@tanstack/table-core 9.0.0-beta.9 → 9.0.1

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

@@ -1,115 +0,0 @@
-import {
-  assignPrototypeAPIs,
-  assignTableAPIs,
-  makeStateUpdater,
-} from '../../utils'
-import {
-  cell_getIsAggregated,
-  cell_getIsGrouped,
-  cell_getIsPlaceholder,
-  column_getAggregationFn,
-  column_getAutoAggregationFn,
-  column_getCanGroup,
-  column_getGroupedIndex,
-  column_getIsGrouped,
-  column_getToggleGroupingHandler,
-  column_toggleGrouping,
-  getDefaultGroupingState,
-  row_getGroupingValue,
-  row_getIsGrouped,
-  table_resetGrouping,
-  table_setGrouping,
-} from './columnGroupingFeature.utils'
-import type { TableFeature } from '../../types/TableFeatures'
-
-/**
- * Feature that adds column grouping state, aggregation defaults, and grouped row APIs.
- */
-export const columnGroupingFeature: TableFeature = {
-  getInitialState: (initialState) => {
-    return {
-      grouping: getDefaultGroupingState(),
-      ...initialState,
-    }
-  },
-
-  getDefaultColumnDef: () => {
-    return {
-      aggregatedCell: ({ getValue }: any) => getValue()?.toString?.() ?? null,
-      aggregationFn: 'auto',
-    }
-  },
-
-  getDefaultTableOptions: (table) => {
-    return {
-      onGroupingChange: makeStateUpdater('grouping', table),
-      groupedColumnMode: 'reorder',
-    }
-  },
-
-  assignCellPrototype: (prototype, table) => {
-    assignPrototypeAPIs('columnGroupingFeature', prototype, table, {
-      cell_getIsGrouped: {
-        fn: (cell) => cell_getIsGrouped(cell),
-      },
-      cell_getIsPlaceholder: {
-        fn: (cell) => cell_getIsPlaceholder(cell),
-      },
-      cell_getIsAggregated: {
-        fn: (cell) => cell_getIsAggregated(cell),
-      },
-    })
-  },
-
-  assignColumnPrototype: (prototype, table) => {
-    assignPrototypeAPIs('columnGroupingFeature', prototype, table, {
-      column_toggleGrouping: {
-        fn: (column) => column_toggleGrouping(column),
-      },
-      column_getCanGroup: {
-        fn: (column) => column_getCanGroup(column),
-      },
-      column_getIsGrouped: {
-        fn: (column) => column_getIsGrouped(column),
-      },
-      column_getGroupedIndex: {
-        fn: (column) => column_getGroupedIndex(column),
-      },
-      column_getToggleGroupingHandler: {
-        fn: (column) => column_getToggleGroupingHandler(column),
-      },
-      column_getAutoAggregationFn: {
-        fn: (column) => column_getAutoAggregationFn(column),
-      },
-      column_getAggregationFn: {
-        fn: (column) => column_getAggregationFn(column),
-      },
-    })
-  },
-
-  assignRowPrototype: (prototype, table) => {
-    assignPrototypeAPIs('columnGroupingFeature', prototype, table, {
-      row_getIsGrouped: {
-        fn: (row) => row_getIsGrouped(row),
-      },
-      row_getGroupingValue: {
-        fn: (row, columnId) => row_getGroupingValue(row, columnId),
-      },
-    })
-  },
-
-  initRowInstanceData: (row) => {
-    ;(row as any)._groupingValuesCache = {}
-  },
-
-  constructTableAPIs: (table) => {
-    assignTableAPIs('columnGroupingFeature', table, {
-      table_setGrouping: {
-        fn: (updater) => table_setGrouping(table, updater),
-      },
-      table_resetGrouping: {
-        fn: (defaultState) => table_resetGrouping(table, defaultState),
-      },
-    })
-  },
-}

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

@@ -1,226 +0,0 @@
-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

@@ -1,354 +0,0 @@
-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
-  )
-}