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

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

@@ -0,0 +1,201 @@
+---
+name: ds-data-table-migration
+description: >
+  Migrating deprecated @elliemae/ds-data-table APIs to their modern replacements. V1 filter strings
+  (FILTER_TYPES.MULTI_SELECT, SELECT, etc.) → FILTER_TYPES V2 values. Lowercase pagination prop →
+  capital-P Pagination render prop. onColumnSortChange → onColumnSort. onColumnResize →
+  onColumnSizeChange. Scan for all instances before migrating — partial migration is not a migration.
+type: lifecycle
+library: ds-data-table
+library_version: '3.60.0'
+sources:
+  - '@elliemae/ds-data-table:dist/types/exported-related/FilterTypes.d.ts'
+  - '@elliemae/ds-data-table:dist/types/react-desc-prop-types.d.ts'
+---
+
+## Migration checklist
+
+Before migrating, scan the entire codebase for all instances. Determine the correct source directory for the project you are working in (common conventions include `src/`, `lib/`, `app/`, `view/`, or a monorepo package root — inspect the project structure before running any search):
+
+```
+# Patterns to search for — adapt the directory to the project's structure
+
+# V1 filter usage — covers all types that have V1/V2 variants:
+FILTER_TYPES\.(MULTI_SELECT|SELECT|CREATABLE_SELECT|CREATABLE_MULTI_SELECT|SINGLE_DATE|DATE_RANGE|DATE_SWITCHER|NUMBER_RANGE|FREE_TEXT_SEARCH|CURRENCY_RANGE)\b[^_]
+ds-filter-multi-select
+ds-filter-select
+
+# Deprecated pagination prop:
+pagination={
+
+# Deprecated sort/resize callbacks:
+onColumnSortChange
+onColumnResize
+```
+
+Migrate all instances in one pass. Partial migration leaves tech debt in place and creates mixed patterns that are harder to finish later.
+
+## V1 filters → V2
+
+```js
+// Before (V1 — a11y-unsafe, do not use in any context)
+import { FILTER_TYPES } from '@elliemae/ds-data-table';
+
+const columns = [
+  { Header: 'Position', accessor: 'position', filter: FILTER_TYPES.MULTI_SELECT },
+  { Header: 'Status', accessor: 'status', filter: FILTER_TYPES.SELECT },
+];
+```
+
+```js
+// After (V2 — always use these)
+import { FILTER_TYPES } from '@elliemae/ds-data-table';
+
+const columns = [
+  { Header: 'Position', accessor: 'position', filter: FILTER_TYPES.MULTI_SELECT_V2 },
+  { Header: 'Status', accessor: 'status', filter: FILTER_TYPES.SELECT_V2 },
+];
+```
+
+V1 filter types are not a11y safe and are kept only for legacy app migration. They have no valid use case in new or updated code.
+
+## V2 filter type mapping
+
+Every filter type in `FILTER_TYPES` has both a V1 and a V2 variant. The V1 name is the bare type name; the V2 name carries the `_V2` suffix.
+
+| V1 (deprecated — a11y-unsafe)         | V2 (current)                             |
+| ------------------------------------- | ---------------------------------------- |
+| `FILTER_TYPES.MULTI_SELECT`           | `FILTER_TYPES.MULTI_SELECT_V2`           |
+| `FILTER_TYPES.SELECT`                 | `FILTER_TYPES.SELECT_V2`                 |
+| `FILTER_TYPES.CREATABLE_SELECT`       | `FILTER_TYPES.CREATABLE_SELECT_V2`       |
+| `FILTER_TYPES.CREATABLE_MULTI_SELECT` | `FILTER_TYPES.CREATABLE_MULTI_SELECT_V2` |
+| `FILTER_TYPES.SINGLE_DATE`            | `FILTER_TYPES.SINGLE_DATE_V2`            |
+| `FILTER_TYPES.DATE_RANGE`             | `FILTER_TYPES.DATE_RANGE_V2`             |
+| `FILTER_TYPES.DATE_SWITCHER`          | `FILTER_TYPES.DATE_SWITCHER_V2`          |
+| `FILTER_TYPES.NUMBER_RANGE`           | `FILTER_TYPES.NUMBER_RANGE_V2`           |
+| `FILTER_TYPES.FREE_TEXT_SEARCH`       | `FILTER_TYPES.FREE_TEXT_SEARCH_V2`       |
+| `FILTER_TYPES.CURRENCY_RANGE`         | `FILTER_TYPES.CURRENCY_RANGE_V2`         |
+| `'ds-filter-multi-select'`            | `FILTER_TYPES.MULTI_SELECT_V2`           |
+| `'ds-filter-select'`                  | `FILTER_TYPES.SELECT_V2`                 |
+
+## Lowercase `pagination` → capital-P `Pagination`
+
+```jsx
+// Before (deprecated — legacy prop)
+<DataTable
+  columns={columns}
+  data={rows}
+  height={500}
+  pagination={{ pageSize: 10, totalCount: 1000 }}
+/>
+
+// After
+<DataTable columns={columns} data={pagedData} height={500} Pagination={TablePagination} />
+```
+
+Two things change in the migration:
+
+1. **Integration model** — the legacy prop accepted total count and delegated slicing internally; the modern pattern requires the app to own data fetching and page slicing via AJAX
+2. **Component model** — `Pagination` receives a React component reference, not a config object; that component must be defined at module level and read state from the project's state manager
+
+For the full correct implementation of `TablePagination`, load `ds-data-table-pagination/SKILL.md`.
+
+## `onColumnSortChange` → `onColumnSort`
+
+```jsx
+// Before (deprecated)
+<DataTable columns={columns} data={rows} height={500} onColumnSortChange={handleSort} />
+```
+
+```jsx
+// After
+// Signature: (newColumns, sortedColumnId, sortDirection) => void
+const handleColumnSort = useCallback((newColumns) => dispatch(setColumns(newColumns)), []);
+
+<DataTable columns={columns} data={rows} height={500} onColumnSort={handleColumnSort} />;
+```
+
+## `onColumnResize` → `onColumnSizeChange`
+
+```jsx
+// Before (deprecated)
+<DataTable columns={columns} data={rows} height={500} isResizeable onColumnResize={handleResize} />
+```
+
+```jsx
+// After
+// Signature: (newColumns, headerId, width) => void
+const handleColumnSizeChange = useCallback((newColumns) => dispatch(setColumns(newColumns)), []);
+
+<DataTable
+  columns={columns}
+  data={rows}
+  height={500}
+  colsLayoutStyle="fixed"
+  isResizeable
+  onColumnSizeChange={handleColumnSizeChange}
+/>;
+```
+
+## Common Mistakes
+
+### CRITICAL Migrating one V1 filter instance while leaving others in the same codebase
+
+Wrong:
+
+```jsx
+// File A — migrated
+{ accessor: 'status', filter: FILTER_TYPES.SELECT_V2 }
+
+// File B — still V1 (same codebase)
+{ accessor: 'position', filter: FILTER_TYPES.MULTI_SELECT }
+```
+
+Correct:
+
+```jsx
+// Scan all files and migrate every instance before closing the task
+// V1 and V2 can coexist technically but it is treated as incomplete migration
+{ accessor: 'status', filter: FILTER_TYPES.SELECT_V2 }
+{ accessor: 'position', filter: FILTER_TYPES.MULTI_SELECT_V2 }
+```
+
+V1 filters are tech debt. Partial migration leaves the a11y risk in place on the unmigrated columns and creates a mixed pattern that is harder to finish.
+
+Source: https://dimsum.mortgagetech.ice.com/iframe.html?id=components-datatable-features-filtersv2--multi-select-filter-vs-multi-select-v-2
+
+---
+
+### HIGH Not accounting for the data-slicing responsibility change when migrating pagination
+
+Wrong:
+
+```jsx
+// Migrated the prop name but still passing allData to DataTable
+<DataTable columns={columns} data={allData} height={500} Pagination={MemoizedPagination} />
+```
+
+Correct:
+
+```jsx
+// App must slice data to the current page — DataTable does not paginate internally
+<DataTable columns={columns} data={pagedData} height={500} Pagination={MemoizedPagination} />
+```
+
+The legacy `pagination` prop delegated slicing to DataTable. The modern `Pagination` render prop does not — the app is responsible for slicing `data` before passing it.
+
+Source: https://dimsum.mortgagetech.ice.com/iframe.html?id=components-datatable-features-pagination--paginated-table
+
+---
+
+See also: ds-data-table-filtering/SKILL.md — V2 filter configuration patterns
+See also: ds-data-table-pagination/SKILL.md — modern Pagination render prop 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-pagination/SKILL.md

@@ -0,0 +1,182 @@
+---
+name: ds-data-table-pagination
+description: >
+  Pagination for @elliemae/ds-data-table using the capital-P Pagination render prop with
+  @elliemae/ds-pagination primitives (DSPaginationContainer, DSPaginator, DSPagePrevButton,
+  DSPageNextButton, DSPerPageSelector). App slices data to current page before passing to DataTable.
+  Lowercase pagination prop is deprecated legacy — migrate to Pagination component on sight.
+type: core
+library: ds-data-table
+library_version: '3.60.0'
+requires:
+  - ds-data-table-setup
+  - ds-pagination-setup
+sources:
+  - '@elliemae/ds-data-table:dist/types/react-desc-prop-types.d.ts'
+---
+
+## Setup
+
+`TablePagination` assembles `@elliemae/ds-pagination` primitives and reads pagination state from the project's state manager. Its assembly is outside the scope of this skill.
+
+**Before implementing `TablePagination`:**
+
+1. Check whether `@elliemae/ds-pagination` has a published intent skill — run `npx @tanstack/intent install` in the project or look for a `skills/` directory inside the `@elliemae/ds-pagination` package. The `ds-pagination-setup` skill covers the full composable assembly. If found, load it.
+2. If no skill is found, ask the human to share a correct implementation example from the Dimsum storybook before proceeding. Do not approximate the assembly from incomplete information — omitting the AJAX model or memoization requirements produces incorrect implementations.
+
+The DataTable side of the wiring. `TablePagination` is defined at module level — it is already a stable reference and does not need `useCallback`. Pass `pagedData` (the current page slice), not the full dataset — DataTable does not paginate internally; it renders whatever array it receives.
+
+```jsx
+import { DataTable } from '@elliemae/ds-data-table';
+
+const TablePagination = () => {
+  // ... full assembly — see @elliemae/ds-pagination ds-pagination-setup skill
+};
+
+<DataTable columns={columns} data={pagedData} height={438} Pagination={TablePagination} />;
+```
+
+## Core Patterns
+
+### Resetting page index on filter change
+
+Page index must always reset to 1 when filters change. With AJAX pagination, this means dispatching the new filters and page 1 together in a single API call:
+
+```jsx
+const onFiltersChange = useCallback(
+  (newFilters) => {
+    dispatch(setFilters(newFilters));
+    dispatch(setPageIndex(1));
+    dispatch(fetchPagedData({ filters: newFilters, page: 1, pageSize }));
+  },
+  [pageSize],
+);
+```
+
+If you encounter pagination combined with client-side filtering (`applyOutOfTheBoxFilters` slicing an in-memory array), treat it as a code smell. Pagination is by industry standards a backend concern — backends have specialized tools for it (SQL LIMIT/OFFSET, cursor-based queries, database engine algorithms optimized for exactly this problem). Implementing it on the frontend duplicates that concern on the wrong layer with inferior tools, making the whole flow suboptimal and fragile. Rendering paginated chunks from an in-memory array is better than rendering all rows at once, but it covers a backend limitation rather than solving the underlying problem.
+
+Combined with client-side filtering the situation is worse: filters applied to an in-memory slice operate only on the current page, not the full dataset — the results are silently incorrect. Additionally, the in-memory array grows stale the moment the source data changes; server-side pagination and filtering inherently avoid this because every request fetches fresh data from the authoritative source. Raise this with the team before implementing.
+
+## Common Mistakes
+
+### HIGH Using deprecated lowercase pagination prop
+
+Wrong:
+
+```jsx
+<DataTable columns={columns} data={rows} height={500} pagination={{ pageSize: 10 }} />
+// or
+<DataTable columns={columns} data={rows} height={500} pagination={false} />
+```
+
+Correct:
+
+```jsx
+// Capital-P Pagination render prop — TablePagination defined at module level
+<DataTable columns={columns} data={pagedData} height={500} Pagination={TablePagination} />
+```
+
+The lowercase `pagination` prop is legacy kept for backwards compatibility. Migrate on sight.
+
+Source: https://dimsum.mortgagetech.ice.com/iframe.html?id=components-datatable-features-pagination--paginated-table
+
+---
+
+### HIGH Passing full dataset to DataTable instead of current page slice
+
+Wrong:
+
+```jsx
+<DataTable columns={columns} data={allData} height={500} Pagination={TablePagination} />
+```
+
+Correct:
+
+```jsx
+<DataTable columns={columns} data={pagedData} height={500} Pagination={TablePagination} />
+```
+
+DataTable does not internally paginate data. The app must slice to the current page. Passing all rows defeats virtualization.
+
+Source: https://dimsum.mortgagetech.ice.com/iframe.html?id=components-datatable-features-pagination--paginated-table
+
+---
+
+### HIGH Pagination component defined inside parent component instead of at module level
+
+Wrong:
+
+```jsx
+// Defined inside a component — new reference or new component type on every render
+const ParentComponent = () => {
+  const MyPagination = () => <DSPaginationContainer>...</DSPaginationContainer>;
+  // or: const MyPagination = useCallback(() => <DSPaginationContainer>...</DSPaginationContainer>, [...]);
+  return <DataTable columns={columns} data={pagedData} height={500} Pagination={MyPagination} />;
+};
+```
+
+Correct:
+
+```jsx
+// Defined at module level — stable reference, reads state from state manager directly
+// See ds-pagination-setup skill from @elliemae/ds-pagination for the full implementation
+const TablePagination = () => {
+  /* ... */
+};
+
+const ParentComponent = () => (
+  <DataTable columns={columns} data={pagedData} height={500} Pagination={TablePagination} />
+);
+```
+
+A component defined inside another component creates a new component type identity on every render. React unmounts and remounts the subtree on every cycle, regardless of `useCallback` memoization. State manager integration (Redux/Zustand/Jotai) is the correct mechanism for sharing pagination state with a module-level component.
+
+Source: https://dimsum.mortgagetech.ice.com/iframe.html?id=components-datatable-features-pagination--paginated-table
+
+---
+
+### MEDIUM Not resetting page index when filters change
+
+Wrong:
+
+```jsx
+const onFiltersChange = useCallback(
+  (newFilters) => {
+    dispatch(setFilters(newFilters));
+    dispatch(fetchPagedData({ filters: newFilters, page: pageIndex, pageSize }));
+    // pageIndex not reset — user stays on page 3 of a now-smaller result set
+  },
+  [pageIndex, pageSize],
+);
+```
+
+Correct:
+
+```jsx
+const onFiltersChange = useCallback(
+  (newFilters) => {
+    dispatch(setFilters(newFilters));
+    dispatch(setPageIndex(1));
+    dispatch(fetchPagedData({ filters: newFilters, page: 1, pageSize }));
+  },
+  [pageSize],
+);
+```
+
+Stale page index after a filter change leaves the user on a page that may not exist in the filtered result set.
+
+Source: https://dimsum.mortgagetech.ice.com/iframe.html?id=components-datatable-features-pagination--paginated-table
+
+---
+
+See also: ds-data-table-migration/SKILL.md — lowercase pagination prop migration
+See also: ds-pagination-setup/SKILL.md — full TablePagination assembly with @elliemae/ds-pagination primitives
+
+---
+
+## 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-row-variants/SKILL.md

@@ -0,0 +1,260 @@
+---
+name: ds-data-table-row-variants
+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).
+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'
+  - '@elliemae/ds-data-table:dist/types/exported-related/RowVariants.d.ts'
+  - '@elliemae/ds-data-table:dist/types/exported-related/groupBy.d.ts'
+---
+
+## Setup
+
+```jsx
+import { DataTable, ROW_VARIANTS } from '@elliemae/ds-data-table';
+
+// getRowVariant receives the row object and returns a ROW_VARIANTS value.
+// Default is ROW_VARIANTS.PRIMARY — only override rows that need a different variant.
+//
+// getRowVariant is a plain function called at render time — not a React component.
+// Do not call hooks in the callback body (the linter may even flag this).
+// If returning a component type, that component IS rendered via <Component {...props} />
+// and can use hooks normally — the constraint is on the callback body only.
+const getRowVariant = (row) => {
+  if (row.original.status === 'inactive') return ROW_VARIANTS.SECONDARY;
+  return ROW_VARIANTS.PRIMARY;
+};
+
+<DataTable columns={columns} data={rows} height={500} getRowVariant={getRowVariant} />;
+```
+
+### Available ROW_VARIANTS values
+
+```js
+import { ROW_VARIANTS } from '@elliemae/ds-data-table';
+
+ROW_VARIANTS.PRIMARY; // 'ds-primary-row'         — standard row (default)
+ROW_VARIANTS.SECONDARY; // 'ds-secondary-row'       — alternate visual treatment
+ROW_VARIANTS.HEADER_GROUP; // 'ds-header-group-row'    — group header row (used with groupBy)
+ROW_VARIANTS.COMPACT_PRIMARY; // 'ds-compact-primary-row' — compact density, primary style
+ROW_VARIANTS.COMPACT_SECONDARY; // 'ds-compact-secondary-row' — compact density, secondary style
+ROW_VARIANTS.SKELETON; // 'ds-skeleton-row'        — skeleton loading row; accessible via getRowVariant
+//   but the standard skeleton UX is controlled by the isSkeleton prop,
+//   not by returning this from getRowVariant (see ds-data-table-feedback)
+```
+
+## Core Patterns
+
+### 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.
+
+**What groupBy produces:**
+
+```js
+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' },
+];
+
+const groupedData = groupBy(rows, 'position');
+// Result:
+// [
+//   {
+//     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' },
+//     ],
+//     uid: '<auto-generated>',          // stable key for DataTable row identity
+//   },
+//   {
+//     dimsumHeaderValue: 'Designer',
+//     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.
+
+**Wiring getRowVariant and groupedRowsRenderHeader:**
+
+```jsx
+// getRowVariant distinguishes group header rows from data rows using dimsumHeaderValue
+const getRowVariant = useCallback((row) => {
+  if (row.original.dimsumHeaderValue) return ROW_VARIANTS.HEADER_GROUP;
+  return ROW_VARIANTS.PRIMARY;
+}, []);
+
+// groupedRowsRenderHeader: function returning JSX.Element, or a static string.
+// 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.
+// <MyGroupHeader value={value} subRows={subRows} />), that component gets its own fiber
+// as a rendered child and can use hooks normally — the constraint is on the callback body only.
+const groupedRowsRenderHeader = useCallback(
+  (value, subRows) => (
+    <span>
+      {value} ({subRows?.length ?? 0} items)
+    </span>
+  ),
+  [],
+);
+
+<DataTable
+  columns={columns}
+  data={groupedData}
+  height={500}
+  uniqueRowAccessor="uid"
+  getRowVariant={getRowVariant}
+  groupedRowsRenderHeader={groupedRowsRenderHeader}
+/>;
+```
+
+### Switching group-by column dynamically
+
+The active group-by key belongs in the state manager — it drives which data the table displays and should survive navigation or component remounts.
+
+```jsx
+const { activeGroupBy } = useSelector(selectTableState);
+const dispatch = useDispatch();
+
+const groupedByPosition = useMemo(() => groupBy(rows, 'position'), [rows]);
+const groupedByCountry = useMemo(() => groupBy(rows, 'country'), [rows]);
+
+const displayedData = activeGroupBy === 'country' ? groupedByCountry : groupedByPosition;
+
+const handleGroupByPosition = useCallback(() => dispatch(setGroupBy('position')), [dispatch]);
+const handleGroupByCountry = useCallback(() => dispatch(setGroupBy('country')), [dispatch]);
+```
+
+### disabledRows
+
+```jsx
+// disabledRows: Record<rowUid, boolean>
+// Disabled rows are visually styled as inactive and excluded from selection
+const disabledRows = useMemo(() => ({ 'row-1': true, 'row-4': true }), []);
+
+<DataTable columns={columns} data={rows} height={500} uniqueRowAccessor="id" disabledRows={disabledRows} />;
+```
+
+## Common Mistakes
+
+### HIGH Using ROW_VARIANTS that does not exist
+
+Wrong:
+
+```jsx
+import { ROW_VARIANTS } from '@elliemae/ds-data-table';
+const getRowVariant = (row) => {
+  if (row.original.isError) return ROW_VARIANTS.HIGHLIGHTED; // undefined — not a real value
+  return ROW_VARIANTS.PRIMARY;
+};
+```
+
+Correct:
+
+```jsx
+const getRowVariant = (row) => {
+  if (row.original.isError) return ROW_VARIANTS.SECONDARY;
+  return ROW_VARIANTS.PRIMARY;
+};
+```
+
+`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.
+
+---
+
+### HIGH Returning a JSX element from getRowVariant instead of a component reference or variant string
+
+Wrong:
+
+```jsx
+// Returns a JSX element (React.createElement result) — a new object on every call
+const getRowVariant = (row) => {
+  if (row.original.isHeader) return <CustomHeaderRow row={row} />;
+  return ROW_VARIANTS.PRIMARY;
+};
+```
+
+Correct — use ROW_VARIANTS (preferred):
+
+```jsx
+const getRowVariant = (row) => {
+  if (row.original.dimsumHeaderValue) return ROW_VARIANTS.HEADER_GROUP;
+  return ROW_VARIANTS.PRIMARY;
+};
+```
+
+Correct — component reference as last resort (strongly discouraged, see note below):
+
+```jsx
+// CustomHeaderRow defined at module level — stable reference
+const CustomHeaderRow = (props) => {
+  /* ... */
+};
+
+const getRowVariant = useCallback((row) => {
+  if (row.original.dimsumHeaderValue) return CustomHeaderRow; // reference, not instance
+  return ROW_VARIANTS.PRIMARY;
+}, []);
+```
+
+`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.
+
+Source: https://dimsum.mortgagetech.ice.com/iframe.html?id=components-datatable-advanced--group-by-column
+
+---
+
+### MEDIUM Manually constructing groupBy objects instead of using the utility
+
+Wrong:
+
+```jsx
+// Manually building what groupBy produces — fragile and likely to diverge
+const groupedData = [{ dimsumHeaderValue: 'Developer', subRows: [row1, row2], uid: 'hardcoded-1' }];
+```
+
+Correct:
+
+```jsx
+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.
+
+---
+
+### HIGH Non-primitive row variant props not memoized cause unnecessary re-renders
+
+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                   |
+
+Non-stable references cause DataTable to re-render on every parent render cycle regardless of whether row variant state actually changed.
+
+---
+
+See also: ds-data-table-expandable/SKILL.md — expand patterns; tableRowDetails master-detail is deprecated