@elliemae/ds-data-table 3.80.0-next.64 → 3.80.0-next.67

package/skills/ds-data-table-row-variants/SKILL.md

@@ -4,11 +4,12 @@ description: >
   Row styling variants and visual grouping for @elliemae/ds-data-table. getRowVariant callback
   returning ROW_VARIANTS values (PRIMARY, SECONDARY, HEADER_GROUP, COMPACT_PRIMARY,
   COMPACT_SECONDARY). disabledRows Record<uid, boolean>. groupBy utility converting flat data into
-  nested group objects (dimsumHeaderValue + subRows) that DataTable renders as header-group rows.
-  groupedRowsRenderHeader for group label rendering (JSX.Element function or static string).
+  nested group objects (dimsumHeaderValue + subRows) that DataTable renders as header-group rows when
+  getRowVariant returns ROW_VARIANTS.HEADER_GROUP for them. groupedRowsRenderHeader callback for group
+  label rendering (a string value is not used as the label).
 type: core
 library: ds-data-table
-library_version: '3.60.0'
+library_version: '3.80.0'
 requires:
   - ds-data-table-setup
 sources:
@@ -57,7 +58,7 @@ ROW_VARIANTS.SKELETON; // 'ds-skeleton-row'        — skeleton loading row; acc
 ### groupBy — visual header-group rows
 
 `groupBy(data, fieldName)` converts a flat data array into a nested group structure that DataTable
-renders as header-group rows with their data rows below them.
+renders as group rows with their data rows below them (header styling and expansion have the conditions listed below).
 
 **What groupBy produces:**
 
@@ -65,9 +66,9 @@ renders as header-group rows with their data rows below them.
 import { groupBy } from '@elliemae/ds-data-table';
 
 const rows = [
-  { id: 1, position: 'Developer', name: 'John', uid: 'abc' },
-  { id: 2, position: 'Developer', name: 'Jane', uid: 'def' },
-  { id: 3, position: 'Designer', name: 'Sam', uid: 'ghi' },
+  { id: '1', position: 'Developer', name: 'John', uid: 'abc' },
+  { id: '2', position: 'Developer', name: 'Jane', uid: 'def' },
+  { id: '3', position: 'Designer', name: 'Sam', uid: 'ghi' },
 ];
 
 const groupedData = groupBy(rows, 'position');
@@ -76,22 +77,26 @@ const groupedData = groupBy(rows, 'position');
 //   {
 //     dimsumHeaderValue: 'Developer',  // group label — used by getRowVariant and groupedRowsRenderHeader
 //     subRows: [                        // the data rows belonging to this group
-//       { id: 1, position: 'Developer', name: 'John', uid: 'abc' },
-//       { id: 2, position: 'Developer', name: 'Jane', uid: 'def' },
+//       { id: '1', position: 'Developer', name: 'John', uid: 'abc' },
+//       { id: '2', position: 'Developer', name: 'Jane', uid: 'def' },
 //     ],
-//     uid: '<auto-generated>',          // stable key for DataTable row identity
+//     uid: '<auto-generated>',          // key for DataTable row identity (random; new on each groupBy call)
 //   },
 //   {
 //     dimsumHeaderValue: 'Designer',
-//     subRows: [{ id: 3, position: 'Designer', name: 'Sam', uid: 'ghi' }],
+//     subRows: [{ id: '3', position: 'Designer', name: 'Sam', uid: 'ghi' }],
 //     uid: '<auto-generated>',
 //   },
 // ]
 ```
 
 DataTable receives this nested structure and renders it visually as a flat list:
-one header-group row per group (styled via `ROW_VARIANTS.HEADER_GROUP`), followed by
-its data rows. DataTable handles the flattening internally — do not manually flatten before passing.
+one row per group, followed by its data rows. DataTable handles the flattening internally — do not manually flatten before passing.
+
+Two conditions apply:
+
+- A group row is styled as a header only when `getRowVariant` returns `ROW_VARIANTS.HEADER_GROUP` for it. The table does not use `dimsumHeaderValue` to choose the header row component.
+- A group's data rows are shown only while the group is expanded, and only when `isExpandable` is set. So the grouped table needs `isExpandable`, a controlled `expandedRows` and `onRowExpand` (see https://dimsum.mortgagetech.ice.com/iframe.html?id=components-datatable-advanced--group-by-column).
 
 **Wiring getRowVariant and groupedRowsRenderHeader:**
 
@@ -102,7 +107,8 @@ const getRowVariant = useCallback((row) => {
   return ROW_VARIANTS.PRIMARY;
 }, []);
 
-// groupedRowsRenderHeader: function returning JSX.Element, or a static string.
+// groupedRowsRenderHeader: a callback (value, subRows) returning the group label. A static string
+// value is not used: the header falls back to dimsumHeaderValue.
 // groupedRowsRenderHeader is a plain function called at render time — not a React component.
 // Do not call hooks in the callback body (the linter will flag this).
 // If returning a JSX element containing a component (e.g.
@@ -117,11 +123,17 @@ const groupedRowsRenderHeader = useCallback(
   [],
 );
 
+const { expandedRows } = useSelector(selectTableState);
+const handleRowExpand = useCallback((newExpandedRows) => dispatch(setExpandedRows(newExpandedRows)), [dispatch]);
+
 <DataTable
   columns={columns}
   data={groupedData}
   height={500}
+  isExpandable
   uniqueRowAccessor="uid"
+  expandedRows={expandedRows}
+  onRowExpand={handleRowExpand}
   getRowVariant={getRowVariant}
   groupedRowsRenderHeader={groupedRowsRenderHeader}
 />;
@@ -177,7 +189,7 @@ const getRowVariant = (row) => {
 };
 ```
 
-`ROW_VARIANTS.HIGHLIGHTED` does not exist. The full set of valid values is `PRIMARY`, `SECONDARY`, `HEADER_GROUP`, `COMPACT_PRIMARY`, `COMPACT_SECONDARY`, `SKELETON`. Returning an unrecognised string throws at runtime: `Error: <value> is not an out-of-the-box row variant` — it does not silently fall back.
+`ROW_VARIANTS.HIGHLIGHTED` does not exist, so the expression evaluates to `undefined`, which the table tries to render as a component type and React rejects with an error. The full set of valid values is `PRIMARY`, `SECONDARY`, `HEADER_GROUP`, `COMPACT_PRIMARY`, `COMPACT_SECONDARY`, `SKELETON`. Returning an unrecognised string literal (for example `'ds-highlighted-row'`) throws at runtime: `Error: <value> is not an out-of-the-box row variant` — it does not silently fall back.
 
 ---
 
@@ -218,7 +230,7 @@ const getRowVariant = useCallback((row) => {
 
 `getRowVariant` accepts `RowVariant | React.ComponentType<RowVariantProps>` — the component _reference_ (not a JSX element instance). Returning `<CustomHeaderRow row={row} />` creates a new element object on every call and passes the wrong type. Returning `CustomHeaderRow` (a stable module-level reference) is type-correct and does not violate the rule that component props must receive stable module-level references.
 
-However, DataTable renders the component by spreading the full internal `RowVariantProps` onto it — including `focusedRowId`, `drilldownRowId`, `itemIndex`, `draggableProps`, `isDragOverlay`, `minHeight`, `height`, `dropIndicatorPosition`, `isDropValid`, and `CustomRowContentRenderer`. A custom component must handle all of these correctly or risk breaking row focus, drag-and-drop, height virtualization, and drop indicator rendering. This is why the custom component path is strongly discouraged. Use `ROW_VARIANTS` string values for all standard scenarios. If no available variant satisfies the requirement, contact the Dimsum team through your organization's established channel.
+However, DataTable renders the component as `<Component {...props} />` with five props only: `row`, `itemIndex`, `isDragOverlay`, `focusedRowId` and `drilldownRowId` (the `RowVariantProps` type of the `DSDataTableT` namespace). It does not pass `draggableProps`, `minHeight`, `height`, `dropIndicatorPosition`, `isDropValid` or `CustomRowContentRenderer` to the variant. The custom component owns the row's rendering: its cells, focus handling from `focusedRowId`, and any drag-and-drop or drop-indicator behaviour. This is why the custom component path is strongly discouraged. Use `ROW_VARIANTS` string values for all standard scenarios. If no available variant satisfies the requirement, contact the Dimsum team through your organization's established channel.
 
 Source: https://dimsum.mortgagetech.ice.com/iframe.html?id=components-datatable-advanced--group-by-column
 
@@ -239,7 +251,7 @@ Correct:
 const groupedData = groupBy(rows, 'position');
 ```
 
-`groupBy` generates a stable `uid` for each group object via a 16-character random ID. Manually constructing these objects risks producing malformed group data (wrong uid, missing subRows shape) that breaks row identity tracking inside DataTable.
+`groupBy` gives each group object a random 16-character `uid` on every call, so the uids change whenever `groupBy` is re-run. Memoize the result, and do not expect `expandedRows` keys for groups to carry over to a re-grouped array. Manually constructing these objects risks producing malformed group data (wrong uid, missing subRows shape) that breaks row identity tracking inside DataTable.
 
 ---
 
@@ -247,11 +259,11 @@ const groupedData = groupBy(rows, 'position');
 
 Every non-primitive prop passed to DataTable must be a stable reference. For row variants and grouping, the props that require memoization are:
 
-| Prop                      | Type               | Memoization                                       |
-| ------------------------- | ------------------ | ------------------------------------------------- |
-| `getRowVariant`           | callback           | `useCallback`                                     |
-| `groupedRowsRenderHeader` | callback or string | `useCallback` if function; stable const if string |
-| `disabledRows`            | object             | `useMemo` if constructed inline                   |
+| Prop                      | Type     | Memoization                     |
+| ------------------------- | -------- | ------------------------------- |
+| `getRowVariant`           | callback | `useCallback`                   |
+| `groupedRowsRenderHeader` | callback | `useCallback`                   |
+| `disabledRows`            | object   | `useMemo` if constructed inline |
 
 Non-stable references cause DataTable to re-render on every parent render cycle regardless of whether row variant state actually changed.
 

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

@@ -9,7 +9,7 @@ description: >
   select and deselect gestures; newSelection covers all in-memory rows.
 type: core
 library: ds-data-table
-library_version: '3.60.0'
+library_version: '3.80.0'
 requires:
   - ds-data-table-setup
 sources:
@@ -29,8 +29,8 @@ const columns = [
 ];
 
 // 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".
+// Values are true (selected) or false (not selected). The type also allows 'mixed', but DataTable never
+// writes it: the header checkbox's indeterminate state is derived internally from the displayed rows.
 // Lives in the project state manager, e.g for Redux:
 const { selection } = useSelector(selectTableState);
 const dispatch = useDispatch();
@@ -105,8 +105,8 @@ If after that review the product explicitly confirms they want to continue, the
 // 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).
+// and must not be used to duplicate selection logic (it fires before onSelectionChange,
+// and the internal handler calls onSelectionChange for the same click).
 <DataTable
   columns={columns}
   data={rows}
@@ -120,13 +120,13 @@ If after that review the product explicitly confirms they want to continue, the
 
 ### 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.
+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. For multi-select, `Header` is the select-all checkbox: replacing it removes select-all and leaves its semantics to you.
 
 **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
+```tsx
 import { DataTable, multiSelectColumn } from '@elliemae/ds-data-table';
 
 // Spread multiSelectColumn and override only what differs.
@@ -134,8 +134,7 @@ import { DataTable, multiSelectColumn } from '@elliemae/ds-data-table';
 // 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 },
+  cellStyle: { position: 'sticky', left: 0, background: 'white', zIndex: 2 } as const,
 };
 
 const columns = [CustomSelectColumn, { Header: 'Name', accessor: 'name' }];
@@ -157,6 +156,7 @@ For single-select customization, you must also set `selectSingle={true}`. Withou
 
 ```jsx
 import { DataTable, singleSelectColumn } from '@elliemae/ds-data-table';
+import { ScreenReaderOnly } from '@elliemae/ds-accessibility';
 
 const CustomSingleSelectColumn = {
   ...singleSelectColumn,
@@ -181,17 +181,17 @@ const columns = [CustomSingleSelectColumn, { Header: 'Name', accessor: 'name' }]
 
 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.
+- `newSelection` — a `Record<uid, boolean>` built from every row in the `data` prop (all rows and sub-rows recursively). It covers the rows passed to `data`, not only the rows currently displayed (see the note below).
 - `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.
+- An empty `{}` means deselect. A select-all map holds `true` for enabled rows and `false` for disabled rows; if every row is disabled it holds only `false` values, so detect select-all by the map being non-empty, not by a `true` value.
 
-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.
+DataTable has no knowledge of records beyond what was passed to `data`, and its select-all acts on exactly that set. With client-side pagination (full data in memory) that set spans every page; with AJAX pagination `data` holds only the current page, so the set is the current page.
 
 **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/)
+This is the Dimsum recommendation, consistent with established industry practice. Other industry relevant design system like PatternFly documents the same pattern: _"Text label that reflects the total number of items selected. If pagination is in use, it will reflect the number of 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.
+**Critical implementation detail — "select all" does not merge:** when the header checkbox fires, `newSelection` is built from scratch starting at `{}`. It contains the UIDs of every row in `data`, not only the displayed rows; with AJAX pagination `data` is the current page, so only that page's UIDs are included. 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(
@@ -215,16 +215,14 @@ const handleSelectionChange = useCallback(
       dispatch(setSelection(newSelection));
     }
   },
-  [dispatch, selection, data, uniqueRowAccessor],
+  [dispatch, selection, pagedData, 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
+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. DataTable itself reports `{}`, which replaces the whole selection if dispatched as is. Clearing the entire selection across all pages belongs to the external "Clear selection" action — not to the header.
 
 ---
 
@@ -234,15 +232,15 @@ This is an architectural signal that a dataset-level concern has been routed int
 
 **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.
+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." Its select-all acts on every row in `data`, which with client-side pagination already includes rows on other pages. Silently expanding that scope to 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))
+This is not theoretical. HTTPie made its main repository private by mistake (the author believed he was working on an empty repo), and GitHub permanently deleted its stars and watchers, about 54,000 stargazers and roughly 1,000 watchers, within roughly half an hour. The confirmation dialog for the visibility change warned of a "potentially destructive action" and did not show the magnitude; the author states it looked the same for a repository with no stars 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 table header checkbox acts only on the rows the table has been given. 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:**
 
@@ -271,7 +269,7 @@ const LoanQueuePage = () => {
       {/* 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 */}
+      {/* The header checkbox shows the state of the displayed page; select-all acts on every row in `data` */}
       <DataTable
         columns={columns}
         data={pagedData}
@@ -319,7 +317,7 @@ Correct:
 />
 ```
 
-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.
+Without `uniqueRowAccessor`, each row's uid falls back to its position in `data`, so the `selection` record is keyed by position. No error is thrown. If `data` is reordered, filtered or replaced, the selected keys point at different rows.
 
 Source: `@elliemae/ds-data-table:dist/types/react-desc-prop-types.d.ts`
 
@@ -347,7 +345,7 @@ Correct:
 />
 ```
 
-`selection` and `onSelectionChange` must both be provided. Selections appear to work visually but state is not captured or persisted without the handler.
+`selection` and `onSelectionChange` must both be provided. Selection is controlled: without `onSelectionChange` the table cannot update `selection`, so checkboxes and radios do not change when clicked.
 
 Source: https://dimsum.mortgagetech.ice.com/iframe.html?id=components-datatable-features-row--select-multiple
 
@@ -375,7 +373,7 @@ const columns = [
 ];
 ```
 
-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.
+The auto-injected column always prepends. A manually placed selection column stays where you put it (DataTable does not move a column it already finds in `columns`). In a trailing position it 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
 

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

@@ -1,14 +1,15 @@
 ---
 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
+  First-time setup of @elliemae/ds-data-table. Required props: columns, data. height defaults to '100%', and
+  for large data it must be bounded (a number, a px string, a viewport unit, or a percentage of a parent with a
+  definite height), otherwise the table renders nearly every row. 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'
+library_version: '3.80.0'
 sources:
   - '@elliemae/ds-data-table:dist/types/react-desc-prop-types.d.ts'
 ---
@@ -29,7 +30,7 @@ const columns = [
   data={rows}
   height={500}
   uniqueRowAccessor="id"
-  dsDataTableTableWrapper={{ 'aria-label': 'Employees table' }}
+  dsDatatableTableWrapper={{ 'aria-label': 'Employees table' }}
 />;
 ```
 
@@ -94,7 +95,7 @@ Required for selection, drag & drop, and expandable rows.
 
 ```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
+// aria-controls on the header checkbox, the id of a hidden editable-cell instruction span, 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" />
@@ -130,12 +131,12 @@ Source: `@elliemae/ds-data-table:dist/types/react-desc-prop-types.d.ts`
 
 ---
 
-### HIGH Using height in % or vh silently defeats virtualization
+### HIGH Table without a bounded height renders nearly every row
 
-Wrong:
+Wrong (the default `height="100%"` inside a parent with no definite height, or `height="auto"`):
 
 ```jsx
-<DataTable columns={columns} data={rows} height="100%" />
+<DataTable columns={columns} data={rows} />
 ```
 
 Correct:
@@ -144,8 +145,25 @@ Correct:
 <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.
+The table virtualizes (renders only the visible rows) only when its height is bounded: a number, a px string, a viewport unit such as `'60vh'`, or a percentage of a parent that has a definite height. With the default `'100%'` in a parent without a definite height, or with `height="auto"`, the table grows with its content: it has no internal scroll and renders nearly every row. For large data always give the table a bounded height; a number is the simplest.
+
+---
+
+### HIGH isSkeleton with a percentage height renders the wrong number of skeleton rows
+
+Wrong:
+
+```jsx
+<DataTable columns={columns} data={[]} height="100%" isSkeleton={isLoading} />
+```
+
+Correct:
+
+```jsx
+<DataTable columns={columns} data={[]} height={500} isSkeleton={isLoading} />
+```
 
+`height` defaults to `'100%'`. A percentage resolves against the parent, so it is bounded only when the parent has a definite height (see the bounded-height rule above). The skeleton row count is the exception: it is computed from the leading number of `height` (`floor((parseInt(height) - 25) / 52)`), so `'100%'` is read as 100px and renders a single placeholder row. Pass a pixel number when using `isSkeleton`.
 ---
 
 ### HIGH Managing DataTable state with local useState instead of the project state manager
@@ -185,13 +203,13 @@ Correct:
 <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.
+`domIdAffix` is used internally to construct DOM IDs for aria relationships — `aria-controls` on the header checkbox (pointing to individual row checkboxes), the `id` of the hidden instruction span in editable cells (`editable-cell-<cellId>-<domIdAffix>`), which names the editable group through `aria-labelledby`, 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
+### HIGH Missing dsDatatableTableWrapper aria-label
 
 Wrong:
 
@@ -206,7 +224,7 @@ Correct:
   columns={columns}
   data={rows}
   height={500}
-  dsDataTableTableWrapper={{ 'aria-label': 'Loan applications table' }}
+  dsDatatableTableWrapper={{ 'aria-label': 'Loan applications table' }}
 />
 ```
 

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

@@ -7,7 +7,7 @@ description: >
   DSDataTableSlots. App side owns long-term maintenance of anything injected via slots.
 type: core
 library: ds-data-table
-library_version: '3.60.0'
+library_version: '3.80.0'
 requires:
   - ds-data-table-setup
 sources:
@@ -19,7 +19,7 @@ sources:
 
 Slots are injection points into specific rendered DOM nodes. The `data-dimsum-slot` attribute value on each node identifies the slot — values use camelCase with the component prefix, e.g. `dsDatatableCellsContainer`. Understanding the hierarchy is required to inject props into the right element — injecting `aria-*` attributes at the wrong level produces silent accessibility failures.
 
-**About this map:** Verified against `@elliemae/ds-data-table@3.60.0` via probe tests. Slot names and positions are governed by the Dimsum breaking change protocol — renames and structural moves are intentional, coordinated, and documented in the official resources; they do not happen silently. The map is likely accurate for nearby versions, but not guaranteed for all time.
+**About this map:** Verified against `@elliemae/ds-data-table@3.80.0` via probe tests. Slot names and positions are governed by the Dimsum breaking change protocol — renames and structural moves are intentional, coordinated, and documented in the official resources; they do not happen silently. The map is likely accurate for nearby versions, but not guaranteed for all time.
 
 **If something doesn't match the version you're integrating with:** Find a way to inspect the actual rendered HTML of the component — how you do that depends on your environment and what tools are available to you. If you cannot do it autonomously, ask the human in the loop to render the component with synthetic or placeholder data and share the resulting HTML structure. **Important:** the human must not copy HTML from a production environment or any page containing real user data, real loan information, or any personally identifiable information — the goal is slot position verification, which requires only the DOM structure, not real content. Placeholder text and fake IDs are sufficient and correct for this purpose.
 
@@ -28,8 +28,12 @@ Each entry below shows: `SLOT_KEY (data-dimsum-slot="value") · tag · notes`.
 ```
 ROOT (dsDatatableRoot) · div
 ├── FILTER_BAR_WRAPPER (dsDatatableFilterBarWrapper) · div  ← only when withFilterBar=true
-│   └── FILTER_BAR_MENU_BUTTON  ← static, no interaction needed
-│       wraps DSMenuButton → DOM shows dsButtonRoot (no dsDatatableFilterBarMenuButton attr)
+│   └── (default menu, when no filterBarAddonRenderer) dsMenubuttonRoot · div[data-testid="ds-menubutton-root"]
+│       ├── FILTER_BAR_MENU_BUTTON: the DSMenuButton trigger · button[data-testid="filter-bar-ddmenu-button"]
+│       │   data-dimsum-slot="dsButtonRoot", data-dimsum-parent-slot="dsOpinionatedbuttonRoot", aria-haspopup="menu",
+│       │   aria-expanded. Props injected through the FILTER_BAR_MENU_BUTTON slot prop land on this trigger button (see the note below the nested-slots table).
+│       └── flyout menu, after the trigger is clicked (portal, dsFloatingwrapperContent):
+│           dsFlyoutmenuRoot > dsFlyoutmenuListWrapper[role="menu"] > dsMenuitemMenuItemWrapper[role="menuitem"]
 └── CONTENT_WRAPPER (dsDatatableContentWrapper) · div
     ├── TABLE_WRAPPER (dsDatatableTableWrapper) · div[role="table"]
     │   └── VIRTUAL_LIST_WRAPPER (dsDatatableVirtualListWrapper) · div[role="rowgroup" tabIndex="-1"]
@@ -40,6 +44,8 @@ ROOT (dsDatatableRoot) · div
     │           │           └── HEAD_TH (dsDatatableHeadTh) · div[role="columnheader"]
     │           │               ║  prop: dsDatatableHeadTh
     │           │               ║  callback: ({ columnId, firstFocuseableColumnHeaderId }) => props
+    │           │               ├── GLOBAL_CHECKBOX_CONTAINER (dsDatatableGlobalCheckboxContainer) · span
+    │           │               │   present in: the multi-select column header cell only (select-all checkbox)
     │           │               ├── HEAD_RIGHT_ICONS_WRAPPER (dsDatatableHeadRightIconsWrapper) · div
     │           │               │   present when: canSort=true OR column.filter is set
     │           │               │   ├── sort button (dsButtonRoot — no DataTable slot attr)
@@ -68,10 +74,10 @@ ROOT (dsDatatableRoot) · div
     │           ├── CENTER_CONTENT_FLEX_WRAPPER (dsDatatableCenterContentFlexWrapper) · div[role="row"]
     │           │   present when: data=[]  (sibling of HEAD_WRAPPER)
     │           │   └── EMPTY_STATE_WRAPPER (dsDatatableEmptyStateWrapper) · div[role="cell"]
-    │           │       ├── warning icon (dsIconRoot — no DataTable slot attr)
+    │           │       ├── WARNING_ICON (data-dimsum-slot="dsIconRoot", data-dimsum-parent-slot="dsDatatableWarningIcon") · span
     │           │       ├── EMPTY_PRIMARY_MESSAGE (dsDatatableEmptyPrimaryMessage) · p
     │           │       ├── EMPTY_SECONDARY_MESSAGE (dsDatatableEmptySecondaryMessage) · p
-    │           │       └── CTA button (dsButtonRoot — no DataTable slot attr)
+    │           │       └── EMPTY_BUTTON (data-dimsum-slot="dsButtonRoot", data-dimsum-parent-slot="dsDatatableEmptyButton") · button
     │           │           present when: noResultsButtonLabel + onNoResultsButtonClick provided
     │           │
     │           └── ROW (dsDatatableRow) · div[position:absolute]  (one per visible row)
@@ -92,7 +98,7 @@ ROOT (dsDatatableRoot) · div
     │                       │   ├── EDITABLE_CONTAINER (dsDatatableEditableContainer) · div[role="group"]
     │                       │   │   present when: column.editable is set
     │                       │   │   ├── CELL_CONTENT (dsDatatableCellContent) · div
-    │                       │   │   ├── pencil icon (dsIconRoot — no DataTable slot attr)
+    │                       │   │   ├── PENCIL_ICON (data-dimsum-slot="dsIconRoot", data-dimsum-parent-slot="dsDatatablePencilIcon") · span
     │                       │   │   └── TEXT_EDITABLE_CELL_INPUT (dsDatatableTextEditableCellInput) · input
     │                       │   │       present after user clicks to enter edit mode (autoFocus on mount)
     │                       │   └── CELL_CONTENT (dsDatatableCellContent) · div  (standard columns)
@@ -109,7 +115,7 @@ ROOT (dsDatatableRoot) · div
     │                               └── TOOLBAR_WRAPPER (dsDatatableToolbarWrapper) · div
     │                                   ├── TOOLBAR_BUTTONS_WRAPPER (dsDatatableToolbarButtonsWrapper) · div
     │                                   │   present after user opens the toolbar
-    │                                   └── trigger button (dsButtonRoot — no DataTable slot attr)
+    │                                   └── TOOLBAR_BUTTON (data-dimsum-slot="dsButtonRoot", data-dimsum-parent-slot="dsDatatableToolbarButton") · button
     │                                       data-testid="data-table-toolbar-trigger"
     │
     └── PAGINATION_WRAPPER (dsDatatablePaginationWrapper) · div
@@ -118,30 +124,54 @@ ROOT (dsDatatableRoot) · div
 
 ── FILTER_POPOVER portal  ← rendered at document body level, not inside DataTable DOM
    present after user clicks a column's FILTER_POPOVER_BUTTON trigger
-   DOM shows: dsFloatingwrapperRoot[role="dialog"] · (root)
+   DOM shows: dsFloatingwrapperRoot[role="dialog"] · (root), data-dimsum-parent-slot="dsDatatableFilterPopover"
    └── dsFloatingwrapperContent
        └── FILTER_POPOVER_CONTENT (dsDatatableFilterPopoverContent) · div
            ├── FREE_TEXT_SEARCH_WRAPPER (dsDatatableFreeTextSearchWrapper) · div
            │   └── FREE_TEXT_SEARCH_FILTER (dsDatatableFreeTextSearchFilter)
-           │       prop: dsDatatableFreeTextSearchFilter  ·  wraps DSInputText
-           │       data-dimsum-slot="dsDatatableFreeTextSearchFilter" and data-testid="data-table-filter-free-text-search"
-           │       land on the inner input element
-           └── FILTER_POPOVER_FOOTER — no dsDatatableFilterPopoverFooter attr in DOM
-               └── submit/reset buttons (dsButtonRoot)
+           │       prop: dsDatatableFreeTextSearchFilter  ·  wraps DSInputText; only the inner <input> is visible in the DOM:
+           │       data-testid="data-table-filter-free-text-search", data-dimsum-slot="dsInputtextInput" and
+           │       data-dimsum-parent-slot="dsDatatableFreeTextSearchFilter" (same for the V1 and V2 filter types)
+           └── FILTER_POPOVER_FOOTER (data-dimsum-slot="dsDialogFooter", data-dimsum-parent-slot="dsDatatableFilterPopoverFooter") · div
+               └── submit/reset buttons (dsButtonRoot) — V2 filter types only (the V1 popover has no footer)
 ```
 
-**Slots that are injectable but do not appear as `dsDatatable*` in the DOM:**
+**Slots on wrapped Dimsum components — nested slots:**
 
-These slot props work for injection, but when you inspect the DOM you will not see a `dsDatatableXxx` attribute. The table below shows what you will see instead. This matters if you are debugging injection or writing DOM-based test assertions.
+When the DataTable gives a slot to a Dimsum component (an input, a button, an icon, a dialog footer, a floating wrapper), the element in the DOM carries the wrapped component's own `data-dimsum-slot`, and the DataTable slot name is in `data-dimsum-parent-slot`. This is how nested slots work: you inject through the DataTable slot prop as usual (for example `dsDatatableFilterPopover={{ ... }}`), and when you inspect the DOM or write DOM-based test assertions you look the element up by `data-dimsum-parent-slot`.
 
-| Slot key                 | What the DOM shows                                   | Where to find it                                                                |
-| ------------------------ | ---------------------------------------------------- | ------------------------------------------------------------------------------- |
-| `PENCIL_ICON`            | `dsIconRoot` + `dsIconSvg`                           | Inside `EDITABLE_CONTAINER`; present in DOM but CSS-hidden until hover/focus    |
-| `TOOLBAR_BUTTON`         | `dsButtonRoot`                                       | Inside `TOOLBAR_BUTTONS_WRAPPER`, visible after toolbar is opened               |
-| `EMPTY_BUTTON`           | `dsButtonRoot`                                       | Inside `EMPTY_STATE_WRAPPER`, the CTA button                                    |
-| `FILTER_POPOVER`         | `dsFloatingwrapperRoot` + `dsFloatingwrapperContent` | Portal at document body — `role="dialog"`, not inside the DataTable DOM subtree |
-| `FILTER_POPOVER_FOOTER`  | `dsDialogFooter`                                     | Inside `FILTER_POPOVER_CONTENT`                                                 |
-| `FILTER_BAR_MENU_BUTTON` | `dsButtonRoot`                                       | Inside `FILTER_BAR_WRAPPER`, always visible when `withFilterBar=true`           |
+| Slot key                  | Element in the DOM (`data-dimsum-slot`)                               | `data-dimsum-parent-slot`         | Where to find it                                                                                     |
+| ------------------------- | --------------------------------------------------------------------- | --------------------------------- | ---------------------------------------------------------------------------------------------------- |
+| `RESIZER`                 | `dsInputtextInput`                                                    | `dsDatatableResizer`              | The `<input type="range">` inside the column header (see the tree)                                   |
+| `FREE_TEXT_SEARCH_FILTER` | `dsInputtextInput`                                                    | `dsDatatableFreeTextSearchFilter` | The input inside the filter popover (V1 and V2 filter types)                                         |
+| `FILTER_POPOVER`          | `dsFloatingwrapperRoot` (its `dsFloatingwrapperContent` is inside it) | `dsDatatableFilterPopover`        | Portal at document body — `role="dialog"`, not inside the DataTable DOM subtree                      |
+| `FILTER_POPOVER_FOOTER`   | `dsDialogFooter`                                                      | `dsDatatableFilterPopoverFooter`  | Inside `FILTER_POPOVER_CONTENT` (V2 filter types only)                                               |
+| `WARNING_ICON`            | `dsIconRoot`                                                          | `dsDatatableWarningIcon`          | The icon of the empty state, inside `EMPTY_STATE_WRAPPER`                                            |
+| `EMPTY_BUTTON`            | `dsButtonRoot`                                                        | `dsDatatableEmptyButton`          | The empty state's call-to-action button (needs `noResultsButtonLabel` and `onNoResultsButtonClick`)  |
+| `TOOLBAR_BUTTON`          | `dsButtonRoot`                                                        | `dsDatatableToolbarButton`        | The row-actions trigger button (`data-testid="data-table-toolbar-trigger"`) inside `TOOLBAR_WRAPPER` |
+| `PENCIL_ICON`             | `dsIconRoot`                                                          | `dsDatatablePencilIcon`           | Inside `EDITABLE_CONTAINER`; in the DOM but CSS-hidden until hover/focus                             |
+
+**`FILTER_BAR_MENU_BUTTON`:** props injected through the `dsDatatableFilterBarMenuButton` slot prop land on the trigger button of the default filter bar menu and of the menu rendered by `FilterBarDropdownMenu`. That button's `data-dimsum-parent-slot` is the menu button's own (`dsOpinionatedbuttonRoot`), so the DataTable slot name is not in the DOM for this one; find the trigger with `data-testid="filter-bar-ddmenu-button"`.
+
+**`FOCUS_WITHIN`:** a `div` that wraps `EXPAND_CELL_CONTAINER` (header and rows) and `DRAG_AND_DROP_GRIPPER` (header and rows): the element that draws the focus border when something inside it has the focus. In the rows its parent is `CELL_CONTENT`. It is not in the tree above.
+
+**`EMPTY_HEADER`:** it is not in the DOM at rest. It renders only inside the drag overlay of a column group header (the thin line under the group title) while that group is being dragged, so props injected through `dsDatatableEmptyHeader` can only be observed during that drag.
+
+**Arguments of the function form:** slots that repeat per row, cell or column pass that instance to a function-form slot prop as an object with named keys, for example `dsDatatableFullsizeGrid={({ row }) => ({ ... })}`. The single-instance slots (the root, the wrappers around the table, the loader, the filter bar, the empty state) receive no arguments. The keys are ours; the row and the cell inside them are your data and the table's internals, whose shape the DataTable does not guarantee.
+
+| Slot keys                                                                                                                                                                                             | Argument                                                                                                                                                                                                                                        |
+| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `FULLSIZE_GRID`, `GROUP_HEADER_CONTAINER`, `GROUP_HEADER_TITLE`, `ACTION_CELL`, `SINGLE_CELL_CONTAINER`, `TOOLBAR_POSITION`, `TOOLBAR_WRAPPER`, `TOOLBAR_BUTTONS_WRAPPER`, `TOOLBAR_BUTTON`           | `{ row }`                                                                                                                                                                                                                                       |
+| `PENCIL_ICON`                                                                                                                                                                                         | `{ cell }`                                                                                                                                                                                                                                      |
+| `HEAD_TH`, `HEAD_RIGHT_ICONS_WRAPPER`                                                                                                                                                                 | `{ columnId, firstFocuseableColumnHeaderId }`                                                                                                                                                                                                   |
+| `HEADER_CELL_WRAPPER`, `RESIZER`, `EMPTY_HEADER`, `FILTER_POPOVER`, `FILTER_POPOVER_BUTTON`, `FILTER_POPOVER_CONTENT`, `FILTER_POPOVER_FOOTER`, `FREE_TEXT_SEARCH_FILTER`, `FREE_TEXT_SEARCH_WRAPPER` | `{ columnId }`                                                                                                                                                                                                                                  |
+| `DRAG_AND_DROP_GRIPPER`                                                                                                                                                                               | one object, `{ row?, columnId? }`: `row` for a row handle, `columnId` for a column header handle, the other key is not there                                                                                                                    |
+| `EXPAND_CELL_CONTAINER`                                                                                                                                                                               | `{ isGlobal }` (`true` for the header expand-all control)                                                                                                                                                                                       |
+| `FOCUS_WITHIN`                                                                                                                                                                                        | one object, `{ row?, columnId?, firstFocuseableColumnHeaderId?, isGlobal? }`: `columnId` and `firstFocuseableColumnHeaderId` on a header drag handle, `isGlobal` on the expand carets, `row` on a row drag handle, the other keys are not there |
+| `ROW`, `CELL_CONTAINER` (legacy shape)                                                                                                                                                                | the row itself, also on group header rows                                                                                                                                                                                                       |
+| `CELL`, `CELL_CONTENT`, `EDITABLE_CONTAINER`, `TEXT_EDITABLE_CELL_INPUT` (legacy shape)                                                                                                               | the cell itself (`cell.row.original`, `cell.row.uid`, `cell.column`, `cell.id`)                                                                                                                                                                 |
+
+The legacy-shape slots shipped before the named-key convention, so they still receive the row or the cell directly; they will move to `{ row }` / `{ cell }` only through a deliberate, announced breaking change.
 
 **Slots only visible in interactive states (not in static render):**
 
@@ -235,7 +265,7 @@ const cellProps = useCallback((cell) => {
 
 Always wrap callbacks in `useCallback`. Inline callbacks create a new reference on every render, causing all virtualized rows to re-render unnecessarily.
 
-In `dsDatatableCell`, access row data via `cell.row.original` (raw data) or `cell.row.uid` (UID from `uniqueRowAccessor`). Do not use `cell.row.id` — that is react-table's internal positional index and shifts when data is reordered.
+In `dsDatatableCell`, access row data via `cell.row.original` (raw data) or `cell.row.uid` (UID from `uniqueRowAccessor`). Do not use `cell.row.id` — that is the DataTable's internal position-based id and shifts when data is reordered.
 
 ## `column.cellStyle` vs `dsDatatableCell`