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

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

@@ -0,0 +1,257 @@
+---
+name: ds-data-table-slots
+description: >
+  Low-level slot injection surface for @elliemae/ds-data-table. Reach for this only after OOB
+  features cannot satisfy the requirement. Valid uses: data-* attribute injection (analytics,
+  tracking), aria-* overrides, and conditional styling. Full slot surface in DATA_TABLE_SLOTS /
+  DSDataTableSlots. App side owns long-term maintenance of anything injected via slots.
+type: core
+library: ds-data-table
+library_version: '3.60.0'
+requires:
+  - ds-data-table-setup
+sources:
+  - '@elliemae/ds-data-table:dist/types/constants/index.d.ts'
+  - '@elliemae/ds-data-table:dist/types/react-desc-prop-types.d.ts'
+---
+
+## Slot surface — DOM hierarchy
+
+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.
+
+**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.
+
+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)
+└── CONTENT_WRAPPER (dsDatatableContentWrapper) · div
+    ├── TABLE_WRAPPER (dsDatatableTableWrapper) · div[role="table"]
+    │   └── VIRTUAL_LIST_WRAPPER (dsDatatableVirtualListWrapper) · div[role="rowgroup" tabIndex="-1"]
+    │       └── TABLE_CONTENT_WRAPPER (dsDatatableTableContentWrapper) · div
+    │           ├── HEAD_WRAPPER (dsDatatableHeadWrapper) · div
+    │           │   └── HEAD_TR (dsDatatableHeadTr) · div[role="row"]
+    │           │       └── HEADER_CELL_WRAPPER (dsDatatableHeaderCellWrapper) · div  (one per column)
+    │           │           └── HEAD_TH (dsDatatableHeadTh) · div[role="columnheader"]
+    │           │               ║  prop: dsDatatableHeadTh
+    │           │               ║  callback: ({ columnId, firstFocuseableColumnHeaderId }) => props
+    │           │               ├── HEAD_RIGHT_ICONS_WRAPPER (dsDatatableHeadRightIconsWrapper) · div
+    │           │               │   present when: canSort=true OR column.filter is set
+    │           │               │   ├── sort button (dsButtonRoot — no DataTable slot attr)
+    │           │               │   └── FILTER_POPOVER_BUTTON (dsDatatableFilterPopoverButton) · span
+    │           │               │       present when: column.filter is set
+    │           │               │       └── filter trigger button (dsButtonRoot — no DataTable slot attr)
+    │           │               │           clicking this opens the filter popover (portal — see below)
+    │           │               ├── EXPAND_CELL_CONTAINER (dsDatatableExpandCellContainer) · span[role="button"]
+    │           │               │   present in: the expand column header cell only
+    │           │               └── RESIZER (dsDatatableResizer)  ← isResizeable=true only
+    │           │                   prop: dsDatatableResizer  ·  wraps DSInputText
+    │           │                   DSInputText root shows dsInputtextRoot  ·  data-dimsum-slot="dsDatatableResizer"
+    │           │                   and data-testid="ds-datatable-resizer" land on the inner input element
+    │           │
+    │           ├── LOADER_WRAPPER (dsDatatableLoaderWrapper) · div[role="row"]
+    │           │   present when: isLoading=true  (sibling of HEAD_WRAPPER)
+    │           │
+    │           ├── 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)
+    │           │       ├── EMPTY_PRIMARY_MESSAGE (dsDatatableEmptyPrimaryMessage) · p
+    │           │       ├── EMPTY_SECONDARY_MESSAGE (dsDatatableEmptySecondaryMessage) · p
+    │           │       └── CTA button (dsButtonRoot — no DataTable slot attr)
+    │           │           present when: noResultsButtonLabel + onNoResultsButtonClick provided
+    │           │
+    │           └── ROW (dsDatatableRow) · div[position:absolute]  (one per visible row)
+    │               ║  prop: dsDatatableRow  ·  layout wrapper — not the semantic row element
+    │               └── FULLSIZE_GRID (dsDatatableFullsizeGrid) · div
+    │                   ║  prop: dsDatatableFullsizeGrid  ·  owns onClick/onKeyDown row interaction handlers
+    │                   └── CELL_CONTAINER (dsDatatableCellsContainer) · div[role="row"]
+    │                       ║  ★ THE semantic row element — what screen readers traverse
+    │                       ║  prop: dsDatatableCellsContainer  ·  callback: (row) => props
+    │                       ║  inject aria-*, data-* attributes, bg/color xstyled props here
+    │                       │
+    │                       ├── GROUP_HEADER_CONTAINER (dsDatatableGroupHeaderContainer) · div[role="cell"]
+    │                       │   present in: group header rows only (requires getRowVariant returning 'ds-header-group-row')
+    │                       │   └── GROUP_HEADER_TITLE (dsDatatableHeaderTitle) · span
+    │                       │
+    │                       ├── CELL (dsDatatableCell) · div[role="cell"]  (one per data column)
+    │                       │   ║  prop: dsDatatableCell  ·  callback: (cell) => props
+    │                       │   ├── EDITABLE_CONTAINER (dsDatatableEditableContainer) · div[role="group"]
+    │                       │   │   present when: column.editable is set
+    │                       │   │   ├── CELL_CONTENT (dsDatatableCellContent) · div
+    │                       │   │   ├── pencil icon (dsIconRoot — no DataTable slot attr)
+    │                       │   │   └── TEXT_EDITABLE_CELL_INPUT (dsDatatableTextEditableCellInput) · input
+    │                       │   │       present after user clicks to enter edit mode (autoFocus on mount)
+    │                       │   └── CELL_CONTENT (dsDatatableCellContent) · div  (standard columns)
+    │                       │       ├── EXPAND_CELL_CONTAINER (dsDatatableExpandCellContainer) · span[role="button"]
+    │                       │       │   present in: expand column data cells only
+    │                       │       ├── SINGLE_CELL_CONTAINER (dsDatatableSingleCellContainer) · div
+    │                       │       │   present in: single-select column data cells only
+    │                       │       └── DRAG_AND_DROP_GRIPPER (dsDatatableDragAndDropGripper) · div[role="button"]
+    │                       │           present in: DnD column data cells (dragAndDropRows=true)
+    │                       │
+    │                       └── ACTION_CELL (dsDatatableActionCell) · div[role="cell"]
+    │                           present when: renderRowActions prop is set
+    │                           └── TOOLBAR_POSITION (dsDatatableToolbarPosition) · div
+    │                               └── TOOLBAR_WRAPPER (dsDatatableToolbarWrapper) · div
+    │                                   ├── TOOLBAR_BUTTONS_WRAPPER (dsDatatableToolbarButtonsWrapper) · div
+    │                                   │   present after user opens the toolbar
+    │                                   └── trigger button (dsButtonRoot — no DataTable slot attr)
+    │                                       data-testid="data-table-toolbar-trigger"
+    │
+    └── PAGINATION_WRAPPER (dsDatatablePaginationWrapper) · div
+        present when: pagination prop is set
+        └── (ds-pagination component — dsPaginationWrapper etc.)
+
+── 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)
+   └── 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)
+```
+
+**Slots that are injectable but do not appear as `dsDatatable*` in the DOM:**
+
+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.
+
+| 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`           |
+
+**Slots only visible in interactive states (not in static render):**
+
+| Slot key                                              | Required interaction                   | How to trigger in a test                                                                       |
+| ----------------------------------------------------- | -------------------------------------- | ---------------------------------------------------------------------------------------------- |
+| `TOOLBAR_BUTTONS_WRAPPER`                             | Click toolbar trigger                  | `userEvent.click(screen.getByTestId('data-table-toolbar-trigger'))`                            |
+| `TEXT_EDITABLE_CELL_INPUT`                            | Click editable cell to enter edit mode | `userEvent.click(screen.getByTestId('ds-datatable-editable-container'))`                       |
+| `FILTER_POPOVER_CONTENT` / `FREE_TEXT_SEARCH_WRAPPER` | Click column filter button             | `fireEvent.click(screen.getByTestId('data-table-filter-menu-button').querySelector('button'))` |
+| `DROP_INDICATOR`                                      | Active drag in progress                | Requires a real browser drag interaction — not reliably reproducible in JSDOM                  |
+
+**Critical distinction — `CELL_CONTAINER` vs `ROW` vs `FULLSIZE_GRID`:**
+
+Three slots wrap each row. They are not interchangeable:
+
+- `ROW` (`dsDatatableRow`) — the absolute-positioned layout div. Inject layout-level CSS only. Not a semantic element.
+- `FULLSIZE_GRID` (`dsDatatableFullsizeGrid`) — the grid div that owns the click/keyboard handlers. Injectable via `dsDatatableFullsizeGrid` slot prop.
+- `CELL_CONTAINER` (`dsDatatableCellsContainer`) — the `role="row"` div. **This is the semantic row.** Screen readers traverse this. `aria-rowindex`, `aria-label`, `aria-selected`, and background color belong here.
+
+Injecting `aria-selected` or a background color into `ROW` instead of `CELL_CONTAINER` is a silent failure — the attribute exists in the DOM but attaches to a layout wrapper that screen readers skip.
+
+**Header slots:**
+
+- `HEAD_TR` (`dsDatatableHeadTr`) — the `role="row"` header row container. Injectable via `dsDatatableHeadTr` slot prop.
+- `HEAD_TH` (`dsDatatableHeadTh`) — the `role="columnheader"` element. Use for `innerRef` focus-bridge wiring and column-level aria overrides.
+
+`DATA_TABLE_SLOTS.HEAD_TH` (prop: `dsDatatableHeadTh`) has a distinct callback argument shape from row and cell slots. It receives `{ columnId: string, firstFocuseableColumnHeaderId: string | undefined }` — the ID of the current header cell and the ID of the first focusable column header in the table. This is used for focus-bridge patterns such as wiring a `fallbackRef` from an external filter bar to the first column header when the last filter pill is removed.
+
+```jsx
+const dsDatatableHeadTh = useCallback(
+  ({ columnId, firstFocuseableColumnHeaderId }) => {
+    if (columnId === firstFocuseableColumnHeaderId) return { innerRef: fallbackRef };
+    return {};
+  },
+  [fallbackRef],
+);
+```
+
+## When to reach for slots
+
+**Try OOB first.** The DataTable exposes first-class callbacks for every stateful interaction — `onSelectionChange`, `onFiltersChange`, `onColumnSort`, `onRowExpand`, `onCellValueChange`. These are the correct and complete sites for application logic. Slots are not a shortcut to those.
+
+Slots are a low-level escape hatch. They inject props directly into internal styled components. The application side owns long-term maintenance of everything injected this way — if the DataTable's internal structure changes, slot-based injections break silently.
+
+**Valid uses:**
+
+- `data-*` attributes — analytics tracking, feature flags, test selectors that the DataTable doesn't expose natively. Example: `data-private="true"`, `data-loan-id={row.original.id}`.
+- `aria-*` overrides — accessibility attributes the DataTable doesn't set automatically for your specific use case.
+- Conditional styling — `bg`, `color`, `style` driven by row/cell data. The app team accepts ownership of visual maintenance.
+
+**Red flag — event listeners via slots.** If you find yourself attaching `onClick`, `onKeyDown`, or other event listeners through `dsDatatableCellsContainer` or `dsDatatableCell`, stop. The DataTable already manages its own interaction model. Before proceeding:
+
+1. Check whether an OOB callback already handles what you need.
+2. Re-examine the UX requirement — if the system provides no first-class support for this interaction, that is a signal the design may be solving a problem in a non-standard way.
+3. Engage the Dimsum team (ICE engineers: Teams/Jira; partners: your org's Dimsum contact) to verify whether an OOB solution exists or should be added.
+
+## Setup
+
+The two primary consumer props. Both receive a memoized callback returning a plain props object — not a React component, no hooks inside.
+
+```jsx
+import { DataTable } from '@elliemae/ds-data-table';
+
+// Row level — targets CELL_CONTAINER (the semantic role="row" element)
+const rowContainerProps = useCallback((row) => {
+  if (row.original.status === 'error') {
+    return {
+      'data-error-row': 'true', // data-* injection
+      'aria-invalid': 'true', // aria-* injection
+      bg: { _: 'red.100', hover: 'red.200 !important' }, // xstyled
+    };
+  }
+  return {};
+}, []);
+
+// Cell level — targets CELL (individual role="cell" element)
+const cellProps = useCallback((cell) => {
+  if (cell.row.original.status === 'error') {
+    return { style: { color: 'red' } }; // React CSSProperties
+  }
+  return {};
+}, []);
+
+<DataTable
+  columns={columns}
+  data={rows}
+  height={500}
+  dsDatatableCellsContainer={rowContainerProps}
+  dsDatatableCell={cellProps}
+/>;
+```
+
+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.
+
+## `column.cellStyle` vs `dsDatatableCell`
+
+`column.cellStyle` (`React.CSSProperties`) applies the same CSS to every cell in that column. Use it for uniform column-level layout: sticky positioning, fixed-width overrides. It requires no callback.
+
+`dsDatatableCell` varies per row based on data. Use it when the styling depends on row state (error, highlight, selection). Reaching for `dsDatatableCell` to apply the same style to all rows in a column is the wrong tool — `column.cellStyle` is simpler and sufficient for that case.
+
+## Critical constraint — no hooks inside slot callbacks
+
+`dsDatatableCellsContainer` and `dsDatatableCell` are JavaScript functions called at render time inside the DataTable's own rendering context. They are not React components. Hook calls inside them register against the calling component's hook list — a rules-of-hooks violation. Obtain all external values (theme tokens, feature flags, state) at component level and close over them:
+
+```jsx
+const theme = useTheme();
+const errorBg = theme.colors.danger[50];
+
+const rowContainerProps = useCallback(
+  (row) => {
+    if (row.original.status === 'error') return { bg: errorBg };
+    return {};
+  },
+  [errorBg],
+);
+```
+
+---
+
+See also: ds-data-table-boundaries/SKILL.md — when slots cannot satisfy the requirement, escalation path