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

package/components/datepicker/demo/keyboard-behavior.md

@@ -33,14 +33,14 @@
 <td>-</td>
 <td>Collapsed</td>
 <td>Trigger input, <strong>NOT</strong> the input clear button</td>
-<td>Opens the calendar bib. Focus moves to the calendar grid, with <code>aria-activedescendant</code> pointing to the active date cell. The Enter key behavior overrides the inherited <code>auro-dropdown</code> key behavior outlined below.</td>
+<td>Opens the calendar bib. Focus moves to the calendar grid; the active date cell is marked imperatively and announced via the <code>aria-live</code> region. The Enter key behavior overrides the inherited <code>auro-dropdown</code> key behavior outlined below.</td>
 </tr>
 <tr>
 <td>Space</td>
 <td>-</td>
 <td>Collapsed</td>
 <td>Trigger input, <strong>NOT</strong> the input clear button</td>
-<td>Opens the calendar bib. Focus moves to the calendar grid, with <code>aria-activedescendant</code> pointing to the active date cell. The Space key behavior overrides the inherited <code>auro-dropdown</code> key behavior outlined below.</td>
+<td>Opens the calendar bib. Focus moves to the calendar grid; the active date cell is marked imperatively and announced via the <code>aria-live</code> region. The Space key behavior overrides the inherited <code>auro-dropdown</code> key behavior outlined below.</td>
 </tr>
 </tbody>
 </table>
@@ -89,7 +89,7 @@
 </tbody>
 </table>
 <auro-header level="3" id="keyEvents-calendarGrid">Calendar grid</auro-header>
-<p>When the calendar bib is open, DOM focus remains on a wrapper element (<code>#calendarGrid</code>) while <code>aria-activedescendant</code> points to a proxy element that mirrors the active cell's ARIA attributes. Arrow keys move the active cell indicator without wrapping — when a boundary is reached the calendar navigates to the adjacent month. A debounced live region announces the full date context after navigation pauses.</p>
+<p>When the calendar bib is open, DOM focus stays on the <code>#calendarGrid</code> wrapper. The active cell is tracked imperatively (an <code>active</code> property on the cell host and an <code>.activeCell</code> class on its button) — no <code>aria-activedescendant</code> or proxy element is used. Arrow keys move the active cell indicator without wrapping; when a boundary is reached the calendar navigates to the adjacent month. A debounced <code>aria-live</code> region announces the full date context after navigation pauses.</p>
 <table>
 <thead>
 <tr>

package/components/datepicker/demo/voiceover.md

@@ -37,7 +37,7 @@
 <auro-header level="3" id="voiceOverClearButton">Clear Button</auro-header>
 <p>When the clear button is focused, VoiceOver announces the <code>aria-label</code> from the <code>ariaLabel.input.clear</code> slot (or the default i18n text), followed by <em>"button"</em>.</p>
 <auro-header level="3" id="voiceOverCalendarNavigation">Calendar Navigation</auro-header>
-<p>When the calendar bib is open, DOM focus stays on the calendar grid wrapper while <code>aria-activedescendant</code> points to a proxy element that mirrors the active cell's ARIA attributes. This prevents duplicate screen reader announcements during rapid arrow-key navigation. A debounced live region (150 ms) announces the full context after the user pauses.</p>
+<p>When the calendar bib is open, DOM focus stays on the calendar grid wrapper. The active cell is tracked imperatively (an <code>active</code> property on the cell host and an <code>.activeCell</code> class on its button) and its full localized label is announced through a debounced <code>aria-live</code> region (150&nbsp;ms), so rapid arrow-key navigation produces one announcement per pause rather than one per keystroke.</p>
 <p>Users can navigate calendar cells using VoiceOver gestures (swipe left/right) or arrow keys. Each cell announces:</p>
 <ul>
 <li>The full localized date (e.g. <em>"Thursday, May 14, 2026"</em>)</li>
@@ -47,7 +47,7 @@
 <li><em>"current date"</em> for today's date (via <code>aria-current="date"</code>)</li>
 <li>Selection state: <em>"selected"</em> or not (via <code>aria-selected</code>)</li>
 </ul>
-<p>Out-of-range cells (outside min/max bounds) are completely hidden from VoiceOver with <code>aria-hidden="true"</code>.</p>
+<p>Out-of-range cells (outside min/max bounds) use the native <code>disabled</code> attribute on their button and drop <code>role</code>/<code>aria-label</code> on the host, so arrow-key navigation skips them and VoiceOver does not browse into them.</p>
 <auro-header level="3" id="voiceOverDateSelection">Date Selection</auro-header>
 <p>When a date is selected, an <code>aria-live="assertive"</code> region announces the selected date (e.g. <em>"Thursday, May 14, 2026"</em>). For range datepickers, both the start and end selections are announced.</p>
 <auro-header level="3" id="voiceOverDialogName">Dialog Name</auro-header>
@@ -70,7 +70,7 @@
 <ol>
 <li><strong>Focus</strong> — Tab to the datepicker input.</li>
 <li><strong>Type a date</strong> — Enter a date value directly, or press Enter/Space to open the calendar.</li>
-<li><strong>Calendar opens</strong> — Focus moves to the calendar grid wrapper, with <code>aria-activedescendant</code> pointing to the active date. VoiceOver announces the active date. Navigate dates with VoiceOver gestures (swipe) or arrow keys.</li>
+<li><strong>Calendar opens</strong> — Focus moves to the calendar grid wrapper. The initial active cell is marked imperatively, and the <code>aria-live</code> region announces its full localized label so VoiceOver reads the active date. Navigate dates with VoiceOver gestures (swipe) or arrow keys.</li>
 <li><strong>Select a date</strong> — Activate a calendar cell (double-tap with VoiceOver, or Enter/Space with keyboard) to select the date. The selected date is announced via a live region and populates the input. The calendar remains open; close it by pressing Escape or activating the Done button.</li>
 </ol>
 <auro-header level="2" id="voiceOverSmallVPAnnouncements">Small Viewport Workflow</auro-header>
@@ -78,7 +78,7 @@
 <ol>
 <li><strong>Focus</strong> — Tab or swipe to the datepicker input.</li>
 <li>
-<strong>Open:</strong> The fullscreen modal dialog opens. VoiceOver announces the dialog name (e.g. <em>"Departure date, dialog"</em>). Focus is moved to the calendar grid wrapper, with <code>aria-activedescendant</code> pointing to the active date.
+<strong>Open:</strong> The fullscreen modal dialog opens. VoiceOver announces the dialog name (e.g. <em>"Departure date, dialog"</em>). Focus is moved to the calendar grid wrapper, and the <code>aria-live</code> region announces the initial active date.
 </li>
 <li><strong>Navigate dates</strong> — Swipe through calendar cells or use arrow keys.</li>
 <li>

package/components/datepicker/demo/why-datepicker.md

@@ -4,11 +4,11 @@
 <p>Native date inputs vary widely across browsers and platforms, with inconsistent screen reader announcements, keyboard behavior, and focus management.</p>
 <p><code>auro-datepicker</code> provides:</p>
 <ul>
-<li><strong>Full keyboard navigation</strong> — Arrow keys move between days, months, and years. Enter and Space select a date. Escape closes the calendar. The <code>aria-activedescendant</code> pattern keeps DOM focus on the calendar grid wrapper while visually indicating the active cell, so screen readers stay in sync without duplicate announcements during rapid navigation.</li>
+<li><strong>Full keyboard navigation</strong> — Arrow keys move between days, months, and years. Enter and Space select a date. Escape closes the calendar. DOM focus stays on the calendar grid wrapper while an imperatively-tracked active cell is announced through a debounced <code>aria-live</code> region, so screen readers stay in sync without duplicate announcements during rapid navigation.</li>
 <li><strong>Rich ARIA semantics</strong> — Every cell is labeled with its full date, day-of-week, and contextual state (e.g. "selected", "today", "unavailable", "range start", "in range"). Screen reader users hear meaningful announcements, not just numbers.</li>
 <li><strong>Live region announcements</strong> — Month changes are announced via <code>aria-live</code> so assistive technology users know the visible month has changed.</li>
 <li><strong>Reduced motion support</strong> — Scrolling and transitions respect <code>prefers-reduced-motion</code>.</li>
-<li><strong>Focus management</strong> — Opening the calendar moves focus to the calendar grid wrapper, with <code>aria-activedescendant</code> pointing to the active date cell. Closing it returns focus to the trigger input. The fullscreen dialog uses <code>showModal()</code> for native inert-background behavior, while the desktop modal traps focus within the bib.</li>
+<li><strong>Focus management</strong> — Opening the calendar moves focus to the calendar grid wrapper; the initial active date cell is marked imperatively and announced via the <code>aria-live</code> region. Closing returns focus to the trigger input. The fullscreen dialog uses <code>showModal()</code> for native inert-background behavior, while the desktop modal traps focus within the bib.</li>
 </ul>
 <p>By contrast, native <code>&lt;input type="date"&gt;</code> delegates all of this to the browser, and the result differs significantly between Chrome, Safari, and Firefox — often with no keyboard navigation of the calendar grid at all on some platforms.</p>
 <auro-header level="2" id="dateRangeSelection">Date range selection</auro-header>

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,18 @@ export class AuroCalendarCell extends LitElement {
      */
     private handleSlotContent;
     firstUpdated(): void;
+    /**
+     * Wires the cell to its ancestor calendar-month and calendar (and, via
+     * the calendar, to the datepicker). Extracted from firstUpdated() so the
+     * retry loop can re-attempt without recursively invoking a Lit lifecycle
+     * method (which is outside the framework's contract).
+     * @private
+     * @returns {void}
+     */
+    private _initFromAncestors;
+    _firstUpdatedRetries: any;
+    _firstUpdatedRetryTimer: any;
+    calendar: any;
     datepicker: any;
     _slotContentHandler: (() => void) | undefined;
     _cachedButton: Element | null | undefined;
@@ -226,8 +246,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 +261,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;
@@ -265,6 +293,23 @@ export class AuroCalendarCell extends LitElement {
      * @returns {void}
      */
     clearRangePreviewClasses(): void;
+    /**
+     * Re-applies the committed-range classes (inRange / rangeDepartDate /
+     * rangeReturnDate) imperatively from the cell's current `day`,
+     * `dateFrom`, and `dateTo`. Used after month navigation flushes:
+     * classMap in `renderCellButton` tracks its own previous state, so a
+     * preceding imperative `classList.remove` (from
+     * `clearRangePreviewClasses`) leaves classMap thinking the class is
+     * still applied. On re-render with the same class-value, classMap emits
+     * no delta and the class stays missing in the DOM. Re-toggling
+     * imperatively resyncs the DOM with the committed range.
+     *
+     * Delegates to the same `isInRange` / `isDepartDate` / `isReturnDate`
+     * helpers `renderCellButton` uses, so the two code paths cannot drift
+     * (including whatever timestamp normalization those helpers apply).
+     * @returns {void}
+     */
+    applyCommittedRangeClasses(): void;
     renderCellButton(): import("lit-html").TemplateResult;
     render(): import("lit-html").TemplateResult;
 }

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.
@@ -158,6 +173,15 @@ export class AuroCalendar extends RangeDatepicker {
      * @private
      */
     private calendarRangeMonths;
+    /**
+     * @deprecated Use `auro-datepicker.blackoutDates` (an array of
+     * `YYYY-MM-DD` ISO strings) instead. This legacy array of Unix
+     * timestamps is still honored for backward compatibility but emits a
+     * one-time `console.debug` the first time a non-empty value is observed.
+     * Support will be removed in a future major release.
+     * @private
+     */
+    private _disabledDays;
     /**
      * @private
      */
@@ -219,6 +243,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 +294,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 +316,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 +333,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 +343,39 @@ 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 on **reference identity** — only when the
+     * consumer reassigns the array (`el.blackoutDates = [...]`), matching
+     * Lit's own reactivity semantics for array properties. In-place mutations
+     * on the existing array (`push`, `splice`, index assignment) will NOT
+     * invalidate the cache and the new entries will be silently ignored.
+     * Consumers must reassign to update — see the JSDoc on
+     * `auro-datepicker.blackoutDates` for the recommended pattern.
+     *
+     * A shallow-equality tier was considered but rejected: it would run
+     * O(N) work on every cell render (this method is called per-cell via
+     * `isBlackout()`) and still wouldn't catch same-length value swaps,
+     * offering a false sense of safety.
+     * @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 +408,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 +455,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.
@@ -376,12 +476,52 @@ export class AuroCalendar extends RangeDatepicker {
      * @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.
+     *   when both dateFrom and dateTo are set. Used by month nav handlers to
+     *   strip the imperative-only `lastHoveredDate` before the re-render.
+     *   The other two classes (`inRange`, `rangeDepartDate`) are classMap-
+     *   managed and get stripped as a side effect here; because classMap
+     *   remembers what it last emitted and does not diff against the actual
+     *   DOM, the following month re-render will NOT re-add them on its own.
+     *   Nav handlers must schedule `refreshCommittedRangeClasses` (via
+     *   `scheduleCommittedRangeClassRefresh`) to resync them.
      * @returns {void}
      */
     private clearRangePreview;
+    /**
+     * Re-applies the committed-range classes across every focusable cell
+     * after a month navigation. classMap in the cell tracks its own
+     * previous state: once `clearRangePreview({ force: true })` strips
+     * `inRange`/`rangeDepartDate` imperatively before the re-render,
+     * classMap's next diff sees the same class-value it emitted before and
+     * produces no delta, leaving the DOM without the classes even though a
+     * full range is committed. Re-applying imperatively resyncs the two
+     * months' cells with `dateFrom`/`dateTo`.
+     *
+     * Iterates `getAllFocusableCells()` — out-of-range cells (blocked by
+     * `min`/`max`) can never carry range classes anyway, so skipping them
+     * is correct and cheaper than a whole-grid walk.
+     *
+     * The cell's `applyCommittedRangeClasses` reuses the same
+     * `isInRange`/`isDepartDate`/`isReturnDate` helpers `renderCellButton`
+     * uses, so we don't parse dateFrom/dateTo here — the helpers already
+     * normalize their inputs (midnight-truncation, string→int) internally.
+     * @private
+     * @returns {void}
+     */
+    private refreshCommittedRangeClasses;
+    /**
+     * Schedules `refreshCommittedRangeClasses` to run after the month
+     * re-render has flushed and the cells' button caches have refreshed.
+     * Both `handlePrevMonth` and `handleNextMonth` need this exact call
+     * shape; keeping it in one place prevents them from drifting apart.
+     *
+     * Bails synchronously when a full committed range isn't set — otherwise
+     * every prev/next click in single-date mode (or before the user picks
+     * both dates in range mode) pays for an unused double-rAF hop.
+     * @private
+     * @returns {void}
+     */
+    private scheduleCommittedRangeClassRefresh;
     /**
      * Overrides the base class handler to prevent setting `this.hoveredDate`
      * as a reactive property. Instead, handles the range preview imperatively.
@@ -391,7 +531,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 +588,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
@@ -434,6 +608,10 @@ export class AuroCalendar extends RangeDatepicker {
      * 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.
+     *
+     * This is a documented deviation from WCAG 2.1 SC 4.1.3, which
+     * prefers `polite` for status messages. See the "Documented
+     * Deviation" section in components/datepicker/docs/pages/accessibility.md.
      * @private
      * @param {String} dateStr - The localized date string to announce.
      * @returns {void}