Skip to content

An open source design system that's fully customizable and agent ready

TypeScript
38.8 KB
Raw Blame
// Copyright (c) Meta Platforms, Inc. and affiliates.

/**
 * @file Tooltip.test.tsx
 * @input Uses vitest, @testing-library/react, Tooltip component
 * @output Unit tests for Tooltip component behavior
 * @position Testing; validates Tooltip.tsx implementation
 *
 * SYNC: When Tooltip.tsx changes, update tests to match new behavior
 */

import {
  describe,
  it,
  expect,
  vi,
  beforeAll,
  beforeEach,
  afterAll,
} from 'vitest';
import {
  render,
  renderHook,
  screen,
  fireEvent,
  waitFor,
} from '@testing-library/react';
import {useRef} from 'react';
import {Tooltip} from './Tooltip';
import {ClickableCard} from '../ClickableCard/ClickableCard';
import {Item} from '../Item/Item';
import {Token} from '../Token/Token';
import {useTooltip} from './useTooltip';
import {__resetInteractionModalityForTest} from '../utils/interactionModality';
import userEvent from '@testing-library/user-event';
import {IconButton} from '../IconButton/IconButton';
import {Toolbar} from '../Toolbar/Toolbar';
import {TestIcon} from '../__tests__/TestIcon';

// Store original matches to restore later
const originalMatches = HTMLElement.prototype.matches;

// Track popover open state per element
const popoverOpenState = new WeakMap<HTMLElement, boolean>();

// Mock Popover API for jsdom
beforeAll(() => {
  HTMLElement.prototype.showPopover = vi.fn(function (this: HTMLElement) {
    popoverOpenState.set(this, true);
  });
  HTMLElement.prototype.hidePopover = vi.fn(function (this: HTMLElement) {
    popoverOpenState.set(this, false);
  });

  // Only intercept :popover-open, delegate everything else to original
  // eslint-disable-next-line @typescript-eslint/no-explicit-any
  (HTMLElement.prototype as any).matches = function (
    selector: string,
  ): boolean {
    if (selector === ':popover-open') {
      return popoverOpenState.get(this) ?? false;
    }
    return originalMatches.call(this, selector);
  };
});

afterAll(() => {
  // eslint-disable-next-line @typescript-eslint/no-explicit-any
  (HTMLElement.prototype as any).matches = originalMatches;
});

describe('useTooltip identity', () => {
  it('keeps callback refs stable across unchanged rerenders', () => {
    const {result, rerender} = renderHook(() => useTooltip());
    const firstRef = result.current.ref;
    const firstInteractionRef = result.current.interactionRef;

    rerender();

    expect(result.current.ref).toBe(firstRef);
    expect(result.current.interactionRef).toBe(firstInteractionRef);
  });
});

describe('Tooltip', () => {
  it('renders trigger element', () => {
    render(
      <Tooltip content="Tooltip text">
        <button type="button">Trigger</button>
      </Tooltip>,
    );
    expect(screen.getByRole('button', {name: 'Trigger'})).toBeInTheDocument();
  });

  it('renders the content prop inside the tooltip layer', () => {
    render(
      <Tooltip content="Tooltip text">
        <button type="button">Trigger</button>
      </Tooltip>,
    );
    expect(screen.getByRole('tooltip', {hidden: true})).toHaveTextContent(
      'Tooltip text',
    );
  });

  it('calls onOpenChange(true) when shown via hover', async () => {
    const onOpenChange = vi.fn();
    render(
      <Tooltip content="Tooltip text" onOpenChange={onOpenChange} delay={0}>
        <button type="button">Trigger</button>
      </Tooltip>,
    );

    const trigger = screen.getByRole('button', {name: 'Trigger'});
    fireEvent.mouseEnter(trigger);

    await waitFor(() => {
      expect(onOpenChange).toHaveBeenCalledWith(true);
    });
  });

  describe('content taller than the room above and below (spec:AST-059 FR4)', () => {
    it('carries its one combined fallback list from the start, so it never settles over its trigger', async () => {
      render(
        <Tooltip content="Tall tooltip" isDefaultOpen placement="below">
          <button type="button">Trigger</button>
        </Tooltip>,
      );
      const tooltip = await waitFor(() => {
        const el = document.querySelector('[role="tooltip"]') as HTMLElement;
        expect(el).not.toBeNull();
        return el;
      });
      expect(tooltip.style.positionTryFallbacks).toBe(
        'flip-block, --astryx-layer-beside-end, --astryx-layer-beside-start, --astryx-layer-fit-below, --astryx-layer-fit-above',
      );
    });
  });

  describe('isDefaultOpen', () => {
    it('shows tooltip on mount when isDefaultOpen is true', async () => {
      render(
        <Tooltip content="Default open tooltip" isDefaultOpen>
          <button type="button">Trigger</button>
        </Tooltip>,
      );

      // showPopover should be called on mount
      await waitFor(() => {
        expect(HTMLElement.prototype.showPopover).toHaveBeenCalled();
      });
    });

    it('calls onOpenChange(true) on mount when isDefaultOpen is true', async () => {
      const onOpenChange = vi.fn();
      render(
        <Tooltip
          content="Default open tooltip"
          isDefaultOpen
          onOpenChange={onOpenChange}>
          <button type="button">Trigger</button>
        </Tooltip>,
      );

      await waitFor(() => {
        expect(onOpenChange).toHaveBeenCalledWith(true);
      });
    });

    it('does not show tooltip on mount when isDefaultOpen is false', async () => {
      vi.mocked(HTMLElement.prototype.showPopover).mockClear();
      render(
        <Tooltip content="Not default open">
          <button type="button">Trigger</button>
        </Tooltip>,
      );

      // Give it time to potentially fire
      await new Promise(resolve => setTimeout(resolve, 50));
      expect(HTMLElement.prototype.showPopover).not.toHaveBeenCalled();
    });

    it('tooltip is still dismissible after isDefaultOpen', async () => {
      const onOpenChange = vi.fn();
      render(
        <Tooltip
          content="Dismissible tooltip"
          isDefaultOpen
          onOpenChange={onOpenChange}
          hideDelay={0}>
          <button type="button">Trigger</button>
        </Tooltip>,
      );

      // Wait for it to show
      await waitFor(() => {
        expect(onOpenChange).toHaveBeenCalledWith(true);
      });

      // Mouse leave should hide it
      const trigger = screen.getByRole('button', {name: 'Trigger'});
      fireEvent.mouseLeave(trigger);

      await waitFor(() => {
        expect(onOpenChange).toHaveBeenCalledWith(false);
      });
    });
  });

  describe('icon-only trigger', () => {
    // A rendered icon is an SVGElement, and ShowPopoverOptions.source is
    // declared as an HTMLElement. Handing the icon to showPopover throws
    // during dictionary conversion, before the popover opens, so the hint
    // never appeared. (#7226)
    it('opens an icon trigger without passing an SVGElement as the source', async () => {
      const showSpy = vi.mocked(HTMLElement.prototype.showPopover);
      showSpy.mockClear();

      render(
        <Tooltip content="Shared memory" isDefaultOpen>
          <svg data-testid="icon" aria-hidden="true" />
        </Tooltip>,
      );

      await waitFor(() => {
        expect(showSpy).toHaveBeenCalled();
      });

      const [options] = showSpy.mock.calls[0];
      // Compared as a boolean on purpose: a plain `toBeUndefined` failure makes
      // the diff printer walk the SVGElement, which it cannot inspect.
      expect(options?.source === undefined).toBe(true);

      // The icon is still the trigger the ARIA tooltip pattern is wired to.
      expect(screen.getByTestId('icon').getAttribute('aria-describedby')).toBe(
        screen.getByRole('tooltip', {hidden: true}).id,
      );
    });
  });

  describe('WCAG 1.4.13 — content on hover or focus', () => {
    it('dismisses on Escape while visible (dismissible)', async () => {
      const onOpenChange = vi.fn();
      render(
        <Tooltip content="Dismiss me" onOpenChange={onOpenChange} delay={0}>
          <button type="button">Trigger</button>
        </Tooltip>,
      );

      const trigger = screen.getByRole('button', {name: 'Trigger'});
      fireEvent.mouseEnter(trigger);
      await waitFor(() => {
        expect(onOpenChange).toHaveBeenCalledWith(true);
      });

      fireEvent.keyDown(document, {key: 'Escape'});
      await waitFor(() => {
        expect(onOpenChange).toHaveBeenCalledWith(false);
      });
    });

    it('ignores Escape during IME composition', async () => {
      const onOpenChange = vi.fn();
      render(
        <Tooltip content="Stay" onOpenChange={onOpenChange} delay={0}>
          <button type="button">Trigger</button>
        </Tooltip>,
      );

      const trigger = screen.getByRole('button', {name: 'Trigger'});
      fireEvent.mouseEnter(trigger);
      await waitFor(() => {
        expect(onOpenChange).toHaveBeenCalledWith(true);
      });
      onOpenChange.mockClear();

      fireEvent.keyDown(document, {key: 'Escape', isComposing: true});
      // Give any (incorrect) async hide a chance to run.
      await new Promise(r => setTimeout(r, 20));
      expect(onOpenChange).not.toHaveBeenCalledWith(false);
    });

    it('stays open when the pointer moves onto the tooltip surface (hoverable)', async () => {
      const onOpenChange = vi.fn();
      render(
        <Tooltip content="Hover me" onOpenChange={onOpenChange} delay={0}>
          <button type="button">Trigger</button>
        </Tooltip>,
      );

      const trigger = screen.getByRole('button', {name: 'Trigger'});
      fireEvent.mouseEnter(trigger);
      await waitFor(() => {
        expect(onOpenChange).toHaveBeenCalledWith(true);
      });
      onOpenChange.mockClear();

      // Pointer leaves the trigger but enters the tooltip surface before the
      // hover-bridge grace period elapses — the tooltip must not hide.
      fireEvent.mouseLeave(trigger);
      const layer = screen.getByRole('tooltip', {hidden: true});
      fireEvent.mouseEnter(layer);

      await new Promise(r => setTimeout(r, 150));
      expect(onOpenChange).not.toHaveBeenCalledWith(false);
    });
  });

  describe('press-to-dismiss', () => {
    it('hides the tooltip when the trigger is pressed', async () => {
      const onOpenChange = vi.fn();
      render(
        <Tooltip content="Copy link" onOpenChange={onOpenChange} delay={0}>
          <button type="button">Trigger</button>
        </Tooltip>,
      );

      const trigger = screen.getByRole('button', {name: 'Trigger'});
      fireEvent.mouseEnter(trigger);
      await waitFor(() => {
        expect(onOpenChange).toHaveBeenCalledWith(true);
      });

      fireEvent.pointerDown(trigger);
      await waitFor(() => {
        expect(onOpenChange).toHaveBeenCalledWith(false);
      });
    });

    it('does not press-dismiss a controlled tooltip', async () => {
      const onOpenChange = vi.fn();
      render(
        <Tooltip
          content="Controlled"
          isOpen
          onOpenChange={onOpenChange}
          delay={0}>
          <button type="button">Trigger</button>
        </Tooltip>,
      );

      const trigger = screen.getByRole('button', {name: 'Trigger'});
      await waitFor(() => {
        expect(onOpenChange).toHaveBeenCalledWith(true);
      });
      onOpenChange.mockClear();

      fireEvent.pointerDown(trigger);
      // Give any (incorrect) async hide a chance to run.
      await new Promise(r => setTimeout(r, 20));
      expect(onOpenChange).not.toHaveBeenCalledWith(false);
    });
  });

  describe('controlled', () => {
    /** Whether the tooltip's layer is open. */
    const isShown = () =>
      screen
        .getByRole('tooltip', {hidden: true})
        .closest<HTMLElement>('[popover]')
        ?.matches(':popover-open') ?? false;

    it('reports keyboard-focus intent once while held closed, and shows nothing', async () => {
      const onOpenChange = vi.fn();
      render(
        <Tooltip
          content="Held"
          isOpen={false}
          onOpenChange={onOpenChange}
          delay={0}>
          <button type="button">Trigger</button>
        </Tooltip>,
      );
      const trigger = screen.getByRole('button', {name: 'Trigger'});
      const realMatches = trigger.matches.bind(trigger);
      vi.spyOn(trigger, 'matches').mockImplementation((selector: string) =>
        selector === ':focus-visible' ? true : realMatches(selector),
      );
      fireEvent.keyDown(document, {key: 'Tab'});
      fireEvent.focusIn(trigger);
      await waitFor(() => expect(onOpenChange).toHaveBeenCalledWith(true));
      await new Promise(r => setTimeout(r, 20));
      expect(onOpenChange).toHaveBeenCalledTimes(1);
      expect(isShown()).toBe(false);
    });

    it('reports Escape as onOpenChange(false) while held open, and stays shown', async () => {
      const onOpenChange = vi.fn();
      render(
        <Tooltip content="Held" isOpen onOpenChange={onOpenChange} delay={0}>
          <button type="button">Trigger</button>
        </Tooltip>,
      );
      await waitFor(() => expect(isShown()).toBe(true));
      onOpenChange.mockClear();
      fireEvent.keyDown(document, {key: 'Escape'});
      expect(onOpenChange).toHaveBeenCalledWith(false);
      expect(isShown()).toBe(true);
    });

    // Escape asks a controlled tooltip to close by calling this same handler,
    // so a consumer who complies sees the request and then this echo. Pinning
    // the echo here keeps the two straight.
    it('echoes the close through onOpenChange when the consumer flips isOpen', async () => {
      const onOpenChange = vi.fn();
      const {rerender} = render(
        <Tooltip content="Pinned" isOpen onOpenChange={onOpenChange} delay={0}>
          <button type="button">Trigger</button>
        </Tooltip>,
      );
      await waitFor(() => {
        expect(onOpenChange).toHaveBeenCalledWith(true);
      });
      onOpenChange.mockClear();

      rerender(
        <Tooltip
          content="Pinned"
          isOpen={false}
          onOpenChange={onOpenChange}
          delay={0}>
          <button type="button">Trigger</button>
        </Tooltip>,
      );

      await waitFor(() => {
        expect(onOpenChange).toHaveBeenCalledWith(false);
      });
    });
  });
  describe('touch', () => {
    // The modality is document-global; a tap in one case must not decide the
    // next one's answer.
    beforeEach(() => {
      __resetInteractionModalityForTest();
    });

    /**
     * A tap, in the order a browser dispatches it: the finger's pointer events,
     * then the hover it synthesizes, then the `click` that says the touch was a
     * tap and not the start of a scroll.
     */
    const tap = (element: HTMLElement) => {
      // A finger's arrival fires pointerenter too, and that is the path a pen
      // must not take — cover it here rather than starting at pointerdown.
      fireEvent.pointerEnter(element, {pointerType: 'touch'});
      fireEvent.pointerDown(element, {pointerType: 'touch'});
      fireEvent.pointerUp(element, {pointerType: 'touch'});
      // Touch synthesizes hover after the press; the tooltip must not act on it.
      fireEvent.mouseEnter(element);
      fireEvent.click(element);
    };

    /** A tap outside: what a finger landing and lifting elsewhere dispatches. */
    const tapOutside = (element: HTMLElement) => {
      fireEvent.pointerDown(element, {pointerType: 'touch'});
      fireEvent.pointerUp(element, {pointerType: 'touch'});
      fireEvent.click(element);
    };

    it('opens on a tap when the trigger performs no action', async () => {
      const onOpenChange = vi.fn();
      render(
        <Tooltip content="Tooltip text" onOpenChange={onOpenChange} delay={200}>
          Abbreviation
        </Tooltip>,
      );

      tap(screen.getByText('Abbreviation'));

      // Immediately: a tap is a decision, not hover intent, so no delay applies.
      await waitFor(() => {
        expect(onOpenChange).toHaveBeenCalledWith(true);
      });
    });

    it('stays shut on a tap when the trigger performs an action', async () => {
      const onOpenChange = vi.fn();
      render(
        <Tooltip content="Tooltip text" onOpenChange={onOpenChange} delay={0}>
          <button type="button">Save</button>
        </Tooltip>,
      );

      tap(screen.getByRole('button', {name: 'Save'}));

      await new Promise(resolve => setTimeout(resolve, 50));
      expect(onOpenChange).not.toHaveBeenCalledWith(true);
    });

    it('opens on a tap of an action trigger when touchTrigger is "tap"', async () => {
      const onOpenChange = vi.fn();
      render(
        <Tooltip
          content="What this metric means"
          onOpenChange={onOpenChange}
          touchTrigger="tap"
          delay={0}>
          <button type="button">Info</button>
        </Tooltip>,
      );

      tap(screen.getByRole('button', {name: 'Info'}));

      await waitFor(() => {
        expect(onOpenChange).toHaveBeenCalledWith(true);
      });
    });

    it('never opens on a tap when touchTrigger is "none"', async () => {
      const onOpenChange = vi.fn();
      render(
        <Tooltip
          content="Tooltip text"
          onOpenChange={onOpenChange}
          touchTrigger="none"
          delay={0}>
          Abbreviation
        </Tooltip>,
      );

      tap(screen.getByText('Abbreviation'));

      await new Promise(resolve => setTimeout(resolve, 50));
      expect(onOpenChange).not.toHaveBeenCalledWith(true);
    });

    it('closes on a second tap of the trigger', async () => {
      const onOpenChange = vi.fn();
      render(
        <Tooltip content="Tooltip text" onOpenChange={onOpenChange} delay={0}>
          Abbreviation
        </Tooltip>,
      );

      const trigger = screen.getByText('Abbreviation');
      tap(trigger);
      await waitFor(() => {
        expect(onOpenChange).toHaveBeenCalledWith(true);
      });

      tap(trigger);
      await waitFor(() => {
        expect(onOpenChange).toHaveBeenCalledWith(false);
      });
    });

    it('closes on a tap outside — the dismissal a tap-open owes the user', async () => {
      const onOpenChange = vi.fn();
      render(
        <>
          <Tooltip content="Tooltip text" onOpenChange={onOpenChange} delay={0}>
            Abbreviation
          </Tooltip>
          <button type="button">Elsewhere</button>
        </>,
      );

      tap(screen.getByText('Abbreviation'));
      await waitFor(() => {
        expect(onOpenChange).toHaveBeenCalledWith(true);
      });

      tapOutside(screen.getByRole('button', {name: 'Elsewhere'}));

      await waitFor(() => {
        expect(onOpenChange).toHaveBeenCalledWith(false);
      });
    });

    it('opens when the finger lifts, not when it lands', async () => {
      const onOpenChange = vi.fn();
      render(
        <Tooltip content="Tooltip text" onOpenChange={onOpenChange} delay={0}>
          Abbreviation
        </Tooltip>,
      );

      const trigger = screen.getByText('Abbreviation');
      fireEvent.pointerEnter(trigger, {pointerType: 'touch'});
      fireEvent.pointerDown(trigger, {pointerType: 'touch'});
      // The finger is still down: it may be starting a scroll.
      await new Promise(resolve => setTimeout(resolve, 50));
      expect(onOpenChange).not.toHaveBeenCalled();

      fireEvent.pointerUp(trigger, {pointerType: 'touch'});
      fireEvent.click(trigger);
      await waitFor(() => {
        expect(onOpenChange).toHaveBeenCalledWith(true);
      });
    });

    it('stays open when a pen that lands and stays down past the hover delay lifts', async () => {
      const onOpenChange = vi.fn();
      render(
        <Tooltip content="Tooltip text" onOpenChange={onOpenChange} delay={0}>
          Abbreviation
        </Tooltip>,
      );

      const trigger = screen.getByText('Abbreviation');
      // A pen in range hovers like a mouse: its arrival starts the hover show.
      fireEvent.pointerEnter(trigger, {pointerType: 'pen'});
      fireEvent.mouseEnter(trigger);
      fireEvent.pointerDown(trigger, {pointerType: 'pen'});
      // The pen stays down past the hover delay, then lifts.
      await new Promise(resolve => setTimeout(resolve, 50));
      fireEvent.pointerUp(trigger, {pointerType: 'pen'});
      fireEvent.click(trigger);
      await waitFor(() => {
        expect(onOpenChange).toHaveBeenCalledWith(true);
      });
      expect(onOpenChange).not.toHaveBeenCalledWith(false);
    });

    it('still opens on a mouse hover after its delay, and a mouse press still closes it', async () => {
      const onOpenChange = vi.fn();
      render(
        <Tooltip content="Tooltip text" onOpenChange={onOpenChange} delay={20}>
          Abbreviation
        </Tooltip>,
      );

      const trigger = screen.getByText('Abbreviation');
      fireEvent.pointerEnter(trigger, {pointerType: 'mouse'});
      fireEvent.mouseEnter(trigger);
      expect(onOpenChange).not.toHaveBeenCalled();
      await waitFor(() => {
        expect(onOpenChange).toHaveBeenCalledWith(true);
      });
      fireEvent.pointerDown(trigger, {pointerType: 'mouse'});
      await waitFor(() => {
        expect(onOpenChange).toHaveBeenLastCalledWith(false);
      });
    });

    it('never opens for a touch that turns into a scroll', async () => {
      const onOpenChange = vi.fn();
      render(
        <Tooltip content="Tooltip text" onOpenChange={onOpenChange} delay={0}>
          Abbreviation
        </Tooltip>,
      );

      const trigger = screen.getByText('Abbreviation');
      fireEvent.pointerEnter(trigger, {pointerType: 'touch'});
      fireEvent.pointerDown(trigger, {pointerType: 'touch'});
      // The browser takes the touch for the page scroll: no tap follows.
      fireEvent.pointerCancel(trigger, {pointerType: 'touch'});

      await new Promise(resolve => setTimeout(resolve, 50));
      expect(onOpenChange).not.toHaveBeenCalled();
    });

    it('never opens for a press the browser did not count as a tap', async () => {
      const onOpenChange = vi.fn();
      render(
        <Tooltip content="Tooltip text" onOpenChange={onOpenChange} delay={0}>
          Abbreviation
        </Tooltip>,
      );

      const trigger = screen.getByText('Abbreviation');
      // A long press: the finger lifts, but the browser fires no click
      // (it selected text or showed its own menu instead).
      fireEvent.pointerDown(trigger, {pointerType: 'touch'});
      fireEvent.pointerUp(trigger, {pointerType: 'touch'});

      await new Promise(resolve => setTimeout(resolve, 50));
      expect(onOpenChange).not.toHaveBeenCalled();
    });

    it('does not take a later keyboard click for the tap of an earlier press', async () => {
      const onOpenChange = vi.fn();
      render(
        <Tooltip
          content="What this metric means"
          onOpenChange={onOpenChange}
          touchTrigger="tap"
          delay={0}>
          <button type="button">Info</button>
        </Tooltip>,
      );

      const trigger = screen.getByRole('button', {name: 'Info'});
      // A press that never became a tap ...
      fireEvent.pointerDown(trigger, {pointerType: 'touch'});
      fireEvent.pointerUp(trigger, {pointerType: 'touch'});
      // ... then Enter on the focused button, which fires its own click.
      fireEvent.keyDown(trigger, {key: 'Enter'});
      fireEvent.click(trigger);

      await new Promise(resolve => setTimeout(resolve, 50));
      expect(onOpenChange).not.toHaveBeenCalledWith(true);
    });

    it('closes on a tap outside when the finger lifts, not when it lands', async () => {
      const onOpenChange = vi.fn();
      render(
        <>
          <Tooltip content="Tooltip text" onOpenChange={onOpenChange} delay={0}>
            Abbreviation
          </Tooltip>
          <button type="button">Elsewhere</button>
        </>,
      );

      tap(screen.getByText('Abbreviation'));
      await waitFor(() => {
        expect(onOpenChange).toHaveBeenCalledWith(true);
      });

      const elsewhere = screen.getByRole('button', {name: 'Elsewhere'});
      fireEvent.pointerDown(elsewhere, {pointerType: 'touch'});
      await new Promise(resolve => setTimeout(resolve, 50));
      expect(onOpenChange).not.toHaveBeenCalledWith(false);

      fireEvent.pointerUp(elsewhere, {pointerType: 'touch'});
      await waitFor(() => {
        expect(onOpenChange).toHaveBeenCalledWith(false);
      });
    });

    it('closes when a scroll starts outside', async () => {
      const onOpenChange = vi.fn();
      render(
        <>
          <Tooltip content="Tooltip text" onOpenChange={onOpenChange} delay={0}>
            Abbreviation
          </Tooltip>
          <p>Page content</p>
        </>,
      );

      tap(screen.getByText('Abbreviation'));
      await waitFor(() => {
        expect(onOpenChange).toHaveBeenCalledWith(true);
      });

      const page = screen.getByText('Page content');
      fireEvent.pointerDown(page, {pointerType: 'touch'});
      fireEvent.pointerCancel(page, {pointerType: 'touch'});

      await waitFor(() => {
        expect(onOpenChange).toHaveBeenCalledWith(false);
      });
    });

    it('still opens on a real mouse hover after a tap', async () => {
      const onOpenChange = vi.fn();
      render(
        <Tooltip content="Tooltip text" onOpenChange={onOpenChange} delay={0}>
          <button type="button">Save</button>
        </Tooltip>,
      );

      const trigger = screen.getByRole('button', {name: 'Save'});
      tap(trigger);
      await new Promise(resolve => setTimeout(resolve, 20));
      expect(onOpenChange).not.toHaveBeenCalledWith(true);

      // A hybrid device: the same trigger, now under a mouse.
      fireEvent.pointerEnter(trigger, {pointerType: 'mouse'});
      fireEvent.mouseEnter(trigger);

      await waitFor(() => {
        expect(onOpenChange).toHaveBeenCalledWith(true);
      });
    });

    it('opens on a hovering pen, which is a hover and not a tap', async () => {
      const onOpenChange = vi.fn();
      render(
        <Tooltip content="Tooltip text" onOpenChange={onOpenChange} delay={0}>
          <button type="button">Save</button>
        </Tooltip>,
      );

      const trigger = screen.getByRole('button', {name: 'Save'});
      // A stylus in detection range: pointerenter with nothing in contact, on
      // a device where `(hover: hover)` matches. Reading that as touch would
      // bail out of the hover path and leave the user no tooltip at all.
      fireEvent.pointerEnter(trigger, {pointerType: 'pen', buttons: 0});
      fireEvent.mouseEnter(trigger);

      await waitFor(() => {
        expect(onOpenChange).toHaveBeenCalledWith(true);
      });
    });

    it('tap-opens when a pen lands on an inert trigger', async () => {
      const onOpenChange = vi.fn();
      render(
        <Tooltip content="Tooltip text" onOpenChange={onOpenChange} delay={200}>
          Abbreviation
        </Tooltip>,
      );

      const trigger = screen.getByText('Abbreviation');
      // Hovering first, as a real pen does — then contact, which is a tap.
      fireEvent.pointerEnter(trigger, {pointerType: 'pen', buttons: 0});
      fireEvent.pointerDown(trigger, {pointerType: 'pen'});
      fireEvent.pointerUp(trigger, {pointerType: 'pen'});
      fireEvent.click(trigger);

      await waitFor(() => {
        expect(onOpenChange).toHaveBeenCalledWith(true);
      });
    });

    it('does not reopen from the focus a tapped text field takes', async () => {
      const onOpenChange = vi.fn();
      render(
        <Tooltip content="Tooltip text" onOpenChange={onOpenChange} delay={0}>
          <input type="text" aria-label="Amount" />
        </Tooltip>,
      );

      const trigger = screen.getByLabelText('Amount');
      // A tapped text field matches `:focus-visible` in a real browser —
      // deliberately, per Selectors 4, so typing has a visible home. jsdom
      // does not model that, so stand it up here; without it this case cannot
      // fail, whatever the focus path does.
      const realMatches = trigger.matches.bind(trigger);
      vi.spyOn(trigger, 'matches').mockImplementation((selector: string) =>
        selector === ':focus-visible' ? true : realMatches(selector),
      );

      // An `<input>` is an action trigger, so `auto` gives it the tap — and
      // the focus it takes must not put the tooltip back over the field the
      // user is about to type into.
      tap(trigger);
      fireEvent.focusIn(trigger);

      await new Promise(resolve => setTimeout(resolve, 50));
      expect(onOpenChange).not.toHaveBeenCalledWith(true);
    });

    it('still opens on keyboard focus of a trigger a finger touched', async () => {
      const onOpenChange = vi.fn();
      render(
        <Tooltip content="Tooltip text" onOpenChange={onOpenChange} delay={0}>
          <input type="text" aria-label="Amount" />
        </Tooltip>,
      );

      const trigger = screen.getByLabelText('Amount');
      const realMatches = trigger.matches.bind(trigger);
      vi.spyOn(trigger, 'matches').mockImplementation((selector: string) =>
        selector === ':focus-visible' ? true : realMatches(selector),
      );

      tap(trigger);
      // Reaching for the keyboard ends the touch interaction; the guard is on
      // the gesture in flight, not on the device the trigger last saw.
      fireEvent.keyDown(document, {key: 'Tab'});
      fireEvent.focusIn(trigger);

      await waitFor(() => {
        expect(onOpenChange).toHaveBeenCalledWith(true);
      });
    });
  });
});

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

describe('Tooltip in a roving Toolbar (focusTrigger="auto")', () => {
  it('opens on arrow-key focus for a member whose tooltip was added after mount', async () => {
    const user = userEvent.setup();
    function FormatToolbar({hasHints}: {hasHints: boolean}) {
      return (
        <Toolbar
          label="Format"
          startContent={
            <>
              <IconButton
                label="Copy"
                icon={<TestIcon />}
                tooltip="Copy"
                onClick={() => {}}
              />
              <IconButton
                label="Filter"
                icon={<TestIcon />}
                tooltip={hasHints ? 'Filter (F)' : undefined}
                onClick={() => {}}
              />
            </>
          }
        />
      );
    }
    const {rerender} = render(<FormatToolbar hasHints={false} />);
    rerender(<FormatToolbar hasHints />);
    const filter = screen.getByRole('button', {name: 'Filter'});
    const realMatches = filter.matches.bind(filter);
    vi.spyOn(filter, 'matches').mockImplementation((selector: string) =>
      selector === ':focus-visible' ? true : realMatches(selector),
    );

    screen.getByRole('button', {name: 'Copy'}).focus();
    await user.keyboard('{ArrowRight}');
    expect(filter).toHaveFocus();
    const describedBy = filter.getAttribute('aria-describedby') ?? '';
    await waitFor(() => {
      const layer = describedBy
        .split(' ')
        .map(id => document.getElementById(id))
        .find(element => element?.textContent === 'Filter (F)');
      expect(layer).toBeDefined();
      expect(layer?.matches(':popover-open')).toBe(true);
    });
  });
});

// FR11: a press inside an open tooltip acts only within the tooltip.
describe('Tooltip surface press', () => {
  it('keeps a click on the tooltip text from activating a clickable card', () => {
    const onCardClick = vi.fn();
    render(
      <ClickableCard label="Card" onClick={onCardClick}>
        <span>Card body</span>
        <Tooltip content="Tooltip text" isOpen>
          <button type="button">Trigger</button>
        </Tooltip>
      </ClickableCard>,
    );
    fireEvent.click(screen.getByText('Tooltip text'));
    expect(onCardClick).not.toHaveBeenCalled();
    // Positive control: a click on the card's own content still activates it.
    fireEvent.click(screen.getByText('Card body'));
    expect(onCardClick).toHaveBeenCalledTimes(1);
  });

  it('keeps a click on the tooltip text from running an Item row', () => {
    const onRowClick = vi.fn();
    render(
      <Item
        label="Row"
        onClick={onRowClick}
        endContent={
          <Tooltip content="Tooltip text" isOpen>
            <span tabIndex={0}>Info</span>
          </Tooltip>
        }
      />,
    );
    fireEvent.click(screen.getByText('Tooltip text'));
    expect(onRowClick).not.toHaveBeenCalled();
    fireEvent.click(screen.getByText('Row'));
    expect(onRowClick).toHaveBeenCalledTimes(1);
  });

  it('keeps a click on the tooltip text from running a Token', () => {
    const onTokenClick = vi.fn();
    render(
      <Token
        label="Tag"
        onClick={onTokenClick}
        endContent={
          <Tooltip content="Tooltip text" isOpen>
            <span tabIndex={0}>Info</span>
          </Tooltip>
        }
      />,
    );
    fireEvent.click(screen.getByText('Tooltip text'));
    expect(onTokenClick).not.toHaveBeenCalled();
    fireEvent.click(screen.getByText('Tag'));
    expect(onTokenClick).toHaveBeenCalledTimes(1);
  });

  it('keeps a middle-button press on the tooltip text from opening a card link', () => {
    const open = vi.spyOn(window, 'open').mockReturnValue(null);
    render(
      <ClickableCard label="Card" href="https://example.com/">
        <Tooltip content="Tooltip text" isOpen>
          <button type="button">Trigger</button>
        </Tooltip>
      </ClickableCard>,
    );
    fireEvent.mouseUp(screen.getByText('Tooltip text'), {button: 1});
    expect(open).not.toHaveBeenCalled();
    open.mockRestore();
  });

  it('still lets document listeners see a click on the tooltip text', () => {
    // A Typeahead or menu inside a layer closes and opens from document
    // listeners, so the press must keep propagating.
    const onDocumentClick = vi.fn();
    document.addEventListener('click', onDocumentClick);
    render(
      <Tooltip content="Tooltip text" isOpen>
        <button type="button">Trigger</button>
      </Tooltip>,
    );
    fireEvent.click(screen.getByText('Tooltip text'));
    document.removeEventListener('click', onDocumentClick);
    expect(onDocumentClick).toHaveBeenCalledTimes(1);
  });

  it('keeps a click on the tooltip text inside a label from toggling its control', () => {
    render(
      <label>
        <input type="checkbox" /> Accept{' '}
        <Tooltip content="Why we ask" isOpen>
          <button type="button">Info</button>
        </Tooltip>
      </label>,
    );
    // The surface mounts outside the label (a label cannot contain it), so
    // a click on its text is not label activation.
    fireEvent.click(screen.getByText('Why we ask'));
    expect(screen.getByRole('checkbox')).not.toBeChecked();
    // Positive control: a click on the label's own text still toggles it.
    fireEvent.click(screen.getByText('Accept'));
    expect(screen.getByRole('checkbox')).toBeChecked();
  });
});

describe('Tooltip on every input (component:Tooltip FR5)', () => {
  beforeEach(() => {
    __resetInteractionModalityForTest();
  });

  /** An info-only trigger: a span, or a button. */
  function setup(
    touchTrigger?: 'auto' | 'tap' | 'none',
    trigger: 'span' | 'button' = 'span',
  ) {
    const onOpenChange = vi.fn<(open: boolean) => void>();
    render(
      <Tooltip
        content="Billed monthly"
        delay={0}
        onOpenChange={onOpenChange}
        touchTrigger={touchTrigger}>
        {trigger === 'button' ? (
          <button type="button">Billing</button>
        ) : (
          <span tabIndex={0}>Billing</span>
        )}
      </Tooltip>,
    );
    const opened = () => onOpenChange.mock.calls.some(([open]) => open);
    return {trigger: screen.getByText('Billing'), opened};
  }

  /** A finger or a landed pen: down, up, then the click (a pen hovers, so no arrival). */
  function tap(element: HTMLElement, pointerType: 'touch' | 'pen') {
    if (pointerType === 'touch') {
      fireEvent.pointerEnter(element, {pointerType});
    }
    fireEvent.pointerDown(element, {pointerType});
    fireEvent.pointerUp(element, {pointerType});
    fireEvent.click(element);
  }

  const settle = async () =>
    new Promise(resolve => {
      setTimeout(resolve, 50);
    });

  describe('on an info-only trigger', () => {
    it('a mouse hover previews it', async () => {
      const {trigger, opened} = setup();
      fireEvent.pointerEnter(trigger, {pointerType: 'mouse'});
      fireEvent.mouseEnter(trigger);
      await waitFor(() => expect(opened()).toBe(true));
    });

    it('keyboard focus previews it', async () => {
      const {trigger, opened} = setup();
      const realMatches = trigger.matches.bind(trigger);
      vi.spyOn(trigger, 'matches').mockImplementation((selector: string) =>
        selector === ':focus-visible' ? true : realMatches(selector),
      );
      fireEvent.keyDown(document, {key: 'Tab'});
      fireEvent.focusIn(trigger);
      await waitFor(() => expect(opened()).toBe(true));
    });

    it.each(['touch', 'pen'] as const)(
      'a %s tap opens it',
      async pointerType => {
        const {trigger, opened} = setup();
        tap(trigger, pointerType);
        await settle();
        expect(opened()).toBe(true);
      },
    );

    it.each(['mouse click', 'touch tap'] as const)(
      'a %s on a button trigger pins nothing',
      async press => {
        const {trigger} = setup(undefined, 'button');
        if (press === 'mouse click') {
          fireEvent.pointerDown(trigger, {pointerType: 'mouse'});
          fireEvent.pointerUp(trigger, {pointerType: 'mouse'});
          fireEvent.click(trigger);
        } else {
          tap(trigger, 'touch');
        }
        await settle();
        expect(trigger).not.toHaveAttribute('aria-expanded');
      },
    );
  });

  it.each([
    ['none', 'span', 'no tap opens it', false],
    ['tap', 'button', 'every tap opens it', true],
  ] as const)(
    'touchTrigger="%s" on a %s decides: %s',
    async (touchTrigger, trigger, _, tapOpens) => {
      const tip = setup(touchTrigger, trigger);
      tap(tip.trigger, 'touch');
      await settle();
      expect(tip.opened()).toBe(tapOpens);
    },
  );
});