@aurodesignsystem-dev/auro-datetime 0.0.0-pr82.5 → 0.0.0-pr82.7

package/demo/api.md

@@ -284,6 +284,13 @@ How the `timeZone` attribute composes with the input depends on whether `value`
 - **`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).
 - **`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).
 
+#### Invalid `timeZone` and `locale` values
+
+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):
+
+- **Invalid `locale`** (e.g. `"xx-INVALID-tag"`) → falls back to `"en-US"`.
+- **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.
+
 ## Slot Examples
 
 ### Pre and Post Slots

package/demo/auro-datetime.min.js

@@ -143,6 +143,13 @@ class AuroDatetime extends i {
      */
     this._warnedLocales = new Set();
 
+    /**
+     * Tracks invalid timeZone inputs already warned about. Same dedup
+     * pattern as `_warnedLocales`.
+     * @private
+     */
+    this._warnedTimeZones = new Set();
+
     /**
      * @private
      */
@@ -180,6 +187,46 @@ class AuroDatetime extends i {
     }
   }
 
+  /**
+   * Validate an IANA timezone identifier. Invalid input warns once per
+   * unique value per element and resolves to `undefined`, which makes
+   * the rest of `_resolveInputDate` behave as if `timeZone` was never
+   * specified — i.e. wall-clock display from the input components.
+   *
+   * Without this guard, a typo like `"US/Pacfic"` would cause
+   * `Intl.DateTimeFormat` / `toLocaleString` to throw `RangeError` at
+   * render time and crash the component.
+   *
+   * Note: when `value` is also unset, the wall-clock branch resolves to
+   * "today's date in the viewer's machine zone," which is viewer-
+   * dependent. This narrow case is the only scenario where two viewers
+   * see different output for the same component; the warning surfaces
+   * the typo so the developer can fix it.
+   *
+   * @private
+   * @param {string | undefined} input - Consumer-supplied timezone.
+   * @returns {string | undefined} Valid timezone, or undefined on fallback.
+   */
+  _resolveTimeZone(input) {
+    if (!input) {
+      return undefined;
+    }
+    try {
+      // Constructing the formatter is enough to surface a RangeError;
+      // we don't need to format anything yet.
+      new Intl.DateTimeFormat(undefined, { timeZone: input });
+      return input;
+    } catch {
+      if (this._warnedTimeZones && !this._warnedTimeZones.has(input)) {
+        this._warnedTimeZones.add(input);
+        console.warn(
+          `auro-datetime: "${input}" is not a valid IANA timezone. Falling back to viewer-local.`,
+        );
+      }
+      return undefined;
+    }
+  }
+
   connectedCallback() {
     super.connectedCallback();
 
@@ -314,8 +361,13 @@ class AuroDatetime extends i {
    * timeZone option for `Intl.DateTimeFormat`.
    *
    * Behavior:
-   * - No `value`: returns today's date. `timeZone` (if any) is honored.
-   * - `value` invalid: warns and returns `{ date: null }`.
+   * - `value` omitted (null/undefined): returns today's date. `timeZone`
+   *   (if any) is honored.
+   * - `value` invalid (including empty string ""): warns and returns
+   *   `{ date: null }`. Empty is *not* the same as omitted — Lit reflects
+   *   `value=""` as the empty string, which is not a valid ISO 8601
+   *   form, so we surface it as a typo rather than silently rendering
+   *   today's date.
    * - `timeZone` set + input has offset/Z: parses as an absolute moment
    *   (offset honored) and asks `toLocaleString` to convert into the target zone.
    * - `timeZone` set + input has no offset: interprets the wall-clock as
@@ -328,8 +380,13 @@ class AuroDatetime extends i {
    * @returns {{ date: Date | null, timeZoneOption: string | undefined }}
    */
   _resolveInputDate() {
-    if (!this.value) {
-      return { date: new Date(), timeZoneOption: this.timeZone || undefined };
+    const resolvedTz = this._resolveTimeZone(this.timeZone);
+
+    // Only true "omitted" inputs (null/undefined) get the today's-date
+    // treatment. Empty string falls through to ISO validation, which will
+    // fail and produce the documented warn + empty render.
+    if (this.value == null) {
+      return { date: new Date(), timeZoneOption: resolvedTz };
     }
 
     const match = this.value.match(ISO_8601_REGEX);
@@ -342,27 +399,50 @@ class AuroDatetime extends i {
 
     const localPart = match[1];
     const hasOffset = Boolean(match[2]);
+
+    // The regex permits an offset/Z suffix on a bare date (e.g. "2020-09-22Z"
+    // or "2020-09-22-07:00"). Those forms are not valid ISO 8601 — an offset
+    // is only meaningful with a time component — and the wall-clock branch
+    // would silently drop the offset, producing surprising output. Reject
+    // them up front so the consumer sees a warning.
+    if (hasOffset && !localPart.includes("T")) {
+      console.warn(
+        `auro-datetime: "${this.value}" is not a valid ISO 8601 string (offset/Z requires a time component).`,
+      );
+      return { date: null, timeZoneOption: undefined };
+    }
+
     const normalized = localPart.includes("T")
       ? localPart
       : `${localPart}T00:00:00`;
 
-    if (this.timeZone) {
-      if (hasOffset) {
-        return { date: new Date(this.value), timeZoneOption: this.timeZone };
+    // The regex only validates string shape, not value ranges — "2022-99-99"
+    // matches but produces an Invalid Date. Detect that and treat it like
+    // any other malformed input so render falls back to the documented
+    // empty output instead of "Invalid Date" or a thrown RangeError from
+    // downstream Intl calls.
+    const buildDate = () => {
+      if (resolvedTz && !hasOffset) {
+        return this._zonedWallClockToUtc(normalized, resolvedTz);
       }
-      // No offset: the wall-clock is ambiguous without a zone. Treat it as
-      // being in `timeZone` so the rendered output matches the input
-      // regardless of where the viewer is.
-      return {
-        date: this._zonedWallClockToUtc(normalized, this.timeZone),
-        timeZoneOption: this.timeZone,
-      };
+      if (resolvedTz && hasOffset) {
+        return new Date(this.value);
+      }
+      // Wall-clock: keep the components in the input verbatim. JS parses
+      // bare "YYYY-MM-DD" as UTC midnight, which shifts the date in the
+      // viewer's timezone; appending a time forces local-time parsing.
+      return new Date(normalized);
+    };
+
+    const date = buildDate();
+    if (Number.isNaN(date.getTime())) {
+      console.warn(
+        `auro-datetime: "${this.value}" is not a valid ISO 8601 date.`,
+      );
+      return { date: null, timeZoneOption: undefined };
     }
 
-    // Wall-clock: keep the components in the input verbatim. JS parses
-    // bare "YYYY-MM-DD" as UTC midnight, which shifts the date in the
-    // viewer's timezone; appending a time forces local-time parsing.
-    return { date: new Date(normalized), timeZoneOption: undefined };
+    return { date, timeZoneOption: resolvedTz };
   }
 
   /**

package/dist/auro-datetime-Cq0WDk5L.js

@@ -0,0 +1,6 @@
+import{LitElement as e,html as t}from"lit";class n{registerComponent(e,t){customElements.get(e)||customElements.define(e,class extends t{})}closestElement(e,t=this,n=(t,i=t&&t.closest(e))=>t&&t!==document&&t!==window?i||n(t.getRootNode().host):null){return n(t)}handleComponentTagRename(e,t){const n=t.toLowerCase();e.tagName.toLowerCase()!==n&&e.setAttribute(n,!0)}elementMatch(e,t){const n=t.toLowerCase();return e.tagName.toLowerCase()===n||e.hasAttribute(n)}getSlotText(e,t){const n=e.shadowRoot?.querySelector(`slot[name="${t}"]`);return(n?.assignedNodes({flatten:!0})||[]).map(e=>e.textContent?.trim()).join(" ").trim()||null}}const i=/^(\d{4}-\d{2}-\d{2}(?:T\d{2}:\d{2}(?::\d{2}(?:\.\d+)?)?)?)(Z|[+-]\d{2}:\d{2})?$/u;class a extends e{constructor(){super(),this._initializeDefaults()}_initializeDefaults(){this.weekday="short",this.month="short",this.locale="en-US",this._warnedLocales=new Set,this._warnedTimeZones=new Set,this._effectiveLocale=this._resolveLocale(this.locale),this.runtimeUtils=new n}_resolveLocale(e){if(!e)return"en-US";try{return Intl.getCanonicalLocales(e)[0]}catch{return this._warnedLocales&&!this._warnedLocales.has(e)&&(this._warnedLocales.add(e),console.warn(`auro-datetime: "${e}" is not a valid BCP 47 locale tag. Falling back to "en-US".`)),"en-US"}}_resolveTimeZone(e){if(e)try{return new Intl.DateTimeFormat(void 0,{timeZone:e}),e}catch{return void(this._warnedTimeZones&&!this._warnedTimeZones.has(e)&&(this._warnedTimeZones.add(e),console.warn(`auro-datetime: "${e}" is not a valid IANA timezone. Falling back to viewer-local.`)))}}connectedCallback(){super.connectedCallback(),this.dateTemplate={weekday:this.weekday,year:"numeric",month:this.month,day:"numeric"},this.timeTemplate={hour:"2-digit",minute:"2-digit"}}static get properties(){return{locale:{type:String},month:{type:String},timeZone:{type:String},type:{type:String},value:{type:String},weekday:{type:String}}}static register(e="auro-datetime"){n.prototype.registerComponent(e,a)}willUpdate(e){e.has("locale")&&(this._effectiveLocale=this._resolveLocale(this.locale))}firstUpdated(){this.runtimeUtils.handleComponentTagRename(this,"auro-datetime")}_zonedWallClockToUtc(e,t){const n=new Date(`${e}Z`),i=new Intl.DateTimeFormat("en-US",{timeZone:t,hourCycle:"h23",year:"numeric",month:"2-digit",day:"2-digit",hour:"2-digit",minute:"2-digit",second:"2-digit"}).formatToParts(n),a=Object.fromEntries(i.filter(e=>"literal"!==e.type).map(e=>[e.type,e.value])),o=new Date(`${a.year}-${a.month}-${a.day}T${a.hour}:${a.minute}:${a.second}Z`),s=n.getTime()-o.getTime();return new Date(n.getTime()+s)}_resolveInputDate(){const e=this._resolveTimeZone(this.timeZone);if(null==this.value)return{date:new Date,timeZoneOption:e};const t=this.value.match(i);if(!t)return console.warn(`auro-datetime: "${this.value}" is not a valid ISO 8601 string.`),{date:null,timeZoneOption:void 0};const n=t[1],a=Boolean(t[2]);if(a&&!n.includes("T"))return console.warn(`auro-datetime: "${this.value}" is not a valid ISO 8601 string (offset/Z requires a time component).`),{date:null,timeZoneOption:void 0};const o=n.includes("T")?n:`${n}T00:00:00`,s=(()=>e&&!a?this._zonedWallClockToUtc(o,e):e&&a?new Date(this.value):new Date(o))();return Number.isNaN(s.getTime())?(console.warn(`auro-datetime: "${this.value}" is not a valid ISO 8601 date.`),{date:null,timeZoneOption:void 0}):{date:s,timeZoneOption:e}}humanDate(){const{date:e,timeZoneOption:t}=this._resolveInputDate();if(!e)return"";const n={...this.dateTemplate};return t&&(n.timeZone=t),e.toLocaleString(this._effectiveLocale,n)}humanDateConversion(){const{date:e,timeZoneOption:t}=this._resolveInputDate();if(!e)return"";const n={};switch(t&&(n.timeZone=t),this.type){case"day":n.day="numeric";break;case"month":n.month=this.month;break;case"year":n.year="numeric";break;case"weekday":n.weekday=this.weekday}return e.toLocaleString(this._effectiveLocale,n)}numericDate(){const{date:e,timeZoneOption:t}=this._resolveInputDate();if(!e)return"";const n={...this.dateTemplate,month:"numeric"};return Reflect.deleteProperty(n,"weekday"),t&&(n.timeZone=t),e.toLocaleString(this._effectiveLocale,n)}humanTime(){const{date:e,timeZoneOption:t}=this._resolveInputDate();if(!e)return"";const n={...this.timeTemplate};t&&(n.timeZone=t);const i=e.toLocaleString(this._effectiveLocale,n);return/[ap]\.?m\.?/iu.test(i)?i.replace(/^0+/u,"").toLowerCase():i}whichDate(){switch(this.type){case"date":default:return this.humanDate();case"time":return this.humanTime();case"year":case"month":case"weekday":case"day":return this.humanDateConversion();case"numeric":return this.numericDate()}}render(){return t`
+      <slot name="pre"></slot>
+      <span class="yield">${this.whichDate()}</span>
+      <slot name="post"></slot>
+      <slot></slot>
+    `}}export{a as A};

package/dist/index.js

@@ -1 +1 @@
-export{A as AuroDatetime}from"./auro-datetime-BmzswYzJ.js";import"lit";
+export{A as AuroDatetime}from"./auro-datetime-Cq0WDk5L.js";import"lit";

package/dist/registered.js

@@ -1 +1 @@
-import{A as r}from"./auro-datetime-BmzswYzJ.js";import"lit";r.register();
+import{A as r}from"./auro-datetime-Cq0WDk5L.js";import"lit";r.register();

package/package.json

@@ -7,7 +7,7 @@
     "================================================================================"
   ],
   "name": "@aurodesignsystem-dev/auro-datetime",
-  "version": "0.0.0-pr82.5",
+  "version": "0.0.0-pr82.7",
   "description": "auro-datetime HTML custom element",
   "repository": {
     "type": "git",

package/dist/auro-datetime-BmzswYzJ.js

@@ -1,6 +0,0 @@
-import{LitElement as e,html as t}from"lit";class n{registerComponent(e,t){customElements.get(e)||customElements.define(e,class extends t{})}closestElement(e,t=this,n=(t,i=t&&t.closest(e))=>t&&t!==document&&t!==window?i||n(t.getRootNode().host):null){return n(t)}handleComponentTagRename(e,t){const n=t.toLowerCase();e.tagName.toLowerCase()!==n&&e.setAttribute(n,!0)}elementMatch(e,t){const n=t.toLowerCase();return e.tagName.toLowerCase()===n||e.hasAttribute(n)}getSlotText(e,t){const n=e.shadowRoot?.querySelector(`slot[name="${t}"]`);return(n?.assignedNodes({flatten:!0})||[]).map(e=>e.textContent?.trim()).join(" ").trim()||null}}const i=/^(\d{4}-\d{2}-\d{2}(?:T\d{2}:\d{2}(?::\d{2}(?:\.\d+)?)?)?)(Z|[+-]\d{2}:\d{2})?$/u;class a extends e{constructor(){super(),this._initializeDefaults()}_initializeDefaults(){this.weekday="short",this.month="short",this.locale="en-US",this._warnedLocales=new Set,this._effectiveLocale=this._resolveLocale(this.locale),this.runtimeUtils=new n}_resolveLocale(e){if(!e)return"en-US";try{return Intl.getCanonicalLocales(e)[0]}catch{return this._warnedLocales&&!this._warnedLocales.has(e)&&(this._warnedLocales.add(e),console.warn(`auro-datetime: "${e}" is not a valid BCP 47 locale tag. Falling back to "en-US".`)),"en-US"}}connectedCallback(){super.connectedCallback(),this.dateTemplate={weekday:this.weekday,year:"numeric",month:this.month,day:"numeric"},this.timeTemplate={hour:"2-digit",minute:"2-digit"}}static get properties(){return{locale:{type:String},month:{type:String},timeZone:{type:String},type:{type:String},value:{type:String},weekday:{type:String}}}static register(e="auro-datetime"){n.prototype.registerComponent(e,a)}willUpdate(e){e.has("locale")&&(this._effectiveLocale=this._resolveLocale(this.locale))}firstUpdated(){this.runtimeUtils.handleComponentTagRename(this,"auro-datetime")}_zonedWallClockToUtc(e,t){const n=new Date(`${e}Z`),i=new Intl.DateTimeFormat("en-US",{timeZone:t,hourCycle:"h23",year:"numeric",month:"2-digit",day:"2-digit",hour:"2-digit",minute:"2-digit",second:"2-digit"}).formatToParts(n),a=Object.fromEntries(i.filter(e=>"literal"!==e.type).map(e=>[e.type,e.value])),o=new Date(`${a.year}-${a.month}-${a.day}T${a.hour}:${a.minute}:${a.second}Z`),s=n.getTime()-o.getTime();return new Date(n.getTime()+s)}_resolveInputDate(){if(!this.value)return{date:new Date,timeZoneOption:this.timeZone||void 0};const e=this.value.match(i);if(!e)return console.warn(`auro-datetime: "${this.value}" is not a valid ISO 8601 string.`),{date:null,timeZoneOption:void 0};const t=e[1],n=Boolean(e[2]),a=t.includes("T")?t:`${t}T00:00:00`;return this.timeZone?n?{date:new Date(this.value),timeZoneOption:this.timeZone}:{date:this._zonedWallClockToUtc(a,this.timeZone),timeZoneOption:this.timeZone}:{date:new Date(a),timeZoneOption:void 0}}humanDate(){const{date:e,timeZoneOption:t}=this._resolveInputDate();if(!e)return"";const n={...this.dateTemplate};return t&&(n.timeZone=t),e.toLocaleString(this._effectiveLocale,n)}humanDateConversion(){const{date:e,timeZoneOption:t}=this._resolveInputDate();if(!e)return"";const n={};switch(t&&(n.timeZone=t),this.type){case"day":n.day="numeric";break;case"month":n.month=this.month;break;case"year":n.year="numeric";break;case"weekday":n.weekday=this.weekday}return e.toLocaleString(this._effectiveLocale,n)}numericDate(){const{date:e,timeZoneOption:t}=this._resolveInputDate();if(!e)return"";const n={...this.dateTemplate,month:"numeric"};return Reflect.deleteProperty(n,"weekday"),t&&(n.timeZone=t),e.toLocaleString(this._effectiveLocale,n)}humanTime(){const{date:e,timeZoneOption:t}=this._resolveInputDate();if(!e)return"";const n={...this.timeTemplate};t&&(n.timeZone=t);const i=e.toLocaleString(this._effectiveLocale,n);return/[ap]\.?m\.?/iu.test(i)?i.replace(/^0+/u,"").toLowerCase():i}whichDate(){switch(this.type){case"date":default:return this.humanDate();case"time":return this.humanTime();case"year":case"month":case"weekday":case"day":return this.humanDateConversion();case"numeric":return this.numericDate()}}render(){return t`
-      <slot name="pre"></slot>
-      <span class="yield">${this.whichDate()}</span>
-      <slot name="post"></slot>
-      <slot></slot>
-    `}}export{a as A};