@astryxdesign/core 0.7.5 → 0.7.6-canary.00507ba

package/src/Carousel/__tests__/Carousel.a11y.chromium.spec.ts

@@ -120,16 +120,30 @@ function bindingState(id: string): CarouselBindingRow {
   return state;
 }
 
-test('every expectation is exercised by at least one Carousel state', async ({
-  page,
-}) => {
-  const cdp = await page.context().newCDPSession(page);
+// Checking coverage runs every state again, which on a loaded runner nears
+// the per-test timeout as one test. It runs as one serial part per state,
+// sharing their results, then one check over all of them.
+test.describe('every expectation is exercised by at least one Carousel state', () => {
+  test.describe.configure({mode: 'serial'});
   const results: BindingResult[] = [];
+
   for (const state of CAROUSEL_BINDING_STATES) {
-    results.push(await runState(page, cdp, state));
+    test(`runs ${state.id}`, async ({page}) => {
+      const cdp = await page.context().newCDPSession(page);
+      results.push(await runState(page, cdp, state));
+    });
   }
-  expect(neverExercised(results)).toEqual([]);
-  expect(unmatchedKnownFailures(CAROUSEL_KNOWN_FAILURES, results)).toEqual([]);
+
+  test('no expectation is left unexercised', () => {
+    // Every part ran in this worker; this test alone proves nothing.
+    expect(results.map(result => result.state).sort()).toEqual(
+      CAROUSEL_BINDING_STATES.map(state => state.id).sort(),
+    );
+    expect(neverExercised(results)).toEqual([]);
+    expect(unmatchedKnownFailures(CAROUSEL_KNOWN_FAILURES, results)).toEqual(
+      [],
+    );
+  });
 });
 
 for (const state of CAROUSEL_BINDING_STATES) {

package/src/Carousel/__tests__/Carousel.a11y.known-failures.ts

@@ -9,19 +9,4 @@
 
 import type {KnownFailure} from '@astryxdesign/a11y-spec';
 
-export const CAROUSEL_KNOWN_FAILURES: ReadonlyArray<KnownFailure> = [
-  {
-    expectation: 'carousel.scroller.role-and-name',
-    binding: 'Carousel',
-    state: 'scroller-keyboard',
-    evidenceLayer: 'accessibility-tree',
-    failureEquals:
-      'the browser exposes the focusable scroll container with no role',
-    standardsReference:
-      'WCAG 2.2 4.1.2 Name, Role, Value; Astryx spec:AST-025 FR12 — a viewport that takes keyboard scrolling must provide an appropriate role and accessible name',
-    userImpact:
-      'A keyboard user who tabs onto the scroll container hears nothing about where they are or what the arrow keys will do; the named region around it is the only clue.',
-    reason:
-      'This test-only binding records the gap; naming the scroll container is a Carousel markup change that ships as its own spec-backed fix.',
-  },
-];
+export const CAROUSEL_KNOWN_FAILURES: ReadonlyArray<KnownFailure> = [];

package/src/Chat/ChatComposerTokenElement.spec.md

@@ -1,13 +1,13 @@
 ---
 schema_version: 3
-template_version: 5
+template_version: 7
 kind: component
 id: component:ChatComposerTokenElement
-authority: draft
+authority: current
 archive_reason: null
 superseded_by: null
-approved_by: null
-approved_at: null
+approved_by: cixzhang
+approved_at: 2026-10-31
 owners: [cixzhang]
 review_triggers: [public-api, behavior, accessibility, theming, testing]
 verified_by:
@@ -33,15 +33,15 @@ system_specs: [spec:AST-002, spec:AST-029]
 
 ## Contract at a glance
 
-| Area                    | Contract                                                                                                                                                                                      |
-| ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Public contract         | No token shape, default, or rendering change. The public props type and existing span passthrough are directly reachable from the Chat package path.                                          |
-| Behavior                | A structured token renders Badge content; a custom token renders caller content. Both retain the serialized value marker and stay non-editable when placed inside a contenteditable composer. |
-| End-user impact         | Token labels and caller content remain visible without becoming editable text.                                                                                                                |
-| Builder impact          | Builders can type the existing component props and attach neutral span attributes, styles, and a ref without recreating its contract.                                                         |
-| Compatibility/readiness | Additive patch-compatible contract repair. This observational record adds no token meaning or visual policy.                                                                                  |
-| Review checks           | Reject a token wrapper that loses its serialized value, becomes editable, drops accepted span props, or changes the structured/custom rendering split.                                        |
-| Governing rules         | `architecture:public-component-api/INV1, INV5–INV6, INV8–INV9, INV12`; `architecture:component-test-sufficiency/INV1–INV8, INV10–INV11`; `spec:AST-029/FR3–FR5, FR7`.                         |
+| Area                    | Contract                                                                                                                                                                                                                                                                                  |
+| ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Public contract         | `ChatComposerTokenElement` with a required `token`: structured, which is `value` plus Badge props, of which only `label`, `variant`, and `icon` render and the rest are accepted and ignored; or custom `{value, render}`, `ref`, `xstyle`, `className`, `style`, and neutral span props. |
+| Behavior                | A structured token renders Badge content; a custom token renders caller content. Both retain the serialized value marker and stay non-editable when placed inside a contenteditable composer.                                                                                             |
+| End-user impact         | Token labels and caller content remain visible without becoming editable text.                                                                                                                                                                                                            |
+| Builder impact          | None.                                                                                                                                                                                                                                                                                     |
+| Compatibility/readiness | Records shipped behavior; no public change. Evidence still pending for AR1 and parts of FR1, FR2, and FR4 (read from source; see the verification map).                                                                                                                                   |
+| Review checks           | Reject a token wrapper that loses its serialized value, becomes editable, drops accepted span props, or changes the structured/custom rendering split.                                                                                                                                    |
+| Governing rules         | `architecture:public-component-api/INV1, INV5–INV6, INV8–INV9, INV12`; `architecture:component-test-sufficiency/INV1–INV8, INV10–INV11`; `spec:AST-029/FR3–FR5, FR7`.                                                                                                                     |
 
 This table is a review projection; the body below is authoritative.
 
@@ -54,11 +54,13 @@ their existing owners.
 
 ## Compatibility and migration
 
-- Released default preserved: yes
-- Compatibility class: additive props-type and DOM-passthrough repair
-- Token values and rendering branches: unchanged
+- Released default preserved: `yes`
+- Compatibility class: records shipped behavior; no public change
+- Controlled/uncontrolled behavior: not applicable
 - Migration decision: none
 
+Consumer migration instructions belong in consumer docs and release notes.
+
 ## Ownership boundary
 
 **Owns**
@@ -85,12 +87,12 @@ their existing owners.
 
 ## Behavioral and layout contract
 
-| ID  | Candidate invariant                                                                                                                                                        | Basis                                                                | Draft review state |
-| --- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------- | ------------------ |
-| FR1 | The root MUST expose `data-astryx-token` and the exact supplied `token.value`, and MUST remain `contentEditable={false}`.                                                  | shipped implementation, public docs, ChatComposerInput serialization | verify             |
-| FR2 | Structured tokens MUST delegate label, variant, and icon rendering to Badge without changing the token value.                                                              | shipped implementation and public token type                         | verify             |
-| FR3 | Custom tokens MUST render the caller function result without adding component-owned semantics or interaction.                                                              | shipped implementation and public token type                         | verify             |
-| FR4 | Accepted ref, DOM/data/ARIA, className, style, and xstyle inputs MUST reach and compose on the root span while component-owned serialization attributes retain precedence. | `architecture:public-component-api/INV5–INV6, INV8`                  | settled            |
+| ID  | Invariant                                                                                                                                                                  | Basis                                               |
+| --- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------- |
+| FR1 | The root MUST expose `data-astryx-token` and the exact supplied `token.value`, and MUST remain `contentEditable={false}`.                                                  | Current source, docs, and tests                     |
+| FR2 | Structured tokens MUST delegate label, variant, and icon rendering to Badge without changing the token value.                                                              | shipped implementation and public token type        |
+| FR3 | Custom tokens MUST render the caller function result without adding component-owned semantics or interaction.                                                              | shipped implementation and public token type        |
+| FR4 | Accepted ref, DOM/data/ARIA, className, style, and xstyle inputs MUST reach and compose on the root span while component-owned serialization attributes retain precedence. | `architecture:public-component-api/INV5–INV6, INV8` |
 
 ### Allowed variation
 
@@ -108,15 +110,18 @@ their existing owners.
 
 ## Accessibility contract
 
-- The wrapper owns no interactive role or accessible name beyond accepted caller props.
-- Structured Badge text remains visible content; custom content semantics remain caller owned.
-- `contentEditable={false}` keeps the token atomically non-editable when nested in an editor.
+- **AR1 — No owned semantics.** The wrapper owns no interactive role or
+  accessible name beyond accepted caller props.
+- **AR2 — Visible content.** Structured Badge text remains visible content;
+  custom content semantics remain caller owned.
+- **AR3 — Atomic token.** `contentEditable={false}` keeps the token atomically
+  non-editable when nested in an editor.
 
 ## Design relationships
 
 | Anatomy or state   | Design requirement        | Representation authority | Hierarchy role | Component contract |
 | ------------------ | ------------------------- | ------------------------ | -------------- | ------------------ |
-| token wrapper      | Inline alignment only     | observed implementation  | supporting     | FR1, FR4           |
+| token wrapper      | Inline alignment only     | Current source           | supporting     | FR1, FR4           |
 | structured content | Badge presentation        | `component:Badge`        | supporting     | FR2                |
 | custom content     | caller-owned presentation | caller                   | supporting     | FR3                |
 
@@ -128,19 +133,26 @@ target. Badge theming remains owned by Badge, and custom content remains caller
 - `component:ChatComposerInput` owns insertion, serialization traversal, deletion, and selection behavior.
 - `architecture:public-component-api` owns the public props type, ref, and BaseProps composition.
 - `architecture:component-test-sufficiency` owns direct evidence for the established public serialization seam.
-- `spec:AST-029` owns this observational audit backfill and its finite evidence inventory.
+- `spec:AST-029` owns the audit evidence inventory this record's verification map follows.
 
 ## Verification map
 
-| Contract        | Verification                                                       | Representative states                        | Mutation or failure expectation                                                                 | Audit section                             |
-| --------------- | ------------------------------------------------------------------ | -------------------------------------------- | ----------------------------------------------------------------------------------------------- | ----------------------------------------- |
-| FR1–FR3         | `ChatComposerTokenElement.test.tsx`; direct Storybook stories      | structured and custom tokens                 | A marker/value disappears, the wrapper becomes editable, or the wrong rendering branch appears. | `audit:ChatComposerTokenElement/behavior` |
-| FR4             | focused ref and DOM-passthrough test; public typecheck             | ref, ARIA/data props, styling seams          | An accepted input is dropped or an owned serialization marker is replaced.                      | `audit:ChatComposerTokenElement/api`      |
-| rendered states | direct Storybook stories and exact-head visual/accessibility gates | Badge and custom content in supported themes | A story is unreachable or introduces an accessibility/visual regression.                        | `audit:ChatComposerTokenElement/rendered` |
+| Contract         | Verification                                                  | Representative states                        | Mutation or failure expectation                                                                 | Audit section                             |
+| ---------------- | ------------------------------------------------------------- | -------------------------------------------- | ----------------------------------------------------------------------------------------------- | ----------------------------------------- |
+| FR1–FR3, AR2–AR3 | `ChatComposerTokenElement.test.tsx`; direct Storybook stories | structured and custom tokens                 | A marker/value disappears, the wrapper becomes editable, or the wrong rendering branch appears. | `audit:ChatComposerTokenElement/behavior` |
+| FR4              | focused ref and DOM-passthrough test; public typecheck        | ref, ARIA/data props, styling seams          | An accepted input is dropped or an owned serialization marker is replaced.                      | `audit:ChatComposerTokenElement/api`      |
+| rendered states  | direct Storybook stories                                      | Badge and custom content in supported themes | An unreachable story fails the story checks.                                                    | `audit:ChatComposerTokenElement/rendered` |
+
+Read from source, with no focused test yet:
+
+- AR1: the wrapper adding no role or accessible name of its own.
+- FR1: `contentEditable` staying `false` when a caller passes it.
+- FR2: `variant` and `icon` reaching the Badge.
+- FR4: `className`, `style`, and `xstyle` composing on the span.
 
 ## Decision log
 
-No component-local policy decision is created by this observational draft.
+No component-local decision is recorded.
 
 ## Open questions
 

package/src/CheckboxInput/CheckboxInput.tsx

@@ -41,17 +41,18 @@ import {FieldLabel} from '../Field/FieldLabel';
 import {FieldStatus} from '../FieldStatus/FieldStatus';
 import type {IconType} from '../Icon';
 import type {InputStatus} from '../Field/types';
-import {Spinner} from '../Spinner';
-import {useTooltip} from '../Tooltip';
-import {mergeProps, rtlStyles} from '../utils';
+import {Spinner} from '../Spinner/Spinner';
+import {useTooltip} from '../Tooltip/useTooltip';
+import {mergeProps} from '../utils/mergeProps';
+import {rtlStyles} from '../utils/rtlStyles';
 import {indicatorScope} from '../Indicator/indicator.markers.stylex';
 import {interactionOverlayStyles} from '../utils/interactionOverlay.stylex';
-import {useTranslator} from '../i18n';
+import {useTranslator} from '../i18n/useTranslator';
 import {useIndicatorFocusRing} from '../hooks/useIndicatorFocusRing';
 import {useBusyAnnouncement} from '../hooks/useBusyAnnouncement';
 import {usePressFeedback} from '../hooks/usePressFeedback';
 import {useResolvedRequired} from '../hooks/useResolvedRequired';
-import {useIndicator} from '../Indicator';
+import {useIndicator} from '../Indicator/useIndicator';
 import {themeProps} from '../utils/themeProps';
 
 import {useMergedRefs} from '../hooks/useMergedRefs';

package/src/ClickableCard/ClickableCard.test.tsx

@@ -1,9 +1,11 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
+import {Activity, type ReactNode} from 'react';
 import {describe, it, expect, vi} from 'vitest';
 import {render, screen, fireEvent} from '@testing-library/react';
 import userEvent from '@testing-library/user-event';
 import {ClickableCard} from './ClickableCard';
+import {LinkProvider} from '../Link';
 import {
   afterPaintsPress,
   hasReleaseFade,
@@ -171,6 +173,100 @@ describe('ClickableCard', () => {
     expect(handleClick).not.toHaveBeenCalled();
   });
 
+  it('does not render a disabled link through the router link component', () => {
+    function RouterLink({
+      href,
+      children,
+    }: {
+      href?: string;
+      children?: ReactNode;
+    }) {
+      if (href == null) {
+        throw new Error('Router link requires an href');
+      }
+      return <a href={href}>{children}</a>;
+    }
+
+    render(
+      <LinkProvider component={RouterLink}>
+        <ClickableCard label="Disabled link" href="/settings" isDisabled>
+          <span>Content</span>
+        </ClickableCard>
+      </LinkProvider>,
+    );
+
+    const link = screen.getByRole('link', {name: 'Disabled link'});
+    expect(link).toHaveAttribute('aria-disabled', 'true');
+    expect(link).not.toHaveAttribute('href');
+  });
+
+  it('keeps focus when a focused link card toggles its disabled state', async () => {
+    const user = userEvent.setup();
+    const {rerender} = render(
+      <ClickableCard label="Focus card" href="/settings">
+        <span>Content</span>
+      </ClickableCard>,
+    );
+
+    await user.tab();
+    expect(screen.getByRole('link', {name: 'Focus card'})).toHaveFocus();
+
+    rerender(
+      <ClickableCard label="Focus card" href="/settings" isDisabled>
+        <span>Content</span>
+      </ClickableCard>,
+    );
+    expect(screen.getByRole('link', {name: 'Focus card'})).toHaveFocus();
+
+    rerender(
+      <ClickableCard label="Focus card" href="/settings">
+        <span>Content</span>
+      </ClickableCard>,
+    );
+    expect(screen.getByRole('link', {name: 'Focus card'})).toHaveFocus();
+  });
+
+  it('leaves focus where the person put it when a hidden card is revealed', async () => {
+    const user = userEvent.setup();
+    function Harness({isHidden}: {isHidden: boolean}) {
+      return (
+        <>
+          <Activity mode={isHidden ? 'hidden' : 'visible'}>
+            <ClickableCard label="Hidden card" href="/settings">
+              <span>Content</span>
+            </ClickableCard>
+          </Activity>
+          <button type="button">Elsewhere</button>
+        </>
+      );
+    }
+    const {rerender} = render(<Harness isHidden={false} />);
+    await user.tab();
+    expect(screen.getByRole('link', {name: 'Hidden card'})).toHaveFocus();
+    rerender(<Harness isHidden />);
+    screen.getByRole('button', {name: 'Elsewhere'}).focus();
+    rerender(<Harness isHidden={false} />);
+    expect(screen.getByRole('button', {name: 'Elsewhere'})).toHaveFocus();
+  });
+
+  it('takes focus back without scrolling the page', async () => {
+    const user = userEvent.setup();
+    const {rerender} = render(
+      <ClickableCard label="Scroll card" href="/settings">
+        <span>Content</span>
+      </ClickableCard>,
+    );
+    await user.tab();
+    const focus = vi.spyOn(HTMLElement.prototype, 'focus');
+    rerender(
+      <ClickableCard label="Scroll card" href="/settings" isDisabled>
+        <span>Content</span>
+      </ClickableCard>,
+    );
+    expect(focus).toHaveBeenCalledWith({preventScroll: true});
+    focus.mockRestore();
+  });
+
   it('runs onClick once from the keyboard via the hidden button', async () => {
     const user = userEvent.setup();
     const handleClick = vi.fn();

package/src/ClickableCard/ClickableCard.tsx

@@ -29,7 +29,13 @@
  * For toggle selection, use SelectableCard.
  */
 
-import {type ReactNode, type MouseEvent, useRef, type Ref} from 'react';
+import {
+  type ReactNode,
+  type MouseEvent,
+  useCallback,
+  useRef,
+  type Ref,
+} from 'react';
 import * as stylex from '@stylexjs/stylex';
 import type {StyleXStyles} from '@stylexjs/stylex';
 import {
@@ -327,6 +333,41 @@ export function ClickableCard({
   const pressable = usePressFeedback();
   const containerRef = useRef<HTMLDivElement | null>(null);
   const interactiveRef = useRef<HTMLElement | null>(null);
+  const restoreFocusRef = useRef(false);
+  // The isDisabled value of the link that just detached: a link card that
+  // flips it replaces its hidden link (router component and plain anchor),
+  // and only that replacement takes focus back.
+  const detachedDisabledRef = useRef<boolean | null>(null);
+
+  // A focused link remounts when isDisabled changes: the replacement takes
+  // focus back, without scrolling, if focus fell to the page. Any other
+  // detach and attach (a hidden Activity or Suspense boundary revealed
+  // again) leaves focus where the person put it.
+  const setInteractiveRef = useCallback(
+    (node: HTMLElement | null) => {
+      if (node == null) {
+        const previous = interactiveRef.current;
+        restoreFocusRef.current =
+          previous != null && previous === previous.ownerDocument.activeElement;
+        detachedDisabledRef.current = isDisabled;
+        interactiveRef.current = null;
+        return;
+      }
+      interactiveRef.current = node;
+      const isFlip =
+        detachedDisabledRef.current != null &&
+        detachedDisabledRef.current !== isDisabled;
+      const active = node.ownerDocument.activeElement;
+      const hasFallen = active == null || active === node.ownerDocument.body;
+      if (restoreFocusRef.current && isFlip && hasFallen) {
+        node.focus({preventScroll: true});
+      }
+      restoreFocusRef.current = false;
+      detachedDisabledRef.current = null;
+    },
+    [isDisabled],
+  );
+
   const LinkComponent = useLinkComponent();
 
   const {onClick, onMouseUp} = useClickableContainer({
@@ -347,6 +388,9 @@ export function ClickableCard({
 
   const isLink = href != null;
 
+  // Disabled links have no href, so bypass the router and render an anchor.
+  const LinkRoot = isDisabled ? 'a' : LinkComponent;
+
   // Only the `default` variant has a visible border. Card draws a transparent
   // 1px border on every other variant purely to avoid layout jitter; we drop
   // it here so the hover overlay covers the full box with no untinted ring.
@@ -385,8 +429,8 @@ export function ClickableCard({
       onMouseUp={!isDisabled ? handleMouseUp : undefined}
       {...props}>
       {isLink ? (
-        <LinkComponent
-          ref={interactiveRef as React.Ref<HTMLAnchorElement>}
+        <LinkRoot
+          ref={setInteractiveRef}
           href={isDisabled ? undefined : href}
           target={isDisabled ? undefined : target}
           role={isDisabled ? 'link' : undefined}
@@ -399,7 +443,7 @@ export function ClickableCard({
         />
       ) : (
         <button
-          ref={interactiveRef as React.Ref<HTMLButtonElement>}
+          ref={setInteractiveRef}
           type="button"
           aria-label={label}
           aria-disabled={isDisabled || undefined}

package/src/Collapsible/Collapsible.spec.md

@@ -69,6 +69,8 @@ Consumer migration instructions belong in consumer docs and release notes.
 - caller-provided chevron, cue, icon, or render-function escape hatches;
 - TreeList, Table, or another component's disclosure indicator;
 - generic icon resolution or artwork customization;
+- sibling open-value coordination, group state, and the divided group wrapper
+  — owned by `component:CollapsibleGroup`;
 - a shared responsive or directional API; or
 - new content-reveal motion behavior. Existing behavior outside this decision stays
   unchanged until its own current authority changes it.