github / relative-time-element

Web component extensions to the standard <time> element.

Home Page:https://github.github.io/relative-time-element/examples/

Geek Repo:Geek Repo

Github PK Tool:Github PK Tool

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 (aka threshold=PT0S): Display the full date and time localised to the users locale preference.
  • format=relative (aka format=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 example in 1 day, 1 year ago.
  • format=duration (aka format=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' }).