@aurodesignsystem-dev/auro-datetime 0.0.0-pr83.0 → 0.0.0-pr89.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.
Files changed (8) hide show
  1. package/demo/api.md +128 -55
  2. package/demo/auro-datetime.min.js +325 -122
  3. package/dist/auro-datetime-39FU0ZIU.js +6 -0
  4. package/dist/index.d.ts +145 -69
  5. package/dist/index.js +1 -1
  6. package/dist/registered.js +1 -1
  7. package/package.json +4 -4
  8. package/dist/auro-datetime-jIlTbbhr.js +0 -6
package/demo/api.md CHANGED
@@ -7,15 +7,14 @@ The `auro-datetime` element is for the purposes of providing an easy to use date
7
7
 
8
8
  ### Properties & Attributes
9
9
 
10
- | Properties | Attributes | Modifiers | Type | Default | Description |
11
- | ---------- | ---------- | --------- | ------------------------------------------------------------------------------------------------ | ------- | ------------------------------------------------------------------------------------------------- |
12
- | cap | cap | | boolean | | Capitalize AM or PM designation |
13
- | month | month | | `short` \| `long` | `short` | Defines format of month |
14
- | setDate | setDate | | string | | Pass in string to set date |
15
- | timeZone | timeZone | | string | | Pass in string to define [timeZone](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones) |
16
- | type | type | | `date` \| `time` \| `year` \| `month` \| `weekday` \| `day` \| `numeric` \| `tzDate` \| `tzTime` | | Defines type of data to render |
17
- | utc | utc | | string | | Pass in ISO 8601 UTC formatted time code |
18
- | weekday | weekday | | `short` \| `long` | `short` | Defines format of weekday |
10
+ | Properties | Attributes | Modifiers | Type | Default | Description |
11
+ | ---------- | ---------- | --------- | ------------------------------------------------------------------------ | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
12
+ | locale | locale | | string | `en-US` | BCP 47 language tag for locale-aware date/time formatting (e.g. 'en-GB', 'de-DE', 'ja-JP'). |
13
+ | month | month | | `short` \| `long` | `short` | Defines format of month |
14
+ | timezone | timezone | | string | | Pass in string to define [timezone](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones).<br>When set, the moment described by `value` is converted into this IANA zone for display.<br>When unset, the wall-clock time from the input string is rendered as-is. |
15
+ | type | type | | `date` \| `time` \| `year` \| `month` \| `weekday` \| `day` \| `numeric` | | Defines type of data to render |
16
+ | value | value | | string | | ISO 8601 date or date-time string. Examples:<br>- `2022-07-14T08:00:00-07:00` (with offset)<br>- `2022-07-14T08:00:00Z` (UTC)<br>- `2022-07-14T08:00:00` (no offset)<br>- `2022-07-14` (date only)<br><br>When omitted, the component renders today's date.<br>Invalid input is logged as a warning and renders nothing. |
17
+ | weekday | weekday | | `short` \| `long` | `short` | Defines format of weekday |
19
18
 
20
19
  ### Methods
21
20
 
@@ -71,23 +70,81 @@ The `auro-datetime` element is for the purposes of providing an easy to use date
71
70
 
72
71
  ## Property & Attribute Examples
73
72
 
74
- ### Time with Capitalization
73
+ ### International Date Formatting
75
74
 
76
- Using the `cap` attribute will return the basic time string with a capitalized `AM` or `PM`.
75
+ Use the `locale` attribute with a [BCP 47 language tag](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl#locales_argument) to render dates and times in a specific locale (e.g. `en-GB`, `de-DE`, `ja-JP`). When omitted, the component defaults to `en-US` formatting. The `locale` attribute controls **output formatting only** (month names, separators, 12/24-hour clock); it does not perform timezone conversion. Invalid tags are logged as a warning and fall back to `en-US`.
76
+
77
+ #### Locale with type="date"
78
+
79
+ <div class="exampleWrapper">
80
+ <!-- AURO-GENERATED-CONTENT:START (FILE:src=../apiExamples/locale-date.html) -->
81
+ <!-- The below content is automatically added from ../apiExamples/locale-date.html -->
82
+ <auro-datetime type="date" locale="en-GB" value="2020-09-22T01:38:22Z"></auro-datetime><br>
83
+ <auro-datetime type="date" locale="de-DE" value="2020-09-22T01:38:22Z"></auro-datetime><br>
84
+ <auro-datetime type="date" locale="ja-JP" value="2020-09-22T01:38:22Z"></auro-datetime>
85
+ <!-- AURO-GENERATED-CONTENT:END -->
86
+ </div>
87
+ <auro-accordion alignRight>
88
+ <span slot="trigger">See code</span>
89
+ <!-- AURO-GENERATED-CONTENT:START (CODE:src=../apiExamples/locale-date.html) -->
90
+ <!-- The below code snippet is automatically added from ../apiExamples/locale-date.html -->
91
+
92
+ ```html
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
+ ```
97
+ <!-- AURO-GENERATED-CONTENT:END -->
98
+ </auro-accordion>
99
+
100
+ #### Locale with type="numeric"
101
+
102
+ <div class="exampleWrapper">
103
+ <!-- AURO-GENERATED-CONTENT:START (FILE:src=../apiExamples/locale-numeric.html) -->
104
+ <!-- The below content is automatically added from ../apiExamples/locale-numeric.html -->
105
+ <auro-datetime type="numeric" locale="en-GB" value="2020-09-22T01:38:22Z"></auro-datetime><br>
106
+ <auro-datetime type="numeric" locale="de-DE" value="2020-09-22T01:38:22Z"></auro-datetime><br>
107
+ <auro-datetime type="numeric" locale="ja-JP" value="2020-09-22T01:38:22Z"></auro-datetime>
108
+ <!-- AURO-GENERATED-CONTENT:END -->
109
+ </div>
110
+ <auro-accordion alignRight>
111
+ <span slot="trigger">See code</span>
112
+ <!-- AURO-GENERATED-CONTENT:START (CODE:src=../apiExamples/locale-numeric.html) -->
113
+ <!-- The below code snippet is automatically added from ../apiExamples/locale-numeric.html -->
114
+
115
+ ```html
116
+ <auro-datetime type="numeric" locale="en-GB" value="2020-09-22T01:38:22Z"></auro-datetime><br>
117
+ <auro-datetime type="numeric" locale="de-DE" value="2020-09-22T01:38:22Z"></auro-datetime><br>
118
+ <auro-datetime type="numeric" locale="ja-JP" value="2020-09-22T01:38:22Z"></auro-datetime>
119
+ ```
120
+ <!-- AURO-GENERATED-CONTENT:END -->
121
+ </auro-accordion>
122
+
123
+ #### Locale with type="time"
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` → `م`).
126
+
127
+ Note: the choice of 12-hour vs 24-hour is decided by the runtime's `Intl.DateTimeFormat` per locale, not by this component. Several locales (`zh-CN`, `ja-JP`, `de-DE`, `fr-FR`, `en-GB`) default to a 24-hour clock for the short-time skeleton even though the language has 12-hour period words available — the component honors whatever the platform produces.
77
128
 
78
129
  <div class="exampleWrapper">
79
- <!-- AURO-GENERATED-CONTENT:START (FILE:src=../apiExamples/cap.html) -->
80
- <!-- The below content is automatically added from ../apiExamples/cap.html -->
81
- <auro-datetime type="time" cap></auro-datetime>
130
+ <!-- AURO-GENERATED-CONTENT:START (FILE:src=../apiExamples/locale-time.html) -->
131
+ <!-- The below content is automatically added from ../apiExamples/locale-time.html -->
132
+ <auro-datetime type="time" locale="en-US" value="2020-09-22T14:05:00"></auro-datetime><br>
133
+ <auro-datetime type="time" locale="de-DE" value="2020-09-22T14:05:00"></auro-datetime><br>
134
+ <auro-datetime type="time" locale="ko-KR" value="2020-09-22T14:05:00"></auro-datetime><br>
135
+ <auro-datetime type="time" locale="ar-EG" value="2020-09-22T14:05:00"></auro-datetime>
82
136
  <!-- AURO-GENERATED-CONTENT:END -->
83
137
  </div>
84
138
  <auro-accordion alignRight>
85
139
  <span slot="trigger">See code</span>
86
- <!-- AURO-GENERATED-CONTENT:START (CODE:src=../apiExamples/cap.html) -->
87
- <!-- The below code snippet is automatically added from ../apiExamples/cap.html -->
140
+ <!-- AURO-GENERATED-CONTENT:START (CODE:src=../apiExamples/locale-time.html) -->
141
+ <!-- The below code snippet is automatically added from ../apiExamples/locale-time.html -->
88
142
 
89
143
  ```html
90
- <auro-datetime type="time" cap></auro-datetime>
144
+ <auro-datetime type="time" locale="en-US" value="2020-09-22T14:05:00"></auro-datetime><br>
145
+ <auro-datetime type="time" locale="de-DE" value="2020-09-22T14:05:00"></auro-datetime><br>
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>
91
148
  ```
92
149
  <!-- AURO-GENERATED-CONTENT:END -->
93
150
  </auro-accordion>
@@ -113,16 +170,23 @@ Use the `month="long"` attribute to display the full month name, and `weekday="l
113
170
  <!-- AURO-GENERATED-CONTENT:END -->
114
171
  </auro-accordion>
115
172
 
116
- ### Set date/time with string
173
+ ### Set date/time with `value`
117
174
 
118
- Use the `setDate` property to inject a specific date into the element and parse as needed.
175
+ 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:
176
+
177
+ - `2022-07-14T08:00:00-07:00` (date-time with offset)
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.
119
183
 
120
184
  <div class="exampleWrapper">
121
185
  <!-- AURO-GENERATED-CONTENT:START (FILE:src=../apiExamples/set-date.html) -->
122
186
  <!-- The below content is automatically added from ../apiExamples/set-date.html -->
123
- <auro-datetime setDate="August 19, 1975 23:15:30"></auro-datetime><br>
124
- <auro-datetime weekday="long" month="long" setDate="August 19, 1975 23:15:30"></auro-datetime><br>
125
- <auro-datetime type="time" setDate="August 19, 1975 23:15:30"></auro-datetime>
187
+ <auro-datetime value="1975-08-19T23:15:30"></auro-datetime><br>
188
+ <auro-datetime weekday="long" month="long" value="1975-08-19T23:15:30"></auro-datetime><br>
189
+ <auro-datetime type="time" value="1975-08-19T23:15:30"></auro-datetime>
126
190
  <!-- AURO-GENERATED-CONTENT:END -->
127
191
  </div>
128
192
  <auro-accordion alignRight>
@@ -131,16 +195,16 @@ Use the `setDate` property to inject a specific date into the element and parse
131
195
  <!-- The below code snippet is automatically added from ../apiExamples/set-date.html -->
132
196
 
133
197
  ```html
134
- <auro-datetime setDate="August 19, 1975 23:15:30"></auro-datetime><br>
135
- <auro-datetime weekday="long" month="long" setDate="August 19, 1975 23:15:30"></auro-datetime><br>
136
- <auro-datetime type="time" setDate="August 19, 1975 23:15:30"></auro-datetime>
198
+ <auro-datetime value="1975-08-19T23:15:30"></auro-datetime><br>
199
+ <auro-datetime weekday="long" month="long" value="1975-08-19T23:15:30"></auro-datetime><br>
200
+ <auro-datetime type="time" value="1975-08-19T23:15:30"></auro-datetime>
137
201
  ```
138
202
  <!-- AURO-GENERATED-CONTENT:END -->
139
203
  </auro-accordion>
140
204
 
141
205
  ### Type
142
206
 
143
- Use `type` to define the type of data to render. Options are `[date, time, year, month, weekday, day, numeric, tzDate, tzTime]`.
207
+ Use `type` to define the type of data to render. Options are `[date, time, year, month, weekday, day, numeric]`.
144
208
 
145
209
  #### Numeric Date
146
210
 
@@ -163,19 +227,17 @@ Using the `auro-datetime` element with `type=numeric` will return the **current
163
227
  <!-- AURO-GENERATED-CONTENT:END -->
164
228
  </auro-accordion>
165
229
 
166
- #### Set date with code +/- time zone
230
+ #### Wall-clock display from offset
167
231
 
168
- <auro-alert type="information">The <code>auro-datetime</code> element <strong>does not</strong> support local/time zone conversion. The scope of this element is to use current or specifically assigned date/time data and return a string for display.</auro-alert>
169
- <br />
170
- Use `type="tzTime"`or `type="tzDate"` with the `setDate` property to define a new date object in a specific time zone using the `YYYY-MM-DDTHH:MM:SS-HH:MM` model.
232
+ When the `value` attribute contains a timezone offset (or `Z`) and no `timezone` attribute is set, the component renders the **wall-clock** components from the input verbatim. This is the right behavior for displaying local airport time on a flight schedule, where the offset describes the location of the flight rather than the viewer.
171
233
 
172
- Example using `2022-07-13T21:35:00-07:00` with Pacific `(-07:00)` time zone during daylight saving time. (The offset is `(-06:00)` during standard time.)
234
+ Example using `2022-07-13T21:35:00-07:00`. The same string is rendered identically regardless of the viewer's location.
173
235
 
174
236
  <div class="exampleWrapper">
175
237
  <!-- AURO-GENERATED-CONTENT:START (FILE:src=../apiExamples/plus-minus.html) -->
176
238
  <!-- The below content is automatically added from ../apiExamples/plus-minus.html -->
177
- <auro-datetime type="tzTime" setDate="2022-07-13T21:35:00-07:00"></auro-datetime><br>
178
- <auro-datetime type="tzDate" setDate="2022-07-13T21:35:00-07:00"></auro-datetime>
239
+ <auro-datetime type="time" value="2022-07-13T21:35:00-07:00"></auro-datetime><br>
240
+ <auro-datetime type="date" value="2022-07-13T21:35:00-07:00"></auro-datetime>
179
241
  <!-- AURO-GENERATED-CONTENT:END -->
180
242
  </div>
181
243
  <auro-accordion alignRight>
@@ -184,25 +246,22 @@ Example using `2022-07-13T21:35:00-07:00` with Pacific `(-07:00)` time zone duri
184
246
  <!-- The below code snippet is automatically added from ../apiExamples/plus-minus.html -->
185
247
 
186
248
  ```html
187
- <auro-datetime type="tzTime" setDate="2022-07-13T21:35:00-07:00"></auro-datetime><br>
188
- <auro-datetime type="tzDate" setDate="2022-07-13T21:35:00-07:00"></auro-datetime>
249
+ <auro-datetime type="time" value="2022-07-13T21:35:00-07:00"></auro-datetime><br>
250
+ <auro-datetime type="date" value="2022-07-13T21:35:00-07:00"></auro-datetime>
189
251
  ```
190
252
  <!-- AURO-GENERATED-CONTENT:END -->
191
253
  </auro-accordion>
192
254
 
193
- ### Set date with UTC (Zulu) time code
255
+ ### UTC (Zulu) input
194
256
 
195
- <auro-alert type="information">Times are expressed in ISO 8601 date and time format in UTC (Coordinated Universal Time), with a special UTC designator ("Z").<br>
196
- `YYYY-MM-DDTHH:MM:SSZ`</auro-alert>
197
- <br />
198
- Using the `utc` property, be sure to only use a properly-formatted UTC code.
257
+ 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).
199
258
 
200
259
  <div class="exampleWrapper">
201
260
  <!-- AURO-GENERATED-CONTENT:START (FILE:src=../apiExamples/utc.html) -->
202
261
  <!-- The below content is automatically added from ../apiExamples/utc.html -->
203
- <auro-datetime utc="2020-09-22T01:38:22Z"></auro-datetime><br>
204
- <auro-datetime type="time" utc="2020-09-22T01:38:22Z"></auro-datetime><br>
205
- <auro-datetime weekday="long" month="long" utc="2020-09-22T01:38:22Z"></auro-datetime>
262
+ <auro-datetime value="2020-09-22T01:38:22Z"></auro-datetime><br>
263
+ <auro-datetime type="time" value="2020-09-22T01:38:22Z"></auro-datetime><br>
264
+ <auro-datetime weekday="long" month="long" value="2020-09-22T01:38:22Z"></auro-datetime>
206
265
  <!-- AURO-GENERATED-CONTENT:END -->
207
266
  </div>
208
267
  <auro-accordion alignRight>
@@ -211,13 +270,27 @@ Using the `utc` property, be sure to only use a properly-formatted UTC code.
211
270
  <!-- The below code snippet is automatically added from ../apiExamples/utc.html -->
212
271
 
213
272
  ```html
214
- <auro-datetime utc="2020-09-22T01:38:22Z"></auro-datetime><br>
215
- <auro-datetime type="time" utc="2020-09-22T01:38:22Z"></auro-datetime><br>
216
- <auro-datetime weekday="long" month="long" utc="2020-09-22T01:38:22Z"></auro-datetime>
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>
217
276
  ```
218
277
  <!-- AURO-GENERATED-CONTENT:END -->
219
278
  </auro-accordion>
220
279
 
280
+ ### Combining `value` and `timezone`
281
+
282
+ How the `timezone` attribute composes with the input depends on whether `value` carries an offset:
283
+
284
+ - **`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).
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
288
+
289
+ 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):
290
+
291
+ - **Invalid `locale`** (e.g. `"xx-INVALID-tag"`) → falls back to `"en-US"`.
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.
293
+
221
294
  ## Slot Examples
222
295
 
223
296
  ### Pre and Post Slots
@@ -262,8 +335,8 @@ Example using `2022-07-14T06:00:00-04:00` with Eastern `(-04:00)` time zone.
262
335
  <div class="exampleWrapper">
263
336
  <!-- AURO-GENERATED-CONTENT:START (FILE:src=../apiExamples/east-plus-minus.html) -->
264
337
  <!-- The below content is automatically added from ../apiExamples/east-plus-minus.html -->
265
- <auro-datetime type="tzTime" setDate="2022-07-14T06:00:00-04:00"></auro-datetime><br>
266
- <auro-datetime type="tzDate" setDate="2022-07-14T06:00:00-04:00"></auro-datetime>
338
+ <auro-datetime type="time" value="2022-07-14T06:00:00-04:00"></auro-datetime><br>
339
+ <auro-datetime type="date" value="2022-07-14T06:00:00-04:00"></auro-datetime>
267
340
  <!-- AURO-GENERATED-CONTENT:END -->
268
341
  </div>
269
342
  <auro-accordion alignRight>
@@ -272,8 +345,8 @@ Example using `2022-07-14T06:00:00-04:00` with Eastern `(-04:00)` time zone.
272
345
  <!-- The below code snippet is automatically added from ../apiExamples/east-plus-minus.html -->
273
346
 
274
347
  ```html
275
- <auro-datetime type="tzTime" setDate="2022-07-14T06:00:00-04:00"></auro-datetime><br>
276
- <auro-datetime type="tzDate" setDate="2022-07-14T06:00:00-04:00"></auro-datetime>
348
+ <auro-datetime type="time" value="2022-07-14T06:00:00-04:00"></auro-datetime><br>
349
+ <auro-datetime type="date" value="2022-07-14T06:00:00-04:00"></auro-datetime>
277
350
  ```
278
351
  <!-- AURO-GENERATED-CONTENT:END -->
279
352
  </auro-accordion>
@@ -285,8 +358,8 @@ Example using `2022-07-14T08:00:00-10:00` with Hawaii `(-10:00)` time zone.
285
358
  <div class="exampleWrapper">
286
359
  <!-- AURO-GENERATED-CONTENT:START (FILE:src=../apiExamples/hawaii-plus-minus.html) -->
287
360
  <!-- The below content is automatically added from ../apiExamples/hawaii-plus-minus.html -->
288
- <auro-datetime type="tzTime" setDate="2022-07-16T08:00:00-10:00"></auro-datetime><br>
289
- <auro-datetime type="tzDate" setDate="2022-07-16T08:00:00-10:00"></auro-datetime>
361
+ <auro-datetime type="time" value="2022-07-16T08:00:00-10:00"></auro-datetime><br>
362
+ <auro-datetime type="date" value="2022-07-16T08:00:00-10:00"></auro-datetime>
290
363
  <!-- AURO-GENERATED-CONTENT:END -->
291
364
  </div>
292
365
  <auro-accordion alignRight>
@@ -295,8 +368,8 @@ Example using `2022-07-14T08:00:00-10:00` with Hawaii `(-10:00)` time zone.
295
368
  <!-- The below code snippet is automatically added from ../apiExamples/hawaii-plus-minus.html -->
296
369
 
297
370
  ```html
298
- <auro-datetime type="tzTime" setDate="2022-07-16T08:00:00-10:00"></auro-datetime><br>
299
- <auro-datetime type="tzDate" setDate="2022-07-16T08:00:00-10:00"></auro-datetime>
371
+ <auro-datetime type="time" value="2022-07-16T08:00:00-10:00"></auro-datetime><br>
372
+ <auro-datetime type="date" value="2022-07-16T08:00:00-10:00"></auro-datetime>
300
373
  ```
301
374
  <!-- AURO-GENERATED-CONTENT:END -->
302
- </auro-accordion>
375
+ </auro-accordion>