Skip to content

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

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

/**
 * @file List.test.tsx
 * @input Uses vitest, @testing-library/react, List, ListItem
 * @output Unit tests for List and ListItem, including the row edge treatment
 * @position Testing; validates List.tsx and ListItem.tsx implementation
 *
 * SYNC: When modified, update this header
 */

import {useRef} from 'react';
import {describe, it, expect, vi} from 'vitest';
import {cleanup, render, screen} from '@testing-library/react';
import userEvent from '@testing-library/user-event';
import {rulesDeclaredFor} from '../__tests__/pressState';
import {swipeLayerLoaded} from '../Item/__tests__/swipeLayerLoaded';

/**
 * The element's injected rules split by the touch gate: inside
 * `@media (pointer: coarse)` (TOUCH_QUERY, utils/touchQueries.ts), or
 * not.
 */
function touchGatedRules(el: Element): {touch: string[]; other: string[]} {
  const classes = el.className
    .split(/\s+/)
    .filter(Boolean)
    .map(name => `.${name}`);
  const out = {touch: [] as string[], other: [] as string[]};
  const visit = (rules: CSSRuleList, touch: boolean) => {
    for (const rule of Array.from(rules)) {
      if (rule instanceof CSSStyleRule) {
        if (classes.some(cls => rule.selectorText.startsWith(cls))) {
          (touch ? out.touch : out.other).push(
            `${rule.selectorText} {${rule.style.cssText}}`,
          );
        }
        continue;
      }
      const nested = (rule as CSSGroupingRule).cssRules;
      if (nested == null) {
        continue;
      }
      const condition = (rule as CSSConditionRule).conditionText ?? '';
      visit(nested, touch || condition.includes('pointer: coarse'));
    }
  };
  for (const sheet of Array.from(document.styleSheets)) {
    visit(sheet.cssRules, false);
  }
  return out;
}
import {List} from './List';
import {ListItem} from './ListItem';
import {ListMarkerScope} from './ListContext';
import {HIT_INSET_PROPERTIES} from '../utils/hitArea';
import {useAnimatedLayout} from '../hooks/useAnimatedLayout';

describe('List', () => {
  it('forwards ListItem align to its Item row unchanged', () => {
    render(
      <List>
        <ListItem label="Default" data-testid="default" />
        <ListItem label="Start" align="start" data-testid="start" />
        <ListItem label="First" align="first-line" data-testid="first" />
      </List>,
    );
    expect(screen.getByTestId('default')).toHaveAttribute(
      'data-align',
      'center',
    );
    expect(screen.getByTestId('start')).toHaveAttribute('data-align', 'start');
    expect(screen.getByTestId('first')).toHaveAttribute(
      'data-align',
      'first-line',
    );
  });

  // ===========================================================================
  // Basic rendering
  // ===========================================================================

  it('renders a list with items', () => {
    render(
      <List>
        <ListItem label="Item 1" />
        <ListItem label="Item 2" />
      </List>,
    );
    expect(screen.getByText('Item 1')).toBeInTheDocument();
    expect(screen.getByText('Item 2')).toBeInTheDocument();
  });

  it('renders label and description', () => {
    render(
      <List>
        <ListItem label="Settings" description="Manage your preferences" />
      </List>,
    );
    expect(screen.getByText('Settings')).toBeInTheDocument();
    expect(screen.getByText('Manage your preferences')).toBeInTheDocument();
  });

  it('supports data-testid on list', () => {
    render(
      <List data-testid="my-list">
        <ListItem label="Item" />
      </List>,
    );
    expect(screen.getByTestId('my-list')).toBeInTheDocument();
  });

  it('supports data-testid on list item', () => {
    render(
      <List>
        <ListItem label="Item" data-testid="my-item" />
      </List>,
    );
    expect(screen.getByTestId('my-item')).toBeInTheDocument();
  });

  // ===========================================================================
  // Semantic HTML
  // ===========================================================================

  it('renders as <ul> by default', () => {
    const {container} = render(
      <List>
        <ListItem label="Item" />
      </List>,
    );
    expect(container.querySelector('ul')).toBeInTheDocument();
    expect(container.querySelector('ol')).not.toBeInTheDocument();
  });

  it('renders as <ol> when listStyle is decimal', () => {
    const {container} = render(
      <List listStyle="decimal">
        <ListItem label="First" />
        <ListItem label="Second" />
      </List>,
    );
    expect(container.querySelector('ol')).toBeInTheDocument();
    expect(container.querySelector('ul')).not.toBeInTheDocument();
  });

  it('applies custom counter start value', () => {
    const {container} = render(
      <List listStyle="decimal" start={3}>
        <ListItem label="Third" />
        <ListItem label="Fourth" />
      </List>,
    );
    const ol = container.querySelector('ol')!;
    // The counter-reset style should include the start offset (start - 1 = 2)
    expect(ol.className).toContain('counterStart');
  });

  it('emits the start HTML attribute on <ol> when start is non-default', () => {
    // Browsers and assistive tech read the start attribute directly; the CSS
    // counter alone is invisible to AT and copy-paste.
    const {container} = render(
      <List listStyle="decimal" start={5}>
        <ListItem label="Fifth" />
      </List>,
    );
    const ol = container.querySelector('ol')!;
    expect(ol.getAttribute('start')).toBe('5');
  });

  it('does not emit the start HTML attribute for the default (start=1)', () => {
    const {container} = render(
      <List listStyle="decimal">
        <ListItem label="First" />
      </List>,
    );
    const ol = container.querySelector('ol')!;
    expect(ol.hasAttribute('start')).toBe(false);
  });

  it('renders as <ul> when listStyle is disc', () => {
    const {container} = render(
      <List listStyle="disc">
        <ListItem label="Item" />
      </List>,
    );
    expect(container.querySelector('ul')).toBeInTheDocument();
  });

  it('renders as <ul> when listStyle is circle', () => {
    const {container} = render(
      <List listStyle="circle">
        <ListItem label="Item" />
      </List>,
    );
    expect(container.querySelector('ul')).toBeInTheDocument();
  });

  it.each(['none', 'disc', 'circle', 'decimal'] as const)(
    'adds an explicit role="list" when listStyle is %s (Safari fix)',
    listStyle => {
      // The base list style always sets list-style-type: none (markers are
      // custom-rendered by ListItem), so Safari/VoiceOver drops the implicit
      // list role for EVERY variant — the explicit role must always be there.
      render(
        <List listStyle={listStyle}>
          <ListItem label="Item 1" />
          <ListItem label="Item 2" />
        </List>,
      );
      const list = screen.getByRole('list');
      expect(list).toHaveAttribute('role', 'list');
      expect(screen.getAllByRole('listitem')).toHaveLength(2);
    },
  );

  it('renders items as <li> elements', () => {
    const {container} = render(
      <List>
        <ListItem label="Item 1" />
        <ListItem label="Item 2" />
      </List>,
    );
    const items = container.querySelectorAll('li');
    expect(items).toHaveLength(2);
  });

  // ===========================================================================
  // Header with aria-labelledby
  // ===========================================================================

  it('renders header and associates via aria-labelledby', () => {
    const {container} = render(
      <List header={<span>Team Members</span>}>
        <ListItem label="Alice" />
      </List>,
    );
    expect(screen.getByText('Team Members')).toBeInTheDocument();
    const ul = container.querySelector('ul');
    const headerId = ul?.getAttribute('aria-labelledby');
    expect(headerId).toBeTruthy();
    const headerEl = document.getElementById(headerId!);
    expect(headerEl).toBeInTheDocument();
    expect(headerEl?.textContent).toBe('Team Members');
  });

  it('does not render aria-labelledby when no header', () => {
    const {container} = render(
      <List>
        <ListItem label="Item" />
      </List>,
    );
    const ul = container.querySelector('ul');
    expect(ul).not.toHaveAttribute('aria-labelledby');
  });

  it('wraps header and list in a column container', () => {
    const {container} = render(
      <List header={<span>Group</span>}>
        <ListItem label="Item" />
      </List>,
    );
    const header = screen.getByText('Group');
    const wrapper = header.parentElement?.parentElement;
    const ul = container.querySelector('ul');
    expect(wrapper).toContainElement(header.parentElement);
    expect(wrapper).toContainElement(ul);
  });

  it('does not add a wrapper div when header is absent', () => {
    const {container} = render(
      <List data-testid="my-list">
        <ListItem label="Item" />
      </List>,
    );
    const ul = container.querySelector('ul');
    expect(ul?.parentElement).toBe(container);
  });

  // ===========================================================================
  // Density variants
  // ===========================================================================

  it('renders with compact density', () => {
    const {container} = render(
      <List density="compact">
        <ListItem label="Item" />
      </List>,
    );
    const item = container.querySelector('li');
    expect(item).toBeInTheDocument();
    expect(item).toHaveAttribute('data-density', 'compact');
  });

  it('renders with balanced density (default)', () => {
    const {container} = render(
      <List>
        <ListItem label="Item" />
      </List>,
    );
    const item = container.querySelector('li');
    expect(item).toBeInTheDocument();
    expect(item).toHaveAttribute('data-density', 'balanced');
    expect(item).not.toHaveAttribute('data-density', 'spacious');
  });

  it('renders with spacious density', () => {
    const {container} = render(
      <List density="spacious">
        <ListItem label="Item" />
      </List>,
    );
    const item = container.querySelector('li');
    expect(item).toBeInTheDocument();
    expect(item).toHaveAttribute('data-density', 'spacious');
  });

  // ===========================================================================
  // Edge treatment
  // ===========================================================================

  /** Every injected rule that names one of the element's classes. */
  function declarationsFor(el: Element): string {
    return rulesDeclaredFor(el).join('\n').replace(/\s+/g, '');
  }

  /** The declarations of the row inset variable that reach the row. */
  function insetDeclarations(item: Element): string[] {
    return rulesDeclaredFor(item).filter(rule =>
      rule.includes('--_item-inset-inline:'),
    );
  }

  const ZERO_INSET = /--_item-inset-inline:\s*0(px)?\s*;/;
  const LIST_REACH = [
    'margin-inline-start:calc(-1*var(--container-padding-inline-start,0px))',
    'margin-inline-end:calc(-1*var(--container-padding-inline-end,0px))',
    'width:calc(100%+var(--container-padding-inline-start,0px)+var(--container-padding-inline-end,0px))',
  ];
  const OUTSET_ROW = [
    'margin-inline-start:max(var(--container-padding-inline-start,0px)-var(--_item-inset-inline),0px)',
    'margin-inline-end:max(var(--container-padding-inline-end,0px)-var(--_item-inset-inline),0px)',
  ];
  const BLEED_ROW = [
    'padding-inline-start:max(var(--container-padding-inline-start,0px),var(--_item-inset-inline))',
    'padding-inline-end:max(var(--container-padding-inline-end,0px),var(--_item-inset-inline))',
  ];

  function renderEdge(props: Partial<React.ComponentProps<typeof List>>) {
    const {container} = render(
      <List header={<span>Items</span>} {...props}>
        <ListItem label="Static" />
        <ListItem label="Button" onClick={() => {}} />
        <ListItem label="Link" href="/docs" />
      </List>,
    );
    const ul = container.querySelector('ul')!;
    return {
      ul,
      header: ul.parentElement!,
      items: [...ul.querySelectorAll('li')],
    };
  }

  it('keeps the row padding and leaves the list and rows in place by default', () => {
    const {ul, items} = renderEdge({});
    for (const item of items) {
      expect(item.className).not.toMatch(/edge(Flush|Outset|Bleed)/);
      expect(insetDeclarations(item)).toHaveLength(1);
      expect(insetDeclarations(item)[0]).not.toMatch(ZERO_INSET);
    }
    expect(ul.className).not.toContain('reachesContainerPadding');
    expect(edgeContext(ul)).toBe('padded');
  });

  /** The edge each row resolved, read from the row's own edge class. */
  function edgeContext(ul: Element): string {
    const edges = [...ul.querySelectorAll('li')].map(li => {
      const match = /edge(Flush|Outset|Bleed)/.exec(li.className);
      return match ? match[1].toLowerCase() : 'padded';
    });
    expect(new Set(edges).size).toBe(1);
    return edges[0];
  }

  it('applies one treatment to every row, static or interactive, and never to the header', () => {
    for (const edge of ['flush', 'outset', 'bleed'] as const) {
      const {ul, header, items} = renderEdge({edge});
      expect(items).toHaveLength(3);
      expect(edgeContext(ul)).toBe(edge);
      expect(header.className).not.toMatch(/edge|reachesContainerPadding/);
      cleanup();
    }
  });

  it('flush: zeroes the shared inset at every density and leaves the list in place', () => {
    for (const density of ['compact', 'balanced', 'spacious'] as const) {
      const {ul, items} = renderEdge({edge: 'flush', density});
      expect(ul.className).not.toContain('reachesContainerPadding');
      for (const item of items) {
        expect(item).toHaveAttribute('data-density', density);
        const insets = insetDeclarations(item);
        expect(insets).toHaveLength(1);
        expect(insets[0]).toMatch(ZERO_INSET);
      }
      cleanup();
    }
  });

  it('outset: the list reaches the container padding and each row steps back in by what its inset does not fill, per edge', () => {
    // Each edge reads its own container padding var: one var on both edges
    // over-reaches the other edge under asymmetric padding (16px start /
    // 4px end), so a selected row would paint past the outer border.
    const {ul, items} = renderEdge({edge: 'outset'});
    const listCss = declarationsFor(ul);
    for (const declaration of LIST_REACH) {
      expect(listCss).toContain(declaration);
    }
    for (const item of items) {
      const css = declarationsFor(item);
      for (const declaration of OUTSET_ROW) {
        expect(css).toContain(declaration);
      }
      expect(css).not.toContain(
        'margin-inline-end:max(var(--container-padding-inline-start',
      );
      expect(insetDeclarations(item)[0]).not.toMatch(ZERO_INSET);
    }
  });

  it('bleed: the list reaches the container padding and rows fill it with text on the padding line, per edge', () => {
    const {ul, items} = renderEdge({edge: 'bleed'});
    const listCss = declarationsFor(ul);
    for (const declaration of LIST_REACH) {
      expect(listCss).toContain(declaration);
    }
    for (const item of items) {
      const css = declarationsFor(item);
      for (const declaration of BLEED_ROW) {
        expect(css).toContain(declaration);
      }
      expect(css).toContain('border-radius:0');
      expect(css).not.toMatch(/margin-inline-(start|end):max/);
    }
  });

  it('keeps the inline clip on the list for every treatment', () => {
    for (const edge of ['padded', 'flush', 'outset', 'bleed'] as const) {
      const {ul} = renderEdge({edge});
      expect(declarationsFor(ul)).toContain('overflow-x:clip');
      cleanup();
    }
  });

  it('treats the deprecated edgeCompensation="inline" as edge="outset" without a runtime warning', () => {
    // Plain use is reported statically by the @deprecated type; rendering
    // never warns merely because the old name is used (spec:AST-017 FR29a).
    const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
    const {ul} = renderEdge({edgeCompensation: 'inline'});
    expect(edgeContext(ul)).toBe('outset');
    expect(ul.className).toContain('reachesContainerPadding');
    expect(warn).not.toHaveBeenCalled();
    warn.mockRestore();
  });

  it('lets edge win over the deprecated edgeCompensation and warns about the conflict', () => {
    const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
    const {ul} = renderEdge({edge: 'flush', edgeCompensation: 'inline'});
    expect(edgeContext(ul)).toBe('flush');
    expect(ul.className).not.toContain('reachesContainerPadding');
    expect(warn).toHaveBeenCalledTimes(1);
    const message = String(warn.mock.calls[0][0]);
    expect(message).toContain('`edge` wins');
    expect(message).toContain('astryx upgrade');
    warn.mockRestore();
  });

  it('keeps the inset of a ListItem outside a List', () => {
    const {container} = render(<ListItem label="Standalone" />);
    expect(container.querySelector('li')!.className).not.toMatch(
      /edge(Flush|Outset|Bleed)/,
    );
  });
  // ===========================================================================
  // Dividers
  // ===========================================================================

  it('renders dividers between items when hasDividers is true', () => {
    const {container} = render(
      <List hasDividers>
        <ListItem label="Item 1" />
        <ListItem label="Item 2" />
        <ListItem label="Item 3" />
      </List>,
    );
    // Dividers are rendered as borders on <li> elements, not separate DOM nodes
    const items = container.querySelectorAll('li');
    expect(items).toHaveLength(3);
    // No <hr> elements should exist
    const hrs = container.querySelectorAll('hr');
    expect(hrs).toHaveLength(0);
  });

  it('does not add extra DOM elements for dividers', () => {
    const {container} = render(
      <List hasDividers>
        <ListItem label="Item 1" />
        <ListItem label="Item 2" />
      </List>,
    );
    const list = container.querySelector('ul');
    // Only <li> children — no <hr> or other divider elements
    const children = list?.children;
    expect(children).toHaveLength(2);
    expect(children?.[0]?.tagName).toBe('LI');
    expect(children?.[1]?.tagName).toBe('LI');
  });

  it('does not render dividers when hasDividers is false', () => {
    const {container} = render(
      <List>
        <ListItem label="Item 1" />
        <ListItem label="Item 2" />
      </List>,
    );
    const hrs = container.querySelectorAll('hr');
    expect(hrs).toHaveLength(0);
  });

  // ===========================================================================
  // Touch hit area
  // ===========================================================================

  /** The rules among `rules` whose selector reaches the row's `::after`. */
  const afterRules = (rules: string[]): string[] =>
    rules.filter(rule => rule.slice(0, rule.indexOf('{')).includes('::after'));

  it('gives an interactive, enabled row an invisible hit layer under a finger only', () => {
    render(
      <List>
        <ListItem label="Pressable" onClick={() => {}} />
        <ListItem label="Link" href="#settings" />
        <ListItem label="Read-only" />
        <ListItem label="Disabled" onClick={() => {}} isDisabled />
      </List>,
    );
    const row = (text: string) => screen.getByText(text).closest('li')!;
    for (const text of ['Pressable', 'Link']) {
      const {touch, other} = touchGatedRules(row(text));
      const layer = afterRules(touch).join('\n');
      // Positioned past the row by the measured insets, clipped to the band
      // outside the row's own box, and painting nothing.
      expect(layer).toContain('position: absolute');
      expect(layer).toMatch(/clip-path: polygon\(evenodd/);
      // One inset per side, in physical order: top, right, bottom, left.
      const offset = (side: keyof typeof HIT_INSET_PROPERTIES) =>
        `calc\\(\\(var\\(${HIT_INSET_PROPERTIES[side]}, ?0px\\) \\+ var\\(--_hit-border-${side}, ?0px\\)\\) \\* -1\\)`;
      expect(layer).toMatch(
        new RegExp(
          `inset: ${offset('top')} ${offset('right')} ${offset('bottom')} ${offset('left')}`,
        ),
      );
      // Above the rows after it, so a later row does not hit-test over the
      // band; painting nothing.
      expect(layer).toMatch(/z-index: 1/);
      expect(layer).not.toMatch(
        /[{;]\s*(?:background|border|box-shadow|outline)[\w-]*\s*:/,
      );
      // The row itself takes no z-index: it stays no stacking context.
      expect(
        touch.filter(
          rule =>
            !rule.slice(0, rule.indexOf('{')).includes('::') &&
            rule.includes('z-index'),
        ),
      ).toEqual([]);
      // At rest the row's stacking stays as it was: a rule that isolates the
      // row is keyed on a press.
      for (const rule of touch.filter(r => r.includes('isolation'))) {
        expect(rule.slice(0, rule.indexOf('{'))).toContain(
          '[data-astryx-press',
        );
      }
      // With a mouse: no pseudo-element.
      expect(afterRules(other)).toEqual([]);
    }
    // A row with nothing to press offers no target.
    for (const text of ['Read-only', 'Disabled']) {
      expect(afterRules(touchGatedRules(row(text)).touch)).toEqual([]);
    }
  });

  // ===========================================================================
  // Interactive items — onClick (invisible button pattern)
  // ===========================================================================

  it('renders an invisible button when onClick is provided', () => {
    const onClick = vi.fn();
    const {container} = render(
      <List>
        <ListItem label="Clickable" onClick={onClick} />
      </List>,
    );
    const button = container.querySelector('button');
    expect(button).toBeInTheDocument();
    expect(button?.textContent).toContain('Clickable');
  });

  it('fires onClick when invisible button is clicked', async () => {
    const user = userEvent.setup();
    const onClick = vi.fn();
    render(
      <List>
        <ListItem label="Clickable" onClick={onClick} />
      </List>,
    );
    await user.click(screen.getByRole('button'));
    expect(onClick).toHaveBeenCalledTimes(1);
  });

  it('fires onClick when container area is clicked', async () => {
    const user = userEvent.setup();
    const onClick = vi.fn();
    render(
      <List>
        <ListItem
          label="Clickable"
          onClick={onClick}
          data-testid="item"
          startContent={<span data-testid="start">★</span>}
        />
      </List>,
    );
    // Click on startContent (non-interactive, should propagate)
    await user.click(screen.getByTestId('start'));
    expect(onClick).toHaveBeenCalledTimes(1);
  });

  it('does not fire item onClick when endContent interactive element is clicked', async () => {
    const user = userEvent.setup();
    const itemClick = vi.fn();
    const buttonClick = vi.fn();
    render(
      <List>
        <ListItem
          label="Item"
          onClick={itemClick}
          endContent={
            <button type="button" onClick={buttonClick}>
              Action
            </button>
          }
        />
      </List>,
    );
    await user.click(screen.getByText('Action'));
    expect(buttonClick).toHaveBeenCalledTimes(1);
    expect(itemClick).not.toHaveBeenCalled();
  });

  it('invisible button is focusable via keyboard', async () => {
    const user = userEvent.setup();
    const onClick = vi.fn();
    render(
      <List>
        <ListItem label="Focusable" onClick={onClick} />
      </List>,
    );
    await user.tab();
    expect(screen.getByRole('button')).toHaveFocus();
  });

  it('invisible button can be activated via keyboard', async () => {
    const user = userEvent.setup();
    const onClick = vi.fn();
    render(
      <List>
        <ListItem label="Pressable" onClick={onClick} />
      </List>,
    );
    await user.tab();
    await user.keyboard('{Enter}');
    expect(onClick).toHaveBeenCalledTimes(1);
  });

  it('does not render nested buttons — only one invisible button', () => {
    const {container} = render(
      <List>
        <ListItem label="Item" onClick={() => {}} />
      </List>,
    );
    const buttons = container.querySelectorAll('li button');
    // Should be exactly 1 invisible button (no nesting)
    expect(buttons).toHaveLength(1);
  });

  // ===========================================================================
  // Interactive items — href (invisible anchor pattern)
  // ===========================================================================

  it('renders an invisible anchor when href is provided', () => {
    const {container} = render(
      <List>
        <ListItem label="Link" href="/docs" />
      </List>,
    );
    const anchor = container.querySelector('a');
    expect(anchor).toBeInTheDocument();
    expect(anchor).toHaveAttribute('href', '/docs');
    expect(anchor?.textContent).toContain('Link');
  });

  it('sets target on anchor when provided', () => {
    const {container} = render(
      <List>
        <ListItem label="External" href="https://example.com" target="_blank" />
      </List>,
    );
    const anchor = container.querySelector('a');
    expect(anchor).toHaveAttribute('target', '_blank');
    expect(anchor).toHaveAttribute('rel', 'noopener noreferrer');
  });

  it('does not render button or anchor for static items', () => {
    const {container} = render(
      <List>
        <ListItem label="Static" />
      </List>,
    );
    expect(container.querySelector('button')).not.toBeInTheDocument();
    expect(container.querySelector('a')).not.toBeInTheDocument();
  });

  // ===========================================================================
  // Disabled state
  // ===========================================================================

  it('applies aria-disabled when isDisabled', () => {
    const {container} = render(
      <List>
        <ListItem label="Disabled" isDisabled />
      </List>,
    );
    const item = container.querySelector('.astryx-item');
    expect(item).toHaveAttribute('aria-disabled', 'true');
  });

  it('disables the invisible button when isDisabled', () => {
    const {container} = render(
      <List>
        <ListItem label="Disabled" onClick={() => {}} isDisabled />
      </List>,
    );
    const button = container.querySelector('button');
    expect(button).toBeDisabled();
  });

  it('does not fire onClick when disabled item is clicked', async () => {
    const onClick = vi.fn();
    const {container} = render(
      <List>
        <ListItem label="Disabled" onClick={onClick} isDisabled />
      </List>,
    );
    // pointerEvents: none prevents click, but let's verify the handler guards
    const li = container.querySelector('li');
    // Manually dispatch click (bypassing pointer-events)
    li?.dispatchEvent(new MouseEvent('click', {bubbles: true}));
    expect(onClick).not.toHaveBeenCalled();
  });

  // ===========================================================================
  // Selected state
  // ===========================================================================

  it('conveys selection via aria-current when isSelected', () => {
    // aria-selected is not permitted on an li (role listitem, axe:
    // aria-allowed-attr), so selection is exposed via aria-current — valid on
    // any element — so screen-reader users are still told which item is chosen.
    const {container} = render(
      <List>
        <ListItem label="Selected" isSelected onClick={() => {}} />
      </List>,
    );
    const item = container.querySelector('.astryx-item');
    expect(item).not.toHaveAttribute('aria-selected');
    expect(item).toHaveAttribute('aria-current', 'true');
  });

  it('applies neither aria-selected nor aria-current when not selected', () => {
    const {container} = render(
      <List>
        <ListItem label="Not Selected" />
      </List>,
    );
    const li = container.querySelector('li');
    expect(li).not.toHaveAttribute('aria-selected');
    expect(li).not.toHaveAttribute('aria-current');
  });

  // ===========================================================================
  // startContent and endContent
  // ===========================================================================

  it('renders startContent before label', () => {
    render(
      <List>
        <ListItem
          label="With Icon"
          startContent={<span data-testid="icon">★</span>}
        />
      </List>,
    );
    expect(screen.getByTestId('icon')).toBeInTheDocument();
  });

  it('renders endContent after label', () => {
    render(
      <List>
        <ListItem
          label="With Badge"
          endContent={<span data-testid="badge">3</span>}
        />
      </List>,
    );
    expect(screen.getByTestId('badge')).toBeInTheDocument();
  });

  it('startContent and endContent are siblings to invisible button', () => {
    const {container} = render(
      <List>
        <ListItem
          label="Item"
          onClick={() => {}}
          startContent={<span data-testid="start">★</span>}
          endContent={<span data-testid="end">→</span>}
        />
      </List>,
    );
    const button = container.querySelector('button');
    const li = container.querySelector('li');
    // startContent and endContent should be children of li, not inside button
    expect(li?.querySelector('[data-testid="start"]')).toBeInTheDocument();
    expect(li?.querySelector('[data-testid="end"]')).toBeInTheDocument();
    expect(
      button?.querySelector('[data-testid="start"]'),
    ).not.toBeInTheDocument();
    expect(
      button?.querySelector('[data-testid="end"]'),
    ).not.toBeInTheDocument();
  });

  // ===========================================================================
  // Border radius
  // ===========================================================================

  it('applies content radius by default', () => {
    render(
      <List>
        <ListItem label="Item" data-testid="item" isSelected />
      </List>,
    );
    const item = screen.getByTestId('item');
    expect(item).toBeInTheDocument();
  });

  it('removes radius when hasDividers is true', () => {
    render(
      <List hasDividers>
        <ListItem label="Item" data-testid="item" isSelected />
      </List>,
    );
    const item = screen.getByTestId('item');
    expect(item).toBeInTheDocument();
  });

  // ===========================================================================
  // List markers
  // ===========================================================================

  it('renders list markers for disc style', () => {
    render(
      <List listStyle="disc">
        <ListItem label="Bullet item" data-testid="item" />
      </List>,
    );
    const item = screen.getByTestId('item');
    // Custom marker rendered as a span (dot marker container)
    const markerContainer = item.querySelector(':scope > span:first-child');
    expect(markerContainer).toBeInTheDocument();
    // The dot itself is a nested span
    const dot = markerContainer?.querySelector('span');
    expect(dot).toBeInTheDocument();
  });

  it('renders list markers for decimal style', () => {
    render(
      <List listStyle="decimal">
        <ListItem label="Numbered item" data-testid="item" />
      </List>,
    );
    const item = screen.getByTestId('item');
    // Number marker uses CSS counter via ::before pseudo-element
    const marker = item.querySelector(':scope > span:first-child');
    expect(marker).toBeInTheDocument();
  });

  it('does not render markers when listStyle is none', () => {
    render(
      <List listStyle="disc">
        <ListItem label="With marker" data-testid="with-marker" />
      </List>,
    );
    const withMarker = screen.getByTestId('with-marker');
    const markerCount = withMarker.children.length;

    render(
      <List listStyle="none">
        <ListItem label="Plain item" data-testid="no-marker" />
      </List>,
    );
    const noMarker = screen.getByTestId('no-marker');
    // Without markers, the item should have fewer direct children
    // (no marker container element)
    expect(noMarker.children.length).toBeLessThan(markerCount);
  });

  // ===========================================================================
  // Description rendering
  // ===========================================================================

  it('does not render description when not provided', () => {
    render(
      <List>
        <ListItem label="Label Only" />
      </List>,
    );
    // Should have the label span only (plus possibly wrapper spans)
    expect(screen.getByText('Label Only')).toBeInTheDocument();
    expect(screen.queryByText('undefined')).not.toBeInTheDocument();
  });

  // ===========================================================================
  // ReactNode description
  // ===========================================================================

  it('accepts ReactNode as description', () => {
    render(
      <List>
        <ListItem
          label="Item"
          description={
            <div>
              <span>Rich</span> <span>description</span>
            </div>
          }
        />
      </List>,
    );
    expect(screen.getByText('Rich')).toBeInTheDocument();
    expect(screen.getByText('description')).toBeInTheDocument();
  });

  it('still accepts string description', () => {
    render(
      <List>
        <ListItem label="Item" description="Simple text" />
      </List>,
    );
    expect(screen.getByText('Simple text')).toBeInTheDocument();
  });

  it('forwards data and aria attributes onto the list element', () => {
    // BaseProps keeps data-*/aria-*; the list element dropped them.
    const {container} = render(
      <List listStyle="decimal" data-delimiter=")" aria-label="Steps">
        <ListItem label="First" />
      </List>,
    );
    const list = container.querySelector('ol')!;
    expect(list.getAttribute('data-delimiter')).toBe(')');
    expect(list.getAttribute('aria-label')).toBe('Steps');
  });

  it('keeps an aria-labelledby pointing outside the component', () => {
    // With no header of its own there is nothing to associate, so the
    // consumer's label must survive.
    const {container} = render(
      <List aria-labelledby="external-heading">
        <ListItem label="First" />
      </List>,
    );
    expect(container.querySelector('ul')!.getAttribute('aria-labelledby')).toBe(
      'external-heading',
    );
  });

  it('keeps its own list role and header association', () => {
    // The rest spread comes first so a consumer prop cannot drop the
    // Safari/VoiceOver role workaround or the generated header association.
    const {container} = render(
      <List header="Steps" role="presentation" aria-labelledby="elsewhere">
        <ListItem label="First" />
      </List>,
    );
    const list = container.querySelector('ul')!;
    expect(list.getAttribute('role')).toBe('list');
    expect(list.getAttribute('aria-labelledby')).not.toBe('elsewhere');
  });

  it('accepts number as description (ReactNode)', () => {
    render(
      <List>
        <ListItem label="Count" description={42} />
      </List>,
    );
    expect(screen.getByText('42')).toBeInTheDocument();
  });

  describe('ListMarkerScope (internal, for Markdown nested lists)', () => {
    /** The shape inside the item's marker box. */
    const markerShape = (container: HTMLElement) => {
      // The dot, ring, or square: an empty element in the marker box.
      const shape = container.querySelector('li > span > span:empty');
      return shape == null ? null : getComputedStyle(shape);
    };

    it('draws the list style marker without a scope', () => {
      const {container} = render(
        <List listStyle="disc">
          <ListItem label="Item" />
        </List>,
      );
      expect(markerShape(container)?.borderRadius).toBe('50%');
    });

    it('draws the scope marker in place of the list style', () => {
      const {container} = render(
        <List listStyle="disc">
          <ListMarkerScope marker="square">
            <ListItem label="Item" />
          </ListMarkerScope>
        </List>,
      );
      const shape = markerShape(container);
      expect(shape).not.toBeNull();
      expect(shape?.borderRadius).not.toBe('50%');
      expect(container.querySelector('ul')).not.toBeNull();
    });

    it("draws a task item's read-only checkbox in place of its marker", () => {
      const {container} = render(
        <List listStyle="disc">
          <ListMarkerScope
            marker="disc"
            task={{isChecked: true, label: 'Done'}}>
            <ListItem label="Done" />
          </ListMarkerScope>
          <ListItem label="Plain" />
        </List>,
      );
      const checkbox = screen.getByRole('checkbox', {name: 'Done'});
      expect(checkbox).toBeChecked();
      expect(checkbox).toHaveAttribute('aria-readonly', 'true');
      const [task, plain] = container.querySelectorAll('li');
      expect(task?.contains(checkbox)).toBe(true);
      // The task item has no dot in its marker box; the plain item keeps it.
      expect(task?.querySelector(':scope > span > span:empty')).toBeNull();
      expect(plain?.querySelector(':scope > span > span:empty')).not.toBeNull();
    });

    it('draws no task checkbox in a list without markers', () => {
      render(
        <List>
          <ListMarkerScope
            marker="disc"
            task={{isChecked: true, label: 'Done'}}>
            <ListItem label="Done" />
          </ListMarkerScope>
        </List>,
      );
      expect(screen.queryByRole('checkbox')).toBeNull();
    });

    it('keeps a numbered list ordered with a letter marker', () => {
      render(
        <List listStyle="decimal" start={3}>
          <ListMarkerScope marker="lower-alpha">
            <ListItem label="Item" />
          </ListMarkerScope>
        </List>,
      );
      const list = screen.getByRole('list');
      expect(list.tagName).toBe('OL');
      expect(list).toHaveAttribute('start', '3');
    });

    it('draws no marker in a list without markers, or outside a list', () => {
      const {container} = render(
        <>
          <List>
            <ListMarkerScope marker="square">
              <ListItem label="In a plain list" />
            </ListMarkerScope>
          </List>
          <ListMarkerScope marker="square">
            <span>Outside a list</span>
          </ListMarkerScope>
        </>,
      );
      expect(markerShape(container)).toBeNull();
      expect(screen.getByText('Outside a list')).toBeInTheDocument();
    });
  });
});

/** A row whose press goes to a control inside it (`interactiveRef`), with swipe actions. */
function DelegateSwipeRow() {
  const ref = useRef<HTMLButtonElement>(null);
  return (
    <ListItem
      label="Delegate"
      interactiveRef={ref}
      endContent={
        <button ref={ref} type="button">
          Open
        </button>
      }
      swipeActions={{trailing: [{label: 'Archive', onActivate: () => {}}]}}
    />
  );
}

describe('List and swipe actions', () => {
  it('clips the rows in the inline axis with clip, never hidden, so a row dragged aside paints no further than the list', () => {
    render(
      <List>
        <ListItem label="A" />
      </List>,
    );
    const rules = rulesDeclaredFor(screen.getByRole('list'));
    // Declared as `overflow-inline`; StyleX emits the physical longhand of
    // the same axis in horizontal writing modes.
    expect(rules.some(r => /overflow-(inline|x): clip/.test(r))).toBe(true);
    expect(rules.some(r => /overflow[-a-z]*: hidden/.test(r))).toBe(false);
  });

  it('under a finger, isolates its rows, so what rises inside the list stays below a sticky header; with a mouse it keeps its stacking', () => {
    render(
      <List>
        <ListItem label="A" onClick={() => {}} />
      </List>,
    );
    const {touch, other} = touchGatedRules(screen.getByRole('list'));
    // Under a finger the list is the isolation boundary for its rows'
    // z-index. So a page-level sticky header at z-index 1 stays above every
    // part of the list.
    expect(touch.join('\n')).toMatch(/isolation: isolate/);
    // With a mouse nothing rises, so the list is no stacking context.
    expect(other.filter(rule => rule.includes('isolation'))).toEqual([]);
  });

  it('isolates for every pointer under an animatedLayout handle, since a sliding row rides above its neighbors with a mouse too', () => {
    function Animated() {
      const containerRef = useRef<HTMLDivElement | null>(null);
      const animatedLayout = useAnimatedLayout({containerRef});
      return (
        <div ref={containerRef}>
          <List animatedLayout={animatedLayout}>
            <ListItem label="A" itemKey="a" onClick={() => {}} />
          </List>
        </div>
      );
    }
    render(<Animated />);
    const {other} = touchGatedRules(screen.getByRole('list'));
    expect(other.join('\n')).toMatch(/isolation: isolate/);
  });

  it('under a finger, raises a swipeable interactive row above the rows after it: it is a stacking context, so its touch band’s own z-index orders only inside it', () => {
    render(
      <List>
        <ListItem
          label="Swipeable"
          onClick={() => {}}
          swipeActions={{trailing: [{label: 'Archive', onActivate: () => {}}]}}
        />
        <ListItem label="Pressable" onClick={() => {}} />
        <ListItem
          label="Static"
          swipeActions={{trailing: [{label: 'Archive', onActivate: () => {}}]}}
        />
        <ListItem
          label="Empty sides"
          onClick={() => {}}
          swipeActions={{leading: [], trailing: []}}
        />
        <DelegateSwipeRow />
      </List>,
    );
    const row = (text: string) => screen.getByText(text).closest('li')!;
    const rowZ = (el: Element) => {
      const {touch, other} = touchGatedRules(el);
      const own = (rules: string[]) =>
        rules.filter(
          rule =>
            !rule.slice(0, rule.indexOf('{')).includes('::') &&
            rule.includes('z-index:'),
        );
      return {touch: own(touch), other: own(other)};
    };
    const swipeable = rowZ(row('Swipeable'));
    expect(swipeable.touch.join('\n')).toMatch(/z-index: 1/);
    // With a mouse there is no band: the row's only z-index is an update's
    // travelling raise, while it slides across other rows.
    for (const rule of swipeable.other) {
      expect(rule.slice(0, rule.indexOf('{'))).toContain(
        '[data-astryx-travelling]',
      );
    }
    // A row that is no stacking context needs no raise (its band's own
    // z-index orders it), and a swipeable row with no band gets none.
    expect(rowZ(row('Pressable')).touch).toEqual([]);
    expect(rowZ(row('Static')).touch).toEqual([]);
    // Item serves no swipe actions on a row with no entry on either side. Nor
    // does it on a row whose press goes to a control inside it. Neither row is
    // a stacking context, so neither is raised.
    expect(rowZ(row('Empty sides')).touch).toEqual([]);
    expect(rowZ(row('Delegate')).touch).toEqual([]);
  });

  it('raises nothing in a ListItem outside a List, where nothing isolates it: its touch band and a swipeable row take no z-index', () => {
    render(
      <ul>
        <ListItem
          label="Outside"
          onClick={() => {}}
          swipeActions={{trailing: [{label: 'Archive', onActivate: () => {}}]}}
        />
      </ul>,
    );
    const {touch} = touchGatedRules(screen.getByText('Outside').closest('li')!);
    // It keeps its touch target, the band past its box.
    expect(
      touch
        .filter(rule => rule.slice(0, rule.indexOf('{')).includes('::after'))
        .join('\n'),
    ).toContain('position: absolute');
    // But nothing it draws rises: not the band, not the row. A rule keyed on
    // a press is left out, since it orders layers only inside the pressed row.
    expect(
      touch.filter(
        rule =>
          rule.includes('z-index') &&
          !rule.slice(0, rule.indexOf('{')).includes('[data-astryx-press'),
      ),
    ).toEqual([]);
  });

  it('passes swipeActions and swipeBehavior through to the row unchanged', async () => {
    render(
      <List>
        <ListItem
          label="A"
          data-testid="row"
          swipeBehavior="commit"
          swipeActions={{trailing: [{label: 'Archive', onActivate: () => {}}]}}
        />
      </List>,
    );
    const row = screen.getByTestId('row');
    expect(row.tagName).toBe('LI');
    expect(row.parentElement).toBe(screen.getByRole('list'));
    // The panel arrives with the lazily loaded swipe layer.
    await swipeLayerLoaded();
    const panel = row.querySelector('[data-swipe-panel="trailing"]');
    expect(panel).not.toBeNull();
    // Commit: presentational.
    expect(panel).toHaveAttribute('aria-hidden', 'true');
  });
});