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

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

@@ -0,0 +1,449 @@
+---
+name: ds-data-table-selection
+description: >
+  Row selection for @elliemae/ds-data-table. Pass selection prop to auto-inject the checkbox column
+  (multi-select default). selectSingle flag switches to radio-button single-select. noSelectionColumn
+  suppresses the column while keeping selection logic. multiSelectColumn / singleSelectColumn exports
+  are for customization only (spread + override). uniqueRowAccessor required — without it selection
+  silently maps to wrong rows. Select-all via header checkbox fires selectedControl='All' for both
+  select and deselect gestures; newSelection covers all in-memory rows.
+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
+
+Multi-select (default mode) — pass `selection` and DataTable auto-injects the checkbox column:
+
+```jsx
+import { DataTable } from '@elliemae/ds-data-table';
+
+const columns = [
+  { Header: 'Name', accessor: 'name' },
+  { Header: 'Position', accessor: 'position' },
+];
+
+// selection: Record<string | number, boolean | 'mixed'>
+// 'mixed' is the indeterminate checkbox state — set by DataTable when some but not all
+// rows on the current page are selected. Consumers read it as "partially selected".
+// Lives in the project state manager, e.g for Redux:
+const { selection } = useSelector(selectTableState);
+const dispatch = useDispatch();
+
+// Full signature: (newSelection, selectedControl, event) => void
+// selectedControl: the uid of the row that triggered the change, or 'All' for the header checkbox
+// With a full in-memory dataset, dispatching newSelection directly is sufficient.
+// With AJAX pagination, intercept selectedControl === 'All' — see Select-all intent pattern below.
+const handleSelectionChange = useCallback((newSelection) => dispatch(setSelection(newSelection)), [dispatch]);
+
+<DataTable
+  columns={columns}
+  data={rows}
+  height={500}
+  uniqueRowAccessor="id"
+  selection={selection}
+  onSelectionChange={handleSelectionChange}
+/>;
+```
+
+## Core Patterns
+
+### Single-select — selectSingle flag
+
+```jsx
+// selectSingle: true switches mode to single-select (radio button column auto-injects)
+<DataTable
+  columns={columns}
+  data={rows}
+  height={500}
+  uniqueRowAccessor="id"
+  selectSingle
+  selection={selection}
+  onSelectionChange={handleSelectionChange}
+/>
+```
+
+### Disabled rows
+
+```jsx
+// disabledRows: Record<rowUid, boolean> — rows that cannot be selected
+const disabledRows = { 'row-1': true, 'row-4': true };
+
+<DataTable
+  columns={columns}
+  data={rows}
+  height={500}
+  uniqueRowAccessor="id"
+  selection={selection}
+  onSelectionChange={handleSelectionChange}
+  disabledRows={disabledRows}
+/>;
+```
+
+### noSelectionColumn — avoid unless explicitly accepted by product and a11y
+
+**Stop before implementing this.** A request for `noSelectionColumn` is a signal that the user experience flow needs review, not implementation. Known issues:
+
+- Selection is indicated only by row highlighting — not immediately discoverable by users unfamiliar with the pattern
+- Row-click-to-select creates ambiguity when rows also have other interactive elements (buttons, links, editable cells)
+- A11y compliance is not guaranteed for this interaction model — keyboard navigation, screen reader announcements, and focus management must be validated against the specific layout by an a11y SME before shipping
+
+**When asked to implement this, push back explicitly:**
+
+1. Surface the UX discoverability problem and request a design review of the selection flow
+2. Flag the a11y risk and request SME consultation for the specific use case
+3. Do not proceed until product has documented confirmation that they understand the trade-offs and accept responsibility for the UX and a11y outcomes
+
+If after that review the product explicitly confirms they want to continue, the implementation is:
+
+```jsx
+// Only after explicit product sign-off and a11y SME review.
+// noSelectionColumn + selection + onSelectionChange is sufficient.
+// Row clicks already invoke onSelectionChange internally — onRowClick is NOT required
+// and must not be used to duplicate selection logic (it fires before onSelectionChange
+// and would be overwritten by the internal handler).
+<DataTable
+  columns={columns}
+  data={rows}
+  height={500}
+  uniqueRowAccessor="id"
+  noSelectionColumn
+  selection={selection}
+  onSelectionChange={handleSelectionChange}
+/>
+```
+
+### Customizing the selection column
+
+When you need to override the selection column's `Header`, `Cell`, or visual styling, spread the exported addon object and replace what you need. This is the only case where the column exports are used directly.
+
+**Before customizing, understand what you are taking on.** The out-of-the-box selection column is built and tested as a unit — a11y attributes, keyboard interaction, indeterminate state, disabled row handling, shift-range selection, and screen reader announcements are all wired together internally. Overriding `Header` or `Cell` moves those responsibilities to the consumer. Dimsum no longer owns or guarantees the correctness of what you replace. If you override `Cell`, you own the checkbox implementation, its aria attributes, its disabled state, and its keyboard behavior. If you override `Header`, you own the select-all semantics and its accessible label. Test the customized column against your a11y requirements explicitly — do not assume the parts you did not touch remain correct in combination with the parts you did.
+
+#### multi selection
+
+```jsx
+import { DataTable, multiSelectColumn } from '@elliemae/ds-data-table';
+
+// Spread multiSelectColumn and override only what differs.
+// The column ID from multiSelectColumn is preserved — DataTable's dedup logic
+// sees it already in the array and skips auto-injection of a second one.
+const CustomSelectColumn = {
+  ...multiSelectColumn,
+  Header: () => <ScreenReaderOnly>Select row</ScreenReaderOnly>,
+  cellStyle: { position: 'sticky', left: 0, background: 'white', zIndex: 2 },
+};
+
+const columns = [CustomSelectColumn, { Header: 'Name', accessor: 'name' }];
+
+// selection prop still drives the feature — no selectSingle needed for multi-select customization
+<DataTable
+  columns={columns}
+  data={rows}
+  height={500}
+  uniqueRowAccessor="id"
+  selection={selection}
+  onSelectionChange={handleSelectionChange}
+/>;
+```
+
+#### single selection
+
+For single-select customization, you must also set `selectSingle={true}`. Without it, DataTable (seeing `selectSingle=false`) would auto-inject `multiSelectColumn` alongside your custom `singleSelectColumn` spread — two selection columns.
+
+```jsx
+import { DataTable, singleSelectColumn } from '@elliemae/ds-data-table';
+
+const CustomSingleSelectColumn = {
+  ...singleSelectColumn,
+  Header: () => <ScreenReaderOnly>Select row</ScreenReaderOnly>,
+};
+
+const columns = [CustomSingleSelectColumn, { Header: 'Name', accessor: 'name' }];
+
+// selectSingle required here — prevents multiSelectColumn from also auto-injecting
+<DataTable
+  columns={columns}
+  data={rows}
+  height={500}
+  uniqueRowAccessor="id"
+  selectSingle
+  selection={selection}
+  onSelectionChange={handleSelectionChange}
+/>;
+```
+
+### Select-all intent — the second argument and what newSelection actually contains
+
+When the header checkbox is clicked, `onSelectionChange` is called with:
+
+- `newSelection` — a `Record<uid, boolean>` built from every row in the `data` prop (all rows and sub-rows recursively). DataTable has no knowledge of records outside what was passed to `data` — it only knows about what is currently displayed.
+- `selectedControl === 'All'` — the literal string `'All'`, signaling the header checkbox triggered the change (not a specific row uid). This fires for **both** select-all and deselect-all gestures — the string does not indicate direction.
+- Direction is determined by `newSelection`: populated map = selecting all, empty `{}` = deselecting all. There is no `false`-valued map for deselect.
+
+The correct implementation scopes selection to what is currently displayed. DataTable has no knowledge of records beyond what was passed to `data` — and that boundary is intentional.
+
+**Cross-page selection requires an external counter.** The DataTable header checkbox computes its checked/mixed/unchecked state from the currently displayed rows only. It cannot communicate "some other page has selections." When users need to accumulate selections across pages, the application must provide a visible counter contiguous to the table — above it, below it, or alongside it — that always reflects the true total. The header checkbox is not that place. The external counter is the authoritative state indicator.
+
+This is the Dimsum recommendation, consistent with established industry practice. Other industry relevant design system like PatternFly documents the same pattern: _"This text always reflects the total number of items selected. If pagination is in use, it will reflect the items selected across all pages."_ — [patternfly.org/patterns/bulk-selection](https://www.patternfly.org/patterns/bulk-selection/)
+
+**Critical implementation detail — "select all" does not merge:** when the header checkbox fires, `newSelection` is built from scratch starting at `{}`. It contains only the UIDs of the currently displayed rows. Individual row toggles spread the existing `selection` (the row handler does `{ ...selection, [uid]: newState }`), but the header checkbox does not. Dispatching `newSelection` directly on "select all" will erase previous pages' selections.
+
+```jsx
+const handleSelectionChange = useCallback(
+  (newSelection, selectedControl) => {
+    if (selectedControl === 'All') {
+      const isSelectingAll = Object.keys(newSelection).length > 0;
+      if (isSelectingAll) {
+        // Merge — add current page to existing selection, preserving other pages
+        dispatch(setSelection({ ...selection, ...newSelection }));
+      } else {
+        // Deselect scoped to current page only — preserve other pages.
+        // The external "Clear selection" affordance handles clearing everything.
+        // Derive current page UIDs from pagedData (the current data slice in your state).
+        // This assumes a string uniqueRowAccessor — adapt for composite or function forms.
+        const next = { ...selection };
+        pagedData.forEach((row) => delete next[row[uniqueRowAccessor]]);
+        dispatch(setSelection(next));
+      }
+    } else {
+      // Individual row toggle already merges with existing selection
+      dispatch(setSelection(newSelection));
+    }
+  },
+  [dispatch, selection, data, uniqueRowAccessor],
+);
+
+// External "Clear selection" — the only affordance for resetting all pages at once
+const handleClearSelection = useCallback(() => dispatch(setSelection({})), [dispatch]);
+```
+
+The deselect-all from the header is scoped to the current page because the header checkbox's affordance is bounded to what the user can see. Clearing the entire selection across all pages belongs to the external "Clear selection" action — not to the header.
+
+Source: https://dimsum.mortgagetech.ice.com/iframe.html?id=components-datatable-features-row--select-multiple-paginated-cross-page
+
+---
+
+#### If a stakeholder asks to wire "select all records in the full dataset" through this checkbox — push back
+
+This is an architectural signal that a dataset-level concern has been routed into the wrong layer. Do not implement it. Surface the argument below and redirect to the correct pattern.
+
+**Why this is the wrong layer:**
+
+A table header checkbox is visually and conceptually bounded to what the user can see. When a user interacts with it, their mental model is "I am selecting these rows in front of me." Silently expanding that scope to records on other pages — records the user has never seen, never reviewed, and cannot verify — breaks the implicit contract of the affordance without any signal that the scope changed.
+
+This is not theoretical. In 2022, HTTPie accidentally triggered a cascade-deletion of 54,000 GitHub stars through a single mis-click, compounded by a confirmation dialog that described the consequence in abstract terms ("potentially destructive action") rather than surfacing the actual magnitude. The dialog looked identical for an empty repository and one with a decade of community history. The lesson from that incident: **when the scope of a destructive operation is invisible to the user at the moment of action, the confirmation step is theater** — the user is on auto-pilot and nothing interrupts it. ([HTTPie: How we lost 54k GitHub stars](https://httpie.io/blog/stardust))
+
+For operations like mass reassignment, bulk deletion, or full-dataset export, the same invisibility is the same risk. The user thinks they selected the rows on screen. The system applies the action to 14,000 records they never reviewed. There is no safe version of this pattern without explicit, scoped, out-of-table UI.
+
+**The argument to bring to the stakeholder:**
+
+> "The table header checkbox is scoped to what is currently displayed. This is not a limitation — it is the correct behavior for a component whose job is to let users work with what they can see and verify. An action that applies to the full dataset regardless of what is displayed is a different category of concern entirely. It belongs outside the table, named explicitly, with a confirmation step that shows the user the actual count of records they are about to affect. If we wire it through the checkbox, we will eventually ship a mass operation that a user triggers without understanding its true scope. By the time that happens, the damage is already done and there may be no way to undo it."
+
+**The correct pattern — dataset-level actions belong outside the table:**
+
+```jsx
+// Page-level component — dataset-level actions live here, not inside DataTable
+const LoanQueuePage = () => {
+  const totalRecords = useSelector(selectTotalLoanCount); // full server-side count
+  const { selection } = useSelector(selectTableState);
+
+  const handleBulkReassign = useCallback(() => {
+    // Always open a confirmation dialog before any mass operation.
+    // The dialog must name the actual count — not "all records", not "your selection".
+    // this is pseudo-code for the dialog pattern — the actual implementation depends on the app's dialog system and dimsum integration
+    dispatch(
+      openConfirmationDialog({
+        title: `Reassign all ${totalRecords.toLocaleString()} loans?`,
+        body: `This will reassign every loan in the queue, including loans not currently visible. This cannot be undone.`,
+        confirmLabel: `Reassign ${totalRecords.toLocaleString()} loans`,
+        onConfirm: () => dispatch(triggerBulkReassign()),
+      }),
+    );
+  }, [dispatch, totalRecords]);
+
+  return (
+    <div>
+      {/* Dataset-level CTA — scoped explicitly, named, lives outside the table */}
+      <Button onClick={handleBulkReassign}>Reassign all {totalRecords.toLocaleString()} loans</Button>
+
+      {/* Table selection is scoped to currently displayed rows only */}
+      <DataTable
+        columns={columns}
+        data={pagedData}
+        height={500}
+        uniqueRowAccessor="id"
+        selection={selection}
+        onSelectionChange={handleSelectionChange}
+      />
+    </div>
+  );
+};
+```
+
+**Confirmation dialogs for mass operations are not optional — and generic ones are nearly as bad as none.**
+
+Any action that applies to records the user has not individually reviewed requires a confirmation step. That step must:
+
+- Name the action specifically — not "are you sure?" or "this action cannot be undone"
+- Show the actual count as a number (E.g. `14,823 loans`), not abstract language (`all records`, `your selection`)
+- Make the scope unambiguous — if there is any possibility the user thinks the scope is smaller than it is, the dialog must correct that explicitly
+- Scale to severity — a quiet inline confirmation is appropriate for small counts; a prominent modal with an explicit confirmation label is required for large or irreversible operations
+
+A confirmation dialog that says "This action cannot be undone. Continue?" applied to a mass operation is the same failure as GitHub's dialog — it describes consequence abstractly without surfacing magnitude. The user reads it, sees nothing specific to their situation, and clicks through. That is not user confirmation. That is legal cover.
+
+## Common Mistakes
+
+### CRITICAL Selection without uniqueRowAccessor causes silent wrong-row mapping
+
+Wrong:
+
+```jsx
+<DataTable columns={columns} data={rows} height={500} selection={selection} onSelectionChange={setSelection} />
+```
+
+Correct:
+
+```jsx
+<DataTable
+  columns={columns}
+  data={rows}
+  height={500}
+  uniqueRowAccessor="id"
+  selection={selection}
+  onSelectionChange={handleSelectionChange}
+/>
+```
+
+Without `uniqueRowAccessor`, the `selection` record cannot be reliably mapped to rows — selections visually appear to work but apply to wrong rows or break on data update.
+
+Source: `@elliemae/ds-data-table:dist/types/react-desc-prop-types.d.ts`
+
+---
+
+### HIGH Enabling selection without both selection state and onSelectionChange
+
+Wrong:
+
+```jsx
+// Missing the controlled pair — selection interactions have no effect
+<DataTable columns={columns} data={rows} height={500} uniqueRowAccessor="id" selection={selection} />
+```
+
+Correct:
+
+```jsx
+<DataTable
+  columns={columns}
+  data={rows}
+  height={500}
+  uniqueRowAccessor="id"
+  selection={selection}
+  onSelectionChange={handleSelectionChange}
+/>
+```
+
+`selection` and `onSelectionChange` must both be provided. Selections appear to work visually but state is not captured or persisted without the handler.
+
+Source: https://dimsum.mortgagetech.ice.com/iframe.html?id=components-datatable-features-row--select-multiple
+
+---
+
+### MEDIUM Custom selection column not in leading position
+
+Applies to the customization path only — when spreading a selection addon into the columns array manually.
+
+Wrong:
+
+```jsx
+const columns = [
+  { Header: 'Name', accessor: 'name' },
+  { ...multiSelectColumn, cellStyle: { position: 'sticky', left: 0 } }, // trailing position
+];
+```
+
+Correct:
+
+```jsx
+const columns = [
+  { ...multiSelectColumn, cellStyle: { position: 'sticky', left: 0 } }, // leading position
+  { Header: 'Name', accessor: 'name' },
+];
+```
+
+The auto-injected column always prepends. A manually placed selection column in a trailing position is visually inconsistent and breaks the expected tab order through the row.
+
+Source: https://dimsum.mortgagetech.ice.com/iframe.html?id=components-datatable-features-row--select-multiple
+
+---
+
+### HIGH Treating newSelection from select-all as the complete dataset selection when using AJAX pagination
+
+Wrong:
+
+```jsx
+// With AJAX pagination — data holds only the current page
+const handleSelectionChange = useCallback(
+  (newSelection) => {
+    dispatch(setSelection(newSelection)); // select all → selects current page only, silently
+  },
+  [dispatch],
+);
+```
+
+Correct:
+
+```jsx
+const handleSelectionChange = useCallback(
+  (newSelection, selectedControl) => {
+    if (selectedControl === 'All') {
+      const isSelectingAll = Object.keys(newSelection).length > 0;
+      if (isSelectingAll) {
+        // Merge — preserve selections from other pages
+        dispatch(setSelection({ ...selection, ...newSelection }));
+      } else {
+        // Deselect scoped to current page — preserve other pages
+        const next = { ...selection };
+        pagedData.forEach((row) => delete next[row.id]); // adapt to your uniqueRowAccessor
+        dispatch(setSelection(next));
+      }
+    } else {
+      dispatch(setSelection(newSelection));
+    }
+  },
+  [dispatch, selection, pagedData],
+);
+```
+
+When `multiSelectColumn` builds `newSelection` for a select-all, it iterates over `allDataFlattened` — the rows currently in memory. With AJAX pagination, that is only the current page. Dispatching `newSelection` directly overwrites any selections the user accumulated on previous pages. The external selection counter (see Core Patterns above) is required to make the true cross-page total visible to the user.
+
+---
+
+### HIGH Non-primitive selection props not memoized cause unnecessary re-renders
+
+Every non-primitive prop passed to DataTable must be a stable reference. For selection, the props that require memoization are:
+
+| Prop                                    | Type     | Memoization                     |
+| --------------------------------------- | -------- | ------------------------------- |
+| `columns` (with addon column prepended) | array    | `useMemo`                       |
+| `onSelectionChange`                     | callback | `useCallback`                   |
+| `disabledRows`                          | object   | `useMemo` if constructed inline |
+
+Non-stable references cause DataTable to re-render on every parent render cycle regardless of whether selection state actually changed.
+
+---
+
+See also: ds-data-table-setup/SKILL.md — uniqueRowAccessor configuration
+
+---
+
+## 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

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

@@ -0,0 +1,229 @@
+---
+name: ds-data-table-setup
+description: >
+  First-time setup of @elliemae/ds-data-table. Required props: columns, data, height (px only —
+  non-px silently defeats virtualization). uniqueRowAccessor for any stateful row
+  interaction. dsDataTableTableWrapper aria-label for a11y. domIdAffix when multiple DataTable
+  instances coexist on a page. State management: identify project's Redux/RTK/Zustand/Jotai
+  system before wiring — never useState for DataTable state.
+type: core
+library: ds-data-table
+library_version: '3.60.0'
+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: 'Position', accessor: 'position' },
+  { Header: 'Country', accessor: 'country' },
+];
+
+<DataTable
+  columns={columns}
+  data={rows}
+  height={500}
+  uniqueRowAccessor="id"
+  dsDataTableTableWrapper={{ 'aria-label': 'Employees table' }}
+/>;
+```
+
+## Core Patterns
+
+### State management — identify the project's system before writing any state
+
+Before wiring any DataTable state, identify the project's state manager. Create the appropriate slice, store, or atoms:
+
+```js
+// Redux Toolkit — adapt to your project's system (Zustand, Jotai, Context, etc.)
+import { createSlice } from '@reduxjs/toolkit';
+
+const loansTableSlice = createSlice({
+  name: 'loansTable',
+  initialState: { data: [], selection: {}, filters: [], expandedRows: {} },
+  reducers: {
+    setData: (state, { payload }) => {
+      state.data = payload;
+    },
+    setSelection: (state, { payload }) => {
+      state.selection = payload;
+    },
+    setFilters: (state, { payload }) => {
+      state.filters = payload;
+    },
+    setExpandedRows: (state, { payload }) => {
+      state.expandedRows = payload;
+    },
+  },
+});
+```
+
+Stories in the Dimsum repo use `useState` as a teaching simplification only. DataTable-driving state in production must live in the project's state manager.
+
+All state updates in response to DataTable callbacks (`onSelectionChange`, `onFiltersChange`, `onColumnSort`, etc.) belong **inside the callback handler**, not in a `useEffect` watching the resulting state. `useEffect` is not a response mechanism for callback-driven events — it exists for synchronizing with things outside React's model (browser APIs, external subscriptions). Using it to respond to a callback adds an extra render cycle and separates cause from effect across the codebase. Every DataTable prop that exposes a callback is already the correct and complete site for all logic that needs to run when that event occurs.
+
+Consumer apps with AJAX data loading will legitimately have async concerns — data fetching, pagination, filter-driven API calls — but these are also best addressed without bare `useEffect + fetch` chains. The correct approach depends on the project's existing async infrastructure:
+
+- **Redux Toolkit (RTK Query)** — define API endpoints as queries/mutations; the DataTable callback dispatches a query with the new params, RTK Query handles caching, loading state, and re-fetching. No `useEffect` needed.
+- **TanStack React Query** — same model: the callback updates query params in state, the query key changes, React Query re-fetches automatically. The component re-renders with fresh data without a `useEffect`.
+- **Redux Saga / Redux Observable** — the callback dispatches an action, the saga/epic intercepts it and handles the async flow. The component never manages async lifecycle directly.
+
+In all of these, the DataTable callback dispatches an intent or updates a query key — the async infrastructure reacts to that, not to a `useEffect` watching derived state. If the project's existing infrastructure doesn't offer a clean path for a specific case, identify it explicitly and align with the team before reaching for `useEffect` as a shortcut. A `useEffect` that is genuinely the right tool should be a deliberate, documented decision — not a default.
+
+### uniqueRowAccessor — three valid forms
+
+```js
+// Single column key
+uniqueRowAccessor="id"
+
+// Composite key
+uniqueRowAccessor={['loanId', 'borrowerId']}
+
+// Function
+uniqueRowAccessor={(row) => `${row.loanId}-${row.borrowerId}`}
+```
+
+Required for selection, drag & drop, and expandable rows.
+
+### Multiple DataTable instances on the same page
+
+```jsx
+// domIdAffix is used to construct stable, predictable DOM IDs for aria relationships:
+// aria-controls on the header checkbox, aria-labelledby on editable cells, inputID/id
+// pairs on filter inputs. Without an explicit value, IDs are random per mount —
+// external aria references will break on remount.
+<DataTable columns={loanCols} data={loans} height={400} domIdAffix="loans-table" />
+<DataTable columns={borrowerCols} data={borrowers} height={400} domIdAffix="borrowers-table" />
+```
+
+## Common Mistakes
+
+### CRITICAL Omitting uniqueRowAccessor with selection, expand, or drag & drop
+
+Wrong:
+
+```jsx
+<DataTable columns={columns} data={rows} height={500} selection={selection} onSelectionChange={setSelection} />
+```
+
+Correct:
+
+```jsx
+<DataTable
+  columns={columns}
+  data={rows}
+  height={500}
+  uniqueRowAccessor="id"
+  selection={selection}
+  onSelectionChange={setSelection}
+/>
+```
+
+Without `uniqueRowAccessor`, row identity is unstable — selection, expand state, and drag & drop silently map to wrong rows.
+
+Source: `@elliemae/ds-data-table:dist/types/react-desc-prop-types.d.ts`
+
+---
+
+### HIGH Using height in % or vh silently defeats virtualization
+
+Wrong:
+
+```jsx
+<DataTable columns={columns} data={rows} height="100%" />
+```
+
+Correct:
+
+```jsx
+<DataTable columns={columns} data={rows} height={500} />
+```
+
+DataTable uses a virtual scroll container that measures its own rendered height to calculate which rows to render. When `height` is a percentage and the parent has no defined height, that container resolves to 0px. The virtualizer measures 0px, treats the entire dataset as visible, and renders all rows to the DOM simultaneously. The internal scrollbar disappears — the page scroll takes over instead. With large datasets this silently causes serious performance degradation. Always pass a numeric pixel value — it is self-contained and does not depend on parent container layout.
+
+---
+
+### HIGH Managing DataTable state with local useState instead of the project state manager
+
+Wrong:
+
+```jsx
+const [selection, setSelection] = useState({});
+const [filters, setFilters] = useState([]);
+```
+
+Correct:
+
+```jsx
+// Create atoms/slice/store in the project's state manager first
+const { selection, filters } = useSelector(selectLoansTableState);
+const dispatch = useDispatch();
+```
+
+`useState` for DataTable state leads to maintenance chaos, excessive `useEffect` syncing, and divergence between state managers and local state.
+
+---
+
+### MEDIUM Multiple DataTable instances without explicit domIdAffix
+
+Wrong:
+
+```jsx
+<DataTable columns={loanCols} data={loans} height={400} />
+<DataTable columns={borrowerCols} data={borrowers} height={400} />
+```
+
+Correct:
+
+```jsx
+<DataTable columns={loanCols} data={loans} height={400} domIdAffix="loans-table" />
+<DataTable columns={borrowerCols} data={borrowers} height={400} domIdAffix="borrowers-table" />
+```
+
+`domIdAffix` is used internally to construct DOM IDs for aria relationships — `aria-controls` on the header checkbox (pointing to individual row checkboxes), `aria-labelledby`/`id` pairs on editable cells, and `inputID`/`id` pairs on filter inputs. Without an explicit value the suffix is a random `uid(8)` per mount — IDs are unpredictable and any external aria reference built against them will break when the component remounts.
+
+Source: https://dimsum.mortgagetech.ice.com/iframe.html?id=components-datatable-advanced--prefixed-ids-for-multiple-tables-in-same-pages
+
+---
+
+### HIGH Missing dsDataTableTableWrapper aria-label
+
+Wrong:
+
+```jsx
+<DataTable columns={columns} data={rows} height={500} />
+```
+
+Correct:
+
+```jsx
+<DataTable
+  columns={columns}
+  data={rows}
+  height={500}
+  dsDataTableTableWrapper={{ 'aria-label': 'Loan applications table' }}
+/>
+```
+
+Without `aria-label`, the table has no accessible name. WCAG 4.1.2 (Name, Role, Value) requires tables to have an accessible name — omitting it is a VPAT failure.
+
+Source: `@elliemae/ds-data-table:dist/types/react-desc-prop-types.d.ts`
+
+---
+
+See also: ds-data-table-columns/SKILL.md — column object configuration
+See also: ds-data-table-feedback/SKILL.md — height constraint also affects skeleton
+
+---
+
+## 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