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 Keyboard Behavior page. ARIA Roles and Attributes Trigger Input The trigger contains one or two `` elements (depending on whether `range` is set). Each input exposes standard ARIA attributes: | Attribute | Value | Description | |---|---|---| | `aria-label` | slot text | The input receives its accessible name from the `fromLabel` or `toLabel` slot content. | | `aria-invalid` | `true` / `false` | Reflects whether the current value fails validation. | Clear Button The clear button (shown when the input has a value) exposes: | Attribute | Value | Description | |---|---|---| | `aria-label` | slot text or i18n default | Receives its accessible name from the `ariaLabel.input.clear` slot, falling back to a localized default. | Help Text and Errors - 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. Calendar Grid 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. | | `role="row"` | Week row | Groups each week of date cells. | | `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 ``) 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 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). | Focus Management 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). Active Cell Tracking 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. 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. Focus on Open 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. Screen Reader Announcements - **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. Documented Deviation: `aria-live="assertive"` for Arrow-Key Navigation 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. Accessible Labels - 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. Configurable Range Labels 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 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. | Fullscreen (Modal) Behavior 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. - 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. Desktop Modal Behavior 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. Reduced Motion 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. Form Participation The datepicker integrates with HTML forms through its internal `` elements, which render hidden native `` elements with `aria-hidden="true"`. These elements: - Participate in HTML form submissions, ensuring the selected date value(s) are included in form data. - Support the `required` and `disabled` attributes. - Are invisible and unreachable by assistive technology — all user interaction goes through the custom component.