@astryxdesign/core 0.7.2 → 0.7.3-canary.06872b4

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

package/src/Tooltip/__tests__/Tooltip.a11y.states.ts

@@ -0,0 +1,132 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Tooltip.a11y.states.ts
+ * @input Tooltip's and useTooltip's representative states and the facts TOOLTIP_PATTERN reads
+ * @output TOOLTIP_BINDING_STATES and the explicit ownership exclusions for this binding
+ * @position Binding inventory shared by the jsdom test and the Chromium spec (Tooltip and useTooltip under spec:AST-020 FR15)
+ */
+
+import type {TooltipStateFacts} from '@astryxdesign/a11y-spec';
+
+/**
+ * How the caller attaches the tooltip: wrapping an element, wrapping plain
+ * text, pointing `anchorRef` at its own element, or calling `useTooltip`.
+ */
+export type TooltipAttachment =
+  'wrapped-element' | 'text' | 'anchor-ref' | 'hook';
+
+export interface TooltipBindingState {
+  readonly id: string;
+  readonly summary: string;
+  readonly storyId: string;
+  readonly attachment: TooltipAttachment;
+  /**
+   * The trigger's visible text. A `button` trigger is also named by it; a
+   * text trigger has no role, so the lanes find it by this text.
+   */
+  readonly triggerText: string;
+  readonly triggerRole: 'button' | null;
+  /** The tooltip `content`. */
+  readonly content: string;
+  /** A visible hint the trigger is already described by, besides the tooltip. */
+  readonly hint?: string;
+  readonly facts: TooltipStateFacts;
+}
+
+const story = (id: string) => `a11y-tooltip--${id}`;
+
+/** Tooltip's and useTooltip's default hover delay. */
+const DEFAULT_DELAY: TooltipStateFacts = {showsOnHover: true, showDelayMs: 200};
+
+export const TOOLTIP_BINDING_STATES = [
+  {
+    id: 'wrapped-button',
+    summary:
+      'a Tooltip wrapping a Button, which attaches to the Button and describes it',
+    storyId: story('wrapped-button'),
+    attachment: 'wrapped-element',
+    triggerText: 'Save',
+    triggerRole: 'button',
+    content: 'Saves your changes to this draft',
+    facts: DEFAULT_DELAY,
+  },
+  {
+    id: 'text-trigger',
+    summary:
+      'a Tooltip wrapping plain text, which renders its own focusable inline trigger',
+    storyId: story('text-trigger'),
+    attachment: 'text',
+    triggerText: 'Draft',
+    triggerRole: null,
+    content: 'Only you can see a draft',
+    facts: DEFAULT_DELAY,
+  },
+  {
+    id: 'anchor-ref-with-hint',
+    summary:
+      'a Tooltip attached through anchorRef to a caller button that is already described by a visible hint, so the trigger is described by both',
+    storyId: story('anchor-ref-with-hint'),
+    attachment: 'anchor-ref',
+    triggerText: 'Publish',
+    triggerRole: 'button',
+    content: 'Makes this page visible to everyone',
+    hint: 'Last published yesterday',
+    facts: DEFAULT_DELAY,
+  },
+  {
+    id: 'use-tooltip-hook',
+    summary:
+      "useTooltip on a caller button, which spreads the hook's ref and describedBy onto it and renders the tooltip",
+    storyId: story('use-tooltip-hook'),
+    attachment: 'hook',
+    triggerText: 'Archive',
+    triggerRole: 'button',
+    content: 'Moves this page out of the list',
+    facts: DEFAULT_DELAY,
+  },
+] as const satisfies ReadonlyArray<TooltipBindingState>;
+
+export const TOOLTIP_EXCLUSIONS = [
+  {
+    id: 'focus-trigger',
+    owner:
+      "the 24 core hosts that pass focusTrigger 'always' — the disabledMessage tooltips on the field and choice controls (TextInput, TextArea, NumberInput, Switch, CheckboxInput, CheckboxList, RadioList, Selector, MultiSelector, SegmentedControl, Slider, Typeahead, Tokenizer, FileInput, and the date and time inputs), the Slider value bubble and ProgressBar marks — each through its own suite (for example TextInput.test.tsx 'shows the reason tooltip on keyboard focus'); and any caller that passes 'never'",
+    reason:
+      "'always' attaches the focus listeners to a wrapper that is not itself focusable, so focusin bubbling from the control inside it shows the hint; the described element and the focused element differ, which this contract's trigger-centred rows do not model, so each host proves its own keyboard path. 'never' detaches focus showing for a trigger inside a composite widget that moves focus itself, which then owns how a keyboard user reaches the hint; no shipped composition uses it. Every state here uses the default 'auto'.",
+  },
+  {
+    id: 'touch-trigger',
+    owner:
+      'useTooltip.test.tsx and Tooltip.test.tsx (touchTrigger suites) through the shared useTouchTrigger hook',
+    reason:
+      'On a touch pointer there is no hover, so a tap opens the tooltip or leaves it to the control the tap operates; the APG defines no touch behaviour, and the Chromium lane drives a mouse and a keyboard only.',
+  },
+  {
+    id: 'controlled-and-disabled',
+    owner:
+      'Tooltip.test.tsx and useTooltip.test.tsx (isOpen, isDefaultOpen and isEnabled suites)',
+    reason:
+      'A controlled tooltip answers Escape by reporting instead of hiding, and a disabled one never shows; both hand visibility to the caller, so the hover and focus outcomes this contract reads belong to the uncontrolled, enabled tooltip every state renders.',
+  },
+  {
+    id: 'interactive-hover-content',
+    owner: 'the HoverCard binding and the overlay-dismissal family',
+    reason:
+      'Hover content a user can interact with is a non-modal dialog, not a tooltip, so HoverCard and other interactive popovers are reviewed separately; no state here places a focusable control inside a tooltip.',
+  },
+  {
+    id: 'host-compositions',
+    owner:
+      "the composing components' own contracts (Button for the IconButton label tooltip, the input status binding for useInputStatusIcon, which renders the on-field status tooltip) and their tests",
+    reason:
+      'IconButton, useInputStatusIcon and Lab InfoTip render Tooltip or useTooltip for their own purposes; this binding proves the tooltip they render, and what each host adds around it is that host.',
+  },
+  {
+    id: 'placement-and-paint',
+    owner:
+      'Tooltip.test.tsx (placement and alignment), the layer runtime anchor tests, and the repository visual gate',
+    reason:
+      'Placement, alignment, the inverted surface and the hover underline on a text trigger are layout and paint; they change no role, description, focus or dismissal outcome, so every state uses the default placement.',
+  },
+] as const;

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

@@ -0,0 +1,126 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+/** @vitest-environment jsdom */
+
+/**
+ * @file Tooltip.a11y.test.tsx
+ * @input TOOLTIP_PATTERN bound to Tooltip's and useTooltip's representative states
+ * @output jsdom-lane proof of the DOM expectations and an honest "unrun" report for the browser layers
+ * @position Binding test for Tooltip and useTooltip (the Chromium spec covers the rest)
+ */
+
+import {cleanup, render, screen} from '@testing-library/react';
+import {describe, expect, it} from 'vitest';
+import {
+  TOOLTIP_PATTERN,
+  checkAccessibilitySpec,
+  createJsdomHarness,
+  expectAccessibilitySpec,
+  summarize,
+  type BindingResult,
+} from '@astryxdesign/a11y-spec';
+import {renderTooltipState} from './Tooltip.a11y.renders';
+import {
+  TOOLTIP_BINDING_STATES,
+  TOOLTIP_EXCLUSIONS,
+  type TooltipBindingState,
+} from './Tooltip.a11y.states';
+
+function triggerFor(state: TooltipBindingState): HTMLElement {
+  return state.triggerRole == null
+    ? screen.getByText(state.triggerText, {exact: true})
+    : screen.getByRole(state.triggerRole, {name: state.triggerText});
+}
+
+function relatedFor(): Readonly<Record<string, Element>> {
+  return {
+    // The tooltip stays in the page while hidden; it is found with hidden
+    // elements included so the DOM rows can read it before it shows.
+    tooltip: screen.getByRole('tooltip', {hidden: true}),
+    before: screen.getByRole('button', {name: 'Before the trigger'}),
+    after: screen.getByRole('button', {name: 'After the trigger'}),
+  };
+}
+
+async function checkState(state: TooltipBindingState): Promise<BindingResult> {
+  return checkAccessibilitySpec({
+    spec: TOOLTIP_PATTERN,
+    binding: 'Tooltip',
+    state: state.id,
+    facts: state.facts,
+    mount: async () => {
+      render(renderTooltipState(state));
+      return createJsdomHarness({
+        subject: triggerFor(state),
+        related: relatedFor(),
+      });
+    },
+    unmount: cleanup,
+  });
+}
+
+describe('Tooltip — tooltip pattern, jsdom lane', () => {
+  it.each(
+    TOOLTIP_BINDING_STATES.map(
+      state => [state.id, state.summary, state] as const,
+    ),
+  )('%s — %s', async (_id, _summary, state) => {
+    await expectAccessibilitySpec({
+      spec: TOOLTIP_PATTERN,
+      binding: 'Tooltip',
+      state: state.id,
+      facts: state.facts,
+      render: () => {
+        render(renderTooltipState(state));
+      },
+      subject: () => triggerFor(state),
+      related: () => relatedFor(),
+      cleanup,
+    });
+  });
+
+  it('runs the DOM layer and reports the browser-owned outcomes as unrun', async () => {
+    const results: BindingResult[] = [];
+    for (const state of TOOLTIP_BINDING_STATES) {
+      results.push(await checkState(state));
+    }
+    const report = summarize(TOOLTIP_PATTERN, results);
+    expect(report.counts.pass).toBeGreaterThan(0);
+    expect(report.unrunLayers).toEqual(['accessibility-tree', 'real-browser']);
+    expect(report.counts.unexpectedPass).toBe(0);
+  });
+});
+
+describe('tooltip binding inventory', () => {
+  it('gives every representative state a distinct checked-in story', () => {
+    const stories = TOOLTIP_BINDING_STATES.map(state => state.storyId);
+    expect(new Set(stories).size).toBe(stories.length);
+  });
+
+  it('keeps focus-trigger opt-outs, touch, controlled visibility, interactive hover content, host compositions and paint explicit', () => {
+    expect(TOOLTIP_EXCLUSIONS.map(row => row.id)).toEqual([
+      'focus-trigger',
+      'touch-trigger',
+      'controlled-and-disabled',
+      'interactive-hover-content',
+      'host-compositions',
+      'placement-and-paint',
+    ]);
+    for (const exclusion of TOOLTIP_EXCLUSIONS) {
+      expect(exclusion.owner.length, exclusion.id).toBeGreaterThan(20);
+      expect(exclusion.reason.length, exclusion.id).toBeGreaterThan(80);
+    }
+  });
+
+  it('renders the trigger, one tooltip and both page buttons for every state', () => {
+    for (const state of TOOLTIP_BINDING_STATES) {
+      render(renderTooltipState(state));
+      expect(triggerFor(state), state.id).toBeTruthy();
+      expect(
+        screen.getAllByRole('tooltip', {hidden: true}),
+        state.id,
+      ).toHaveLength(1);
+      expect(Object.keys(relatedFor())).toEqual(['tooltip', 'before', 'after']);
+      cleanup();
+    }
+  });
+});

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

@@ -0,0 +1,74 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file TooltipHoverBridge.a11y.chromium.spec.ts
+ * @input The `Core/Tooltip` Default story in a built Storybook and real mouse
+ *   input.
+ * @output Real-engine proof that a pointer moving from the trigger onto the
+ *   tooltip in one step keeps the tooltip open (WCAG 2.2 1.4.13 Content on
+ *   Hover or Focus, hoverable), and that leaving the tooltip still hides it.
+ * @position Run with `pnpm test:a11y-contract`. The defect lives in the order
+ *   the engine dispatches mouseout and mouseleave on one pointer step, which
+ *   only a real engine produces.
+ */
+
+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';
+
+let storybook: StaticServer;
+
+test.beforeAll(async () => {
+  storybook = await serveStorybook(
+    process.env.ASTRYX_STORYBOOK_DIR ?? DEFAULT_STORYBOOK_DIR,
+  );
+});
+
+test.afterAll(async () => {
+  await storybook?.close();
+});
+
+const STORY = 'core-tooltip--default';
+
+async function openTooltip(page: Page) {
+  await page.setViewportSize({width: 900, height: 600});
+  await page.goto(`${storybook.origin}/iframe.html?id=${STORY}&viewMode=story`);
+  await holdMotionStill(page);
+  const trigger = page.getByRole('button', {name: 'Hover me'});
+  await trigger.hover();
+  const tooltip = page.getByRole('tooltip');
+  await expect(tooltip).toBeVisible();
+  const t = await trigger.boundingBox();
+  const s = await tooltip.boundingBox();
+  if (t == null || s == null) {
+    throw new Error('the trigger or the tooltip has no layout box');
+  }
+  return {tooltip, s};
+}
+
+test('a one-step move from the trigger onto the tooltip keeps it open', async ({
+  page,
+}) => {
+  const {tooltip, s} = await openTooltip(page);
+
+  // One mousemove event straight onto the tooltip, as a quick hand makes.
+  await page.mouse.move(s.x + s.width / 2, s.y + s.height / 2);
+  // Well past the 100ms hover bridge.
+  await page.waitForTimeout(400);
+
+  await expect(tooltip).toBeVisible();
+});
+
+test('leaving the tooltip for the page still hides it', async ({page}) => {
+  const {tooltip, s} = await openTooltip(page);
+
+  await page.mouse.move(s.x + s.width / 2, s.y + s.height / 2);
+  await page.waitForTimeout(200);
+  await page.mouse.move(5, 5);
+
+  await expect(tooltip).toBeHidden();
+});

package/src/Tooltip/useTooltip.test.tsx

@@ -214,6 +214,29 @@ describe('useTooltip — hide delay', () => {
     expect(onHide).toHaveBeenCalledTimes(1);
   });
 
+  it('stays open when the pointer crosses onto the tooltip in one step', () => {
+    const onHide = vi.fn();
+    showTooltip(onHide);
+    const surface = tooltipElement();
+
+    // A one-step crossing dispatches in browser order: the trigger's mouseout
+    // (React derives the surface's onMouseEnter from it), then the trigger's
+    // native mouseleave, both pointing at the surface. fireEvent.mouseLeave
+    // would add a mouseout after the leave, so the leave is dispatched raw.
+    fireEvent.mouseOut(trigger(), {relatedTarget: surface});
+    act(() => {
+      trigger().dispatchEvent(
+        new MouseEvent('mouseleave', {relatedTarget: surface}),
+      );
+    });
+    tick(500);
+    expect(onHide).not.toHaveBeenCalled();
+
+    fireEvent.mouseOut(surface, {relatedTarget: document.body});
+    tick(100);
+    expect(onHide).toHaveBeenCalledTimes(1);
+  });
+
   it('uses an explicit hideDelay instead of the hover bridge', () => {
     const onHide = vi.fn();
     showTooltip(onHide, {hideDelay: 500});

package/src/Tooltip/useTooltip.tsx

@@ -397,15 +397,28 @@ export function useTooltip(options: TooltipOptions = {}): TooltipReturn {
     scheduleShow();
   }, [isTouchPointerRef, scheduleShow]);
 
-  const handleMouseLeave = useCallback(() => {
-    // On touch the synthesized mouseleave arrives with the next tap elsewhere,
-    // which the outside-tap dismissal already handles — and handling it here
-    // too would close the tooltip behind the tap-open bookkeeping's back.
-    if (isTouchPointerRef.current) {
-      return;
-    }
-    scheduleHide();
-  }, [isTouchPointerRef, scheduleHide]);
+  const handleMouseLeave = useCallback(
+    (event: Event) => {
+      // On touch the synthesized mouseleave arrives with the next tap elsewhere,
+      // which the outside-tap dismissal already handles — and handling it here
+      // too would close the tooltip behind the tap-open bookkeeping's back.
+      if (isTouchPointerRef.current) {
+        return;
+      }
+      // Leaving straight onto the tooltip: the surface's onMouseEnter already
+      // ran, because React dispatches it from the mouseout that precedes this
+      // mouseleave, so a hide scheduled now would never be cancelled. The
+      // surface's own mouse leave schedules the hide instead.
+      const next = (event as MouseEvent).relatedTarget as Node | null;
+      const surface =
+        next == null ? null : next.ownerDocument?.getElementById(layerId);
+      if (surface != null && surface.contains(next)) {
+        return;
+      }
+      scheduleHide();
+    },
+    [isTouchPointerRef, layerId, scheduleHide],
+  );
 
   const handleFocusIn = useCallback(
     (e: Event) => {