@aurodesignsystem-dev/auro-formkit 0.0.0-pr1540.0 → 0.0.0-pr1540.2

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

@@ -31,19 +31,22 @@
 <auro-header level="2" id="keyEvents">Key Events</auro-header>
 <!-- AURO-GENERATED-CONTENT:START (FILE:src=./../docs/partials/keyboard-behavior/keyEvents.md) -->
 <!-- The below content is automatically added from ./../docs/partials/keyboard-behavior/keyEvents.md -->
+<div class="note">
+<p><strong>Note:</strong> The "Focused element" column below indicates the initial <code>event.target</code> — the element that has DOM focus when the key is pressed. The select's keyboard strategy listener is attached once to the <code>&lt;auro-select&gt;</code> host; it receives events via composed bubbling regardless of display mode. When the bib is displayed as a fullscreen dialog (see <code>fullscreenBreakpoint</code>), focus moves to the dialog's close button rather than remaining on the trigger, but keydown events still bubble across the shadow-root boundary up to the host listener, and <code>aria-activedescendant</code> continues to track the active option. An "active option" is one that is not <code>disabled</code>, <code>hidden</code>, or <code>static</code> — these are always skipped during navigation and type-ahead matching.</p>
+</div>
 <table>
 <thead>
 <tr>
 <th>Key</th>
 <th>Modifier</th>
 <th>Current State</th>
-<th>Focus Element</th>
+<th>Focused element</th>
 <th>Behavior</th>
 </tr>
 </thead>
 <tbody>
 <tr>
-<td rowspan="8">ArrowDown</td>
+<td rowspan="6">ArrowDown</td>
 <td rowspan="2">-</td>
 <td>Collapsed</td>
 <td>Trigger element</td>
@@ -57,24 +60,6 @@
 </td>
 </tr>
 <tr>
-<td rowspan="2">Meta (Command / Windows key)</td>
-<td>Collapsed</td>
-<td>Trigger element</td>
-<td>
-            Opens the bib.
-<div class="note">
-<strong>Note:</strong> On Windows, <code>Meta</code> + arrow key combinations are reserved by the operating system for window management. Windows users should use <code>Control</code> or <code>Alt</code> instead.
-</div>
-</td>
-</tr>
-<tr>
-<td>Expanded</td>
-<td>Trigger element</td>
-<td>
-            Advances the <code>focused</code> option to the last enabled option in the list.
-</td>
-</tr>
-<tr>
 <td rowspan="2">Alt (Option)</td>
 <td>Collapsed</td>
 <td>Trigger element</td>
@@ -94,7 +79,7 @@
 <td>
             Opens the bib.
 <div class="note">
-<strong>Note:</strong> On macOS, <code>Control</code> + arrow key combinations are reserved by the operating system for Mission Control and Application Windows. macOS users should use <code>Meta</code> or <code>Alt</code> instead.
+<strong>Note:</strong> On macOS, <code>Control</code> + arrow key combinations are reserved by the operating system for Mission Control and Application Windows. macOS users should use <code>Alt</code> instead.
 </div>
 </td>
 </tr>
@@ -106,7 +91,7 @@
 </td>
 </tr>
 <tr>
-<td rowspan="8">ArrowUp</td>
+<td rowspan="6">ArrowUp</td>
 <td rowspan="2">-</td>
 <td>Collapsed</td>
 <td>Trigger element</td>
@@ -120,24 +105,6 @@
 </td>
 </tr>
 <tr>
-<td rowspan="2">Meta (Command / Windows key)</td>
-<td>Collapsed</td>
-<td>Trigger element</td>
-<td>
-            Opens the bib.
-<div class="note">
-<strong>Note:</strong> On Windows, <code>Meta</code> + arrow key combinations are reserved by the operating system for window management. Windows users should use <code>Control</code> or <code>Alt</code> instead.
-</div>
-</td>
-</tr>
-<tr>
-<td>Expanded</td>
-<td>Trigger element</td>
-<td>
-            Advances the <code>focused</code> option to the first enabled option in the list.
-</td>
-</tr>
-<tr>
 <td rowspan="2">Alt (Option)</td>
 <td>Collapsed</td>
 <td>Trigger element</td>
@@ -157,7 +124,7 @@
 <td>
             Opens the bib.
 <div class="note">
-<strong>Note:</strong> On macOS, <code>Control</code> + arrow key combinations are reserved by the operating system for Mission Control and Application Windows. macOS users should use <code>Meta</code> or <code>Alt</code> instead.
+<strong>Note:</strong> On macOS, <code>Control</code> + arrow key combinations are reserved by the operating system for Mission Control and Application Windows. macOS users should use <code>Alt</code> instead.
 </div>
 </td>
 </tr>
@@ -185,23 +152,47 @@
 </td>
 </tr>
 <tr>
-<td rowspan="2">Enter</td>
-<td rowspan="2">-</td>
+<td rowspan="3">Enter</td>
+<td rowspan="3">-</td>
+<td>Collapsed</td>
+<td>Trigger element</td>
+<td>Opens the bib. Bubbling is stopped so that a parent form does not treat Enter as a submit.</td>
+</tr>
+<tr>
+<td>Expanded, without <code>multiSelect</code></td>
+<td>Trigger element</td>
 <td>
-            Expanded, without <code>multiSelect</code>
+            The current <code>active</code> option is selected, and the bib closes.
 </td>
+</tr>
+<tr>
+<td>Expanded, with <code>multiSelect</code></td>
 <td>Trigger element</td>
 <td>
-            The current <code>focused</code> option is selected, closes the bib.
+            The current <code>active</code> option is toggled; the bib stays open so additional options can be selected.
 </td>
 </tr>
 <tr>
+<td rowspan="3">Escape</td>
+<td rowspan="3">-</td>
+<td>Collapsed</td>
+<td>Trigger element</td>
 <td>
-            Expanded, with <code>multiSelect</code>
+            Clears the type-ahead buffer. No other change; the event is allowed to bubble so an ancestor dialog or drawer may still handle it.
 </td>
+</tr>
+<tr>
+<td>Expanded</td>
 <td>Trigger element</td>
 <td>
-            The current <code>focused</code> option is toggled, does not close the bib.
+            Clears the type-ahead buffer and closes the bib. Bubbling is stopped so that an ancestor dialog, drawer, or popup does not also close.
+</td>
+</tr>
+<tr>
+<td>Expanded, fullscreen bib</td>
+<td>Close button</td>
+<td>
+            The Escape keydown bubbles from the close button to the select's keyboard strategy, which clears the type-ahead buffer and calls <code>dropdown.hide()</code> — the same handler as the popover case. The native <code>&lt;dialog&gt;</code> <code>cancel</code> → <code>auro-bib-cancel</code> path is a fallback that closes the bib if the strategy did not run. Focus is restored to the trigger on close.
 </td>
 </tr>
 <tr>
@@ -226,9 +217,9 @@
 <td>Expanded</td>
 <td>Trigger element</td>
 <td>
-            The current <code>focused</code> option is selected.
+            The bib closes. If there is an <code>active</code> option, it is selected first in single-select, or toggled in <code>multiSelect</code>. If no option is active, focus simply moves on without a selection change.
 <div class="note">
-<strong>Note:</strong> the page will also navigate to the next focusable element in the tabindex sequence.
+<strong>Note:</strong> <code>Tab</code> does not <code>preventDefault</code>, so the browser continues to move focus to the next element in the tabindex sequence after the selection is applied.
 </div>
 </td>
 </tr>
@@ -237,19 +228,23 @@
 <td>Expanded</td>
 <td>Trigger element</td>
 <td>
-            The current <code>focused</code> option is selected.
-<div class="note">
-<strong>Note:</strong> the page will also navigate to the previous focusable element in the tabindex sequence.
-</div>
+            Same behavior as <code>Tab</code>: the bib closes and any <code>active</code> option is selected (single-select) or toggled (<code>multiSelect</code>). The strategy does not read <code>shiftKey</code>; only the browser's own focus traversal reverses direction, moving focus to the previous element in the tabindex sequence.
 </td>
 </tr>
 <tr>
-<td>Space</td>
-<td>-</td>
-<td>Collapsed or Expanded</td>
+<td rowspan="2">Space</td>
+<td rowspan="2">-</td>
+<td>Collapsed or Expanded, type-ahead buffer active</td>
+<td>Trigger element</td>
+<td>
+            Extends the type-ahead buffer with a space character. The <code>active</code> option advances if the buffer matches an active option; the bib state is unchanged. See the <a href="customize.html#typeAhead">Type-Ahead</a> section on the Customize page.
+</td>
+</tr>
+<tr>
+<td>Collapsed or Expanded, type-ahead buffer empty</td>
 <td>Trigger element</td>
 <td>
-            When the type-ahead buffer is empty, Space behaves as documented in the inherited Space row below. While the buffer is active, Space extends the buffer instead — the <code>focused</code> option advances if the buffer matches an enabled option, and the bib state is unchanged. See the <a href="customize.html#typeAhead">Type-Ahead</a> section on the Customize page.
+            Toggles the bib — opens it when collapsed and closes it when expanded. No selection change occurs.
 </td>
 </tr>
 <tr>
@@ -258,7 +253,7 @@
 <td>Collapsed or Expanded</td>
 <td>Trigger element</td>
 <td>
-            Extends the type-ahead buffer. When the buffer matches an enabled option's displayed text, the <code>focused</code> option advances to that option and the bib opens if it was collapsed. A keystroke that does not match any option leaves the bib state unchanged. Repeated keystrokes within <code>typeaheadTimeoutMs</code> extend the buffer; pressing the same character repeatedly cycles through matching options. See the <a href="customize.html#typeAhead">Type-Ahead</a> section on the Customize page.
+            Extends the type-ahead buffer. When the buffer matches an enabled option's displayed text, the <code>focused</code> option advances to that option and the bib opens if it was collapsed. A keystroke that does not match any option leaves the bib state unchanged. Repeated keystrokes within <code>typeaheadTimeoutMs</code> (default 500&nbsp;ms) extend the buffer; pressing the same character repeatedly cycles through matching options. Keys chorded with <code>Ctrl</code>, <code>Meta</code>, or <code>Alt</code> are ignored so browser and OS shortcuts do not leak into the buffer. See the <a href="customize.html#typeAhead">Type-Ahead</a> section on the Customize page.
 </td>
 </tr>
 </tbody>

package/components/select/demo/voiceover.md

@@ -27,7 +27,7 @@
 </tr>
 <tr>
 <td>Invalid</td>
-<td><em>"invalid data"</em></td>
+<td>The trigger itself does not carry <code>aria-invalid</code>; the invalid state is announced through the alert-role Help Text (see <a href="#voiceOverStateInvalid">Invalid</a> below), not as a state hint on focus.</td>
 </tr>
 <tr>
 <td>Disabled</td>
@@ -95,7 +95,7 @@
 <p>Key characteristics across both platforms:</p>
 <ul>
 <li>The <code>label</code> is always read first.</li>
-<li>The component <strong>role</strong> is announced as <em>"pop-up button"</em> (macOS) or <em>"button"</em> (iOS).</li>
+<li>The trigger <strong>role</strong> is announced as <em>"combo box"</em> in both single-select and multi-select modes. The role does not change between large and small viewports — the fullscreen dialog on mobile wraps the same trigger, it does not remap the trigger's role to <em>"pop-up button"</em>, <em>"button"</em>, or <em>"list box"</em>. In multi-select mode, <code>aria-multiselectable="true"</code> is applied to the internal <code>&lt;auro-menu&gt;</code> (the listbox), not to the trigger.</li>
 <li><code>disabled</code> options are announced as <em>"dimmed"</em> and cannot be selected.</li>
 </ul>
 <auro-header level="2" id="voiceOverStates">Impact of State</auro-header>
@@ -116,7 +116,7 @@
 <li><strong>Focus</strong></li>
 <li><strong>Open | Expand</strong></li>
 <li><strong>Navigate Options:</strong> Moves through options; announces each option name plus <em>"selected"</em> or nothing.</li>
-<li><strong>Selecting an option:</strong> Double-tap toggles the focused option's selection — announces <em>"selected"</em> or <em>"unselected"</em>.</li>
+<li><strong>Selecting an option:</strong> Double-tap toggles the focused option's selection — announces <em>"selected"</em> or <em>"not selected"</em>.</li>
 <li><strong>Close | Collapse:</strong> Collapses the list, announces the expanded state change.</li>
 </ol>
 <auro-header level="4" id="voiceOverStateMultiSelectSmallVP">Small Viewport Multi-select</auro-header>
@@ -125,7 +125,7 @@
 <li><strong>Focus</strong></li>
 <li><strong>Open | Expand</strong></li>
 <li><strong>Navigate Options:</strong> Moves through options; announces each option name plus <em>"selected"</em> or nothing.</li>
-<li><strong>Selecting an option:</strong> Double-tap toggles the focused option's selection — announces <em>"selected"</em> or <em>"unselected"</em>.</li>
+<li><strong>Selecting an option:</strong> Double-tap toggles the focused option's selection — announces <em>"selected"</em> or <em>"not selected"</em>.</li>
 <li><strong>Close | Collapse:</strong> Collapses the list, announces the expanded state change.</li>
 </ol>
 <p>Key differences from single-select:</p>
@@ -139,9 +139,9 @@
 </thead>
 <tbody>
 <tr>
-<td>Role</td>
-<td>pop-up button</td>
-<td>list box</td>
+<td>Trigger role</td>
+<td>combo box</td>
+<td>combo box (with <code>aria-multiselectable="true"</code> on the internal listbox)</td>
 </tr>
 <tr>
 <td>Interaction model</td>
@@ -153,31 +153,44 @@
 <td>
 <p>Current selected value</p>
 <div class="note">
-<strong>On focus:</strong> Announces "[component label], [current value or 'no selection'], pop-up button"
+<strong>On focus:</strong> Announces "[component label], [current value or 'no selection'], combo box"
 </div>
 </td>
 <td>
 <p>Each option's selected state individually</p>
 <div class="note">
-<strong>On focus:</strong> Announces "[component label], [[{option label, 'selected'}, {option label, 'selected'}] or 'no selection'], list box"
+<strong>On focus:</strong> Announces "[component label], [[{option label, 'selected'}, {option label, 'selected'}] or 'no selection'], combo box"
 </div>
 <div class="note">
-<strong>On selection change:</strong> Announces "[option label], ['selected' | 'unselected']"
+<strong>On selection change:</strong> Announces "[option label], ['selected' | 'not selected']"
 </div>
 </td>
 </tr>
 <tr>
 <td>Space key</td>
 <td>Opens/closes picker</td>
-<td>Toggles selection</td>
+<td>Opens/closes picker — <strong>Enter</strong> toggles the active option's selection. Space does not toggle selection in multi-select.</td>
 </tr>
 </tbody>
 </table>
 <div class="note"><strong>Important caveat:</strong> Multi-select is notoriously difficult for all users, including screen reader users — WCAG and usability research generally recommend avoiding <code>&lt;auro-select multiSelect&gt;</code> in favor of checkboxes or other patterns that make multi-selection more discoverable.</div>
 <auro-header level="3" id="voiceOverStateInvalid">Invalid</auro-header>
-<p>When an <code>&lt;auro-select&gt;</code> is invalid the following occurs:</p>
+<p>When an <code>&lt;auro-select&gt;</code> becomes invalid the following occurs:</p>
 <ul>
-<li><code>Focus</code> — VoiceOver announces <em>"invalid data"</em> (macOS) or <em>"invalid entry"</em> (iOS) after the element's label.</li>
-<li>The Help Text will render the error message and it will be included in the VoiceOver focus announcement.</li>
+<li>The Help Text region renders the error message with <code>role="alert"</code> and <code>aria-live="assertive"</code>, so VoiceOver announces the error message immediately when the state transitions to invalid — the announcement does not wait for the next focus.</li>
+<li>On subsequent focus of the trigger, the help text's error content is read as part of the description, following the label / value / role announcement.</li>
 </ul>
-<p>Example: when focusing on an invalid <code>&lt;auro-select&gt;</code> the VoiceOver announces something like <em>"Country, invalid data, combo box, Please select a country"</em>.</p>
+<div class="note"><strong>Note:</strong> the trigger itself does not set <code>aria-invalid</code>, so VoiceOver does not include the words <em>"invalid data"</em> (macOS) or <em>"invalid entry"</em> (iOS) as part of the trigger's own announcement. The invalid state is conveyed entirely through the alert-role help text.</div>
+<p>Example: when the select becomes invalid, VoiceOver announces the error message (e.g., <em>"Please select a country"</em>) via the assertive alert. On the next focus of the trigger, VoiceOver announces something like <em>"Country, no selection, combo box, Please select a country"</em>.</p>
+<auro-header level="2" id="voiceOverImplementation">How the Announcements Are Wired</auro-header>
+<p>The following implementation details are relevant when debugging or verifying VoiceOver behavior in <code>&lt;auro-select&gt;</code>:</p>
+<auro-header level="3" id="voiceOverImplActiveDescendant">Active option (aria-activedescendant)</auro-header>
+<p>Focus remains on the trigger while the bib is open; the currently active option is exposed via <code>aria-activedescendant</code>. Because the trigger and the option live in different shadow roots, the code sets <code>trigger.ariaActiveDescendantElement</code> (the IDL/property form) rather than the string attribute alone — this is what allows VoiceOver to announce the active option's label and state across the shadow boundary.</p>
+<auro-header level="3" id="voiceOverImplSetSize">Position in list (aria-setsize / aria-posinset)</auro-header>
+<p>Each option is stamped with <code>aria-setsize</code> (total count of navigable options) and <code>aria-posinset</code> (its 1-based position). Stamping runs on initial menu configuration and again whenever <code>auroMenu-optionsChange</code> fires (options added, removed, or otherwise re-initialized), so VoiceOver's <em>"N of M"</em> announcement stays accurate across dynamic option lists. A pure <code>value</code> change does not re-stamp on its own — it only updates selection state — unless it triggers a menu re-initialization in an empty/deferred-match path.</p>
+<auro-header level="3" id="voiceOverImplLiveRegion">Live region routing</auro-header>
+<p>Selection-change announcements (single-select confirmation and multi-select toggle wording) are written into an <code>aria-live="polite"</code> span that lives in the host component's shadow root by default. In fullscreen mode the trigger becomes <code>inert</code> and everything outside the <code>&lt;dialog&gt;</code> is hidden from assistive tech — so the live region is routed into the bib's shadow root instead, ensuring the announcement is reachable while the dialog is open.</p>
+<auro-header level="3" id="voiceOverImplDebounce">Announcement timing</auro-header>
+<p>Selection announcements are delayed briefly (~300ms) so the option's <em>"selected"</em> / <em>"not selected"</em> announcement is not overridden by the <em>"collapsed"</em> announcement that follows when the bib closes.</p>
+<auro-header level="3" id="voiceOverImplFullscreen">Fullscreen focus and inert</auro-header>
+<p>When the fullscreen dialog opens, focus moves to the dialog's <strong>Close</strong> button and the trigger is marked <code>inert</code> so screen readers cannot reach it — the user is effectively inside the dialog until it closes, at which point focus returns to the trigger and <code>inert</code> is removed.</p>

package/components/select/dist/auro-select.d.ts

@@ -266,7 +266,7 @@ export class AuroSelect extends AuroElement {
             reflect: boolean;
         };
         /**
-         * Value selected for the component.
+         * Value selected for the component. When set programmatically or as a preset attribute, the value must match a selectable option. If it matches an option marked `disabled` or `static`, the selection is rejected: `value` is cleared to `undefined` while `optionSelected` is cleared to `undefined` in single-select or `[]` in multiSelect. `hidden` options remain selectable by value.
          */
         value: {
             type: StringConstructor;
@@ -529,7 +529,11 @@ export class AuroSelect extends AuroElement {
      */
     private clearSelection;
     firstUpdated(): void;
-    setMenuValue(value: any): void;
+    /**
+     * Sets the selected value by matching it against the menu options. Options marked `disabled` or `static` are not selectable: if the value matches one, the selection is rejected and `value` is cleared to `undefined` while `optionSelected` is cleared to `undefined` in single-select or `[]` in multiSelect. `hidden` options remain selectable.
+     * @param {string} value - The value to match against the menu options.
+     */
+    setMenuValue(value: string): void;
     /**
      * Scrolls the currently active option into view.
      * Respects user's motion preferences for accessibility.