@tanstack/table-core 9.0.0-beta.7 → 9.0.0-beta.70

package/skills/core/SKILL.md

@@ -0,0 +1,175 @@
+---
+name: core
+description: >
+  Use TanStack Table v9 as a headless data-grid state and row-processing engine. Load for first-table architecture, stable data and columns, row numbering with getDisplayIndex, semantic rendering, framework adapter choice, or deciding what Table owns versus the renderer.
+metadata:
+  type: core
+  library: '@tanstack/table-core'
+  library_version: '9.0.0-beta.70'
+sources:
+  - 'TanStack/table:docs/overview.md'
+  - 'TanStack/table:docs/guide/tables.md'
+  - 'TanStack/table:docs/guide/data.md'
+  - 'TanStack/table:docs/guide/rows.md'
+  - 'TanStack/table:packages/table-core/src/index.ts'
+---
+
+# TanStack Table Core
+
+TanStack Table creates a table instance, state, and row models. It does not render a component, choose a component library, apply CSS, or supply interaction accessibility. Use a framework adapter in UI code; use `constructTable` only for framework-neutral integrations.
+
+## Setup
+
+<!-- skill-snippet:check -->
+
+```ts
+import {
+  constructTable,
+  createColumnHelper,
+  tableFeatures,
+} from '@tanstack/table-core'
+import { storeReactivityBindings } from '@tanstack/table-core/store-reactivity-bindings'
+
+type Person = { id: string; name: string }
+const features = tableFeatures({
+  coreReactivityFeature: storeReactivityBindings(),
+})
+const helper = createColumnHelper<typeof features, Person>()
+const columns = helper.columns([helper.accessor('name', { header: 'Name' })])
+const data: Person[] = [{ id: '1', name: 'Ada' }]
+const table = constructTable({
+  features,
+  columns,
+  data,
+  getRowId: (row) => row.id,
+})
+
+for (const row of table.getRowModel().rows) {
+  console.log(row.getAllCells().map((cell) => cell.getValue()))
+}
+```
+
+## Core Patterns
+
+### Start with core, add only behavior used
+
+```ts
+const features = tableFeatures({
+  coreReactivityFeature: storeReactivityBindings(),
+})
+```
+
+The core row model is automatic; filtering, sorting, pagination, and other optional behavior require their feature plugins.
+
+### Keep model inputs stable
+
+```ts
+const data: Person[] = [{ id: '1', name: 'Ada' }]
+const columns = helper.columns([helper.accessor('name', { header: 'Name' })])
+```
+
+Define static inputs once and preserve query/store references when data has not changed.
+
+### Number rows in current display order
+
+```ts
+const rowNumberColumn = helper.display({
+  id: 'rowNumber',
+  header: '#',
+  cell: ({ row }) => {
+    const displayIndex = row.getDisplayIndex()
+    return displayIndex === -1 ? '' : displayIndex + 1
+  },
+})
+```
+
+`row.getDisplayIndex()` follows the current filtering, grouping, sorting, and expansion order before pagination. `row.index` remains the row's creation-time position within its parent array.
+
+## Common Mistakes
+
+### [HIGH] Expecting Table to render a grid
+
+Wrong:
+
+```ts
+document.body.append(table as unknown as Node)
+```
+
+Correct:
+
+```ts
+const names = table
+  .getRowModel()
+  .rows.map((row) => row.getValue<string>('name'))
+document.body.textContent = names.join(', ')
+```
+
+The table instance is a model; markup, CSS, semantics, and accessibility are renderer responsibilities.
+
+Source: `docs/overview.md`
+
+### [HIGH] Recreating model inputs repeatedly
+
+Wrong:
+
+```ts
+const options = () => ({
+  data: source.map((item) => item),
+  columns: helper.columns([]),
+})
+```
+
+Correct:
+
+```ts
+const data = source.map((item) => item)
+const columns = helper.columns([])
+const options = () => ({ data, columns })
+```
+
+New references invalidate memoized row and column work and can create adapter render loops.
+
+Source: `docs/guide/data.md`
+
+### [HIGH] Detaching prototype-bound methods
+
+Wrong:
+
+```ts
+const { getValue } = table.getRowModel().rows[0]!
+getValue('name')
+```
+
+Correct:
+
+```ts
+const row = table.getRowModel().rows[0]!
+row.getValue('name')
+```
+
+V9 row, cell, column, and header methods use their instance as `this`.
+
+Source: `docs/framework/react/guide/migrating.md#instance-methods-must-be-called-on-their-instance`
+
+### [HIGH] Reading the display-index cache directly
+
+Wrong:
+
+```ts
+const rowNumber = row._displayIndexCache + 1
+```
+
+Correct:
+
+```ts
+const displayIndex = row.getDisplayIndex()
+const rowNumber = displayIndex === -1 ? undefined : displayIndex + 1
+```
+
+`_displayIndexCache` is internal and may be stale until display order is recomputed. The public method refreshes display order, validates that the cached slot still contains the row, and returns `-1` when it does not.
+
+Source: `docs/guide/rows.md#row-numbers-and-display-indexes`, `packages/table-core/src/core/rows/coreRowsFeature.utils.ts`
+
+## API Discovery
+
+Inspect `node_modules/@tanstack/table-core/dist/index.d.ts`, then follow the exported implementation. For UI creation and rendering, inspect `node_modules/@tanstack/<framework>-table/dist/index.d.ts` and load that adapter's getting-started skill.

package/skills/custom-features/SKILL.md

@@ -0,0 +1,235 @@
+---
+name: custom-features
+description: >
+  Author a TanStack Table v9 feature plugin across every FeatureMap and API installation surface: state, options, column definitions, table, column, row, cell, header, row-model functions/caches, defaults, prototypes, and table/row/column instance data lifecycles. Load for initTableInstanceData, resetTableInstanceData, constructTableAPIs, or reusable behavior not covered by built-ins, meta, or option composition.
+metadata:
+  type: sub-skill
+  library: '@tanstack/table-core'
+  library_version: '9.0.0-beta.70'
+requires: ['core', 'table-features', 'typescript']
+sources:
+  - 'TanStack/table:docs/framework/react/guide/custom-features.md'
+  - 'TanStack/table:packages/table-core/src/types'
+  - 'TanStack/table:packages/table-core/src/types/TableFeatures.ts'
+  - 'TanStack/table:packages/table-core/src/utils.ts'
+  - 'TanStack/table:packages/table-core/src/features'
+  - 'TanStack/table:examples/react/custom-plugin'
+---
+
+This skill builds on `core`, `table-features`, and `typescript`. Prefer a built-in feature or typed `tableMeta`/`columnMeta` for application callbacks; create a feature only for reusable state or behavior that must augment Table objects.
+
+## Extension Surface
+
+Declaration-merge `Plugins` to register the feature key, then merge only the maps backed by runtime behavior:
+
+| Feature map                                      | Contribution                              |
+| ------------------------------------------------ | ----------------------------------------- |
+| `TableState_FeatureMap`                          | State slices in options, atoms, and store |
+| `TableOptions_FeatureMap<TFeatures, TData>`      | Table options and change callbacks        |
+| `Table_FeatureMap<TFeatures, TData>`             | Public table APIs                         |
+| `ColumnDef_FeatureMap<TFeatures, TData, TValue>` | Column-definition options                 |
+| `Column_FeatureMap<TFeatures, TData>`            | Public column APIs/data                   |
+| `Row_FeatureMap<TFeatures, TData>`               | Public row APIs/data                      |
+| `Cell_FeatureMap`                                | Public cell APIs                          |
+| `Header_FeatureMap`                              | Public header APIs                        |
+| `RowModelFns_FeatureMap<TFeatures, TData>`       | Advanced `table._rowModelFns` registries  |
+| `CachedRowModels_FeatureMap<TFeatures, TData>`   | Advanced `table._rowModels` cache getters |
+
+`assignTableAPIs` installs singleton table methods. Use `assignPrototypeAPIs` inside `assignColumnPrototype`, `assignRowPrototype`, `assignCellPrototype`, or `assignHeaderPrototype` for shared object methods. Use `initColumnInstanceData` and `initRowInstanceData` only for per-instance fields.
+
+Use `initTableInstanceData` for mutable, non-reactive data owned by one table. It runs once after options, state atoms, and the store exist, and every feature initialization finishes before any `constructTableAPIs` hook runs. Use `resetTableInstanceData` to clear transient instance data after internal atoms reset during `table.reset()`; it does not own state slices or externally controlled state. Keep `constructTableAPIs` exclusively for method assignment.
+
+## Table Instance Lifecycle
+
+```ts
+import type { TableFeature } from '@tanstack/table-core'
+
+interface InteractionData {
+  _interactionHistory: Set<string>
+}
+
+const interactionData = (table: object): InteractionData =>
+  table as unknown as InteractionData
+
+export const interactionFeature: TableFeature = {
+  initTableInstanceData: (table) => {
+    interactionData(table)._interactionHistory = new Set()
+  },
+  resetTableInstanceData: (table) => {
+    interactionData(table)._interactionHistory.clear()
+  },
+}
+```
+
+Initialization may allocate resources once while reset clears their transient contents. Do not rerun initialization during `table.reset()`.
+
+## Complete Example
+
+This single example shows every ordinary FeatureMap and API installation path. It names the two advanced row-model maps without enabling them because density does not own the row-model pipeline.
+
+<!-- skill-snippet:check -->
+
+```ts
+import {
+  assignPrototypeAPIs,
+  assignTableAPIs,
+  functionalUpdate,
+  makeStateUpdater,
+  tableFeatures,
+  type CellData,
+  type OnChangeFn,
+  type RowData,
+  type TableFeature,
+  type TableFeatures,
+  type Updater,
+} from '@tanstack/table-core'
+
+type Density = 'sm' | 'md'
+interface DensityState {
+  density: Density
+}
+interface DensityOptions {
+  onDensityChange?: OnChangeFn<Density>
+}
+interface DensityColumnDef {
+  enableDensity?: boolean
+}
+interface DensityAPI {
+  getDensity: () => Density
+}
+interface DensityTable extends DensityAPI {
+  setDensity: (updater: Updater<Density>) => void
+}
+interface DensityColumn extends DensityAPI {
+  densityAtCreation?: Density
+}
+interface DensityRow extends DensityAPI {
+  densityAtCreation?: Density
+}
+type DensityCell = DensityAPI
+type DensityHeader = DensityAPI
+
+declare module '@tanstack/table-core' {
+  interface Plugins {
+    densityFeature: TableFeature
+  }
+  interface TableState_FeatureMap {
+    densityFeature: DensityState
+  }
+  interface TableOptions_FeatureMap<
+    TFeatures extends TableFeatures,
+    TData extends RowData,
+  > {
+    densityFeature: DensityOptions
+  }
+  interface Table_FeatureMap<
+    TFeatures extends TableFeatures,
+    TData extends RowData,
+  > {
+    densityFeature: DensityTable
+  }
+  interface ColumnDef_FeatureMap<
+    TFeatures extends TableFeatures,
+    TData extends RowData,
+    TValue extends CellData,
+  > {
+    densityFeature: DensityColumnDef
+  }
+  interface Column_FeatureMap<
+    TFeatures extends TableFeatures,
+    TData extends RowData,
+  > {
+    densityFeature: DensityColumn
+  }
+  interface Row_FeatureMap<
+    TFeatures extends TableFeatures,
+    TData extends RowData,
+  > {
+    densityFeature: DensityRow
+  }
+  interface Cell_FeatureMap {
+    densityFeature: DensityCell
+  }
+  interface Header_FeatureMap {
+    densityFeature: DensityHeader
+  }
+
+  // If this feature actually owned a row-model stage, it would also merge
+  // RowModelFns_FeatureMap and CachedRowModels_FeatureMap here, then populate
+  // table._rowModelFns/table._rowModels with matching runtime/cache wiring.
+}
+
+const readDensity = (table: unknown): Density =>
+  (
+    table as {
+      atoms: { density: { get: () => Density } }
+    }
+  ).atoms.density.get()
+
+export const densityFeature: TableFeature = {
+  getInitialState: (state) => ({ density: 'md', ...state }),
+  getDefaultTableOptions: (table) => ({
+    onDensityChange: makeStateUpdater('density', table),
+  }),
+  constructTableAPIs: (table) => {
+    assignTableAPIs('densityFeature', table, {
+      table_getDensity: { fn: () => readDensity(table) },
+      table_setDensity: {
+        fn: (updater: Updater<Density>) =>
+          (table.options as DensityOptions).onDensityChange?.((old) =>
+            functionalUpdate(updater, old),
+          ),
+      },
+    })
+  },
+  assignColumnPrototype: (prototype, table) => {
+    assignPrototypeAPIs('densityFeature', prototype, table, {
+      column_getDensity: { fn: (column) => readDensity(column.table) },
+    })
+  },
+  assignRowPrototype: (prototype, table) => {
+    assignPrototypeAPIs('densityFeature', prototype, table, {
+      row_getDensity: { fn: (row) => readDensity(row.table) },
+    })
+  },
+  assignCellPrototype: (prototype, table) => {
+    assignPrototypeAPIs('densityFeature', prototype, table, {
+      cell_getDensity: { fn: (cell) => readDensity(cell.table) },
+    })
+  },
+  assignHeaderPrototype: (prototype, table) => {
+    assignPrototypeAPIs('densityFeature', prototype, table, {
+      header_getDensity: { fn: (header) => readDensity(header.table) },
+    })
+  },
+  initColumnInstanceData: (column) => {
+    ;(column as unknown as DensityColumn).densityAtCreation = readDensity(
+      column.table,
+    )
+  },
+  initRowInstanceData: (row) => {
+    ;(row as unknown as DensityRow).densityAtCreation = readDensity(row.table)
+  },
+}
+
+export const features = tableFeatures({ densityFeature })
+```
+
+`getDefaultColumnDef` is also available for overridable column defaults; add it when the feature owns a real column-definition default. Do not add lifecycle hooks merely to fill the surface.
+
+## Guardrails
+
+- Keep the feature object and `tableFeatures({ densityFeature })` result stable.
+- Match every declaration-merged API with runtime installation. Types alone do nothing.
+- Preserve incoming state in `getInitialState`; put user state after defaults.
+- Method keys use `table_`, `column_`, `row_`, `cell_`, or `header_`; the prefix is removed on installation.
+- Table API `fn` receives declared arguments. Prototype API `fn` receives the current object first.
+- Initialize table-owned mutable data in `initTableInstanceData`, not `constructTableAPIs`; all feature data is initialized before any table API is assigned.
+- Clear transient table-owned data in `resetTableInstanceData`. Reset state slices through atoms/updaters, and do not expect this hook to reset externally controlled state.
+- Add `memoDeps` only for a genuinely derived method. Prototype methods are shared and must not close over per-object mutable data.
+- There are no `assignColumnAPIs`, `assignRowAPIs`, `assignCellAPIs`, or `assignHeaderAPIs`; use `assignPrototypeAPIs` in the matching hook.
+- Do not mutate constructed instances ad hoc or use a feature for renderer-only callbacks that belong in meta.
+
+## API Discovery
+
+Inspect exported `*_FeatureMap` interfaces under `node_modules/@tanstack/table-core/dist/types/`, `TableFeature` in `types/TableFeatures.d.ts`, and `assignTableAPIs`/`assignPrototypeAPIs` in `utils.d.ts`. Copy lifecycle shapes—not domain behavior—from the nearest stock feature under `dist/features/`.

package/skills/expanding/SKILL.md

@@ -0,0 +1,80 @@
+---
+name: expanding
+description: >
+  Expand hierarchical subrows or custom detail panels with rowExpandingFeature, expandedRowModel, getSubRows, getRowCanExpand, manualExpanding, and paginateExpandedRows. Load when expansion state changes but no UI appears.
+metadata:
+  {
+    type: sub-skill,
+    library: '@tanstack/table-core',
+    library_version: '9.0.0-beta.70',
+  }
+requires: ['core', 'table-features', 'client-vs-server']
+sources:
+  - 'TanStack/table:docs/framework/react/guide/expanding.md'
+  - 'TanStack/table:packages/table-core/src/features/row-expanding'
+  - 'TanStack/table:examples/react/expanding'
+---
+
+This skill builds on `core`, `table-features`, and `client-vs-server`. Expansion controls row-tree inclusion; the renderer owns disclosure controls and detail panels.
+
+## Setup
+
+```ts
+import {
+  createExpandedRowModel,
+  rowExpandingFeature,
+  tableFeatures,
+} from '@tanstack/table-core'
+
+type Node = { id: string; children?: Node[] }
+export const features = tableFeatures({
+  rowExpandingFeature,
+  expandedRowModel: createExpandedRowModel(),
+})
+export const options = { getSubRows: (row: Node) => row.children }
+```
+
+## Core Patterns
+
+```ts
+const detailOptions = { getRowCanExpand: () => true }
+const isDetailOpen = row.getIsExpanded()
+```
+
+For custom detail UI, render an additional row/panel when `isDetailOpen` is true.
+
+## Common Mistakes
+
+### [HIGH] Omitting the subrow accessor
+
+Wrong: `const options = { data: nestedRows }`
+
+Correct: `const options = { data: nestedRows, getSubRows: (row: Node) => row.children }`
+
+Nested object structure is not inferred automatically.
+
+Source: `docs/framework/react/guide/expanding.md#table-rows-as-expanded-data`
+
+### [HIGH] Expecting detail markup from state
+
+Wrong: `row.toggleExpanded(true)`
+
+Correct: `if (row.getIsExpanded()) renderDetail(row.original)`
+
+Table is headless and cannot render a custom detail panel.
+
+Source: `docs/framework/react/guide/expanding.md#custom-expanding-ui`
+
+### [HIGH] Misreading pagination placement
+
+Wrong: `const options = { paginateExpandedRows: false }; const leafOnlyPages = true`
+
+Correct: `const options = { paginateExpandedRows: false }; const descendantsStayWithParent = true`
+
+This option controls whether expansion happens before or after pagination; it does not make page size count only leaf rows.
+
+Source: `packages/table-core/src/features/row-expanding/rowExpandingFeature.types.ts`
+
+## API Discovery
+
+Inspect `node_modules/@tanstack/table-core/dist/features/row-expanding/` for expansion state, row APIs, and model placement.

package/skills/global-filtering/SKILL.md

@@ -0,0 +1,84 @@
+---
+name: global-filtering
+description: >
+  Apply globalFilter across eligible columns with globalFilteringFeature, columnFilteringFeature, filteredRowModel, globalFilterFn, and manual server filtering. Load when columns unexpectedly participate or a global filter changes state without changing rows.
+metadata:
+  {
+    type: sub-skill,
+    library: '@tanstack/table-core',
+    library_version: '9.0.0-beta.70',
+  }
+requires: ['core', 'table-features', 'client-vs-server', 'column-filtering']
+sources:
+  - 'TanStack/table:docs/framework/react/guide/global-filtering.md'
+  - 'TanStack/table:packages/table-core/src/features/global-filtering'
+  - 'TanStack/table:examples/react/filters'
+---
+
+This skill builds on `core`, `table-features`, `client-vs-server`, and `column-filtering`. Global filtering reuses the column-filtering pipeline.
+
+## Setup
+
+```ts
+import {
+  columnFilteringFeature,
+  createFilteredRowModel,
+  filterFn_includesString,
+  globalFilteringFeature,
+  tableFeatures,
+} from '@tanstack/table-core'
+
+export const features = tableFeatures({
+  columnFilteringFeature,
+  globalFilteringFeature,
+  filteredRowModel: createFilteredRowModel(),
+  filterFns: { includesString: filterFn_includesString },
+})
+```
+
+## Core Patterns
+
+```ts
+const options = {
+  globalFilterFn: 'includesString' as const,
+  getColumnCanGlobalFilter: (column) => column.id !== 'actions',
+}
+```
+
+Declare eligibility when product rules differ from default primitive-value detection.
+
+## Common Mistakes
+
+### [CRITICAL] Omitting column-filter prerequisite
+
+Wrong: `tableFeatures({ globalFilteringFeature })`
+
+Correct: `tableFeatures({ columnFilteringFeature, globalFilteringFeature, filteredRowModel: createFilteredRowModel() })`
+
+Global filtering depends on column filtering and needs the filtered model for client processing.
+
+Source: `packages/table-core/src/types/TableFeatures.ts#FeatureSlotPrereqs`
+
+### [HIGH] Assuming every column participates
+
+Wrong: `const options = { globalFilterFn: 'includesString' }`
+
+Correct: `const options = { getColumnCanGlobalFilter: column => column.id !== 'actions' }`
+
+Default eligibility uses the first core row and accepts string or number values.
+
+Source: `packages/table-core/src/features/global-filtering/globalFilteringFeature.ts`
+
+### [HIGH] Keeping manual filter local only
+
+Wrong: `table.setGlobalFilter(search); const options = { manualFiltering: true }`
+
+Correct: `const page = await fetchRows({ search }); const options = { data: page.rows, manualFiltering: true }`
+
+Manual filtering bypasses the client model, so the value must drive the server request.
+
+Source: `docs/framework/react/guide/global-filtering.md#manual-server-side-global-filtering`
+
+## API Discovery
+
+Inspect `node_modules/@tanstack/table-core/dist/features/global-filtering/` plus `dist/features/column-filtering/` for shared state and filter functions.