Skip to content

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

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

'use client';

/**
 * @file ListInput.tsx
 * @input React, StyleX, Astryx field/list/button/icon/empty-state
 *   primitives, the container-reveal hook, compact size context, browser
 *   scroll geometry, and programmatic theme tokens. Also core List's reorder
 *   session and handle, run by the owner's createReorderable object through
 *   Core's internal entry `@astryxdesign/core/internal/reorder`
 * @output Exports ListInput and its controlled data, column, renderer, and change types
 * @position Lab experiment (RFC meta/astryx#4531) for editing compact repeated records
 *
 * SYNC: When modified, update these files to stay in sync:
 * - /packages/lab/src/ListInput/ListInput.doc.mjs
 * - /packages/lab/src/ListInput/ListInput.test.tsx
 * - /packages/lab/src/ListInput/index.ts
 * - /apps/storybook/stories/ListInput.stories.tsx
 */

import {
  useEffect,
  useId,
  useLayoutEffect,
  useMemo,
  useRef,
  type Key,
  type ReactNode,
} from 'react';
import * as stylex from '@stylexjs/stylex';
import type {BaseProps} from '@astryxdesign/core';
import {Button} from '@astryxdesign/core/Button';
import {EmptyState} from '@astryxdesign/core/EmptyState';
import {Field, type InputStatus} from '@astryxdesign/core/Field';
import {FieldStatus} from '@astryxdesign/core/FieldStatus';
import {Icon} from '@astryxdesign/core/Icon';
import {
  useAnnounce,
  useContainerReveal,
  useMediaQuery,
} from '@astryxdesign/core/hooks';
import {IconButton} from '@astryxdesign/core/IconButton';
import {useTranslator} from '@astryxdesign/core/i18n';
import {
  ListReorderScope,
  useListReorderScope,
} from '@astryxdesign/core/internal/reorder';
import type {Reorderable} from '@astryxdesign/core';
import {SizeProvider} from '@astryxdesign/core/SizeContext';
import type {ColumnWidth} from '@astryxdesign/core/Table';
import {useTheme} from '@astryxdesign/core/theme';
import {
  colorVars,
  fontWeightVars,
  sizeVars,
  spacingVars,
  typeScaleVars,
} from '@astryxdesign/core/theme/tokens.stylex';
import {mergeProps, themeProps} from '@astryxdesign/core/utils';

// Bundlers replace this value at build time. The declaration lets a product
// without Node's types type-check this file.
declare const process: {readonly env: {readonly NODE_ENV?: string}};

export type ListInputChange<T> =
  | {type: 'add'; item: T; index: number}
  | {
      type: 'update';
      item: T;
      previousItem: T;
      index: number;
      columnKey?: string;
    }
  | {type: 'remove'; item: T; index: number};

export interface ListInputValueContext<T> {
  /** Current record. */
  item: T;
  /** Current visual position. */
  index: number;
  /** Accessible cell label, including the record position. */
  label: string;
  /** True because ListInput owns the visible column label. */
  isLabelHidden: boolean;
}

export interface ListInputRenderContext<T> extends ListInputValueContext<T> {
  /** Complete validation status scoped to this field. */
  status?: InputStatus;
  /** Forward to the rendered Astryx control so status uses its native tooltip. */
  statusVariant: 'tooltip';
  /** Whether the rendered control should be disabled. */
  isDisabled: boolean;
  /** Whether an asynchronous list operation is in progress. */
  isLoading: boolean;
  /** Replace this record in the controlled list. */
  updateItem: (nextItem: T, columnKey?: string) => void;
}

export interface ListInputColumn<T> {
  /** Stable column identifier, also passed to getFieldStatus. */
  key: string;
  /** Field label shown on the first record and repeated when rows stack. */
  header: string;
  /**
   * Column sizing. Use proportional() or pixel() from @astryxdesign/core/Table
   * to tune the width ratio. Defaults to a proportional column with a 140px floor.
   */
  width?: ColumnWidth;
  /** Renders the editable control for one cell. */
  renderInput: (context: ListInputRenderContext<T>) => ReactNode;
}

export interface ListInputProps<T> extends Omit<
  BaseProps<HTMLDivElement>,
  'onChange'
> {
  /** Ref forwarded to the outer field element. */
  ref?: React.Ref<HTMLDivElement>;
  /** Visible and accessible label for the list. */
  label: string;
  /** Optional supporting text. */
  description?: string;
  /** Controlled records. */
  value: T[];
  /** Called for every record mutation with the next value and mutation detail. */
  onChange: (nextValue: T[], change: ListInputChange<T>) => void;
  /** Returns a stable key for focus preservation and reordering. */
  getItemKey: (item: T) => Key;
  /** Creates a new record when the Add action is used. */
  createItem: () => T;
  /** Column definitions and cell renderers. */
  columns: ListInputColumn<T>[];
  /** Singular name used in action labels and announcements. @default 'item' */
  itemName?: string;
  /** Validation status for the whole list. */
  status?: InputStatus;
  /** Returns a validation status displayed across one record. */
  getItemStatus?: (item: T, index: number) => InputStatus | undefined;
  /** Returns a validation status passed to one field renderer. */
  getFieldStatus?: (
    item: T,
    columnKey: string,
    index: number,
  ) => InputStatus | undefined;
  /**
   * Makes the records reorderable: pass the object
   * `createReorderable` makes, keyed by `getItemKey`. Each record ends with
   * core List's reorder handle. A finger holds it a moment, then drags. A
   * mouse drags at once. Its arrow keys move the record. The object's
   * `isReorderable(key)` says which records move, and each move goes to its
   * `onReorder({key, to})`, `to` being the record's index in `value` after
   * the move. Without it, the records keep their order.
   */
  reorderable?: Reorderable;
  /** Disables fields and mutation controls. @default false */
  isDisabled?: boolean;
  /** Marks the list busy and prevents mutations. @default false */
  isLoading?: boolean;
  /** Maximum record count. Reaching it disables, but does not remove, Add. */
  maxItems?: number;
  /** Visually hides the list label while preserving its accessible name. */
  isLabelHidden?: boolean;
  /** Marks the list optional. */
  isOptional?: boolean;
  /** Marks the list required. */
  isRequired?: boolean;
}

interface PendingFocus {
  itemKey?: string;
  target: 'first-field' | 'remove' | 'add';
}

interface PendingAddScrollAnchor {
  addTop: number;
  expectedKeys: string[];
  itemKey: string;
}

interface LayoutSnapshot {
  element: HTMLElement;
  rect: DOMRect;
}

interface PendingMutationMotion<T> {
  before: Map<string, LayoutSnapshot>;
  duration: number;
  easing: string;
  entryOffset: string;
  matchesValue: (nextValue: T[]) => boolean;
}

// Core List's reorder handle is 28 px wide for every pointer.
const REORDER_HANDLE_SIZE = 28;

const styles = stylex.create({
  group: {
    display: 'flex',
    flexDirection: 'column',
    minWidth: 0,
    overflowAnchor: 'none',
    width: '100%',
    containerType: 'inline-size',
    containerName: 'list-input',
  },
  list: {
    display: 'flex',
    flexDirection: 'column',
    gap: {
      default: spacingVars['--spacing-2'],
      '@container list-input (max-width: 640px)': spacingVars['--spacing-8'],
    },
    listStyleType: 'none',
    margin: 0,
    padding: 0,
  },
  item: {
    display: 'flex',
    flexDirection: 'column',
    minWidth: 0,
    position: 'relative',
  },
  row: {
    display: 'grid',
    alignItems: 'end',
    columnGap: spacingVars['--spacing-1'],
    rowGap: {
      default: 0,
      '@container list-input (max-width: 640px)': spacingVars['--spacing-2'],
    },
    minWidth: 0,
    // Core's reorder handle reaches into a ListItem row's inline inset. A
    // record has no inset, so the handle and its focus ring end at its edge.
    '--_item-inset-inline': '0px',
  },
  rowFieldsOnly: {
    gridTemplateColumns: 'minmax(0, 1fr)',
  },
  rowWithRemove: {
    gridTemplateColumns: `minmax(0, 1fr) ${sizeVars['--size-element-md']}`,
  },
  // Fields, then Remove and the reorder handle in one cell at the row's end
  // (UIKit's reorder control is the trailing control of an editing row). The
  // cell's track is fixed, so the Add row, which has no controls, keeps the
  // fields' width.
  rowWithRemoveAndHandle: {
    gridTemplateColumns: `minmax(0, 1fr) calc(${sizeVars['--size-element-md']} + ${spacingVars['--spacing-1']} + ${REORDER_HANDLE_SIZE}px)`,
  },
  fields: {
    display: {
      default: 'grid',
      '@container list-input (max-width: 640px)': 'contents',
    },
    alignItems: 'end',
    gap: {
      default: spacingVars['--spacing-1'],
      '@container list-input (max-width: 640px)': spacingVars['--spacing-2'],
    },
    minWidth: 0,
  },
  fieldCell: {
    gridColumn: {
      default: 'auto',
      '@container list-input (max-width: 640px)': '1',
    },
  },
  contentOnly: {gridColumn: '1 / -1'},
  contentBeforeOneControl: {gridColumn: '1 / -2'},
  itemStatus: {
    gridRow: {
      default: '2',
      '@container list-input (max-width: 640px)': 'auto',
    },
    marginBlockStart: {
      default: spacingVars['--spacing-1'],
      '@container list-input (max-width: 640px)': 0,
    },
    minWidth: 0,
  },
  actionRow: {
    display: 'grid',
    alignItems: 'center',
    columnGap: spacingVars['--spacing-1'],
    marginBlockStart: spacingVars['--spacing-2'],
  },
  actionContent: {
    minWidth: 0,
  },
  columnLabel: {
    display: 'block',
    marginBlockEnd: {
      default: spacingVars['--spacing-0-5'],
      '@container list-input (max-width: 640px)': spacingVars['--spacing-1'],
    },
    color: colorVars['--color-text-primary'],
    fontSize: typeScaleVars['--text-label-size'],
    lineHeight: typeScaleVars['--text-label-leading'],
    fontWeight: fontWeightVars['--font-weight-medium'],
  },
  repeatedColumnLabel: {
    display: {
      default: 'none',
      '@container list-input (max-width: 640px)': 'block',
    },
  },
  cellContent: {minWidth: 0},
  controlCell: {
    display: 'flex',
    alignItems: 'center',
    alignSelf: 'end',
    // Remove keeps its column in a record that has no reorder handle.
    justifyContent: 'flex-start',
    columnGap: spacingVars['--spacing-1'],
    minHeight: sizeVars['--size-element-md'],
  },
  removeControlCell: {
    gridColumn: {
      default: 'auto',
      '@container list-input (max-width: 640px)': '2',
    },
    gridRow: {
      default: 'auto',
      '@container list-input (max-width: 640px)': '1',
    },
  },
  emptyItem: {
    width: '100%',
  },
});

const dynamicStyles = stylex.create({
  fields: (gridTemplateColumns: string) => ({
    gridTemplateColumns: {
      default: gridTemplateColumns,
      '@container list-input (max-width: 640px)': 'minmax(0, 1fr)',
    },
  }),
});

function resolveColumnTrack(width?: ColumnWidth): string {
  if (width?.type === 'pixel') {
    return `${width.value}px`;
  }
  const proportion = width?.value ?? 1;
  const minWidth = width?.minWidth ?? 140;
  return `minmax(${minWidth}px, ${proportion}fr)`;
}

function joinIDs(...ids: Array<string | undefined>): string | undefined {
  const resolved = ids.filter(Boolean);
  return resolved.length > 0 ? resolved.join(' ') : undefined;
}

const focusableFieldSelector =
  '[data-list-input-cell] input, [data-list-input-cell] select, [data-list-input-cell] textarea, [data-list-input-cell] button, [data-list-input-cell] [tabindex]:not([tabindex="-1"])';

function getScrollableAncestors(element: HTMLElement): HTMLElement[] {
  const scrollRoots: HTMLElement[] = [];
  let current = element.parentElement;

  while (current != null) {
    const overflowY = window.getComputedStyle(current).overflowY;
    const isScrollable =
      (overflowY === 'auto' ||
        overflowY === 'scroll' ||
        overflowY === 'overlay') &&
      current.scrollHeight > current.clientHeight;

    if (isScrollable) {
      scrollRoots.push(current);
    }
    current = current.parentElement;
  }

  return scrollRoots;
}

function isVerticallyPerceivable(element: HTMLElement): boolean {
  const elementBounds = element.getBoundingClientRect();
  const viewportBottom =
    window.innerHeight || document.documentElement.clientHeight;
  let visibleTop = 0;
  let visibleBottom = viewportBottom;
  let current = element.parentElement;

  while (current != null) {
    const overflowY = window.getComputedStyle(current).overflowY;
    if (
      overflowY === 'auto' ||
      overflowY === 'scroll' ||
      overflowY === 'overlay' ||
      overflowY === 'hidden' ||
      overflowY === 'clip'
    ) {
      const bounds = current.getBoundingClientRect();
      const contentTop = bounds.top + current.clientTop;
      visibleTop = Math.max(visibleTop, contentTop);
      visibleBottom = Math.min(
        visibleBottom,
        contentTop + current.clientHeight,
      );
    }
    current = current.parentElement;
  }

  const elementCenter = (elementBounds.top + elementBounds.bottom) / 2;
  return elementCenter >= visibleTop && elementCenter <= visibleBottom;
}

function scrollByInstantly(
  scrollRoot: HTMLElement | null,
  delta: number,
): void {
  const styleTarget = scrollRoot ?? document.documentElement;
  const previousBehavior =
    styleTarget.style.getPropertyValue('scroll-behavior');
  const previousPriority =
    styleTarget.style.getPropertyPriority('scroll-behavior');
  styleTarget.style.setProperty('scroll-behavior', 'auto', 'important');

  try {
    if (scrollRoot != null) {
      scrollRoot.scrollTop += delta;
    } else {
      window.scrollBy(0, delta);
    }
  } finally {
    if (previousBehavior === '') {
      styleTarget.style.removeProperty('scroll-behavior');
    } else {
      styleTarget.style.setProperty(
        'scroll-behavior',
        previousBehavior,
        previousPriority,
      );
    }
  }
}

function parseDuration(value: string): number {
  const normalizedValue = value.trim();
  const duration = Number.parseFloat(normalizedValue);
  if (!Number.isFinite(duration)) {
    return 0;
  }
  if (normalizedValue.endsWith('ms')) {
    return duration;
  }
  return normalizedValue.endsWith('s') ? duration * 1000 : 0;
}

function captureMutationLayout(
  root: HTMLElement,
  activeAnimations: Map<HTMLElement, Animation>,
): Map<string, LayoutSnapshot> {
  const snapshots = new Map<string, LayoutSnapshot>();
  const elements: HTMLElement[] = [];
  for (const child of root.children) {
    if (!(child instanceof HTMLElement)) {
      continue;
    }
    if (child.tagName === 'OL') {
      for (const item of child.children) {
        if (
          item instanceof HTMLElement &&
          item.dataset.listInputMotionKey != null
        ) {
          elements.push(item);
        }
      }
    } else if (child.dataset.listInputMotionKey != null) {
      elements.push(child);
    }
  }
  for (const element of elements) {
    const key = element.dataset.listInputMotionKey;
    if (key == null) {
      continue;
    }
    const rect = element.getBoundingClientRect();
    activeAnimations.get(element)?.cancel();
    activeAnimations.delete(element);
    snapshots.set(key, {element, rect});
  }
  return snapshots;
}

function startMutationAnimation(
  element: HTMLElement,
  keyframes: Keyframe[],
  options: KeyframeAnimationOptions,
  activeAnimations: Map<HTMLElement, Animation>,
): void {
  try {
    const animation = element.animate(keyframes, options);
    activeAnimations.set(element, animation);
    void animation.finished.then(
      () => {
        if (activeAnimations.get(element) === animation) {
          activeAnimations.delete(element);
        }
      },
      () => {
        if (activeAnimations.get(element) === animation) {
          activeAnimations.delete(element);
        }
      },
    );
  } catch {
    // Motion is progressive enhancement; the controlled update already ran.
  }
}

/**
 * A compact editor for short collections of consistent, simple records.
 *
 * ListInput owns list semantics, add/remove controls, handle-only reordering,
 * live collection motion, focus restoration, announcements, and list/item/
 * field validation placement. Consumers keep ownership of the controlled data
 * and render each field with standard Astryx inputs.
 *
 * @example
 * ```
 * <ListInput
 *   label="Guests"
 *   value={guests}
 *   onChange={setGuests}
 *   getItemKey={guest => guest.id}
 *   createItem={() => ({id: crypto.randomUUID(), name: '', email: ''})}
 *   columns={columns}
 *   itemName="guest"
 *   reorderable={reorderable}
 * />
 * ```
 */
export function ListInput<T>({
  label,
  description,
  value,
  onChange,
  getItemKey,
  createItem,
  columns,
  itemName = 'item',
  status,
  getItemStatus,
  getFieldStatus,
  reorderable,
  isDisabled = false,
  isLoading = false,
  maxItems,
  isLabelHidden = false,
  isOptional = false,
  isRequired = false,
  ref,
  ...rest
}: ListInputProps<T>): ReactNode {
  const generatedID = useId();
  const groupID = `list-input-${generatedID}`;
  const labelID = `${groupID}-label`;
  const descriptionID = description ? `${groupID}-description` : undefined;
  const statusID = status?.message ? `${groupID}-status` : undefined;
  const reorderInstructionsID = `${groupID}-reorder-instructions`;
  const rowRefs = useRef(new Map<string, HTMLDivElement>());
  const groupRef = useRef<HTMLDivElement>(null);
  const listRef = useRef<HTMLOListElement>(null);
  const addActionRef = useRef<HTMLDivElement>(null);
  const addButtonRef = useRef<HTMLButtonElement>(null);
  const addPointerAnchorTopRef = useRef<number | null>(null);
  const addAnchorFrameRef = useRef<number | null>(null);
  const pendingFocusRef = useRef<PendingFocus | null>(null);
  const pendingAddScrollAnchorRef = useRef<PendingAddScrollAnchor | null>(null);
  const pendingMutationMotionRef = useRef<PendingMutationMotion<T> | null>(
    null,
  );
  const activeMutationAnimationsRef = useRef(new Map<HTMLElement, Animation>());
  const t = useTranslator();
  const announce = useAnnounce();
  const {tokens: themeTokens} = useTheme();
  const mutationDuration = parseDuration(
    themeTokens['--duration-fast-max'] ?? '',
  );
  const mutationEasing = themeTokens['--ease-standard'] ?? 'linear';
  const mutationEntryOffset = themeTokens['--spacing-2'] ?? '8px';
  const prefersReducedMotion = useMediaQuery(
    '(prefers-reduced-motion: reduce)',
  );
  // Each record row reveals its row actions (Remove and, when reorderable, the
  // reorder handle) on hover or keyboard focus; touch keeps them visible.
  const {getContainerProps, getContentRevealProps} = useContainerReveal();
  // A disabled or loading list keeps its handles focusable but inert.
  const reorderScope = useListReorderScope(
    reorderable,
    () => listRef.current,
    reorderInstructionsID,
  );
  const canReorder = reorderScope?.options.isReorderable;
  const showReorderHandle = reorderScope != null;
  // The handle comes with the owner's object: a list without one loads no
  // reorder code.
  const Handle = reorderScope?.session.Handle;
  const showRemoveColumn = true;
  const fieldGridTemplate = useMemo(
    () => columns.map(column => resolveColumnTrack(column.width)).join(' '),
    [columns],
  );

  useEffect(() => {
    if (process.env.NODE_ENV === 'production') {
      return;
    }
    const itemKeys = new Set<string>();
    for (const item of value) {
      const key = String(getItemKey(item));
      if (itemKeys.has(key)) {
        console.warn(
          `ListInput: getItemKey returned duplicate key "${key}". Keys must be unique and stable.`,
        );
        break;
      }
      itemKeys.add(key);
    }
    const columnKeys = new Set<string>();
    for (const column of columns) {
      if (columnKeys.has(column.key)) {
        console.warn(
          `ListInput: columns contains duplicate key "${column.key}". Column keys must be unique.`,
        );
        break;
      }
      columnKeys.add(column.key);
    }
  }, [columns, getItemKey, value]);

  useEffect(() => {
    const activeAnimations = activeMutationAnimationsRef.current;
    return () => {
      if (addAnchorFrameRef.current != null) {
        window.cancelAnimationFrame(addAnchorFrameRef.current);
      }
      for (const animation of activeAnimations.values()) {
        animation.cancel();
      }
      activeAnimations.clear();
    };
  }, []);

  useEffect(() => {
    if (!prefersReducedMotion) {
      return;
    }
    for (const animation of activeMutationAnimationsRef.current.values()) {
      animation.cancel();
    }
    activeMutationAnimationsRef.current.clear();
    pendingMutationMotionRef.current = null;
  }, [prefersReducedMotion]);

  useLayoutEffect(() => {
    const pendingAnchor = pendingAddScrollAnchorRef.current;
    if (pendingAnchor == null) {
      return;
    }
    const matchesValue =
      value.length === pendingAnchor.expectedKeys.length &&
      value.every(
        (item, index) =>
          String(getItemKey(item)) === pendingAnchor.expectedKeys[index],
      );
    if (!matchesValue) {
      pendingAddScrollAnchorRef.current = null;
      return;
    }
    pendingAddScrollAnchorRef.current = null;

    const addAction = addActionRef.current;
    if (addAction == null) {
      return;
    }
    const pendingFocus = pendingFocusRef.current;
    const addedRow = rowRefs.current.get(pendingAnchor.itemKey);
    const focusTarget =
      pendingFocus?.target === 'first-field' &&
      pendingFocus.itemKey === pendingAnchor.itemKey
        ? (addedRow?.querySelector<HTMLElement>(focusableFieldSelector) ?? null)
        : null;
    if (focusTarget != null) {
      focusTarget.focus({preventScroll: true});
      pendingFocusRef.current = null;
    }

    // Resolve after insertion: the new record may make a nearer overflow
    // container scrollable for the first time. Cascade any clamped remainder
    // outward so a partially growing inner container does not displace Add.
    const preserveAddPosition = () => {
      const scrollRoots = getScrollableAncestors(addAction);
      for (const scrollRoot of scrollRoots) {
        const scrollDelta =
          addAction.getBoundingClientRect().top - pendingAnchor.addTop;
        if (Math.abs(scrollDelta) < 0.5) {
          break;
        }
        scrollByInstantly(scrollRoot, scrollDelta);
      }
      const viewportDelta =
        addAction.getBoundingClientRect().top - pendingAnchor.addTop;
      if (Math.abs(viewportDelta) >= 0.5) {
        scrollByInstantly(null, viewportDelta);
      }
    };
    preserveAddPosition();

    // Slight clipping should not move Add away from an active pointer. Only a
    // meaningfully hidden target takes priority over pointer anchoring.
    if (focusTarget != null && !isVerticallyPerceivable(focusTarget)) {
      focusTarget.scrollIntoView?.({block: 'nearest', inline: 'nearest'});
    } else {
      // Recheck once after the browser's native anchoring/focus phase. This is
      // interaction-scoped work, not a persistent scroll or resize observer.
      if (addAnchorFrameRef.current != null) {
        window.cancelAnimationFrame(addAnchorFrameRef.current);
      }
      addAnchorFrameRef.current = window.requestAnimationFrame(() => {
        addAnchorFrameRef.current = null;
        if (addAction.isConnected) {
          preserveAddPosition();
        }
      });
    }
  }, [getItemKey, value]);

  useLayoutEffect(() => {
    const pendingMotion = pendingMutationMotionRef.current;
    if (pendingMotion == null) {
      return;
    }
    if (!pendingMotion.matchesValue(value)) {
      pendingMutationMotionRef.current = null;
      return;
    }
    pendingMutationMotionRef.current = null;
    const root = groupRef.current;
    if (root == null) {
      return;
    }

    const activeAnimations = activeMutationAnimationsRef.current;
    const after = captureMutationLayout(root, activeAnimations);
    const options: KeyframeAnimationOptions = {
      duration: pendingMotion.duration,
      easing: pendingMotion.easing,
    };
    const hasSizeChange = Array.from(after).some(([key, nextSnapshot]) => {
      const previousSnapshot = pendingMotion.before.get(key);
      return (
        previousSnapshot != null &&
        (Math.abs(previousSnapshot.rect.width - nextSnapshot.rect.width) >=
          0.5 ||
          Math.abs(previousSnapshot.rect.height - nextSnapshot.rect.height) >=
            0.5)
      );
    });
    const hasEnteringParticipant = Array.from(after.keys()).some(
      key => !pendingMotion.before.has(key),
    );
    for (const [key, nextSnapshot] of after) {
      const previousSnapshot = pendingMotion.before.get(key);
      if (previousSnapshot == null) {
        startMutationAnimation(
          nextSnapshot.element,
          [
            {transform: `translateY(${pendingMotion.entryOffset})`},
            {transform: 'translateY(0)'},
          ],
          options,
          activeAnimations,
        );
        continue;
      }
      // Appended rows already carry the orientation cue; moving the Add action
      // from beneath them would temporarily overlap the new live controls.
      if (hasSizeChange || hasEnteringParticipant) {
        continue;
      }

      const deltaX = previousSnapshot.rect.left - nextSnapshot.rect.left;
      const deltaY = previousSnapshot.rect.top - nextSnapshot.rect.top;
      if (Math.abs(deltaX) < 0.5 && Math.abs(deltaY) < 0.5) {
        continue;
      }
      startMutationAnimation(
        nextSnapshot.element,
        [
          {transform: `translate(${deltaX}px, ${deltaY}px)`},
          {transform: 'translate(0, 0)'},
        ],
        options,
        activeAnimations,
      );
    }
  }, [value]);

  useLayoutEffect(() => {
    const pendingFocus = pendingFocusRef.current;
    if (pendingFocus == null) {
      return;
    }
    let target: HTMLElement | null = null;
    if (pendingFocus.target === 'add') {
      target = addButtonRef.current;
    } else if (pendingFocus.itemKey != null) {
      const row = rowRefs.current.get(pendingFocus.itemKey);
      const selector =
        pendingFocus.target === 'remove'
          ? '[data-list-input-remove]'
          : focusableFieldSelector;
      target = row?.querySelector<HTMLElement>(selector) ?? null;
    }
    if (target != null) {
      target.focus();
      pendingFocusRef.current = null;
    }
  }, [value]);

  const mutationsDisabled = isDisabled || isLoading;
  const hasReachedMax = maxItems != null && value.length >= maxItems;

  const prepareMutationMotion = (nextValue: T[]) => {
    const root = groupRef.current;
    if (
      root == null ||
      prefersReducedMotion ||
      mutationDuration <= 0 ||
      typeof root.animate !== 'function'
    ) {
      pendingMutationMotionRef.current = null;
      return;
    }

    const expectedKeys = nextValue.map(item => String(getItemKey(item)));
    const pendingMotion: PendingMutationMotion<T> = {
      before: captureMutationLayout(root, activeMutationAnimationsRef.current),
      duration: mutationDuration,
      easing: mutationEasing,
      entryOffset: mutationEntryOffset,
      matchesValue: candidate =>
        candidate.length === expectedKeys.length &&
        candidate.every(
          (item, index) => String(getItemKey(item)) === expectedKeys[index],
        ),
    };
    pendingMutationMotionRef.current = pendingMotion;
    window.setTimeout(() => {
      // Delayed controlled updates cannot safely reuse viewport measurements
      // from the originating interaction. Synchronous updates consume the
      // snapshot in the layout effect before the next task.
      if (pendingMutationMotionRef.current === pendingMotion) {
        pendingMutationMotionRef.current = null;
      }
    }, 0);
  };

  const prepareAddScrollAnchor = (
    nextValue: T[],
    itemKey: string,
    pointerDownTop?: number,
  ) => {
    const addAction = addActionRef.current;
    if (addAction == null) {
      pendingAddScrollAnchorRef.current = null;
      return;
    }

    const pendingAnchor: PendingAddScrollAnchor = {
      addTop: pointerDownTop ?? addAction.getBoundingClientRect().top,
      expectedKeys: nextValue.map(item => String(getItemKey(item))),
      itemKey,
    };
    pendingAddScrollAnchorRef.current = pendingAnchor;
    window.setTimeout(() => {
      // Controlled updates that arrive in a later task cannot safely reuse a
      // pointer position captured during the originating click.
      if (pendingAddScrollAnchorRef.current === pendingAnchor) {
        pendingAddScrollAnchorRef.current = null;
      }
    }, 0);
  };

  const handleAddPointerDown = (
    event: React.PointerEvent<HTMLButtonElement>,
  ) => {
    if (
      event.button !== 0 ||
      !event.isPrimary ||
      mutationsDisabled ||
      hasReachedMax
    ) {
      addPointerAnchorTopRef.current = null;
      return;
    }
    addPointerAnchorTopRef.current =
      addActionRef.current?.getBoundingClientRect().top ?? null;
  };

  const handleAdd = (event: React.MouseEvent<HTMLButtonElement>) => {
    if (mutationsDisabled || hasReachedMax) {
      return;
    }
    const item = createItem();
    const nextValue = [...value, item];
    const itemKey = String(getItemKey(item));
    pendingFocusRef.current = {
      itemKey,
      target: 'first-field',
    };
    if (event.detail > 0) {
      prepareAddScrollAnchor(
        nextValue,
        itemKey,
        addPointerAnchorTopRef.current ?? undefined,
      );
    } else {
      pendingAddScrollAnchorRef.current = null;
    }
    addPointerAnchorTopRef.current = null;
    prepareMutationMotion(nextValue);
    onChange(nextValue, {type: 'add', item, index: value.length});
    announce(
      t('@astryx.listInput.announceAdded', {
        itemName,
        position: value.length + 1,
      }),
    );
  };

  const handleUpdate = (
    item: T,
    index: number,
    nextItem: T,
    columnKey?: string,
  ) => {
    if (mutationsDisabled) {
      return;
    }
    const nextValue = value.slice();
    nextValue[index] = nextItem;
    onChange(nextValue, {
      type: 'update',
      item: nextItem,
      previousItem: item,
      index,
      columnKey,
    });
  };

  const handleRemove = (item: T) => {
    if (mutationsDisabled) {
      return;
    }
    const itemKey = String(getItemKey(item));
    const index = value.findIndex(
      candidate => String(getItemKey(candidate)) === itemKey,
    );
    if (index < 0) {
      return;
    }
    const removedItem = value[index];
    const nextValue = value.filter((_, itemIndex) => itemIndex !== index);
    const nextFocusItem = nextValue[Math.min(index, nextValue.length - 1)];
    pendingFocusRef.current =
      nextFocusItem == null
        ? {target: 'add'}
        : {itemKey: String(getItemKey(nextFocusItem)), target: 'remove'};
    prepareMutationMotion(nextValue);
    onChange(nextValue, {type: 'remove', item: removedItem, index});
    announce(
      t('@astryx.listInput.announceRemoved', {itemName, position: index + 1}),
    );
  };

  const rowLayoutStyle = showReorderHandle
    ? styles.rowWithRemoveAndHandle
    : showRemoveColumn
      ? styles.rowWithRemove
      : styles.rowFieldsOnly;
  const contentGridStyle = showRemoveColumn
    ? styles.contentBeforeOneControl
    : styles.contentOnly;
  return (
    <SizeProvider value="md">
      <Field
        ref={ref}
        label={label}
        description={description}
        inputID={groupID}
        labelID={labelID}
        descriptionID={descriptionID}
        isGroupLabel
        isLabelHidden={isLabelHidden}
        isOptional={isOptional}
        isRequired={isRequired}
        isDisabled={isDisabled}
        status={status == null ? undefined : {...status, messageID: statusID}}
        statusVariant="detached"
        {...rest}>
        <div
          ref={groupRef}
          id={groupID}
          role="group"
          aria-labelledby={labelID}
          aria-describedby={joinIDs(descriptionID, statusID)}
          aria-disabled={isDisabled || undefined}
          aria-busy={isLoading || undefined}
          {...mergeProps(
            themeProps('list-input', {
              state: isLoading
                ? 'loading'
                : isDisabled
                  ? 'disabled'
                  : undefined,
              reorderable: showReorderHandle ? 'true' : undefined,
            }),
            stylex.props(styles.group),
          )}>
          <ListReorderScope reorder={reorderScope}>
            <ol
              ref={listRef}
              role="list"
              aria-labelledby={labelID}
              aria-describedby={joinIDs(descriptionID, statusID)}
              {...stylex.props(
                styles.list,
                // The session's line marks where a dragged record would land.
                reorderScope?.session.listStyle,
              )}>
              {value.length === 0 ? (
                <li
                  data-list-input-motion-key="state:empty"
                  {...stylex.props(styles.emptyItem)}>
                  <EmptyState
                    title={t('@astryx.listInput.emptyTitle', {itemName})}
                    description={t('@astryx.listInput.emptyDescription', {
                      itemName,
                    })}
                    isCompact
                  />
                </li>
              ) : (
                value.map((item, index) => {
                  const itemKey = getItemKey(item);
                  const itemKeyString = String(itemKey);
                  // A record the owner's isReorderable rejects keeps its
                  // place, with no handle.
                  const hasHandle =
                    showReorderHandle && (canReorder?.(itemKey) ?? true);
                  const itemStatus = getItemStatus?.(item, index);
                  const itemStatusID = itemStatus?.message
                    ? `${groupID}-item-${index}-status`
                    : undefined;
                  return (
                    <li
                      key={itemKey}
                      data-list-input-motion-key={`item:${itemKeyString}`}
                      aria-describedby={itemStatusID}
                      aria-invalid={itemStatus?.type === 'error' || undefined}
                      aria-posinset={index + 1}
                      aria-setsize={value.length}
                      {...stylex.props(
                        styles.item,
                        hasHandle && reorderScope?.session.rowStyle,
                      )}>
                      <div
                        ref={node => {
                          if (node == null) {
                            rowRefs.current.delete(itemKeyString);
                          } else {
                            rowRefs.current.set(itemKeyString, node);
                          }
                        }}
                        data-list-input-row={itemKeyString}
                        {...mergeProps(
                          getContainerProps(),
                          stylex.props(styles.row, rowLayoutStyle),
                        )}>
                        <div
                          {...stylex.props(
                            styles.fields,
                            dynamicStyles.fields(fieldGridTemplate),
                          )}>
                          {columns.map((column, columnIndex) => {
                            const fieldStatus = getFieldStatus?.(
                              item,
                              column.key,
                              index,
                            );
                            const isRepeatedLabel = index !== 0;
                            const cellLabel = isRepeatedLabel
                              ? t('@astryx.listInput.fieldLabelWithPosition', {
                                  header: column.header,
                                  itemName,
                                  position: index + 1,
                                  total: value.length,
                                })
                              : column.header;
                            const valueContext: ListInputValueContext<T> = {
                              item,
                              index,
                              label: cellLabel,
                              isLabelHidden: true,
                            };
                            const content = column.renderInput({
                              ...valueContext,
                              status: fieldStatus,
                              statusVariant: 'tooltip',
                              isDisabled: isDisabled || isLoading,
                              isLoading,
                              updateItem: (nextItem, changeColumnKey) =>
                                handleUpdate(
                                  item,
                                  index,
                                  nextItem,
                                  changeColumnKey ?? column.key,
                                ),
                            });
                            return (
                              <div
                                key={column.key}
                                data-list-input-cell={String(columnIndex)}
                                {...stylex.props(
                                  styles.cellContent,
                                  styles.fieldCell,
                                )}>
                                <span
                                  aria-hidden="true"
                                  data-list-input-column-label={
                                    isRepeatedLabel ? 'responsive' : 'primary'
                                  }
                                  {...stylex.props(
                                    styles.columnLabel,
                                    isRepeatedLabel &&
                                      styles.repeatedColumnLabel,
                                  )}>
                                  {column.header}
                                </span>
                                <div {...stylex.props(styles.cellContent)}>
                                  {content}
                                </div>
                              </div>
                            );
                          })}
                        </div>
                        {showRemoveColumn ? (
                          <div
                            {...mergeProps(
                              // Opacity only: Remove and the reorder handle keep
                              // their places, so the fields never shift when
                              // they appear.
                              getContentRevealProps({isLayoutPreserved: true}),
                              stylex.props(
                                styles.controlCell,
                                styles.removeControlCell,
                              ),
                            )}>
                            <IconButton
                              label={t('@astryx.listInput.removeItem', {
                                itemName,
                                position: index + 1,
                              })}
                              tooltip={
                                isDisabled || isLoading
                                  ? t('@astryx.listInput.removeUnavailable', {
                                      itemName,
                                    })
                                  : t('@astryx.listInput.removeItem', {
                                      itemName,
                                      position: index + 1,
                                    })
                              }
                              icon={<Icon icon="close" size="sm" />}
                              variant="ghost"
                              size="md"
                              isDisabled={isDisabled || isLoading}
                              data-list-input-remove=""
                              onClick={() => handleRemove(item)}
                            />
                            {Handle != null && hasHandle ? (
                              // Named "Reorder guest 2", like Remove.
                              <Handle
                                label={t('@astryx.listInput.itemName', {
                                  itemName,
                                  position: index + 1,
                                })}
                                itemKey={itemKey}
                                isDisabled={isDisabled || isLoading}
                              />
                            ) : null}
                          </div>
                        ) : null}
                        {itemStatus?.message ? (
                          <FieldStatus
                            id={itemStatusID}
                            type={itemStatus.type}
                            message={itemStatus.message}
                            variant="detached"
                            data-list-input-item-status=""
                            xstyle={[styles.itemStatus, contentGridStyle]}
                          />
                        ) : null}
                      </div>
                    </li>
                  );
                })
              )}
            </ol>
          </ListReorderScope>
          <div
            ref={addActionRef}
            data-list-input-motion-key="action:add"
            {...stylex.props(styles.actionRow, rowLayoutStyle)}>
            <div
              data-list-input-add-content=""
              {...stylex.props(styles.actionContent, contentGridStyle)}>
              <Button
                ref={addButtonRef}
                label={t('@astryx.listInput.addItem', {itemName})}
                variant="secondary"
                size="md"
                width="100%"
                isDisabled={isDisabled || hasReachedMax}
                isLoading={isLoading}
                onPointerDown={handleAddPointerDown}
                onPointerCancel={() => {
                  addPointerAnchorTopRef.current = null;
                }}
                onClick={handleAdd}
              />
            </div>
          </div>
        </div>
      </Field>
    </SizeProvider>
  );
}

ListInput.displayName = 'ListInput';