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

package/src/features/column-ordering/columnOrderingFeature.utils.ts

@@ -1,12 +1,15 @@
 import { table_getPinnedVisibleLeafColumns } from '../column-pinning/columnPinningFeature.utils'
-import { cloneState } from '../../utils'
+import { callMemoOrStaticFn, cloneState, makeObjectMap } from '../../utils'
 import type { GroupingState } from '../column-grouping/columnGroupingFeature.types'
 import type { CellData, RowData, Updater } from '../../types/type-utils'
 import type { TableFeatures } from '../../types/TableFeatures'
 import type { Table_Internal } from '../../types/Table'
-import type { Column_Internal } from '../../types/Column'
+import type { Column, Column_Internal } from '../../types/Column'
 import type { ColumnPinningPosition } from '../column-pinning/columnPinningFeature.types'
-import type { ColumnOrderState } from './columnOrderingFeature.types'
+import type {
+  ColumnIndexes,
+  ColumnOrderState,
+} from './columnOrderingFeature.types'
 
 /**
  * Creates the default column order state.
@@ -23,10 +26,46 @@ export function getDefaultColumnOrderState(): ColumnOrderState {
   return []
 }
 
+/**
+ * Builds column-id to index records for each visible pinning region.
+ *
+ * All four regions are built in one pass so a single memo entry serves every
+ * `column_getIndex` lookup without per-column scans.
+ *
+ * @example
+ * ```ts
+ * const indexes = table_getColumnIndexes(table)
+ * ```
+ */
+export function table_getColumnIndexes<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+>(table: Table_Internal<TFeatures, TData>): ColumnIndexes {
+  const buildIndexes = (
+    columns: ReadonlyArray<
+      | Column<TFeatures, TData, unknown>
+      | Column_Internal<TFeatures, TData, unknown>
+    >,
+  ): Record<string, number> => {
+    const indexes = makeObjectMap<number>()
+    for (let i = 0; i < columns.length; i++) {
+      indexes[columns[i]!.id] = i
+    }
+    return indexes
+  }
+
+  return {
+    all: buildIndexes(table_getPinnedVisibleLeafColumns(table)),
+    center: buildIndexes(table_getPinnedVisibleLeafColumns(table, 'center')),
+    start: buildIndexes(table_getPinnedVisibleLeafColumns(table, 'start')),
+    end: buildIndexes(table_getPinnedVisibleLeafColumns(table, 'end')),
+  }
+}
+
 /**
  * Finds this column's index within a visible pinning region.
  *
- * Pass `'left'`, `'center'`, or `'right'` to search that region; omit the
+ * Pass `'start'`, `'center'`, or `'end'` to search that region; omit the
  * position to search the full visible leaf column list.
  *
  * @example
@@ -42,8 +81,20 @@ export function column_getIndex<
   column: Column_Internal<TFeatures, TData, TValue>,
   position?: ColumnPinningPosition | 'center',
 ) {
-  const columns = table_getPinnedVisibleLeafColumns(column.table, position)
-  return columns.findIndex((d) => d.id === column.id)
+  const indexes = callMemoOrStaticFn(
+    column.table,
+    'getColumnIndexes',
+    table_getColumnIndexes,
+  )
+  const key =
+    position === 'start'
+      ? 'start'
+      : position === 'end'
+        ? 'end'
+        : position === 'center'
+          ? 'center'
+          : 'all'
+  return indexes[key][column.id] ?? -1
 }
 
 /**
@@ -53,7 +104,7 @@ export function column_getIndex<
  *
  * @example
  * ```ts
- * const isFirst = column_getIsFirstColumn(column, 'left')
+ * const isFirst = column_getIsFirstColumn(column, 'start')
  * ```
  */
 export function column_getIsFirstColumn<
@@ -75,7 +126,7 @@ export function column_getIsFirstColumn<
  *
  * @example
  * ```ts
- * const isLast = column_getIsLastColumn(column, 'right')
+ * const isLast = column_getIsLastColumn(column, 'end')
  * ```
  */
 export function column_getIsLastColumn<

package/src/features/column-pinning/columnPinningFeature.ts

@@ -12,36 +12,41 @@ import {
   column_pin,
   getDefaultColumnPinningState,
   row_getCenterVisibleCells,
-  row_getLeftVisibleCells,
-  row_getRightVisibleCells,
+  row_getEndVisibleCells,
+  row_getStartVisibleCells,
   table_getCenterFlatHeaders,
   table_getCenterFooterGroups,
   table_getCenterHeaderGroups,
   table_getCenterLeafColumns,
   table_getCenterLeafHeaders,
   table_getCenterVisibleLeafColumns,
+  table_getEndFlatHeaders,
+  table_getEndFooterGroups,
+  table_getEndHeaderGroups,
+  table_getEndLeafColumns,
+  table_getEndLeafHeaders,
+  table_getEndVisibleLeafColumns,
   table_getIsSomeColumnsPinned,
-  table_getLeftFlatHeaders,
-  table_getLeftFooterGroups,
-  table_getLeftHeaderGroups,
-  table_getLeftLeafColumns,
-  table_getLeftLeafHeaders,
-  table_getLeftVisibleLeafColumns,
   table_getPinnedLeafColumns,
   table_getPinnedVisibleLeafColumns,
-  table_getRightFlatHeaders,
-  table_getRightFooterGroups,
-  table_getRightHeaderGroups,
-  table_getRightLeafColumns,
-  table_getRightLeafHeaders,
-  table_getRightVisibleLeafColumns,
+  table_getStartFlatHeaders,
+  table_getStartFooterGroups,
+  table_getStartHeaderGroups,
+  table_getStartLeafColumns,
+  table_getStartLeafHeaders,
+  table_getStartVisibleLeafColumns,
   table_resetColumnPinning,
   table_setColumnPinning,
 } from './columnPinningFeature.utils'
 import type { TableFeature } from '../../types/TableFeatures'
 
 /**
- * Feature that adds column pinning state and APIs for left, center, and right regions.
+ * Feature that adds column pinning state and APIs for logical start, center,
+ * and end regions.
+ *
+ * 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.
  */
 export const columnPinningFeature: TableFeature = {
   getInitialState: (initialState) => {
@@ -87,19 +92,19 @@ export const columnPinningFeature: TableFeature = {
           row.table.atoms.columnVisibility?.get(),
         ],
       },
-      row_getLeftVisibleCells: {
-        fn: (row) => row_getLeftVisibleCells(row),
+      row_getStartVisibleCells: {
+        fn: (row) => row_getStartVisibleCells(row),
         memoDeps: (row) => [
           row.getAllCells(),
-          row.table.atoms.columnPinning?.get()?.left,
+          row.table.atoms.columnPinning?.get()?.start,
           row.table.atoms.columnVisibility?.get(),
         ],
       },
-      row_getRightVisibleCells: {
-        fn: (row) => row_getRightVisibleCells(row),
+      row_getEndVisibleCells: {
+        fn: (row) => row_getEndVisibleCells(row),
         memoDeps: (row) => [
           row.getAllCells(),
-          row.table.atoms.columnPinning?.get()?.right,
+          row.table.atoms.columnPinning?.get()?.end,
           row.table.atoms.columnVisibility?.get(),
         ],
       },
@@ -118,8 +123,8 @@ export const columnPinningFeature: TableFeature = {
         fn: (position) => table_getIsSomeColumnsPinned(table, position),
       },
       // header groups
-      table_getLeftHeaderGroups: {
-        fn: () => table_getLeftHeaderGroups(table),
+      table_getStartHeaderGroups: {
+        fn: () => table_getStartHeaderGroups(table),
         memoDeps: () => [
           table.getAllColumns(),
           callMemoOrStaticFn(
@@ -127,7 +132,7 @@ export const columnPinningFeature: TableFeature = {
             'getVisibleLeafColumns',
             table_getVisibleLeafColumns,
           ),
-          table.atoms.columnPinning?.get()?.left,
+          table.atoms.columnPinning?.get()?.start,
           table.atoms.columnOrder?.get(),
         ],
       },
@@ -144,8 +149,8 @@ export const columnPinningFeature: TableFeature = {
           table.atoms.columnOrder?.get(),
         ],
       },
-      table_getRightHeaderGroups: {
-        fn: () => table_getRightHeaderGroups(table),
+      table_getEndHeaderGroups: {
+        fn: () => table_getEndHeaderGroups(table),
         memoDeps: () => [
           table.getAllColumns(),
           callMemoOrStaticFn(
@@ -153,18 +158,18 @@ export const columnPinningFeature: TableFeature = {
             'getVisibleLeafColumns',
             table_getVisibleLeafColumns,
           ),
-          table.atoms.columnPinning?.get()?.right,
+          table.atoms.columnPinning?.get()?.end,
           table.atoms.columnOrder?.get(),
         ],
       },
       // footer groups
-      table_getLeftFooterGroups: {
-        fn: () => table_getLeftFooterGroups(table),
+      table_getStartFooterGroups: {
+        fn: () => table_getStartFooterGroups(table),
         memoDeps: () => [
           callMemoOrStaticFn(
             table,
-            'getLeftHeaderGroups',
-            table_getLeftHeaderGroups,
+            'getStartHeaderGroups',
+            table_getStartHeaderGroups,
           ),
         ],
       },
@@ -178,34 +183,34 @@ export const columnPinningFeature: TableFeature = {
           ),
         ],
       },
-      table_getRightFooterGroups: {
-        fn: () => table_getRightFooterGroups(table),
+      table_getEndFooterGroups: {
+        fn: () => table_getEndFooterGroups(table),
         memoDeps: () => [
           callMemoOrStaticFn(
             table,
-            'getRightHeaderGroups',
-            table_getRightHeaderGroups,
+            'getEndHeaderGroups',
+            table_getEndHeaderGroups,
           ),
         ],
       },
       // flat headers
-      table_getLeftFlatHeaders: {
-        fn: () => table_getLeftFlatHeaders(table),
+      table_getStartFlatHeaders: {
+        fn: () => table_getStartFlatHeaders(table),
         memoDeps: () => [
           callMemoOrStaticFn(
             table,
-            'getLeftHeaderGroups',
-            table_getLeftHeaderGroups,
+            'getStartHeaderGroups',
+            table_getStartHeaderGroups,
           ),
         ],
       },
-      table_getRightFlatHeaders: {
-        fn: () => table_getRightFlatHeaders(table),
+      table_getEndFlatHeaders: {
+        fn: () => table_getEndFlatHeaders(table),
         memoDeps: () => [
           callMemoOrStaticFn(
             table,
-            'getRightHeaderGroups',
-            table_getRightHeaderGroups,
+            'getEndHeaderGroups',
+            table_getEndHeaderGroups,
           ),
         ],
       },
@@ -220,23 +225,23 @@ export const columnPinningFeature: TableFeature = {
         ],
       },
       // leaf headers
-      table_getLeftLeafHeaders: {
-        fn: () => table_getLeftLeafHeaders(table),
+      table_getStartLeafHeaders: {
+        fn: () => table_getStartLeafHeaders(table),
         memoDeps: () => [
           callMemoOrStaticFn(
             table,
-            'getLeftHeaderGroups',
-            table_getLeftHeaderGroups,
+            'getStartHeaderGroups',
+            table_getStartHeaderGroups,
           ),
         ],
       },
-      table_getRightLeafHeaders: {
-        fn: () => table_getRightLeafHeaders(table),
+      table_getEndLeafHeaders: {
+        fn: () => table_getEndLeafHeaders(table),
         memoDeps: () => [
           callMemoOrStaticFn(
             table,
-            'getRightHeaderGroups',
-            table_getRightHeaderGroups,
+            'getEndHeaderGroups',
+            table_getEndHeaderGroups,
           ),
         ],
       },
@@ -251,20 +256,24 @@ export const columnPinningFeature: TableFeature = {
         ],
       },
       // leaf columns
-      table_getLeftLeafColumns: {
-        fn: () => table_getLeftLeafColumns(table),
+      table_getStartLeafColumns: {
+        fn: () => table_getStartLeafColumns(table),
         memoDeps: () => [
           table.options.columns,
           table.atoms.columnPinning?.get(),
           table.atoms.columnOrder?.get(),
+          table.atoms.grouping?.get(),
+          table.options.groupedColumnMode,
         ],
       },
-      table_getRightLeafColumns: {
-        fn: () => table_getRightLeafColumns(table),
+      table_getEndLeafColumns: {
+        fn: () => table_getEndLeafColumns(table),
         memoDeps: () => [
           table.options.columns,
           table.atoms.columnPinning?.get(),
           table.atoms.columnOrder?.get(),
+          table.atoms.grouping?.get(),
+          table.options.groupedColumnMode,
         ],
       },
       table_getCenterLeafColumns: {
@@ -273,6 +282,8 @@ export const columnPinningFeature: TableFeature = {
           table.options.columns,
           table.atoms.columnPinning?.get(),
           table.atoms.columnOrder?.get(),
+          table.atoms.grouping?.get(),
+          table.options.groupedColumnMode,
         ],
       },
       table_getPinnedLeafColumns: {
@@ -280,13 +291,15 @@ export const columnPinningFeature: TableFeature = {
         // must not memo here as it's just a shortcut function
       },
       // visible leaf columns
-      table_getLeftVisibleLeafColumns: {
-        fn: () => table_getLeftVisibleLeafColumns(table),
+      table_getStartVisibleLeafColumns: {
+        fn: () => table_getStartVisibleLeafColumns(table),
         memoDeps: () => [
           table.options.columns,
           table.atoms.columnPinning?.get(),
           table.atoms.columnVisibility?.get(),
           table.atoms.columnOrder?.get(),
+          table.atoms.grouping?.get(),
+          table.options.groupedColumnMode,
         ],
       },
       table_getCenterVisibleLeafColumns: {
@@ -296,15 +309,19 @@ export const columnPinningFeature: TableFeature = {
           table.atoms.columnPinning?.get(),
           table.atoms.columnVisibility?.get(),
           table.atoms.columnOrder?.get(),
+          table.atoms.grouping?.get(),
+          table.options.groupedColumnMode,
         ],
       },
-      table_getRightVisibleLeafColumns: {
-        fn: () => table_getRightVisibleLeafColumns(table),
+      table_getEndVisibleLeafColumns: {
+        fn: () => table_getEndVisibleLeafColumns(table),
         memoDeps: () => [
           table.options.columns,
           table.atoms.columnPinning?.get(),
           table.atoms.columnVisibility?.get(),
           table.atoms.columnOrder?.get(),
+          table.atoms.grouping?.get(),
+          table.options.groupedColumnMode,
         ],
       },
       table_getPinnedVisibleLeafColumns: {

package/src/features/column-pinning/columnPinningFeature.types.ts

@@ -5,11 +5,18 @@ import type { Header } from '../../types/Header'
 import type { HeaderGroup } from '../../types/HeaderGroup'
 import type { Column } from '../../types/Column'
 
-export type ColumnPinningPosition = false | 'left' | 'right'
+/**
+ * Logical column pinning region.
+ *
+ * In LTR languages/layouts, `start` usually corresponds to left and `end`
+ * usually corresponds to right. In RTL languages/layouts, `start` usually
+ * corresponds to right and `end` usually corresponds to left.
+ */
+export type ColumnPinningPosition = false | 'start' | 'end'
 
 export interface ColumnPinningState {
-  left: Array<string>
-  right: Array<string>
+  start: Array<string>
+  end: Array<string>
 }
 
 export interface TableState_ColumnPinning {
@@ -18,7 +25,11 @@ export interface TableState_ColumnPinning {
 
 export interface TableOptions_ColumnPinning {
   /**
-   * Allows columns to be pinned into left and right regions.
+   * Allows columns to be pinned into logical start and end regions.
+   *
+   * 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.
    *
    * Defaults to `true`; column-level `enablePinning` can still opt individual
    * columns out.
@@ -52,7 +63,7 @@ export interface Column_ColumnPinning {
    */
   getCanPin: () => boolean
   /**
-   * Reads the column's pinned position: `'left'`, `'right'`, or `false`.
+   * Reads the column's logical pinned position: `'start'`, `'end'`, or `false`.
    */
   getIsPinned: () => ColumnPinningPosition
   /**
@@ -60,33 +71,33 @@ export interface Column_ColumnPinning {
    */
   getPinnedIndex: () => number
   /**
-   * Pins this column's leaf columns left or right, or unpins them when `false`
-   * is passed.
+   * Pins this column's leaf columns to logical start or end, or unpins them
+   * when `false` is passed.
    */
   pin: (position: ColumnPinningPosition) => void
 }
 
 export interface Row_ColumnPinning<
-  TFeatures extends TableFeatures,
-  TData extends RowData,
+  in out TFeatures extends TableFeatures,
+  in out TData extends RowData,
 > {
   /**
-   * Gets visible row cells whose columns are not pinned left or right.
+   * Gets visible row cells whose columns are not pinned start or end.
    */
   getCenterVisibleCells: () => Array<Cell<TFeatures, TData, unknown>>
   /**
-   * Gets visible row cells whose columns are pinned left.
+   * Gets visible row cells whose columns are pinned to logical start.
    */
-  getLeftVisibleCells: () => Array<Cell<TFeatures, TData, unknown>>
+  getStartVisibleCells: () => Array<Cell<TFeatures, TData, unknown>>
   /**
-   * Gets visible row cells whose columns are pinned right.
+   * Gets visible row cells whose columns are pinned to logical end.
    */
-  getRightVisibleCells: () => Array<Cell<TFeatures, TData, unknown>>
+  getEndVisibleCells: () => Array<Cell<TFeatures, TData, unknown>>
 }
 
 export interface Table_ColumnPinning<
-  TFeatures extends TableFeatures,
-  TData extends RowData,
+  in out TFeatures extends TableFeatures,
+  in out TData extends RowData,
 > {
   /**
    * Builds flat center-region headers for columns that are not pinned,
@@ -102,7 +113,7 @@ export interface Table_ColumnPinning<
    */
   getCenterHeaderGroups: () => Array<HeaderGroup<TFeatures, TData>>
   /**
-   * Gets leaf columns that are not pinned left or right.
+   * Gets leaf columns that are not pinned start or end.
    */
   getCenterLeafColumns: () => Array<Column<TFeatures, TData, unknown>>
   /**
@@ -118,59 +129,59 @@ export interface Table_ColumnPinning<
    */
   getIsSomeColumnsPinned: (position?: ColumnPinningPosition) => boolean
   /**
-   * Builds flat left-region headers for pinned columns, including parent
+   * Builds flat logical start-region headers for pinned columns, including parent
    * headers.
    */
-  getLeftFlatHeaders: () => Array<Header<TFeatures, TData, unknown>>
+  getStartFlatHeaders: () => Array<Header<TFeatures, TData, unknown>>
   /**
-   * Builds footer groups for left-pinned columns.
+   * Builds footer groups for logical start-pinned columns.
    */
-  getLeftFooterGroups: () => Array<HeaderGroup<TFeatures, TData>>
+  getStartFooterGroups: () => Array<HeaderGroup<TFeatures, TData>>
   /**
-   * Builds header groups for left-pinned columns.
+   * Builds header groups for logical start-pinned columns.
    */
-  getLeftHeaderGroups: () => Array<HeaderGroup<TFeatures, TData>>
+  getStartHeaderGroups: () => Array<HeaderGroup<TFeatures, TData>>
   /**
-   * Gets leaf columns pinned to the left region in pinning-state order.
+   * Gets leaf columns pinned to the logical start region in pinning-state order.
    */
-  getLeftLeafColumns: () => Array<Column<TFeatures, TData, unknown>>
+  getStartLeafColumns: () => Array<Column<TFeatures, TData, unknown>>
   /**
-   * Builds leaf headers for left-pinned columns.
+   * Builds leaf headers for logical start-pinned columns.
    */
-  getLeftLeafHeaders: () => Array<Header<TFeatures, TData, unknown>>
+  getStartLeafHeaders: () => Array<Header<TFeatures, TData, unknown>>
   /**
-   * Lists visible leaf columns in the left pinned region.
+   * Lists visible leaf columns in the logical start pinned region.
    */
-  getLeftVisibleLeafColumns: () => Array<Column<TFeatures, TData, unknown>>
+  getStartVisibleLeafColumns: () => Array<Column<TFeatures, TData, unknown>>
   /**
-   * Builds flat right-region headers for pinned columns, including parent
+   * Builds flat logical end-region headers for pinned columns, including parent
    * headers.
    */
-  getRightFlatHeaders: () => Array<Header<TFeatures, TData, unknown>>
+  getEndFlatHeaders: () => Array<Header<TFeatures, TData, unknown>>
   /**
-   * Builds footer groups for right-pinned columns.
+   * Builds footer groups for logical end-pinned columns.
    */
-  getRightFooterGroups: () => Array<HeaderGroup<TFeatures, TData>>
+  getEndFooterGroups: () => Array<HeaderGroup<TFeatures, TData>>
   /**
-   * Builds header groups for right-pinned columns.
+   * Builds header groups for logical end-pinned columns.
    */
-  getRightHeaderGroups: () => Array<HeaderGroup<TFeatures, TData>>
+  getEndHeaderGroups: () => Array<HeaderGroup<TFeatures, TData>>
   /**
-   * Gets leaf columns pinned to the right region in pinning-state order.
+   * Gets leaf columns pinned to the logical end region in pinning-state order.
    */
-  getRightLeafColumns: () => Array<Column<TFeatures, TData, unknown>>
+  getEndLeafColumns: () => Array<Column<TFeatures, TData, unknown>>
   /**
-   * Builds leaf headers for right-pinned columns.
+   * Builds leaf headers for logical end-pinned columns.
    */
-  getRightLeafHeaders: () => Array<Header<TFeatures, TData, unknown>>
+  getEndLeafHeaders: () => Array<Header<TFeatures, TData, unknown>>
   /**
-   * Lists visible leaf columns in the right pinned region.
+   * Lists visible leaf columns in the logical end pinned region.
    */
-  getRightVisibleLeafColumns: () => Array<Column<TFeatures, TData, unknown>>
+  getEndVisibleLeafColumns: () => Array<Column<TFeatures, TData, unknown>>
   /**
    * Resets `columnPinning` to `initialState.columnPinning`.
    *
-   * Pass `true` to ignore initial state and reset to empty left/right arrays.
+   * Pass `true` to ignore initial state and reset to empty start/end arrays.
    */
   resetColumnPinning: (defaultState?: boolean) => void
   /**