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

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

@@ -0,0 +1,316 @@
+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 { TableFeature } from '../../types/TableFeatures'
+
+/**
+ * Feature that adds column pinning state and APIs for left, center, and right regions.
+ */
+export const columnPinningFeature: TableFeature = {
+  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
+      },
+    })
+  },
+}

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>>
+}