@tanstack/table-core 9.0.0-alpha.8 → 9.0.0-beta.1

package/skills/row-expanding/SKILL.md

@@ -0,0 +1,348 @@
+---
+name: row-expanding
+description: >
+  Expand and collapse rows in TanStack Table v9 with the `expandedRowModel`
+  stage. Two patterns: (1) tree sub-rows via `getSubRows`, (2) detail panels
+  via `getRowCanExpand`. Covers `rowExpandingFeature` + `createExpandedRowModel()`,
+  `state.expanded` (ExpandedState = true | Record<string, boolean>),
+  `onExpandedChange`, `manualExpanding`, `paginateExpandedRows` (default true),
+  `autoResetExpanded`, `row.toggleExpanded` / `getIsExpanded` / `getCanExpand` /
+  `getIsAllParentsExpanded` / `getToggleExpandedHandler`, `table.toggleAllRowsExpanded`,
+  `row.depth` for indentation, and the `filterFromLeafRows` /
+  `maxLeafRowFilterDepth` interaction with filtering.
+type: core
+library: tanstack-table
+library_version: '9.0.0-alpha.48'
+requires:
+  - state-management
+sources:
+  - TanStack/table:docs/guide/expanding.md
+  - TanStack/table:packages/table-core/src/features/row-expanding/rowExpandingFeature.utils.ts
+  - TanStack/table:examples/react/expanding/src/main.tsx
+  - TanStack/table:examples/react/sub-components/src/main.tsx
+---
+
+This skill builds on `tanstack-table/state-management`. Read it first for the atom model.
+
+## Setup
+
+```ts
+import {
+  tableFeatures,
+  rowExpandingFeature,
+  createExpandedRowModel,
+  constructTable,
+} from '@tanstack/table-core'
+import type { ExpandedState } from '@tanstack/table-core'
+
+const features = tableFeatures({ rowExpandingFeature })
+
+// Tree mode — data has nested subRows
+const table = constructTable({
+  features,
+  rowModels: { expandedRowModel: createExpandedRowModel() },
+  columns,
+  data,
+  getSubRows: (row) => row.subRows,
+  initialState: { expanded: {} satisfies ExpandedState },
+})
+
+// Or detail-panel mode — every row can expand to a sub-component
+const detailTable = constructTable({
+  features,
+  rowModels: { expandedRowModel: createExpandedRowModel() },
+  columns,
+  data,
+  getRowCanExpand: () => true,
+})
+```
+
+## Core Patterns
+
+### Tree table with indentation
+
+```tsx
+// From examples/react/expanding/src/main.tsx
+{
+  row.getVisibleCells().map((cell, i) => (
+    <td key={cell.id}>
+      {i === 0 && row.getCanExpand() ? (
+        <button
+          onClick={row.getToggleExpandedHandler()}
+          style={{ paddingLeft: `${row.depth * 2}rem` }}
+        >
+          {row.getIsExpanded() ? '👇' : '👉'}
+        </button>
+      ) : null}
+      <table.FlexRender cell={cell} />
+    </td>
+  ))
+}
+```
+
+`row.depth` is 0-based. `row.getCanExpand()` returns true when `row.subRows.length > 0`.
+
+### Detail panels for flat data
+
+```tsx
+// From examples/react/sub-components/src/main.tsx
+{
+  table.getRowModel().rows.map((row) => (
+    <React.Fragment key={row.id}>
+      <tr>
+        {row.getVisibleCells().map((cell) => (
+          <td key={cell.id}>
+            <table.FlexRender cell={cell} />
+          </td>
+        ))}
+      </tr>
+      {row.getIsExpanded() && (
+        <tr>
+          <td colSpan={row.getVisibleCells().length}>
+            <SubComponent row={row} />
+          </td>
+        </tr>
+      )}
+    </React.Fragment>
+  ))
+}
+```
+
+### Toggle ALL rows expanded at once
+
+```tsx
+<button onClick={table.getToggleAllRowsExpandedHandler()}>
+  {table.getIsAllRowsExpanded() ? '👇' : '👉'} Toggle All
+</button>
+```
+
+### Keep expanded children on their parent's page
+
+```ts
+const table = constructTable({
+  features: tableFeatures({ rowExpandingFeature, rowPaginationFeature }),
+  rowModels: {
+    expandedRowModel: createExpandedRowModel(),
+    paginatedRowModel: createPaginatedRowModel(),
+  },
+  columns,
+  data,
+  getSubRows: (r) => r.subRows,
+  paginateExpandedRows: false, // children stay glued to their parent
+})
+```
+
+`paginateExpandedRows: true` (default) flows expanded children through pagination — each child counts toward `pageSize`. `false` keeps them stuck under their parent.
+
+### Tree filtering with leaf-match propagation
+
+```ts
+const table = constructTable({
+  features: tableFeatures({ rowExpandingFeature, columnFilteringFeature }),
+  rowModels: {
+    expandedRowModel: createExpandedRowModel(),
+    filteredRowModel: createFilteredRowModel(filterFns),
+  },
+  columns,
+  data,
+  getSubRows: (r) => r.subRows,
+  filterFromLeafRows: true, // keep parent visible when ANY descendant matches
+})
+```
+
+## Common Mistakes
+
+### [HIGH] Setting `getRowCanExpand: () => true` together with tree data
+
+Wrong:
+
+```ts
+// every row gets an expander icon, including leaves with no subRows
+const table = useTable({
+  getRowCanExpand: () => true,
+  getSubRows: (r) => r.subRows,
+})
+// In cell: row.getCanExpand() always true → leaf rows show 👉 with nothing to expand
+```
+
+Correct:
+
+```ts
+// For pure tree data, omit getRowCanExpand and let it auto-detect:
+const table = useTable({
+  features,
+  rowModels: { expandedRowModel: createExpandedRowModel() },
+  columns,
+  data,
+  getSubRows: (row) => row.subRows,
+  // row.getCanExpand() is true only when subRows.length > 0
+})
+
+// For pure detail panels, override and skip getSubRows:
+const table = useTable({
+  features: tableFeatures({ rowExpandingFeature }),
+  rowModels: { expandedRowModel: createExpandedRowModel() },
+  columns,
+  data,
+  getRowCanExpand: () => true,
+})
+```
+
+`row_getCanExpand` resolves to `options.getRowCanExpand?.(row) ?? (enableExpanding ?? true) && !!row.subRows.length`. When `getRowCanExpand` is set, it wins — including for leaves.
+
+Source: packages/table-core/src/features/row-expanding/rowExpandingFeature.utils.ts
+
+### [MEDIUM] Setting `paginateExpandedRows: false` and expecting `pageSize` to be a hard cap
+
+Wrong:
+
+```ts
+const table = useTable({
+  paginateExpandedRows: false,
+  initialState: { pagination: { pageSize: 10 } },
+  // user expands all parents → 10 parents * 5 children = 60 visible rows
+})
+```
+
+Correct:
+
+```ts
+// Default behavior — children flow through pagination, pageSize is enforced:
+const table = useTable({
+  features,
+  rowModels: {
+    expandedRowModel: createExpandedRowModel(),
+    paginatedRowModel: createPaginatedRowModel(),
+  },
+  columns,
+  data,
+  getSubRows: (r) => r.subRows,
+  // paginateExpandedRows defaults to true
+})
+
+// OR keep children with parent — accept that pageSize is a soft cap:
+// paginateExpandedRows: false
+```
+
+`paginateExpandedRows: false` inflates each parent's page slice via `expandRows` — more rows render than `pageSize`. Pick deliberately.
+
+Source: packages/table-core/src/features/row-pagination/createPaginatedRowModel.ts
+
+### [MEDIUM] Storing `expanded` as `true` then writing into it like a Record
+
+Wrong:
+
+```ts
+// spreading `true` (a boolean) into an object gives {} - all rows collapse except [id]
+setExpanded((old) => ({ ...old, [row.id]: true }))
+// When old === true, this becomes { [row.id]: true } — everything else collapses!
+```
+
+Correct:
+
+```ts
+// Prefer the built-in handler — it materializes properly:
+<button onClick={row.getToggleExpandedHandler()}>
+  {row.getIsExpanded() ? '👇' : '👉'}
+</button>
+
+// Or handle materialization yourself:
+table.setExpanded((old) => {
+  if (old === true) {
+    const map: Record<string, boolean> = {}
+    Object.keys(table.getRowModel().rowsById).forEach((id) => { map[id] = true })
+    return { ...map, [row.id]: !map[row.id] }
+  }
+  return { ...old, [row.id]: !(old as Record<string, boolean>)[row.id] }
+})
+```
+
+`ExpandedState = true | Record<string, boolean>`. The `true` literal means "all rows expanded" — `row.toggleExpanded` materializes it correctly before applying per-row changes.
+
+Source: packages/table-core/src/features/row-expanding/rowExpandingFeature.utils.ts
+
+### [MEDIUM] `manualExpanding: true` with `expandedRowModel` registered
+
+Wrong:
+
+```ts
+// manualExpanding bypasses the expanded row model; sub-rows are never flattened
+const table = useTable({
+  features: tableFeatures({ rowExpandingFeature }),
+  rowModels: { expandedRowModel: createExpandedRowModel() }, // ignored
+  columns,
+  data,
+  getSubRows: (r) => r.subRows,
+  manualExpanding: true,
+})
+```
+
+Correct:
+
+```ts
+// Manual expanding is for server-side patterns where the server returns
+// a pre-flattened view based on which rows are expanded.
+const table = useTable({
+  features: tableFeatures({ rowExpandingFeature }),
+  rowModels: {}, // no expandedRowModel for manual mode
+  columns,
+  data: dataQuery.data, // server returns flattened rows when expanded
+  manualExpanding: true,
+  state: { expanded },
+  onExpandedChange: setExpanded,
+})
+
+// For client-side tree, omit manualExpanding:
+const clientTable = useTable({
+  features: tableFeatures({ rowExpandingFeature }),
+  rowModels: { expandedRowModel: createExpandedRowModel() },
+  columns,
+  data,
+  getSubRows: (r) => r.subRows,
+})
+```
+
+With `manualExpanding: true`, `getExpandedRowModel` skips the registered factory and returns `getPreExpandedRowModel()` (sorted rows). The expanded state still tracks "which rows are open" but the row model is NOT inflated.
+
+Source: packages/table-core/src/core/row-models/coreRowModelsFeature.utils.ts
+
+### [CRITICAL] Reimplementing tree flattening manually
+
+Wrong:
+
+```ts
+// Hand-rolled tree-to-flat conversion
+const flatRows = useMemo(() => {
+  const out: Person[] = []
+  function walk(rows: Person[], depth = 0) {
+    rows.forEach((r) => {
+      out.push({ ...r, depth })
+      if (expanded[r.id]) walk(r.subRows ?? [], depth + 1)
+    })
+  }
+  walk(data)
+  return out
+}, [data, expanded])
+```
+
+Correct:
+
+```ts
+const table = useTable({
+  features: tableFeatures({ rowExpandingFeature }),
+  rowModels: { expandedRowModel: createExpandedRowModel() },
+  columns, data,
+  getSubRows: (r) => r.subRows,
+})
+
+// then: table.getRowModel().rows already has row.depth and the expanded view
+table.getRowModel().rows.map((row) => /* render with row.depth */)
+```
+
+Source: maintainer interview (Phase 4, 2026-05-17)
+
+## See also
+
+- `tanstack-table/grouping` — pairs with expanding for drill-down on grouped rows
+- `tanstack-table/pagination` — `paginateExpandedRows` interaction
+- `tanstack-table/filtering` — `filterFromLeafRows` / `maxLeafRowFilterDepth` for tree filtering

package/skills/row-pinning/SKILL.md

@@ -0,0 +1,269 @@
+---
+name: row-pinning
+description: >
+  Pin specific rows to a top or bottom region in TanStack Table v9. State shape
+  is `rowPinning: { top: string[]; bottom: string[] }` keyed by `row.id`. Covers
+  `rowPinningFeature`, `row.pin(position, includeLeafRows?, includeParentRows?)`,
+  `row.getIsPinned` / `getPinnedIndex` / `getCanPin`, `table.getTopRows` /
+  `getBottomRows` / `getCenterRows` / `getIsSomeRowsPinned`, the
+  `enableRowPinning` option (bool or row predicate), and `keepPinnedRows`
+  (default true — persist across pagination/filtering vs. hide when filtered out).
+  Simpler pipeline than column pinning — only one reorder step: Row Pinning →
+  Sorting.
+type: core
+library: tanstack-table
+library_version: '9.0.0-alpha.48'
+requires:
+  - state-management
+sources:
+  - TanStack/table:docs/guide/row-pinning.md
+  - TanStack/table:packages/table-core/src/features/row-pinning/rowPinningFeature.utils.ts
+  - TanStack/table:examples/react/row-pinning/src/main.tsx
+---
+
+This skill builds on `tanstack-table/state-management`. Read it first for the atom model.
+
+## Setup
+
+```ts
+import {
+  tableFeatures,
+  rowPinningFeature,
+  rowPaginationFeature,
+  createPaginatedRowModel,
+  constructTable,
+} from '@tanstack/table-core'
+import type { RowPinningState } from '@tanstack/table-core'
+
+const features = tableFeatures({ rowPinningFeature, rowPaginationFeature })
+
+const table = constructTable({
+  features,
+  rowModels: {
+    paginatedRowModel: createPaginatedRowModel(),
+  },
+  columns,
+  data,
+  getRowId: (row) => row.userId, // ← essentially mandatory
+  initialState: {
+    rowPinning: { top: [], bottom: [] } satisfies RowPinningState,
+  },
+})
+
+// Pin a row
+row.pin('top') // or 'bottom' | false
+```
+
+## Core Patterns
+
+### Pin/unpin buttons in a cell
+
+```tsx
+// From examples/react/row-pinning/src/main.tsx
+<button onClick={() => row.pin('top')} disabled={!row.getCanPin()}>📌⬆</button>
+<button onClick={() => row.pin('bottom')} disabled={!row.getCanPin()}>📌⬇</button>
+{row.getIsPinned() && <button onClick={() => row.pin(false)}>✖ Unpin</button>}
+```
+
+For grouped/expanded data, pass include flags:
+
+```ts
+row.pin('top', /* includeLeafRows */ true, /* includeParentRows */ false)
+```
+
+### Render pinned rows separately
+
+```tsx
+<tbody>
+  {table.getTopRows().map((row) => (
+    <PinnedRow key={row.id} row={row} table={table} />
+  ))}
+  {table.getCenterRows().map((row) => (
+    <tr key={row.id}>
+      {row.getAllCells().map((cell) => (
+        <td key={cell.id}>
+          <table.FlexRender cell={cell} />
+        </td>
+      ))}
+    </tr>
+  ))}
+  {table.getBottomRows().map((row) => (
+    <PinnedRow key={row.id} row={row} table={table} />
+  ))}
+</tbody>
+```
+
+### Disable persistence across pagination
+
+```ts
+const table = constructTable({
+  features: tableFeatures({ rowPinningFeature, columnFilteringFeature }),
+  rowModels: { filteredRowModel: createFilteredRowModel(filterFns) },
+  columns,
+  data,
+  getRowId: (row) => row.id,
+  keepPinnedRows: false, // pinned rows disappear when filtered/paginated out
+})
+```
+
+`keepPinnedRows: true` (default) keeps pinned rows visible even when their underlying row would otherwise be filtered or paginated away.
+
+### Conditional pin permission
+
+```ts
+const table = constructTable({
+  features,
+  columns,
+  data,
+  enableRowPinning: (row) => !row.original.archived, // predicate form
+})
+```
+
+## Common Mistakes
+
+### [HIGH] Omitting `getRowId` so pins attach to array indices
+
+Wrong:
+
+```ts
+// row.id defaults to row.index; pin survives wrong rows after refetch
+const table = useTable({
+  features: tableFeatures({ rowPinningFeature, rowPaginationFeature }),
+  data, // refetched periodically
+})
+```
+
+Correct:
+
+```ts
+const table = useTable({
+  features: tableFeatures({ rowPinningFeature, rowPaginationFeature }),
+  data,
+  getRowId: (row) => row.userId, // or row.uuid, row.id from API, etc.
+})
+
+// For grouped/expanded data, pass the include flags too:
+row.pin('top', includeLeafRows, includeParentRows)
+```
+
+`rowPinning.top` and `rowPinning.bottom` are arrays of string row ids. Default `row.id` is the data array index — refetched data reuses index 3 for a different record, but the pinning state still pins index 3.
+
+Source: docs/guide/row-selection.md (same root principle); examples/react/row-pinning/src/main.tsx
+
+### [MEDIUM] Surprise behavior from `keepPinnedRows: true` default
+
+Wrong:
+
+```ts
+// Expecting pinned rows to vanish on filter, but they don't (default)
+const table = useTable({
+  features: tableFeatures({ rowPinningFeature, columnFilteringFeature }),
+  // keepPinnedRows defaults to true; pinned rows survive filtering
+})
+```
+
+Correct:
+
+```ts
+// Be explicit about the UX you want
+const table = useTable({
+  features: tableFeatures({ rowPinningFeature, columnFilteringFeature }),
+  keepPinnedRows: false, // pinned rows disappear when filtered/paginated out
+})
+
+// Or keep the default and render pinned separately:
+<tbody>
+  {table.getTopRows().map((row) => <PinnedRow row={row} key={row.id} />)}
+  {table.getCenterRows().map((row) => <Row row={row} key={row.id} />)}
+  {table.getBottomRows().map((row) => <PinnedRow row={row} key={row.id} />)}
+</tbody>
+```
+
+`keepPinnedRows: true` makes `getTopRows()` / `getBottomRows()` search the full pre-pagination row set; `false` only finds rows currently in the row model.
+
+Source: packages/table-core/src/features/row-pinning/rowPinningFeature.utils.ts; examples/react/row-pinning/src/main.tsx
+
+### [MEDIUM] Rendering pinned rows TWICE (once at top/bottom, once in main flow)
+
+Wrong:
+
+```tsx
+<tbody>
+  {table.getTopRows().map((row) => (
+    <PinnedRow row={row} key={row.id} />
+  ))}
+  {table.getRowModel().rows.map(
+    (
+      row, // ← still includes pinned rows
+    ) => (
+      <tr key={row.id}>...</tr>
+    ),
+  )}
+  {table.getBottomRows().map((row) => (
+    <PinnedRow row={row} key={row.id} />
+  ))}
+</tbody>
+```
+
+Correct:
+
+```tsx
+<tbody>
+  {table.getTopRows().map((row) => (
+    <PinnedRow key={row.id} row={row} table={table} />
+  ))}
+  {table.getCenterRows().map((row) => (
+    <tr key={row.id}>
+      {row.getAllCells().map((cell) => (
+        <td key={cell.id}>
+          <table.FlexRender cell={cell} />
+        </td>
+      ))}
+    </tr>
+  ))}
+  {table.getBottomRows().map((row) => (
+    <PinnedRow key={row.id} row={row} table={table} />
+  ))}
+</tbody>
+```
+
+`getRowModel()` returns the complete current row model with pinned rows still in it. Use `getCenterRows()` for the main flow. Use `getRowModel()` only if you intentionally want pinned rows duplicated.
+
+Source: examples/react/row-pinning/src/main.tsx
+
+### [CRITICAL] Reimplementing pin behavior manually
+
+Wrong:
+
+```ts
+// Hand-rolled "pinned" map + manual filter on render
+const [pinned, setPinned] = useState<Record<string, true>>({})
+const pinnedRows = rows.filter((r) => pinned[r.id])
+const otherRows = rows.filter((r) => !pinned[r.id])
+```
+
+Correct:
+
+```ts
+const table = useTable({
+  features: tableFeatures({ rowPinningFeature }),
+  rowModels: {},
+  columns,
+  data,
+  getRowId: (row) => row.id,
+})
+
+row.pin('top') // pin one row
+table.setRowPinning({ top: ['a', 'b'], bottom: [] }) // bulk set
+table.getTopRows()
+table.getCenterRows()
+table.getBottomRows()
+```
+
+Source: maintainer interview (Phase 4, 2026-05-17)
+
+## See also
+
+- `tanstack-table/state-management` — `rowPinning` state slice ownership
+- `tanstack-table/row-selection` — same `getRowId` stability concern
+- `tanstack-table/column-layout` — column pinning sits in a separate, more complex pipeline