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

package/components/datepicker/demo/keyboard-behavior.md

@@ -11,9 +11,208 @@
 <p>Each focusable element <em>(when shown)</em> participates in the browser window's default <code>tabindex</code> sequence.</p>
 <p>When the component is <code>disabled</code> it is removed from the <code>tabindex</code> sequence. VoiceOver's virtual cursor <em>(swipe navigation)</em> can still encounter the component, but standard keyboard <code>Tab</code> navigation skips it.</p>
 <div class="note">
-<p><strong>Note:</strong> The current implementation <strong>DOES</strong> support full interaction of the bib content and calendar with touch, click and VoiceOver interactions.</p>
-<p>The current implementation of the component <strong>DOES</strong> support using the keyboard to navigate the trigger and type dates via the keyboard. It <strong>DOES NOT</strong> support navigating the bib content and calendar via the keyboard. This functionality is scheduled to be added in the next major redesign of the component.</p>
+<p><strong>Note:</strong> The datepicker supports full interaction via touch, click, VoiceOver, and keyboard. The trigger input accepts typed dates, and the calendar bib supports arrow-key navigation between date cells, Enter/Space to select, and Escape to close.</p>
 </div>
+<auro-header level="3" id="keyEventsCounterGroup">Key Events</auro-header>
+<!-- AURO-GENERATED-CONTENT:START (FILE:src=./../docs/partials/keyEvents.md) -->
+<!-- The below content is automatically added from ./../docs/partials/keyEvents.md -->
+<auro-header level="3" id="keyEvents-trigger">Trigger input</auro-header>
+<table>
+<thead>
+<tr>
+<th>Key</th>
+<th>Modifier</th>
+<th>Current State</th>
+<th>Focus Element</th>
+<th>Behavior</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td>Enter</td>
+<td>-</td>
+<td>Collapsed</td>
+<td>Trigger input, <strong>NOT</strong> the input clear button</td>
+<td>Opens the calendar bib. Focus moves to the active date cell inside the calendar grid. The Enter key behavior overrides the inherited <code>auro-dropdown</code> key behavior outlined below.</td>
+</tr>
+<tr>
+<td>Space</td>
+<td>-</td>
+<td>Collapsed</td>
+<td>Trigger input, <strong>NOT</strong> the input clear button</td>
+<td>Opens the calendar bib. Focus moves to the active date cell inside the calendar grid. The Space key behavior overrides the inherited <code>auro-dropdown</code> key behavior outlined below.</td>
+</tr>
+</tbody>
+</table>
+<auro-header level="3" id="keyEvents-calendar">Calendar</auro-header>
+<table>
+<thead>
+<tr>
+<th>Key</th>
+<th>Modifier</th>
+<th>Current State</th>
+<th>Focus Element</th>
+<th>Behavior</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td rowspan="3">Enter</td>
+<td rowspan="3">-</td>
+<td rowspan="3">Expanded</td>
+<td>Previous Month Button</td>
+<td>Re-renders the calendar to show the previous month</td>
+</tr>
+<tr>
+<td>Next Month Button</td>
+<td>Re-renders the calendar to show the next month</td>
+</tr>
+<tr>
+<td>Done button</td>
+<td>Collapses the bib.</td>
+</tr>
+<tr>
+<td rowspan="3">Space</td>
+<td rowspan="3">-</td>
+<td rowspan="3">Expanded</td>
+<td>Previous Month Button</td>
+<td>Re-renders the calendar to show the previous month</td>
+</tr>
+<tr>
+<td>Next Month Button</td>
+<td>Re-renders the calendar to show the next month</td>
+</tr>
+<tr>
+<td>Done button</td>
+<td>Collapses the bib.</td>
+</tr>
+</tbody>
+</table>
+<auro-header level="3" id="keyEvents-calendarGrid">Calendar grid</auro-header>
+<p>When the calendar bib is open, one date cell is the <em>active</em> cell (roving <code>tabindex="0"</code>). All other cells have <code>tabindex="-1"</code>. Arrow keys move the active cell without wrapping — when a boundary is reached the calendar navigates to the adjacent month.</p>
+<table>
+<thead>
+<tr>
+<th>Key</th>
+<th>Modifier</th>
+<th>Current State</th>
+<th>Focus Element</th>
+<th>Behavior</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td>ArrowRight</td>
+<td>-</td>
+<td>Expanded</td>
+<td>Any date cell</td>
+<td>Moves focus to the next day. If at the end of the month, navigates to the first focusable day of the next month.</td>
+</tr>
+<tr>
+<td>ArrowLeft</td>
+<td>-</td>
+<td>Expanded</td>
+<td>Any date cell</td>
+<td>Moves focus to the previous day. If at the start of the month, navigates to the last focusable day of the previous month.</td>
+</tr>
+<tr>
+<td>ArrowDown</td>
+<td>-</td>
+<td>Expanded</td>
+<td>Any date cell</td>
+<td>Moves focus to the same day of the week in the next week (+7 days). Navigates to the next month if needed.</td>
+</tr>
+<tr>
+<td>ArrowUp</td>
+<td>-</td>
+<td>Expanded</td>
+<td>Any date cell</td>
+<td>Moves focus to the same day of the week in the previous week (−7 days). Navigates to the previous month if needed.</td>
+</tr>
+<tr>
+<td>Enter / Space</td>
+<td>-</td>
+<td>Expanded</td>
+<td>Any date cell</td>
+<td>Selects the focused date. Blackout dates receive focus but cannot be selected.</td>
+</tr>
+<tr>
+<td>Escape</td>
+<td>-</td>
+<td>Expanded</td>
+<td>Any date cell</td>
+<td>Closes the calendar bib and returns focus to the trigger input.</td>
+</tr>
+<tr>
+<td>Tab</td>
+<td>-</td>
+<td>Expanded</td>
+<td>Any date cell</td>
+<td>Moves focus to the next focusable element outside the calendar grid (e.g., month navigation buttons or the close button in fullscreen mode).</td>
+</tr>
+</tbody>
+</table>
+<!-- AURO-GENERATED-CONTENT:END -->
+<auro-header level="4" id="keyEventsDropdown">Key Events inherited from Auro-Dropdown</auro-header>
+<!-- AURO-GENERATED-CONTENT:START (FILE:src=./../../dropdown/docs/partials/keyEvents.md) -->
+<!-- The below content is automatically added from ./../../dropdown/docs/partials/keyEvents.md -->
+<table>
+<thead>
+<tr>
+<th>Key</th>
+<th>Modifier</th>
+<th>Current State</th>
+<th>Focus Element</th>
+<th>Behavior</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td rowspan="2">Enter</td>
+<td>-</td>
+<td>Collapsed</td>
+<td>
+              Trigger or any <strong>focusable</strong> element within the trigger.
+</td>
+<td>Opens the bib.</td>
+</tr>
+<tr>
+<td>-</td>
+<td>Expanded</td>
+<td>
+              Trigger or any <strong>focusable</strong> element within the trigger.
+</td>
+<td>Closes the bib.</td>
+</tr>
+<tr>
+<td>Escape</td>
+<td>-</td>
+<td>Expanded</td>
+<td>
+              Component <code>:host</code> or any <strong>focusable</strong> element within the component.
+</td>
+<td>Closes the bib.</td>
+</tr>
+<tr>
+<td rowspan="2">Space</td>
+<td>-</td>
+<td>Collapsed</td>
+<td>
+              Trigger or any <strong>focusable</strong> element within the trigger.
+</td>
+<td>Opens the bib.</td>
+</tr>
+<tr>
+<td>-</td>
+<td>Expanded</td>
+<td>
+              Trigger or any <strong>focusable</strong> element within the trigger.
+</td>
+<td>Closes the bib.</td>
+</tr>
+</tbody>
+</table>
+<!-- AURO-GENERATED-CONTENT:END -->
 </div>
 </div>
 </div>

package/components/datepicker/demo/pages.json

@@ -1 +1 @@
-["accessibility.md","api.md","customize.md","design.md","getting-started.md","index.md","keyboard-behavior.md","voiceover.md","readme.md"]
+["accessibility.md","api.md","customize.md","design.md","getting-started.md","index.md","keyboard-behavior.md","voiceover.md","why-datepicker.md","readme.md"]

package/components/datepicker/demo/voiceover.md

@@ -37,12 +37,19 @@
 <auro-header level="3" id="voiceOverClearButton">Clear Button</auro-header>
 <p>When the clear button is focused, VoiceOver announces the <code>aria-label</code> from the <code>ariaLabel.input.clear</code> slot (or the default i18n text), followed by <em>"button"</em>.</p>
 <auro-header level="3" id="voiceOverCalendarNavigation">Calendar Navigation</auro-header>
-<p>When the calendar bib is open, users can navigate calendar cells using VoiceOver gestures (swipe left/right). Each cell announces:</p>
+<p>When the calendar bib is open, users can navigate calendar cells using VoiceOver gestures (swipe left/right) or arrow keys. Each cell announces:</p>
 <ul>
-<li>The date (e.g. <em>"January 15, 2026"</em>)</li>
-<li>Whether the date is selected or within the selected range</li>
-<li>Whether the date is disabled (outside min/max bounds)</li>
-</ul>
+<li>The full localized date (e.g. <em>"Thursday, May 14, 2026"</em>)</li>
+<li>Range position when in range mode (e.g. <em>", range start"</em>, <em>", in range"</em>, <em>", before range"</em>)</li>
+<li><em>", unavailable"</em> for blackout dates (dates within the min/max range that are explicitly disabled)</li>
+<li><em>"current date"</em> for today's date (via <code>aria-current="date"</code>)</li>
+<li>Selection state: <em>"selected"</em> or not (via <code>aria-selected</code>)</li>
+</ul>
+<p>Out-of-range cells (outside min/max bounds) are completely hidden from VoiceOver with <code>aria-hidden="true"</code>.</p>
+<auro-header level="3" id="voiceOverDateSelection">Date Selection</auro-header>
+<p>When a date is selected, an <code>aria-live="assertive"</code> region announces the selected date (e.g. <em>"Thursday, May 14, 2026"</em>). For range datepickers, both the start and end selections are announced.</p>
+<auro-header level="3" id="voiceOverDialogName">Dialog Name</auro-header>
+<p>The calendar dialog receives its accessible name from the <code>fromLabel</code> slot content. VoiceOver announces the dialog as e.g. <em>"Departure date, dialog"</em> when it opens.</p>
 <auro-header level="3" id="voiceOverCloseGesture">Close Gesture</auro-header>
 <p>The calendar bib may be <strong>closed</strong> using a gesture.</p>
 <ul>
@@ -60,22 +67,22 @@
 <p>Examples: large tablet, typical size or larger desktop browser window</p>
 <ol>
 <li><strong>Focus</strong> — Tab to the datepicker input.</li>
-<li><strong>Type a date</strong> — Enter a date value directly or click/tap to open the calendar.</li>
-<li><strong>Calendar opens</strong> — The dropdown bib opens with the calendar. Navigate dates with VoiceOver gestures.</li>
-<li><strong>Select a date</strong> — Activate a calendar cell to select the date. The calendar closes and the selected date populates the input.</li>
+<li><strong>Type a date</strong> — Enter a date value directly, or press Enter/Space to open the calendar.</li>
+<li><strong>Calendar opens</strong> — Focus moves to the active date cell inside the calendar grid. Navigate dates with VoiceOver gestures (swipe) or arrow keys.</li>
+<li><strong>Select a date</strong> — 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.</li>
 </ol>
 <auro-header level="2" id="voiceOverSmallVPAnnouncements">Small Viewport Workflow</auro-header>
 <p>Examples: mobile phone, very small desktop browser window</p>
 <ol>
 <li><strong>Focus</strong> — Tab or swipe to the datepicker input.</li>
 <li>
-<strong>Open:</strong> Focus is moved to the fullscreen modal dialog <strong>Close</strong> button.
+<strong>Open:</strong> The fullscreen modal dialog opens. VoiceOver announces the dialog name (e.g. <em>"Departure date, dialog"</em>). Focus is moved to the active date cell inside the calendar grid.
 </li>
-<li><strong>Navigate dates</strong> — Swipe through calendar cells.</li>
+<li><strong>Navigate dates</strong> — Swipe through calendar cells or use arrow keys.</li>
 <li>
-<strong>Select a date:</strong> Closes the fullscreen modal dialog, the selected date populates the input.
+<strong>Select a date:</strong> The selected date is announced via a live region and populates the input. The fullscreen modal remains open so additional dates can be reviewed.
 <p>~OR~</p>
-<strong>Close without selecting:</strong> Closes the fullscreen modal dialog.
+<strong>Close:</strong> Activate the close button, press Escape, or use the VoiceOver scrub gesture to close the fullscreen modal dialog.
 </li>
 </ol>
 <auro-header level="2" id="voiceOverStates">Impact of State</auro-header>

package/components/datepicker/demo/why-datepicker.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/why-datepicker.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 | Why auro-datepicker</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('./why-datepicker.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/why-datepicker.md

@@ -0,0 +1,133 @@
+<auro-header level="1" id="overview">Why auro-datepicker?</auro-header>
+<p>The native HTML <code>&lt;input type="date"&gt;</code> element provides a minimal date-picking experience, but it falls short for the needs of a complex, accessible, and branded application. <code>auro-datepicker</code> bridges those gaps with a purpose-built component designed for real-world use.</p>
+<auro-header level="2" id="accessibility">Accessibility</auro-header>
+<p>Native date inputs vary widely across browsers and platforms, with inconsistent screen reader announcements, keyboard behavior, and focus management.</p>
+<p><code>auro-datepicker</code> provides:</p>
+<ul>
+<li><strong>Full keyboard navigation</strong> — Arrow keys move between days, months, and years. Enter and Space select a date. Escape closes the calendar. The roving <code>tabindex</code> pattern ensures only one cell is in the tab order at a time, so users can Tab past the calendar efficiently.</li>
+<li><strong>Rich ARIA semantics</strong> — Every cell is labeled with its full date, day-of-week, and contextual state (e.g. "selected", "today", "unavailable", "range start", "in range"). Screen reader users hear meaningful announcements, not just numbers.</li>
+<li><strong>Live region announcements</strong> — Month changes are announced via <code>aria-live</code> so assistive technology users know the visible month has changed.</li>
+<li><strong>Reduced motion support</strong> — Scrolling and transitions respect <code>prefers-reduced-motion</code>.</li>
+<li><strong>Focus management</strong> — Opening the calendar moves focus to the active date cell. Closing it returns focus to the trigger input. The fullscreen dialog uses <code>showModal()</code> for native inert-background behavior, while the desktop modal traps focus within the bib.</li>
+</ul>
+<p>By contrast, native <code>&lt;input type="date"&gt;</code> delegates all of this to the browser, and the result differs significantly between Chrome, Safari, and Firefox — often with no keyboard navigation of the calendar grid at all on some platforms.</p>
+<auro-header level="2" id="dateRangeSelection">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.</p>
+<p><code>auro-datepicker</code> handles this with a single <code>range</code> attribute, providing:</p>
+<ul>
+<li>Two coordinated input fields with shared calendar interaction</li>
+<li>Visual range highlighting across the calendar grid</li>
+<li>Customizable ARIA labels for range positions (start, end, in-range, before range, after range)</li>
+<li>Automatic value coordination between departure and return dates</li>
+</ul>
+<auro-header level="2" id="blackoutDates">Blackout dates</auro-header>
+<p>Native date inputs have no mechanism to mark specific dates as unavailable. <code>minDate</code> and <code>maxDate</code> can restrict to a range, but they cannot express "these specific dates within the range are not selectable."</p>
+<p><code>auro-datepicker</code> supports a <code>blackoutDates</code> array of ISO date strings. Blacked-out dates are:</p>
+<ul>
+<li>Visually styled as unavailable</li>
+<li>Announced as unavailable (with a customizable label like "sold out") to screen readers</li>
+<li>Focusable but not selectable via click or keyboard</li>
+<li>Validated on typed input — entering a blackout date triggers a <code>customError</code> validity state</li>
+</ul>
+<auro-header level="2" id="validation">Validation</auro-header>
+<p>Native date validation is limited to <code>required</code>, <code>min</code>, and <code>max</code>. Error messages are browser-controlled and cannot be customized.</p>
+<p><code>auro-datepicker</code> integrates with the Auro form validation system:</p>
+<ul>
+<li>Supports <code>required</code>, <code>minDate</code>, <code>maxDate</code>, and blackout date constraints</li>
+<li>Custom error messages for each validity state (<code>setCustomValidityValueMissing</code>, <code>setCustomValidityRangeOverflow</code>, <code>setCustomValidityRangeUnderflow</code>, <code>setCustomValidityCustomError</code>)</li>
+<li>Validation runs on blur, on value change, and when constraints change (e.g. <code>blackoutDates</code> is updated)</li>
+<li>Dispatches <code>auroFormElement-validated</code> events so parent forms can react</li>
+<li>Displays errors inline via the help text slot</li>
+</ul>
+<auro-header level="2" id="responsiveLayout">Responsive layout</auro-header>
+<p>Native date inputs render a small, browser-controlled popup that cannot be styled or repositioned.</p>
+<p><code>auro-datepicker</code> adapts to viewport size:</p>
+<ul>
+<li><strong>Desktop</strong> — Calendar appears as a positioned dropdown bib, with optional modal behavior (<code>desktopModal</code>) that traps focus and makes background content inert</li>
+<li><strong>Mobile</strong> — Calendar opens as a fullscreen dialog via <code>showModal()</code>, with a configurable breakpoint (<code>fullscreenBreakpoint</code>). The virtual keyboard stays open during the transition so users can continue typing</li>
+<li><strong>Multi-month</strong> — Desktop viewports can display two months side-by-side for range selection</li>
+</ul>
+<auro-header level="2" id="localization">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, labels, or ARIA text.</p>
+<p><code>auro-datepicker</code> supports:</p>
+<ul>
+<li>Custom <code>monthNames</code> arrays for any language</li>
+<li>Localizable navigation labels (<code>navLabelPrevMonth</code>, <code>navLabelNextMonth</code>)</li>
+<li>Localizable range position labels for screen readers</li>
+<li>Customizable <code>blackoutLabel</code> text</li>
+<li>Configurable date display format</li>
+</ul>
+<auro-header level="2" id="customCellContent">Custom cell content</auro-header>
+<p>Native date inputs render a fixed grid of numbers. There is no way to add prices, icons, or supplementary information to individual dates.</p>
+<p><code>auro-datepicker</code> supports per-date slot content:</p>
+<ul>
+<li><strong>Date slots</strong> (<code>date_MM_DD_YYYY</code>) — Add custom HTML below the date number (e.g. flight prices, availability indicators)</li>
+<li><strong>Popover slots</strong> (<code>popover_MM_DD_YYYY</code>) — Add popover content that appears on hover or focus for a specific date</li>
+<li><strong>Reference dates</strong> — Display reference data alongside dates for decision-making</li>
+</ul>
+<auro-header level="2" id="designSystemIntegration">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.</p>
+<p><code>auro-datepicker</code> is built with the Alaska Airlines Auro Design System:</p>
+<ul>
+<li>Consistent visual language with other Auro form components</li>
+<li>Light and dark theme support (<code>appearance="default"</code> or <code>appearance="inverse"</code>)</li>
+<li>CSS custom properties and <code>::part()</code> selectors for targeted styling</li>
+<li>Composed from versioned Auro sub-components (dropdown, input, button, icon) for consistency</li>
+</ul>
+<auro-header level="2" id="summary">Summary</auro-header>
+<table>
+<thead>
+<tr>
+<th>Capability</th>
+<th><code>&lt;input type="date"&gt;</code></th>
+<th><code>auro-datepicker</code></th>
+</tr>
+</thead>
+<tbody>
+<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</td>
+<td>Rich ARIA labels and live regions</td>
+</tr>
+<tr>
+<td>Date range</td>
+<td>Not supported</td>
+<td>Built-in with <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>Not supported</td>
+<td>Per-constraint custom messages</td>
+</tr>
+<tr>
+<td>Responsive layout</td>
+<td>Fixed 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>Theming</td>
+<td>Minimal / browser-dependent</td>
+<td>Full design system integration</td>
+</tr>
+</tbody>
+</table>