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

package/skills/column-filtering/SKILL.md

@@ -0,0 +1,87 @@
+---
+name: column-filtering
+description: >
+  Filter columns with columnFilteringFeature, filteredRowModel, filterFns, filterMeta, nested-row direction, and manualFiltering. Load for accessor compatibility, controlled filter updaters, fuzzy metadata, or client/server ownership.
+metadata:
+  {
+    type: sub-skill,
+    library: '@tanstack/table-core',
+    library_version: '9.0.0-beta.50',
+  }
+requires: ['core', 'table-features', 'client-vs-server']
+sources:
+  - 'TanStack/table:docs/framework/react/guide/column-filtering.md'
+  - 'TanStack/table:packages/table-core/src/features/column-filtering'
+  - 'TanStack/table:examples/react/filters'
+---
+
+This skill builds on `core`, `table-features`, and `client-vs-server`. Filtering state, row processing, and filter UI are separate concerns.
+
+## Setup
+
+```ts
+import {
+  columnFilteringFeature,
+  createFilteredRowModel,
+  filterFn_includesString,
+  tableFeatures,
+} from '@tanstack/table-core'
+
+export const features = tableFeatures({
+  columnFilteringFeature,
+  filteredRowModel: createFilteredRowModel(),
+  filterFns: { includesString: filterFn_includesString },
+})
+```
+
+Import individual `filterFn_*` built-ins and register only those your columns
+reference by string name or that `filterFn: 'auto'` should resolve for your
+data types. The full `filterFns` registry object still works but bundles every
+built-in.
+
+## Core Patterns
+
+```ts
+const options = {
+  filterFromLeafRows: true,
+  maxLeafRowFilterDepth: 2,
+}
+```
+
+Use leaf-first filtering only when a parent should survive because a descendant matches.
+
+## Common Mistakes
+
+### [HIGH] Combining manual and client filtering
+
+Wrong: `const options = { manualFiltering: true }`
+
+Correct: `const options = { manualFiltering: false }`
+
+Manual mode returns the pre-filtered model; send filter state to the server instead if it is `true`.
+
+Source: `packages/table-core/src/features/column-filtering/columnFilteringFeature.types.ts`
+
+### [HIGH] Filtering renderer output
+
+Wrong: `helper.accessor(row => ({ label: row.status }), { filterFn: 'includesString' })`
+
+Correct: `helper.accessor('status', { filterFn: 'includesString' })`
+
+Built-in string and numeric filters expect comparable accessor values, not objects or UI nodes.
+
+Source: `docs/framework/react/guide/column-filtering.md#filterfns`
+
+### [HIGH] Ignoring updater-function callbacks
+
+Wrong: `onColumnFiltersChange: value => { columnFilters = value as ColumnFiltersState }`
+
+Correct: `onColumnFiltersChange: updater => { columnFilters = functionalUpdate(updater, columnFilters) }`
+
+Controlled callbacks receive either a value or a function of previous state.
+
+Source: `packages/table-core/src/features/column-filtering/columnFilteringFeature.types.ts`
+
+## API Discovery
+
+Inspect `node_modules/@tanstack/table-core/src/features/column-filtering/` and `src/fns/filterFns.ts` for exact signatures and auto-remove behavior.

package/skills/column-ordering/SKILL.md

@@ -0,0 +1,75 @@
+---
+name: column-ordering
+description: >
+  Control TanStack Table v9 leaf columnOrder with stable IDs while accounting for pinning regions, visibility, and groupedColumnMode precedence. Load for drag-and-drop columns or rendered order that differs from state.
+metadata:
+  {
+    type: sub-skill,
+    library: '@tanstack/table-core',
+    library_version: '9.0.0-beta.50',
+  }
+requires: ['core', 'table-features']
+sources:
+  - 'TanStack/table:docs/framework/react/guide/column-ordering.md'
+  - 'TanStack/table:packages/table-core/src/features/column-ordering'
+  - 'TanStack/table:examples/react/column-dnd'
+---
+
+This skill builds on `core` and `table-features`. `columnOrder` orders unpinned leaf IDs; other plugins can still determine the final visual regions.
+
+## Setup
+
+```ts
+import { columnOrderingFeature, tableFeatures } from '@tanstack/table-core'
+
+export const features = tableFeatures({ columnOrderingFeature })
+export const initialState = { columnOrder: ['name', 'age', 'actions'] }
+```
+
+## Core Patterns
+
+```ts
+const next = columnOrder.filter((id) => id !== activeId)
+next.splice(next.indexOf(overId), 0, activeId)
+table.setColumnOrder(next)
+```
+
+Use column IDs as drag identities and replace the array.
+
+## Common Mistakes
+
+### [HIGH] Assuming state is final order
+
+Wrong: `renderIds(columnOrder)`
+
+Correct: `renderColumns(table.getAllLeafColumns())`
+
+Pinning regions and grouping mode apply after base ordering. If
+`columnVisibilityFeature` is also registered, render
+`table.getVisibleLeafColumns()` to apply visibility too.
+
+Source: `docs/framework/react/guide/column-ordering.md#what-affects-column-order`
+
+### [HIGH] Using labels as identities
+
+Wrong: `const activeId = column.columnDef.header as string`
+
+Correct: `const activeId = column.id`
+
+Headers can collide or change; ordering state stores stable leaf column IDs.
+
+Source: `packages/table-core/src/features/column-ordering/columnOrderingFeature.types.ts`
+
+### [HIGH] Mutating controlled state in place
+
+Wrong: `columnOrder.splice(0, 1); table.setColumnOrder(columnOrder)`
+
+Correct: `table.setColumnOrder(columnOrder.slice(1))`
+
+Reactive owners commonly require a new array reference.
+
+Source: `examples/react/column-dnd/src/main.tsx`
+
+## API Discovery
+
+Inspect `node_modules/@tanstack/table-core/src/features/column-ordering/`; combine with pinning/visibility skills when those plugins are registered.

package/skills/column-pinning/SKILL.md

@@ -0,0 +1,89 @@
+---
+name: column-pinning
+description: >
+  Pin columns into logical start, center, and end regions with columnPinningFeature and renderer-owned sticky CSS. Load for RTL offsets, z-index, backgrounds, overflow, widths, gaps, or overlaps.
+metadata:
+  {
+    type: sub-skill,
+    library: '@tanstack/table-core',
+    library_version: '9.0.0-beta.50',
+  }
+requires: ['core', 'table-features', 'column-sizing']
+sources:
+  - 'TanStack/table:docs/framework/react/guide/column-pinning.md'
+  - 'TanStack/table:packages/table-core/src/features/column-pinning'
+  - 'TanStack/table:examples/react/column-pinning-sticky'
+---
+
+This skill builds on `core`, `table-features`, and `column-sizing`. Pinning partitions models; CSS creates the sticky visual result.
+
+## Setup
+
+```ts
+import {
+  columnPinningFeature,
+  columnSizingFeature,
+  tableFeatures,
+} from '@tanstack/table-core'
+
+export const features = tableFeatures({
+  columnSizingFeature,
+  columnPinningFeature,
+})
+export const initialState = {
+  columnPinning: { start: ['name'], end: ['actions'] },
+}
+```
+
+## Core Patterns
+
+```ts
+const style = (column: Column<any, any>) => ({
+  position: column.getIsPinned() ? 'sticky' : 'relative',
+  insetInlineStart:
+    column.getIsPinned() === 'start'
+      ? `${column.getStart('start')}px`
+      : undefined,
+  insetInlineEnd:
+    column.getIsPinned() === 'end' ? `${column.getAfter('end')}px` : undefined,
+  width: `${column.getSize()}px`,
+  zIndex: column.getIsPinned() ? 1 : 0,
+  background: 'Canvas',
+})
+```
+
+## Common Mistakes
+
+### [HIGH] Using physical v8 regions
+
+Wrong: `column.pin('left')`
+
+Correct: `column.pin('start')`
+
+V9 uses logical `start` and `end`, including state and collection APIs.
+
+Source: `docs/framework/react/guide/migrating.md#column-pinning`
+
+### [HIGH] Expecting sticky CSS automatically
+
+Wrong: `column.pin('start')`
+
+Correct: `Object.assign(cell.style, style(column))`
+
+The feature only computes regions and offsets; the renderer owns positioning, backgrounds, overflow, and stacking.
+
+Source: `examples/react/column-pinning-sticky/src/main.tsx`
+
+### [HIGH] Diverging rendered and model widths
+
+Wrong: `cell.style.width = 'auto'`
+
+Correct: `cell.style.width = `${column.getSize()}px``
+
+Sticky offsets use numeric sizes, so mismatched DOM widths create gaps or overlaps.
+
+Source: `docs/framework/react/guide/column-pinning.md#useful-column-pinning-apis`
+
+## API Discovery
+
+Inspect `node_modules/@tanstack/table-core/src/features/column-pinning/`; use CSS logical properties for direction-aware rendering.

package/skills/column-resizing/SKILL.md

@@ -0,0 +1,91 @@
+---
+name: column-resizing
+description: >
+  Wire columnResizingFeature, header.getResizeHandler, resize mode and direction, pointer or touch events, and performant CSS-variable updates. Load when resize state changes but widths do not, or large tables resize slowly.
+metadata:
+  {
+    type: sub-skill,
+    library: '@tanstack/table-core',
+    library_version: '9.0.0-beta.50',
+  }
+requires: ['core', 'table-features', 'column-sizing']
+sources:
+  - 'TanStack/table:docs/framework/react/guide/column-resizing.md'
+  - 'TanStack/table:packages/table-core/src/features/column-resizing'
+  - 'TanStack/table:examples/react/column-resizing-performant'
+---
+
+This skill builds on `core`, `table-features`, and `column-sizing`. Resizing supplies gesture APIs and state; the renderer supplies handles and widths.
+
+## Setup
+
+```ts
+import {
+  columnResizingFeature,
+  columnSizingFeature,
+  tableFeatures,
+} from '@tanstack/table-core'
+
+export const features = tableFeatures({
+  columnSizingFeature,
+  columnResizingFeature,
+})
+export const options = {
+  columnResizeMode: 'onChange' as const,
+  columnResizeDirection: 'ltr' as const,
+}
+```
+
+## Core Patterns
+
+```ts
+const handler = header.getResizeHandler()
+handle.addEventListener('mousedown', handler)
+handle.addEventListener('touchstart', handler)
+```
+
+For large grids, compute all visible sizes once per update and expose them as CSS variables.
+
+## Common Mistakes
+
+### [CRITICAL] Omitting sizing prerequisite
+
+Wrong: `tableFeatures({ columnResizingFeature })`
+
+Correct: `tableFeatures({ columnSizingFeature, columnResizingFeature })`
+
+Resizing modifies the sizing state and requires `columnSizingFeature`.
+
+Source: `packages/table-core/src/types/TableFeatures.ts#FeatureSlotPrereqs`
+
+### [HIGH] Rendering an inert handle
+
+Wrong: `handle.addEventListener('pointerdown', header.getResizeHandler())`
+
+Correct:
+
+```ts
+const handler = header.getResizeHandler()
+handle.addEventListener('mousedown', handler)
+handle.addEventListener('touchstart', handler)
+```
+
+The shipped handler distinguishes `touchstart` from the mouse path. A single
+`pointerdown` listener does not provide working touch resizing; wire both mouse
+and touch start events.
+
+Source: `docs/framework/react/guide/column-resizing.md#connect-column-resizing-apis-to-ui`
+
+### [MEDIUM] Reading sizes in every cell
+
+Wrong: `cells.forEach(cell => cell.style.width = `${cell.column.getSize()}px`)`
+
+Correct: `root.style.setProperty(`--col-${header.id}`, `${header.getSize()}px`)`
+
+Caching sizes or CSS variables avoids repeated work during `onChange` resizing.
+
+Source: `examples/react/column-resizing-performant/src/main.tsx`
+
+## API Discovery
+
+Inspect `node_modules/@tanstack/table-core/src/features/column-resizing/` and the sizing feature directory for the state it updates.

package/skills/column-sizing/SKILL.md

@@ -0,0 +1,72 @@
+---
+name: column-sizing
+description: >
+  Use columnSizingFeature numeric size, minSize, maxSize, getSize, getStart, getAfter, and total-size APIs in table, grid, or flex CSS. Load for auto or percentage misconceptions and sizing/pinning layout mismatch.
+metadata:
+  {
+    type: sub-skill,
+    library: '@tanstack/table-core',
+    library_version: '9.0.0-beta.50',
+  }
+requires: ['core', 'table-features']
+sources:
+  - 'TanStack/table:docs/framework/react/guide/column-sizing.md'
+  - 'TanStack/table:packages/table-core/src/features/column-sizing'
+  - 'TanStack/table:examples/react/column-sizing'
+---
+
+This skill builds on `core` and `table-features`. Sizing is numeric state; translating it to layout is a renderer decision.
+
+## Setup
+
+```ts
+import { columnSizingFeature, tableFeatures } from '@tanstack/table-core'
+
+export const features = tableFeatures({ columnSizingFeature })
+export const defaultColumn = { size: 180, minSize: 80, maxSize: 480 }
+```
+
+## Core Patterns
+
+```ts
+cell.style.width = `${cell.column.getSize()}px`
+tableElement.style.width = `${table.getTotalSize()}px`
+```
+
+Apply the same model sizes consistently to headers, cells, and pinned offsets.
+
+## Common Mistakes
+
+### [HIGH] Expecting state to style DOM
+
+Wrong: `const options = { defaultColumn: { size: 180 } }`
+
+Correct: `cell.style.width = `${cell.column.getSize()}px``
+
+Numeric state does not apply CSS to headless markup.
+
+Source: `docs/framework/react/guide/column-sizing.md#column-size-apis`
+
+### [HIGH] Passing CSS sizes into numeric APIs
+
+Wrong: `const column = { size: '25%' }`
+
+Correct: `const column = { size: 240 }`
+
+Table sizing state is numeric; percentages and auto layout belong in renderer CSS.
+
+Source: `packages/table-core/src/features/column-sizing/columnSizingFeature.types.ts`
+
+### [HIGH] Letting content override offsets
+
+Wrong: `cell.style.minWidth = 'max-content'`
+
+Correct: `cell.style.width = `${column.getSize()}px`; cell.style.overflow = 'hidden'`
+
+If rendered width differs from the model, totals and pinning offsets no longer match geometry.
+
+Source: `examples/react/column-sizing/src/main.tsx`
+
+## API Discovery
+
+Inspect `node_modules/@tanstack/table-core/src/features/column-sizing/` for defaults and region-aware offset signatures.

package/skills/column-visibility/SKILL.md

@@ -0,0 +1,75 @@
+---
+name: column-visibility
+description: >
+  Hide columns with columnVisibilityFeature while rendering visibility-aware header, column, and cell collections. Load when hidden columns remain in the DOM, false-versus-absent state is confused, or enableHiding is misunderstood.
+metadata:
+  {
+    type: sub-skill,
+    library: '@tanstack/table-core',
+    library_version: '9.0.0-beta.50',
+  }
+requires: ['core', 'table-features']
+sources:
+  - 'TanStack/table:docs/framework/react/guide/column-visibility.md'
+  - 'TanStack/table:packages/table-core/src/features/column-visibility'
+  - 'TanStack/table:examples/react/column-visibility'
+---
+
+This skill builds on `core` and `table-features`. Visibility state changes visibility-aware models; it never removes the column definition.
+
+## Setup
+
+```ts
+import { columnVisibilityFeature, tableFeatures } from '@tanstack/table-core'
+
+export const features = tableFeatures({ columnVisibilityFeature })
+export const initialState = { columnVisibility: { internalId: false } }
+```
+
+## Core Patterns
+
+```ts
+const headers = table.getHeaderGroups()
+const cells = row.getVisibleCells()
+const toggles = table
+  .getAllLeafColumns()
+  .filter((column) => column.getCanHide())
+```
+
+Use all-column APIs for controls and visible APIs for rendered table content.
+
+## Common Mistakes
+
+### [HIGH] Rendering hidden cells anyway
+
+Wrong: `row.getAllCells().map(renderCell)`
+
+Correct: `row.getVisibleCells().map(renderCell)`
+
+All-cell APIs intentionally include hidden columns.
+
+Source: `docs/framework/react/guide/column-visibility.md#column-visibility-aware-table-apis`
+
+### [HIGH] Treating absence as hidden
+
+Wrong: `const hidden = !columnVisibility[column.id]`
+
+Correct: `const hidden = columnVisibility[column.id] === false`
+
+Only explicit `false` hides a column; an absent entry is visible.
+
+Source: `packages/table-core/src/features/column-visibility/columnVisibilityFeature.ts`
+
+### [MEDIUM] Treating enableHiding as visibility
+
+Wrong: `helper.accessor('id', { enableHiding: false })`
+
+Correct: `const initialState = { columnVisibility: { id: false } }`
+
+`enableHiding` controls whether hiding is allowed; visibility belongs in table state.
+
+Source: `packages/table-core/src/features/column-visibility/columnVisibilityFeature.types.ts`
+
+## API Discovery
+
+Inspect `node_modules/@tanstack/table-core/src/features/column-visibility/` for visibility-aware table, row, and column APIs.

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.50'
+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/src/index.ts`, then follow the exported implementation. For UI creation and rendering, inspect `node_modules/@tanstack/<framework>-table/src/index.ts` and load that adapter's getting-started skill.