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

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

@@ -31,6 +31,11 @@ export interface ColumnOrderingFeatureConstructors<
   // TableState: TableState_ColumnOrdering
 }
 
+/**
+ * Creates the stock column ordering feature.
+ *
+ * The returned feature registers its state defaults, option defaults, and instance APIs so it can be included in a `tableFeatures({ ... })` call.
+ */
 export function constructColumnOrderingFeature<
   TFeatures extends TableFeatures,
   TData extends RowData,
@@ -58,6 +63,7 @@ export function constructColumnOrderingFeature<
             column.table.atoms.columnOrder?.get(),
             column.table.atoms.columnPinning?.get(),
             column.table.atoms.grouping?.get(),
+            column.table.atoms.columnVisibility?.get(),
           ],
         },
         column_getIsFirstColumn: {
@@ -91,6 +97,9 @@ export function constructColumnOrderingFeature<
 }
 
 /**
- * The Column Ordering feature adds column ordering state and APIs to the table and column objects.
+ * The stock column ordering feature.
+ *
+ * Register this feature to add column order state and APIs for deriving the
+ * ordered leaf column list alongside grouping and pinning.
  */
 export const columnOrderingFeature = constructColumnOrderingFeature()

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

@@ -10,7 +10,9 @@ export interface TableState_ColumnOrdering {
 
 export interface TableOptions_ColumnOrdering {
   /**
-   * If provided, this function will be called with an `updaterFn` when `state.columnOrder` changes. This overrides the default internal state management, so you will need to persist the state change either fully or partially outside of the table.
+   * Called with an updater when column order state changes. Pair this with
+   * `state.columnOrder` when using external state; external atoms can own the
+   * slice without this callback.
    */
   onColumnOrderChange?: OnChangeFn<ColumnOrderState>
 }
@@ -43,7 +45,7 @@ export interface Table_ColumnOrdering<
    */
   resetColumnOrder: (defaultState?: boolean) => void
   /**
-   * Sets or updates the `state.columnOrder` state.
+   * Sets column order state using a value or updater.
    */
   setColumnOrder: (updater: Updater<ColumnOrderState>) => void
 }

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

@@ -8,10 +8,30 @@ import type { Column_Internal } from '../../types/Column'
 import type { ColumnPinningPosition } from '../column-pinning/columnPinningFeature.types'
 import type { ColumnOrderState } from './columnOrderingFeature.types'
 
+/**
+ * Returns the default column order state.
+ *
+ * Feature constructors use this value to initialize the table state or option defaults when no user value is provided.
+ *
+ * @example
+ * ```ts
+ * const initialValue = getDefaultColumnOrderState()
+ * ```
+ */
 export function getDefaultColumnOrderState(): ColumnOrderState {
   return []
 }
 
+/**
+ * Returns index for a column.
+ *
+ * This derives the value from the column definition, table options, and the feature state atoms registered on the table.
+ *
+ * @example
+ * ```ts
+ * const value = column_getIndex(column)
+ * ```
+ */
 export function column_getIndex<
   TFeatures extends TableFeatures,
   TData extends RowData,
@@ -24,6 +44,16 @@ export function column_getIndex<
   return columns.findIndex((d) => d.id === column.id)
 }
 
+/**
+ * Returns is first column for a column.
+ *
+ * This derives the value from the column definition, table options, and the feature state atoms registered on the table.
+ *
+ * @example
+ * ```ts
+ * const value = column_getIsFirstColumn(column)
+ * ```
+ */
 export function column_getIsFirstColumn<
   TFeatures extends TableFeatures,
   TData extends RowData,
@@ -36,6 +66,16 @@ export function column_getIsFirstColumn<
   return columns[0]?.id === column.id
 }
 
+/**
+ * Returns is last column for a column.
+ *
+ * This derives the value from the column definition, table options, and the feature state atoms registered on the table.
+ *
+ * @example
+ * ```ts
+ * const value = column_getIsLastColumn(column)
+ * ```
+ */
 export function column_getIsLastColumn<
   TFeatures extends TableFeatures,
   TData extends RowData,
@@ -48,6 +88,16 @@ export function column_getIsLastColumn<
   return columns[columns.length - 1]?.id === column.id
 }
 
+/**
+ * Updates the table's column order state slice.
+ *
+ * The updater follows TanStack Table updater semantics and is routed through the corresponding `on*Change` option or backing atom.
+ *
+ * @example
+ * ```ts
+ * table_setColumnOrder(table, (old) => old)
+ * ```
+ */
 export function table_setColumnOrder<
   TFeatures extends TableFeatures,
   TData extends RowData,
@@ -55,6 +105,17 @@ export function table_setColumnOrder<
   table.options.onColumnOrderChange?.(updater)
 }
 
+/**
+ * Resets the table's column order state slice.
+ *
+ * By default the reset uses `table.initialState`; when supported, a blank/default reset bypasses the saved initial value.
+ *
+ * @example
+ * ```ts
+ * table_resetColumnOrder(table)
+ * table_resetColumnOrder(table, true)
+ * ```
+ */
 export function table_resetColumnOrder<
   TFeatures extends TableFeatures,
   TData extends RowData,
@@ -65,6 +126,16 @@ export function table_resetColumnOrder<
   )
 }
 
+/**
+ * Returns order columns fn for the table.
+ *
+ * This reads the relevant table atoms, options, and row-model cache to derive the current table-level value.
+ *
+ * @example
+ * ```ts
+ * const value = table_getOrderColumnsFn(table)
+ * ```
+ */
 export function table_getOrderColumnsFn<
   TFeatures extends TableFeatures,
   TData extends RowData,
@@ -80,30 +151,48 @@ export function table_getOrderColumnsFn<
     if (!columnOrder?.length) {
       orderedColumns = columns
     } else {
-      const columnOrderCopy = [...columnOrder]
-
-      // If there is an order, make a copy of the columns
-      const columnsCopy = [...columns]
-
-      // And make a new ordered array of the columns
+      // Index columns by id for O(1) lookup
+      const remaining = new Map<
+        string,
+        Column_Internal<TFeatures, TData, unknown>
+      >()
+      for (let i = 0; i < columns.length; i++) {
+        const column = columns[i]!
+        remaining.set(column.id, column)
+      }
 
-      // Loop over the columns and place them in order into the new array
-      while (columnsCopy.length && columnOrderCopy.length) {
-        const targetColumnId = columnOrderCopy.shift()
-        const foundIndex = columnsCopy.findIndex((d) => d.id === targetColumnId)
-        if (foundIndex > -1) {
-          orderedColumns.push(columnsCopy.splice(foundIndex, 1)[0]!)
+      // Place columns in the requested order, removing each as it's used
+      // (handles duplicates and unknown ids in columnOrder)
+      for (let i = 0; i < columnOrder.length; i++) {
+        const id = columnOrder[i]!
+        const column = remaining.get(id)
+        if (column) {
+          orderedColumns.push(column)
+          remaining.delete(id)
         }
       }
 
-      // If there are any columns left, add them to the end
-      orderedColumns = [...orderedColumns, ...columnsCopy]
+      // Append leftover columns in their original order
+      for (let i = 0; i < columns.length; i++) {
+        const column = columns[i]!
+        if (remaining.has(column.id)) orderedColumns.push(column)
+      }
     }
 
     return orderColumns(table, orderedColumns)
   }
 }
 
+/**
+ * Orders leaf columns with manual ordering, grouping, and pinning rules.
+ *
+ * This helper is used by the column ordering feature to produce the final visible column order.
+ *
+ * @example
+ * ```ts
+ * const orderedColumns = orderColumns(leafColumns, columnOrder, grouping, groupedColumnMode)
+ * ```
+ */
 export function orderColumns<
   TFeatures extends TableFeatures,
   TData extends RowData,
@@ -126,9 +215,20 @@ export function orderColumns<
     return nonGroupingColumns
   }
 
-  const groupingColumns = grouping
-    .map((g) => leafColumns.find((col) => col.id === g)!)
-    .filter(Boolean)
+  const leafColumnsById = new Map<
+    string,
+    Column_Internal<TFeatures, TData, unknown>
+  >()
+  for (let i = 0; i < leafColumns.length; i++) {
+    const col = leafColumns[i]!
+    leafColumnsById.set(col.id, col)
+  }
+
+  const groupingColumns: Array<Column_Internal<TFeatures, TData, unknown>> = []
+  for (let i = 0; i < grouping.length; i++) {
+    const col = leafColumnsById.get(grouping[i]!)
+    if (col) groupingColumns.push(col)
+  }
 
   return [...groupingColumns, ...nonGroupingColumns]
 }

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

@@ -61,6 +61,11 @@ export interface ColumnPinningFeatureConstructors<
   // TableState: TableState_ColumnPinning
 }
 
+/**
+ * Creates the stock column pinning feature.
+ *
+ * The returned feature registers its state defaults, option defaults, and instance APIs so it can be included in a `tableFeatures({ ... })` call.
+ */
 export function constructColumnPinningFeature<
   TFeatures extends TableFeatures,
   TData extends RowData,
@@ -296,11 +301,7 @@ export function constructColumnPinningFeature<
         },
         table_getPinnedLeafColumns: {
           fn: (position) => table_getPinnedLeafColumns(table, position),
-          memoDeps: (position) => [
-            position,
-            table.options.columns,
-            table.atoms.columnPinning?.get(),
-          ],
+          // must not memo here as it's just a shortcut function
         },
         // visible leaf columns
         table_getLeftVisibleLeafColumns: {
@@ -329,12 +330,7 @@ export function constructColumnPinningFeature<
         },
         table_getPinnedVisibleLeafColumns: {
           fn: (position) => table_getPinnedVisibleLeafColumns(table, position),
-          memoDeps: (position) => [
-            position,
-            table.options.columns,
-            table.atoms.columnPinning?.get(),
-            table.atoms.columnVisibility?.get(),
-          ],
+          // must not memo here as it's just a shortcut function
         },
       })
     },
@@ -342,6 +338,9 @@ export function constructColumnPinningFeature<
 }
 
 /**
- * The Column Pinning feature adds column pinning state and APIs to the table, row, and column objects.
+ * The stock column pinning feature.
+ *
+ * Register this feature to add column pinning state plus table, row, and column
+ * APIs for splitting columns into left, center, and right regions.
  */
 export const columnPinningFeature = constructColumnPinningFeature()

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

@@ -22,7 +22,9 @@ export interface TableOptions_ColumnPinning {
    */
   enableColumnPinning?: boolean
   /**
-   * If provided, this function will be called with an `updaterFn` when `state.columnPinning` changes. This overrides the default internal state management, so you will also need to supply `state.columnPinning` from your own managed state.
+   * Called with an updater when column pinning state changes. Pair this with
+   * `state.columnPinning` when using external state; external atoms can own the
+   * slice without this callback.
    */
   onColumnPinningChange?: OnChangeFn<ColumnPinningState>
 }
@@ -160,15 +162,17 @@ export interface Table_ColumnPinning<
    */
   resetColumnPinning: (defaultState?: boolean) => void
   /**
-   * Sets or updates the `state.columnPinning` state.
+   * Sets column pinning state using a value or updater.
    */
   setColumnPinning: (updater: Updater<ColumnPinningState>) => void
   /**
+   * Returns pinned leaf columns for the requested pinning region.
    */
   getPinnedLeafColumns: (
     position: ColumnPinningPosition | 'center',
   ) => Array<Column<TFeatures, TData, unknown>>
   /**
+   * Returns visible pinned leaf columns for the requested pinning region.
    */
   getPinnedVisibleLeafColumns: (
     position: ColumnPinningPosition | 'center',