Make `format` API more consistent
keithamus opened this issue · comments
Format can currently be one of auto
, micro
, or elapsed
.
auto
means the display will be relative, unless the time is outside of the given threshold at which point it will be the "full" formatted date.micro
means the display will be relative but in a "micro" style. This is the same as auto but displays differently, using single character notation.elapsed
is a different format which displays the time elapsed between two the two dates like a countdown.
There are really three discrete behaviours that we use to format time:
format=datetime
(akathreshold=PT0S
): Display the full date and time localised to the users locale preference.format=relative
(akaformat=auto
): Display the date time describing the distance relative to the current date, rounded to a single unit. Distance means displaying information about the current tense, for examplein 1 day
,1 year ago
.format=duration
(akaformat=micro
,format=elapsed
): Display the time in one or more units, counting the time elapsed between the given date and the current date.
This then aligns nicely to the Intl.
constructors we use for each piece; format=datetime
will use Intl.DateTimeFormat
, format=relative
will use Intl.RelativeTimeFormat
, and format=duration
will use Intl.DurationFormat
.
The unit names that are displayed can then be determined with a style:
formatStyle=long
(aka default): Display the full names for each unit, e.g.in 1 month
,1 month
formatStyle=narrow
: Display the shortened names for each unit, e.g.in 1 mo
,1m
This also coincides with the Intl constructor options. E.g. Intl.DurationFormat('en', {style: 'narrow'})
, Intl.DurationFormat('en', { style: 'narrow' })
.