Skip to content

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

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

'use client';

/**
 * @file useTableRowExpansion.tsx
 * @input React, StyleX, Icon, the theme's `table-row-expand` icon slot, Table
 *   types, table context (density), i18n
 *   (useComponentTranslator)
 * @output Exports useTableRowExpansion hook + config type
 * @position Row-expansion plugin (detail panel); consumed by Table via plugins prop
 *
 * Expands a full-width detail panel below a row, rendered by the consumer's
 * `renderExpanded(item)`. For hierarchical/tree tables (child rows that reuse
 * the parent columns) use `useTableTreeData` + `useTableTreeState` instead.
 *
 * SYNC: When modified, update these files to stay in sync:
 * - /packages/core/src/Table/index.ts (exports)
 * - /packages/core/src/Table/useTableRowExpansion.doc.mjs
 */

import {
  useCallback,
  useLayoutEffect,
  useMemo,
  useRef,
  type ReactNode,
  type RefObject,
} from 'react';
import * as stylex from '@stylexjs/stylex';
import {
  spacingVars,
  colorVars,
  radiusVars,
  borderVars,
  durationVars,
  easeVars,
} from '../../../theme/tokens.stylex';
import {tableRowMarker} from '../../table.stylex';
import {panelDividerFor} from '../../rowDivider';
import {useTheme, useThemeName} from '../../../theme/useTheme';
import {Icon} from '../../../Icon';
import {ComponentIcon} from '../../../Icon/ComponentIcon';
import {iconBoxSizeStyles} from '../../../Icon/IconSize.stylex';
import {VisuallyHidden} from '../../../VisuallyHidden';
import {resolveContextActions} from '../../tableContextMenu';
import {useTableContext} from '../../useTableCellStyles';
import {rtlStyles} from '../../../utils';
import {
  hasInteractiveAncestor,
  hasTextSelection,
} from '../../../hooks/useClickableContainer';
import type {
  TablePlugin,
  TableColumn,
  BodyRowRenderProps,
  BodyCellRenderProps,
  HeaderCellRenderProps,
  ScrollWrapperRenderProps,
} from '../../types';
import {LayoutChangeSnapshot} from '../../../motion/LayoutChangeSnapshot';
import {
  applyLayoutChangeTransition,
  glideOf,
  playLayoutChange,
  reportLayoutChange,
  type AnimatedLayout,
  type LayoutChange,
} from '../../../motion/animatedLayout';
import {
  dividerOffset,
  GLIDING_ATTRIBUTE,
  glidingDividerStyles,
  markGlidingRows,
  rowEdge,
  type BottomEdge,
} from '../../glidingDivider';
import {
  registerEnglishFallback,
  useComponentTranslator,
} from '../../../i18n/useComponentTranslator';
import english from '../../../i18n/generated-english/Table/plugins/rowExpansion/useTableRowExpansion.generated';

registerEnglishFallback(english);

// =============================================================================
// Config
// =============================================================================

/**
 * Configuration for useTableRowExpansion (detail-panel mode).
 *
 * The consumer owns expansion state; the plugin provides the chevron UI, the
 * full-width detail panel rendered below an expanded row, and a right-click
 * "Expand/Collapse row" action.
 */
export interface UseTableRowExpansionConfig<T extends Record<string, unknown>> {
  /** Set of currently-expanded row keys. */
  expandedKeys: Set<string>;
  /** Called with a row key when its expansion is toggled. */
  onToggle: (key: string) => void;
  /** Derive a stable unique key from a row item. */
  getRowKey: (item: T) => string;
  /**
   * Render the detail content shown in a full-width panel below the row when
   * it is expanded. Receives the row's item.
   */
  renderExpanded: (item: T) => ReactNode;
  /**
   * Derive a human-readable row identity for the expansion control's accessible
   * name. The plugin combines it with localized expand/collapse wording. Blank
   * labels fall back to the generic row label.
   *
   * @example
   * ```
   * getRowLabel: item => item.name
   * ```
   */
  getRowLabel?: (item: T) => string;
  /**
   * Control which rows are expandable. Non-expandable rows show no chevron, no
   * context-menu action, and never render a panel. @default all rows expandable
   */
  getIsItemExpandable?: (item: T) => boolean;
  /**
   * Background behind the detail panel.
   *
   * - `transparent` (default): the panel paints nothing and takes whatever
   *   surface is behind the table. The panel is the row's own continuation,
   *   so it inherits the table's background the way the row does, and on a
   *   striped table the zebra reads on unchanged — a panel is not a row, and
   *   is not counted as one.
   * - `muted`: a wash marking the panel as commentary on the row above rather
   *   than another row of data. Reach for it in a bare table — no card, no
   *   dividers, no striping — where nothing else distinguishes the panel from
   *   the data around it. It is an opt-in, not the house style: a table on a
   *   Card gets a third surface out of it, and a striped table gets a band in
   *   the same token as the stripe, which reads as a data row.
   *
   * Worth knowing when choosing: the wash is a low-alpha near-black, so over a
   * dark card it is close to invisible. `muted` is largely a light-theme
   * effect, and dark themes look like `transparent` either way.
   * @default 'transparent'
   */
  panelVariant?: 'muted' | 'transparent';
  /**
   * Toggle a row by clicking anywhere on it, not only on its chevron.
   *
   * This is a pointer-only convenience layered over the chevron: keyboard and
   * assistive-tech users toggle via the chevron button (which stays the
   * accessible control). Clicks originating from interactive cell content
   * (buttons, links, form controls) or a text selection do not toggle.
   * Non-expandable rows stay inert.
   * @default false (only the chevron toggles expansion).
   */
  hasRowClickExpansion?: boolean;
  /**
   * A handle from `useAnimatedLayout`. With it, opening or closing a row's
   * panel glides the rows after it to their new places instead of jumping,
   * and an opening panel plays its entrance on the same motion. Without it,
   * rows jump, as before.
   */
  animatedLayout?: AnimatedLayout;
}

// =============================================================================
// Styles
// =============================================================================

/**
 * The chevron column's width, in pixels.
 *
 * A column width is a number the layout does arithmetic on, not a CSS value,
 * so this stays a fixed pixel width at every root font size. The panel's
 * indent, which has to line up with the first real column, spells the same
 * pixels rather than a spacing token: spacing is rem and grows with the root
 * font size, which would push the panel past the column it lines up with. The
 * unit test pins the two together so neither can move without the other.
 */
const EXPANSION_COLUMN_WIDTH_PX = 40;
const EXPANSION_COLUMN_KEY = '__expansion';
/** The chevron button: the spacing step, never wider than its column. */
const CHEVRON_SIZE = `min(${spacingVars['--spacing-6']}, ${EXPANSION_COLUMN_WIDTH_PX}px)`;
const EXPANSION_COLUMN_WIDTH = {
  type: 'pixel' as const,
  value: EXPANSION_COLUMN_WIDTH_PX,
};

const expansionStyles = stylex.create({
  chevronButton: {
    display: 'inline-flex',
    alignItems: 'center',
    justifyContent: 'center',
    width: CHEVRON_SIZE,
    height: CHEVRON_SIZE,
    backgroundColor: 'transparent',
    borderWidth: 0,
    borderStyle: 'none',
    borderRadius: radiusVars['--radius-inner'],
    cursor: {
      default: 'pointer',
      ':is(:disabled,[aria-disabled="true"])': 'default',
    },
    color: colorVars['--color-icon-secondary'],
    // Colour only. The rotation belongs to the glyph, not to the button: the
    // button is the hit target and carries the hover chip, and turning that
    // swings the rounded rectangle and its highlight around with the arrow.
    transitionProperty: 'color',
    transitionDuration: durationVars['--duration-fast'],
    transitionTimingFunction: easeVars['--ease-standard'],
    padding: 0,
    // Match IconButton ghost hover: subtle overlay background.
    backgroundImage: {
      default: null,
      ':hover:where(:not(:disabled,[aria-disabled="true"]))': {
        '@media (hover: hover)': `linear-gradient(${colorVars['--color-overlay-hover']}, ${colorVars['--color-overlay-hover']})`,
      },
    },
    ':hover:where(:not(:disabled,[aria-disabled="true"]))': {
      color: colorVars['--color-icon-primary'],
    },
  },
  // The button takes its baseline from this fixed box. A theme's glyph size
  // or a hidden glyph then keeps the row height. The box is the toggle's
  // first child, which the glide gives its spring, so it carries the turn.
  glyphBox: {
    display: 'inline-block',
    position: 'relative',
    flexShrink: 0,
  },
  glyphCenter: {
    position: 'absolute',
    inset: 0,
    display: 'flex',
    alignItems: 'center',
    justifyContent: 'center',
  },
  chevron: {
    transitionProperty: 'transform',
    transitionDuration: durationVars['--duration-fast'],
    transitionTimingFunction: easeVars['--ease-standard'],
  },
  // The RTL mirror is folded into each state's transform rather than living
  // on a parent span, matching TreeListItem's chevron (both are `transform`,
  // so on one element the later value would win).
  chevronExpanded: {
    transform: {
      default: 'rotate(90deg)',
      ':is([dir="rtl"] *)': 'scaleX(-1) rotate(90deg)',
    },
  },
  chevronCollapsed: {
    transform: {
      default: 'rotate(0deg)',
      ':is([dir="rtl"] *)': 'scaleX(-1) rotate(0deg)',
    },
  },
  // The wash goes on the panel's cell, not on its row. A row that paints its
  // own box plays in under a clip that moves with its edge. On iOS that clip
  // can trail the rows that glide below it. The cell slides in with the
  // panel's content.
  mutedPanel: {
    backgroundColor: colorVars['--color-background-muted'],
  },
  expandedCell: {
    paddingBlock: spacingVars['--spacing-4'],
    paddingInlineEnd: spacingVars['--spacing-5'],
  },
  /** Whole-row-click expansion: signal the row is interactive. */
  clickableRow: {
    cursor: {
      default: 'pointer',
      ':is(:disabled,[aria-disabled="true"])': 'default',
    },
  },
});

/**
 * An expanded row and its panel are one unit, so the row divider belongs after
 * the pair rather than between them — left alone, the row's own bottom border
 * draws a line cutting it off from the detail it just opened, and the panel
 * then runs flush into the next row, which is the wrong way round.
 *
 * So the row gives up its border and the panel takes one. On a table with no
 * row dividers the suppression is a no-op (there was no border to remove) and
 * the panel's is never applied, so neither needs to consult the divider mode.
 */
const dividerStyles = stylex.create({
  expandedRowCell: {
    '--_table-row-divider-width': '0px',
    borderBottomWidth: 0,
  },
  // The row's divider, carried down: its row's themed or app-set border
  // reaches the panel through `--_table-panel-divider-*` on the panel's cell
  // (set after each commit, see ExpansionPanelCell), the tokens otherwise.
  panelCell: {
    // The width this divider draws, for its stand-in during a glide.
    '--_table-row-divider-width': {
      default: `var(--_table-panel-divider-width, ${borderVars['--border-width']})`,
      [stylex.when.ancestor(':last-child', tableRowMarker)]: '0px',
    },
    borderBottomWidth: {
      default: `var(--_table-panel-divider-width, ${borderVars['--border-width']})`,
      // Same rule TableCell uses: no trailing line under the last row of the
      // table. Scoped to the marker so <tbody>, also a :last-child, does not
      // match and suppress every panel's border.
      [stylex.when.ancestor(':last-child', tableRowMarker)]: '0',
    },
    borderBottomStyle: 'var(--_table-panel-divider-style, solid)',
    borderBottomColor: `var(--_table-panel-divider-color, ${colorVars['--color-border']})`,
  },
});

/**
 * Start inset for the detail panel, one per density.
 *
 * The panel is one cell spanning the whole row, so left to itself its content
 * starts at the row's edge — under the chevron, a column to the left of every
 * label it describes. These line it up with the first real column instead: the
 * chevron column's fixed width, plus the inline padding a cell of that density
 * gives its own content.
 *
 * Written as a logical property so RTL mirrors it, and kept in `calc` so the
 * padding half still tracks the spacing scale, as the cell's own padding does.
 */
const panelIndentStyles = stylex.create({
  compact: {
    paddingInlineStart: `calc(${EXPANSION_COLUMN_WIDTH_PX}px + ${spacingVars['--spacing-2']})`,
  },
  balanced: {
    paddingInlineStart: `calc(${EXPANSION_COLUMN_WIDTH_PX}px + ${spacingVars['--spacing-3']})`,
  },
  spacious: {
    paddingInlineStart: `calc(${EXPANSION_COLUMN_WIDTH_PX}px + ${spacingVars['--spacing-4']})`,
  },
});

/**
 * The chevron sits centered in its column, as the selection checkbox does.
 *
 * The column is a fixed pixel width, but its cells' insets follow the spacing
 * scale: the first column's edge inset, plus the density padding a body cell
 * moves onto its right-click trigger. Laid out after both, the button ran past
 * the column's edge, which clips its hover chip and, under a larger spacing
 * scale or root font size, pushes the glyph out of view; and the header cell's
 * insets alone outgrow 40px at a large root, widening the column. So the
 * header cell, which holds only a visually hidden label, drops its inline
 * insets, the body cell drops its inline-start inset, and the button cancels
 * the trigger's padding (the same density step the panel indent uses) and
 * centers itself.
 */
const chevronHeaderCellStyles = stylex.create({
  cell: {
    paddingInlineStart: 0,
    paddingInlineEnd: 0,
  },
});

const chevronCellStyles = stylex.create({
  cell: {
    paddingInlineStart: 0,
  },
});

const chevronOffsetStyles = stylex.create({
  compact: {
    marginInlineStart: `calc((${EXPANSION_COLUMN_WIDTH_PX}px - ${CHEVRON_SIZE}) / 2 - ${spacingVars['--spacing-2']})`,
  },
  balanced: {
    marginInlineStart: `calc((${EXPANSION_COLUMN_WIDTH_PX}px - ${CHEVRON_SIZE}) / 2 - ${spacingVars['--spacing-3']})`,
  },
  spacious: {
    marginInlineStart: `calc((${EXPANSION_COLUMN_WIDTH_PX}px - ${CHEVRON_SIZE}) / 2 - ${spacingVars['--spacing-4']})`,
  },
});

// =============================================================================
// Chevron Cell
// =============================================================================

function ExpansionChevron({
  rowLabel,
  isExpanded,
  onToggle,
}: {
  rowLabel?: string;
  isExpanded: boolean;
  onToggle: () => void;
}) {
  const t = useComponentTranslator();
  const ariaLabel = rowLabel
    ? isExpanded
      ? t('@astryx.tableRowExpansion.collapseRowNamed', {label: rowLabel})
      : t('@astryx.tableRowExpansion.expandRowNamed', {label: rowLabel})
    : isExpanded
      ? t('@astryx.tableRowExpansion.collapseRow')
      : t('@astryx.tableRowExpansion.expandRow');
  const ctx = useTableContext();
  return (
    <button
      type="button"
      data-expansion-toggle=""
      {...stylex.props(
        expansionStyles.chevronButton,
        chevronOffsetStyles[ctx?.density ?? 'balanced'],
      )}
      onClick={e => {
        e.stopPropagation();
        onToggle();
      }}
      aria-label={ariaLabel}
      aria-expanded={isExpanded}>
      <span
        {...stylex.props(
          expansionStyles.glyphBox,
          iconBoxSizeStyles.xsm,
          expansionStyles.chevron,
          isExpanded
            ? expansionStyles.chevronExpanded
            : expansionStyles.chevronCollapsed,
        )}>
        <span {...stylex.props(expansionStyles.glyphCenter)}>
          <ComponentIcon
            slot="table-row-expand"
            state={{expanded: isExpanded}}
            fallback={{icon: 'chevronRight', size: 'xsm'}}
          />
        </span>
      </span>
    </button>
  );
}

const PANEL_DIVIDER_PROPERTIES = [
  '--_table-panel-divider-width',
  '--_table-panel-divider-style',
  '--_table-panel-divider-color',
] as const;

/**
 * Carries the row's divider onto a panel cell where an override makes it
 * differ from what the panel paints on its own (the divider tokens, in CSS),
 * and carries nothing otherwise, so a later token or theme change reaches
 * the panel the way it reaches the row.
 */
function carryPanelDivider(cell: HTMLTableCellElement): void {
  const row = cell.parentElement?.previousElementSibling;
  const edge = row == null ? null : panelDividerFor(row);
  if (edge == null) {
    return;
  }
  // What the panel paints with nothing carried.
  const carried = PANEL_DIVIDER_PROPERTIES.map(name =>
    cell.style.getPropertyValue(name),
  );
  if (carried.some(value => value !== '')) {
    for (const name of PANEL_DIVIDER_PROPERTIES) {
      cell.style.removeProperty(name);
    }
  }
  const own = getComputedStyle(cell);
  const isOverride =
    edge.color !== own.borderBottomColor ||
    edge.style !== own.borderBottomStyle ||
    (edge.width !== 'initial' && edge.width !== own.borderBottomWidth);
  if (!isOverride) {
    return;
  }
  const next = [edge.width, edge.style, edge.color];
  PANEL_DIVIDER_PROPERTIES.forEach((name, index) => {
    cell.style.setProperty(name, next[index]);
  });
}

/**
 * One per table: when the colour mode or the theme changes (a Theme's, or
 * the operating system's mode under `system`) the open panels' carried
 * dividers are read again. The panels register their cells with the hook.
 */
function PanelDividerModeWatch({
  cellsRef,
}: {
  cellsRef: RefObject<Set<HTMLTableCellElement>>;
}) {
  const {mode} = useTheme();
  const themeName = useThemeName();
  const lastRef = useRef({mode, themeName});
  // Syncs the panel dividers with the computed theme CSS after a color mode or
  // theme change.
  useLayoutEffect(() => {
    const last = lastRef.current;
    if (last.mode === mode && last.themeName === themeName) {
      return;
    }
    lastRef.current = {mode, themeName};
    for (const cell of cellsRef.current) {
      carryPanelDivider(cell);
    }
  }, [mode, themeName, cellsRef]);
  return null;
}

/**
 * The detail panel's cell. A component rather than a bare `<td>` so it can
 * read the table's density and divider mode off the context — to indent itself
 * to match the first column, and to carry the row divider its own row gave up.
 * The plugin builds this row outside the Table's own render, where that
 * context is not otherwise in hand.
 */
function ExpansionPanelCell({
  colSpan,
  cellsRef,
  isMuted,
  children,
}: {
  colSpan: number;
  cellsRef: RefObject<Set<HTMLTableCellElement>>;
  isMuted: boolean;
  children: ReactNode;
}) {
  const ctx = useTableContext();
  const hasRowDividers = ctx?.dividers === 'rows' || ctx?.dividers === 'grid';
  const cellRef = useRef<HTMLTableCellElement>(null);
  // The panel carries its row's divider (a theme's `table-cell` border or an
  // app's own never reach this cell, which is not one of the row's cells).
  // Read after each commit, and on a colour-mode change by the table's one
  // PanelDividerModeWatch.
  useLayoutEffect(() => {
    const cell = cellRef.current;
    const row = cell?.parentElement?.previousElementSibling;
    if (cell == null || row == null || !hasRowDividers) {
      return;
    }
    if (!row.hasAttribute(GLIDING_ATTRIBUTE)) {
      carryPanelDivider(cell);
      return;
    }
    // A row a glide is moving has transparent cells until it ends: the
    // panel reads its row once the glide has let it go.
    let frame = 0;
    const carryWhenStill = () => {
      if (row.hasAttribute(GLIDING_ATTRIBUTE)) {
        frame = requestAnimationFrame(carryWhenStill);
        return;
      }
      carryPanelDivider(cell);
    };
    frame = requestAnimationFrame(carryWhenStill);
    return () => cancelAnimationFrame(frame);
  });
  useLayoutEffect(() => {
    const cell = cellRef.current;
    if (cell == null || !hasRowDividers) {
      return;
    }
    const cells = cellsRef.current;
    cells.add(cell);
    return () => {
      cells.delete(cell);
    };
  }, [cellsRef, hasRowDividers]);
  return (
    <td
      ref={cellRef}
      colSpan={colSpan}
      {...stylex.props(
        expansionStyles.expandedCell,
        isMuted && expansionStyles.mutedPanel,
        panelIndentStyles[ctx?.density ?? 'balanced'],
        hasRowDividers && dividerStyles.panelCell,
        glidingDividerStyles.cell,
        hasRowDividers && glidingDividerStyles.panelCell,
      )}>
      {children}
    </td>
  );
}

/**
 * Measures each expansion change for the glide, except in a table with
 * column lines (`dividers` "columns" or "grid"): they are painted at the
 * cells' static places too, and only row dividers have a moving stand-in, so
 * such a table changes at once, panel, rows and chevron, as without a handle
 * (component:Table FR15).
 */
function ExpansionSnapshot({
  value,
  onBeforeChange,
  onColumnLines,
}: {
  value: Set<string>;
  onBeforeChange: (previous: Set<string>) => void;
  /** The chevrons drop a spring an earlier glide set on them. */
  onColumnLines: () => void;
}) {
  const ctx = useTableContext();
  const hasColumnLines =
    ctx?.dividers === 'grid' || ctx?.dividers === 'columns';
  useLayoutEffect(() => {
    if (hasColumnLines) {
      onColumnLines();
    }
  }, [hasColumnLines, onColumnLines]);
  if (hasColumnLines) {
    return null;
  }
  return <LayoutChangeSnapshot value={value} onBeforeChange={onBeforeChange} />;
}

// =============================================================================
// Hook
// =============================================================================

/**
 * Returns a TablePlugin that expands a full-width detail panel below a row.
 *
 * The consumer owns the `expandedKeys` set (via `useState`); the plugin adds
 * a leading chevron column, a right-click expand/collapse action, and renders
 * `renderExpanded(item)` in a full-width panel below each expanded row.
 *
 * For hierarchical data (child rows sharing the parent columns) use
 * `useTableTreeData` + `useTableTreeState` instead.
 *
 * @example
 * ```
 * const [expandedKeys, setExpandedKeys] = useState<Set<string>>(new Set());
 * const expansion = useTableRowExpansion({
 *   expandedKeys,
 *   onToggle: key =>
 *     setExpandedKeys(prev => {
 *       const next = new Set(prev);
 *       next.has(key) ? next.delete(key) : next.add(key);
 *       return next;
 *     }),
 *   getRowKey: item => item.id,
 *   getRowLabel: item => item.name,
 *   renderExpanded: item => <OrderDetails order={item} />,
 * });
 * <Table data={data} columns={columns} idKey="id" plugins={{expansion}} />;
 * ```
 */
export function useTableRowExpansion<T extends Record<string, unknown>>(
  config: UseTableRowExpansionConfig<T>,
): TablePlugin<T> {
  const {
    expandedKeys,
    onToggle,
    getRowKey,
    renderExpanded,
    getRowLabel,
    getIsItemExpandable,
    hasRowClickExpansion,
    panelVariant = 'transparent',
    animatedLayout,
  } = config;

  const t = useComponentTranslator();

  // Final rendered column count, captured in transformColumns (pipeline step
  // 1) and read in transformBodyRow for the detail panel's colSpan.
  const columnCountRef = useRef(1);
  // The open panels' cells, for the table's one colour-mode watch.
  const panelCellsRef = useRef(new Set<HTMLTableCellElement>());

  // With an `animatedLayout` handle, a panel opening or closing glides the
  // rows after it (`spec:AST-105`, `architecture:react-component-runtime`
  // INV12). LayoutChangeSnapshot measures each changed row in the commit,
  // before the DOM changes; the layout effect below runs the glide after it.
  const scrollWrapperRef = useRef<HTMLDivElement | null>(null);
  // The scroll wrapper's merged ref, kept while the inner ref is the same.
  const mergedScrollWrapperRef = useRef<{
    inner: ScrollWrapperRenderProps['htmlProps']['ref'] | null;
    merged: (node: HTMLDivElement | null) => void;
  } | null>(null);
  const pendingLayoutRef = useRef<
    {change: LayoutChange; key: string; isExpanding: boolean}[]
  >([]);
  // The height the closing panels gave up (read with the measurement), and
  // the height the scroll wrapper holds while rows glide up into it (see the
  // layout effect).
  const closedHeightRef = useRef(0);
  const heldHeightRef = useRef(0);
  const holdBaseRef = useRef<{padding: number; margin: number} | null>(null);
  // This table's own body rows only: a table nested in a panel can reuse the
  // same row keys. The first table in the wrapper is this one.
  const rowFor = useCallback(
    (key: string) =>
      scrollWrapperRef.current
        ?.querySelector('table')
        ?.querySelector<HTMLElement>(
          `:scope > tbody > tr[data-expansion-key="${CSS.escape(key)}"]`,
        ) ?? null,
    [],
  );
  const measureChanges = useCallback(
    (previous: Set<string>) => {
      if (animatedLayout == null) {
        return;
      }
      const changed = [
        ...[...previous].filter(key => !expandedKeys.has(key)),
        ...[...expandedKeys].filter(key => !previous.has(key)),
      ];
      for (const key of changed) {
        const row = rowFor(key);
        if (row == null) {
          continue;
        }
        const change = reportLayoutChange(animatedLayout, () => row);
        change.measureBefore();
        // A closing panel's height, read in the same layout the measurement
        // just read.
        const panel = row.nextElementSibling;
        if (
          !expandedKeys.has(key) &&
          panel?.hasAttribute('data-expansion-panel') === true
        ) {
          closedHeightRef.current += panel.getBoundingClientRect().height;
          // The wrapper's own bottom padding and margin (a container's
          // bleed), which the hold adds to rather than replaces.
          const wrapper = scrollWrapperRef.current;
          if (wrapper != null && holdBaseRef.current == null) {
            const style = getComputedStyle(wrapper);
            holdBaseRef.current = {
              padding: parseFloat(style.paddingBlockEnd) || 0,
              margin: parseFloat(style.marginBlockEnd) || 0,
            };
          }
        }
        // The chevron turns on the glide's motion (component:Table FR15);
        // written after the measurement so the read finds the layout clean.
        applyLayoutChangeTransition(
          animatedLayout,
          row.querySelector<HTMLElement>('[data-expansion-toggle] > *'),
        );
        pendingLayoutRef.current.push({
          change,
          key,
          isExpanding: expandedKeys.has(key),
        });
      }
    },
    [animatedLayout, expandedKeys, rowFor],
  );
  // The chevrons back on the theme's own turn: a spring a handle set stays
  // only while the glide runs (`spec:AST-105` FR2), so it goes without a
  // handle and in a table with column lines.
  const resetChevrons = useCallback(() => {
    const table = scrollWrapperRef.current?.querySelector('table');
    for (const glyph of table?.querySelectorAll<HTMLElement>(
      '[data-expansion-toggle] > *',
    ) ?? []) {
      // This table's chevrons, not a nested table's.
      if (glyph.closest('table') === table) {
        applyLayoutChangeTransition(null, glyph);
      }
    }
  }, []);
  // Syncs the chevron transitions with the `animatedLayout` handle. Without a
  // handle, the chevrons use the theme's turn.
  useLayoutEffect(() => {
    if (animatedLayout == null) {
      resetChevrons();
    }
  }, [animatedLayout, resetChevrons]);

  useLayoutEffect(() => {
    const pendings = pendingLayoutRef.current;
    pendingLayoutRef.current = [];
    // The rows that changed, each with the panel it opened (if that panel
    // plays in) and the borders of the rows the glide may move.
    const moved: {
      row: HTMLElement;
      panel: HTMLElement | null;
      entrance: Animation | null;
      panelOffset: number | null;
      edges: Map<Element, BottomEdge>;
    }[] = [];
    for (const pending of pendings) {
      const row = rowFor(pending.key);
      if (row == null) {
        pending.change.animate();
        continue;
      }
      const next = row.nextElementSibling;
      // Filled in by beforeMove, during the glide's own microtask.
      const record = {
        row,
        panel:
          pending.isExpanding &&
          next instanceof HTMLElement &&
          next.hasAttribute('data-expansion-panel')
            ? next
            : null,
        entrance: null as Animation | null,
        panelOffset: null as number | null,
        edges: new Map<Element, BottomEdge>(),
      };
      // Read where the glide reads the layout, before anything moves: the
      // rows' borders, then the panel's entrance (it reads too).
      const isMeasured = pending.change.animate(candidates => {
        for (const candidate of candidates) {
          if (
            candidate instanceof HTMLTableRowElement &&
            candidate.parentElement === row.parentElement
          ) {
            const edge = rowEdge(candidate);
            if (edge != null) {
              record.edges.set(candidate, edge);
            }
          }
        }
        if (record.panel != null) {
          const edge = rowEdge(record.panel);
          if (edge != null) {
            record.edges.set(record.panel, edge);
            // Its entrance moves its cell: read where its line hangs first.
            record.panelOffset = dividerOffset(record.panel, edge);
          }
          record.entrance = playLayoutChange(animatedLayout, record.panel);
        }
      });
      if (isMeasured) {
        moved.push(record);
      }
    }
    // The table's scroll wrapper clips what it holds, and a panel that closed
    // shrank it at once: the rows gliding up into its place would be cut off
    // at its new bottom until they arrive. For the glide, it keeps the height
    // the panels gave up as bottom padding, given back with an equal negative
    // margin so the content after the table moves exactly as it would have;
    // both go together when the rows stop, which changes nothing outside.
    const wrapper = scrollWrapperRef.current;
    const held = moved.length > 0 ? closedHeightRef.current : 0;
    closedHeightRef.current = 0;
    if (heldHeightRef.current === 0 && held <= 0.5) {
      holdBaseRef.current = null;
    }
    if (moved.length === 0) {
      return;
    }
    // The glide starts in the microtask the module queued in animate(); this
    // one runs after it, before the frame paints, and only writes.
    queueMicrotask(() => {
      const stopped = Promise.all(
        moved.map(async ({row, panel, entrance, panelOffset, edges}) =>
          markGlidingRows(
            row,
            edges,
            panel != null && entrance != null
              ? {row: panel, animation: entrance, offset: panelOffset}
              : null,
            glideOf,
          ),
        ),
      );
      if (held <= 0.5 || wrapper == null) {
        return;
      }
      const hold = (height: number) => {
        const base = holdBaseRef.current ?? {padding: 0, margin: 0};
        wrapper.style.paddingBlockEnd =
          height > 0 ? `${base.padding + height}px` : '';
        wrapper.style.marginBlockEnd =
          height > 0 ? `${base.margin - height}px` : '';
        if (height <= 0) {
          holdBaseRef.current = null;
        }
      };
      heldHeightRef.current += held;
      hold(heldHeightRef.current);
      void stopped.then(() => {
        heldHeightRef.current = Math.max(0, heldHeightRef.current - held);
        hold(heldHeightRef.current);
      });
    });
  }, [expandedKeys, animatedLayout, rowFor]);

  const expansionColumn = useMemo(
    (): TableColumn<T> => ({
      key: EXPANSION_COLUMN_KEY,
      // A `<th>` with no discernible text is announced as an unlabelled
      // column; the label is hidden because the column shows only chevrons.
      header: (
        <VisuallyHidden>
          {t('@astryx.tableRowExpansion.columnHeader')}
        </VisuallyHidden>
      ),
      width: EXPANSION_COLUMN_WIDTH,
      resizable: false,
      renderCell: (item: T) => {
        const expandable = getIsItemExpandable
          ? getIsItemExpandable(item)
          : true;
        if (!expandable) {
          return null;
        }
        const key = getRowKey(item);
        const isExpanded = expandedKeys.has(key);
        return (
          <ExpansionChevron
            rowLabel={getRowLabel?.(item)?.trim() || undefined}
            isExpanded={isExpanded}
            onToggle={() => onToggle(key)}
          />
        );
      },
    }),
    [expandedKeys, onToggle, getRowKey, getIsItemExpandable, getRowLabel, t],
  );

  return useMemo(
    (): TablePlugin<T> => ({
      rowModel: 'detail',
      // One colour-mode watch per table for the open panels' dividers.
      transformTableContext(children: ReactNode): ReactNode {
        return (
          <>
            {children}
            <PanelDividerModeWatch cellsRef={panelCellsRef} />
          </>
        );
      },
      transformColumns(columns: TableColumn<T>[]) {
        const withExpansion = [expansionColumn, ...columns];
        columnCountRef.current = withExpansion.length;
        return withExpansion;
      },

      transformHeaderCell(
        props: HeaderCellRenderProps,
        column: TableColumn<T>,
      ): HeaderCellRenderProps {
        // Keep the chevron column at its fixed width (chevronCellStyles).
        return column.key === EXPANSION_COLUMN_KEY
          ? {...props, xstyle: [...props.xstyle, chevronHeaderCellStyles.cell]}
          : props;
      },

      transformBodyCell(
        props: BodyCellRenderProps,
        column: TableColumn<T>,
        item: T,
      ): BodyCellRenderProps {
        // Contribute the expand/collapse action on every cell; BaseTable
        // aggregates them into one menu per row. Skip non-expandable rows.
        const expandable = getIsItemExpandable
          ? getIsItemExpandable(item)
          : true;
        if (!expandable) {
          return props;
        }
        const key = getRowKey(item);
        const isExpanded = expandedKeys.has(key);
        return {
          ...props,
          xstyle: [
            ...props.xstyle,
            // The chevron centers itself in its column (chevronCellStyles).
            ...(column.key === EXPANSION_COLUMN_KEY
              ? [chevronCellStyles.cell]
              : []),
            // Hand the row divider to the panel below, so the line closes the
            // row-plus-panel pair instead of splitting it.
            ...(isExpanded ? [dividerStyles.expandedRowCell] : []),
          ],
          contextMenuActions: () => [
            ...resolveContextActions(props.contextMenuActions),
            {
              id: 'row-expansion-toggle',
              group: 'row-expansion',
              label: isExpanded
                ? t('@astryx.tableRowExpansion.collapseRow')
                : t('@astryx.tableRowExpansion.expandRow'),
              icon: (
                <Icon
                  icon={isExpanded ? 'chevronDown' : 'chevronRight'}
                  size="xsm"
                  aria-hidden
                  // chevronDown needs no mirroring; chevronRight (collapsed,
                  // pointing toward the reveal direction) does.
                  xstyle={!isExpanded && rtlStyles.mirror}
                />
              ),
              onSelect: () => onToggle(key),
            },
          ],
        };
      },

      transformScrollWrapper(
        props: ScrollWrapperRenderProps,
      ): ScrollWrapperRenderProps {
        // One merged ref per inner ref, so React does not detach and
        // re-attach the wrapper's refs (a later plugin's listeners
        // included) on every render.
        const existingRef = props.htmlProps.ref ?? null;
        const cached = mergedScrollWrapperRef.current;
        const mergedRef =
          cached != null && cached.inner === existingRef
            ? cached.merged
            : (node: HTMLDivElement | null) => {
                scrollWrapperRef.current = node;
                if (typeof existingRef === 'function') {
                  existingRef(node);
                } else if (existingRef != null) {
                  existingRef.current = node;
                }
              };
        mergedScrollWrapperRef.current = {
          inner: existingRef,
          merged: mergedRef,
        };
        return {
          ...props,
          htmlProps: {...props.htmlProps, ref: mergedRef},
          beforeTable:
            animatedLayout == null ? (
              props.beforeTable
            ) : (
              <>
                {props.beforeTable}
                <ExpansionSnapshot
                  value={expandedKeys}
                  onBeforeChange={measureChanges}
                  onColumnLines={resetChevrons}
                />
              </>
            ),
        };
      },

      transformBodyRow(props: BodyRowRenderProps, item: T): BodyRowRenderProps {
        const expandable = getIsItemExpandable
          ? getIsItemExpandable(item)
          : true;
        if (!expandable) {
          return props;
        }
        const key = getRowKey(item);
        // The row a glide measures from, found again after the commit.
        const keyAttribute: Record<string, string> = {
          'data-expansion-key': key,
        };
        const keyed = {
          ...props,
          htmlProps: {...props.htmlProps, ...keyAttribute},
        };

        // Whole-row-click expansion (opt-in), applied before the collapsed
        // early-return: a collapsed row is precisely the one a click has to
        // reach, since opening it is the whole point.
        const withClick = hasRowClickExpansion
          ? {
              ...keyed,
              htmlProps: {
                ...keyed.htmlProps,
                onClick: (event: React.MouseEvent<HTMLTableRowElement>) => {
                  // Don't hijack clicks on interactive cell content (the
                  // chevron already stops propagation, but a composed
                  // selection checkbox, link, or action button does not) or a
                  // text selection. Both rules come from
                  // `useClickableContainer`, the same pair every clickable
                  // surface in the system uses — the hook itself wants a ref
                  // we have no way to hand it from inside `transformBodyRow`,
                  // so this shares its guards rather than its plumbing.
                  const row = event.currentTarget;
                  const target = event.target;
                  if (!(target instanceof Element)) {
                    return;
                  }
                  if (target !== row && hasInteractiveAncestor(target, row)) {
                    return;
                  }
                  // A click inside a contenteditable region is an edit
                  // action, not a row toggle. The shared guard does not
                  // include contenteditable (it would change ClickableCard
                  // and other consumers), so the Table row-click path
                  // checks it separately.
                  if (
                    target !== row &&
                    target.closest(
                      '[contenteditable]:not([contenteditable="false"])',
                    )
                  ) {
                    return;
                  }
                  if (hasTextSelection(row)) {
                    return;
                  }
                  keyed.htmlProps.onClick?.(event);
                  onToggle(key);
                },
              },
              xstyle: [...keyed.xstyle, expansionStyles.clickableRow],
            }
          : keyed;

        if (!expandedKeys.has(key)) {
          return withClick;
        }

        const panel = (
          <tr
            key={`${key}-expanded`}
            // A panel is its row's continuation, not a row of its own. Striping
            // counts `:nth-child(even of :not([data-expansion-panel]))`, so this
            // attribute is what keeps an open panel from inverting the zebra of
            // every row beneath it. Load-bearing, not diagnostic.
            data-expansion-panel=""
            {...stylex.props(
              // Carries the marker so the panel cell's divider can ask whether
              // this row is the table's last, the same way TableCell does.
              tableRowMarker,
              glidingDividerStyles.row,
            )}>
            <ExpansionPanelCell
              colSpan={columnCountRef.current}
              cellsRef={panelCellsRef}
              isMuted={panelVariant === 'muted'}>
              {renderExpanded(item)}
            </ExpansionPanelCell>
          </tr>
        );

        return {
          ...withClick,
          afterRow: withClick.afterRow ? (
            <>
              {withClick.afterRow}
              {panel}
            </>
          ) : (
            panel
          ),
        };
      },
    }),
    [
      expandedKeys,
      getRowKey,
      renderExpanded,
      getIsItemExpandable,
      hasRowClickExpansion,
      panelVariant,
      onToggle,
      t,
      expansionColumn,
      animatedLayout,
      measureChanges,
      resetChevrons,
    ],
  );
}