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

package/src/features/global-filtering/globalFilteringFeature.ts

@@ -0,0 +1,99 @@
+import {
+  assignPrototypeAPIs,
+  assignTableAPIs,
+  makeStateUpdater,
+} from '../../utils'
+import {
+  column_getCanGlobalFilter,
+  table_getGlobalAutoFilterFn,
+  table_getGlobalFilterFn,
+  table_resetGlobalFilter,
+  table_setGlobalFilter,
+} from './globalFilteringFeature.utils'
+import type { RowData } from '../../types/type-utils'
+import type { TableFeature, TableFeatures } from '../../types/TableFeatures'
+// import type {
+//   ColumnDef_GlobalFiltering,
+//   Column_GlobalFiltering,
+//   TableOptions_GlobalFiltering,
+//   TableState_GlobalFiltering,
+//   Table_GlobalFiltering,
+// } from './globalFilteringFeature.types'
+
+export interface GlobalFilteringFeatureConstructors<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+> {
+  // Column: Column_GlobalFiltering
+  // ColumnDef: ColumnDef_GlobalFiltering
+  // Table: Table_GlobalFiltering<TFeatures, TData>
+  // TableOptions: TableOptions_GlobalFiltering<TFeatures, TData>
+  // TableState: TableState_GlobalFiltering
+}
+
+/**
+ * Creates the stock global filtering feature.
+ *
+ * The returned feature registers its state defaults, option defaults, and instance APIs so it can be included in a `tableFeatures({ ... })` call.
+ */
+export function constructGlobalFilteringFeature<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+>(): TableFeature<GlobalFilteringFeatureConstructors<TFeatures, TData>> {
+  return {
+    getInitialState: (initialState) => {
+      return {
+        globalFilter: undefined,
+        ...initialState,
+      }
+    },
+
+    getDefaultTableOptions: (table) => {
+      return {
+        onGlobalFilterChange: makeStateUpdater('globalFilter', table),
+        globalFilterFn: 'auto',
+        getColumnCanGlobalFilter: (column) => {
+          const value = table
+            .getCoreRowModel()
+            .flatRows[0]?.getAllCellsByColumnId()
+            [column.id]?.getValue()
+
+          return typeof value === 'string' || typeof value === 'number'
+        },
+      }
+    },
+
+    assignColumnPrototype: (prototype, table) => {
+      assignPrototypeAPIs('globalFilteringFeature', prototype, table, {
+        column_getCanGlobalFilter: {
+          fn: (column) => column_getCanGlobalFilter(column),
+        },
+      })
+    },
+
+    constructTableAPIs: (table) => {
+      assignTableAPIs('globalFilteringFeature', table, {
+        table_getGlobalAutoFilterFn: {
+          fn: () => table_getGlobalAutoFilterFn(),
+        },
+        table_getGlobalFilterFn: {
+          fn: () => table_getGlobalFilterFn(table),
+        },
+        table_setGlobalFilter: {
+          fn: (updater) => table_setGlobalFilter(table, updater),
+        },
+        table_resetGlobalFilter: {
+          fn: (defaultState) => table_resetGlobalFilter(table, defaultState),
+        },
+      })
+    },
+  }
+}
+
+/**
+ * The stock global filtering feature.
+ *
+ * Register this feature with column filtering support to add global filter
+ * state, global filter function resolution, and column eligibility APIs.
+ */
+export const globalFilteringFeature = constructGlobalFilteringFeature()

package/src/features/global-filtering/globalFilteringFeature.types.ts

@@ -0,0 +1,91 @@
+import type {
+  CellData,
+  OnChangeFn,
+  RowData,
+  Updater,
+} from '../../types/type-utils'
+import type { TableFeatures } from '../../types/TableFeatures'
+import type { Column } from '../../types/Column'
+import type {
+  FilterFn,
+  FilterFnOption,
+} from '../column-filtering/columnFilteringFeature.types'
+
+export interface TableState_GlobalFiltering {
+  globalFilter: any
+}
+
+export interface ColumnDef_GlobalFiltering {
+  /**
+   * Allows this column to be scanned by global filtering.
+   *
+   * Defaults to `true`; table-level global filtering and `enableFilters` must
+   * also allow filtering.
+   */
+  enableGlobalFilter?: boolean
+}
+
+export interface Column_GlobalFiltering {
+  /**
+   * Checks whether this accessor column participates in global filtering.
+   */
+  getCanGlobalFilter: () => boolean
+}
+
+export interface TableOptions_GlobalFiltering<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+> {
+  /**
+   * Enables global filtering across columns that allow it.
+   */
+  enableGlobalFilter?: boolean
+  /**
+   * If provided, this function will be called with the column and should return `true` or `false` to indicate whether this column should be used for global filtering.
+   * This is useful if the column can contain data that is not `string` or `number` (i.e. `undefined`).
+   */
+  getColumnCanGlobalFilter?: <
+    TFeatures extends TableFeatures,
+    TData extends RowData,
+    TValue extends CellData = CellData,
+  >(
+    column: Column<TFeatures, TData, TValue>,
+  ) => boolean
+  /**
+   * The filter function to use for global filtering.
+   * - A `string` referencing a built-in filter function
+   * - A `string` that references a custom filter functions provided via the `tableOptions.filterFns` option
+   * - A custom filter function
+   */
+  globalFilterFn?: FilterFnOption<TFeatures, TData>
+  /**
+   * Called with an updater when global filter state changes. Pair this with
+   * `state.globalFilter` when using external state; external atoms can own the
+   * slice without this callback.
+   */
+  onGlobalFilterChange?: OnChangeFn<any>
+}
+
+export interface Table_GlobalFiltering<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+> {
+  /**
+   * Currently, this function returns the built-in `includesString` filter function. In future releases, it may return more dynamic filter functions based on the nature of the data provided.
+   */
+  getGlobalAutoFilterFn: () => FilterFn<TFeatures, TData> | undefined
+  /**
+   * Returns the filter function (either user-defined or automatic, depending on configuration) for the global filter.
+   */
+  getGlobalFilterFn: () => FilterFn<TFeatures, TData> | undefined
+  /**
+   * Resets `globalFilter` to `initialState.globalFilter`.
+   *
+   * Pass `true` to ignore initial state and reset to `undefined`.
+   */
+  resetGlobalFilter: (defaultState?: boolean) => void
+  /**
+   * Updates global filter state with a next value or updater function.
+   */
+  setGlobalFilter: (updater: Updater<any>) => void
+}

package/src/features/global-filtering/globalFilteringFeature.utils.ts

@@ -0,0 +1,116 @@
+import { filterFn_includesString } from '../../fns/filterFns'
+import { cloneState, isFunction } from '../../utils'
+import type { Column_Internal } from '../../types/Column'
+import type { FilterFn } from '../column-filtering/columnFilteringFeature.types'
+import type { CellData, RowData } from '../../types/type-utils'
+import type { TableFeatures } from '../../types/TableFeatures'
+import type { Table_Internal } from '../../types/Table'
+
+/**
+ * Checks whether this accessor column participates in global filtering.
+ *
+ * The column must have an accessor and pass column-level, table-level, and
+ * optional `getColumnCanGlobalFilter` checks.
+ *
+ * @example
+ * ```ts
+ * const canGlobalFilter = column_getCanGlobalFilter(column)
+ * ```
+ */
+export function column_getCanGlobalFilter<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+  TValue extends CellData = CellData,
+>(column: Column_Internal<TFeatures, TData, TValue>): boolean {
+  return (
+    (column.columnDef.enableGlobalFilter ?? true) &&
+    (column.table.options.enableGlobalFilter ?? true) &&
+    (column.table.options.enableFilters ?? true) &&
+    (column.table.options.getColumnCanGlobalFilter?.(column) ?? true) &&
+    !!column.accessorFn
+  )
+}
+
+/**
+ * Provides the built-in automatic global filter function.
+ *
+ * Global filtering defaults to `includesString`, which gives search-box style
+ * matching across globally filterable columns.
+ *
+ * @example
+ * ```ts
+ * const filterFn = table_getGlobalAutoFilterFn()
+ * ```
+ */
+export function table_getGlobalAutoFilterFn() {
+  return filterFn_includesString
+}
+
+/**
+ * Resolves the filter function used for global filtering.
+ *
+ * Function-valued `options.globalFilterFn` is returned directly, `'auto'`
+ * delegates to `table_getGlobalAutoFilterFn`, and string values are looked up in
+ * the table's filter function registry.
+ *
+ * @example
+ * ```ts
+ * const filterFn = table_getGlobalFilterFn(table)
+ * ```
+ */
+export function table_getGlobalFilterFn<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+>(
+  table: Table_Internal<TFeatures, TData>,
+): FilterFn<TFeatures, TData> | FilterFn<TFeatures, TData> | undefined {
+  const { globalFilterFn: globalFilterFn } = table.options
+  const filterFns: Record<string, FilterFn<TFeatures, TData>> | undefined =
+    table._rowModelFns.filterFns
+
+  return isFunction(globalFilterFn)
+    ? globalFilterFn
+    : globalFilterFn === 'auto'
+      ? table_getGlobalAutoFilterFn()
+      : filterFns?.[globalFilterFn as string]
+}
+
+/**
+ * Routes a global filter updater through the table's global filter handler.
+ *
+ * The updater may be a next value or a function of the previous value, matching
+ * the instance `table.setGlobalFilter` behavior.
+ *
+ * @example
+ * ```ts
+ * table_setGlobalFilter(table, 'search text')
+ * ```
+ */
+export function table_setGlobalFilter<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+>(table: Table_Internal<TFeatures, TData>, updater: any) {
+  table.options.onGlobalFilterChange?.(updater)
+}
+
+/**
+ * Resets `globalFilter` to the configured initial state or feature default.
+ *
+ * With no argument, the reset clones `table.initialState.globalFilter`. Passing
+ * `true` ignores initial state and resets to `undefined`.
+ *
+ * @example
+ * ```ts
+ * table_resetGlobalFilter(table)
+ * table_resetGlobalFilter(table, true)
+ * ```
+ */
+export function table_resetGlobalFilter<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+>(table: Table_Internal<TFeatures, TData>, defaultState?: boolean) {
+  table_setGlobalFilter(
+    table,
+    defaultState ? undefined : cloneState(table.initialState.globalFilter),
+  )
+}

package/src/features/row-expanding/createExpandedRowModel.ts

@@ -0,0 +1,82 @@
+import { tableMemo } from '../../utils'
+import { row_getIsExpanded } from './rowExpandingFeature.utils'
+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 expanded 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 createExpandedRowModel<
+  TFeatures extends TableFeatures,
+  TData extends RowData = any,
+>(): (table: Table<TFeatures, TData>) => () => RowModel<TFeatures, TData> {
+  return (_table) => {
+    const table: Table_Internal<TFeatures, TData> = _table
+    return tableMemo({
+      feature: 'rowExpandingFeature',
+      table,
+      fnName: 'table.getExpandedRowModel',
+      memoDeps: () => [
+        table.atoms.expanded?.get(),
+        table.getPreExpandedRowModel(),
+        table.options.paginateExpandedRows,
+      ],
+      fn: () => _createExpandedRowModel(table),
+    })
+  }
+}
+
+function _createExpandedRowModel<
+  TFeatures extends TableFeatures,
+  TData extends RowData = any,
+>(table: Table_Internal<TFeatures, TData>): RowModel<TFeatures, TData> {
+  const rowModel = table.getPreExpandedRowModel()
+  const expanded = table.atoms.expanded?.get()
+
+  if (
+    !rowModel.rows.length ||
+    (expanded !== true && !Object.keys(expanded ?? {}).length)
+  ) {
+    return rowModel
+  }
+
+  if (!table.options.paginateExpandedRows) {
+    // Only expand rows at this point if they are being paginated
+    return rowModel
+  }
+
+  return expandRows(rowModel)
+}
+
+/**
+ * Expands a row model according to the current expanded row state.
+ *
+ * Expanded sub-rows are inserted into the flattened row order while preserving the original row hierarchy.
+ */
+export function expandRows<
+  TFeatures extends TableFeatures,
+  TData extends RowData = any,
+>(rowModel: RowModel<TFeatures, TData>): RowModel<TFeatures, TData> {
+  const expandedRows: Array<Row<TFeatures, TData>> = []
+
+  const handleRow = (row: Row<TFeatures, TData>) => {
+    expandedRows.push(row)
+
+    if (row.subRows.length && row_getIsExpanded(row)) {
+      row.subRows.forEach(handleRow)
+    }
+  }
+
+  rowModel.rows.forEach(handleRow)
+
+  return {
+    rows: expandedRows,
+    flatRows: rowModel.flatRows,
+    rowsById: rowModel.rowsById,
+  }
+}

package/src/features/row-expanding/rowExpandingFeature.ts

@@ -0,0 +1,130 @@
+import {
+  assignPrototypeAPIs,
+  assignTableAPIs,
+  makeStateUpdater,
+} from '../../utils'
+import {
+  getDefaultExpandedState,
+  row_getCanExpand,
+  row_getIsAllParentsExpanded,
+  row_getIsExpanded,
+  row_getToggleExpandedHandler,
+  row_toggleExpanded,
+  table_autoResetExpanded,
+  table_getCanSomeRowsExpand,
+  table_getExpandedDepth,
+  table_getIsAllRowsExpanded,
+  table_getIsSomeRowsExpanded,
+  table_getToggleAllRowsExpandedHandler,
+  table_resetExpanded,
+  table_setExpanded,
+  table_toggleAllRowsExpanded,
+} from './rowExpandingFeature.utils'
+import type { RowData } from '../../types/type-utils'
+import type { TableFeature, TableFeatures } from '../../types/TableFeatures'
+// import type {
+//   CachedRowModel_Expanded,
+//   CreateRowModel_Expanded,
+//   Row_RowExpanding,
+//   TableOptions_RowExpanding,
+//   TableState_RowExpanding,
+//   Table_RowExpanding,
+// } from './rowExpandingFeature.types'
+
+export interface RowExpandingFeatureConstructors<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+> {
+  // CachedRowModel: CachedRowModel_Expanded<TFeatures, TData>
+  // CreateRowModels: CreateRowModel_Expanded<TFeatures, TData>
+  // Row: Row_RowExpanding
+  // Table: Table_RowExpanding<TFeatures, TData>
+  // TableOptions: TableOptions_RowExpanding<TFeatures, TData>
+  // TableState: TableState_RowExpanding
+}
+
+/**
+ * Creates the stock row expanding feature.
+ *
+ * The returned feature registers its state defaults, option defaults, and instance APIs so it can be included in a `tableFeatures({ ... })` call.
+ */
+export function constructRowExpandingFeature<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+>(): TableFeature<RowExpandingFeatureConstructors<TFeatures, TData>> {
+  return {
+    getInitialState: (initialState) => {
+      return {
+        expanded: getDefaultExpandedState(),
+        ...initialState,
+      }
+    },
+
+    getDefaultTableOptions: (table) => {
+      return {
+        onExpandedChange: makeStateUpdater('expanded', table),
+        paginateExpandedRows: true,
+      }
+    },
+
+    assignRowPrototype: (prototype, table) => {
+      assignPrototypeAPIs('rowExpandingFeature', prototype, table, {
+        row_toggleExpanded: {
+          fn: (row, expanded) => row_toggleExpanded(row, expanded),
+        },
+        row_getIsExpanded: {
+          fn: (row) => row_getIsExpanded(row),
+        },
+        row_getCanExpand: {
+          fn: (row) => row_getCanExpand(row),
+        },
+        row_getIsAllParentsExpanded: {
+          fn: (row) => row_getIsAllParentsExpanded(row),
+        },
+        row_getToggleExpandedHandler: {
+          fn: (row) => row_getToggleExpandedHandler(row),
+        },
+      })
+    },
+
+    constructTableAPIs: (table) => {
+      assignTableAPIs('rowExpandingFeature', table, {
+        table_autoResetExpanded: {
+          fn: () => table_autoResetExpanded(table),
+        },
+        table_setExpanded: {
+          fn: (updater) => table_setExpanded(table, updater),
+        },
+        table_toggleAllRowsExpanded: {
+          fn: (expanded) => table_toggleAllRowsExpanded(table, expanded),
+        },
+        table_resetExpanded: {
+          fn: (defaultState) => table_resetExpanded(table, defaultState),
+        },
+        table_getCanSomeRowsExpand: {
+          fn: () => table_getCanSomeRowsExpand(table),
+        },
+        table_getToggleAllRowsExpandedHandler: {
+          fn: () => table_getToggleAllRowsExpandedHandler(table),
+        },
+        table_getIsSomeRowsExpanded: {
+          fn: () => table_getIsSomeRowsExpanded(table),
+        },
+        table_getIsAllRowsExpanded: {
+          fn: () => table_getIsAllRowsExpanded(table),
+        },
+        table_getExpandedDepth: {
+          fn: () => table_getExpandedDepth(table),
+        },
+      })
+    },
+  }
+}
+
+/**
+ * The stock row expanding feature.
+ *
+ * Register this feature to add expanded row state, row expansion APIs, and
+ * helpers for deriving expanded row models and expansion depth.
+ */
+export const rowExpandingFeature = constructRowExpandingFeature()

package/src/features/row-expanding/rowExpandingFeature.types.ts

@@ -0,0 +1,147 @@
+import type { Table } from '../../types/Table'
+import type { OnChangeFn, RowData, Updater } from '../../types/type-utils'
+import type { TableFeatures } from '../../types/TableFeatures'
+import type { RowModel } from '../../core/row-models/coreRowModelsFeature.types'
+import type { Row } from '../../types/Row'
+
+export type ExpandedStateList = Record<string, boolean>
+export type ExpandedState = true | Record<string, boolean>
+
+export interface TableState_RowExpanding {
+  expanded: ExpandedState
+}
+
+export interface Row_RowExpanding {
+  /**
+   * Checks whether this row can be expanded.
+   */
+  getCanExpand: () => boolean
+  /**
+   * Checks whether every ancestor of this row is expanded.
+   */
+  getIsAllParentsExpanded: () => boolean
+  /**
+   * Checks whether this row is currently expanded.
+   */
+  getIsExpanded: () => boolean
+  /**
+   * Creates a handler that toggles this row's expanded state.
+   */
+  getToggleExpandedHandler: () => () => void
+  /**
+   * Toggles the expanded state (or sets it if `expanded` is provided) for the row.
+   */
+  toggleExpanded: (expanded?: boolean) => void
+}
+
+export interface TableOptions_RowExpanding<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+> {
+  /**
+   * Enables automatic expanded-state resets when page-altering table state changes.
+   */
+  autoResetExpanded?: boolean
+  /**
+   * Allows rows with subRows to be expanded.
+   */
+  enableExpanding?: boolean
+  /**
+   * If provided, allows you to override the default behavior of determining whether a row is currently expanded.
+   */
+  getIsRowExpanded?: (row: Row<TFeatures, TData>) => boolean
+  /**
+   * If provided, allows you to override the default behavior of determining whether a row can be expanded.
+   */
+  getRowCanExpand?: (row: Row<TFeatures, TData>) => boolean
+  /**
+   * Enables manual row expansion. If this is set to `true`, `getExpandedRowModel` will not be used to expand rows and you would be expected to perform the expansion in your own data model. This is useful if you are doing server-side expansion.
+   */
+  manualExpanding?: boolean
+  /**
+   * Called with an updater when expanded state changes. Pair this with
+   * `state.expanded` when using external state; external atoms can own the
+   * slice without this callback.
+   */
+  onExpandedChange?: OnChangeFn<ExpandedState>
+  /**
+   * If `true` expanded rows will be paginated along with the rest of the table (which means expanded rows may span multiple pages). If `false` expanded rows will not be considered for pagination (which means expanded rows will always render on their parents page. This also means more rows will be rendered than the set page size)
+   */
+  paginateExpandedRows?: boolean
+}
+
+export interface Table_RowExpanding<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+> {
+  autoResetExpanded: () => void
+  /**
+   * Checks whether at least one row can be expanded.
+   */
+  getCanSomeRowsExpand: () => boolean
+  /**
+   * Computes the deepest expanded row id depth.
+   */
+  getExpandedDepth: () => number
+  /**
+   * Checks whether all rows in the current row model are expanded.
+   */
+  getIsAllRowsExpanded: () => boolean
+  /**
+   * Checks whether any row is currently expanded.
+   */
+  getIsSomeRowsExpanded: () => boolean
+  /**
+   * Creates a handler that toggles all rows expanded.
+   */
+  getToggleAllRowsExpandedHandler: () => (event: unknown) => void
+  /**
+   * Resets `expanded` to `initialState.expanded`.
+   *
+   * Pass `true` to ignore initial state and reset to `{}`.
+   */
+  resetExpanded: (defaultState?: boolean) => void
+  /**
+   * Updates expanded state with `true`, a row-id map, or an updater function.
+   */
+  setExpanded: (updater: Updater<ExpandedState>) => void
+  /**
+   * Toggles the expanded state for all rows.
+   */
+  toggleAllRowsExpanded: (expanded?: boolean) => void
+}
+
+export interface Table_RowModels_Expanded<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+> {
+  /**
+   * Resolves the row model after expanded rows have been flattened into view.
+   */
+  getExpandedRowModel: () => RowModel<TFeatures, TData>
+  /**
+   * Reads the row model immediately before expansion.
+   */
+  getPreExpandedRowModel: () => RowModel<TFeatures, TData>
+}
+
+export interface CreateRowModel_Expanded<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+> {
+  /**
+   * Factory used to retrieve the expanded row model. If this function is not
+   * provided, the table will not expand rows. To use client-side expansion,
+   * pass `createExpandedRowModel()` or implement your own factory.
+   */
+  expandedRowModel?: (
+    table: Table<TFeatures, TData>,
+  ) => () => RowModel<TFeatures, TData>
+}
+
+export interface CachedRowModel_Expanded<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+> {
+  expandedRowModel: () => RowModel<TFeatures, TData>
+}