@astryxdesign/core 0.7.5 → 0.7.6-canary.0bd3b37

package/src/Typeahead/BaseTypeahead.spec.md

@@ -77,34 +77,34 @@ Consumer migration instructions belong in consumer docs and release notes.
 
 ## Public concepts
 
-| Concept         | Closed values or states                  | Meaning                                                      | Availability by state      | Default                          | Owner                        | Stability | Invalid-value behavior                                                                   |
-| --------------- | ---------------------------------------- | ------------------------------------------------------------ | -------------------------- | -------------------------------- | ---------------------------- | --------- | ---------------------------------------------------------------------------------------- |
-| selection       | `T` or `null`                            | Caller-controlled selected result                            | all states                 | required                         | `component:BaseTypeahead`    | released  | caller retains control                                                                   |
-| search source   | `search`, `bootstrap`, optional `cancel` | Supplies query and focus results                             | enabled input              | required                         | `component:BaseTypeahead`    | released  | rejected work clears current results                                                     |
-| focus bootstrap | on or off                                | Offers bootstrap results before query input                  | empty focused input        | off                              | `component:BaseTypeahead`    | released  | off keeps the menu closed                                                                |
-| query threshold | non-negative number                      | Minimum visible-character count before search                | non-empty query            | `1`                              | `component:BaseTypeahead`    | released  | below threshold cancels work and closes results                                          |
-| debounce        | milliseconds                             | Delays query search                                          | typed query                | `150`                            | `component:BaseTypeahead`    | released  | non-positive runs immediately                                                            |
-| result cap      | number                                   | Limits fetched results shown                                 | completed search/bootstrap | `10`                             | `component:BaseTypeahead`    | released  | source order is preserved                                                                |
-| result content  | default, `renderItem`, or `item.element` | Chooses content inside the stable option row                 | result present             | default TypeaheadItem            | caller and component         | released  | `item.element` takes precedence                                                          |
-| disabled state  | native or focusable-disabled             | Blocks query mutation; native disabled blocks all activation | disabled                   | native disabled                  | component and caller wrapper | released  | an already-open focusable-disabled list can still select with Enter (retained violation) |
-| popup width     | intrinsic or fixed pixels                | Sets result popup width before viewport clamping             | popup present              | intrinsic, at least anchor width | `component:BaseTypeahead`    | released  | viewport fit wins                                                                        |
-| size            | `sm`, `md`, `lg`                         | Selects option-row padding                                   | popup options              | `md`                             | `component:BaseTypeahead`    | released  | TypeScript rejects other values                                                          |
+| Concept         | Closed values or states                  | Meaning                                                      | Availability by state      | Default                          | Owner                        | Stability | Invalid-value behavior                                                          |
+| --------------- | ---------------------------------------- | ------------------------------------------------------------ | -------------------------- | -------------------------------- | ---------------------------- | --------- | ------------------------------------------------------------------------------- |
+| selection       | `T` or `null`                            | Caller-controlled selected result                            | all states                 | required                         | `component:BaseTypeahead`    | released  | caller retains control                                                          |
+| search source   | `search`, `bootstrap`, optional `cancel` | Supplies query and focus results                             | enabled input              | required                         | `component:BaseTypeahead`    | released  | rejected work clears current results                                            |
+| focus bootstrap | on or off                                | Offers bootstrap results before query input                  | empty focused input        | off                              | `component:BaseTypeahead`    | released  | off keeps the menu closed                                                       |
+| query threshold | non-negative number                      | Minimum visible-character count before search                | non-empty query            | `1`                              | `component:BaseTypeahead`    | released  | below threshold cancels work and closes results                                 |
+| debounce        | milliseconds                             | Delays query search                                          | typed query                | `150`                            | `component:BaseTypeahead`    | released  | non-positive runs immediately                                                   |
+| result cap      | number                                   | Limits fetched results shown                                 | completed search/bootstrap | `10`                             | `component:BaseTypeahead`    | released  | source order is preserved                                                       |
+| result content  | default, `renderItem`, or `item.element` | Chooses content inside the stable option row                 | result present             | default TypeaheadItem            | caller and component         | released  | `item.element` takes precedence                                                 |
+| disabled state  | native or focusable-disabled             | Blocks query mutation; native disabled blocks all activation | disabled                   | native disabled                  | component and caller wrapper | released  | a list open before focusable-disabled applied picks nothing and can still close |
+| popup width     | intrinsic or fixed pixels                | Sets result popup width before viewport clamping             | popup present              | intrinsic, at least anchor width | `component:BaseTypeahead`    | released  | viewport fit wins                                                               |
+| size            | `sm`, `md`, `lg`                         | Selects option-row padding                                   | popup options              | `md`                             | `component:BaseTypeahead`    | released  | TypeScript rejects other values                                                 |
 
 ## Behavioral and layout contract
 
 Draft requirements identify their observational or current-authority basis.
 
-| ID  | Candidate invariant                                                                                                                                                                                                                                           | Basis                                                 | Draft review state                             |
-| --- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------- | ---------------------------------------------- |
-| FR1 | The input is controlled by internal query state while `value` is caller-controlled; selecting a result calls `onChange(item)`, clears query/results, closes the popup, and returns focus to the input.                                                        | Current source and tests                              | verified shipped behavior                      |
-| FR2 | Search starts only at the grapheme-count threshold, uses the configured debounce, and never presents an empty result for a query that was not searched.                                                                                                       | Public API, current i18n character utility, tests     | verified audit remediation                     |
-| FR3 | A newer query, selection, clear, source replacement, or unmount invalidates stale asynchronous work. Escape hides the current popup but does not invalidate pending work, so a late response currently reopens it (retained violation).                       | Current source, focused retained-red probe, and tests | verified shipped behavior                      |
-| FR4 | The popup is a named listbox whose result rows are options. A completed empty search renders one disabled option so the listbox retains a valid owned child.                                                                                                  | APG combobox pattern, axe, tests                      | verified audit remediation                     |
-| FR5 | Arrow keys wrap the highlight; Home/End move to the first/last option; Enter selects; Escape and Tab hide the current popup; IME-owned key events do not activate combobox commands. Escape dismissal is not durable while source work remains pending (FR3). | Current source and tests                              | verified shipped behavior; Escape gap retained |
-| FR6 | Pending asynchronous source work sets `aria-busy` and renders one named Spinner unless the composed wrapper owns the busy indicator lane.                                                                                                                     | Current source, input-family FR7, tests               | verified shipped behavior                      |
-| FR7 | Supported BaseProps DOM, ARIA, data, class, style, event, and `xstyle` inputs reach the combobox input while component-owned role, state, value, and behavior remain authoritative.                                                                           | `architecture:public-component-api/INV5–INV7`, tests  | verified audit remediation                     |
-| FR8 | The popup remains within the inline viewport at 320 CSS px, including long default results and a requested width larger than the available viewport.                                                                                                          | WCAG 1.4.10, real Chromium                            | verified audit remediation                     |
-| FR9 | Native disabled removes ordinary focus and activation. Focusable-disabled uses `aria-disabled` plus `readOnly` and blocks text/query mutation, but applying it after the popup opens does not currently block Enter selection (retained violation).           | Current source, tests, and focused retained-red probe | verified shipped behavior                      |
+| ID  | Candidate invariant                                                                                                                                                                                                                                                                                        | Basis                                                 | Draft review state                             |
+| --- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------- | ---------------------------------------------- |
+| FR1 | The input is controlled by internal query state while `value` is caller-controlled; selecting a result calls `onChange(item)`, clears query/results, closes the popup, and returns focus to the input.                                                                                                     | Current source and tests                              | verified shipped behavior                      |
+| FR2 | Search starts only at the grapheme-count threshold, uses the configured debounce, and never presents an empty result for a query that was not searched.                                                                                                                                                    | Public API, current i18n character utility, tests     | verified audit remediation                     |
+| FR3 | A newer query, selection, clear, source replacement, or unmount invalidates stale asynchronous work. Escape hides the current popup but does not invalidate pending work, so a late response currently reopens it (retained violation).                                                                    | Current source, focused retained-red probe, and tests | verified shipped behavior                      |
+| FR4 | The popup is a named listbox whose result rows are options. A completed empty search renders one disabled option so the listbox retains a valid owned child.                                                                                                                                               | APG combobox pattern, axe, tests                      | verified audit remediation                     |
+| FR5 | Arrow keys wrap the highlight; Home/End move to the first/last option; Enter selects; Escape and Tab hide the current popup; IME-owned key events do not activate combobox commands. Escape dismissal is not durable while source work remains pending (FR3).                                              | Current source and tests                              | verified shipped behavior; Escape gap retained |
+| FR6 | Pending asynchronous source work sets `aria-busy` and renders one named Spinner unless the composed wrapper owns the busy indicator lane.                                                                                                                                                                  | Current source, input-family FR7, tests               | verified shipped behavior                      |
+| FR7 | Supported BaseProps DOM, ARIA, data, class, style, event, and `xstyle` inputs reach the combobox input while component-owned role, state, value, and behavior remain authoritative.                                                                                                                        | `architecture:public-component-api/INV5–INV7`, tests  | verified audit remediation                     |
+| FR8 | The popup remains within the inline viewport at 320 CSS px, including long default results and a requested width larger than the available viewport.                                                                                                                                                       | WCAG 1.4.10, real Chromium                            | verified audit remediation                     |
+| FR9 | Native disabled removes ordinary focus and activation. Focusable-disabled uses `aria-disabled` plus `readOnly` and blocks text/query mutation, opening the list, and selection by Enter or a press, including from a list that was open before it applied; that list can still close (`spec:AST-085` FR2). | Current source and tests                              | verified shipped behavior                      |
 
 ### Allowed variation
 
@@ -116,17 +116,17 @@ Draft requirements identify their observational or current-authority basis.
 
 ### Representative states
 
-| State             | Required invariant                                                                                                                    | Allowed variation                      |
-| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------- |
-| rest              | named combobox is closed and not busy                                                                                                 | caller-owned wrapper and label         |
-| focused bootstrap | popup opens only when enabled and results exist                                                                                       | synchronous or asynchronous source     |
-| query pending     | combobox is busy and duplicate stale work is rejected                                                                                 | direct or wrapper-owned Spinner        |
-| results           | one highlighted option and valid active descendant                                                                                    | grouped/default/custom content         |
-| completed empty   | one disabled empty option; no active descendant                                                                                       | caller-supplied empty text             |
-| selected result   | matching option exposes `aria-selected=true`                                                                                          | generic check presentation             |
-| disabled          | native disabled blocks activation; focusable-disabled blocks query mutation but can still select an already-open highlight with Enter | native or focusable-disabled semantics |
-| dismissed pending | Escape hides the popup; a late pending response currently reopens it                                                                  | source completion timing               |
-| narrow viewport   | popup and result content remain inside two viewport gutters                                                                           | intrinsic or requested width           |
+| State             | Required invariant                                                                                                               | Allowed variation                      |
+| ----------------- | -------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------- |
+| rest              | named combobox is closed and not busy                                                                                            | caller-owned wrapper and label         |
+| focused bootstrap | popup opens only when enabled and results exist                                                                                  | synchronous or asynchronous source     |
+| query pending     | combobox is busy and duplicate stale work is rejected                                                                            | direct or wrapper-owned Spinner        |
+| results           | one highlighted option and valid active descendant                                                                               | grouped/default/custom content         |
+| completed empty   | one disabled empty option; no active descendant                                                                                  | caller-supplied empty text             |
+| selected result   | matching option exposes `aria-selected=true`                                                                                     | generic check presentation             |
+| disabled          | native disabled blocks activation; focusable-disabled blocks query mutation, opening and picking, also from an already-open list | native or focusable-disabled semantics |
+| dismissed pending | Escape hides the popup; a late pending response currently reopens it                                                             | source completion timing               |
+| narrow viewport   | popup and result content remain inside two viewport gutters                                                                      | intrinsic or requested width           |
 
 ### Transformation and precedence order
 
@@ -237,17 +237,17 @@ Draft requirements identify their observational or current-authority basis.
 
 ## Verification map
 
-| Contract        | Verification                                           | Representative states                             | Mutation or failure expectation                                        | Audit section                    |
-| --------------- | ------------------------------------------------------ | ------------------------------------------------- | ---------------------------------------------------------------------- | -------------------------------- |
-| FR1–FR2         | BaseTypeahead and Typeahead tests                      | query, overlap, select, clear                     | current work replaces newer results or selection does not close        | `audit:BaseTypeahead/behavior`   |
-| FR3             | shared stale-response tests plus retained-red probe    | newer query, clear, unmount, Escape while pending | late work replaces current results or reopens after explicit dismissal | `audit:BaseTypeahead/a11y`       |
-| FR4, AR1–AR4    | focused tests, component-scoped axe, live-region tests | results, empty, busy, selected                    | invalid listbox ownership or state/announcement disappears             | `audit:BaseTypeahead/a11y`       |
-| FR5, AR5        | keyboard, focus-out, IME, and retained-red tests       | arrows, Home/End, Enter, Escape, Tab, composition | command selects or dismisses at the wrong time                         | `audit:BaseTypeahead/a11y`       |
-| FR6             | busy-lane tests                                        | direct and composed pending source                | duplicate/missing Spinner or stale busy state                          | `audit:BaseTypeahead/a11y`       |
-| FR7             | focused passthrough tests and strict lint              | native-only, alias collisions, DOM/style/events   | supported consumer input is dropped or owned semantics are replaced    | `audit:BaseTypeahead/api`        |
-| FR8             | real-Chromium 320px sensor receipt                     | long result, wide request, LTR/RTL                | popup or its content crosses either viewport gutter                    | `audit:BaseTypeahead/responsive` |
-| FR9             | shared disabled tests plus retained-red probe          | native disabled, focusable-disabled after open    | disabled mode mutates query or accepts an already-open selection       | `audit:BaseTypeahead/a11y`       |
-| Theming anatomy | knowledge and theming-target checks                    | all mapped parts                                  | target inventory or disposition drifts                                 | `audit:BaseTypeahead/theming`    |
+| Contract        | Verification                                           | Representative states                                     | Mutation or failure expectation                                        | Audit section                    |
+| --------------- | ------------------------------------------------------ | --------------------------------------------------------- | ---------------------------------------------------------------------- | -------------------------------- |
+| FR1–FR2         | BaseTypeahead and Typeahead tests                      | query, overlap, select, clear                             | current work replaces newer results or selection does not close        | `audit:BaseTypeahead/behavior`   |
+| FR3             | shared stale-response tests plus retained-red probe    | newer query, clear, unmount, Escape while pending         | late work replaces current results or reopens after explicit dismissal | `audit:BaseTypeahead/a11y`       |
+| FR4, AR1–AR4    | focused tests, component-scoped axe, live-region tests | results, empty, busy, selected                            | invalid listbox ownership or state/announcement disappears             | `audit:BaseTypeahead/a11y`       |
+| FR5, AR5        | keyboard, focus-out, IME, and retained-red tests       | arrows, Home/End, Enter, Escape, Tab, composition         | command selects or dismisses at the wrong time                         | `audit:BaseTypeahead/a11y`       |
+| FR6             | busy-lane tests                                        | direct and composed pending source                        | duplicate/missing Spinner or stale busy state                          | `audit:BaseTypeahead/a11y`       |
+| FR7             | focused passthrough tests and strict lint              | native-only, alias collisions, DOM/style/events           | supported consumer input is dropped or owned semantics are replaced    | `audit:BaseTypeahead/api`        |
+| FR8             | real-Chromium 320px sensor receipt                     | long result, wide request, LTR/RTL                        | popup or its content crosses either viewport gutter                    | `audit:BaseTypeahead/responsive` |
+| FR9             | shared disabled tests                                  | native disabled; focusable-disabled before and after open | disabled mode mutates query, opens the list, or accepts a selection    | `audit:BaseTypeahead/a11y`       |
+| Theming anatomy | knowledge and theming-target checks                    | all mapped parts                                          | target inventory or disposition drifts                                 | `audit:BaseTypeahead/theming`    |
 
 ## Decision log
 

package/src/Typeahead/BaseTypeahead.tsx

@@ -153,10 +153,10 @@ export interface BaseTypeaheadProps<T extends SearchableItem> extends Omit<
    * When disabled with a reason, keeps the input focusable via `aria-disabled`
    * (instead of the native `disabled` attribute) and `readOnly` so an
    * associated disabled-reason tooltip stays discoverable by keyboard and
-   * assistive technology. Query and text mutation are blocked, but an
-   * already-open highlighted option can still be selected with Enter after a
-   * transition into this state. Consumers (Typeahead) own the tooltip and
-   * wrapper.
+   * assistive technology. Query and text mutation, opening the list, and a
+   * pick by Enter or a press are blocked, also from a list that was open
+   * before this state applied; Escape or Tab still closes it. Consumers
+   * (Typeahead) own the tooltip and wrapper.
    * @default false
    */
   isFocusableDisabled?: boolean;
@@ -687,11 +687,25 @@ export const BaseTypeahead = function BaseTypeahead<T extends SearchableItem>({
   // Show the layer, deferring past the active click if a pointer is down.
   // Without this, popover="auto" light-dismiss immediately closes the
   // dropdown when it opens between pointerdown and pointerup/click.
+  // Read at show time, so a search or bootstrap that settles after the field
+  // became disabled does not open the list (spec:AST-085 FR2).
+  const isDisabledRef = useRef(isDisabled);
+  useIsomorphicLayoutEffect(() => {
+    isDisabledRef.current = isDisabled;
+  }, [isDisabled]);
   const showLayer = useCallback(() => {
+    if (isDisabledRef.current) {
+      return;
+    }
     if (pointerActiveRef.current) {
       document.addEventListener(
         'click',
-        () => requestAnimationFrame(() => popover.show()),
+        () =>
+          requestAnimationFrame(() => {
+            if (!isDisabledRef.current) {
+              popover.show();
+            }
+          }),
         {once: true},
       );
     } else {
@@ -915,6 +929,11 @@ export const BaseTypeahead = function BaseTypeahead<T extends SearchableItem>({
   // Handle item selection
   const handleSelect = useCallback(
     (item: T) => {
+      // A disabled field changes nothing, also from a list that was open
+      // before it became disabled (spec:AST-085 FR2).
+      if (isDisabled) {
+        return;
+      }
       // Bump generation to invalidate any in-flight async searches
       searchGenRef.current++;
       if (searchTimeoutRef.current) {
@@ -933,7 +952,7 @@ export const BaseTypeahead = function BaseTypeahead<T extends SearchableItem>({
       popover.hide();
       inputRef.current?.focus();
     },
-    [onChange, popover, searchSource, setLoading],
+    [isDisabled, onChange, popover, searchSource, setLoading],
   );
 
   // Shared by handleFocus and handleClick: bootstrap entries if none are
@@ -984,7 +1003,7 @@ export const BaseTypeahead = function BaseTypeahead<T extends SearchableItem>({
   // dropdown never reopens until the user clicks away and back (#6845). See
   // wasAlreadyFocusedRef above for how the two cases are told apart.
   const handleClick = useCallback(() => {
-    if (!wasAlreadyFocusedRef.current || popover.isOpen) {
+    if (isDisabled || !wasAlreadyFocusedRef.current || popover.isOpen) {
       return;
     }
     if (
@@ -997,6 +1016,7 @@ export const BaseTypeahead = function BaseTypeahead<T extends SearchableItem>({
     }
     openIfEligible();
   }, [
+    isDisabled,
     popover.isOpen,
     hasEntriesOnFocus,
     query.length,
@@ -1050,18 +1070,51 @@ export const BaseTypeahead = function BaseTypeahead<T extends SearchableItem>({
         return;
       }
 
+      // A focusable-disabled field opens no list and picks nothing; it only
+      // lets a list that was open before it became disabled close
+      // (spec:AST-085 FR2).
+      if (isDisabled) {
+        // Enter on a list that is still open picks nothing, and must not
+        // submit an enclosing form either, as it would not while enabled.
+        if (popover.isOpen && e.key === 'Enter') {
+          e.preventDefault();
+        }
+        if (popover.isOpen && (e.key === 'Escape' || e.key === 'Tab')) {
+          if (e.key === 'Escape') {
+            e.preventDefault();
+          }
+          popover.hide();
+        }
+        return;
+      }
+
       if (!popover.isOpen) {
         if (e.key === 'ArrowDown' && (hasEntriesOnFocus || query.length > 0)) {
           e.preventDefault();
-          if (results.length > 0) {
+          // Results held from a replaced search source are not current
+          // (spec:AST-092 FR4): they count as none, so the new source loads.
+          const hasResultsFromCurrentSource =
+            results.length > 0 && resultsGenRef.current >= sourceGenRef.current;
+          const isQueryBelowMinLength = isBelowMinQueryLength(
+            query,
+            minQueryLength,
+          );
+          if (hasResultsFromCurrentSource) {
             popover.show();
             setHighlightedIndex(0);
+          } else if (
+            results.length > 0 &&
+            query.length > 0 &&
+            !isQueryBelowMinLength
+          ) {
+            // The typed query runs again against the new source.
+            void performSearch(query);
           } else if (
             hasEntriesOnFocus &&
             // A below-threshold query was never searched; falling back to the
             // bootstrap entries here would open a menu of suggestions that
             // ignore what the user has already typed.
-            !isBelowMinQueryLength(query, minQueryLength)
+            !isQueryBelowMinLength
           ) {
             void performBootstrap();
           }
@@ -1123,6 +1176,7 @@ export const BaseTypeahead = function BaseTypeahead<T extends SearchableItem>({
       }
     },
     [
+      isDisabled,
       popover,
       results,
       highlightedIndex,
@@ -1131,6 +1185,7 @@ export const BaseTypeahead = function BaseTypeahead<T extends SearchableItem>({
       query,
       minQueryLength,
       performBootstrap,
+      performSearch,
       externalOnKeyDown,
     ],
   );
@@ -1218,8 +1273,8 @@ export const BaseTypeahead = function BaseTypeahead<T extends SearchableItem>({
         placeholder={placeholder}
         // When a disabled-reason tooltip is shown the input keeps focusability
         // via aria-disabled + readOnly instead of the native disabled
-        // attribute. Query and text mutation are blocked, but an already-open
-        // highlighted option can still be selected with Enter after transition.
+        // attribute. Query and text mutation, opening and picking are blocked
+        // by the handlers above (spec:AST-085 FR2).
         disabled={isDisabled && !isFocusableDisabled}
         readOnly={isFocusableDisabled || undefined}
         autoFocus={hasAutoFocus}

package/src/Typeahead/Typeahead.tsx

@@ -63,6 +63,7 @@ import {
   isImeKeyEvent,
   mergeProps,
 } from '../utils';
+import {joinAriaIDs} from '../utils/inputAria';
 import {TrailingKeyDownContext} from './trailingKeyDown';
 import {
   type FieldInputBaseProps,
@@ -75,6 +76,7 @@ import {useTranslator} from '../i18n';
 
 import {useMergedRefs} from '../hooks/useMergedRefs';
 import {useBusyAnnouncement} from '../hooks/useBusyAnnouncement';
+import {useResolvedRequired} from '../hooks/useResolvedRequired';
 export type {
   InputStatus as TypeaheadStatus,
   InputStatusType as TypeaheadStatusType,
@@ -416,8 +418,10 @@ export function Typeahead<T extends SearchableItem>({
   controlStyle,
   id: idProp,
   'aria-describedby': ariaDescribedByProp,
+  'aria-labelledby': ariaLabelledByProp,
   ...restProps
 }: TypeaheadProps<T>) {
+  const isEffectivelyRequired = useResolvedRequired({isRequired, isOptional});
   const {rest, container} = useFieldInputStyling('Typeahead', restProps, {
     containerXstyle,
     containerClassName,
@@ -428,6 +432,8 @@ export function Typeahead<T extends SearchableItem>({
   const generatedInputId = useId();
   const inputId = idProp ?? generatedInputId;
   const inputLabelId = useId();
+  const fieldLabelId = useId();
+  const tokenValueId = useId();
   const descriptionId = useId();
   const statusMessageId = useId();
   const inputGroup = useInputGroup();
@@ -609,6 +615,13 @@ export function Typeahead<T extends SearchableItem>({
     inputGroup,
   );
 
+  // A caller aria-labelledby names the input together with the field's own
+  // label (the Field label standalone, the group and input labels in a group).
+  const inputLabelledBy =
+    ariaLabelledByProp != null
+      ? joinAriaIDs(ariaLabelledBy ?? fieldLabelId, ariaLabelledByProp)
+      : ariaLabelledBy;
+
   const sizeStyle = wrapperSizeStyles[size];
 
   const typeaheadContent = (
@@ -653,14 +666,33 @@ export function Typeahead<T extends SearchableItem>({
         <BusyIndicatorLaneProvider value={busyLane}>
           <div {...stylex.props(styles.contentLane)}>
             {showToken && (
-              <Token
-                ref={tokenRef}
-                label={value.label}
-                size={size}
-                onClick={handleEnterEditMode}
-                isDisabled={isDisabled}
-                xstyle={styles.tokenOverlay}
-              />
+              <>
+                {/* The token's button is the field's Tab stop while a value
+                    shows, so it is named as the input is (the field label,
+                    with a caller aria-labelledby) plus the value, and
+                    described like the input (input-fields FR10; WCAG 2.4.6,
+                    4.1.2). */}
+                <span id={tokenValueId} hidden>
+                  {value.label}
+                </span>
+                <Token
+                  ref={tokenRef}
+                  label={value.label}
+                  size={size}
+                  onClick={handleEnterEditMode}
+                  isDisabled={isDisabled}
+                  aria-labelledby={joinAriaIDs(
+                    inputLabelledBy ?? fieldLabelId,
+                    tokenValueId,
+                  )}
+                  aria-describedby={
+                    [ariaDescribedByProp, ariaDescribedBy]
+                      .filter(Boolean)
+                      .join(' ') || undefined
+                  }
+                  xstyle={styles.tokenOverlay}
+                />
+              </>
             )}
             <TrailingKeyDownContext value={onKeyDown}>
               <BaseTypeahead
@@ -684,7 +716,15 @@ export function Typeahead<T extends SearchableItem>({
                     .filter(Boolean)
                     .join(' ') || undefined
                 }
-                ariaLabelledBy={ariaLabelledBy}
+                ariaLabelledBy={inputLabelledBy}
+                // The resolved required state reaches the combobox, also when a
+                // FormLayout default hides the visible marker (component:FormLayout
+                // FR5, AR2).
+                aria-required={isEffectivelyRequired || rest['aria-required']}
+                // An error status is exposed on the combobox as on every other field
+                // (WCAG 4.1.2; spec:AST-020 FR9). Without one, a caller's own
+                // aria-required / aria-invalid still applies.
+                aria-invalid={status?.type === 'error' || rest['aria-invalid']}
                 onChangeQuery={onChangeQuery}
                 onOpenChange={onOpenChange}
                 debounceMs={debounceMs}
@@ -735,6 +775,8 @@ export function Typeahead<T extends SearchableItem>({
       isLabelHidden={isLabelHidden}
       description={description}
       inputID={inputId}
+      // Always set: the value token's name references the field label.
+      labelID={fieldLabelId}
       descriptionID={description ? descriptionId : undefined}
       isOptional={isOptional}
       isRequired={isRequired}

package/src/gestures/GestureArena.ts

@@ -119,10 +119,15 @@ interface Timer {
   callback: () => void;
 }
 
+/**
+ * The arena that decides which recognizer gets a touch.
+ */
 export class GestureArena {
   readonly environment: GestureEnvironment;
   private readonly clock: GestureClock;
   private readonly options: GestureArenaOptions;
+  /** The touches whose move the arena is delivering right now. */
+  private movingIds: ReadonlySet<number> = new Set();
   private readonly records = new Map<number, TouchRecord>();
   /** Recognizers involved in the current interaction, in resolution order. */
   private active: GestureRecognizer[] = [];
@@ -134,6 +139,10 @@ export class GestureArena {
   /** The latest time processed: input never moves the clock backwards. */
   private latestTime = Number.NEGATIVE_INFINITY;
   private depth = 0;
+  /** Open `deferResolution` calls: what their stops unblock waits. */
+  private deferDepth = 0;
+  /** A deferred stop left recognitions, held touches or resets to settle. */
+  private owesResolution = false;
 
   constructor(options: GestureArenaOptions = {}) {
     this.options = options;
@@ -262,6 +271,41 @@ export class GestureArena {
     });
   }
 
+  /**
+   * A contact began where nothing takes part (plain page content). It is
+   * never tracked and stays the browser's; recognizers already tracking a
+   * gesture hear of it, as of any touch off their hit path.
+   */
+  untrackedBegan(input: TouchBeganInput): void {
+    if (!this.active.some(recognizer => recognizer.numberOfTouches > 0)) {
+      return;
+    }
+    this.run(input.time, () => {
+      const time = this.clampTime(input.time);
+      const touch: GestureTouch = {
+        id: input.id,
+        pointerType: input.pointerType,
+        phase: 'began',
+        x: input.x,
+        y: input.y,
+        time,
+        startX: input.x,
+        startY: input.y,
+        startTime: time,
+        samples: [{x: input.x, y: input.y, time}],
+        target: input.target,
+        scroll: input.scroll ?? null,
+        takenByBrowser: false,
+      };
+      const context = this.context();
+      for (const recognizer of [...this.active]) {
+        if (recognizer.numberOfTouches > 0) {
+          recognizer.deliverBeganElsewhere([touch], context);
+        }
+      }
+    });
+  }
+
   /** Contacts moved. */
   moved(inputs: ReadonlyArray<TouchInput>): void {
     if (inputs.length === 0) {
@@ -273,8 +317,14 @@ export class GestureArena {
         return;
       }
       const context = this.context();
-      for (const recognizer of [...this.active]) {
-        recognizer.deliverMoved(changed, context);
+      const previous = this.movingIds;
+      this.movingIds = new Set(changed.map(touch => touch.id));
+      try {
+        for (const recognizer of [...this.active]) {
+          recognizer.deliverMoved(changed, context);
+        }
+      } finally {
+        this.movingIds = previous;
       }
       for (const touch of changed) {
         const record = this.records.get(touch.id);
@@ -421,13 +471,43 @@ export class GestureArena {
     }
   }
 
+  /**
+   * Runs `body`, code outside input that stops recognizers (an Effect that
+   * turns one off or detaches it), without resolving what those stops
+   * unblock: the recognitions waiting on them, the touches they held from a
+   * view, the resets. A pass a microtask later resolves all of it, at the
+   * last event's time, so the listeners and consumers it reaches hear it
+   * outside the caller's frame and read the recognized state
+   * (react-component-runtime INV2).
+   */
+  deferResolution(body: () => void): void {
+    this.deferDepth += 1;
+    try {
+      body();
+    } finally {
+      this.deferDepth -= 1;
+    }
+    if (this.deferDepth === 0 && this.owesResolution) {
+      queueMicrotask(() => {
+        if (this.owesResolution && this.deferDepth === 0) {
+          this.run(this.lastEventTime(), () => {});
+        }
+      });
+    }
+  }
+
+  /** The last event's time, or now before any event. */
+  private lastEventTime(): number {
+    return Number.isFinite(this.latestTime)
+      ? this.latestTime
+      : this.clock.now();
+  }
+
   /** Cancel an active recognizer, or fail a possible one. */
   stop(recognizer: GestureRecognizer): void {
     // A cancel from code between events happens at the last event's time:
     // wall time would run deadlines ahead of input still queued (FR16).
-    const time =
-      this.currentTime ??
-      (Number.isFinite(this.latestTime) ? this.latestTime : this.clock.now());
+    const time = this.currentTime ?? this.lastEventTime();
     this.run(time, () => {
       if (isActive(recognizer.state)) {
         this.apply(recognizer, 'cancelled');
@@ -534,6 +614,11 @@ export class GestureArena {
     }
     recognizer.pending = null;
     this.apply(recognizer, 'failed');
+    if (this.deferDepth > 0) {
+      // Inside `deferResolution`, the next pass settles.
+      this.owesResolution = true;
+      return;
+    }
     this.reviewPending();
   }
 
@@ -541,12 +626,19 @@ export class GestureArena {
    * A recognition that claimed its touches and then fails or is cancelled (a
    * waiting recognition that fails, a gesture a second finger or the app
    * cancels) gives them back to the browser unless another recognition owns
-   * them, so a finger still resting there can pinch-zoom the page.
+   * them, so a finger still resting there can pinch-zoom the page. A gesture
+   * that cancels itself on a finger's move (a long press past its tolerance)
+   * keeps that finger until it lifts: the drag goes on, and the page never
+   * takes it over midway (`spec:AST-094` FR14), as UIKit's scroll view never
+   * takes a touch another recognizer had.
    */
-  private releaseClaim(recognizer: GestureRecognizer): void {
+  private releaseClaim(
+    recognizer: GestureRecognizer,
+    keep: ReadonlySet<number> = new Set(),
+  ): void {
     for (const touch of recognizer.trackedTouches) {
       const record = this.records.get(touch.id);
-      if (record == null || !record.isClaimed) {
+      if (record == null || !record.isClaimed || keep.has(touch.id)) {
         continue;
       }
       // A recognized discrete gesture (`ended`, a swipe) still owns its
@@ -577,7 +669,9 @@ export class GestureArena {
     if (isTerminal(next)) {
       this.clearTimer(recognizer);
     }
-    if (next === 'cancelled' || next === 'failed') {
+    if (next === 'cancelled') {
+      this.releaseClaim(recognizer, this.movingIds);
+    } else if (next === 'failed') {
       this.releaseClaim(recognizer);
     }
   }
@@ -835,9 +929,15 @@ export class GestureArena {
       this.currentTime = this.clampTime(time);
       body();
       // Re-entrant calls settle with the outermost one: settling mid-delivery
-      // would reset recognizers that have not heard the event yet.
+      // would reset recognizers that have not heard the event yet. Inside
+      // `deferResolution`, the next pass settles.
       if (this.depth === 1) {
-        this.settle();
+        if (this.deferDepth > 0) {
+          this.owesResolution = true;
+        } else {
+          this.owesResolution = false;
+          this.settle();
+        }
       }
     } finally {
       this.depth -= 1;