@tanstack/table-core 9.0.0-alpha.0 → 9.0.0-alpha.11

package/src/core/table/coreTablesFeature.types.ts

@@ -0,0 +1,123 @@
+import type { Derived, Store } from '@tanstack/store'
+import type { CoreFeatures } from '../coreFeatures'
+import type { RowModelFns } from '../../types/RowModelFns'
+import type { RowData, Updater } from '../../types/type-utils'
+import type { TableFeatures } from '../../types/TableFeatures'
+import type { CachedRowModels, CreateRowModels_All } from '../../types/RowModel'
+import type { TableOptions } from '../../types/TableOptions'
+import type { TableState } from '../../types/TableState'
+
+export interface TableMeta<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+> {}
+
+export interface TableOptions_Table<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+> {
+  /**
+   * The features that you want to enable for the table.
+   */
+  _features: TFeatures
+  /**
+   * The row model options that you want to enable for the table.
+   */
+  _rowModels?: CreateRowModels_All<TFeatures, TData>
+  /**
+   * Set this option to override any of the `autoReset...` feature options.
+   */
+  autoResetAll?: boolean
+  /**
+   * The data for the table to display. When the `data` option changes reference, the table will reprocess the data.
+   */
+  data: Array<TData>
+  /**
+   * Use this option to optionally pass initial state to the table. This state will be used when resetting various table states either automatically by the table (eg. `options.autoResetPageIndex`) or via functions like `table.resetRowSelection()`. Most reset function allow you optionally pass a flag to reset to a blank/default state instead of the initial state.
+   * Table state will not be reset when this object changes, which also means that the initial state object does not need to be stable.
+   */
+  initialState?: Partial<TableState<TFeatures>>
+  /**
+   * This option is used to optionally implement the merging of table options.
+   */
+  mergeOptions?: (
+    defaultOptions: TableOptions<TFeatures, TData>,
+    options: Partial<TableOptions<TFeatures, TData>>,
+  ) => TableOptions<TFeatures, TData>
+  /**
+   * You can pass any object to `options.meta` and access it anywhere the `table` is available via `table.options.meta`.
+   */
+  meta?: TableMeta<TFeatures, TData>
+  /**
+   * Pass in individual self-managed state to the table.
+   */
+  state?: Partial<TableState<TFeatures>>
+  /**
+   * Optionally, provide your own external TanStack Store instance if you want to manage the table state externally.
+   */
+  store?: Store<TableState<TFeatures>>
+}
+
+export interface Table_CoreProperties<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+> {
+  /**
+   * The features that are enabled for the table.
+   */
+  _features: Partial<CoreFeatures> & TFeatures
+  /**
+   * Prototype cache for Cell objects - shared by all cells in this table
+   */
+  _cellPrototype?: object
+  /**
+   * Prototype cache for Column objects - shared by all columns in this table
+   */
+  _columnPrototype?: object
+  /**
+   * Prototype cache for Header objects - shared by all headers in this table
+   */
+  _headerPrototype?: object
+  /**
+   * The row model processing functions that are used to process the data by features.
+   */
+  _rowModelFns: RowModelFns<TFeatures, TData>
+  /**
+   * The row models that are enabled for the table.
+   */
+  _rowModels: CachedRowModels<TFeatures, TData>
+  /**
+   * Prototype cache for Row objects - shared by all rows in this table
+   */
+  _rowPrototype?: object
+  /**
+   * The base store for the table. This can be used to write to the table state.
+   */
+  baseStore: Store<TableState<TFeatures>>
+  /**
+   * This is the resolved initial state of the table.
+   */
+  initialState: TableState<TFeatures>
+  /**
+   * A read-only reference to the table's current options.
+   */
+  options: TableOptions<TFeatures, TData>
+  /**
+   * Where the table state is stored.
+   */
+  store: Derived<TableState<TFeatures>, [Store<TableState<TFeatures>>]>
+}
+
+export interface Table_Table<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+> extends Table_CoreProperties<TFeatures, TData> {
+  /**
+   * Call this function to reset the table state to the initial state.
+   */
+  reset: () => void
+  /**
+   * This function can be used to update the table options.
+   */
+  setOptions: (newOptions: Updater<TableOptions<TFeatures, TData>>) => void
+}

package/src/core/table/coreTablesFeature.utils.ts

@@ -0,0 +1,40 @@
+import { functionalUpdate } from '../../utils'
+import type { RowData, Updater } from '../../types/type-utils'
+import type { TableFeatures } from '../../types/TableFeatures'
+import type { Table_Internal } from '../../types/Table'
+import type { TableOptions } from '../../types/TableOptions'
+
+export function table_reset<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+>(table: Table_Internal<TFeatures, TData>): void {
+  table.baseStore.setState(structuredClone(table.initialState))
+}
+
+export function table_mergeOptions<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+>(
+  table: Table_Internal<TFeatures, TData>,
+  newOptions: TableOptions<TFeatures, TData>,
+) {
+  if (table.options.mergeOptions) {
+    return table.options.mergeOptions(table.options, newOptions)
+  }
+
+  return {
+    ...table.options,
+    ...newOptions,
+  }
+}
+
+export function table_setOptions<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+>(
+  table: Table_Internal<TFeatures, TData>,
+  updater: Updater<TableOptions<TFeatures, TData>>,
+): void {
+  const newOptions = functionalUpdate(updater, table.options)
+  table.options = table_mergeOptions(table, newOptions)
+}

package/src/features/column-faceting/columnFacetingFeature.ts

@@ -0,0 +1,112 @@
+import {
+  assignPrototypeAPIs,
+  assignTableAPIs,
+  callMemoOrStaticFn,
+} from '../../utils'
+import {
+  column_getFacetedMinMaxValues,
+  column_getFacetedRowModel,
+  column_getFacetedUniqueValues,
+  table_getGlobalFacetedMinMaxValues,
+  table_getGlobalFacetedRowModel,
+  table_getGlobalFacetedUniqueValues,
+} from './columnFacetingFeature.utils'
+import type { RowData } from '../../types/type-utils'
+import type { TableFeature, TableFeatures } from '../../types/TableFeatures'
+import type { Column_Internal } from '../../types/Column'
+// import type {
+//   CachedRowModel_Faceted,
+//   Column_ColumnFaceting,
+//   CreateRowModel_Faceted,
+// } from './columnFacetingFeature.types'
+
+interface ColumnFacetingFeatureConstructors<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+> {
+  // CachedRowModel: CachedRowModel_Faceted<TFeatures, TData>
+  // Column: Column_ColumnFaceting<TFeatures, TData>
+  // CreateRowModels: CreateRowModel_Faceted<TFeatures, TData>
+}
+
+export function constructColumnFacetingFeature<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+>(): TableFeature<ColumnFacetingFeatureConstructors<TFeatures, TData>> {
+  return {
+    assignColumnPrototype: (prototype, table) => {
+      assignPrototypeAPIs('columnFacetingFeature', prototype, table, {
+        column_getFacetedRowModel: {
+          memoDeps: () => [
+            table.getPreFilteredRowModel().rows,
+            table.store.state.columnFilters,
+            table.store.state.globalFilter,
+            table.getFilteredRowModel().rows,
+          ],
+          fn: (column) => column_getFacetedRowModel(column, column.table),
+        },
+        column_getFacetedMinMaxValues: {
+          memoDeps: (column: Column_Internal<TFeatures, TData>) => [
+            callMemoOrStaticFn(
+              column,
+              'getFacetedRowModel',
+              column_getFacetedRowModel,
+              column.table,
+            ).flatRows,
+          ],
+          fn: (column) => column_getFacetedMinMaxValues(column, column.table),
+        },
+        column_getFacetedUniqueValues: {
+          memoDeps: (column: Column_Internal<TFeatures, TData>) => [
+            callMemoOrStaticFn(
+              column,
+              'getFacetedRowModel',
+              column_getFacetedRowModel,
+              column.table,
+            ).flatRows,
+          ],
+          fn: (column) => column_getFacetedUniqueValues(column, column.table),
+        },
+      })
+    },
+
+    constructTableAPIs: (table) => {
+      assignTableAPIs('columnFacetingFeature', table, {
+        table_getGlobalFacetedRowModel: {
+          memoDeps: () => [
+            table.getPreFilteredRowModel().rows,
+            table.store.state.columnFilters,
+            table.store.state.globalFilter,
+            table.getFilteredRowModel().rows,
+          ],
+          fn: () => table_getGlobalFacetedRowModel(table),
+        },
+        table_getGlobalFacetedMinMaxValues: {
+          memoDeps: () => [
+            callMemoOrStaticFn(
+              table,
+              'getGlobalFacetedRowModel',
+              table_getGlobalFacetedRowModel,
+            ).flatRows,
+          ],
+          fn: () => table_getGlobalFacetedMinMaxValues(table),
+        },
+        table_getGlobalFacetedUniqueValues: {
+          memoDeps: () => [
+            callMemoOrStaticFn(
+              table,
+              'getGlobalFacetedRowModel',
+              table_getGlobalFacetedRowModel,
+            ).flatRows,
+          ],
+          fn: () => table_getGlobalFacetedUniqueValues(table),
+        },
+      })
+    },
+  }
+}
+
+/**
+ * The Column Faceting feature adds column faceting APIs to the column objects.
+ */
+export const columnFacetingFeature = constructColumnFacetingFeature()

package/src/features/column-faceting/columnFacetingFeature.types.ts

@@ -0,0 +1,97 @@
+import type { Table } from '../../types/Table'
+import type { RowData } from '../../types/type-utils'
+import type { TableFeatures } from '../../types/TableFeatures'
+import type { RowModel } from '../../core/row-models/coreRowModelsFeature.types'
+
+export interface Column_ColumnFaceting<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+> {
+  /**
+   * A function that **computes and returns** a min/max tuple derived from `column.getFacetedRowModel`. Useful for displaying faceted result values.
+   */
+  getFacetedMinMaxValues: () => undefined | [number, number]
+  /**
+   * A function that **computes and returns** a row model with all other column filters applied, excluding its own filter. Useful for displaying faceted result counts.
+   */
+  getFacetedRowModel: () => RowModel<TFeatures, TData>
+  /**
+   * Returns a `Map` of unique values and their occurrences derived from `column.getFacetedRowModel`. Useful for displaying faceted result values.
+   */
+  getFacetedUniqueValues: () => Map<any, number>
+}
+
+export interface Table_RowModels_Faceted<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+> {
+  /**
+   * A function that **computes and returns** a min/max tuple derived from `column.getFacetedRowModel`. Useful for displaying faceted result values.
+   * > ⚠️ Requires that you pass a valid `getFacetedMinMaxValues` function to `options.getFacetedMinMaxValues`. A default implementation is provided via the exported `getFacetedMinMaxValues` function.
+   */
+  getFacetedMinMaxValues: () => undefined | [number, number]
+  /**
+   * Returns the row model with all other column filters applied, excluding its own filter. Useful for displaying faceted result counts.
+   * > ⚠️ Requires that you pass a valid `getFacetedRowModel` function to `options.facetedRowModel`. A default implementation is provided via the exported `getFacetedRowModel` function.
+   */
+  getFacetedRowModel: () => RowModel<TFeatures, TData>
+  /**
+   * A function that **computes and returns** a `Map` of unique values and their occurrences derived from `column.getFacetedRowModel`. Useful for displaying faceted result values.
+   * > ⚠️ Requires that you pass a valid `getFacetedUniqueValues` function to `options.getFacetedUniqueValues`. A default implementation is provided via the exported `getFacetedUniqueValues` function.
+   */
+  getFacetedUniqueValues: () => Map<any, number>
+}
+
+export interface CreateRowModel_Faceted<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+> {
+  /**
+   * This function is used to retrieve the faceted min/max values. If using server-side faceting, this function is not required. To use client-side faceting, pass the exported `getFacetedMinMaxValues()` from your adapter to your table or implement your own.
+   */
+  facetedMinMaxValues?: (
+    table: Table<TFeatures, TData>,
+    columnId: string,
+  ) => () => [number, number] | undefined
+  /**
+   * This function is used to retrieve the faceted row model. If using server-side faceting, this function is not required. To use client-side faceting, pass the exported `getFacetedRowModel()` from your adapter to your table or implement your own.
+   */
+  facetedRowModel?: (
+    table: Table<TFeatures, TData>,
+    columnId: string,
+  ) => () => RowModel<TFeatures, TData>
+  /**
+   * This function is used to retrieve the faceted unique values. If using server-side faceting, this function is not required. To use client-side faceting, pass the exported `getFacetedUniqueValues()` from your adapter to your table or implement your own.
+   */
+  facetedUniqueValues?: (
+    table: Table<TFeatures, TData>,
+    columnId: string,
+  ) => () => Map<any, number>
+}
+
+export interface CachedRowModel_Faceted<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+> {
+  facetedRowModel?: (columnId: string) => () => RowModel<TFeatures, TData>
+  facetedMinMaxValues?: (columnId: string) => [number, number]
+  facetedUniqueValues?: (columnId: string) => Map<any, number>
+}
+
+export interface Table_ColumnFaceting<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+> {
+  /**
+   * Returns the min and max values for the global filter.
+   */
+  getGlobalFacetedMinMaxValues: () => undefined | [number, number]
+  /**
+   * Returns the row model for the table after **global** filtering has been applied.
+   */
+  getGlobalFacetedRowModel: () => RowModel<TFeatures, TData>
+  /**
+   * Returns the faceted unique values for the global filter.
+   */
+  getGlobalFacetedUniqueValues: () => Map<any, number>
+}

package/src/features/column-faceting/columnFacetingFeature.utils.ts

@@ -0,0 +1,77 @@
+import type { CellData, RowData } from '../../types/type-utils'
+import type { TableFeatures } from '../../types/TableFeatures'
+import type { RowModel } from '../../core/row-models/coreRowModelsFeature.types'
+import type { Table_Internal } from '../../types/Table'
+import type { Column_Internal } from '../../types/Column'
+
+export function column_getFacetedMinMaxValues<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+  TValue extends CellData = CellData,
+>(
+  column: Column_Internal<TFeatures, TData, TValue>,
+  table: Table_Internal<TFeatures, TData>,
+): [number, number] | undefined {
+  const facetedMinMaxValuesFn =
+    table.options._rowModels?.facetedMinMaxValues?.(table, column.id) ??
+    (() => undefined)
+  return facetedMinMaxValuesFn()
+}
+
+export function column_getFacetedRowModel<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+  TValue extends CellData = CellData,
+>(
+  column: Column_Internal<TFeatures, TData, TValue> | undefined,
+  table: Table_Internal<TFeatures, TData>,
+): RowModel<TFeatures, TData> {
+  const facetedRowModelFn =
+    table.options._rowModels?.facetedRowModel?.(table, column?.id ?? '') ??
+    (() => table.getPreFilteredRowModel())
+  return facetedRowModelFn()
+}
+
+export function column_getFacetedUniqueValues<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+  TValue extends CellData = CellData,
+>(
+  column: Column_Internal<TFeatures, TData, TValue>,
+  table: Table_Internal<TFeatures, TData>,
+): Map<any, number> {
+  const facetedUniqueValuesFn =
+    table.options._rowModels?.facetedUniqueValues?.(table, column.id) ??
+    (() => new Map<any, number>())
+  return facetedUniqueValuesFn()
+}
+
+export function table_getGlobalFacetedMinMaxValues<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+>(table: Table_Internal<TFeatures, TData>): undefined | [number, number] {
+  const facetedMinMaxValuesFn =
+    table.options._rowModels?.facetedMinMaxValues?.(table, '__global__') ??
+    (() => undefined)
+  return facetedMinMaxValuesFn()
+}
+
+export function table_getGlobalFacetedRowModel<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+>(table: Table_Internal<TFeatures, TData>): RowModel<TFeatures, TData> {
+  const facetedRowModelFn =
+    table.options._rowModels?.facetedRowModel?.(table, '__global__') ??
+    (() => table.getPreFilteredRowModel())
+  return facetedRowModelFn()
+}
+
+export function table_getGlobalFacetedUniqueValues<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+>(table: Table_Internal<TFeatures, TData>): Map<any, number> {
+  const facetedUniqueValuesFn =
+    table.options._rowModels?.facetedUniqueValues?.(table, '__global__') ??
+    (() => new Map())
+  return facetedUniqueValuesFn()
+}

package/src/features/column-faceting/createFacetedMinMaxValues.ts

@@ -0,0 +1,63 @@
+import { callMemoOrStaticFn, tableMemo } from '../../utils'
+import { column_getFacetedRowModel } from './columnFacetingFeature.utils'
+import type { Row } from '../../types/Row'
+import type { Table, Table_Internal } from '../../types/Table'
+import type { TableFeatures } from '../../types/TableFeatures'
+import type { RowData } from '../../types/type-utils'
+
+export function createFacetedMinMaxValues<
+  TFeatures extends TableFeatures,
+  TData extends RowData = any,
+>(): (
+  table: Table<TFeatures, TData>,
+  columnId: string,
+) => () => undefined | [number, number] {
+  return (_table, columnId) => {
+    const table = _table as Table_Internal<TFeatures, TData>
+    return tableMemo({
+      feature: 'columnFacetingFeature',
+      fn: (flatRows) => _createFacetedMinMaxValues(columnId, flatRows),
+      fnName: 'table.getFacetedMinMaxValues',
+      memoDeps: () => {
+        const column = table.getColumn(columnId)
+        if (!column) return [table.getPreFilteredRowModel().flatRows]
+        return [
+          callMemoOrStaticFn(
+            column,
+            'getFacetedRowModel',
+            column_getFacetedRowModel,
+            table,
+          ).flatRows,
+        ]
+      },
+      table,
+    })
+  }
+}
+
+function _createFacetedMinMaxValues<
+  TFeatures extends TableFeatures,
+  TData extends RowData = any,
+>(
+  columnId: string,
+  flatRows: Array<Row<TFeatures, TData>>,
+): undefined | [number, number] {
+  if (!flatRows.length) return undefined
+
+  const numericValues = flatRows
+    .map((flatRow) => flatRow.getValue(columnId))
+    .map(Number)
+    .filter((value) => !Number.isNaN(value))
+
+  if (!numericValues.length) return undefined
+
+  let facetedMinValue = numericValues[0]!
+  let facetedMaxValue = numericValues[0]!
+
+  for (const value of numericValues) {
+    if (value < facetedMinValue) facetedMinValue = value
+    if (value > facetedMaxValue) facetedMaxValue = value
+  }
+
+  return [facetedMinValue, facetedMaxValue]
+}

package/src/features/column-faceting/createFacetedRowModel.ts

@@ -0,0 +1,76 @@
+import { tableMemo } from '../../utils'
+import { filterRows } from '../column-filtering/filterRowsUtils'
+import type { Table, Table_Internal } from '../../types/Table'
+import type {
+  ColumnFiltersState,
+  Row_ColumnFiltering,
+} from '../column-filtering/columnFilteringFeature.types'
+import type { TableFeatures } from '../../types/TableFeatures'
+import type { RowModel } from '../../core/row-models/coreRowModelsFeature.types'
+import type { Row } from '../../types/Row'
+import type { RowData } from '../../types/type-utils'
+
+export function createFacetedRowModel<
+  TFeatures extends TableFeatures,
+  TData extends RowData = any,
+>(): (
+  table: Table<TFeatures, TData>,
+  columnId: string,
+) => () => RowModel<TFeatures, TData> {
+  return (_table, columnId) => {
+    const table = _table as Table_Internal<TFeatures, TData>
+    return tableMemo({
+      feature: 'columnFacetingFeature',
+      table,
+      fnName: 'createFacetedRowModel',
+      memoDeps: () => [
+        table.getPreFilteredRowModel(),
+        table.store.state.columnFilters,
+        table.store.state.globalFilter,
+        table.getFilteredRowModel(),
+      ],
+      fn: (preRowModel, columnFilters, globalFilter) =>
+        _createFacetedRowModel(
+          table,
+          columnId,
+          preRowModel,
+          columnFilters,
+          globalFilter,
+        ),
+    })
+  }
+}
+
+function _createFacetedRowModel<
+  TFeatures extends TableFeatures,
+  TData extends RowData = any,
+>(
+  table: Table_Internal<TFeatures, TData>,
+  columnId: string,
+  preRowModel: RowModel<TFeatures, TData>,
+  columnFilters?: ColumnFiltersState,
+  globalFilter?: string,
+) {
+  if (!preRowModel.rows.length || (!columnFilters?.length && !globalFilter)) {
+    return preRowModel
+  }
+
+  const filterableIds = [
+    ...(columnFilters?.map((d) => d.id).filter((d) => d !== columnId) ?? []),
+    globalFilter ? '__global__' : undefined,
+  ].filter(Boolean) as Array<string>
+
+  const filterRowsImpl = (
+    row: Row<TFeatures, TData> & Partial<Row_ColumnFiltering<TFeatures, TData>>,
+  ) => {
+    // Horizontally filter rows through each column
+    for (const colId of filterableIds) {
+      if (row.columnFilters?.[colId] === false) {
+        return false
+      }
+    }
+    return true
+  }
+
+  return filterRows(preRowModel.rows, filterRowsImpl, table)
+}

package/src/features/column-faceting/createFacetedUniqueValues.ts

@@ -0,0 +1,60 @@
+import { callMemoOrStaticFn, tableMemo } from '../../utils'
+import { column_getFacetedRowModel } from './columnFacetingFeature.utils'
+import type { Row } from '../../types/Row'
+import type { Table, Table_Internal } from '../../types/Table'
+import type { TableFeatures } from '../../types/TableFeatures'
+import type { RowData } from '../../types/type-utils'
+
+export function createFacetedUniqueValues<
+  TFeatures extends TableFeatures,
+  TData extends RowData = any,
+>(): (
+  table: Table<TFeatures, TData>,
+  columnId: string,
+) => () => Map<any, number> {
+  return (_table, columnId) => {
+    const table = _table as Table_Internal<TFeatures, TData>
+    return tableMemo({
+      feature: 'columnFacetingFeature',
+      table,
+      fnName: 'table.getFacetedUniqueValues',
+      memoDeps: () => {
+        const column = table.getColumn(columnId)
+        if (!column) return [table.getPreFilteredRowModel().flatRows]
+        return [
+          callMemoOrStaticFn(
+            column,
+            'getFacetedRowModel',
+            column_getFacetedRowModel,
+            table,
+          ).flatRows,
+        ]
+      },
+      fn: (flatRows) => _createFacetedUniqueValues(columnId, flatRows),
+    })
+  }
+}
+
+function _createFacetedUniqueValues<
+  TFeatures extends TableFeatures,
+  TData extends RowData = any,
+>(columnId: string, flatRows: Array<Row<TFeatures, TData>>): Map<any, number> {
+  const facetedUniqueValues = new Map<any, number>()
+
+  for (const row of flatRows) {
+    const values = row.getUniqueValues(columnId)
+
+    for (const value of values) {
+      if (facetedUniqueValues.has(value)) {
+        facetedUniqueValues.set(
+          value,
+          (facetedUniqueValues.get(value) ?? 0) + 1,
+        )
+      } else {
+        facetedUniqueValues.set(value, 1)
+      }
+    }
+  }
+
+  return facetedUniqueValues
+}