@tanstack/table-core 9.0.0-beta.5 → 9.0.0-beta.51

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.51'
+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/src/types/`, `TableFeature` in `types/TableFeatures.ts`, and `assignTableAPIs`/`assignPrototypeAPIs` in `utils.ts`. Copy lifecycle shapes—not domain behavior—from the nearest stock feature under `src/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.51',
+  }
+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/src/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.51',
+  }
+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/src/features/global-filtering/` plus `src/features/column-filtering/` for shared state and filter functions.