@tanstack/table-core 9.0.0-alpha.4 → 9.0.0-alpha.41

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'
+
+export 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,59 @@
+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'
+
+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: Record<string, FilterFn<TFeatures, TData>> | undefined =
+    table._rowModelFns.filterFns
+
+  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 : cloneState(table.initialState.globalFilter),
+  )
+}

package/src/features/row-expanding/createExpandedRowModel.ts

@@ -0,0 +1,72 @@
+import { tableMemo } from '../../utils'
+import { row_getIsExpanded } from './rowExpandingFeature.utils'
+import type { TableFeatures } from '../../types/TableFeatures'
+import type { RowModel } from '../../core/row-models/coreRowModelsFeature.types'
+import type { Table, Table_Internal } from '../../types/Table'
+import type { Row } from '../../types/Row'
+import type { RowData } from '../../types/type-utils'
+
+export function createExpandedRowModel<
+  TFeatures extends TableFeatures,
+  TData extends RowData = any,
+>(): (table: Table<TFeatures, TData>) => () => RowModel<TFeatures, TData> {
+  return (_table) => {
+    const table: Table_Internal<TFeatures, TData> = _table
+    return tableMemo({
+      feature: 'rowExpandingFeature',
+      table,
+      fnName: 'table.getExpandedRowModel',
+      memoDeps: () => [
+        table.atoms.expanded?.get(),
+        table.getPreExpandedRowModel(),
+        table.options.paginateExpandedRows,
+      ],
+      fn: () => _createExpandedRowModel(table),
+    })
+  }
+}
+
+function _createExpandedRowModel<
+  TFeatures extends TableFeatures,
+  TData extends RowData = any,
+>(table: Table_Internal<TFeatures, TData>): RowModel<TFeatures, TData> {
+  const rowModel = table.getPreExpandedRowModel()
+  const expanded = table.atoms.expanded?.get()
+
+  if (
+    !rowModel.rows.length ||
+    (expanded !== true && !Object.keys(expanded ?? {}).length)
+  ) {
+    return rowModel
+  }
+
+  if (!table.options.paginateExpandedRows) {
+    // Only expand rows at this point if they are being paginated
+    return rowModel
+  }
+
+  return expandRows(rowModel)
+}
+
+export function expandRows<
+  TFeatures extends TableFeatures,
+  TData extends RowData = any,
+>(rowModel: RowModel<TFeatures, TData>): RowModel<TFeatures, TData> {
+  const expandedRows: Array<Row<TFeatures, TData>> = []
+
+  const handleRow = (row: Row<TFeatures, TData>) => {
+    expandedRows.push(row)
+
+    if (row.subRows.length && row_getIsExpanded(row)) {
+      row.subRows.forEach(handleRow)
+    }
+  }
+
+  rowModel.rows.forEach(handleRow)
+
+  return {
+    rows: expandedRows,
+    flatRows: rowModel.flatRows,
+    rowsById: rowModel.rowsById,
+  }
+}

package/src/features/row-expanding/rowExpandingFeature.ts

@@ -0,0 +1,122 @@
+import {
+  assignPrototypeAPIs,
+  assignTableAPIs,
+  makeStateUpdater,
+} from '../../utils'
+import {
+  getDefaultExpandedState,
+  row_getCanExpand,
+  row_getIsAllParentsExpanded,
+  row_getIsExpanded,
+  row_getToggleExpandedHandler,
+  row_toggleExpanded,
+  table_autoResetExpanded,
+  table_getCanSomeRowsExpand,
+  table_getExpandedDepth,
+  table_getIsAllRowsExpanded,
+  table_getIsSomeRowsExpanded,
+  table_getToggleAllRowsExpandedHandler,
+  table_resetExpanded,
+  table_setExpanded,
+  table_toggleAllRowsExpanded,
+} from './rowExpandingFeature.utils'
+import type { RowData } from '../../types/type-utils'
+import type { TableFeature, TableFeatures } from '../../types/TableFeatures'
+// import type {
+//   CachedRowModel_Expanded,
+//   CreateRowModel_Expanded,
+//   Row_RowExpanding,
+//   TableOptions_RowExpanding,
+//   TableState_RowExpanding,
+//   Table_RowExpanding,
+// } from './rowExpandingFeature.types'
+
+export interface RowExpandingFeatureConstructors<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+> {
+  // CachedRowModel: CachedRowModel_Expanded<TFeatures, TData>
+  // CreateRowModels: CreateRowModel_Expanded<TFeatures, TData>
+  // Row: Row_RowExpanding
+  // Table: Table_RowExpanding<TFeatures, TData>
+  // TableOptions: TableOptions_RowExpanding<TFeatures, TData>
+  // TableState: TableState_RowExpanding
+}
+
+export function constructRowExpandingFeature<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+>(): TableFeature<RowExpandingFeatureConstructors<TFeatures, TData>> {
+  return {
+    getInitialState: (initialState) => {
+      return {
+        expanded: getDefaultExpandedState(),
+        ...initialState,
+      }
+    },
+
+    getDefaultTableOptions: (table) => {
+      return {
+        onExpandedChange: makeStateUpdater('expanded', table),
+        paginateExpandedRows: true,
+      }
+    },
+
+    assignRowPrototype: (prototype, table) => {
+      assignPrototypeAPIs('rowExpandingFeature', prototype, table, {
+        row_toggleExpanded: {
+          fn: (row, expanded) => row_toggleExpanded(row, expanded),
+        },
+        row_getIsExpanded: {
+          fn: (row) => row_getIsExpanded(row),
+        },
+        row_getCanExpand: {
+          fn: (row) => row_getCanExpand(row),
+        },
+        row_getIsAllParentsExpanded: {
+          fn: (row) => row_getIsAllParentsExpanded(row),
+        },
+        row_getToggleExpandedHandler: {
+          fn: (row) => row_getToggleExpandedHandler(row),
+        },
+      })
+    },
+
+    constructTableAPIs: (table) => {
+      assignTableAPIs('rowExpandingFeature', table, {
+        table_autoResetExpanded: {
+          fn: () => table_autoResetExpanded(table),
+        },
+        table_setExpanded: {
+          fn: (updater) => table_setExpanded(table, updater),
+        },
+        table_toggleAllRowsExpanded: {
+          fn: (expanded) => table_toggleAllRowsExpanded(table, expanded),
+        },
+        table_resetExpanded: {
+          fn: (defaultState) => table_resetExpanded(table, defaultState),
+        },
+        table_getCanSomeRowsExpand: {
+          fn: () => table_getCanSomeRowsExpand(table),
+        },
+        table_getToggleAllRowsExpandedHandler: {
+          fn: () => table_getToggleAllRowsExpandedHandler(table),
+        },
+        table_getIsSomeRowsExpanded: {
+          fn: () => table_getIsSomeRowsExpanded(table),
+        },
+        table_getIsAllRowsExpanded: {
+          fn: () => table_getIsAllRowsExpanded(table),
+        },
+        table_getExpandedDepth: {
+          fn: () => table_getExpandedDepth(table),
+        },
+      })
+    },
+  }
+}
+
+/**
+ * The Row Expanding feature adds row expanding state and APIs to the table and row objects.
+ */
+export const rowExpandingFeature = constructRowExpandingFeature()

package/src/features/row-expanding/rowExpandingFeature.types.ts

@@ -0,0 +1,141 @@
+import type { Table } from '../../types/Table'
+import type { 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'
+
+export type ExpandedStateList = Record<string, boolean>
+export type ExpandedState = true | Record<string, boolean>
+
+export interface TableState_RowExpanding {
+  expanded: ExpandedState
+}
+
+export interface Row_RowExpanding {
+  /**
+   * Returns whether the row can be expanded.
+   */
+  getCanExpand: () => boolean
+  /**
+   * Returns whether all parent rows of the row are expanded.
+   */
+  getIsAllParentsExpanded: () => boolean
+  /**
+   * Returns whether the row is expanded.
+   */
+  getIsExpanded: () => boolean
+  /**
+   * Returns a function that can be used to toggle the expanded state of the row. This function can be used to bind to an event handler to a button.
+   */
+  getToggleExpandedHandler: () => () => void
+  /**
+   * Toggles the expanded state (or sets it if `expanded` is provided) for the row.
+   */
+  toggleExpanded: (expanded?: boolean) => void
+}
+
+export interface TableOptions_RowExpanding<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+> {
+  /**
+   * Enable this setting to automatically reset the expanded state of the table when expanding state changes.
+   */
+  autoResetExpanded?: boolean
+  /**
+   * Enable/disable expanding for all rows.
+   */
+  enableExpanding?: boolean
+  /**
+   * If provided, allows you to override the default behavior of determining whether a row is currently expanded.
+   */
+  getIsRowExpanded?: (row: Row<TFeatures, TData>) => boolean
+  /**
+   * If provided, allows you to override the default behavior of determining whether a row can be expanded.
+   */
+  getRowCanExpand?: (row: Row<TFeatures, TData>) => boolean
+  /**
+   * Enables manual row expansion. If this is set to `true`, `getExpandedRowModel` will not be used to expand rows and you would be expected to perform the expansion in your own data model. This is useful if you are doing server-side expansion.
+   */
+  manualExpanding?: boolean
+  /**
+   * This function is called when the `expanded` table state changes. If a function is provided, you will be responsible for managing this state on your own. To pass the managed state back to the table, use the `tableOptions.state.expanded` option.
+   */
+  onExpandedChange?: OnChangeFn<ExpandedState>
+  /**
+   * If `true` expanded rows will be paginated along with the rest of the table (which means expanded rows may span multiple pages). If `false` expanded rows will not be considered for pagination (which means expanded rows will always render on their parents page. This also means more rows will be rendered than the set page size)
+   */
+  paginateExpandedRows?: boolean
+}
+
+export interface Table_RowExpanding<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+> {
+  autoResetExpanded: () => void
+  /**
+   * Returns whether there are any rows that can be expanded.
+   */
+  getCanSomeRowsExpand: () => boolean
+  /**
+   * Returns the maximum depth of the expanded rows.
+   */
+  getExpandedDepth: () => number
+  /**
+   * Returns whether all rows are currently expanded.
+   */
+  getIsAllRowsExpanded: () => boolean
+  /**
+   * Returns whether there are any rows that are currently expanded.
+   */
+  getIsSomeRowsExpanded: () => boolean
+  /**
+   * Returns a handler that can be used to toggle the expanded state of all rows. This handler is meant to be used with an `input[type=checkbox]` element.
+   */
+  getToggleAllRowsExpandedHandler: () => (event: unknown) => void
+  /**
+   * Resets the expanded state of the table to the initial state.
+   */
+  resetExpanded: (defaultState?: boolean) => void
+  /**
+   * Updates the expanded state of the table via an update function or value.
+   */
+  setExpanded: (updater: Updater<ExpandedState>) => void
+  /**
+   * Toggles the expanded state for all rows.
+   */
+  toggleAllRowsExpanded: (expanded?: boolean) => void
+}
+
+export interface Table_RowModels_Expanded<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+> {
+  /**
+   * Returns the row model after expansion has been applied.
+   */
+  getExpandedRowModel: () => RowModel<TFeatures, TData>
+  /**
+   * Returns the row model before expansion has been applied.
+   */
+  getPreExpandedRowModel: () => RowModel<TFeatures, TData>
+}
+
+export interface CreateRowModel_Expanded<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+> {
+  /**
+   * This function is responsible for returning the expanded row model. If this function is not provided, the table will not expand rows. You can use the default exported `getExpandedRowModel` function to get the expanded row model or implement your own.
+   */
+  expandedRowModel?: (
+    table: Table<TFeatures, TData>,
+  ) => () => RowModel<TFeatures, TData>
+}
+
+export interface CachedRowModel_Expanded<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+> {
+  expandedRowModel: () => RowModel<TFeatures, TData>
+}