@astryxdesign/core 0.6.2 → 0.6.3-canary.01fa439

package/src/ToggleButton/ToggleButton.test.tsx

@@ -3,7 +3,8 @@
 /**
  * @file ToggleButton.test.tsx
  * @input Uses vitest, @testing-library/react, ToggleButton, ToggleButtonGroup
- * @output Unit tests for ToggleButton and ToggleButtonGroup
+ * @output Unit tests for ToggleButton callback/Action order, pending state,
+ *   group-owned selection, and ToggleButtonGroup
  *
  * SYNC: When ToggleButton.tsx or ToggleButtonGroup.tsx changes, update tests
  */
@@ -388,8 +389,94 @@ describe('ToggleButton', () => {
     expect(pressedChangeAction).toHaveBeenCalledWith(true);
   });
 
+  it('runs the synchronous callback before the Action with the same next state', async () => {
+    const calls: string[] = [];
+    const pressedChangeAction = vi.fn(() => {
+      calls.push('action');
+    });
+    const onPressedChange = vi.fn(() => {
+      expect(pressedChangeAction).not.toHaveBeenCalled();
+      calls.push('change');
+    });
+    render(
+      <ToggleButton
+        label="Favorite"
+        isPressed={false}
+        onPressedChange={onPressedChange}
+        pressedChangeAction={pressedChangeAction}
+      />,
+    );
+
+    await userEvent.setup().click(screen.getByRole('button'));
+
+    expect(calls).toEqual(['change', 'action']);
+    expect(onPressedChange).toHaveBeenCalledExactlyOnceWith(
+      true,
+      expect.anything(),
+    );
+    expect(pressedChangeAction).toHaveBeenCalledExactlyOnceWith(true);
+  });
+
+  it('keeps callback-only controlled toggles synchronous without pending feedback', async () => {
+    function LegacyToggle() {
+      const [isPressed, setIsPressed] = useState(false);
+      return (
+        <ToggleButton
+          label="Bold"
+          isPressed={isPressed}
+          onPressedChange={setIsPressed}
+        />
+      );
+    }
+    render(<LegacyToggle />);
+    const button = screen.getByRole('button');
+
+    fireEvent.click(button);
+    expect(button).toHaveAttribute('aria-pressed', 'true');
+    expect(button).not.toHaveAttribute('aria-busy', 'true');
+    fireEvent.click(button);
+    expect(button).toHaveAttribute('aria-pressed', 'false');
+    expect(button).not.toHaveAttribute('aria-busy', 'true');
+    await act(async () => {});
+  });
+
+  it('runs an Action without onPressedChange and settles to the controlled value', async () => {
+    let resolveAction: (() => void) | undefined;
+    const pressedChangeAction = vi.fn(
+      async () =>
+        new Promise<void>(resolve => {
+          resolveAction = resolve;
+        }),
+    );
+    const {rerender} = render(
+      <ToggleButton
+        label="Favorite"
+        isPressed={false}
+        pressedChangeAction={pressedChangeAction}
+      />,
+    );
+    const button = screen.getByRole('button');
+
+    await userEvent.setup().click(button);
+    expect(pressedChangeAction).toHaveBeenCalledExactlyOnceWith(true);
+    expect(button).toHaveAttribute('aria-pressed', 'true');
+    expect(button).toHaveAttribute('aria-busy', 'true');
+    await act(async () => resolveAction?.());
+    expect(button).toHaveAttribute('aria-pressed', 'false');
+    expect(button).not.toHaveAttribute('aria-busy', 'true');
+
+    rerender(
+      <ToggleButton
+        label="Favorite"
+        isPressed
+        pressedChangeAction={pressedChangeAction}
+      />,
+    );
+    expect(button).toHaveAttribute('aria-pressed', 'true');
+    expect(pressedChangeAction).toHaveBeenCalledTimes(1);
+  });
+
   it('skips pressedChangeAction when onPressedChange calls preventDefault', async () => {
-    const user = userEvent.setup();
     const pressedChangeAction = vi.fn();
     const onPressedChange = vi.fn(
       (_next: boolean, event: MouseEvent<HTMLButtonElement>) => {
@@ -406,10 +493,17 @@ describe('ToggleButton', () => {
       />,
     );
 
-    await user.click(screen.getByRole('button', {name: 'Favorite'}));
+    const button = screen.getByRole('button', {name: 'Favorite'});
+    fireEvent.click(button);
 
-    expect(onPressedChange).toHaveBeenCalledWith(true, expect.anything());
+    expect(onPressedChange).toHaveBeenCalledExactlyOnceWith(
+      true,
+      expect.anything(),
+    );
     expect(pressedChangeAction).not.toHaveBeenCalled();
+    expect(button).toHaveAttribute('aria-pressed', 'false');
+    expect(button).not.toHaveAttribute('aria-busy', 'true');
+    await act(async () => {});
   });
 });
 
@@ -570,6 +664,207 @@ describe('ToggleButtonGroup (multiple)', () => {
   });
 });
 
+// =============================================================================
+// Group ownership — member Actions must not compete with controlled selection
+// =============================================================================
+
+describe.each(['single', 'multiple'] as const)(
+  'ToggleButtonGroup (%s) ownership',
+  type => {
+    it('keeps selection group-owned even when a member has standalone handlers', async () => {
+      const onChange = vi.fn();
+      const onPressedChange = vi.fn();
+      const pressedChangeAction = vi.fn();
+      const groupProps =
+        type === 'single'
+          ? {type, value: 'list', onChange}
+          : {type, value: ['list'], onChange};
+      const children = (
+        <>
+          <ToggleButton value="list" label="List" isPressed={false} />
+          <ToggleButton
+            value="grid"
+            label="Grid"
+            isPressed
+            onPressedChange={onPressedChange}
+            pressedChangeAction={pressedChangeAction}
+          />
+        </>
+      );
+      const {rerender} = render(
+        <ToggleButtonGroup {...groupProps} label="View">
+          {children}
+        </ToggleButtonGroup>,
+      );
+      const grid = screen.getByRole('button', {name: 'Grid'});
+      expect(grid).toHaveAttribute('aria-pressed', 'false');
+      expect(screen.getByRole('button', {name: 'List'})).toHaveAttribute(
+        'aria-pressed',
+        'true',
+      );
+
+      await userEvent.setup().click(grid);
+      expect(onChange).toHaveBeenCalledExactlyOnceWith(
+        type === 'single' ? 'grid' : ['list', 'grid'],
+      );
+      expect(onPressedChange).not.toHaveBeenCalled();
+      expect(pressedChangeAction).not.toHaveBeenCalled();
+      expect(grid).toHaveAttribute('aria-pressed', 'false');
+      expect(grid).not.toHaveAttribute('aria-busy', 'true');
+
+      const acceptedProps =
+        type === 'single'
+          ? {type, value: 'grid', onChange}
+          : {type, value: ['list', 'grid'], onChange};
+      rerender(
+        <ToggleButtonGroup {...acceptedProps} label="View">
+          {children}
+        </ToggleButtonGroup>,
+      );
+      expect(grid).toHaveAttribute('aria-pressed', 'true');
+      await userEvent.setup().click(grid);
+      expect(onChange).toHaveBeenLastCalledWith(
+        type === 'single' ? null : ['list'],
+      );
+      expect(onPressedChange).not.toHaveBeenCalled();
+      expect(pressedChangeAction).not.toHaveBeenCalled();
+    });
+  },
+);
+
+// =============================================================================
+// Disabled state — family:buttons FR3 (disabled means non-operable)
+// =============================================================================
+
+/**
+ * Two ways a ToggleButton becomes unavailable, and the rule that binds them:
+ * a group disables everything it contains, and a member can disable itself
+ * while the group stays enabled. Neither source may cancel the other out.
+ *
+ * The tooltip cases are here at the attribute and callback level only. A
+ * tooltip'd disabled toggle carries `aria-disabled` instead of the native
+ * `disabled` attribute, so whether a REAL mouse press is refused is an engine
+ * fact that jsdom's synthetic click cannot settle — that half lives in
+ * ./__tests__/ToggleButton.a11y.chromium.spec.ts.
+ */
+describe('disabled state', () => {
+  it('keeps a member disabled when the group disables nothing', async () => {
+    const user = userEvent.setup();
+    const handleChange = vi.fn();
+    render(
+      <ToggleButtonGroup value={null} onChange={handleChange} label="View mode">
+        <ToggleButton value="list" label="List" isDisabled />
+        <ToggleButton value="grid" label="Grid" />
+      </ToggleButtonGroup>,
+    );
+
+    expect(screen.getByRole('button', {name: 'List'})).toBeDisabled();
+
+    await user.click(screen.getByRole('button', {name: 'List'}));
+    expect(handleChange).not.toHaveBeenCalled();
+  });
+
+  it('leaves the rest of an enabled group selectable', async () => {
+    const user = userEvent.setup();
+    const handleChange = vi.fn();
+    render(
+      <ToggleButtonGroup value={null} onChange={handleChange} label="View mode">
+        <ToggleButton value="list" label="List" isDisabled />
+        <ToggleButton value="grid" label="Grid" />
+      </ToggleButtonGroup>,
+    );
+
+    expect(screen.getByRole('button', {name: 'Grid'})).toBeEnabled();
+
+    await user.click(screen.getByRole('button', {name: 'Grid'}));
+    expect(handleChange).toHaveBeenCalledWith('grid');
+  });
+
+  it('still disables a member that says nothing when the group is disabled', async () => {
+    const user = userEvent.setup();
+    const handleChange = vi.fn();
+    render(
+      <ToggleButtonGroup
+        value={null}
+        onChange={handleChange}
+        label="View mode"
+        isDisabled>
+        <ToggleButton value="list" label="List" />
+      </ToggleButtonGroup>,
+    );
+
+    expect(screen.getByRole('button', {name: 'List'})).toBeDisabled();
+
+    await user.click(screen.getByRole('button', {name: 'List'}));
+    expect(handleChange).not.toHaveBeenCalled();
+  });
+
+  it('keeps a tooltip-bearing disabled member focusable but inert', async () => {
+    const user = userEvent.setup();
+    const handleChange = vi.fn();
+    render(
+      <ToggleButtonGroup value={null} onChange={handleChange} label="View mode">
+        <ToggleButton
+          value="list"
+          label="List"
+          tooltip="List view is unavailable for this dataset"
+          isDisabled
+        />
+      </ToggleButtonGroup>,
+    );
+
+    const member = screen.getByRole('button', {name: 'List'});
+    // The tooltip is the disabled reason, so the control stays reachable to
+    // read it: aria-disabled rather than the native attribute, which would
+    // take it out of the tab order along with its own explanation.
+    expect(member).toHaveAttribute('aria-disabled', 'true');
+    expect(member).not.toBeDisabled();
+
+    await user.click(member);
+    expect(handleChange).not.toHaveBeenCalled();
+  });
+
+  it('does not toggle a standalone disabled toggle that carries a tooltip', async () => {
+    const user = userEvent.setup();
+    const handleChange = vi.fn();
+    render(
+      <ToggleButton
+        label="Bold"
+        tooltip="Formatting is locked for this document"
+        isPressed={false}
+        onPressedChange={handleChange}
+        isDisabled
+      />,
+    );
+
+    const toggle = screen.getByRole('button', {name: 'Bold'});
+    expect(toggle).toHaveAttribute('aria-disabled', 'true');
+
+    await user.click(toggle);
+    expect(handleChange).not.toHaveBeenCalled();
+    expect(toggle).toHaveAttribute('aria-pressed', 'false');
+  });
+
+  it('still toggles an enabled toggle that carries the same tooltip', async () => {
+    const user = userEvent.setup();
+    const handleChange = vi.fn();
+    render(
+      <ToggleButton
+        label="Bold"
+        tooltip="Bold the selected text"
+        isPressed={false}
+        onPressedChange={handleChange}
+      />,
+    );
+
+    const toggle = screen.getByRole('button', {name: 'Bold'});
+    expect(toggle).not.toHaveAttribute('aria-disabled');
+
+    await user.click(toggle);
+    expect(handleChange).toHaveBeenCalledWith(true, expect.anything());
+  });
+});
+
 // jsdom cannot emulate forced-colors rendering, so these assert that the
 // compiled output includes the forced-colors rules; visual behavior needs
 // manual verification under Windows High Contrast.

package/src/ToggleButton/ToggleButton.tsx

@@ -9,7 +9,7 @@
  * @position Thin wrapper over Button; adds controlled toggle pattern
  *
  * ToggleButton wraps Button with `isPressed` and adds:
- * - `onPressedChange` controlled toggle callback
+ * - `onPressedChange` from internal `onClick`; `pressedChangeAction` via Button
  * - `pressedIcon` for outline-to-filled icon swap
  * - Font weight shift on press with width reservation to prevent layout shift
  * - Group integration via ToggleButtonGroupContext
@@ -116,10 +116,12 @@ export interface ToggleButtonProps extends BaseProps<HTMLButtonElement> {
   ) => void;
 
   /**
-   * Action handler for API- or navigation-backed toggles, run inside a
-   * transition by Button. The button shows a loading spinner while the action
-   * is pending — whether it returns a promise or synchronously triggers a
-   * suspending update (e.g. a router navigation that suspends on data).
+   * Action handler for API- or navigation-backed toggles, run through Button's
+   * clickAction transition after onPressedChange unless that callback prevents
+   * default. It also runs without a callback. Omit it for callback-only toggles
+   * that need no Action transition. The button shows a loading spinner while
+   * the action is pending, including synchronous actions that suspend.
+   * Ignored when a value identifies this button as a ToggleButtonGroup member.
    *
    * @example
    * ```
@@ -154,7 +156,8 @@ export interface ToggleButtonProps extends BaseProps<HTMLButtonElement> {
 
   /**
    * Whether the button is disabled.
-   * When used inside ToggleButtonGroup, the group's isDisabled overrides this.
+   * When used inside ToggleButtonGroup, a disabled group disables this button
+   * too, but an enabled group does not re-enable a button that disables itself.
    * @default false
    */
   isDisabled?: boolean;
@@ -263,54 +266,44 @@ export function ToggleButton({
       ? group.selectedValues.has(value)
       : (isPressedProp ?? false);
   const size = sizeProp ?? group?.size ?? 'md';
-  const isDisabled = group?.isDisabled ?? isDisabledProp;
+  // Either source disabling this button is enough. `??` could not express that:
+  // the group always supplies a boolean (its own prop defaults to false), so the
+  // fallback never ran and an enabled group handed a member that had disabled
+  // itself its availability back. A group still disables everything it contains
+  // — that is the half `??` got right — but it cannot re-enable a member
+  // (family:buttons FR3).
+  const isDisabled = (group?.isDisabled ?? false) || isDisabledProp;
 
-  // Track the pressed state optimistically so the button reflects the intended
-  // state immediately while an async action is pending. The optimistic update
-  // is applied inside Button's clickAction transition (below), satisfying
-  // React's "useOptimistic must run in a transition" rule.
   const [optimisticPressed, setOptimisticPressed] =
     useOptimistic(committedPressed);
   const isPressed = optimisticPressed;
-
-  // Next state derives from the *optimistic* value, not the committed one, so a
-  // re-click while an action is pending reads the in-flight intent and toggles
-  // (true -> false -> true) rather than recomputing from the stale committed
-  // state. handleClick and clickAction share this so the callback and the
-  // optimistic update always agree within a single click.
+  // Both paths use the same in-flight intent, so re-clicks reverse a pending
+  // toggle rather than deriving from the stale controlled value.
   const nextPressed = !isPressed;
-
   const resolvedIcon = isPressed && pressedIcon ? pressedIcon : icon;
 
-  // Synchronous part of the toggle. Button calls onClick before clickAction and
-  // skips clickAction when the event is defaultPrevented, so calling
-  // preventDefault() inside onPressedChange opts out of pressedChangeAction.
   const handleClick = (event: React.MouseEvent<HTMLButtonElement>) => {
     if (isDisabled) {
       return;
     }
     if (group && value != null) {
-      // Group mode delegates selection to the group; no async-action path.
       group.toggle(value);
       event.preventDefault();
       return;
     }
+
     onPressedChangeProp?.(nextPressed, event);
   };
 
-  // Async part of the toggle, run inside Button's transition (so the optimistic
-  // update is valid and Button's isPending drives the pending spinner). Skipped
-  // automatically by Button when handleClick called preventDefault, and never
-  // wired in group mode (where there is no async action). Button is rendered
-  // interruptible, so it stays clickable while pending and a re-click starts a
-  // fresh transition that interrupts the previous one.
+  // Button runs onClick first and skips clickAction when the callback prevents
+  // default. Its transition owns both the optimistic update and pending UI.
   const clickAction =
-    group && value != null
-      ? undefined
-      : async () => {
+    pressedChangeAction && !(group && value != null)
+      ? async () => {
           setOptimisticPressed(nextPressed);
-          await pressedChangeAction?.(nextPressed);
-        };
+          await pressedChangeAction(nextPressed);
+        }
+      : undefined;
 
   // isIconOnly prop is the source of truth for icon-only rendering.
   const labelContent =

package/src/ToggleButton/ToggleButtonGroup.doc.mjs

@@ -11,7 +11,7 @@ export const docs = {
     {
       name: 'children',
       type: 'ReactNode',
-      description: 'ToggleButton children.',
+      description: 'ToggleButton children. Give each member a value; the group owns its pressed state and ignores its isPressed, onPressedChange, and pressedChangeAction props. Member activation calls the group’s onChange without starting a member Action transition.',
       required: true,
       slotElements: [
         {
@@ -83,7 +83,7 @@ export const docsZh = {
   displayName: 'Toggle Button Group',
   description: '将切换按钮分组，支持单选或多选行为。通过 type 判别联合类型实现类型安全。',
   propDescriptions: {
-    children: 'ToggleButton 子元素。',
+    children: 'ToggleButton 子元素；每个成员都需要 value。分组控制按下状态，并忽略成员的 isPressed、onPressedChange 和 pressedChangeAction。激活成员只调用分组的 onChange，不启动成员的 Action 过渡。',
     label: '分组的无障碍标签 (aria-label)。',
     type: '选择模式。single 允许单个激活，multiple 允许多个。',
     value: '当前选中的值。类型取决于选择模式。',
@@ -101,7 +101,7 @@ export const docsDense = {
   displayName: 'Toggle Button Group',
   description: 'groups toggle btns for exclusive/multi-select; discriminated union on type',
   propDescriptions: {
-    children: 'ToggleButton children',
+    children: 'ToggleButton children; each member needs a value. Group owns pressed state; member isPressed/onPressedChange/pressedChangeAction are ignored. Selection uses group onChange, with no member Action transition.',
     label: 'a11y label (aria-label)',
     type: 'selection mode: single or multiple',
     value: 'selected value(s); type depends on mode',

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

@@ -0,0 +1,209 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file ToggleButton.a11y.chromium.spec.ts
+ * @input Uses @playwright/test, the a11y-spec static Storybook server, and the
+ *   checked-in ToggleButtonDisabledA11y stories
+ * @output Real-browser evidence for `docs/families/buttons.md` FR3 — disabled
+ *   means non-operable — across the two ways a ToggleButton becomes disabled,
+ *   plus the enabled control that catches a fix which disables too much.
+ * @position The half of FR3 that jsdom cannot honestly reach. A disabled toggle
+ *   kept focusable by a tooltip carries `aria-disabled` instead of the native
+ *   `disabled` attribute, so whether a real mouse press is refused is an engine
+ *   fact — jsdom's synthetic click does not settle it
+ *   (`docs/specs/AST-013/spec.md`: a browser claim is made in a browser).
+ *
+ * Each state drives a checked-in story rather than a page this file builds, so
+ * the reproduction path for any failure is a URL a person can open
+ * (`docs/specs/AST-009/spec.md` FR30). Each story counts its own activations,
+ * which is what `activationsOn` reads — a toggle that refuses a press leaves no
+ * trace on itself.
+ *
+ * Presses go through `page.mouse` at the control's own centre rather than
+ * `locator.click()`. Playwright's actionability wait would refuse to press a
+ * natively disabled control at all, which would prove nothing about what the
+ * engine does with a press that really lands.
+ *
+ * SYNC: Fixtures live in
+ *   /apps/storybook/stories/ToggleButtonDisabledA11y.stories.tsx.
+ */
+
+import {expect, test, type Page} from '@playwright/test';
+import {holdMotionStill} from '@astryxdesign/a11y-spec/chromium';
+import {
+  DEFAULT_STORYBOOK_DIR,
+  serveStorybook,
+  type StaticServer,
+} from '@astryxdesign/a11y-spec/storybook';
+
+const STORY_BASE = 'a11y-togglebutton-disabled-state';
+
+let storybook: StaticServer;
+
+test.beforeAll(async () => {
+  storybook = await serveStorybook(
+    process.env.ASTRYX_STORYBOOK_DIR ?? DEFAULT_STORYBOOK_DIR,
+  );
+});
+
+test.afterAll(async () => {
+  await storybook?.close();
+});
+
+/** Load a story and wait for the control the assertions press. */
+async function mountStory(page: Page, storyId: string): Promise<void> {
+  await page.goto(
+    `${storybook.origin}/iframe.html?id=${STORY_BASE}--${storyId}&viewMode=story`,
+    {waitUntil: 'load'},
+  );
+  await holdMotionStill(page);
+  await page
+    .locator('#storybook-root')
+    .getByRole('button')
+    .first()
+    .waitFor({state: 'attached'});
+}
+
+/**
+ * How many times this story's own handler has run.
+ *
+ * The story publishes the count as an attribute, so this reads a fact the story
+ * renders rather than instrumenting the page from the test — a person opening
+ * the story sees the same number the spec does.
+ */
+async function activationsOn(page: Page): Promise<number> {
+  const raw = await page
+    .locator('[data-a11y-activations]')
+    .first()
+    .getAttribute('data-a11y-activations');
+  return Number(raw ?? '0');
+}
+
+/**
+ * A real mouse press at the control's own centre, landing whether or not
+ * Playwright would consider the control actionable. This is the press the
+ * expectations are about: a user aiming at a control that looks unavailable.
+ */
+async function pressWithMouse(page: Page, name: string): Promise<void> {
+  const control = page
+    .locator('#storybook-root')
+    .getByRole('button', {name, includeHidden: true})
+    .first();
+  const box = await control.boundingBox();
+  if (box == null) {
+    throw new Error(
+      `"${name}" has no layout box, so no mouse press could land on it`,
+    );
+  }
+  await page.mouse.click(box.x + box.width / 2, box.y + box.height / 2);
+}
+
+/**
+ * Whether the engine reports this control as unavailable, by either of the two
+ * spellings FR3 permits: the native attribute, or focusable `aria-disabled`.
+ */
+async function isUnavailable(page: Page, name: string): Promise<boolean> {
+  return page
+    .locator('#storybook-root')
+    .getByRole('button', {name, includeHidden: true})
+    .first()
+    .evaluate(
+      element =>
+        (element as HTMLButtonElement).disabled ||
+        element.getAttribute('aria-disabled') === 'true',
+    );
+}
+
+test('a member that disables itself stays disabled inside an enabled group', async ({
+  page,
+}) => {
+  await mountStory(page, 'group-enabled-member-disabled');
+
+  expect(
+    await isUnavailable(page, 'List'),
+    'the member sets isDisabled, so it must be exposed as unavailable even though the group disables nothing',
+  ).toBe(true);
+
+  await pressWithMouse(page, 'List');
+  expect(
+    await activationsOn(page),
+    'a disabled member must not invoke the group selection callback (family:buttons FR3)',
+  ).toBe(0);
+});
+
+test('an enabled member of the same group still toggles', async ({page}) => {
+  await mountStory(page, 'group-enabled-member-disabled');
+
+  expect(await isUnavailable(page, 'Grid')).toBe(false);
+
+  await pressWithMouse(page, 'Grid');
+  expect(
+    await activationsOn(page),
+    'the sibling says nothing about its own availability and the group disables nothing, so it must still select',
+  ).toBe(1);
+});
+
+test('a group disabled state still disables a member that says nothing', async ({
+  page,
+}) => {
+  await mountStory(page, 'group-disabled-member-silent');
+
+  expect(await isUnavailable(page, 'List')).toBe(true);
+
+  await pressWithMouse(page, 'List');
+  expect(
+    await activationsOn(page),
+    'a group disabled state overrides member availability (family:buttons FR3)',
+  ).toBe(0);
+});
+
+test('a disabled toggle kept focusable by its tooltip refuses a mouse press', async ({
+  page,
+}) => {
+  await mountStory(page, 'disabled-with-tooltip');
+
+  const control = page.locator('#storybook-root').getByRole('button').first();
+
+  // The tooltip is why this control is focusable rather than natively disabled,
+  // so the press has to be made the way a user reaches it: hover first, let the
+  // tip come up, then press. Pressing cold would skip the hover state the
+  // tooltip's own pointer listeners run in.
+  await control.hover();
+  await expect(page.getByRole('tooltip')).toBeVisible();
+
+  expect(
+    await control.evaluate(element => element.getAttribute('aria-disabled')),
+    'a tooltip keeps the reason reachable by making the control focusable rather than natively disabled',
+  ).toBe('true');
+  expect(await control.getAttribute('aria-pressed')).toBe('false');
+
+  await pressWithMouse(page, 'Bold');
+
+  expect(
+    await activationsOn(page),
+    'focusable is not operable: a disabled toggle must not invoke onPressedChange from a mouse press (family:buttons FR3)',
+  ).toBe(0);
+  expect(
+    await control.getAttribute('aria-pressed'),
+    'the pressed state must not flip',
+  ).toBe('false');
+});
+
+test('an enabled toggle with the same tooltip still toggles on a mouse press', async ({
+  page,
+}) => {
+  await mountStory(page, 'enabled-with-tooltip');
+
+  const control = page.locator('#storybook-root').getByRole('button').first();
+  await control.hover();
+  await expect(page.getByRole('tooltip')).toBeVisible();
+  expect(await control.getAttribute('aria-pressed')).toBe('false');
+
+  await pressWithMouse(page, 'Bold');
+
+  expect(
+    await activationsOn(page),
+    'the enabled path must be untouched by the disabled-state fix',
+  ).toBe(1);
+  expect(await control.getAttribute('aria-pressed')).toBe('true');
+});