Skip to content

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

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

import {beforeEach, describe, it, expect, vi} from 'vitest';
import {Activity, type KeyboardEvent} from 'react';
import {render, screen, fireEvent} from '@testing-library/react';
import userEvent from '@testing-library/user-event';
import {LinkProvider} from '../Link';
import {NavHeadingMenu} from './NavHeadingMenu';
import {NavHeadingMenuItem} from './NavHeadingMenuItem';
import {NavHeadingCloseContext} from './NavMenuContext';
import {__resetMenuPressForTest} from '../hooks/useMenuPress';
import {expectNativeLinkClicks} from '../hooks/__tests__/menuLinkClicks';

describe('NavHeadingMenu', () => {
  it('renders with role="menu"', () => {
    render(
      <NavHeadingMenu>
        <NavHeadingMenuItem label="Item 1" />
      </NavHeadingMenu>,
    );
    expect(screen.getByRole('menu')).toBeInTheDocument();
  });

  it('renders children as menuitems', () => {
    render(
      <NavHeadingMenu>
        <NavHeadingMenuItem label="Dashboard" />
        <NavHeadingMenuItem label="Settings" />
      </NavHeadingMenu>,
    );
    const items = screen.getAllByRole('menuitem');
    expect(items).toHaveLength(2);
    expect(items[0]).toHaveTextContent('Dashboard');
    expect(items[1]).toHaveTextContent('Settings');
  });

  it('applies size class to container', () => {
    render(
      <NavHeadingMenu size="lg">
        <NavHeadingMenuItem label="Item" />
      </NavHeadingMenu>,
    );
    const menu = screen.getByRole('menu');
    expect(menu.className).toContain('nav-heading-menu');
  });

  it('applies data-testid', () => {
    render(
      <NavHeadingMenu data-testid="product-menu">
        <NavHeadingMenuItem label="Item" />
      </NavHeadingMenu>,
    );
    expect(screen.getByTestId('product-menu')).toBeInTheDocument();
  });

  it('applies minWidth override via inline style', () => {
    render(
      <NavHeadingMenu minWidth={300}>
        <NavHeadingMenuItem label="Item" />
      </NavHeadingMenu>,
    );
    const menu = screen.getByRole('menu');
    expect(menu.style.minWidth).toBe('300px');
  });
});

describe('NavHeadingMenuItem', () => {
  it('renders with role="menuitem"', () => {
    render(
      <NavHeadingMenu>
        <NavHeadingMenuItem label="Dashboard" />
      </NavHeadingMenu>,
    );
    expect(screen.getByRole('menuitem')).toHaveTextContent('Dashboard');
  });

  it('renders as a link when href is provided', () => {
    render(
      <NavHeadingMenu>
        <NavHeadingMenuItem label="Docs" href="/docs" />
      </NavHeadingMenu>,
    );
    const item = screen.getByRole('menuitem');
    expect(item.tagName).toBe('A');
    expect(item).toHaveAttribute('href', '/docs');
  });

  it('renders as div when no href', () => {
    render(
      <NavHeadingMenu>
        <NavHeadingMenuItem label="Action" onClick={() => {}} />
      </NavHeadingMenu>,
    );
    const item = screen.getByRole('menuitem');
    expect(item.tagName).toBe('DIV');
  });

  it('calls onClick on click', async () => {
    const user = userEvent.setup();
    const onClick = vi.fn();
    render(
      <NavHeadingMenu>
        <NavHeadingMenuItem label="Action" onClick={onClick} />
      </NavHeadingMenu>,
    );
    await user.click(screen.getByRole('menuitem'));
    expect(onClick).toHaveBeenCalledOnce();
  });

  it('does not call onClick when disabled', async () => {
    const user = userEvent.setup();
    const onClick = vi.fn();
    render(
      <NavHeadingMenu>
        <NavHeadingMenuItem label="Action" onClick={onClick} isDisabled />
      </NavHeadingMenu>,
    );
    await user.click(screen.getByRole('menuitem'));
    expect(onClick).not.toHaveBeenCalled();
  });

  it('sets aria-disabled when disabled', () => {
    render(
      <NavHeadingMenu>
        <NavHeadingMenuItem label="Disabled" isDisabled />
      </NavHeadingMenu>,
    );
    expect(screen.getByRole('menuitem')).toHaveAttribute(
      'aria-disabled',
      'true',
    );
  });

  it('exposes no destination on a disabled link item', () => {
    render(
      <NavHeadingMenu>
        <NavHeadingMenuItem label="Docs" href="/docs" isDisabled />
      </NavHeadingMenu>,
    );
    const item = screen.getByRole('menuitem');
    // No href means no navigation path at all: not a pointer click, a
    // middle-click, an assistive-technology activation, or Enter.
    expect(item).not.toHaveAttribute('href');
    // The row keeps its shape and still reports the disabled state.
    expect(item.tagName).toBe('A');
    expect(item).toHaveAttribute('aria-disabled', 'true');
  });

  it('does not reach a custom link component when a link item is disabled', () => {
    function CustomLink({
      children,
      ref,
      ...props
    }: React.ComponentPropsWithRef<'a'>) {
      return (
        <a ref={ref} data-custom-link {...props}>
          {children}
        </a>
      );
    }
    render(
      <LinkProvider component={CustomLink}>
        <NavHeadingMenu>
          <NavHeadingMenuItem label="Docs" href="/docs" isDisabled />
        </NavHeadingMenu>
      </LinkProvider>,
    );
    const item = screen.getByRole('menuitem');
    expect(item).not.toHaveAttribute('data-custom-link');
    expect(item).not.toHaveAttribute('href');
  });

  it('keeps an enabled link item on the custom link component', () => {
    function CustomLink({
      children,
      ref,
      ...props
    }: React.ComponentPropsWithRef<'a'>) {
      return (
        <a ref={ref} data-custom-link {...props}>
          {children}
        </a>
      );
    }
    render(
      <LinkProvider component={CustomLink}>
        <NavHeadingMenu>
          <NavHeadingMenuItem label="Docs" href="/docs" />
        </NavHeadingMenu>
      </LinkProvider>,
    );
    const item = screen.getByRole('menuitem');
    expect(item).toHaveAttribute('data-custom-link');
    expect(item).toHaveAttribute('href', '/docs');
  });

  it('keeps a disabled link item focusable but out of the Tab order', () => {
    render(
      <NavHeadingMenu>
        <NavHeadingMenuItem label="Docs" href="/docs" isDisabled />
      </NavHeadingMenu>,
    );
    const item = screen.getByRole('menuitem');
    // No href and no tabindex would make the anchor unfocusable.
    expect(item).toHaveAttribute('tabindex', '-1');
    item.focus();
    expect(item).toHaveFocus();
  });

  it('keeps focus on a link item that becomes disabled while focused', () => {
    const {rerender} = render(
      <NavHeadingMenu>
        <NavHeadingMenuItem label="Docs" href="/docs" />
      </NavHeadingMenu>,
    );
    screen.getByRole('menuitem').focus();
    expect(screen.getByRole('menuitem')).toHaveFocus();

    rerender(
      <NavHeadingMenu>
        <NavHeadingMenuItem label="Docs" href="/docs" isDisabled />
      </NavHeadingMenu>,
    );
    const disabled = screen.getByRole('menuitem');
    expect(disabled).not.toHaveAttribute('href');
    expect(disabled).toHaveFocus();

    rerender(
      <NavHeadingMenu>
        <NavHeadingMenuItem label="Docs" href="/docs" />
      </NavHeadingMenu>,
    );
    expect(screen.getByRole('menuitem')).toHaveFocus();
  });

  it('does not steal focus when an unfocused link item toggles disabled', () => {
    const {rerender} = render(
      <NavHeadingMenu>
        <NavHeadingMenuItem label="Docs" href="/docs" />
      </NavHeadingMenu>,
    );
    rerender(
      <NavHeadingMenu>
        <NavHeadingMenuItem label="Docs" href="/docs" isDisabled />
      </NavHeadingMenu>,
    );
    expect(screen.getByRole('menuitem')).not.toHaveFocus();
  });

  it('does not pull focus back when an Activity boundary reveals a row', () => {
    const tree = (mode: 'visible' | 'hidden') => (
      <>
        <button type="button">Elsewhere</button>
        <Activity mode={mode}>
          <NavHeadingMenu>
            <NavHeadingMenuItem label="Docs" href="/docs" />
          </NavHeadingMenu>
        </Activity>
      </>
    );
    const {rerender} = render(tree('visible'));
    screen.getByRole('menuitem').focus();
    expect(screen.getByRole('menuitem')).toHaveFocus();

    // Hide the row while it holds focus, then move focus elsewhere.
    rerender(tree('hidden'));
    const other = screen.getByRole('button', {name: 'Elsewhere'});
    other.focus();
    expect(other).toHaveFocus();

    // Revealing the same node must leave focus where the person put it.
    rerender(tree('visible'));
    expect(other).toHaveFocus();
  });

  it('leaves focus on the page when an Activity boundary reveals a row', () => {
    const tree = (mode: 'visible' | 'hidden') => (
      <Activity mode={mode}>
        <NavHeadingMenu>
          <NavHeadingMenuItem label="Docs" href="/docs" />
        </NavHeadingMenu>
      </Activity>
    );
    const {rerender} = render(tree('visible'));
    screen.getByRole('menuitem').focus();
    expect(screen.getByRole('menuitem')).toHaveFocus();

    // Hide while focused, then drop focus to the page.
    rerender(tree('hidden'));
    (document.activeElement as HTMLElement | null)?.blur();

    // The same node re-attaches on reveal; it was not replaced, so it must not
    // pull focus back from the page.
    rerender(tree('visible'));
    expect(document.activeElement).toBe(document.body);
  });

  it('does not take focus on reveal when isDisabled flipped while hidden', () => {
    const tree = (mode: 'visible' | 'hidden', isDisabled: boolean) => (
      <>
        <button type="button">Elsewhere</button>
        <Activity mode={mode}>
          <NavHeadingMenu>
            <NavHeadingMenuItem
              label="Billing"
              href="/billing"
              isDisabled={isDisabled}
            />
          </NavHeadingMenu>
        </Activity>
      </>
    );
    const {rerender} = render(tree('visible', false));
    screen.getByRole('menuitem').focus();
    expect(screen.getByRole('menuitem')).toHaveFocus();

    // Hide while focused, swap the row's element type while hidden, then move
    // focus to another control.
    rerender(tree('hidden', false));
    rerender(tree('hidden', true));
    const other = screen.getByRole('button', {name: 'Elsewhere'});
    other.focus();
    expect(other).toHaveFocus();

    // The swapped-in node attaches only now and must not take focus.
    rerender(tree('visible', true));
    expect(screen.getByRole('menuitem')).not.toHaveAttribute('href');
    expect(other).toHaveFocus();
  });

  it('renders description text', () => {
    render(
      <NavHeadingMenu>
        <NavHeadingMenuItem label="Dashboard" description="View metrics" />
      </NavHeadingMenu>,
    );
    expect(screen.getByText('View metrics')).toBeInTheDocument();
  });

  it('applies data-testid', () => {
    render(
      <NavHeadingMenu>
        <NavHeadingMenuItem label="Item" data-testid="menu-item-1" />
      </NavHeadingMenu>,
    );
    expect(screen.getByTestId('menu-item-1')).toBeInTheDocument();
  });
});

describe('keyboard navigation', () => {
  it('reaches a disabled row with the keys and type-ahead; the row stays inert', async () => {
    const user = userEvent.setup();
    const onArchive = vi.fn();
    render(
      <NavHeadingMenu>
        <NavHeadingMenuItem label="Rename" />
        <NavHeadingMenuItem label="Archive" isDisabled onClick={onArchive} />
        <NavHeadingMenuItem label="Delete" />
      </NavHeadingMenu>,
    );
    const [rename, archive, del] = screen.getAllByRole('menuitem');
    rename.focus();
    fireEvent.keyDown(rename, {key: 'ArrowDown'});
    expect(archive).toHaveFocus();
    await user.keyboard('{Enter}');
    expect(onArchive).not.toHaveBeenCalled();
    fireEvent.keyDown(archive, {key: 'ArrowDown'});
    expect(del).toHaveFocus();
    fireEvent.keyDown(del, {key: 'a'});
    expect(archive).toHaveFocus();
  });

  it('keeps arrow navigation when an item handler cancels', () => {
    const onKeyDown = vi.fn((event: KeyboardEvent) => event.preventDefault());
    render(
      <NavHeadingMenu>
        <NavHeadingMenuItem label="First" onKeyDown={onKeyDown} />
        <NavHeadingMenuItem label="Second" />
      </NavHeadingMenu>,
    );
    const [first, second] = screen.getAllByRole('menuitem');
    first.focus();
    fireEvent.keyDown(first, {key: 'ArrowDown'});
    expect(onKeyDown).toHaveBeenCalledOnce();
    expect(second).toHaveFocus();
  });

  it.each(['onKeyDown', 'onKeyDownCapture'] as const)(
    'preserves menu-level cancellation through %s',
    handler => {
      const cancel = vi.fn((event: KeyboardEvent) => event.preventDefault());
      render(
        <NavHeadingMenu {...{[handler]: cancel}}>
          <NavHeadingMenuItem label="First" />
          <NavHeadingMenuItem label="Second" />
        </NavHeadingMenu>,
      );
      const first = screen.getAllByRole('menuitem')[0];
      first.focus();
      fireEvent.keyDown(first, {key: 'ArrowDown'});
      expect(cancel).toHaveBeenCalledOnce();
      expect(first).toHaveFocus();
    },
  );

  it('moves focus with arrow keys', async () => {
    const user = userEvent.setup();
    render(
      <NavHeadingMenu>
        <NavHeadingMenuItem label="First" />
        <NavHeadingMenuItem label="Second" />
        <NavHeadingMenuItem label="Third" />
      </NavHeadingMenu>,
    );
    const items = screen.getAllByRole('menuitem');
    items[0].focus();
    expect(document.activeElement).toBe(items[0]);

    await user.keyboard('{ArrowDown}');
    expect(document.activeElement).toBe(items[1]);

    await user.keyboard('{ArrowDown}');
    expect(document.activeElement).toBe(items[2]);

    await user.keyboard('{ArrowUp}');
    expect(document.activeElement).toBe(items[1]);
  });

  it('wraps focus at boundaries', async () => {
    const user = userEvent.setup();
    render(
      <NavHeadingMenu>
        <NavHeadingMenuItem label="First" />
        <NavHeadingMenuItem label="Last" />
      </NavHeadingMenu>,
    );
    const items = screen.getAllByRole('menuitem');
    items[1].focus();

    await user.keyboard('{ArrowDown}');
    expect(document.activeElement).toBe(items[0]);
  });

  it('Home focuses first item, End focuses last', async () => {
    const user = userEvent.setup();
    render(
      <NavHeadingMenu>
        <NavHeadingMenuItem label="First" />
        <NavHeadingMenuItem label="Middle" />
        <NavHeadingMenuItem label="Last" />
      </NavHeadingMenu>,
    );
    const items = screen.getAllByRole('menuitem');
    items[1].focus();

    await user.keyboard('{Home}');
    expect(document.activeElement).toBe(items[0]);

    await user.keyboard('{End}');
    expect(document.activeElement).toBe(items[2]);
  });

  it('activates a focused onClick-only item with Enter', async () => {
    const user = userEvent.setup();
    const onClick = vi.fn();
    render(
      <NavHeadingMenu>
        <NavHeadingMenuItem label="Action" onClick={onClick} />
      </NavHeadingMenu>,
    );
    const item = screen.getByRole('menuitem');
    item.focus();

    await user.keyboard('{Enter}');
    expect(onClick).toHaveBeenCalledOnce();
  });

  it('activates a focused onClick-only item with Space', async () => {
    const user = userEvent.setup();
    const onClick = vi.fn();
    render(
      <NavHeadingMenu>
        <NavHeadingMenuItem label="Action" onClick={onClick} />
      </NavHeadingMenu>,
    );
    const item = screen.getByRole('menuitem');
    item.focus();

    await user.keyboard('{ }');
    expect(onClick).toHaveBeenCalledOnce();
  });

  it('does not activate a disabled item with Enter', async () => {
    const user = userEvent.setup();
    const onClick = vi.fn();
    render(
      <NavHeadingMenu>
        <NavHeadingMenuItem label="Action" onClick={onClick} isDisabled />
      </NavHeadingMenu>,
    );
    const item = screen.getByRole('menuitem');
    item.focus();

    await user.keyboard('{Enter}');
    expect(onClick).not.toHaveBeenCalled();
  });

  it('typeahead focuses the item matching the typed character (menus-11)', () => {
    render(
      <NavHeadingMenu>
        <NavHeadingMenuItem label="Cut" />
        <NavHeadingMenuItem label="Paste" />
      </NavHeadingMenu>,
    );
    const menu = screen.getByRole('menu');
    fireEvent.keyDown(menu, {key: 'p'});
    expect(screen.getByRole('menuitem', {name: 'Paste'})).toHaveFocus();
  });

  it('typeahead reaches a disabled menuitem, which stays discoverable', () => {
    render(
      <NavHeadingMenu>
        <NavHeadingMenuItem label="Cut" />
        <NavHeadingMenuItem label="Paste (disabled)" isDisabled />
        <NavHeadingMenuItem label="Paste special" />
      </NavHeadingMenu>,
    );
    const menu = screen.getByRole('menu');
    fireEvent.keyDown(menu, {key: 'p'});
    expect(
      screen.getByRole('menuitem', {name: 'Paste (disabled)'}),
    ).toHaveFocus();
  });
});

describe('context forwarding', () => {
  it('forwards closeMenu from parent NavMenuContext', async () => {
    const user = userEvent.setup();
    const closeMenu = vi.fn();
    render(
      <NavHeadingMenu>
        <NavHeadingMenuItem label="Action" onClick={() => {}} />
      </NavHeadingMenu>,
      {
        wrapper: ({children}) => (
          <NavHeadingCloseContext value={{closeMenu}}>
            {children}
          </NavHeadingCloseContext>
        ),
      },
    );
    await user.click(screen.getByRole('menuitem'));
    expect(closeMenu).toHaveBeenCalledOnce();
  });

  it('calls parent closeMenu on Escape', async () => {
    const user = userEvent.setup();
    const closeMenu = vi.fn();
    render(
      <NavHeadingMenu>
        <NavHeadingMenuItem label="First" />
      </NavHeadingMenu>,
      {
        wrapper: ({children}) => (
          <NavHeadingCloseContext value={{closeMenu}}>
            {children}
          </NavHeadingCloseContext>
        ),
      },
    );
    screen.getByRole('menuitem').focus();
    await user.keyboard('{Escape}');
    expect(closeMenu).toHaveBeenCalledOnce();
  });
});

describe('NavHeadingMenu pass-through props', () => {
  it('forwards pass-through props to the menu element', () => {
    render(
      <NavHeadingMenu aria-label="Products" id="products" data-source="nav">
        <NavHeadingMenuItem label="First" />
      </NavHeadingMenu>,
    );
    const menu = screen.getByRole('menu');
    expect(menu).toHaveAttribute('aria-label', 'Products');
    expect(menu).toHaveAttribute('id', 'products');
    expect(menu).toHaveAttribute('data-source', 'nav');
  });

  it('runs a caller onKeyDown alongside the menu keyboard model', async () => {
    const user = userEvent.setup();
    const onKeyDown = vi.fn();
    render(
      <NavHeadingMenu onKeyDown={onKeyDown}>
        <NavHeadingMenuItem label="First" />
        <NavHeadingMenuItem label="Second" />
      </NavHeadingMenu>,
    );
    const items = screen.getAllByRole('menuitem');
    items[0].focus();
    await user.keyboard('{ArrowDown}');
    expect(onKeyDown).toHaveBeenCalled();
    expect(items[1]).toHaveFocus();
  });
});

describe('NavHeadingMenuItem pass-through props', () => {
  it('forwards pass-through props to the item element', () => {
    render(
      <NavHeadingMenu>
        <NavHeadingMenuItem
          label="Dashboard"
          aria-label="Open dashboard"
          id="nav-dashboard"
          data-tracking="nav-item"
          data-testid="item"
        />
      </NavHeadingMenu>,
    );
    const item = screen.getByTestId('item');
    expect(item).toHaveAttribute('aria-label', 'Open dashboard');
    expect(item).toHaveAttribute('id', 'nav-dashboard');
    expect(item).toHaveAttribute('data-tracking', 'nav-item');
  });

  it('forwards event handlers to the item element', () => {
    const handleMouseEnter = vi.fn();
    render(
      <NavHeadingMenu>
        <NavHeadingMenuItem
          label="Dashboard"
          onMouseEnter={handleMouseEnter}
          data-testid="item"
        />
      </NavHeadingMenu>,
    );
    fireEvent.mouseEnter(screen.getByTestId('item'));
    expect(handleMouseEnter).toHaveBeenCalledOnce();
  });

  it('keeps the menuitem contract over colliding pass-throughs', () => {
    render(
      <NavHeadingMenu>
        <NavHeadingMenuItem
          label="Dashboard"
          data-testid="item"
          role="button"
          aria-disabled="false"
          isDisabled
        />
      </NavHeadingMenu>,
    );
    // Owned role and aria-disabled win over the colliding pass-throughs.
    const item = screen.getByTestId('item');
    expect(item).toHaveAttribute('role', 'menuitem');
    expect(item).toHaveAttribute('aria-disabled', 'true');
  });
});

describe('NavHeadingMenu as an action group (family:action-groups)', () => {
  beforeEach(() => {
    __resetMenuPressForTest();
  });

  const item = (name: string) => screen.getByRole('menuitem', {name});
  const finger = {pointerType: 'touch', pointerId: 1};
  const mouse = {pointerType: 'mouse', pointerId: 1, button: 0};

  function renderMenu() {
    const onDashboard = vi.fn();
    const onSettings = vi.fn();
    const closeMenu = vi.fn();
    render(
      <NavHeadingCloseContext value={{closeMenu}}>
        <NavHeadingMenu>
          <NavHeadingMenuItem label="Dashboard" onClick={onDashboard} />
          <NavHeadingMenuItem label="Settings" onClick={onSettings} />
          <NavHeadingMenuItem label="Archive" isDisabled />
        </NavHeadingMenu>
      </NavHeadingCloseContext>,
    );
    return {onDashboard, onSettings, closeMenu};
  }

  it('renders a link item undraggable, so a mouse press that slides to another item is not a drag', () => {
    render(
      <NavHeadingMenu>
        <NavHeadingMenuItem label="Docs" href="/docs" />
        <NavHeadingMenuItem label="Sign out" onClick={() => {}} />
      </NavHeadingMenu>,
    );
    expect(item('Docs')).toHaveAttribute('draggable', 'false');
    expect(item('Sign out')).not.toHaveAttribute('draggable');
  });

  it('leaves a Ctrl-, Cmd-, Shift- or middle click on a link item to the browser', () => {
    render(
      <NavHeadingMenu>
        <NavHeadingMenuItem label="Docs" href="/docs" />
        <NavHeadingMenuItem label="Status" href="/status" />
      </NavHeadingMenu>,
    );
    expectNativeLinkClicks(item('Docs'));
  });

  it('acts on the item a finger lifts on, once, after sliding from another (FR1, FR2)', () => {
    const {onDashboard, onSettings} = renderMenu();
    fireEvent.pointerDown(item('Dashboard'), finger);
    fireEvent.pointerMove(item('Settings'), finger);
    fireEvent.pointerUp(item('Settings'), finger);
    expect(onSettings).toHaveBeenCalledTimes(1);
    expect(onDashboard).not.toHaveBeenCalled();
  });

  it('acts on the item a held mouse lifts on (FR5)', () => {
    const {onDashboard, onSettings} = renderMenu();
    fireEvent.pointerDown(item('Settings'), mouse);
    fireEvent.pointerMove(item('Dashboard'), mouse);
    fireEvent.pointerUp(item('Dashboard'), mouse);
    expect(onDashboard).toHaveBeenCalledTimes(1);
    expect(onSettings).not.toHaveBeenCalled();
  });

  it('acts on nothing for a lift on a disabled item (FR2)', () => {
    const {onDashboard, onSettings} = renderMenu();
    fireEvent.pointerDown(item('Dashboard'), finger);
    fireEvent.pointerMove(item('Archive'), finger);
    fireEvent.pointerUp(item('Archive'), finger);
    expect(onDashboard).not.toHaveBeenCalled();
    expect(onSettings).not.toHaveBeenCalled();
  });
});