@aurodesignsystem-dev/auro-datetime 0.0.0-pr110.0 → 0.0.0-pr112.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +30 -41
- package/custom-elements.json +373 -0
- package/demo/api.md +198 -153
- package/demo/api.min.js +125 -136
- package/demo/index.md +14 -11
- package/demo/index.min.js +125 -136
- package/demo/readme.md +21 -20
- package/dist/auro-datetime-CRsYbYbt.js +6 -0
- package/dist/index.d.ts +75 -71
- package/dist/index.js +1 -1
- package/dist/registered.js +1 -1
- package/package.json +8 -6
- package/dist/auro-datetime-39FU0ZIU.js +0 -6
package/demo/api.md
CHANGED
|
@@ -3,35 +3,48 @@
|
|
|
3
3
|
|
|
4
4
|
# auro-datetime
|
|
5
5
|
|
|
6
|
-
|
|
6
|
+
Shows a date or time as text, formatted for a language and region you choose and, optionally, a specific time zone.
|
|
7
|
+
|
|
8
|
+
**Key capabilities**
|
|
9
|
+
- **What to show**: `type` picks the full date, the time, a numeric date, or a single part, such as the year or weekday.
|
|
10
|
+
- **Date and time to show**: `value` takes an ISO 8601 date or date-time; without it, the element shows the current date and time.
|
|
11
|
+
- **Language formatting**: `locale` formats month names, separators, and the 12- or 24-hour clock for a language, such as `de-DE`.
|
|
12
|
+
- **Time zones**: `timezone` shows the moment in a time zone, such as `America/Los_Angeles`.
|
|
13
|
+
- **Name length**: `month="long"` and `weekday="long"` spell out the month and weekday names.
|
|
14
|
+
|
|
15
|
+
**Example**
|
|
16
|
+
<pre class="language-html"><code class="language-html"><auro-datetime type="date" value="2022-07-14T08:00:00"></auro-datetime></code></pre>
|
|
7
17
|
|
|
8
18
|
### Properties & Attributes
|
|
9
19
|
|
|
10
|
-
| Properties | Attributes | Modifiers | Type | Default | Description
|
|
11
|
-
| ---------- | ---------- | --------- | ------------------------------------------------------------------------ | ------- |
|
|
12
|
-
| locale | locale | | string | `en-US` |
|
|
13
|
-
| month | month | |
|
|
14
|
-
| timezone | timezone | | string | |
|
|
15
|
-
| type | type | |
|
|
16
|
-
| value | value | | string | | ISO 8601 date or date-time
|
|
17
|
-
| weekday | weekday | |
|
|
20
|
+
| Properties | Attributes | Modifiers | Type | Default | Description |
|
|
21
|
+
| ---------- | ---------- | --------- | ------------------------------------------------------------------------ | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
22
|
+
| locale | locale | | string | `en-US` | Sets the language and region used to format the date or time, such as `en-GB`, `de-DE`, or `ja-JP` (a BCP 47 language tag). It changes month and weekday names, separators, and whether times use a 12- or 24-hour clock, but not the time zone. A malformed tag logs a console warning and falls back to `en-US`; a well-formed tag the browser doesn't support, such as `zz-ZZ`, uses the browser's default language instead, with no warning. |
|
|
23
|
+
| month | month | | "short" \| "long" | `short` | Sets how the month name is written: `short`, such as "Jul", or `long`, such as "July". It applies to the full date and to `type="month"`. |
|
|
24
|
+
| timezone | timezone | | string | | Sets the time zone to show the date or time in, such as `America/Los_Angeles` or `UTC` (an IANA time zone name). When `value` has an offset or `Z`, the element converts that moment into this zone; when it has none, the element reads `value` as a time already in this zone. Without it, or with an invalid name, which logs a console warning, the element shows the date and time in `value` as written, or the current date and time in the viewer's own time zone when `value` isn't set. |
|
|
25
|
+
| type | type | | "date" \| "time" \| "year" \| "month" \| "weekday" \| "day" \| "numeric" | | Sets which part of the date or time to show: `date` for the full date, such as "Thu, Jul 14, 2022", `numeric` for a numeric date, such as "7/14/2022", `time` for the hour and minute, such as "8:00 am", or `year`, `month`, `weekday`, or `day` for that part alone. Without it, or with any other value, the element shows the full date. |
|
|
26
|
+
| value | value | | string | | Sets the date or time to show, as an ISO 8601 date or date-time, such as `2022-07-14`, `2022-07-14T08:00:00`, or `2022-07-14T08:00:00-07:00`. Without it, the element shows the current date and time from when it last rendered; it doesn't currently update as time passes. Invalid input, including an empty value, logs a console warning and shows nothing. |
|
|
27
|
+
| weekday | weekday | | "short" \| "long" | `short` | Sets how the weekday name is written: `short`, such as "Thu", or `long`, such as "Thursday". It applies to the full date and to `type="weekday"`. |
|
|
18
28
|
|
|
19
29
|
### Methods
|
|
20
30
|
|
|
21
|
-
| Name | Parameters
|
|
22
|
-
| -------- |
|
|
23
|
-
| register | `name` (string) - The name
|
|
31
|
+
| Name | Parameters | Return | Description |
|
|
32
|
+
| -------- | ---------------------------------------------------------------------------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
|
33
|
+
| register | `name` (string) - The tag name to register the element under, such as `custom-datetime`. | void | Registers the element with the browser under a tag name. Use a custom name to run more than one version of the element on the same page. If the tag name is already registered, it does nothing. |
|
|
24
34
|
|
|
25
35
|
### Slots
|
|
26
36
|
|
|
27
|
-
| Name
|
|
28
|
-
|
|
|
29
|
-
|
|
|
30
|
-
|
|
|
37
|
+
| Name | Description |
|
|
38
|
+
| --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
39
|
+
| (default) | Content shown after the `post` slot's content, such as the end of a sentence that includes the date. |
|
|
40
|
+
| post | Content shown after the date or time, such as "local time". The element doesn't currently let content sit right against the date or time: this content, or text right after the element, always shows with a space between them, so a period or comma can't follow the date or time directly. |
|
|
41
|
+
| pre | Content shown before the date or time, such as "Departs". The element doesn't currently let content sit right against the date or time: this content, or text right before the element, always shows with a space between it and the date or time. |
|
|
31
42
|
<!-- AURO-GENERATED-CONTENT:END -->
|
|
32
43
|
|
|
33
|
-
## Basic
|
|
34
|
-
|
|
44
|
+
## Basic
|
|
45
|
+
|
|
46
|
+
Without `value`, the element shows today's date.
|
|
47
|
+
|
|
35
48
|
<div class="exampleWrapper">
|
|
36
49
|
<!-- AURO-GENERATED-CONTENT:START (FILE:src=./../apiExamples/basic.html) -->
|
|
37
50
|
<!-- The below content is automatically added from ./../apiExamples/basic.html -->
|
|
@@ -43,12 +56,20 @@ The `auro-datetime` element is for the purposes of providing an easy to use date
|
|
|
43
56
|
<!-- AURO-GENERATED-CONTENT:START (CODE:src=./../apiExamples/basic.html) -->
|
|
44
57
|
<!-- The below code snippet is automatically added from ./../apiExamples/basic.html -->
|
|
45
58
|
|
|
46
|
-
<pre class="language-html"><code class="language-html"><auro-datetime type="date"></auro-datetime></code></pre>
|
|
59
|
+
<pre class="language-html"><code class="language-html"><auro-datetime type="date"></auro-datetime></code></pre>
|
|
47
60
|
<!-- AURO-GENERATED-CONTENT:END -->
|
|
48
61
|
</auro-accordion>
|
|
49
62
|
|
|
50
|
-
##
|
|
63
|
+
## Property and attribute examples
|
|
51
64
|
|
|
65
|
+
### Type
|
|
66
|
+
|
|
67
|
+
Use `type` to choose what to show: `date` for the full date, `numeric` for a short numeric date, `time` for the hour and minute, or `year`, `month`, `weekday`, or `day` for a single part. Without `type`, the element shows the full date.
|
|
68
|
+
|
|
69
|
+
#### Time
|
|
70
|
+
|
|
71
|
+
`type="time"` shows the hour and minute. When the time ends in AM or PM, the element writes it in lowercase and drops a leading zero, such as "8:00 am".
|
|
72
|
+
|
|
52
73
|
<div class="exampleWrapper">
|
|
53
74
|
<!-- AURO-GENERATED-CONTENT:START (FILE:src=./../apiExamples/basic-time.html) -->
|
|
54
75
|
<!-- The below content is automatically added from ./../apiExamples/basic-time.html -->
|
|
@@ -60,17 +81,124 @@ The `auro-datetime` element is for the purposes of providing an easy to use date
|
|
|
60
81
|
<!-- AURO-GENERATED-CONTENT:START (CODE:src=./../apiExamples/basic-time.html) -->
|
|
61
82
|
<!-- The below code snippet is automatically added from ./../apiExamples/basic-time.html -->
|
|
62
83
|
|
|
63
|
-
<pre class="language-html"><code class="language-html"><auro-datetime type="time"></auro-datetime></code></pre>
|
|
84
|
+
<pre class="language-html"><code class="language-html"><auro-datetime type="time"></auro-datetime></code></pre>
|
|
85
|
+
<!-- AURO-GENERATED-CONTENT:END -->
|
|
86
|
+
</auro-accordion>
|
|
87
|
+
|
|
88
|
+
#### Numeric date
|
|
89
|
+
|
|
90
|
+
`type="numeric"` shows the date in numbers, in the order and with the separators that `locale` uses. With the default `en-US` locale, that's month, day, and year, such as "7/14/2022".
|
|
91
|
+
|
|
92
|
+
<div class="exampleWrapper">
|
|
93
|
+
<!-- AURO-GENERATED-CONTENT:START (FILE:src=../apiExamples/numeric-date.html) -->
|
|
94
|
+
<!-- The below content is automatically added from ../apiExamples/numeric-date.html -->
|
|
95
|
+
<auro-datetime type="numeric"></auro-datetime>
|
|
96
|
+
<!-- AURO-GENERATED-CONTENT:END -->
|
|
97
|
+
</div>
|
|
98
|
+
<auro-accordion alignRight>
|
|
99
|
+
<span slot="trigger">See code</span>
|
|
100
|
+
<!-- AURO-GENERATED-CONTENT:START (CODE:src=../apiExamples/numeric-date.html) -->
|
|
101
|
+
<!-- The below code snippet is automatically added from ../apiExamples/numeric-date.html -->
|
|
102
|
+
|
|
103
|
+
<pre class="language-html"><code class="language-html"><auro-datetime type="numeric"></auro-datetime></code></pre>
|
|
104
|
+
<!-- AURO-GENERATED-CONTENT:END -->
|
|
105
|
+
</auro-accordion>
|
|
106
|
+
|
|
107
|
+
### Value
|
|
108
|
+
|
|
109
|
+
Use `value` to set the date or time to show, as an ISO 8601 date or date-time. It replaces the `setDate` and `utc` attributes from earlier versions. It accepts forms such as these:
|
|
110
|
+
|
|
111
|
+
- `2022-07-14T08:00:00-07:00`: a date and time with an offset.
|
|
112
|
+
- `2022-07-14T08:00:00Z`: a date and time in UTC.
|
|
113
|
+
- `2022-07-14T08:00:00`: a date and time with no offset.
|
|
114
|
+
- `2022-07-14`: a date only.
|
|
115
|
+
|
|
116
|
+
Without `timezone`, the element shows the date and time as written in `value`, ignoring any offset or `Z`. Invalid input, including an empty value, logs a console warning and shows nothing.
|
|
117
|
+
|
|
118
|
+
<div class="exampleWrapper">
|
|
119
|
+
<!-- AURO-GENERATED-CONTENT:START (FILE:src=../apiExamples/set-date.html) -->
|
|
120
|
+
<!-- The below content is automatically added from ../apiExamples/set-date.html -->
|
|
121
|
+
<auro-datetime value="1975-08-19T23:15:30"></auro-datetime><br>
|
|
122
|
+
<auro-datetime weekday="long" month="long" value="1975-08-19T23:15:30"></auro-datetime><br>
|
|
123
|
+
<auro-datetime type="time" value="1975-08-19T23:15:30"></auro-datetime>
|
|
124
|
+
<!-- AURO-GENERATED-CONTENT:END -->
|
|
125
|
+
</div>
|
|
126
|
+
<auro-accordion alignRight>
|
|
127
|
+
<span slot="trigger">See code</span>
|
|
128
|
+
<!-- AURO-GENERATED-CONTENT:START (CODE:src=../apiExamples/set-date.html) -->
|
|
129
|
+
<!-- The below code snippet is automatically added from ../apiExamples/set-date.html -->
|
|
130
|
+
|
|
131
|
+
<pre class="language-html"><code class="language-html"><auro-datetime value="1975-08-19T23:15:30"></auro-datetime><br>
|
|
132
|
+
<auro-datetime weekday="long" month="long" value="1975-08-19T23:15:30"></auro-datetime><br>
|
|
133
|
+
<auro-datetime type="time" value="1975-08-19T23:15:30"></auro-datetime></code></pre>
|
|
134
|
+
<!-- AURO-GENERATED-CONTENT:END -->
|
|
135
|
+
</auro-accordion>
|
|
136
|
+
|
|
137
|
+
#### UTC input
|
|
138
|
+
|
|
139
|
+
A `value` that ends in `Z` is in UTC. Without `timezone`, the element still shows the date and time as written, so set `timezone` to show that moment in another time zone.
|
|
140
|
+
|
|
141
|
+
<div class="exampleWrapper">
|
|
142
|
+
<!-- AURO-GENERATED-CONTENT:START (FILE:src=../apiExamples/utc.html) -->
|
|
143
|
+
<!-- The below content is automatically added from ../apiExamples/utc.html -->
|
|
144
|
+
<auro-datetime value="2020-09-22T01:38:22Z"></auro-datetime><br>
|
|
145
|
+
<auro-datetime type="time" value="2020-09-22T01:38:22Z"></auro-datetime><br>
|
|
146
|
+
<auro-datetime weekday="long" month="long" value="2020-09-22T01:38:22Z"></auro-datetime>
|
|
147
|
+
<!-- AURO-GENERATED-CONTENT:END -->
|
|
148
|
+
</div>
|
|
149
|
+
<auro-accordion alignRight>
|
|
150
|
+
<span slot="trigger">See code</span>
|
|
151
|
+
<!-- AURO-GENERATED-CONTENT:START (CODE:src=../apiExamples/utc.html) -->
|
|
152
|
+
<!-- The below code snippet is automatically added from ../apiExamples/utc.html -->
|
|
153
|
+
|
|
154
|
+
<pre class="language-html"><code class="language-html"><auro-datetime value="2020-09-22T01:38:22Z"></auro-datetime><br>
|
|
155
|
+
<auro-datetime type="time" value="2020-09-22T01:38:22Z"></auro-datetime><br>
|
|
156
|
+
<auro-datetime weekday="long" month="long" value="2020-09-22T01:38:22Z"></auro-datetime></code></pre>
|
|
64
157
|
<!-- AURO-GENERATED-CONTENT:END -->
|
|
65
158
|
</auro-accordion>
|
|
66
159
|
|
|
67
|
-
|
|
160
|
+
### Time zone
|
|
161
|
+
|
|
162
|
+
Use `timezone` with an IANA time zone name, such as `America/Los_Angeles` or `UTC`, to show the date or time in that zone. How it works depends on whether `value` has an offset:
|
|
163
|
+
|
|
164
|
+
- **`value` has an offset or `Z`:** the element converts that moment into `timezone`. For example, `type="time" value="2022-07-14T08:00:00-04:00" timezone="America/Los_Angeles"` shows "5:00 am", because 8:00 am Eastern is 5:00 am Pacific.
|
|
165
|
+
- **`value` has no offset:** the element reads `value` as a time already in `timezone`, so every reader sees the same result. For example, `type="time" value="2022-07-14T08:00:00" timezone="America/New_York"` shows "8:00 am" wherever the reader is. Use this form when you know the zone a time belongs to but don't have its offset, such as flight times listed by airport.
|
|
166
|
+
- **`value` isn't set:** the element shows the current date or time in `timezone`, as in the example below.
|
|
167
|
+
|
|
168
|
+
<div class="exampleWrapper">
|
|
169
|
+
<!-- AURO-GENERATED-CONTENT:START (FILE:src=../apiExamples/timezone.html) -->
|
|
170
|
+
<!-- The below content is automatically added from ../apiExamples/timezone.html -->
|
|
171
|
+
<p>Your time zone: <auro-datetime type="time"></auro-datetime></p>
|
|
172
|
+
<p>Hawai'i: <auro-datetime type="time" timezone="Pacific/Honolulu"></auro-datetime></p>
|
|
173
|
+
<p>West coast: <auro-datetime type="time" timezone="America/Los_Angeles"></auro-datetime></p>
|
|
174
|
+
<p>Mountain: <auro-datetime type="time" timezone="America/Denver"></auro-datetime></p>
|
|
175
|
+
<p>Midwest: <auro-datetime type="time" timezone="America/Chicago"></auro-datetime></p>
|
|
176
|
+
<p>East coast: <auro-datetime type="time" timezone="America/New_York"></auro-datetime></p>
|
|
177
|
+
<p>Puerto Rico: <auro-datetime type="time" timezone="America/Puerto_Rico"></auro-datetime></p>
|
|
178
|
+
<p>UTC: <auro-datetime type="time" timezone="UTC"></auro-datetime></p>
|
|
179
|
+
<!-- AURO-GENERATED-CONTENT:END -->
|
|
180
|
+
</div>
|
|
181
|
+
<auro-accordion alignRight>
|
|
182
|
+
<span slot="trigger">See code</span>
|
|
183
|
+
<!-- AURO-GENERATED-CONTENT:START (CODE:src=../apiExamples/timezone.html) -->
|
|
184
|
+
<!-- The below code snippet is automatically added from ../apiExamples/timezone.html -->
|
|
185
|
+
|
|
186
|
+
<pre class="language-html"><code class="language-html"><p>Your time zone: <auro-datetime type="time"></auro-datetime></p>
|
|
187
|
+
<p>Hawai'i: <auro-datetime type="time" timezone="Pacific/Honolulu"></auro-datetime></p>
|
|
188
|
+
<p>West coast: <auro-datetime type="time" timezone="America/Los_Angeles"></auro-datetime></p>
|
|
189
|
+
<p>Mountain: <auro-datetime type="time" timezone="America/Denver"></auro-datetime></p>
|
|
190
|
+
<p>Midwest: <auro-datetime type="time" timezone="America/Chicago"></auro-datetime></p>
|
|
191
|
+
<p>East coast: <auro-datetime type="time" timezone="America/New_York"></auro-datetime></p>
|
|
192
|
+
<p>Puerto Rico: <auro-datetime type="time" timezone="America/Puerto_Rico"></auro-datetime></p>
|
|
193
|
+
<p>UTC: <auro-datetime type="time" timezone="UTC"></auro-datetime></p></code></pre>
|
|
194
|
+
<!-- AURO-GENERATED-CONTENT:END -->
|
|
195
|
+
</auro-accordion>
|
|
68
196
|
|
|
69
|
-
###
|
|
197
|
+
### Locale
|
|
70
198
|
|
|
71
|
-
Use
|
|
199
|
+
Use `locale` with a [BCP 47 language tag](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl#locales_argument), such as `en-GB`, `de-DE`, or `ja-JP`, to format the date or time for that language and region. Without it, the element uses `en-US`. `locale` changes month and weekday names, separators, and the clock style, but not the time zone.
|
|
72
200
|
|
|
73
|
-
#### Locale with
|
|
201
|
+
#### Locale with a full date
|
|
74
202
|
|
|
75
203
|
<div class="exampleWrapper">
|
|
76
204
|
<!-- AURO-GENERATED-CONTENT:START (FILE:src=../apiExamples/locale-date.html) -->
|
|
@@ -87,11 +215,11 @@ Use the `locale` attribute with a [BCP 47 language tag](https://developer.mozill
|
|
|
87
215
|
|
|
88
216
|
<pre class="language-html"><code class="language-html"><auro-datetime type="date" locale="en-GB" value="2020-09-22T01:38:22Z"></auro-datetime><br>
|
|
89
217
|
<auro-datetime type="date" locale="de-DE" value="2020-09-22T01:38:22Z"></auro-datetime><br>
|
|
90
|
-
<auro-datetime type="date" locale="ja-JP" value="2020-09-22T01:38:22Z"></auro-datetime></code></pre>
|
|
218
|
+
<auro-datetime type="date" locale="ja-JP" value="2020-09-22T01:38:22Z"></auro-datetime></code></pre>
|
|
91
219
|
<!-- AURO-GENERATED-CONTENT:END -->
|
|
92
220
|
</auro-accordion>
|
|
93
221
|
|
|
94
|
-
#### Locale with
|
|
222
|
+
#### Locale with a numeric date
|
|
95
223
|
|
|
96
224
|
<div class="exampleWrapper">
|
|
97
225
|
<!-- AURO-GENERATED-CONTENT:START (FILE:src=../apiExamples/locale-numeric.html) -->
|
|
@@ -108,15 +236,15 @@ Use the `locale` attribute with a [BCP 47 language tag](https://developer.mozill
|
|
|
108
236
|
|
|
109
237
|
<pre class="language-html"><code class="language-html"><auro-datetime type="numeric" locale="en-GB" value="2020-09-22T01:38:22Z"></auro-datetime><br>
|
|
110
238
|
<auro-datetime type="numeric" locale="de-DE" value="2020-09-22T01:38:22Z"></auro-datetime><br>
|
|
111
|
-
<auro-datetime type="numeric" locale="ja-JP" value="2020-09-22T01:38:22Z"></auro-datetime></code></pre>
|
|
239
|
+
<auro-datetime type="numeric" locale="ja-JP" value="2020-09-22T01:38:22Z"></auro-datetime></code></pre>
|
|
112
240
|
<!-- AURO-GENERATED-CONTENT:END -->
|
|
113
241
|
</auro-accordion>
|
|
114
242
|
|
|
115
|
-
#### Locale with
|
|
243
|
+
#### Locale with a time
|
|
116
244
|
|
|
117
|
-
|
|
245
|
+
Times vary the most between locales. The examples below show four patterns: a 12-hour clock with "pm" after the time (`en-US`), a 24-hour clock (`de-DE`), a 12-hour clock with the Korean period word before the time (`ko-KR`), and a 12-hour clock with Arabic-Indic digits and an Arabic period marker (`ar-EG`).
|
|
118
246
|
|
|
119
|
-
|
|
247
|
+
The browser decides whether each locale uses a 12- or 24-hour clock, not the element. Some locales, such as `zh-CN`, `ja-JP`, `de-DE`, `fr-FR`, and `en-GB`, use a 24-hour clock for short times.
|
|
120
248
|
|
|
121
249
|
<div class="exampleWrapper">
|
|
122
250
|
<!-- AURO-GENERATED-CONTENT:START (FILE:src=../apiExamples/locale-time.html) -->
|
|
@@ -135,13 +263,13 @@ Note: the choice of 12-hour vs 24-hour is decided by the runtime's `Intl.DateTim
|
|
|
135
263
|
<pre class="language-html"><code class="language-html"><auro-datetime type="time" locale="en-US" value="2020-09-22T14:05:00"></auro-datetime><br>
|
|
136
264
|
<auro-datetime type="time" locale="de-DE" value="2020-09-22T14:05:00"></auro-datetime><br>
|
|
137
265
|
<auro-datetime type="time" locale="ko-KR" value="2020-09-22T14:05:00"></auro-datetime><br>
|
|
138
|
-
<auro-datetime type="time" locale="ar-EG" value="2020-09-22T14:05:00"></auro-datetime></code></pre>
|
|
266
|
+
<auro-datetime type="time" locale="ar-EG" value="2020-09-22T14:05:00"></auro-datetime></code></pre>
|
|
139
267
|
<!-- AURO-GENERATED-CONTENT:END -->
|
|
140
268
|
</auro-accordion>
|
|
141
269
|
|
|
142
|
-
### Long
|
|
270
|
+
### Long month and weekday names
|
|
143
271
|
|
|
144
|
-
Use
|
|
272
|
+
Use `month="long"` to spell out the month name, such as "July", and `weekday="long"` to spell out the weekday name, such as "Thursday".
|
|
145
273
|
|
|
146
274
|
<div class="exampleWrapper">
|
|
147
275
|
<!-- AURO-GENERATED-CONTENT:START (FILE:src=../apiExamples/long.html) -->
|
|
@@ -154,68 +282,57 @@ Use the `month="long"` attribute to display the full month name, and `weekday="l
|
|
|
154
282
|
<!-- AURO-GENERATED-CONTENT:START (CODE:src=../apiExamples/long.html) -->
|
|
155
283
|
<!-- The below code snippet is automatically added from ../apiExamples/long.html -->
|
|
156
284
|
|
|
157
|
-
<pre class="language-html"><code class="language-html"><auro-datetime type="date" month="long" weekday="long"></auro-datetime></code></pre>
|
|
285
|
+
<pre class="language-html"><code class="language-html"><auro-datetime type="date" month="long" weekday="long"></auro-datetime></code></pre>
|
|
158
286
|
<!-- AURO-GENERATED-CONTENT:END -->
|
|
159
287
|
</auro-accordion>
|
|
160
288
|
|
|
161
|
-
###
|
|
162
|
-
|
|
163
|
-
Use the `value` attribute to pass a single ISO 8601 date or date-time string into the element. The `value` attribute is locale-agnostic and replaces the previous `setDate` and `utc` attributes. Accepted shapes include:
|
|
289
|
+
### Invalid `timezone` and `locale` values
|
|
164
290
|
|
|
165
|
-
|
|
166
|
-
- `2022-07-14T08:00:00Z` (UTC, Zulu designator)
|
|
167
|
-
- `2022-07-14T08:00:00` (date-time, no offset)
|
|
168
|
-
- `2022-07-14` (date only)
|
|
291
|
+
An invalid `timezone` or `locale` doesn't break the element. It logs a console warning, once per value for each element, and falls back:
|
|
169
292
|
|
|
170
|
-
Invalid
|
|
293
|
+
- **Invalid `locale`**, such as the malformed tag `xx-INVALID-tag`: the element uses `en-US`.
|
|
294
|
+
- **Invalid `timezone`**, such as the typo `America/Los_Angles`: the element acts as if `timezone` isn't set. With `value` set, it shows the date and time as written, the same for every reader. Without `value`, it shows the current date and time in the reader's own time zone.
|
|
171
295
|
|
|
172
|
-
|
|
173
|
-
<!-- AURO-GENERATED-CONTENT:START (FILE:src=../apiExamples/set-date.html) -->
|
|
174
|
-
<!-- The below content is automatically added from ../apiExamples/set-date.html -->
|
|
175
|
-
<auro-datetime value="1975-08-19T23:15:30"></auro-datetime><br>
|
|
176
|
-
<auro-datetime weekday="long" month="long" value="1975-08-19T23:15:30"></auro-datetime><br>
|
|
177
|
-
<auro-datetime type="time" value="1975-08-19T23:15:30"></auro-datetime>
|
|
178
|
-
<!-- AURO-GENERATED-CONTENT:END -->
|
|
179
|
-
</div>
|
|
180
|
-
<auro-accordion alignRight>
|
|
181
|
-
<span slot="trigger">See code</span>
|
|
182
|
-
<!-- AURO-GENERATED-CONTENT:START (CODE:src=../apiExamples/set-date.html) -->
|
|
183
|
-
<!-- The below code snippet is automatically added from ../apiExamples/set-date.html -->
|
|
296
|
+
A well-formed `locale` tag the browser doesn't support, such as `zz-ZZ`, isn't treated as invalid: it logs no warning, and the browser formats the date in its default language.
|
|
184
297
|
|
|
185
|
-
|
|
186
|
-
<auro-datetime weekday="long" month="long" value="1975-08-19T23:15:30"></auro-datetime><br>
|
|
187
|
-
<auro-datetime type="time" value="1975-08-19T23:15:30"></auro-datetime></code></pre>
|
|
188
|
-
<!-- AURO-GENERATED-CONTENT:END -->
|
|
189
|
-
</auro-accordion>
|
|
298
|
+
## Slot examples
|
|
190
299
|
|
|
191
|
-
###
|
|
300
|
+
### Pre and post slots
|
|
192
301
|
|
|
193
|
-
Use `
|
|
194
|
-
|
|
195
|
-
#### Numeric Date
|
|
302
|
+
Use the `pre` and `post` slots to add text before and after the date or time. This example also puts content in the default slot, which shows after the `post` content.
|
|
196
303
|
|
|
197
|
-
|
|
304
|
+
The element doesn't currently let content sit right against the date or time. Text in the `pre` or `post` slot, or right before or after the element, always shows with a space between it and the date or time, so a period or comma can't follow the date directly. Word your text to avoid it, as this example does.
|
|
198
305
|
|
|
199
306
|
<div class="exampleWrapper">
|
|
200
|
-
<!-- AURO-GENERATED-CONTENT:START (FILE:src=../apiExamples/
|
|
201
|
-
<!-- The below content is automatically added from ../apiExamples/
|
|
202
|
-
<auro-datetime type="
|
|
307
|
+
<!-- AURO-GENERATED-CONTENT:START (FILE:src=../apiExamples/slots.html) -->
|
|
308
|
+
<!-- The below content is automatically added from ../apiExamples/slots.html -->
|
|
309
|
+
<auro-datetime type="day">
|
|
310
|
+
<span slot="pre">Day</span>
|
|
311
|
+
<span slot="post">of <auro-datetime type="month" month="long"></auro-datetime> in the year <auro-datetime type="year"></auro-datetime></span>
|
|
312
|
+
falls on a <auro-datetime type="weekday" weekday="long"></auro-datetime>
|
|
313
|
+
</auro-datetime>
|
|
203
314
|
<!-- AURO-GENERATED-CONTENT:END -->
|
|
204
315
|
</div>
|
|
205
316
|
<auro-accordion alignRight>
|
|
206
317
|
<span slot="trigger">See code</span>
|
|
207
|
-
<!-- AURO-GENERATED-CONTENT:START (CODE:src=../apiExamples/
|
|
208
|
-
<!-- The below code snippet is automatically added from ../apiExamples/
|
|
318
|
+
<!-- AURO-GENERATED-CONTENT:START (CODE:src=../apiExamples/slots.html) -->
|
|
319
|
+
<!-- The below code snippet is automatically added from ../apiExamples/slots.html -->
|
|
209
320
|
|
|
210
|
-
<pre class="language-html"><code class="language-html"><auro-datetime type="
|
|
321
|
+
<pre class="language-html"><code class="language-html"><auro-datetime type="day">
|
|
322
|
+
<span slot="pre">Day</span>
|
|
323
|
+
<span slot="post">of <auro-datetime type="month" month="long"></auro-datetime> in the year <auro-datetime type="year"></auro-datetime></span>
|
|
324
|
+
falls on a <auro-datetime type="weekday" weekday="long"></auro-datetime>
|
|
325
|
+
</auro-datetime></code></pre>
|
|
211
326
|
<!-- AURO-GENERATED-CONTENT:END -->
|
|
212
327
|
</auro-accordion>
|
|
213
328
|
|
|
214
|
-
|
|
329
|
+
## Common usage patterns
|
|
330
|
+
|
|
331
|
+
### Local time at the airport
|
|
215
332
|
|
|
216
|
-
When
|
|
333
|
+
When `value` has an offset and `timezone` isn't set, the element shows the date and time as written in `value`, the same for every reader. Use this to show a flight's local time at its airport, where the offset describes the airport, not the reader.
|
|
217
334
|
|
|
218
|
-
|
|
335
|
+
This example uses `2022-07-13T21:35:00-07:00`, a Pacific time.
|
|
219
336
|
|
|
220
337
|
<div class="exampleWrapper">
|
|
221
338
|
<!-- AURO-GENERATED-CONTENT:START (FILE:src=../apiExamples/plus-minus.html) -->
|
|
@@ -230,85 +347,13 @@ Example using `2022-07-13T21:35:00-07:00`. The same string is rendered identical
|
|
|
230
347
|
<!-- The below code snippet is automatically added from ../apiExamples/plus-minus.html -->
|
|
231
348
|
|
|
232
349
|
<pre class="language-html"><code class="language-html"><auro-datetime type="time" value="2022-07-13T21:35:00-07:00"></auro-datetime><br>
|
|
233
|
-
<auro-datetime type="date" value="2022-07-13T21:35:00-07:00"></auro-datetime></code></pre>
|
|
234
|
-
<!-- AURO-GENERATED-CONTENT:END -->
|
|
235
|
-
</auro-accordion>
|
|
236
|
-
|
|
237
|
-
### UTC (Zulu) input
|
|
238
|
-
|
|
239
|
-
The `value` attribute also accepts ISO 8601 strings ending in the `Z` designator. Without a `timezone` attribute, the wall-clock components are rendered as written. To convert into a viewer-meaningful timezone, also set `timezone` (see the timezone example).
|
|
240
|
-
|
|
241
|
-
<div class="exampleWrapper">
|
|
242
|
-
<!-- AURO-GENERATED-CONTENT:START (FILE:src=../apiExamples/utc.html) -->
|
|
243
|
-
<!-- The below content is automatically added from ../apiExamples/utc.html -->
|
|
244
|
-
<auro-datetime value="2020-09-22T01:38:22Z"></auro-datetime><br>
|
|
245
|
-
<auro-datetime type="time" value="2020-09-22T01:38:22Z"></auro-datetime><br>
|
|
246
|
-
<auro-datetime weekday="long" month="long" value="2020-09-22T01:38:22Z"></auro-datetime>
|
|
247
|
-
<!-- AURO-GENERATED-CONTENT:END -->
|
|
248
|
-
</div>
|
|
249
|
-
<auro-accordion alignRight>
|
|
250
|
-
<span slot="trigger">See code</span>
|
|
251
|
-
<!-- AURO-GENERATED-CONTENT:START (CODE:src=../apiExamples/utc.html) -->
|
|
252
|
-
<!-- The below code snippet is automatically added from ../apiExamples/utc.html -->
|
|
253
|
-
|
|
254
|
-
<pre class="language-html"><code class="language-html"><auro-datetime value="2020-09-22T01:38:22Z"></auro-datetime><br>
|
|
255
|
-
<auro-datetime type="time" value="2020-09-22T01:38:22Z"></auro-datetime><br>
|
|
256
|
-
<auro-datetime weekday="long" month="long" value="2020-09-22T01:38:22Z"></auro-datetime></code></pre>
|
|
257
|
-
<!-- AURO-GENERATED-CONTENT:END -->
|
|
258
|
-
</auro-accordion>
|
|
259
|
-
|
|
260
|
-
### Combining `value` and `timezone`
|
|
261
|
-
|
|
262
|
-
How the `timezone` attribute composes with the input depends on whether `value` carries an offset:
|
|
263
|
-
|
|
264
|
-
- **`value` has an offset (or `Z`):** the offset anchors the absolute moment; `timezone` is the display zone. Example: `value="2022-07-14T08:00:00-04:00" timezone="US/Pacific"` renders as `5:00 am` (8am Eastern → 5am Pacific).
|
|
265
|
-
- **`value` has no offset:** the wall-clock is interpreted as being in `timezone`, so display in that same zone matches the input verbatim. Example: `value="2022-07-14T08:00:00" timezone="US/Eastern"` renders as `8:00 am` regardless of where the viewer is. This is the recommended shape when consumers know the source zone but don't have an offset readily available (e.g. flight-schedule data keyed by airport).
|
|
266
|
-
|
|
267
|
-
#### Invalid `timezone` and `locale` values
|
|
268
|
-
|
|
269
|
-
Both attributes are validated up-front. Invalid inputs do **not** crash the component — they fall back gracefully and log a `console.warn` (deduplicated per element):
|
|
270
|
-
|
|
271
|
-
- **Invalid `locale`** (e.g. `"xx-INVALID-tag"`) → falls back to `"en-US"`.
|
|
272
|
-
- **Invalid `timezone`** (e.g. `"US/Pacfic"` typo) → falls back to behaving as if `timezone` was not specified. With `value` set, that means wall-clock display from the input components — visually the same string for every viewer. With `value` unset, that means the current time in the viewer's machine zone. The warning surfaces the typo so the developer can fix it.
|
|
273
|
-
|
|
274
|
-
## Slot Examples
|
|
275
|
-
|
|
276
|
-
### Pre and Post Slots
|
|
277
|
-
|
|
278
|
-
This example demonstrates the use of the `pre` and `post` slots to customize the content before and after the datetime output.
|
|
279
|
-
|
|
280
|
-
<div class="exampleWrapper">
|
|
281
|
-
<!-- AURO-GENERATED-CONTENT:START (FILE:src=../apiExamples/slots.html) -->
|
|
282
|
-
<!-- The below content is automatically added from ../apiExamples/slots.html -->
|
|
283
|
-
<auro-datetime type="year">
|
|
284
|
-
<span slot="pre">In the year </span>
|
|
285
|
-
<span slot="post">
|
|
286
|
-
day<auro-datetime type="day"></auro-datetime>
|
|
287
|
-
of <auro-datetime type="month" month="long"></auro-datetime>
|
|
288
|
-
</span>falls on a <auro-datetime type="weekday" weekday="long"></auro-datetime>
|
|
289
|
-
</auro-datetime>
|
|
290
|
-
<!-- AURO-GENERATED-CONTENT:END -->
|
|
291
|
-
</div>
|
|
292
|
-
<auro-accordion alignRight>
|
|
293
|
-
<span slot="trigger">See code</span>
|
|
294
|
-
<!-- AURO-GENERATED-CONTENT:START (CODE:src=../apiExamples/slots.html) -->
|
|
295
|
-
<!-- The below code snippet is automatically added from ../apiExamples/slots.html -->
|
|
296
|
-
|
|
297
|
-
<pre class="language-html"><code class="language-html"><auro-datetime type="year">
|
|
298
|
-
<span slot="pre">In the year </span>
|
|
299
|
-
<span slot="post">
|
|
300
|
-
day<auro-datetime type="day"></auro-datetime>
|
|
301
|
-
of <auro-datetime type="month" month="long"></auro-datetime>
|
|
302
|
-
</span>falls on a <auro-datetime type="weekday" weekday="long"></auro-datetime>
|
|
303
|
-
</auro-datetime></code></pre>
|
|
350
|
+
<auro-datetime type="date" value="2022-07-13T21:35:00-07:00"></auro-datetime></code></pre>
|
|
304
351
|
<!-- AURO-GENERATED-CONTENT:END -->
|
|
305
352
|
</auro-accordion>
|
|
306
353
|
|
|
307
|
-
|
|
308
|
-
|
|
309
|
-
### Example using Eastern Time Zone
|
|
354
|
+
#### Eastern time
|
|
310
355
|
|
|
311
|
-
|
|
356
|
+
This example uses `2022-07-14T06:00:00-04:00`, an Eastern time.
|
|
312
357
|
|
|
313
358
|
<div class="exampleWrapper">
|
|
314
359
|
<!-- AURO-GENERATED-CONTENT:START (FILE:src=../apiExamples/east-plus-minus.html) -->
|
|
@@ -323,13 +368,13 @@ Example using `2022-07-14T06:00:00-04:00` with Eastern `(-04:00)` time zone.
|
|
|
323
368
|
<!-- The below code snippet is automatically added from ../apiExamples/east-plus-minus.html -->
|
|
324
369
|
|
|
325
370
|
<pre class="language-html"><code class="language-html"><auro-datetime type="time" value="2022-07-14T06:00:00-04:00"></auro-datetime><br>
|
|
326
|
-
<auro-datetime type="date" value="2022-07-14T06:00:00-04:00"></auro-datetime></code></pre>
|
|
371
|
+
<auro-datetime type="date" value="2022-07-14T06:00:00-04:00"></auro-datetime></code></pre>
|
|
327
372
|
<!-- AURO-GENERATED-CONTENT:END -->
|
|
328
373
|
</auro-accordion>
|
|
329
374
|
|
|
330
|
-
|
|
375
|
+
#### Hawaii time
|
|
331
376
|
|
|
332
|
-
|
|
377
|
+
This example uses `2022-07-16T08:00:00-10:00`, a Hawaii time.
|
|
333
378
|
|
|
334
379
|
<div class="exampleWrapper">
|
|
335
380
|
<!-- AURO-GENERATED-CONTENT:START (FILE:src=../apiExamples/hawaii-plus-minus.html) -->
|
|
@@ -344,6 +389,6 @@ Example using `2022-07-14T08:00:00-10:00` with Hawaii `(-10:00)` time zone.
|
|
|
344
389
|
<!-- The below code snippet is automatically added from ../apiExamples/hawaii-plus-minus.html -->
|
|
345
390
|
|
|
346
391
|
<pre class="language-html"><code class="language-html"><auro-datetime type="time" value="2022-07-16T08:00:00-10:00"></auro-datetime><br>
|
|
347
|
-
<auro-datetime type="date" value="2022-07-16T08:00:00-10:00"></auro-datetime></code></pre>
|
|
392
|
+
<auro-datetime type="date" value="2022-07-16T08:00:00-10:00"></auro-datetime></code></pre>
|
|
348
393
|
<!-- AURO-GENERATED-CONTENT:END -->
|
|
349
394
|
</auro-accordion>
|