Skip to content

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

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

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

import {
  describe,
  it,
  expect,
  vi,
  beforeAll,
  beforeEach,
  afterEach,
  afterAll,
} from 'vitest';
import {
  render,
  renderHook,
  screen,
  fireEvent,
  waitFor,
  act,
  cleanup,
  within,
} from '@testing-library/react';
import {renderToString} from 'react-dom/server';
import {hydrateRoot} from 'react-dom/client';
import {createPortal} from 'react-dom';
import {StrictMode, useState, type ComponentProps} from 'react';
import * as stylex from '@stylexjs/stylex';
import {Button} from '../Button/Button';
import {ClickableCard} from '../ClickableCard/ClickableCard';
import {Theme, defineTheme} from '../theme';
import {HoverCard} from './HoverCard';
import {useHoverCard} from './useHoverCard';
import {useFocusTrap} from '../hooks/useFocusTrap';
import {__resetInteractionModalityForTest} from '../utils/interactionModality';

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

beforeEach(() => {
  vi.mocked(HTMLElement.prototype.showPopover).mockClear();
  vi.mocked(HTMLElement.prototype.hidePopover).mockClear();
});

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

    rerender();

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

  it('does not rebind trigger listeners on rerender', () => {
    function Harness() {
      const card = useHoverCard();
      return (
        <div>
          <span ref={card.ref}>Trigger</span>
          {card.renderHoverCard(<div>Card</div>)}
        </div>
      );
    }
    const {getByText, rerender} = render(<Harness />);
    const trigger = getByText('Trigger');
    const added: string[] = [];
    const add = trigger.addEventListener.bind(trigger);
    trigger.addEventListener = ((type: string, ...rest: unknown[]) => {
      added.push(type);
      return (add as (...args: unknown[]) => void)(type, ...rest);
    }) as typeof trigger.addEventListener;

    rerender(<Harness />);

    expect(added).toEqual([]);
  });
});

// A card closed while the pointer rests on it unmounts without a mouseleave,
// so the hook must not keep believing the pointer is over the card: if it
// does, the next open of the same trigger never closes on leave.
describe('useHoverCard closing while the pointer is on the card', () => {
  function Harness() {
    const card = useHoverCard({delay: 0, hideDelay: 0});
    return (
      <div>
        <span ref={card.ref}>Trigger</span>
        <output data-testid="state">{card.isOpen ? 'open' : 'closed'}</output>
        {card.renderHoverCard(
          <button type="button" onClick={card.hide}>
            Pick
          </button>,
        )}
      </div>
    );
  }

  async function openThenRestOnCard() {
    const state = screen.getByTestId('state');
    fireEvent.mouseEnter(screen.getByText('Trigger'));
    await waitFor(() => expect(state).toHaveTextContent('open'));
    const pick = screen.getByRole('button', {name: 'Pick', hidden: true});
    fireEvent.mouseLeave(screen.getByText('Trigger'));
    fireEvent.mouseEnter(pick.parentElement!);
    return {state, pick};
  }

  async function expectNextOpenClosesOnLeave(state: HTMLElement) {
    const trigger = screen.getByText('Trigger');
    fireEvent.mouseEnter(trigger);
    await waitFor(() => expect(state).toHaveTextContent('open'));
    fireEvent.mouseLeave(trigger);
    await waitFor(() => expect(state).toHaveTextContent('closed'));
  }

  it('closes the next open on leave after hide() from inside the card', async () => {
    render(<Harness />);
    const {state, pick} = await openThenRestOnCard();

    fireEvent.click(pick);
    await waitFor(() => expect(state).toHaveTextContent('closed'));

    await expectNextOpenClosesOnLeave(state);
  });

  it('closes the next open on leave after Escape dismisses the card', async () => {
    render(<Harness />);
    const {state} = await openThenRestOnCard();

    fireEvent.keyDown(document.body, {key: 'Escape'});
    await waitFor(() => expect(state).toHaveTextContent('closed'));

    await expectNextOpenClosesOnLeave(state);
  });
});

describe('useHoverCard — focusTrigger="auto" decides when focus arrives', () => {
  it('opens on focus of a trigger that was tabindex="-1" when it attached', async () => {
    const onShow = vi.fn();
    function RovingMember() {
      const card = useHoverCard({onShow, delay: 0});
      return (
        <div>
          {/* A roving-tabindex member that is not the tab stop when the
              card attaches. */}
          <button type="button" tabIndex={-1} ref={card.ref}>
            Filter
          </button>
          {card.renderHoverCard(<span>Card</span>)}
        </div>
      );
    }
    render(<RovingMember />);
    const member = screen.getByRole('button', {name: 'Filter'});
    // The roving hook moves the tab stop, then focus, as an arrow key does.
    member.setAttribute('tabindex', '0');
    fireEvent.focusIn(member);
    await waitFor(() => expect(onShow).toHaveBeenCalledTimes(1));
  });

  it('opens on focus of a focusable trigger it does not list, such as a summary', async () => {
    const onShow = vi.fn();
    function SummaryTrigger() {
      const card = useHoverCard({onShow, delay: 0});
      return (
        <details>
          <summary ref={card.ref}>More</summary>
          {card.renderHoverCard(<span>Card</span>)}
        </details>
      );
    }
    render(<SummaryTrigger />);
    fireEvent.focusIn(screen.getByText('More'));
    await waitFor(() => expect(onShow).toHaveBeenCalledTimes(1));
  });

  it('ignores focus inside a plain wrapper trigger', async () => {
    const onShow = vi.fn();
    function WrapperTrigger() {
      const card = useHoverCard({onShow, delay: 0});
      return (
        <div>
          <div ref={card.ref}>
            <input aria-label="Amount" />
          </div>
          {card.renderHoverCard(<span>Card</span>)}
        </div>
      );
    }
    render(<WrapperTrigger />);
    fireEvent.focusIn(screen.getByRole('textbox', {name: 'Amount'}));
    await act(async () => {
      await new Promise(resolve => setTimeout(resolve, 20));
    });
    expect(onShow).not.toHaveBeenCalled();
  });

  it('hides on blur from inside a focusable trigger that left the tab order', async () => {
    const onShow = vi.fn();
    const onHide = vi.fn();
    function FocusableRow() {
      const card = useHoverCard({onShow, onHide, delay: 0, hideDelay: 0});
      return (
        <div>
          <div tabIndex={0} ref={card.ref} data-testid="row">
            <button type="button">Inside</button>
          </div>
          {card.renderHoverCard(<span>Card</span>)}
        </div>
      );
    }
    render(<FocusableRow />);
    const inside = screen.getByRole('button', {name: 'Inside'});
    // Focus inside a focusable trigger counts.
    fireEvent.focusIn(inside);
    await waitFor(() => expect(onShow).toHaveBeenCalledTimes(1));
    // The trigger leaves the tab order before focus moves on: the focus that
    // counted still hides the card.
    screen.getByTestId('row').setAttribute('tabindex', '-1');
    fireEvent.focusOut(inside);
    await waitFor(() => expect(onHide).toHaveBeenCalledTimes(1));
  });

  it('hides on blur of a trigger that left the tab order while focused', async () => {
    const onShow = vi.fn();
    const onHide = vi.fn();
    function RovingMember() {
      const card = useHoverCard({onShow, onHide, delay: 0, hideDelay: 0});
      return (
        <div>
          <button type="button" ref={card.ref}>
            Filter
          </button>
          {card.renderHoverCard(<span>Card</span>)}
        </div>
      );
    }
    render(<RovingMember />);
    const member = screen.getByRole('button', {name: 'Filter'});
    fireEvent.focusIn(member);
    await waitFor(() => expect(onShow).toHaveBeenCalledTimes(1));
    // The roving hook takes the tab stop away before focus moves on.
    member.setAttribute('tabindex', '-1');
    fireEvent.focusOut(member);
    await waitFor(() => expect(onHide).toHaveBeenCalledTimes(1));
  });
});

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

  it('exposes the floating layer as role="group" when no label is provided', async () => {
    render(
      <HoverCard content={<span>Card content</span>} delay={0}>
        <button type="button">Trigger</button>
      </HoverCard>,
    );
    // A group may validly be unnamed; an unnamed dialog may not. Without a
    // label the layer must not claim the dialog role.
    expect(screen.queryByRole('group', {hidden: true})).toBeNull();
    expect(screen.queryByRole('dialog', {hidden: true})).toBeNull();

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

    await waitFor(() => {
      expect(screen.getByRole('group', {hidden: true})).toHaveTextContent(
        'Card content',
      );
    });
  });

  it('exposes the floating layer as a named dialog when label is provided', async () => {
    render(
      <HoverCard
        content={<span>Card content</span>}
        label="Profile preview"
        delay={0}>
        <button type="button">Trigger</button>
      </HoverCard>,
    );
    expect(screen.queryByRole('dialog', {hidden: true})).toBeNull();

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

    const dialog = await screen.findByRole('dialog', {hidden: true});
    expect(dialog).toHaveAttribute('aria-label', 'Profile preview');
    expect(dialog).toHaveTextContent('Card content');
    expect(screen.queryByRole('group', {hidden: true})).toBeNull();
  });

  it('wraps element children in an inline-safe span', () => {
    const {container} = render(
      <p>
        Before{' '}
        <HoverCard content={<span>Card content</span>}>
          <a href="#trigger">Trigger</a>
        </HoverCard>{' '}
        after
      </p>,
    );

    const trigger = screen.getByRole('link', {name: 'Trigger'});
    const paragraph = container.querySelector('p');

    expect(trigger.parentElement?.tagName).toBe('SPAN');
    expect(paragraph?.querySelector('div')).toBeNull();
    expect(paragraph?.querySelector('template')).not.toBeNull();
  });

  it('portals block content before showing and restores the marker after hiding', async () => {
    let contentWasPresentAtShow = false;
    vi.mocked(HTMLElement.prototype.showPopover).mockImplementationOnce(
      function (this: HTMLElement) {
        contentWasPresentAtShow =
          this.textContent?.includes('Block card content') ?? false;
        popoverOpenState.set(this, true);
      },
    );
    const consoleErrorSpy = vi
      .spyOn(console, 'error')
      .mockImplementation(() => {});

    const {container} = render(
      <p>
        Before{' '}
        <HoverCard
          content={<div>Block card content</div>}
          delay={0}
          hideDelay={0}>
          Trigger
        </HoverCard>{' '}
        after
      </p>,
    );

    const paragraph = container.querySelector('p');
    const trigger = screen.getByText('Trigger');

    expect(screen.queryByText('Block card content')).toBeNull();
    expect(paragraph?.querySelector('template')).not.toBeNull();
    expect(paragraph?.querySelector('div')).toBeNull();
    expect(consoleErrorSpy).not.toHaveBeenCalled();

    fireEvent.mouseEnter(trigger);

    await waitFor(() => {
      const content = screen.getByText('Block card content');
      const layer = content.closest('[popover]');

      expect(layer?.tagName).toBe('DIV');
      expect(layer?.parentElement).toBe(container);
      expect(paragraph?.contains(content)).toBe(false);
      expect(contentWasPresentAtShow).toBe(true);
      expect(HTMLElement.prototype.showPopover).toHaveBeenCalled();
      expect(consoleErrorSpy).not.toHaveBeenCalled();
    });

    fireEvent.mouseLeave(trigger);

    await waitFor(() => {
      expect(screen.queryByText('Block card content')).toBeNull();
      expect(paragraph?.querySelector('template')).not.toBeNull();
    });

    consoleErrorSpy.mockRestore();
  });

  it('hosts the floating layer outside a wrapping link', async () => {
    // Interactive ancestors capture the layer's own interactions: a card left
    // inside an <a> puts its links and buttons inside that link, so clicking
    // one navigates.
    render(
      <a href="#profile">
        <HoverCard
          content={
            <span>
              <a href="#inner">Inner link</a>
            </span>
          }
          delay={0}>
          Trigger
        </HoverCard>
      </a>,
    );

    const link = screen.getByRole('link', {name: /Trigger/});
    expect(screen.queryByText('Inner link')).toBeNull();
    fireEvent.mouseEnter(screen.getByText('Trigger'));

    const layer = (await screen.findByText('Inner link')).closest('[popover]');

    expect(layer).not.toBeNull();
    expect(link.contains(layer as Node)).toBe(false);
  });

  it('keeps a safe layer inline at its JSX position', async () => {
    const {container} = render(
      <>
        <HoverCard content={<div>Block card content</div>} delay={0}>
          <button type="button">Trigger</button>
        </HoverCard>
        <button type="button">Following control</button>
      </>,
    );

    expect(screen.queryByText('Block card content')).toBeNull();
    fireEvent.mouseEnter(screen.getByRole('button', {name: 'Trigger'}));

    await waitFor(() => {
      const layer = screen.getByText('Block card content').closest('[popover]');
      const following = screen.getByRole('button', {name: 'Following control'});

      expect(layer?.parentElement).toBe(container);
      expect(layer?.nextElementSibling).toBe(following);
    });
  });

  it('does not open on trigger focus while controlled closed', () => {
    const onOpenChange = vi.fn();
    render(
      <HoverCard
        isOpen={false}
        onOpenChange={onOpenChange}
        content={<span>Card content</span>}>
        <button type="button">Trigger</button>
      </HoverCard>,
    );
    const trigger = screen.getByRole('button', {name: 'Trigger'});

    // Hover is already refused; keyboard focus must be refused the same way.
    fireEvent.focusIn(trigger);
    expect(screen.queryByText('Card content')).toBeNull();
    expect(onOpenChange).not.toHaveBeenCalled();
  });

  it('does not render content initially', () => {
    const {container} = render(
      <HoverCard content={<span>Card content</span>}>
        <button type="button">Trigger</button>
      </HoverCard>,
    );
    expect(screen.queryByText('Card content')).toBeNull();
    expect(container.querySelector('[popover]')).toBeNull();
    expect(container.querySelector('template')).not.toBeNull();
  });

  it('keeps a paragraph portal inside the nearest nested theme scope', async () => {
    const outerTheme = defineTheme({name: 'hovercard-outer-test'});
    const innerTheme = defineTheme({
      name: 'hovercard-inner-test',
      components: {
        'hover-card': {base: {borderWidth: '7px'}},
        button: {base: {fontWeight: '700'}},
      },
    });

    const {container} = render(
      <Theme theme={outerTheme}>
        <Theme theme={innerTheme}>
          <p>
            <HoverCard
              content={<Button label="View profile">View profile</Button>}
              delay={0}>
              Trigger
            </HoverCard>
          </p>
        </Theme>
      </Theme>,
    );

    fireEvent.mouseEnter(screen.getByText('Trigger'));

    await waitFor(() => {
      const button = screen.getByText('View profile').closest('button');
      const layer = button?.closest('[popover]') ?? null;
      const innerThemeScope = container.querySelector(
        '[data-astryx-theme="hovercard-inner-test"]',
      );

      expect(innerThemeScope).not.toBeNull();
      expect(button).not.toBeNull();
      expect(layer?.parentElement).toBe(innerThemeScope);
      expect(innerThemeScope?.contains(layer)).toBe(true);
      expect(container.querySelector('p')?.contains(layer)).toBe(false);
    });
  });

  it('does not freeze computed CSS variables on a paragraph portal', async () => {
    const variables = new Map([
      ['--color-neutral', 'rgb(1, 2, 3)'],
      ['--color-text-primary', 'rgb(250, 251, 252)'],
    ]);
    const getComputedStyleSpy = vi
      .spyOn(window, 'getComputedStyle')
      .mockImplementation(
        element =>
          ({
            length: variables.size,
            item: (index: number) => Array.from(variables.keys())[index] ?? '',
            getPropertyValue: (property: string) =>
              variables.get(property) ?? '',
            direction:
              element.tagName.toLowerCase() === 'template' ? 'rtl' : 'ltr',
            writingMode:
              element.tagName.toLowerCase() === 'template'
                ? 'vertical-rl'
                : 'horizontal-tb',
          }) as CSSStyleDeclaration,
      );

    const {container} = render(
      <p>
        <HoverCard
          content={<Button label="View profile">View profile</Button>}
          delay={0}>
          Trigger
        </HoverCard>
      </p>,
    );

    expect(screen.queryByRole('button', {name: 'View profile'})).toBeNull();
    fireEvent.mouseEnter(screen.getByText('Trigger'));

    await waitFor(() => {
      const button = screen.getByRole('button', {name: 'View profile'});
      const layer = button.closest('[popover]');

      expect(layer?.parentElement).toBe(container);
      expect(container.querySelector('p')?.contains(button)).toBe(false);
      expect(layer).not.toBeNull();
      expect(
        (layer as HTMLElement).style.getPropertyValue('--color-neutral'),
      ).toBe('');
      expect(
        (layer as HTMLElement).style.getPropertyValue('--color-text-primary'),
      ).toBe('');
      expect((layer as HTMLElement).style.direction).toBe('rtl');
      expect((layer as HTMLElement).style.writingMode).toBe('vertical-rl');
    });

    getComputedStyleSpy.mockRestore();
  });

  it('applies the theme body font to the floating layer', async () => {
    render(
      <HoverCard content={<span>Card content</span>} delay={0}>
        <button type="button">Trigger</button>
      </HoverCard>,
    );

    fireEvent.mouseEnter(screen.getByRole('button', {name: 'Trigger'}));
    const layer = (await screen.findByText('Card content')).closest(
      '[popover]',
    );
    expect(layer).not.toBeNull();
    expect(getComputedStyle(layer as Element).fontFamily).toBe(
      'var(--font-family-body)',
    );
  });

  it('advertises a dialog popup on the trigger when labelled', () => {
    render(
      <HoverCard content={<span>Card content</span>} label="Profile actions">
        <button type="button">Trigger</button>
      </HoverCard>,
    );
    const trigger = screen.getByRole('button', {name: 'Trigger'});
    expect(trigger).toHaveAttribute('aria-haspopup', 'dialog');
    // While closed, the layer is not in the DOM, so aria-controls must not
    // point at a missing id (see DateInput). It is set once the card opens.
    expect(trigger).not.toHaveAttribute('aria-controls');
    expect(trigger).toHaveAttribute('aria-expanded', 'false');
    expect(trigger).not.toHaveAttribute('aria-describedby');
  });

  it('merges existing popup attributes on the trigger when labelled', () => {
    render(
      <HoverCard content={<span>Card content</span>} label="Profile actions">
        <button
          type="button"
          aria-haspopup="menu"
          aria-controls="menu-id"
          aria-expanded="true">
          Trigger
        </button>
      </HoverCard>,
    );
    const trigger = screen.getByRole('button', {name: 'Trigger'});
    // The hover card's dialog popup is advertised, but the trigger's own
    // popup semantics are preserved rather than overwritten.
    expect(trigger).toHaveAttribute('aria-haspopup', 'dialog');
    expect(trigger.getAttribute('aria-controls')).toContain('menu-id');
    expect(trigger).toHaveAttribute('aria-expanded', 'false');
  });

  it('gives a role-less trigger neither aria-haspopup nor aria-expanded', () => {
    render(
      <HoverCard content={<span>Card content</span>} label="Timestamp details">
        <time dateTime="2026-08-25" tabIndex={0}>
          2 hours ago
        </time>
      </HoverCard>,
    );
    const trigger = screen.getByText('2 hours ago');
    expect(trigger.tagName).toBe('TIME');
    // ARIA 1.2 supports neither attribute on the time role.
    expect(trigger).not.toHaveAttribute('aria-haspopup');
    expect(trigger).not.toHaveAttribute('aria-expanded');
  });

  it('names the open card from a role-less trigger through aria-controls only', () => {
    render(
      <HoverCard
        content={<span>Card content</span>}
        label="Profile actions"
        isOpen>
        <span tabIndex={0} aria-controls="own-region">
          Trigger
        </span>
      </HoverCard>,
    );
    const trigger = screen.getByText('Trigger');
    const card = screen.getByRole('dialog', {hidden: true});
    expect(trigger).toHaveAttribute('aria-controls', `own-region ${card.id}`);
    expect(trigger).not.toHaveAttribute('aria-haspopup');
    expect(trigger).not.toHaveAttribute('aria-expanded');
  });

  it('keeps aria-expanded on a role-less trigger that declares a supporting role', () => {
    render(
      <HoverCard content={<span>Card content</span>} label="Profile actions">
        <span role="button" tabIndex={0}>
          Trigger
        </span>
      </HoverCard>,
    );
    const trigger = screen.getByRole('button', {name: 'Trigger'});
    expect(trigger).toHaveAttribute('aria-expanded', 'false');
  });

  it('leaves a role-less trigger own aria-expanded untouched', () => {
    render(
      <HoverCard content={<span>Card content</span>} label="Profile actions">
        <span aria-expanded="true">Trigger</span>
      </HoverCard>,
    );
    const trigger = screen.getByText('Trigger');
    expect(trigger).toHaveAttribute('aria-expanded', 'true');
  });

  it('keeps aria-expanded on triggers whose implicit role supports it', () => {
    render(
      <HoverCard content={<span>Card content</span>} label="Profile actions">
        <input type="button" value="Trigger" />
      </HoverCard>,
    );
    expect(screen.getByRole('button')).toHaveAttribute(
      'aria-expanded',
      'false',
    );
  });

  it('keeps aria-describedby on the trigger when no label is provided', () => {
    render(
      <HoverCard content={<span>Card content</span>}>
        <button type="button">Trigger</button>
      </HoverCard>,
    );
    const trigger = screen.getByRole('button', {name: 'Trigger'});
    expect(trigger).toHaveAttribute('aria-describedby');
    expect(trigger).not.toHaveAttribute('aria-haspopup');
  });

  it('preserves existing aria-describedby when no label is provided', () => {
    render(
      <HoverCard content={<span>Card content</span>}>
        <button type="button" aria-describedby="existing-id">
          Trigger
        </button>
      </HoverCard>,
    );
    const trigger = screen.getByRole('button', {name: 'Trigger'});
    const describedBy = trigger.getAttribute('aria-describedby');
    expect(describedBy).toContain('existing-id');
  });

  it('updates aria-expanded when the labelled hover card opens and closes', async () => {
    render(
      <HoverCard
        content={<span>Card content</span>}
        label="Profile actions"
        delay={0}>
        <button type="button">Trigger</button>
      </HoverCard>,
    );
    const trigger = screen.getByRole('button', {name: 'Trigger'});
    expect(trigger).toHaveAttribute('aria-expanded', 'false');
    expect(trigger).not.toHaveAttribute('aria-controls');

    fireEvent.mouseEnter(trigger);
    await waitFor(() => {
      expect(trigger).toHaveAttribute('aria-expanded', 'true');
      // The layer is in the DOM now, so aria-controls points at it.
      expect(trigger).toHaveAttribute('aria-controls');
    });

    fireEvent.mouseLeave(trigger);
    await waitFor(() => {
      expect(trigger).toHaveAttribute('aria-expanded', 'false');
      // The layer is gone from the DOM, so aria-controls is cleared.
      expect(trigger).not.toHaveAttribute('aria-controls');
    });
  });

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

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

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

  it('respects isEnabled prop', async () => {
    const onOpenChange = vi.fn();
    render(
      <HoverCard
        content={<span>Card content</span>}
        onOpenChange={onOpenChange}
        isEnabled={false}
        delay={0}>
        <button type="button">Trigger</button>
      </HoverCard>,
    );

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

    // Wait a bit and verify onOpenChange was not called
    await new Promise(resolve => setTimeout(resolve, 50));
    expect(onOpenChange).not.toHaveBeenCalled();
  });

  it('supports text-only children with inline wrapper', () => {
    render(
      <HoverCard content={<span>Card content</span>} label="Profile actions">
        Just text, no element
      </HoverCard>,
    );
    // Text should be rendered
    expect(screen.getByText('Just text, no element')).toBeInTheDocument();
    // The wrapper is a role-less <span>, so it carries neither
    // aria-haspopup nor aria-expanded.
    const wrapper = screen.getByText('Just text, no element');
    expect(wrapper.tagName).toBe('SPAN');
    expect(wrapper).toHaveAttribute('tabindex', '0');
    expect(wrapper).not.toHaveAttribute('aria-haspopup');
    expect(wrapper).not.toHaveAttribute('aria-expanded');
    // While closed, the layer is not in the DOM, so aria-controls is unset.
    expect(wrapper).not.toHaveAttribute('aria-controls');
    expect(wrapper).not.toHaveAttribute('aria-describedby');
  });

  it('keeps aria-describedby on text-only children when no label is provided', () => {
    render(
      <HoverCard content={<span>Card content</span>}>
        Just text, no element
      </HoverCard>,
    );
    const wrapper = screen.getByText('Just text, no element');
    expect(wrapper.tagName).toBe('SPAN');
    expect(wrapper).toHaveAttribute('aria-describedby');
    expect(wrapper).not.toHaveAttribute('aria-haspopup');
  });

  describe('isDefaultOpen', () => {
    it('shows hover card on mount when isDefaultOpen is true', async () => {
      vi.mocked(HTMLElement.prototype.showPopover).mockClear();
      render(
        <HoverCard content={<span>Default open card</span>} isDefaultOpen>
          <button type="button">Trigger</button>
        </HoverCard>,
      );

      await waitFor(() => {
        expect(HTMLElement.prototype.showPopover).toHaveBeenCalled();
      });
    });

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

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

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

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

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

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

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

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

  describe('text written around an expression', () => {
    it('wraps several text children in one focusable trigger', async () => {
      const when = '2 hours ago';
      const onOpenChange = vi.fn();
      render(
        <HoverCard
          content={<span>Edited by Kai</span>}
          onOpenChange={onOpenChange}
          delay={0}>
          Edited {when}
        </HoverCard>,
      );
      const trigger = screen.getByText('Edited 2 hours ago');
      expect(trigger.tagName).toBe('SPAN');
      expect(trigger).toHaveAttribute('tabindex', '0');
      expect(trigger).toHaveAttribute('aria-describedby');
      fireEvent.mouseEnter(trigger);
      await waitFor(() => expect(onOpenChange).toHaveBeenLastCalledWith(true));
    });

    it('ignores holes that render nothing', () => {
      const isDraft = false;
      render(
        <HoverCard label="History" content={<span>Card</span>}>
          Edited {isDraft && 'draft'} {null}today
        </HoverCard>,
      );
      // The text wrapper is the trigger: it is the tab stop.
      expect(screen.getByText(/Edited/)).toHaveAttribute('tabindex', '0');
    });

    // The auto hover cue (FR8) is a class on the text trigger; a single
    // string's trigger is the reference.
    function cueClassOf(
      children: ComponentProps<typeof HoverCard>['children'],
    ) {
      const {unmount} = render(
        <HoverCard content={<span>Card</span>}>{children}</HoverCard>,
      );
      const className = (
        document.querySelector('span[tabindex="0"]') as HTMLElement
      ).className;
      unmount();
      return className;
    }

    it('gives several text children the same hover cue as one string', () => {
      const when = 'today';
      const single = cueClassOf('Edited today');
      // JSX passes `Edited {when}` as this array.
      expect(cueClassOf(['Edited ', when])).toBe(single);
      const {unmount} = render(
        <HoverCard content={<span>Card</span>} hasHoverIndication={false}>
          Edited today
        </HoverCard>,
      );
      expect(
        (document.querySelector('span[tabindex="0"]') as HTMLElement).className,
      ).not.toBe(single);
      unmount();
    });

    it('keeps the hover cue when holes render nothing', () => {
      const isDraft = false;
      const single = cueClassOf('Edited today');
      expect(cueClassOf(['Edited ', isDraft && 'draft', null, 'today'])).toBe(
        single,
      );
    });

    it('still attaches to the first element when one is present', () => {
      render(
        <HoverCard label="History" content={<span>Card</span>} isOpen>
          Edited <time dateTime="2026-11-02">today</time>
        </HoverCard>,
      );
      const card = screen.getByRole('dialog', {hidden: true});
      expect(screen.getByText('today')).toHaveAttribute(
        'aria-controls',
        card.id,
      );
    });
  });

  describe('a replaced trigger element', () => {
    function SwapsItsRoot() {
      const [isLink, setIsLink] = useState(false);
      return isLink ? (
        <a href="#profile">Profile link</a>
      ) : (
        <button type="button" onClick={() => setIsLink(true)}>
          Profile button
        </button>
      );
    }

    it('wires the new element when the children change', async () => {
      const onOpenChange = vi.fn();
      const {rerender} = render(
        <HoverCard
          label="Profile"
          content={<span>Card</span>}
          onOpenChange={onOpenChange}
          delay={0}>
          <button type="button">First</button>
        </HoverCard>,
      );
      rerender(
        <HoverCard
          label="Profile"
          content={<span>Card</span>}
          onOpenChange={onOpenChange}
          delay={0}>
          <a href="#second">Second</a>
        </HoverCard>,
      );
      const second = screen.getByRole('link', {name: 'Second'});
      await waitFor(() =>
        expect(second).toHaveAttribute('aria-haspopup', 'dialog'),
      );
      fireEvent.mouseEnter(second);
      await waitFor(() => expect(onOpenChange).toHaveBeenLastCalledWith(true));
    });

    it('wires the new element when a child component swaps its own root', async () => {
      const onOpenChange = vi.fn();
      render(
        <HoverCard
          label="Profile"
          content={<span>Card</span>}
          onOpenChange={onOpenChange}
          delay={0}>
          <SwapsItsRoot />
        </HoverCard>,
      );
      fireEvent.click(screen.getByRole('button', {name: 'Profile button'}));
      const link = screen.getByRole('link', {name: 'Profile link'});
      await waitFor(() =>
        expect(link).toHaveAttribute('aria-haspopup', 'dialog'),
      );
      fireEvent.mouseEnter(link);
      await waitFor(() => expect(onOpenChange).toHaveBeenLastCalledWith(true));
    });

    it('releases the old element when the children are reordered', async () => {
      const first = (
        <button key="a" type="button">
          Alpha
        </button>
      );
      const second = (
        <button key="b" type="button">
          Beta
        </button>
      );
      const {rerender} = render(
        <HoverCard label="Profile" content={<span>Card</span>}>
          {[first, second]}
        </HoverCard>,
      );
      const alpha = screen.getByRole('button', {name: 'Alpha'});
      expect(alpha).toHaveAttribute('aria-haspopup', 'dialog');

      rerender(
        <HoverCard label="Profile" content={<span>Card</span>}>
          {[second, first]}
        </HoverCard>,
      );
      const beta = screen.getByRole('button', {name: 'Beta'});
      await waitFor(() =>
        expect(beta).toHaveAttribute('aria-haspopup', 'dialog'),
      );
      // The old element stays in the DOM, released.
      expect(alpha).toBeInTheDocument();
      expect(alpha).not.toHaveAttribute('aria-haspopup');
    });

    it('describes the new element of an unnamed card', async () => {
      render(
        <HoverCard content={<span>Card</span>} delay={0}>
          <SwapsItsRoot />
        </HoverCard>,
      );
      fireEvent.click(screen.getByRole('button', {name: 'Profile button'}));
      const link = screen.getByRole('link', {name: 'Profile link'});
      await waitFor(() => expect(link).toHaveAttribute('aria-describedby'));
    });
  });

  describe('Escape key behavior', () => {
    it('takes Escape before a focus-trap container its trigger sits in', async () => {
      const onOpenChange = vi.fn();
      const onEscape = vi.fn();
      function Trap() {
        const {containerRef} = useFocusTrap<HTMLDivElement>({
          isActive: true,
          onEscape,
        });
        return (
          <div ref={containerRef}>
            <HoverCard
              content={<span>Card content</span>}
              onOpenChange={onOpenChange}
              delay={0}
              hideDelay={0}>
              <button type="button">Trigger</button>
            </HoverCard>
          </div>
        );
      }
      render(<Trap />);
      fireEvent.mouseEnter(screen.getByRole('button', {name: 'Trigger'}));
      await waitFor(() => expect(onOpenChange).toHaveBeenLastCalledWith(true));

      fireEvent.keyDown(document.body, {key: 'Escape'});
      await waitFor(() => expect(onOpenChange).toHaveBeenLastCalledWith(false));
      expect(onEscape).not.toHaveBeenCalled();
    });

    describe('in a second document', () => {
      // A same-origin iframe stands in for any second document an app renders
      // into through a portal, Document Picture-in-Picture included. A key
      // press reaches only the document it happened in.
      let frame: HTMLIFrameElement;

      beforeEach(() => {
        frame = document.createElement('iframe');
        document.body.appendChild(frame);
        // The frame has its own element prototypes: give them the same
        // Popover API stand-ins as this document's.
        const frameWindow = frame.contentWindow as Window & typeof globalThis;
        const proto = frameWindow.HTMLElement.prototype;
        const frameMatches = proto.matches;
        proto.showPopover = function (this: HTMLElement) {
          popoverOpenState.set(this, true);
        };
        proto.hidePopover = function (this: HTMLElement) {
          popoverOpenState.set(this, false);
        };
        // eslint-disable-next-line @typescript-eslint/no-explicit-any
        (proto as any).matches = function (selector: string): boolean {
          if (selector === ':popover-open') {
            return popoverOpenState.get(this) ?? false;
          }
          return frameMatches.call(this, selector);
        };
      });

      afterEach(() => {
        // Unmount before the frame goes, or React removes nodes from a
        // document that no longer exists.
        cleanup();
        frame.remove();
      });

      it('closes a card rendered into the second document on Escape there', async () => {
        const onOpenChange = vi.fn();
        const frameDocument = frame.contentDocument!;
        render(
          createPortal(
            <HoverCard
              content={<span>Card content</span>}
              onOpenChange={onOpenChange}
              delay={0}
              hideDelay={0}>
              <button type="button">Trigger</button>
            </HoverCard>,
            frameDocument.body,
          ),
        );
        const trigger = within(frameDocument.body).getByRole('button', {
          name: 'Trigger',
        });

        fireEvent.mouseEnter(trigger);
        await waitFor(() =>
          expect(onOpenChange).toHaveBeenLastCalledWith(true),
        );

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

      it('takes Escape in the second document when its trigger appears there after the hook mounts', async () => {
        const frameDocument = frame.contentDocument!;
        function LateTrigger() {
          const card = useHoverCard({delay: 0, hideDelay: 0});
          const [isShown, setIsShown] = useState(false);
          return (
            <>
              <button type="button" onClick={() => setIsShown(true)}>
                Show trigger
              </button>
              <output data-testid="state">
                {card.isOpen ? 'open' : 'closed'}
              </output>
              {isShown
                ? createPortal(
                    <>
                      <span ref={card.ref}>Late trigger</span>
                      {card.renderHoverCard(<span>Card</span>)}
                    </>,
                    frameDocument.body,
                  )
                : null}
            </>
          );
        }
        render(<LateTrigger />);
        fireEvent.click(screen.getByRole('button', {name: 'Show trigger'}));
        const state = screen.getByTestId('state');
        fireEvent.mouseEnter(
          within(frameDocument.body).getByText('Late trigger'),
        );
        await waitFor(() => expect(state).toHaveTextContent('open'));

        // A press in the page is not the card's.
        fireEvent.keyDown(document.body, {key: 'Escape'});
        expect(state).toHaveTextContent('open');

        fireEvent.keyDown(frameDocument.body, {key: 'Escape'});
        await waitFor(() => expect(state).toHaveTextContent('closed'));
      });

      it('takes Escape where its trigger is after the trigger moves into the frame and back', async () => {
        const frameDocument = frame.contentDocument!;
        function MovingTrigger() {
          const card = useHoverCard({delay: 0, hideDelay: 0});
          const [isInFrame, setIsInFrame] = useState(false);
          return (
            <>
              <button type="button" onClick={() => setIsInFrame(x => !x)}>
                Move trigger
              </button>
              <output data-testid="state">
                {card.isOpen ? 'open' : 'closed'}
              </output>
              {createPortal(
                <>
                  <span ref={card.ref}>Moving trigger</span>
                  {card.renderHoverCard(<span>Card</span>)}
                </>,
                isInFrame ? frameDocument.body : document.body,
              )}
            </>
          );
        }
        render(<MovingTrigger />);
        const state = screen.getByTestId('state');
        const move = () =>
          fireEvent.click(screen.getByRole('button', {name: 'Move trigger'}));
        const openIn = async (doc: Document) => {
          fireEvent.mouseEnter(within(doc.body).getByText('Moving trigger'));
          await waitFor(() => expect(state).toHaveTextContent('open'));
        };

        move();
        await openIn(frameDocument);
        fireEvent.keyDown(document.body, {key: 'Escape'});
        expect(state).toHaveTextContent('open');
        fireEvent.keyDown(frameDocument.body, {key: 'Escape'});
        await waitFor(() => expect(state).toHaveTextContent('closed'));

        move();
        await openIn(document);
        fireEvent.keyDown(frameDocument.body, {key: 'Escape'});
        expect(state).toHaveTextContent('open');
        fireEvent.keyDown(document.body, {key: 'Escape'});
        await waitFor(() => expect(state).toHaveTextContent('closed'));
      });

      it('stays open when focus moves from the trigger into the card', async () => {
        const onOpenChange = vi.fn();
        const frameDocument = frame.contentDocument!;
        const button = (text: string) =>
          Array.from(frameDocument.querySelectorAll('button')).find(
            candidate => candidate.textContent === text,
          );
        render(
          createPortal(
            <HoverCard
              content={<button type="button">Inside</button>}
              onOpenChange={onOpenChange}
              delay={0}
              hideDelay={0}>
              <button type="button">Trigger</button>
            </HoverCard>,
            frameDocument.body,
          ),
        );
        const trigger = button('Trigger')!;
        fireEvent.mouseEnter(trigger);
        await waitFor(() =>
          expect(onOpenChange).toHaveBeenLastCalledWith(true),
        );
        trigger.focus();
        button('Inside')!.focus();
        await act(async () => {
          await new Promise(resolve => setTimeout(resolve, 50));
        });
        expect(onOpenChange).toHaveBeenLastCalledWith(true);
      });

      it('returns focus to the trigger when Escape closes the card from inside it', async () => {
        const frameDocument = frame.contentDocument!;
        // Testing Library's role queries cannot read the frame's popover, so
        // find buttons by text.
        const button = (text: string) =>
          Array.from(frameDocument.querySelectorAll('button')).find(
            candidate => candidate.textContent === text,
          );
        render(
          createPortal(
            <HoverCard
              content={<button type="button">Inside</button>}
              delay={0}
              hideDelay={0}>
              <button type="button">Trigger</button>
            </HoverCard>,
            frameDocument.body,
          ),
        );
        const trigger = button('Trigger')!;
        fireEvent.mouseEnter(trigger);
        await waitFor(() => expect(button('Inside')).toBeDefined());
        const inside = button('Inside')!;
        inside.focus();
        // Compared as booleans: printing a frame's element fails.
        expect(frameDocument.activeElement === inside).toBe(true);

        fireEvent.keyDown(inside, {key: 'Escape'});
        await waitFor(() =>
          expect(frameDocument.activeElement === trigger).toBe(true),
        );
      });
    });

    it('hides hover card when Escape is pressed on trigger', async () => {
      const onOpenChange = vi.fn();
      // Reset the mock before this test
      vi.mocked(HTMLElement.prototype.hidePopover).mockClear();

      render(
        <HoverCard
          content={<span>Card content</span>}
          onOpenChange={onOpenChange}
          delay={0}
          hideDelay={0}>
          <button type="button">Trigger</button>
        </HoverCard>,
      );

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

      // Show the hover card
      fireEvent.mouseEnter(trigger);
      await waitFor(() => {
        expect(HTMLElement.prototype.showPopover).toHaveBeenCalled();
      });

      // Press Escape on trigger
      fireEvent.keyDown(trigger, {key: 'Escape'});

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

    it('hides hover card when Escape is pressed inside content', async () => {
      vi.mocked(HTMLElement.prototype.hidePopover).mockClear();

      render(
        <HoverCard
          content={<button type="button">Interactive button</button>}
          delay={0}
          hideDelay={0}>
          <button type="button">Trigger</button>
        </HoverCard>,
      );

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

      // Show the hover card
      fireEvent.mouseEnter(trigger);
      await waitFor(() => {
        expect(HTMLElement.prototype.showPopover).toHaveBeenCalled();
      });

      // Find the interactive content using getByText (works inside popovers)
      const contentButton = screen.getByText('Interactive button');
      fireEvent.keyDown(contentButton, {key: 'Escape'});

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

    it('refocuses trigger after Escape from content', async () => {
      render(
        <HoverCard
          content={<button type="button">Interactive button</button>}
          delay={0}
          hideDelay={0}>
          <button type="button">Trigger</button>
        </HoverCard>,
      );

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

      // Show the hover card via focus
      fireEvent.focus(trigger);
      await waitFor(() => {
        expect(HTMLElement.prototype.showPopover).toHaveBeenCalled();
      });

      // Focus the content button
      const contentButton = screen.getByText('Interactive button');
      contentButton.focus();

      // Press Escape - should refocus trigger
      fireEvent.keyDown(contentButton, {key: 'Escape'});

      await waitFor(() => {
        expect(document.activeElement).toBe(trigger);
      });
    });

    it('does not re-show hover card after Escape dismiss and refocus', async () => {
      const onOpenChange = vi.fn();
      render(
        <HoverCard
          content={<button type="button">Interactive button</button>}
          onOpenChange={onOpenChange}
          delay={0}
          hideDelay={0}>
          <button type="button">Trigger</button>
        </HoverCard>,
      );

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

      // Show the hover card via focus
      fireEvent.focus(trigger);
      await waitFor(() => {
        expect(onOpenChange).toHaveBeenCalledTimes(1);
      });

      // Focus the content button
      const contentButton = screen.getByText('Interactive button');
      contentButton.focus();

      // Clear the mock to track new calls
      onOpenChange.mockClear();

      // Press Escape - this refocuses trigger but shouldn't re-show
      fireEvent.keyDown(contentButton, {key: 'Escape'});

      // Wait a bit and verify onOpenChange was not called with true (re-show)
      // It may be called with false (dismiss), which is expected
      await new Promise(resolve => setTimeout(resolve, 50));
      expect(onOpenChange).not.toHaveBeenCalledWith(true);
    });
  });

  describe('SSR / hydration', () => {
    // Regression coverage for the hydration mismatch (#3107). The floating
    // layer used to be portaled into document.body behind a
    // `typeof document !== 'undefined'` gate: the server rendered nothing while
    // the first client render emitted the portal, so the two trees disagreed.
    //
    // Context layers now render the same inert <template> marker on the server
    // and the first client render. Arbitrary content mounts only when the card
    // is requested and its final inline/portal position is known.

    it('renders only the inert marker before and after hydration', async () => {
      const tree = (
        <HoverCard content={<span>Card content</span>}>
          <button type="button">Trigger</button>
        </HoverCard>
      );

      const serverHTML = renderToString(tree);
      expect(serverHTML).not.toContain('popover=');
      expect(serverHTML).not.toContain('Card content');
      expect(serverHTML).toContain('<template');

      const container = document.createElement('div');
      container.innerHTML = serverHTML;
      document.body.appendChild(container);

      let root: ReturnType<typeof hydrateRoot>;
      await act(async () => {
        root = hydrateRoot(container, tree);
      });

      expect(container.querySelector('[popover]')).toBeNull();
      expect(container.querySelector('template')).not.toBeNull();

      await act(async () => {
        root.unmount();
      });
      container.remove();
    });

    it('emits only a valid marker inside a paragraph', () => {
      const html = renderToString(
        <p>
          Before{' '}
          <HoverCard content={<div>Block card content</div>}>
            <a href="#trigger">Trigger</a>
          </HoverCard>{' '}
          after
        </p>,
      );

      // <template> is inert phrasing/script-supporting content, so the parser
      // has no block layer or consumer content to reparent out of the <p>.
      expect(html).not.toContain('<div');
      expect(html).not.toContain('popover=');
      expect(html).not.toContain('Block card content');
      expect(html).toContain('<template');
    });

    it('server markup matches the first client render (no hydration mismatch)', async () => {
      const tree = (
        <StrictMode>
          <p>
            Glossary:{' '}
            <HoverCard content={<div>Definition</div>}>
              <a href="#term">term</a>
            </HoverCard>
            .
          </p>
        </StrictMode>
      );

      const serverHTML = renderToString(tree);

      const container = document.createElement('div');
      container.innerHTML = serverHTML;
      document.body.appendChild(container);

      // Capture any hydration diagnostics. React reports hydration mismatches
      // both through console.error and through onRecoverableError.
      const consoleErrorSpy = vi
        .spyOn(console, 'error')
        .mockImplementation(() => {});
      const recoverableErrors: unknown[] = [];

      let root: ReturnType<typeof hydrateRoot>;
      await act(async () => {
        root = hydrateRoot(container, tree, {
          onRecoverableError: error => {
            recoverableErrors.push(error);
          },
        });
      });

      const hydrationErrors = consoleErrorSpy.mock.calls.filter(call =>
        String(call[0] ?? '')
          .toLowerCase()
          .includes('hydrat'),
      );

      expect(hydrationErrors).toEqual([]);
      expect(recoverableErrors).toEqual([]);
      expect(container.querySelector('[popover]')).toBeNull();
      expect(container.querySelector('template')).not.toBeNull();

      await act(async () => {
        root.unmount();
      });
      consoleErrorSpy.mockRestore();
      container.remove();
    });

    it('hydrates a default-open hover card without a mismatch', async () => {
      vi.mocked(HTMLElement.prototype.showPopover).mockClear();

      const tree = (
        <HoverCard content={<span>Default open</span>} isDefaultOpen>
          <button type="button">Trigger</button>
        </HoverCard>
      );

      const serverHTML = renderToString(tree);
      // isDefaultOpen must not leak the final layer into SSR markup. The marker
      // hydrates first; the effect then requests and opens the real popover.
      expect(serverHTML).not.toContain('popover=');
      expect(serverHTML).toContain('<template');

      const container = document.createElement('div');
      container.innerHTML = serverHTML;
      document.body.appendChild(container);

      const consoleErrorSpy = vi
        .spyOn(console, 'error')
        .mockImplementation(() => {});
      const recoverableErrors: unknown[] = [];

      let root: ReturnType<typeof hydrateRoot>;
      await act(async () => {
        root = hydrateRoot(container, tree, {
          onRecoverableError: error => {
            recoverableErrors.push(error);
          },
        });
      });

      const hydrationErrors = consoleErrorSpy.mock.calls.filter(call =>
        String(call[0] ?? '')
          .toLowerCase()
          .includes('hydrat'),
      );
      expect(hydrationErrors).toEqual([]);
      expect(recoverableErrors).toEqual([]);

      // The card opens after hydration via the mount effect.
      await waitFor(() => {
        expect(HTMLElement.prototype.showPopover).toHaveBeenCalled();
      });
      expect(container.querySelector('[popover]')).not.toBeNull();
      expect(container).toHaveTextContent('Default open');

      await act(async () => {
        root.unmount();
      });
      consoleErrorSpy.mockRestore();
      container.remove();
    });
  });

  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 card must not act on it.
      fireEvent.mouseEnter(element);
      fireEvent.click(element);
    };

    it('opens on a tap when the trigger performs no action', async () => {
      const onOpenChange = vi.fn();
      render(
        <HoverCard
          content={<span>Card content</span>}
          onOpenChange={onOpenChange}
          delay={300}>
          Ruby Cheung
        </HoverCard>,
      );

      tap(screen.getByText('Ruby Cheung'));

      // Immediately: a tap is a decision, not hover intent, so no delay applies.
      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(
        <HoverCard
          content={<span>Card content</span>}
          onOpenChange={onOpenChange}
          delay={0}>
          Ruby Cheung
        </HoverCard>,
      );

      const trigger = screen.getByText('Ruby Cheung');
      // 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('stays shut on a tap when the trigger performs an action', async () => {
      const onOpenChange = vi.fn();
      render(
        <HoverCard
          content={<span>Card content</span>}
          onOpenChange={onOpenChange}
          delay={0}>
          <button type="button">Save</button>
        </HoverCard>,
      );

      const trigger = screen.getByRole('button', {name: 'Save'});
      tap(trigger);
      // A tap focuses what it activates; that focus must not reopen the card.
      fireEvent.focusIn(trigger);

      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(
        <HoverCard
          content={<span>Card content</span>}
          onOpenChange={onOpenChange}
          touchTrigger="tap"
          delay={0}>
          <button type="button">Details</button>
        </HoverCard>,
      );

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

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

    it('survives a tap on its own content', async () => {
      const onOpenChange = vi.fn();
      render(
        <HoverCard
          content={<button type="button">Follow</button>}
          onOpenChange={onOpenChange}
          delay={0}
          hideDelay={0}>
          Ruby Cheung
        </HoverCard>,
      );

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

      const action = await screen.findByRole('button', {
        name: 'Follow',
        hidden: true,
      });
      fireEvent.pointerDown(action, {pointerType: 'touch'});
      fireEvent.pointerUp(action, {pointerType: 'touch'});
      fireEvent.click(action);

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

    it('closes on a tap outside', async () => {
      const onOpenChange = vi.fn();
      render(
        <>
          <HoverCard
            content={<span>Card content</span>}
            onOpenChange={onOpenChange}
            delay={0}
            hideDelay={0}>
            Ruby Cheung
          </HoverCard>
          <button type="button">Elsewhere</button>
        </>,
      );

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

      const elsewhere = screen.getByRole('button', {name: 'Elsewhere'});
      fireEvent.pointerDown(elsewhere, {pointerType: 'touch'});
      // Not yet: a popover closes when the outside tap lifts.
      await new Promise(resolve => setTimeout(resolve, 50));
      expect(onOpenChange).not.toHaveBeenCalledWith(false);

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

    it('opens when the finger lifts, not when it lands', async () => {
      const onOpenChange = vi.fn();
      render(
        <HoverCard
          content={<span>Card content</span>}
          onOpenChange={onOpenChange}
          delay={0}>
          Ruby Cheung
        </HoverCard>,
      );

      const trigger = screen.getByText('Ruby Cheung');
      fireEvent.pointerEnter(trigger, {pointerType: 'touch'});
      fireEvent.pointerDown(trigger, {pointerType: 'touch'});
      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('never opens for a touch that turns into a scroll', async () => {
      const onOpenChange = vi.fn();
      render(
        <HoverCard
          content={<span>Card content</span>}
          onOpenChange={onOpenChange}
          delay={0}>
          Ruby Cheung
        </HoverCard>,
      );

      const trigger = screen.getByText('Ruby Cheung');
      fireEvent.pointerEnter(trigger, {pointerType: 'touch'});
      fireEvent.pointerDown(trigger, {pointerType: 'touch'});
      fireEvent.pointerCancel(trigger, {pointerType: 'touch'});

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

    it('closes when a scroll starts outside, but not for one inside the card', async () => {
      const onOpenChange = vi.fn();
      render(
        <>
          <HoverCard
            content={<p>Card content</p>}
            onOpenChange={onOpenChange}
            delay={0}
            hideDelay={0}>
            Ruby Cheung
          </HoverCard>
          <p>Page content</p>
        </>,
      );

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

      // Scrolling the card's own content keeps it.
      const inside = await screen.findByText('Card content');
      fireEvent.pointerDown(inside, {pointerType: 'touch'});
      fireEvent.pointerCancel(inside, {pointerType: 'touch'});
      await new Promise(resolve => setTimeout(resolve, 50));
      expect(onOpenChange).not.toHaveBeenCalledWith(false);

      const page = screen.getByText('Page content');
      fireEvent.pointerDown(page, {pointerType: 'touch'});
      fireEvent.pointerCancel(page, {pointerType: 'touch'});
      await waitFor(() => {
        expect(onOpenChange).toHaveBeenCalledWith(false);
      });
    });

    it('closes on a second tap of the trigger', async () => {
      const onOpenChange = vi.fn();
      render(
        <HoverCard
          content={<span>Card content</span>}
          onOpenChange={onOpenChange}
          delay={0}
          hideDelay={0}>
          Ruby Cheung
        </HoverCard>,
      );

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

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

    it('ignores the focus a tap leaves behind, but not keyboard focus', async () => {
      const onOpenChange = vi.fn();
      render(
        <HoverCard
          content={<span>Card content</span>}
          onOpenChange={onOpenChange}
          delay={0}>
          <button type="button">Save</button>
        </HoverCard>,
      );

      const trigger = screen.getByRole('button', {name: 'Save'});
      // The tap goes to the button, as `auto` decides for an action trigger —
      // and the focus it leaves behind must not put the card over the control
      // the user just pressed.
      tap(trigger);
      fireEvent.focusIn(trigger);
      await new Promise(resolve => setTimeout(resolve, 50));
      expect(onOpenChange).not.toHaveBeenCalledWith(true);

      // Reaching for the keyboard ends the touch interaction: the same trigger,
      // focused by Tab, still opens.
      fireEvent.keyDown(document, {key: 'Tab'});
      fireEvent.focusIn(trigger);

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

describe('HoverCard theme target names', () => {
  it('renders only the canonical target class on the card surface', async () => {
    render(
      <HoverCard content={<span>Card content</span>} delay={0}>
        <button type="button">Trigger</button>
      </HoverCard>,
    );
    fireEvent.mouseEnter(screen.getByRole('button', {name: 'Trigger'}));

    await waitFor(() => {
      const layer = screen.getByText('Card content').closest('[popover]');
      expect(layer).toHaveClass('astryx-hover-card');
      expect(layer).not.toHaveClass('astryx-hovercard');
    });
  });
});

// FR11: a press inside an open card acts only within the card.
describe('HoverCard surface press', () => {
  it('keeps a click on card content from activating a clickable card', () => {
    const onCardClick = vi.fn();
    const onCardButton = vi.fn();
    render(
      <ClickableCard label="Card" onClick={onCardClick}>
        <span>Card body</span>
        <HoverCard
          isOpen
          content={
            <span>
              Hover content{' '}
              <button type="button" onClick={onCardButton}>
                Card action
              </button>
            </span>
          }>
          <button type="button">Trigger</button>
        </HoverCard>
      </ClickableCard>,
    );
    fireEvent.click(screen.getByText(/Hover content/));
    fireEvent.click(
      screen.getByRole('button', {name: 'Card action', hidden: true}),
    );
    expect(onCardClick).not.toHaveBeenCalled();
    // The hover card's own button keeps its activation.
    expect(onCardButton).toHaveBeenCalledTimes(1);
    // 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 a padded card's own edge from activating a clickable card", () => {
    const onCardClick = vi.fn();
    render(
      <ClickableCard label="Card" onClick={onCardClick}>
        <HoverCard
          isOpen
          style={{padding: 24}}
          content={<span>Hover content</span>}>
          <button type="button">Trigger</button>
        </HoverCard>
      </ClickableCard>,
    );
    // The padding belongs to the layer root around the content.
    const root = screen.getByText('Hover content').closest('[popover]')!;
    fireEvent.click(root);
    expect(onCardClick).not.toHaveBeenCalled();
  });

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

  it('still lets document listeners see a click inside the card', () => {
    const onDocumentClick = vi.fn();
    document.addEventListener('click', onDocumentClick);
    render(
      <HoverCard isOpen content={<span>Hover content</span>}>
        <button type="button">Trigger</button>
      </HoverCard>,
    );
    fireEvent.click(screen.getByText('Hover content'));
    document.removeEventListener('click', onDocumentClick);
    expect(onDocumentClick).toHaveBeenCalledTimes(1);
  });

  it('keeps a click on card text inside a label from toggling its control', () => {
    render(
      <label>
        <input type="checkbox" /> Accept{' '}
        <HoverCard isOpen content={<span>Card content</span>}>
          <button type="button">Info</button>
        </HoverCard>
      </label>,
    );
    // The card mounts outside the label (a label cannot contain it), so a
    // click on its text is not label activation.
    fireEvent.click(screen.getByText('Card content'));
    expect(screen.getByRole('checkbox')).not.toBeChecked();
  });
});

describe('HoverCard timing, hold, and controlled state', () => {
  beforeEach(() => {
    vi.useFakeTimers();
  });

  afterEach(() => {
    vi.useRealTimers();
  });

  function advance(ms: number) {
    act(() => {
      vi.advanceTimersByTime(ms);
    });
  }

  function renderCard(props: Partial<ComponentProps<typeof HoverCard>> = {}) {
    const onOpenChange = vi.fn();
    const result = render(
      <HoverCard
        content={<button type="button">Card action</button>}
        onOpenChange={onOpenChange}
        {...props}>
        <button type="button">Trigger</button>
      </HoverCard>,
    );
    return {
      ...result,
      onOpenChange,
      trigger: screen.getByRole('button', {name: 'Trigger'}),
    };
  }

  function cardSurface(): HTMLElement {
    const action = screen.getByText('Card action');
    return action.parentElement as HTMLElement;
  }

  it('opens only once the hover delay has passed', () => {
    const {trigger, onOpenChange} = renderCard({delay: 300});
    fireEvent.mouseEnter(trigger);
    advance(299);
    expect(onOpenChange).not.toHaveBeenCalled();
    advance(1);
    expect(onOpenChange).toHaveBeenCalledWith(true);
  });

  it('closes only once the hide delay has passed after the pointer leaves', () => {
    const {trigger, onOpenChange} = renderCard({delay: 0, hideDelay: 200});
    fireEvent.mouseEnter(trigger);
    advance(0);
    expect(onOpenChange).toHaveBeenLastCalledWith(true);
    fireEvent.mouseLeave(trigger);
    advance(199);
    expect(onOpenChange).not.toHaveBeenCalledWith(false);
    advance(1);
    expect(onOpenChange).toHaveBeenLastCalledWith(false);
  });

  it('stays open while the pointer moves from the trigger into the card, and closes when it leaves the card', () => {
    const {trigger, onOpenChange} = renderCard({delay: 0, hideDelay: 200});
    fireEvent.mouseEnter(trigger);
    advance(0);
    fireEvent.mouseLeave(trigger);
    fireEvent.mouseEnter(cardSurface());
    advance(500);
    expect(onOpenChange).not.toHaveBeenCalledWith(false);
    expect(screen.getByText('Card action')).toBeInTheDocument();

    fireEvent.mouseLeave(cardSurface());
    advance(200);
    expect(onOpenChange).toHaveBeenLastCalledWith(false);
  });

  it('keeps a card held open by isOpen={true} open when the pointer leaves', () => {
    const {trigger, onOpenChange} = renderCard({
      isOpen: true,
      delay: 0,
      hideDelay: 0,
    });
    expect(screen.getByText('Card action')).toBeInTheDocument();
    fireEvent.mouseEnter(trigger);
    fireEvent.mouseLeave(trigger);
    advance(500);
    expect(onOpenChange).not.toHaveBeenCalledWith(false);
    expect(screen.getByText('Card action')).toBeInTheDocument();
  });

  it('keeps a card held closed by isOpen={false} closed on hover', () => {
    const {trigger, onOpenChange} = renderCard({isOpen: false, delay: 0});
    fireEvent.mouseEnter(trigger);
    advance(500);
    expect(onOpenChange).not.toHaveBeenCalled();
    expect(screen.queryByText('Card action')).not.toBeInTheDocument();
  });

  it('returns focus to the trigger, without reopening, when the caller closes a card that holds focus', () => {
    const {trigger, onOpenChange, rerender} = renderCard({isOpen: true});
    const action = screen.getByText('Card action');
    act(() => {
      action.focus();
    });
    expect(action).toHaveFocus();
    onOpenChange.mockClear();

    rerender(
      <HoverCard
        content={<button type="button">Card action</button>}
        onOpenChange={onOpenChange}
        isOpen={false}>
        <button type="button">Trigger</button>
      </HoverCard>,
    );
    advance(500);
    expect(trigger).toHaveFocus();
    expect(onOpenChange).not.toHaveBeenCalledWith(true);
  });

  it('after the caller closes a focused card and lets go of isOpen, the next trigger focus opens it', () => {
    const {trigger, onOpenChange, rerender} = renderCard({isOpen: true});
    const action = screen.getByText('Card action');
    act(() => {
      action.focus();
    });
    const card = (isOpen: boolean | undefined) => (
      <HoverCard
        content={<button type="button">Card action</button>}
        onOpenChange={onOpenChange}
        isOpen={isOpen}>
        <button type="button">Trigger</button>
      </HoverCard>
    );
    rerender(card(false));
    advance(500);
    expect(trigger).toHaveFocus();

    // The refocus that the close made used up the re-show guard, so the
    // first focus after the caller lets go opens the card.
    rerender(card(undefined));
    act(() => {
      trigger.blur();
    });
    onOpenChange.mockClear();
    act(() => {
      trigger.focus();
    });
    advance(500);
    expect(onOpenChange).toHaveBeenCalledWith(true);
  });

  it('applies xstyle to the themed card surface', () => {
    const overrides = stylex.create({card: {minWidth: 240}});
    renderCard({isOpen: true, xstyle: overrides.card});
    const card = screen.getByText('Card action').closest('[popover]');
    expect(card).toHaveClass('astryx-hover-card');
    const callerClasses = stylex.props(overrides.card).className?.split(' ');
    expect(callerClasses?.length).toBeGreaterThan(0);
    expect(card).toHaveClass(...(callerClasses ?? []));
  });

  it('applies className and style to the themed card surface', () => {
    renderCard({
      isOpen: true,
      className: 'caller-card',
      style: {maxInlineSize: 320},
    });
    const card = screen.getByText('Card action').closest('[popover]');
    expect(card).toHaveClass('astryx-hover-card');
    expect(card).toHaveClass('caller-card');
    expect(card?.getAttribute('style')).toContain('max-inline-size: 320px');
  });

  it("restores the trigger's own popup attributes when the label is removed", () => {
    const {rerender} = render(
      <HoverCard content={<span>Card content</span>} label="Profile" isOpen>
        <button
          type="button"
          aria-haspopup="menu"
          aria-expanded="false"
          aria-controls="own-menu">
          Trigger
        </button>
      </HoverCard>,
    );
    const trigger = screen.getByRole('button', {name: 'Trigger'});
    const cardId = screen.getByText('Card content').closest('[popover]')?.id;
    expect(trigger).toHaveAttribute('aria-haspopup', 'dialog');
    expect(trigger).toHaveAttribute('aria-expanded', 'true');
    expect(trigger).toHaveAttribute('aria-controls', `own-menu ${cardId}`);

    rerender(
      <HoverCard content={<span>Card content</span>} isOpen>
        <button
          type="button"
          aria-haspopup="menu"
          aria-expanded="false"
          aria-controls="own-menu">
          Trigger
        </button>
      </HoverCard>,
    );
    expect(trigger).toHaveAttribute('aria-haspopup', 'menu');
    expect(trigger).toHaveAttribute('aria-expanded', 'false');
    expect(trigger).toHaveAttribute('aria-controls', 'own-menu');
    expect(trigger).toHaveAttribute('aria-describedby');
  });
});