@aurodesignsystem-dev/auro-datetime 0.0.0-pr111.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 +251 -232
- package/demo/api.min.js +595 -1
- package/demo/index.md +24 -25
- package/demo/index.min.js +595 -1
- package/demo/readme.md +117 -0
- 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/demo/auro-datetime.min.js +0 -608
- package/dist/auro-datetime-39FU0ZIU.js +0 -6
package/demo/api.md
CHANGED
|
@@ -3,373 +3,392 @@
|
|
|
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
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
49
|
+
<!-- AURO-GENERATED-CONTENT:START (FILE:src=./../apiExamples/basic.html) -->
|
|
50
|
+
<!-- The below content is automatically added from ./../apiExamples/basic.html -->
|
|
51
|
+
<auro-datetime type="date"></auro-datetime>
|
|
52
|
+
<!-- AURO-GENERATED-CONTENT:END -->
|
|
40
53
|
</div>
|
|
41
54
|
<auro-accordion alignRight>
|
|
42
|
-
|
|
55
|
+
<span slot="trigger">See code</span>
|
|
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
|
-
|
|
47
|
-
<auro-datetime type="date"></auro-datetime>
|
|
48
|
-
```
|
|
59
|
+
<pre class="language-html"><code class="language-html"><auro-datetime type="date"></auro-datetime></code></pre>
|
|
49
60
|
<!-- AURO-GENERATED-CONTENT:END -->
|
|
50
61
|
</auro-accordion>
|
|
51
62
|
|
|
52
|
-
##
|
|
63
|
+
## Property and attribute examples
|
|
53
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
|
+
|
|
54
73
|
<div class="exampleWrapper">
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
74
|
+
<!-- AURO-GENERATED-CONTENT:START (FILE:src=./../apiExamples/basic-time.html) -->
|
|
75
|
+
<!-- The below content is automatically added from ./../apiExamples/basic-time.html -->
|
|
76
|
+
<auro-datetime type="time"></auro-datetime>
|
|
77
|
+
<!-- AURO-GENERATED-CONTENT:END -->
|
|
59
78
|
</div>
|
|
60
79
|
<auro-accordion alignRight>
|
|
61
|
-
|
|
80
|
+
<span slot="trigger">See code</span>
|
|
62
81
|
<!-- AURO-GENERATED-CONTENT:START (CODE:src=./../apiExamples/basic-time.html) -->
|
|
63
82
|
<!-- The below code snippet is automatically added from ./../apiExamples/basic-time.html -->
|
|
64
83
|
|
|
65
|
-
|
|
66
|
-
<auro-datetime type="time"></auro-datetime>
|
|
67
|
-
```
|
|
84
|
+
<pre class="language-html"><code class="language-html"><auro-datetime type="time"></auro-datetime></code></pre>
|
|
68
85
|
<!-- AURO-GENERATED-CONTENT:END -->
|
|
69
86
|
</auro-accordion>
|
|
70
87
|
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
### International Date Formatting
|
|
88
|
+
#### Numeric date
|
|
74
89
|
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
#### Locale with type="date"
|
|
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".
|
|
78
91
|
|
|
79
92
|
<div class="exampleWrapper">
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
<auro-datetime type="date" locale="ja-JP" value="2020-09-22T01:38:22Z"></auro-datetime>
|
|
85
|
-
<!-- AURO-GENERATED-CONTENT:END -->
|
|
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 -->
|
|
86
97
|
</div>
|
|
87
98
|
<auro-accordion alignRight>
|
|
88
|
-
|
|
89
|
-
<!-- AURO-GENERATED-CONTENT:START (CODE:src=../apiExamples/
|
|
90
|
-
<!-- The below code snippet is automatically added from ../apiExamples/
|
|
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 -->
|
|
91
102
|
|
|
92
|
-
|
|
93
|
-
<auro-datetime type="date" locale="en-GB" value="2020-09-22T01:38:22Z"></auro-datetime><br>
|
|
94
|
-
<auro-datetime type="date" locale="de-DE" value="2020-09-22T01:38:22Z"></auro-datetime><br>
|
|
95
|
-
<auro-datetime type="date" locale="ja-JP" value="2020-09-22T01:38:22Z"></auro-datetime>
|
|
96
|
-
```
|
|
103
|
+
<pre class="language-html"><code class="language-html"><auro-datetime type="numeric"></auro-datetime></code></pre>
|
|
97
104
|
<!-- AURO-GENERATED-CONTENT:END -->
|
|
98
105
|
</auro-accordion>
|
|
99
106
|
|
|
100
|
-
|
|
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.
|
|
101
117
|
|
|
102
118
|
<div class="exampleWrapper">
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
|
|
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 -->
|
|
109
125
|
</div>
|
|
110
126
|
<auro-accordion alignRight>
|
|
111
|
-
|
|
112
|
-
<!-- AURO-GENERATED-CONTENT:START (CODE:src=../apiExamples/
|
|
113
|
-
<!-- The below code snippet is automatically added from ../apiExamples/
|
|
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 -->
|
|
114
130
|
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
|
|
118
|
-
<auro-datetime type="numeric" locale="ja-JP" value="2020-09-22T01:38:22Z"></auro-datetime>
|
|
119
|
-
```
|
|
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>
|
|
120
134
|
<!-- AURO-GENERATED-CONTENT:END -->
|
|
121
135
|
</auro-accordion>
|
|
122
136
|
|
|
123
|
-
####
|
|
124
|
-
|
|
125
|
-
Time is the most format-divergent type across locales. The examples below highlight four distinct patterns: 12-hour with a Latin am/pm suffix (`en-US`), 24-hour with no marker (`de-DE`), 12-hour with a Korean period prefix (`ko-KR` → `오후`), and 12-hour with Arabic-Indic digits and an Arabic period marker (`ar-EG` → `م`).
|
|
137
|
+
#### UTC input
|
|
126
138
|
|
|
127
|
-
|
|
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.
|
|
128
140
|
|
|
129
141
|
<div class="exampleWrapper">
|
|
130
|
-
|
|
131
|
-
|
|
132
|
-
|
|
133
|
-
|
|
134
|
-
|
|
135
|
-
|
|
136
|
-
<!-- AURO-GENERATED-CONTENT:END -->
|
|
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 -->
|
|
137
148
|
</div>
|
|
138
149
|
<auro-accordion alignRight>
|
|
139
|
-
|
|
140
|
-
<!-- AURO-GENERATED-CONTENT:START (CODE:src=../apiExamples/
|
|
141
|
-
<!-- The below code snippet is automatically added from ../apiExamples/
|
|
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 -->
|
|
142
153
|
|
|
143
|
-
|
|
144
|
-
|
|
145
|
-
|
|
146
|
-
<auro-datetime type="time" locale="ko-KR" value="2020-09-22T14:05:00"></auro-datetime><br>
|
|
147
|
-
<auro-datetime type="time" locale="ar-EG" value="2020-09-22T14:05:00"></auro-datetime>
|
|
148
|
-
```
|
|
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>
|
|
149
157
|
<!-- AURO-GENERATED-CONTENT:END -->
|
|
150
158
|
</auro-accordion>
|
|
151
159
|
|
|
152
|
-
###
|
|
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:
|
|
153
163
|
|
|
154
|
-
|
|
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.
|
|
155
167
|
|
|
156
168
|
<div class="exampleWrapper">
|
|
157
|
-
|
|
158
|
-
|
|
159
|
-
|
|
160
|
-
|
|
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 -->
|
|
161
180
|
</div>
|
|
162
181
|
<auro-accordion alignRight>
|
|
163
|
-
|
|
164
|
-
<!-- AURO-GENERATED-CONTENT:START (CODE:src=../apiExamples/
|
|
165
|
-
<!-- The below code snippet is automatically added from ../apiExamples/
|
|
166
|
-
|
|
167
|
-
|
|
168
|
-
|
|
169
|
-
|
|
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>
|
|
170
194
|
<!-- AURO-GENERATED-CONTENT:END -->
|
|
171
195
|
</auro-accordion>
|
|
172
196
|
|
|
173
|
-
###
|
|
197
|
+
### Locale
|
|
174
198
|
|
|
175
|
-
Use
|
|
176
|
-
|
|
177
|
-
|
|
178
|
-
- `2022-07-14T08:00:00Z` (UTC, Zulu designator)
|
|
179
|
-
- `2022-07-14T08:00:00` (date-time, no offset)
|
|
180
|
-
- `2022-07-14` (date only)
|
|
181
|
-
|
|
182
|
-
Invalid input is logged as a warning and renders nothing.
|
|
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.
|
|
200
|
+
|
|
201
|
+
#### Locale with a full date
|
|
183
202
|
|
|
184
203
|
<div class="exampleWrapper">
|
|
185
|
-
|
|
186
|
-
|
|
187
|
-
|
|
188
|
-
|
|
189
|
-
|
|
190
|
-
|
|
204
|
+
<!-- AURO-GENERATED-CONTENT:START (FILE:src=../apiExamples/locale-date.html) -->
|
|
205
|
+
<!-- The below content is automatically added from ../apiExamples/locale-date.html -->
|
|
206
|
+
<auro-datetime type="date" locale="en-GB" value="2020-09-22T01:38:22Z"></auro-datetime><br>
|
|
207
|
+
<auro-datetime type="date" locale="de-DE" value="2020-09-22T01:38:22Z"></auro-datetime><br>
|
|
208
|
+
<auro-datetime type="date" locale="ja-JP" value="2020-09-22T01:38:22Z"></auro-datetime>
|
|
209
|
+
<!-- AURO-GENERATED-CONTENT:END -->
|
|
191
210
|
</div>
|
|
192
211
|
<auro-accordion alignRight>
|
|
193
|
-
|
|
194
|
-
<!-- AURO-GENERATED-CONTENT:START (CODE:src=../apiExamples/
|
|
195
|
-
<!-- The below code snippet is automatically added from ../apiExamples/
|
|
212
|
+
<span slot="trigger">See code</span>
|
|
213
|
+
<!-- AURO-GENERATED-CONTENT:START (CODE:src=../apiExamples/locale-date.html) -->
|
|
214
|
+
<!-- The below code snippet is automatically added from ../apiExamples/locale-date.html -->
|
|
196
215
|
|
|
197
|
-
|
|
198
|
-
|
|
199
|
-
|
|
200
|
-
<auro-datetime type="time" value="1975-08-19T23:15:30"></auro-datetime>
|
|
201
|
-
```
|
|
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>
|
|
217
|
+
<auro-datetime type="date" locale="de-DE" value="2020-09-22T01:38:22Z"></auro-datetime><br>
|
|
218
|
+
<auro-datetime type="date" locale="ja-JP" value="2020-09-22T01:38:22Z"></auro-datetime></code></pre>
|
|
202
219
|
<!-- AURO-GENERATED-CONTENT:END -->
|
|
203
220
|
</auro-accordion>
|
|
204
221
|
|
|
205
|
-
|
|
206
|
-
|
|
207
|
-
Use `type` to define the type of data to render. Options are `[date, time, year, month, weekday, day, numeric]`.
|
|
208
|
-
|
|
209
|
-
#### Numeric Date
|
|
210
|
-
|
|
211
|
-
Using the `auro-datetime` element with `type=numeric` will return the **current date** based on client local preferences as a numeric type.
|
|
222
|
+
#### Locale with a numeric date
|
|
212
223
|
|
|
213
224
|
<div class="exampleWrapper">
|
|
214
|
-
|
|
215
|
-
|
|
216
|
-
|
|
217
|
-
|
|
225
|
+
<!-- AURO-GENERATED-CONTENT:START (FILE:src=../apiExamples/locale-numeric.html) -->
|
|
226
|
+
<!-- The below content is automatically added from ../apiExamples/locale-numeric.html -->
|
|
227
|
+
<auro-datetime type="numeric" locale="en-GB" value="2020-09-22T01:38:22Z"></auro-datetime><br>
|
|
228
|
+
<auro-datetime type="numeric" locale="de-DE" value="2020-09-22T01:38:22Z"></auro-datetime><br>
|
|
229
|
+
<auro-datetime type="numeric" locale="ja-JP" value="2020-09-22T01:38:22Z"></auro-datetime>
|
|
230
|
+
<!-- AURO-GENERATED-CONTENT:END -->
|
|
218
231
|
</div>
|
|
219
232
|
<auro-accordion alignRight>
|
|
220
|
-
|
|
221
|
-
<!-- AURO-GENERATED-CONTENT:START (CODE:src=../apiExamples/numeric
|
|
222
|
-
<!-- The below code snippet is automatically added from ../apiExamples/numeric
|
|
233
|
+
<span slot="trigger">See code</span>
|
|
234
|
+
<!-- AURO-GENERATED-CONTENT:START (CODE:src=../apiExamples/locale-numeric.html) -->
|
|
235
|
+
<!-- The below code snippet is automatically added from ../apiExamples/locale-numeric.html -->
|
|
223
236
|
|
|
224
|
-
|
|
225
|
-
|
|
226
|
-
|
|
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>
|
|
238
|
+
<auro-datetime type="numeric" locale="de-DE" value="2020-09-22T01:38:22Z"></auro-datetime><br>
|
|
239
|
+
<auro-datetime type="numeric" locale="ja-JP" value="2020-09-22T01:38:22Z"></auro-datetime></code></pre>
|
|
227
240
|
<!-- AURO-GENERATED-CONTENT:END -->
|
|
228
241
|
</auro-accordion>
|
|
229
242
|
|
|
230
|
-
####
|
|
243
|
+
#### Locale with a time
|
|
231
244
|
|
|
232
|
-
|
|
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`).
|
|
233
246
|
|
|
234
|
-
|
|
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.
|
|
235
248
|
|
|
236
249
|
<div class="exampleWrapper">
|
|
237
|
-
|
|
238
|
-
|
|
239
|
-
|
|
240
|
-
|
|
241
|
-
|
|
250
|
+
<!-- AURO-GENERATED-CONTENT:START (FILE:src=../apiExamples/locale-time.html) -->
|
|
251
|
+
<!-- The below content is automatically added from ../apiExamples/locale-time.html -->
|
|
252
|
+
<auro-datetime type="time" locale="en-US" value="2020-09-22T14:05:00"></auro-datetime><br>
|
|
253
|
+
<auro-datetime type="time" locale="de-DE" value="2020-09-22T14:05:00"></auro-datetime><br>
|
|
254
|
+
<auro-datetime type="time" locale="ko-KR" value="2020-09-22T14:05:00"></auro-datetime><br>
|
|
255
|
+
<auro-datetime type="time" locale="ar-EG" value="2020-09-22T14:05:00"></auro-datetime>
|
|
256
|
+
<!-- AURO-GENERATED-CONTENT:END -->
|
|
242
257
|
</div>
|
|
243
258
|
<auro-accordion alignRight>
|
|
244
|
-
|
|
245
|
-
<!-- AURO-GENERATED-CONTENT:START (CODE:src=../apiExamples/
|
|
246
|
-
<!-- The below code snippet is automatically added from ../apiExamples/
|
|
259
|
+
<span slot="trigger">See code</span>
|
|
260
|
+
<!-- AURO-GENERATED-CONTENT:START (CODE:src=../apiExamples/locale-time.html) -->
|
|
261
|
+
<!-- The below code snippet is automatically added from ../apiExamples/locale-time.html -->
|
|
247
262
|
|
|
248
|
-
|
|
249
|
-
|
|
250
|
-
|
|
251
|
-
|
|
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>
|
|
264
|
+
<auro-datetime type="time" locale="de-DE" value="2020-09-22T14:05:00"></auro-datetime><br>
|
|
265
|
+
<auro-datetime type="time" locale="ko-KR" value="2020-09-22T14:05:00"></auro-datetime><br>
|
|
266
|
+
<auro-datetime type="time" locale="ar-EG" value="2020-09-22T14:05:00"></auro-datetime></code></pre>
|
|
252
267
|
<!-- AURO-GENERATED-CONTENT:END -->
|
|
253
268
|
</auro-accordion>
|
|
254
269
|
|
|
255
|
-
###
|
|
270
|
+
### Long month and weekday names
|
|
256
271
|
|
|
257
|
-
|
|
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".
|
|
258
273
|
|
|
259
274
|
<div class="exampleWrapper">
|
|
260
|
-
|
|
261
|
-
|
|
262
|
-
|
|
263
|
-
|
|
264
|
-
<auro-datetime weekday="long" month="long" value="2020-09-22T01:38:22Z"></auro-datetime>
|
|
265
|
-
<!-- AURO-GENERATED-CONTENT:END -->
|
|
275
|
+
<!-- AURO-GENERATED-CONTENT:START (FILE:src=../apiExamples/long.html) -->
|
|
276
|
+
<!-- The below content is automatically added from ../apiExamples/long.html -->
|
|
277
|
+
<auro-datetime type="date" month="long" weekday="long"></auro-datetime>
|
|
278
|
+
<!-- AURO-GENERATED-CONTENT:END -->
|
|
266
279
|
</div>
|
|
267
280
|
<auro-accordion alignRight>
|
|
268
|
-
|
|
269
|
-
<!-- AURO-GENERATED-CONTENT:START (CODE:src=../apiExamples/
|
|
270
|
-
<!-- The below code snippet is automatically added from ../apiExamples/
|
|
281
|
+
<span slot="trigger">See code</span>
|
|
282
|
+
<!-- AURO-GENERATED-CONTENT:START (CODE:src=../apiExamples/long.html) -->
|
|
283
|
+
<!-- The below code snippet is automatically added from ../apiExamples/long.html -->
|
|
271
284
|
|
|
272
|
-
|
|
273
|
-
<auro-datetime value="2020-09-22T01:38:22Z"></auro-datetime><br>
|
|
274
|
-
<auro-datetime type="time" value="2020-09-22T01:38:22Z"></auro-datetime><br>
|
|
275
|
-
<auro-datetime weekday="long" month="long" value="2020-09-22T01:38:22Z"></auro-datetime>
|
|
276
|
-
```
|
|
285
|
+
<pre class="language-html"><code class="language-html"><auro-datetime type="date" month="long" weekday="long"></auro-datetime></code></pre>
|
|
277
286
|
<!-- AURO-GENERATED-CONTENT:END -->
|
|
278
287
|
</auro-accordion>
|
|
279
288
|
|
|
280
|
-
###
|
|
281
|
-
|
|
282
|
-
How the `timezone` attribute composes with the input depends on whether `value` carries an offset:
|
|
289
|
+
### Invalid `timezone` and `locale` values
|
|
283
290
|
|
|
284
|
-
|
|
285
|
-
- **`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).
|
|
286
|
-
|
|
287
|
-
#### Invalid `timezone` and `locale` values
|
|
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:
|
|
288
292
|
|
|
289
|
-
|
|
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.
|
|
290
295
|
|
|
291
|
-
-
|
|
292
|
-
- **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.
|
|
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.
|
|
293
297
|
|
|
294
|
-
## Slot
|
|
298
|
+
## Slot examples
|
|
295
299
|
|
|
296
|
-
### Pre and
|
|
300
|
+
### Pre and post slots
|
|
297
301
|
|
|
298
|
-
|
|
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.
|
|
303
|
+
|
|
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.
|
|
299
305
|
|
|
300
306
|
<div class="exampleWrapper">
|
|
301
|
-
|
|
302
|
-
|
|
303
|
-
|
|
304
|
-
|
|
305
|
-
|
|
306
|
-
|
|
307
|
-
|
|
308
|
-
|
|
309
|
-
</auro-datetime>
|
|
310
|
-
<!-- AURO-GENERATED-CONTENT:END -->
|
|
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>
|
|
314
|
+
<!-- AURO-GENERATED-CONTENT:END -->
|
|
311
315
|
</div>
|
|
312
316
|
<auro-accordion alignRight>
|
|
313
|
-
|
|
317
|
+
<span slot="trigger">See code</span>
|
|
314
318
|
<!-- AURO-GENERATED-CONTENT:START (CODE:src=../apiExamples/slots.html) -->
|
|
315
319
|
<!-- The below code snippet is automatically added from ../apiExamples/slots.html -->
|
|
316
320
|
|
|
317
|
-
|
|
318
|
-
|
|
319
|
-
|
|
320
|
-
|
|
321
|
-
|
|
322
|
-
of <auro-datetime type="month" month="long"></auro-datetime>
|
|
323
|
-
</span>falls on a <auro-datetime type="weekday" weekday="long"></auro-datetime>
|
|
324
|
-
</auro-datetime>
|
|
325
|
-
```
|
|
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>
|
|
326
326
|
<!-- AURO-GENERATED-CONTENT:END -->
|
|
327
327
|
</auro-accordion>
|
|
328
328
|
|
|
329
|
-
## Common
|
|
329
|
+
## Common usage patterns
|
|
330
|
+
|
|
331
|
+
### Local time at the airport
|
|
332
|
+
|
|
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.
|
|
334
|
+
|
|
335
|
+
This example uses `2022-07-13T21:35:00-07:00`, a Pacific time.
|
|
336
|
+
|
|
337
|
+
<div class="exampleWrapper">
|
|
338
|
+
<!-- AURO-GENERATED-CONTENT:START (FILE:src=../apiExamples/plus-minus.html) -->
|
|
339
|
+
<!-- The below content is automatically added from ../apiExamples/plus-minus.html -->
|
|
340
|
+
<auro-datetime type="time" value="2022-07-13T21:35:00-07:00"></auro-datetime><br>
|
|
341
|
+
<auro-datetime type="date" value="2022-07-13T21:35:00-07:00"></auro-datetime>
|
|
342
|
+
<!-- AURO-GENERATED-CONTENT:END -->
|
|
343
|
+
</div>
|
|
344
|
+
<auro-accordion alignRight>
|
|
345
|
+
<span slot="trigger">See code</span>
|
|
346
|
+
<!-- AURO-GENERATED-CONTENT:START (CODE:src=../apiExamples/plus-minus.html) -->
|
|
347
|
+
<!-- The below code snippet is automatically added from ../apiExamples/plus-minus.html -->
|
|
348
|
+
|
|
349
|
+
<pre class="language-html"><code class="language-html"><auro-datetime type="time" value="2022-07-13T21:35:00-07:00"></auro-datetime><br>
|
|
350
|
+
<auro-datetime type="date" value="2022-07-13T21:35:00-07:00"></auro-datetime></code></pre>
|
|
351
|
+
<!-- AURO-GENERATED-CONTENT:END -->
|
|
352
|
+
</auro-accordion>
|
|
330
353
|
|
|
331
|
-
|
|
354
|
+
#### Eastern time
|
|
332
355
|
|
|
333
|
-
|
|
356
|
+
This example uses `2022-07-14T06:00:00-04:00`, an Eastern time.
|
|
334
357
|
|
|
335
358
|
<div class="exampleWrapper">
|
|
336
|
-
|
|
337
|
-
|
|
338
|
-
|
|
339
|
-
|
|
340
|
-
|
|
359
|
+
<!-- AURO-GENERATED-CONTENT:START (FILE:src=../apiExamples/east-plus-minus.html) -->
|
|
360
|
+
<!-- The below content is automatically added from ../apiExamples/east-plus-minus.html -->
|
|
361
|
+
<auro-datetime type="time" value="2022-07-14T06:00:00-04:00"></auro-datetime><br>
|
|
362
|
+
<auro-datetime type="date" value="2022-07-14T06:00:00-04:00"></auro-datetime>
|
|
363
|
+
<!-- AURO-GENERATED-CONTENT:END -->
|
|
341
364
|
</div>
|
|
342
365
|
<auro-accordion alignRight>
|
|
343
|
-
|
|
366
|
+
<span slot="trigger">See code</span>
|
|
344
367
|
<!-- AURO-GENERATED-CONTENT:START (CODE:src=../apiExamples/east-plus-minus.html) -->
|
|
345
368
|
<!-- The below code snippet is automatically added from ../apiExamples/east-plus-minus.html -->
|
|
346
369
|
|
|
347
|
-
|
|
348
|
-
|
|
349
|
-
<auro-datetime type="date" value="2022-07-14T06:00:00-04:00"></auro-datetime>
|
|
350
|
-
```
|
|
370
|
+
<pre class="language-html"><code class="language-html"><auro-datetime type="time" value="2022-07-14T06:00:00-04:00"></auro-datetime><br>
|
|
371
|
+
<auro-datetime type="date" value="2022-07-14T06:00:00-04:00"></auro-datetime></code></pre>
|
|
351
372
|
<!-- AURO-GENERATED-CONTENT:END -->
|
|
352
373
|
</auro-accordion>
|
|
353
374
|
|
|
354
|
-
|
|
375
|
+
#### Hawaii time
|
|
355
376
|
|
|
356
|
-
|
|
377
|
+
This example uses `2022-07-16T08:00:00-10:00`, a Hawaii time.
|
|
357
378
|
|
|
358
379
|
<div class="exampleWrapper">
|
|
359
|
-
|
|
360
|
-
|
|
361
|
-
|
|
362
|
-
|
|
363
|
-
|
|
380
|
+
<!-- AURO-GENERATED-CONTENT:START (FILE:src=../apiExamples/hawaii-plus-minus.html) -->
|
|
381
|
+
<!-- The below content is automatically added from ../apiExamples/hawaii-plus-minus.html -->
|
|
382
|
+
<auro-datetime type="time" value="2022-07-16T08:00:00-10:00"></auro-datetime><br>
|
|
383
|
+
<auro-datetime type="date" value="2022-07-16T08:00:00-10:00"></auro-datetime>
|
|
384
|
+
<!-- AURO-GENERATED-CONTENT:END -->
|
|
364
385
|
</div>
|
|
365
386
|
<auro-accordion alignRight>
|
|
366
|
-
|
|
387
|
+
<span slot="trigger">See code</span>
|
|
367
388
|
<!-- AURO-GENERATED-CONTENT:START (CODE:src=../apiExamples/hawaii-plus-minus.html) -->
|
|
368
389
|
<!-- The below code snippet is automatically added from ../apiExamples/hawaii-plus-minus.html -->
|
|
369
390
|
|
|
370
|
-
|
|
371
|
-
|
|
372
|
-
<auro-datetime type="date" value="2022-07-16T08:00:00-10:00"></auro-datetime>
|
|
373
|
-
```
|
|
391
|
+
<pre class="language-html"><code class="language-html"><auro-datetime type="time" value="2022-07-16T08:00:00-10:00"></auro-datetime><br>
|
|
392
|
+
<auro-datetime type="date" value="2022-07-16T08:00:00-10:00"></auro-datetime></code></pre>
|
|
374
393
|
<!-- AURO-GENERATED-CONTENT:END -->
|
|
375
394
|
</auro-accordion>
|