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

package/skills/column-definitions/SKILL.md

@@ -1,333 +0,0 @@
----
-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.48'
-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

@@ -1,328 +0,0 @@
----
-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.48'
-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