@tanstack/table-core 9.0.0-alpha.8 → 9.0.0-beta.1

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

@@ -0,0 +1,352 @@
+import {
+  assignPrototypeAPIs,
+  assignTableAPIs,
+  callMemoOrStaticFn,
+  makeStateUpdater,
+} from '../../utils'
+import { table_getVisibleLeafColumns } from '../column-visibility/columnVisibilityFeature.utils'
+import {
+  column_getCanPin,
+  column_getIsPinned,
+  column_getPinnedIndex,
+  column_pin,
+  getDefaultColumnPinningState,
+  row_getCenterVisibleCells,
+  row_getLeftVisibleCells,
+  row_getRightVisibleCells,
+  table_getCenterFlatHeaders,
+  table_getCenterFooterGroups,
+  table_getCenterHeaderGroups,
+  table_getCenterLeafColumns,
+  table_getCenterLeafHeaders,
+  table_getCenterVisibleLeafColumns,
+  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_resetColumnPinning,
+  table_setColumnPinning,
+} from './columnPinningFeature.utils'
+import type { RowData } from '../../types/type-utils'
+import type { TableFeature, TableFeatures } from '../../types/TableFeatures'
+// import type {
+//   ColumnDef_ColumnPinning,
+//   Column_ColumnPinning,
+//   Row_ColumnPinning,
+//   TableOptions_ColumnPinning,
+//   TableState_ColumnPinning,
+//   Table_ColumnPinning,
+// } from './columnPinningFeature.types'
+
+export interface ColumnPinningFeatureConstructors<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+> {
+  // Column: Column_ColumnPinning
+  // ColumnDef: ColumnDef_ColumnPinning
+  // Row: Row_ColumnPinning<TFeatures, TData>
+  // Table: Table_ColumnPinning<TFeatures, TData>
+  // TableOptions: TableOptions_ColumnPinning
+  // 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,
+>(): TableFeature<ColumnPinningFeatureConstructors<TFeatures, TData>> {
+  return {
+    getInitialState: (initialState) => {
+      return {
+        columnPinning: {
+          ...getDefaultColumnPinningState(),
+          ...initialState.columnPinning,
+        },
+        ...initialState,
+      }
+    },
+
+    getDefaultTableOptions: (table) => {
+      return {
+        onColumnPinningChange: makeStateUpdater('columnPinning', table),
+      }
+    },
+
+    assignColumnPrototype: (prototype, table) => {
+      assignPrototypeAPIs('columnPinningFeature', prototype, table, {
+        column_pin: {
+          fn: (column, position) => column_pin(column, position),
+        },
+        column_getCanPin: {
+          fn: (column) => column_getCanPin(column),
+        },
+        column_getPinnedIndex: {
+          fn: (column) => column_getPinnedIndex(column),
+        },
+        column_getIsPinned: {
+          fn: (column) => column_getIsPinned(column),
+        },
+      })
+    },
+
+    assignRowPrototype: (prototype, table) => {
+      assignPrototypeAPIs('columnPinningFeature', prototype, table, {
+        row_getCenterVisibleCells: {
+          fn: (row) => row_getCenterVisibleCells(row),
+          memoDeps: (row) => [
+            row.getAllCells(),
+            row.table.atoms.columnPinning?.get(),
+            row.table.atoms.columnVisibility?.get(),
+          ],
+        },
+        row_getLeftVisibleCells: {
+          fn: (row) => row_getLeftVisibleCells(row),
+          memoDeps: (row) => [
+            row.getAllCells(),
+            row.table.atoms.columnPinning?.get()?.left,
+            row.table.atoms.columnVisibility?.get(),
+          ],
+        },
+        row_getRightVisibleCells: {
+          fn: (row) => row_getRightVisibleCells(row),
+          memoDeps: (row) => [
+            row.getAllCells(),
+            row.table.atoms.columnPinning?.get()?.right,
+            row.table.atoms.columnVisibility?.get(),
+          ],
+        },
+      })
+    },
+
+    constructTableAPIs: (table) => {
+      assignTableAPIs('columnPinningFeature', table, {
+        table_setColumnPinning: {
+          fn: (updater) => table_setColumnPinning(table, updater),
+        },
+        table_resetColumnPinning: {
+          fn: (defaultState) => table_resetColumnPinning(table, defaultState),
+        },
+        table_getIsSomeColumnsPinned: {
+          fn: (position) => table_getIsSomeColumnsPinned(table, position),
+        },
+        // header groups
+        table_getLeftHeaderGroups: {
+          fn: () => table_getLeftHeaderGroups(table),
+          memoDeps: () => [
+            table.getAllColumns(),
+            callMemoOrStaticFn(
+              table,
+              'getVisibleLeafColumns',
+              table_getVisibleLeafColumns,
+            ),
+            table.atoms.columnPinning?.get()?.left,
+            table.atoms.columnOrder?.get(),
+          ],
+        },
+        table_getCenterHeaderGroups: {
+          fn: () => table_getCenterHeaderGroups(table),
+          memoDeps: () => [
+            table.getAllColumns(),
+            callMemoOrStaticFn(
+              table,
+              'getVisibleLeafColumns',
+              table_getVisibleLeafColumns,
+            ),
+            table.atoms.columnPinning?.get(),
+            table.atoms.columnOrder?.get(),
+          ],
+        },
+        table_getRightHeaderGroups: {
+          fn: () => table_getRightHeaderGroups(table),
+          memoDeps: () => [
+            table.getAllColumns(),
+            callMemoOrStaticFn(
+              table,
+              'getVisibleLeafColumns',
+              table_getVisibleLeafColumns,
+            ),
+            table.atoms.columnPinning?.get()?.right,
+            table.atoms.columnOrder?.get(),
+          ],
+        },
+        // footer groups
+        table_getLeftFooterGroups: {
+          fn: () => table_getLeftFooterGroups(table),
+          memoDeps: () => [
+            callMemoOrStaticFn(
+              table,
+              'getLeftHeaderGroups',
+              table_getLeftHeaderGroups,
+            ),
+          ],
+        },
+        table_getCenterFooterGroups: {
+          fn: () => table_getCenterFooterGroups(table),
+          memoDeps: () => [
+            callMemoOrStaticFn(
+              table,
+              'getCenterHeaderGroups',
+              table_getCenterHeaderGroups,
+            ),
+          ],
+        },
+        table_getRightFooterGroups: {
+          fn: () => table_getRightFooterGroups(table),
+          memoDeps: () => [
+            callMemoOrStaticFn(
+              table,
+              'getRightHeaderGroups',
+              table_getRightHeaderGroups,
+            ),
+          ],
+        },
+        // flat headers
+        table_getLeftFlatHeaders: {
+          fn: () => table_getLeftFlatHeaders(table),
+          memoDeps: () => [
+            callMemoOrStaticFn(
+              table,
+              'getLeftHeaderGroups',
+              table_getLeftHeaderGroups,
+            ),
+          ],
+        },
+        table_getRightFlatHeaders: {
+          fn: () => table_getRightFlatHeaders(table),
+          memoDeps: () => [
+            callMemoOrStaticFn(
+              table,
+              'getRightHeaderGroups',
+              table_getRightHeaderGroups,
+            ),
+          ],
+        },
+        table_getCenterFlatHeaders: {
+          fn: () => table_getCenterFlatHeaders(table),
+          memoDeps: () => [
+            callMemoOrStaticFn(
+              table,
+              'getCenterHeaderGroups',
+              table_getCenterHeaderGroups,
+            ),
+          ],
+        },
+        // leaf headers
+        table_getLeftLeafHeaders: {
+          fn: () => table_getLeftLeafHeaders(table),
+          memoDeps: () => [
+            callMemoOrStaticFn(
+              table,
+              'getLeftHeaderGroups',
+              table_getLeftHeaderGroups,
+            ),
+          ],
+        },
+        table_getRightLeafHeaders: {
+          fn: () => table_getRightLeafHeaders(table),
+          memoDeps: () => [
+            callMemoOrStaticFn(
+              table,
+              'getRightHeaderGroups',
+              table_getRightHeaderGroups,
+            ),
+          ],
+        },
+        table_getCenterLeafHeaders: {
+          fn: () => table_getCenterLeafHeaders(table),
+          memoDeps: () => [
+            callMemoOrStaticFn(
+              table,
+              'getCenterHeaderGroups',
+              table_getCenterHeaderGroups,
+            ),
+          ],
+        },
+        // leaf columns
+        table_getLeftLeafColumns: {
+          fn: () => table_getLeftLeafColumns(table),
+          memoDeps: () => [
+            table.options.columns,
+            table.atoms.columnPinning?.get(),
+            table.atoms.columnOrder?.get(),
+          ],
+        },
+        table_getRightLeafColumns: {
+          fn: () => table_getRightLeafColumns(table),
+          memoDeps: () => [
+            table.options.columns,
+            table.atoms.columnPinning?.get(),
+            table.atoms.columnOrder?.get(),
+          ],
+        },
+        table_getCenterLeafColumns: {
+          fn: () => table_getCenterLeafColumns(table),
+          memoDeps: () => [
+            table.options.columns,
+            table.atoms.columnPinning?.get(),
+            table.atoms.columnOrder?.get(),
+          ],
+        },
+        table_getPinnedLeafColumns: {
+          fn: (position) => table_getPinnedLeafColumns(table, position),
+          // must not memo here as it's just a shortcut function
+        },
+        // visible leaf columns
+        table_getLeftVisibleLeafColumns: {
+          fn: () => table_getLeftVisibleLeafColumns(table),
+          memoDeps: () => [
+            table.options.columns,
+            table.atoms.columnPinning?.get(),
+            table.atoms.columnVisibility?.get(),
+            table.atoms.columnOrder?.get(),
+          ],
+        },
+        table_getCenterVisibleLeafColumns: {
+          fn: () => table_getCenterVisibleLeafColumns(table),
+          memoDeps: () => [
+            table.options.columns,
+            table.atoms.columnPinning?.get(),
+            table.atoms.columnVisibility?.get(),
+            table.atoms.columnOrder?.get(),
+          ],
+        },
+        table_getRightVisibleLeafColumns: {
+          fn: () => table_getRightVisibleLeafColumns(table),
+          memoDeps: () => [
+            table.options.columns,
+            table.atoms.columnPinning?.get(),
+            table.atoms.columnVisibility?.get(),
+            table.atoms.columnOrder?.get(),
+          ],
+        },
+        table_getPinnedVisibleLeafColumns: {
+          fn: (position) => table_getPinnedVisibleLeafColumns(table, position),
+          // must not memo here as it's just a shortcut function
+        },
+      })
+    },
+  }
+}
+
+/**
+ * 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

@@ -0,0 +1,192 @@
+import type { OnChangeFn, RowData, Updater } from '../../types/type-utils'
+import type { TableFeatures } from '../../types/TableFeatures'
+import type { Cell } from '../../types/Cell'
+import type { Header } from '../../types/Header'
+import type { HeaderGroup } from '../../types/HeaderGroup'
+import type { Column } from '../../types/Column'
+
+export type ColumnPinningPosition = false | 'left' | 'right'
+
+export interface ColumnPinningState {
+  left: Array<string>
+  right: Array<string>
+}
+
+export interface TableState_ColumnPinning {
+  columnPinning: ColumnPinningState
+}
+
+export interface TableOptions_ColumnPinning {
+  /**
+   * Allows columns to be pinned into left and right regions.
+   *
+   * Defaults to `true`; column-level `enablePinning` can still opt individual
+   * columns out.
+   */
+  enableColumnPinning?: boolean
+  /**
+   * 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>
+}
+
+export interface ColumnPinningDefaultOptions {
+  onColumnPinningChange: OnChangeFn<ColumnPinningState>
+}
+
+export interface ColumnDef_ColumnPinning {
+  /**
+   * Allows this column's leaf columns to be pinned.
+   *
+   * Defaults to `true`; table-level `enableColumnPinning` must also allow
+   * pinning.
+   */
+  enablePinning?: boolean
+}
+
+export interface Column_ColumnPinning {
+  /**
+   * Checks whether this column or any of its leaves can be pinned.
+   */
+  getCanPin: () => boolean
+  /**
+   * Reads the column's pinned position: `'left'`, `'right'`, or `false`.
+   */
+  getIsPinned: () => ColumnPinningPosition
+  /**
+   * Finds this column's index within its pinned region.
+   */
+  getPinnedIndex: () => number
+  /**
+   * Pins this column's leaf columns left or right, or unpins them when `false`
+   * is passed.
+   */
+  pin: (position: ColumnPinningPosition) => void
+}
+
+export interface Row_ColumnPinning<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+> {
+  /**
+   * Gets visible row cells whose columns are not pinned left or right.
+   */
+  getCenterVisibleCells: () => Array<Cell<TFeatures, TData, unknown>>
+  /**
+   * Gets visible row cells whose columns are pinned left.
+   */
+  getLeftVisibleCells: () => Array<Cell<TFeatures, TData, unknown>>
+  /**
+   * Gets visible row cells whose columns are pinned right.
+   */
+  getRightVisibleCells: () => Array<Cell<TFeatures, TData, unknown>>
+}
+
+export interface Table_ColumnPinning<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+> {
+  /**
+   * Builds flat center-region headers for columns that are not pinned,
+   * including parent headers.
+   */
+  getCenterFlatHeaders: () => Array<Header<TFeatures, TData, unknown>>
+  /**
+   * Builds footer groups for the center region of unpinned columns.
+   */
+  getCenterFooterGroups: () => Array<HeaderGroup<TFeatures, TData>>
+  /**
+   * Builds header groups for the center region of unpinned columns.
+   */
+  getCenterHeaderGroups: () => Array<HeaderGroup<TFeatures, TData>>
+  /**
+   * Gets leaf columns that are not pinned left or right.
+   */
+  getCenterLeafColumns: () => Array<Column<TFeatures, TData, unknown>>
+  /**
+   * Builds center-region leaf headers for columns that are not pinned.
+   */
+  getCenterLeafHeaders: () => Array<Header<TFeatures, TData, unknown>>
+  /**
+   * Lists visible leaf columns in the unpinned center region.
+   */
+  getCenterVisibleLeafColumns: () => Array<Column<TFeatures, TData, unknown>>
+  /**
+   * Checks whether any columns are pinned, optionally limited to one side.
+   */
+  getIsSomeColumnsPinned: (position?: ColumnPinningPosition) => boolean
+  /**
+   * Builds flat left-region headers for pinned columns, including parent
+   * headers.
+   */
+  getLeftFlatHeaders: () => Array<Header<TFeatures, TData, unknown>>
+  /**
+   * Builds footer groups for left-pinned columns.
+   */
+  getLeftFooterGroups: () => Array<HeaderGroup<TFeatures, TData>>
+  /**
+   * Builds header groups for left-pinned columns.
+   */
+  getLeftHeaderGroups: () => Array<HeaderGroup<TFeatures, TData>>
+  /**
+   * Gets leaf columns pinned to the left region in pinning-state order.
+   */
+  getLeftLeafColumns: () => Array<Column<TFeatures, TData, unknown>>
+  /**
+   * Builds leaf headers for left-pinned columns.
+   */
+  getLeftLeafHeaders: () => Array<Header<TFeatures, TData, unknown>>
+  /**
+   * Lists visible leaf columns in the left pinned region.
+   */
+  getLeftVisibleLeafColumns: () => Array<Column<TFeatures, TData, unknown>>
+  /**
+   * Builds flat right-region headers for pinned columns, including parent
+   * headers.
+   */
+  getRightFlatHeaders: () => Array<Header<TFeatures, TData, unknown>>
+  /**
+   * Builds footer groups for right-pinned columns.
+   */
+  getRightFooterGroups: () => Array<HeaderGroup<TFeatures, TData>>
+  /**
+   * Builds header groups for right-pinned columns.
+   */
+  getRightHeaderGroups: () => Array<HeaderGroup<TFeatures, TData>>
+  /**
+   * Gets leaf columns pinned to the right region in pinning-state order.
+   */
+  getRightLeafColumns: () => Array<Column<TFeatures, TData, unknown>>
+  /**
+   * Builds leaf headers for right-pinned columns.
+   */
+  getRightLeafHeaders: () => Array<Header<TFeatures, TData, unknown>>
+  /**
+   * Lists visible leaf columns in the right pinned region.
+   */
+  getRightVisibleLeafColumns: () => Array<Column<TFeatures, TData, unknown>>
+  /**
+   * Resets `columnPinning` to `initialState.columnPinning`.
+   *
+   * Pass `true` to ignore initial state and reset to empty left/right arrays.
+   */
+  resetColumnPinning: (defaultState?: boolean) => void
+  /**
+   * Updates column pinning state with a next state or updater function.
+   */
+  setColumnPinning: (updater: Updater<ColumnPinningState>) => void
+  /**
+   * Returns pinned leaf columns for the requested pinning region.
+   */
+  getPinnedLeafColumns: (
+    position: ColumnPinningPosition | 'center',
+  ) => Array<Column<TFeatures, TData, unknown>>
+  /**
+   * Lists visible leaf columns for the requested pinning region.
+   */
+  getPinnedVisibleLeafColumns: (
+    position: ColumnPinningPosition | 'center',
+  ) => Array<Column<TFeatures, TData, unknown>>
+}