@elliemae/ds-data-table 3.70.0-next.2 → 3.70.0-next.4

package/skills/ds-data-table-boundaries/SKILL.md

@@ -0,0 +1,363 @@
+---
+name: ds-data-table-boundaries
+description: >
+  When NOT to use @elliemae/ds-data-table. Row actions column via renderRowActions +
+  DSMenuButton (not Column.Cell). State access priority inside custom Cell renderers:
+  (1) project state manager for app-level state; (2) CellRendererProps IoC arguments
+  (row, column, cell, isRowSelected, isDisabledRow, draggableProps); (3) useWholeStore
+  last resort only. Arrow key conflict handling required when DSMenuButton is inside a
+  DataTable cell. DataTable-as-form forbidden — use @elliemae/ds-grid.
+type: core
+library: ds-data-table
+library_version: '3.60.0'
+sources:
+  - '@elliemae/ds-data-table:dist/types/react-desc-prop-types.d.ts'
+---
+
+## useWholeStore — exported hook, highest render cost
+
+`useWholeStore` is the only exported store hook. It subscribes to all internal DataTable state with no selector and re-renders the consumer on any state change anywhere in the table.
+
+## State access hierarchy inside custom Cell renderers
+
+When a custom Cell component (`Column.Cell`) needs state, follow this priority order:
+
+**1. Project state manager** — for app-level state (filter values, pagination, global UI flags). Connect directly to the Redux selector, Zustand store, or Jotai atom. This produces the best performance (selective subscriptions) and the best app-side maintainability.
+
+**2. CellRendererProps IoC arguments** — for DataTable-provided context. These are passed in directly with zero subscription cost:
+
+```ts
+interface CellRendererProps {
+  row: InternalRow;
+  column: InternalColumn;
+  cell: Cell;
+  isRowSelected: boolean;
+  isDisabledRow?: boolean;
+  isDragOverlay: boolean;
+  shouldAddExpandCell: boolean;
+  draggableProps?: DraggablePropsT;
+  domIdAffix?: string;
+}
+```
+
+**3. `useWholeStore` — last resort only.** Subscribes to all internal DataTable state with no selector. Re-renders the consumer on any change anywhere in the table. If you have reached for `useWholeStore`, stop and reconsider whether the state manager or an OOB feature can satisfy the requirement instead.
+
+If neither the state manager nor `CellRendererProps` cover the requirement, that is an architecture signal: the Cell is doing too much, or the requirement should route through an OOB feature.
+
+## When NOT to use DataTable
+
+**Reach for a layout grid with form components instead when:**
+
+- The layout is a form with many editable fields arranged in rows and columns
+- The primary purpose is data entry, not data display
+- There are no sorting, filtering, selection, or pagination requirements
+
+In this design system, `@elliemae/ds-grid` is the correct layout primitive for that use case. Consult its own documentation for usage.
+
+**Editable cells are acceptable when:**
+
+- Used sparingly for inline editing of individual values in a data display context
+- `column.editable: 'ds-edit-text'` or `column.editable: 'ds-edit-combobox'` applies to a small number of columns
+
+**Editable cells are NOT acceptable when:**
+
+- The entire table is editable and functions as a data-entry form
+
+## Row actions column — renderRowActions
+
+When a column is needed exclusively for per-row action buttons, use the dedicated `renderRowActions` prop — not `Column.Cell`. Two valid patterns depending on the number of action levels:
+
+### Single-level flat actions — Toolbar + DSToolbarV2
+
+Use when each action is a direct button (delete, print, copy, edit) with no sub-menus.
+
+```jsx
+import { DataTable, Toolbar } from '@elliemae/ds-data-table';
+import { DSToolbarV2, DSToolbarItemV2 } from '@elliemae/ds-toolbar-v2';
+import { DSButtonV3 } from '@elliemae/ds-button-v2';
+
+const RowActionsRenderer = React.memo((props) => (
+  <Toolbar {...props}>
+    <DSToolbarV2 withDepth={false}>
+      <DSToolbarItemV2
+        render={(itemProps) => (
+          <DSButtonV3 autoFocus buttonType="icon" {...itemProps} aria-label="Delete">
+            {/* icon */}
+          </DSButtonV3>
+        )}
+      />
+      {/* ...additional DSToolbarItemV2 per action */}
+    </DSToolbarV2>
+  </Toolbar>
+));
+
+const renderRowActions = { columnWidth: 32, renderer: RowActionsRenderer };
+
+<DataTable columns={columns} data={rows} height={500} renderRowActions={renderRowActions} />;
+```
+
+`Toolbar` (from `@elliemae/ds-data-table`) is a required wrapper — it handles the DataTable keyboard integration. `DSToolbarItemV2` passes `itemProps` which includes `tabIndex` and `innerRef` wiring automatically.
+
+### Multi-level menus — DSMenuButton
+
+Use when actions have sub-menus or multi-level structure.
+
+```tsx
+import { BUTTON_TYPES } from '@elliemae/ds-button-v2';
+import { type DSDataTableT } from '@elliemae/ds-data-table';
+import { Grid } from '@elliemae/ds-grid';
+import { MoreOptionsVert } from '@elliemae/ds-icons';
+import { DSMenuButton } from '@elliemae/ds-menu-button';
+
+const RowActionsRenderer: DSDataTableT.RenderRowActionsConfig['renderer'] = React.memo(
+  ({ isRowSelected, cell }) => {
+    const { ref } = cell as unknown as { ref: React.MutableRefObject<HTMLButtonElement> };
+
+    const handleConflictingKeyPresses = React.useCallback<React.KeyboardEventHandler<HTMLDivElement>>(
+      (event) => {
+        if (event.key === 'ArrowUp' || event.key === 'ArrowDown') {
+          event.stopPropagation();
+          event.preventDefault();
+        }
+      },
+      [],
+    );
+
+    return (
+      <Grid minHeight="100%" minWidth="100%" justifyContent="center" alignItems="center" onKeyDown={handleConflictingKeyPresses}>
+        <DSMenuButton
+          innerRef={ref}
+          tabIndex={isRowSelected ? 0 : -1}
+          buttonType={BUTTON_TYPES.ICON}
+          aria-label="Show row actions, to resume table row navigation press tab"
+          {/* ...DSMenuButton props per scenario (options, onActivateItem, etc.) */}
+        >
+          <MoreOptionsVert />
+        </DSMenuButton>
+      </Grid>
+    );
+  },
+);
+
+const renderRowActions: DSDataTableT.RenderRowActionsConfig = { columnWidth: 32, renderer: RowActionsRenderer };
+
+<DataTable columns={columns} data={rows} height={500} renderRowActions={renderRowActions} />
+```
+
+**`onKeyDown` on the Grid wrapper is required.** `DSMenuButton` uses ArrowUp/ArrowDown to navigate menu items. Without `stopPropagation`, those keystrokes also move the DataTable's row focus — the two navigation models conflict silently.
+
+**`aria-label` must include the return instruction.** Screen reader users cannot infer how to get back to table navigation. The label `"Show row actions, to resume table row navigation press tab"` makes this explicit.
+
+## Common Mistakes
+
+### CRITICAL Using DataTable to implement a form in rows and columns
+
+Wrong:
+
+```jsx
+// DataTable driving an editable grid of loan fields
+const columns = [
+  { Header: 'Loan Number', accessor: 'loanNumber', editable: 'ds-edit-text' },
+  { Header: 'Borrower', accessor: 'borrower', editable: 'ds-edit-combobox' },
+  { Header: 'Amount', accessor: 'amount', editable: 'ds-edit-text' },
+  { Header: 'Rate', accessor: 'rate', editable: 'ds-edit-text' },
+  // ... every field is editable
+];
+<DataTable columns={columns} data={formRows} height={500} />;
+```
+
+Correct: use a layout grid with form components instead — `@elliemae/ds-grid` in this design system. DataTable has no role in data entry.
+
+DataTable is a data-viewing component. Turning it into a fully editable form violates its semantic role, breaks a11y, and loses all data management features.
+
+Source: https://dimsum.mortgagetech.ice.com/iframe.html?id=components-grid--documentation
+
+---
+
+### HIGH Reaching for useWholeStore — always signals being outside the IoC surface
+
+Wrong:
+
+```jsx
+import { useWholeStore } from '@elliemae/ds-data-table';
+
+const MyCell = ({ row, column }) => {
+  const { tableProps } = useWholeStore(); // subscribes to everything
+  return <span style={{ color: tableProps.filters.length ? 'red' : 'black' }}>{row.original.name}</span>;
+};
+```
+
+Correct:
+
+```jsx
+// These examples are illustrative only — the style logic shown does not represent
+// a real use case. The point is to show where each category of state comes from.
+
+// Option A — app-level state comes from the project state manager directly
+const MyCell = ({ row, column }) => {
+  const activeFilters = useSelector(selectTableFilters); // Redux/Zustand/Jotai
+  return <span style={{ color: activeFilters.length ? 'red' : 'black' }}>{row.original.name}</span>;
+};
+
+// Option B — DataTable-provided context comes from CellRendererProps IoC arguments
+const MyCell = ({ row, isRowSelected }) => {
+  return <span style={{ fontWeight: isRowSelected ? 'bold' : 'normal' }}>{row.original.name}</span>;
+};
+```
+
+`useWholeStore` re-renders the consumer on any change in either internal store. All out-of-the-box interactions expose everything needed via IoC callback arguments. Needing `useWholeStore` means the Cell requires something outside its intended surface — stop, evaluate OOB alternatives, and if blocked, contact the Dimsum team through your organization's established channel (ICE engineers: Teams/Jira; partners: your org's point of contact for Dimsum).
+
+---
+
+### HIGH Using editable cells as the primary data-entry mechanism for a form
+
+Wrong:
+
+```jsx
+// Every column is editable — DataTable used as a spreadsheet-style form
+const columns = allFormFields.map((field) => ({
+  Header: field.label,
+  accessor: field.key,
+  editable: 'ds-edit-text',
+}));
+```
+
+Correct:
+
+```jsx
+// Sparse inline editing is acceptable
+const columns = [
+  { Header: 'Name', accessor: 'name' },
+  { Header: 'Notes', accessor: 'notes', editable: 'ds-edit-text' }, // one editable column
+];
+```
+
+Editable cells (`ds-edit-text`, `ds-edit-combobox`) are tolerable for sparse inline editing of individual values. Using them to turn DataTable into a primary data-entry form violates its semantic role.
+
+Source: https://dimsum.mortgagetech.ice.com/iframe.html?id=components-datatable--documentation
+
+---
+
+### CRITICAL Interactive element in custom Cell without tabIndex + cell.ref breaks keyboard navigation
+
+Wrong:
+
+```jsx
+// Button always tabbable — bypasses the table's row keyboard navigation model
+Cell: ({ row }) => (
+  <DSButtonV3 onClick={() => handleAction(row.original.id)}>
+    Action
+  </DSButtonV3>
+),
+```
+
+Correct:
+
+```jsx
+// tabIndex and cell.ref wire the element into the table's keyboard navigation model
+Cell: ({ row, cell, isRowSelected }) => (
+  <DSButtonV3
+    tabIndex={isRowSelected ? 0 : -1}
+    innerRef={cell.ref}
+    onClick={() => handleAction(row.original.id)}
+  >
+    Action
+  </DSButtonV3>
+),
+```
+
+The DataTable uses an Enter-to-enter-row keyboard model: Tab moves between rows; Enter "enters" a row to navigate its interactive elements; Escape exits back to row navigation. An interactive element with `tabIndex={0}` unconditionally is permanently tabbable from outside the row — it intercepts Tab focus and breaks the row navigation model entirely.
+
+Two props from `CellRendererProps` are required:
+
+- `tabIndex={isRowSelected ? 0 : -1}` — makes the element focusable only when the row is entered
+- `cell.ref` — registers the element as the row's focusable target so Enter moves focus to it
+
+For components that accept `innerRef`: pass `innerRef={cell.ref}`. For components that wrap the element: pass `containerProps={{ ref: cell.ref }}`. For standard DOM elements: pass `ref={cell.ref}`.
+
+Source: https://dimsum.mortgagetech.ice.com/iframe.html?id=components-datatable-features-cell--custom-cell-row-and-header
+
+---
+
+### HIGH Using Column.Cell for a row actions button instead of renderRowActions
+
+Wrong:
+
+```tsx
+const columns = [
+  {
+    Header: '',
+    accessor: 'actions',
+    Cell: ({ row, cell, isRowSelected }) => (
+      <DSMenuButton
+        innerRef={cell.ref}
+        tabIndex={isRowSelected ? 0 : -1}
+        options={getActions(row.original)}
+        buttonType={BUTTON_TYPES.ICON}
+      >
+        <MoreOptionsVert />
+      </DSMenuButton>
+    ),
+  },
+];
+```
+
+Correct — use `renderRowActions`:
+
+```tsx
+const renderRowActions: DSDataTableT.RenderRowActionsConfig = {
+  columnWidth: 32,
+  renderer: RowActionsRenderer,
+};
+
+<DataTable columns={columns} data={rows} height={500} renderRowActions={renderRowActions} />;
+```
+
+`renderRowActions` is the dedicated first-class API for per-row action columns. `Column.Cell` misses the arrow key conflict handler and loses built-in column width management for the actions column.
+
+Source: https://dimsum.mortgagetech.ice.com/iframe.html?id=components-datatable-advanced--with-multilevel-menu-button
+
+---
+
+### HIGH Nesting DSMenuButton inside DSToolbarV2 for multi-level row actions
+
+Wrong:
+
+```tsx
+// Toolbar wrapping a DSMenuButton for a multi-level actions column
+const RowActionsRenderer = React.memo((props) => (
+  <Toolbar {...props}>
+    <DSToolbarV2 withDepth={false}>
+      <DSToolbarItemV2
+        render={(itemProps) => (
+          <DSMenuButton {...itemProps} {/* ...options, onActivateItem, etc. */} />
+        )}
+      />
+    </DSToolbarV2>
+  </Toolbar>
+));
+```
+
+Correct — use `DSMenuButton` directly without the `Toolbar` / `DSToolbarV2` wrapper (see Multi-level menus pattern above).
+
+Nesting `DSMenuButton` inside `DSToolbarV2` for multi-level row actions is not natively supported by Dimsum. It requires a four-step manual a11y remediation (chevron as dialog trigger → dialog → toolbar → menu button) that the application team owns entirely and must maintain. `DSMenuButton` via `renderRowActions` directly is the designated supported path for this scenario.
+
+Source: https://dimsum.mortgagetech.ice.com/iframe.html?id=components-datatable-advanced--with-multilevel-menu-button
+
+---
+
+### HIGH Non-primitive row action props not memoized cause unnecessary re-renders
+
+Every non-primitive prop passed to DataTable must be a stable reference. For row actions, the props that require memoization are:
+
+| Prop                | Type     | Memoization                                                                    |
+| ------------------- | -------- | ------------------------------------------------------------------------------ |
+| `renderRowActions`  | object   | `useMemo` if constructed inside the component body, or defined at module level |
+| `dsDatatableHeadTh` | callback | `useCallback`                                                                  |
+
+`renderer` inside `renderRowActions` must be a stable component reference — define it at module level with `React.memo`. Non-stable references cause DataTable to re-render on every parent render cycle.
+
+---
+
+See also: ds-data-table-slots/SKILL.md — slot injection as the correct first alternative to custom Cell
+See also: ds-data-table-columns/SKILL.md — Column.Cell and Column.Header escalation path

package/skills/ds-data-table-columns/SKILL.md

@@ -0,0 +1,273 @@
+---
+name: ds-data-table-columns
+description: >
+  Column object configuration for @elliemae/ds-data-table. accessor, Header, width (px only),
+  textWrap, canSort + onColumnSort, isResizeable + onColumnSizeChange + colsLayoutStyle fixed,
+  hiddenColumns, dragAndDropColumns + onColumnsReorder, column grouping via nested columns array.
+  Column.Cell and Column.Header custom renderers are strongly discouraged — try slot injection first.
+type: core
+library: ds-data-table
+library_version: '3.60.0'
+requires:
+  - ds-data-table-setup
+sources:
+  - '@elliemae/ds-data-table:dist/types/react-desc-prop-types.d.ts'
+---
+
+## Setup
+
+```jsx
+import { DataTable } from '@elliemae/ds-data-table';
+
+const columns = [
+  { Header: 'Name', accessor: 'name' },
+  { Header: 'Salary', accessor: 'salary', width: 120 },
+  { Header: 'Position', accessor: 'position', canSort: true },
+];
+
+<DataTable columns={columns} data={rows} height={500} />;
+```
+
+## Core Patterns
+
+### IoC callback contract
+
+All column feature callbacks share the same contract:
+
+- **First argument** (`newColumns` / `newData`) — the pre-baked OOB result. For standard cases with no custom business logic, no custom cells, and no column grouping edge cases, dispatch this directly to the state manager. This is the intended fast path.
+- **Remaining arguments** — raw data (column ID, width, direction, reorder indexes). Use these when the OOB result falls short and custom handling is required (server-side operations, constraint validation, non-standard persistence).
+
+### Sorting
+
+```jsx
+const columns = [
+  { Header: 'Name', accessor: 'name', canSort: true },
+  { Header: 'Salary', accessor: 'salary', canSort: true },
+];
+
+// Full signature: (newColumns: Column[], headerId: string, direction: 'ASC' | 'DESC') => void
+// First arg is the OOB result — dispatch directly for standard cases
+// Use headerId + direction only if custom logic is needed (e.g. server-side sort)
+const handleColumnSort = useCallback((newColumns, headerId, direction) => dispatch(setColumns(newColumns)), []);
+
+<DataTable columns={columns} data={rows} height={500} onColumnSort={handleColumnSort} />;
+```
+
+### Column resizing
+
+```jsx
+// isResizeable requires colsLayoutStyle='fixed' (the default — set it explicitly)
+
+// Full signature: (newColumns: Column[], headerId: string, width: number) => void
+// First arg is the OOB result — dispatch directly for standard cases
+// Use headerId + width only if custom logic is needed (e.g. resize constraints, persistence)
+const handleColumnSizeChange = useCallback((newColumns, headerId, width) => dispatch(setColumns(newColumns)), []);
+
+<DataTable
+  columns={columns}
+  data={rows}
+  height={500}
+  colsLayoutStyle="fixed"
+  isResizeable
+  onColumnSizeChange={handleColumnSizeChange}
+/>;
+```
+
+### Column drag & drop reorder
+
+```jsx
+// disableDnD: true on a column prevents that specific column from being dragged
+const columns = [
+  {
+    Header: 'Name',
+    columns: [
+      { Header: 'First', accessor: 'first' },
+      { Header: 'Last', accessor: 'last' },
+    ],
+  },
+  { Header: 'Info', columns: [{ Header: 'Date', accessor: 'date', disableDnD: true }] },
+];
+
+// Full signature: (newData: Column[], indexes: { targetIndex: number; fromIndex: number }) => void
+// First arg is the OOB result — dispatch directly for standard cases
+// Use targetIndex + fromIndex only if custom logic is needed (e.g. reorder validation, server sync)
+const handleColumnsReorder = useCallback((newData, { targetIndex, fromIndex }) => dispatch(setColumns(newData)), []);
+
+<DataTable columns={columns} data={rows} height={500} dragAndDropColumns onColumnsReorder={handleColumnsReorder} />;
+```
+
+### Column grouping (nested columns)
+
+```jsx
+const columns = [
+  {
+    Header: 'Identity',
+    columns: [
+      { Header: 'First Name', accessor: 'firstName' },
+      { Header: 'Last Name', accessor: 'lastName' },
+    ],
+  },
+  {
+    Header: 'Details',
+    columns: [
+      { Header: 'Position', accessor: 'position' },
+      { Header: 'Country', accessor: 'country' },
+    ],
+  },
+];
+```
+
+## Common Mistakes
+
+### HIGH isResizeable with colsLayoutStyle auto silently breaks resizing
+
+Wrong:
+
+```jsx
+<DataTable columns={columns} data={rows} height={500} colsLayoutStyle="auto" isResizeable />
+```
+
+Correct:
+
+```jsx
+<DataTable
+  columns={columns}
+  data={rows}
+  height={500}
+  colsLayoutStyle="fixed"
+  isResizeable
+  onColumnSizeChange={handleResize}
+/>
+```
+
+`colsLayoutStyle='auto'` fills the container by distributing column widths equally. Under `auto`, `onColumnSizeChange` does not reliably track individual column widths — custom resize redistribution is not supported. Use `colsLayoutStyle='fixed'` (the default) whenever `isResizeable` and `onColumnSizeChange` are required.
+
+Source: https://dimsum.mortgagetech.ice.com/iframe.html?id=components-datatable-features-column--dynamic-columns-layout-1
+
+---
+
+### HIGH Using deprecated onColumnSortChange instead of onColumnSort
+
+Wrong:
+
+```jsx
+<DataTable columns={columns} data={rows} height={500} onColumnSortChange={handleSort} />
+```
+
+Correct:
+
+```jsx
+const handleColumnSort = useCallback((newColumns, columnId, direction) => handleSort(newColumns), []);
+
+<DataTable columns={columns} data={rows} height={500} onColumnSort={handleColumnSort} />;
+```
+
+`onColumnSortChange` is deprecated. Migrate on sight.
+
+Source: https://dimsum.mortgagetech.ice.com/iframe.html?id=components-datatable--documentation
+
+---
+
+### HIGH Using deprecated onColumnResize instead of onColumnSizeChange
+
+Wrong:
+
+```jsx
+<DataTable columns={columns} data={rows} height={500} onColumnResize={handleResize} />
+```
+
+Correct:
+
+```jsx
+const handleColumnSizeChange = useCallback((newColumns, headerId, width) => handleResize(newColumns), []);
+
+<DataTable columns={columns} data={rows} height={500} onColumnSizeChange={handleColumnSizeChange} />;
+```
+
+`onColumnResize` is deprecated. Migrate on sight.
+
+Source: https://dimsum.mortgagetech.ice.com/iframe.html?id=components-datatable--documentation
+
+---
+
+### HIGH Reaching for Column.Cell when slot injection solves the requirement
+
+Wrong:
+
+```jsx
+const columns = [
+  {
+    Header: 'Status',
+    accessor: 'status',
+    Cell: ({ row }) => (
+      <span style={{ color: row.original.status === 'error' ? 'red' : 'inherit' }}>{row.original.status}</span>
+    ),
+  },
+];
+```
+
+Correct:
+
+```jsx
+// Use dsDatatableCell slot injection — no custom Cell needed
+const cellProps = useCallback((cell) => {
+  if (cell.row.original.status === 'error') return { style: { color: 'red' } };
+  return {};
+}, []);
+
+<DataTable columns={columns} data={rows} height={500} dsDatatableCell={cellProps} />;
+```
+
+Custom Cell renderers lose built-in filtering integration, degrade virtualization performance, and remove embedded a11y. Try slot injection first. If a custom Cell is unavoidable, read `ds-data-table-boundaries/SKILL.md` in full, re-evaluate the plan against everything in that skill, and only then implement.
+
+Source: https://dimsum.mortgagetech.ice.com/iframe.html?id=components-datatable-advanced--target-specific-row-style
+
+---
+
+### MEDIUM Column width in non-pixel units
+
+Wrong:
+
+```jsx
+{ Header: 'Name', accessor: 'name', width: '20%' }
+```
+
+Correct:
+
+```jsx
+{ Header: 'Name', accessor: 'name', width: 200 }
+```
+
+Column `width` accepts only pixel values (number or `"Npx"` string). Percentage widths are not supported.
+
+Source: https://dimsum.mortgagetech.ice.com/iframe.html?id=components-datatable--documentation
+
+---
+
+### HIGH Non-primitive column props not memoized cause unnecessary re-renders
+
+Every non-primitive prop passed to DataTable must be a stable reference. For column configuration, the props that require memoization are:
+
+| Prop                 | Type     | Memoization                     |
+| -------------------- | -------- | ------------------------------- |
+| `columns`            | array    | `useMemo`                       |
+| `hiddenColumns`      | array    | `useMemo` if constructed inline |
+| `onColumnSort`       | callback | `useCallback`                   |
+| `onColumnSizeChange` | callback | `useCallback`                   |
+| `onColumnsReorder`   | callback | `useCallback`                   |
+
+Non-stable references cause DataTable to re-render on every parent render cycle regardless of whether column state actually changed.
+
+---
+
+See also: ds-data-table-slots/SKILL.md — row and cell theming without custom Cell
+See also: ds-data-table-migration/SKILL.md — deprecated sort/resize callback migration
+
+---
+
+## When this isn't enough
+
+If the documented patterns cannot satisfy the requirement, contact the Dimsum team:
+
+**ICE internal:** Microsoft Teams — Dimsum channel (informal) / Jira Dimsum board (formal)
+**Partners:** Your organization's Dimsum point of contact