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

package/components/datepicker/demo/accessibility.md

@@ -4,7 +4,7 @@
 <div class="scrollWrapper">
 The `auro-datepicker` component is built on top of `auro-dropdown` and `auro-input`, combining their accessibility features with a calendar interface. This page documents the ARIA semantics, screen reader announcements, and other accessibility behaviors built into the component.
 
-For keyboard interaction details, see the <a href="./keyboard-behavior.html">Keyboard Behavior</a> page.
+For keyboard interaction details, see the <auro-hyperlink href="keyboard-behavior">Keyboard Behavior</auro-hyperlink> page.
 
 <auro-header level="2" id="ariaRolesAndAttributes">ARIA Roles and Attributes</auro-header>
 <auro-header level="3" id="trigger">Trigger Input</auro-header>
@@ -32,20 +32,20 @@ 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="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. |
+| `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 | Each selectable date cell. Includes `aria-selected`, `aria-current="date"` (for today), and an `aria-label` on the host with the full localized date string. |
+| 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). |
+| Accessible name | Date cell host | Provided via `aria-label` on the cell host element (set by `updateHostAria()` on each render), with the button's inner content marked `aria-hidden="true"` so screen readers don't double-announce. 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).
 
-<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.
+<auro-header level="3" id="activeCellTracking">Active Cell Tracking</auro-header>
+The calendar tracks a single active cell across the rendered month(s). DOM focus stays on the `#calendarGrid` wrapper the entire time — arrow keys never move focus onto individual cell buttons. `setActiveCell()` imperatively marks the chosen cell (adds the `active` property on the cell host and an `.activeCell` class on its button) without a Lit re-render. Screen-reader awareness of the active cell is provided by an `aria-live` region rather than by `aria-activedescendant`, so the reader is never asked to shift its point of regard on every arrow keypress — a debounce coalesces bursts (see [Screen Reader Announcements](#screenReaderAnnouncements)).
 
 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.
 
@@ -57,7 +57,7 @@ The initial active cell is determined in priority order:
 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.
+When the calendar bib opens, focus moves to the calendar grid wrapper (`#calendarGrid`). The initial active cell is marked via `setActiveCell()`, and the `aria-live` region announces its full localized label so screen readers describe the starting position. 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.
@@ -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 reasons:
+
+- **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.
@@ -83,7 +92,8 @@ When `range` is set, each date cell's label includes its position relative to th
 | `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). |
+| `rangeLabelAfterRange` | "after range" | Announced for dates after a fully selected range. |
+| `rangeLabelEndPreview` | "previewing range end" | Announced for the focused cell while picking the range end (`dateFrom` set, `dateTo` not yet selected) so AT users know that pressing Enter would commit this cell as the range end. |
 
 <auro-header level="2" id="fullscreenBehavior">Fullscreen (Modal) Behavior</auro-header>
 On smaller viewports, the calendar bib opens as a fullscreen modal dialog:

package/components/datepicker/demo/api.md

@@ -7,68 +7,69 @@ The `auro-datepicker` component provides users with a way to select a date or da
 
 ## Properties
 
-| 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". |
+| 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).<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. |
+| `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 a fully selected range (both<br />`dateFrom` and `dateTo` are set). While a range is still being<br />picked (`dateFrom` set, `dateTo` unset), focused cells past the<br />start use `rangeLabelEndPreview` instead. |
+| `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.     |
+| `rangeLabelEndPreview`            | `rangeLabelEndPreview`            |           | `string`                                         | "'previewing range end'"       | Label announced for the focused cell while previewing a range end<br />(dateFrom set, dateTo not yet selected). Tells AT users that<br />pressing Enter would commit this cell as the range end. |
+| `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
 
@@ -109,6 +110,8 @@ The `auro-datepicker` component provides users with a way to select a date or da
 | `fromLabel`                | Defines the label content for the first input.   |
 | `helpText`                 | Defines the content of the helpText.             |
 | `label`                    | Defines the label content for the entire datepicker when `layout="snowflake"`. |
+| `optionalFromLabel`        | Overrides the "(optional)" text rendered next to the first input's label when the datepicker is not `required`. |
+| `optionalToLabel`          | Overrides the "(optional)" text rendered next to the second input's label when `range` is set and the datepicker is not `required`. |
 | `popover_YYYY_MM_DD`       | Defines the content to display in the auro-calendar-cell popover for the specified date. |
 | `toLabel`                  | Defines the label content for the second input when the `range` attribute is used. |