diff --git a/docs/_sidebar.md b/docs/_sidebar.md index 58d94001..7f71c10e 100644 --- a/docs/_sidebar.md +++ b/docs/_sidebar.md @@ -52,6 +52,7 @@ - [Format Bytes](/components/format-bytes.md) - [Format Number](/components/format-number.md) - [Include](/components/include.md) + - [Relative Time](/components/relative-time.md) - [Resize Observer](/components/resize-observer.md) - [Theme](/components/theme.md) diff --git a/docs/components/relative-time.md b/docs/components/relative-time.md new file mode 100644 index 00000000..5561b70c --- /dev/null +++ b/docs/components/relative-time.md @@ -0,0 +1,61 @@ +# Relative Time + +[component-header:sl-relative-time] + +Outputs a localized time phrase relative to the current time. + +Localization is handled by the browser's [Intl.RelativeTimeFormat API](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/RelativeTimeFormat) so there'e no need to load language packs. + +```html preview +
+``` + +The `date` prop must be a [`Date`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date) object or a string that [`Date.parse()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/parse) can interpret. When using strings, avoid ambiguous dates such as `03/04/2020` which can be interpreted as March 4 or April 3 depending on the user's browser and locale. Instead, use a valid [ISO 8601 date time string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/parse#Date_Time_String_Format) to ensure proper parsing. + +?> [The Intl.RelativeTimeFormat API is available in all major browsers](https://caniuse.com/mdn-javascript_builtins_intl_relativetimeformat), but it first became available to Safari in version 14. If you need to support Safari 13, you'll need to [use a polyfill](https://github.com/catamphetamine/relative-time-format). + +## Examples + +### Keeping Time in Sync + +Use the `sync` attribute to update the displayed value as time passes. + +```html preview +
+ +

+ Reset +
+ + +``` + +### Formatting Styles + +You can change the way times are formatted with the `format` attribute. Note that some locales may show the same result for `narrow` and `short` formats. + +```html preview +
+
+ +``` + +### Localization + +Use the `locale` attribute to set the desired locale. + +```html preview +English:
+Chinese:
+German:
+Russian: +``` + +[component-metadata:sl-relative-time] diff --git a/docs/getting-started/changelog.md b/docs/getting-started/changelog.md index 664cea8c..02ab789d 100644 --- a/docs/getting-started/changelog.md +++ b/docs/getting-started/changelog.md @@ -9,6 +9,7 @@ _During the beta period, these restrictions may be relaxed in the event of a mis ## Next - Added `sl-format-number` component +- Added `sl-relative-time` component - Added `closable` prop to `sl-tab` - Added experimental `sl-resize-observer` utility - Added experimental `sl-theme` utility and updated theming documentation diff --git a/src/components.d.ts b/src/components.d.ts index eaf719dd..8711be7d 100644 --- a/src/components.d.ts +++ b/src/components.d.ts @@ -897,6 +897,24 @@ export namespace Components { */ "value": number; } + interface SlRelativeTime { + /** + * The date from which to calculate time from. + */ + "date": Date | string; + /** + * The formatting style to use. + */ + "format": 'long' | 'short' | 'narrow'; + /** + * The locale to use when formatting the number. + */ + "locale": string; + /** + * When `auto`, values such as "yesterday" and "tomorrow" will be shown when possible. When `always`, values such as "1 day ago" and "in 1 day" will be shown. + */ + "numeric": 'always' | 'auto'; + } interface SlResizeObserver { } interface SlResponsiveEmbed { @@ -1434,6 +1452,12 @@ declare global { prototype: HTMLSlRatingElement; new (): HTMLSlRatingElement; }; + interface HTMLSlRelativeTimeElement extends Components.SlRelativeTime, HTMLStencilElement { + } + var HTMLSlRelativeTimeElement: { + prototype: HTMLSlRelativeTimeElement; + new (): HTMLSlRelativeTimeElement; + }; interface HTMLSlResizeObserverElement extends Components.SlResizeObserver, HTMLStencilElement { } var HTMLSlResizeObserverElement: { @@ -1544,6 +1568,7 @@ declare global { "sl-radio": HTMLSlRadioElement; "sl-range": HTMLSlRangeElement; "sl-rating": HTMLSlRatingElement; + "sl-relative-time": HTMLSlRelativeTimeElement; "sl-resize-observer": HTMLSlResizeObserverElement; "sl-responsive-embed": HTMLSlResponsiveEmbedElement; "sl-select": HTMLSlSelectElement; @@ -2477,6 +2502,24 @@ declare namespace LocalJSX { */ "value"?: number; } + interface SlRelativeTime { + /** + * The date from which to calculate time from. + */ + "date"?: Date | string; + /** + * The formatting style to use. + */ + "format"?: 'long' | 'short' | 'narrow'; + /** + * The locale to use when formatting the number. + */ + "locale"?: string; + /** + * When `auto`, values such as "yesterday" and "tomorrow" will be shown when possible. When `always`, values such as "1 day ago" and "in 1 day" will be shown. + */ + "numeric"?: 'always' | 'auto'; + } interface SlResizeObserver { /** * Emitted when the element is resized. @@ -2862,6 +2905,7 @@ declare namespace LocalJSX { "sl-radio": SlRadio; "sl-range": SlRange; "sl-rating": SlRating; + "sl-relative-time": SlRelativeTime; "sl-resize-observer": SlResizeObserver; "sl-responsive-embed": SlResponsiveEmbed; "sl-select": SlSelect; @@ -2912,6 +2956,7 @@ declare module "@stencil/core" { "sl-radio": LocalJSX.SlRadio & JSXBase.HTMLAttributes; "sl-range": LocalJSX.SlRange & JSXBase.HTMLAttributes; "sl-rating": LocalJSX.SlRating & JSXBase.HTMLAttributes; + "sl-relative-time": LocalJSX.SlRelativeTime & JSXBase.HTMLAttributes; "sl-resize-observer": LocalJSX.SlResizeObserver & JSXBase.HTMLAttributes; "sl-responsive-embed": LocalJSX.SlResponsiveEmbed & JSXBase.HTMLAttributes; "sl-select": LocalJSX.SlSelect & JSXBase.HTMLAttributes; diff --git a/src/components/relative-time/relative-time.tsx b/src/components/relative-time/relative-time.tsx new file mode 100644 index 00000000..336105b2 --- /dev/null +++ b/src/components/relative-time/relative-time.tsx @@ -0,0 +1,45 @@ +import { Component, Prop, State, h } from '@stencil/core'; + +/** + * @since 2.0 + * @status stable + */ + +@Component({ + tag: 'sl-relative-time', + shadow: true +}) +export class RelativeTime { + @State() displayTime = ''; + + /** The date from which to calculate time from. */ + @Prop() date: Date | string; + + /** The locale to use when formatting the number. */ + @Prop() locale: string; + + /** The formatting style to use. */ + @Prop() format: 'long' | 'short' | 'narrow' = 'long'; + + /** + * When `auto`, values such as "yesterday" and "tomorrow" will be shown when possible. When `always`, values such as + * "1 day ago" and "in 1 day" will be shown. + */ + @Prop() numeric: 'always' | 'auto' = 'auto'; + + render() { + const date = new Date(this.date); + + if (isNaN(date.getSeconds())) { + return ''; + } + + // // @ts-ignore - https://caniuse.com/mdn-javascript_builtins_intl_relativetimeformat + // new Intl.RelativeTimeFormat(this.locale, { + // numeric: this.numeric, + // style: this.type + // }).format(this.value, this.unit); + + return ; + } +}