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

package/src/features/column-filtering/columnFilteringFeature.types.ts

@@ -0,0 +1,232 @@
+import type { Table } from '../../types/Table'
+import type { BuiltInFilterFn } from '../../fns/filterFns'
+import type {
+  CellData,
+  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'
+import type { Column } from '../../types/Column'
+
+export interface FilterMeta {}
+
+export interface FilterFns {}
+
+export interface TableState_ColumnFiltering {
+  columnFilters: ColumnFiltersState
+}
+
+export type ColumnFiltersState = Array<ColumnFilter>
+
+export interface ColumnFilter {
+  id: string
+  value: unknown
+}
+
+export interface ResolvedColumnFilter<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+> {
+  filterFn: FilterFn<TFeatures, TData>
+  id: string
+  resolvedValue: unknown
+}
+
+export interface RowModelFns_ColumnFiltering<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+> {
+  filterFns: Record<keyof FilterFns, FilterFn<TFeatures, TData>>
+}
+
+export interface FilterFn<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+> {
+  (
+    row: Row<TFeatures, TData>,
+    columnId: string,
+    filterValue: any,
+    addMeta?: (meta: FilterMeta) => void,
+  ): boolean
+  autoRemove?: ColumnFilterAutoRemoveTestFn<TFeatures, TData>
+  resolveFilterValue?: TransformFilterValueFn<TFeatures, TData>
+}
+
+export type TransformFilterValueFn<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+  TValue extends CellData = CellData,
+> = (value: any, column?: Column<TFeatures, TData, TValue>) => TValue
+
+export type ColumnFilterAutoRemoveTestFn<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+  TValue extends CellData = CellData,
+> = (value: any, column?: Column<TFeatures, TData, TValue>) => boolean
+
+export type CustomFilterFns<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+> = Record<string, FilterFn<TFeatures, TData>>
+
+export type FilterFnOption<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+> = 'auto' | BuiltInFilterFn | keyof FilterFns | FilterFn<TFeatures, TData>
+
+export interface ColumnDef_ColumnFiltering<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+> {
+  /**
+   * Enables this column to participate in column-specific filtering.
+   *
+   * Defaults to `true`; table-level `enableColumnFilters` and `enableFilters`
+   * must also allow filtering.
+   */
+  enableColumnFilter?: boolean
+  /**
+   * The filter function to use with this column. Can be the name of a built-in filter function or a custom filter function.
+   */
+  filterFn?: FilterFnOption<TFeatures, TData>
+}
+
+export interface Column_ColumnFiltering<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+> {
+  /**
+   * Returns an automatically calculated filter function for the column based off of the columns first known value.
+   */
+  getAutoFilterFn: () => FilterFn<TFeatures, TData>
+  /**
+   * Checks whether this accessor column can currently be column-filtered.
+   */
+  getCanFilter: () => boolean
+  /**
+   * Returns the filter function (either user-defined or automatic, depending on configuration) for the columnId specified.
+   */
+  getFilterFn: () => FilterFn<TFeatures, TData>
+  /**
+   * Returns the index (including `-1`) of the column filter in the table's `state.columnFilters` array.
+   */
+  getFilterIndex: () => number
+  /**
+   * Reads this column's current value from `state.columnFilters`.
+   */
+  getFilterValue: () => unknown
+  /**
+   * Checks whether this column has an active entry in `state.columnFilters`.
+   */
+  getIsFiltered: () => boolean
+  /**
+   * Adds, updates, or removes this column's filter value.
+   *
+   * Updater functions receive the previous filter value. Values that satisfy
+   * the filter function's `autoRemove` rule are removed from filter state.
+   */
+  setFilterValue: (updater: Updater<any>) => void
+}
+
+export interface Row_ColumnFiltering<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+> {
+  /**
+   * The column filters map for the row. This object tracks whether a row is passing/failing specific filters by their column ID.
+   */
+  columnFilters: Record<string, boolean>
+  /**
+   * The column filters meta map for the row. This object tracks any filter meta for a row as optionally provided during the filtering process.
+   */
+  columnFiltersMeta: Record<string, FilterMeta>
+}
+
+export interface TableOptions_ColumnFiltering<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+> {
+  /**
+   * Enables column-specific filtering for all columns that also allow it.
+   */
+  enableColumnFilters?: boolean
+  /**
+   * Enables all filtering features for the table.
+   *
+   * Set this to `false` to disable both column filtering and global filtering.
+   */
+  enableFilters?: boolean
+  /**
+   * By default, filtering is done from parent rows down (so if a parent row is filtered out, all of its children will be filtered out as well). Setting this option to `true` will cause filtering to be done from leaf rows up (which means parent rows will be included so long as one of their child or grand-child rows is also included).
+   */
+  filterFromLeafRows?: boolean
+  /**
+   * Disables the `getFilteredRowModel` from being used to filter data. This may be useful if your table needs to dynamically support both client-side and server-side filtering.
+   */
+  manualFiltering?: boolean
+  /**
+     * By default, filtering is done for all rows (max depth of 100), no matter if they are root level parent rows or the child leaf rows of a parent row. Setting this option to `0` will cause filtering to only be applied to the root level parent rows, with all sub-rows remaining unfiltered. Similarly, setting this option to `1` will cause filtering to only be applied to child leaf rows 1 level deep, and so on.
+
+     * This is useful for situations where you want a row's entire child hierarchy to be visible regardless of the applied filter.
+     */
+  maxLeafRowFilterDepth?: number
+  /**
+   * Called with an updater when column filter state changes. Pair this with
+   * `state.columnFilters` when using external state; external atoms can own the
+   * slice without this callback.
+   */
+  onColumnFiltersChange?: OnChangeFn<ColumnFiltersState>
+}
+
+export interface Table_ColumnFiltering {
+  /**
+   * Resets `columnFilters` to `initialState.columnFilters`.
+   *
+   * Pass `true` to ignore initial state and reset to `[]`.
+   */
+  resetColumnFilters: (defaultState?: boolean) => void
+  /**
+   * Updates column filter state with a next array or updater function.
+   */
+  setColumnFilters: (updater: Updater<ColumnFiltersState>) => void
+}
+
+export interface Table_RowModels_Filtered<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+> {
+  /**
+   * Resolves the row model after column and global filters have been applied.
+   */
+  getFilteredRowModel: () => RowModel<TFeatures, TData>
+  /**
+   * Reads the row model immediately before filtering.
+   */
+  getPreFilteredRowModel: () => RowModel<TFeatures, TData>
+}
+
+export interface CreateRowModel_Filtered<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+> {
+  /**
+   * If provided, this factory is called once per table and should return a
+   * function that calculates the filtered row model.
+   * - For server-side filtering, this function is unnecessary and can be ignored since the server should already return the filtered row model.
+   * - For client-side filtering, pass the exported `createFilteredRowModel()` or implement your own factory.
+   */
+  filteredRowModel?: (
+    table: Table<TFeatures, TData>,
+  ) => () => RowModel<TFeatures, TData>
+}
+
+export interface CachedRowModel_Filtered<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+> {
+  filteredRowModel: () => RowModel<TFeatures, TData>
+}

package/src/features/column-filtering/columnFilteringFeature.utils.ts

@@ -0,0 +1,331 @@
+import { cloneState, functionalUpdate, isFunction } from '../../utils'
+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 {
+  ColumnFiltersState,
+  FilterFn,
+} from './columnFilteringFeature.types'
+
+/**
+ * Creates the default column filter state.
+ *
+ * The feature default is an empty array, meaning no column filters are active.
+ * Reset APIs use this value when `defaultState` is `true`.
+ *
+ * @example
+ * ```ts
+ * const filters = getDefaultColumnFiltersState()
+ * ```
+ */
+export function getDefaultColumnFiltersState(): ColumnFiltersState {
+  return []
+}
+
+/**
+ * Chooses a built-in filter function from the column's first core row value.
+ *
+ * Strings use `includesString`, numbers use `inNumberRange`, booleans and
+ * objects use `equals`, arrays use `arrIncludes`, and unknown values fall back
+ * to `weakEquals`.
+ *
+ * @example
+ * ```ts
+ * const filterFn = column_getAutoFilterFn(column)
+ * ```
+ */
+export function column_getAutoFilterFn<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+  TValue extends CellData = CellData,
+>(column: Column_Internal<TFeatures, TData, TValue>) {
+  const filterFns: Record<string, FilterFn<TFeatures, TData>> | undefined =
+    column.table._rowModelFns.filterFns
+
+  const firstRow = column.table.getCoreRowModel().flatRows[0]
+
+  const value = firstRow ? firstRow.getValue(column.id) : undefined
+
+  if (typeof value === 'string') {
+    return filterFns?.includesString
+  }
+
+  if (typeof value === 'number') {
+    return filterFns?.inNumberRange
+  }
+
+  if (typeof value === 'boolean') {
+    return filterFns?.equals
+  }
+
+  if (value !== null && typeof value === 'object') {
+    return filterFns?.equals
+  }
+
+  if (Array.isArray(value)) {
+    return filterFns?.arrIncludes
+  }
+
+  return filterFns?.weakEquals
+}
+
+/**
+ * Resolves the filter function configured for a column.
+ *
+ * Function-valued `columnDef.filterFn` is returned directly, `'auto'` delegates
+ * to `column_getAutoFilterFn`, and string values are looked up in the table's
+ * filter function registry.
+ *
+ * @example
+ * ```ts
+ * const filterFn = column_getFilterFn(column)
+ * ```
+ */
+export function column_getFilterFn<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+  TValue extends CellData = CellData,
+>(
+  column: Column_Internal<TFeatures, TData, TValue>,
+): FilterFn<TFeatures, TData> | undefined {
+  let filterFn = null
+  const filterFns: Record<string, FilterFn<TFeatures, TData>> | undefined =
+    column.table._rowModelFns.filterFns
+  filterFn = isFunction(column.columnDef.filterFn)
+    ? column.columnDef.filterFn
+    : column.columnDef.filterFn === 'auto'
+      ? column_getAutoFilterFn(column)
+      : filterFns?.[column.columnDef.filterFn as string]
+
+  if (process.env.NODE_ENV === 'development' && !filterFn) {
+    console.warn(
+      `Could not find a valid 'column.filterFn' for column with the ID: ${column.id}.`,
+    )
+  }
+
+  return filterFn
+}
+
+/**
+ * Checks whether column filtering is enabled for this accessor column.
+ *
+ * The column must have an accessor and filtering must be enabled by the column
+ * definition, `enableColumnFilters`, and the table-wide `enableFilters` option.
+ *
+ * @example
+ * ```ts
+ * const canFilter = column_getCanFilter(column)
+ * ```
+ */
+export function column_getCanFilter<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+  TValue extends CellData = CellData,
+>(column: Column_Internal<TFeatures, TData, TValue>) {
+  return (
+    (column.columnDef.enableColumnFilter ?? true) &&
+    (column.table.options.enableColumnFilters ?? true) &&
+    (column.table.options.enableFilters ?? true) &&
+    !!column.accessorFn
+  )
+}
+
+/**
+ * Checks whether this column currently has an entry in `state.columnFilters`.
+ *
+ * This only reflects filter state presence; it does not indicate whether the
+ * filter removes any rows.
+ *
+ * @example
+ * ```ts
+ * const isFiltered = column_getIsFiltered(column)
+ * ```
+ */
+export function column_getIsFiltered<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+  TValue extends CellData = CellData,
+>(column: Column_Internal<TFeatures, TData, TValue>) {
+  return column_getFilterIndex(column) > -1
+}
+
+/**
+ * Reads this column's current filter value from `state.columnFilters`.
+ *
+ * Missing filter entries return `undefined`.
+ *
+ * @example
+ * ```ts
+ * const value = column_getFilterValue(column)
+ * ```
+ */
+export function column_getFilterValue<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+  TValue extends CellData = CellData,
+>(column: Column_Internal<TFeatures, TData, TValue>) {
+  return column.table.atoms.columnFilters
+    ?.get()
+    ?.find((d) => d.id === column.id)?.value
+}
+
+/**
+ * Finds this column's position in the ordered `state.columnFilters` array.
+ *
+ * The result is `-1` when the column has no active filter.
+ *
+ * @example
+ * ```ts
+ * const index = column_getFilterIndex(column)
+ * ```
+ */
+export function column_getFilterIndex<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+  TValue extends CellData = CellData,
+>(column: Column_Internal<TFeatures, TData, TValue>): number {
+  return (
+    column.table.atoms.columnFilters
+      ?.get()
+      ?.findIndex((d) => d.id === column.id) ?? -1
+  )
+}
+
+/**
+ * Adds, updates, or removes this column's filter value.
+ *
+ * The incoming value may be an updater. After resolution, `autoRemove` rules
+ * decide whether the filter should be removed instead of stored.
+ *
+ * @example
+ * ```ts
+ * column_setFilterValue(column, (old) => String(old ?? '').trim())
+ * ```
+ */
+export function column_setFilterValue<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+  TValue extends CellData = CellData,
+>(column: Column_Internal<TFeatures, TData, TValue>, value: any) {
+  table_setColumnFilters(column.table, (old) => {
+    const filterFn = column_getFilterFn(column)
+    const previousFilter = old.find((d) => d.id === column.id)
+
+    const newFilter = functionalUpdate(
+      value,
+      previousFilter ? previousFilter.value : undefined,
+    )
+
+    if (shouldAutoRemoveFilter(filterFn, newFilter, column)) {
+      return old.filter((d) => d.id !== column.id)
+    }
+
+    const newFilterObj = { id: column.id, value: newFilter }
+
+    if (previousFilter) {
+      return old.map((d) => {
+        if (d.id === column.id) {
+          return newFilterObj
+        }
+        return d
+      })
+    }
+
+    if (old.length) {
+      return [...old, newFilterObj]
+    }
+
+    return [newFilterObj]
+  })
+}
+
+/**
+ * Routes a column filter updater through the table's filter change handler.
+ *
+ * The resolved filters are cleaned before they are emitted: filters for known
+ * columns are removed when their filter function says the value should be
+ * auto-removed.
+ *
+ * @example
+ * ```ts
+ * table_setColumnFilters(table, (old) => old.filter((filter) => filter.id !== 'age'))
+ * ```
+ */
+export function table_setColumnFilters<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+>(
+  table: Table_Internal<TFeatures, TData>,
+  updater: Updater<ColumnFiltersState>,
+) {
+  const leafColumnsById = table.getAllLeafColumnsById()
+
+  const updateFn = (old: ColumnFiltersState) => {
+    return functionalUpdate(updater, old).filter((filter) => {
+      const column = leafColumnsById[filter.id]
+
+      if (column) {
+        const filterFn = column_getFilterFn(column)
+
+        if (shouldAutoRemoveFilter(filterFn, filter.value, column)) {
+          return false
+        }
+      }
+
+      return true
+    })
+  }
+
+  table.options.onColumnFiltersChange?.(updateFn)
+}
+
+/**
+ * Resets `columnFilters` to the configured initial state or feature default.
+ *
+ * With no argument, the reset clones `table.initialState.columnFilters` when it
+ * exists. Passing `true` ignores initial state and resets to `[]`.
+ *
+ * @example
+ * ```ts
+ * table_resetColumnFilters(table)
+ * table_resetColumnFilters(table, true)
+ * ```
+ */
+export function table_resetColumnFilters<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+>(table: Table_Internal<TFeatures, TData>, defaultState?: boolean) {
+  table_setColumnFilters(
+    table,
+    defaultState ? [] : cloneState(table.initialState.columnFilters ?? []),
+  )
+}
+
+/**
+ * Returns whether a filter value should be removed from filter state.
+ *
+ * This checks the filter function's `autoRemove` hook and built-in empty-value rules.
+ *
+ * @example
+ * ```ts
+ * const removeFilter = shouldAutoRemoveFilter(filterFn, value, column)
+ * ```
+ */
+export function shouldAutoRemoveFilter<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+  TValue extends CellData = CellData,
+>(
+  filterFn?: FilterFn<TFeatures, TData>,
+  value?: any,
+  column?: Column_Internal<TFeatures, TData, TValue>,
+) {
+  return (
+    (filterFn && filterFn.autoRemove
+      ? filterFn.autoRemove(value, column)
+      : false) ||
+    typeof value === 'undefined' ||
+    (typeof value === 'string' && !value)
+  )
+}