@aurodesignsystem-dev/auro-formkit 0.0.0-pr1507.0 → 0.0.0-pr1508.1

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

@@ -25,6 +25,14 @@ export class AuroCalendarCell extends LitElement {
             type: BooleanConstructor;
             reflect: boolean;
         };
+        /**
+         * @deprecated Propagated from the legacy `auro-calendar.disabledDays`
+         * Unix-timestamp array. The cell honors it for backward compatibility
+         * (see the divergence-check fallback inside `isBlackout`), but
+         * consumers should migrate to `auro-datepicker.blackoutDates`
+         * (YYYY-MM-DD ISO strings). The calendar emits a one-time
+         * deprecation warning the first time a non-empty value is observed.
+         */
         disabledDays: {
             type: ArrayConstructor;
         };
@@ -211,6 +219,7 @@ export class AuroCalendarCell extends LitElement {
      */
     private handleSlotContent;
     firstUpdated(): void;
+    calendar: any;
     datepicker: any;
     _slotContentHandler: (() => void) | undefined;
     _cachedButton: Element | null | undefined;
@@ -226,8 +235,8 @@ export class AuroCalendarCell extends LitElement {
     auroPopover: any;
     updated(properties: any): void;
     /**
-     * Updates ARIA attributes on the host element so that
-     * ariaActiveDescendantElement can expose cell info to the SR.
+     * Sets host-level ARIA so each cell exposes its date, selection state,
+     * and blackout status to assistive tech browsing the month grid.
      * @private
      * @returns {void}
      */
@@ -241,7 +250,15 @@ export class AuroCalendarCell extends LitElement {
     focusButton(): void;
     /**
      * Imperatively marks this cell as active without triggering a Lit re-render.
-     * Note: buttons stay tabindex="-1" because the grid uses aria-activedescendant.
+     * Buttons stay tabindex="-1" because DOM focus stays on the grid wrapper —
+     * arrow keys move the active cell imperatively and the live region carries
+     * the SR announcement.
+     *
+     * Refuses to activate out-of-range cells: those are aria-hidden, have no
+     * click/focus handlers, and are filtered out of `getFocusableCells`. The
+     * active class showing on a disabled cell would be visually misleading,
+     * so this guard is the single source of truth across every code path
+     * that might call setActive (keyboard nav, focus restore, cell click).
      * @returns {void}
      */
     setActive(): void;

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

@@ -118,6 +118,13 @@ export class AuroCalendar extends RangeDatepicker {
             type: ArrayConstructor;
         };
     };
+    /**
+     * Per-class flag that gates the `disabledDays` deprecation warning so it
+     * fires exactly once per page no matter how many calendars or rebuild
+     * cycles encounter the legacy array.
+     * @private
+     */
+    private static _warnedDisabledDaysDeprecation;
     /**
      * @private
      */
@@ -144,6 +151,14 @@ export class AuroCalendar extends RangeDatepicker {
      * @private
      */
     private activeCellDate;
+    /**
+     * Cached reference to the active cell host. Set by setActiveCell and
+     * refreshed by scrollToActiveCell when its cache check misses (stale
+     * or missing). Lets scrollToActiveCell skip a full cell scan on each
+     * arrow key.
+     * @private
+     */
+    private _activeCell;
     /**
      * Whether the #calendarGrid wrapper currently has focus.
      * Used to determine whether the visualFocus ring should be shown.
@@ -219,6 +234,32 @@ export class AuroCalendar extends RangeDatepicker {
      * @returns {void}
      */
     private updateActiveCellForVisibleMonth;
+    /**
+     * Schedules `callback` two animation frames out, giving the child
+     * `auro-formkit-calendar-month` and `auro-formkit-calendar-cell` elements
+     * a full render-and-paint cycle to settle before the callback reads or
+     * mutates DOM.
+     *
+     * Why two frames, not one:
+     * 1. Lit batches property updates and renders in a microtask, so frame N
+     *    schedules the render but the new DOM may not be painted yet.
+     * 2. Cells re-cache `_cachedButton` inside their own `updateComplete.then`,
+     *    which also lands a tick later. Reading buttons from frame N+1
+     *    (after both renders + cache refresh have flushed) reliably hits the
+     *    new month's cells.
+     *
+     * Used by every code path that calls `handleNextMonth`/`handlePrevMonth`
+     * and then needs to inspect the freshly-rendered cells (cross-month
+     * keyboard nav, boundary events, `updateActiveCellForVisibleMonth`).
+     * Do NOT collapse to a single rAF — it intermittently lands before
+     * `_cachedButton` is refreshed, which silently breaks focus restoration
+     * and `setActiveCell` lookups.
+     * @private
+     * @param {() => void} callback - Runs once after the month re-render and
+     * the cells' button caches have refreshed.
+     * @returns {void}
+     */
+    private _afterMonthRender;
     /**
      * Renders all of the auro-calendar-months HTML.
      * @private
@@ -244,6 +285,20 @@ export class AuroCalendar extends RangeDatepicker {
      * @returns {Array} Array of auro-formkit-calendar-month elements.
      */
     private getMonthComponents;
+    /**
+     * Picks the focusable cell whose date is closest to targetTs. Used as a
+     * fallback after a month-boundary nav when the exact target date isn't
+     * focusable — typically because the month re-render lagged or the date
+     * was filtered out by isOutOfRange. When two cells are equidistant, the
+     * navigation direction breaks the tie so the user moves the way they
+     * pressed (forward → later cell, backward → earlier cell).
+     * @private
+     * @param {Array} cells - Focusable cells from getAllFocusableCells.
+     * @param {Number} targetTs - Desired Unix timestamp (seconds).
+     * @param {'next'|'prev'} direction - Navigation direction.
+     * @returns {Object|null} The nearest cell, or null when cells is empty.
+     */
+    private pickNearestCell;
     /**
      * Gets all focusable cells across all rendered months.
      * @private
@@ -252,9 +307,9 @@ export class AuroCalendar extends RangeDatepicker {
     private getAllFocusableCells;
     /**
      * Sets the active cell across all months. Only one cell has tabindex="0" at a time.
-     * Uses imperative DOM manipulation — no Lit re-render triggered.
-     * Also updates ariaActiveDescendantElement on the grid wrapper so
-     * screen readers announce the active cell without moving DOM focus.
+     * Uses imperative DOM manipulation — no Lit re-render triggered. DOM focus
+     * stays on the grid wrapper; the live region (see getOrCreateLiveRegion)
+     * is what announces the active cell to assistive tech.
      * @param {Number} date - Unix timestamp of the cell to activate.
      * @returns {void}
      */
@@ -269,6 +324,7 @@ export class AuroCalendar extends RangeDatepicker {
     /**
      * Shows the activeCell ring when the grid gains focus.
      * @private
+     * @param {FocusEvent} [event] - The focusin event.
      * @returns {void}
      */
     private handleGridFocusIn;
@@ -278,6 +334,28 @@ export class AuroCalendar extends RangeDatepicker {
      * @returns {void}
      */
     private handleGridFocusOut;
+    /**
+     * Returns a memoized Set of blackout timestamps (seconds) drawn from both
+     * the legacy `disabledDays` array and the datepicker's ISO `blackoutDates`.
+     * The cache invalidates when either source array's reference changes, which
+     * matches Lit's own reactive identity semantics for array properties.
+     * @private
+     * @returns {Set<Number>}
+     */
+    private _getBlackoutSet;
+    _blackoutSet: Set<number> | undefined;
+    _cachedBlackoutDisabledDays: any;
+    _cachedBlackoutDates: any;
+    /**
+     * One-time `console.debug` directing consumers from the legacy
+     * `disabledDays` Unix-timestamp API to the ISO `blackoutDates` API. Fires
+     * the first time `_getBlackoutSet` rebuilds from a non-empty
+     * `disabledDays`; subsequent calls (on this or any other AuroCalendar
+     * instance on the page) are silent.
+     * @private
+     * @returns {void}
+     */
+    private _warnDisabledDaysDeprecated;
     /**
      * Computes the initial active date from data properties alone — no DOM required.
      * Priority:
@@ -310,8 +388,8 @@ export class AuroCalendar extends RangeDatepicker {
     private isDateInRange;
     /**
      * Handles arrow key navigation on the calendar grid wrapper.
-     * Focus stays on the grid wrapper; only ariaActiveDescendantElement
-     * and the visual active-cell indicator change.
+     * Focus stays on the grid wrapper; only the visual active-cell indicator
+     * changes. The live region announces the new active cell.
      * @private
      * @param {KeyboardEvent} event - The keyboard event.
      * @returns {void}
@@ -357,7 +435,9 @@ export class AuroCalendar extends RangeDatepicker {
      */
     private getRangePositionLabel;
     /**
-     * Checks whether a given date is a blackout date.
+     * Checks whether a given date is a blackout date. Delegates to the
+     * memoized `_getBlackoutSet` so the YYYY-MM-DD parsing and the
+     * legacy/ISO merge rules live in exactly one place (see `blackoutUtils.js`).
      * @private
      * @param {Number} dateTs - Unix timestamp (seconds).
      * @returns {Boolean} True if the date is blacked out.
@@ -391,7 +471,28 @@ export class AuroCalendar extends RangeDatepicker {
      */
     private hoveredDateChanged;
     /**
-     * Scrolls the calendar to ensure the month containing the active cell is visible.
+     * Scrolls the calendar so the active cell is visible.
+     *
+     * Walks the flat tree (rendered, slot-aware) outward from the active
+     * cell's button and calls `scrollBy` on every vertically-scrollable
+     * ancestor by whatever delta still separates the cell from that
+     * ancestor's viewport. Native `scrollIntoView` is not used because the
+     * cell sits inside multiple nested scroll containers (the dropdown bib's
+     * `<dialog>`, the bibtemplate's `#bodyContainer`) and the algorithm only
+     * scrolls one of them on its own, leaving the cell short of the
+     * viewport in mobile fullscreen.
+     *
+     * Uses `behavior: 'auto'` (the spec's universally-supported non-animated
+     * value) so each `scrollBy` resolves synchronously and the next
+     * iteration's `getBoundingClientRect` reads post-scroll positions
+     * accurately. This also satisfies `prefers-reduced-motion` users — the
+     * scroll containers do not set CSS `scroll-behavior: smooth`, so `auto`
+     * is effectively instant.
+     *
+     * The active cell is looked up from the cache populated by
+     * `setActiveCell`. On a cache miss (stale or absent) the cache is
+     * refreshed from a single full scan so subsequent calls stay on the
+     * fast path.
      * @private
      * @returns {void}
      */
@@ -427,6 +528,19 @@ export class AuroCalendar extends RangeDatepicker {
      * @returns {void}
      */
     private announceSelection;
+    /**
+     * Writes `dateStr` to the live region. If the dropdown's dialog hasn't
+     * mounted yet (so getOrCreateLiveRegion can't attach), retries on the
+     * next animation frame up to MAX_LIVE_REGION_RETRIES instead of silently
+     * dropping the announcement. The retry uses the same `_announceRafId`
+     * the double-rAF below uses, so a newer announceSelection call (or
+     * disconnectedCallback) cancels any in-flight retry.
+     * @private
+     * @param {String} dateStr - The localized date string to announce.
+     * @param {Number} attempts - Number of prior retry attempts.
+     * @returns {void}
+     */
+    private _deliverAnnouncement;
     /**
      * Debounced version of announceSelection for focus navigation.
      * Uses the assertive live region with a 150ms debounce so only the

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.
@@ -59,6 +61,7 @@ export class AuroDatePicker extends AuroElement {
         };
         /**
          * Label announced for blackout (disabled but in-range) date cells.
+         * @default 'unavailable'
          */
         blackoutLabel: {
             type: StringConstructor;
@@ -73,6 +76,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 +213,7 @@ export class AuroDatePicker extends AuroElement {
         };
         /**
          * Accessible label for the next month navigation button.
+         * @default 'Next month'
          */
         navLabelNextMonth: {
             type: StringConstructor;
@@ -216,6 +221,7 @@ export class AuroDatePicker extends AuroElement {
         };
         /**
          * Accessible label for the previous month navigation button.
+         * @default 'Previous month'
          */
         navLabelPrevMonth: {
             type: StringConstructor;
@@ -281,7 +287,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 +299,7 @@ export class AuroDatePicker extends AuroElement {
         };
         /**
          * Label announced for cells before the range start.
+         * @default 'before range'
          */
         rangeLabelBeforeRange: {
             type: StringConstructor;
@@ -296,13 +307,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 +333,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 +438,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 +471,7 @@ export class AuroDatePicker extends AuroElement {
     rangeLabelBeforeRange: string;
     rangeLabelInRange: string;
     rangeLabelAfterRange: string;
+    rangeLabelEndPreview: string;
     blackoutDates: any[];
     blackoutLabel: string;
     navLabelPrevMonth: string;
@@ -518,6 +552,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 +684,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;
     /**
@@ -770,6 +835,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;