@astryxdesign/core 0.1.8 → 0.1.9-canary.02ef052

package/src/Table/plugins/tree/useTableTreeData.test.tsx

@@ -55,14 +55,18 @@ const columns: TableColumn<FileRow>[] = [
 ];
 
 function TreeTable(
-  props: Partial<UseTableTreeStateConfig<FileRow>> & {data?: FileRow[]},
+  props: Partial<UseTableTreeStateConfig<FileRow>> & {
+    data?: FileRow[];
+    hasExpandAllControl?: boolean;
+  },
 ) {
+  const {hasExpandAllControl, ...stateProps} = props;
   const {visibleData, treeConfig} = useTableTreeState<FileRow>({
     data: props.data ?? fileTree,
     idKey: 'id',
-    ...props,
+    ...stateProps,
   });
-  const tree = useTableTreeData(treeConfig);
+  const tree = useTableTreeData({...treeConfig, hasExpandAllControl});
 
   return (
     <Table data={visibleData} columns={columns} idKey="id" plugins={{tree}} />
@@ -592,3 +596,131 @@ describe('useTableTreeData — composition with sorting', () => {
     expect(names).toEqual(['src', 'utils.ts', 'components', 'README.md']);
   });
 });
+
+// =============================================================================
+// header expand-all control
+// =============================================================================
+
+describe('useTableTreeData: expand-all header control', () => {
+  /** The header row is the first row; return its expand-all toggle if present. */
+  function queryExpandAllButton(): HTMLElement | null {
+    const headerRow = screen.getAllByRole('row')[0];
+    return (
+      within(headerRow).queryByRole('button', {name: /expand all/i}) ??
+      within(headerRow).queryByRole('button', {name: /collapse all/i})
+    );
+  }
+
+  it('renders no expand-all control by default', () => {
+    render(<TreeTable defaultExpandedIds={['src']} />);
+    expect(queryExpandAllButton()).toBeNull();
+  });
+
+  it('renders an "Expand all" toggle in the tree column header when enabled and collapsed', () => {
+    render(<TreeTable hasExpandAllControl />);
+    const headerRow = screen.getAllByRole('row')[0];
+    expect(
+      within(headerRow).getByRole('button', {name: /expand all/i}),
+    ).toBeInTheDocument();
+  });
+
+  it('expands every row when the collapsed toggle is clicked', async () => {
+    const user = userEvent.setup();
+    render(<TreeTable hasExpandAllControl />);
+
+    // Collapsed: only roots are visible.
+    expect(getBodyRows()).toHaveLength(2);
+
+    await user.click(
+      within(screen.getAllByRole('row')[0]).getByRole('button', {
+        name: /expand all/i,
+      }),
+    );
+
+    // Every level is now visible.
+    expect(
+      getBodyRows().map(r => within(r).getByText(/.+/, {selector: 'td *'})),
+    ).not.toHaveLength(2);
+    expect(screen.getByText('Button.tsx')).toBeInTheDocument();
+  });
+
+  it('relabels the toggle "Collapse all" once everything is expanded', () => {
+    render(
+      <TreeTable
+        hasExpandAllControl
+        defaultExpandedIds={['src', 'components']}
+      />,
+    );
+    const headerRow = screen.getAllByRole('row')[0];
+    expect(
+      within(headerRow).getByRole('button', {name: /collapse all/i}),
+    ).toBeInTheDocument();
+  });
+
+  it('collapses back to roots when the expanded toggle is clicked', async () => {
+    const user = userEvent.setup();
+    render(
+      <TreeTable
+        hasExpandAllControl
+        defaultExpandedIds={['src', 'components']}
+      />,
+    );
+    expect(screen.getByText('Button.tsx')).toBeInTheDocument();
+
+    await user.click(
+      within(screen.getAllByRole('row')[0]).getByRole('button', {
+        name: /collapse all/i,
+      }),
+    );
+
+    expect(getBodyRows()).toHaveLength(2);
+    expect(screen.queryByText('Button.tsx')).not.toBeInTheDocument();
+  });
+
+  it('marks the toggle aria-expanded=false in the indeterminate (partial) state', () => {
+    // 'src' expanded but 'components' not: partially expanded.
+    render(<TreeTable hasExpandAllControl defaultExpandedIds={['src']} />);
+    const headerRow = screen.getAllByRole('row')[0];
+    const toggle = within(headerRow).getByRole('button', {
+      name: /expand all/i,
+    });
+    expect(toggle).toHaveAttribute('aria-expanded', 'false');
+  });
+
+  it('does not render the control for flat data even when enabled', () => {
+    const flat: FileRow[] = [
+      {id: 'a', name: 'A', size: 1},
+      {id: 'b', name: 'B', size: 2},
+    ];
+    render(<TreeTable data={flat} hasExpandAllControl />);
+    expect(queryExpandAllButton()).toBeNull();
+  });
+
+  it('renders the toggle inline with the header label, not stacked above it', () => {
+    render(<TreeTable hasExpandAllControl />);
+    const headerRow = screen.getAllByRole('row')[0];
+    const toggle = within(headerRow).getByRole('button', {
+      name: /expand all/i,
+    });
+    // The tree column's <th> holds the label text ('Name'). The bug was that
+    // the toggle went into the `before` slot, which BaseTable renders as a
+    // block sibling of the label, stacking the chevron ABOVE the title. The
+    // fix wraps the label + toggle in one inline-flex container, so they must
+    // share the same immediate parent (the toggle is a sibling of the label,
+    // not in a separate stacked slot).
+    const th = toggle.closest('th');
+    expect(th).not.toBeNull();
+    const label = within(th as HTMLElement).getByText('Name');
+    const wrapper = label.parentElement as HTMLElement;
+    expect(wrapper).toContainElement(toggle);
+    // The toggle precedes the label within that shared wrapper (chevron sits
+    // to the LEFT of the title). StyleX compiles the inline-flex layout to a
+    // class on this wrapper; assert the class is present (real CSS is not
+    // applied in jsdom, so we check the class hook, not computed display).
+    expect(wrapper.className).not.toBe('');
+    const kids = Array.from(wrapper.childNodes);
+    expect(kids.indexOf(toggle)).toBeLessThan(
+      kids.findIndex(n => n.textContent === 'Name' || n.contains(label)),
+    );
+  });
+});

package/src/Table/plugins/tree/useTableTreeData.tsx

@@ -42,8 +42,13 @@ import {
 import * as stylex from '@stylexjs/stylex';
 import {colorVars, radiusVars, spacingVars} from '../../../theme/tokens.stylex';
 import {Icon} from '../../../Icon';
-import {mergeRefs} from '../../../utils';
-import type {TablePlugin, TableColumn, BodyRowRenderProps} from '../../types';
+import {mergeRefs, rtlStyles} from '../../../utils';
+import type {
+  TablePlugin,
+  TableColumn,
+  BodyRowRenderProps,
+  HeaderCellRenderProps,
+} from '../../types';
 import {useTranslator} from '../../../i18n';
 
 // =============================================================================
@@ -78,6 +83,22 @@ export interface UseTableTreeDataConfig<T extends Record<string, unknown>> {
    * identically to a Table without the plugin.
    */
   hasExpandableRows: boolean;
+  /**
+   * Aggregate expansion state across every expandable row. When provided
+   * together with `onExpandAll`/`onCollapseAll`, the tree column header shows
+   * an expand-all toggle. `useTableTreeState` supplies all three.
+   */
+  isAllExpanded?: boolean | 'indeterminate';
+  /** Expand every expandable row. Wired to the header expand-all control. */
+  onExpandAll?: () => void;
+  /** Collapse every row. Wired to the header expand-all control. */
+  onCollapseAll?: () => void;
+  /**
+   * Show the expand-all/collapse-all toggle in the tree column header. Needs
+   * `isAllExpanded` and `onExpandAll`/`onCollapseAll` to be present.
+   * @default false
+   */
+  hasExpandAllControl?: boolean;
   /**
    * Indent step per level, as spacing tokens.
    * @default 'md'
@@ -243,6 +264,13 @@ const treeStyles = stylex.create({
     height: '24px',
     flexShrink: '0',
   },
+  /** Header expand-all toggle: same affordance as a row expander. */
+  headerCell: {
+    display: 'inline-flex',
+    alignItems: 'center',
+    gap: spacingVars['--spacing-1'],
+    minWidth: 0,
+  },
 });
 
 // =============================================================================
@@ -271,12 +299,63 @@ function TreeExpander({
           : t('@astryx.tableTree.expandRow')
       }
       aria-expanded={isExpanded}>
-      <span
-        {...stylex.props(
-          treeStyles.chevron,
-          isExpanded && treeStyles.chevronExpanded,
-        )}>
-        <Icon icon="chevronRight" size="xsm" />
+      <span {...stylex.props(rtlStyles.mirror)}>
+        <span
+          {...stylex.props(
+            treeStyles.chevron,
+            isExpanded && treeStyles.chevronExpanded,
+          )}>
+          <Icon icon="chevronRight" size="xsm" />
+        </span>
+      </span>
+    </button>
+  );
+}
+
+/**
+ * Header expand-all/collapse-all toggle. Rendered in the tree column header
+ * when `hasExpandAllControl` is set and the state hook supplies the aggregate
+ * `isAllExpanded` plus `onExpandAll`/`onCollapseAll`. Shares the chevron
+ * affordance with the per-row expander; the chevron points down (expanded)
+ * only when every expandable row is expanded, matching the row expander.
+ */
+function TreeExpandAllToggle({
+  isAllExpanded,
+  onExpandAll,
+  onCollapseAll,
+}: {
+  isAllExpanded: boolean | 'indeterminate';
+  onExpandAll: () => void;
+  onCollapseAll: () => void;
+}) {
+  const t = useTranslator();
+  const allExpanded = isAllExpanded === true;
+  return (
+    <button
+      type="button"
+      {...stylex.props(treeStyles.expanderButton)}
+      onClick={e => {
+        e.stopPropagation();
+        if (allExpanded) {
+          onCollapseAll();
+        } else {
+          onExpandAll();
+        }
+      }}
+      aria-label={
+        allExpanded
+          ? t('@astryx.tableTree.collapseAllRows')
+          : t('@astryx.tableTree.expandAllRows')
+      }
+      aria-expanded={allExpanded}>
+      <span {...stylex.props(rtlStyles.mirror)}>
+        <span
+          {...stylex.props(
+            treeStyles.chevron,
+            allExpanded && treeStyles.chevronExpanded,
+          )}>
+          <Icon icon="chevronRight" size="xsm" />
+        </span>
       </span>
     </button>
   );
@@ -380,6 +459,11 @@ export function useTableTreeData<T extends Record<string, unknown>>(
     output: TableColumn<T>[];
   } | null>(null);
 
+  // The resolved tree column key, written by transformColumns (pipeline step 1)
+  // and read by transformHeaderCell (step 4) to place the expand-all toggle on
+  // the same column that carries the row expanders.
+  const treeKeyRef = useRef<string | undefined>(undefined);
+
   // The plugin object is created once per store and never changes shape:
   // every transform reads the live config through the store, and
   // internally no-ops when hasExpandableRows is false. Swapping between
@@ -426,6 +510,7 @@ export function useTableTreeData<T extends Record<string, unknown>>(
           ? treeColumnKey
           : (columns.find(c => !c.key.startsWith('__'))?.key ??
             columns[0]?.key);
+        treeKeyRef.current = treeKey;
 
         // Migration guarantee: flat data renders identically to a Table
         // without the plugin.
@@ -459,6 +544,52 @@ export function useTableTreeData<T extends Record<string, unknown>>(
         return output;
       },
 
+      transformHeaderCell(
+        props: HeaderCellRenderProps,
+        column: TableColumn<T>,
+      ): HeaderCellRenderProps {
+        const {
+          hasExpandableRows,
+          hasExpandAllControl,
+          isAllExpanded,
+          onExpandAll,
+          onCollapseAll,
+        } = store.getConfig();
+
+        // Only the tree column carries the toggle, and only when the control
+        // is enabled, the data is actually hierarchical, and the state hook
+        // supplied the aggregate state plus both handlers. Otherwise this is a
+        // pass-through (flat data stays a no-op).
+        if (
+          !hasExpandAllControl ||
+          !hasExpandableRows ||
+          column.key !== treeKeyRef.current ||
+          isAllExpanded === undefined ||
+          !onExpandAll ||
+          !onCollapseAll
+        ) {
+          return props;
+        }
+
+        // Wrap the header label + the toggle in one inline-flex row so the
+        // chevron sits to the LEFT of the title on the same line. BaseTable
+        // only applies its own flex row for the `after` slot, so a bare
+        // `before` would stack above the label in the block-level <th>.
+        return {
+          ...props,
+          content: (
+            <span {...stylex.props(treeStyles.headerCell)}>
+              <TreeExpandAllToggle
+                isAllExpanded={isAllExpanded}
+                onExpandAll={onExpandAll}
+                onCollapseAll={onCollapseAll}
+              />
+              {props.content}
+            </span>
+          ),
+        };
+      },
+
       transformBodyRow(props: BodyRowRenderProps, item: T) {
         // Attach a ref that subscribes to the store for imperative row
         // ARIA. The ref returns a cleanup so React unsubscribes on

package/src/Table/plugins/tree/useTableTreeState.test.tsx

@@ -634,3 +634,107 @@ describe('useTableTreeState — semantics edges', () => {
     expect(ids(result.current.visibleData)).toEqual(['src', 'readme']);
   });
 });
+
+// =============================================================================
+// isAllExpanded (drives the header expand-all control)
+// =============================================================================
+
+describe('useTableTreeState: isAllExpanded', () => {
+  it('reports false when nothing is expanded', () => {
+    const {result} = renderHook(() =>
+      useTableTreeState({data: fileTree, idKey: 'id'}),
+    );
+
+    expect(result.current.isAllExpanded).toBe(false);
+  });
+
+  it('reports true only when every expandable row is expanded', () => {
+    const {result} = renderHook(() =>
+      useTableTreeState({data: fileTree, idKey: 'id'}),
+    );
+
+    act(() => {
+      result.current.expandAll();
+    });
+
+    expect(result.current.isAllExpanded).toBe(true);
+  });
+
+  it("reports 'indeterminate' when some but not all expandable rows are expanded", () => {
+    const {result} = renderHook(() =>
+      useTableTreeState({
+        data: fileTree,
+        idKey: 'id',
+        defaultExpandedIds: ['src'],
+      }),
+    );
+
+    // 'src' and 'components' are both expandable; only 'src' is expanded.
+    expect(result.current.isAllExpanded).toBe('indeterminate');
+  });
+
+  it('returns to false after collapseAll', () => {
+    const {result} = renderHook(() =>
+      useTableTreeState({
+        data: fileTree,
+        idKey: 'id',
+        defaultExpandedIds: ['src', 'components'],
+      }),
+    );
+
+    act(() => {
+      result.current.collapseAll();
+    });
+
+    expect(result.current.isAllExpanded).toBe(false);
+  });
+
+  it('reports false for flat data (no expandable rows)', () => {
+    const flat: FileRow[] = [
+      {id: 'a', name: 'A', size: 1},
+      {id: 'b', name: 'B', size: 2},
+    ];
+    const {result} = renderHook(() =>
+      useTableTreeState({data: flat, idKey: 'id'}),
+    );
+
+    expect(result.current.isAllExpanded).toBe(false);
+  });
+
+  it('ignores expanded ids that match no expandable row when aggregating', () => {
+    // 'readme' is a leaf (not expandable) and 'ghost' matches nothing; neither
+    // should count toward the expandable total, so an all-expandable set that
+    // omits them still reads as fully expanded.
+    const {result} = renderHook(() =>
+      useTableTreeState({
+        data: fileTree,
+        idKey: 'id',
+        defaultExpandedIds: ['src', 'components', 'readme', 'ghost'],
+      }),
+    );
+
+    expect(result.current.isAllExpanded).toBe(true);
+  });
+
+  it('exposes the aggregate state and expand/collapse handlers through treeConfig', () => {
+    const {result} = renderHook(() =>
+      useTableTreeState({data: fileTree, idKey: 'id'}),
+    );
+
+    // The headless plugin reads everything it needs to render the header
+    // expand-all control from treeConfig, not from the state hook directly.
+    expect(result.current.treeConfig.isAllExpanded).toBe(false);
+
+    act(() => {
+      result.current.treeConfig.onExpandAll?.();
+    });
+    expect(result.current.isAllExpanded).toBe(true);
+    expect(result.current.treeConfig.isAllExpanded).toBe(true);
+
+    act(() => {
+      result.current.treeConfig.onCollapseAll?.();
+    });
+    expect(result.current.isAllExpanded).toBe(false);
+    expect(result.current.treeConfig.isAllExpanded).toBe(false);
+  });
+});

package/src/Table/plugins/tree/useTableTreeState.tsx

@@ -74,6 +74,12 @@ export interface UseTableTreeStateResult<T extends Record<string, unknown>> {
   treeConfig: UseTableTreeDataConfig<T>;
   /** The current expanded row ids. */
   expandedIds: ReadonlySet<string>;
+  /**
+   * Aggregate expansion state across every expandable row: `true` when all are
+   * expanded, `false` when none are, `'indeterminate'` when some but not all
+   * are. Drives the header expand-all control. Reports `false` for flat data.
+   */
+  isAllExpanded: boolean | 'indeterminate';
   /** Expand every expandable row in the tree. */
   expandAll: () => void;
   /** Collapse every row. */
@@ -211,6 +217,25 @@ export function useTableTreeState<T extends Record<string, unknown>>(
 
   const hasExpandableRows = allExpandableIds.length > 0;
 
+  // Aggregate state for the header expand-all control. Only expandable ids
+  // count toward the total, so expanded ids that match a leaf or no row at
+  // all never skew the tally.
+  const isAllExpanded: boolean | 'indeterminate' = useMemo(() => {
+    if (!hasExpandableRows) {
+      return false;
+    }
+    const expandedCount = allExpandableIds.filter(id =>
+      expandedIds.has(id),
+    ).length;
+    if (expandedCount === 0) {
+      return false;
+    }
+    if (expandedCount === allExpandableIds.length) {
+      return true;
+    }
+    return 'indeterminate';
+  }, [hasExpandableRows, allExpandableIds, expandedIds]);
+
   const onToggleItem = useCallback(
     (item: T) => {
       const id = getId(item);
@@ -243,11 +268,30 @@ export function useTableTreeState<T extends Record<string, unknown>>(
       getRowMeta,
       onToggleItem,
       hasExpandableRows,
+      isAllExpanded,
+      onExpandAll: expandAll,
+      onCollapseAll: collapseAll,
       indent,
       treeColumnKey,
     }),
-    [getRowMeta, onToggleItem, hasExpandableRows, indent, treeColumnKey],
+    [
+      getRowMeta,
+      onToggleItem,
+      hasExpandableRows,
+      isAllExpanded,
+      expandAll,
+      collapseAll,
+      indent,
+      treeColumnKey,
+    ],
   );
 
-  return {visibleData, treeConfig, expandedIds, expandAll, collapseAll};
+  return {
+    visibleData,
+    treeConfig,
+    expandedIds,
+    isAllExpanded,
+    expandAll,
+    collapseAll,
+  };
 }

package/src/Table/types.ts

@@ -540,6 +540,39 @@ export interface BaseTableProps<
   /** Plugins to transform render props at each level */
   plugins?: TablePlugin<T>[];
 
+  /**
+   * ARIA row index (1-based) assigned to the **first** rendered body row.
+   *
+   * The row ordinal is an accessibility concern independent of any visible
+   * index column: `aria-rowindex` on each `<tr>` should reflect the row's
+   * position in the **full** dataset, not just the current page. For a
+   * paginated / windowed view, pass the offset of the first visible row,
+   * e.g. `(page - 1) * pageSize + 1`.
+   *
+   * Setting this (or {@link rowCount}) opts the table into emitting
+   * `aria-rowindex` on body rows and `aria-rowcount` on the `<table>`. Data
+   * rows are numbered from this value; the header row keeps native table
+   * semantics and is not assigned an ARIA row index (so the visible
+   * `useTableRowIndex` numbering and `aria-rowindex` stay in agreement).
+   *
+   * Applies to data-driven mode only (ignored in children mode).
+   *
+   * @default 1
+   */
+  rowIndexStart?: number;
+  /**
+   * Total number of body rows across **all** pages/windows, used for
+   * `aria-rowcount` on the `<table>`. Provide this for paginated data so
+   * assistive tech can announce "row X of Y" against the full dataset.
+   *
+   * When omitted but {@link rowIndexStart} is set (a windowed view with an
+   * unknown total, e.g. cursor pagination), `aria-rowcount` is set to `-1`
+   * per the ARIA convention for an unknown row count.
+   *
+   * Applies to data-driven mode only (ignored in children mode).
+   */
+  rowCount?: number;
+
   /** Children mode — render `<tr>`/`<td>` directly instead of data-driven */
   children?: ReactNode;
   /**

package/src/Table/useBaseTablePlugins.ts

@@ -38,6 +38,7 @@
 
 import {useRef} from 'react';
 import type {TablePlugin} from './types';
+import {devWarn} from '../utils/devWarning';
 
 // ======================================================================// Canonical Plugin Order
 // ======================================================================
@@ -112,8 +113,9 @@ function validatePlugin<T extends Record<string, unknown>>(
   // Warn about unknown keys (likely misspelled transform names)
   for (const key of keys) {
     if (!VALID_TRANSFORM_KEYS.has(key)) {
-      console.warn(
-        `[Table] Plugin "${name}" has unknown key "${key}". ` +
+      devWarn(
+        'Table',
+        `Plugin "${name}" has unknown key "${key}". ` +
           `Valid keys: ${[...VALID_TRANSFORM_KEYS].join(', ')}. ` +
           `This key will be ignored.`,
       );
@@ -125,8 +127,9 @@ function validatePlugin<T extends Record<string, unknown>>(
     if (VALID_TRANSFORM_KEYS.has(key)) {
       const value = (plugin as Record<string, unknown>)[key];
       if (value != null && typeof value !== 'function') {
-        console.warn(
-          `[Table] Plugin "${name}" has non-function value for "${key}" ` +
+        devWarn(
+          'Table',
+          `Plugin "${name}" has non-function value for "${key}" ` +
             `(got ${typeof value}). Transform will be skipped.`,
         );
       }
@@ -140,8 +143,9 @@ function validatePlugin<T extends Record<string, unknown>>(
       typeof (plugin as Record<string, unknown>)[key] === 'function',
   );
   if (!hasTransforms) {
-    console.warn(
-      `[Table] Plugin "${name}" has no transform methods. ` +
+    devWarn(
+      'Table',
+      `Plugin "${name}" has no transform methods. ` +
         `It will be included in the pipeline but won't do anything.`,
     );
   }

package/src/Table/useTableRowStatus.doc.mjs

@@ -0,0 +1,30 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('../docs-types').ComponentDoc} */
+
+export const docs = {
+  name: 'useTableRowStatus',
+  subComponentOf: 'Table',
+  displayName: 'useTableRowStatus',
+  description:
+    'Hook that returns a TablePlugin which prepends a narrow column signaling per-row status: a colored status dot by default, or an icon when provided (shape + color is more accessible than color alone). getStatus maps a row to a semantic color (mapped to a theme token) or raw CSS color, an optional icon, and a required accessible label (shown in a tooltip on hover and announced to assistive technology, so status is never color-only); return null for no indicator. Memoize getStatus with useCallback for a stable plugin identity.',
+  props: [
+    {
+      name: 'getStatus',
+      type: "(item: T) => { color: 'accent' | 'success' | 'error' | 'warning' | 'red' | 'orange' | 'green' | 'yellow' | 'blue' | 'gray' | string; icon?: IconName; label: string } | null",
+      description:
+        'Derive the status indicator for a row: a semantic color (accent, success, error, warning, red, orange, green, yellow, blue, gray, each mapped to a theme token) or a raw CSS color as an escape hatch; an optional icon to signal status by shape instead of the dot (recommended when multiple statuses coexist; valid names: close, chevronDown, chevronLeft, chevronRight, check, success, error, warning, info, calendar, clock, externalLink, menu, moreHorizontal, search, arrowUp, arrowDown, arrowsUpDown, funnel, eyeSlash, viewColumns, copy, checkDouble, wrench, stop, microphone); and a required accessible label (announced via role="img" and shown in a tooltip on hover, so a status is never conveyed by color alone). Return null for rows with no status. Memoize with useCallback for a stable plugin identity.',
+      required: true,
+    },
+  ],
+};
+
+/** @type {import('../docs-types').TranslationDoc} */
+export const docsDense = {
+  description:
+    'Returns a TablePlugin that prepends a narrow per-row status column: a colored dot, or an icon when provided (shape + color beats color alone for a11y). getStatus maps a row to {color, icon?, label} or null. color is a semantic name (success/error/warning/etc.) mapped to a theme token, or a raw CSS color. label is required (tooltip + accessible name). Memoize getStatus with useCallback.',
+  propDescriptions: {
+    getStatus:
+      'Map a row to {color, icon?, label} or null. color = semantic status name (mapped to a token) or raw CSS; icon = shape signifier (a11y); label = required accessible name (tooltip + role="img"). Memoize with useCallback.',
+  },
+};