@aurodesignsystem-dev/auro-formkit 0.0.0-pr1503.3 → 0.0.0-pr1503.5

package/components/datepicker/dist/{src/auro-datepicker.d.ts → auro-datepicker.d.ts}

@@ -12,6 +12,8 @@
  * @slot label - Defines the label content for the entire datepicker when `layout="snowflake"`.
  * @slot toLabel - Defines the label content for the second input when the `range` attribute is used.
  * @slot fromLabel - Defines the label content for the first input.
+ * @slot optionalFromLabel - Overrides the "(optional)" text rendered next to the first input's label when the datepicker is not `required`.
+ * @slot optionalToLabel - Overrides the "(optional)" text rendered next to the second input's label when `range` is set and the datepicker is not `required`.
  * @slot date_YYYY_MM_DD - Defines the content to display in the auro-calendar-cell for the specified date. The content text is colored using the success state token when the `highlight` attribute is applied to the slot.
  * @slot popover_YYYY_MM_DD - Defines the content to display in the auro-calendar-cell popover for the specified date.
  * @csspart dropdown - Use for customizing the style of the dropdown.
@@ -52,6 +54,14 @@ export class AuroDatePicker extends AuroElement {
         };
         /**
          * Array of dates that cannot be selected. Dates should be in ISO format (YYYY-MM-DD).
+         *
+         * **Immutable update required.** The datepicker treats this array as
+         * immutable and memoizes a lookup Set keyed on the array's reference
+         * identity — matching Lit's own reactivity semantics for array
+         * properties. In-place mutations (`blackoutDates.push(...)`,
+         * `blackoutDates[i] = ...`, `blackoutDates.splice(...)`) will not
+         * invalidate the cache and the new entries will be silently ignored.
+         * To update, reassign the property: `el.blackoutDates = [...el.blackoutDates, '2024-12-25']`.
          */
         blackoutDates: {
             type: ArrayConstructor;
@@ -59,6 +69,7 @@ export class AuroDatePicker extends AuroElement {
         };
         /**
          * Label announced for blackout (disabled but in-range) date cells.
+         * @default 'unavailable'
          */
         blackoutLabel: {
             type: StringConstructor;
@@ -73,6 +84,7 @@ export class AuroDatePicker extends AuroElement {
         };
         /**
          * Accessible label for the calendar grid containing the days of the month.
+         * @default 'Calendar days of the month'
          */
         calendarGridLabel: {
             type: StringConstructor;
@@ -209,6 +221,7 @@ export class AuroDatePicker extends AuroElement {
         };
         /**
          * Accessible label for the next month navigation button.
+         * @default 'Next month'
          */
         navLabelNextMonth: {
             type: StringConstructor;
@@ -216,6 +229,7 @@ export class AuroDatePicker extends AuroElement {
         };
         /**
          * Accessible label for the previous month navigation button.
+         * @default 'Previous month'
          */
         navLabelPrevMonth: {
             type: StringConstructor;
@@ -281,7 +295,11 @@ export class AuroDatePicker extends AuroElement {
             reflect: boolean;
         };
         /**
-         * Label announced for cells after the range (or after start when no end is selected).
+         * Label announced for cells after a fully selected range (both
+         * `dateFrom` and `dateTo` are set). While a range is still being
+         * picked (`dateFrom` set, `dateTo` unset), focused cells past the
+         * start use `rangeLabelEndPreview` instead.
+         * @default 'after range'
          */
         rangeLabelAfterRange: {
             type: StringConstructor;
@@ -289,6 +307,7 @@ export class AuroDatePicker extends AuroElement {
         };
         /**
          * Label announced for cells before the range start.
+         * @default 'before range'
          */
         rangeLabelBeforeRange: {
             type: StringConstructor;
@@ -296,13 +315,25 @@ export class AuroDatePicker extends AuroElement {
         };
         /**
          * Label announced for the range end date cell.
+         * @default 'range end'
          */
         rangeLabelEnd: {
             type: StringConstructor;
             reflect: boolean;
         };
+        /**
+         * Label announced for the focused cell while previewing a range end
+         * (dateFrom set, dateTo not yet selected). Tells AT users that
+         * pressing Enter would commit this cell as the range end.
+         * @default 'previewing range end'
+         */
+        rangeLabelEndPreview: {
+            type: StringConstructor;
+            reflect: boolean;
+        };
         /**
          * Label announced for cells within the selected range.
+         * @default 'in range'
          */
         rangeLabelInRange: {
             type: StringConstructor;
@@ -310,13 +341,14 @@ export class AuroDatePicker extends AuroElement {
         };
         /**
          * Label announced for the range start date cell.
+         * @default 'range start'
          */
         rangeLabelStart: {
             type: StringConstructor;
             reflect: boolean;
         };
         /**
-         * Dates that the user should have for reference as part of their decision making when selecting a date.
+         * Dates that the user should have for reference as part of their decision-making when selecting a date.
          * This should be a JSON string array of ISO date strings (`YYYY-MM-DD`).
          */
         referenceDates: {
@@ -414,6 +446,15 @@ export class AuroDatePicker extends AuroElement {
      *
      */
     static register(name?: string): void;
+    /**
+     * Per-class dedup set used by `_warnInvalidLocale`. Static so the dedup
+     * spans every datepicker instance on the page; lives on the class (not
+     * at module scope) so it stays an encapsulated implementation detail of
+     * this component and does not interfere with WCA's class-JSDoc
+     * attachment.
+     * @private
+     */
+    private static _warnedInvalidLocales;
     /**
      * @private
      */
@@ -438,6 +479,7 @@ export class AuroDatePicker extends AuroElement {
     rangeLabelBeforeRange: string;
     rangeLabelInRange: string;
     rangeLabelAfterRange: string;
+    rangeLabelEndPreview: string;
     blackoutDates: any[];
     blackoutLabel: string;
     navLabelPrevMonth: string;
@@ -518,6 +560,21 @@ export class AuroDatePicker extends AuroElement {
      * @returns {void}
      */
     private handleClick;
+    /**
+     * Single AbortController shared by every listener registered in the
+     * configure* methods. Lets disconnectedCallback tear all of them down
+     * with one abort() call.
+     *
+     * The genuine leak risk is the listeners attached to children that can
+     * outlive the host if they get reparented — `this.dropdown`,
+     * `this.calendar`, and the inputs inside the dropdown's slot.
+     * Listeners attached to `this` (e.g. focusin/focusout on the host)
+     * form a self-contained reference graph that the GC can collect with
+     * the host anyway, but they share the same signal so the cleanup
+     * pattern stays uniform across all configure* sites.
+     * @private
+     */
+    private _listenerAbortController;
     /**
      * Handles click on the clear button.
      * @private
@@ -635,10 +692,26 @@ export class AuroDatePicker extends AuroElement {
      */
     get calendarFocusDateObject(): Date | undefined;
     /**
-     * Converts a Unix timestamp (seconds) from the vendor calendar to an ISO date string.
+     * Converts a Unix timestamp (seconds) from the vendored range-datepicker
+     * (`src/vendor/wc-range-datepicker/day.js`) to an ISO date string.
+     *
+     * Timezone contract:
+     * - INPUT: `time` is assumed to be the seconds-since-epoch of **local
+     *   midnight** for the intended calendar day. The vendor's Day constructor
+     *   builds it via `date-fns format(date, 't')` from a locally-constructed
+     *   Date, so this assumption currently holds end-to-end.
+     * - OUTPUT: `dateFormatter.toISOFormatString` reads the Date's local
+     *   getFullYear/getMonth/getDate components, so the returned YYYY-MM-DD
+     *   string matches the local calendar day.
+     *
+     * If the vendor ever switches to emitting UTC-midnight timestamps, this
+     * conversion will silently shift the returned date by one day in zones
+     * west of UTC. Any vendor swap should re-verify this contract; the TZ
+     * regression suite (`npm run test:hst`, UTC-10) will catch the symptom.
+     *
      * @private
-     * @param {number} time - Unix timestamp in seconds.
-     * @returns {string} ISO date string (yyyy-mm-dd).
+     * @param {number} time - Unix timestamp (seconds), local midnight of the day.
+     * @returns {string} ISO date string (yyyy-mm-dd) reflecting the local calendar day.
      */
     private convertWcTimeToDate;
     /**
@@ -680,7 +753,7 @@ export class AuroDatePicker extends AuroElement {
      */
     private configureDropdown;
     dropdown: any;
-    centralDate: any;
+    _restoreFocusOnClose: boolean | undefined;
     /**
      * Binds all behavior needed to the input after rendering.
      * @private
@@ -770,6 +843,16 @@ export class AuroDatePicker extends AuroElement {
      * @returns {boolean}
      */
     get hasError(): boolean;
+    /**
+     * Logs a one-time `console.debug` when an unsupported locale falls back to
+     * en-US. Deduped by the offending tag so noisy re-renders that resurface
+     * the same bad value stay quiet, but each new bad value still signals so
+     * consumers can spot the typo or missing tag.
+     * @private
+     * @param {string|undefined} badLocale - The locale value that failed.
+     * @returns {void}
+     */
+    private _warnInvalidLocale;
     /**
      * Lifecycle method to check if the locale is valid.
      * @ignore

package/components/datepicker/dist/blackoutUtils.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Single source of truth for parsing and matching blackout dates across the
+ * datepicker. Both `auro-calendar` (memoized Set + `isDateBlackout`) and the
+ * pre-`firstUpdated` fallback inside `auro-calendar-cell` route through these
+ * helpers so the YYYY-MM-DD → seconds conversion and the merge-with-legacy
+ * `disabledDays` rules are defined exactly once.
+ */
+/**
+ * Converts a `YYYY-MM-DD` ISO date string to a Unix timestamp (seconds)
+ * representing local midnight on that calendar day. Returns `null` for
+ * inputs that don't parse to a finite timestamp.
+ *
+ * Uses the `new Date(year, monthIndex, day)` constructor (NOT
+ * `new Date(isoStr)`) so the result is local-midnight rather than UTC
+ * midnight — required to keep the calendar grid aligned with the user's
+ * local calendar day in negative-offset timezones.
+ *
+ * @param {string} isoStr - Date string in `YYYY-MM-DD` format.
+ * @returns {number|null} Local-midnight Unix timestamp (seconds), or null.
+ */
+export function parseIsoToTimestamp(isoStr: string): number | null;
+/**
+ * Builds a `Set<number>` of seconds-since-epoch timestamps covering both the
+ * legacy `disabledDays` (already-numeric) array and the ISO `blackoutDates`
+ * array. Use this for O(1) membership checks in hot paths.
+ *
+ * @param {Array<string|number>|undefined} disabledDays - Legacy timestamp array.
+ * @param {Array<string>|undefined} blackoutDates - ISO `YYYY-MM-DD` array.
+ * @returns {Set<number>}
+ */
+export function buildBlackoutSet(disabledDays: Array<string | number> | undefined, blackoutDates: Array<string> | undefined): Set<number>;
+/**
+ * One-shot membership test for a single timestamp against both blackout
+ * sources. Allocates a Set on each call; only use this in cold paths
+ * (e.g. the pre-`firstUpdated` cell fallback). Hot paths should hold the
+ * Set returned from `buildBlackoutSet` and `.has(ts)` directly.
+ *
+ * @param {number} dateTs - Unix timestamp (seconds) to test.
+ * @param {Array<string|number>|undefined} disabledDays - Legacy timestamp array.
+ * @param {Array<string>|undefined} blackoutDates - ISO `YYYY-MM-DD` array.
+ * @returns {boolean}
+ */
+export function isBlackoutTimestamp(dateTs: number, disabledDays: Array<string | number> | undefined, blackoutDates: Array<string> | undefined): boolean;