@astryxdesign/core 0.7.2 → 0.7.3-canary.02f5fe4

package/src/Timestamp/Timestamp.tsx

@@ -17,7 +17,14 @@
  * - /packages/cli/assets/templates/blocks/components/Timestamp/ (showcase blocks)
  */
 
-import {lazy, Suspense, useEffect, useRef, useState} from 'react';
+import {
+  lazy,
+  Suspense,
+  useEffect,
+  useRef,
+  useState,
+  useSyncExternalStore,
+} from 'react';
 import * as stylex from '@stylexjs/stylex';
 import {Text} from '../Text';
 import type {TextType, TextSize, TextColor, TextWeight} from '../theme/types';
@@ -215,6 +222,13 @@ function getLiveInterval(diffSeconds: number): number {
   return 300_000; // every 5 minutes
 }
 
+// Whether this render may read the current time. Server renders (including
+// static prerenders) and the hydration pass read `false`, so the markup never
+// depends on when it was rendered; client renders read `true`.
+const subscribeToNothing = () => () => {};
+const canReadClockOnClient = () => true;
+const canReadClockOnServer = () => false;
+
 /** Whether a format is non-relative (i.e. shows a fixed date/time). */
 function isAbsoluteFormat(
   format: TimestampFormat,
@@ -279,7 +293,29 @@ export function Timestamp({
   const locale = useLocale();
   const timeRef = useRef<HTMLTimeElement>(null);
   const mergedTimeRef = useMergedRefs(ref, timeRef);
-  const [now, setNow] = useState(() => new Date());
+  // Only relative and auto formats depend on the current time. Absolute
+  // formats never read the clock, so they render identically on the server,
+  // in a static prerender, and on the client. A clock-dependent format reads
+  // it on the client only: server renders and the hydration pass show the
+  // full date and time in UTC, and the client switches to the relative phrase
+  // right after hydration.
+  const needsClock = !isAbsoluteFormat(format);
+  const canReadClock = useSyncExternalStore(
+    subscribeToNothing,
+    canReadClockOnClient,
+    canReadClockOnServer,
+  );
+  const [now, setNow] = useState<Date | null>(() =>
+    needsClock && canReadClock ? new Date() : null,
+  );
+  // Read the clock during render once it may be read: after hydration (the
+  // store re-renders with its client value) and when `format` switches from
+  // an absolute value to a clock-dependent one, so the placeholder never
+  // commits on the client.
+  if (needsClock && canReadClock && now === null) {
+    // eslint-disable-next-line @eslint-react/purity -- seeds clock state once, like the initializer; never runs on the server or while hydrating
+    setNow(new Date());
+  }
 
   const date = parseValue(value);
   // An unparseable value (a malformed date string, or a NaN timestamp from
@@ -289,25 +325,40 @@ export function Timestamp({
   const isValidDate = !Number.isNaN(date.getTime());
   const isoString = isValidDate ? date.toISOString() : '';
 
-  // Determine effective format
-  const diffSeconds = Math.round((now.getTime() - date.getTime()) / 1000);
-  const effectiveFormat: TimestampFormat =
-    format === 'auto'
+  // Determine effective format. Until the clock is read, a clock-dependent
+  // format renders as the full date and time.
+  const isClockPending = needsClock && now === null;
+  const diffSeconds =
+    now === null ? 0 : Math.round((now.getTime() - date.getTime()) / 1000);
+  const effectiveFormat: TimestampFormat = isClockPending
+    ? 'date_time'
+    : format === 'auto'
       ? Math.abs(diffSeconds) <= autoThreshold
         ? 'relative'
         : 'date_time'
       : format;
 
-  // Format the display text. No time zone is passed: the visible text always
-  // reads in the viewer's own zone, and only the tooltip names others.
+  // Format the display text in the viewer's own zone; only the tooltip names
+  // others. The one exception is the pre-hydration placeholder, written in
+  // UTC with its label so every zone produces the same markup.
   const displayText = !isValidDate
     ? ''
     : effectiveFormat === 'relative'
-      ? formatRelativeTime(date, now, locale, 'long')
+      ? formatRelativeTime(date, now ?? date, locale, 'long')
       : effectiveFormat === 'relative_short'
-        ? formatRelativeTime(date, now, locale, 'narrow')
+        ? formatRelativeTime(date, now ?? date, locale, 'narrow')
         : isAbsoluteFormat(effectiveFormat)
-          ? formatInstant(date, effectiveFormat, locale, {isTimezoneShown})
+          ? formatInstant(
+              date,
+              effectiveFormat,
+              locale,
+              // The pre-hydration placeholder is written in UTC, labelled, so
+              // the server and the hydrating client produce the same text in
+              // every time zone.
+              isClockPending
+                ? {timeZone: 'UTC', isTimezoneShown: true}
+                : {isTimezoneShown},
+            )
           : '';
 
   // Full absolute text for the tooltip (visible — keeps the compact timezone

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>
+  );
+}