@aurodesignsystem-dev/auro-formkit 0.0.0-pr1532.1 → 0.0.0-pr1533.1

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/auro-calendar-cell.d.ts

@@ -219,6 +219,17 @@ 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;

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

@@ -173,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
      */
@@ -337,8 +346,19 @@ export class AuroCalendar extends RangeDatepicker {
     /**
      * 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.
+     *
+     * 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>}
      */
@@ -588,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}

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

@@ -54,6 +54,14 @@ export class AuroDatePicker extends AuroElement {
         };
         /**
          * Array of dates that cannot be selected. Dates should be in ISO format (YYYY-MM-DD).
+         *
+         * **Immutable update required.** The datepicker treats this array as
+         * immutable and memoizes a lookup Set keyed on the array's reference
+         * identity — matching Lit's own reactivity semantics for array
+         * properties. In-place mutations (`blackoutDates.push(...)`,
+         * `blackoutDates[i] = ...`, `blackoutDates.splice(...)`) will not
+         * invalidate the cache and the new entries will be silently ignored.
+         * To update, reassign the property: `el.blackoutDates = [...el.blackoutDates, '2024-12-25']`.
          */
         blackoutDates: {
             type: ArrayConstructor;
@@ -745,7 +753,7 @@ export class AuroDatePicker extends AuroElement {
      */
     private configureDropdown;
     dropdown: any;
-    centralDate: any;
+    _restoreFocusOnClose: boolean | undefined;
     /**
      * Binds all behavior needed to the input after rendering.
      * @private