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

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

@@ -0,0 +1,220 @@
+import { flattenBy, tableMemo } from '../../utils'
+import { constructRow } from '../../core/rows/constructRow'
+import { table_getColumn } from '../../core/columns/coreColumnsFeature.utils'
+import { table_autoResetExpanded } from '../row-expanding/rowExpandingFeature.utils'
+import { table_autoResetPageIndex } from '../row-pagination/rowPaginationFeature.utils'
+import {
+  column_getAggregationFn,
+  row_getGroupingValue,
+} from './columnGroupingFeature.utils'
+import type { Column } from '../../types/Column'
+import type {
+  AggregationFn,
+  AggregationFns,
+  Row_ColumnGrouping,
+} from './columnGroupingFeature.types'
+import type { TableFeatures } from '../../types/TableFeatures'
+import type { RowModel } from '../../core/row-models/coreRowModelsFeature.types'
+import type { Table, Table_Internal } from '../../types/Table'
+import type { Row } from '../../types/Row'
+import type { RowData } from '../../types/type-utils'
+
+/**
+ * Creates a memoized grouped row model factory.
+ *
+ * The factory reads the relevant table state atoms and options, then returns a row model function used by the table row-model pipeline.
+ */
+export function createGroupedRowModel<
+  TFeatures extends TableFeatures,
+  TData extends RowData = any,
+>(
+  aggregationFns: Record<keyof AggregationFns, AggregationFn<TFeatures, TData>>,
+): (table: Table<TFeatures, TData>) => () => RowModel<TFeatures, TData> {
+  return (_table) => {
+    const table: Table_Internal<TFeatures, TData> = _table
+    if (!table._rowModelFns.aggregationFns)
+      table._rowModelFns.aggregationFns = aggregationFns
+    return tableMemo({
+      feature: 'columnGroupingFeature',
+      table,
+      fnName: 'table.getGroupedRowModel',
+      memoDeps: () => [
+        table.atoms.grouping?.get(),
+        table.getPreGroupedRowModel(),
+      ],
+      fn: () => _createGroupedRowModel(table),
+      onAfterUpdate: () => {
+        table_autoResetExpanded(table)
+        table_autoResetPageIndex(table)
+      },
+    })
+  }
+}
+
+function _createGroupedRowModel<
+  TFeatures extends TableFeatures,
+  TData extends RowData = any,
+>(table: Table_Internal<TFeatures, TData>): RowModel<TFeatures, TData> {
+  const rowModel = table.getPreGroupedRowModel()
+  const grouping = table.atoms.grouping?.get()
+
+  if (!rowModel.rows.length || !grouping?.length) {
+    rowModel.rows.forEach((row) => {
+      row.depth = 0
+      row.parentId = undefined
+    })
+    return rowModel
+  }
+
+  // Filter the grouping list down to columns that exist
+  const existingGrouping = grouping.filter((columnId) =>
+    table_getColumn(table, columnId),
+  )
+
+  const groupedFlatRows: Array<Row<TFeatures, TData>> &
+    Partial<Row_ColumnGrouping> = []
+  const groupedRowsById: Record<string, Row<TFeatures, TData>> = {}
+
+  // Recursively group the data
+  const groupUpRecursively = (
+    rows: Array<Row<TFeatures, TData>>,
+    depth = 0,
+    parentId?: string,
+  ) => {
+    // Grouping depth has been been met
+    // Stop grouping and simply rewrite thd depth and row relationships
+    if (depth >= existingGrouping.length) {
+      return rows.map((row) => {
+        row.depth = depth
+
+        groupedFlatRows.push(row)
+        groupedRowsById[row.id] = row
+
+        if (row.subRows.length) {
+          row.subRows = groupUpRecursively(row.subRows, depth + 1, row.id)
+        }
+
+        return row
+      })
+    }
+
+    const columnId = existingGrouping[depth] as string
+
+    // Group the rows together for this level
+    const rowGroupsMap = groupBy(rows, columnId)
+
+    // Perform aggregations for each group
+    const aggregatedGroupedRows = Array.from(rowGroupsMap.entries()).map(
+      ([groupingValue, groupedRows], index) => {
+        let id = `${columnId}:${groupingValue}`
+        id = parentId ? `${parentId}>${id}` : id
+
+        // First, Recurse to group sub rows before aggregation
+        const subRows = groupUpRecursively(groupedRows, depth + 1, id)
+
+        subRows.forEach((subRow) => {
+          subRow.parentId = id
+        })
+
+        // Flatten the leaf rows of the rows in this group
+        const leafRows = depth
+          ? flattenBy(groupedRows, (row) => row.subRows)
+          : groupedRows
+
+        const row = constructRow(
+          table,
+          id,
+          leafRows[0]!.original,
+          index,
+          depth,
+          undefined,
+          parentId,
+        ) as Row<TFeatures, TData> & Partial<Row_ColumnGrouping>
+
+        Object.assign(row, {
+          groupingColumnId: columnId,
+          groupingValue,
+          subRows,
+          leafRows,
+          getValue: (colId: string) => {
+            // Don't aggregate columns that are in the grouping
+            if (existingGrouping.includes(colId)) {
+              if (row._valuesCache.hasOwnProperty(colId)) {
+                return row._valuesCache[colId]
+              }
+
+              if (groupedRows[0]) {
+                row._valuesCache[colId] =
+                  groupedRows[0].getValue(colId) ?? undefined
+              }
+
+              return row._valuesCache[colId]
+            }
+
+            if (row._groupingValuesCache?.hasOwnProperty(colId)) {
+              return row._groupingValuesCache[colId]
+            }
+
+            // Aggregate the values
+            const column = table.getColumn(colId)
+            const aggregateFn = column_getAggregationFn(
+              column as Column<TFeatures, TData, unknown>,
+            )
+
+            if (!row._groupingValuesCache) row._groupingValuesCache = {}
+
+            if (aggregateFn) {
+              row._groupingValuesCache[colId] = aggregateFn(
+                colId,
+                leafRows,
+                groupedRows,
+              )
+
+              return row._groupingValuesCache[colId]
+            }
+          },
+        })
+
+        subRows.forEach((subRow) => {
+          groupedFlatRows.push(subRow)
+          groupedRowsById[subRow.id] = subRow
+        })
+
+        return row
+      },
+    )
+
+    return aggregatedGroupedRows
+  }
+
+  const groupedRows = groupUpRecursively(rowModel.rows, 0)
+
+  groupedRows.forEach((subRow) => {
+    groupedFlatRows.push(subRow)
+    groupedRowsById[subRow.id] = subRow
+  })
+
+  return {
+    rows: groupedRows,
+    flatRows: groupedFlatRows,
+    rowsById: groupedRowsById,
+  }
+}
+
+function groupBy<TFeatures extends TableFeatures, TData extends RowData = any>(
+  rows: Array<Row<TFeatures, TData>>,
+  columnId: string,
+) {
+  const groupMap = new Map<any, Array<Row<TFeatures, TData>>>()
+
+  return rows.reduce((map, row) => {
+    const resKey = `${row_getGroupingValue(row, columnId)}`
+    const previous = map.get(resKey)
+    if (!previous) {
+      map.set(resKey, [row])
+    } else {
+      previous.push(row)
+    }
+    return map
+  }, groupMap)
+}

package/src/features/column-ordering/columnOrderingFeature.ts

@@ -0,0 +1,105 @@
+import {
+  assignPrototypeAPIs,
+  assignTableAPIs,
+  makeStateUpdater,
+} from '../../utils'
+import {
+  column_getIndex,
+  column_getIsFirstColumn,
+  column_getIsLastColumn,
+  getDefaultColumnOrderState,
+  table_getOrderColumnsFn,
+  table_resetColumnOrder,
+  table_setColumnOrder,
+} from './columnOrderingFeature.utils'
+import type { RowData } from '../../types/type-utils'
+import type { TableFeature, TableFeatures } from '../../types/TableFeatures'
+// import type {
+//   Column_ColumnOrdering,
+//   TableOptions_ColumnOrdering,
+//   TableState_ColumnOrdering,
+//   Table_ColumnOrdering,
+// } from './columnOrderingFeature.types'
+
+export interface ColumnOrderingFeatureConstructors<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+> {
+  // Column: Column_ColumnOrdering
+  // Table: Table_ColumnOrdering<TFeatures, TData>
+  // TableOptions: TableOptions_ColumnOrdering
+  // TableState: TableState_ColumnOrdering
+}
+
+/**
+ * Creates the stock column ordering feature.
+ *
+ * The returned feature registers its state defaults, option defaults, and instance APIs so it can be included in a `tableFeatures({ ... })` call.
+ */
+export function constructColumnOrderingFeature<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+>(): TableFeature<ColumnOrderingFeatureConstructors<TFeatures, TData>> {
+  return {
+    getInitialState: (initialState) => {
+      return {
+        columnOrder: getDefaultColumnOrderState(),
+        ...initialState,
+      }
+    },
+
+    getDefaultTableOptions: (table) => {
+      return {
+        onColumnOrderChange: makeStateUpdater('columnOrder', table),
+      }
+    },
+
+    assignColumnPrototype: (prototype, table) => {
+      assignPrototypeAPIs('columnOrderingFeature', prototype, table, {
+        column_getIndex: {
+          fn: (column, position) => column_getIndex(column, position),
+          memoDeps: (column, position) => [
+            position,
+            column.table.atoms.columnOrder?.get(),
+            column.table.atoms.columnPinning?.get(),
+            column.table.atoms.grouping?.get(),
+            column.table.atoms.columnVisibility?.get(),
+          ],
+        },
+        column_getIsFirstColumn: {
+          fn: (column, position) => column_getIsFirstColumn(column, position),
+        },
+        column_getIsLastColumn: {
+          fn: (column, position) => column_getIsLastColumn(column, position),
+        },
+      })
+    },
+
+    constructTableAPIs: (table) => {
+      assignTableAPIs('columnOrderingFeature', table, {
+        table_setColumnOrder: {
+          fn: (updater) => table_setColumnOrder(table, updater),
+        },
+        table_resetColumnOrder: {
+          fn: (defaultState) => table_resetColumnOrder(table, defaultState),
+        },
+        table_getOrderColumnsFn: {
+          fn: () => table_getOrderColumnsFn(table),
+          memoDeps: () => [
+            table.atoms.columnOrder?.get(),
+            table.atoms.grouping?.get(),
+            table.options.groupedColumnMode,
+          ],
+        },
+      })
+    },
+  }
+}
+
+/**
+ * The stock column ordering feature.
+ *
+ * Register this feature to add column order state and APIs for deriving the
+ * ordered leaf column list alongside grouping and pinning.
+ */
+export const columnOrderingFeature = constructColumnOrderingFeature()

package/src/features/column-ordering/columnOrderingFeature.types.ts

@@ -0,0 +1,60 @@
+import type { OnChangeFn, RowData, Updater } from '../../types/type-utils'
+import type { TableFeatures } from '../../types/TableFeatures'
+import type { ColumnPinningPosition } from '../column-pinning/columnPinningFeature.types'
+
+export type ColumnOrderState = Array<string>
+
+export interface TableState_ColumnOrdering {
+  columnOrder: ColumnOrderState
+}
+
+export interface TableOptions_ColumnOrdering {
+  /**
+   * Called with an updater when column order state changes. Pair this with
+   * `state.columnOrder` when using external state; external atoms can own the
+   * slice without this callback.
+   */
+  onColumnOrderChange?: OnChangeFn<ColumnOrderState>
+}
+
+export interface Column_ColumnOrdering {
+  /**
+   * Finds this column's zero-based index among visible columns.
+   *
+   * Pass `'left'`, `'center'`, or `'right'` to measure within that pinned
+   * region instead of the full visible leaf order.
+   */
+  getIndex: (position?: ColumnPinningPosition | 'center') => number
+  /**
+   * Checks whether this column is the first visible column.
+   *
+   * Pass a pinned region to check the first column within that region.
+   */
+  getIsFirstColumn: (position?: ColumnPinningPosition | 'center') => boolean
+  /**
+   * Checks whether this column is the last visible column.
+   *
+   * Pass a pinned region to check the last column within that region.
+   */
+  getIsLastColumn: (position?: ColumnPinningPosition | 'center') => boolean
+}
+
+export interface ColumnOrderDefaultOptions {
+  onColumnOrderChange: OnChangeFn<ColumnOrderState>
+}
+
+export interface Table_ColumnOrdering<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+> {
+  /**
+   * Resets `columnOrder` to `initialState.columnOrder`.
+   *
+   * Pass `true` to ignore initial state and reset to `[]`.
+   */
+  resetColumnOrder: (defaultState?: boolean) => void
+  /**
+   * Updates column order state with a next ordered id array or updater function.
+   */
+  setColumnOrder: (updater: Updater<ColumnOrderState>) => void
+}

package/src/features/column-ordering/columnOrderingFeature.utils.ts

@@ -0,0 +1,241 @@
+import { table_getPinnedVisibleLeafColumns } from '../column-pinning/columnPinningFeature.utils'
+import { cloneState } from '../../utils'
+import type { GroupingState } from '../column-grouping/columnGroupingFeature.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 { Column_Internal } from '../../types/Column'
+import type { ColumnPinningPosition } from '../column-pinning/columnPinningFeature.types'
+import type { ColumnOrderState } from './columnOrderingFeature.types'
+
+/**
+ * Creates the default column order state.
+ *
+ * The feature default is an empty array, meaning leaf columns keep their natural
+ * definition order. Reset APIs use this value when `defaultState` is `true`.
+ *
+ * @example
+ * ```ts
+ * const order = getDefaultColumnOrderState()
+ * ```
+ */
+export function getDefaultColumnOrderState(): ColumnOrderState {
+  return []
+}
+
+/**
+ * Finds this column's index within a visible pinning region.
+ *
+ * Pass `'left'`, `'center'`, or `'right'` to search that region; omit the
+ * position to search the full visible leaf column list.
+ *
+ * @example
+ * ```ts
+ * const index = column_getIndex(column, 'center')
+ * ```
+ */
+export function column_getIndex<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+  TValue extends CellData = CellData,
+>(
+  column: Column_Internal<TFeatures, TData, TValue>,
+  position?: ColumnPinningPosition | 'center',
+) {
+  const columns = table_getPinnedVisibleLeafColumns(column.table, position)
+  return columns.findIndex((d) => d.id === column.id)
+}
+
+/**
+ * Checks whether this column is the first visible column in a pinning region.
+ *
+ * The same `position` semantics as `column_getIndex` apply.
+ *
+ * @example
+ * ```ts
+ * const isFirst = column_getIsFirstColumn(column, 'left')
+ * ```
+ */
+export function column_getIsFirstColumn<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+  TValue extends CellData = CellData,
+>(
+  column: Column_Internal<TFeatures, TData, TValue>,
+  position?: ColumnPinningPosition | 'center',
+) {
+  const columns = table_getPinnedVisibleLeafColumns(column.table, position)
+  return columns[0]?.id === column.id
+}
+
+/**
+ * Checks whether this column is the last visible column in a pinning region.
+ *
+ * The same `position` semantics as `column_getIndex` apply.
+ *
+ * @example
+ * ```ts
+ * const isLast = column_getIsLastColumn(column, 'right')
+ * ```
+ */
+export function column_getIsLastColumn<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+  TValue extends CellData = CellData,
+>(
+  column: Column_Internal<TFeatures, TData, TValue>,
+  position?: ColumnPinningPosition | 'center',
+) {
+  const columns = table_getPinnedVisibleLeafColumns(column.table, position)
+  return columns[columns.length - 1]?.id === column.id
+}
+
+/**
+ * Routes a column order updater through the table's column-order change handler.
+ *
+ * The updater may be a next ordered id array or a function of the previous
+ * array, matching the instance `table.setColumnOrder` behavior.
+ *
+ * @example
+ * ```ts
+ * table_setColumnOrder(table, ['firstName', 'lastName', 'age'])
+ * ```
+ */
+export function table_setColumnOrder<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+>(table: Table_Internal<TFeatures, TData>, updater: Updater<ColumnOrderState>) {
+  table.options.onColumnOrderChange?.(updater)
+}
+
+/**
+ * Resets `columnOrder` to the configured initial state or feature default.
+ *
+ * With no argument, the reset clones `table.initialState.columnOrder` when it
+ * exists. Passing `true` ignores initial state and resets to `[]`.
+ *
+ * @example
+ * ```ts
+ * table_resetColumnOrder(table)
+ * table_resetColumnOrder(table, true)
+ * ```
+ */
+export function table_resetColumnOrder<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+>(table: Table_Internal<TFeatures, TData>, defaultState?: boolean) {
+  table_setColumnOrder(
+    table,
+    defaultState ? [] : cloneState(table.initialState.columnOrder ?? []),
+  )
+}
+
+/**
+ * Creates the ordering function used to arrange leaf columns.
+ *
+ * The returned function applies `state.columnOrder`, preserves unspecified
+ * columns in their original order, then delegates to grouping rules.
+ *
+ * @example
+ * ```ts
+ * const orderColumnsForTable = table_getOrderColumnsFn(table)
+ * ```
+ */
+export function table_getOrderColumnsFn<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+>(table: Table_Internal<TFeatures, TData>) {
+  const columnOrder = table.atoms.columnOrder?.get()
+
+  return (columns: Array<Column_Internal<TFeatures, TData, unknown>>) => {
+    // Sort grouped columns to the start of the column list
+    // before the headers are built
+    let orderedColumns: Array<Column_Internal<TFeatures, TData, unknown>> = []
+
+    // If there is no order, return the normal columns
+    if (!columnOrder?.length) {
+      orderedColumns = columns
+    } else {
+      // Index columns by id for O(1) lookup
+      const remaining = new Map<
+        string,
+        Column_Internal<TFeatures, TData, unknown>
+      >()
+      for (let i = 0; i < columns.length; i++) {
+        const column = columns[i]!
+        remaining.set(column.id, column)
+      }
+
+      // Place columns in the requested order, removing each as it's used
+      // (handles duplicates and unknown ids in columnOrder)
+      for (let i = 0; i < columnOrder.length; i++) {
+        const id = columnOrder[i]!
+        const column = remaining.get(id)
+        if (column) {
+          orderedColumns.push(column)
+          remaining.delete(id)
+        }
+      }
+
+      // Append leftover columns in their original order
+      for (let i = 0; i < columns.length; i++) {
+        const column = columns[i]!
+        if (remaining.has(column.id)) orderedColumns.push(column)
+      }
+    }
+
+    return orderColumns(table, orderedColumns)
+  }
+}
+
+/**
+ * Applies grouped-column placement rules to an already ordered leaf-column list.
+ *
+ * `groupedColumnMode: 'remove'` drops grouped columns from the list.
+ * `groupedColumnMode: 'reorder'` moves grouped columns to the front in grouping
+ * state order.
+ *
+ * @example
+ * ```ts
+ * const orderedColumns = orderColumns(table, leafColumns)
+ * ```
+ */
+export function orderColumns<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+>(
+  table: Table_Internal<TFeatures, TData>,
+  leafColumns: Array<Column_Internal<TFeatures, TData, unknown>>,
+) {
+  const grouping = table.atoms.grouping?.get() ?? ([] as GroupingState)
+  const { groupedColumnMode } = table.options
+
+  if (!grouping.length || !groupedColumnMode) {
+    return leafColumns
+  }
+
+  const nonGroupingColumns = leafColumns.filter(
+    (col) => !grouping.includes(col.id),
+  )
+
+  if (groupedColumnMode === 'remove') {
+    return nonGroupingColumns
+  }
+
+  const leafColumnsById = new Map<
+    string,
+    Column_Internal<TFeatures, TData, unknown>
+  >()
+  for (let i = 0; i < leafColumns.length; i++) {
+    const col = leafColumns[i]!
+    leafColumnsById.set(col.id, col)
+  }
+
+  const groupingColumns: Array<Column_Internal<TFeatures, TData, unknown>> = []
+  for (let i = 0; i < grouping.length; i++) {
+    const col = leafColumnsById.get(grouping[i]!)
+    if (col) groupingColumns.push(col)
+  }
+
+  return [...groupingColumns, ...nonGroupingColumns]
+}