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

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

@@ -0,0 +1,182 @@
+import {
+  assignPrototypeAPIs,
+  assignTableAPIs,
+  makeStateUpdater,
+} from '../../utils'
+import {
+  column_getAfter,
+  column_getSize,
+  column_getStart,
+  column_resetSize,
+  getDefaultColumnSizingColumnDef,
+  getDefaultColumnSizingState,
+  header_getSize,
+  header_getStart,
+  table_getCenterTotalSize,
+  table_getLeftTotalSize,
+  table_getRightTotalSize,
+  table_getTotalSize,
+  table_resetColumnSizing,
+  table_setColumnSizing,
+} from './columnSizingFeature.utils'
+import type { RowData } from '../../types/type-utils'
+import type { TableFeature, TableFeatures } from '../../types/TableFeatures'
+// import type {
+//   ColumnDef_ColumnSizing,
+//   Column_ColumnSizing,
+//   Header_ColumnSizing,
+//   TableOptions_ColumnSizing,
+//   TableState_ColumnSizing,
+//   Table_ColumnSizing,
+// } from './columnSizingFeature.types'
+
+export interface ColumnSizingFeatureConstructors<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+> {
+  // ColumnDef: ColumnDef_ColumnSizing
+  // Column: Column_ColumnSizing
+  // Header: Header_ColumnSizing
+  // Table: Table_ColumnSizing
+  // TableOptions: TableOptions_ColumnSizing
+  // TableState: TableState_ColumnSizing
+}
+
+/**
+ * Creates the stock column sizing feature.
+ *
+ * The returned feature registers its state defaults, option defaults, and instance APIs so it can be included in a `tableFeatures({ ... })` call.
+ */
+export function constructColumnSizingFeature<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+>(): TableFeature<ColumnSizingFeatureConstructors<TFeatures, TData>> {
+  return {
+    getInitialState: (initialState) => {
+      return {
+        columnSizing: getDefaultColumnSizingState(),
+        ...initialState,
+      }
+    },
+
+    getDefaultColumnDef: () => {
+      return getDefaultColumnSizingColumnDef()
+    },
+
+    getDefaultTableOptions: (table) => {
+      return {
+        onColumnSizingChange: makeStateUpdater('columnSizing', table),
+      }
+    },
+
+    assignColumnPrototype: (prototype, table) => {
+      assignPrototypeAPIs('columnSizingFeature', prototype, table, {
+        column_getSize: {
+          fn: (column) => column_getSize(column),
+          memoDeps: (column) => [
+            table.options.columns,
+            table.atoms.columnSizing?.get()?.[column.id], // just this column's size state
+          ],
+        },
+        column_getStart: {
+          fn: (column, position) => column_getStart(column, position),
+          memoDeps: (column, position) => [
+            position,
+            table.options.columns,
+            table.atoms.columnSizing?.get(),
+            table.atoms.columnOrder?.get(),
+            table.atoms.columnPinning?.get(),
+            table.atoms.columnVisibility?.get(),
+          ],
+        },
+        column_getAfter: {
+          fn: (column, position) => column_getAfter(column, position),
+          memoDeps: (column, position) => [
+            position,
+            table.options.columns,
+            table.atoms.columnSizing?.get(),
+            table.atoms.columnOrder?.get(),
+            table.atoms.columnPinning?.get(),
+            table.atoms.columnVisibility?.get(),
+          ],
+        },
+        column_resetSize: {
+          fn: (column) => column_resetSize(column),
+        },
+      })
+    },
+
+    assignHeaderPrototype: (prototype, table) => {
+      assignPrototypeAPIs('columnSizingFeature', prototype, table, {
+        header_getSize: {
+          fn: (header) => header_getSize(header),
+          memoDeps: (header) => [
+            table.options.columns,
+            header.column.columns.length > 0
+              ? table.atoms.columnSizing?.get() // must be all columns (sum child columns)
+              : table.atoms.columnSizing?.get()?.[header.column.id], // can just check it's associated column size state
+          ],
+        },
+        header_getStart: {
+          fn: (header) => header_getStart(header),
+          memoDeps: (header, position) => [
+            position,
+            table.options.columns,
+            table.atoms.columnSizing?.get(),
+            table.atoms.columnOrder?.get(),
+            table.atoms.columnPinning?.get(),
+            table.atoms.columnVisibility?.get(),
+          ],
+        },
+      })
+    },
+
+    constructTableAPIs: (table) => {
+      assignTableAPIs('columnSizingFeature', table, {
+        table_setColumnSizing: {
+          fn: (updater) => table_setColumnSizing(table, updater),
+        },
+        table_resetColumnSizing: {
+          fn: (defaultState) => table_resetColumnSizing(table, defaultState),
+        },
+        table_getTotalSize: {
+          fn: () => table_getTotalSize(table),
+          memoDeps: () => [
+            table.atoms.columnSizing?.get(),
+            table.getHeaderGroups(),
+          ],
+        },
+        table_getLeftTotalSize: {
+          fn: () => table_getLeftTotalSize(table),
+          memoDeps: () => [
+            table.atoms.columnSizing?.get(),
+            table.getHeaderGroups(),
+          ],
+        },
+        table_getCenterTotalSize: {
+          fn: () => table_getCenterTotalSize(table),
+          memoDeps: () => [
+            table.atoms.columnSizing?.get(),
+            table.getHeaderGroups(),
+          ],
+        },
+        table_getRightTotalSize: {
+          fn: () => table_getRightTotalSize(table),
+          memoDeps: () => [
+            table.atoms.columnSizing?.get(),
+            table.getHeaderGroups(),
+          ],
+        },
+      })
+    },
+  }
+}
+
+/**
+ * The stock column sizing feature.
+ *
+ * Register this feature to add column width state and table, header, and column
+ * APIs for reading and resetting sizes. Column drag resizing lives in
+ * `columnResizingFeature`.
+ */
+export const columnSizingFeature = constructColumnSizingFeature()

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

@@ -0,0 +1,102 @@
+import type { OnChangeFn, Updater } from '../../types/type-utils'
+import type { ColumnPinningPosition } from '../column-pinning/columnPinningFeature.types'
+
+export interface TableState_ColumnSizing {
+  columnSizing: ColumnSizingState
+}
+
+export type ColumnSizingState = Record<string, number>
+
+export interface TableOptions_ColumnSizing {
+  /**
+   * Called with an updater when committed column sizing state changes. Pair
+   * this with `state.columnSizing` when using external state; external atoms
+   * can own the slice without this callback.
+   */
+  onColumnSizingChange?: OnChangeFn<ColumnSizingState>
+}
+
+export type ColumnSizingDefaultOptions = Pick<
+  TableOptions_ColumnSizing,
+  'onColumnSizingChange'
+>
+
+export interface Table_ColumnSizing {
+  /**
+   * Sums the current sizes of visible center-region leaf columns.
+   */
+  getCenterTotalSize: () => number
+  /**
+   * Sums the current sizes of visible left-pinned leaf columns.
+   */
+  getLeftTotalSize: () => number
+  /**
+   * Sums the current sizes of visible right-pinned leaf columns.
+   */
+  getRightTotalSize: () => number
+  /**
+   * Sums the current sizes of all visible leaf columns.
+   */
+  getTotalSize: () => number
+  /**
+   * Resets column sizing to `initialState.columnSizing`. Pass `true` to reset
+   * to the feature default of `{}`.
+   */
+  resetColumnSizing: (defaultState?: boolean) => void
+  /**
+   * Updates committed column sizing state with a next map or updater function.
+   */
+  setColumnSizing: (updater: Updater<ColumnSizingState>) => void
+}
+
+export interface ColumnDef_ColumnSizing {
+  /**
+   * Upper bound used when resolving this column's size.
+   */
+  maxSize?: number
+  /**
+   * Lower bound used when resolving this column's size.
+   */
+  minSize?: number
+  /**
+   * Initial size used before column sizing state overrides it.
+   */
+  size?: number
+}
+
+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.
+   */
+  getAfter: (position?: ColumnPinningPosition | 'center') => number
+  /**
+   * Resolves the column's current size after state and min/max constraints.
+   */
+  getSize: () => number
+  /**
+   * 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.
+   */
+  getStart: (position?: ColumnPinningPosition | 'center') => number
+  /**
+   * Resets the column to its initial size.
+   */
+  resetSize: () => void
+}
+
+export interface Header_ColumnSizing {
+  /**
+   * Computes this header's rendered size from its leaf columns.
+   */
+  getSize: () => number
+  /**
+   * Returns the offset measurement along the row-axis (usually the x-axis for standard tables) for the header. This is effectively a sum of the offset measurements of all preceding headers.
+   */
+  getStart: (position?: ColumnPinningPosition) => number
+}

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

@@ -0,0 +1,381 @@
+import {
+  table_getCenterHeaderGroups,
+  table_getLeftHeaderGroups,
+  table_getPinnedVisibleLeafColumns,
+  table_getRightHeaderGroups,
+} from '../column-pinning/columnPinningFeature.utils'
+import { column_getIndex } from '../column-ordering/columnOrderingFeature.utils'
+import { callMemoOrStaticFn, cloneState } from '../../utils'
+import type { ColumnPinningPosition } from '../column-pinning/columnPinningFeature.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 { Header } from '../../types/Header'
+import type { Column_Internal } from '../../types/Column'
+import type { ColumnSizingState } from './columnSizingFeature.types'
+
+/**
+ * Creates the default committed column sizing state.
+ *
+ * The feature default is an empty map, so columns fall back to their column def
+ * size or the built-in sizing defaults.
+ *
+ * @example
+ * ```ts
+ * const sizing = getDefaultColumnSizingState()
+ * ```
+ */
+export function getDefaultColumnSizingState(): ColumnSizingState {
+  return {}
+}
+
+/**
+ * Creates the built-in sizing defaults for column definitions.
+ *
+ * Columns default to `size: 150`, `minSize: 20`, and
+ * `maxSize: Number.MAX_SAFE_INTEGER` unless overridden by column definitions or
+ * table defaults.
+ *
+ * @example
+ * ```ts
+ * const defaults = getDefaultColumnSizingColumnDef()
+ * ```
+ */
+export function getDefaultColumnSizingColumnDef() {
+  return {
+    size: 150,
+    minSize: 20,
+    maxSize: Number.MAX_SAFE_INTEGER,
+  }
+}
+
+/**
+ * Resolves a column's current pixel size.
+ *
+ * Committed `state.columnSizing[column.id]` wins over `columnDef.size`, then the
+ * built-in default size. The result is clamped between min and max size.
+ *
+ * @example
+ * ```ts
+ * const width = column_getSize(column)
+ * ```
+ */
+export function column_getSize<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+  TValue extends CellData = CellData,
+>(column: Column_Internal<TFeatures, TData, TValue>): number {
+  const defaultSizes = getDefaultColumnSizingColumnDef()
+  const columnSize = column.table.atoms.columnSizing?.get()?.[column.id]
+
+  return Math.min(
+    Math.max(
+      column.columnDef.minSize ?? defaultSizes.minSize,
+      columnSize ?? column.columnDef.size ?? defaultSizes.size,
+    ),
+    column.columnDef.maxSize ?? defaultSizes.maxSize,
+  )
+}
+
+/**
+ * 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.
+ *
+ * @example
+ * ```ts
+ * const leftOffset = column_getStart(column, 'left')
+ * ```
+ */
+export function column_getStart<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+  TValue extends CellData = CellData,
+>(
+  column: Column_Internal<TFeatures, TData, TValue>,
+  position: ColumnPinningPosition | 'center',
+): number {
+  const index = callMemoOrStaticFn(
+    column,
+    'getIndex',
+    column_getIndex,
+    position,
+  )
+  if (index <= 0) return 0
+
+  const visibleLeafColumns = callMemoOrStaticFn(
+    column.table,
+    'getPinnedVisibleLeafColumns',
+    table_getPinnedVisibleLeafColumns,
+    position,
+  )
+
+  const prevColumn = visibleLeafColumns[index - 1]!
+  return (
+    callMemoOrStaticFn(prevColumn, 'getStart', column_getStart, position) +
+    callMemoOrStaticFn(prevColumn, 'getSize', column_getSize)
+  )
+}
+
+/**
+ * Computes the offset from the end edge of a pinning region after this column.
+ *
+ * The value is the sum of all following visible leaf column sizes in the
+ * requested region.
+ *
+ * @example
+ * ```ts
+ * const rightOffset = column_getAfter(column, 'right')
+ * ```
+ */
+export function column_getAfter<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+  TValue extends CellData = CellData,
+>(
+  column: Column_Internal<TFeatures, TData, TValue>,
+  position: ColumnPinningPosition | 'center',
+): number {
+  const visibleLeafColumns = callMemoOrStaticFn(
+    column.table,
+    'getPinnedVisibleLeafColumns',
+    table_getPinnedVisibleLeafColumns,
+    position,
+  )
+  const index = callMemoOrStaticFn(
+    column,
+    'getIndex',
+    column_getIndex,
+    position,
+  )
+  if (index < 0 || index >= visibleLeafColumns.length - 1) return 0
+
+  const nextColumn = visibleLeafColumns[index + 1]!
+  return (
+    callMemoOrStaticFn(nextColumn, 'getSize', column_getSize) +
+    callMemoOrStaticFn(nextColumn, 'getAfter', column_getAfter, position)
+  )
+}
+
+/**
+ * Removes this column's committed size override.
+ *
+ * After reset, the column resolves size from `columnDef.size` or built-in
+ * defaults again.
+ *
+ * @example
+ * ```ts
+ * column_resetSize(column)
+ * ```
+ */
+export function column_resetSize<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+  TValue extends CellData = CellData,
+>(column: Column_Internal<TFeatures, TData, TValue>) {
+  table_setColumnSizing(column.table, ({ [column.id]: _, ...rest }) => {
+    return rest
+  })
+}
+
+/**
+ * Computes a header's rendered size from its leaf headers.
+ *
+ * Group headers sum the sizes of all descendant leaf columns. Leaf headers use
+ * their column's current size.
+ *
+ * @example
+ * ```ts
+ * const width = header_getSize(header)
+ * ```
+ */
+export function header_getSize<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+  TValue extends CellData = CellData,
+>(header: Header<TFeatures, TData, TValue>) {
+  let sum = 0
+
+  const recurse = (h: Header<TFeatures, TData, TValue>) => {
+    if (h.subHeaders.length) {
+      h.subHeaders.forEach(recurse)
+    } else {
+      sum += column_getSize(h.column)
+    }
+  }
+
+  recurse(header)
+
+  return sum
+}
+
+/**
+ * Computes a header's offset from the start of its header group.
+ *
+ * The offset is the previous sibling header's start plus size, or `0` for the
+ * first header in the group.
+ *
+ * @example
+ * ```ts
+ * const offset = header_getStart(header)
+ * ```
+ */
+export function header_getStart<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+  TValue extends CellData = CellData,
+>(header: Header<TFeatures, TData, TValue>): number {
+  if (header.index > 0) {
+    const prevSiblingHeader = header.headerGroup?.headers[header.index - 1]
+    if (prevSiblingHeader) {
+      return (
+        callMemoOrStaticFn(prevSiblingHeader, 'getStart', header_getStart) +
+        callMemoOrStaticFn(prevSiblingHeader, 'getSize', header_getSize)
+      )
+    }
+  }
+
+  return 0
+}
+
+// Table APIs
+
+/**
+ * Routes a committed column sizing updater through the table's sizing handler.
+ *
+ * The updater may be a next size map or a function of the previous map,
+ * matching the instance `table.setColumnSizing` behavior.
+ *
+ * @example
+ * ```ts
+ * table_setColumnSizing(table, (old) => ({ ...old, age: 96 }))
+ * ```
+ */
+export function table_setColumnSizing<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+>(
+  table: Table_Internal<TFeatures, TData>,
+  updater: Updater<ColumnSizingState>,
+) {
+  table.options.onColumnSizingChange?.(updater)
+}
+
+/**
+ * Resets `columnSizing` to the configured initial state or feature default.
+ *
+ * With no argument, the reset clones `table.initialState.columnSizing` when it
+ * exists. Passing `true` ignores initial state and resets to `{}`.
+ *
+ * @example
+ * ```ts
+ * table_resetColumnSizing(table)
+ * table_resetColumnSizing(table, true)
+ * ```
+ */
+export function table_resetColumnSizing<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+>(table: Table_Internal<TFeatures, TData>, defaultState?: boolean) {
+  table_setColumnSizing(
+    table,
+    defaultState ? {} : cloneState(table.initialState.columnSizing ?? {}),
+  )
+}
+
+/**
+ * Sums the rendered size of the full table header row.
+ *
+ * This includes left, center, and right columns in the main header group.
+ *
+ * @example
+ * ```ts
+ * const width = table_getTotalSize(table)
+ * ```
+ */
+export function table_getTotalSize<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+>(table: Table_Internal<TFeatures, TData>) {
+  return (
+    table.getHeaderGroups()[0]?.headers.reduce((sum, header) => {
+      return sum + header_getSize(header)
+    }, 0) ?? 0
+  )
+}
+
+/**
+ * Sums the rendered size of the left pinned header region.
+ *
+ * An empty left pinning region returns `0`.
+ *
+ * @example
+ * ```ts
+ * const width = table_getLeftTotalSize(table)
+ * ```
+ */
+export function table_getLeftTotalSize<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+>(table: Table_Internal<TFeatures, TData>) {
+  return (
+    callMemoOrStaticFn(
+      table,
+      'getLeftHeaderGroups',
+      table_getLeftHeaderGroups,
+    )[0]?.headers.reduce((sum: number, header: Header<TFeatures, TData>) => {
+      return sum + header_getSize(header)
+    }, 0) ?? 0
+  )
+}
+
+/**
+ * Sums the rendered size of the center, unpinned header region.
+ *
+ * An empty center region returns `0`.
+ *
+ * @example
+ * ```ts
+ * const width = table_getCenterTotalSize(table)
+ * ```
+ */
+export function table_getCenterTotalSize<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+>(table: Table_Internal<TFeatures, TData>) {
+  return (
+    callMemoOrStaticFn(
+      table,
+      'getCenterHeaderGroups',
+      table_getCenterHeaderGroups,
+    )[0]?.headers.reduce((sum: number, header: Header<TFeatures, TData>) => {
+      return sum + header_getSize(header)
+    }, 0) ?? 0
+  )
+}
+
+/**
+ * Sums the rendered size of the right pinned header region.
+ *
+ * An empty right pinning region returns `0`.
+ *
+ * @example
+ * ```ts
+ * const width = table_getRightTotalSize(table)
+ * ```
+ */
+export function table_getRightTotalSize<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+>(table: Table_Internal<TFeatures, TData>) {
+  return (
+    callMemoOrStaticFn(
+      table,
+      'getRightHeaderGroups',
+      table_getRightHeaderGroups,
+    )[0]?.headers.reduce((sum: number, header: Header<TFeatures, TData>) => {
+      return sum + header_getSize(header)
+    }, 0) ?? 0
+  )
+}