@astryxdesign/core 0.4.6 → 0.4.7-canary.20bae6c

package/src/Table/plugins/groupedRows/useTableGroupedRows.test.tsx

@@ -5,6 +5,7 @@ import {render, screen, fireEvent, within} from '@testing-library/react';
 import {useState, useCallback} from 'react';
 import {Table} from '../../Table';
 import type {TableColumn} from '../../types';
+import {useTableRowStatus, type TableRowStatus} from '../rowStatus';
 import {useTableGroupedRows} from './useTableGroupedRows';
 
 interface Person extends Record<string, unknown> {
@@ -175,6 +176,105 @@ describe('useTableGroupedRows', () => {
     ).not.toBeInTheDocument();
   });
 
+  it('never runs a column renderCell against a group header row', () => {
+    // The renderer that breaks: it keys a lookup off a field rather than
+    // printing it, so the header Proxy answering `''` is no better than
+    // `undefined`.
+    const TEAM_META: Record<string, {dot: string}> = {
+      Core: {dot: 'green'},
+      Infra: {dot: 'blue'},
+    };
+    const seen: Person[] = [];
+    const lookupColumns: TableColumn<Person>[] = [
+      {
+        key: 'team',
+        header: 'Team',
+        renderCell: item => {
+          seen.push(item);
+          return <span>{TEAM_META[item.team].dot}</span>;
+        },
+      },
+    ];
+
+    function LookupHarness() {
+      const [collapsed, setCollapsed] = useState<Set<string>>(EMPTY);
+      const grouped = useTableGroupedRows<Person>({
+        data: people,
+        groupBy: p => p.team,
+        collapsedGroups: collapsed,
+        onToggleGroup: k => setCollapsed(new Set([k])),
+        getRowKey: p => p.id,
+      });
+      return (
+        <Table
+          data={grouped.data}
+          columns={lookupColumns}
+          idKey={grouped.idKey}
+          plugins={{grouped: grouped.plugin}}
+        />
+      );
+    }
+
+    expect(() => render(<LookupHarness />)).not.toThrow();
+    expect(seen.map(p => p.name)).toEqual(['Alice', 'Bob', 'Carol']);
+    expect(screen.getByText('Core')).toBeInTheDocument();
+    expect(screen.getByText('Infra')).toBeInTheDocument();
+  });
+
+  describe.each([
+    ['grouped first', true],
+    ['rowStatus first', false],
+  ])(
+    'with a column contributed by another plugin (%s)',
+    (_label, groupedFirst) => {
+      // `grouped` and `rowStatus` are both absent from PLUGIN_ORDER, so the
+      // record's insertion order is the pipeline order. Whichever way round
+      // the consumer types it, the status column's renderCell must not see a
+      // header row.
+      const STATUS_BY_TEAM: Record<string, TableRowStatus> = {
+        Core: {color: 'success', label: 'Healthy'},
+        Infra: {color: 'error', label: 'Paging'},
+      };
+
+      function StatusHarness() {
+        const [collapsed, setCollapsed] = useState<Set<string>>(EMPTY);
+        const grouped = useTableGroupedRows<Person>({
+          data: people,
+          groupBy: p => p.team,
+          collapsedGroups: collapsed,
+          onToggleGroup: k => setCollapsed(new Set([k])),
+          getRowKey: p => p.id,
+        });
+        const rowStatus = useTableRowStatus<Person>({
+          getStatus: useCallback((item: Person) => {
+            const {color, label} = STATUS_BY_TEAM[item.team];
+            return {color, label};
+          }, []),
+        });
+        return (
+          <Table
+            data={grouped.data}
+            columns={columns}
+            idKey={grouped.idKey}
+            plugins={
+              groupedFirst
+                ? {grouped: grouped.plugin, rowStatus}
+                : {rowStatus, grouped: grouped.plugin}
+            }
+          />
+        );
+      }
+
+      it('renders the group headers without throwing', () => {
+        expect(() => render(<StatusHarness />)).not.toThrow();
+        expect(screen.getByText('Core')).toBeInTheDocument();
+        expect(screen.getByText('Infra')).toBeInTheDocument();
+        // One indicator per real row, none on the two headers.
+        expect(screen.getAllByRole('img')).toHaveLength(3);
+      });
+    },
+  );
+
   it('keeps a group collapsed across a data change (state keyed by group)', () => {
     function ChangingHarness() {
       const [collapsed, setCollapsed] = useState<Set<string>>(

package/src/Table/plugins/groupedRows/useTableGroupedRows.tsx

@@ -41,8 +41,11 @@ function isGroupHeader(item: unknown): item is GroupHeader {
   );
 }
 
-// Proxy handler: any field access beyond the marker fields resolves to `''`
-// so user cell renderers (`item.name.toUpperCase()`) never throw on a header.
+// Proxy handler: any field access beyond the marker fields resolves to `''`,
+// which keeps anything that reads a header's data — the sortable and filtering
+// plugins, a consumer's own row handler — off `undefined`. Cell renderers are
+// handled at render time instead (see `transformBodyCell` below); the Proxy
+// never protected them, because `''` fails a lookup exactly as `undefined` does.
 const HEADER_PROXY_HANDLER: ProxyHandler<Record<string | symbol, unknown>> = {
   // eslint-disable-next-line @typescript-eslint/promise-function-async -- Proxy get trap, not a promise-returning fn
   get(t: Record<string | symbol, unknown>, prop: string | symbol): unknown {
@@ -54,12 +57,9 @@ const HEADER_PROXY_HANDLER: ProxyHandler<Record<string | symbol, unknown>> = {
 };
 
 /**
- * Build a synthetic header row wrapped in a Proxy so arbitrary field access
- * from user cell renderers (e.g. `item.name.toUpperCase()`) resolves to `''`
- * instead of throwing — BaseTable evaluates `col.renderCell(item)` on every
- * row (including synthetic headers) before `transformBodyRow` can replace the
- * row's cells. `transformBodyRow` then discards those cells and renders a
- * single full-width header cell.
+ * Build a synthetic header row wrapped in a Proxy so field access resolves to
+ * `''` instead of `undefined`. `transformBodyRow` then discards the row's
+ * cells and renders a single full-width header cell.
  */
 function makeHeader<T extends Record<string, unknown>>(
   groupKey: string,
@@ -301,6 +301,15 @@ export function useTableGroupedRows<T extends Record<string, unknown>>(
 
   const plugin = useMemo(
     (): TablePlugin<T> => ({
+      // A header row is not one of the caller's rows, so running a cell
+      // renderer against it can only misread it or throw — and the cells are
+      // discarded by `transformBodyRow` below regardless.
+      transformBodyCell(props, _column, item) {
+        if (!isGroupHeader(item)) {
+          return props;
+        }
+        return {...props, isContentSuppressed: true};
+      },
       // Replace a header row's pre-rendered cells with one full-width cell.
       transformBodyRow(props, item) {
         if (!isGroupHeader(item)) {

package/src/Table/plugins/pagination/useTablePagination.test.tsx

@@ -229,7 +229,7 @@ describe('useTablePagination', () => {
       ).toBeTruthy();
     });
 
-    it('transformTableContext renders Pagination above and below', () => {
+    it('transformTableContext renders distinctly named Pagination above and below', () => {
       render(
         <PaginatedTable
           data={generateItems(30)}
@@ -237,10 +237,40 @@ describe('useTablePagination', () => {
           position="both"
         />,
       );
-      const navs = screen.getAllByRole('navigation', {
-        name: 'Table pagination',
+      const table = screen.getByRole('table');
+      // Each nav landmark gets a unique accessible name (axe landmark-unique)
+      const topNav = screen.getByRole('navigation', {
+        name: 'Table pagination (top)',
+      });
+      const bottomNav = screen.getByRole('navigation', {
+        name: 'Table pagination (bottom)',
       });
-      expect(navs).toHaveLength(2);
+      // Top nav comes before the table, bottom nav after it in DOM order
+      expect(
+        table.compareDocumentPosition(topNav) &
+          Node.DOCUMENT_POSITION_PRECEDING,
+      ).toBeTruthy();
+      expect(
+        table.compareDocumentPosition(bottomNav) &
+          Node.DOCUMENT_POSITION_FOLLOWING,
+      ).toBeTruthy();
+    });
+
+    it('position="both" interpolates a consumer label into distinct nav names', () => {
+      render(
+        <PaginatedTable
+          data={generateItems(30)}
+          pageSize={10}
+          position="both"
+          label="Users table"
+        />,
+      );
+      expect(
+        screen.getByRole('navigation', {name: 'Users table (top)'}),
+      ).toBeInTheDocument();
+      expect(
+        screen.getByRole('navigation', {name: 'Users table (bottom)'}),
+      ).toBeInTheDocument();
     });
 
     it('transformTableContext does not render Pagination when position is none', () => {

package/src/Table/plugins/pagination/useTablePagination.tsx

@@ -164,6 +164,9 @@ export interface UseTablePaginationConfig {
 
   /**
    * Accessible label for the pagination nav landmark.
+   * When `position` is 'both', the two navs get distinct names by suffixing
+   * this label — "{label} (top)" above and "{label} (bottom)" below — so
+   * same-type landmarks stay distinguishable to assistive technology.
    * @default 'Table pagination'
    */
   label?: string;
@@ -211,6 +214,10 @@ export function useTablePagination<T extends Record<string, unknown>>(
     label: labelFromProps,
   } = config;
   const label = labelFromProps ?? t('@astryx.table.pagination.label');
+  // position='both' renders two nav landmarks; suffix the base label so each
+  // gets a unique accessible name (axe landmark-unique).
+  const labelAbove = t('@astryx.table.pagination.labelAbove', {label});
+  const labelBelow = t('@astryx.table.pagination.labelBelow', {label});
 
   // Same guard as Pagination itself: 0/NaN/negative pageSize would produce an
   // Infinity/NaN totalPages here, which bypasses Pagination's own coercion
@@ -240,8 +247,20 @@ export function useTablePagination<T extends Record<string, unknown>>(
 
   // Keep current config in a ref so the plugin can read the latest values
   // without needing to recreate the plugin object on every change.
-  const configRef = useRef({paginationProps, position, align});
-  configRef.current = {paginationProps, position, align};
+  const configRef = useRef({
+    paginationProps,
+    position,
+    align,
+    labelAbove,
+    labelBelow,
+  });
+  configRef.current = {
+    paginationProps,
+    position,
+    align,
+    labelAbove,
+    labelBelow,
+  };
 
   // Stable plugin object \u2014 created once, reads config via ref.
   return useMemo(
@@ -251,6 +270,8 @@ export function useTablePagination<T extends Record<string, unknown>>(
           position: pos,
           paginationProps: props,
           align: a,
+          labelAbove: above,
+          labelBelow: below,
         } = configRef.current;
         if (pos === 'none') {
           return children;
@@ -277,7 +298,18 @@ export function useTablePagination<T extends Record<string, unknown>>(
               a === 'end' && styles.alignEnd,
               a === 'start' && styles.alignStart,
             )}>
-            <Pagination {...props} />
+            <Pagination
+              {...props}
+              // Two navs with the same name are indistinguishable landmarks;
+              // give each side a unique name when both render.
+              label={
+                pos === 'both'
+                  ? side === 'above'
+                    ? above
+                    : below
+                  : props.label
+              }
+            />
           </div>
         );
 

package/src/Table/plugins/rowExpansion/useTableRowExpansion.tsx

@@ -21,6 +21,7 @@ import {useMemo, useRef, type ReactNode} from 'react';
 import * as stylex from '@stylexjs/stylex';
 import {spacingVars, colorVars, radiusVars} from '../../../theme/tokens.stylex';
 import {Icon} from '../../../Icon';
+import {VisuallyHidden} from '../../../VisuallyHidden';
 import {resolveContextActions} from '../../tableContextMenu';
 import {useTranslator} from '../../../i18n';
 import {rtlStyles} from '../../../utils';
@@ -207,7 +208,13 @@ export function useTableRowExpansion<T extends Record<string, unknown>>(
   const expansionColumn = useMemo(
     (): TableColumn<T> => ({
       key: '__expansion',
-      header: '',
+      // 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) => {
@@ -226,7 +233,7 @@ export function useTableRowExpansion<T extends Record<string, unknown>>(
         );
       },
     }),
-    [expandedKeys, onToggle, getRowKey, getIsItemExpandable],
+    [expandedKeys, onToggle, getRowKey, getIsItemExpandable, t],
   );
 
   return useMemo(

package/src/Table/plugins/rowStatus/useTableRowStatus.test.tsx

@@ -44,12 +44,18 @@ function Harness({
 }
 
 describe('useTableRowStatus', () => {
-  it('prepends a narrow status column with an empty header', () => {
+  it('names the status column header for assistive technology', () => {
     render(<Harness />);
-    const headers = screen.getAllByRole('columnheader');
-    // Status column is first; its header is empty.
-    expect(headers[0]).toHaveAttribute('data-column-key', '__rowStatus');
-    expect(headers[0].textContent).toBe('');
+    // The gutter looks blank but its th carries a visually hidden name.
+    const header = screen.getByRole('columnheader', {name: 'Row status'});
+    expect(header).toHaveAttribute('data-column-key', '__rowStatus');
+    // Status column is first.
+    expect(screen.getAllByRole('columnheader')[0]).toBe(header);
+    // The name must come from the clipped VisuallyHidden span — bare th text
+    // would be a visible header on what should stay a blank gutter.
+    const hiddenText = within(header).getByText('Row status');
+    expect(hiddenText.tagName).toBe('SPAN');
+    expect(hiddenText.className).not.toBe('');
   });
 
   it('renders a labeled dot for rows with a status', () => {
@@ -131,8 +137,8 @@ describe('useTableRowStatus', () => {
 
   it('renders the status header with empty data and no indicators', () => {
     render(<Harness rows={[]} />);
-    const headers = screen.getAllByRole('columnheader');
-    expect(headers[0]).toHaveAttribute('data-column-key', '__rowStatus');
+    const header = screen.getByRole('columnheader', {name: 'Row status'});
+    expect(header).toHaveAttribute('data-column-key', '__rowStatus');
     expect(screen.queryByRole('img')).not.toBeInTheDocument();
   });
 });

package/src/Table/plugins/rowStatus/useTableRowStatus.tsx

@@ -4,7 +4,7 @@
 
 /**
  * @file useTableRowStatus.tsx
- * @input React, StyleX, Icon, Table types
+ * @input React, StyleX, Icon, i18n, VisuallyHidden, Table types
  * @output Exports useTableRowStatus hook + config type
  * @position Row-status plugin; consumed by Table via plugins prop
  *
@@ -16,6 +16,8 @@ import {useMemo} from 'react';
 import * as stylex from '@stylexjs/stylex';
 import {Icon, type IconColor, type IconName} from '../../../Icon';
 import {Tooltip} from '../../../Tooltip';
+import {useTranslator} from '../../../i18n';
+import {VisuallyHidden} from '../../../VisuallyHidden';
 import type {TableColumn, TablePlugin} from '../../types';
 
 /**
@@ -142,6 +144,7 @@ const styles = stylex.create({
 export function useTableRowStatus<T extends Record<string, unknown>>(
   config: UseTableRowStatusConfig<T>,
 ): TablePlugin<T> {
+  const t = useTranslator();
   const {getStatus} = config;
 
   return useMemo(
@@ -149,7 +152,13 @@ export function useTableRowStatus<T extends Record<string, unknown>>(
       transformColumns(columns) {
         const statusColumn: TableColumn<T> = {
           key: '__rowStatus',
-          header: '',
+          // The gutter stays visually blank, but the th needs a discernible
+          // name for assistive technology (axe: empty-table-header).
+          header: (
+            <VisuallyHidden>
+              {t('@astryx.table.rowStatus.columnHeader')}
+            </VisuallyHidden>
+          ),
           width: STATUS_COLUMN_WIDTH,
           resizable: false,
           renderCell: (item: T) => {
@@ -184,6 +193,6 @@ export function useTableRowStatus<T extends Record<string, unknown>>(
         return [statusColumn, ...columns];
       },
     }),
-    [getStatus],
+    [getStatus, t],
   );
 }

package/src/Table/plugins/selection/useTableSelection.test.tsx

@@ -13,6 +13,7 @@ import {act, render, renderHook, screen, within} from '@testing-library/react';
 import userEvent from '@testing-library/user-event';
 import {Table} from '../../Table';
 import {useTableSelection} from './useTableSelection';
+import {colorVars} from '../../../theme/tokens.stylex';
 import type {BodyRowRenderProps, TableColumn} from '../../types';
 
 // =============================================================================
@@ -41,10 +42,12 @@ function SelectionTable({
   getIsItemSelectable,
   getIsItemEnabled,
   getRowLabel,
+  hasRowHighlight,
 }: {
   getIsItemSelectable?: (item: SelectableUser) => boolean;
   getIsItemEnabled?: (item: SelectableUser) => boolean;
   getRowLabel?: (item: SelectableUser) => string;
+  hasRowHighlight?: boolean;
 }) {
   const [selectedKeys, setSelectedKeys] = useState<Set<string>>(new Set());
 
@@ -78,6 +81,7 @@ function SelectionTable({
     getIsItemSelectable,
     getIsItemEnabled,
     getRowLabel,
+    hasRowHighlight,
   });
 
   return (
@@ -211,6 +215,78 @@ describe('useTableSelection', () => {
     expect(headers).toHaveLength(3);
   });
 
+  describe('hasRowHighlight', () => {
+    const selectedBgColor = colorVars['--color-accent-muted'];
+
+    it('paints a checked row with the accent wash by default', async () => {
+      const user = userEvent.setup();
+      render(<SelectionTable />);
+
+      await user.click(screen.getAllByLabelText('Select row')[0]);
+
+      const row = screen.getAllByRole('row')[1];
+      expect(row.style.backgroundColor).toBe(selectedBgColor);
+      expect(row).toHaveAttribute('aria-selected', 'true');
+    });
+
+    it('leaves the row background alone when hasRowHighlight is false', async () => {
+      const user = userEvent.setup();
+      render(<SelectionTable hasRowHighlight={false} />);
+
+      await user.click(screen.getAllByLabelText('Select row')[0]);
+
+      const row = screen.getAllByRole('row')[1];
+      expect(row.style.backgroundColor).toBe('');
+      // The wash is opt-out; the semantics are not.
+      expect(row).toHaveAttribute('aria-selected', 'true');
+    });
+
+    it('clears an already-painted row when the flag flips to false', async () => {
+      const user = userEvent.setup();
+      const {rerender} = render(<SelectionTable />);
+
+      await user.click(screen.getAllByLabelText('Select row')[0]);
+      expect(screen.getAllByRole('row')[1].style.backgroundColor).toBe(
+        selectedBgColor,
+      );
+
+      rerender(<SelectionTable hasRowHighlight={false} />);
+
+      const row = screen.getAllByRole('row')[1];
+      expect(row.style.backgroundColor).toBe('');
+      expect(row).toHaveAttribute('aria-selected', 'true');
+    });
+
+    it('repaints an already-checked row when the flag flips back to true', async () => {
+      const user = userEvent.setup();
+      const {rerender} = render(<SelectionTable hasRowHighlight={false} />);
+
+      await user.click(screen.getAllByLabelText('Select row')[0]);
+      rerender(<SelectionTable hasRowHighlight />);
+
+      expect(screen.getAllByRole('row')[1].style.backgroundColor).toBe(
+        selectedBgColor,
+      );
+    });
+
+    it('never paints unchecked rows in either mode', async () => {
+      const user = userEvent.setup();
+      const {rerender} = render(<SelectionTable />);
+
+      await user.click(screen.getAllByLabelText('Select row')[0]);
+      expect(screen.getAllByRole('row')[2].style.backgroundColor).toBe('');
+      expect(screen.getAllByRole('row')[2]).not.toHaveAttribute(
+        'aria-selected',
+      );
+
+      rerender(<SelectionTable hasRowHighlight={false} />);
+      expect(screen.getAllByRole('row')[2].style.backgroundColor).toBe('');
+      expect(screen.getAllByRole('row')[2]).not.toHaveAttribute(
+        'aria-selected',
+      );
+    });
+  });
+
   it('unsubscribes detached row refs instead of accumulating listeners', () => {
     const getIsItemSelected = vi.fn(() => false);
     const {result, rerender} = renderHook(() =>

package/src/Table/plugins/selection/useTableSelection.tsx

@@ -26,7 +26,13 @@
  * DOM elements and no central element tracking. Each subscription
  * self-cleans when the row disconnects.
  *
+ * Because the background is an inline style, it outranks anything
+ * userland can layer on with StyleX. `hasRowHighlight: false` is the
+ * supported way to reclaim the row background; `aria-selected` is
+ * unaffected by it.
+ *
  * SYNC: When modified, update these files to stay in sync:
+ * - /packages/core/src/Table/useTableSelection.doc.mjs (config prop table)
  * - /packages/core/src/Table/Table.doc.mjs (selection documentation)
  * - /packages/core/src/Table/index.ts (exports)
  */
@@ -81,6 +87,22 @@ export interface UseTableSelectionConfig<T extends Record<string, unknown>> {
    * ```
    */
   getRowLabel?: (item: T) => string;
+  /**
+   * Paint checked rows with the accent wash. Set false when the surrounding
+   * UI already uses row background to mean something else — a row that is
+   * open in a detail panel, for instance. The wash is an inline style, so
+   * it cannot be overridden from userland; this flag is the way off it.
+   *
+   * Only the background is dropped. `aria-selected` is still set on checked
+   * rows either way, so the selection stays legible to screen readers.
+   *
+   * @default true
+   * @example
+   * ```
+   * useTableSelection({...config, hasRowHighlight: false})
+   * ```
+   */
+  hasRowHighlight?: boolean;
 }
 
 // =============================================================================
@@ -121,18 +143,24 @@ function createSelectionStore<T extends Record<string, unknown>>(
 
 /**
  * Apply or remove selection styling on a <tr> element.
+ *
+ * `aria-selected` tracks selection on its own: it is the semantic half of
+ * the state and stays correct whether or not the row is painted.
  */
 function applyRowSelectionStyle(
   el: HTMLTableRowElement,
   isSelected: boolean,
+  hasRowHighlight: boolean,
 ): void {
   if (isSelected) {
     el.setAttribute('aria-selected', 'true');
-    el.style.backgroundColor = selectedBgColor;
   } else {
     el.removeAttribute('aria-selected');
-    el.style.backgroundColor = '';
   }
+  // Written on every pass, not just when painting: the flag can flip while a
+  // row is already selected, and the wash has to come back off.
+  el.style.backgroundColor =
+    isSelected && hasRowHighlight ? selectedBgColor : '';
 }
 
 // =============================================================================
@@ -358,18 +386,23 @@ export function useTableSelection<T extends Record<string, unknown>>(
           if (!el) {
             return;
           }
+          const applyStyle = () => {
+            const config = store.getConfig();
+            applyRowSelectionStyle(
+              el,
+              config.getIsItemSelected(item),
+              config.hasRowHighlight ?? true,
+            );
+          };
           // Apply initial style
-          applyRowSelectionStyle(el, store.getConfig().getIsItemSelected(item));
+          applyStyle();
           // Subscribe for future changes
           const unsub = store.subscribe(() => {
             if (!el.isConnected) {
               unsub();
               return;
             }
-            applyRowSelectionStyle(
-              el,
-              store.getConfig().getIsItemSelected(item),
-            );
+            applyStyle();
           });
           return () => {
             unsub();

package/src/Table/types.ts

@@ -322,6 +322,19 @@ export interface BodyCellRenderProps {
    * sticky offsets. Optional for backward compatibility.
    */
   columns?: ReadonlyArray<TableColumn<Record<string, unknown>>>;
+  /**
+   * When true, the cell renders empty: BaseTable calls neither the column's
+   * `renderCell` nor the default renderer. Set it for a row whose cells a
+   * plugin is going to replace wholesale in `transformBodyRow` (a grouped-rows
+   * section header, a summary row) — the row is not one the consumer supplied,
+   * so their renderer can only misread it or throw, and its output is
+   * discarded moments later anyway.
+   *
+   * Applies to this cell only, and is decided per render against the final
+   * column list, so it covers columns other plugins contributed regardless of
+   * where in the pipeline this plugin sits.
+   */
+  isContentSuppressed?: boolean;
 }
 
 /**
@@ -414,13 +427,18 @@ export type TableContextActions =
  *
  * 1. `transformColumns` — filter, reorder, or inject columns before rendering
  * 2. `transformTable` — transform the root `<table>` element props
- * 3. `transformHeaderRow` — transform the header `<tr>` props
- * 4. `transformHeaderCell` — transform each `<th>` props
- * 5. `transformBodyRow` — transform each body `<tr>` props
- * 6. `transformBodyCell` — transform each body `<td>` props
+ * 3. `transformHeaderCell` — transform each `<th>` props
+ * 4. `transformHeaderRow` — transform the header `<tr>` props
+ * 5. `transformBodyCell` — transform each body `<td>` props
+ * 6. `transformBodyRow` — transform each body `<tr>` props
  * 7. `transformScrollWrapper` — transform the scroll-container wrapper around the table
  * 8. `transformTableContext` — wrap the table output in context providers
  *
+ * A row's cells are built before its row transform runs, and reach it as
+ * `children`: the cell hook is the earliest per-cell interception point, and a
+ * row transform can discard cells but cannot stop them being built (see
+ * `isContentSuppressed` on `BodyCellRenderProps` for that).
+ *
  * Plugins may also contribute right-click menu actions by appending to
  * `contextMenuActions` in `transformHeaderCell` / `transformBodyCell`
  * (aggregated into one menu per header cell / row).

package/src/Table/useBaseTablePlugins.ts

@@ -46,6 +46,11 @@ import {devWarn} from '../utils/devWarning';
  * Canonical ordering for first-party plugin names.
  * Plugins are sorted by their position in this array.
  * Unknown names are appended after the known set.
+ *
+ * This decides LAYOUT — which column lands left of which, who wraps whom. It
+ * must never decide whether the table works: a plugin that renders in one
+ * order and crashes in the other is broken, and adding it here buys a lucky
+ * order rather than a fix.
  */
 const PLUGIN_ORDER: ReadonlyArray<string> = [
   'columnSettings',