diff --git a/README.md b/README.md index a037dd0..1ba2ef0 100644 --- a/README.md +++ b/README.md @@ -69,8 +69,10 @@ So, a relative date phrase is used for up to a month and then the actual date is | Property Name | Attribute Name | Possible Values | Default Value | |:---------------|:-----------------|:-----------------------------------------------------------------------------------------|:-----------------------| | `datetime` | `datetime` | `string` | - | +| `format` | `format` | `'auto'|'micro'|'elapsed'|string` | 'auto' | | `date` | - | `Date \| null` | - | | `tense` | `tense` | `'auto'\|'past'\|'future'` | `'auto'` | +| `precision` | `precision` | `'year'|'month'|'day'|'hour'|'minute'|'second'` | `'second'` | | `threshold` | `threshold` | `string` | `'P30D'` | | `prefix` | `prefix` | `string` | `'on'` | | `second` | `second` | `'numeric'\|'2-digit'\|undefined` | `undefined` | @@ -100,6 +102,39 @@ This is the datetime that the element is meant to represent. This must be a vali ``` +##### format (`'auto'|'micro'|'elapsed'|string`, default: `'auto'`) + +The default format is `auto`, but this can be changed to `micro` or `elapsed`. + +The default `auto` format will display dates relative to the current time (unless they are past the `threshold` value - see below). The values are rounded to display a single unit, for example if the time between the given `datetime` and the current wall clock time exceeds a day, then the format will _only_ ouput in days, and will not display hours, minutes or seconds. + +The `micro` format which will display relative dates (within the threshold) in a more compact format. Similar to `auto`, the `micro` format rounds values to the nearest largest value. Additionally, `micro` format will not round _lower_ than 1 minute, as such a `datetime` which is less than a minute from the current wall clock time will display `'1m'`. + +The `elapsed` format will always non-rounded units of time, where any non-zero unit of time is displayed in the compact notation format. This format is also absolute, and so tense does not apply. This can be useful for displaying actively running timers. + +| `format=auto` | `format=micro` | `format=elapsed` | +|:-------------:|:--------------:|:----------------:| +| in 2 years | 2y | 2y 10d 3h 20m 8s | +| 2 years ago | 2y | 2y 10d 3h 20m 8s | +| in 30 days | 30d | 30d 4h 20m 8s | +| 21 minutes ago| 21m | 21m 30s | +| 37 seconds ago| 1m | 37s | + +Additionally, format accepts a [strftime](https://strftime.org/) compatible format. Providing a strftime format will override all other attributes on the element, and the time will be displayed formatted based on the strftime value. This can be useful, for example, to dynamically remove relative formatting based on a user action. + +```html + + + +``` + +```html + + + +``` + + ##### tense (`'auto'|'past'|'future'`, default: `auto`) If `format` is anything other than `'auto'` or `'micro'` then this value will be ignored. @@ -118,6 +153,21 @@ Tense can be used to fix relative-time to always display a date's relative tense ``` +#### precision (`'year'|'month'|'day'|'hour'|'minute'|'second'`, default: `'second'`) + +If `format` is anything other than `'elapsed'` then this value will be ignored. + +Precision can be used to limit the display of an `elapsed` formatted time. By default the `elapsed` time will display times down to the `second` level of precision. Changing this value will truncate the display to the respective unit, and smaller units will be elided. Some examples: + +| `precision=` | Display | +|:-------------:|:-------------------:| +| seconds | 2y 6m 10d 3h 20m 8s | +| minutes | 2y 6m 10d 3h 20m | +| hours | 2y 6m 10d 3h | +| days | 2y 6m 10d | +| months | 2y 6m | +| years | 2y | + ##### threshold (`string`, default: `P30D`) If `tense` is anything other than `'auto'` or `format` is anything other than `'auto'` or `'micro'` then this value will be ignored. @@ -154,32 +204,6 @@ When formatting an absolute date (see above `threshold` for more details) it can For dates outside of the specified `threshold`, the formatting of the date can be configured using these attributes. The values for these attributes are passed to [Intl.DateTimeFormat](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/DateTimeFormat/DateTimeFormat): -##### format (`'auto'|'micro'|string`, default: `'auto'`) - -The default format is `auto`, but this can be changed to `micro` which will display relative dates (within the threshold) in a more compact format. Micro format will not display relative times shorter than 1 minute (`'1m'`). Some examples: - -| `format=auto` | `format=micro` | -|:-------------:|:--------------:| -| in 2 years | 2y | -| 2 yars ago | 2y | -| in 30 days | 30d | -| 21 minutes ago| 21m | -| 37 seconds ago| 1m | - -Additionally, format accepts a [strftime](https://strftime.org/) compatible format. Providing a strftime format will override all other attributes on the element, and the time will be displayed formatted based on the strftime value. This can be useful, for example, to dynamically remove relative formatting based on a user action. - -```html - - - -``` - -```html - - - -``` - ##### lang Lang is a [built-in global attribute](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/lang). Relative Time will use this to provide an applicable language to the `Intl` APIs. If the individual element does not have a `lang` attribute then it will traverse upwards in the tree to find the closest element that does, or default the lang to `en`. diff --git a/examples/index.html b/examples/index.html index af52d4f..f0ba169 100644 --- a/examples/index.html +++ b/examples/index.html @@ -82,6 +82,22 @@

Future Date

+

+ Time until: + + Oops! This browser doesn't support Web Components. + +

+ +

+ Time until (micro format): + + Oops! This browser doesn't support Web Components. + +

+ + +

Dynamic Formats

Nearby, dynamic, relative time: @@ -89,6 +105,7 @@

Future Date

+

Nearby, dynamic, relative time: @@ -103,23 +120,22 @@

Future Date

- -

- Time until: - + How long you've been on this page + Oops! This browser doesn't support Web Components. - +

- Time until (micro format): - + Countdown timer until 2038 bug: + Oops! This browser doesn't support Web Components.

- - + + + diff --git a/src/duration-format.ts b/src/duration-format.ts index 520af7d..b5810fe 100644 --- a/src/duration-format.ts +++ b/src/duration-format.ts @@ -1,4 +1,5 @@ -export type Unit = 'second' | 'minute' | 'hour' | 'day' | 'month' | 'year' +export const unitNames = ['second', 'minute', 'hour', 'day', 'month', 'year'] as const +export type Unit = typeof unitNames[number] export function timeAgo(date: Date): [number, Unit] { const ms = new Date().getTime() - date.getTime() @@ -109,3 +110,21 @@ export function microTimeUntil(date: Date): [number, Unit] { return [1, 'minute'] } } + +export function elapsedTime(date: Date): Array<[number, Unit]> { + const ms = Math.abs(date.getTime() - new Date().getTime()) + const sec = Math.floor(ms / 1000) + const min = Math.floor(sec / 60) + const hr = Math.floor(min / 60) + const day = Math.floor(hr / 24) + const month = Math.floor(day / 30) + const year = Math.floor(month / 12) + const units: Array<[number, Unit]> = [] + if (year) units.push([year, 'year']) + if (month - year * 12) units.push([month - year * 12, 'month']) + if (day - month * 30) units.push([day - month * 30, 'day']) + if (hr - day * 24) units.push([hr - day * 24, 'hour']) + if (min - hr * 60) units.push([min - hr * 60, 'minute']) + if (sec - min * 60) units.push([sec - min * 60, 'second']) + return units +} diff --git a/src/relative-time-element.ts b/src/relative-time-element.ts index f35e7e8..92cea37 100644 --- a/src/relative-time-element.ts +++ b/src/relative-time-element.ts @@ -1,4 +1,4 @@ -import {microTimeAgo, microTimeUntil, timeUntil, timeAgo} from './duration-format.js' +import {unitNames, Unit, microTimeAgo, microTimeUntil, timeUntil, timeAgo, elapsedTime} from './duration-format.js' import {DateTimeFormat as DateTimeFormatPonyFill} from './datetimeformat-ponyfill.js' import {RelativeTimeFormat as RelativeTimeFormatPonyfill} from './relative-time-ponyfill.js' import {isDuration, withinDuration} from './duration.js' @@ -10,7 +10,7 @@ const DateTimeFormat = supportsIntlDatetime ? Intl.DateTimeFormat : DateTimeForm const supportsIntlRelativeTime = 'Intl' in window && 'RelativeTimeFormat' in Intl const RelativeTimeFormat = supportsIntlRelativeTime ? Intl.RelativeTimeFormat : RelativeTimeFormatPonyfill -export type Format = 'auto' | 'micro' | string +export type Format = 'auto' | 'micro' | 'elapsed' | string export type Tense = 'auto' | 'past' | 'future' export class RelativeTimeUpdatedEvent extends Event { @@ -19,8 +19,17 @@ export class RelativeTimeUpdatedEvent extends Event { } } -function getUnitFactor(ms: number): number { - ms = Math.abs(Date.now() - ms) +function getUnitFactor(el: RelativeTimeElement): number { + if (!el.date) return Infinity + if (el.format === 'elapsed') { + const precision = el.precision + if (precision === 'second') { + return 1000 + } else if (precision === 'minute') { + return 60 * 1000 + } + } + const ms = Math.abs(Date.now() - el.date.getTime()) if (ms < 60 * 1000) return 1000 if (ms < 60 * 60 * 1000) return 60 * 1000 return 60 * 60 * 1000 @@ -35,7 +44,7 @@ const dateObserver = new (class { this.elements.add(element) const date = element.date if (date && date.getTime()) { - const ms = getUnitFactor(date.getTime()) + const ms = getUnitFactor(element) const time = Date.now() + ms if (time < this.time) { clearTimeout(this.timer) @@ -57,8 +66,7 @@ const dateObserver = new (class { let nearestDistance = Infinity for (const timeEl of this.elements) { - const distance = timeEl.date ? getUnitFactor(timeEl.date.getTime()) : Infinity - nearestDistance = Math.min(nearestDistance, distance) + nearestDistance = Math.min(nearestDistance, getUnitFactor(timeEl)) timeEl.update() } this.time = Math.min(60 * 60 * 1000, nearestDistance) @@ -89,6 +97,7 @@ export default class RelativeTimeElement extends HTMLElement implements Intl.Dat 'prefix', 'threhsold', 'tense', + 'precision', 'format', 'datetime', 'lang', @@ -119,8 +128,12 @@ export default class RelativeTimeElement extends HTMLElement implements Intl.Dat const date = this.date if (!date) return const format = this.format - if (format !== 'auto' && format !== 'micro') { + if (format !== 'auto' && format !== 'micro' && format !== 'elapsed') { return strftime(date, format) + } else if (format === 'elapsed') { + const precisionIndex = unitNames.indexOf(this.precision) || 0 + const units = elapsedTime(date).filter(unit => unitNames.indexOf(unit[1]) >= precisionIndex) + return units.map(([int, unit]) => `${int}${unit[0]}`).join(' ') || `0${this.precision[0]}` } const tense = this.tense const micro = format === 'micro' @@ -271,9 +284,20 @@ export default class RelativeTimeElement extends HTMLElement implements Intl.Dat this.setAttribute('tense', value) } + get precision(): Unit { + const precision = this.getAttribute('precision') as unknown as Unit + if (unitNames.includes(precision)) return precision + return 'second' + } + + set precision(value: Unit) { + this.setAttribute('precision', value) + } + get format(): Format { const format = this.getAttribute('format') if (format === 'micro') return 'micro' + if (format === 'elapsed') return 'elapsed' if (format && format.includes('%')) return format return 'auto' } @@ -343,7 +367,7 @@ export default class RelativeTimeElement extends HTMLElement implements Intl.Dat const date = this.date const format = this.format const isRelative = (format === 'auto' || format === 'micro') && date && withinDuration(now, date, this.threshold) - if (isRelative) { + if (format === 'elapsed' || isRelative) { dateObserver.observe(this) } else { dateObserver.unobserve(this) diff --git a/test/relative-time.js b/test/relative-time.js index b4af825..a82fed6 100644 --- a/test/relative-time.js +++ b/test/relative-time.js @@ -684,6 +684,25 @@ suite('relative-time', function () { {datetime: '2021-05-18T14:46:00.000Z', tense: 'past', format: 'micro', expected: '1y'}, {datetime: '2021-05-17T14:46:00.000Z', tense: 'past', format: 'micro', expected: '2y'}, + // Elapsed Times + {datetime: '2022-10-24T14:46:10.000Z', format: 'elapsed', expected: '10s'}, + {datetime: '2022-10-24T14:45:50.000Z', format: 'elapsed', expected: '10s'}, + {datetime: '2022-10-24T14:45:50.000Z', format: 'elapsed', precision: 'minute', expected: '0m'}, + {datetime: '2022-10-24T14:47:40.000Z', format: 'elapsed', expected: '1m 40s'}, + {datetime: '2022-10-24T14:44:20.000Z', format: 'elapsed', expected: '1m 40s'}, + {datetime: '2022-10-24T14:44:20.000Z', format: 'elapsed', precision: 'minute', expected: '1m'}, + {datetime: '2022-10-24T15:51:40.000Z', format: 'elapsed', expected: '1h 5m 40s'}, + {datetime: '2022-10-24T15:51:40.000Z', format: 'elapsed', precision: 'minute', expected: '1h 5m'}, + {datetime: '2022-10-24T15:52:00.000Z', format: 'elapsed', expected: '1h 6m'}, + {datetime: '2022-10-24T17:46:00.000Z', format: 'elapsed', expected: '3h'}, + {datetime: '2022-10-24T10:46:00.000Z', format: 'elapsed', expected: '4h'}, + {datetime: '2022-10-25T18:46:00.000Z', format: 'elapsed', expected: '1d 4h'}, + {datetime: '2022-10-23T10:46:00.000Z', format: 'elapsed', expected: '1d 4h'}, + {datetime: '2022-10-23T10:46:00.000Z', format: 'elapsed', precision: 'day', expected: '1d'}, + {datetime: '2021-10-30T14:46:00.000Z', format: 'elapsed', expected: '11m 29d'}, + {datetime: '2021-10-30T14:46:00.000Z', format: 'elapsed', precision: 'month', expected: '11m'}, + {datetime: '2021-10-29T14:46:00.000Z', format: 'elapsed', expected: '1y'}, + // Dates in the past {datetime: '2022-09-24T14:46:00.000Z', tense: 'future', format: 'auto', expected: 'now'}, {datetime: '2022-10-23T14:46:00.000Z', tense: 'future', format: 'auto', expected: 'now'}, @@ -756,13 +775,14 @@ suite('relative-time', function () { } ]) - for (const {datetime, expected, tense, format, reference = referenceDate} of tests) { + for (const {datetime, expected, tense, format, precision = '', reference = referenceDate} of tests) { test(` => ${expected}`, function () { freezeTime(new Date(reference)) const time = document.createElement('relative-time') time.setAttribute('tense', tense) time.setAttribute('datetime', datetime) time.setAttribute('format', format) + time.setAttribute('precision', precision) assert.equal(time.shadowRoot.textContent, expected) }) }