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

package/src/features/column-grouping/columnGroupingFeature.types.ts

@@ -0,0 +1,226 @@
+import type { RowModel } from '../../core/row-models/coreRowModelsFeature.types'
+import type { Table } from '../../types/Table'
+import type { BuiltInAggregationFn } from '../../fns/aggregationFns'
+import type {
+  CellData,
+  OnChangeFn,
+  RowData,
+  Updater,
+} from '../../types/type-utils'
+import type { TableFeatures } from '../../types/TableFeatures'
+import type { Row } from '../../types/Row'
+import type { Cell } from '../../types/Cell'
+import type { ColumnDefTemplate } from '../../types/ColumnDef'
+
+export type GroupingState = Array<string>
+
+export interface TableState_ColumnGrouping {
+  grouping: GroupingState
+}
+
+export interface RowModelFns_ColumnGrouping<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+> {
+  aggregationFns: Record<keyof AggregationFns, AggregationFn<TFeatures, TData>>
+}
+
+export interface AggregationFns {}
+
+export type AggregationFn<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+> = (
+  columnId: string,
+  leafRows: Array<Row<TFeatures, TData>>,
+  childRows: Array<Row<TFeatures, TData>>,
+) => any
+
+export type CustomAggregationFns<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+> = Record<string, AggregationFn<TFeatures, TData>>
+
+export type AggregationFnOption<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+> =
+  | 'auto'
+  | keyof AggregationFns
+  | BuiltInAggregationFn
+  | AggregationFn<TFeatures, TData>
+
+export interface ColumnDef_ColumnGrouping<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+  TValue extends CellData = CellData,
+> {
+  /**
+   * The cell to display each row for the column if the cell is an aggregate. If a function is passed, it will be passed a props object with the context of the cell and should return the property type for your adapter (the exact type depends on the adapter being used).
+   */
+  aggregatedCell?: ColumnDefTemplate<
+    ReturnType<Cell<TFeatures, TData, TValue>['getContext']>
+  >
+  /**
+   * The resolved aggregation function for the column.
+   */
+  aggregationFn?: AggregationFnOption<TFeatures, TData>
+  /**
+   * Allows this column to be added to grouping state.
+   *
+   * Defaults to `true`; table-level `enableGrouping` must also allow grouping.
+   */
+  enableGrouping?: boolean
+  /**
+   * Specify a value to be used for grouping rows on this column. If this option is not specified, the value derived from `accessorKey` / `accessorFn` will be used instead.
+   */
+  getGroupingValue?: (row: TData) => any
+}
+
+export interface Column_ColumnGrouping<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+> {
+  /**
+   * Returns the aggregation function for the column.
+   */
+  getAggregationFn: () => AggregationFn<TFeatures, TData> | undefined
+  /**
+   * Returns the automatically inferred aggregation function for the column.
+   */
+  getAutoAggregationFn: () => AggregationFn<TFeatures, TData> | undefined
+  /**
+   * Checks whether this column can currently be grouped.
+   */
+  getCanGroup: () => boolean
+  /**
+   * Finds this column's position in the ordered grouping state.
+   */
+  getGroupedIndex: () => number
+  /**
+   * Checks whether this column id is present in grouping state.
+   */
+  getIsGrouped: () => boolean
+  /**
+   * Returns a function that toggles the grouping state of the column. This is useful for passing to the `onClick` prop of a button.
+   */
+  getToggleGroupingHandler: () => () => void
+  /**
+   * Toggles the grouping state of the column.
+   */
+  toggleGrouping: () => void
+}
+
+export interface Row_ColumnGrouping {
+  _groupingValuesCache: Record<string, any>
+  /**
+   * Reads the value used to group this row for a column id.
+   */
+  getGroupingValue: (columnId: string) => unknown
+  /**
+   * Checks whether this row represents a grouped row.
+   */
+  getIsGrouped: () => boolean
+  /**
+   * If this row is grouped, this is the id of the column that this row is grouped by.
+   */
+  groupingColumnId?: string
+  /**
+   * If this row is grouped, this is the unique/shared value for the `groupingColumnId` for all of the rows in this group.
+   */
+  groupingValue?: unknown
+}
+
+export interface Cell_ColumnGrouping {
+  /**
+   * Checks whether this cell should render an aggregated value.
+   */
+  getIsAggregated: () => boolean
+  /**
+   * Checks whether this cell represents the active grouping column.
+   */
+  getIsGrouped: () => boolean
+  /**
+   * Checks whether this cell is hidden as a grouping placeholder.
+   */
+  getIsPlaceholder: () => boolean
+}
+
+export interface ColumnDefaultOptions {
+  enableGrouping: boolean
+  onGroupingChange: OnChangeFn<GroupingState>
+}
+
+export interface TableOptions_ColumnGrouping {
+  /**
+   * Allows columns to be grouped for this table.
+   */
+  enableGrouping?: boolean
+  /**
+   * Grouping columns are automatically reordered by default to the start of the columns list. If you would rather remove them or leave them as-is, set the appropriate mode here.
+   */
+  groupedColumnMode?: false | 'reorder' | 'remove'
+  /**
+   * Enables manual grouping. If this option is set to `true`, the table will not automatically group rows using `getGroupedRowModel()` and instead will expect you to manually group the rows before passing them to the table. This is useful if you are doing server-side grouping and aggregation.
+   */
+  manualGrouping?: boolean
+  /**
+   * Called with an updater when grouping state changes. Pair this with
+   * `state.grouping` when using external state; external atoms can own the
+   * slice without this callback.
+   */
+  onGroupingChange?: OnChangeFn<GroupingState>
+}
+
+export type GroupingColumnMode = false | 'reorder' | 'remove'
+
+export interface Table_ColumnGrouping<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+> {
+  /**
+   * Resets `grouping` to `initialState.grouping`.
+   *
+   * Pass `true` to ignore initial state and reset to `[]`.
+   */
+  resetGrouping: (defaultState?: boolean) => void
+  /**
+   * Updates grouping state with a next ordered id array or updater function.
+   */
+  setGrouping: (updater: Updater<GroupingState>) => void
+}
+
+export interface Table_RowModels_Grouped<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+> {
+  /**
+   * Resolves the row model after grouping and aggregation have been applied.
+   */
+  getGroupedRowModel: () => RowModel<TFeatures, TData>
+  /**
+   * Reads the row model immediately before grouping.
+   */
+  getPreGroupedRowModel: () => RowModel<TFeatures, TData>
+}
+
+export interface CreateRowModel_Grouped<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+> {
+  /**
+   * Factory used to retrieve the grouped row model. If using server-side
+   * grouping, this is not required. To use client-side grouping, pass
+   * `createGroupedRowModel()` or implement your own factory.
+   */
+  groupedRowModel?: (
+    table: Table<TFeatures, TData>,
+  ) => () => RowModel<TFeatures, TData>
+}
+
+export interface CachedRowModel_Grouped<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+> {
+  groupedRowModel: () => RowModel<TFeatures, TData>
+}

package/src/features/column-grouping/columnGroupingFeature.utils.ts

@@ -0,0 +1,354 @@
+import { cloneState, isFunction } from '../../utils'
+import type { Column_Internal } from '../../types/Column'
+import type { CellData, RowData, Updater } from '../../types/type-utils'
+import type { TableFeatures } from '../../types/TableFeatures'
+import type { Table_Internal } from '../../types/Table'
+import type { Row } from '../../types/Row'
+import type { Cell } from '../../types/Cell'
+import type {
+  AggregationFn,
+  GroupingState,
+  Row_ColumnGrouping,
+} from './columnGroupingFeature.types'
+
+/**
+ * Creates the default grouping state.
+ *
+ * The feature default is an empty array, meaning no columns are grouped. Reset
+ * APIs use this value when `defaultState` is `true`.
+ *
+ * @example
+ * ```ts
+ * const grouping = getDefaultGroupingState()
+ * ```
+ */
+export function getDefaultGroupingState(): GroupingState {
+  return []
+}
+
+/**
+ * Adds or removes this column id from the grouping state.
+ *
+ * Existing grouped columns keep their order. A column already present in
+ * `state.grouping` is removed; otherwise it is appended.
+ *
+ * @example
+ * ```ts
+ * column_toggleGrouping(column)
+ * ```
+ */
+export function column_toggleGrouping<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+  TValue extends CellData = CellData,
+>(column: Column_Internal<TFeatures, TData, TValue>) {
+  table_setGrouping(column.table, (old) => {
+    // Find any existing grouping for this column
+    if (old.includes(column.id)) {
+      return old.filter((d) => d !== column.id)
+    }
+
+    return [...old, column.id]
+  })
+}
+
+/**
+ * Checks whether this column can be used for grouping.
+ *
+ * Grouping must be enabled at the column and table level, and the column must
+ * either have an accessor or provide `getGroupingValue`.
+ *
+ * @example
+ * ```ts
+ * const canGroup = column_getCanGroup(column)
+ * ```
+ */
+export function column_getCanGroup<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+  TValue extends CellData = CellData,
+>(column: Column_Internal<TFeatures, TData, TValue>) {
+  return (
+    (column.columnDef.enableGrouping ?? true) &&
+    (column.table.options.enableGrouping ?? true) &&
+    (!!column.accessorFn || !!column.columnDef.getGroupingValue)
+  )
+}
+
+/**
+ * Checks whether this column id is present in `state.grouping`.
+ *
+ * The result only reflects grouping state, not whether the grouped row model has
+ * been calculated yet.
+ *
+ * @example
+ * ```ts
+ * const isGrouped = column_getIsGrouped(column)
+ * ```
+ */
+export function column_getIsGrouped<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+  TValue extends CellData = CellData,
+>(column: Column_Internal<TFeatures, TData, TValue>): boolean {
+  return !!column.table.atoms.grouping?.get()?.includes(column.id)
+}
+
+/**
+ * Finds this column's position in the ordered grouping state.
+ *
+ * The result is `-1` when the column is not grouped.
+ *
+ * @example
+ * ```ts
+ * const index = column_getGroupedIndex(column)
+ * ```
+ */
+export function column_getGroupedIndex<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+  TValue extends CellData = CellData,
+>(column: Column_Internal<TFeatures, TData, TValue>): number {
+  return column.table.atoms.grouping?.get()?.indexOf(column.id) ?? -1
+}
+
+/**
+ * Creates a header/control handler that toggles grouping for this column.
+ *
+ * The handler is a no-op when `column_getCanGroup(column)` is false.
+ *
+ * @example
+ * ```ts
+ * const onClick = column_getToggleGroupingHandler(column)
+ * ```
+ */
+export function column_getToggleGroupingHandler<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+  TValue extends CellData = CellData,
+>(column: Column_Internal<TFeatures, TData, TValue>) {
+  const canGroup = column_getCanGroup(column)
+
+  return () => {
+    if (!canGroup) return
+    column_toggleGrouping(column)
+  }
+}
+
+/**
+ * Chooses a built-in aggregation function from the first core row value.
+ *
+ * Numeric columns default to `sum`, date-like values default to `extent`, and
+ * other value types leave aggregation unspecified.
+ *
+ * @example
+ * ```ts
+ * const aggregationFn = column_getAutoAggregationFn(column)
+ * ```
+ */
+export function column_getAutoAggregationFn<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+  TValue extends CellData = CellData,
+>(column: Column_Internal<TFeatures, TData, TValue>) {
+  const aggregationFns:
+    | Record<string, AggregationFn<TFeatures, TData>>
+    | undefined = column.table._rowModelFns.aggregationFns
+
+  const firstRow = column.table.getCoreRowModel().flatRows[0]
+
+  const value = firstRow?.getValue(column.id)
+
+  if (typeof value === 'number') {
+    return aggregationFns?.sum
+  }
+
+  if (Object.prototype.toString.call(value) === '[object Date]') {
+    return aggregationFns?.extent
+  }
+}
+
+/**
+ * Resolves the aggregation function configured for a column.
+ *
+ * Function-valued `columnDef.aggregationFn` is returned directly, `'auto'`
+ * delegates to `column_getAutoAggregationFn`, and string values are looked up in
+ * the table's aggregation function registry.
+ *
+ * @example
+ * ```ts
+ * const aggregationFn = column_getAggregationFn(column)
+ * ```
+ */
+export function column_getAggregationFn<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+  TValue extends CellData = CellData,
+>(column: Column_Internal<TFeatures, TData, TValue>) {
+  const aggregationFns:
+    | Record<string, AggregationFn<TFeatures, TData>>
+    | undefined = column.table._rowModelFns.aggregationFns
+
+  return isFunction(column.columnDef.aggregationFn)
+    ? column.columnDef.aggregationFn
+    : column.columnDef.aggregationFn === 'auto'
+      ? column_getAutoAggregationFn(column)
+      : aggregationFns?.[column.columnDef.aggregationFn as string]
+}
+
+/**
+ * Routes a grouping updater through the table's grouping change handler.
+ *
+ * The updater may be a next `GroupingState` array or a function of the previous
+ * grouping state, matching the instance `table.setGrouping` behavior.
+ *
+ * @example
+ * ```ts
+ * table_setGrouping(table, (old) => [...old, 'status'])
+ * ```
+ */
+export function table_setGrouping<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+>(table: Table_Internal<TFeatures, TData>, updater: Updater<GroupingState>) {
+  table.options.onGroupingChange?.(updater)
+}
+
+/**
+ * Resets `grouping` to the configured initial state or feature default.
+ *
+ * With no argument, the reset clones `table.initialState.grouping` when it
+ * exists. Passing `true` ignores initial state and resets to `[]`.
+ *
+ * @example
+ * ```ts
+ * table_resetGrouping(table)
+ * table_resetGrouping(table, true)
+ * ```
+ */
+export function table_resetGrouping<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+>(table: Table_Internal<TFeatures, TData>, defaultState?: boolean) {
+  table_setGrouping(
+    table,
+    defaultState ? [] : cloneState(table.initialState.grouping ?? []),
+  )
+}
+
+/**
+ * Checks whether this row was created as a grouped row.
+ *
+ * Grouped rows carry a `groupingColumnId`; ordinary leaf rows do not.
+ *
+ * @example
+ * ```ts
+ * const isGrouped = row_getIsGrouped(row)
+ * ```
+ */
+export function row_getIsGrouped<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+>(row: Row<TFeatures, TData> & Partial<Row_ColumnGrouping>) {
+  return !!row.groupingColumnId
+}
+
+/**
+ * Reads and caches this row's grouping value for a column.
+ *
+ * `columnDef.getGroupingValue` wins when provided; otherwise the normal row
+ * accessor value is used.
+ *
+ * @example
+ * ```ts
+ * const groupValue = row_getGroupingValue(row, 'status')
+ * ```
+ */
+export function row_getGroupingValue<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+>(row: Row<TFeatures, TData> & Partial<Row_ColumnGrouping>, columnId: string) {
+  if (row._groupingValuesCache?.hasOwnProperty(columnId)) {
+    return row._groupingValuesCache[columnId]
+  }
+
+  const column = row.table.getColumn(columnId) as Column_Internal<
+    TFeatures,
+    TData
+  >
+
+  if (!column.columnDef.getGroupingValue) {
+    return row.getValue(columnId)
+  }
+
+  if (row._groupingValuesCache) {
+    row._groupingValuesCache[columnId] = column.columnDef.getGroupingValue(
+      row.original,
+    )
+  }
+
+  return row._groupingValuesCache?.[columnId]
+}
+
+/**
+ * Checks whether this cell represents the grouped column for a grouped row.
+ *
+ * This is the cell that usually renders the grouped value and expansion control.
+ *
+ * @example
+ * ```ts
+ * const isGroupedCell = cell_getIsGrouped(cell)
+ * ```
+ */
+export function cell_getIsGrouped<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+  TValue extends CellData = CellData,
+>(cell: Cell<TFeatures, TData, TValue>) {
+  const row = cell.row as Row<TFeatures, TData> & Partial<Row_ColumnGrouping>
+  return (
+    column_getIsGrouped(cell.column) && cell.column.id === row.groupingColumnId
+  )
+}
+
+/**
+ * Checks whether this cell is a placeholder hidden by grouping.
+ *
+ * Placeholder cells belong to grouped columns other than the row's active
+ * grouping column.
+ *
+ * @example
+ * ```ts
+ * const isPlaceholder = cell_getIsPlaceholder(cell)
+ * ```
+ */
+export function cell_getIsPlaceholder<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+  TValue extends CellData = CellData,
+>(cell: Cell<TFeatures, TData, TValue>) {
+  return !cell_getIsGrouped(cell) && column_getIsGrouped(cell.column)
+}
+
+/**
+ * Checks whether this cell should render an aggregated value.
+ *
+ * Aggregated cells are non-placeholder, non-grouped cells on rows that have
+ * subRows.
+ *
+ * @example
+ * ```ts
+ * const isAggregated = cell_getIsAggregated(cell)
+ * ```
+ */
+export function cell_getIsAggregated<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+  TValue extends CellData = CellData,
+>(cell: Cell<TFeatures, TData, TValue>) {
+  return (
+    !cell_getIsGrouped(cell) &&
+    !cell_getIsPlaceholder(cell) &&
+    !!cell.row.subRows.length
+  )
+}