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

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

@@ -0,0 +1,121 @@
+import {
+  assignPrototypeAPIs,
+  assignTableAPIs,
+  makeStateUpdater,
+} from '../../utils'
+import {
+  column_getAutoFilterFn,
+  column_getCanFilter,
+  column_getFilterFn,
+  column_getFilterIndex,
+  column_getFilterValue,
+  column_getIsFiltered,
+  column_setFilterValue,
+  getDefaultColumnFiltersState,
+  table_resetColumnFilters,
+  table_setColumnFilters,
+} from './columnFilteringFeature.utils'
+import type { RowData } from '../../types/type-utils'
+import type { TableFeature, TableFeatures } from '../../types/TableFeatures'
+// import type {
+//   CachedRowModel_Filtered,
+//   ColumnDef_ColumnFiltering,
+//   Column_ColumnFiltering,
+//   CreateRowModel_Filtered,
+//   RowModelFns_ColumnFiltering,
+//   Row_ColumnFiltering,
+//   TableOptions_ColumnFiltering,
+//   TableState_ColumnFiltering,
+//   Table_ColumnFiltering,
+// } from './columnFilteringFeature.types'
+
+interface ColumnFilteringFeatureConstructors<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+> {
+  // CachedRowModel: CachedRowModel_Filtered<TFeatures, TData>
+  // Column: Column_ColumnFiltering<TFeatures, TData>
+  // ColumnDef: ColumnDef_ColumnFiltering<TFeatures, TData>
+  // CreateRowModels: CreateRowModel_Filtered<TFeatures, TData>
+  // Row: Row_ColumnFiltering<TFeatures, TData>
+  // RowModelFns: RowModelFns_ColumnFiltering<TFeatures, TData>
+  // Table: Table_ColumnFiltering<TFeatures, TData>
+  // TableOptions: TableOptions_ColumnFiltering<TFeatures, TData>
+  // TableState: TableState_ColumnFiltering
+}
+
+export function constructColumnFilteringFeature<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+>(): TableFeature<ColumnFilteringFeatureConstructors<TFeatures, TData>> {
+  return {
+    getInitialState: (initialState) => {
+      return {
+        columnFilters: getDefaultColumnFiltersState(),
+        ...initialState,
+      }
+    },
+
+    getDefaultColumnDef: () => {
+      return {
+        filterFn: 'auto',
+      }
+    },
+
+    getDefaultTableOptions: (table) => {
+      return {
+        onColumnFiltersChange: makeStateUpdater('columnFilters', table),
+        filterFromLeafRows: false,
+        maxLeafRowFilterDepth: 100,
+      }
+    },
+
+    assignColumnPrototype: (prototype, table) => {
+      assignPrototypeAPIs('columnFilteringFeature', prototype, table, {
+        column_getAutoFilterFn: {
+          fn: (column) => column_getAutoFilterFn(column),
+        },
+        column_getFilterFn: {
+          fn: (column) => column_getFilterFn(column),
+        },
+        column_getCanFilter: {
+          fn: (column) => column_getCanFilter(column),
+        },
+        column_getIsFiltered: {
+          fn: (column) => column_getIsFiltered(column),
+        },
+        column_getFilterValue: {
+          fn: (column) => column_getFilterValue(column),
+        },
+        column_getFilterIndex: {
+          fn: (column) => column_getFilterIndex(column),
+        },
+        column_setFilterValue: {
+          fn: (column, value) => column_setFilterValue(column, value),
+        },
+      })
+    },
+
+    initRowInstanceData: (row) => {
+      ;(row as any).columnFilters = {}
+      ;(row as any).columnFiltersMeta = {}
+    },
+
+    constructTableAPIs: (table) => {
+      assignTableAPIs('columnFilteringFeature', table, {
+        table_setColumnFilters: {
+          fn: (updater) => table_setColumnFilters(table, updater),
+        },
+        table_resetColumnFilters: {
+          fn: (defaultState) => table_resetColumnFilters(table, defaultState),
+        },
+      })
+    },
+  }
+}
+
+/**
+ * The Column Filtering feature adds column filtering state and APIs to the table, row, and column objects.
+ * **Note:** This does not include Global Filtering. The globalFilteringFeature feature has been split out into its own standalone feature.
+ */
+export const columnFilteringFeature = constructColumnFilteringFeature()

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

@@ -0,0 +1,219 @@
+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/disables the **column** filter for this column.
+   */
+  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>
+  /**
+   * Returns whether or not the column can 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
+  /**
+   * Returns the current filter value for the column.
+   */
+  getFilterValue: () => unknown
+  /**
+   * Returns whether or not the column is currently filtered.
+   */
+  getIsFiltered: () => boolean
+  /**
+   * A function that sets the current filter value for the column. You can pass it a value or an updater function for immutability-safe operations on existing values.
+   */
+  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/disables **column** filtering for all columns.
+   */
+  enableColumnFilters?: boolean
+  /**
+   * Enables/disables all filtering for the table.
+   */
+  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
+  /**
+   * If provided, this function will be called with an `updaterFn` when `state.columnFilters` changes. This overrides the default internal state management, so you will need to persist the state change either fully or partially outside of the table.
+   */
+  onColumnFiltersChange?: OnChangeFn<ColumnFiltersState>
+}
+
+export interface Table_ColumnFiltering {
+  /**
+   * Resets the **columnFilters** state to `initialState.columnFilters`, or `true` can be passed to force a default blank state reset to `[]`.
+   */
+  resetColumnFilters: (defaultState?: boolean) => void
+  /**
+   * Sets or updates the `state.columnFilters` state.
+   */
+  setColumnFilters: (updater: Updater<ColumnFiltersState>) => void
+}
+
+export interface Table_RowModels_Filtered<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+> {
+  /**
+   * Returns the row model for the table after **column** filtering has been applied.
+   */
+  getFilteredRowModel: () => RowModel<TFeatures, TData>
+  /**
+   * Returns the row model for the table before any **column** filtering has been applied.
+   */
+  getPreFilteredRowModel: () => RowModel<TFeatures, TData>
+}
+
+export interface CreateRowModel_Filtered<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+> {
+  /**
+   * If provided, this function is called **once** per table and should return a **new function** which will calculate and return the row model for the table when it's filtered.
+   * - 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, this function is required. A default implementation is provided via any table adapter's `{ getFilteredRowModel }` export.
+   */
+  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,213 @@
+import { 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'
+
+export function getDefaultColumnFiltersState(): ColumnFiltersState {
+  return structuredClone([])
+}
+
+export function column_getAutoFilterFn<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+  TValue extends CellData = CellData,
+>(column: Column_Internal<TFeatures, TData, TValue>) {
+  const filterFns = column.table._rowModelFns.filterFns as
+    | Record<string, FilterFn<TFeatures, TData>>
+    | undefined
+
+  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
+}
+
+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 = column.table._rowModelFns.filterFns as
+    | Record<string, FilterFn<TFeatures, TData>>
+    | undefined
+  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
+}
+
+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
+  )
+}
+
+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
+}
+
+export function column_getFilterValue<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+  TValue extends CellData = CellData,
+>(column: Column_Internal<TFeatures, TData, TValue>) {
+  return column.table.store.state.columnFilters?.find((d) => d.id === column.id)
+    ?.value
+}
+
+export function column_getFilterIndex<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+  TValue extends CellData = CellData,
+>(column: Column_Internal<TFeatures, TData, TValue>): number {
+  return (
+    column.table.store.state.columnFilters?.findIndex(
+      (d) => d.id === column.id,
+    ) ?? -1
+  )
+}
+
+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]
+  })
+}
+
+export function table_setColumnFilters<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+>(
+  table: Table_Internal<TFeatures, TData>,
+  updater: Updater<ColumnFiltersState>,
+) {
+  const leafColumns = table.getAllLeafColumns()
+
+  const updateFn = (old: ColumnFiltersState) => {
+    return functionalUpdate(updater, old).filter((filter) => {
+      const column = leafColumns.find((d) => d.id === filter.id)
+
+      if (column) {
+        const filterFn = column_getFilterFn(column)
+
+        if (shouldAutoRemoveFilter(filterFn, filter.value, column)) {
+          return false
+        }
+      }
+
+      return true
+    })
+  }
+
+  table.options.onColumnFiltersChange?.(updateFn)
+}
+
+export function table_resetColumnFilters<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+>(table: Table_Internal<TFeatures, TData>, defaultState?: boolean) {
+  table_setColumnFilters(
+    table,
+    defaultState ? [] : (table.initialState.columnFilters ?? []),
+  )
+}
+
+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 Column_Internal<TFeatures, TData, unknown>,
+        )
+      : false) ||
+    typeof value === 'undefined' ||
+    (typeof value === 'string' && !value)
+  )
+}