@astryxdesign/core 0.7.2 → 0.7.3-canary.0bf23bd

package/src/TimeInput/TimeInput.doc.mjs

@@ -212,7 +212,7 @@ export const docs = {
       name: 'increment',
       type: 'number',
       description:
-        'Number of minutes to add or subtract when the user presses the up or down arrow key.',
+        'Number of minutes to add or subtract when the user presses the up or down arrow key. Steps are whole minutes; a fractional value leaves the time unchanged.',
       default: '1',
     },
     {
@@ -392,7 +392,8 @@ export const docsZh = {
     {
       name: 'increment',
       type: 'number',
-      description: '用户按上或下方向键时增加或减少的分钟数。',
+      description:
+        '用户按上或下方向键时增加或减少的分钟数。步长为整分钟；传入小数时时间保持不变。',
       default: '1',
     },
     {
@@ -623,7 +624,8 @@ export const docsDense = {
     hasClear: 'Shows clear button when value set+not disabled.',
     hourFormat:
       "Display format. '12h' shows AM/PM; '24h' uses 24-hour notation.",
-    increment: 'Minutes to add/subtract on arrow up/down.',
+    increment:
+      'Minutes to add/subtract on arrow up/down. Whole minutes only; a fractional value leaves the time unchanged.',
     presentation:
       "picker surface: 'adaptive-native' (default) = typed field fine / browser/OS coarse (hasSeconds or increment!=1 retains typed); 'native' = browser/OS always, no fallback; 'adaptive-bottom-sheet' = typed fine / Astryx wheel sheet coarse; 'bottom-sheet' = sheet always; 'text-input'/'popover' = typed field only.",
     nativePicker:

package/src/TimeInput/TimeInput.test.tsx

@@ -65,6 +65,26 @@ describe('TimeInput', () => {
     expect(onChange).toHaveBeenCalledWith('14:31');
   });
 
+  it('does not step into a fractional minute when increment is fractional', () => {
+    const onChange = vi.fn();
+    render(
+      <TimeInput
+        label="Time"
+        value={'14:30' as ISOTimeString}
+        increment={0.5}
+        onChange={onChange}
+      />,
+    );
+    const input = screen.getByLabelText('Time');
+
+    // `increment` is documented as minutes and typed `number`. A fractional one
+    // used to reach formatISOTime unrounded, which pads "30.5" to two
+    // characters and leaves it, so the arrow key handed the consumer a value
+    // that is no longer a time at all.
+    fireEvent.keyDown(input, {key: 'ArrowUp'});
+    expect(onChange).toHaveBeenCalledWith('14:30');
+  });
+
   it('displays formatted time in 12h format', () => {
     render(
       <TimeInput

package/src/TimeInput/TimeInput.tsx

@@ -286,7 +286,8 @@ export interface TimeInputProps extends Omit<
   hourFormat?: TimeInputHourFormat;
 
   /**
-   * Increment in minutes when using arrow keys.
+   * Increment in minutes when using arrow keys. Steps are whole minutes: a
+   * fractional value leaves the time unchanged.
    * @default 1
    */
   increment?: number;

package/src/Token/Token.test.tsx

@@ -134,8 +134,10 @@ describe('Token', () => {
       />,
     );
     const button = screen.getByRole('button', {name: 'Disabled'});
-    expect(button).toBeDisabled();
+    expect(button).not.toHaveAttribute('disabled');
+    expect(button).toHaveAttribute('aria-disabled', 'true');
     expect(button.tagName).toBe('BUTTON');
+    fireEvent.click(button);
     // Container click is also disabled
     const container = screen.getByTestId('token');
     fireEvent.click(container);
@@ -254,14 +256,34 @@ describe('Token accessibility', () => {
     ).toBeInTheDocument();
   });
 
-  it('disables both buttons when isDisabled is true', () => {
+  it('keeps both buttons focusable and inert when isDisabled is true', async () => {
+    const user = userEvent.setup();
+    const handleClick = vi.fn();
+    const handleRemove = vi.fn();
     render(
-      <Token label="Token" onClick={() => {}} onRemove={() => {}} isDisabled />,
+      <Token
+        label="Token"
+        onClick={handleClick}
+        onRemove={handleRemove}
+        isDisabled
+      />,
     );
     const buttons = screen.getAllByRole('button');
+    expect(buttons).toHaveLength(2);
     for (const button of buttons) {
-      expect(button).toBeDisabled();
+      expect(button).not.toHaveAttribute('disabled');
+      expect(button).toHaveAttribute('aria-disabled', 'true');
+      // A wrapping Popover listens for clicks on the button itself.
+      const nativeClick = vi.fn();
+      button.addEventListener('click', nativeClick);
+      await user.tab();
+      expect(button).toHaveFocus();
+      await user.keyboard('{Enter} ');
+      expect(nativeClick).not.toHaveBeenCalled();
+      fireEvent.click(button);
     }
+    expect(handleClick).not.toHaveBeenCalled();
+    expect(handleRemove).not.toHaveBeenCalled();
   });
 
   it('does not fire onClick or onRemove when disabled', () => {

package/src/Token/Token.tsx

@@ -41,6 +41,7 @@ import {interactionOverlayStyles} from '../utils/interactionOverlay.stylex';
 import {usePressFeedback} from '../hooks/usePressFeedback';
 import {useTranslator} from '../i18n';
 import type {TokenColorMap} from './index';
+import {disabledInteractionProps} from '../utils/disabledInteraction';
 
 // =============================================================================
 // Types
@@ -321,7 +322,9 @@ export function Token({
         e.stopPropagation();
         onRemove(e);
       }}
-      disabled={isDisabled}
+      // Focusable while disabled (spec:AST-085 FR1), but inert (FR2).
+      aria-disabled={isDisabled || undefined}
+      {...(isDisabled ? disabledInteractionProps() : null)}
       {...focusOutlineProps.focusVisible(styles.removeButton)}>
       <Icon icon="close" size="xsm" color="inherit" />
     </button>
@@ -455,7 +458,8 @@ export function Token({
         <button
           type="button"
           onClick={effectiveOnClick}
-          disabled={isDisabled}
+          aria-disabled={isDisabled || undefined}
+          {...(isDisabled ? disabledInteractionProps() : null)}
           {...stylex.props(styles.invisibleButton)}>
           <span
             {...stylex.props(

package/src/Tokenizer/Tokenizer.spec.md

@@ -166,23 +166,23 @@ pending.
 
 ### Representative states
 
-| State                                      | Required invariant                                                                                                                                         | Allowed variation                                                                        |
-| ------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- |
-| Empty field                                | The mounted inner input is the opening control; a full-width menu stays aligned to the outer field.                                                        | Placeholder and bootstrap results may vary.                                              |
-| Focus bootstrap, choices remain            | A committed selection is removed from the displayed cohort; the input and popup remain active on the next valid remaining choice.                          | Internal cohort storage and projection may vary.                                         |
-| Focus bootstrap, selected choice was last  | The nearest preceding remaining choice becomes active without changing the displayed order.                                                                | Option identity representation may vary.                                                 |
-| Focus bootstrap, no choices or max reached | The popup closes and no active descendant remains; pending work cannot reopen it.                                                                          | Source cancellation mechanism may vary.                                                  |
-| Source pending or replaced                 | Busy semantics identify pending work; stale work cannot add choices or reopen a terminal popup.                                                            | A settled current cohort may be retained internally.                                     |
-| Disabled                                   | No choice can be committed; an open popup closes and clears its active descendant while disabled-reason focusability remains available where configured.   | Native-disabled or focusable-disabled representation follows current Tokenizer behavior. |
-| One or many tokens                         | The same input remains after tokens and moves with wrapping; full-width placement does not follow that movement.                                           | Token labels, wrapping rows, and custom content may vary.                                |
-| At `maxEntries`                            | The input identity remains mounted but its zero-width/hidden box is unusable as geometry; opening falls back to the outer field.                           | Search remains unavailable under current behavior.                                       |
-| Token removal or clear                     | Input identity survives and current refocus behavior remains.                                                                                              | Token count and input position change.                                                   |
-| `unfocusedInline`                          | Blurred OverflowList and focused direct-token layouts resolve the same live input identity; a collapsed input is not used as geometry.                     | Visible token count may vary with width.                                                 |
-| `unfocusedLayer`, focused                  | The live wrapper/input may be reparented into the context layer without descriptor churn.                                                                  | Corrective portal location may vary.                                                     |
-| `unfocusedLayer`, unfocused                | The hidden-layer input is unusable for a new open; the ordinary-flow outer-field fallback is used.                                                         | Placeholder token count may vary.                                                        |
-| Default or custom token edit               | The actual activated token/control is captured before edit state changes; if no usable descendant control exists, input then outer-field fallback applies. | Custom token markup may vary.                                                            |
-| LTR or RTL                                 | Physical proximity selects an edge only for a narrower surface; logical start wins ties and full-width placement.                                          | Collision may move the final rendered surface.                                           |
-| SSR, hydration, or unmount                 | No server geometry read occurs; first client open prepares normally; unmount clears identities and pending show work.                                      | Hydration timing may vary.                                                               |
+| State                                      | Required invariant                                                                                                                                         | Allowed variation                                         |
+| ------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------- |
+| Empty field                                | The mounted inner input is the opening control; a full-width menu stays aligned to the outer field.                                                        | Placeholder and bootstrap results may vary.               |
+| Focus bootstrap, choices remain            | A committed selection is removed from the displayed cohort; the input and popup remain active on the next valid remaining choice.                          | Internal cohort storage and projection may vary.          |
+| Focus bootstrap, selected choice was last  | The nearest preceding remaining choice becomes active without changing the displayed order.                                                                | Option identity representation may vary.                  |
+| Focus bootstrap, no choices or max reached | The popup closes and no active descendant remains; pending work cannot reopen it.                                                                          | Source cancellation mechanism may vary.                   |
+| Source pending or replaced                 | Busy semantics identify pending work; stale work cannot add choices or reopen a terminal popup.                                                            | A settled current cohort may be retained internally.      |
+| Disabled                                   | No choice can be committed; an open popup closes and clears its active descendant while disabled-reason focusability remains available where configured.   | The disabled representation follows `spec:AST-085`.       |
+| One or many tokens                         | The same input remains after tokens and moves with wrapping; full-width placement does not follow that movement.                                           | Token labels, wrapping rows, and custom content may vary. |
+| At `maxEntries`                            | The input identity remains mounted but its zero-width/hidden box is unusable as geometry; opening falls back to the outer field.                           | Search remains unavailable under current behavior.        |
+| Token removal or clear                     | Input identity survives and current refocus behavior remains.                                                                                              | Token count and input position change.                    |
+| `unfocusedInline`                          | Blurred OverflowList and focused direct-token layouts resolve the same live input identity; a collapsed input is not used as geometry.                     | Visible token count may vary with width.                  |
+| `unfocusedLayer`, focused                  | The live wrapper/input may be reparented into the context layer without descriptor churn.                                                                  | Corrective portal location may vary.                      |
+| `unfocusedLayer`, unfocused                | The hidden-layer input is unusable for a new open; the ordinary-flow outer-field fallback is used.                                                         | Placeholder token count may vary.                         |
+| Default or custom token edit               | The actual activated token/control is captured before edit state changes; if no usable descendant control exists, input then outer-field fallback applies. | Custom token markup may vary.                             |
+| LTR or RTL                                 | Physical proximity selects an edge only for a narrower surface; logical start wins ties and full-width placement.                                          | Collision may move the final rendered surface.            |
+| SSR, hydration, or unmount                 | No server geometry read occurs; first client open prepares normally; unmount clears identities and pending show work.                                      | Hydration timing may vary.                                |
 
 ### Transformation and precedence order
 
@@ -282,8 +282,8 @@ consumer docs, and Changeset together. Exact-head browser evidence must exercise
    next remaining option active.
 2. The fallback when the committed option was last, plus terminal closure for no
    remaining choice and `maxEntries`.
-3. Escape, Tab or outside focus departure, transition to native-disabled and
-   focusable-disabled states, and pending or stale source settlement without a
+3. Escape, Tab or outside focus departure, transition to the disabled state,
+   and pending or stale source settlement without a
    later reopen.
 4. The unchanged path when `hasEntriesOnFocus` is off and direct single-select
    BaseTypeahead selection still closes.
@@ -297,15 +297,15 @@ become Tokenizer policy.
 
 ## Verification map
 
-| Contract         | Verification                                                                       | Representative states                                                                                                                        | Mutation or failure expectation                                                                                                                                           | Audit section                    |
-| ---------------- | ---------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------- |
-| FR1–FR3          | Existing Tokenizer/BaseTypeahead unit tests plus source inspection                 | empty, tokens, remove, clear, max, wrapping, both overflow modes                                                                             | Input remounts, suggestion menu changes anchor/width semantics, or overflow ownership is misstated.                                                                       | `audit:Tokenizer/current`        |
-| FR4–FR8          | Focused descriptor identity/capture tests when implemented                         | add, default/custom token edit, max, hidden layer, reparent, stale node, unmount, SSR                                                        | Descriptor leaks publicly, captures a transient result/pointer, misses custom controls, or uses unusable geometry.                                                        | `audit:Tokenizer/opening-anchor` |
-| FR9–FR12         | Layer unit tests and real-Chromium geometry checks when implemented                | full/equal/narrow surface, start/end/tie, LTR/RTL, collision, stale fallback                                                                 | Full-width follows inner input, tie is physical, collision runs early, or stale identity flashes.                                                                         | `audit:Tokenizer/placement`      |
-| FR13–FR15, AR5   | Focused Tokenizer/BaseTypeahead tests and exact-head Chromium interaction evidence | pointer/keyboard commit, first/middle/last choice, rejected/deferred control, loading, disabled, max, exhaustion, Escape, Tab, outside focus | Selected values remain available, order changes, focus leaves the combobox, active descendant names no option, stale work reopens, or a terminal state stays interactive. | `audit:Tokenizer/multi-select`   |
-| PR1–PR5          | Instrumented reads, pending-frame cleanup tests, and first-frame Chromium capture  | open, close before frame, reopen opposite side, resize while open                                                                            | Render-time/repeated reads, observer/pointer tracking, uncancelled frame, or first-frame jump occurs.                                                                     | `audit:Tokenizer/performance`    |
-| AR1–AR5          | Existing interaction suites plus focused pointer/keyboard/browser checks           | add/edit, focus/refocus, overflow, disabled, dismissal, retained bootstrap selection                                                         | Modality changes placement, semantics/focus regress, active descendant becomes invalid, or visible placement is wrong before fallback.                                    | `audit:Tokenizer/accessibility`  |
-| Record structure | `scripts/check-knowledge.mjs`                                                      | Template-v3 current record and current-only frontmatter links                                                                                | Invalid metadata, authority, or relationship references fail repository validation.                                                                                       | `audit:Tokenizer/knowledge`      |
+| Contract         | Verification                                                                                                                              | Representative states                                                                                                                        | Mutation or failure expectation                                                                                                                                           | Audit section                    |
+| ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------- |
+| FR1–FR3          | Existing Tokenizer/BaseTypeahead unit tests plus source inspection                                                                        | empty, tokens, remove, clear, max, wrapping, both overflow modes                                                                             | Input remounts, suggestion menu changes anchor/width semantics, or overflow ownership is misstated.                                                                       | `audit:Tokenizer/current`        |
+| FR4–FR8          | Focused descriptor identity/capture tests when implemented                                                                                | add, default/custom token edit, max, hidden layer, reparent, stale node, unmount, SSR                                                        | Descriptor leaks publicly, captures a transient result/pointer, misses custom controls, or uses unusable geometry.                                                        | `audit:Tokenizer/opening-anchor` |
+| FR9–FR12         | Layer unit tests and real-Chromium geometry checks when implemented                                                                       | full/equal/narrow surface, start/end/tie, LTR/RTL, collision, stale fallback                                                                 | Full-width follows inner input, tie is physical, collision runs early, or stale identity flashes.                                                                         | `audit:Tokenizer/placement`      |
+| FR13–FR15, AR5   | Focused Tokenizer/BaseTypeahead tests and exact-head Chromium interaction evidence                                                        | pointer/keyboard commit, first/middle/last choice, rejected/deferred control, loading, disabled, max, exhaustion, Escape, Tab, outside focus | Selected values remain available, order changes, focus leaves the combobox, active descendant names no option, stale work reopens, or a terminal state stays interactive. | `audit:Tokenizer/multi-select`   |
+| PR1–PR5          | Instrumented reads, pending-frame cleanup tests, and first-frame Chromium capture                                                         | open, close before frame, reopen opposite side, resize while open                                                                            | Render-time/repeated reads, observer/pointer tracking, uncancelled frame, or first-frame jump occurs.                                                                     | `audit:Tokenizer/performance`    |
+| AR1–AR5          | Existing interaction suites plus focused pointer/keyboard/browser checks; native-disabled assertions pending conformance (`spec:AST-085`) | add/edit, focus/refocus, overflow, disabled, dismissal, retained bootstrap selection                                                         | Modality changes placement, semantics/focus regress, active descendant becomes invalid, or visible placement is wrong before fallback.                                    | `audit:Tokenizer/accessibility`  |
+| Record structure | `scripts/check-knowledge.mjs`                                                                                                             | Template-v3 current record and current-only frontmatter links                                                                                | Invalid metadata, authority, or relationship references fail repository validation.                                                                                       | `audit:Tokenizer/knowledge`      |
 
 ## Decision log
 

package/src/Tooltip/Tooltip.test.tsx

@@ -25,6 +25,7 @@ import {
   fireEvent,
   waitFor,
 } from '@testing-library/react';
+import {useRef} from 'react';
 import {Tooltip} from './Tooltip';
 import {useTooltip} from './useTooltip';
 import {__resetInteractionModalityForTest} from '../utils/interactionModality';
@@ -84,17 +85,15 @@ describe('Tooltip', () => {
     expect(screen.getByRole('button', {name: 'Trigger'})).toBeInTheDocument();
   });
 
-  it('gives the tooltip layer role="tooltip" linked from the trigger', () => {
+  it('renders the content prop inside the tooltip layer', () => {
     render(
       <Tooltip content="Tooltip text">
         <button type="button">Trigger</button>
       </Tooltip>,
     );
-    const layer = screen.getByRole('tooltip', {hidden: true});
-    expect(layer).toHaveTextContent('Tooltip text');
-    // ARIA tooltip pattern: trigger references the layer via aria-describedby.
-    const trigger = screen.getByRole('button', {name: 'Trigger'});
-    expect(trigger.getAttribute('aria-describedby')).toBe(layer.id);
+    expect(screen.getByRole('tooltip', {hidden: true})).toHaveTextContent(
+      'Tooltip text',
+    );
   });
 
   it('calls onOpenChange(true) when shown via hover', async () => {
@@ -604,3 +603,49 @@ describe('Tooltip', () => {
     });
   });
 });
+
+describe('Tooltip sibling mode (anchorRef)', () => {
+  // SideNavItem's collapsed rail tooltip renders the Tooltip inside the very
+  // element anchorRef points at. React attaches an ancestor's ref after its
+  // descendants' layout effects, so on mount the tooltip's effect used to see
+  // a null anchor and never retried (#7692).
+  it('attaches to an anchor it is rendered inside of', async () => {
+    const onOpenChange = vi.fn();
+    function AnchorInside() {
+      const anchorRef = useRef<HTMLDivElement>(null);
+      return (
+        <div ref={anchorRef}>
+          <button type="button">Inner</button>
+          <Tooltip
+            content="Sibling tooltip"
+            anchorRef={anchorRef}
+            delay={0}
+            onOpenChange={onOpenChange}
+          />
+        </div>
+      );
+    }
+
+    const {unmount} = render(<AnchorInside />);
+    const anchor = screen.getByRole('button', {name: 'Inner'})
+      .parentElement as HTMLElement;
+
+    // The anchor is described by the tooltip once the commit has attached refs.
+    await waitFor(() => {
+      expect(anchor.getAttribute('aria-describedby')).not.toBe('');
+    });
+    const layer = screen.getByRole('tooltip', {hidden: true});
+    expect(anchor.getAttribute('aria-describedby')).toBe(layer.id);
+
+    // Hovering the anchor opens the tooltip: the interaction listeners were
+    // attached to the late anchor too.
+    fireEvent.mouseEnter(anchor);
+    await waitFor(() => {
+      expect(onOpenChange).toHaveBeenCalledWith(true);
+    });
+
+    // Unmounting detaches: the aria-describedby the tooltip added is removed.
+    unmount();
+    expect(anchor.getAttribute('aria-describedby')).toBe(null);
+  });
+});

package/src/Tooltip/Tooltip.tsx

@@ -242,28 +242,51 @@ export function Tooltip({
       return;
     }
 
+    const attach = (el: HTMLElement) => {
+      // Use combined ref for position + interaction
+      tooltip.ref(el);
+
+      // Set aria-describedby, merging with existing
+      const existingDescribedBy = el.getAttribute('aria-describedby');
+      el.setAttribute(
+        'aria-describedby',
+        mergeIds(existingDescribedBy, tooltip.describedBy) ?? '',
+      );
+
+      return () => {
+        tooltip.ref(null);
+        if (existingDescribedBy) {
+          el.setAttribute('aria-describedby', existingDescribedBy);
+        } else {
+          el.removeAttribute('aria-describedby');
+        }
+      };
+    };
+
     const el = anchorRef.current;
-    if (!el) {
-      return;
+    if (el) {
+      return attach(el);
     }
 
-    // Use combined ref for position + interaction
-    tooltip.ref(el);
-
-    // Set aria-describedby, merging with existing
-    const existingDescribedBy = el.getAttribute('aria-describedby');
-    el.setAttribute(
-      'aria-describedby',
-      mergeIds(existingDescribedBy, tooltip.describedBy) ?? '',
-    );
-
-    return () => {
-      tooltip.ref(null);
-      if (existingDescribedBy) {
-        el.setAttribute('aria-describedby', existingDescribedBy);
-      } else {
-        el.removeAttribute('aria-describedby');
+    // React attaches an ancestor's ref after its descendants' layout effects,
+    // so a tooltip rendered inside its own anchor (SideNavItem's collapsed
+    // rail tooltip) still sees null here on mount, and this effect's deps
+    // never change to re-run it. Re-check once the commit has attached all
+    // refs; if the anchor is still gone, this tooltip has no anchor, as before.
+    let detach: (() => void) | undefined;
+    let cancelled = false;
+    queueMicrotask(() => {
+      if (cancelled) {
+        return;
       }
+      const el = anchorRef.current;
+      if (el) {
+        detach = attach(el);
+      }
+    });
+    return () => {
+      cancelled = true;
+      detach?.();
     };
   }, [anchorRef, tooltip.ref, tooltip.describedBy]);
 

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

@@ -0,0 +1,129 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Tooltip.a11y.chromium.spec.ts
+ * @input Built tooltip stories and TOOLTIP_PATTERN in real Chromium
+ * @output Browser evidence for every tooltip expectation across Tooltip's and useTooltip's representative states
+ * @position Chromium lane of the Tooltip binding
+ */
+
+import {
+  expect,
+  test,
+  type CDPSession,
+  type Locator,
+  type Page,
+} from '@playwright/test';
+import {
+  TOOLTIP_PATTERN,
+  blockingResults,
+  checkAccessibilitySpec,
+  formatFailures,
+  neverExercised,
+  summarize,
+  type BindingResult,
+} from '@astryxdesign/a11y-spec';
+import {
+  createChromiumHarness,
+  holdMotionStill,
+} from '@astryxdesign/a11y-spec/chromium';
+import {
+  DEFAULT_STORYBOOK_DIR,
+  serveStorybook,
+  type StaticServer,
+} from '@astryxdesign/a11y-spec/storybook';
+import {
+  TOOLTIP_BINDING_STATES,
+  type TooltipBindingState,
+} from './Tooltip.a11y.states';
+
+let storybook: StaticServer;
+
+test.beforeAll(async () => {
+  storybook = await serveStorybook(
+    process.env.ASTRYX_STORYBOOK_DIR ?? DEFAULT_STORYBOOK_DIR,
+  );
+});
+
+test.afterAll(async () => {
+  await storybook?.close();
+});
+
+function storyUrl(storyId: string): string {
+  return `${storybook.origin}/iframe.html?id=${storyId}&viewMode=story`;
+}
+
+async function mountState(
+  page: Page,
+  state: TooltipBindingState,
+): Promise<{subject: Locator; related: Record<string, Locator>}> {
+  await page.goto(storyUrl(state.storyId), {waitUntil: 'load'});
+  await holdMotionStill(page);
+  const root = page.locator('#storybook-root');
+  const subject =
+    state.triggerRole == null
+      ? root.getByText(state.triggerText, {exact: true})
+      : root.getByRole(state.triggerRole, {
+          name: state.triggerText,
+          exact: true,
+        });
+  await expect(subject).toBeVisible();
+  return {
+    subject,
+    related: {
+      // The layer may mount the tooltip outside the story root, and it stays
+      // in the page while hidden, so it is found page-wide, hidden included.
+      tooltip: page.getByRole('tooltip', {includeHidden: true}),
+      before: root.getByRole('button', {
+        name: 'Before the trigger',
+        exact: true,
+      }),
+      after: root.getByRole('button', {
+        name: 'After the trigger',
+        exact: true,
+      }),
+    },
+  };
+}
+
+async function runState(
+  page: Page,
+  cdp: CDPSession,
+  state: TooltipBindingState,
+): Promise<BindingResult> {
+  return checkAccessibilitySpec({
+    spec: TOOLTIP_PATTERN,
+    binding: 'Tooltip',
+    state: state.id,
+    facts: state.facts,
+    mount: async () => {
+      const {subject, related} = await mountState(page, state);
+      return createChromiumHarness({page, cdp, subject, related});
+    },
+  });
+}
+
+test('every tooltip expectation is exercised by a Tooltip state', async ({
+  page,
+}) => {
+  test.setTimeout(3 * 60 * 1000);
+  const cdp = await page.context().newCDPSession(page);
+  const results: BindingResult[] = [];
+  for (const state of TOOLTIP_BINDING_STATES) {
+    results.push(await runState(page, cdp, state));
+  }
+  expect(neverExercised(results)).toEqual([]);
+});
+
+for (const state of TOOLTIP_BINDING_STATES) {
+  test(`Tooltip [${state.id}] — ${state.summary}`, async ({page}) => {
+    test.setTimeout(2 * 60 * 1000);
+    const cdp = await page.context().newCDPSession(page);
+    const result = await runState(page, cdp, state);
+    const report = summarize(TOOLTIP_PATTERN, [result]);
+    // Required rows block (AST-020 FR9); advisory rows report.
+    expect(formatFailures(blockingResults([result]))).toBe('');
+    expect(report.unrunLayers).toEqual([]);
+    expect(report.counts.unexpectedPass).toBe(0);
+  });
+}

package/src/Tooltip/__tests__/Tooltip.a11y.renders.tsx

@@ -0,0 +1,86 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file Tooltip.a11y.renders.tsx
+ * @input One tooltip binding state from Tooltip.a11y.states.ts
+ * @output The React tree every lane renders for that state (the jsdom test directly, the story through Storybook): a page button before the trigger, the trigger and its tooltip, and a page button after it
+ * @position Shared fixture for the Tooltip and useTooltip binding
+ */
+
+import {useRef, type ReactElement} from 'react';
+import {Button} from '../../Button/Button';
+import {isRenderable} from '../../utils/isRenderable';
+import {Tooltip} from '../Tooltip';
+import {useTooltip} from '../useTooltip';
+import type {TooltipBindingState} from './Tooltip.a11y.states';
+
+const HINT_ID = 'tooltip-a11y-hint';
+
+type TriggerState = Pick<
+  TooltipBindingState,
+  'attachment' | 'triggerText' | 'content' | 'hint'
+>;
+
+/** A caller button the tooltip attaches to through `anchorRef`. */
+function AnchorRefTrigger({state}: {state: TriggerState}): ReactElement {
+  const anchorRef = useRef<HTMLButtonElement>(null);
+  return (
+    <>
+      <button
+        ref={anchorRef}
+        type="button"
+        aria-describedby={state.hint == null ? undefined : HINT_ID}>
+        {state.triggerText}
+      </button>
+      <Tooltip anchorRef={anchorRef} content={state.content} />
+    </>
+  );
+}
+
+/** A caller button wired by hand through `useTooltip`. */
+function HookTrigger({state}: {state: TriggerState}): ReactElement {
+  const tooltip = useTooltip();
+  return (
+    <>
+      <button
+        ref={tooltip.ref}
+        type="button"
+        aria-describedby={tooltip.describedBy}>
+        {state.triggerText}
+      </button>
+      {tooltip.renderTooltip(state.content)}
+    </>
+  );
+}
+
+function Trigger({state}: {state: TriggerState}): ReactElement {
+  switch (state.attachment) {
+    case 'wrapped-element':
+      return (
+        <Tooltip content={state.content}>
+          <Button label={state.triggerText} />
+        </Tooltip>
+      );
+    case 'text':
+      return <Tooltip content={state.content}>{state.triggerText}</Tooltip>;
+    case 'anchor-ref':
+      return <AnchorRefTrigger state={state} />;
+    case 'hook':
+      return <HookTrigger state={state} />;
+  }
+}
+
+export function renderTooltipState(state: TriggerState): ReactElement {
+  return (
+    <div style={{padding: 64}}>
+      <button type="button">Before the trigger</button>{' '}
+      <Trigger state={state} />
+      {isRenderable(state.hint) ? (
+        <span id={HINT_ID}> {state.hint}</span>
+      ) : null}{' '}
+      <button type="button">After the trigger</button>
+    </div>
+  );
+}