Front End Development Thread

Introduction

Full-Stop is a period tracker for Urbit. Both directly connected front-ends and offline->sync applications can communicate updates to Full-Stop allowing users to utilize offline local data storage when they are without internet, while maintaining an accurate record of data on their urbits. When offline systems sync, their changes are read and implemented (where appropriate) and the resultant data is sent back to the application to update local state.

Model Theory

Full-Stop operates on the following model:

Always receive an indeterminately long list of update instructions
Process each update instruction, from the tail (first in, first out), excluding those that have update dates prior to the most recent update date (mostly - some elements are not checked for sanity in this way, e.g. rate and spot).
State-engine flop + Produce FE effects
Almost never fail - provide the user with feedback as to why some state changes have not been accepted, such that offline applications can queue a list of changes and get back a list of updates and failures, both of which are legible for user and FE.
Await next command list.

Subscription

Subscribe on [%website ~] for data.

On first subscription, receive full data set:

+$  state-0
  $:  %0
      =moon                                              ::  cycles
      =spot                                              ::  spotting
      =rain                                              ::  mucosal discharge
      =fire                                              ::  basal body temp
      =mate                                              ::  sexual encounters
      =bear                                              ::  pregnancy
      =hold                                              ::  birth control
      =opts                                              ::  system options
  ==
::
+$  moon  (cycle flow)                                   ::  track cycles
+$  flow                                                 ::  flow includes:
  $:  stop=(unit time)                                   ::    - stop date (or not)
      rate=(cycle rate)                                  ::    - flow rate (or none)
      edit=time                                          ::    - last edit date
  ==
::
+$  spot  (set time)                                     ::  track out of cycle bleeding, loosely (no edit filtering)
+$  rain  (cycle [p=cons edit=time])                     ::  track cervical mucousal viscocity
+$  fire  (cycle [p=base edit=time])                     ::  track basal body temperature
+$  mate  (set [p=time q=(unit @t) r=?])                 ::  track sexual encounters with optional details
+$  bear  (unit [star=time edit=time])                   ::  track pregnancy
+$  opts  [noti=? fert=? edit=time]                      ::  options - notifications and fertility predictions
+$  hold
  %-  unit
  $:  $=  type
      $%  [%pill h=@ud m=@ud am=? miss=(set time)]       ::  track hormonal pill b.c., record missed pills
          [%term wen=time again=time]                    ::  track implant/term b.c., record replacement date
      ==
      edit=time
  ==

Pokes and Outcomes

Pokes

Pokes are separated into 6 categories, each of which will be coded out in units for testing and FE work delegation. If a section below has not been completed assume that the code is subject to change.

The system always expects a drop which is a (list [activity time]). An activity is a blended case of all the pokes listed below, the time at the tail of the cell should be when the poke was made by the user, so that we can date it against conflicting updates from other sources, during sync.

Marks

The expected mark is a %dot-point. When there is a unit in a poke, I will write soft parsers - please assume that sending me 'garbage' or anything other than a reasonable answer will result in a null while a reasonable answer will be taken as the unit of itself.

Notes

Note: The user's experience, if it receives an empty data set from subscription, should be to enter a period they've experienced, from their past or currently using a [%flow wen=time], OR identify that they are pregnant, with a [%move wen=time due=?]. Almost all other activity is gated off of having some period recorded.

Note: Always Midnight, Sis. All times are interpreted as midnight on that day so don't try sending me something more specific. Or do. I don't really care. (this does not apply to the (list [activity **TIME**]) time, but anything called wen is midnight on that day.

Sanguine

Handles menstruation tracking.

+$  sanguine
  $%  [%flow wen=time]                                   ::  note menstruation start
      [%stop wen=time]                                   ::  note menstruation stop
      [%rate how=(unit rate) wen=time]                   ::  note flow rate
      [%spot wen=time]                                   ::  note spotting
  ==

Test Data

Load period data starting 11.1.2021 thru 8.5.2022:

:full-stop &dot-point ~[[stop+~2022.8.5 now] [flow+~2022.8.1 now] [stop+~2022.7.5 now] [flow+~2022.7.1 now] [stop+~2022.6.5 now] [flow+~2022.6.1 now] [stop+~2022.5.5 now] [flow+~2022.5.1 now] [stop+~2022.4.5 now] [flow+~2022.4.1 now] [stop+~2022.3.5 now] [flow+~2022.3.1 now] [stop+~2022.2.5 now] [flow+~2022.2.1 now] [stop+~2022.1.5 now] [flow+~2022.1.1 now] [stop+~2021.12.5 now] [flow+~2021.12.1 now] [stop+~2021.11.5 now] [flow+~2021.11.1 now]]

Add some rate reports:

:full-stop &dot-point ~[[rate+[`%1 ~2021.12.1] now] [rate+[`%2 ~2021.12.2] now] [rate+[`%3 ~2021.12.3] now] [rate+[`%4 ~2021.12.4] now] [rate+[`%5 ~2021.12.5] now]]

Add some spotting reports:

:full-stop &dot-point ~[[spot+~2021.11.6 now] [spot+~2021.12.7 now] [spot+~2022.1.8 now] [spot+~2022.2.9 now] [spot+~2022.3.10 now] [spot+~2022.4.11 now] [spot+~2022.5.12 now] [spot+~2022.6.13 now] [spot+~2022.7.14 now] [spot+~2022.8.15 now]]

`[%flow wen=time]`

Example JSON Poke:

[%a p=~[[%o p={[p='wen' q=[%n p=~.1660317998]] [p='flow' q=[%o p={[p='wen' q=[%n p=~.1660317998]]}]]}]]]

Expectation Start or remove a flow - we'll basically take anything, except for a time within another period. If you give us a day we already have tracked as the start of a period, we'll delete that instance.
Result
- On Delete - { del-flow: <start-date in seconds> }
- On Add -
```
{ add-flow: :~  <start-date in seconds>
            { stop: <~ or stop-date>,
              rate: ~[<rate-date> <1-5 flow rating, 5 being heavy>],
              edit: <last-edit-date> }}
```
- On Error:
- { need-flow-stop: <start-date-of-conflicting-period> } - You have an open period recorded prior to the one you're trying to record that needs to be closed. Close it and try entering this again.

`[%stop wen=time]`

Example JSON Poke

[%a p=~[[%o p={[p='wen' q=[%n p=~.1660322836]] [p='stop' q=[%o p={[p='wen' q=[%n p=~.1660322836]]}]]}]]]

Expectation Set or adjust the stop date for a given period. We'll take anything, find the period corresponding to it, and (assuming we don't have a more recent update for that period) adjust the period's stop date to the date you just provided.

Result

On Add

{ add-flow: :~  <start-date in seconds>
            { stop: <stop-date>,
              rate: ~[<rate-date> <1-5 flow rating, 5 being heavy>],
              edit: <last-edit-date> }}

On Adjust

{ add-flow: :~  <start-date in seconds>
            { stop: <~ or stop-date>,
              rate: ~[<rate-date> <1-5 flow rating, 5 being heavy>],
              edit: <last-edit-date> }}

and separately if needed

{ add-spots:  ~,
del-spots: <list of spotting dates to remove, as they were inside the period now>
}

On Error
- {need-flow-start: <proposed stop date>} - You've given me a stop date I cannot associate with a period.

`[%spot wen=time]`

Example JSON Poke

[%a p=~[[%o p={[p='wen' q=[%n p=~.1660322836]] [p='spot' q=[%o p={[p='wen' q=[%n p=~.1660322836]]}]]}]]]

Expectation Add or delete an instance of spotting, outside your cycle. These are not checked against edit time.
Result
- On Add/Delete
```
{ add-spots: [<array of dates>], del-spots: [<array of dates>]
```
- On Error
- {need-prior-flow: <a spotting date you gave me>} - I don't see a flow starting and stopping before this date, and thus I can't tell if this is a valid spotting occasion.
- {need-flow-stop: <a spotting date you gave me>} - You indicated you are spotting in a period that doesn't have a stop date associated - are you sure this isn't part of your period?
- {spot-inside-flow: [<start date> <stop date>]} - You indicated you were spotting during a recorded period - not sure what you want me to do with that.

`[%rate how=(unit ?(%1 %2 %3 %4 %5) wen=time]`

Example JSON Poke

[%a p=~[[%o p={[p='wen' q=[%n p=~.1660322990]] [p='rate' q=[%o p={[p='how' q=[%n p=~.4]] [p='wen' q=[%n p=~.1660322990]]}]]}]]]

[%a p=~[[%o p={[p='wen' q=[%n p=~.1660322990]] [p='rate' q=[%o p={[p='how' q=~] [p='wen' q=[%n p=~.1660322990]]}]]}]]]

Expectation Add or delete (on how=~) a rate report within the window of a period. These are not checked against edit time so go crazy, go stupid, enter conflicting information from various sources, we won't even notice.
Result
- On Add/Delete
```
{ add-flow: :~  <start-date in seconds>
            { stop: <~ or stop-date>,
              rate: ~[<rate-date> <1-5 flow rating, 5 being heavy>],  <- contains the new information, or removed info
              edit: <last-edit-date> }}
```
- On Error
- {need-flow-start: <your-rate-date>} - I don't have a flow to which this could correspond.
- {rate-doesnt-exist: <your-rate-date>} - You asked me to delete a rate report that I don't have recorded.
- {rate-outside-flow: ~[<start-date> <stop-date>]} - You gave me a rate report outside of your purported period, here is the stop and start date I have recorded - fix that first.

Physical

Handles fertility prediction aid tracking (basal body temp and cervical mucosal consistency)

+$  physical
  $%  [%temp baz=(unit base) wen=time]                   ::  note basal body temp for some day
      [%muco con=(unit cons) wen=time]                   ::  note cervical mucosal consistency
  ==

Test Data

Load some temps

:full-stop &dot-point ~[[temp+[`.98.6 now] now] [temp+[`.98.6 ~2022.8.9] now] [temp+[`.98.6 ~2022.8.8] now] [temp+[`.98.6 ~2022.8.7] now] [temp+[`.98.6 ~2022.8.6] now] [temp+[`.98.6 ~2022.8.5] now] [temp+[`.98.6 ~2022.8.4] now] [temp+[`.98.6 ~2022.8.3] now] [temp+[`.98.6 ~2022.8.2] now]]

Load some mucosal reports

:full-stop &dot-point ~[[muco+[`%1 now] now] [muco+[`%1 ~2022.8.9] now] [muco+[`%1 ~2022.8.8] now] [muco+[`%1 ~2022.8.7] now] [muco+[`%2 ~2022.8.6] now]  [muco+[`%3 ~2022.8.5] now]  [muco+[`%5 ~2022.8.4] now]  [muco+[`%1 ~2022.8.3] now] [muco+[`%1 ~2022.8.2] now]]

`[%temp baz=(unit @rs) wen=time]`

Example JSON Poke

[%a p=~[[%o p={[p='wen' q=[%n p=~.1660323095]] [p='temp' q=[%o p={[p='wen' q=[%n p=~.1660323095]] [p='baz' q=[%s p='.98.6']]}]]}]]]

Expectation
- Add or remove a basal body temperature report
Result
- On Add/Delete {del-fire: <date to delete>} or `{add-fire: {when: , heat:
On Error
- {temp-fail-delete: <date you gave>} - You gave me a null unit, indicating you wanted to delete a something - I don't have a report there.

`[%muco con=(unit cons) wen=time]`

Example JSON Poke

[%o p={[p='muco' q=[%o p={[p='wen' q=[%n p=~.1660188657]] [p='con' q=[%n p=~.5]] [p='edit' q=[%n p=~.1660188657]]}]]}]

Expectation
- Add or remove a cervical mucosal discharge consistency report
Result
- On Add/Delete {del-rain: <date to delete>} or {add-rain: {when: <date>, drip: <rating>, edit: <date>}}

NOTE: %1 is "thick" and %5 is "thin" consistency wise - because %1 is the base state.

On Error
- {muco-fail-delete: <date you gave>} - You gave me a null unit indicating you wanted to delete something - I don't have a report there.

Controls

Handles birth control method tracking/alerting

Relation

Handles sexual encounter tracking

Election

Handles agent settings (notifications, fertility window predictions)

Pregnant

Handles pregnancy tracking

Scrys

[%x %all ~] Gives front end startup information

[%x %moon ?([%each ~] [%just @ ~] [%some @ @ ~])] Gives you all periods, a period (the one specified), or the periods between (the first one specified and the second one specified)

[%x %spot ~] Gives spot data

[%x %rain ~] Gives mucous data

[%x %fire ~] Gives basal body temp data

[%x %mate ~] Gives sex data

[%x %bear ~] Gives pregnancy data

[%x %hold ~] Gives birth control data

[%x %opts ~] Gives agent settings data

[%x %next ~] Gives a prediction of next period, if it can

On Error:

{ need-next-data: ~ } - We need more consecutive periods to predict an outcome - basically we need at least 6 months of "consecutive" (more often than every 60 days, well over the normal variance) periods, recently, to be able to predict your next period. This means 7 start flow dates within 60 days of each other, end-over-end, and at least one within 45 days of now.bowl.

dalten-collective / full-stop