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

package/src/features/column-visibility/columnVisibilityFeature.utils.ts

@@ -0,0 +1,384 @@
+import { callMemoOrStaticFn, cloneState } from '../../utils'
+import { getDefaultColumnPinningState } from '../column-pinning/columnPinningFeature.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 { Cell } from '../../types/Cell'
+import type { Column_Internal } from '../../types/Column'
+import type { ColumnVisibilityState } from './columnVisibilityFeature.types'
+import type { Row } from '../../types/Row'
+
+/**
+ * Creates the default column visibility state.
+ *
+ * The feature default is an empty object, where missing column ids are treated
+ * as visible. Reset APIs use this value when `defaultState` is `true`.
+ *
+ * @example
+ * ```ts
+ * const visibility = getDefaultColumnVisibilityState()
+ * ```
+ */
+export function getDefaultColumnVisibilityState(): ColumnVisibilityState {
+  return {}
+}
+
+/**
+ * Updates this column's visibility when hiding is allowed.
+ *
+ * Passing `visible` stores that value. Omitting it flips the column's current
+ * visibility state. Columns that cannot hide are left unchanged.
+ *
+ * @example
+ * ```ts
+ * column_toggleVisibility(column)
+ * ```
+ */
+export function column_toggleVisibility<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+  TValue extends CellData = CellData,
+>(column: Column_Internal<TFeatures, TData, TValue>, visible?: boolean): void {
+  if (column_getCanHide(column)) {
+    table_setColumnVisibility(column.table, (old) => ({
+      ...old,
+      [column.id]:
+        visible ??
+        !callMemoOrStaticFn(column, 'getIsVisible', column_getIsVisible),
+    }))
+  }
+}
+
+/**
+ * Checks whether this column is visible.
+ *
+ * Leaf columns read `state.columnVisibility[column.id]`, where missing entries
+ * default to visible. Parent columns are visible when at least one child column
+ * is visible.
+ *
+ * @example
+ * ```ts
+ * const visible = column_getIsVisible(column)
+ * ```
+ */
+export function column_getIsVisible<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+  TValue extends CellData = CellData,
+>(column: Column_Internal<TFeatures, TData, TValue>): boolean {
+  const childColumns = column.columns
+  return (
+    (childColumns.length
+      ? childColumns.some((childColumn) =>
+          callMemoOrStaticFn(childColumn, 'getIsVisible', column_getIsVisible),
+        )
+      : column.table.atoms.columnVisibility?.get()?.[column.id]) ?? true
+  )
+}
+
+/**
+ * Checks whether this column is allowed to be hidden.
+ *
+ * Both `columnDef.enableHiding` and table `enableHiding` default to `true`.
+ *
+ * @example
+ * ```ts
+ * const canHide = column_getCanHide(column)
+ * ```
+ */
+export function column_getCanHide<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+  TValue extends CellData = CellData,
+>(column: Column_Internal<TFeatures, TData, TValue>) {
+  return (
+    (column.columnDef.enableHiding ?? true) &&
+    (column.table.options.enableHiding ?? true)
+  )
+}
+
+/**
+ * Creates a checkbox-style handler that writes this column's visibility.
+ *
+ * The handler reads `event.target.checked`, so it is intended for visibility
+ * controls whose checked state means "visible".
+ *
+ * @example
+ * ```ts
+ * const onChange = column_getToggleVisibilityHandler(column)
+ * ```
+ */
+export function column_getToggleVisibilityHandler<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+  TValue extends CellData = CellData,
+>(column: Column_Internal<TFeatures, TData, TValue>) {
+  return (e: unknown) => {
+    column_toggleVisibility(
+      column,
+      ((e as MouseEvent).target as HTMLInputElement).checked,
+    )
+  }
+}
+
+/**
+ * Collects the cells from this row whose columns are visible.
+ *
+ * When column pinning is active, the result is ordered as left-pinned cells,
+ * center cells, then right-pinned cells.
+ *
+ * @example
+ * ```ts
+ * const visibleCells = row_getVisibleCells(row)
+ * ```
+ */
+export function row_getVisibleCells<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+>(row: Row<TFeatures, TData>): Array<Cell<TFeatures, TData, unknown>> {
+  const allCells = row.getAllCells()
+  const visibleCells: Array<Cell<TFeatures, TData, unknown>> = []
+  for (let i = 0; i < allCells.length; i++) {
+    const cell = allCells[i]!
+    if (callMemoOrStaticFn(cell.column, 'getIsVisible', column_getIsVisible)) {
+      visibleCells.push(cell)
+    }
+  }
+
+  const { left, right } =
+    row.table.atoms.columnPinning?.get() ?? getDefaultColumnPinningState()
+  if (!left.length && !right.length) return visibleCells // no pinning, return early
+
+  const visibleCellsByColumnId = callMemoOrStaticFn(
+    row,
+    'getVisibleCellsByColumnId',
+    row_getVisibleCellsByColumnId,
+  )
+
+  const leftCells: Array<Cell<TFeatures, TData, unknown>> = []
+  for (let i = 0; i < left.length; i++) {
+    const cell = visibleCellsByColumnId[left[i]!]
+    if (cell) leftCells.push(cell)
+  }
+
+  const rightCells: Array<Cell<TFeatures, TData, unknown>> = []
+  for (let i = 0; i < right.length; i++) {
+    const cell = visibleCellsByColumnId[right[i]!]
+    if (cell) rightCells.push(cell)
+  }
+
+  // Center cells: visible cells in natural column order, minus pinned ones.
+  const centerCells: Array<Cell<TFeatures, TData, unknown>> = []
+  for (let i = 0; i < visibleCells.length; i++) {
+    const cell = visibleCells[i]!
+    const id = cell.column.id
+    if (!left.includes(id) && !right.includes(id)) centerCells.push(cell)
+  }
+
+  return [...leftCells, ...centerCells, ...rightCells]
+}
+
+/**
+ * Builds a lookup map of this row's visible cells keyed by column id.
+ *
+ * Hidden columns are omitted from the map.
+ *
+ * @example
+ * ```ts
+ * const visibleCellsById = row_getVisibleCellsByColumnId(row)
+ * ```
+ */
+export function row_getVisibleCellsByColumnId<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+>(row: Row<TFeatures, TData>): Record<string, Cell<TFeatures, TData, unknown>> {
+  const result: Record<string, Cell<TFeatures, TData, unknown>> = {}
+  const allCells = row.getAllCells()
+  for (let i = 0; i < allCells.length; i++) {
+    const cell = allCells[i]!
+    if (callMemoOrStaticFn(cell.column, 'getIsVisible', column_getIsVisible)) {
+      result[cell.column.id] = cell
+    }
+  }
+  return result
+}
+
+/**
+ * Filters the flat column list down to visible columns.
+ *
+ * Parent/group columns are included when `column_getIsVisible` considers them
+ * visible.
+ *
+ * @example
+ * ```ts
+ * const columns = table_getVisibleFlatColumns(table)
+ * ```
+ */
+export function table_getVisibleFlatColumns<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+>(table: Table_Internal<TFeatures, TData>) {
+  return table
+    .getAllFlatColumns()
+    .filter((column) =>
+      callMemoOrStaticFn(column, 'getIsVisible', column_getIsVisible),
+    )
+}
+
+/**
+ * Filters leaf columns down to those currently visible.
+ *
+ * This is the column list most row rendering code uses before pinning-specific
+ * partitioning.
+ *
+ * @example
+ * ```ts
+ * const columns = table_getVisibleLeafColumns(table)
+ * ```
+ */
+export function table_getVisibleLeafColumns<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+>(table: Table_Internal<TFeatures, TData>) {
+  return table
+    .getAllLeafColumns()
+    .filter((column) =>
+      callMemoOrStaticFn(column, 'getIsVisible', column_getIsVisible),
+    )
+}
+
+/**
+ * Routes a column visibility updater through the table's visibility change handler.
+ *
+ * The updater may be a next visibility map or a function of the previous map,
+ * matching the instance `table.setColumnVisibility` behavior.
+ *
+ * @example
+ * ```ts
+ * table_setColumnVisibility(table, (old) => ({ ...old, age: false }))
+ * ```
+ */
+export function table_setColumnVisibility<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+>(
+  table: Table_Internal<TFeatures, TData>,
+  updater: Updater<ColumnVisibilityState>,
+) {
+  table.options.onColumnVisibilityChange?.(updater)
+}
+
+/**
+ * Resets `columnVisibility` to the configured initial state or feature default.
+ *
+ * With no argument, the reset clones `table.initialState.columnVisibility` when
+ * it exists. Passing `true` ignores initial state and resets to `{}`.
+ *
+ * @example
+ * ```ts
+ * table_resetColumnVisibility(table)
+ * table_resetColumnVisibility(table, true)
+ * ```
+ */
+export function table_resetColumnVisibility<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+>(table: Table_Internal<TFeatures, TData>, defaultState?: boolean) {
+  table_setColumnVisibility(
+    table,
+    defaultState ? {} : cloneState(table.initialState.columnVisibility ?? {}),
+  )
+}
+
+/**
+ * Shows or hides every hideable leaf column.
+ *
+ * Columns that cannot hide stay visible when toggling all columns off.
+ *
+ * @example
+ * ```ts
+ * table_toggleAllColumnsVisible(table)
+ * ```
+ */
+export function table_toggleAllColumnsVisible<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+>(table: Table_Internal<TFeatures, TData>, value?: boolean) {
+  value = value ?? !table_getIsAllColumnsVisible(table)
+
+  const visibility: Record<string, boolean> = {}
+  const leafColumns = table.getAllLeafColumns()
+  for (let i = 0; i < leafColumns.length; i++) {
+    const column = leafColumns[i]!
+    visibility[column.id] = !value ? !column_getCanHide(column) : value
+  }
+
+  table_setColumnVisibility(table, visibility)
+}
+
+/**
+ * Checks whether every leaf column is currently visible.
+ *
+ * Non-hideable columns are naturally visible because missing visibility entries
+ * default to `true`.
+ *
+ * @example
+ * ```ts
+ * const allVisible = table_getIsAllColumnsVisible(table)
+ * ```
+ */
+export function table_getIsAllColumnsVisible<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+>(table: Table_Internal<TFeatures, TData>) {
+  return !table
+    .getAllLeafColumns()
+    .some(
+      (column) =>
+        !callMemoOrStaticFn(column, 'getIsVisible', column_getIsVisible),
+    )
+}
+
+/**
+ * Checks whether at least one leaf column is currently visible.
+ *
+ * This is useful for tri-state "show all columns" controls.
+ *
+ * @example
+ * ```ts
+ * const someVisible = table_getIsSomeColumnsVisible(table)
+ * ```
+ */
+export function table_getIsSomeColumnsVisible<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+>(table: Table_Internal<TFeatures, TData>) {
+  return table
+    .getAllLeafColumns()
+    .some((column) =>
+      callMemoOrStaticFn(column, 'getIsVisible', column_getIsVisible),
+    )
+}
+
+/**
+ * Creates a checkbox-style handler that shows or hides all columns.
+ *
+ * The handler reads `event.target.checked`, so it is intended for controls whose
+ * checked state means "all columns visible".
+ *
+ * @example
+ * ```ts
+ * const onChange = table_getToggleAllColumnsVisibilityHandler(table)
+ * ```
+ */
+export function table_getToggleAllColumnsVisibilityHandler<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+>(table: Table_Internal<TFeatures, TData>) {
+  return (e: unknown) => {
+    table_toggleAllColumnsVisible(
+      table,
+      ((e as MouseEvent).target as HTMLInputElement).checked,
+    )
+  }
+}

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

@@ -0,0 +1,65 @@
+import {
+  assignPrototypeAPIs,
+  assignTableAPIs,
+  makeStateUpdater,
+} from '../../utils'
+import {
+  column_getCanGlobalFilter,
+  table_getGlobalAutoFilterFn,
+  table_getGlobalFilterFn,
+  table_resetGlobalFilter,
+  table_setGlobalFilter,
+} from './globalFilteringFeature.utils'
+import type { TableFeature } from '../../types/TableFeatures'
+
+/**
+ * Feature that adds global filtering state, defaults, and global filter APIs.
+ */
+export const globalFilteringFeature: TableFeature = {
+  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),
+      },
+    })
+  },
+}

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,118 @@
+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> | undefined {
+  const { globalFilterFn: globalFilterFn } = table.options
+  const filterFns: Record<string, FilterFn<TFeatures, TData>> | undefined =
+    table._rowModelFns.filterFns
+
+  const filterFn = isFunction(globalFilterFn)
+    ? globalFilterFn
+    : globalFilterFn === 'auto'
+      ? table_getGlobalAutoFilterFn()
+      : filterFns?.[globalFilterFn as string]
+
+  return filterFn
+}
+
+/**
+ * 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),
+  )
+}