@tanstack/table-core 9.0.0-alpha.47 → 9.0.0-alpha.48

package/skills/column-definitions/SKILL.md

@@ -0,0 +1,333 @@
+---
+name: column-definitions
+description: >
+  Define TanStack Table v9 columns with `createColumnHelper<typeof _features, TData>()`.
+  Covers `columnHelper.accessor` (key + function forms), `columnHelper.display`,
+  `columnHelper.group`, `columnHelper.columns`, the `ColumnDef`/`AccessorKeyColumnDef`/
+  `AccessorFnColumnDef`/`DisplayColumnDef`/`GroupColumnDef` types, `accessorKey` with
+  `DeepKeys`, `accessorFn`, the `header`/`cell`/`footer`/`aggregatedCell` renderers,
+  required `id` rules, and `getRowId` for stable row identity.
+type: core
+library: tanstack-table
+library_version: '9.0.0-alpha.47'
+sources:
+  - TanStack/table:docs/guide/column-defs.md
+  - TanStack/table:docs/guide/columns.md
+  - TanStack/table:packages/table-core/src/helpers/columnHelper.ts
+  - TanStack/table:packages/table-core/src/core/columns/constructColumn.ts
+  - TanStack/table:examples/react/basic-use-table/src/main.tsx
+---
+
+## Setup
+
+`createColumnHelper` takes TWO generics in v9: the features type (so accessor keys, sort/filter strings, etc. are typed against your registered features) and the row data type.
+
+```ts
+import {
+  createColumnHelper,
+  tableFeatures,
+  rowSortingFeature,
+} from '@tanstack/table-core'
+
+type Person = {
+  id: string
+  firstName: string
+  lastName: string
+  age: number
+  visits: number
+}
+
+const _features = tableFeatures({ rowSortingFeature })
+
+// TFeatures FIRST, TData SECOND
+const columnHelper = createColumnHelper<typeof _features, Person>()
+
+const columns = columnHelper.columns([
+  // accessorKey — deep keys via DeepKeys (dot paths) are supported
+  columnHelper.accessor('firstName', { header: 'First Name' }),
+  columnHelper.accessor('lastName', { header: 'Last Name' }),
+  columnHelper.accessor('age', { header: 'Age' }),
+
+  // accessorFn — needs an explicit `id`
+  columnHelper.accessor((row) => `${row.firstName} ${row.lastName}`, {
+    id: 'fullName',
+    header: 'Full Name',
+    cell: (info) => info.getValue(),
+  }),
+
+  // display column — no value extraction, just rendering
+  columnHelper.display({
+    id: 'actions',
+    header: 'Actions',
+    cell: ({ row }) => `Edit ${row.original.id}`,
+  }),
+
+  // group column — wraps child columns under a shared header
+  columnHelper.group({
+    id: 'stats',
+    header: 'Stats',
+    columns: [columnHelper.accessor('visits', { header: 'Visits' })],
+  }),
+])
+```
+
+## Core Patterns
+
+### Stable row identity with `getRowId`
+
+```ts
+const table = useTable({
+  _features,
+  _rowModels: {},
+  columns,
+  data,
+  getRowId: (row) => row.id, // ← stable from row's own data
+})
+```
+
+Without `getRowId`, `row.id` defaults to the row's array index. Row-keyed state (selection, expansion, pinning) then attaches to whatever happens to be at that index after a sort/filter/refetch.
+
+### Accessor key with deep path
+
+```ts
+type User = { name: { first: string; last: string } }
+
+const columnHelper = createColumnHelper<typeof _features, User>()
+
+columnHelper.accessor('name.first', { header: 'First' })
+columnHelper.accessor('name.last', { header: 'Last' })
+```
+
+For nested objects with non-optional intermediate keys, the dotted `accessorKey` form works and infers the right value type. Switch to `accessorFn` when intermediates are optional (see Common Mistakes below).
+
+### Header / cell / footer renderers
+
+```ts
+columnHelper.accessor('age', {
+  header: () => 'Age',
+  cell: (info) => info.getValue(),
+  footer: (info) => `${info.table.getRowModel().rows.length} rows`,
+})
+```
+
+Renderers accept string, JSX (in framework adapters), or function forms. Render via `flexRender(def, ctx)` or `<table.FlexRender header={header} />` so all three forms work uniformly.
+
+### `columnHelper.columns([...])` for module-scope stability
+
+```ts
+// Outside any component / hook — stable reference forever
+const columns = columnHelper.columns([
+  columnHelper.accessor('firstName', { header: 'First' }),
+  columnHelper.accessor('lastName', { header: 'Last' }),
+])
+```
+
+`columnHelper.columns` returns the array as-is but preserves the precise tuple types. Hoist to module scope or wrap in `useMemo` — the table compares `columns` by reference.
+
+## Common Mistakes
+
+### [CRITICAL] Passing only `TData` to `createColumnHelper`
+
+Wrong:
+
+```ts
+// v8 signature — TData ends up in the TFeatures slot
+const columnHelper = createColumnHelper<Person>()
+```
+
+Correct:
+
+```ts
+const _features = tableFeatures({ rowSortingFeature })
+const columnHelper = createColumnHelper<typeof _features, Person>()
+```
+
+v9 changed the generic order: `<TFeatures, TData>`. The compiler error is noisy because `Person` lands in the `TFeatures` slot and breaks every column type that follows.
+
+Source: packages/table-core/src/helpers/columnHelper.ts; docs/framework/react/guide/migrating.md
+
+### [HIGH] Accessor function returns an object or array
+
+Wrong:
+
+```ts
+// returns an object — built-in alphanumeric sort and includesString filter break
+columnHelper.accessor((row) => row.name, {
+  id: 'name',
+  cell: (info) => `${info.getValue().first} ${info.getValue().last}`,
+})
+```
+
+Correct:
+
+```ts
+// accessor returns a primitive; cell can still format it
+columnHelper.accessor((row) => `${row.name.first} ${row.name.last}`, {
+  id: 'fullName',
+  cell: (info) => info.getValue(),
+})
+```
+
+The accessed value drives sorting, filtering, faceting, and grouping. Built-in `sortFn`/`filterFn`/`aggregationFn` expect a primitive `string` / `number` / `Date`. Return a primitive — or supply a matching custom function.
+
+Source: docs/guide/column-defs.md
+
+### [CRITICAL] Omitting `id` on an `accessorFn` column
+
+Wrong:
+
+```tsx
+// accessorFn + JSX header => no id can be derived
+columnHelper.accessor((row) => row.lastName, {
+  header: () => <span>Last Name</span>,
+  cell: (info) => info.getValue(),
+})
+```
+
+Correct:
+
+```tsx
+columnHelper.accessor((row) => row.lastName, {
+  id: 'lastName', // required when there's no string accessorKey or string header
+  header: () => <span>Last Name</span>,
+  cell: (info) => info.getValue(),
+})
+```
+
+The constructor throws "coreColumnsFeature require an id when using an accessorFn" in development. The same applies to non-string `header` values without a fallback `id`.
+
+Source: packages/table-core/src/core/columns/constructColumn.ts
+
+### [CRITICAL] Defining `columns` inside the component without `useMemo`
+
+Wrong:
+
+```tsx
+function MyTable() {
+  // new array reference every render → infinite render loop
+  const columns = [
+    columnHelper.accessor('firstName', { header: 'First' }),
+    columnHelper.accessor('lastName', { header: 'Last' }),
+  ]
+  const table = useTable({ _features, _rowModels: {}, columns, data })
+}
+```
+
+Correct:
+
+```tsx
+function MyTable() {
+  const columns = React.useMemo(
+    () =>
+      columnHelper.columns([
+        columnHelper.accessor('firstName', { header: 'First' }),
+        columnHelper.accessor('lastName', { header: 'Last' }),
+      ]),
+    [],
+  )
+  const table = useTable({ _features, _rowModels: {}, columns, data })
+}
+```
+
+TanStack Table compares `columns` and `data` by reference. The #1 FAQ entry across versions.
+
+Source: docs/faq.md; examples/react/basic-subscribe/src/main.tsx
+
+### [HIGH] Using array-index row IDs with mutating data
+
+Wrong:
+
+```ts
+// no getRowId — rowSelection survives data updates but maps to wrong rows
+const table = useTable({
+  _features,
+  _rowModels: {},
+  columns,
+  data,
+  enableRowSelection: true,
+})
+```
+
+Correct:
+
+```ts
+const table = useTable({
+  _features,
+  _rowModels: {},
+  columns,
+  data,
+  getRowId: (row) => row.id,
+  enableRowSelection: true,
+})
+```
+
+When `data` reorders, filters, or items are removed/refetched, row-keyed state (selection, expansion, pinning) attaches to the wrong row.
+
+Source: docs/guide/rows.md; packages/table-core/src/core/rows/coreRowsFeature.utils.ts
+
+### [MEDIUM] `accessorKey` with optional path strips `undefined` from `getValue` type
+
+Wrong:
+
+```ts
+// amount inferred as `number` even though salary is optional
+columnHelper.accessor('user.salary.amount', {
+  cell: (info) => {
+    const amount = info.getValue() // type: number (WRONG)
+    return amount.toFixed(2) // crashes when salary is undefined
+  },
+})
+```
+
+Correct:
+
+```ts
+columnHelper.accessor((row) => row.user.salary?.amount, {
+  id: 'salary',
+  cell: (info) => {
+    const amount = info.getValue() // type: number | undefined
+    return amount?.toFixed(2) ?? '-'
+  },
+})
+```
+
+The `DeepValue` type doesn't propagate `undefined` through optional intermediates. Use `accessorFn` when any segment is optional — the type follows the expression.
+
+Source: https://github.com/TanStack/table/issues/6238
+
+### [MEDIUM] `columnHelper.accessor` nested inside `columnHelper.group` loses `getValue` inference
+
+Wrong:
+
+```ts
+// info.getValue() inferred as unknown
+columnHelper.group({
+  id: 'name',
+  columns: [
+    columnHelper.accessor('firstName', {
+      cell: (info) => info.getValue(), // unknown
+    }),
+  ],
+})
+```
+
+Correct:
+
+```ts
+// Hoist accessor definitions out of the group
+const firstNameCol = columnHelper.accessor('firstName', {
+  cell: (info) => info.getValue(), // string
+})
+
+columnHelper.group({ id: 'name', columns: [firstNameCol] })
+```
+
+The group helper's overloads don't thread `TData` through correctly when accessors are defined inline.
+
+Source: https://github.com/TanStack/table/issues/5860
+
+## See also
+
+- `tanstack-table/setup` — how `_features` and `_rowModels` thread through `useTable`
+- `tanstack-table/customizing-feature-behavior` — per-column `sortFn`/`filterFn`/`aggregationFn`
+- `tanstack-table/row-selection` — why `getRowId` is essentially mandatory

package/skills/column-layout/SKILL.md

@@ -0,0 +1,328 @@
+---
+name: column-layout
+description: >
+  The five UI-state-only column features in TanStack Table v9 that shape how
+  columns render — visibility, ordering, pinning, sizing, resizing. None
+  require a row model. Covers `columnVisibilityFeature` (getVisibleLeafColumns,
+  row.getVisibleCells), `columnOrderingFeature` (columnOrder string[], column.getIndex),
+  `columnPinningFeature` (left/right ColumnPinningState, column.pin, column.getStart /
+  getAfter, split-table getLeft*/getCenter*/getRight* APIs, sticky-CSS pattern;
+  `enableColumnPinning` table-level option distinct from per-column `enablePinning`),
+  `columnSizingFeature` (defaultColumnSizing, column.getSize, table.getTotalSize),
+  `columnResizingFeature` (columnResizeMode 'onEnd'/'onChange', columnResizeDirection
+  'ltr'/'rtl', header.getResizeHandler for mouse + touch, CSS-variable
+  performant resize pattern). Pipeline: Column Pinning → columnOrder → Grouping.
+type: core
+library: tanstack-table
+library_version: '9.0.0-alpha.47'
+requires:
+  - state-management
+sources:
+  - TanStack/table:docs/guide/column-visibility.md
+  - TanStack/table:docs/guide/column-ordering.md
+  - TanStack/table:docs/guide/column-pinning.md
+  - TanStack/table:docs/guide/column-sizing.md
+  - TanStack/table:docs/guide/column-resizing.md
+  - TanStack/table:examples/react/column-visibility/src/main.tsx
+  - TanStack/table:examples/react/column-resizing/src/main.tsx
+  - TanStack/table:examples/react/column-resizing-performant/src/main.tsx
+  - TanStack/table:examples/react/column-pinning-split/src/main.tsx
+  - TanStack/table:examples/react/column-pinning-sticky/src/main.tsx
+  - TanStack/table:examples/react/column-dnd/src/main.tsx
+---
+
+This skill builds on `tanstack-table/state-management`. Read it first for the atom model — these are UI-state-only features (no row model).
+
+## Setup
+
+All five features are opt-in via `tableFeatures({...})`. The reorder pipeline is fixed: **(1) Column Pinning splits into left/center/right → (2) `columnOrder` reorders the center → (3) Grouping (`groupedColumnMode: 'reorder' | 'remove'`) may move grouped columns to the front.**
+
+```ts
+import {
+  tableFeatures,
+  columnVisibilityFeature,
+  columnOrderingFeature,
+  columnPinningFeature,
+  columnSizingFeature,
+  columnResizingFeature,
+  constructTable,
+} from '@tanstack/table-core'
+
+const _features = tableFeatures({
+  columnVisibilityFeature,
+  columnOrderingFeature,
+  columnPinningFeature,
+  columnSizingFeature,
+  columnResizingFeature, // explicit — formerly part of v8 ColumnSizing
+})
+
+const table = constructTable({
+  _features,
+  _rowModels: {}, // no row model needed for these features
+  columns,
+  data,
+  initialState: {
+    columnVisibility: {},
+    columnOrder: [],
+    columnPinning: { left: [], right: [] },
+    columnSizing: {},
+  },
+})
+```
+
+## Subsystems
+
+| Feature                   | State slice            | Key APIs                                             |
+| ------------------------- | ---------------------- | ---------------------------------------------------- |
+| `columnVisibilityFeature` | `columnVisibility`     | `column.toggleVisibility()`, `row.getVisibleCells()` |
+| `columnOrderingFeature`   | `columnOrder`          | `table.setColumnOrder()`, `column.getIndex()`        |
+| `columnPinningFeature`    | `columnPinning` (l/r)  | `column.pin()`, `column.getStart()`, `getAfter()`    |
+| `columnSizingFeature`     | `columnSizing`         | `column.getSize()`, `table.getTotalSize()`           |
+| `columnResizingFeature`   | (transient drag state) | `header.getResizeHandler()`, `columnResizeMode`      |
+
+Full API surface, render strategies, and additional MEDIUM-priority failure modes (reorder-pinned-via-columnOrder, react-dnd/react-beautiful-dnd avoidance, touch-resize handler) in [subsystems.md](references/subsystems.md).
+
+## Core Patterns
+
+### Performant `'onChange'` resize (React)
+
+```tsx
+// From examples/react/column-resizing-performant/src/main.tsx
+const columnSizeVars = React.useMemo(() => {
+  const headers = table.getFlatHeaders()
+  const colSizes: { [key: string]: number } = {}
+  for (const header of headers) {
+    colSizes[`--header-${header.id}-size`] = header.getSize()
+    colSizes[`--col-${header.column.id}-size`] = header.column.getSize()
+  }
+  return colSizes
+}, [table.state.columnResizing, table.state.columnSizing])
+
+<div className="divTable" style={{ ...columnSizeVars, width: table.getTotalSize() }}>
+  {table.store.state.columnResizing.isResizingColumn
+    ? <MemoizedTableBody table={table} />
+    : <TableBody table={table} />}
+</div>
+
+// Body cells use the CSS variable (no per-cell getSize() call)
+<div className="td" style={{ width: `calc(var(--col-${cell.column.id}-size) * 1px)` }}>
+  {cell.renderValue()}
+</div>
+
+export const MemoizedTableBody = React.memo(
+  TableBody,
+  (prev, next) => prev.table.options.data === next.table.options.data,
+)
+```
+
+## Common Mistakes
+
+### [HIGH] Rendering body cells with `row.getAllCells()` while visibility is registered
+
+Wrong:
+
+```tsx
+// Toggling visibility has no effect on rendered cells
+{
+  table.getAllLeafColumns().map((column) => <th key={column.id}>...</th>)
+}
+{
+  row.getAllCells().map((cell) => (
+    <td key={cell.id}>
+      <table.FlexRender cell={cell} />
+    </td>
+  ))
+}
+```
+
+Correct:
+
+```tsx
+// Header groups already respect visibility; use them for headers.
+// For body cells, swap getAllCells → getVisibleCells.
+<thead>
+  {table.getHeaderGroups().map((headerGroup) => (
+    <tr key={headerGroup.id}>
+      {headerGroup.headers.map((header) => (
+        <th key={header.id} colSpan={header.colSpan}>
+          {header.isPlaceholder ? null : <table.FlexRender header={header} />}
+        </th>
+      ))}
+    </tr>
+  ))}
+</thead>
+<tbody>
+  {table.getRowModel().rows.map((row) => (
+    <tr key={row.id}>
+      {row.getVisibleCells().map((cell) => (
+        <td key={cell.id}><table.FlexRender cell={cell} /></td>
+      ))}
+    </tr>
+  ))}
+</tbody>
+```
+
+The `getAll*` accessors do NOT consult `columnVisibility` state. Only `Visible` variants and header-group APIs filter by visibility.
+
+Source: docs/guide/column-visibility.md; examples/react/column-visibility/src/main.tsx
+
+### [HIGH] `columnResizeMode: 'onChange'` + `column.getSize()` per cell + un-memoized body
+
+Wrong:
+
+```tsx
+const table = useTable({
+  _features: tableFeatures({ columnSizingFeature, columnResizingFeature }),
+  columnResizeMode: 'onChange',
+})
+<td style={{ width: cell.column.getSize() }}>{cell.renderValue()}</td>
+```
+
+Correct:
+
+```tsx
+// See "Performant 'onChange' resize" above — CSS variables + memoized body
+const columnSizeVars = React.useMemo(() => {
+  /* … */
+}, [table.state.columnResizing, table.state.columnSizing])
+
+{
+  table.store.state.columnResizing.isResizingColumn ? (
+    <MemoizedTableBody table={table} />
+  ) : (
+    <TableBody table={table} />
+  )
+}
+
+;<div
+  className="td"
+  style={{ width: `calc(var(--col-${cell.column.id}-size) * 1px)` }}
+/>
+```
+
+`'onChange'` commits a new `columnSizing` map on every pointer move. Per-cell `getSize()` blows the 16ms frame budget. The CSS-variable pattern caches widths once per resize batch.
+
+Source: docs/guide/column-resizing.md; examples/react/column-resizing-performant/src/main.tsx
+
+### [HIGH] Using v8 `enablePinning` at the table level
+
+Wrong:
+
+```ts
+// v8 syntax — no longer disables pinning at table level in v9
+const table = useTable({
+  _features: tableFeatures({ columnPinningFeature }),
+  enablePinning: false, // ignored
+})
+```
+
+Correct:
+
+```ts
+// v9 split: two distinct table-level options
+const table = useTable({
+  _features: tableFeatures({ columnPinningFeature, rowPinningFeature }),
+  enableColumnPinning: false,
+  enableRowPinning: false,
+})
+
+// Per-column opt-out is still spelled `enablePinning`:
+columnHelper.accessor('id', {
+  enablePinning: false, // this column can't be pinned
+})
+```
+
+v9 split `enablePinning` into `enableColumnPinning` and `enableRowPinning`. The bare name now refers ONLY to per-column opt-out.
+
+Source: packages/table-core/src/features/column-pinning/columnPinningFeature.types.ts
+
+### [HIGH] Defining `columns` inline (infinite loop once a layout feature commits state)
+
+Wrong:
+
+```tsx
+function App() {
+  const columns = [
+    columnHelper.accessor('firstName', {
+      /* … */
+    }),
+    columnHelper.accessor('lastName', {
+      /* … */
+    }),
+  ]
+  const table = useTable({
+    _features: tableFeatures({ columnPinningFeature, columnResizingFeature }),
+    columns,
+    data,
+  })
+}
+```
+
+Correct:
+
+```tsx
+const defaultColumns = columnHelper.columns([
+  columnHelper.accessor('firstName', {
+    /* … */
+  }),
+  columnHelper.accessor('lastName', {
+    /* … */
+  }),
+])
+function App() {
+  const [columns] = React.useState(() => [...defaultColumns])
+  const table = useTable({ _features, columns, data })
+}
+
+// or: useMemo
+const columns = React.useMemo(
+  () =>
+    columnHelper.columns([
+      /* … */
+    ]),
+  [],
+)
+```
+
+Layout features commit state on every interaction. An inline `columns` array gets a new identity each render → table rebuild → another render. FAQ Pitfall 1.
+
+Source: docs/faq.md; examples/react/column-pinning-split/src/main.tsx; examples/react/column-dnd/src/main.tsx
+
+### [CRITICAL] Reimplementing visibility / pinning / resize logic manually
+
+Wrong:
+
+```ts
+// Hand-rolled hide/show with a separate set
+const [hidden, setHidden] = useState(new Set<string>())
+const visibleColumns = useMemo(
+  () => columns.filter((c) => !hidden.has(c.id)),
+  [columns, hidden],
+)
+```
+
+Correct:
+
+```ts
+const table = useTable({
+  _features: tableFeatures({ columnVisibilityFeature }),
+  _rowModels: {},
+  columns,
+  data,
+})
+column.toggleVisibility()
+column.getIsVisible()
+table.getVisibleLeafColumns()
+```
+
+Source: maintainer interview (Phase 4, 2026-05-17)
+
+## See also
+
+- `tanstack-table/state-management` — `state.columnVisibility` / `columnOrder` / `columnPinning` / `columnSizing` slices
+- `tanstack-table/row-pinning` — analogous pinning for rows (different render pipeline)
+- `tanstack-table/grouping` — `groupedColumnMode` interacts with `columnOrder`
+
+## References
+
+- [subsystems.md](references/subsystems.md) — full API surface per UI-state subsystem (visibility, ordering, pinning, sizing, resizing) plus MEDIUM-priority failure modes: reorder-pinned-via-`columnOrder`, react-dnd / react-beautiful-dnd avoidance, touch-resize handler