bab-app/docs/time.md

Dealing with Time

Dealing with time sucks, okay? We have three different formats we need to deal with:

1. ES Date - The native ECMAScript Date object. This is saddled with all the legacy of the decades. Hopefully, we will be able to retire this one day... Ref: https://tc39.es/proposal-temporal/docs/index.html
2. ISO 8601 Date - Used by Appwrite backend. This is just a string, but can represent any date, with or without a timezone.
3. Timestamp - Used internally by QCalendar.

We can't just use one format. We need ISO8601 format for Appwrite, and we get passed Timestamp objects by QCalendar. In the middle of that, we need ES Date objects to do some underlying math.

Componentization: In order to make things clean and modular, we will rely on Timestamp as the main format in a component.

In data that comes from, or goes to the backend, we will store absolute dates in ISO format.

For any user-facing dates / times, the data will be rendered in the users local time.

For time-only data (as used in Intervals, eg: '09:00'), the template will be stored as a string of 'hh:mm', and represent the users local time. We may want to change this in the future, as this could prove a problem when a user is travelling, but wants to apply a template to their home location.

For now, we'll use the Timestamp object provided by QCalendar. We might need to refactor this in the future.