@tanstack/table-core 9.0.0-beta.37 → 9.0.0-beta.42

package/src/features/column-sizing/columnSizingFeature.ts

@@ -14,8 +14,8 @@ import {
   header_getStart,
   table_getCenterTotalSize,
   table_getColumnOffsets,
-  table_getLeftTotalSize,
-  table_getRightTotalSize,
+  table_getEndTotalSize,
+  table_getStartTotalSize,
   table_getTotalSize,
   table_resetColumnSizing,
   table_setColumnSizing,
@@ -119,8 +119,8 @@ export const columnSizingFeature: TableFeature = {
           table.getHeaderGroups(),
         ],
       },
-      table_getLeftTotalSize: {
-        fn: () => table_getLeftTotalSize(table),
+      table_getStartTotalSize: {
+        fn: () => table_getStartTotalSize(table),
         memoDeps: () => [
           table.atoms.columnSizing?.get(),
           table.getHeaderGroups(),
@@ -133,8 +133,8 @@ export const columnSizingFeature: TableFeature = {
           table.getHeaderGroups(),
         ],
       },
-      table_getRightTotalSize: {
-        fn: () => table_getRightTotalSize(table),
+      table_getEndTotalSize: {
+        fn: () => table_getEndTotalSize(table),
         memoDeps: () => [
           table.atoms.columnSizing?.get(),
           table.getHeaderGroups(),

package/src/features/column-sizing/columnSizingFeature.types.ts

@@ -30,13 +30,19 @@ export interface ColumnOffsetsByPosition {
    */
   center: ColumnOffsets
   /**
-   * Offsets within the left pinned region.
+   * Offsets within the logical start pinned region.
+   *
+   * In LTR languages/layouts, start usually corresponds to left. In RTL
+   * languages/layouts, start usually corresponds to right.
    */
-  left: ColumnOffsets
+  start: ColumnOffsets
   /**
-   * Offsets within the right pinned region.
+   * Offsets within the logical end pinned region.
+   *
+   * In LTR languages/layouts, end usually corresponds to right. In RTL
+   * languages/layouts, end usually corresponds to left.
    */
-  right: ColumnOffsets
+  end: ColumnOffsets
 }
 
 export interface TableOptions_ColumnSizing {
@@ -66,13 +72,13 @@ export interface Table_ColumnSizing {
    */
   getColumnOffsets: () => ColumnOffsetsByPosition
   /**
-   * Sums the current sizes of visible left-pinned leaf columns.
+   * Sums the current sizes of visible logical start-pinned leaf columns.
    */
-  getLeftTotalSize: () => number
+  getStartTotalSize: () => number
   /**
-   * Sums the current sizes of visible right-pinned leaf columns.
+   * Sums the current sizes of visible logical end-pinned leaf columns.
    */
-  getRightTotalSize: () => number
+  getEndTotalSize: () => number
   /**
    * Sums the current sizes of all visible leaf columns.
    */
@@ -107,8 +113,8 @@ export interface Column_ColumnSizing {
   /**
    * Measures the offset from this column's end edge to the end of its region.
    *
-   * Pass a pinned region to measure within that region. The value is the sum
-   * of visible leaf column sizes after this column.
+   * Pass a pinned region to measure within that logical region. The value is
+   * the sum of visible leaf column sizes after this column.
    */
   getAfter: (position?: ColumnPinningPosition | 'center') => number
   /**
@@ -119,8 +125,8 @@ export interface Column_ColumnSizing {
    * Measures the offset from the start of this column's region to its start
    * edge.
    *
-   * Pass a pinned region to measure within that region. The value is the sum
-   * of visible leaf column sizes before this column.
+   * Pass a pinned region to measure within that logical region. The value is
+   * the sum of visible leaf column sizes before this column.
    */
   getStart: (position?: ColumnPinningPosition | 'center') => number
   /**

package/src/features/column-sizing/columnSizingFeature.utils.ts

@@ -1,8 +1,8 @@
 import {
   table_getCenterHeaderGroups,
-  table_getLeftHeaderGroups,
+  table_getEndHeaderGroups,
   table_getPinnedVisibleLeafColumns,
-  table_getRightHeaderGroups,
+  table_getStartHeaderGroups,
 } from '../column-pinning/columnPinningFeature.utils'
 import {
   callMemoOrStaticFn,
@@ -125,7 +125,7 @@ function buildColumnOffsets<
  * @example
  * ```ts
  * const offsets = table_getColumnOffsets(table)
- * const leftOffset = offsets.left.starts[column.id]
+ * const startOffset = offsets.start.starts[column.id]
  * ```
  */
 export function table_getColumnOffsets<
@@ -143,13 +143,13 @@ export function table_getColumnOffsets<
         Column_Internal<TFeatures, TData, unknown>
       >,
     ),
-    left: buildColumnOffsets(
-      table_getPinnedVisibleLeafColumns(table, 'left') as Array<
+    start: buildColumnOffsets(
+      table_getPinnedVisibleLeafColumns(table, 'start') as Array<
         Column_Internal<TFeatures, TData, unknown>
       >,
     ),
-    right: buildColumnOffsets(
-      table_getPinnedVisibleLeafColumns(table, 'right') as Array<
+    end: buildColumnOffsets(
+      table_getPinnedVisibleLeafColumns(table, 'end') as Array<
         Column_Internal<TFeatures, TData, unknown>
       >,
     ),
@@ -159,10 +159,10 @@ export function table_getColumnOffsets<
 function toOffsetsKey(
   position: ColumnPinningPosition | 'center' | undefined,
 ): keyof ColumnOffsetsByPosition {
-  return position === 'left'
-    ? 'left'
-    : position === 'right'
-      ? 'right'
+  return position === 'start'
+    ? 'start'
+    : position === 'end'
+      ? 'end'
       : position === 'center'
         ? 'center'
         : 'all' // undefined | false use the full visible list
@@ -172,11 +172,15 @@ function toOffsetsKey(
  * Computes the offset from the start edge of a pinning region to this column.
  *
  * The value is the sum of all previous visible leaf column sizes in the
- * requested `'left'`, `'center'`, or `'right'` region.
+ * requested `'start'`, `'center'`, or `'end'` region.
+ *
+ * `start` and `end` are logical positions. In LTR languages/layouts, `start`
+ * usually corresponds to left and `end` to right. In RTL languages/layouts,
+ * `start` usually corresponds to right and `end` to left.
  *
  * @example
  * ```ts
- * const leftOffset = column_getStart(column, 'left')
+ * const startOffset = column_getStart(column, 'start')
  * ```
  */
 export function column_getStart<
@@ -203,7 +207,7 @@ export function column_getStart<
  *
  * @example
  * ```ts
- * const rightOffset = column_getAfter(column, 'right')
+ * const endOffset = column_getAfter(column, 'end')
  * ```
  */
 export function column_getAfter<
@@ -364,7 +368,7 @@ export function table_resetColumnSizing<
 /**
  * Sums the rendered size of the full table header row.
  *
- * This includes left, center, and right columns in the main header group.
+ * This includes start, center, and end columns in the main header group.
  *
  * @example
  * ```ts
@@ -383,24 +387,24 @@ export function table_getTotalSize<
 }
 
 /**
- * Sums the rendered size of the left pinned header region.
+ * Sums the rendered size of the logical start pinned header region.
  *
- * An empty left pinning region returns `0`.
+ * An empty start pinning region returns `0`.
  *
  * @example
  * ```ts
- * const width = table_getLeftTotalSize(table)
+ * const width = table_getStartTotalSize(table)
  * ```
  */
-export function table_getLeftTotalSize<
+export function table_getStartTotalSize<
   TFeatures extends TableFeatures,
   TData extends RowData,
 >(table: Table_Internal<TFeatures, TData>) {
   return (
     callMemoOrStaticFn(
       table,
-      'getLeftHeaderGroups',
-      table_getLeftHeaderGroups,
+      'getStartHeaderGroups',
+      table_getStartHeaderGroups,
     )[0]?.headers.reduce((sum: number, header: Header<TFeatures, TData>) => {
       return sum + header_getSize(header)
     }, 0) ?? 0
@@ -433,24 +437,24 @@ export function table_getCenterTotalSize<
 }
 
 /**
- * Sums the rendered size of the right pinned header region.
+ * Sums the rendered size of the logical end pinned header region.
  *
- * An empty right pinning region returns `0`.
+ * An empty end pinning region returns `0`.
  *
  * @example
  * ```ts
- * const width = table_getRightTotalSize(table)
+ * const width = table_getEndTotalSize(table)
  * ```
  */
-export function table_getRightTotalSize<
+export function table_getEndTotalSize<
   TFeatures extends TableFeatures,
   TData extends RowData,
 >(table: Table_Internal<TFeatures, TData>) {
   return (
     callMemoOrStaticFn(
       table,
-      'getRightHeaderGroups',
-      table_getRightHeaderGroups,
+      'getEndHeaderGroups',
+      table_getEndHeaderGroups,
     )[0]?.headers.reduce((sum: number, header: Header<TFeatures, TData>) => {
       return sum + header_getSize(header)
     }, 0) ?? 0

package/src/features/column-visibility/columnVisibilityFeature.utils.ts

@@ -32,7 +32,7 @@ export function getDefaultColumnVisibilityState(): ColumnVisibilityState {
  * Updates this column's visibility when hiding is allowed.
  *
  * Passing `visible` stores that value. Omitting it flips the column's current
- * visibility state. Columns that cannot hide are left unchanged.
+ * visibility state. Columns that cannot hide are start unchanged.
  *
  * @example
  * ```ts
@@ -137,8 +137,8 @@ export function column_getToggleVisibilityHandler<
 /**
  * Collects the cells from this row whose columns are visible.
  *
- * When column pinning is active, the result is ordered as left-pinned cells,
- * center cells, then right-pinned cells.
+ * When column pinning is active, the result is ordered as start-pinned cells,
+ * center cells, then end-pinned cells.
  *
  * @example
  * ```ts
@@ -158,9 +158,9 @@ export function row_getVisibleCells<
     }
   }
 
-  const { left, right } =
+  const { start, end } =
     row.table.atoms.columnPinning?.get() ?? getDefaultColumnPinningState()
-  if (!left.length && !right.length) return visibleCells // no pinning, return early
+  if (!start.length && !end.length) return visibleCells // no pinning, return early
 
   const visibleCellsByColumnId = callMemoOrStaticFn(
     row,
@@ -168,16 +168,16 @@ export function row_getVisibleCells<
     row_getVisibleCellsByColumnId,
   )
 
-  const leftCells: Array<Cell<TFeatures, TData, unknown>> = []
-  for (let i = 0; i < left.length; i++) {
-    const cell = visibleCellsByColumnId[left[i]!]
-    if (cell) leftCells.push(cell)
+  const startCells: Array<Cell<TFeatures, TData, unknown>> = []
+  for (let i = 0; i < start.length; i++) {
+    const cell = visibleCellsByColumnId[start[i]!]
+    if (cell) startCells.push(cell)
   }
 
-  const rightCells: Array<Cell<TFeatures, TData, unknown>> = []
-  for (let i = 0; i < right.length; i++) {
-    const cell = visibleCellsByColumnId[right[i]!]
-    if (cell) rightCells.push(cell)
+  const endCells: Array<Cell<TFeatures, TData, unknown>> = []
+  for (let i = 0; i < end.length; i++) {
+    const cell = visibleCellsByColumnId[end[i]!]
+    if (cell) endCells.push(cell)
   }
 
   // Center cells: visible cells in natural column order, minus pinned ones.
@@ -185,10 +185,10 @@ export function row_getVisibleCells<
   for (let i = 0; i < visibleCells.length; i++) {
     const cell = visibleCells[i]!
     const id = cell.column.id
-    if (!left.includes(id) && !right.includes(id)) centerCells.push(cell)
+    if (!start.includes(id) && !end.includes(id)) centerCells.push(cell)
   }
 
-  return [...leftCells, ...centerCells, ...rightCells]
+  return [...startCells, ...centerCells, ...endCells]
 }
 
 /**

package/skills/column-definitions/SKILL.md

@@ -1,330 +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,
-  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, 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, 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,
-  columns,
-  data,
-  enableRowSelection: true,
-})
-```
-
-Correct:
-
-```ts
-const table = useTable({
-  features,
-  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` (with row model factory slots) threads through `useTable`
-- `tanstack-table/customizing-feature-behavior` — per-column `sortFn`/`filterFn`/`aggregationFn`
-- `tanstack-table/row-selection` — why `getRowId` is essentially mandatory