diff --git a/.github/workflows/publish.yml b/.github/workflows/publish.yml
index c1b229d..8e219eb 100644
--- a/.github/workflows/publish.yml
+++ b/.github/workflows/publish.yml
@@ -11,7 +11,7 @@ jobs:
- uses: actions/checkout@v3
- uses: actions/setup-node@v3
with:
- node-version: 14
+ node-version: 18
registry-url: https://registry.npmjs.org/
cache: npm
- run: npm ci
diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml
index b21d91c..f5dc344 100644
--- a/.github/workflows/test.yml
+++ b/.github/workflows/test.yml
@@ -7,10 +7,10 @@ jobs:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v2
- - name: Use Node.js 14.x
+ - name: Use Node.js 18.x
uses: actions/setup-node@v1
with:
- node-version: 14.x
+ node-version: 18.x
- name: npm install, build, and test
run: |
npm it
diff --git a/.gitignore b/.gitignore
index 1eae0cf..e5b7106 100644
--- a/.gitignore
+++ b/.gitignore
@@ -1,2 +1,3 @@
dist/
node_modules/
+custom-elements.json
diff --git a/CODEOWNERS b/CODEOWNERS
index e6bf555..68f394d 100644
--- a/CODEOWNERS
+++ b/CODEOWNERS
@@ -1 +1 @@
-* @github/web-systems-reviewers
+* @github/primer-reviewers
diff --git a/README.md b/README.md
index 458e3ee..a037dd0 100644
--- a/README.md
+++ b/README.md
@@ -1,4 +1,4 @@
-# <time> element extensions
+# <relative-time> element
Formats a timestamp as a localized string or as relative text that auto-updates in the user's browser.
@@ -40,7 +40,7 @@ A relative time-ago-in-words description can be generated by using the `relative
Add a `` element to your markup. Provide a default formatted date as the element's text content (e.g. April 1, 2014).
-``` html
+```html
April 1, 2014
@@ -64,15 +64,141 @@ Depending on how far in the future this is being viewed, the element's text will
So, a relative date phrase is used for up to a month and then the actual date is shown.
+#### Attributes
+
+| Property Name | Attribute Name | Possible Values | Default Value |
+|:---------------|:-----------------|:-----------------------------------------------------------------------------------------|:-----------------------|
+| `datetime` | `datetime` | `string` | - |
+| `date` | - | `Date \| null` | - |
+| `tense` | `tense` | `'auto'\|'past'\|'future'` | `'auto'` |
+| `threshold` | `threshold` | `string` | `'P30D'` |
+| `prefix` | `prefix` | `string` | `'on'` |
+| `second` | `second` | `'numeric'\|'2-digit'\|undefined` | `undefined` |
+| `minute` | `minute` | `'numeric'\|'2-digit'\|undefined` | `undefined` |
+| `hour` | `hour` | `'numeric'\|'2-digit'\|undefined` | `undefined` |
+| `weekday` | `weekday` | `'short'\|'long'\|'narrow'\|undefined` | `undefined` |
+| `day` | `day` | `'numeric'\|'2-digit'\|undefined` | `'numeric'` |
+| `month` | `month` | `'numeric'\|'2-digit'\|'short'\|'long'\|'narrow'\|undefined` | `'short'` |
+| `year` | `year` | `'numeric'\|'2-digit'\|undefined` | `'numeric'`*|
+| `timeZoneName` | `time-zone-name` | `'long'\|'short'\|'shortOffset'\|'longOffset'\|'shortGeneric'\|'longGeneric'\|undefined` | `undefined` |
+
+*: If unspecified, `year` will return `'numeric'` if `datetime` represents the same year as the current year. It will return `undefined` if unspecified and if `datetime` represents a different year to the current year.
+
+##### datetime (`string`)
+
+This is the datetime that the element is meant to represent. This must be a valid [ISO8601 DateTime](https://en.wikipedia.org/wiki/ISO_8601). It is also possible to use the `date` property on the element to set the date. `el.date` expects a `Date` object, while `el.datetime` expects a string. Setting one will override the other.
+
+```html
+
+ April 1, 2038
+
+
+```
+
+##### tense (`'auto'|'past'|'future'`, default: `auto`)
+
+If `format` is anything other than `'auto'` or `'micro'` then this value will be ignored.
+
+Tense can be used to fix relative-time to always display a date's relative tense in the future or the past. Setting `tense=past` will always display future dates as `now`, while setting it to `future` will always display past dates as `now`.
+
+```html
+
+ April 1, 2038
+
+```
+
+```html
+
+ April 1, 2038
+
+```
+
+##### 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.
+
+Threshold can be used to specify when a relative display (e.g. "5 days ago") should turn into an absolute display (i.e. the full date). This should be a valid [ISO8601 Time Duration](https://en.wikipedia.org/wiki/ISO_8601#Durations). If the difference between the current time and the specified `datetime` is _more_ than the duration, then the date will be displayed as an absolute value (i.e. the full date), otherwise it will be formatted to a relative display (e.g. "5 days ago").
+
+The default value for this is `P30D`, meaning if the current time is more than 30 days away from the specified date time, then an absolute date will be displayed.
+
+```html
+
+
+
+```
+
+```html
+
+
+
+```
+
+##### prefix (`string`, default: `'on'`)
+
+If `tense` is anything other than `'auto'` or `format` is anything other than `'auto'` or `'micro'` then this value will be ignored.
+
+When formatting an absolute date (see above `threshold` for more details) it can be useful to prefix the date with some text. The default value for this is `on` but it can be any string value, an will be prepended to the date.
+
+```html
+
+
+
+```
+
+##### second, minute, hour, weekday, day, month, year, timeZoneName
+
+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`.
+
+## Additional Elements
+
+In addition to `` this package provides convenience elements, which are configurations over ``. These additional elements will be removed in a future major version release.
+
### time-until
+This element is the same as ``. `.tense` will always return `future`, regardless of the value set in the attribute.
+
You can use `time-until` to always display a relative date that's in the future. It operates much like ``, except in the reverse, with past events shown as `just now` and future events always showing as relative:
-- 10 years from now
-- 20 days from now
-- 6 hours from now
-- 20 minutes from now
-- 30 seconds from now
+- in 10 years
+- in 20 days
+- in 6 hours
+- in 20 minutes
+- in 30 seconds
- just now
Add a `` element to your markup. Provide a default formatted date as the element's text content (e.g. April 1, 2024).
@@ -82,9 +208,20 @@ Add a `` element to your markup. Provide a default formatted date as
April 1, 2024
```
+#### Micro format
+
+The optional `format="micro"` attribute shortens the descriptions to 1m, 1h, 1d, 1y.
+
+``` html
+
+ April 1, 2014
+
+```
### time-ago
+This element is the same as ``. `.tense` will always return `past`, regardless of the value set in the attribute.
+
An *always* relative time-ago-in-words description can be generated by using the `time-ago` element extension. This is similar to the `relative-time` extension. However, this will never switch to displaying the date. It strictly shows relative date phrases, even after a month has passed.
``` html
@@ -107,6 +244,8 @@ The optional `format="micro"` attribute shortens the descriptions to 1m, 1h, 1d,
### local-time
+This is a variation of `` with some subtly different formatting.
+
This custom time extension is useful for formatting a date and time in the user's preferred locale format.
``` html
@@ -122,20 +261,6 @@ This custom time extension is useful for formatting a date and time in the user'
When this markup is viewed in a CDT timezone, it will show `Apr 1, 2014 6:30PM`. If it's viewed in a browser with European date preferences, it will read `1 Apr 2014 18:30`.
-### Options
-
-Attribute | Options | Description
---- | --- | ---
-`datetime` | ISO 8601 date | Required date of element `2014-06-01T13:05:07Z`
-`year` | 2-digit, numeric | Format year as `14` or `2014`
-`month` | short, long | Format month as `Jun` or `June`
-`day` | 2-digit, numeric | Format day as `01` or `1`
-`weekday` | short, long | Format weekday as `Sun` or `Sunday`
-`hour` | 2-digit, numeric | Format hour as `01` or `1`
-`minute` | 2-digit, numeric | Format minute as `05` or `5`
-`second` | 2-digit, numeric | Format second as `07` or `7`
-`time-zone-name` | short, long | Display time zone as `GMT+1` or by its full name
-
## Browser Support
Browsers without native [custom element support][support] require a [polyfill][].
diff --git a/custom-elements-manifest.config.js b/custom-elements-manifest.config.js
new file mode 100644
index 0000000..8f593a3
--- /dev/null
+++ b/custom-elements-manifest.config.js
@@ -0,0 +1,5 @@
+export default {
+ packagejson: true,
+ globs: ['src/*-element.ts'],
+ plugins: []
+}
diff --git a/examples/index.html b/examples/index.html
index 83f3a81..af52d4f 100644
--- a/examples/index.html
+++ b/examples/index.html
@@ -77,6 +77,34 @@ Future Date
+
+ Relative time with custom format:
+
+
+
+
+ Nearby, dynamic, relative time:
+
+ Oops! This browser doesn't support Web Components.
+
+
+
+
+ Nearby, dynamic, relative time:
+
+ Oops! This browser doesn't support Web Components.
+
+
+
+
+ Nearby, dynamic, relative time:
+
+ Oops! This browser doesn't support Web Components.
+
+
+
+
+
Time until:
@@ -92,5 +120,13 @@ Future Date
+