@tanstack/table-core 9.0.0-beta.37 → 9.0.0-beta.42

package/skills/row-pinning/SKILL.md

@@ -1,273 +1,82 @@
 ---
 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
+  Pin stable row IDs into top, center, and bottom collections with rowPinningFeature and keepPinnedRows. Load for filtering/pagination visibility, explicit region rendering, or renderer-owned sticky CSS.
+metadata:
+  {
+    type: sub-skill,
+    library: '@tanstack/table-core',
+    library_version: '9.0.0-beta.42',
+  }
+requires: ['core', 'table-features']
 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
+  - 'TanStack/table:docs/framework/react/guide/row-pinning.md'
+  - 'TanStack/table:packages/table-core/src/features/row-pinning'
+  - 'TanStack/table:examples/react/row-pinning'
 ---
 
-This skill builds on `tanstack-table/state-management`. Read it first for the atom model.
+This skill builds on `core` and `table-features`. Pinning creates row regions; the renderer controls order and sticky layout.
 
 ## Setup
 
 ```ts
-import {
-  tableFeatures,
-  rowPinningFeature,
-  rowPaginationFeature,
-  createPaginatedRowModel,
-  constructTable,
-} from '@tanstack/table-core'
-import type { RowPinningState } from '@tanstack/table-core'
-
-const features = tableFeatures({
-  rowPinningFeature,
-  rowPaginationFeature,
-  paginatedRowModel: createPaginatedRowModel(),
-})
-
-const table = constructTable({
-  features,
-  columns,
-  data,
-  getRowId: (row) => row.userId, // ← essentially mandatory
-  initialState: {
-    rowPinning: { top: [], bottom: [] } satisfies RowPinningState,
-  },
-})
-
-// Pin a row
-row.pin('top') // or 'bottom' | false
+import { rowPinningFeature, tableFeatures } from '@tanstack/table-core'
+
+type Person = { id: string; name: string }
+export const features = tableFeatures({ rowPinningFeature })
+export const options = {
+  getRowId: (row: Person) => row.id,
+  keepPinnedRows: true,
+}
 ```
 
 ## 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,
-    filteredRowModel: createFilteredRowModel(),
-    filterFns,
-  }),
-  columns,
-  data,
-  getRowId: (row) => row.id,
-  keepPinnedRows: false, // pinned rows disappear when filtered/paginated out
-})
+const regions = [
+  table.getTopRows(),
+  table.getCenterRows(),
+  table.getBottomRows(),
+]
+for (const rows of regions) rows.forEach(renderRow)
 ```
 
-`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
-})
-```
+Render each region explicitly if the visual order matters.
 
 ## 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)
+### [HIGH] Persisting index-based IDs
 
-Wrong:
+Wrong: `const options = { getRowId: (_row: Person, index: number) => String(index) }`
 
-```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: `const options = { getRowId: (row: Person) => row.id }`
 
-Correct:
+Indexes change under sorting, filtering, pagination, and insertion.
 
-```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>
-```
+Source: `docs/framework/react/guide/row-pinning.md`
 
-`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.
+### [HIGH] Expecting sticky rows automatically
 
-Source: examples/react/row-pinning/src/main.tsx
+Wrong: `row.pin('top')`
 
-### [CRITICAL] Reimplementing pin behavior manually
+Correct: `topRowElement.style.position = 'sticky'`
 
-Wrong:
+Pinning state does not style or place DOM elements.
 
-```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])
-```
+Source: `examples/react/row-pinning/src/main.tsx`
 
-Correct:
+## Choose the pinned-row visibility policy
 
-```ts
-const table = useTable({
-  features: tableFeatures({ rowPinningFeature }),
-  columns,
-  data,
-  getRowId: (row) => row.id,
-})
+- `keepPinnedRows: true` is the default. Pinned rows stay visible in their
+  pinned region even when filtering or pagination removes them from the center
+  row model.
+- `keepPinnedRows: false` limits pinned rows to those present in the current
+  filtered and paginated row model.
 
-row.pin('top') // pin one row
-table.setRowPinning({ top: ['a', 'b'], bottom: [] }) // bulk set
-table.getTopRows()
-table.getCenterRows()
-table.getBottomRows()
-```
+Choose explicitly based on product behavior; neither value is inherently wrong.
 
-Source: maintainer interview (Phase 4, 2026-05-17)
+Source: `packages/table-core/src/features/row-pinning/rowPinningFeature.types.ts`
 
-## See also
+## API Discovery
 
-- `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
+Inspect `node_modules/@tanstack/table-core/src/features/row-pinning/` for region getters, row APIs, and `keepPinnedRows` semantics.