@aurodesignsystem-dev/auro-datetime 0.0.0-pr110.0 → 0.0.0-pr112.0

package/demo/index.min.js

@@ -114,16 +114,29 @@ const t=globalThis,i$1=t=>t,s$1=t.trustedTypes,e=s$1?s$1.createPolicy("lit-html"
 const ISO_8601_REGEX =
   /^(\d{4}-\d{2}-\d{2}(?:T\d{2}:\d{2}(?::\d{2}(?:\.\d+)?)?)?)(Z|[+-]\d{2}:\d{2})?$/u;
 
-// See https://git.io/JJ6SJ for "How to document your components using JSDoc"
 /**
- * The `auro-datetime` element is for the purposes of providing an easy to use date and time API.
+ * Shows a date or time as text, formatted for a language and region you choose and, optionally, a specific time zone.
+ *
+ * **Key capabilities**
+ * - **What to show**: `type` picks the full date, the time, a numeric date, or a single part, such as the year or weekday.
+ * - **Date and time to show**: `value` takes an ISO 8601 date or date-time; without it, the element shows the current date and time.
+ * - **Language formatting**: `locale` formats month names, separators, and the 12- or 24-hour clock for a language, such as `de-DE`.
+ * - **Time zones**: `timezone` shows the moment in a time zone, such as `America/Los_Angeles`.
+ * - **Name length**: `month="long"` and `weekday="long"` spell out the month and weekday names.
+ *
+ * **Example**
+ * ```html
+ * <auro-datetime type="date" value="2022-07-14T08:00:00"></auro-datetime>
+ * ```
+ *
+ * @summary Date or time text formatted by language and time zone, with full, numeric, and single-part formats.
  * @customElement auro-datetime
  *
- * @slot pre - Content that comes before the `post` content
- * @slot post - Content that comes after the `pre` content
+ * @slot 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. {@category ui}
+ * @slot 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. {@category ui}
+ * @slot - Content shown after the `post` slot's content, such as the end of a sentence that includes the date. {@category ui}
  */
 
-// build the component class
 class AuroDatetime extends i {
   constructor() {
     super();
@@ -131,6 +144,11 @@ class AuroDatetime extends i {
     this._initializeDefaults();
   }
 
+  /**
+   * Sets the element's default values.
+   * @private
+   * @returns {void}
+   */
   _initializeDefaults() {
     this.weekday = "short";
     this.month = "short";
@@ -144,15 +162,15 @@ class AuroDatetime extends i {
     this._warnedLocales = new Set();
 
     /**
-     * Tracks invalid timeZone inputs already warned about. Same dedup
-     * pattern as `_warnedLocales`.
+     * Tracks invalid `timezone` values this element has already warned
+     * about, so the same bad value logs only one warning.
      * @private
      */
     this._warnedTimeZones = new Set();
 
     /**
-     * Tracks invalid value inputs already warned about. Same dedup
-     * pattern as `_warnedLocales`.
+     * Tracks invalid `value` inputs this element has already warned about,
+     * so the same bad value logs only one warning.
      * @private
      */
     this._warnedValues = new Set();
@@ -174,13 +192,13 @@ class AuroDatetime extends i {
   }
 
   /**
-   * Validate and canonicalize a BCP 47 locale tag. Falls back to "en-US"
-   * for empty or invalid input. The first invalid value seen per element
-   * is logged via `console.warn`; subsequent identical inputs are silent.
+   * Checks a BCP 47 locale tag and returns its canonical form. Empty or invalid
+   * input falls back to "en-US". Each invalid value logs a console warning the
+   * first time this element sees it.
    *
    * @private
-   * @param {string} input - User-supplied locale tag.
-   * @returns {string} Canonical locale tag (e.g. "en-GB"), or "en-US" on fallback.
+   * @param {string} input - The locale tag set on the element.
+   * @returns {string} The canonical locale tag, such as "en-GB", or "en-US" for empty or invalid input.
    */
   _resolveLocale(input) {
     if (!input) {
@@ -200,121 +218,92 @@ 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.
+   * Checks an IANA time zone name. An invalid name logs a console warning
+   * the first time this element sees it and returns `undefined`, so the
+   * element acts as if `timezone` isn't set.
    *
    * @private
-   * @param {string | undefined} input - Consumer-supplied timezone.
-   * @returns {string | undefined} Valid timezone, or undefined on fallback.
+   * @param {string | undefined} input - The time zone name set on the element.
+   * @returns {string | undefined} The time zone name if it's valid; otherwise, `undefined`.
    */
   _resolveTimeZone(input) {
     if (!input) {
       return undefined;
     }
     try {
-      // Constructing the formatter is enough to surface a RangeError;
-      // we don't need to format anything yet.
+      // Creating the formatter is enough to catch an invalid name. Without
+      // this check, a typo such as "America/Los_Angles" makes
+      // Intl.DateTimeFormat and toLocaleString throw a RangeError at render
+      // time.
       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.`,
+          `auro-datetime: "${input}" is not a valid IANA timezone. Ignoring it.`,
         );
       }
       return undefined;
     }
   }
 
-  connectedCallback() {
-    super.connectedCallback();
-
-    this.dateTemplate = {
-      weekday: this.weekday,
-      year: "numeric",
-      month: this.month,
-      day: "numeric",
-    };
-
-    this.timeTemplate = {
-      hour: "2-digit",
-      minute: "2-digit",
-    };
-  }
-
-  // function to define props used within the scope of this component
   static get properties() {
     return {
-      // ...super.properties,
-
       /**
-       * BCP 47 language tag for locale-aware date/time formatting (e.g. 'en-GB', 'de-DE', 'ja-JP').
+       * 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.
        * @type {string}
-       * @default 'en-US'
+       * @default "en-US"
+       * @category ui
        */
       locale: { type: String },
 
       /**
-       * Defines format of month
-       * @type {'short' | 'long'}
-       * @default '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"`.
+       * @type {"short" | "long"}
+       * @default "short"
+       * @category ui
        */
       month: { type: String },
 
       /**
-       * Pass in string to define [timezone](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones).
-       * When set, the moment described by `value` is converted into this IANA zone for display.
-       * When unset, the wall-clock time from the input string is rendered as-is.
+       * 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.
+       * @type {string}
+       * @category behavior
        */
       timezone: { type: String },
 
       /**
-       * Defines type of data to render
-       * @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.
+       * @type {"date" | "time" | "year" | "month" | "weekday" | "day" | "numeric"}
+       * @category ui
        */
       type: { type: String },
 
       /**
-       * ISO 8601 date or date-time string. Examples:
-       * - `2022-07-14T08:00:00-07:00` (with offset)
-       * - `2022-07-14T08:00:00Z` (UTC)
-       * - `2022-07-14T08:00:00` (no offset)
-       * - `2022-07-14` (date only)
-       *
-       * When omitted, the component renders today's date.
-       * Invalid input is logged as a warning and renders nothing.
+       * 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.
+       * @type {string}
+       * @category behavior
        */
       value: { type: String },
 
       /**
-       * Defines format of weekday
-       * @type {'short' | 'long'}
-       * @default '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"`.
+       * @type {"short" | "long"}
+       * @default "short"
+       * @category ui
        */
       weekday: { type: String },
     };
   }
 
   /**
-   * This will register this element with the browser.
-   * @param {string} [name="auro-datetime"] - The name of the element that you want to register.
+   * 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.
+   * @param {string} [name="auro-datetime"] - The tag name to register the element under, such as `custom-datetime`.
+   * @returns {void}
    *
    * @example
-   * AuroDatetime.register("custom-datetime") // this will register this element to <custom-datetime/>
-   *
+   * AuroDatetime.register("custom-datetime"); // registers <custom-datetime>
    */
   static register(name = "auro-datetime") {
     AuroLibraryRuntimeUtils.prototype.registerComponent(name, AuroDatetime);
@@ -330,24 +319,24 @@ class AuroDatetime extends i {
   }
 
   firstUpdated() {
-    // Add the tag name as an attribute if it is different than the component name
+    // Adds the tag name as an attribute when it differs from auro-datetime.
     this.runtimeUtils.handleComponentTagRename(this, "auro-datetime");
   }
 
   /**
-   * Construct a UTC Date that, when displayed in the given IANA timezone,
-   * shows the supplied wall-clock components. Used when `value` has no
-   * offset but `timeZone` is set — the wall-clock is interpreted as being
-   * in the target zone rather than the viewer's local zone.
+   * Creates a Date that shows the given wall-clock time when displayed in
+   * the given IANA time zone. `_resolveInputDate` uses it when `value` has
+   * no offset and `timezone` is set, so the time is read as already being
+   * in that zone rather than the viewer's.
    *
-   * Algorithm: parse the wall-clock as if it were UTC (a "naive" Date),
-   * ask Intl what that moment looks like in the target zone, and use the
-   * delta between the two to recover the true UTC moment.
+   * It parses the wall-clock time as if it were UTC, asks `Intl` what that
+   * moment looks like in the target zone, and uses the difference between
+   * the two to find the real moment.
    *
    * @private
-   * @param {string} localISO - ISO string with no offset, e.g. "2022-07-14T08:00:00".
-   * @param {string} timeZone - IANA zone, e.g. "US/Eastern".
-   * @returns {Date}
+   * @param {string} localISO - The ISO 8601 date-time with no offset, such as "2022-07-14T08:00:00".
+   * @param {string} timeZone - The IANA time zone name, such as "America/New_York".
+   * @returns {Date} The moment that reads as `localISO` in `timeZone`.
    */
   _zonedWallClockToUtc(localISO, timeZone) {
     const naiveUtc = new Date(`${localISO}Z`);
@@ -372,34 +361,33 @@ class AuroDatetime extends i {
   }
 
   /**
-   * Resolve the `value` and `timezone` attributes into a Date and an optional
-   * timeZone option for `Intl.DateTimeFormat`.
-   *
-   * Behavior:
-   * - `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
-   *   being in the target zone, so display in that zone matches the input
-   *   verbatim. This is viewer-independent.
-   * - Default (no `timezone`): strips the offset/Z from the input and treats
-   *   the remaining wall-clock components as local time, so they render verbatim.
+   * Gets the Date to show and the `timeZone` option for `Intl.DateTimeFormat`,
+   * from `value` and `timezone`. Returns `{ date: null }` for invalid input,
+   * including an empty string.
    *
    * @private
-   * @returns {{ date: Date | null, timeZoneOption: string | undefined }}
+   * @returns {{ date: Date | null, timeZoneOption: string | undefined }} The Date to show, or `null` for invalid input, and the `timeZone` option to format it with.
    */
   _resolveInputDate() {
+    // How each case resolves:
+    // - `value` not set (null or undefined): the current date and time, in
+    //   `timezone` if it's set.
+    // - `value` invalid, including an empty string: logs a warning and
+    //   returns { date: null }. An empty string isn't the same as not set:
+    //   Lit gives value="" as an empty string, which isn't valid ISO 8601,
+    //   so it's reported as a likely mistake instead of showing the
+    //   current date.
+    // - `timezone` set and `value` has an offset or Z: reads `value` as an
+    //   exact moment and has toLocaleString convert it into `timezone`.
+    // - `timezone` set and `value` has no offset: reads `value` as a time
+    //   already in `timezone`, so every viewer sees it as written.
+    // - `timezone` not set: drops any offset or Z and reads the rest as
+    //   local time, so it shows as written.
     const resolvedTz = this._effectiveTimeZone;
 
-    // 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.
+    // Only true "omitted" inputs (null/undefined) get the current-date
+    // treatment. Empty string falls through to ISO validation, which
+    // fails and produces the documented warning and empty output.
     if (this.value == null) {
       return { date: new Date(), timeZoneOption: resolvedTz };
     }
@@ -418,9 +406,9 @@ 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
+    // The regex permits an offset/Z suffix on a bare date (such as "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")) {
@@ -437,7 +425,7 @@ class AuroDatetime extends i {
       ? localPart
       : `${localPart}T00:00:00`;
 
-    // The regex only validates string shape, not value ranges — "2022-99-99"
+    // 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
@@ -470,16 +458,22 @@ class AuroDatetime extends i {
   }
 
   /**
-   * Internal function to generate full date string.
+   * Formats the full date, such as "Thu, Jul 14, 2022", with the current `month` and `weekday` settings.
    * @private
-   * @returns {string} - Date string.
+   * @returns {string} The formatted date, or an empty string when `value` is invalid.
    */
   humanDate() {
     const { date, timeZoneOption } = this._resolveInputDate();
     if (!date) {
       return "";
     }
-    const template = { ...this.dateTemplate };
+    // Read month and weekday on every render so later changes show up.
+    const template = {
+      weekday: this.weekday || "short",
+      year: "numeric",
+      month: this.month || "short",
+      day: "numeric",
+    };
     if (timeZoneOption) {
       template.timeZone = timeZoneOption;
     }
@@ -487,9 +481,9 @@ class AuroDatetime extends i {
   }
 
   /**
-   * Internal function to format a single date part (year/month/weekday/day).
+   * Formats the single date part that `type` names: the year, month, weekday, or day.
    * @private
-   * @returns {string} - Date string.
+   * @returns {string} The formatted date, or an empty string when `value` is invalid.
    */
   humanDateConversion() {
     const { date, timeZoneOption } = this._resolveInputDate();
@@ -506,13 +500,13 @@ class AuroDatetime extends i {
         template.day = "numeric";
         break;
       case "month":
-        template.month = this.month;
+        template.month = this.month || "short";
         break;
       case "year":
         template.year = "numeric";
         break;
       case "weekday":
-        template.weekday = this.weekday;
+        template.weekday = this.weekday || "short";
         break;
     }
 
@@ -520,17 +514,16 @@ class AuroDatetime extends i {
   }
 
   /**
-   * Internal function to generate numeric date string MM/DD/YYYY.
+   * Formats the date in numbers, in the order and with the separators `locale` uses, such as "7/14/2022" for `en-US`.
    * @private
-   * @returns {string} - Date string.
+   * @returns {string} The formatted date, or an empty string when `value` is invalid.
    */
   numericDate() {
     const { date, timeZoneOption } = this._resolveInputDate();
     if (!date) {
       return "";
     }
-    const template = { ...this.dateTemplate, month: "numeric" };
-    Reflect.deleteProperty(template, "weekday");
+    const template = { year: "numeric", month: "numeric", day: "numeric" };
     if (timeZoneOption) {
       template.timeZone = timeZoneOption;
     }
@@ -538,16 +531,16 @@ class AuroDatetime extends i {
   }
 
   /**
-   * Internal function to generate standard time string.
+   * Formats the hour and minute. When the time ends in AM or PM, it lowercases the period and drops a leading zero.
    * @private
-   * @returns {string} - Time string.
+   * @returns {string} The formatted time, or an empty string when `value` is invalid.
    */
   humanTime() {
     const { date, timeZoneOption } = this._resolveInputDate();
     if (!date) {
       return "";
     }
-    const template = { ...this.timeTemplate };
+    const template = { hour: "2-digit", minute: "2-digit" };
     if (timeZoneOption) {
       template.timeZone = timeZoneOption;
     }
@@ -559,8 +552,8 @@ class AuroDatetime extends i {
     // (case-insensitive), so it catches en-US (`PM`), en-AU/hi-IN (`pm`),
     // and en-CA/es-MX (`p.m.`) alike. Non-Latin period markers (ko `오후`,
     // ar `م`, zh-TW `下午`) have no ASCII a/p+m chars and correctly fall
-    // through unchanged. 24h locales (en-GB, de-DE, fr-FR, ja-JP …) also
-    // fall through, preserving their leading zeros.
+    // through unchanged. 24h locales (en-GB, de-DE, fr-FR, ja-JP, and
+    // others) also fall through, preserving their leading zeros.
     if (!/[ap]\.?m\.?/iu.test(formatted)) {
       return formatted;
     }
@@ -569,9 +562,9 @@ class AuroDatetime extends i {
   }
 
   /**
-   * Internal function UI decision.
+   * Gets the text to show for the current `type`.
    * @private
-   * @returns {string} - String determined by `type` (or full date if no type set).
+   * @returns {string} The formatted text; the full date when `type` isn't set or isn't recognized.
    */
   whichDate() {
     switch (this.type) {
@@ -591,10 +584,6 @@ class AuroDatetime extends i {
     }
   }
 
-  // When using auroElement, use the following attribute and function when hiding content from screen readers.
-  // aria-hidden="${this.hideAudible(this.hiddenAudible)}"
-
-  // function that renders the HTML and CSS into  the scope of the component
   render() {
     return b`
       <slot name="pre"></slot>

package/demo/readme.md

@@ -12,7 +12,7 @@ The following sections are editable by making changes to the following files:
 | SECTION                | DESCRIPTION                                       | FILE LOCATION                       |
 |------------------------|---------------------------------------------------|-------------------------------------|
 | Description            | Description of the component                      | `./docs/partials/description.md`    |
-| Use Cases              | Examples for when to use this component           | `./docs/partials/useCases.md`       |
+| Use cases              | Examples for when to use this component           | `./docs/partials/useCases.md`       |
 | Additional Information | For use to add any component specific information | `./docs/partials/readmeAddlInfo.md` |
 | Component Example Code | HTML sample code of the components use            | `./apiExamples/basic.html`          |
 -->
@@ -21,20 +21,22 @@ The following sections are editable by making changes to the following files:
 
 <!-- AURO-GENERATED-CONTENT:START (FILE:src=./docs/partials/description.md) -->
 <!-- The below content is automatically added from ./docs/partials/description.md -->
-The `<auro-datetime>` custom element makes it really easy to add dates to your web app with a simple HTML API.
+The `<auro-datetime>` element shows a date or time as text, formatted for a language and region you choose and, optionally, a specific time zone. Set `type` to choose the full date, the time, a numeric date, or a single part, such as the weekday.
 <!-- AURO-GENERATED-CONTENT:END -->
 <!-- AURO-GENERATED-CONTENT:START (FILE:src=./docs/partials/readmeAddlInfo.md) -->
 <!-- The below content is automatically added from ./docs/partials/readmeAddlInfo.md -->
 <!-- AURO-GENERATED-CONTENT This file is to be used for any additional content that should be included in the README.md which is specific to this component. -->
 <!-- AURO-GENERATED-CONTENT:END -->
 
-## Use Cases
+## Use cases
 
 <!-- AURO-GENERATED-CONTENT:START (FILE:src=./docs/partials/useCases.md) -->
 <!-- The below content is automatically added from ./docs/partials/useCases.md -->
-The `<auro-datetime>` element should be used in situations where users may:
+Use `<auro-datetime>` to:
 
-* A date and/or time is required
+* Show a date or time, such as a departure date or arrival time.
+* Show a time in a specific time zone, such as a flight's local time at its airport.
+* Format a date for a language and region, such as `de-DE` or `ja-JP`.
 <!-- AURO-GENERATED-CONTENT:END -->
 
 ## Install
@@ -49,10 +51,10 @@ The `<auro-datetime>` element should be used in situations where users may:
 
 <!-- AURO-GENERATED-CONTENT:END -->
 
-### Define Dependency in Project
+### Define dependency in project
 
 <!-- AURO-GENERATED-CONTENT:START (REMOTE:url=https://raw.githubusercontent.com/AlaskaAirlines/auro-templates/main/templates/default/partials/usage/componentImportDescription.md) -->
-Defining the dependency within each project that is using the `<auro-datetime>` component.
+Import the component in each project that uses `<auro-datetime>`.
 
 <!-- AURO-GENERATED-CONTENT:END -->
 <!-- AURO-GENERATED-CONTENT:START (REMOTE:url=https://raw.githubusercontent.com/AlaskaAirlines/auro-templates/main/templates/default/partials/usage/componentImport.md) -->
@@ -64,41 +66,40 @@ Defining the dependency within each project that is using the `<auro-datetime>`
 ### Use CDN
 
 <!-- AURO-GENERATED-CONTENT:START (REMOTE:url=https://raw.githubusercontent.com/AlaskaAirlines/auro-templates/main/templates/default/partials/usage/bundleInstallDescription.md) -->
-In cases where the project is not able to process JS assets, there are pre-processed assets available for use. Legacy browsers such as IE11 are no longer supported.
+If your project can't process JS assets, use the pre-processed assets. Legacy browsers, such as IE11, aren't supported.
 
-<pre class="language-html"><code class="language-html">&lt;script type="module" src="https://cdn.jsdelivr.net/npm/@aurodesignsystem/auro-datetime@latest/+esm"&gt;&lt;/script&gt;</code></pre>
+<pre class="language-html"><code class="language-html">&lt;script type="module" src="https://cdn.jsdelivr.net/npm/@aurodesignsystem/auro-datetime@latest/+esm"&gt;&lt;/script&gt;</code></pre>
 
 <!-- AURO-GENERATED-CONTENT:END -->
 
-## Basic Example
+## Basic example
 
 <!-- AURO-GENERATED-CONTENT:START (CODE:src=./apiExamples/basic.html) -->
 <!-- The below code snippet is automatically added from ./apiExamples/basic.html -->
 
-<pre class="language-html"><code class="language-html">&lt;auro-datetime type="date"&gt;&lt;/auro-datetime&gt;</code></pre>
+<pre class="language-html"><code class="language-html">&lt;auro-datetime type="date"&gt;&lt;/auro-datetime&gt;</code></pre>
 <!-- AURO-GENERATED-CONTENT:END -->
 
-## Custom Component Registration for Version Management
+## Custom component registration for version management
 
-There are two key parts to every Auro component: the <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Classes">class</a> and the custom element definition.
+Every Auro component has two key parts: the <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Classes">class</a> and the custom element definition.
 The class defines the component’s behavior, while the custom element registers it under a specific name so it can be used in HTML.
 
-When you install the component as described on the `Install` page, the class is imported automatically, and the component is registered globally for you.
+Installing the component as described in the Install section imports the class and registers the component globally for you.
 
-However, if you need to load multiple versions of the same component on a single page (for example, when two projects depend on different versions), you can manually register the class under a custom element name to avoid conflicts.
+However, if you need to load multiple versions of the same component on a single page (for example, when two projects depend on different versions), register the class manually under a custom element name to avoid conflicts.
 
-You can do this by importing only the component class and using the `register(name)` method with a unique name:
+To do this, import only the component class and call the `register(name)` method with a unique name:
 
 <!-- AURO-GENERATED-CONTENT:START (FILE:src=./docs/partials/customRegistration.md) -->
 <!-- The below content is automatically added from ./docs/partials/customRegistration.md -->
 
 <pre class="language-js"><code class="language-js">// Import the class only
 import { AuroDatetime } from '@aurodesignsystem/auro-datetime/class';
-​
-// Register with a custom name if desired
+&#10;// Register it under a custom name
 AuroDatetime.register('custom-datetime');</code></pre>
 
-This will create a new custom element `<custom-datetime>` that behaves exactly like `<auro-datetime>`, allowing both to coexist on the same page without interfering with each other.
+`<custom-datetime>` then works the same as `<auro-datetime>`, and both can run on the same page without affecting each other.
 <!-- AURO-GENERATED-CONTENT:END -->
 <div class="exampleWrapper exampleWrapper--flex">
 <!-- AURO-GENERATED-CONTENT:START (FILE:src=./apiExamples/custom.html) -->
@@ -111,6 +112,6 @@ This will create a new custom element `<custom-datetime>` that behaves exactly l
 <!-- AURO-GENERATED-CONTENT:START (CODE:src=./apiExamples/custom.html) -->
 <!-- The below code snippet is automatically added from ./apiExamples/custom.html -->
 
-<pre class="language-html"><code class="language-html">&lt;custom-datetime type="date"&gt;&lt;/custom-datetime&gt;</code></pre>
+<pre class="language-html"><code class="language-html">&lt;custom-datetime type="date"&gt;&lt;/custom-datetime&gt;</code></pre>
 <!-- AURO-GENERATED-CONTENT:END -->
 </auro-accordion>

package/dist/auro-datetime-CRsYbYbt.js

@@ -0,0 +1,6 @@
+import{LitElement as e,html as t}from"lit";class i{registerComponent(e,t){customElements.get(e)||customElements.define(e,class extends t{})}closestElement(e,t=this,i=(t,n=t&&t.closest(e))=>t&&t!==document&&t!==window?n||i(t.getRootNode().host):null){return i(t)}handleComponentTagRename(e,t){const i=t.toLowerCase();e.tagName.toLowerCase()!==i&&e.setAttribute(i,!0)}elementMatch(e,t){const i=t.toLowerCase();return e.tagName.toLowerCase()===i||e.hasAttribute(i)}getSlotText(e,t){const i=e.shadowRoot?.querySelector(`slot[name="${t}"]`);return(i?.assignedNodes({flatten:!0})||[]).map(e=>e.textContent?.trim()).join(" ").trim()||null}}const n=/^(\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._warnedValues=new Set,this._effectiveLocale=this._resolveLocale(this.locale),this._effectiveTimeZone=this._resolveTimeZone(this.timezone),this.runtimeUtils=new i}_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. Ignoring it.`)))}}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"){i.prototype.registerComponent(e,a)}willUpdate(e){e.has("locale")&&(this._effectiveLocale=this._resolveLocale(this.locale)),e.has("timezone")&&(this._effectiveTimeZone=this._resolveTimeZone(this.timezone))}firstUpdated(){this.runtimeUtils.handleComponentTagRename(this,"auro-datetime")}_zonedWallClockToUtc(e,t){const i=new Date(`${e}Z`),n=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(i),a=Object.fromEntries(n.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=i.getTime()-o.getTime();return new Date(i.getTime()+s)}_resolveInputDate(){const e=this._effectiveTimeZone;if(null==this.value)return{date:new Date,timeZoneOption:e};const t=this.value.match(n);if(!t)return this._warnedValues.has(this.value)||(this._warnedValues.add(this.value),console.warn(`auro-datetime: "${this.value}" is not a valid ISO 8601 string.`)),{date:null,timeZoneOption:void 0};const i=t[1],a=Boolean(t[2]);if(a&&!i.includes("T"))return this._warnedValues.has(this.value)||(this._warnedValues.add(this.value),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=i.includes("T")?i:`${i}T00:00:00`,s=(()=>e&&!a?this._zonedWallClockToUtc(o,e):e&&a?new Date(this.value):new Date(o))();return Number.isNaN(s.getTime())?(this._warnedValues.has(this.value)||(this._warnedValues.add(this.value),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 i={weekday:this.weekday||"short",year:"numeric",month:this.month||"short",day:"numeric"};return t&&(i.timeZone=t),e.toLocaleString(this._effectiveLocale,i)}humanDateConversion(){const{date:e,timeZoneOption:t}=this._resolveInputDate();if(!e)return"";const i={};switch(t&&(i.timeZone=t),this.type){case"day":i.day="numeric";break;case"month":i.month=this.month||"short";break;case"year":i.year="numeric";break;case"weekday":i.weekday=this.weekday||"short"}return e.toLocaleString(this._effectiveLocale,i)}numericDate(){const{date:e,timeZoneOption:t}=this._resolveInputDate();if(!e)return"";const i={year:"numeric",month:"numeric",day:"numeric"};return t&&(i.timeZone=t),e.toLocaleString(this._effectiveLocale,i)}humanTime(){const{date:e,timeZoneOption:t}=this._resolveInputDate();if(!e)return"";const i={hour:"2-digit",minute:"2-digit"};t&&(i.timeZone=t);const n=e.toLocaleString(this._effectiveLocale,i);return/[ap]\.?m\.?/iu.test(n)?n.replace(/^0+/u,"").toLowerCase():n}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};