@aurodesignsystem-dev/auro-formkit 0.0.0-pr1524.1 → 0.0.0-pr1530.0

package/components/combobox/dist/index.js

@@ -4812,7 +4812,7 @@ let AuroHelpText$2 = class AuroHelpText extends LitElement {
   }
 };
 
-var formkitVersion$2 = '202607022214';
+var formkitVersion$2 = '202607021905';
 
 let AuroElement$2 = class AuroElement extends LitElement {
   static get properties() {
@@ -17694,17 +17694,14 @@ class BaseInput extends AuroElement$1 {
    * @returns {void}
    */
   notifyValueChanged() {
-    // This echoes Lit's reactive value update (and handleClickClear's
-    // programmatic clear) — it is NOT a fresh user-input event. Mark it
-    // `isProgrammatic` so consumers (e.g. auro-combobox) can distinguish
-    // it from genuine user typing and skip clobbering their own
-    // programmatic state during init-time renders.
-    const inputEvent = new Event('input', {
+    let inputEvent = null;
+
+    inputEvent = new Event('input', {
       bubbles: true,
       composed: true,
     });
-    inputEvent.isProgrammatic = true;
 
+    // Dispatched event to alert outside shadow DOM context of event firing.
     this.dispatchEvent(inputEvent);
   }
 
@@ -18417,7 +18414,7 @@ let AuroHelpText$1 = class AuroHelpText extends LitElement {
   }
 };
 
-var formkitVersion$1 = '202607022214';
+var formkitVersion$1 = '202607021905';
 
 // Copyright (c) 2025 Alaska Airlines. All right reserved. Licensed under the Apache-2.0 license
 // See LICENSE in the project root for license information.
@@ -18703,15 +18700,20 @@ class AuroInput extends BaseInput {
    * @returns {void}
    */
   checkDisplayValueSlotChange() {
-    // flatten:true resolves through auro-combobox's forwarding slot
-    // (<slot name="displayValue" slot="displayValue">) so a clone appended
-    // directly to auro-input's light DOM alongside the forwarder still
-    // counts as content. The prior nodes[0].tagName === 'SLOT' recursion
-    // discarded any siblings past the forwarder.
-    const slot = this.shadowRoot.querySelector('slot[name="displayValue"]');
-    const nodes = slot.assignedNodes({ flatten: true });
+    let nodes = this.shadowRoot.querySelector('slot[name="displayValue"]').assignedNodes();
+
+    // Handle when DisplayValue is multi-level slot content (e.g. combobox passing displayValue to input)
+    if (nodes && nodes[0] && nodes[0].tagName === 'SLOT') {
+      nodes = nodes[0].assignedNodes();
+    }
+
+    let hasContent = false;
+
+    if (nodes.length > 0) {
+      hasContent = true;
+    }
 
-    this.hasDisplayValueContent = nodes.length > 0;
+    this.hasDisplayValueContent = hasContent;
   }
 
   firstUpdated() {
@@ -19538,7 +19540,7 @@ class AuroBibtemplate extends LitElement {
   }
 }
 
-var formkitVersion = '202607022214';
+var formkitVersion = '202607021905';
 
 var styleCss$1 = css`.util_displayInline{display:inline}.util_displayInlineBlock{display:inline-block}.util_displayBlock{display:block}.util_displayFlex{display:flex}.util_displayHidden{display:none}.util_displayHiddenVisually{position:absolute;overflow:hidden;clip:rect(1px, 1px, 1px, 1px);width:1px;height:1px;padding:0;border:0}:host{display:block;text-align:left}:host [auro-dropdown]{--ds-auro-dropdown-trigger-background-color: transparent}:host #inputInBib::part(wrapper){box-shadow:none}:host #inputInBib::part(accent-left){display:none}:host([layout*=classic]) [auro-input]{width:100%}:host([layout*=classic]) [auro-input]::part(helpText){display:none}:host([layout*=classic]) #slotHolder{display:none}`;
 
@@ -20637,19 +20639,9 @@ class AuroCombobox extends AuroElement {
   /**
    * Processes hidden state of all menu options and determines if there are any available options not hidden.
    * @private
-   * @param {object} [options={}] - Optional flag bag.
-   * @param {boolean} [options.preferComboboxValue=false] - When true,
-   *   handleMenuOptions matches the selected option against `this.value`
-   *   first instead of `this.input.value`. Needed on mount and re-mount
-   *   because under `persistInput` the consumer's typedValue prop can drift
-   *   from the framework value (Svelte `{#key}` re-mount after a swap, or
-   *   SPA preselect after route change) and the old input-first match would
-   *   then pick the stale text. Only handleSlotChange passes this; typing
-   *   and clearing paths keep the input-first match so user clears aren't
-   *   undone.
    * @returns {void}
    */
-  handleMenuOptions({ preferComboboxValue = false } = {}) {
+  handleMenuOptions() {
     this.generateOptionsArray();
     this.availableOptions = [];
     // Single source of truth for the menu's filter/highlight token per call.
@@ -20670,20 +20662,7 @@ class AuroCombobox extends AuroElement {
       option.setAttribute('aria-posinset', index + 1);
     });
 
-    // On mount/re-mount (via handleSlotChange), prefer the framework-set
-    // `this.value` when it matches a menu option. Covers SPA preselect and
-    // consumer swap patterns (e.g. Svelte `{#key}` re-mount) where
-    // `this.value` is authoritative but `this.input.value` may be empty or
-    // carry stale typed text from another field. Event-driven callers do
-    // not pass the flag, otherwise user clears would be undone by
-    // re-syncing to the previous combobox.value.
-    if (preferComboboxValue &&
-        this.value &&
-        this.menu.options?.some((opt) => opt.value === this.value)) {
-      this.setMenuValue(this.value);
-      this.syncValuesAndStates();
-    } else if (this.input.value &&
-        this.menu.options?.some((opt) => opt.value === this.input.value)) {
+    if (this.input.value && this.menu.options && this.menu.options.some((opt) => opt.value === this.input.value)) {
       this.setMenuValue(this.input.value);
       this.syncValuesAndStates();
     }
@@ -21120,25 +21099,7 @@ class AuroCombobox extends AuroElement {
       this.optionActive = evt.detail;
 
       if (this.input) {
-        // setActiveDescendant runs after Lit's update finishes because the
-        // template's `.a11yActivedescendant` binding calls setAttribute on
-        // the internal <input> in auro-input.updated(), which clears the
-        // reflected ariaActiveDescendantElement property. Setting the ref
-        // synchronously here would get overwritten by that attribute write.
-        // Awaiting updateComplete lets the attribute write finish first,
-        // then the ref sticks and screen readers can cross the shadow-DOM
-        // boundary to the auro-menuoption in light DOM.
-        //
-        // The equality check covers the async gap: this.optionActive can
-        // change before the callback runs (user arrowed elsewhere, or the
-        // menu closed and cleared it to null), so we bail if the target
-        // no longer matches to avoid reinstating a stale ref.
-        const targetOption = this.optionActive;
-        this.updateComplete.then(() => {
-          if (this.input && this.optionActive === targetOption) {
-            this.input.setActiveDescendant(targetOption);
-          }
-        });
+        this.input.setActiveDescendant(this.optionActive);
       }
 
       // In fullscreen mode the menu sits inside a nested <dialog> shadow root,
@@ -21275,18 +21236,6 @@ class AuroCombobox extends AuroElement {
       }
     }
 
-    // SPA preselect guard: on init render, auro-input's notifyValueChanged
-    // echoes an empty value through as an isProgrammatic input event before
-    // the framework-set combobox.value has propagated down to the input.
-    // Without this bail, the `this.value = this.input.value` below clobbers
-    // the framework value with '' and clear() wipes optionSelected. Scoped
-    // to the exact shape of that echo (isProgrammatic + non-empty combobox
-    // value + empty input.value) so it doesn't affect the swap/typed paths
-    // where value/input already track each other through the sync helpers.
-    if (event && event.isProgrammatic && this.value && !this.input.value) {
-      return;
-    }
-
     this.value = this.input.value;
 
     // Ignore re-entrant input events caused by programmatic value sets.
@@ -21719,11 +21668,7 @@ class AuroCombobox extends AuroElement {
           }
         });
 
-        // Slot change (mount/re-mount): pass `preferComboboxValue` so that a
-        // framework-set `this.value` wins over any stale `input.value` when
-        // matching against the newly-available options. Fixes the display
-        // for SPA preselect and Svelte `{#key}` re-mount swap patterns.
-        this.handleMenuOptions({ preferComboboxValue: true });
+        this.handleMenuOptions();
 
         break;
 

package/components/combobox/dist/registered.js

@@ -4812,7 +4812,7 @@ let AuroHelpText$2 = class AuroHelpText extends LitElement {
   }
 };
 
-var formkitVersion$2 = '202607022214';
+var formkitVersion$2 = '202607021905';
 
 let AuroElement$2 = class AuroElement extends LitElement {
   static get properties() {
@@ -17694,17 +17694,14 @@ class BaseInput extends AuroElement$1 {
    * @returns {void}
    */
   notifyValueChanged() {
-    // This echoes Lit's reactive value update (and handleClickClear's
-    // programmatic clear) — it is NOT a fresh user-input event. Mark it
-    // `isProgrammatic` so consumers (e.g. auro-combobox) can distinguish
-    // it from genuine user typing and skip clobbering their own
-    // programmatic state during init-time renders.
-    const inputEvent = new Event('input', {
+    let inputEvent = null;
+
+    inputEvent = new Event('input', {
       bubbles: true,
       composed: true,
     });
-    inputEvent.isProgrammatic = true;
 
+    // Dispatched event to alert outside shadow DOM context of event firing.
     this.dispatchEvent(inputEvent);
   }
 
@@ -18417,7 +18414,7 @@ let AuroHelpText$1 = class AuroHelpText extends LitElement {
   }
 };
 
-var formkitVersion$1 = '202607022214';
+var formkitVersion$1 = '202607021905';
 
 // Copyright (c) 2025 Alaska Airlines. All right reserved. Licensed under the Apache-2.0 license
 // See LICENSE in the project root for license information.
@@ -18703,15 +18700,20 @@ class AuroInput extends BaseInput {
    * @returns {void}
    */
   checkDisplayValueSlotChange() {
-    // flatten:true resolves through auro-combobox's forwarding slot
-    // (<slot name="displayValue" slot="displayValue">) so a clone appended
-    // directly to auro-input's light DOM alongside the forwarder still
-    // counts as content. The prior nodes[0].tagName === 'SLOT' recursion
-    // discarded any siblings past the forwarder.
-    const slot = this.shadowRoot.querySelector('slot[name="displayValue"]');
-    const nodes = slot.assignedNodes({ flatten: true });
+    let nodes = this.shadowRoot.querySelector('slot[name="displayValue"]').assignedNodes();
+
+    // Handle when DisplayValue is multi-level slot content (e.g. combobox passing displayValue to input)
+    if (nodes && nodes[0] && nodes[0].tagName === 'SLOT') {
+      nodes = nodes[0].assignedNodes();
+    }
+
+    let hasContent = false;
+
+    if (nodes.length > 0) {
+      hasContent = true;
+    }
 
-    this.hasDisplayValueContent = nodes.length > 0;
+    this.hasDisplayValueContent = hasContent;
   }
 
   firstUpdated() {
@@ -19538,7 +19540,7 @@ class AuroBibtemplate extends LitElement {
   }
 }
 
-var formkitVersion = '202607022214';
+var formkitVersion = '202607021905';
 
 var styleCss$1 = css`.util_displayInline{display:inline}.util_displayInlineBlock{display:inline-block}.util_displayBlock{display:block}.util_displayFlex{display:flex}.util_displayHidden{display:none}.util_displayHiddenVisually{position:absolute;overflow:hidden;clip:rect(1px, 1px, 1px, 1px);width:1px;height:1px;padding:0;border:0}:host{display:block;text-align:left}:host [auro-dropdown]{--ds-auro-dropdown-trigger-background-color: transparent}:host #inputInBib::part(wrapper){box-shadow:none}:host #inputInBib::part(accent-left){display:none}:host([layout*=classic]) [auro-input]{width:100%}:host([layout*=classic]) [auro-input]::part(helpText){display:none}:host([layout*=classic]) #slotHolder{display:none}`;
 
@@ -20637,19 +20639,9 @@ class AuroCombobox extends AuroElement {
   /**
    * Processes hidden state of all menu options and determines if there are any available options not hidden.
    * @private
-   * @param {object} [options={}] - Optional flag bag.
-   * @param {boolean} [options.preferComboboxValue=false] - When true,
-   *   handleMenuOptions matches the selected option against `this.value`
-   *   first instead of `this.input.value`. Needed on mount and re-mount
-   *   because under `persistInput` the consumer's typedValue prop can drift
-   *   from the framework value (Svelte `{#key}` re-mount after a swap, or
-   *   SPA preselect after route change) and the old input-first match would
-   *   then pick the stale text. Only handleSlotChange passes this; typing
-   *   and clearing paths keep the input-first match so user clears aren't
-   *   undone.
    * @returns {void}
    */
-  handleMenuOptions({ preferComboboxValue = false } = {}) {
+  handleMenuOptions() {
     this.generateOptionsArray();
     this.availableOptions = [];
     // Single source of truth for the menu's filter/highlight token per call.
@@ -20670,20 +20662,7 @@ class AuroCombobox extends AuroElement {
       option.setAttribute('aria-posinset', index + 1);
     });
 
-    // On mount/re-mount (via handleSlotChange), prefer the framework-set
-    // `this.value` when it matches a menu option. Covers SPA preselect and
-    // consumer swap patterns (e.g. Svelte `{#key}` re-mount) where
-    // `this.value` is authoritative but `this.input.value` may be empty or
-    // carry stale typed text from another field. Event-driven callers do
-    // not pass the flag, otherwise user clears would be undone by
-    // re-syncing to the previous combobox.value.
-    if (preferComboboxValue &&
-        this.value &&
-        this.menu.options?.some((opt) => opt.value === this.value)) {
-      this.setMenuValue(this.value);
-      this.syncValuesAndStates();
-    } else if (this.input.value &&
-        this.menu.options?.some((opt) => opt.value === this.input.value)) {
+    if (this.input.value && this.menu.options && this.menu.options.some((opt) => opt.value === this.input.value)) {
       this.setMenuValue(this.input.value);
       this.syncValuesAndStates();
     }
@@ -21120,25 +21099,7 @@ class AuroCombobox extends AuroElement {
       this.optionActive = evt.detail;
 
       if (this.input) {
-        // setActiveDescendant runs after Lit's update finishes because the
-        // template's `.a11yActivedescendant` binding calls setAttribute on
-        // the internal <input> in auro-input.updated(), which clears the
-        // reflected ariaActiveDescendantElement property. Setting the ref
-        // synchronously here would get overwritten by that attribute write.
-        // Awaiting updateComplete lets the attribute write finish first,
-        // then the ref sticks and screen readers can cross the shadow-DOM
-        // boundary to the auro-menuoption in light DOM.
-        //
-        // The equality check covers the async gap: this.optionActive can
-        // change before the callback runs (user arrowed elsewhere, or the
-        // menu closed and cleared it to null), so we bail if the target
-        // no longer matches to avoid reinstating a stale ref.
-        const targetOption = this.optionActive;
-        this.updateComplete.then(() => {
-          if (this.input && this.optionActive === targetOption) {
-            this.input.setActiveDescendant(targetOption);
-          }
-        });
+        this.input.setActiveDescendant(this.optionActive);
       }
 
       // In fullscreen mode the menu sits inside a nested <dialog> shadow root,
@@ -21275,18 +21236,6 @@ class AuroCombobox extends AuroElement {
       }
     }
 
-    // SPA preselect guard: on init render, auro-input's notifyValueChanged
-    // echoes an empty value through as an isProgrammatic input event before
-    // the framework-set combobox.value has propagated down to the input.
-    // Without this bail, the `this.value = this.input.value` below clobbers
-    // the framework value with '' and clear() wipes optionSelected. Scoped
-    // to the exact shape of that echo (isProgrammatic + non-empty combobox
-    // value + empty input.value) so it doesn't affect the swap/typed paths
-    // where value/input already track each other through the sync helpers.
-    if (event && event.isProgrammatic && this.value && !this.input.value) {
-      return;
-    }
-
     this.value = this.input.value;
 
     // Ignore re-entrant input events caused by programmatic value sets.
@@ -21719,11 +21668,7 @@ class AuroCombobox extends AuroElement {
           }
         });
 
-        // Slot change (mount/re-mount): pass `preferComboboxValue` so that a
-        // framework-set `this.value` wins over any stale `input.value` when
-        // matching against the newly-available options. Fixes the display
-        // for SPA preselect and Svelte `{#key}` re-mount swap patterns.
-        this.handleMenuOptions({ preferComboboxValue: true });
+        this.handleMenuOptions();
 
         break;
 

package/components/counter/demo/customize.min.js

@@ -1114,7 +1114,7 @@ let AuroHelpText$1 = class AuroHelpText extends i$2 {
   }
 };
 
-var formkitVersion$1 = '202607022214';
+var formkitVersion$1 = '202607021905';
 
 // Copyright (c) 2026 Alaska Airlines. All rights reserved. Licensed under the Apache-2.0 license
 // See LICENSE in the project root for license information.
@@ -5460,7 +5460,7 @@ class AuroHelpText extends i$2 {
   }
 }
 
-var formkitVersion = '202607022214';
+var formkitVersion = '202607021905';
 
 let AuroElement$1 = class AuroElement extends i$2 {
   static get properties() {

package/components/counter/demo/index.min.js

@@ -1114,7 +1114,7 @@ let AuroHelpText$1 = class AuroHelpText extends i$2 {
   }
 };
 
-var formkitVersion$1 = '202607022214';
+var formkitVersion$1 = '202607021905';
 
 // Copyright (c) 2026 Alaska Airlines. All rights reserved. Licensed under the Apache-2.0 license
 // See LICENSE in the project root for license information.
@@ -5460,7 +5460,7 @@ class AuroHelpText extends i$2 {
   }
 }
 
-var formkitVersion = '202607022214';
+var formkitVersion = '202607021905';
 
 let AuroElement$1 = class AuroElement extends i$2 {
   static get properties() {

package/components/counter/dist/index.js

@@ -1064,7 +1064,7 @@ let AuroHelpText$1 = class AuroHelpText extends LitElement {
   }
 };
 
-var formkitVersion$1 = '202607022214';
+var formkitVersion$1 = '202607021905';
 
 // Copyright (c) 2026 Alaska Airlines. All rights reserved. Licensed under the Apache-2.0 license
 // See LICENSE in the project root for license information.
@@ -5392,7 +5392,7 @@ class AuroHelpText extends LitElement {
   }
 }
 
-var formkitVersion = '202607022214';
+var formkitVersion = '202607021905';
 
 let AuroElement$1 = class AuroElement extends LitElement {
   static get properties() {

package/components/counter/dist/registered.js

@@ -1064,7 +1064,7 @@ let AuroHelpText$1 = class AuroHelpText extends LitElement {
   }
 };
 
-var formkitVersion$1 = '202607022214';
+var formkitVersion$1 = '202607021905';
 
 // Copyright (c) 2026 Alaska Airlines. All rights reserved. Licensed under the Apache-2.0 license
 // See LICENSE in the project root for license information.
@@ -5392,7 +5392,7 @@ class AuroHelpText extends LitElement {
   }
 }
 
-var formkitVersion = '202607022214';
+var formkitVersion = '202607021905';
 
 let AuroElement$1 = class AuroElement extends LitElement {
   static get properties() {

package/components/datepicker/demo/accessibility.md

@@ -32,11 +32,11 @@ The calendar uses the WAI-ARIA grid pattern for screen reader navigation:
 | Attribute | Applied to | Description |
 |---|---|---|
 | `role="grid"` | Calendar table | Identifies the calendar as a grid. The month heading is rendered as visible text adjacent to the grid but is excluded from the accessibility tree (announcements are handled via the live region described below). |
-| `role="rowgroup"` | Body group | Groups the week rows. The day-of-week header row is `aria-hidden="true"` (see below). |
+| `role="rowgroup"` | Body group | Groups the week rows. |
 | `role="row"` | Week row | Groups each week of date cells. |
-| Day-of-week header | Day-of-week row | Rendered as visible `<abbr>` elements with the full day name in the `title` attribute, but the row is `aria-hidden="true"` since the per-cell accessible name already includes the weekday name. |
+| `role="columnheader"` | Day-of-week header | Each weekday cell in the header row exposes the abbreviated day name as visible text and the full localized day name via `aria-label` (e.g. `aria-label="Sunday"`). |
 | `role="gridcell"` | In-range date cell, active-descendant proxy | Each selectable date cell. Includes `aria-selected`, `aria-current="date"` (for today), and a visually-hidden text label. A proxy `<span>` inside the calendar grid wrapper mirrors the active cell's ARIA attributes for `aria-activedescendant`. |
-| `role="presentation"` | Out-of-range date cell | Cells outside the valid min/max range. Also receive `aria-hidden="true"` and `tabindex="-1"` to remove them from both the accessibility tree and the tab order. |
+| Out-of-range date cell | Cells outside the valid min/max range | The button uses the native `disabled` attribute (spec-compliant way to express "not actionable" on a `<button>`) and is filtered out of keyboard navigation. The host cell drops its `role` and `aria-label` so assistive tech does not browse into it — no `aria-hidden` or `role="presentation"` is applied. |
 | `aria-disabled="true"` | Blackout date cell | Cells matching the `blackout` dates list. Unlike out-of-range cells, blackout cells **remain focusable** via arrow-key navigation so screen reader users can discover them. The cell's label includes ", unavailable" to communicate that the date cannot be selected. |
 | `aria-selected` | Date cell button | `"true"` for the selected date(s), `"false"` for all other in-range cells. |
 | Accessible name | Date cell button | Provided via visually-hidden text content (not an `aria-label` attribute). Localized label built from `Intl.DateTimeFormat` (weekday, month, day, year), plus any date slot content (e.g. prices), the range position label (e.g., "range start"), and availability status (", unavailable" for blackout dates). |
@@ -66,6 +66,15 @@ When the calendar bib opens, focus moves to the calendar grid wrapper (`#calenda
 - **Validation errors** — When a validation error occurs, the error message is rendered with `role="alert"` and `aria-live="assertive"`, causing it to be announced immediately without requiring focus.
 - **Help text** — The help text content is associated with the input so that screen readers announce it as part of the element description when focused.
 
+<auro-header level="3" id="ariaLiveDeviation">Documented Deviation: `aria-live="assertive"` for Arrow-Key Navigation</auro-header>
+WCAG 2.1 SC 4.1.3 (Status Messages) generally recommends `aria-live="polite"` for non-critical status updates so screen readers don't interrupt the user. The calendar's navigation live region intentionally uses `aria-live="assertive"` instead. This is a knowing deviation, made for the following reason:
+
+- **VoiceOver behavior** — VoiceOver treats `polite` announcements as "wait until idle," and during active arrow-key traversal the screen reader is never idle. Polite announcements are silently dropped, leaving keyboard users with no feedback about which cell is now active. `assertive` is the only reliable way to communicate the newly focused date on macOS/iOS VoiceOver during navigation.
+- **Interruption mitigation** — A 150 ms debounce is applied in [`announceFocusDebounced`](../src/auro-calendar.js) so only the final cell after a burst of arrow keys is announced. Rapid navigation produces one announcement per pause, not one per keystroke, which minimizes the interruption cost of `assertive`.
+- **Scope** — The same live region is reused for date selection and month-change announcements, all of which are user-initiated and expected. It is never used for background/system-generated updates.
+
+Consumers auditing against APG or WCAG 4.1.3 should treat this as an intentional, documented trade-off between spec-preferred politeness and reliable VoiceOver support.
+
 <auro-header level="2" id="accessibleLabels">Accessible Labels</auro-header>
 - The `fromLabel` slot content is used as the accessible name for the first date input. It is also forwarded to the dropdown bib as the dialog's accessible name (`aria-labelledby`).
 - When `range` is set, the `toLabel` slot content provides the accessible name for the second date input.

package/components/datepicker/demo/api.md

@@ -11,7 +11,7 @@ The `auro-datepicker` component provides users with a way to select a date or da
 |-----------------------------------|-----------------------------------|-----------|--------------------------------------------------|--------------------------------|--------------------------------------------------|
 | `appearance`                      | `appearance`                      |           | `'default' \| 'inverse'`                         | "'default'"                    | Defines whether the component will be on lighter or darker backgrounds. |
 | `autoPlacement`                   | `autoPlacement`                   |           | `boolean`                                        | "false"                        | If declared, bib's position will be automatically calculated where to appear. |
-| `blackoutDates`                   | `blackoutDates`                   |           | `array`                                          | []                             | Array of dates that cannot be selected. Dates should be in ISO format (YYYY-MM-DD). |
+| `blackoutDates`                   | `blackoutDates`                   |           | `array`                                          | []                             | Array of dates that cannot be selected. Dates should be in ISO format (YYYY-MM-DD).<br /><br />**Immutable update required.** The datepicker treats this array as<br />immutable and memoizes a lookup Set keyed on the array's reference<br />identity — matching Lit's own reactivity semantics for array<br />properties. In-place mutations (`blackoutDates.push(...)`,<br />`blackoutDates[i] = ...`, `blackoutDates.splice(...)`) will not<br />invalidate the cache and the new entries will be silently ignored.<br />To update, reassign the property: `el.blackoutDates = [...el.blackoutDates, '2024-12-25']`. |
 | `blackoutLabel`                   | `blackoutLabel`                   |           | `string`                                         | "'unavailable'"                | Label announced for blackout (disabled but in-range) date cells. |
 | `calendarEndDate`                 | `calendarEndDate`                 |           | `string`                                         | "undefined"                    | The last date that may be displayed in the calendar. |
 | `calendarEndDateObject`           |                                   | readonly  | `Date \| undefined`                              |                                | Read-only `Date` object derived from `calendarEndDate`. Returns `undefined` when `calendarEndDate` is empty or not a valid date. |