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

package/src/features/row-pinning/rowPinningFeature.ts

@@ -0,0 +1,97 @@
+import {
+  assignPrototypeAPIs,
+  assignTableAPIs,
+  makeStateUpdater,
+} from '../../utils'
+import {
+  getDefaultRowPinningState,
+  row_getCanPin,
+  row_getIsPinned,
+  row_getPinnedIndex,
+  row_pin,
+  table_getBottomRows,
+  table_getCenterRows,
+  table_getIsSomeRowsPinned,
+  table_getTopRows,
+  table_resetRowPinning,
+  table_setRowPinning,
+} from './rowPinningFeature.utils'
+import type { TableFeature } from '../../types/TableFeatures'
+
+/**
+ * Feature that adds row pinning state and APIs for top, center, and bottom rows.
+ */
+export const rowPinningFeature: TableFeature = {
+  getInitialState: (initialState) => {
+    return {
+      ...initialState,
+      rowPinning: {
+        ...getDefaultRowPinningState(),
+        ...initialState.rowPinning,
+      },
+    }
+  },
+
+  getDefaultTableOptions: (table) => {
+    return {
+      onRowPinningChange: makeStateUpdater('rowPinning', table),
+    }
+  },
+
+  assignRowPrototype: (prototype, table) => {
+    assignPrototypeAPIs('rowPinningFeature', prototype, table, {
+      row_getCanPin: {
+        fn: (row) => row_getCanPin(row),
+      },
+      row_getIsPinned: {
+        fn: (row) => row_getIsPinned(row),
+      },
+      row_getPinnedIndex: {
+        fn: (row) => row_getPinnedIndex(row),
+        memoDeps: (row) => [
+          row.table.getRowModel().rows,
+          row.table.atoms.rowPinning?.get(),
+        ],
+      },
+      row_pin: {
+        fn: (row, position, includeLeafRows, includeParentRows) =>
+          row_pin(row, position, includeLeafRows, includeParentRows),
+      },
+    })
+  },
+
+  constructTableAPIs: (table) => {
+    assignTableAPIs('rowPinningFeature', table, {
+      table_setRowPinning: {
+        fn: (updater) => table_setRowPinning(table, updater),
+      },
+      table_resetRowPinning: {
+        fn: (defaultState) => table_resetRowPinning(table, defaultState),
+      },
+      table_getIsSomeRowsPinned: {
+        fn: (position) => table_getIsSomeRowsPinned(table, position),
+      },
+      table_getTopRows: {
+        fn: () => table_getTopRows(table),
+        memoDeps: () => [
+          table.getRowModel().rows,
+          table.atoms.rowPinning?.get()?.top,
+        ],
+      },
+      table_getBottomRows: {
+        fn: () => table_getBottomRows(table),
+        memoDeps: () => [
+          table.getRowModel().rows,
+          table.atoms.rowPinning?.get()?.bottom,
+        ],
+      },
+      table_getCenterRows: {
+        fn: () => table_getCenterRows(table),
+        memoDeps: () => [
+          table.getRowModel().rows,
+          table.atoms.rowPinning?.get(),
+        ],
+      },
+    })
+  },
+}

package/src/features/row-pinning/rowPinningFeature.types.ts

@@ -0,0 +1,95 @@
+import type { OnChangeFn, RowData, Updater } from '../../types/type-utils'
+import type { TableFeatures } from '../../types/TableFeatures'
+import type { Row } from '../../types/Row'
+
+export type RowPinningPosition = false | 'top' | 'bottom'
+
+export interface RowPinningState {
+  bottom: Array<string>
+  top: Array<string>
+}
+
+export interface TableState_RowPinning {
+  rowPinning: RowPinningState
+}
+
+export interface TableOptions_RowPinning<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+> {
+  /**
+   * Allows rows to be pinned to top or bottom regions.
+   *
+   * Provide a predicate to decide per row. Defaults to `true`.
+   */
+  enableRowPinning?: boolean | ((row: Row<TFeatures, 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`.
+   */
+  keepPinnedRows?: boolean
+  /**
+   * Called with an updater when row pinning state changes. Pair this with
+   * `state.rowPinning` when using external state; external atoms can own the
+   * slice without this callback.
+   */
+  onRowPinningChange?: OnChangeFn<RowPinningState>
+}
+
+export interface RowPinningDefaultOptions {
+  onRowPinningChange: OnChangeFn<RowPinningState>
+}
+
+export interface Row_RowPinning {
+  /**
+   * Checks whether this row can be pinned.
+   */
+  getCanPin: () => boolean
+  /**
+   * Returns the pinned position of the row. (`'top'`, `'bottom'` or `false`)
+   */
+  getIsPinned: () => RowPinningPosition
+  /**
+   * Returns the numeric pinned index of the row within a pinned row group.
+   */
+  getPinnedIndex: () => number
+  /**
+   * Pins a row to the `'top'` or `'bottom'`, or unpins the row to the center if `false` is passed.
+   */
+  pin: (
+    position: RowPinningPosition,
+    includeLeafRows?: boolean,
+    includeParentRows?: boolean,
+  ) => void
+}
+
+export interface Table_RowPinning<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+> {
+  /**
+   * Gets rows pinned to the bottom region.
+   */
+  getBottomRows: () => Array<Row<TFeatures, TData>>
+  /**
+   * Gets rows that are not pinned to the top or bottom region.
+   */
+  getCenterRows: () => Array<Row<TFeatures, TData>>
+  /**
+   * Checks whether any rows are pinned, optionally limited to one region.
+   */
+  getIsSomeRowsPinned: (position?: RowPinningPosition) => boolean
+  /**
+   * Gets rows pinned to the top region.
+   */
+  getTopRows: () => Array<Row<TFeatures, TData>>
+  /**
+   * Resets `rowPinning` to `initialState.rowPinning`.
+   *
+   * Pass `true` to ignore initial state and reset to empty top/bottom arrays.
+   */
+  resetRowPinning: (defaultState?: boolean) => void
+  /**
+   * Updates row pinning state with a next state or updater function.
+   */
+  setRowPinning: (updater: Updater<RowPinningState>) => void
+}

package/src/features/row-pinning/rowPinningFeature.utils.ts

@@ -0,0 +1,323 @@
+import { row_getIsAllParentsExpanded } from '../row-expanding/rowExpandingFeature.utils'
+import { callMemoOrStaticFn, cloneState } from '../../utils'
+import type { RowData, Updater } from '../../types/type-utils'
+import type { TableFeatures } from '../../types/TableFeatures'
+import type { Table_Internal } from '../../types/Table'
+import type { Row } from '../../types/Row'
+import type {
+  RowPinningPosition,
+  RowPinningState,
+} from './rowPinningFeature.types'
+
+// State Utils
+
+/**
+ * Creates the default row pinning state.
+ *
+ * Both pinning regions start empty. Reset APIs use this value when
+ * `defaultState` is `true`.
+ *
+ * @example
+ * ```ts
+ * const pinning = getDefaultRowPinningState()
+ * ```
+ */
+export function getDefaultRowPinningState(): RowPinningState {
+  return {
+    top: [],
+    bottom: [],
+  }
+}
+
+/**
+ * Routes a row pinning updater through the table's row-pinning change handler.
+ *
+ * The updater may be a next `{ top, bottom }` state or a function of the
+ * previous state, matching the instance `table.setRowPinning` behavior.
+ *
+ * @example
+ * ```ts
+ * table_setRowPinning(table, (old) => ({ ...old, top: [rowId] }))
+ * ```
+ */
+export function table_setRowPinning<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+>(
+  table: Table_Internal<TFeatures, TData>,
+  updater: Updater<RowPinningState>,
+): void {
+  table.options.onRowPinningChange?.(updater)
+}
+
+/**
+ * Resets `rowPinning` to the configured initial state or feature default.
+ *
+ * With no argument, the reset clones `table.initialState.rowPinning` when it
+ * exists. Passing `true` ignores initial state and resets to empty top/bottom
+ * arrays.
+ *
+ * @example
+ * ```ts
+ * table_resetRowPinning(table)
+ * table_resetRowPinning(table, true)
+ * ```
+ */
+export function table_resetRowPinning<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+>(table: Table_Internal<TFeatures, TData>, defaultState?: boolean): void {
+  table_setRowPinning(
+    table,
+    defaultState
+      ? getDefaultRowPinningState()
+      : cloneState(
+          table.initialState.rowPinning ?? getDefaultRowPinningState(),
+        ),
+  )
+}
+
+// Table Utils
+
+/**
+ * Checks whether any rows are pinned.
+ *
+ * Omit `position` to check both regions, or pass `'top'`/`'bottom'` to inspect
+ * one region.
+ *
+ * @example
+ * ```ts
+ * const hasPinnedRows = table_getIsSomeRowsPinned(table)
+ * ```
+ */
+export function table_getIsSomeRowsPinned<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+>(
+  table: Table_Internal<TFeatures, TData>,
+  position?: RowPinningPosition,
+): boolean {
+  const rowPinning = table.atoms.rowPinning?.get()
+
+  if (!position) {
+    return Boolean(rowPinning?.top.length || rowPinning?.bottom.length)
+  }
+  return Boolean(rowPinning?.[position].length)
+}
+
+function table_getPinnedRows<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+>(
+  table: Table_Internal<TFeatures, TData>,
+  position: 'top' | 'bottom',
+): Array<Row<TFeatures, TData>> {
+  const visibleRows = table.getRowModel().rows
+  const pinnedRowIds = table.atoms.rowPinning?.get()?.[position] ?? []
+  const keepPinnedRows = table.options.keepPinnedRows ?? true
+
+  const result: Array<Row<TFeatures, TData>> = []
+  for (let i = 0; i < pinnedRowIds.length; i++) {
+    const rowId = pinnedRowIds[i]!
+    let row: Row<TFeatures, TData> | undefined
+    if (keepPinnedRows) {
+      // get all rows that are pinned even if they would not be otherwise
+      // visible; account for expanded parent rows, but not pagination/filtering
+      const fullRow = table.getRow(rowId, true)
+      if (row_getIsAllParentsExpanded(fullRow)) row = fullRow
+    } else {
+      // else get only visible rows that are pinned
+      row = visibleRows.find((r) => r.id === rowId)
+    }
+    if (!row)
+      continue
+      // Assign position property directly to preserve prototype chain
+    ;(row as any).position = position
+    result.push(row)
+  }
+  return result
+}
+
+/**
+ * Resolves the visible rows pinned to the top region.
+ *
+ * The result follows `state.rowPinning.top` order and marks each row with
+ * `position = 'top'`.
+ *
+ * @example
+ * ```ts
+ * const rows = table_getTopRows(table)
+ * ```
+ */
+export function table_getTopRows<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+>(table: Table_Internal<TFeatures, TData>): Array<Row<TFeatures, TData>> {
+  return table_getPinnedRows(table, 'top')
+}
+
+/**
+ * Resolves the visible rows pinned to the bottom region.
+ *
+ * The result follows `state.rowPinning.bottom` order and marks each row with
+ * `position = 'bottom'`.
+ *
+ * @example
+ * ```ts
+ * const rows = table_getBottomRows(table)
+ * ```
+ */
+export function table_getBottomRows<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+>(table: Table_Internal<TFeatures, TData>): Array<Row<TFeatures, TData>> {
+  return table_getPinnedRows(table, 'bottom')
+}
+
+/**
+ * Resolves rows that are not pinned to top or bottom.
+ *
+ * The current row model is filtered by `state.rowPinning.top` and
+ * `state.rowPinning.bottom`.
+ *
+ * @example
+ * ```ts
+ * const rows = table_getCenterRows(table)
+ * ```
+ */
+export function table_getCenterRows<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+>(table: Table_Internal<TFeatures, TData>): Array<Row<TFeatures, TData>> {
+  const { top, bottom } =
+    table.atoms.rowPinning?.get() ?? getDefaultRowPinningState()
+  const allRows = table.getRowModel().rows
+
+  const topAndBottom = new Set([...top, ...bottom])
+  return allRows.filter((d) => !topAndBottom.has(d.id))
+}
+
+// Row Utils
+
+/**
+ * Checks whether this row can be pinned.
+ *
+ * `options.enableRowPinning` may be a boolean or a row predicate; it defaults
+ * to `true`.
+ *
+ * @example
+ * ```ts
+ * const canPin = row_getCanPin(row)
+ * ```
+ */
+export function row_getCanPin<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+>(row: Row<TFeatures, TData>): boolean {
+  const { enableRowPinning } = row.table.options
+  if (typeof enableRowPinning === 'function') {
+    return enableRowPinning(row)
+  }
+  return enableRowPinning ?? true
+}
+
+/**
+ * Reads this row's current pinning region.
+ *
+ * Rows listed in `state.rowPinning.top` return `'top'`, rows listed in
+ * `bottom` return `'bottom'`, and unpinned rows return `false`.
+ *
+ * @example
+ * ```ts
+ * const position = row_getIsPinned(row)
+ * ```
+ */
+export function row_getIsPinned<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+>(row: Row<TFeatures, TData>): RowPinningPosition {
+  const { top, bottom } =
+    row.table.atoms.rowPinning?.get() ?? getDefaultRowPinningState()
+
+  return top.includes(row.id)
+    ? 'top'
+    : bottom.includes(row.id)
+      ? 'bottom'
+      : false
+}
+
+/**
+ * Finds this row's visible index within its pinned region.
+ *
+ * Unpinned rows return `-1`.
+ *
+ * @example
+ * ```ts
+ * const index = row_getPinnedIndex(row)
+ * ```
+ */
+export function row_getPinnedIndex<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+>(row: Row<TFeatures, TData>): number {
+  const position = row_getIsPinned(row)
+  if (!position) return -1
+
+  const visiblePinnedRowIds = (
+    position === 'top'
+      ? callMemoOrStaticFn(row.table, 'getTopRows', table_getTopRows)
+      : callMemoOrStaticFn(row.table, 'getBottomRows', table_getBottomRows)
+  ).map(({ id }) => id)
+
+  return visiblePinnedRowIds.indexOf(row.id)
+}
+
+/**
+ * Pins or unpins a row.
+ *
+ * Optional flags let callers include parent rows or leaf rows when updating
+ * the row pinning state.
+ *
+ * @example
+ * ```ts
+ * row_pin(row, 'top')
+ * ```
+ */
+export function row_pin<TFeatures extends TableFeatures, TData extends RowData>(
+  row: Row<TFeatures, TData>,
+  position: RowPinningPosition,
+  includeLeafRows?: boolean,
+  includeParentRows?: boolean,
+): void {
+  const leafRowIds = includeLeafRows
+    ? row.getLeafRows().map(({ id }) => id)
+    : []
+  const parentRowIds = includeParentRows
+    ? row.getParentRows().map(({ id }) => id)
+    : []
+  const rowIds: Set<string> = new Set([...parentRowIds, row.id, ...leafRowIds])
+
+  table_setRowPinning(row.table, (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)),
+    }
+  })
+}

package/src/features/row-selection/rowSelectionFeature.ts

@@ -0,0 +1,140 @@
+import {
+  assignPrototypeAPIs,
+  assignTableAPIs,
+  makeStateUpdater,
+} from '../../utils'
+import {
+  getDefaultRowSelectionState,
+  row_getCanMultiSelect,
+  row_getCanSelect,
+  row_getCanSelectSubRows,
+  row_getIsAllSubRowsSelected,
+  row_getIsSelected,
+  row_getIsSomeSelected,
+  row_getToggleSelectedHandler,
+  row_toggleSelected,
+  table_getFilteredSelectedRowModel,
+  table_getGroupedSelectedRowModel,
+  table_getIsAllPageRowsSelected,
+  table_getIsAllRowsSelected,
+  table_getIsSomePageRowsSelected,
+  table_getIsSomeRowsSelected,
+  table_getPreSelectedRowModel,
+  table_getSelectedRowModel,
+  table_getToggleAllPageRowsSelectedHandler,
+  table_getToggleAllRowsSelectedHandler,
+  table_resetRowSelection,
+  table_setRowSelection,
+  table_toggleAllPageRowsSelected,
+  table_toggleAllRowsSelected,
+} from './rowSelectionFeature.utils'
+import type { TableFeature } from '../../types/TableFeatures'
+
+/**
+ * Feature that adds row selection state and APIs for row and page selection.
+ */
+export const rowSelectionFeature: TableFeature = {
+  getInitialState: (initialState) => {
+    return {
+      rowSelection: getDefaultRowSelectionState(),
+      ...initialState,
+    }
+  },
+
+  getDefaultTableOptions: (table) => {
+    return {
+      onRowSelectionChange: makeStateUpdater('rowSelection', table),
+      enableRowSelection: true,
+      enableMultiRowSelection: true,
+      enableSubRowSelection: true,
+    }
+  },
+
+  assignRowPrototype: (prototype, table) => {
+    assignPrototypeAPIs('rowSelectionFeature', prototype, table, {
+      row_toggleSelected: {
+        fn: (row, value, opts) => row_toggleSelected(row, value, opts),
+      },
+      row_getIsSelected: {
+        fn: (row) => row_getIsSelected(row),
+      },
+      row_getIsSomeSelected: {
+        fn: (row) => row_getIsSomeSelected(row),
+      },
+      row_getIsAllSubRowsSelected: {
+        fn: (row) => row_getIsAllSubRowsSelected(row),
+      },
+      row_getCanSelect: {
+        fn: (row) => row_getCanSelect(row),
+      },
+      row_getCanSelectSubRows: {
+        fn: (row) => row_getCanSelectSubRows(row),
+      },
+      row_getCanMultiSelect: {
+        fn: (row) => row_getCanMultiSelect(row),
+      },
+      row_getToggleSelectedHandler: {
+        fn: (row) => row_getToggleSelectedHandler(row),
+      },
+    })
+  },
+
+  constructTableAPIs: (table) => {
+    assignTableAPIs('rowSelectionFeature', table, {
+      table_setRowSelection: {
+        fn: (updater) => table_setRowSelection(table, updater),
+      },
+      table_resetRowSelection: {
+        fn: (defaultState) => table_resetRowSelection(table, defaultState),
+      },
+      table_toggleAllRowsSelected: {
+        fn: (value) => table_toggleAllRowsSelected(table, value),
+      },
+      table_toggleAllPageRowsSelected: {
+        fn: (value) => table_toggleAllPageRowsSelected(table, value),
+      },
+      table_getPreSelectedRowModel: {
+        fn: () => table_getPreSelectedRowModel(table),
+      },
+      table_getSelectedRowModel: {
+        fn: () => table_getSelectedRowModel(table),
+        memoDeps: () => [
+          table.atoms.rowSelection?.get(),
+          table.getCoreRowModel(),
+        ],
+      },
+      table_getFilteredSelectedRowModel: {
+        fn: () => table_getFilteredSelectedRowModel(table),
+        memoDeps: () => [
+          table.atoms.rowSelection?.get(),
+          table.getFilteredRowModel(),
+        ],
+      },
+      table_getGroupedSelectedRowModel: {
+        fn: () => table_getGroupedSelectedRowModel(table),
+        memoDeps: () => [
+          table.atoms.rowSelection?.get(),
+          table.getSortedRowModel(),
+        ],
+      },
+      table_getIsAllRowsSelected: {
+        fn: () => table_getIsAllRowsSelected(table),
+      },
+      table_getIsAllPageRowsSelected: {
+        fn: () => table_getIsAllPageRowsSelected(table),
+      },
+      table_getIsSomeRowsSelected: {
+        fn: () => table_getIsSomeRowsSelected(table),
+      },
+      table_getIsSomePageRowsSelected: {
+        fn: () => table_getIsSomePageRowsSelected(table),
+      },
+      table_getToggleAllRowsSelectedHandler: {
+        fn: () => table_getToggleAllRowsSelectedHandler(table),
+      },
+      table_getToggleAllPageRowsSelectedHandler: {
+        fn: () => table_getToggleAllPageRowsSelectedHandler(table),
+      },
+    })
+  },
+}