@aurodesignsystem-dev/auro-formkit 0.0.0-pr1489.5 → 0.0.0-pr1489.7

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

@@ -6,9 +6,6 @@ export class AuroCalendarCell extends LitElement {
         selected: {
             type: BooleanConstructor;
         };
-        hovered: {
-            type: BooleanConstructor;
-        };
         dateTo: {
             type: StringConstructor;
         };
@@ -31,9 +28,6 @@ export class AuroCalendarCell extends LitElement {
         disabledDays: {
             type: ArrayConstructor;
         };
-        hoveredDate: {
-            type: StringConstructor;
-        };
         isCurrentDate: {
             type: BooleanConstructor;
         };
@@ -46,10 +40,6 @@ export class AuroCalendarCell extends LitElement {
         renderForDateSlot: {
             type: BooleanConstructor;
         };
-        active: {
-            type: BooleanConstructor;
-            reflect: boolean;
-        };
         hasPopoverContent: {
             type: BooleanConstructor;
         };
@@ -57,7 +47,6 @@ export class AuroCalendarCell extends LitElement {
     static get styles(): import("lit").CSSResult[];
     day: any;
     selected: boolean;
-    hovered: boolean;
     dateTo: any;
     dateFrom: any;
     month: any;
@@ -65,7 +54,6 @@ export class AuroCalendarCell extends LitElement {
     max: any;
     disabled: boolean;
     disabledDays: any[];
-    hoveredDate: any;
     isCurrentDate: boolean;
     _locale: any;
     dateStr: string | null;
@@ -77,11 +65,12 @@ export class AuroCalendarCell extends LitElement {
     set locale(value: any);
     get locale(): any;
     /**
-     * Handles selected and hovered states of the calendar cell when the date changes.
+     * Handles selected state of the calendar cell when the selection changes.
+     * Also clears any imperative range preview classes so classMap is the
+     * sole source of truth after a selection update.
      * @private
      * @param {Number} dateFrom - Depart date.
      * @param {Number} dateTo - Return date.
-     * @param {Number} hoveredDate - Hovered date.
      * @param {Object} day - An object containing the dateFrom and day of month values.
      * @returns {void}
      */
@@ -94,11 +83,21 @@ export class AuroCalendarCell extends LitElement {
     private handleTap;
     /**
      * Handles user hover events and dispatches a custom event.
-     * Always dispatches for range pickers so the preview updates correctly.
+     * Does NOT set any reactive properties — the range preview is handled
+     * imperatively by the calendar component to avoid O(N) re-renders.
      * @private
      * @returns {void}
      */
     private handleHover;
+    /**
+     * Handles focus events on the cell button.
+     * Dispatches a lightweight event for the calendar to handle SR
+     * announcements and range preview updates without triggering
+     * any Lit lifecycle updates.
+     * @private
+     * @returns {void}
+     */
+    private handleFocus;
     /**
      * Checks if the current date is outside the valid min/max range.
      * Out-of-range cells are not focusable and are hidden from screen readers.
@@ -185,9 +184,9 @@ export class AuroCalendarCell extends LitElement {
      */
     private isLastHoveredDate;
     /**
-     * Checks if the current date is a highlighted date.
+     * Checks if the current date is a referenced date.
      * @param {Object} dateStr - The date string in MM_DD_YYYY format.
-     * @returns Boolean - True if the date is a highlighted date.
+     * @returns Boolean - True if the date is a referenced date.
      */
     isReferenceDate(dateStr: Object): boolean;
     /**
@@ -212,6 +211,7 @@ export class AuroCalendarCell extends LitElement {
     firstUpdated(): void;
     datepicker: any;
     _slotContentHandler: (() => void) | undefined;
+    _cachedButton: Element | null | undefined;
     calendarMonth: any;
     /**
      * Configures the popover instance with the calendar month boundary.
@@ -223,11 +223,46 @@ export class AuroCalendarCell extends LitElement {
     private configurePopover;
     auroPopover: any;
     updated(properties: any): void;
+    /**
+     * Updates ARIA attributes on the host element so that
+     * ariaActiveDescendantElement can expose cell info to the SR.
+     * @private
+     * @returns {void}
+     */
+    private updateHostAria;
     /**
      * Programmatically focuses the cell's interactive button element.
+     * Uses focusVisible: true so the :focus-visible ring appears even when
+     * the bib was opened via mouse click (which sets mouse input modality).
      * @returns {void}
      */
     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.
+     * @returns {void}
+     */
+    setActive(): void;
+    /**
+     * Imperatively marks this cell as inactive without triggering a Lit re-render.
+     * @returns {void}
+     */
+    clearActive(): void;
+    /**
+     * Updates range preview classes imperatively (no Lit re-render).
+     * Called by the calendar component when the hovered date changes
+     * during range selection (dateFrom set, dateTo not yet set).
+     * @param {Number} hoveredDate - Unix timestamp of the currently hovered/focused date.
+     * @param {Number} dateFrom - Unix timestamp of the selected departure date.
+     * @returns {void}
+     */
+    updateRangePreviewClasses(hoveredDate: number, dateFrom: number): void;
+    /**
+     * Clears all imperative range preview classes from the cell button.
+     * Called when a selection occurs so classMap becomes the sole source of truth.
+     * @returns {void}
+     */
+    clearRangePreviewClasses(): void;
     renderCellButton(): import("lit-html").TemplateResult;
     render(): import("lit-html").TemplateResult;
 }

package/components/datepicker/dist/src/auro-calendar-month.d.ts

@@ -37,12 +37,20 @@ export class AuroCalendarMonth extends RangeDatepickerCalendar {
      */
     getFocusableCells(): any[];
     /**
-     * Handles arrow key navigation within the month grid.
-     * Dispatches a cross-month navigation event when the boundary is reached.
+     * Overrides the base class handler to prevent setting `this.hoveredDate`
+     * as a reactive property. Instead, just dispatches the event upward so
+     * the calendar can handle range preview imperatively.
      * @private
-     * @param {KeyboardEvent} event - The keyboard event.
+     * @param {CustomEvent} event - The date-is-hovered event from a cell.
      * @returns {void}
      */
-    private handleGridKeyDown;
+    private handleDateHovered;
+    /**
+     * Dispatches a bubbling event when the mouse leaves the date grid body
+     * so the parent calendar can clear the range hover preview.
+     * @private
+     * @returns {void}
+     */
+    private handleTbodyMouseLeave;
 }
 import { RangeDatepickerCalendar } from './vendor/wc-range-datepicker/range-datepicker-calendar.js';

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

@@ -129,6 +129,12 @@ export class AuroCalendar extends RangeDatepicker {
      * @private
      */
     private activeCellDate;
+    /**
+     * Whether the #calendarGrid wrapper currently has focus.
+     * Used to determine whether the visualFocus ring should be shown.
+     * @private
+     */
+    private _gridHasFocus;
     /**
      * @private
      */
@@ -154,16 +160,40 @@ export class AuroCalendar extends RangeDatepicker {
      */
     private buttonTag;
     dropdown: any;
+    /**
+     * Unique instance ID for the live region element.
+     * @private
+     */
+    private _calendarInstanceId;
+    /**
+     * Updates the month and year when the user navigates to the previous calendar month.
+     * @private
+     * @param {Object} [options] - Optional settings.
+     * @param {boolean} [options.skipActiveUpdate=false] - When true, skip the active cell
+     *   recomputation. Used by arrow key handlers that manage the active cell themselves.
+     * @returns {void}
+     */
+    private handlePrevMonth;
+    /**
+     * Updates the month and year when the user navigates to the next calendar month.
+     * @private
+     * @param {Object} [options] - Optional settings.
+     * @param {boolean} [options.skipActiveUpdate=false] - When true, skip the active cell
+     *   recomputation. Used by arrow key handlers that manage the active cell themselves.
+     * @returns {void}
+     */
+    private handleNextMonth;
     /**
      * Announces the current month and year via the live region after navigation.
      * @private
      * @returns {void}
      */
     private announceMonthChange;
+    _focusAnnounceTimer: any;
     /**
-     * Recomputes and sets the active cell for the newly visible month after
-     * month navigation. Without this, activeCellDate can point at a date in
-     * the old month, leaving no tabindex="0" cell in the grid.
+     * Updates the active cell after month navigation (prev/next buttons).
+     * Always moves the active cell to the first enabled date in the newly
+     * visible months so that tabbing back to the grid lands on an enabled cell.
      * @private
      * @returns {void}
      */
@@ -201,17 +231,32 @@ 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.
      * @param {Number} date - Unix timestamp of the cell to activate.
      * @returns {void}
      */
     setActiveCell(date: number): void;
     /**
-     * Focuses the currently active cell. If activeCellDate is set but no cell
-     * has the active attribute yet, sets it first. Waits for the cell's render
-     * to complete so the focused button is the final DOM element.
+     * Focuses the calendar grid wrapper and sets the active cell.
+     * DOM focus stays on the grid wrapper; the aria-live region
+     * tells the screen reader which cell is "active".
      * @returns {void}
      */
     focusActiveCell(): void;
+    /**
+     * Shows the activeCell ring when the grid gains focus.
+     * @private
+     * @returns {void}
+     */
+    private handleGridFocusIn;
+    /**
+     * Hides the activeCell ring when the grid loses focus.
+     * @private
+     * @returns {void}
+     */
+    private handleGridFocusOut;
     /**
      * Computes the initial active date from data properties alone — no DOM required.
      * Priority:
@@ -223,7 +268,7 @@ export class AuroCalendar extends RangeDatepicker {
      *   5b. First enabled date scanning forward from finite min (unbounded max)
      *   5c. First enabled date scanning backward from finite max (unbounded min)
      *   6. First in-range date (even if blackout) so focus can land somewhere
-     *   7. undefined — no valid target
+     *   7. Undefined — no valid target.
      *
      * @private
      * @param {Object} [options] - Optional settings.
@@ -233,6 +278,24 @@ export class AuroCalendar extends RangeDatepicker {
      * @returns {Number|undefined} Unix timestamp (seconds) of the date to activate, or undefined.
      */
     private computeActiveDate;
+    /**
+     * Checks if a target date (unix seconds) is within the configured [min, max] range.
+     * Returns false if the date falls outside the range, preventing navigation
+     * to months where all dates are disabled.
+     * @private
+     * @param {Number} targetTs - Unix timestamp in seconds.
+     * @returns {Boolean} True if the date is within range.
+     */
+    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.
+     * @private
+     * @param {KeyboardEvent} event - The keyboard event.
+     * @returns {void}
+     */
+    private handleGridKeyDown;
     /**
      * Handles cross-month boundary navigation events from month components.
      * @private
@@ -247,6 +310,60 @@ export class AuroCalendar extends RangeDatepicker {
      * @returns {void}
      */
     private handleCellActivate;
+    /**
+     * Handles focus events from calendar cells.
+     * Updates the live region with an SR announcement and triggers
+     * the imperative range preview if applicable.
+     * @private
+     * @param {CustomEvent} event - The calendar-cell-focused event.
+     * @returns {void}
+     */
+    private handleCellFocused;
+    /**
+     * Builds a full SR announcement string for a focused cell date.
+     * Includes the localized date, range position, popover content,
+     * and blackout status.
+     * @private
+     * @param {Number} date - Unix timestamp (seconds) of the focused cell.
+     * @returns {String} The announcement string.
+     */
+    private buildFocusAnnouncement;
+    /**
+     * Determines the range position label for a given date.
+     * @private
+     * @param {Number} date - Unix timestamp (seconds).
+     * @returns {String|null} The range position label, or null.
+     */
+    private getRangePositionLabel;
+    /**
+     * Checks whether a given date is a blackout date.
+     * @private
+     * @param {Number} dateTs - Unix timestamp (seconds).
+     * @returns {Boolean} True if the date is blacked out.
+     */
+    private isDateBlackout;
+    /**
+     * Updates the range preview classes imperatively across all cells.
+     * Only active when in range mode with dateFrom set and dateTo not yet set.
+     * @private
+     * @param {Number} hoveredDate - Unix timestamp of the hovered/focused date.
+     * @returns {void}
+     */
+    private updateRangePreview;
+    /**
+     * Clears range preview classes from all cells.
+     * @private
+     * @returns {void}
+     */
+    private clearRangePreview;
+    /**
+     * Overrides the base class handler to prevent setting `this.hoveredDate`
+     * as a reactive property. Instead, handles the range preview imperatively.
+     * @private
+     * @param {CustomEvent} event - The hovered-date-changed event from a month.
+     * @returns {void}
+     */
+    private hoveredDateChanged;
     /**
      * Scrolls the calendar to ensure the month containing the active cell is visible.
      * @private
@@ -254,12 +371,48 @@ export class AuroCalendar extends RangeDatepicker {
      */
     private scrollToActiveCell;
     /**
-     * Announces a date selection via the live region.
+     * Returns (and lazily creates) an aria-live region inside the dropdown's
+     * <dialog> element. This placement is critical for two reasons:
+     *
+     * 1. Inside the dialog's accessible scope — dialog.showModal() makes
+     *    everything outside the top-layer dialog inert, and desktop modal
+     *    mode uses _setPageInert() on document.body siblings. A live region
+     *    on document.body would be invisible to screen readers in both cases.
+     *
+     * 2. Not nested in shadow DOM — Chrome inconsistently observes aria-live
+     *    mutations inside shadow DOM across machines and versions. The dialog
+     *    element is only one shadow root deep (the dropdown bib's shadow DOM),
+     *    which Chrome handles reliably. The calendar's own shadow DOM (nested
+     *    inside the bib via slotting) is two+ levels deep and unreliable.
+     *
+     * @private
+     * @returns {HTMLElement} The live region element.
+     */
+    private getOrCreateLiveRegion;
+    _liveRegion: any;
+    _announceRafId: any;
+    /**
+     * Announces a date selection or focus change via the live region.
+     * Uses requestAnimationFrame to ensure the clear and set happen in
+     * separate rendering frames — Chrome may coalesce synchronous or
+     * microtask-deferred mutations into a single accessibility tree update.
      * @private
      * @param {String} dateStr - The localized date string to announce.
      * @returns {void}
      */
     private announceSelection;
+    /**
+     * Debounced version of announceSelection for focus navigation.
+     * Uses the assertive live region with a 150ms debounce so only the
+     * final cell after rapid arrow-key traversal is announced. We
+     * originally tried aria-live="polite" here, but VoiceOver treats
+     * polite as "wait until idle" — which never happens during active
+     * keyboard navigation — so the announcements were silently dropped.
+     * @private
+     * @param {String} dateStr - The localized date string to announce.
+     * @returns {void}
+     */
+    private announceFocusDebounced;
     /**
      * Formats a Unix timestamp (seconds) as a localized date string for SR announcements.
      * @private

package/components/datepicker/dist/src/auro-datepicker.d.ts

@@ -39,13 +39,10 @@ export class AuroDatePicker extends AuroElement {
     static get properties(): {
         /**
          * Defines whether the component will be on lighter or darker backgrounds.
-         * @property {'default', 'inverse'}
+         * @type {'default' | 'inverse'}
          * @default 'default'
          */
-        appearance: {
-            type: StringConstructor;
-            reflect: boolean;
-        };
+        appearance: "default" | "inverse";
         /**
          * If declared, bib's position will be automatically calculated where to appear.
          * @default false
@@ -54,6 +51,20 @@ export class AuroDatePicker extends AuroElement {
             type: BooleanConstructor;
             reflect: boolean;
         };
+        /**
+         * Array of dates that cannot be selected. Dates should be in ISO format (YYYY-MM-DD).
+         */
+        blackoutDates: {
+            type: ArrayConstructor;
+            reflect: boolean;
+        };
+        /**
+         * Label announced for blackout (disabled but in-range) date cells.
+         */
+        blackoutLabel: {
+            type: StringConstructor;
+            reflect: boolean;
+        };
         /**
          * The last date that may be displayed in the calendar.
          */
@@ -102,24 +113,6 @@ export class AuroDatePicker extends AuroElement {
             type: StringConstructor;
             reflect: boolean;
         };
-        hasFocus: {
-            type: BooleanConstructor;
-            reflect: boolean;
-        };
-        /**
-         * @private
-         */
-        hasValue: {
-            type: BooleanConstructor;
-            reflect: boolean;
-        };
-        /**
-         * @private
-         */
-        hasAllValues: {
-            type: BooleanConstructor;
-            reflect: boolean;
-        };
         /**
          * Specifies the date format. The default is `mm/dd/yyyy`.
          */
@@ -136,6 +129,24 @@ export class AuroDatePicker extends AuroElement {
          * @default 'sm'
          */
         fullscreenBreakpoint: "xs" | "sm" | "md" | "lg" | "xl" | "disabled";
+        /**
+         * @private
+         */
+        hasAllValues: {
+            type: BooleanConstructor;
+            reflect: boolean;
+        };
+        hasFocus: {
+            type: BooleanConstructor;
+            reflect: boolean;
+        };
+        /**
+         * @private
+         */
+        hasValue: {
+            type: BooleanConstructor;
+            reflect: boolean;
+        };
         /** Exposes inputmode attribute for input. */
         inputmode: {
             type: StringConstructor;
@@ -170,6 +181,12 @@ export class AuroDatePicker extends AuroElement {
             type: StringConstructor;
             reflect: boolean;
         };
+        /**
+         * @private
+         */
+        monthFirst: {
+            type: BooleanConstructor;
+        };
         /**
          * Names of all 12 months to render in the calendar, used for localization of date string in mobile layout.
          */
@@ -177,23 +194,24 @@ export class AuroDatePicker extends AuroElement {
             type: ArrayConstructor;
         };
         /**
-         * @private
+         * Accessible label for the next month navigation button.
          */
-        monthFirst: {
-            type: BooleanConstructor;
+        navLabelNextMonth: {
+            type: StringConstructor;
+            reflect: boolean;
         };
         /**
-         * If declared, the bib will NOT flip to an alternate position
-         * when there isn't enough space in the specified `placement`.
+         * Accessible label for the previous month navigation button.
          */
-        noFlip: {
-            type: BooleanConstructor;
+        navLabelPrevMonth: {
+            type: StringConstructor;
             reflect: boolean;
         };
         /**
-         * If declared, the dropdown will shift its position to avoid being cut off by the viewport.
+         * If declared, the bib will NOT flip to an alternate position
+         * when there isn't enough space in the specified `placement`.
          */
-        shift: {
+        noFlip: {
             type: BooleanConstructor;
             reflect: boolean;
         };
@@ -249,16 +267,9 @@ export class AuroDatePicker extends AuroElement {
             reflect: boolean;
         };
         /**
-         * Label announced for the range start date cell.
-         */
-        rangeLabelStart: {
-            type: StringConstructor;
-            reflect: boolean;
-        };
-        /**
-         * Label announced for the range end date cell.
+         * Label announced for cells after the range (or after start when no end is selected).
          */
-        rangeLabelEnd: {
+        rangeLabelAfterRange: {
             type: StringConstructor;
             reflect: boolean;
         };
@@ -270,44 +281,23 @@ export class AuroDatePicker extends AuroElement {
             reflect: boolean;
         };
         /**
-         * Label announced for cells within the selected range.
-         */
-        rangeLabelInRange: {
-            type: StringConstructor;
-            reflect: boolean;
-        };
-        /**
-         * Label announced for cells after the range (or after start when no end is selected).
-         */
-        rangeLabelAfterRange: {
-            type: StringConstructor;
-            reflect: boolean;
-        };
-        /**
-         * Array of dates that cannot be selected. Dates should be in ISO format (YYYY-MM-DD).
-         */
-        blackoutDates: {
-            type: ArrayConstructor;
-            reflect: boolean;
-        };
-        /**
-         * Label announced for blackout (disabled but in-range) date cells.
+         * Label announced for the range end date cell.
          */
-        blackoutLabel: {
+        rangeLabelEnd: {
             type: StringConstructor;
             reflect: boolean;
         };
         /**
-         * Accessible label for the previous month navigation button.
+         * Label announced for cells within the selected range.
          */
-        navLabelPrevMonth: {
+        rangeLabelInRange: {
             type: StringConstructor;
             reflect: boolean;
         };
         /**
-         * Accessible label for the next month navigation button.
+         * Label announced for the range start date cell.
          */
-        navLabelNextMonth: {
+        rangeLabelStart: {
             type: StringConstructor;
             reflect: boolean;
         };
@@ -357,6 +347,13 @@ export class AuroDatePicker extends AuroElement {
         setCustomValidityValueMissing: {
             type: StringConstructor;
         };
+        /**
+         * If declared, the dropdown will shift its position to avoid being cut off by the viewport.
+         */
+        shift: {
+            type: BooleanConstructor;
+            reflect: boolean;
+        };
         /**
          * Set true to make datepicker stacked style.
          */
@@ -364,6 +361,15 @@ export class AuroDatePicker extends AuroElement {
             type: BooleanConstructor;
             reflect: boolean;
         };
+        /**
+         * Indicates whether the datepicker is in a dirty state (has been interacted with).
+         * @private
+         */
+        touched: {
+            type: BooleanConstructor;
+            reflect: boolean;
+            attribute: boolean;
+        };
         /**
          * Specifies the `validityState` this element is in.
          */
@@ -383,15 +389,6 @@ export class AuroDatePicker extends AuroElement {
         valueEnd: {
             type: StringConstructor;
         };
-        /**
-         * Indicates whether the datepicker is in a dirty state (has been interacted with).
-         * @private
-         */
-        touched: {
-            type: BooleanConstructor;
-            reflect: boolean;
-            attribute: boolean;
-        };
     };
     static get styles(): import("lit").CSSResult[];
     /**
@@ -507,7 +504,7 @@ export class AuroDatePicker extends AuroElement {
     /**
      * Handles click on the clear button.
      * @private
-     * @param {MouseEvent} event
+     * @param {MouseEvent} event - The mouse event from the clear button click.
      * @returns {void}
      */
     private handleClearClick;
@@ -538,8 +535,9 @@ export class AuroDatePicker extends AuroElement {
      */
     private get displayValueFontClass();
     /**
-     * @private
      * Common display value wrapper classes.
+     * @private
+     * @returns {Object} Class map for Lit's classMap directive.
      */
     private get commonDisplayValueWrapperClasses();
     /**