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

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

@@ -0,0 +1,155 @@
+import {
+  assignPrototypeAPIs,
+  assignTableAPIs,
+  makeStateUpdater,
+} from '../../utils'
+import {
+  row_getCenterVisibleCells,
+  row_getLeftVisibleCells,
+  row_getRightVisibleCells,
+} from '../column-pinning/columnPinningFeature.utils'
+import {
+  column_getCanHide,
+  column_getIsVisible,
+  column_getToggleVisibilityHandler,
+  column_toggleVisibility,
+  getDefaultColumnVisibilityState,
+  row_getAllVisibleCells,
+  row_getVisibleCells,
+  table_getIsAllColumnsVisible,
+  table_getIsSomeColumnsVisible,
+  table_getToggleAllColumnsVisibilityHandler,
+  table_getVisibleFlatColumns,
+  table_getVisibleLeafColumns,
+  table_resetColumnVisibility,
+  table_setColumnVisibility,
+  table_toggleAllColumnsVisible,
+} from './columnVisibilityFeature.utils'
+import type { RowData } from '../../types/type-utils'
+import type { TableFeature, TableFeatures } from '../../types/TableFeatures'
+// import type {
+//   ColumnDef_ColumnVisibility,
+//   Column_ColumnVisibility,
+//   Row_ColumnVisibility,
+//   TableOptions_ColumnVisibility,
+//   TableState_ColumnVisibility,
+//   Table_ColumnVisibility,
+// } from './columnVisibilityFeature.types'
+
+interface ColumnVisibilityFeatureConstructors<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+> {
+  // ColumnDef: ColumnDef_ColumnVisibility
+  // Column: Column_ColumnVisibility
+  // Row: Row_ColumnVisibility<TFeatures, TData>
+  // Table: Table_ColumnVisibility<TFeatures, TData>
+  // TableOptions: TableOptions_ColumnVisibility
+  // TableState: TableState_ColumnVisibility
+}
+
+export function constructColumnVisibilityFeature<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+>(): TableFeature<ColumnVisibilityFeatureConstructors<TFeatures, TData>> {
+  return {
+    getInitialState: (initialState) => {
+      return {
+        columnVisibility: getDefaultColumnVisibilityState(),
+        ...initialState,
+      }
+    },
+
+    getDefaultTableOptions: (table) => {
+      return {
+        onColumnVisibilityChange: makeStateUpdater('columnVisibility', table),
+      }
+    },
+
+    assignColumnPrototype: (prototype, table) => {
+      assignPrototypeAPIs('columnVisibilityFeature', prototype, table, {
+        column_getIsVisible: {
+          fn: (column) => column_getIsVisible(column),
+          memoDeps: (column) => [
+            column.table.options.columns,
+            column.table.store.state.columnVisibility,
+            column.columns,
+          ],
+        },
+        column_getCanHide: {
+          fn: (column) => column_getCanHide(column),
+        },
+        column_getToggleVisibilityHandler: {
+          fn: (column) => column_getToggleVisibilityHandler(column),
+        },
+        column_toggleVisibility: {
+          fn: (column, visible) => column_toggleVisibility(column, visible),
+        },
+      })
+    },
+
+    assignRowPrototype: (prototype, table) => {
+      assignPrototypeAPIs('columnVisibilityFeature', prototype, table, {
+        row_getAllVisibleCells: {
+          fn: (row) => row_getAllVisibleCells(row),
+          memoDeps: (row) => [
+            row.getAllCells(),
+            row.table.store.state.columnVisibility,
+          ],
+        },
+        row_getVisibleCells: {
+          fn: (row, left, center, right) =>
+            row_getVisibleCells(left, center, right),
+          memoDeps: (row) => [
+            row_getLeftVisibleCells(row),
+            row_getCenterVisibleCells(row),
+            row_getRightVisibleCells(row),
+          ],
+        },
+      })
+    },
+
+    constructTableAPIs: (table) => {
+      assignTableAPIs('columnVisibilityFeature', table, {
+        table_getVisibleFlatColumns: {
+          fn: () => table_getVisibleFlatColumns(table),
+          memoDeps: () => [
+            table.store.state.columnVisibility,
+            table.options.columns,
+          ],
+        },
+        table_getVisibleLeafColumns: {
+          fn: () => table_getVisibleLeafColumns(table),
+          memoDeps: () => [
+            table.store.state.columnVisibility,
+            table.options.columns,
+          ],
+        },
+        table_setColumnVisibility: {
+          fn: (updater) => table_setColumnVisibility(table, updater),
+        },
+        table_resetColumnVisibility: {
+          fn: (defaultState) =>
+            table_resetColumnVisibility(table, defaultState),
+        },
+        table_toggleAllColumnsVisible: {
+          fn: (value) => table_toggleAllColumnsVisible(table, value),
+        },
+        table_getIsAllColumnsVisible: {
+          fn: () => table_getIsAllColumnsVisible(table),
+        },
+        table_getIsSomeColumnsVisible: {
+          fn: () => table_getIsSomeColumnsVisible(table),
+        },
+        table_getToggleAllColumnsVisibilityHandler: {
+          fn: () => table_getToggleAllColumnsVisibilityHandler(table),
+        },
+      })
+    },
+  }
+}
+
+/**
+ * The Column Visibility feature adds column visibility state and APIs to the table, row, and column objects.
+ */
+export const columnVisibilityFeature = constructColumnVisibilityFeature()

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

@@ -0,0 +1,101 @@
+import type { OnChangeFn, RowData, Updater } from '../../types/type-utils'
+import type { TableFeatures } from '../../types/TableFeatures'
+import type { Cell } from '../../types/Cell'
+import type { Column } from '../../types/Column'
+
+export type ColumnVisibilityState = Record<string, boolean>
+
+export interface TableState_ColumnVisibility {
+  columnVisibility: ColumnVisibilityState
+}
+
+export interface TableOptions_ColumnVisibility {
+  /**
+   * Whether to enable column hiding. Defaults to `true`.
+   */
+  enableHiding?: boolean
+  /**
+   * If provided, this function will be called with an `updaterFn` when `state.columnVisibility` 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.
+   */
+  onColumnVisibilityChange?: OnChangeFn<ColumnVisibilityState>
+}
+
+export type VisibilityDefaultOptions = Pick<
+  TableOptions_ColumnVisibility,
+  'onColumnVisibilityChange'
+>
+
+export interface Table_ColumnVisibility<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+> {
+  /**
+   * Returns whether all columns are visible
+   */
+  getIsAllColumnsVisible: () => boolean
+  /**
+   * Returns whether any columns are visible
+   */
+  getIsSomeColumnsVisible: () => boolean
+  /**
+   * Returns a handler for toggling the visibility of all columns, meant to be bound to a `input[type=checkbox]` element.
+   */
+  getToggleAllColumnsVisibilityHandler: () => (event: unknown) => void
+  /**
+   * Returns a flat array of columns that are visible, including parent columns.
+   */
+  getVisibleFlatColumns: () => Array<Column<TFeatures, TData, unknown>>
+  /**
+   * Returns a flat array of leaf-node columns that are visible.
+   */
+  getVisibleLeafColumns: () => Array<Column<TFeatures, TData, unknown>>
+  /**
+   * Resets the column visibility state to the initial state. If `defaultState` is provided, the state will be reset to `{}`
+   */
+  resetColumnVisibility: (defaultState?: boolean) => void
+  /**
+   * Sets or updates the `state.columnVisibility` state.
+   */
+  setColumnVisibility: (updater: Updater<ColumnVisibilityState>) => void
+  /**
+   * Toggles the visibility of all columns.
+   */
+  toggleAllColumnsVisible: (value?: boolean) => void
+}
+
+export interface ColumnDef_ColumnVisibility {
+  /**
+   * Enables/disables column hiding for this column. Defaults to `true`.
+   */
+  enableHiding?: boolean
+}
+
+export interface Row_ColumnVisibility<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+> {
+  getAllVisibleCells: () => Array<Cell<TFeatures, TData, unknown>>
+  /**
+   * Returns an array of cells that account for column visibility for the row.
+   */
+  getVisibleCells: () => Array<Cell<TFeatures, TData, unknown>>
+}
+
+export interface Column_ColumnVisibility {
+  /**
+   * Returns whether the column can be hidden
+   */
+  getCanHide: () => boolean
+  /**
+   * Returns whether the column is visible
+   */
+  getIsVisible: () => boolean
+  /**
+   * Returns a function that can be used to toggle the column visibility. This function can be used to bind to an event handler to a checkbox.
+   */
+  getToggleVisibilityHandler: () => (event: unknown) => void
+  /**
+   * Toggles the visibility of the column.
+   */
+  toggleVisibility: (value?: boolean) => void
+}

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

@@ -0,0 +1,183 @@
+import { callMemoOrStaticFn } 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 { Cell } from '../../types/Cell'
+import type { Column_Internal } from '../../types/Column'
+import type { ColumnVisibilityState } from './columnVisibilityFeature.types'
+import type { Row } from '../../types/Row'
+
+export function getDefaultColumnVisibilityState(): ColumnVisibilityState {
+  return structuredClone({})
+}
+
+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),
+    }))
+  }
+}
+
+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.store.state.columnVisibility?.[column.id]) ?? true
+  )
+}
+
+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)
+  )
+}
+
+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,
+    )
+  }
+}
+
+export function row_getAllVisibleCells<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+>(row: Row<TFeatures, TData>) {
+  return row
+    .getAllCells()
+    .filter((cell) =>
+      callMemoOrStaticFn(cell.column, 'getIsVisible', column_getIsVisible),
+    )
+}
+
+export function row_getVisibleCells<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+>(
+  left: Array<Cell<TFeatures, TData, unknown>>,
+  center: Array<Cell<TFeatures, TData, unknown>>,
+  right: Array<Cell<TFeatures, TData, unknown>>,
+) {
+  return [...left, ...center, ...right]
+}
+
+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),
+    )
+}
+
+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),
+    )
+}
+
+export function table_setColumnVisibility<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+>(
+  table: Table_Internal<TFeatures, TData>,
+  updater: Updater<ColumnVisibilityState>,
+) {
+  table.options.onColumnVisibilityChange?.(updater)
+}
+
+export function table_resetColumnVisibility<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+>(table: Table_Internal<TFeatures, TData>, defaultState?: boolean) {
+  table_setColumnVisibility(
+    table,
+    defaultState ? {} : (table.initialState.columnVisibility ?? {}),
+  )
+}
+
+export function table_toggleAllColumnsVisible<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+>(table: Table_Internal<TFeatures, TData>, value?: boolean) {
+  value = value ?? !table_getIsAllColumnsVisible(table)
+
+  table_setColumnVisibility(
+    table,
+    table.getAllLeafColumns().reduce(
+      (obj, column) => ({
+        ...obj,
+        [column.id]: !value ? !column_getCanHide(column) : value,
+      }),
+      {},
+    ),
+  )
+}
+
+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),
+    )
+}
+
+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),
+    )
+}
+
+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,92 @@
+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'
+
+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
+}
+
+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 Global Filtering feature adds global filtering state and APIs to the table and column objects.
+ * **Note:** This is dependent on the columnFilteringFeature feature.
+ */
+export const globalFilteringFeature = constructGlobalFilteringFeature()

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

@@ -0,0 +1,84 @@
+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 {
+  /**
+   * Enables/disables the **global** filter for this column.
+   */
+  enableGlobalFilter?: boolean
+}
+
+export interface Column_GlobalFiltering {
+  /**
+   * Returns whether or not the column can be **globally** filtered. Set to `false` to disable a column from being scanned during global filtering.
+   */
+  getCanGlobalFilter: () => boolean
+}
+
+export interface TableOptions_GlobalFiltering<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+> {
+  /**
+   * Enables/disables **global** filtering for all columns.
+   */
+  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>
+  /**
+   * If provided, this function will be called with an `updaterFn` when `state.globalFilter` 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.
+   */
+  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 the **globalFilter** state to `initialState.globalFilter`, or `true` can be passed to force a default blank state reset to `undefined`.
+   */
+  resetGlobalFilter: (defaultState?: boolean) => void
+  /**
+   * Sets or updates the `state.globalFilter` state.
+   */
+  setGlobalFilter: (updater: Updater<any>) => void
+}

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

@@ -0,0 +1,60 @@
+import { filterFn_includesString } from '../../fns/filterFns'
+import { 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'
+
+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
+  )
+}
+
+export function table_getGlobalAutoFilterFn() {
+  return filterFn_includesString
+}
+
+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 = table._rowModelFns.filterFns as
+    | Record<string, FilterFn<TFeatures, TData>>
+    | undefined
+
+  return isFunction(globalFilterFn)
+    ? globalFilterFn
+    : globalFilterFn === 'auto'
+      ? table_getGlobalAutoFilterFn()
+      : filterFns?.[globalFilterFn as string]
+}
+
+export function table_setGlobalFilter<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+>(table: Table_Internal<TFeatures, TData>, updater: any) {
+  table.options.onGlobalFilterChange?.(updater)
+}
+
+export function table_resetGlobalFilter<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+>(table: Table_Internal<TFeatures, TData>, defaultState?: boolean) {
+  table_setGlobalFilter(
+    table,
+    defaultState ? undefined : table.initialState.globalFilter,
+  )
+}