@tanstack/table-core 8.13.1 → 8.14.0

package/src/features/RowPinning.ts

@@ -0,0 +1,273 @@
+import {
+  OnChangeFn,
+  Updater,
+  Table,
+  Row,
+  RowData,
+  TableFeature,
+} from '../types'
+import { getMemoOptions, makeStateUpdater, memo } from '../utils'
+
+export type RowPinningPosition = false | 'top' | 'bottom'
+
+export interface RowPinningState {
+  bottom?: string[]
+  top?: string[]
+}
+
+export interface RowPinningTableState {
+  rowPinning: RowPinningState
+}
+
+export interface RowPinningOptions<TData extends RowData> {
+  /**
+   * Enables/disables row pinning for the table. Defaults to `true`.
+   * @link [API Docs](https://tanstack.com/table/v8/docs/api/features/row-pinning#enablerowpinning)
+   * @link [Guide](https://tanstack.com/table/v8/docs/guide/row-pinning)
+   */
+  enableRowPinning?: boolean | ((row: Row<TData>) => boolean)
+  /**
+   * When `false`, pinned rows will not be visible if they are filtered or paginated out of the table. When `true`, pinned rows will always be visible regardless of filtering or pagination. Defaults to `true`.
+   * @link [API Docs](https://tanstack.com/table/v8/docs/api/features/row-pinning#keeppinnedrows)
+   * @link [Guide](https://tanstack.com/table/v8/docs/guide/row-pinning)
+   */
+  keepPinnedRows?: boolean
+  /**
+   * If provided, this function will be called with an `updaterFn` when `state.rowPinning` changes. This overrides the default internal state management, so you will also need to supply `state.rowPinning` from your own managed state.
+   * @link [API Docs](https://tanstack.com/table/v8/docs/api/features/row-pinning#onrowpinningchange)
+   * @link [Guide](https://tanstack.com/table/v8/docs/guide/onrowpinningchange)
+   */
+  onRowPinningChange?: OnChangeFn<RowPinningState>
+}
+
+export interface RowPinningDefaultOptions {
+  onRowPinningChange: OnChangeFn<RowPinningState>
+}
+
+export interface RowPinningRow {
+  /**
+   * Returns whether or not the row can be pinned.
+   * @link [API Docs](https://tanstack.com/table/v8/docs/api/features/row-pinning#getcanpin-1)
+   * @link [Guide](https://tanstack.com/table/v8/docs/guide/row-pinning)
+   */
+  getCanPin: () => boolean
+  /**
+   * Returns the pinned position of the row. (`'top'`, `'bottom'` or `false`)
+   * @link [API Docs](https://tanstack.com/table/v8/docs/api/features/row-pinning#getispinned-1)
+   * @link [Guide](https://tanstack.com/table/v8/docs/guide/row-pinning)
+   */
+  getIsPinned: () => RowPinningPosition
+  /**
+   * Returns the numeric pinned index of the row within a pinned row group.
+   * @link [API Docs](https://tanstack.com/table/v8/docs/api/features/row-pinning#getpinnedindex-1)
+   * @link [Guide](https://tanstack.com/table/v8/docs/guide/row-pinning)
+   */
+  getPinnedIndex: () => number
+  /**
+   * Pins a row to the `'top'` or `'bottom'`, or unpins the row to the center if `false` is passed.
+   * @link [API Docs](https://tanstack.com/table/v8/docs/api/features/row-pinning#pin-1)
+   * @link [Guide](https://tanstack.com/table/v8/docs/guide/row-pinning)
+   */
+  pin: (
+    position: RowPinningPosition,
+    includeLeafRows?: boolean,
+    includeParentRows?: boolean
+  ) => void
+}
+
+export interface RowPinningInstance<TData extends RowData> {
+  _getPinnedRows: (position: 'top' | 'bottom') => Row<TData>[]
+  /**
+   * Returns all bottom pinned rows.
+   * @link [API Docs](https://tanstack.com/table/v8/docs/api/features/row-pinning#getbottomrows)
+   * @link [Guide](https://tanstack.com/table/v8/docs/guide/row-pinning)
+   */
+  getBottomRows: () => Row<TData>[]
+  /**
+   * Returns all rows that are not pinned to the top or bottom.
+   * @link [API Docs](https://tanstack.com/table/v8/docs/api/features/row-pinning#getcenterrows)
+   * @link [Guide](https://tanstack.com/table/v8/docs/guide/row-pinning)
+   */
+  getCenterRows: () => Row<TData>[]
+  /**
+   * Returns whether or not any rows are pinned. Optionally specify to only check for pinned rows in either the `top` or `bottom` position.
+   * @link [API Docs](https://tanstack.com/table/v8/docs/api/features/row-pinning#getissomerowspinned)
+   * @link [Guide](https://tanstack.com/table/v8/docs/guide/row-pinning)
+   */
+  getIsSomeRowsPinned: (position?: RowPinningPosition) => boolean
+  /**
+   * Returns all top pinned rows.
+   * @link [API Docs](https://tanstack.com/table/v8/docs/api/features/row-pinning#gettoprows)
+   * @link [Guide](https://tanstack.com/table/v8/docs/guide/row-pinning)
+   */
+  getTopRows: () => Row<TData>[]
+  /**
+   * Resets the **rowPinning** state to `initialState.rowPinning`, or `true` can be passed to force a default blank state reset to `{ top: [], bottom: [], }`.
+   * @link [API Docs](https://tanstack.com/table/v8/docs/api/features/row-pinning#resetrowpinning)
+   * @link [Guide](https://tanstack.com/table/v8/docs/guide/row-pinning)
+   */
+  resetRowPinning: (defaultState?: boolean) => void
+  /**
+   * Sets or updates the `state.rowPinning` state.
+   * @link [API Docs](https://tanstack.com/table/v8/docs/api/features/row-pinning#setrowpinning)
+   * @link [Guide](https://tanstack.com/table/v8/docs/guide/row-pinning)
+   */
+  setRowPinning: (updater: Updater<RowPinningState>) => void
+}
+
+//
+
+const getDefaultRowPinningState = (): RowPinningState => ({
+  top: [],
+  bottom: [],
+})
+
+export const RowPinning: TableFeature = {
+  getInitialState: (state): RowPinningTableState => {
+    return {
+      rowPinning: getDefaultRowPinningState(),
+      ...state,
+    }
+  },
+
+  getDefaultOptions: <TData extends RowData>(
+    table: Table<TData>
+  ): RowPinningDefaultOptions => {
+    return {
+      onRowPinningChange: makeStateUpdater('rowPinning', table),
+    }
+  },
+
+  createRow: <TData extends RowData>(
+    row: Row<TData>,
+    table: Table<TData>
+  ): void => {
+    row.pin = (position, includeLeafRows, includeParentRows) => {
+      const leafRowIds = includeLeafRows
+        ? row.getLeafRows().map(({ id }) => id)
+        : []
+      const parentRowIds = includeParentRows
+        ? row.getParentRows().map(({ id }) => id)
+        : []
+      const rowIds = new Set([...parentRowIds, row.id, ...leafRowIds])
+
+      table.setRowPinning(old => {
+        if (position === 'bottom') {
+          return {
+            top: (old?.top ?? []).filter(d => !rowIds?.has(d)),
+            bottom: [
+              ...(old?.bottom ?? []).filter(d => !rowIds?.has(d)),
+              ...Array.from(rowIds),
+            ],
+          }
+        }
+
+        if (position === 'top') {
+          return {
+            top: [
+              ...(old?.top ?? []).filter(d => !rowIds?.has(d)),
+              ...Array.from(rowIds),
+            ],
+            bottom: (old?.bottom ?? []).filter(d => !rowIds?.has(d)),
+          }
+        }
+
+        return {
+          top: (old?.top ?? []).filter(d => !rowIds?.has(d)),
+          bottom: (old?.bottom ?? []).filter(d => !rowIds?.has(d)),
+        }
+      })
+    }
+    row.getCanPin = () => {
+      const { enableRowPinning, enablePinning } = table.options
+      if (typeof enableRowPinning === 'function') {
+        return enableRowPinning(row)
+      }
+      return enableRowPinning ?? enablePinning ?? true
+    }
+    row.getIsPinned = () => {
+      const rowIds = [row.id]
+
+      const { top, bottom } = table.getState().rowPinning
+
+      const isTop = rowIds.some(d => top?.includes(d))
+      const isBottom = rowIds.some(d => bottom?.includes(d))
+
+      return isTop ? 'top' : isBottom ? 'bottom' : false
+    }
+    row.getPinnedIndex = () => {
+      const position = row.getIsPinned()
+      if (!position) return -1
+
+      const visiblePinnedRowIds = table
+        ._getPinnedRows(position)
+        ?.map(({ id }) => id)
+
+      return visiblePinnedRowIds?.indexOf(row.id) ?? -1
+    }
+  },
+
+  createTable: <TData extends RowData>(table: Table<TData>): void => {
+    table.setRowPinning = updater => table.options.onRowPinningChange?.(updater)
+
+    table.resetRowPinning = defaultState =>
+      table.setRowPinning(
+        defaultState
+          ? getDefaultRowPinningState()
+          : table.initialState?.rowPinning ?? getDefaultRowPinningState()
+      )
+
+    table.getIsSomeRowsPinned = position => {
+      const pinningState = table.getState().rowPinning
+
+      if (!position) {
+        return Boolean(pinningState.top?.length || pinningState.bottom?.length)
+      }
+      return Boolean(pinningState[position]?.length)
+    }
+
+    table._getPinnedRows = memo(
+      position => [
+        table.getRowModel().rows,
+        table.getState().rowPinning[position!],
+        position,
+      ],
+      (visibleRows, pinnedRowIds, position) => {
+        const rows =
+          table.options.keepPinnedRows ?? true
+            ? //get all rows that are pinned even if they would not be otherwise visible
+              //account for expanded parent rows, but not pagination or filtering
+              (pinnedRowIds ?? []).map(rowId => {
+                const row = table.getRow(rowId, true)
+                return row.getIsAllParentsExpanded() ? row : null
+              })
+            : //else get only visible rows that are pinned
+              (pinnedRowIds ?? []).map(
+                rowId => visibleRows.find(row => row.id === rowId)!
+              )
+
+        return rows
+          .filter(Boolean)
+          .map(d => ({ ...d, position })) as Row<TData>[]
+      },
+      getMemoOptions(table.options, 'debugRows', '_getPinnedRows')
+    )
+
+    table.getTopRows = () => table._getPinnedRows('top')
+
+    table.getBottomRows = () => table._getPinnedRows('bottom')
+
+    table.getCenterRows = memo(
+      () => [
+        table.getRowModel().rows,
+        table.getState().rowPinning.top,
+        table.getState().rowPinning.bottom,
+      ],
+      (allRows, top, bottom) => {
+        const topAndBottom = new Set([...(top ?? []), ...(bottom ?? [])])
+        return allRows.filter(d => !topAndBottom.has(d.id))
+      },
+      getMemoOptions(table.options, 'debugRows', 'getCenterRows')
+    )
+  },
+}

package/src/features/RowSelection.ts

@@ -1,5 +1,12 @@
-import { TableFeature } from '../core/table'
-import { OnChangeFn, Table, Row, RowModel, Updater, RowData } from '../types'
+import {
+  OnChangeFn,
+  Table,
+  Row,
+  RowModel,
+  Updater,
+  RowData,
+  TableFeature,
+} from '../types'
 import { getMemoOptions, makeStateUpdater, memo } from '../utils'
 
 export type RowSelectionState = Record<string, boolean>

package/src/features/{Sorting.ts → RowSorting.ts}

@@ -1,5 +1,4 @@
 import { RowModel } from '..'
-import { TableFeature } from '../core/table'
 import {
   BuiltInSortingFn,
   reSplitAlphaNumeric,
@@ -14,6 +13,7 @@ import {
   Updater,
   RowData,
   SortingFns,
+  TableFeature,
 } from '../types'
 
 import { isFunction, makeStateUpdater } from '../utils'
@@ -80,12 +80,15 @@ export interface SortingColumnDef<TData extends RowData> {
    */
   sortingFn?: SortingFnOption<TData>
   /**
+   * The priority of undefined values when sorting this column.
    * - `false`
    *   - Undefined values will be considered tied and need to be sorted by the next column filter or original index (whichever applies)
    * - `-1`
    *   - Undefined values will be sorted with higher priority (ascending) (if ascending, undefined will appear on the beginning of the list)
    * - `1`
    *   - Undefined values will be sorted with lower priority (descending) (if ascending, undefined will appear on the end of the list)
+   * @link [API Docs](https://tanstack.com/table/v8/docs/api/features/sorting#sortundefined)
+   * @link [Guide](https://tanstack.com/table/v8/docs/guide/sorting)
    */
   sortUndefined?: false | -1 | 1
 }
@@ -272,7 +275,7 @@ export interface SortingInstance<TData extends RowData> {
 
 //
 
-export const Sorting: TableFeature = {
+export const RowSorting: TableFeature = {
   getInitialState: (state): SortingTableState => {
     return {
       sorting: [],

package/src/filterFns.ts

@@ -1,4 +1,4 @@
-import { FilterFn } from './features/Filters'
+import { FilterFn } from './features/ColumnFiltering'
 
 const includesString: FilterFn<any> = (
   row,

package/src/index.ts

@@ -1,30 +1,42 @@
-export * from './core/table'
+//types
+export * from './columnHelper'
 export * from './types'
+
+//core
+export * from './core/cell'
 export * from './core/column'
 export * from './core/headers'
 export * from './core/row'
-export * from './core/cell'
+export * from './core/table'
+
+//features
+export * from './features/ColumnFaceting'
+export * from './features/ColumnFiltering'
+export * from './features/ColumnGrouping'
+export * from './features/ColumnOrdering'
+export * from './features/ColumnPinning'
 export * from './features/ColumnSizing'
-export * from './features/Expanding'
-export * from './features/Filters'
-export * from './features/Grouping'
-export * from './features/Ordering'
-export * from './features/Pagination'
-export * from './features/Pinning'
+export * from './features/ColumnVisibility'
+export * from './features/GlobalFiltering'
+export * from './features/RowExpanding'
+export * from './features/RowPagination'
+export * from './features/RowPinning'
 export * from './features/RowSelection'
-export * from './features/Sorting'
-export * from './features/Visibility'
-export * from './filterFns'
-export * from './sortingFns'
-export * from './aggregationFns'
-export * from './columnHelper'
+export * from './features/RowSorting'
+
+//utils
 export * from './utils'
 export * from './utils/getCoreRowModel'
-export * from './utils/getFilteredRowModel'
+export * from './utils/getExpandedRowModel'
+export * from './utils/getFacetedMinMaxValues'
 export * from './utils/getFacetedRowModel'
 export * from './utils/getFacetedUniqueValues'
-export * from './utils/getFacetedMinMaxValues'
-export * from './utils/getSortedRowModel'
+export * from './utils/getFilteredRowModel'
 export * from './utils/getGroupedRowModel'
-export * from './utils/getExpandedRowModel'
 export * from './utils/getPaginationRowModel'
+export * from './utils/getSortedRowModel'
+
+//fns
+export * from './aggregationFns'
+export * from './filterFns'
+export * from './sortingFns'

package/src/sortingFns.ts

@@ -1,4 +1,4 @@
-import { SortingFn } from './features/Sorting'
+import { SortingFn } from './features/RowSorting'
 
 export const reSplitAlphaNumeric = /([0-9]+)/gm
 

package/src/types.ts

@@ -6,13 +6,13 @@ import {
   VisibilityOptions,
   VisibilityColumnDef,
   VisibilityRow,
-} from './features/Visibility'
+} from './features/ColumnVisibility'
 import {
   ColumnOrderColumn,
   ColumnOrderInstance,
   ColumnOrderOptions,
   ColumnOrderTableState,
-} from './features/Ordering'
+} from './features/ColumnOrdering'
 import {
   ColumnPinningColumn,
   ColumnPinningColumnDef,
@@ -20,32 +20,42 @@ import {
   ColumnPinningOptions,
   ColumnPinningRow,
   ColumnPinningTableState,
+} from './features/ColumnPinning'
+import {
   RowPinningInstance,
   RowPinningOptions,
   RowPinningRow,
   RowPinningTableState,
-} from './features/Pinning'
+} from './features/RowPinning'
 import {
   CoreHeader,
   CoreHeaderGroup,
   HeaderContext,
   HeadersInstance,
 } from './core/headers'
+import { FacetedColumn, FacetedOptions } from './features/ColumnFaceting'
+import {
+  ColumnFiltersColumn,
+  ColumnFiltersColumnDef,
+  ColumnFiltersInstance,
+  ColumnFiltersOptions,
+  ColumnFiltersRow,
+  ColumnFiltersTableState,
+} from './features/ColumnFiltering'
 import {
-  FiltersColumn,
-  FiltersColumnDef,
-  FiltersInstance,
-  FiltersOptions,
-  FiltersRow,
-  FiltersTableState,
-} from './features/Filters'
+  GlobalFilterColumn,
+  GlobalFilterColumnDef,
+  GlobalFilterInstance,
+  GlobalFilterOptions,
+  GlobalFilterTableState,
+} from './features/GlobalFiltering'
 import {
   SortingColumn,
   SortingColumnDef,
   SortingInstance,
   SortingOptions,
   SortingTableState,
-} from './features/Sorting'
+} from './features/RowSorting'
 import {
   GroupingCell,
   GroupingColumn,
@@ -54,13 +64,13 @@ import {
   GroupingOptions,
   GroupingRow,
   GroupingTableState,
-} from './features/Grouping'
+} from './features/ColumnGrouping'
 import {
   ExpandedInstance,
   ExpandedOptions,
   ExpandedTableState,
   ExpandedRow,
-} from './features/Expanding'
+} from './features/RowExpanding'
 import {
   ColumnSizingColumn,
   ColumnSizingColumnDef,
@@ -74,7 +84,7 @@ import {
   PaginationInstance,
   PaginationOptions,
   PaginationTableState,
-} from './features/Pagination'
+} from './features/RowPagination'
 import {
   RowSelectionInstance,
   RowSelectionOptions,
@@ -86,6 +96,24 @@ import { PartialKeys, UnionToIntersection } from './utils'
 import { CellContext, CoreCell } from './core/cell'
 import { CoreColumn } from './core/column'
 
+export interface TableFeature<TData extends RowData = any> {
+  createCell?: (
+    cell: Cell<TData, unknown>,
+    column: Column<TData>,
+    row: Row<TData>,
+    table: Table<TData>
+  ) => void
+  createColumn?: (column: Column<TData, unknown>, table: Table<TData>) => void
+  createHeader?: (header: Header<TData, unknown>, table: Table<TData>) => void
+  createRow?: (row: Row<TData>, table: Table<TData>) => void
+  createTable?: (table: Table<TData>) => void
+  getDefaultColumnDef?: () => Partial<ColumnDef<TData, unknown>>
+  getDefaultOptions?: (
+    table: Table<TData>
+  ) => Partial<TableOptionsResolved<TData>>
+  getInitialState?: (initialState?: InitialTableState) => Partial<TableState>
+}
+
 export interface TableMeta<TData extends RowData> {}
 
 export interface ColumnMeta<TData extends RowData, TValue> {}
@@ -112,7 +140,8 @@ export interface Table<TData extends RowData>
     ColumnOrderInstance<TData>,
     ColumnPinningInstance<TData>,
     RowPinningInstance<TData>,
-    FiltersInstance<TData>,
+    ColumnFiltersInstance<TData>,
+    GlobalFilterInstance<TData>,
     SortingInstance<TData>,
     GroupingInstance<TData>,
     ColumnSizingInstance,
@@ -125,7 +154,9 @@ interface FeatureOptions<TData extends RowData>
     ColumnOrderOptions,
     ColumnPinningOptions,
     RowPinningOptions<TData>,
-    FiltersOptions<TData>,
+    FacetedOptions<TData>,
+    ColumnFiltersOptions<TData>,
+    GlobalFilterOptions<TData>,
     SortingOptions<TData>,
     GroupingOptions,
     ExpandedOptions<TData>,
@@ -133,8 +164,9 @@ interface FeatureOptions<TData extends RowData>
     PaginationOptions,
     RowSelectionOptions<TData> {}
 
-export type TableOptionsResolved<TData extends RowData> = CoreOptions<TData> &
-  FeatureOptions<TData>
+export interface TableOptionsResolved<TData extends RowData>
+  extends CoreOptions<TData>,
+    FeatureOptions<TData> {}
 
 export interface TableOptions<TData extends RowData>
   extends PartialKeys<
@@ -148,7 +180,8 @@ export interface TableState
     ColumnOrderTableState,
     ColumnPinningTableState,
     RowPinningTableState,
-    FiltersTableState,
+    ColumnFiltersTableState,
+    GlobalFilterTableState,
     SortingTableState,
     ExpandedTableState,
     GroupingTableState,
@@ -162,7 +195,8 @@ interface CompleteInitialTableState
     ColumnOrderTableState,
     ColumnPinningTableState,
     RowPinningTableState,
-    FiltersTableState,
+    ColumnFiltersTableState,
+    GlobalFilterTableState,
     SortingTableState,
     ExpandedTableState,
     GroupingTableState,
@@ -177,7 +211,7 @@ export interface Row<TData extends RowData>
     VisibilityRow<TData>,
     ColumnPinningRow<TData>,
     RowPinningRow,
-    FiltersRow<TData>,
+    ColumnFiltersRow<TData>,
     GroupingRow,
     RowSelectionRow,
     ExpandedRow {}
@@ -220,7 +254,8 @@ type ColumnIdentifiers<TData extends RowData, TValue> =
 interface ColumnDefExtensions<TData extends RowData, TValue = unknown>
   extends VisibilityColumnDef,
     ColumnPinningColumnDef,
-    FiltersColumnDef<TData>,
+    ColumnFiltersColumnDef<TData>,
+    GlobalFilterColumnDef,
     SortingColumnDef<TData>,
     GroupingColumnDef<TData, TValue>,
     ColumnSizingColumnDef {}
@@ -302,7 +337,9 @@ export interface Column<TData extends RowData, TValue = unknown>
   extends CoreColumn<TData, TValue>,
     ColumnVisibilityColumn,
     ColumnPinningColumn,
-    FiltersColumn<TData>,
+    FacetedColumn<TData>,
+    ColumnFiltersColumn<TData>,
+    GlobalFilterColumn,
     SortingColumn<TData>,
     GroupingColumn<TData>,
     ColumnSizingColumn,

package/src/utils/getFilteredRowModel.ts

@@ -1,4 +1,4 @@
-import { ResolvedColumnFilter } from '../features/Filters'
+import { ResolvedColumnFilter } from '../features/ColumnFiltering'
 import { Table, RowModel, Row, RowData } from '../types'
 import { getMemoOptions, memo } from '../utils'
 import { filterRows } from './filterRowsUtils'

package/src/utils/getSortedRowModel.ts

@@ -1,5 +1,5 @@
 import { Table, Row, RowModel, RowData } from '../types'
-import { SortingFn } from '../features/Sorting'
+import { SortingFn } from '../features/RowSorting'
 import { getMemoOptions, memo } from '../utils'
 
 export function getSortedRowModel<TData extends RowData>(): (

package/src/utils.ts

@@ -47,17 +47,15 @@ export type DeepKeys<T, TDepth extends any[] = []> = TDepth['length'] extends 5
   ? never
   : unknown extends T
     ? string
-    : object extends T
-      ? string
-      : T extends readonly any[] & IsTuple<T>
-        ? AllowedIndexes<T> | DeepKeysPrefix<T, AllowedIndexes<T>, TDepth>
-        : T extends any[]
-          ? DeepKeys<T[number], [...TDepth, any]>
-          : T extends Date
-            ? never
-            : T extends object
-              ? (keyof T & string) | DeepKeysPrefix<T, keyof T, TDepth>
-              : never
+    : T extends readonly any[] & IsTuple<T>
+      ? AllowedIndexes<T> | DeepKeysPrefix<T, AllowedIndexes<T>, TDepth>
+      : T extends any[]
+        ? DeepKeys<T[number], [...TDepth, any]>
+        : T extends Date
+          ? never
+          : T extends object
+            ? (keyof T & string) | DeepKeysPrefix<T, keyof T, TDepth>
+            : never
 
 type DeepKeysPrefix<
   T,