@aurodesignsystem-dev/auro-formkit 0.0.0-pr1488.1 → 0.0.0-pr1489.0

package/components/datepicker/demo/accessibility.md

@@ -26,29 +26,77 @@ 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. `aria-labelledby` points to the month heading. |
+| `role="rowgroup"` | Header / body groups | Groups the day-of-week header row and the week rows. |
+| `role="row"` | Week row | Groups each week of date cells. |
+| `role="columnheader"` | Day-of-week header | Each day-of-week abbreviation. Rendered as an `<abbr>` element with the full day name in the `title` attribute so screen readers can announce the expanded form. |
+| `role="gridcell"` | In-range date cell | Each selectable date cell. Includes `aria-selected`, `aria-current="date"` (for today), and a visually-hidden text label. |
+| `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 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="rovingTabindex">Roving Tabindex</auro-header>
+The calendar grid uses a **roving tabindex** pattern. Only one date cell across the entire calendar has `tabindex="0"` at a time — all other cells have `tabindex="-1"`. Arrow keys move the active cell without wrapping; when a boundary is reached the calendar navigates to the adjacent month.
+
+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 active date cell inside the calendar grid. 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.
+- **Date cell labels** — Each date cell contains a visually-hidden `<span class="srOnly">` with the full localized label. 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

@@ -11,6 +11,8 @@ The `auro-datepicker` component provides users with a way to select a date or da
 |-----------------------------------|-----------------------------------|-----------|--------------------------------------------------|--------------------------------------------------|--------------------------------------------------|
 | `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. |
+| `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. |
 | `calendarFocusDate`               | `calendarFocusDate`               |           | `string`                                         | "value"                                          | The date that will first be visually rendered to the user in the calendar. |
 | `calendarStartDate`               | `calendarStartDate`               |           | `string`                                         | "undefined"                                      | The first date that may be displayed in the calendar. |
@@ -27,6 +29,8 @@ The `auro-datepicker` component provides users with a way to select a date or da
 | `maxDate`                         | `maxDate`                         |           | `string`                                         |                                                  | Maximum date. All dates after will be disabled.  |
 | `minDate`                         | `minDate`                         |           | `string`                                         |                                                  | Minimum date. All dates before will be disabled. |
 | `monthNames`                      | `monthNames`                      |           | `array`                                          | ["January","February","March","April","May","June","July","August","September","October","November","December"] | Names of all 12 months to render in the calendar, used for localization of date string in mobile layout. |
+| `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.         |
@@ -35,10 +39,15 @@ The `auro-datepicker` component provides users with a way to select a date or da
 | `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 dates in the format of `MM/DD/YYYY`. |
 | `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`. |
+| `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`. |
@@ -74,7 +83,7 @@ The `auro-datepicker` component provides users with a way to select a date or da
 | `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. |
 | `auroDatePicker-valueSet`       |                                                  | Notifies that the component has a new value set. |
-| `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`                         |                                                  |                                                  |
 
 ## Slots

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);
+    }
+  }
+}

package/components/datepicker/demo/customize.md

@@ -695,13 +695,70 @@
 </auro-accordion>
 <auro-header level="3" id="localization">Localization</auro-header>
 <p>Use the <code>centralDate</code>, locale, and related attributes to configure the datepicker for different regions and languages.</p>
+<auro-header level="4" id="rangeLabels">Screen Reader Labels</auro-header>
+<p>The following attributes customize the labels announced by screen readers when navigating the calendar. Range labels apply when the <code>range</code> attribute is set; navigation labels apply to all configurations.</p>
+<auro-table>
+<table>
+<thead>
+<tr>
+<th>Attribute</th>
+<th>Default</th>
+<th>Description</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td><code>rangeLabelStart</code></td>
+<td>"range start"</td>
+<td>Announced on the departure/start date cell.</td>
+</tr>
+<tr>
+<td><code>rangeLabelEnd</code></td>
+<td>"range end"</td>
+<td>Announced on the return/end date cell.</td>
+</tr>
+<tr>
+<td><code>rangeLabelBeforeRange</code></td>
+<td>"before range"</td>
+<td>Announced on cells before the start date.</td>
+</tr>
+<tr>
+<td><code>rangeLabelInRange</code></td>
+<td>"in range"</td>
+<td>Announced on cells between the start and end dates.</td>
+</tr>
+<tr>
+<td><code>rangeLabelAfterRange</code></td>
+<td>"after range"</td>
+<td>Announced on cells after the end date (or after start when no end is selected).</td>
+</tr>
+<tr>
+<td><code>navLabelPrevMonth</code></td>
+<td>"Previous month"</td>
+<td>Accessible label for the previous month navigation button.</td>
+</tr>
+<tr>
+<td><code>navLabelNextMonth</code></td>
+<td>"Next month"</td>
+<td>Accessible label for the next month navigation button.</td>
+</tr>
+</tbody>
+</table>
+</auro-table>
 <div class="exampleWrapper">
 <!-- AURO-GENERATED-CONTENT:START (FILE:src=./../apiExamples/localization.html) -->
 <!-- The below content is automatically added from ./../apiExamples/localization.html -->
-<auro-datepicker format="yyyy/mm/dd" id="localizationExample">
-<span slot="bib.fullscreen.headline">Localization Headline</span>
-<span slot="fromLabel">Choose a date</span>
-<span slot="bib.fullscreen.fromLabel">Choose a date</span>
+<auro-datepicker range
+  rangeLabelStart="fecha de salida"
+  rangeLabelEnd="fecha de regreso"
+  rangeLabelBeforeRange="antes de la salida"
+  rangeLabelInRange="entre vuelos"
+  rangeLabelAfterRange="después del regreso"
+  navLabelPrevMonth="Ir al mes anterior"
+  navLabelNextMonth="Ir al mes siguiente"
+  id="localizationExample">
+<span slot="fromLabel">Salida</span>
+<span slot="toLabel">Regreso</span>
 </auro-datepicker>
 <!-- AURO-GENERATED-CONTENT:END -->
 </div>
@@ -710,10 +767,17 @@
 <!-- AURO-GENERATED-CONTENT:START (CODE:src=./../apiExamples/localization.html) -->
 <!-- The below code snippet is automatically added from ./../apiExamples/localization.html -->
 
-<pre class="language-html"><code class="language-html">&lt;auro-datepicker format="yyyy/mm/dd" id="localizationExample"&gt;
-  &lt;span slot="bib.fullscreen.headline"&gt;Localization Headline&lt;/span&gt;
-  &lt;span slot="fromLabel"&gt;Choose a date&lt;/span&gt;
-  &lt;span slot="bib.fullscreen.fromLabel"&gt;Choose a date&lt;/span&gt;
+<pre class="language-html"><code class="language-html">&lt;auro-datepicker range
+  rangeLabelStart="fecha de salida"
+  rangeLabelEnd="fecha de regreso"
+  rangeLabelBeforeRange="antes de la salida"
+  rangeLabelInRange="entre vuelos"
+  rangeLabelAfterRange="después del regreso"
+  navLabelPrevMonth="Ir al mes anterior"
+  navLabelNextMonth="Ir al mes siguiente"
+  id="localizationExample"&gt;
+  &lt;span slot="fromLabel"&gt;Salida&lt;/span&gt;
+  &lt;span slot="toLabel"&gt;Regreso&lt;/span&gt;
 &lt;/auro-datepicker&gt;</code></pre>
 <!-- AURO-GENERATED-CONTENT:END -->
 </auro-accordion>