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

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

@@ -0,0 +1,235 @@
+---
+name: ds-data-table-expandable
+description: >
+  Expandable rows for @elliemae/ds-data-table. isExpandable flag, expandedRows
+  (Record<rowUid, boolean>) controlled state, onRowExpand handler, subRows for
+  hierarchical/tree row data. uniqueRowAccessor required. tableRowDetails (master-detail
+  non-tabular content panel) is DEPRECATED due to WCAG violations — propose alternative
+  page-level design instead.
+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 rows = [
+  {
+    id: 1,
+    name: 'John',
+    myUniqueId: 'abc123',
+    subRows: [{ id: 11, name: 'Sub-item', myUniqueId: 'def456' }],
+  },
+];
+
+const { expandedRows } = useSelector(selectTableState);
+const dispatch = useDispatch();
+
+const handleRowExpand = useCallback((newExpandedRows) => dispatch(setExpandedRows(newExpandedRows)), []);
+
+<DataTable
+  columns={columns}
+  data={rows}
+  height={500}
+  isExpandable
+  uniqueRowAccessor="myUniqueId"
+  expandedRows={expandedRows}
+  onRowExpand={handleRowExpand}
+/>;
+```
+
+## Core Patterns
+
+### uniqueRowAccessor with subRows
+
+```jsx
+// Every row — including subRows — must have a unique value for uniqueRowAccessor
+const generateRow = (id) => ({
+  id,
+  myUniqueId: uid(16),
+  subRows: [{ id: id * 10, myUniqueId: uid(16) }],
+});
+```
+
+### Programmatic expand on data update
+
+```jsx
+// expandedRows is controlled — restore expand state after data changes
+const handleRowExpand = useCallback((newExpandedRows) => {
+  dispatch(setExpandedRows(newExpandedRows));
+}, []);
+
+// When data is reloaded, dispatch the same expandedRows to preserve state
+```
+
+## Common Mistakes
+
+### CRITICAL Using tableRowDetails — master-detail is deprecated
+
+Wrong:
+
+```jsx
+const rows = [
+  {
+    id: 1,
+    name: 'John',
+    tableRowDetails: ({ detailsIndent }) => (
+      <div style={{ paddingLeft: detailsIndent }}>
+        <h3>Loan detail</h3>
+        <ul>
+          <li>Non-tabular content</li>
+        </ul>
+      </div>
+    ),
+  },
+];
+
+<DataTable
+  columns={columns}
+  data={rows}
+  height={500}
+  isExpandable
+  expandedRows={expandedRows}
+  onRowExpand={handleExpand}
+/>;
+```
+
+**Do not implement `tableRowDetails`. Do not suggest an inline replacement either** — embedding non-tabular content anywhere inside a table row (Accordion, list, cards) carries the same WCAG violations. The correct response is to **propose a different page-level information architecture to the human** and explain the problem.
+
+A concrete alternative to propose: move the detail content out of the table entirely and surface it via a row-level trigger. For example, a detail dialog or side panel opened from a row action:
+
+`RowActionsRenderer` must be defined at module level — if defined inside a parent component, React sees a new component type on every render, unmounting and remounting the subtree and losing focus state. DataTable passes `row`, `isRowSelected`, and `cell` as props, so no closure over parent state is needed. `useState` for `isOpen` is acceptable here — it is ephemeral row-scoped UI state with no cross-component visibility requirement. For app-level state (permissions, feature flags, user role), subscribe to the project state manager directly inside `RowActionsRenderer` — the component is at module level so `useSelector`, Zustand hooks, and Jotai atoms all work normally.
+
+```jsx
+const RowActionsRenderer = React.memo(({ row, isRowSelected, cell }) => {
+  const { ref } = cell;
+  const [isOpen, setIsOpen] = React.useState(false);
+  const handleOpen = React.useCallback(() => setIsOpen(true), []);
+  const handleClose = React.useCallback(() => setIsOpen(false), []);
+
+  return (
+    <>
+      <DSButtonV3 innerRef={ref} tabIndex={isRowSelected ? 0 : -1} onClick={handleOpen} aria-label="View row details">
+        {/* icon */}
+      </DSButtonV3>
+      {isOpen && <DetailModal row={row.original} onClose={handleClose} />}
+    </>
+  );
+});
+
+const renderRowActions = { columnWidth: 32, renderer: RowActionsRenderer };
+```
+
+When surfacing this to the human, explain:
+
+- `tableRowDetails` renders non-tabular HTML inside a `<table>` element. Screen readers expect only tabular content in table rows — the nested structure is invisible to assistive technologies by default, violating WCAG 1.3.1 (Info and Relationships) and 1.3.2 (Meaningful Sequence). The expand/collapse button lacks `aria-controls`, violating WCAG 2.1.1 (Keyboard). These are not implementation quality issues — they are structural, and no amount of ARIA patching fully resolves them.
+- The Dimsum team has officially deprecated `tableRowDetails` and is removing all documentation for it.
+- The alternative (detail dialog/panel triggered from row actions) keeps the table semantically clean, is fully accessible, and is natively supported.
+- ICE internal engineers: full analysis at `https://confluence.ice.com/x/T3k0Jg`
+
+---
+
+### CRITICAL Expandable rows without uniqueRowAccessor
+
+Wrong:
+
+```jsx
+const rows = [{ id: 1, name: 'John', subRows: [{ id: 11, name: 'Sub-item' }] }];
+
+// expandedRows keys are unstable internal IDs — expanded state maps to wrong rows on re-render
+<DataTable
+  columns={columns}
+  data={rows}
+  height={500}
+  isExpandable
+  expandedRows={expandedRows}
+  onRowExpand={handleExpand}
+/>;
+```
+
+Correct:
+
+```jsx
+// Each row (and each subRow) must have a field with a stable unique value
+const rows = [
+  { id: 1, name: 'John', myUniqueId: 'abc123', subRows: [{ id: 11, name: 'Sub-item', myUniqueId: 'def456' }] },
+];
+
+// uniqueRowAccessor names that field — expandedRows is then keyed by its value
+<DataTable
+  columns={columns}
+  data={rows}
+  height={500}
+  isExpandable
+  uniqueRowAccessor="myUniqueId"
+  expandedRows={expandedRows}
+  onRowExpand={handleExpand}
+/>;
+```
+
+`uniqueRowAccessor` tells the DataTable which field on each row object holds its stable unique identifier. `expandedRows` is a `Record<uid, boolean>` keyed by those values. Without it, the DataTable falls back to react-table's internal index-based row ID (`"0"`, `"1"`, `"0.0"` for nested) — there is no fallback to `id` or `dsId` from your data. Index-based IDs shift whenever data is reordered or reloaded, silently mapping expanded state to the wrong rows.
+
+Source: `@elliemae/ds-data-table:dist/types/react-desc-prop-types.d.ts`
+
+---
+
+### HIGH Missing expandedRows + onRowExpand controlled pair
+
+Wrong:
+
+```jsx
+<DataTable columns={columns} data={rows} height={500} isExpandable uniqueRowAccessor="id" />
+```
+
+Correct:
+
+```jsx
+const handleRowExpand = useCallback((newExpandedRows) => dispatch(setExpandedRows(newExpandedRows)), []);
+
+<DataTable
+  columns={columns}
+  data={rows}
+  height={500}
+  isExpandable
+  uniqueRowAccessor="id"
+  expandedRows={expandedRows}
+  onRowExpand={handleRowExpand}
+/>;
+```
+
+`isExpandable` alone renders the expand caret. The component is fully controlled — `expandedRows` defaults to `{}` and `onRowExpand` defaults to a no-op. Clicking the caret calls the no-op, `expandedRows` stays `{}`, and `isExpanded` is always `false`. The caret appears but clicking it does nothing visible.
+
+Source: https://dimsum.mortgagetech.ice.com/iframe.html?id=components-datatable-features-row--expandable
+
+---
+
+### HIGH Non-primitive expandable props not memoized cause unnecessary re-renders
+
+Every non-primitive prop passed to DataTable must be a stable reference. For expandable rows, the props that require memoization are:
+
+| Prop           | Type     | Memoization                                         |
+| -------------- | -------- | --------------------------------------------------- |
+| `onRowExpand`  | callback | `useCallback`                                       |
+| `expandedRows` | object   | stable from state manager — do not construct inline |
+
+Non-stable references cause DataTable to re-render on every parent render cycle regardless of whether expand state actually changed.
+
+---
+
+See also: ds-data-table-row-variants/SKILL.md — groupBy, getRowVariant, and groupedRowsRenderHeader patterns
+
+---
+
+## 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-feedback/SKILL.md

@@ -0,0 +1,190 @@
+---
+name: ds-data-table-feedback
+description: >
+  Async and empty feedback states for @elliemae/ds-data-table. isLoading spinner overlay,
+  isSkeleton placeholder rows (requires pixel height — non-px silently prevents rendering),
+  noResultsMessage, noResultsSecondaryMessage, noResultsButtonLabel + onNoResultsButtonClick
+  pair for empty-state CTA, noResultsPlaceholder for fully custom empty state component.
+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';
+
+// height must be a pixel value for skeleton and loading states to function
+<DataTable columns={columns} data={data} height={500} isSkeleton={isLoading} />;
+```
+
+## Core Patterns
+
+### isLoading — spinner replacing rows during async operations
+
+```jsx
+<DataTable columns={columns} data={data} height={500} isLoading={isFetching} />
+```
+
+`isLoading` unmounts the row list and renders a spinner in its place. The existing rows are not visible while loading. Prefer `isSkeleton` in most cases — see Common Mistakes.
+
+### isSkeleton — placeholder rows during initial load
+
+```jsx
+// isSkeleton replaces all rows with skeleton placeholders
+<DataTable columns={columns} data={[]} height={500} isSkeleton={isInitialLoading} />
+```
+
+Use `isSkeleton` for the initial data fetch when no rows exist yet. Requires pixel height — percentage or viewport-relative units silently prevent skeleton rows from rendering.
+
+### Empty state with message
+
+```jsx
+<DataTable
+  columns={columns}
+  data={[]}
+  height={400}
+  noResultsMessage="No loans found"
+  noResultsSecondaryMessage="Try adjusting your filters or search terms"
+/>
+```
+
+### Empty state with CTA button
+
+```jsx
+// noResultsButtonLabel and onNoResultsButtonClick must both be provided
+const handleClearFilters = useCallback(() => dispatch(clearFilters()), []);
+
+<DataTable
+  columns={columns}
+  data={[]}
+  height={400}
+  noResultsMessage="No results found"
+  noResultsButtonLabel="Clear all filters"
+  onNoResultsButtonClick={handleClearFilters}
+/>;
+```
+
+### noResultsPlaceholder — fully custom empty state
+
+```jsx
+const handleClearFilters = useCallback(() => dispatch(clearFilters()), []);
+
+const EmptyStatePlaceholder = () => (
+  <div>
+    <img src="/empty-state.svg" alt="" />
+    <p>No loans match your search criteria.</p>
+    <button onClick={handleClearFilters}>Clear filters</button>
+  </div>
+);
+
+<DataTable columns={columns} data={[]} height={400} noResultsPlaceholder={<EmptyStatePlaceholder />} />;
+```
+
+## Common Mistakes
+
+### HIGH isSkeleton does not render when height is not a pixel value
+
+Wrong:
+
+```jsx
+<DataTable columns={columns} data={[]} height="100%" isSkeleton={isLoading} />
+```
+
+Correct:
+
+```jsx
+<DataTable columns={columns} data={[]} height={500} isSkeleton={isLoading} />
+```
+
+Skeleton rows are calculated as `Math.floor((parseInt(height, 10) - 25) / 52)`. `parseInt` strips the unit suffix and reads only the numeric prefix — `"60vh"` → 60, `"100%"` → 100. Most non-pixel values produce zero or far too few rows. Always pass a numeric pixel value so the row count matches the actual table height.
+
+Source: https://dimsum.mortgagetech.ice.com/iframe.html?id=components-datatable-features-row--skeleton-rows-variant
+
+---
+
+### MEDIUM Providing noResultsButtonLabel without onNoResultsButtonClick (or vice versa)
+
+Wrong:
+
+```jsx
+<DataTable columns={columns} data={[]} height={400} noResultsButtonLabel="Clear filters" />
+// or
+<DataTable columns={columns} data={[]} height={400} onNoResultsButtonClick={handleClear} />
+```
+
+Correct:
+
+```jsx
+const handleClearFilters = useCallback(() => dispatch(clearFilters()), []);
+
+<DataTable
+  columns={columns}
+  data={[]}
+  height={400}
+  noResultsButtonLabel="Clear filters"
+  onNoResultsButtonClick={handleClearFilters}
+/>;
+```
+
+The empty-state CTA button only renders when both props are provided. Either alone has no visible effect.
+
+Source: https://dimsum.mortgagetech.ice.com/iframe.html?id=components-datatable--documentation
+
+---
+
+### MEDIUM Using isLoading instead of isSkeleton
+
+Wrong:
+
+```jsx
+<DataTable columns={columns} data={[]} height={500} isLoading={isLoading} />
+```
+
+Correct:
+
+```jsx
+<DataTable columns={columns} data={[]} height={500} isSkeleton={isLoading} />
+```
+
+`isSkeleton` is the default choice. Both props replace the rows with a visual placeholder — the difference is purely graphical. `isSkeleton` renders structured placeholder rows sized to the table height; `isLoading` shows a generic spinner.
+
+Two reasons to default to `isSkeleton`:
+
+- `isSkeleton` is preferred when the expected load time is short (skeleton feels snappier). `isLoading` is appropriate only when the operation is known to take longer and a spinner is a deliberate UX choice.
+- In applications using `pui-react-boilerplate`, a global loader overlay is already applied during async operations. Using `isLoading` in this context produces a double loader — the DataTable spinner renders beneath the app-level overlay simultaneously.
+
+Only use `isLoading` when there is a specific, known business reason to prefer a spinner over skeleton rows.
+
+Source: https://dimsum.mortgagetech.ice.com/iframe.html?id=components-datatable-features-row--skeleton-rows-variant
+
+---
+
+### HIGH Non-primitive feedback props not memoized cause unnecessary re-renders
+
+Every non-primitive prop passed to DataTable must be a stable reference. For feedback states, the props that require memoization are:
+
+| Prop                     | Type          | Memoization                                                   |
+| ------------------------ | ------------- | ------------------------------------------------------------- |
+| `onNoResultsButtonClick` | callback      | `useCallback`                                                 |
+| `noResultsPlaceholder`   | React element | `useMemo` or defined as a stable component outside the parent |
+
+Non-stable references cause DataTable to re-render on every parent render cycle regardless of whether feedback state actually changed.
+
+---
+
+See also: ds-data-table-setup/SKILL.md — pixel height requirement applies to both skeleton and virtualization
+
+---
+
+## 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