@aurodesignsystem-dev/auro-formkit 0.0.0-pr1497.0 → 0.0.0-pr1497.2

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,11 +40,13 @@ export class AuroCalendarCell extends LitElement {
         renderForDateSlot: {
             type: BooleanConstructor;
         };
+        hasPopoverContent: {
+            type: BooleanConstructor;
+        };
     };
     static get styles(): import("lit").CSSResult[];
     day: any;
     selected: boolean;
-    hovered: boolean;
     dateTo: any;
     dateFrom: any;
     month: any;
@@ -58,21 +54,23 @@ export class AuroCalendarCell extends LitElement {
     max: any;
     disabled: boolean;
     disabledDays: any[];
-    hoveredDate: any;
     isCurrentDate: boolean;
     _locale: any;
     dateStr: string | null;
     renderForDateSlot: boolean;
+    active: boolean;
+    hasPopoverContent: boolean;
     runtimeUtils: any;
     popoverTag: any;
     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}
      */
@@ -85,12 +83,43 @@ export class AuroCalendarCell extends LitElement {
     private handleTap;
     /**
      * Handles user hover events and dispatches a custom event.
+     * 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;
     /**
-     * Checks if the current date is a valid date depending on the min and max values.
+     * 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.
+     * @private
+     * @param {Object} day - An object containing the dateFrom and day of month values.
+     * @param {Number} min - The minimum date value.
+     * @param {Number} max - The maximum date value.
+     * @returns {Boolean} - True if the date is out of range.
+     */
+    private isOutOfRange;
+    /**
+     * Checks if the current date is a blackout date (in disabledDays but within range).
+     * Blackout cells are focusable but not selectable.
+     * @private
+     * @returns {Boolean} - True if the date is a blackout date.
+     */
+    private isBlackout;
+    /**
+     * Checks if the current date is disabled based on min/max range or the
+     * legacy disabledDays timestamp list.  Sets the `disabled` attribute on the
+     * host when the date falls outside the allowed range or appears in
+     * disabledDays. Note: blackout dates are handled separately by `isBlackout()`.
      * @private
      * @param {Object} day - An object containing the dateFrom and day of month values.
      * @param {Number} min - The minimum date value.
@@ -99,6 +128,25 @@ export class AuroCalendarCell extends LitElement {
      * @returns {Boolean} - True if the date is disabled.
      */
     private isEnabled;
+    /**
+     * Generates a unique cell ID in the format cell-YYYY-MM-DD.
+     * @private
+     * @returns {String} The unique cell ID.
+     */
+    private getCellId;
+    /**
+     * Generates a localized aria-label for the cell button using Intl.DateTimeFormat.
+     * Includes range position and blackout status.
+     * @private
+     * @returns {String} The aria-label string.
+     */
+    private getAriaLabel;
+    /**
+     * Determines the range position of this cell relative to the current selection.
+     * @private
+     * @returns {String|null} Range position label or null if not in range mode.
+     */
+    private getRangePosition;
     /**
      * Checks if the current date is the depart date.
      * @private
@@ -136,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;
     /**
@@ -164,8 +212,60 @@ export class AuroCalendarCell extends LitElement {
     private handleSlotContent;
     firstUpdated(): void;
     datepicker: any;
+    _slotContentHandler: (() => void) | undefined;
+    _cachedButton: Element | null | undefined;
+    calendarMonth: any;
+    /**
+     * Configures the popover instance with the calendar month boundary.
+     * Called from firstUpdated and updated because the popover element is only
+     * rendered after hasPopoverContent becomes true (set by handleSlotContent).
+     * @private
+     * @returns {void}
+     */
+    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;
 }
 import { LitElement } from "lit";

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

@@ -10,7 +10,7 @@ export class AuroCalendarMonth extends RangeDatepickerCalendar {
         };
         /**
          * BCP 47 locale tag (such as `en-US`) for calendar localization.
-         * as wc-range-datepicker expects a `locale` prop, we use `localeCode` to avoid conflicts.
+         * As wc-range-datepicker expects a `locale` prop, we use `localeCode` to avoid conflicts.
          */
         localeCode: {
             type: StringConstructor;
@@ -31,13 +31,50 @@ export class AuroCalendarMonth extends RangeDatepickerCalendar {
     private computeCurrentMonthName;
     _cachedMonthNames: string[] | undefined;
     _cachedMonthNamesLocale: any;
+    /**
+     * Returns the unique heading ID for this month, used by aria-labelledby.
+     * @private
+     * @returns {String} The heading ID.
+     */
+    private getHeadingId;
     /**
      * Determines the current month name based on locale.
+     * Also builds parallel arrays of full day names for abbr attributes.
      * This is a rewrite of the function used in the class RangeDatepickerCalendar and should not be removed from here.
      * @private
      * @param {Object} changedProperties - The properties that have changed since the last update.
      * @returns {void}
      */
     private updated;
+    dayFullNames: any[] | undefined;
+    /**
+     * Renders a day-of-week header with abbr attribute for the full day name.
+     * @private
+     * @param {String} dayOfWeek - The short day name.
+     * @param {Number} index - The index in the dayNamesOfTheWeek array.
+     * @returns {Object} The header HTML.
+     */
+    private renderDayOfWeek;
+    /**
+     * Returns all focusable cell elements (enabled + blackout, not out-of-range) in this month.
+     * @returns {Array} Array of auro-formkit-calendar-cell elements.
+     */
+    getFocusableCells(): any[];
+    /**
+     * 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 {CustomEvent} event - The date-is-hovered event from a cell.
+     * @returns {void}
+     */
+    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

@@ -138,6 +138,18 @@ export class AuroCalendar extends RangeDatepicker {
     visible: boolean;
     largeFullscreenHeadline: boolean;
     isFullscreen: boolean;
+    /**
+     * The date of the currently active cell (Unix timestamp).
+     * Only one cell across the entire calendar has tabindex="0" at a time.
+     * @private
+     */
+    private activeCellDate;
+    /**
+     * Whether the #calendarGrid wrapper currently has focus.
+     * Used to determine whether the visualFocus ring should be shown.
+     * @private
+     */
+    private _gridHasFocus;
     /**
      * @private
      */
@@ -163,12 +175,50 @@ export class AuroCalendar extends RangeDatepicker {
      */
     private buttonTag;
     dropdown: any;
+    /**
+     * Unique instance ID for the live region element.
+     * @private
+     */
+    private _calendarInstanceId;
     /** @returns {Date|undefined} */
     get centralDateObject(): Date | undefined;
     /** @returns {Date|undefined} */
     get minDateObject(): Date | undefined;
     /** @returns {Date|undefined} */
     get maxDateObject(): Date | undefined;
+    /**
+     * 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;
+    /**
+     * 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}
+     */
+    private updateActiveCellForVisibleMonth;
     /**
      * Renders all of the auro-calendar-months HTML.
      * @private
@@ -188,6 +238,214 @@ export class AuroCalendar extends RangeDatepicker {
      * @returns {void}
      */
     scrollMonthIntoView(date: string): void;
+    /**
+     * Gets all rendered month components.
+     * @private
+     * @returns {Array} Array of auro-formkit-calendar-month elements.
+     */
+    private getMonthComponents;
+    /**
+     * Gets all focusable cells across all rendered months.
+     * @private
+     * @returns {Array} Array of auro-formkit-calendar-cell elements.
+     */
+    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 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:
+     *   1. Selected date (dateFrom) if within range
+     *   2. Today's date if not disabled (in-range and not blackout)
+     *   3. First future non-disabled date (scans day-by-day from today up to 1 year)
+     *   4. First previous non-disabled date (scans day-by-day from today up to 1 year)
+     *   5. First enabled date in finite [min, max] range
+     *   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.
+     *
+     * @private
+     * @param {Object} [options] - Optional settings.
+     * @param {boolean} [options.skipDateFrom=false] - When true, skip the selected-date
+     *   shortcut (step 1). Used after month navigation so the active cell lands in the
+     *   newly visible month instead of jumping back to the selected date's month.
+     * @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
+     * @param {CustomEvent} event - The boundary event with direction and source date info.
+     * @returns {void}
+     */
+    private handleMonthBoundary;
+    /**
+     * Handles cell activation events from month components.
+     * @private
+     * @param {CustomEvent} event - The activation event with target date.
+     * @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
+     * @param {Object} [options] - Optional settings.
+     * @param {boolean} [options.force=false] - When true, clears classes even
+     *   when both dateFrom and dateTo are set. Used by month nav handlers
+     *   since the subsequent re-render re-applies classMap-managed classes,
+     *   while `lastHoveredDate` (not in classMap) would otherwise persist.
+     * @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
+     * @returns {void}
+     */
+    private scrollToActiveCell;
+    /**
+     * 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
+     * @param {String|Number} timestamp - Unix timestamp in seconds.
+     * @returns {String} Localized date string.
+     */
+    private formatAnnouncementDate;
     injectSlot(slotName: any, nodes: any): void;
     render(): import("lit-html").TemplateResult;
 }