@astryxdesign/core 0.7.6-canary.f73623d → 0.7.6-canary.f899313

package/src/Slider/Slider.spec.md

@@ -78,13 +78,14 @@ modes, states, and usage remain documented in `Slider.doc.mjs`.
 
 ## Behavioral and layout contract
 
-| ID  | Candidate invariant                                                                                                                                                                                                                                                                                                                                                                                                                          | Basis                                   | Review state                                       |
-| --- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------- | -------------------------------------------------- |
-| FR1 | The current render places a filled range, one or two thumbs, and optional tick marks over the background track.                                                                                                                                                                                                                                                                                                                              | Current source, docs, and focused tests | Verified current behavior; no new behavior decided |
-| FR2 | `Slider`, `Interactive control`, `Track`, and `Thumb` carry the `slider`, `slider-control`, `slider-track`, and `slider-thumb` targets respectively.                                                                                                                                                                                                                                                                                         | Current source, public docs, and DEC-1  | Approved additive target contract                  |
-| FR3 | Filled range, tick marks, mark labels, and adjacent text value display are stable rendered parts without their own current Slider target.                                                                                                                                                                                                                                                                                                    | Current source and public docs          | Verified current asymmetry; not ratified as policy |
-| FR4 | Label and status presentation continue to use Field and FieldStatus; value tooltips continue to use Tooltip.                                                                                                                                                                                                                                                                                                                                 | Current source and focused tests        | Verified composition boundary                      |
-| FR5 | `onChangeEnd` fires once when an interaction ends — a pointer drag or track press is released or cancelled, or a keyboard step (arrow, Page, Home, End) completes — and carries the value the owner renders after its synchronous response to that interaction's `onChange` calls, including any clamp, snap, or rejection; it never carries a value Slider emitted that the owner did not render. A range reports both values the same way. | Maintainer decision (DEC-3)             | Approved                                           |
+| ID  | Candidate invariant                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          | Basis                                   | Review state                                       |
+| --- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------- | -------------------------------------------------- |
+| FR1 | The current render places a filled range, one or two thumbs, and optional tick marks over the background track.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              | Current source, docs, and focused tests | Verified current behavior; no new behavior decided |
+| FR2 | `Slider`, `Interactive control`, `Track`, and `Thumb` carry the `slider`, `slider-control`, `slider-track`, and `slider-thumb` targets respectively.                                                                                                                                                                                                                                                                                                                                                                                                                                                         | Current source, public docs, and DEC-1  | Approved additive target contract                  |
+| FR3 | Filled range, tick marks, mark labels, and adjacent text value display are stable rendered parts without their own current Slider target.                                                                                                                                                                                                                                                                                                                                                                                                                                                                    | Current source and public docs          | Verified current asymmetry; not ratified as policy |
+| FR4 | Label and status presentation continue to use Field and FieldStatus; value tooltips continue to use Tooltip.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 | Current source and focused tests        | Verified composition boundary                      |
+| FR5 | `onChangeEnd` fires once when an interaction ends — a pointer drag or track press is released or cancelled, or a keyboard step (arrow, Page, Home, End) completes — and carries the value the owner renders after its synchronous response to that interaction's `onChange` calls, including any clamp, snap, or rejection; it never carries a value Slider emitted that the owner did not render. A range reports both values the same way.                                                                                                                                                                 | Maintainer decision (DEC-3)             | Approved                                           |
+| FR6 | When both thumbs of a range share a value, a pointer press takes the thumb that can travel toward the pointer: a press on the track beside them takes the thumb on its side, and a press on the thumbs moves neither until the pointer moves, when the direction of that first movement picks the thumb, which takes the drag's focus, pressed state and value tooltip. A drag that began on the shared thumbs and comes back past their value moves the other thumb: the dragged thumb stops against it and the other follows the pointer, so with both at 80 a drag to 95 and back to 50 ends at [50, 80]. | Current source and focused tests        | Accepted contract                                  |
 
 ### Observed current target asymmetry
 
@@ -225,15 +226,16 @@ separately listed value tooltip retains Tooltip's target.
 
 ## Verification map
 
-| Contract            | Verification                                                                                                                                                                                                                                                                                                                                                                                                                 | Representative states                                                                       | Mutation or failure expectation                                                                                                                                       | Audit section                |
-| ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------- |
-| FR1                 | `Slider.test.tsx` structure, range, and marks suites                                                                                                                                                                                                                                                                                                                                                                         | Single, range, horizontal, vertical, marks                                                  | Removing or misaligning stable parts breaks existing role, position, or mark assertions.                                                                              | `audit:Slider/anatomy`       |
-| AR1                 | Slider accessibility contract (`internal/a11y-spec`, pending) bound to Slider; disabled-thumb Tab stop pending conformance; in jsdom and Chromium; `Slider.test.tsx` keyboard suites, including "follows the mirrored track under RTL: ArrowLeft increases, ArrowRight decreases, Up/Down unchanged" and "keeps ArrowLeft decreasing on a vertical track under RTL"; the Page, Home/End and Up/Down cases under the contract | Single and range; horizontal LTR and RTL; vertical; disabled; formatted value               | A thumb loses its role, name or value properties; an arrow, Page, Home or End key stops stepping or steps against the mirrored track; a range thumb crosses the other | `audit:Slider/accessibility` |
-| FR2                 | `Slider.test.tsx`, `themingTargets.test.ts`, generated probe theme, and Chromium                                                                                                                                                                                                                                                                                                                                             | Root, horizontal/vertical control, disabled control, track, and thumb                       | A target class/state is missing, undocumented, or placed outside its owning anatomy.                                                                                  | `audit:Slider/theming`       |
-| FR3                 | Source and consumer-doc review                                                                                                                                                                                                                                                                                                                                                                                               | Filled range, marks, labels, adjacent text value                                            | A missing target is inaccurately documented as present or intentionally permanent.                                                                                    | `audit:Slider/theming`       |
-| FR4                 | Source inspection; focused tests cover label, status, and disabled-reason Tooltip only                                                                                                                                                                                                                                                                                                                                       | Label, status, value tooltip, disabled reason                                               | Shared composition or its accessible association disappears; value-tooltip composition still lacks focused coverage.                                                  | `audit:Slider/anatomy`       |
-| FR5                 | Pending: `Slider.test.tsx` change-end cases driven by an owner that renders, clamps, or rejects the emitted value (not yet in the suite)                                                                                                                                                                                                                                                                                     | Single and range; pointer release before and after the owner re-renders; each keyboard step | `onChangeEnd` reports a value the owner did not render, fires more than once per interaction, or skips a completed keyboard step                                      | `audit:Slider/accessibility` |
-| Theming anatomy map | `scripts/check-knowledge.mjs`                                                                                                                                                                                                                                                                                                                                                                                                | Canonical anatomy and four current local targets                                            | Missing, extra, prefixed, stale, or unclaimed mappings fail repository validation.                                                                                    | `audit:Slider/theming`       |
+| Contract            | Verification                                                                                                                                                                                                                                                                                                                                                                                                                 | Representative states                                                                                                                                                                   | Mutation or failure expectation                                                                                                                                                            | Audit section                |
+| ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------- |
+| FR1                 | `Slider.test.tsx` structure, range, and marks suites                                                                                                                                                                                                                                                                                                                                                                         | Single, range, horizontal, vertical, marks                                                                                                                                              | Removing or misaligning stable parts breaks existing role, position, or mark assertions.                                                                                                   | `audit:Slider/anatomy`       |
+| AR1                 | Slider accessibility contract (`internal/a11y-spec`, pending) bound to Slider; disabled-thumb Tab stop pending conformance; in jsdom and Chromium; `Slider.test.tsx` keyboard suites, including "follows the mirrored track under RTL: ArrowLeft increases, ArrowRight decreases, Up/Down unchanged" and "keeps ArrowLeft decreasing on a vertical track under RTL"; the Page, Home/End and Up/Down cases under the contract | Single and range; horizontal LTR and RTL; vertical; disabled; formatted value                                                                                                           | A thumb loses its role, name or value properties; an arrow, Page, Home or End key stops stepping or steps against the mirrored track; a range thumb crosses the other                      | `audit:Slider/accessibility` |
+| FR2                 | `Slider.test.tsx`, `themingTargets.test.ts`, generated probe theme, and Chromium                                                                                                                                                                                                                                                                                                                                             | Root, horizontal/vertical control, disabled control, track, and thumb                                                                                                                   | A target class/state is missing, undocumented, or placed outside its owning anatomy.                                                                                                       | `audit:Slider/theming`       |
+| FR3                 | Source and consumer-doc review                                                                                                                                                                                                                                                                                                                                                                                               | Filled range, marks, labels, adjacent text value                                                                                                                                        | A missing target is inaccurately documented as present or intentionally permanent.                                                                                                         | `audit:Slider/theming`       |
+| FR4                 | Source inspection; focused tests cover label, status, and disabled-reason Tooltip only                                                                                                                                                                                                                                                                                                                                       | Label, status, value tooltip, disabled reason                                                                                                                                           | Shared composition or its accessible association disappears; value-tooltip composition still lacks focused coverage.                                                                       | `audit:Slider/anatomy`       |
+| FR5                 | Pending: `Slider.test.tsx` change-end cases driven by an owner that renders, clamps, or rejects the emitted value (not yet in the suite)                                                                                                                                                                                                                                                                                     | Single and range; pointer release before and after the owner re-renders; each keyboard step                                                                                             | `onChangeEnd` reports a value the owner did not render, fires more than once per interaction, or skips a completed keyboard step                                                           | `audit:Slider/accessibility` |
+| FR6                 | `Slider.test.tsx` coincident range thumbs cases                                                                                                                                                                                                                                                                                                                                                                              | Both thumbs at the minimum, the maximum and mid-range; a track press on each side; a press on the thumbs moved either way; a drag that passes back over the shared value; right to left | A press or drag on coincident thumbs moves neither thumb, moves the thumb that cannot travel toward the pointer, or keeps its focus, pressed state or tooltip on a thumb the drag has left | `audit:Slider/anatomy`       |
+| Theming anatomy map | `scripts/check-knowledge.mjs`                                                                                                                                                                                                                                                                                                                                                                                                | Canonical anatomy and four current local targets                                                                                                                                        | Missing, extra, prefixed, stale, or unclaimed mappings fail repository validation.                                                                                                         | `audit:Slider/theming`       |
 
 The focused Slider suite asserts the `slider-control` target's orientation and
 disabled state. Source/metadata guards cover all four target declarations. The

package/src/Slider/Slider.tsx

@@ -5,7 +5,7 @@
 /**
  * @file Slider.tsx
  * @input Uses React, useId, useRef, useCallback, useEffect, Field, Tooltip, useTooltip, VisuallyHidden
- * @output Exports Slider and its props; unfilled marks share the track token; modifier-only key presses do not restore the thumb focus ring; a drag belongs to the pointer that started it
+ * @output Exports Slider and its props; unfilled marks share the track token; modifier-only key presses do not restore the thumb focus ring; a drag belongs to the pointer that started it; two coincident range thumbs separate toward the press or the first movement
  * @position Core implementation; consumed by index.ts, tested by Slider.test.tsx
  *
  * SYNC: When modified, update these files to stay in sync:
@@ -672,8 +672,24 @@ export function Slider({ref, ...props}: SliderProps) {
     [isRange, values],
   );
 
+  // The pointer's value at a press on two coincident thumbs, while no
+  // movement has said which way the drag goes; the first value off it picks
+  // the thumb that can travel that way (see handlePointerMove).
+  const coincidentDragRef = useRef<number | null>(null);
+  // Whether the drag in progress began on two coincident thumbs: such a drag
+  // can always follow the pointer, so when the dragged thumb is held against
+  // the other one and the pointer passes it, the other thumb takes the drag.
+  const coincidentOriginRef = useRef(false);
+
   const updateValue = useCallback(
-    (thumbIndex: number, newVal: number, snap = true) => {
+    (
+      thumbIndex: number,
+      newVal: number,
+      snap = true,
+      // The other thumb's values to start from, when one event moves both
+      // (a drag handed from one coincident thumb to the other).
+      from: ReadonlyArray<number> = values,
+    ) => {
       if (isDisabled) {
         return;
       }
@@ -687,7 +703,7 @@ export function Slider({ref, ...props}: SliderProps) {
       );
 
       if (isRange) {
-        const currentValues = [...values] as [number, number];
+        const currentValues = [...from] as [number, number];
         currentValues[thumbIndex] = clamped;
 
         // Enforce minStepsBetweenThumbs
@@ -765,6 +781,8 @@ export function Slider({ref, ...props}: SliderProps) {
         detachLostCaptureRef.current = null;
         draggingThumbRef.current = null;
         dragPointerRef.current = null;
+        coincidentDragRef.current = null;
+        coincidentOriginRef.current = false;
         setDraggingThumb(null);
         fireChangeEnd();
       }
@@ -804,13 +822,33 @@ export function Slider({ref, ...props}: SliderProps) {
         pressedThumb == null || thumbs == null
           ? -1
           : Array.from(thumbs).indexOf(pressedThumb);
-      // A direct thumb press owns that thumb even when range values coincide.
-      // Track and mark presses still choose the nearest value.
-      const thumbIndex =
+      // A direct thumb press owns that thumb; track and mark presses choose
+      // the nearest value. Two thumbs on one value are the exception: only
+      // one of them can travel toward where the pointer goes. A track press
+      // beside them picks the thumb on its side. A press on the thumbs
+      // themselves (or on their shared value) moves nothing: the pressed
+      // thumb holds the press until the pointer moves, and the direction of
+      // that first movement from the press picks the thumb.
+      const isCoincident = isRange && values[0] === values[1];
+      let thumbIndex =
         pressedThumbIndex >= 0 ? pressedThumbIndex : getClosestThumb(newVal);
+      const parks =
+        isCoincident && (pressedThumbIndex >= 0 || newVal === values[0]);
+      // The first movement is measured from the pointer itself, not from a
+      // mark it pressed (a wide label sits away from its mark's value).
+      coincidentDragRef.current = parks
+        ? getValueFromPosition(e.clientX, e.clientY)
+        : null;
+      // Only a drag that began on the shared thumbs, the press that waited for
+      // the first movement, hands itself to the other thumb (FR6); a track
+      // press beside them already picked its thumb.
+      coincidentOriginRef.current = parks;
+      if (isCoincident && !parks) {
+        thumbIndex = newVal > values[0] ? 1 : 0;
+      }
       draggingThumbRef.current = thumbIndex;
       setDraggingThumb(thumbIndex);
-      updateValue(thumbIndex, newVal);
+      updateValue(thumbIndex, parks ? values[thumbIndex] : newVal);
 
       // Focus the thumb that owns this drag.
       thumbs?.[thumbIndex]?.focus();
@@ -839,7 +877,15 @@ export function Slider({ref, ...props}: SliderProps) {
         (e.currentTarget as HTMLElement).setPointerCapture(e.pointerId);
       }
     },
-    [isDisabled, getValueFromPosition, getClosestThumb, updateValue, endDrag],
+    [
+      isDisabled,
+      isRange,
+      values,
+      getValueFromPosition,
+      getClosestThumb,
+      updateValue,
+      endDrag,
+    ],
   );
 
   const handlePointerMove = useCallback(
@@ -852,6 +898,48 @@ export function Slider({ref, ...props}: SliderProps) {
         return;
       }
       const newVal = getValueFromPosition(e.clientX, e.clientY);
+      // Hands the drag to a thumb, with its focus and pressed paint.
+      const handTo = (thumbIndex: number) => {
+        if (thumbIndex === draggingThumbRef.current) {
+          return;
+        }
+        draggingThumbRef.current = thumbIndex;
+        setDraggingThumb(thumbIndex);
+        const thumbs =
+          trackRef.current?.querySelectorAll<HTMLElement>('[role="slider"]');
+        thumbs?.[thumbIndex]?.focus();
+        setKeyboardFocusThumb(null);
+      };
+      const pressValue = coincidentDragRef.current;
+      if (pressValue !== null) {
+        if (newVal === pressValue) {
+          return;
+        }
+        // The first movement from a press on coincident thumbs hands the
+        // drag to the thumb that can travel that way.
+        coincidentDragRef.current = null;
+        handTo(newVal > pressValue ? 1 : 0);
+      } else if (coincidentOriginRef.current) {
+        // A drag that began on coincident thumbs follows the pointer either
+        // way: once the pointer passes the other thumb, the dragged one stops
+        // against it and the other takes the drag (a first step that drifted
+        // the wrong way never sticks the drag).
+        const current = valuesRef.current;
+        const dragging = draggingThumbRef.current;
+        const other = dragging === 0 ? 1 : 0;
+        if (
+          (dragging === 0 && newVal > current[1]) ||
+          (dragging === 1 && newVal < current[0])
+        ) {
+          // The dragged thumb ends against the other one, as if it had
+          // followed the pointer there, and the other follows the pointer on.
+          const from = [...current];
+          from[dragging] = current[other];
+          handTo(other);
+          updateValue(other, newVal, true, from);
+          return;
+        }
+      }
       updateValue(draggingThumbRef.current, newVal);
     },
     [isDisabled, getValueFromPosition, updateValue],
@@ -1070,7 +1158,11 @@ export function Slider({ref, ...props}: SliderProps) {
           placement={tooltipPlacement}
           delay={0}
           focusTrigger="always"
-          isOpen={draggingThumb === thumbIndex ? true : undefined}>
+          // A drag keeps its own thumb's value showing and closes the other
+          // thumb's, which a drag handed over from it may have forced open.
+          isOpen={
+            draggingThumb === null ? undefined : draggingThumb === thumbIndex
+          }>
           {thumbElement}
         </Tooltip>
       );

package/src/Token/Token.spec.md

@@ -130,7 +130,7 @@ Consumer migration instructions belong in consumer docs and release notes.
 | FR7  | The label never wraps: the root is capped at its container's inline size and clips overflow. In the static and link structures the Label ends in an ellipsis; in the clickable and link-and-remove structures the inner control clips the Label without an ellipsis. `isLabelHidden` keeps the Label in the DOM with a visually hidden clip treatment.                                                                                                                                                                                                                                                                                                                    | Current source and tests |
 | FR8  | `color` defaults to `default`, painting `--color-neutral` with primary text; every other built-in tone paints its tinted background with its matching colored text. The `token` target reflects the resolved `color` and `size` for every value, including a theme-added color, which receives no component fill or text color until a theme paints it.                                                                                                                                                                                                                                                                                                                   | Current source and tests |
 | FR9  | Clickable and link structures paint the shared hover overlay under a hover-capable pointer and the shared pressed overlay for mouse and touch presses; the static structure paints neither.                                                                                                                                                                                                                                                                                                                                                                                                                                                                               | Current source           |
-| FR10 | `ref` reaches the root element of every structure. Supported DOM, ARIA, data, and event props reach the root; `data-testid` reaches the root; `xstyle`, `className`, and `style` merge in that order after component styles.                                                                                                                                                                                                                                                                                                                                                                                                                                              | Current source and tests |
+| FR10 | `ref` reaches the root element of every structure. Supported DOM, ARIA, data, and event props reach the root, except that in the clickable structure `aria-labelledby` and `aria-describedby` reach the inner button, the element that owns the token's action (`architecture:public-component-api` INV5); `data-testid` reaches the root; `xstyle`, `className`, and `style` merge in that order after component styles.                                                                                                                                                                                                                                                 | Current source and tests |
 
 ### Allowed variation
 
@@ -142,15 +142,15 @@ Consumer migration instructions belong in consumer docs and release notes.
 
 ### Representative states
 
-| State              | Required invariant                                                                    | Allowed variation           |
-| ------------------ | ------------------------------------------------------------------------------------- | --------------------------- |
-| Static             | `span` root; Token adds no focusable element except a Remove button.                  | Tone, size, slots.          |
-| Clickable          | One inner button named by the label; container click calls `onClick`.                 | End content.                |
-| Link               | Root is the link; focus outline on the link itself.                                   | Router link component.      |
-| Link and remove    | Container holds a link and a sibling Remove button; surface click activates the link. | Modified and middle clicks. |
-| Removable          | Remove button named "Remove {label}" with a 24 by 24 CSS pixel target.                | Locale wording.             |
-| Disabled clickable | Buttons focusable with `aria-disabled="true"`; no callback fires; half opacity.       | Tone.                       |
-| Hidden label       | Label text visually hidden; the root's `aria-label` equals the label.                 | Structure.                  |
+| State              | Required invariant                                                                                      | Allowed variation           |
+| ------------------ | ------------------------------------------------------------------------------------------------------- | --------------------------- |
+| Static             | `span` root; Token adds no focusable element except a Remove button.                                    | Tone, size, slots.          |
+| Clickable          | One inner button named by the label, or by a caller `aria-labelledby`; container click calls `onClick`. | End content.                |
+| Link               | Root is the link; focus outline on the link itself.                                                     | Router link component.      |
+| Link and remove    | Container holds a link and a sibling Remove button; surface click activates the link.                   | Modified and middle clicks. |
+| Removable          | Remove button named "Remove {label}" with a 24 by 24 CSS pixel target.                                  | Locale wording.             |
+| Disabled clickable | Buttons focusable with `aria-disabled="true"`; no callback fires; half opacity.                         | Tone.                       |
+| Hidden label       | Label text visually hidden; the root's `aria-label` equals the label.                                   | Structure.                  |
 
 ### Transformation and precedence order
 
@@ -178,7 +178,8 @@ Consumer migration instructions belong in consumer docs and release notes.
   separate focusable controls in DOM order; neither is nested in the other, so
   the HTML interactive-content rule holds.
 - **AR2 — Names.** In the clickable and link-and-remove structures the inner
-  button or link takes its name from the Label. In the link structure the link
+  button or link takes its name from the Label, or, in the clickable structure,
+  from a caller `aria-labelledby` (FR10). In the link structure the link
   is the root and takes its name from all of its content, including End content
   (a label "Inbox" with a count reads "Inbox 12"). The
   Remove button is named by the translated "Remove {label}" string.
@@ -234,18 +235,18 @@ token's text color.
 
 ## Verification map
 
-| Contract           | Verification                                                                           | Representative states                                                                  | Mutation or failure expectation                                                                                                                                                                    | Audit section          |
-| ------------------ | -------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------- |
-| FR2, FR10          | `Token.test.tsx` render, ref, and pass-through suites                                  | Static, clickable, and link roots; caller props                                        | A wrong root element, a detached ref, or a dropped caller prop fails DOM assertions. Gap: no test covers the ref on the link-and-remove container.                                                 | `audit:Token/behavior` |
-| FR1, FR7           | `Token.stories.tsx` size, icon, and end-content fixtures in a browser                  | Sizes, icon and end content                                                            | Gap: the size and overflow unit tests assert presence only, and no story renders a long label; slot order and block size are visible only in the rendered fixtures, and the ellipsis has no check. | `audit:Token/layout`   |
-| FR3, FR4, FR6, AR1 | `Token.test.tsx` link, clickable, and link-with-remove suites                          | Link, clickable, link and remove, modified and middle clicks                           | Nesting the Remove button, firing the token action from Remove, or losing delegation fails. Gap: no test asserts that `onClick` is dropped with `href`.                                            | `audit:Token/behavior` |
-| FR5, AR5           | `Token.test.tsx` disabled tests                                                        | Disabled clickable with remove; disabled static; disabled link with and without remove | A native `disabled`, a lost tab stop, a disabled link with a destination, an unreflected disabled state, or a fired callback fails.                                                                | `audit:Token/a11y`     |
-| AR2, AR3, AR7      | `Token.test.tsx` accessibility suite                                                   | Remove name, hidden label, description                                                 | A missing remove name, lost hidden label, or missing description fails. Gap: no test asserts the link structure's content-derived name.                                                            | `audit:Token/a11y`     |
-| AR6                | `TokenRemoveTarget.a11y.chromium.spec.ts`                                              | Pre-set filter tokens (default size), LTR and RTL                                      | A remove target that misses its X edge or swallows a label press fails in real Chromium. Gap: the `sm` clipping is not covered.                                                                    | `audit:Token/a11y`     |
-| FR8                | `Token.test.tsx` custom-color test; `extensibleAxes.test.ts`; `themingTargets.test.ts` | Theme-added color; map wiring                                                          | Dropping the `color` reflection fails. Gap: no test asserts `data-size` or any tone's paint; those are visible only in `Token.stories.tsx`.                                                        | `audit:Token/theming`  |
-| FR9, AR4           | `Token.stories.tsx` clickable and link fixtures in a browser                           | Hover, press, keyboard focus on the token                                              | Gap: no automated check covers overlays or indicators, and no story renders a clickable or link token with Remove, so the double indicator on Remove has no fixture.                               | `audit:Token/design`   |
-| PR1                | Source review                                                                          | Every structure                                                                        | Gap: no automated check fails if Token adds a per-token listener, observer, or timer.                                                                                                              | `audit:Token/behavior` |
-| AR2, AR3, AR5, AR7 | Accessibility-tree evidence (`spec:AST-009` FR3)                                       | Every structure; hidden label; description; disabled                                   | Gap: no accessibility-tree check proves the computed names, the hidden-label name, the description, or the disabled state; the unit tests assert DOM attributes only.                              | `audit:Token/a11y`     |
+| Contract           | Verification                                                                           | Representative states                                                                                   | Mutation or failure expectation                                                                                                                                                                            | Audit section          |
+| ------------------ | -------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------- |
+| FR2, FR10          | `Token.test.tsx` render, ref, and pass-through suites                                  | Static, clickable, and link roots; caller props; caller naming on a clickable and a disabled link token | A wrong root element, a detached ref, a dropped caller prop, or a clickable token's `aria-labelledby` left on its root fails DOM assertions. Gap: no test covers the ref on the link-and-remove container. | `audit:Token/behavior` |
+| FR1, FR7           | `Token.stories.tsx` size, icon, and end-content fixtures in a browser                  | Sizes, icon and end content                                                                             | Gap: the size and overflow unit tests assert presence only, and no story renders a long label; slot order and block size are visible only in the rendered fixtures, and the ellipsis has no check.         | `audit:Token/layout`   |
+| FR3, FR4, FR6, AR1 | `Token.test.tsx` link, clickable, and link-with-remove suites                          | Link, clickable, link and remove, modified and middle clicks                                            | Nesting the Remove button, firing the token action from Remove, or losing delegation fails. Gap: no test asserts that `onClick` is dropped with `href`.                                                    | `audit:Token/behavior` |
+| FR5, AR5           | `Token.test.tsx` disabled tests                                                        | Disabled clickable with remove; disabled static; disabled link with and without remove                  | A native `disabled`, a lost tab stop, a disabled link with a destination, an unreflected disabled state, or a fired callback fails.                                                                        | `audit:Token/a11y`     |
+| AR2, AR3, AR7      | `Token.test.tsx` accessibility suite                                                   | Remove name, hidden label, description                                                                  | A missing remove name, lost hidden label, or missing description fails. Gap: no test asserts the link structure's content-derived name.                                                                    | `audit:Token/a11y`     |
+| AR6                | `TokenRemoveTarget.a11y.chromium.spec.ts`                                              | Pre-set filter tokens (default size), LTR and RTL                                                       | A remove target that misses its X edge or swallows a label press fails in real Chromium. Gap: the `sm` clipping is not covered.                                                                            | `audit:Token/a11y`     |
+| FR8                | `Token.test.tsx` custom-color test; `extensibleAxes.test.ts`; `themingTargets.test.ts` | Theme-added color; map wiring                                                                           | Dropping the `color` reflection fails. Gap: no test asserts `data-size` or any tone's paint; those are visible only in `Token.stories.tsx`.                                                                | `audit:Token/theming`  |
+| FR9, AR4           | `Token.stories.tsx` clickable and link fixtures in a browser                           | Hover, press, keyboard focus on the token                                                               | Gap: no automated check covers overlays or indicators, and no story renders a clickable or link token with Remove, so the double indicator on Remove has no fixture.                                       | `audit:Token/design`   |
+| PR1                | Source review                                                                          | Every structure                                                                                         | Gap: no automated check fails if Token adds a per-token listener, observer, or timer.                                                                                                                      | `audit:Token/behavior` |
+| AR2, AR3, AR5, AR7 | Accessibility-tree evidence (`spec:AST-009` FR3)                                       | Every structure; hidden label; description; disabled                                                    | Gap: no accessibility-tree check proves the computed names, the hidden-label name, the description, or the disabled state; the unit tests assert DOM attributes only.                                      | `audit:Token/a11y`     |
 
 ## Decision log
 

package/src/Token/Token.tsx

@@ -299,6 +299,8 @@ export function Token({
   className,
   style,
   'data-testid': testId,
+  'aria-labelledby': ariaLabelledBy,
+  'aria-describedby': ariaDescribedBy,
   ref,
   ...rest
 }: TokenProps) {
@@ -342,6 +344,14 @@ export function Token({
     </>
   );
 
+  // Naming inputs reach the element that owns the token's action: the inner
+  // button of a clickable token, otherwise the root
+  // (architecture:public-component-api INV5).
+  const labellingProps = {
+    'aria-labelledby': ariaLabelledBy,
+    'aria-describedby': ariaDescribedBy,
+  };
+
   const sharedProps = {
     'data-testid': testId,
     ...(isLabelHidden ? {'aria-label': label} : {}),
@@ -380,6 +390,7 @@ export function Token({
           style,
         )}
         {...rest}
+        {...labellingProps}
         {...disabledInteractionProps(rest.onKeyDown)}
         {...sharedProps}>
         {content}
@@ -413,6 +424,7 @@ export function Token({
             style,
           )}
           {...rest}
+          {...labellingProps}
           {...(isDisabled ? {'aria-disabled': true} : {})}
           {...sharedProps}>
           {content}
@@ -466,6 +478,7 @@ export function Token({
           style,
         )}
         {...rest}
+        {...labellingProps}
         {...sharedProps}
       />
     );
@@ -509,6 +522,7 @@ export function Token({
         <button
           type="button"
           onClick={effectiveOnClick}
+          {...labellingProps}
           aria-disabled={isDisabled || undefined}
           {...(isDisabled ? disabledInteractionProps() : null)}
           {...stylex.props(styles.invisibleButton)}>
@@ -546,6 +560,7 @@ export function Token({
         style,
       )}
       {...rest}
+      {...labellingProps}
       {...sharedProps}>
       {content}
     </span>

package/src/Tokenizer/Tokenizer.tsx

@@ -91,6 +91,7 @@ import {joinAriaIDs} from '../utils/inputAria';
 import {themeProps} from '../utils/themeProps';
 import {useTranslator} from '../i18n';
 import type {TokenizerBottomSheetProps} from './TokenizerBottomSheet';
+import {useResolvedRequired} from '../hooks/useResolvedRequired';
 
 // Re-export status types for convenience
 export type {
@@ -760,6 +761,7 @@ export function Tokenizer<T extends SearchableItem>({
   'aria-labelledby': ariaLabelledByProp,
   ...restProps
 }: TokenizerWithPresentationProps<T>): React.JSX.Element {
+  const isEffectivelyRequired = useResolvedRequired({isRequired, isOptional});
   const {rest, container} = useFieldInputStyling('Tokenizer', restProps, {
     containerXstyle,
     containerClassName,
@@ -1421,6 +1423,14 @@ export function Tokenizer<T extends SearchableItem>({
                 .join(' ') || undefined
             }
             onChangeQuery={onChangeQuery}
+            // 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']}
             __queryEntries={createEntries}
             debounceMs={debounceMs}
             onKeyDown={handleKeyDown}

package/src/Typeahead/BaseTypeahead.tsx

@@ -1091,15 +1091,30 @@ export const BaseTypeahead = function BaseTypeahead<T extends SearchableItem>({
       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();
           }
@@ -1170,6 +1185,7 @@ export const BaseTypeahead = function BaseTypeahead<T extends SearchableItem>({
       query,
       minQueryLength,
       performBootstrap,
+      performSearch,
       externalOnKeyDown,
     ],
   );

package/src/Typeahead/Typeahead.tsx

@@ -76,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,
@@ -420,6 +421,7 @@ export function Typeahead<T extends SearchableItem>({
   'aria-labelledby': ariaLabelledByProp,
   ...restProps
 }: TypeaheadProps<T>) {
+  const isEffectivelyRequired = useResolvedRequired({isRequired, isOptional});
   const {rest, container} = useFieldInputStyling('Typeahead', restProps, {
     containerXstyle,
     containerClassName,
@@ -431,6 +433,7 @@ export function Typeahead<T extends SearchableItem>({
   const inputId = idProp ?? generatedInputId;
   const inputLabelId = useId();
   const fieldLabelId = useId();
+  const tokenValueId = useId();
   const descriptionId = useId();
   const statusMessageId = useId();
   const inputGroup = useInputGroup();
@@ -663,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
@@ -695,6 +717,14 @@ export function Typeahead<T extends SearchableItem>({
                     .join(' ') || undefined
                 }
                 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}
@@ -745,7 +775,8 @@ export function Typeahead<T extends SearchableItem>({
       isLabelHidden={isLabelHidden}
       description={description}
       inputID={inputId}
-      labelID={ariaLabelledByProp != null ? fieldLabelId : undefined}
+      // Always set: the value token's name references the field label.
+      labelID={fieldLabelId}
       descriptionID={description ? descriptionId : undefined}
       isOptional={isOptional}
       isRequired={isRequired}

package/src/i18n/useListFormatter.ts

@@ -0,0 +1,42 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file useListFormatter.ts
+ * @input InternationalizationContext (via use())
+ * @output A memoized function that joins strings as a list in the active locale
+ * @position Internal provider-aware list-formatting hook
+ *   (architecture:internationalization INV8). Components that show several
+ *   catalog messages as one string join them here rather than at the call
+ *   site (INV1a). Not exported from the i18n barrel. Raw Intl.ListFormat
+ *   construction stays centralized in this hook.
+ *
+ * Falls back to `'en'` when called outside a provider, matching the
+ * useTranslator/useCollator fallback.
+ *
+ * SYNC: When modified, update:
+ * - /packages/core/src/i18n/__tests__/useListFormatter.test.tsx
+ * - /internal/eslint-plugin-astryx/no-raw-intl-locale.js
+ */
+
+import {use, useMemo} from 'react';
+import {InternationalizationContext} from './InternationalizationContext';
+
+/**
+ * Returns a function that joins items as a narrow conjunction list (`a, b, c`
+ * in English) for the active provider locale, memoized while the locale is
+ * unchanged. The narrow conjunction separates items in every shipped locale,
+ * including whole sentences, where a unit list runs them together in some
+ * (no separator in zh-CN, only a space in ja-JP).
+ */
+export function useListFormatter(): (items: ReadonlyArray<string>) => string {
+  const ctx = use(InternationalizationContext);
+  return useMemo(() => {
+    const format = new Intl.ListFormat(ctx.locale, {
+      type: 'conjunction',
+      style: 'narrow',
+    });
+    return (items: ReadonlyArray<string>) => format.format(items);
+  }, [ctx.locale]);
+}

package/dist/Item/ItemMarkerColumns.a11y.chromium.spec.d.ts

@@ -1,2 +0,0 @@
-export {};
-//# sourceMappingURL=ItemMarkerColumns.a11y.chromium.spec.d.ts.map