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

package/components/counter/dist/index.js

@@ -1049,7 +1049,7 @@ class AuroHelpText extends LitElement {
   }
 }
 
-var formkitVersion = '202606081518';
+var formkitVersion = '202606081904';
 
 // Copyright (c) 2026 Alaska Airlines. All rights reserved. Licensed under the Apache-2.0 license
 // See LICENSE in the project root for license information.
@@ -1787,6 +1787,14 @@ class AuroBibtemplate extends LitElement {
       large: {
         type: Boolean,
         reflect: true
+      },
+
+      /**
+       * If declared, the footer slot will be rendered even when not in fullscreen mode.
+       */
+      showFooter: {
+        type: Boolean,
+        reflect: true
       }
     };
   }
@@ -1889,7 +1897,7 @@ class AuroBibtemplate extends LitElement {
           <slot></slot>
         </div>
 
-      ${this.isFullscreen ? html`
+      ${this.isFullscreen || this.showFooter ? html`
         <div id="footerContainer">
           <slot name="footer"></slot>
         </div>` : null}

package/components/counter/dist/registered.js

@@ -1049,7 +1049,7 @@ class AuroHelpText extends LitElement {
   }
 }
 
-var formkitVersion = '202606081518';
+var formkitVersion = '202606081904';
 
 // Copyright (c) 2026 Alaska Airlines. All rights reserved. Licensed under the Apache-2.0 license
 // See LICENSE in the project root for license information.
@@ -1787,6 +1787,14 @@ class AuroBibtemplate extends LitElement {
       large: {
         type: Boolean,
         reflect: true
+      },
+
+      /**
+       * If declared, the footer slot will be rendered even when not in fullscreen mode.
+       */
+      showFooter: {
+        type: Boolean,
+        reflect: true
       }
     };
   }
@@ -1889,7 +1897,7 @@ class AuroBibtemplate extends LitElement {
           <slot></slot>
         </div>
 
-      ${this.isFullscreen ? html`
+      ${this.isFullscreen || this.showFooter ? html`
         <div id="footerContainer">
           <slot name="footer"></slot>
         </div>` : null}

package/components/datepicker/demo/accessibility.md

@@ -26,29 +26,80 @@ The clear button (shown when the input has a value) exposes:
 - Help text is associated with the component so screen readers can announce contextual guidance.
 - When validation fails, the error message is rendered with `role="alert"` and `aria-live="assertive"` to ensure it is announced immediately.
 
+<auro-header level="3" id="calendarGrid">Calendar Grid</auro-header>
+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="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="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. |
+| `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). |
+
 <auro-header level="2" id="focusManagement">Focus Management</auro-header>
 The component uses `delegatesFocus: true` on its shadow root, meaning focus is automatically delegated to the first focusable element inside the component (the date input).
 
-When the calendar bib opens on small viewports as a fullscreen modal dialog, focus is moved to the dialog's close button, giving screen reader users an immediate action to dismiss it.
+<auro-header level="3" id="ariaActivedescendant">aria-activedescendant</auro-header>
+The calendar grid uses an **`aria-activedescendant`** pattern for keyboard navigation. DOM focus remains on a wrapper element (`#calendarGrid`) while `aria-activedescendant` points to a proxy `<span>` that mirrors the active cell's ARIA attributes (`aria-label`, `aria-selected`, `aria-current`, `aria-disabled`). This approach keeps the screen reader in sync with the visually active cell without moving DOM focus on every keystroke, which prevents duplicate announcements during rapid arrow-key navigation.
+
+The active cell receives an `.activeCell` CSS class to display a visible focus ring, since the native `:focus-visible` pseudo-class applies to the grid wrapper (which holds actual DOM focus), not to individual cells.
+
+The initial active cell is determined in priority order:
+
+1. The currently selected date (if within the valid range).
+2. Today's date (if enabled).
+3. The first future enabled date.
+4. The first past enabled date.
+
+<auro-header level="3" id="focusOnOpen">Focus on Open</auro-header>
+When the calendar bib opens, focus moves to the calendar grid wrapper (`#calendarGrid`). The `aria-activedescendant` attribute points to a proxy element that carries the active date cell's label, so screen readers announce the active date. This applies to both desktop and fullscreen modes.
 
 <auro-header level="2" id="screenReaderAnnouncements">Screen Reader Announcements</auro-header>
+- **Date selection** — When a date is selected, the calendar's live region (`aria-live="assertive"`) announces the formatted date (e.g., "Wednesday, January 15, 2025"). For range datepickers, both the start and end date selections are announced.
+- **Debounced navigation announcement** — During arrow-key navigation, a debounced live region (150 ms) announces the full date context (date, slot content, range position, availability) after the user pauses. This prevents overlapping announcements during rapid navigation.
+- **Date cell labels** — Each date cell has an `aria-label` on the host element with the full localized label, including any date slot content (e.g. prices). VoiceOver reads this content instead of `aria-label`, which iOS VoiceOver does not reliably announce on buttons.
 - **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="2" id="accessibleLabels">Accessible Labels</auro-header>
-- The `fromLabel` slot content is used as the accessible name for the first date input.
+- 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.
 - The `label` slot is used as the main label when `layout="snowflake"`.
+- The `ariaLabel.bib.close` slot customizes the close button label in fullscreen mode (defaults to "Close").
+- The `ariaLabel.input.clear` slot customizes the clear button label (falls back to a localized default).
 - A label is required. Without it, assistive technology users will not have context for what the datepicker controls.
 
+<auro-header level="3" id="rangeLabels">Configurable Range Labels</auro-header>
+When `range` is set, each date cell's label includes its position relative to the selected range. These labels are configurable via attributes for localization:
+
+| Attribute | Default | Description |
+|---|---|---|
+| `rangeLabelStart` | "range start" | Announced for the range start date. |
+| `rangeLabelEnd` | "range end" | Announced for the range end date. |
+| `rangeLabelBeforeRange` | "before range" | Announced for dates before the range start. |
+| `rangeLabelInRange` | "in range" | Announced for dates within the selected range. |
+| `rangeLabelAfterRange` | "after range" | Announced for dates after the range (or after start when no end is selected). |
+
 <auro-header level="2" id="fullscreenBehavior">Fullscreen (Modal) Behavior</auro-header>
 On smaller viewports, the calendar bib opens as a fullscreen modal dialog:
 
 - The dialog is opened with `showModal()`, which provides **native focus trapping** — only elements inside the dialog are reachable via Tab.
 - Content outside the dialog is automatically made **inert** by the browser, preventing interaction with the page behind it.
-- A close button inside the dialog is focused when the modal opens, giving screen reader users an immediate action to dismiss it.
+- The trigger input is set to `inert` while the fullscreen dialog is open, preventing VoiceOver from reaching it behind the dialog.
 - Touch scrolling on the page behind the dialog is blocked to prevent the background from scrolling into view.
 
+<auro-header level="2" id="desktopModalBehavior">Desktop Modal Behavior</auro-header>
+On larger viewports, the datepicker opens as a popover with modal-like focus management:
+
+- Sibling elements of the dropdown host are set to `inert`, preventing interaction with the rest of the page while the calendar is open.
+- Tab and Shift+Tab are trapped within the bib content, wrapping focus between the first and last focusable elements.
+- Inertness and focus trapping are cleaned up when the bib closes or the component is disconnected.
+
 <auro-header level="2" id="reducedMotion">Reduced Motion</auro-header>
 The component respects the `prefers-reduced-motion` media query. When the user has requested reduced motion, scroll animations use instant scrolling instead of smooth scrolling.
 

package/components/datepicker/demo/api.md

@@ -7,58 +7,68 @@ The `auro-datepicker` component provides users with a way to select a date or da
 
 ## Properties
 
-| Property                          | Attribute                         | Modifiers | Type                                             | Default          | Description                                      |
-|-----------------------------------|-----------------------------------|-----------|--------------------------------------------------|------------------|--------------------------------------------------|
-| `appearance`                      | `appearance`                      |           | `string`                                         | "'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. |
-| `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. |
-| `calendarFocusDate`               | `calendarFocusDate`               |           | `string`                                         | "value"          | The date that will first be visually rendered to the user in the calendar. |
-| `calendarFocusDateObject`         |                                   | readonly  | `Date \| undefined`                              |                  | Read-only `Date` object derived from `calendarFocusDate`. Returns `undefined` when `calendarFocusDate` is empty or not a valid date. |
-| `calendarStartDate`               | `calendarStartDate`               |           | `string`                                         | "undefined"      | The first date that may be displayed in the calendar. |
-| `calendarStartDateObject`         |                                   | readonly  | `Date \| undefined`                              |                  | Read-only `Date` object derived from `calendarStartDate`. Returns `undefined` when `calendarStartDate` is empty or not a valid date. |
-| `centralDate`                     | `centralDate`                     |           | `string`                                         |                  | The date that determines the currently visible month. |
-| `centralDateObject`               |                                   | readonly  | `Date \| undefined`                              |                  | Read-only `Date` object derived from `centralDate`. Returns `undefined` when `centralDate` is empty or not a valid date. |
-| `disabled`                        | `disabled`                        |           | `boolean`                                        | false            | If set, disables the datepicker.                 |
-| `dvInputOnly`                     | `dvInputOnly`                     |           | `boolean`                                        | false            | If defined, the display value slot content will only mask the HTML5 input element. The input's label will not be masked. |
-| `error`                           | `error`                           |           | `string`                                         |                  | When defined, sets persistent validity to `customError` and sets the validation message to the attribute value. |
-| `format`                          | `format`                          |           | `string`                                         |                  | Specifies the date format. The default is `mm/dd/yyyy`. |
-| `fullscreenBreakpoint`            | `fullscreenBreakpoint`            |           | `'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl' \| 'disabled'` | "'sm'"           | Defines the screen size breakpoint at which the dropdown switches to fullscreen mode on mobile. `disabled` indicates a dropdown should _never_ enter fullscreen.<br /><br />When expanded, the dropdown will automatically display in fullscreen mode<br />if the screen size is equal to or smaller than the selected breakpoint. |
-| `hasError`                        |                                   | readonly  | `boolean`                                        |                  | Returns `true` when the datepicker has an active validation error. |
-| `inputmode`                       | `inputmode`                       |           | `string`                                         |                  | Exposes inputmode attribute for input.           |
-| `largeFullscreenHeadline`         | `largeFullscreenHeadline`         |           | `boolean`                                        | false            | If declared, make bib.fullscreen.headline in HeadingDisplay.<br />Otherwise, Heading 600. |
-| `layout`                          | `layout`                          |           | `'classic' \| 'snowflake'`                       | "'classic'"      | Sets the layout of the datepicker.               |
-| `locale`                          | `locale`                          |           | `string`                                         |                  | Defines the locale of the element. Used to derive the date format when `format` is not explicitly set. |
-| `maxDate`                         | `maxDate`                         |           | `string`                                         |                  | Maximum date. All dates after will be disabled.  |
-| `maxDateObject`                   |                                   | readonly  | `Date \| undefined`                              |                  | Read-only `Date` object derived from `maxDate`. Returns `undefined` when `maxDate` is empty or not a valid date. |
-| `minDate`                         | `minDate`                         |           | `string`                                         |                  | Minimum date. All dates before will be disabled. |
-| `minDateObject`                   |                                   | readonly  | `Date \| undefined`                              |                  | Read-only `Date` object derived from `minDate`. Returns `undefined` when `minDate` is empty or not a valid date. |
-| `monthNames`                      | `monthNames`                      |           | `array`                                          |                  | Names of all 12 months to render in the calendar.<br />When omitted, month names will be automatically populated from the active `locale` (falling back to `en-US`). |
-| `noFlip`                          | `noFlip`                          |           | `boolean`                                        | false            | If declared, the bib will NOT flip to an alternate position<br />when there isn't enough space in the specified `placement`. |
-| `noValidate`                      | `noValidate`                      |           | `boolean`                                        | false            | If set, disables auto-validation on blur.        |
-| `offset`                          | `offset`                          |           | `number`                                         | "0"              | Gap between the trigger element and bib.         |
-| `onDark`                          | `onDark`                          |           | `boolean`                                        | false            | DEPRECATED - use `appearance="inverse"` instead. |
-| `placeholder`                     | `placeholder`                     |           | `string`                                         |                  | Placeholder text to display in the input(s) when no value is set. |
-| `placeholderEndDate`              | `placeholderEndDate`              |           | `string`                                         |                  | Optional placeholder text to display in the second input when using date range.<br />By default, datepicker will use `placeholder` for both inputs if placeholder is<br />specified, but placeholderEndDate is not. |
-| `placement`                       | `placement`                       |           | `'top' \| 'right' \| 'bottom' \| 'left' \| 'bottom-start' \| 'top-start' \| 'top-end' \| 'right-start' \| 'right-end' \| 'bottom-end' \| 'left-start' \| 'left-end'` | "'bottom-start'" | Position where the bib should appear relative to the trigger. |
-| `range`                           | `range`                           |           | `boolean`                                        | false            | If set, turns on date range functionality in auro-calendar. |
-| `referenceDates`                  | `referenceDates`                  |           | `array`                                          |                  | Dates that the user should have for reference as part of their decision making when selecting a date.<br />This should be a JSON string array of ISO date strings (`YYYY-MM-DD`). |
-| `required`                        | `required`                        |           | `boolean`                                        | false            | Populates the `required` attribute on the input. Used for client-side validation. |
-| `setCustomValidity`               | `setCustomValidity`               |           | `string`                                         |                  | Sets a custom help text message to display for all validityStates. |
-| `setCustomValidityCustomError`    | `setCustomValidityCustomError`    |           | `string`                                         |                  | Custom help text message to display when validity = `customError`. |
-| `setCustomValidityRangeOverflow`  | `setCustomValidityRangeOverflow`  |           | `string`                                         |                  | Custom help text message to display when validity = `rangeOverflow`. |
-| `setCustomValidityRangeUnderflow` | `setCustomValidityRangeUnderflow` |           | `string`                                         |                  | Custom help text message to display when validity = `rangeUnderflow`. |
-| `setCustomValidityValueMissing`   | `setCustomValidityValueMissing`   |           | `string`                                         |                  | Custom help text message to display when validity = `valueMissing`. |
-| `shape`                           |                                   |           | `string`                                         | "classic"        |                                                  |
-| `shift`                           | `shift`                           |           | `boolean`                                        | false            | If declared, the dropdown will shift its position to avoid being cut off by the viewport. |
-| `size`                            |                                   |           | `string`                                         | "lg"             |                                                  |
-| `stacked`                         | `stacked`                         |           | `boolean`                                        | false            | Set true to make datepicker stacked style.       |
-| `validity`                        | `validity`                        |           | `string`                                         | "undefined"      | Specifies the `validityState` this element is in. |
-| `value`                           | `value`                           |           | `string`                                         | "undefined"      | Value selected for the datepicker.               |
-| `valueEnd`                        | `valueEnd`                        |           | `string`                                         | "undefined"      | Value selected for the second datepicker when using date range. |
-| `valueEndObject`                  |                                   | readonly  | `Date \| undefined`                              |                  | Read-only `Date` object derived from `valueEnd`. Returns `undefined` when `valueEnd` is empty or not a valid date. |
-| `valueObject`                     |                                   | readonly  | `Date \| undefined`                              |                  | Read-only `Date` object derived from `value`. Returns `undefined` when `value` is empty or not a valid date. |
-| `values`                          |                                   | readonly  | `string[]`                                       |                  | A convenience wrapper for `value` and `valueEnd`, uses the new Auro "array value pattern". |
+| Property                          | Attribute                         | Modifiers | Type                                             | Default                      | Description                                      |
+|-----------------------------------|-----------------------------------|-----------|--------------------------------------------------|------------------------------|--------------------------------------------------|
+| `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). |
+| `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. |
+| `calendarFocusDate`               | `calendarFocusDate`               |           | `string`                                         | "value"                      | The date that will first be visually rendered to the user in the calendar. |
+| `calendarFocusDateObject`         |                                   | readonly  | `Date \| undefined`                              |                              | Read-only `Date` object derived from `calendarFocusDate`. Returns `undefined` when `calendarFocusDate` is empty or not a valid date. |
+| `calendarGridLabel`               | `calendarGridLabel`               |           | `string`                                         | "Calendar days of the month" | Accessible label for the calendar grid containing the days of the month. |
+| `calendarStartDate`               | `calendarStartDate`               |           | `string`                                         | "undefined"                  | The first date that may be displayed in the calendar. |
+| `calendarStartDateObject`         |                                   | readonly  | `Date \| undefined`                              |                              | Read-only `Date` object derived from `calendarStartDate`. Returns `undefined` when `calendarStartDate` is empty or not a valid date. |
+| `centralDate`                     | `centralDate`                     |           | `string`                                         |                              | The date that determines the currently visible month. |
+| `centralDateObject`               |                                   | readonly  | `Date \| undefined`                              |                              | Read-only `Date` object derived from `centralDate`. Returns `undefined` when `centralDate` is empty or not a valid date. |
+| `disabled`                        | `disabled`                        |           | `boolean`                                        | false                        | If set, disables the datepicker.                 |
+| `dvInputOnly`                     | `dvInputOnly`                     |           | `boolean`                                        | false                        | If defined, the display value slot content will only mask the HTML5 input element. The input's label will not be masked. |
+| `error`                           | `error`                           |           | `string`                                         |                              | When defined, sets persistent validity to `customError` and sets the validation message to the attribute value. |
+| `format`                          | `format`                          |           | `string`                                         |                              | Specifies the date format. The default is `mm/dd/yyyy`. |
+| `fullscreenBreakpoint`            | `fullscreenBreakpoint`            |           | `'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl' \| 'disabled'` | "'sm'"                       | Defines the screen size breakpoint at which the dropdown switches to fullscreen mode on mobile. `disabled` indicates a dropdown should _never_ enter fullscreen.<br /><br />When expanded, the dropdown will automatically display in fullscreen mode<br />if the screen size is equal to or smaller than the selected breakpoint. |
+| `hasError`                        |                                   | readonly  | `boolean`                                        |                              | Returns `true` when the datepicker has an active validation error. |
+| `inputmode`                       | `inputmode`                       |           | `string`                                         |                              | Exposes inputmode attribute for input.           |
+| `largeFullscreenHeadline`         | `largeFullscreenHeadline`         |           | `boolean`                                        | false                        | If declared, make bib.fullscreen.headline in HeadingDisplay.<br />Otherwise, Heading 600. |
+| `layout`                          | `layout`                          |           | `'classic' \| 'snowflake'`                       | "'classic'"                  | Sets the layout of the datepicker.               |
+| `locale`                          | `locale`                          |           | `string`                                         |                              | Defines the locale of the element. Used to derive the date format when `format` is not explicitly set. |
+| `maxDate`                         | `maxDate`                         |           | `string`                                         |                              | Maximum date. All dates after will be disabled.  |
+| `maxDateObject`                   |                                   | readonly  | `Date \| undefined`                              |                              | Read-only `Date` object derived from `maxDate`. Returns `undefined` when `maxDate` is empty or not a valid date. |
+| `minDate`                         | `minDate`                         |           | `string`                                         |                              | Minimum date. All dates before will be disabled. |
+| `minDateObject`                   |                                   | readonly  | `Date \| undefined`                              |                              | Read-only `Date` object derived from `minDate`. Returns `undefined` when `minDate` is empty or not a valid date. |
+| `monthNames`                      | `monthNames`                      |           | `array`                                          |                              | Names of all 12 months to render in the calendar.<br />When omitted, month names will be automatically populated from the active `locale` (falling back to `en-US`). |
+| `navLabelNextMonth`               | `navLabelNextMonth`               |           | `string`                                         | "Next month"                 | Accessible label for the next month navigation button. |
+| `navLabelPrevMonth`               | `navLabelPrevMonth`               |           | `string`                                         | "Previous month"             | Accessible label for the previous month navigation button. |
+| `noFlip`                          | `noFlip`                          |           | `boolean`                                        | false                        | If declared, the bib will NOT flip to an alternate position<br />when there isn't enough space in the specified `placement`. |
+| `noValidate`                      | `noValidate`                      |           | `boolean`                                        | false                        | If set, disables auto-validation on blur.        |
+| `offset`                          | `offset`                          |           | `number`                                         | "0"                          | Gap between the trigger element and bib.         |
+| `onDark`                          | `onDark`                          |           | `boolean`                                        | false                        | DEPRECATED - use `appearance="inverse"` instead. |
+| `placeholder`                     | `placeholder`                     |           | `string`                                         |                              | Placeholder text to display in the input(s) when no value is set. |
+| `placeholderEndDate`              | `placeholderEndDate`              |           | `string`                                         |                              | Optional placeholder text to display in the second input when using date range.<br />By default, datepicker will use `placeholder` for both inputs if placeholder is<br />specified, but placeholderEndDate is not. |
+| `placement`                       | `placement`                       |           | `'top' \| 'right' \| 'bottom' \| 'left' \| 'bottom-start' \| 'top-start' \| 'top-end' \| 'right-start' \| 'right-end' \| 'bottom-end' \| 'left-start' \| 'left-end'` | "'bottom-start'"             | Position where the bib should appear relative to the trigger. |
+| `range`                           | `range`                           |           | `boolean`                                        | false                        | If set, turns on date range functionality in auro-calendar. |
+| `rangeLabelAfterRange`            | `rangeLabelAfterRange`            |           | `string`                                         | "after range"                | Label announced for cells after the range (or after start when no end is selected). |
+| `rangeLabelBeforeRange`           | `rangeLabelBeforeRange`           |           | `string`                                         | "before range"               | Label announced for cells before the range start. |
+| `rangeLabelEnd`                   | `rangeLabelEnd`                   |           | `string`                                         | "range end"                  | Label announced for the range end date cell.     |
+| `rangeLabelInRange`               | `rangeLabelInRange`               |           | `string`                                         | "in range"                   | Label announced for cells within the selected range. |
+| `rangeLabelStart`                 | `rangeLabelStart`                 |           | `string`                                         | "range start"                | Label announced for the range start date cell.   |
+| `referenceDates`                  | `referenceDates`                  |           | `array`                                          |                              | Dates that the user should have for reference as part of their decision making when selecting a date.<br />This should be a JSON string array of ISO date strings (`YYYY-MM-DD`). |
+| `required`                        | `required`                        |           | `boolean`                                        | false                        | Populates the `required` attribute on the input. Used for client-side validation. |
+| `setCustomValidity`               | `setCustomValidity`               |           | `string`                                         |                              | Sets a custom help text message to display for all validityStates. |
+| `setCustomValidityCustomError`    | `setCustomValidityCustomError`    |           | `string`                                         |                              | Custom help text message to display when validity = `customError`.<br />Also used as the validation message when a blackout date is typed into the input. |
+| `setCustomValidityRangeOverflow`  | `setCustomValidityRangeOverflow`  |           | `string`                                         |                              | Custom help text message to display when validity = `rangeOverflow`. |
+| `setCustomValidityRangeUnderflow` | `setCustomValidityRangeUnderflow` |           | `string`                                         |                              | Custom help text message to display when validity = `rangeUnderflow`. |
+| `setCustomValidityValueMissing`   | `setCustomValidityValueMissing`   |           | `string`                                         |                              | Custom help text message to display when validity = `valueMissing`. |
+| `shape`                           |                                   |           | `string`                                         | "classic"                    |                                                  |
+| `shift`                           | `shift`                           |           | `boolean`                                        | false                        | If declared, the dropdown will shift its position to avoid being cut off by the viewport. |
+| `size`                            |                                   |           | `string`                                         | "lg"                         |                                                  |
+| `stacked`                         | `stacked`                         |           | `boolean`                                        | false                        | Set true to make datepicker stacked style.       |
+| `validity`                        | `validity`                        |           | `string`                                         | "undefined"                  | Specifies the `validityState` this element is in. |
+| `value`                           | `value`                           |           | `string`                                         | "undefined"                  | Value selected for the datepicker.               |
+| `valueEnd`                        | `valueEnd`                        |           | `string`                                         | "undefined"                  | Value selected for the second datepicker when using date range. |
+| `valueEndObject`                  |                                   | readonly  | `Date \| undefined`                              |                              | Read-only `Date` object derived from `valueEnd`. Returns `undefined` when `valueEnd` is empty or not a valid date. |
+| `valueObject`                     |                                   | readonly  | `Date \| undefined`                              |                              | Read-only `Date` object derived from `value`. Returns `undefined` when `value` is empty or not a valid date. |
+| `values`                          |                                   | readonly  | `string[]`                                       |                              | A convenience wrapper for `value` and `valueEnd`, uses the new Auro "array value pattern". |
 
 ## Methods
 
@@ -82,7 +92,7 @@ The `auro-datepicker` component provides users with a way to select a date or da
 | `auroDatePicker-monthChanged`   | `CustomEvent<{ month: any; year: any; numCalendars: any; }>` | Notifies that the visible calendar month(s) have changed. |
 | `auroDatePicker-newSlotContent` | `CustomEvent<any>`                               | Notifies that new slot content has been added to the datepicker. |
 | `auroDatePicker-toggled`        | `CustomEvent<{ expanded: any; }>`                | Notifies that the calendar dropdown has been opened/closed. |
-| `auroFormElement-validated`     |                                                  | Notifies that the component value(s) have been validated. |
+| `auroFormElement-validated`     | `CustomEvent<{ validity: any; message: any; }>`  | Notifies that the component value(s) have been validated. |
 | `input`                         | `CustomEvent<any>`                               |                                                  |
 
 ## Slots

package/components/datepicker/demo/css-only.html

@@ -0,0 +1,57 @@
+<!--
+  Copyright (c) Alaska Air. All right reserved. Licensed under the Apache-2.0 license
+  See LICENSE in the project root for license information.
+
+  HTML in this document is standardized and NOT to be edited.
+  All demo code should be added/edited in ./demo/css-only.md
+
+  With the exception of adding custom elements if needed for the demo.
+
+  ----------------------- DO NOT EDIT -----------------------------
+
+-->
+
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Auro Web Component Demo | auro-datepicker | CSS only</title>
+
+    <!-- highlight.js Stylesheet -->
+    <link rel="stylesheet" type="text/css" href="https://cdn.jsdelivr.net/gh/highlightjs/cdn-release@11.9.0/build/styles/github.min.css"/>
+
+    <!-- Legacy reference is still needed to support auro-datepicker's use of legacy token values at this time -->
+    <link rel="stylesheet" type="text/css" href="https://cdn.jsdelivr.net/npm/@aurodesignsystem/design-tokens@latest/dist/legacy/auro-classic/CSSCustomProperties.css"/>
+
+    <!-- Design Token Alaska Theme -->
+    <link rel="stylesheet" type="text/css" href="https://cdn.jsdelivr.net/npm/@aurodesignsystem/design-tokens@latest/dist/themes/alaska/CSSCustomProperties--alaska.min.css"/>
+
+    <!-- Webcore Stylesheet Alaska Theme -->
+    <link rel="stylesheet" type="text/css" href="https://cdn.jsdelivr.net/npm/@aurodesignsystem/webcorestylesheets@latest/dist/bundled/themes/alaska.global.min.css" />
+
+    <!-- Demo Specific Styles -->
+    <link rel="stylesheet" type="text/css" href="./styles.min.css" />
+    <style>
+      table {
+        --ds-color-container-secondary-default: transparent;
+      }
+
+      tr:not(:last-of-type) {
+        border-bottom: 1px solid var(--ds-color-border-tertiary-default);
+      }
+    </style>
+  </head>
+  <body class="auro-markdown">
+    <main></main>
+
+    <script type="module">
+      import { renderPage } from './demo-support.min.js';
+      await renderPage('./css-only.md');
+    </script>
+
+    <!-- If additional elements are needed for the demo, add them here. -->
+    <script src="https://cdn.jsdelivr.net/npm/@aurodesignsystem/auro-header@latest/+esm" type="module"></script>
+    <script src="https://cdn.jsdelivr.net/npm/@aurodesignsystem/auro-hyperlink@latest/+esm" type="module"></script>
+  </body>
+</html>

package/components/datepicker/demo/css-only.md

@@ -0,0 +1,151 @@
+<auro-header level="1">CSS only with native date input</auro-header>
+<p>For situations where the <code>&lt;auro-datepicker&gt;</code> web component cannot be used, a native HTML <code>&lt;input type="date"&gt;</code> element can be styled with the Auro Design System tokens to approximate the visual appearance of <code>auro-datepicker</code>. Unlike <auro-hyperlink href="https://auro.alaskaair.com/components/auro/hyperlink/css-only" target="_blank">auro-hyperlink</auro-hyperlink>, <auro-hyperlink href="https://alaskaairlines.github.io/WebCoreStyleSheets/" target="_blank">Web Core Style Sheets</auro-hyperlink> does not provide a prebuilt <code>.datepicker</code> class, so the styling must be authored manually using Auro design tokens.</p>
+<auro-header level="2">Styling a native date input</auro-header>
+<p>The native date input can be reset and restyled with the Auro design tokens published by <auro-hyperlink href="https://alaskaairlines.github.io/WebCoreStyleSheets/" target="_blank">@aurodesignsystem/design-tokens</auro-hyperlink>. The pattern below replicates the size, border, and focus-state colors used by <code>auro-datepicker</code>. Note that the browser-controlled calendar UI rendered by <code>&lt;input type="date"&gt;</code> cannot be styled — only the input chrome (the field itself) responds to CSS.</p>
+<pre><code>@import "./node_modules/@aurodesignsystem/design-tokens/dist/tokens/CSSCustomProperties.css";
+​
+.datepicker {
+  appearance: none;
+  -webkit-appearance: none;
+  width: 100%;
+  height: var(--ds-size-600, 3rem);
+  padding: 0 var(--ds-size-200, 1rem);
+  border: 1px solid var(--ds-color-border-ui-default, #6e767f);
+  border-radius: var(--ds-border-radius, 4px);
+  background-color: var(--ds-color-container-primary-default, #ffffff);
+  color: var(--ds-color-text-primary-default, #1d252c);
+  font-family: var(--ds-font-family-default, sans-serif);
+  font-size: var(--ds-text-body-default-size, 1rem);
+  line-height: var(--ds-text-body-default-height, 1.5);
+  cursor: pointer;
+}
+​
+.datepicker:focus-visible {
+  outline: 2px solid var(--ds-color-border-active-default, #01426a);
+  outline-offset: 2px;
+}
+​
+.datepicker:disabled {
+  cursor: not-allowed;
+  opacity: 0.5;
+}
+​
+.datepicker:invalid {
+  border-color: var(--ds-color-border-error-default, #d50000);
+}</code></pre>
+<auro-header level="3">Basic date input</auro-header>
+<p>Apply the <code>.datepicker</code> class to a native <code>&lt;input type="date"&gt;</code> element and pair it with a <code>&lt;label&gt;</code>:</p>
+<pre><code>&lt;label&gt;
+  Departure date
+  &lt;input type="date" class="datepicker" name="departure" /&gt;
+&lt;/label&gt;</code></pre>
+<auro-header level="3">Date range using two inputs</auro-header>
+<p>HTML has no native range input, so a range must be approximated with two separate <code>&lt;input type="date"&gt;</code> elements. The <code>min</code> attribute on the second input can be used to constrain the return date to be on or after the departure date, but this coordination must be wired up with JavaScript:</p>
+<pre><code>&lt;fieldset&gt;
+  &lt;legend&gt;Travel dates&lt;/legend&gt;
+  &lt;label&gt;
+    Departure
+    &lt;input type="date" class="datepicker" name="departure" id="departure" /&gt;
+  &lt;/label&gt;
+  &lt;label&gt;
+    Return
+    &lt;input type="date" class="datepicker" name="return" id="return" /&gt;
+  &lt;/label&gt;
+&lt;/fieldset&gt;</code></pre>
+<auro-header level="2">What you lose without auro-datepicker</auro-header>
+<p>While the CSS above replicates the <strong>visual styling</strong> of the <code>auro-datepicker</code> input chrome, the following functionality built into the <code>auro-datepicker</code> web component is <strong>not available</strong> when using plain HTML:</p>
+<auro-header level="3">Accessibility</auro-header>
+<p>Native date inputs vary widely across browsers and platforms, with inconsistent screen reader announcements, keyboard behavior, and focus management. <code>auro-datepicker</code> provides full arrow-key navigation of the calendar grid, rich ARIA labels on every cell (including state like "selected", "today", "unavailable", "in range"), <code>aria-live</code> announcements when the visible month changes, support for <code>prefers-reduced-motion</code>, and managed focus when the calendar opens and closes. With a native input, all of this is delegated to the browser and often differs significantly between Chrome, Safari, and Firefox — sometimes with no keyboard navigation of the calendar grid at all.</p>
+<auro-header level="3">Date range selection</auro-header>
+<p>HTML has no native concept of a date range picker. Building one from two <code>&lt;input type="date"&gt;</code> elements requires custom logic for coordinating values, enforcing start-before-end ordering, and providing a unified visual experience. <code>auro-datepicker</code> handles this with a single <code>range</code> attribute, providing two coordinated input fields, visual range highlighting across the calendar grid, customizable ARIA labels for range positions, and automatic value coordination between the start and end dates.</p>
+<auro-header level="3">Blackout dates</auro-header>
+<p>Native date inputs have no mechanism to mark specific dates as unavailable. <code>min</code> and <code>max</code> can restrict to a contiguous range, but they cannot express "these specific dates within the range are not selectable." <code>auro-datepicker</code> supports a <code>blackoutDates</code> array of ISO date strings that are visually styled as unavailable, announced to screen readers with a customizable label, focusable but not selectable, and validated on typed input to surface a <code>customError</code> validity state.</p>
+<auro-header level="3">Custom validation</auro-header>
+<p>Native date validation is limited to <code>required</code>, <code>min</code>, and <code>max</code>, and error messages are browser-controlled. <code>auro-datepicker</code> integrates with the Auro form validation system, exposing per-constraint setters (<code>setCustomValidityValueMissing</code>, <code>setCustomValidityRangeOverflow</code>, <code>setCustomValidityRangeUnderflow</code>, <code>setCustomValidityCustomError</code>), running validation on blur, on value change, and when constraints change, dispatching <code>auroFormElement-validated</code> events, and displaying errors inline via the help text slot.</p>
+<auro-header level="3">Responsive layout</auro-header>
+<p>Native date inputs render a small, browser-controlled popup that cannot be styled or repositioned. <code>auro-datepicker</code> adapts to viewport size: on desktop the calendar appears as a positioned dropdown bib, with an optional <code>desktopModal</code> mode that traps focus and makes background content inert; on mobile it opens as a fullscreen dialog via <code>showModal()</code> with a configurable <code>fullscreenBreakpoint</code>; and on desktop range mode it can display two months side-by-side.</p>
+<auro-header level="3">Localization</auro-header>
+<p>Native <code>&lt;input type="date"&gt;</code> follows the browser's locale for display format but offers no control over month names, navigation labels, or ARIA text. <code>auro-datepicker</code> supports custom <code>monthNames</code> arrays for any language, localizable navigation labels (<code>navLabelPrevMonth</code>, <code>navLabelNextMonth</code>), localizable range position labels for screen readers, a customizable <code>blackoutLabel</code>, and a configurable date display format.</p>
+<auro-header level="3">Custom cell content</auro-header>
+<p>Native date inputs render a fixed grid of numbers, with no way to add prices, icons, or supplementary information to individual dates. <code>auro-datepicker</code> supports per-date slot content via <code>date_MM_DD_YYYY</code> slots for content rendered below each date number (e.g. flight prices) and <code>popover_MM_DD_YYYY</code> slots for content that appears on hover or focus for a specific date, enabling reference data alongside dates for decision-making.</p>
+<auro-header level="3">Design system integration</auro-header>
+<p>A native <code>&lt;input type="date"&gt;</code> cannot be styled to match a design system — shadow DOM browser controls resist CSS customization and the calendar popup is entirely outside author control. <code>auro-datepicker</code> is built with the Auro Design System, providing consistent visual language with other Auro form components, light and dark theme support (<code>appearance="default"</code> or <code>appearance="inverse"</code>), CSS custom properties and <code>::part()</code> selectors for targeted styling, and composition from versioned Auro sub-components (dropdown, input, button, icon).</p>
+<auro-header level="2">Summary</auro-header>
+<table>
+<thead>
+<tr>
+<th>Feature</th>
+<th>Native <code>&lt;input type="date"&gt;</code> with Auro tokens</th>
+<th><code>auro-datepicker</code></th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td>Design-system-aligned styling</td>
+<td>Input chrome only (author-written CSS)</td>
+<td>Built-in across input and calendar</td>
+</tr>
+<tr>
+<td>Calendar UI styling</td>
+<td>Not possible (browser-controlled)</td>
+<td>Full control via tokens and parts</td>
+</tr>
+<tr>
+<td>Keyboard navigation</td>
+<td>Browser-dependent</td>
+<td>Full arrow-key grid navigation</td>
+</tr>
+<tr>
+<td>Screen reader support</td>
+<td>Inconsistent across browsers</td>
+<td>Rich ARIA labels and live regions</td>
+</tr>
+<tr>
+<td>Date range</td>
+<td>Manual (two coordinated inputs)</td>
+<td>Built-in via <code>range</code> attribute</td>
+</tr>
+<tr>
+<td>Blackout dates</td>
+<td>Not supported</td>
+<td><code>blackoutDates</code> array with validation</td>
+</tr>
+<tr>
+<td>Custom validation messages</td>
+<td>Limited to <code>setCustomValidity()</code></td>
+<td>Per-constraint custom messages</td>
+</tr>
+<tr>
+<td>Responsive layout</td>
+<td>Fixed browser popup</td>
+<td>Desktop dropdown / mobile fullscreen</td>
+</tr>
+<tr>
+<td>Custom cell content</td>
+<td>Not supported</td>
+<td>Per-date slots and popovers</td>
+</tr>
+<tr>
+<td>Localization</td>
+<td>Browser locale only</td>
+<td>Fully configurable labels and names</td>
+</tr>
+<tr>
+<td>Dark background support</td>
+<td>Manual</td>
+<td>Yes (<code>appearance="inverse"</code>)</td>
+</tr>
+<tr>
+<td>Form validation events</td>
+<td>Not supported</td>
+<td><code>auroFormElement-validated</code></td>
+</tr>
+<tr>
+<td>Multi-brand theming</td>
+<td>Static (import-time tokens)</td>
+<td>Full (design tokens + component logic)</td>
+</tr>
+</tbody>
+</table>
+<auro-header level="2">Recommendation</auro-header>
+<p>Use <code>auro-datepicker</code> whenever possible. Fall back to a CSS-styled native <code>&lt;input type="date"&gt;</code> only in environments where custom elements are not supported or when integrating with third-party systems that require plain HTML — and be prepared to accept the browser's calendar UI as-is and to reimplement range coordination, blackout handling, custom validation messaging, and accessibility affordances yourself.</p>

package/components/datepicker/demo/customize.html

@@ -44,6 +44,8 @@
     <script type="module">
       import { renderPage } from './demo-support.min.js';
       await renderPage('./customize.md');
+      import { initExamples } from "./customize.min.js";
+      initExamples();
     </script>
 
     <!-- Component scripts -->

package/components/datepicker/demo/customize.js

@@ -0,0 +1,19 @@
+import { AuroDatePicker } from '../src/auro-datepicker.js';
+import { localizationExample } from '../apiExamples/localization.js';
+
+AuroDatePicker.register();
+
+export function initExamples(initCount) {
+  initCount = initCount || 0;
+
+  try {
+    localizationExample();
+  } catch {
+    if (initCount <= 20) {
+      // setTimeout handles issue where content is sometimes loaded after the functions get called
+      setTimeout(() => {
+        initExamples(initCount + 1);
+      }, 100);
+    }
+  }
+}