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

package/src/Toast/ToastViewport.tsx

@@ -15,7 +15,6 @@
  */
 
 import {
-  isValidElement,
   useCallback,
   useEffect,
   useLayoutEffect,
@@ -28,6 +27,7 @@ import {createPortal} from 'react-dom';
 import * as stylex from '@stylexjs/stylex';
 import {spacingVars, durationVars, easeVars} from '../theme/tokens.stylex';
 import {mergeProps} from '../utils';
+import {getNodeText} from '../utils/getNodeText';
 import {INTERACTIVE_SELECTORS} from '../hooks/useClickableContainer';
 import {useAnnounce} from '../hooks/useAnnounce';
 import {layerTextReset} from '../Layer/layerTextReset.stylex';
@@ -172,29 +172,6 @@ const styles = stylex.create({
   },
 });
 
-// Flatten a toast's rendered content (title, description, etc.) to the plain
-// text that should be spoken by a screen reader. Only text is announced —
-// interactive endContent is deliberately excluded (it is reachable via F6).
-function getNodeText(node: ReactNode): string {
-  if (node == null || typeof node === 'boolean') {
-    return '';
-  }
-  if (typeof node === 'string') {
-    return node;
-  }
-  if (typeof node === 'number') {
-    return String(node);
-  }
-  if (Array.isArray(node)) {
-    return node.map(getNodeText).filter(Boolean).join(' ');
-  }
-  if (isValidElement(node)) {
-    const {children} = node.props as {children?: ReactNode};
-    return getNodeText(children);
-  }
-  return '';
-}
-
 export interface ToastViewportProps {
   position?: ToastPosition;
   /** Maximum number of visible toasts. @default 5 */
@@ -344,6 +321,19 @@ export function ToastViewport({
   const [exitingIds, setExitingIds] = useState<Set<string>>(new Set());
   const toastsRef = useRef(toasts);
   toastsRef.current = toasts;
+  // The list as last rendered: addToast moves toastsRef ahead of it within
+  // a batch, so this tells a rendered toast from one raised since.
+  const renderedToastsRef = useRef(toasts);
+  renderedToastsRef.current = toasts;
+  // Read by removeToast, which keeps one identity across renders.
+  const maxVisibleRef = useRef(maxVisible);
+  maxVisibleRef.current = maxVisible;
+  // Rendered entries a repeat has replaced in this batch: still found by a
+  // dismissal in the same handler, as before the swap. One replaced before it
+  // rendered was never shown and reports no onHide (Toast.spec.md FR3). A
+  // render starts a new batch.
+  const replacedRef = useRef<Map<string, ToastEntry>>(new Map());
+  replacedRef.current.clear();
 
   const viewportRef = useRef<HTMLDivElement>(null);
   // Toast ids whose exit has begun — guards onHide from double-firing (see
@@ -352,10 +342,13 @@ export function ToastViewport({
   // Toasts dispatched since the last commit, by id: a dismiss() called
   // before the toast first renders still finds it (and its onHide).
   const pendingEntriesRef = useRef<Map<string, ToastEntry>>(new Map());
-  // The element that was focused before the user jumped into the viewport
-  // (via F6). Used to restore focus once all toasts are dismissed so focus
-  // never falls to <body>.
+  // The element that was focused before focus entered the viewport, by F6,
+  // Tab or a click. Used to restore focus once all toasts are dismissed so
+  // focus never falls to <body> (FR10).
   const prevFocusRef = useRef<HTMLElement | null>(null);
+  // The element focus last reached inside the viewport's React tree,
+  // portaled toast content included.
+  const lastFocusedWithinRef = useRef<EventTarget | null>(null);
   // When a toast is dismissed while focus lives inside it, we need to move
   // focus to a sensible neighbor after that toast unmounts. This holds the
   // id of the toast whose removal should trigger a focus handoff.
@@ -410,6 +403,10 @@ export function ToastViewport({
   const addToast = useCallback(
     (entry: ToastEntry) => {
       const {uniqueID, collisionBehavior = 'overwrite'} = entry.options;
+      // A toast holds its uniqueID until it unmounts, leaving included
+      // (Toast.spec.md FR8): an overwrite replaces it in place, and an ignored
+      // namesake is dropped.
+      const holdsUniqueID = (t: ToastEntry) => t.options.uniqueID === uniqueID;
       // Resolve an ignored collision synchronously against the committed list
       // so a suppressed toast is neither shown nor announced. The remaining
       // announce + setToasts run outside the setToasts updater, which React may
@@ -417,16 +414,46 @@ export function ToastViewport({
       if (
         uniqueID &&
         collisionBehavior === 'ignore' &&
-        toastsRef.current.some(t => t.options.uniqueID === uniqueID)
+        toastsRef.current.some(holdsUniqueID)
       ) {
         return;
       }
+      // Only text is announced; interactive endContent is reachable via F6.
       const text = getNodeText(entry.options.body);
       if (text) {
         // Error toasts map to the assertive region (role="alert"); everything
         // else to the polite region (role="status") — mirrors Toast.tsx.
         announce(text, entry.options.type === 'error' ? 'assertive' : 'polite');
       }
+      // A leaving toast that a new one pushes out of the visible window can no
+      // longer finish its exit on screen, so it leaves the list now (it
+      // already reported onHide); otherwise its row would come back collapsed
+      // when the window reached it again, holding a slot and the landmark.
+      const committed = toastsRef.current;
+      const overwritten = uniqueID ? committed.find(holdsUniqueID) : undefined;
+      if (overwritten && renderedToastsRef.current.includes(overwritten)) {
+        replacedRef.current.set(overwritten.id, overwritten);
+      }
+      const projected = overwritten
+        ? committed.map(t => (t === overwritten ? entry : t))
+        : [...committed, entry];
+      // `maxVisible={0}` shows every toast (FR7): nothing leaves the window.
+      const firstVisible = maxVisible > 0 ? projected.length - maxVisible : 0;
+      const cutIds = new Set(
+        projected
+          .filter((t, i) => i < firstVisible && exitingIdsRef.current.has(t.id))
+          .map(t => t.id),
+      );
+      if (cutIds.size > 0) {
+        // Gone from every list, so a later dismissal reports nothing more.
+        for (const id of cutIds) {
+          exitingIdsRef.current.delete(id);
+          pendingEntriesRef.current.delete(id);
+        }
+        setExitingIds(prev => new Set([...prev].filter(id => !cutIds.has(id))));
+      }
+      // Later toasts in the same batch see this one before the next render.
+      toastsRef.current = projected.filter(t => !cutIds.has(t.id));
       const pending = pendingEntriesRef.current;
       if (uniqueID) {
         // An overwrite replaces a toast that has not rendered yet too.
@@ -442,17 +469,17 @@ export function ToastViewport({
       // dismissed. Its settled id is dropped by the prune below, which covers
       // every silent exit with one rule rather than one branch per path.
       setToasts(prev => {
-        if (uniqueID) {
-          const existing = prev.find(t => t.options.uniqueID === uniqueID);
-          if (existing) {
-            // An ignored collision already returned above; overwrite in place.
-            return prev.map(t => (t.options.uniqueID === uniqueID ? entry : t));
-          }
-        }
-        return [...prev, entry];
+        // The cut entries go first, then the choice the projection above made
+        // (by identity): a dismissal in the same handler may have marked the
+        // replaced namesake as leaving since, which must not turn the
+        // overwrite into an append. An ignored collision already returned.
+        const kept = prev.filter(t => !cutIds.has(t.id));
+        return overwritten && kept.includes(overwritten)
+          ? kept.map(t => (t === overwritten ? entry : t))
+          : [...kept, entry];
       });
     },
-    [announce],
+    [announce, maxVisible],
   );
 
   const removeToast = useCallback((id: string, reason: ToastDismissReason) => {
@@ -465,6 +492,7 @@ export function ToastViewport({
     }
     const entry =
       toastsRef.current.find(t => t.id === id) ??
+      replacedRef.current.get(id) ??
       pendingEntriesRef.current.get(id);
     if (entry == null) {
       // Already gone: nothing to hide or report.
@@ -485,29 +513,54 @@ export function ToastViewport({
       dismissedNode.contains(active)
     ) {
       focusHandoffIdRef.current = id;
-      // Pick the neighbor to receive focus while the DOM is still intact:
-      // prefer the next toast, then the previous, else restore.
-      const remaining = toastsRef.current.filter(t => t.id !== id);
-      if (remaining.length > 0) {
-        const dismissedIndex = toastsRef.current.findIndex(t => t.id === id);
-        const next =
-          toastsRef.current[dismissedIndex + 1] ??
-          toastsRef.current[dismissedIndex - 1];
-        pendingFocusRef.current = next ? next.id : 'restore';
-      } else {
-        pendingFocusRef.current = 'restore';
-      }
+      // Pick the toast to receive focus while the DOM is still intact: the
+      // nearest one after it, then before it, that shows once it is gone
+      // (FR10), else restore. The list may already run ahead of the render
+      // within this handler: a toast a repeat replaced has left it, and the
+      // replacement holds its place, so the neighbors are taken around the
+      // replacement, which takes focus only when no neighbor shows.
+      const list = toastsRef.current;
+      const {uniqueID} = entry.options;
+      const ownIndex = list.findIndex(t => t.id === id);
+      const placeIndex =
+        ownIndex >= 0 || uniqueID == null
+          ? ownIndex
+          : list.findIndex(t => t.options.uniqueID === uniqueID);
+      const remaining = list.filter(t => t.id !== id);
+      const max = maxVisibleRef.current;
+      const shown = new Set(max > 0 ? remaining.slice(-max) : remaining);
+      const isShown = (t: ToastEntry) => shown.has(t);
+      const replacement = ownIndex < 0 ? list[placeIndex] : undefined;
+      const next =
+        placeIndex < 0
+          ? undefined
+          : (list.slice(placeIndex + 1).find(isShown) ??
+            list.slice(0, placeIndex).reverse().find(isShown) ??
+            (replacement != null && isShown(replacement)
+              ? replacement
+              : undefined));
+      pendingFocusRef.current = next ? next.id : 'restore';
     }
-    if (dismissedNode == null) {
-      // No row is mounted for it: it is hidden past `maxVisible`, or it has
-      // not rendered yet. Nothing animates out, so it leaves the list now.
+    // A toast this handler has already pushed out of the visible window still
+    // has its row now, but loses it when the batch renders.
+    const index = toastsRef.current.findIndex(t => t.id === id);
+    const isPushedOut =
+      maxVisibleRef.current > 0 &&
+      index >= 0 &&
+      index < toastsRef.current.length - maxVisibleRef.current;
+    if (dismissedNode == null || isPushedOut) {
+      // No row is mounted for it, or none will be: it is hidden past
+      // `maxVisible`, or it has not rendered yet. Nothing animates out, so it
+      // leaves the list now.
       // Waiting for its row to finish exiting would keep it forever: when it
       // surfaced, its row would mount already collapsed, with no transition
       // left to end, and hold a visible slot as an empty row.
       // It leaves the committed list now too, so a second dismissal before
-      // the next render finds nothing to report.
+      // the next render finds nothing to report (nor does a toast a repeat
+      // replaced in this batch).
       exitingIdsRef.current.delete(id);
       pendingEntriesRef.current.delete(id);
+      replacedRef.current.delete(id);
       toastsRef.current = toastsRef.current.filter(t => t.id !== id);
       setToasts(prev => prev.filter(t => t.id !== id));
       return;
@@ -731,6 +784,21 @@ export function ToastViewport({
   const viewport = (
     <div
       ref={viewportRef}
+      onFocus={event => {
+        // Focus entering from outside, however it came, is where a dismissal
+        // of the last toast returns it. React also delivers focus inside a
+        // toast's portaled content here, so focus coming back from the last
+        // element focused within is not an entry, though it sits outside
+        // this element.
+        const from = event.relatedTarget;
+        const fromWithin =
+          from === lastFocusedWithinRef.current ||
+          (from instanceof Node && event.currentTarget.contains(from));
+        lastFocusedWithinRef.current = event.target;
+        if (from instanceof HTMLElement && !fromWithin) {
+          prevFocusRef.current = from;
+        }
+      }}
       role={hasToasts ? 'region' : undefined}
       aria-label={hasToasts ? t('@astryx.toast.viewport') : undefined}
       tabIndex={hasToasts ? -1 : undefined}

package/src/ToggleButton/ToggleButton.test.tsx

@@ -656,6 +656,33 @@ describe('ToggleButtonGroup (single)', () => {
 // ToggleButtonGroup — Multiple mode
 // =============================================================================
 
+describe('ToggleButtonGroup host props (public-component-api INV5)', () => {
+  it('passes className, style, id, aria-* and data-* to the group, keeping its own role and name', () => {
+    render(
+      <ToggleButtonGroup
+        label="Alignment"
+        value={null}
+        onChange={() => {}}
+        className="toolbar-group"
+        style={{marginTop: 8}}
+        id="alignment"
+        aria-describedby="alignment-hint"
+        data-section="format"
+        // A caller role or name never replaces the group's own.
+        {...{role: 'radiogroup', 'aria-label': 'Ignored'}}>
+        <ToggleButton value="left" label="Left" />
+      </ToggleButtonGroup>,
+    );
+    const group = screen.getByRole('group', {name: 'Alignment'});
+    expect(group).toHaveClass('toolbar-group');
+    expect(group).toHaveClass('astryx-toggle-button-group');
+    expect(group).toHaveStyle({marginTop: '8px'});
+    expect(group).toHaveAttribute('id', 'alignment');
+    expect(group).toHaveAttribute('aria-describedby', 'alignment-hint');
+    expect(group).toHaveAttribute('data-section', 'format');
+  });
+});
+
 describe('ToggleButtonGroup (multiple)', () => {
   function MultipleGroup() {
     const [value, setValue] = useState<string[]>(['bold']);

package/src/ToggleButton/ToggleButtonGroup.tsx

@@ -23,6 +23,7 @@ import {createLayerScopedContext as createContext} from '../Layer/layerScopedCon
 import * as stylex from '@stylexjs/stylex';
 import {spacingVars} from '../theme/tokens.stylex';
 import type {ButtonSize} from '../Button';
+import type {BaseProps} from '../BaseProps';
 import {mergeProps} from '../utils';
 import type {StyleXStyles} from '@stylexjs/stylex';
 import {themeProps} from '../utils/themeProps';
@@ -74,7 +75,15 @@ const styles = stylex.create({
 // Props — Discriminated Union
 // =============================================================================
 
-interface ToggleButtonGroupBaseProps {
+/**
+ * Host props reach the group element (`architecture:public-component-api`
+ * INV5): `className`, `style`, `id`, `aria-*`, `data-*` and handlers. The group
+ * keeps its own `role`, `aria-label` and theme target.
+ */
+interface ToggleButtonGroupBaseProps extends Omit<
+  BaseProps<HTMLDivElement>,
+  'onChange' | 'defaultValue' | 'role' | 'aria-label'
+> {
   /** Toggle button children. */
   children: ReactNode;
 
@@ -184,7 +193,14 @@ export function ToggleButtonGroup(props: ToggleButtonGroupProps): ReactNode {
     size,
     isDisabled = false,
     xstyle,
+    className,
+    style,
     'data-testid': testId,
+    // Read through `props` below, where the union narrows them by `type`.
+    type: _type,
+    value: _value,
+    onChange: _onChange,
+    ...hostProps
   } = props;
 
   const isMultiple = props.type === 'multiple';
@@ -225,6 +241,7 @@ export function ToggleButtonGroup(props: ToggleButtonGroupProps): ReactNode {
   return (
     <ToggleButtonGroupContext value={contextValue}>
       <div
+        {...hostProps}
         role="group"
         aria-label={label}
         data-testid={testId}
@@ -235,6 +252,8 @@ export function ToggleButtonGroup(props: ToggleButtonGroupProps): ReactNode {
             orientation === 'vertical' && styles.vertical,
             xstyle,
           ),
+          className,
+          style,
         )}>
         {children}
       </div>

package/src/Token/Token.doc.mjs

@@ -88,7 +88,7 @@ export const docs = {
     },
   ],  theming: {
     targets: [
-      {className: 'astryx-token', visualProps: ['color', 'size']},
+      {className: 'astryx-token', visualProps: ['color', 'size'], states: ['disabled']},
     ],
   },
   usage: {
@@ -193,7 +193,7 @@ export const docsZh = {
   ],
   theming: {
     targets: [
-      {className: 'astryx-token', visualProps: ['color', 'size']},
+      {className: 'astryx-token', visualProps: ['color', 'size'], states: ['disabled']},
     ],
   },
   usage: {

package/src/Token/Token.spec.md

@@ -41,7 +41,7 @@ system_specs: [spec:AST-005, spec:AST-009, spec:AST-085]
 | Behavior                | `href` renders a link, `onClick` (or an enclosing trigger context) renders a container whose inner button wraps the label, and `onRemove` adds a separate remove button beside, never inside, them.           |
 | End-user impact         | Pointer users can activate the whole chip; keyboard and screen-reader users reach the chip's action and its remove action as separate, named controls.                                                        |
 | Builder impact          | None; the record describes shipped behavior.                                                                                                                                                                  |
-| Compatibility/readiness | Released behavior recorded as current; no API, default, or output changes. Six implementation gaps are listed under Current-state impact.                                                                     |
+| Compatibility/readiness | Released behavior recorded as current; no API, default, or output changes. Four implementation gaps are listed under Current-state impact.                                                                    |
 | Review checks           | Reject a remove button nested in the link or the inner button, a remove target smaller than 24 by 24 CSS pixels, a native `disabled` attribute, or a token that navigates around the shared destination rule. |
 | Governing rules         | `family:navigation-destinations`; `spec:AST-005`; `spec:AST-085/FR1,FR2,FR5`; `architecture:public-component-api/INV5,INV6,INV8`; `architecture:component-theming-surface/INV6,INV14`.                        |
 
@@ -66,10 +66,6 @@ Consumer migration instructions belong in consumer docs and release notes.
 
 ## Current-state impact
 
-- **Disabled link token (FR5, AR5).** A disabled token with `href` and no
-  `onClick` renders a static `span`: it loses its tab stop and exposes no
-  disabled state, where `spec:AST-085` FR1 and FR5 keep a disabled control
-  focusable and announced.
 - **`onClick` with `href` (FR3).** When a token renders as a link, a supplied
   `onClick` is not attached or called, where
   `architecture:public-component-api` INV5 preserves accepted event inputs.
@@ -77,10 +73,6 @@ Consumer migration instructions belong in consumer docs and release notes.
   static, clickable, or link-and-remove token puts `aria-label` on a `span` that
   has no role, where WAI-ARIA 1.2 prohibits naming the generic role. The
   visually hidden label text still reaches assistive technology.
-- **Disabled state not reflected on the target (FR5).** No structure reflects
-  `isDisabled` on the `token` target, so a theme cannot style the disabled state
-  through it, where `architecture:component-theming-surface` INV6 keeps state on
-  the owning target.
 - **Two focus indicators on Remove (AR4).** In clickable and link-and-remove
   tokens, keyboard focus on the Remove button draws the token's outline and the
   button's own, where `architecture:interaction-modality` INV3 allows one
@@ -116,29 +108,29 @@ Consumer migration instructions belong in consumer docs and release notes.
 
 ## Public concepts
 
-| Concept          | Closed values or states                                                                                          | Meaning                                                        | Availability by variant/orientation/state                                       | Default   | Owner             | Stability | Invalid-value behavior                                                                                                                         |
-| ---------------- | ---------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------- | ------------------------------------------------------------------------------- | --------- | ----------------- | --------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
-| Structure        | static; clickable; link; link-and-remove                                                                         | Which element owns the token's own action (FR2–FR4).           | Resolved from `href`, `onClick`, `isDisabled`, and an enclosing trigger context | static    | `component:Token` | Stable    | A disabled link token stays a focusable control that exposes its disabled state (FR5); today it resolves to the static structure, the FR5 gap. |
-| Size             | `sm`, `md`, `lg`                                                                                                 | Selects the block size.                                        | All structures                                                                  | `md`      | `component:Token` | Stable    | TypeScript rejects other values.                                                                                                               |
-| Tone (`color`)   | `default`, `red`, `orange`, `yellow`, `green`, `teal`, `cyan`, `blue`, `purple`, `pink`, `gray`; theme additions | Selects fill and text color.                                   | All structures                                                                  | `default` | `component:Token` | Stable    | A theme-added value is reflected on `token` and receives no component fill or color; TypeScript rejects unregistered values.                   |
-| Removable        | present when `onRemove` is supplied; absent                                                                      | Adds the Remove button after the label and end content.        | All structures                                                                  | absent    | `component:Token` | Stable    | —                                                                                                                                              |
-| Label visibility | visible; visually hidden                                                                                         | Hides the label visually while keeping it as the token's name. | All structures                                                                  | visible   | `component:Token` | Stable    | —                                                                                                                                              |
-| Disabled         | enabled; disabled                                                                                                | Blocks every token and remove action.                          | All structures                                                                  | enabled   | `component:Token` | Stable    | —                                                                                                                                              |
+| Concept          | Closed values or states                                                                                          | Meaning                                                        | Availability by variant/orientation/state                                       | Default   | Owner             | Stability | Invalid-value behavior                                                                                                       |
+| ---------------- | ---------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------- | ------------------------------------------------------------------------------- | --------- | ----------------- | --------- | ---------------------------------------------------------------------------------------------------------------------------- |
+| Structure        | static; clickable; link; link-and-remove                                                                         | Which element owns the token's own action (FR2–FR4).           | Resolved from `href`, `onClick`, `isDisabled`, and an enclosing trigger context | static    | `component:Token` | Stable    | A disabled link token stays a focusable control that exposes its disabled state (FR5).                                       |
+| Size             | `sm`, `md`, `lg`                                                                                                 | Selects the block size.                                        | All structures                                                                  | `md`      | `component:Token` | Stable    | TypeScript rejects other values.                                                                                             |
+| Tone (`color`)   | `default`, `red`, `orange`, `yellow`, `green`, `teal`, `cyan`, `blue`, `purple`, `pink`, `gray`; theme additions | Selects fill and text color.                                   | All structures                                                                  | `default` | `component:Token` | Stable    | A theme-added value is reflected on `token` and receives no component fill or color; TypeScript rejects unregistered values. |
+| Removable        | present when `onRemove` is supplied; absent                                                                      | Adds the Remove button after the label and end content.        | All structures                                                                  | absent    | `component:Token` | Stable    | —                                                                                                                            |
+| Label visibility | visible; visually hidden                                                                                         | Hides the label visually while keeping it as the token's name. | All structures                                                                  | visible   | `component:Token` | Stable    | —                                                                                                                            |
+| Disabled         | enabled; disabled                                                                                                | Blocks every token and remove action.                          | All structures                                                                  | enabled   | `component:Token` | Stable    | —                                                                                                                            |
 
 ## Behavioral and layout contract
 
-| ID   | Invariant                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        | Basis                    |
-| ---- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------ |
-| FR1  | Content renders in logical inline order: Icon, Label, End content, Remove button. The root is inline-flex with `--spacing-1` gaps, inline padding `--spacing-2`, `--radius-inner` corners, `--text-supporting-size` type at `--font-weight-medium`, and a minimum block size of `--size-element-sm`, `-md`, or `-lg` minus 8px for `sm`, `md`, and `lg`. That size grows with a set text size under `spec:AST-102` FR4; today's fixed size is a gap.                                                                                                                                                                                                                                                             | Current source and tests |
-| FR2  | With no `href`, `onClick`, or enclosing trigger context, the token is a static `span` holding its content directly.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              | Current source and tests |
-| FR3  | With an enabled `href` and no `onRemove`, the token root is the shared link component carrying the destination; it takes the root ref, passthrough props, and its own focus-visible outline. A supplied `onClick`, as an accepted event input, reaches the element that owns the contract (`architecture:public-component-api` INV5). Implementation gap: in both link structures `onClick` is not attached or called (Current-state impact).                                                                                                                                                                                                                                                                    | Current source and tests |
-| FR4  | With `onClick`, or an enclosing trigger context that resolves the token to a button, the root is a `span` container holding an inner `button` that wraps only the Label and calls `onClick`; a click on the container outside any nested button or link also calls `onClick`. With an enabled `href` and `onRemove`, the container instead holds an inner link wrapping only the Label; a plain click on the surface outside the Remove button follows that link, and a Cmd/Ctrl-click or middle click on the surface opens it in a new tab. A caller `onMouseUp` on the link-and-remove container runs before its delegation.                                                                                   | Current source and tests |
-| FR5  | A disabled token renders at half opacity with pointer events off and fires neither `onClick` nor `onRemove` from pointer, Enter, or Space; inner and Remove buttons stay focusable with `aria-disabled="true"` and never receive native `disabled`. A disabled control keeps its tab stop and exposes its disabled state (`spec:AST-085` FR1, FR5), and the disabled state is reflected on the owning target (`architecture:component-theming-surface` INV6). Implementation gap: a disabled token with `href` and no `onClick` or trigger context renders as a static `span` with no tab stop and no disabled state, and no structure reflects the disabled state on the `token` target (Current-state impact). | Current source and tests |
-| FR6  | `onRemove` renders a `type="button"` Remove button holding a close glyph; a click stops propagation before `onRemove` runs, so it never triggers the token's own action or link. The button is a sibling of the inner button or link, never nested in it.                                                                                                                                                                                                                                                                                                                                                                                                                                                        | Current source and tests |
-| 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 |
+| ID   | Invariant                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 | Basis                    |
+| ---- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------ |
+| FR1  | Content renders in logical inline order: Icon, Label, End content, Remove button. The root is inline-flex with `--spacing-1` gaps, inline padding `--spacing-2`, `--radius-inner` corners, `--text-supporting-size` type at `--font-weight-medium`, and a minimum block size of `--size-element-sm`, `-md`, or `-lg` minus 8px for `sm`, `md`, and `lg`. That size grows with a set text size under `spec:AST-102` FR4; today's fixed size is a gap.                                                                                                                                                                                                                      | Current source and tests |
+| FR2  | With no `href`, `onClick`, or enclosing trigger context, the token is a static `span` holding its content directly.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       | Current source and tests |
+| FR3  | With an enabled `href` and no `onRemove`, the token root is the shared link component carrying the destination; it takes the root ref, passthrough props, and its own focus-visible outline. A supplied `onClick`, as an accepted event input, reaches the element that owns the contract (`architecture:public-component-api` INV5). Implementation gap: in both link structures `onClick` is not attached or called (Current-state impact).                                                                                                                                                                                                                             | Current source and tests |
+| FR4  | With `onClick`, or an enclosing trigger context that resolves the token to a button, the root is a `span` container holding an inner `button` that wraps only the Label and calls `onClick`; a click on the container outside any nested button or link also calls `onClick`. With an enabled `href` and `onRemove`, the container instead holds an inner link wrapping only the Label; a plain click on the surface outside the Remove button follows that link, and a Cmd/Ctrl-click or middle click on the surface opens it in a new tab. A caller `onMouseUp` on the link-and-remove container runs before its delegation.                                            | Current source and tests |
+| FR5  | A disabled token renders at half opacity with pointer events off and fires neither `onClick` nor `onRemove` from pointer, Enter, or Space; inner and Remove buttons stay focusable with `aria-disabled="true"` and never receive native `disabled`. A disabled control keeps its tab stop and exposes its disabled state (`spec:AST-085` FR1, FR5), and the disabled state is reflected on the owning target (`architecture:component-theming-surface` INV6). A disabled token with `href` and no `onClick` or trigger context renders a focusable link with `aria-disabled="true"` and no `href`, and every structure reflects the disabled state on the `token` target. | Current source and tests |
+| FR6  | `onRemove` renders a `type="button"` Remove button holding a close glyph; a click stops propagation before `onRemove` runs, so it never triggers the token's own action or link. The button is a sibling of the inner button or link, never nested in it.                                                                                                                                                                                                                                                                                                                                                                                                                 | Current source and tests |
+| 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, 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
 
@@ -150,24 +142,24 @@ 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
 
 - **ORD1 — Structure.** Enabled `href` → `onClick` → enclosing trigger context →
-  static. `onRemove` with an enabled `href` selects the link-and-remove
-  container. A disabled `href` is skipped, so a disabled link token falls
-  through to `onClick`, a trigger context, or static; the static fall-through is
-  the FR5 gap.
-- **ORD2 — Root attributes.** Component class and `data-color`/`data-size` →
+  disabled `href` → static. `onRemove` with an `href` that wins selects the
+  link-and-remove container. A disabled `href` yields to `onClick` and a
+  trigger context; otherwise it keeps the link structure, rendered disabled
+  (FR5).
+- **ORD2 — Root attributes.** Component class and `data-color`/`data-size`/`data-disabled` →
   component styles → `xstyle` → `className` → `style` → caller props → `data-testid`, hidden-label
   `aria-label`, and `aria-description`. A hidden label's `aria-label` replaces
   a caller `aria-label`.
@@ -186,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.
@@ -204,9 +197,7 @@ Consumer migration instructions belong in consumer docs and release notes.
   those structures shows the container outline and the button's own.
 - **AR5 — Disabled.** A disabled token's controls stay focusable, expose
   `aria-disabled="true"`, and ignore pointer, Enter, and Space (`spec:AST-085`
-  FR1, FR2, FR5); the inner and Remove buttons do. Implementation gap: a
-  disabled link token renders as a static `span` with no tab stop and no
-  disabled state.
+  FR1, FR2, FR5), the disabled link included.
 - **AR6 — Remove target size.** The Remove button's glyph box is 16 by 16 CSS
   pixels and its hit area extends 4 pixels on every side to 24 by 24 at `md`
   and `lg`, meeting WCAG 2.2 2.5.8, while a press on the adjacent label still
@@ -224,7 +215,7 @@ Consumer migration instructions belong in consumer docs and release notes.
 | End content      | Optional trailing content such as a count or status dot.     | Current source and docs  | Supporting     | FR1                |
 | Remove button    | A trailing close control that dismisses the token.           | Current source and docs  | Supporting     | FR6, AR1, AR2, AR6 |
 
-Theming: the root is the single `token` target and reflects `color` and `size`.
+Theming: the root is the single `token` target and reflects `color`, `size`, and the disabled state.
 The Label, End content, and Icon add no targets; the Remove button inherits the
 token's text color.
 
@@ -234,7 +225,7 @@ token's text color.
   for both link structures, including delegated surface clicks; Token adopts
   them through the shared link component and clickable-container delegation.
 - `spec:AST-085` owns focusable disabled controls; FR5 and AR5 record Token's
-  conformance and its one gap.
+  conformance.
 - `architecture:public-component-api` owns ref, passthrough, and styling-input
   rules; FR3 records one gap against INV5.
 - `architecture:component-theming-surface` owns the `token` target and the
@@ -244,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                               | A native `disabled`, a lost tab stop on a button, or a fired callback fails. Gap: no test covers a disabled link token.                                                                            | `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