This page documents the VoiceOver experience when using the <auro-datepicker> component. It covers announcements, gestures, and workflows for both large and small viewports.

When focus is given to the datepicker trigger input the following is announced:

1. Label: fromLabel slot content (e.g. "Choose a date")
2. Current value: [current date value or empty]
3. Role: "text field"
4. State hints:

   State	What gets announced
   Required	"required"
   Invalid	"invalid data"
   Disabled	"dimmed"

5. Additional description: helptext slot content if present (after a brief pause)

When the clear button is focused, VoiceOver announces the aria-label from the ariaLabel.input.clear slot (or the default i18n text), followed by "button".

When the calendar bib is open, DOM focus stays on the calendar grid wrapper. The active cell is tracked imperatively (an active property on the cell host and an .activeCell class on its button) and its full localized label is announced through a debounced aria-live region (150 ms), so rapid arrow-key navigation produces one announcement per pause rather than one per keystroke.

Users can navigate calendar cells using VoiceOver gestures (swipe left/right) or arrow keys. Each cell announces:

• The full localized date (e.g. "Thursday, May 14, 2026")
• Date slot content when present (e.g. prices)
• Range position when in range mode (e.g. ", range start", ", in range", ", before range")
• ", unavailable" for blackout dates (dates within the min/max range that are explicitly disabled)
• "current date" for today's date (via aria-current="date")
• Selection state: "selected" or not (via aria-selected)

Out-of-range cells (outside min/max bounds) use the native disabled attribute on their button and drop role/aria-label on the host, so arrow-key navigation skips them and VoiceOver does not browse into them.

When a date is selected, an aria-live="assertive" region announces the selected date (e.g. "Thursday, May 14, 2026"). For range datepickers, both the start and end selections are announced.

The calendar dialog receives its accessible name from the fromLabel slot content. VoiceOver announces the dialog as e.g. "Departure date, dialog" when it opens.

The calendar bib may be closed using a gesture.

• iOS VoiceOver: The two-finger "scrub" (zigzag / a "Z" shape) gesture acts as the 'Escape' key, commonly used to dismiss modal views.
• Android TalkBack: users typically swipe down then left (an "L" gesture) or use the back gesture to go back/close.
  
  How to Perform Android back/close gesture: Swipe inwards from either the left or right edge of the screen, typically from the middle-edge, to go to the previous screen.

When the component is invalid, the error message is rendered with role="alert" and aria-live="assertive". VoiceOver will immediately announce the error message when it appears.

Examples: large tablet, typical size or larger desktop browser window

1. Focus — Tab to the datepicker input.
2. Type a date — Enter a date value directly, or press Enter/Space to open the calendar.
3. Calendar opens — Focus moves to the calendar grid wrapper. The initial active cell is marked imperatively, and the aria-live region announces its full localized label so VoiceOver reads the active date. Navigate dates with VoiceOver gestures (swipe) or arrow keys.
4. Select a date — Activate a calendar cell (double-tap with VoiceOver, or Enter/Space with keyboard) to select the date. The selected date is announced via a live region and populates the input. The calendar remains open; close it by pressing Escape or activating the Done button.

Examples: mobile phone, very small desktop browser window

1. Focus — Tab or swipe to the datepicker input.
2. Open: The fullscreen modal dialog opens. VoiceOver announces the dialog name (e.g. "Departure date, dialog"). Focus is moved to the calendar grid wrapper, and the aria-live region announces the initial active date.
3. Navigate dates — Swipe through calendar cells or use arrow keys.
4. Select a date: The selected date is announced via a live region and populates the input. The fullscreen modal remains open so additional dates can be reviewed.

   ~OR~

   Close: Activate the close button, press Escape, or use the VoiceOver scrub gesture to close the fullscreen modal dialog.

What VoiceOver does:

• Focuses the element and announces it (e.g., "[label], dimmed, text field" on macOS / "[label], dimmed" on iOS).
• The word "dimmed" is VoiceOver's way of indicating disabled.
• The element remains in the focus order (Tab still reaches it).
• The user cannot interact with it — the calendar can not be opened, and no date can be entered.

Key distinction from aria-hidden: A disabled element is reachable but not operable. If you want VoiceOver to skip it entirely, you would need aria-hidden="true" or tabindex="-1", but that is generally not recommended for disabled controls — users benefit from knowing the field exists and why it may be unavailable.

This is consistent across NVDA and JAWS as well, though the announcement wording differs (e.g., NVDA says "unavailable").

When an <auro-datepicker> is invalid the following occurs:

• Focus — VoiceOver announces "invalid data" (macOS) or "invalid entry" (iOS) after the element's label.
• The Help Text will render the error message and it will be included in the VoiceOver focus announcement.

Example: when focusing on an invalid <auro-datepicker> the VoiceOver announces something like "Choose a date, invalid data, text field, Please select a valid date".