@tanstack/table-core 9.0.0-beta.9 → 9.0.0

package/skills/column-faceting/SKILL.md

@@ -0,0 +1,93 @@
+---
+name: column-faceting
+description: >
+  Build faceted filter UIs with columnFacetingFeature, facetedRowModel, facetedUniqueValues, and facetedMinMaxValues. Load for facet counts, numeric ranges, own-filter exclusion, or server-page facet completeness.
+metadata:
+  { type: sub-skill, library: '@tanstack/table-core', library_version: '9.0.0' }
+requires: ['core', 'table-features', 'column-filtering']
+sources:
+  - 'TanStack/table:docs/framework/react/guide/column-faceting.md'
+  - 'TanStack/table:packages/table-core/src/features/column-faceting'
+  - 'TanStack/table:examples/react/filters-faceted'
+---
+
+This skill builds on `core`, `table-features`, and `column-filtering`. Faceting derives filter choices; it does not render controls.
+
+## Setup
+
+```ts
+import {
+  columnFacetingFeature,
+  columnFilteringFeature,
+  createFacetedMinMaxValues,
+  createFacetedRowModel,
+  createFacetedUniqueValues,
+  createFilteredRowModel,
+  filterFn_includesString,
+  filterFn_inNumberRange,
+  tableFeatures,
+} from '@tanstack/table-core'
+
+export const features = tableFeatures({
+  columnFilteringFeature,
+  filteredRowModel: createFilteredRowModel(),
+  filterFns: {
+    includesString: filterFn_includesString,
+    inNumberRange: filterFn_inNumberRange,
+  },
+  columnFacetingFeature,
+  facetedRowModel: createFacetedRowModel(),
+  facetedUniqueValues: createFacetedUniqueValues(),
+  facetedMinMaxValues: createFacetedMinMaxValues(),
+})
+```
+
+## Core Patterns
+
+```ts
+const counts = table.getColumn('status')?.getFacetedUniqueValues() ?? new Map()
+const range = table.getColumn('age')?.getFacetedMinMaxValues()
+```
+
+Use unique values for discrete controls and min/max only for numeric ranges.
+The filtered model makes facets respond to the table's other active filters.
+Register individually imported built-ins under their conventional keys so
+columns can reference them by string name; a column may instead receive a
+filter function directly without registering it. The full `filterFns` registry
+object still works but bundles every built-in.
+
+## Common Mistakes
+
+### [HIGH] Registering APIs without model slots
+
+Wrong: `tableFeatures({ columnFilteringFeature, columnFacetingFeature })`
+
+Correct: `tableFeatures({ columnFilteringFeature, columnFacetingFeature, facetedRowModel: createFacetedRowModel(), facetedUniqueValues: createFacetedUniqueValues() })`
+
+Each faceting getter needs its matching factory slot.
+
+Source: `packages/table-core/src/features/column-faceting/columnFacetingFeature.ts`
+
+### [MEDIUM] Expecting facet to apply itself
+
+Wrong: `column.getFacetedUniqueValues().get(activeValue) === 0`
+
+Correct: `column.getFacetedUniqueValues().get(activeValue) ?? 0`
+
+A column facet intentionally excludes that column's own filter while applying other filters.
+
+Source: `docs/framework/react/guide/column-faceting.md`
+
+### [HIGH] Treating page facets as global
+
+Wrong: `const globalCounts = column.getFacetedUniqueValues()`
+
+Correct: `const globalCounts = await fetchFacetCounts(activeFilters)`
+
+With server pagination, client faceting sees only loaded data.
+
+Source: `docs/framework/react/guide/column-faceting.md#custom-server-side-faceting`
+
+## API Discovery
+
+Inspect `node_modules/@tanstack/table-core/dist/features/column-faceting/` for exact getters and factory return types.

package/skills/column-filtering/SKILL.md

@@ -0,0 +1,83 @@
+---
+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' }
+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/dist/features/column-filtering/` and `dist/features/column-filtering/filterFns.d.ts` for exact signatures and auto-remove behavior.

package/skills/column-ordering/SKILL.md

@@ -0,0 +1,71 @@
+---
+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' }
+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/dist/features/column-ordering/`; combine with pinning/visibility skills when those plugins are registered.

package/skills/column-pinning/SKILL.md

@@ -0,0 +1,85 @@
+---
+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' }
+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/dist/features/column-pinning/`; use CSS logical properties for direction-aware rendering.

package/skills/column-resizing/SKILL.md

@@ -0,0 +1,87 @@
+---
+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' }
+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/dist/features/column-resizing/` and the sizing feature directory for the state it updates.

package/skills/column-sizing/SKILL.md

@@ -0,0 +1,68 @@
+---
+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' }
+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/dist/features/column-sizing/` for defaults and region-aware offset signatures.

package/skills/column-visibility/SKILL.md

@@ -0,0 +1,71 @@
+---
+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' }
+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/dist/features/column-visibility/` for visibility-aware table, row, and column APIs.