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

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

@@ -0,0 +1,239 @@
+import type { TableReactivityBindings } from '../reactivity/coreReactivityFeature.types'
+import type { Atom, ReadonlyAtom, ReadonlyStore } from '@tanstack/store'
+import type { CoreFeatures } from '../coreFeatures'
+import type { RowModelFns } from '../../types/RowModelFns'
+import type { RowData, Updater } from '../../types/type-utils'
+import type {
+  IsAny,
+  TableFeatures,
+  ValidateFeatureSlots,
+} from '../../types/TableFeatures'
+import type { CachedRowModels } from '../../types/RowModel'
+import type { TableOptions } from '../../types/TableOptions'
+import type { TableState, TableState_All } from '../../types/TableState'
+
+export interface TableMeta<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+> {}
+
+/**
+ * Resolves the type of `options.meta` for a feature set.
+ *
+ * When the features object declares a `tableMeta` type-only slot
+ * (`tableFeatures({ ..., tableMeta: {} as MyTableMeta })`), that type wins.
+ * Otherwise this falls back to the global declaration-merged `TableMeta`
+ * interface.
+ */
+export type ExtractTableMeta<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+> =
+  IsAny<TFeatures> extends true
+    ? TableMeta<TFeatures, TData>
+    : TFeatures extends { tableMeta: infer TMeta extends object }
+      ? TMeta
+      : TableMeta<TFeatures, TData>
+
+/**
+ * A map of writable atoms, one per `TableState` slice. These are the internal
+ * writable atoms that the library always writes to via `makeStateUpdater`.
+ */
+export type BaseAtoms<TFeatures extends TableFeatures> = {
+  [K in keyof TableState<TFeatures>]-?: Atom<TableState<TFeatures>[K]>
+}
+
+/**
+ * A map of readonly derived atoms, one per `TableState` slice. Each derives
+ * from its corresponding `baseAtom` plus, optionally, a per-slice external
+ * atom or external state value.
+ *
+ * Precedence: `options.atoms[key]` > `options.state[key]` > `baseAtoms[key]`.
+ */
+export type Atoms<TFeatures extends TableFeatures> = {
+  [K in keyof TableState<TFeatures>]-?: ReadonlyAtom<TableState<TFeatures>[K]>
+}
+
+/**
+ * A map of optional external atoms, one per `TableState` slice. Consumers can
+ * provide their own writable atom for any state slice to take over ownership
+ * of that slice.
+ */
+export type ExternalAtoms<TFeatures extends TableFeatures> = Partial<{
+  [K in keyof TableState<TFeatures>]: Atom<TableState<TFeatures>[K]>
+}>
+
+/**
+ * Internal "all features" flat variants of the atom types. `Table_Internal`
+ * uses these so feature code (written generically over `TFeatures`) can access
+ * any slice atom (e.g. `table.atoms.columnPinning`) without TypeScript
+ * narrowing away slices that aren't in the current `TFeatures` union.
+ *
+ * Keys are optional: feature code can read atoms from slices it doesn't own,
+ * but those slices may not be registered on the current table. Consumers must
+ * use optional chaining (`table.atoms.columnPinning?.get() ?? default`).
+ */
+export type BaseAtoms_All = {
+  [K in keyof TableState_All]?: Atom<TableState_All[K]>
+}
+export type Atoms_All = {
+  [K in keyof TableState_All]?: ReadonlyAtom<TableState_All[K]>
+}
+export type ExternalAtoms_All = Partial<{
+  [K in keyof TableState_All]: Atom<TableState_All[K]>
+}>
+
+export interface TableOptions_Table<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+> {
+  /**
+   * The feature modules registered on this table instance.
+   *
+   * Feature registration controls which state slices, options, and prototype
+   * APIs are available. This object also carries the table's row model
+   * factories (`sortedRowModel`, `filteredRowModel`, etc.), row model function
+   * registries (`sortFns`, `filterFns`, `aggregationFns`), and type-only meta
+   * slots (`tableMeta`, `columnMeta`).
+   */
+  readonly features: TFeatures & ValidateFeatureSlots<TFeatures>
+  /**
+   * Optionally, provide your own external writable atoms for individual state slices.
+   * When an atom is provided for a given slice, it takes precedence over `options.state[key]`
+   * and the internal base atom for that slice. Feature state update APIs write through
+   * the corresponding atom updater, so external atoms are the preferred v9 ownership
+   * model for app-managed table state slices.
+   */
+  readonly atoms?: ExternalAtoms<TFeatures>
+  /**
+   * Set this option to override any of the `autoReset...` feature options.
+   */
+  readonly autoResetAll?: boolean
+  /**
+   * The data for the table to display. When the `data` option changes reference, the table will reprocess the data.
+   */
+  readonly data: ReadonlyArray<TData>
+  /**
+   * Optional key used to identify this table instance.
+   *
+   * This is used by TanStack Table Devtools to register and select tables. It is
+   * not required unless the table is passed to devtools.
+   */
+  readonly key?: string
+  /**
+   * Optionally provide starting values for registered table state slices.
+   * Feature reset APIs use this value by default, and many reset APIs accept
+   * `true` to reset to that feature's blank/default state instead. Changing this
+   * object later does not reset table state, so it does not need to be stable.
+   */
+  readonly initialState?: Partial<TableState<TFeatures>>
+  /**
+   * This option is used to optionally implement the merging of table options.
+   */
+  readonly 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`.
+   *
+   * Declare its type per-table via the `tableMeta` type-only slot on the
+   * `features` option, or globally via declaration merging on `TableMeta`.
+   */
+  readonly meta?: ExtractTableMeta<TFeatures, TData>
+  /**
+   * Optionally provide externally managed values for individual state slices.
+   *
+   * Pair each slice with its matching `on[State]Change` callback so table state
+   * updates can be persisted outside the table. External atoms take precedence
+   * over this option when both are provided for the same slice.
+   */
+  readonly state?: Partial<TableState<TFeatures>>
+}
+
+export interface Table_CoreProperties<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+> {
+  /**
+   * Table reactivity bindings for interacting with TanStack Store.
+   */
+  readonly _reactivity: TableReactivityBindings
+  /**
+   * 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
+  /**
+   * The features that are enabled for the table.
+   */
+  readonly _features: Partial<CoreFeatures> & TFeatures
+  /**
+   * 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.
+   */
+  readonly _rowModelFns: RowModelFns<TFeatures, TData>
+  /**
+   * The row models that are enabled for the table.
+   */
+  readonly _rowModels: CachedRowModels<TFeatures, TData>
+  /**
+   * Prototype cache for Row objects - shared by all rows in this table
+   */
+  _rowPrototype?: object
+  /**
+   * The readonly derived atoms for each `TableState` slice. Each derives from
+   * its corresponding `baseAtom` plus, optionally, a per-slice external atom or
+   * external state value (precedence: external atom > external state > base atom).
+   */
+  readonly atoms: Atoms<TFeatures>
+  /**
+   * The internal writable atoms for each `TableState` slice. This is the library's
+   * single write surface — all state mutations from features land here.
+   */
+  readonly baseAtoms: BaseAtoms<TFeatures>
+  /**
+   * This is the resolved initial state of the table.
+   */
+  readonly initialState: TableState<TFeatures>
+  /**
+   * A read-only reference to the table's current options.
+   */
+  readonly options: TableOptions<TFeatures, TData>
+  /**
+   * Writable atom for table options. Only created when `createOptionsStore` is
+   * true on the active core reactivity bindings. Adapters that opt out keep
+   * options as plain resolved data instead of backing them with an atom.
+   */
+  readonly optionsStore?: Atom<TableOptions<TFeatures, TData>> | undefined
+  /**
+   * The readonly flat store for the table state. Derives from `table.atoms`
+   * only; never reads external state directly.
+   */
+  readonly store: ReadonlyStore<TableState<TFeatures>>
+}
+
+export interface Table_Table<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+> extends Table_CoreProperties<TFeatures, TData> {
+  /**
+   * Resets the table's internal base atoms to `table.initialState`.
+   *
+   * Prefer feature-specific reset APIs, such as `resetPagination`, when a state
+   * slice may be owned by an external atom or needs that feature's blank/default
+   * reset behavior.
+   */
+  reset: () => void
+  /**
+   * Updates the table options by applying a value or updater to the current
+   * resolved options and then merging them through `options.mergeOptions`.
+   */
+  setOptions: (newOptions: Updater<TableOptions<TFeatures, TData>>) => void
+}

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

@@ -0,0 +1,130 @@
+import { cloneState, 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'
+
+/**
+ * Synchronizes externally controlled state slices into the table's base atoms.
+ *
+ * This keeps legacy `options.state` values reflected in the atom graph so
+ * derived atoms, stores, and table APIs read a consistent snapshot.
+ *
+ * @example
+ * ```ts
+ * table_syncExternalStateToBaseAtoms(table)
+ * ```
+ */
+export function table_syncExternalStateToBaseAtoms<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+>(table: Table_Internal<TFeatures, TData>): void {
+  const state = table.options.state
+  if (!state) {
+    return
+  }
+
+  table._reactivity.batch(() => {
+    for (const key in state) {
+      const baseAtom = (table.baseAtoms as Record<string, any>)[key]
+      if (!baseAtom) {
+        continue
+      }
+
+      const externalState = state[key as keyof typeof state]
+      if (externalState !== baseAtom.get()) {
+        baseAtom.set(() => externalState)
+      }
+    }
+  })
+}
+
+/**
+ * Resets all internal table base atoms to `table.initialState`.
+ *
+ * This resets internally owned state slices in a single reactivity batch. Use
+ * feature-specific reset APIs when a slice may be externally owned.
+ *
+ * @example
+ * ```ts
+ * table_reset(table)
+ * ```
+ */
+export function table_reset<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+>(table: Table_Internal<TFeatures, TData>): void {
+  const snap = cloneState(table.initialState)
+  table._reactivity.batch(() => {
+    const keys = Object.keys(snap) as Array<keyof typeof snap>
+    for (let i = 0; i < keys.length; i++) {
+      const key = keys[i]!
+      ;(table.baseAtoms as any)[key].set(snap[key])
+    }
+  })
+}
+
+/**
+ * Merges new table options with the current resolved options.
+ *
+ * If `options.mergeOptions` is provided, it owns the merge behavior; otherwise
+ * options are shallow-merged.
+ *
+ * @example
+ * ```ts
+ * const options = table_mergeOptions(table, nextOptions)
+ * ```
+ */
+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,
+  }
+}
+
+/**
+ * Updates the table options object.
+ *
+ * The updater receives the current resolved options and the merged result is
+ * immediately assigned to the table instance.
+ *
+ * @example
+ * ```ts
+ * table_setOptions(table, (old) => old)
+ * ```
+ */
+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 static options that should never change after initialization
+  const { features, atoms, initialState } = table.options
+  const mergedOptions = Object.assign(table_mergeOptions(table, newOptions), {
+    // Once the table instance is created those properties should never change after initialization,
+    // so we assign them back preserving the `table_mergeOptions` object reference
+    features,
+    atoms,
+    initialState,
+  })
+
+  if (table.optionsStore) {
+    table.optionsStore.set(() => mergedOptions)
+  } else {
+    table.options = mergedOptions
+  }
+  table_syncExternalStateToBaseAtoms(table)
+}

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

@@ -0,0 +1,89 @@
+import {
+  assignPrototypeAPIs,
+  assignTableAPIs,
+  callMemoOrStaticFn,
+} from '../../utils'
+import {
+  column_getFacetedMinMaxValues,
+  column_getFacetedRowModel,
+  column_getFacetedUniqueValues,
+  table_getGlobalFacetedMinMaxValues,
+  table_getGlobalFacetedRowModel,
+  table_getGlobalFacetedUniqueValues,
+} from './columnFacetingFeature.utils'
+import type { TableFeature } from '../../types/TableFeatures'
+
+/**
+ * Feature that derives faceted row models, unique values, and min/max values for filters.
+ */
+export const columnFacetingFeature: TableFeature = {
+  assignColumnPrototype: (prototype, table) => {
+    assignPrototypeAPIs('columnFacetingFeature', prototype, table, {
+      column_getFacetedRowModel: {
+        memoDeps: () => [
+          table.getPreFilteredRowModel().rows,
+          table.atoms.columnFilters?.get(),
+          table.atoms.globalFilter?.get(),
+          table.getFilteredRowModel().rows,
+        ],
+        fn: (column) => column_getFacetedRowModel(column, column.table),
+      },
+      column_getFacetedMinMaxValues: {
+        memoDeps: (column) => [
+          callMemoOrStaticFn(
+            column,
+            'getFacetedRowModel',
+            column_getFacetedRowModel,
+            column.table,
+          ).flatRows,
+        ],
+        fn: (column) => column_getFacetedMinMaxValues(column, column.table),
+      },
+      column_getFacetedUniqueValues: {
+        memoDeps: (column) => [
+          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.atoms.columnFilters?.get(),
+          table.atoms.globalFilter?.get(),
+          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),
+      },
+    })
+  },
+}

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

@@ -0,0 +1,76 @@
+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,
+> {
+  /**
+   * Computes min/max numeric facet values for this column.
+   */
+  getFacetedMinMaxValues: () => undefined | [number, number]
+  /**
+   * Computes the row model used to derive this column's facet values.
+   *
+   * Other column filters are applied, while this column's own filter is
+   * excluded.
+   */
+  getFacetedRowModel: () => RowModel<TFeatures, TData>
+  /**
+   * Computes unique facet values and occurrence counts for this column.
+   */
+  getFacetedUniqueValues: () => Map<any, number>
+}
+
+export interface Table_RowModels_Faceted<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+> {
+  /**
+   * Computes min/max numeric facet values for the active faceting context.
+   *
+   * Requires a `facetedMinMaxValues` row-model factory on the `features` option.
+   */
+  getFacetedMinMaxValues: () => undefined | [number, number]
+  /**
+   * Computes the row model used to derive facet values.
+   *
+   * Requires a `facetedRowModel` row-model factory on the `features` option.
+   */
+  getFacetedRowModel: () => RowModel<TFeatures, TData>
+  /**
+   * Computes unique facet values and occurrence counts.
+   *
+   * Requires a `facetedUniqueValues` row-model factory on the `features` option.
+   */
+  getFacetedUniqueValues: () => 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]
+  /**
+   * Computes the row model used to derive global facet values.
+   */
+  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,145 @@
+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'
+
+/**
+ * Computes min and max numeric facet values for one column.
+ *
+ * The configured `facetedMinMaxValues` row-model factory owns the calculation.
+ * If no factory is registered, the result is `undefined`.
+ *
+ * @example
+ * ```ts
+ * const range = column_getFacetedMinMaxValues(column, table)
+ * ```
+ */
+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.features.facetedMinMaxValues?.(table, column.id) ??
+    (() => undefined)
+  return facetedMinMaxValuesFn()
+}
+
+/**
+ * Computes the row model used to derive one column's facet values.
+ *
+ * The faceted row model normally applies every other active filter while
+ * excluding this column's own filter. If no factory is registered, the
+ * pre-filtered row model is returned.
+ *
+ * @example
+ * ```ts
+ * const rows = column_getFacetedRowModel(column, table)
+ * ```
+ */
+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.features.facetedRowModel?.(table, column?.id ?? '') ??
+    (() => table.getPreFilteredRowModel())
+  return facetedRowModelFn()
+}
+
+/**
+ * Computes unique facet values and their occurrence counts for one column.
+ *
+ * The configured `facetedUniqueValues` row-model factory owns the calculation.
+ * If no factory is registered, an empty `Map` is returned.
+ *
+ * @example
+ * ```ts
+ * const values = column_getFacetedUniqueValues(column, table)
+ * ```
+ */
+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.features.facetedUniqueValues?.(table, column.id) ??
+    (() => new Map<any, number>())
+  return facetedUniqueValuesFn()
+}
+
+/**
+ * Computes min and max numeric facet values for the global filter context.
+ *
+ * The global context is requested with the internal `__global__` column id. If
+ * no factory is registered, the result is `undefined`.
+ *
+ * @example
+ * ```ts
+ * const range = table_getGlobalFacetedMinMaxValues(table)
+ * ```
+ */
+export function table_getGlobalFacetedMinMaxValues<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+>(table: Table_Internal<TFeatures, TData>): undefined | [number, number] {
+  const facetedMinMaxValuesFn =
+    table.options.features.facetedMinMaxValues?.(table, '__global__') ??
+    (() => undefined)
+  return facetedMinMaxValuesFn()
+}
+
+/**
+ * Computes the row model used to derive global facet values.
+ *
+ * The global context is requested with the internal `__global__` column id. If
+ * no faceted row-model factory is registered, the pre-filtered row model is
+ * returned.
+ *
+ * @example
+ * ```ts
+ * const rows = table_getGlobalFacetedRowModel(table)
+ * ```
+ */
+export function table_getGlobalFacetedRowModel<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+>(table: Table_Internal<TFeatures, TData>): RowModel<TFeatures, TData> {
+  const facetedRowModelFn =
+    table.options.features.facetedRowModel?.(table, '__global__') ??
+    (() => table.getPreFilteredRowModel())
+  return facetedRowModelFn()
+}
+
+/**
+ * Computes unique values and occurrence counts for the global filter context.
+ *
+ * The global context is requested with the internal `__global__` column id. If
+ * no factory is registered, an empty `Map` is returned.
+ *
+ * @example
+ * ```ts
+ * const values = table_getGlobalFacetedUniqueValues(table)
+ * ```
+ */
+export function table_getGlobalFacetedUniqueValues<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+>(table: Table_Internal<TFeatures, TData>): Map<any, number> {
+  const facetedUniqueValuesFn =
+    table.options.features.facetedUniqueValues?.(table, '__global__') ??
+    (() => new Map())
+  return facetedUniqueValuesFn()
+}