Skip to content

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

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

/**
 * @file ListInput.test.tsx
 * @input Uses Vitest, Testing Library, and the controlled ListInput API
 * @output Behavioral coverage for list editing, pointer-stable adding,
 *   tokenized mutation motion, validation, focus, and reordering. Reordering
 *   goes through core List's reorder handle at each record's end, with keys
 *   here. The handle is the one element it adds to a record, and it comes
 *   with the owner's object. The a11y Chromium specs cover it in a real
 *   browser
 * @position Lab tests; validates ListInput.tsx
 *
 * SYNC: When ListInput.tsx behavior changes, update these tests.
 */

import {readFileSync} from 'node:fs';
import path from 'node:path';
import {afterEach, describe, expect, it, vi} from 'vitest';
import {useMemo, useState} from 'react';
import userEvent from '@testing-library/user-event';
import {createReorderable} from '@astryxdesign/core';
import {
  fireEvent,
  render,
  renderHook,
  screen,
  waitFor,
  within,
} from '@testing-library/react';
import {useAnnounce, useContainerReveal} from '@astryxdesign/core/hooks';
import {TextInput} from '@astryxdesign/core/TextInput';
import {
  ListInput,
  type ListInputColumn,
  type ListInputProps,
} from './ListInput';

type Guest = {
  id: string;
  name: string;
};

const guests: Guest[] = [
  {id: 'ada', name: 'Ada'},
  {id: 'grace', name: 'Grace'},
];

const createdGuest: Guest = {id: 'linus', name: 'Linus'};

const columns = [
  {
    key: 'name',
    header: 'Name',
    renderInput: ({
      item,
      label,
      isLabelHidden,
      status,
      statusVariant,
      isDisabled,
      isLoading,
      updateItem,
    }) => (
      <label>
        <span hidden={isLabelHidden}>{label}</span>
        <input
          aria-invalid={status?.type === 'error' || undefined}
          aria-label={label}
          data-label-hidden={String(isLabelHidden)}
          data-status-type={status?.type}
          data-status-message={status?.message}
          data-status-variant={statusVariant}
          disabled={isDisabled || isLoading}
          value={item.name}
          onChange={event =>
            updateItem({...item, name: event.currentTarget.value}, 'name')
          }
        />
      </label>
    ),
  },
] satisfies ListInputColumn<Guest>[];

const nativeStatusColumns = [
  {
    key: 'name',
    header: 'Name',
    renderInput: ({
      item,
      label,
      isLabelHidden,
      status,
      statusVariant,
      isDisabled,
      isLoading,
      updateItem,
    }) => (
      <TextInput
        label={label}
        isLabelHidden={isLabelHidden}
        value={item.name}
        status={status}
        statusVariant={statusVariant}
        isDisabled={isDisabled}
        isLoading={isLoading}
        onChange={name => updateItem({...item, name}, 'name')}
      />
    ),
  },
] satisfies ListInputColumn<Guest>[];

function renderListInput(overrides: Partial<ListInputProps<Guest>> = {}) {
  const props: ListInputProps<Guest> = {
    label: 'Guests',
    itemName: 'guest',
    value: guests,
    onChange: () => {},
    getItemKey: guest => guest.id,
    createItem: () => createdGuest,
    columns,
    ...overrides,
  };

  return render(<ListInput<Guest> {...props} />);
}

/** A reorderable object whose moves go to `onReorder` and nowhere else. */
function reorderableFor(
  onReorder: (move: {key: string | number; to: number}) => void = () => {},
) {
  return createReorderable({onReorder});
}

/**
 * A reorderable ListInput whose owner applies each move it is handed to its
 * value, as an app does.
 */
function OwnedList({
  onReorder,
  isReorderable,
  ...props
}: Partial<ListInputProps<Guest>> & {
  onReorder?: (move: {key: string | number; to: number}) => void;
  isReorderable?: (key: string | number) => boolean;
}) {
  const [value, setValue] = useState(props.value ?? guests);
  const reorderable = useMemo(
    () =>
      createReorderable({
        onReorder: move => {
          onReorder?.(move);
          setValue(current => {
            const moved = current.find(guest => guest.id === move.key);
            if (moved == null) {
              return current;
            }
            const rest = current.filter(guest => guest !== moved);
            return [...rest.slice(0, move.to), moved, ...rest.slice(move.to)];
          });
        },
        isReorderable,
      }),
    [onReorder, isReorderable],
  );
  return (
    <ListInput<Guest>
      label="Guests"
      itemName="guest"
      getItemKey={guest => guest.id}
      createItem={() => createdGuest}
      columns={columns}
      reorderable={reorderable}
      {...props}
      value={value}
      onChange={(nextValue, change) => {
        props.onChange?.(nextValue, change);
        setValue(nextValue);
      }}
    />
  );
}

const isNotAda = (key: string | number) => key !== 'ada';

const HINT =
  'Drag to move this item, or press Space or Enter, then the arrow keys to move it one place at a time. Press Escape when you are done.';

const shownNames = () =>
  screen
    .getAllByRole('textbox')
    .map(input => (input as HTMLInputElement).value);

function classTokens(element: Element | null): string[] {
  return element?.getAttribute('class')?.split(/\s+/).filter(Boolean) ?? [];
}

// The reveal is CSS-only, so jsdom can only prove the wiring: each element
// carries the classes the hook hands out for its role. The browser proves the
// pixels (Storybook).
function revealClasses() {
  const {result} = renderHook(() => useContainerReveal());
  const reveal = result.current;
  const tokensOf = (props: {className?: string}) =>
    props.className?.split(/\s+/).filter(Boolean) ?? [];
  const container = tokensOf(reveal.getContainerProps());
  const grip = tokensOf(
    reveal.getContentRevealProps({isLayoutPreserved: true}),
  );
  const containerInactive = tokensOf(
    reveal.getContainerProps({forceState: 'inactive'}),
  );
  const gripShown = tokensOf(
    reveal.getContentRevealProps({
      isLayoutPreserved: true,
      forceVisibility: 'shown',
    }),
  );
  return {
    container,
    grip,
    onlyInactive: containerInactive.filter(token => !container.includes(token)),
    onlyShown: gripShown.filter(token => !grip.includes(token)),
  };
}

const originalAnimateDescriptor = Object.getOwnPropertyDescriptor(
  HTMLElement.prototype,
  'animate',
);
const originalScrollIntoViewDescriptor = Object.getOwnPropertyDescriptor(
  HTMLElement.prototype,
  'scrollIntoView',
);

function createRect(top: number): DOMRect {
  return {
    x: 0,
    y: top,
    top,
    right: 400,
    bottom: top + 40,
    left: 0,
    width: 400,
    height: 40,
    toJSON: () => {},
  };
}

function mockMutationAnimations(events: string[] = []) {
  const animate = vi.fn(function (
    this: HTMLElement,
    _keyframes: Keyframe[],
    _options?: number | KeyframeAnimationOptions,
  ) {
    events.push('animate');
    return {
      cancel: vi.fn(),
      finished: new Promise(() => {}),
    } as unknown as Animation;
  });
  Object.defineProperty(HTMLElement.prototype, 'animate', {
    configurable: true,
    value: animate,
  });
  vi.spyOn(HTMLElement.prototype, 'getBoundingClientRect').mockImplementation(
    function (this: HTMLElement) {
      if (this.dataset.listInputMotionKey == null) {
        return createRect(0);
      }
      const group = this.closest('[role="group"]');
      const motionElements = Array.from(
        group?.querySelectorAll<HTMLElement>('[data-list-input-motion-key]') ??
          [],
      ).filter(candidate => candidate.closest('[role="group"]') === group);
      return createRect(Math.max(0, motionElements.indexOf(this)) * 40);
    },
  );
  return animate;
}

afterEach(() => {
  vi.restoreAllMocks();
  // The shared live regions outlive each test, and a test that stubs
  // requestAnimationFrame can strand an announcement's frame. An empty
  // announcement clears what is still waiting, so it is not joined into the
  // next test's announcements (spec:AST-086 FR9).
  const announcer = renderHook(() => useAnnounce());
  announcer.result.current('');
  announcer.unmount();
  if (originalAnimateDescriptor == null) {
    Reflect.deleteProperty(HTMLElement.prototype, 'animate');
  } else {
    Object.defineProperty(
      HTMLElement.prototype,
      'animate',
      originalAnimateDescriptor,
    );
  }
  if (originalScrollIntoViewDescriptor == null) {
    Reflect.deleteProperty(HTMLElement.prototype, 'scrollIntoView');
  } else {
    Object.defineProperty(
      HTMLElement.prototype,
      'scrollIntoView',
      originalScrollIntoViewDescriptor,
    );
  }
});

describe('ListInput', () => {
  it('uses list semantics and shows field labels only on the first record', () => {
    renderListInput();

    expect(screen.queryByRole('table')).not.toBeInTheDocument();
    expect(screen.queryByRole('columnheader')).not.toBeInTheDocument();
    expect(screen.getByRole('list')).toBeInTheDocument();

    const inputs = screen.getAllByRole('textbox');
    expect(inputs[0]).toHaveAttribute('data-label-hidden', 'true');
    expect(inputs[0]).toHaveAccessibleName('Name');
    expect(inputs[1]).toHaveAttribute('data-label-hidden', 'true');
    expect(inputs[1]).toHaveAccessibleName('Name, guest 2 of 2');
    expect(inputs[0]).toHaveAttribute('data-status-variant', 'tooltip');
    const primaryLabel = document.querySelector(
      '[data-list-input-column-label="primary"]',
    );
    const responsiveLabel = document.querySelector(
      '[data-list-input-column-label="responsive"]',
    );
    expect(primaryLabel).toHaveTextContent('Name');
    expect(primaryLabel).toHaveAttribute('aria-hidden', 'true');
    expect(responsiveLabel).toHaveTextContent('Name');
    expect(responsiveLabel).toHaveAttribute('aria-hidden', 'true');
    expect(primaryLabel?.closest('[data-list-input-cell]')).toContainElement(
      inputs[0],
    );
    expect(responsiveLabel?.closest('[data-list-input-cell]')).toContainElement(
      inputs[1],
    );
  });

  it('never renders aria-required on the group, even when isRequired is set (#4958)', () => {
    // aria-required is not an allowed attribute on role="group" (axe
    // aria-allowed-attr, impact critical). The requirement is already
    // surfaced visibly through Field's Required indicator.
    renderListInput({isRequired: true});

    const group = screen.getByRole('group');
    expect(group).not.toHaveAttribute('aria-required');
  });

  it('renders a compact centered EmptyState and keeps Add available', () => {
    const {container} = renderListInput({value: []});

    const emptyState = container.querySelector<HTMLElement>(
      '.astryx-empty-state',
    );
    expect(emptyState).toBeInTheDocument();
    expect(emptyState).toHaveClass('astryx-empty-state');
    expect(emptyState).toHaveAttribute('data-variant', 'compact');
    expect(getComputedStyle(emptyState!).alignItems).toBe('center');
    expect(getComputedStyle(emptyState!).justifyContent).toBe('center');
    expect(getComputedStyle(emptyState!).textAlign).toBe('center');
    expect(
      screen.getByRole('heading', {name: 'No guests yet'}),
    ).toBeInTheDocument();
    expect(screen.getByText('Add a guest to get started.')).toBeInTheDocument();
    expect(screen.getByRole('button', {name: 'Add guest'})).toBeEnabled();
  });

  it('emits add and remove changes with the affected item and index', () => {
    const onChange = vi.fn();
    renderListInput({onChange});

    fireEvent.click(screen.getByRole('button', {name: 'Add guest'}));
    expect(onChange).toHaveBeenCalledWith([...guests, createdGuest], {
      type: 'add',
      item: createdGuest,
      index: 2,
    });

    onChange.mockClear();
    fireEvent.click(screen.getByRole('button', {name: 'Remove guest 1'}));
    expect(onChange).toHaveBeenCalledWith([guests[1]], {
      type: 'remove',
      item: guests[0],
      index: 0,
    });
  });

  it('keeps Add under the pointer in the nearest newly scrollable container', () => {
    function ScrollAnchoredList() {
      const [value, setValue] = useState(guests);
      return (
        <div data-outer-scroll="" style={{height: 240, overflowY: 'auto'}}>
          <div
            data-inner-scroll=""
            style={{
              height: 160,
              overflowY: 'auto',
              scrollBehavior: 'smooth',
            }}>
            <ListInput<Guest>
              label="Guests"
              itemName="guest"
              value={value}
              onChange={setValue}
              getItemKey={guest => guest.id}
              createItem={() => createdGuest}
              columns={columns}
            />
          </div>
        </div>
      );
    }

    const {container} = render(<ScrollAnchoredList />);
    const outerScroll = container.querySelector<HTMLElement>(
      '[data-outer-scroll]',
    )!;
    const innerScroll = container.querySelector<HTMLElement>(
      '[data-inner-scroll]',
    )!;
    Object.defineProperties(outerScroll, {
      clientHeight: {configurable: true, value: 240},
      scrollHeight: {configurable: true, value: 400},
    });
    Object.defineProperties(innerScroll, {
      clientHeight: {configurable: true, value: 160},
      scrollHeight: {
        configurable: true,
        get: () => (screen.getAllByRole('listitem').length >= 3 ? 180 : 160),
      },
    });
    let innerScrollTop = 0;
    Object.defineProperty(innerScroll, 'scrollTop', {
      configurable: true,
      get: () => innerScrollTop,
      set: (nextScrollTop: number) => {
        const maxScrollTop =
          screen.getAllByRole('listitem').length >= 3 ? 20 : 0;
        innerScrollTop = Math.max(0, Math.min(nextScrollTop, maxScrollTop));
      },
    });
    outerScroll.scrollTop = 10;
    const setScrollStyle = vi.spyOn(innerScroll.style, 'setProperty');

    const addButton = screen.getByRole('button', {name: 'Add guest'});
    const addAction = addButton.closest<HTMLElement>(
      '[data-list-input-motion-key="action:add"]',
    )!;
    let anchorFrame: FrameRequestCallback | undefined;
    vi.spyOn(window, 'requestAnimationFrame').mockImplementation(callback => {
      anchorFrame = callback;
      return 1;
    });
    vi.spyOn(addAction, 'getBoundingClientRect').mockImplementation(() =>
      createRect(
        screen.getAllByRole('listitem').length * 40 -
          innerScroll.scrollTop -
          outerScroll.scrollTop,
      ),
    );
    const initialTop = addAction.getBoundingClientRect().top;

    fireEvent.click(addButton, {detail: 1});

    expect(innerScroll.scrollTop).toBe(20);
    expect(outerScroll.scrollTop).toBe(30);
    expect(setScrollStyle).toHaveBeenCalledWith(
      'scroll-behavior',
      'auto',
      'important',
    );
    expect(innerScroll.style.scrollBehavior).toBe('smooth');
    expect(addAction.getBoundingClientRect().top).toBe(initialTop);
    expect(screen.getByDisplayValue('Linus')).toHaveFocus();

    outerScroll.scrollTop = 25;
    expect(addAction.getBoundingClientRect().top).toBe(initialTop + 5);
    anchorFrame?.(0);
    expect(outerScroll.scrollTop).toBe(30);
    expect(addAction.getBoundingClientRect().top).toBe(initialTop);
  });

  it('anchors from pointer down before blur-driven validation changes layout', () => {
    function BlurGrowingList() {
      const [value, setValue] = useState([guests[0]]);
      const [isTouched, setIsTouched] = useState(false);
      const blurColumns = [
        {
          key: 'name',
          header: 'Name',
          renderInput: ({item, label, updateItem}) => (
            <input
              aria-label={label}
              value={item.name}
              onChange={event =>
                updateItem({...item, name: event.currentTarget.value}, 'name')
              }
              onBlur={() => setIsTouched(true)}
            />
          ),
        },
      ] satisfies ListInputColumn<Guest>[];
      return (
        <div data-blur-scroll="" style={{height: 100, overflowY: 'auto'}}>
          <ListInput<Guest>
            label="Guests"
            itemName="guest"
            value={value}
            onChange={setValue}
            getItemKey={guest => guest.id}
            createItem={() => createdGuest}
            columns={blurColumns}
            getItemStatus={guest =>
              isTouched && guest.id === 'ada'
                ? {type: 'error', message: 'Review this guest'}
                : undefined
            }
          />
        </div>
      );
    }

    const {container} = render(<BlurGrowingList />);
    const scrollRoot =
      container.querySelector<HTMLElement>('[data-blur-scroll]')!;
    Object.defineProperties(scrollRoot, {
      clientHeight: {configurable: true, value: 100},
      scrollHeight: {configurable: true, value: 400},
    });
    const addButton = screen.getByRole('button', {name: 'Add guest'});
    const addAction = addButton.closest<HTMLElement>(
      '[data-list-input-motion-key="action:add"]',
    )!;
    vi.spyOn(addAction, 'getBoundingClientRect').mockImplementation(() =>
      createRect(
        screen.getAllByRole('listitem').length * 40 +
          (screen.queryByText('Review this guest') == null ? 0 : 20) -
          scrollRoot.scrollTop,
      ),
    );
    const initialTop = addAction.getBoundingClientRect().top;
    const firstInput = screen.getByDisplayValue('Ada');
    firstInput.focus();

    fireEvent.pointerDown(addButton, {
      button: 0,
      isPrimary: true,
      pointerId: 21,
    });
    fireEvent.blur(firstInput);
    expect(screen.getByText('Review this guest')).toBeInTheDocument();
    expect(addAction.getBoundingClientRect().top).toBe(initialTop + 20);
    fireEvent.click(addButton, {detail: 1});

    expect(scrollRoot.scrollTop).toBe(60);
    expect(addAction.getBoundingClientRect().top).toBe(initialTop);
    expect(screen.getByDisplayValue('Linus')).toHaveFocus();
  });

  it('checks every clipping ancestor before preserving focused-field visibility', () => {
    function NestedClippingList() {
      const [value, setValue] = useState(guests);
      return (
        <div data-outer-clip="" style={{height: 80, overflowY: 'auto'}}>
          <div data-inner-clip="" style={{height: 160, overflowY: 'auto'}}>
            <ListInput<Guest>
              label="Guests"
              itemName="guest"
              value={value}
              onChange={setValue}
              getItemKey={guest => guest.id}
              createItem={() => createdGuest}
              columns={columns}
            />
          </div>
        </div>
      );
    }

    const {container} = render(<NestedClippingList />);
    const outerClip =
      container.querySelector<HTMLElement>('[data-outer-clip]')!;
    const innerClip =
      container.querySelector<HTMLElement>('[data-inner-clip]')!;
    Object.defineProperties(outerClip, {
      clientHeight: {configurable: true, value: 80},
      scrollHeight: {configurable: true, value: 400},
    });
    Object.defineProperties(innerClip, {
      clientHeight: {configurable: true, value: 160},
      scrollHeight: {configurable: true, value: 400},
    });
    vi.spyOn(HTMLElement.prototype, 'getBoundingClientRect').mockImplementation(
      function (this: HTMLElement) {
        return this instanceof HTMLInputElement && this.value === 'Linus'
          ? createRect(100)
          : createRect(0);
      },
    );
    const scrollIntoView = vi.fn();
    Object.defineProperty(HTMLElement.prototype, 'scrollIntoView', {
      configurable: true,
      value: scrollIntoView,
    });

    fireEvent.click(screen.getByRole('button', {name: 'Add guest'}), {
      detail: 1,
    });

    expect(scrollIntoView).toHaveBeenCalledWith({
      block: 'nearest',
      inline: 'nearest',
    });
  });

  it('animates live add and removal reflow after the controlled change', async () => {
    const events: string[] = [];
    const animate = mockMutationAnimations(events);

    function ControlledList() {
      const [value, setValue] = useState(guests);
      return (
        <ListInput<Guest>
          label="Guests"
          itemName="guest"
          value={value}
          onChange={(nextValue, change) => {
            events.push(`change:${change.type}`);
            setValue(nextValue);
          }}
          getItemKey={guest => guest.id}
          createItem={() => createdGuest}
          columns={columns}
        />
      );
    }

    render(<ControlledList />);
    fireEvent.click(screen.getByRole('button', {name: 'Add guest'}));

    expect(events[0]).toBe('change:add');
    expect(screen.getByDisplayValue('Linus')).toHaveFocus();
    expect(screen.getAllByRole('listitem')).toHaveLength(3);
    const addedRow = screen
      .getByDisplayValue('Linus')
      .closest<HTMLElement>('li')!;
    const addedAnimationIndex = animate.mock.contexts.indexOf(addedRow);
    expect(addedAnimationIndex).toBeGreaterThanOrEqual(0);
    expect(animate).toHaveBeenCalledTimes(1);
    expect(animate.mock.calls[addedAnimationIndex]).toEqual([
      [{transform: 'translateY(0.5rem)'}, {transform: 'translateY(0)'}],
      {
        duration: 230,
        easing: 'cubic-bezier(0.24, 1, 0.4, 1)',
      },
    ]);
    await waitFor(() => {
      expect(
        Array.from(document.querySelectorAll('[aria-live="polite"]')).some(
          node => node.textContent === 'Added guest 3.',
        ),
      ).toBe(true);
    });

    const removeEventStart = events.length;
    const animationCountBeforeRemove = animate.mock.calls.length;
    fireEvent.click(screen.getByRole('button', {name: 'Remove guest 1'}));

    expect(events[removeEventStart]).toBe('change:remove');
    expect(animate.mock.calls.length).toBeGreaterThan(
      animationCountBeforeRemove,
    );
    expect(screen.queryByDisplayValue('Ada')).not.toBeInTheDocument();
    expect(screen.getByRole('button', {name: 'Remove guest 1'})).toHaveFocus();
    expect(
      animate.mock.calls
        .slice(animationCountBeforeRemove)
        .some(([keyframes], index) => {
          const context = animate.mock.contexts[
            animationCountBeforeRemove + index
          ] as HTMLElement;
          return (
            context.querySelector('input')?.value === 'Grace' &&
            (keyframes as Keyframe[])[0]?.transform === 'translate(0px, 40px)'
          );
        }),
    ).toBe(true);
    await waitFor(() => {
      expect(
        Array.from(document.querySelectorAll('[aria-live="polite"]')).some(
          node => node.textContent === 'Removed guest 1.',
        ),
      ).toBe(true);
    });
  });

  it('uses instant add and remove changes when reduced motion is requested', async () => {
    const animate = mockMutationAnimations();
    vi.spyOn(window, 'matchMedia').mockImplementation(
      query =>
        ({
          matches: query === '(prefers-reduced-motion: reduce)',
          media: query,
          onchange: null,
          addListener: () => {},
          removeListener: () => {},
          addEventListener: () => {},
          removeEventListener: () => {},
          dispatchEvent: () => false,
        }) as MediaQueryList,
    );

    function ReducedMotionList() {
      const [value, setValue] = useState([guests[0]]);
      return (
        <ListInput<Guest>
          label="Guests"
          itemName="guest"
          value={value}
          onChange={setValue}
          getItemKey={guest => guest.id}
          createItem={() => createdGuest}
          columns={columns}
        />
      );
    }

    render(<ReducedMotionList />);
    fireEvent.click(screen.getByRole('button', {name: 'Remove guest 1'}));

    expect(animate).not.toHaveBeenCalled();
    expect(screen.queryByDisplayValue('Ada')).not.toBeInTheDocument();
    expect(screen.getByRole('button', {name: 'Add guest'})).toHaveFocus();
    // The removal and the empty state that appears join in one frame (FR9).
    await waitFor(() => {
      expect(
        Array.from(document.querySelectorAll('[aria-live="polite"]')).some(
          node =>
            node.textContent ===
            'Removed guest 1. No guests yet Add a guest to get started.',
        ),
      ).toBe(true);
    });

    fireEvent.click(screen.getByRole('button', {name: 'Add guest'}));
    expect(animate).not.toHaveBeenCalled();
    expect(screen.getByDisplayValue('Linus')).toHaveFocus();
  });

  it('renders list/item messages and presents field messages in a tooltip', () => {
    renderListInput({
      columns: nativeStatusColumns,
      status: {type: 'error', message: 'Add at least three guests'},
      getItemStatus: guest =>
        guest.id === 'ada'
          ? {type: 'error', message: 'This guest is duplicated'}
          : undefined,
      getFieldStatus: (guest, columnKey) =>
        guest.id === 'ada' && columnKey === 'name'
          ? {type: 'error', message: 'Enter a different name'}
          : undefined,
    });

    expect(screen.getByText('Add at least three guests')).toBeInTheDocument();
    expect(screen.getByText('This guest is duplicated')).toBeInTheDocument();
    const firstInput = screen.getAllByRole('textbox')[0];
    expect(firstInput).toHaveAttribute('aria-invalid', 'true');
    const tooltip = screen
      .getAllByRole('tooltip', {hidden: true})
      .find(node => node.textContent === 'Enter a different name');
    expect(tooltip).toBeDefined();
    expect(tooltip).toHaveTextContent('Enter a different name');
    expect(firstInput.getAttribute('aria-describedby')).toContain(tooltip!.id);
    const fieldCell = firstInput.closest('[data-list-input-cell]');
    expect(fieldCell?.querySelector('.astryx-field-status')).toBeNull();
    expect(
      within(fieldCell as HTMLElement).getByRole('button', {
        name: /error details/i,
      }),
    ).toBeInTheDocument();
    expect(
      firstInput.closest('[role="group"][aria-invalid="true"]'),
    ).toBeNull();

    const itemStatus = screen
      .getByText('This guest is duplicated')
      .closest('[data-list-input-item-status]');
    const itemRow = document.querySelector('[data-list-input-row="ada"]');
    expect(itemStatus).toBeDefined();
    expect(itemStatus?.parentElement).toBe(itemRow);
    expect(
      screen.getAllByRole('listitem')[0].getAttribute('aria-describedby'),
    ).toContain(itemStatus?.id);
  });

  it('fills the fields track with Add and omits reorder handles by default', () => {
    const {container} = renderListInput({columns: nativeStatusColumns});

    const addContent = container.querySelector('[data-list-input-add-content]');
    const addButton = screen.getByRole('button', {name: 'Add guest'});
    const removeButton = screen.getByRole('button', {
      name: 'Remove guest 1',
    });
    const textInput = container.querySelector('.astryx-text-input');
    expect(addContent).toContainElement(addButton);
    expect(addButton).toHaveAttribute('data-size', 'md');
    expect(removeButton).toHaveAttribute('data-size', 'md');
    expect(textInput).toHaveAttribute('data-size', 'md');
    expect(
      screen.queryByRole('button', {name: 'Reorder guest 1'}),
    ).not.toBeInTheDocument();
  });

  it("ends each record with core List's reorder handle, revealed on hover or focus", () => {
    // A fine pointer (jsdom models a mouse): hover reveals the handle.
    expect(window.matchMedia('(pointer: coarse)').matches).toBe(false);
    const reveal = revealClasses();
    const {container} = renderListInput({reorderable: reorderableFor()});
    const row = container.querySelector<HTMLElement>('[data-list-input-row]');
    const handle = screen.getByRole('button', {name: 'Reorder guest 1'});
    const remove = screen.getByRole('button', {name: 'Remove guest 1'});

    // The handle is the record's last control, after Remove in Remove's
    // cell, as UIKit's reorder control ends an editing row.
    expect(within(row!).getAllByRole('button')).toEqual([remove, handle]);
    expect(handle).toHaveAttribute('data-astryx-list-reorder');
    expect(row!.querySelector('[data-list-input-cell]')?.contains(handle)).toBe(
      false,
    );

    // The row is the reveal container; the controls' cell fades with opacity
    // alone, so at rest the handle stays mounted, named, and focusable.
    const handleCell = [...row!.children].find(child => child.contains(handle));
    expect(classTokens(row)).toEqual(expect.arrayContaining(reveal.container));
    expect(classTokens(handleCell ?? null)).toEqual(
      expect.arrayContaining(reveal.grip),
    );
    expect(handle).toBeEnabled();
    expect(handle).not.toHaveAttribute('tabindex', '-1');
  });

  it('reveals Remove on hover or focus, with or without reordering', () => {
    const reveal = revealClasses();
    for (const reorderable of [undefined, reorderableFor()]) {
      const {container, unmount} = renderListInput({reorderable});
      const rows = container.querySelectorAll<HTMLElement>(
        '[data-list-input-row]',
      );
      rows.forEach((row, index) => {
        const remove = within(row).getByRole('button', {
          name: `Remove guest ${index + 1}`,
        });
        // The row's direct child holding Remove is its control cell. It fades
        // with opacity alone, so the button keeps its column, stays mounted,
        // and stays in the tab order.
        const removeCell = [...row.children].find(child =>
          child.contains(remove),
        );
        expect(classTokens(row)).toEqual(
          expect.arrayContaining(reveal.container),
        );
        expect(classTokens(removeCell ?? null)).toEqual(
          expect.arrayContaining(reveal.grip),
        );
        expect(remove).toBeEnabled();
        expect(remove).not.toHaveAttribute('tabindex', '-1');
      });
      unmount();
    }
  });

  it('focuses the first field of an added record, not its grip', () => {
    render(<OwnedList />);
    fireEvent.click(screen.getByRole('button', {name: 'Add guest'}));

    expect(screen.getByDisplayValue('Linus')).toHaveFocus();
  });

  it('supports consumer-owned validation that appears after blur', () => {
    function BlurValidatedList() {
      const [value, setValue] = useState<Guest[]>([guests[0]]);
      const [touchedItems, setTouchedItems] = useState<ReadonlySet<string>>(
        () => new Set(),
      );
      const blurColumns = [
        {
          key: 'name',
          header: 'Name',
          renderInput: ({
            item,
            label,
            isLabelHidden,
            status,
            statusVariant,
            updateItem,
          }) => (
            <TextInput
              label={label}
              isLabelHidden={isLabelHidden}
              value={item.name}
              status={status}
              statusVariant={statusVariant}
              onChange={name => updateItem({...item, name}, 'name')}
              onBlur={() =>
                setTouchedItems(current => {
                  const next = new Set(current);
                  next.add(item.id);
                  return next;
                })
              }
            />
          ),
        },
      ] satisfies ListInputColumn<Guest>[];

      return (
        <ListInput<Guest>
          label="Guests"
          itemName="guest"
          value={value}
          onChange={nextValue => setValue(nextValue)}
          getItemKey={guest => guest.id}
          createItem={() => ({id: 'blank', name: ''})}
          columns={blurColumns}
          getFieldStatus={(guest, columnKey) =>
            touchedItems.has(guest.id) &&
            columnKey === 'name' &&
            guest.name.trim() === ''
              ? {type: 'error', message: 'Enter a name'}
              : undefined
          }
        />
      );
    }

    render(<BlurValidatedList />);
    fireEvent.click(screen.getByRole('button', {name: 'Add guest'}));

    const addedInput = screen.getByRole('textbox', {
      name: 'Name, guest 2 of 2',
    });
    expect(addedInput).toHaveFocus();
    expect(addedInput).not.toHaveAttribute('aria-invalid');
    expect(
      screen
        .queryAllByRole('tooltip', {hidden: true})
        .some(node => node.textContent === 'Enter a name'),
    ).toBe(false);

    fireEvent.blur(addedInput);

    expect(
      screen.getByRole('textbox', {name: 'Name, guest 2 of 2'}),
    ).toHaveAttribute('aria-invalid', 'true');
    expect(
      screen
        .getAllByRole('tooltip', {hidden: true})
        .some(node => node.textContent === 'Enter a name'),
    ).toBe(true);
  });

  it('disables Add at maxItems while keeping removal available', () => {
    const onChange = vi.fn();

    renderListInput({maxItems: 2, onChange});

    expect(screen.getByRole('button', {name: 'Add guest'})).toHaveAttribute(
      'aria-disabled',
      'true',
    );
    const remove = screen.getByRole('button', {name: 'Remove guest 1'});
    expect(remove).toBeEnabled();

    fireEvent.click(remove);
    expect(onChange).toHaveBeenCalledWith([guests[1]], {
      type: 'remove',
      item: guests[0],
      index: 0,
    });
  });

  it("moves a record in reorder mode with the arrow keys, through the owner's onReorder", async () => {
    const user = userEvent.setup();
    const onReorder = vi.fn();
    const onChange = vi.fn();
    render(<OwnedList onReorder={onReorder} onChange={onChange} />);
    const handle = screen.getByRole('button', {name: 'Reorder guest 1'});
    expect(handle).toHaveAttribute('type', 'button');
    expect(handle).toHaveAccessibleDescription(HINT);
    expect(
      screen
        .queryAllByRole('tooltip', {hidden: true})
        .some(tooltip => tooltip.textContent === 'Reorder guest 1'),
    ).toBe(false);

    // Enter turns on reorder mode. Each arrow then moves the record a place.
    // The move is reported in the value's terms: its key and its new index.
    handle.focus();
    await user.keyboard('{Enter}');
    await user.keyboard('{ArrowUp}');
    expect(onReorder).not.toHaveBeenCalled();
    await user.keyboard('{ArrowDown}');
    expect(onReorder).toHaveBeenCalledTimes(1);
    expect(onReorder).toHaveBeenCalledWith({key: 'ada', to: 1});
    expect(shownNames()).toEqual(['Grace', 'Ada']);
    // A move is the owner's, never a ListInput change.
    expect(onChange).not.toHaveBeenCalled();
    expect(handle).toHaveFocus();
    expect(handle).toHaveAccessibleName('Reorder guest 2');
  });

  it('keeps reorder mode through a move that renames the record, and announces it by its new name', async () => {
    const user = userEvent.setup();
    const onReorder = vi.fn();
    render(<OwnedList onReorder={onReorder} />);
    const handle = screen.getByRole('button', {name: 'Reorder guest 1'});

    handle.focus();
    await user.keyboard('{Enter}{ArrowDown}');
    // Records are named by their place, so the move renames this one.
    expect(handle).toHaveAccessibleName('Reorder guest 2');
    expect(handle).toHaveAttribute('aria-pressed', 'true');
    await waitFor(() =>
      expect(document.body).toHaveTextContent(
        'guest 2, position 2 of 2, after guest 1, at the end',
      ),
    );
    // Still in the mode: the next arrow moves it back.
    await user.keyboard('{ArrowUp}');
    expect(onReorder).toHaveBeenCalledTimes(2);
    expect(onReorder).toHaveBeenLastCalledWith({key: 'ada', to: 0});
    expect(handle).toHaveAttribute('aria-pressed', 'true');
    await waitFor(() =>
      expect(document.body).toHaveTextContent(
        'guest 1, position 1 of 2, at the top, before guest 2',
      ),
    );
  });

  it('adds one element to each record for reordering: the handle', () => {
    const plain = renderListInput();
    const plainCount = plain.container
      .querySelector('[data-list-input-row]')!
      .querySelectorAll('*').length;
    plain.unmount();
    const {container} = renderListInput({reorderable: reorderableFor()});
    const row = container.querySelector('[data-list-input-row]');
    expect(row).toContainElement(
      screen.getByRole('button', {name: 'Reorder guest 1'}),
    );
    expect(row!.querySelectorAll('*').length - plainCount).toBe(1);
  });

  it('loads no reorder code without reorderable: the handle comes with the object', () => {
    const source = readFileSync(
      path.join(import.meta.dirname, 'ListInput.tsx'),
      'utf8',
    );
    const names =
      /import\s*\{([^}]*)\}\s*from\s*'@astryxdesign\/core\/internal\/reorder';/
        .exec(source)?.[1]
        .split(',')
        .map(name => name.trim())
        .filter(name => name !== '');
    expect(names?.sort()).toEqual(['ListReorderScope', 'useListReorderScope']);
    expect(source).not.toMatch(/ListReorderHandle/);
  });

  it('ends reorder mode with Escape, keeping the moves', async () => {
    const user = userEvent.setup();
    const onReorder = vi.fn();
    render(<OwnedList onReorder={onReorder} />);
    const handle = screen.getByRole('button', {name: 'Reorder guest 1'});

    handle.focus();
    await user.keyboard('{Enter}{ArrowDown}{Escape}');
    expect(onReorder).toHaveBeenCalledTimes(1);
    expect(shownNames()).toEqual(['Grace', 'Ada']);
    // Out of the mode, an arrow moves nothing.
    await user.keyboard('{ArrowUp}');
    expect(onReorder).toHaveBeenCalledTimes(1);
    expect(handle).toHaveFocus();
  });

  it("gives no handle to a record the owner's isReorderable rejects, and moves no record past it at either end", async () => {
    const user = userEvent.setup();
    const onReorder = vi.fn();
    render(<OwnedList onReorder={onReorder} isReorderable={isNotAda} />);
    expect(screen.queryByRole('button', {name: 'Reorder guest 1'})).toBeNull();
    const handle = screen.getByRole('button', {name: 'Reorder guest 2'});
    handle.focus();
    await user.keyboard('{Enter}{ArrowUp}{Escape}');
    expect(onReorder).not.toHaveBeenCalled();
    expect(shownNames()).toEqual(['Ada', 'Grace']);
  });

  it('locks every field and mutation control when isDisabled is set', () => {
    const onChange = vi.fn();
    const onReorder = vi.fn();
    renderListInput({
      isDisabled: true,
      reorderable: reorderableFor(onReorder),
      onChange,
    });

    const group = screen.getByRole('group');
    expect(group).toHaveAttribute('aria-disabled', 'true');
    expect(group).not.toHaveAttribute('aria-busy');

    for (const field of screen.getAllByRole('textbox')) {
      expect(field).toBeDisabled();
    }
    expect(screen.getByRole('button', {name: /add guest/i})).toHaveAttribute(
      'aria-disabled',
      'true',
    );
    // The handle stays focusable but moves nothing (spec:AST-085 FR1, FR2).
    const handle = screen.getByRole('button', {name: 'Reorder guest 1'});
    expect(handle).toHaveAttribute('aria-disabled', 'true');
    expect(handle).not.toHaveAttribute('disabled');
    handle.focus();
    fireEvent.keyDown(handle, {key: 'ArrowDown'});
    fireEvent.keyDown(handle, {key: ' '});
    fireEvent.keyDown(handle, {key: 'ArrowDown'});
    expect(handle).toHaveFocus();
    // Remove carries a tooltip, so it is disabled via aria and stays focusable
    // rather than dropping out of the tab order with its explanation.
    expect(
      screen.getByRole('button', {name: 'Remove guest 1'}),
    ).toHaveAttribute('aria-disabled', 'true');

    // The values stay readable — a disabled list still communicates content.
    expect(screen.getAllByRole('textbox')[0]).toHaveValue('Ada');
    expect(onChange).not.toHaveBeenCalled();
    expect(onReorder).not.toHaveBeenCalled();
  });

  it('marks the list busy and locks the same controls when isLoading is set', () => {
    renderListInput({isLoading: true, reorderable: reorderableFor()});

    const group = screen.getByRole('group');
    expect(group).toHaveAttribute('aria-busy', 'true');
    // Loading is not disabled: the values may still change, so the group is
    // never reported as disabled to assistive technology.
    expect(group).not.toHaveAttribute('aria-disabled');

    for (const field of screen.getAllByRole('textbox')) {
      expect(field).toBeDisabled();
    }
    // The add button receives isLoading directly (unlike remove/reorder
    // below, which map ListInput's own loading state onto their isDisabled
    // prop), so it stays focusable while busy per Button's "Disabled vs
    // Busy" contract: aria-disabled, not native disabled, so a keyboard
    // user isn't dropped from the list mid-load.
    const addButton = screen.getByRole('button', {name: /add guest/i});
    expect(addButton).not.toBeDisabled();
    expect(addButton).toHaveAttribute('aria-disabled', 'true');
    expect(addButton).toHaveAttribute('aria-busy', 'true');
    expect(
      screen.getByRole('button', {name: 'Reorder guest 1'}),
    ).toHaveAttribute('aria-disabled', 'true');
    expect(
      screen.getByRole('button', {name: 'Remove guest 1'}),
    ).toHaveAttribute('aria-disabled', 'true');
  });

  it('abandons reorder mode when the list becomes busy', async () => {
    const user = userEvent.setup();
    const onReorder = vi.fn();
    const reorderable = reorderableFor(onReorder);
    const props: ListInputProps<Guest> = {
      label: 'Guests',
      itemName: 'guest',
      value: guests,
      onChange: () => {},
      getItemKey: guest => guest.id,
      createItem: () => createdGuest,
      columns,
      reorderable,
    };
    const {rerender} = render(<ListInput<Guest> {...props} />);

    const handle = screen.getByRole('button', {name: 'Reorder guest 1'});
    handle.focus();
    await user.keyboard('{Enter}');
    rerender(<ListInput<Guest> {...props} isLoading />);

    // The handle keeps focus but is inert now: no key moves the record, so
    // no order change escapes (spec:AST-085 FR2, FR4).
    expect(handle).toHaveFocus();
    expect(handle).toHaveAttribute('aria-disabled', 'true');
    await user.keyboard('{ArrowDown}{Enter}');
    expect(onReorder).not.toHaveBeenCalled();
  });

  it('describes warning and success list statuses from the group', () => {
    const {rerender} = renderListInput({
      status: {type: 'warning', message: 'Two guests share a name.'},
    });

    const describedBy = screen
      .getByRole('group')
      .getAttribute('aria-describedby');
    expect(describedBy).toBeTruthy();
    expect(document.getElementById(describedBy!)).toHaveTextContent(
      'Two guests share a name.',
    );

    rerender(
      <ListInput<Guest>
        label="Guests"
        itemName="guest"
        value={guests}
        onChange={() => {}}
        getItemKey={guest => guest.id}
        createItem={() => createdGuest}
        columns={columns}
        status={{type: 'success', message: 'Every guest is confirmed.'}}
      />,
    );
    expect(screen.getByText('Every guest is confirmed.')).toBeInTheDocument();
  });

  it('associates list status with the group and item status with its row', () => {
    renderListInput({
      status: {type: 'error', message: 'Add at least three guests.'},
      getItemStatus: guest =>
        guest.id === 'grace'
          ? {type: 'error', message: 'Grace is already invited.'}
          : undefined,
    });

    const listDescribedBy = screen
      .getByRole('group')
      .getAttribute('aria-describedby');
    expect(document.getElementById(listDescribedBy!)).toHaveTextContent(
      'Add at least three guests.',
    );

    // Row-scoped status belongs to the row, not the list, so a reader on the
    // second record does not inherit the first record's message.
    const rows = screen.getAllByRole('listitem');
    expect(rows[0]).not.toHaveAttribute('aria-invalid');
    expect(rows[1]).toHaveAttribute('aria-invalid', 'true');
    const rowDescribedBy = rows[1].getAttribute('aria-describedby');
    expect(document.getElementById(rowDescribedBy!)).toHaveTextContent(
      'Grace is already invited.',
    );
  });

  it('moves focus to the next record after a removal, and to Add when the list empties', async () => {
    function ControlledList() {
      const [value, setValue] = useState(guests);
      return (
        <ListInput<Guest>
          label="Guests"
          itemName="guest"
          value={value}
          onChange={setValue}
          getItemKey={guest => guest.id}
          createItem={() => createdGuest}
          columns={columns}
        />
      );
    }
    render(<ControlledList />);

    // Removing the first of two lands on the record that took its place, so a
    // keyboard user can delete consecutively without re-tabbing.
    fireEvent.click(screen.getByRole('button', {name: 'Remove guest 1'}));
    await waitFor(() => {
      expect(
        screen.getByRole('button', {name: 'Remove guest 1'}),
      ).toHaveFocus();
    });
    expect(screen.getAllByRole('listitem')).toHaveLength(1);

    // Removing the last record leaves nothing to focus, so focus falls back to Add.
    fireEvent.click(screen.getByRole('button', {name: 'Remove guest 1'}));
    await waitFor(() => {
      expect(screen.getByRole('button', {name: /add guest/i})).toHaveFocus();
    });
  });

  it('warns in development when getItemKey returns a duplicate key', () => {
    const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
    renderListInput({
      value: [guests[0], {...guests[1], id: guests[0].id}],
    });

    expect(warn.mock.calls.flat().join(' ')).toContain(
      'ListInput: getItemKey returned duplicate key',
    );
  });
});