@tanstack/table-core 9.0.0-beta.51 → 9.0.0-beta.53

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

@@ -1,308 +0,0 @@
-import type { BuiltInFilterFn } from './filterFns'
-import type {
-  CellData,
-  OnChangeFn,
-  RowData,
-  TransformDataValueFn,
-  Updater,
-} from '../../types/type-utils'
-import type { IsAny, 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 {}
-
-/**
- * Resolves the type of the filter meta attached to rows for a feature set.
- *
- * When the features object declares a `filterMeta` type-only slot
- * (`tableFeatures({ ..., filterMeta: {} as MyFilterMeta })`), that type wins.
- * Otherwise this falls back to the global declaration-merged `FilterMeta`
- * interface.
- */
-export type ExtractFilterMeta<TFeatures extends TableFeatures> =
-  IsAny<TFeatures> extends true
-    ? FilterMeta
-    : TFeatures extends { filterMeta: infer TFilterMeta extends object }
-      ? TFilterMeta
-      : 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<
-  in out TFeatures extends TableFeatures,
-  in out TData extends RowData,
-> {
-  filterFn: FilterFn<TFeatures, TData>
-  id: string
-  resolvedValue: unknown
-}
-
-export interface RowModelFns_ColumnFiltering<
-  in out TFeatures extends TableFeatures,
-  in out TData extends RowData,
-> {
-  filterFns: Record<string, FilterFn<TFeatures, TData>>
-}
-
-export interface FilterFn<
-  in out TFeatures extends TableFeatures,
-  in out TData extends RowData,
-> {
-  (
-    row: Row<TFeatures, TData>,
-    columnId: string,
-    filterValue: any,
-    addMeta?: (meta: ExtractFilterMeta<TFeatures>) => void,
-  ): boolean
-  /**
-   * Removes the filter from `state.columnFilters` when the filter value fails
-   * this test (e.g. empty strings for text filters).
-   */
-  autoRemove?: ColumnFilterAutoRemoveTestFn<TFeatures, TData>
-  /**
-   * Normalizes the filter value before filtering runs.
-   *
-   * The table applies this once per filter (not per row) and passes the
-   * resolved value to the filter function as `filterValue`.
-   */
-  resolveFilterValue?: TransformFilterValueFn<TFeatures, TData>
-  /**
-   * Normalizes each row's value before it is compared against the filter
-   * value. Only honored by filter functions built with `constructFilterFn`
-   * (including all built-in filter functions).
-   */
-  resolveDataValue?: TransformDataValueFn
-}
-
-/**
- * The definition object accepted by `constructFilterFn`.
- *
- * `filter` is a value-level comparator: it receives the row's (resolved) data
- * value and the (resolved) filter value instead of the whole row, so
- * normalization concerns stay in `resolveDataValue`/`resolveFilterValue`.
- */
-export interface FilterFnDef<
-  in out TFeatures extends TableFeatures,
-  in out TData extends RowData,
-> {
-  filter: (
-    dataValue: any,
-    filterValue: any,
-    row: Row<TFeatures, TData>,
-    columnId: string,
-    addMeta?: (meta: ExtractFilterMeta<TFeatures>) => void,
-  ) => boolean
-  autoRemove?: (filterValue: any) => boolean
-  resolveFilterValue?: (filterValue: any) => any
-  resolveDataValue?: TransformDataValueFn
-}
-
-/**
- * The shape returned by `constructFilterFn`: a `FilterFn` with its definition
- * attached, so variants can be built by spreading it into another
- * `constructFilterFn` call.
- *
- * The call signature is generic so a created filter function can be used with
- * any table's rows, regardless of the feature set it was defined against.
- */
-export interface CreatedFilterFn<
-  in out TFeatures extends TableFeatures,
-  in out TData extends RowData,
-> extends FilterFnDef<TFeatures, TData> {
-  <TRowFeatures extends TableFeatures, TRowData extends RowData>(
-    row: Row<TRowFeatures, TRowData>,
-    columnId: string,
-    filterValue: any,
-    addMeta?: (meta: ExtractFilterMeta<TRowFeatures>) => void,
-  ): boolean
-}
-
-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>>
-
-/**
- * Resolves the valid string names for `columnDef.filterFn` and
- * `options.globalFilterFn` for a feature set.
- *
- * When the features object declares a `filterFns` registry
- * (`tableFeatures({ ..., filterFns })`), its keys are the only valid names; a
- * name is only assignable if a filter function is actually registered for it.
- * Otherwise this falls back to the global declaration-merged `FilterFns`
- * interface.
- */
-export type ExtractFilterFnKeys<TFeatures extends TableFeatures> =
-  IsAny<TFeatures> extends true
-    ? keyof FilterFns | BuiltInFilterFn
-    : TFeatures extends { filterFns: infer TFilterFns extends object }
-      ? Extract<keyof TFilterFns, string>
-      : keyof FilterFns
-
-export type FilterFnOption<
-  TFeatures extends TableFeatures,
-  TData extends RowData,
-> = 'auto' | ExtractFilterFnKeys<TFeatures> | FilterFn<TFeatures, TData>
-
-export interface ColumnDef_ColumnFiltering<
-  in out TFeatures extends TableFeatures,
-  in out 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<
-  in out TFeatures extends TableFeatures,
-  in out 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<
-  in out TFeatures extends TableFeatures,
-  in out _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, ExtractFilterMeta<TFeatures>>
-}
-
-export interface TableOptions_ColumnFiltering<
-  in out _TFeatures extends TableFeatures,
-  in out _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<
-  in out TFeatures extends TableFeatures,
-  in out 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 CachedRowModel_Filtered<
-  in out TFeatures extends TableFeatures,
-  in out TData extends RowData,
-> {
-  filteredRowModel: () => RowModel<TFeatures, TData>
-}

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

@@ -1,345 +0,0 @@
-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`, dates use `inDateRange`, arrays use `arrIncludes`,
- * and unknown values fall back to `weakEquals`.
- *
- * The chosen filter function is looked up in the table's `filterFns`
- * registry. When it is not registered there, this returns `undefined` and
- * warns in development instead of substituting a different filter function.
- *
- * @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
-
-  let filterFnName: string
-
-  if (typeof value === 'string') {
-    filterFnName = 'includesString'
-  } else if (typeof value === 'number') {
-    filterFnName = 'inNumberRange'
-  } else if (typeof value === 'boolean') {
-    filterFnName = 'equals'
-  } else if (Array.isArray(value)) {
-    filterFnName = 'arrIncludes'
-  } else if (Object.prototype.toString.call(value) === '[object Date]') {
-    filterFnName = 'inDateRange'
-  } else if (value !== null && typeof value === 'object') {
-    filterFnName = 'equals'
-  } else {
-    filterFnName = 'weakEquals'
-  }
-
-  const filterFn = filterFns?.[filterFnName]
-
-  if (process.env.NODE_ENV === 'development' && !filterFn) {
-    console.warn(
-      `filterFn '${filterFnName}' (auto) for column '${column.id}' is not registered`,
-    )
-  }
-
-  return filterFn
-}
-
-/**
- * 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 &&
-    column.columnDef.filterFn !== 'auto' // the auto picker warns on its own
-  ) {
-    console.warn(
-      `filterFn '${String(column.columnDef.filterFn)}' for column '${column.id}' is not registered`,
-    )
-  }
-
-  return filterFn ?? undefined
-}
-
-/**
- * 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 as any)
-      : false) ||
-    typeof value === 'undefined' ||
-    (typeof value === 'string' && !value)
-  )
-}