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

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

@@ -0,0 +1,82 @@
+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'
+
+/**
+ * Creates a memoized expanded row model factory.
+ *
+ * The factory reads the relevant table state atoms and options, then returns a row model function used by the table row-model pipeline.
+ */
+export function createExpandedRowModel<
+  TFeatures extends TableFeatures,
+  TData extends RowData = any,
+>(): (table: Table<TFeatures, TData>) => () => RowModel<TFeatures, TData> {
+  return (_table) => {
+    const table = _table as unknown as Table_Internal<TFeatures, TData>
+    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)
+}
+
+/**
+ * Expands a row model according to the current expanded row state.
+ *
+ * Expanded sub-rows are inserted into the flattened row order while preserving the original row hierarchy.
+ */
+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,94 @@
+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 { TableFeature } from '../../types/TableFeatures'
+
+/**
+ * Feature that adds row expansion state and APIs for expandable row trees.
+ */
+export const rowExpandingFeature: TableFeature = {
+  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),
+      },
+    })
+  },
+}

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

@@ -0,0 +1,133 @@
+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 {
+  /**
+   * Checks whether this row can be expanded.
+   */
+  getCanExpand: () => boolean
+  /**
+   * Checks whether every ancestor of this row is expanded.
+   */
+  getIsAllParentsExpanded: () => boolean
+  /**
+   * Checks whether this row is currently expanded.
+   */
+  getIsExpanded: () => boolean
+  /**
+   * Creates a handler that toggles this row's expanded state.
+   */
+  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,
+> {
+  /**
+   * Enables automatic expanded-state resets when page-altering table state changes.
+   */
+  autoResetExpanded?: boolean
+  /**
+   * Allows rows with subRows to be expanded.
+   */
+  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
+  /**
+   * Called with an updater when expanded state changes. Pair this with
+   * `state.expanded` when using external state; external atoms can own the
+   * slice without this callback.
+   */
+  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
+  /**
+   * Checks whether at least one row can be expanded.
+   */
+  getCanSomeRowsExpand: () => boolean
+  /**
+   * Computes the deepest expanded row id depth.
+   */
+  getExpandedDepth: () => number
+  /**
+   * Checks whether all rows in the current row model are expanded.
+   */
+  getIsAllRowsExpanded: () => boolean
+  /**
+   * Checks whether any row is currently expanded.
+   */
+  getIsSomeRowsExpanded: () => boolean
+  /**
+   * Creates a handler that toggles all rows expanded.
+   */
+  getToggleAllRowsExpandedHandler: () => (event: unknown) => void
+  /**
+   * Resets `expanded` to `initialState.expanded`.
+   *
+   * Pass `true` to ignore initial state and reset to `{}`.
+   */
+  resetExpanded: (defaultState?: boolean) => void
+  /**
+   * Updates expanded state with `true`, a row-id map, or an updater function.
+   */
+  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,
+> {
+  /**
+   * Resolves the row model after expanded rows have been flattened into view.
+   */
+  getExpandedRowModel: () => RowModel<TFeatures, TData>
+  /**
+   * Reads the row model immediately before expansion.
+   */
+  getPreExpandedRowModel: () => RowModel<TFeatures, TData>
+}
+
+export interface CachedRowModel_Expanded<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+> {
+  expandedRowModel: () => RowModel<TFeatures, TData>
+}

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

@@ -0,0 +1,374 @@
+import { 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 {
+  ExpandedState,
+  ExpandedStateList,
+} from './rowExpandingFeature.types'
+
+/**
+ * Creates the default expanded state.
+ *
+ * The feature default is an empty map, meaning no rows are expanded. Reset APIs
+ * use this value when `defaultState` is `true`.
+ *
+ * @example
+ * ```ts
+ * const expanded = getDefaultExpandedState()
+ * ```
+ */
+export function getDefaultExpandedState(): ExpandedState {
+  return {}
+}
+
+/**
+ * Schedules an expanded-state reset after row-structure changes.
+ *
+ * The reset runs when `autoResetAll`, `autoResetExpanded`, or the default
+ * client-side expanding behavior allows it. Manual expanding opts out unless
+ * the reset options explicitly opt back in.
+ *
+ * @example
+ * ```ts
+ * table_autoResetExpanded(table)
+ * ```
+ */
+export function table_autoResetExpanded<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+>(table: Table_Internal<TFeatures, TData>) {
+  if (
+    table.options.autoResetAll ??
+    table.options.autoResetExpanded ??
+    !table.options.manualExpanding
+  ) {
+    table._reactivity.schedule(() => table_resetExpanded(table))
+  }
+}
+
+/**
+ * Routes an expanded-state updater through the table's expanded change handler.
+ *
+ * The updater may be `true`, a row-id map, or a function of the previous
+ * expanded state, matching the instance `table.setExpanded` behavior.
+ *
+ * @example
+ * ```ts
+ * table_setExpanded(table, (old) => ({ ...old, [rowId]: true }))
+ * ```
+ */
+export function table_setExpanded<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+>(table: Table_Internal<TFeatures, TData>, updater: Updater<ExpandedState>) {
+  table.options.onExpandedChange?.(updater)
+}
+
+/**
+ * Expands or collapses every row.
+ *
+ * Passing `true` stores the special expanded-all state. Passing `false` stores
+ * an empty map. Omitting the value toggles based on whether all rows are
+ * currently expanded.
+ *
+ * @example
+ * ```ts
+ * table_toggleAllRowsExpanded(table)
+ * ```
+ */
+export function table_toggleAllRowsExpanded<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+>(table: Table_Internal<TFeatures, TData>, expanded?: boolean) {
+  if (expanded ?? !table_getIsAllRowsExpanded(table)) {
+    table_setExpanded(table, true)
+  } else {
+    table_setExpanded(table, {})
+  }
+}
+
+/**
+ * Resets `expanded` to the configured initial state or feature default.
+ *
+ * With no argument, the reset clones `table.initialState.expanded` when it
+ * exists. Passing `true` ignores initial state and resets to `{}`.
+ *
+ * @example
+ * ```ts
+ * table_resetExpanded(table)
+ * table_resetExpanded(table, true)
+ * ```
+ */
+export function table_resetExpanded<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+>(table: Table_Internal<TFeatures, TData>, defaultState?: boolean) {
+  table_setExpanded(
+    table,
+    defaultState ? {} : cloneState(table.initialState.expanded ?? {}),
+  )
+}
+
+/**
+ * Checks whether at least one pre-paginated row can expand.
+ *
+ * Pagination is intentionally ignored so controls can reflect expandable rows
+ * that may not be on the current page.
+ *
+ * @example
+ * ```ts
+ * const canExpand = table_getCanSomeRowsExpand(table)
+ * ```
+ */
+export function table_getCanSomeRowsExpand<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+>(table: Table_Internal<TFeatures, TData>) {
+  return table
+    .getPrePaginatedRowModel()
+    .flatRows.some((row) => row_getCanExpand(row))
+}
+
+/**
+ * Creates an event handler that toggles all rows expanded.
+ *
+ * React-style synthetic events are persisted when present before the table state
+ * is toggled.
+ *
+ * @example
+ * ```ts
+ * const onClick = table_getToggleAllRowsExpandedHandler(table)
+ * ```
+ */
+export function table_getToggleAllRowsExpandedHandler<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+>(table: Table_Internal<TFeatures, TData>) {
+  return (e: unknown) => {
+    ;(e as any).persist?.()
+    table_toggleAllRowsExpanded(table)
+  }
+}
+
+/**
+ * Checks whether any row is expanded.
+ *
+ * The special expanded-all value `true` counts as some rows expanded.
+ *
+ * @example
+ * ```ts
+ * const someExpanded = table_getIsSomeRowsExpanded(table)
+ * ```
+ */
+export function table_getIsSomeRowsExpanded<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+>(table: Table_Internal<TFeatures, TData>) {
+  const expanded = table.atoms.expanded?.get() ?? {}
+  return expanded === true || Object.values(expanded).some(Boolean)
+}
+
+/**
+ * Checks whether every row in the current row model is expanded.
+ *
+ * The special expanded-all value `true` returns true immediately. Empty
+ * expanded state returns false.
+ *
+ * @example
+ * ```ts
+ * const allExpanded = table_getIsAllRowsExpanded(table)
+ * ```
+ */
+export function table_getIsAllRowsExpanded<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+>(table: Table_Internal<TFeatures, TData>) {
+  const expanded = table.atoms.expanded?.get() ?? {}
+
+  // If expanded is true, save some cycles and return true
+  if (expanded === true) {
+    return true
+  }
+
+  if (!Object.keys(expanded).length) {
+    return false
+  }
+
+  // If any row is not expanded, return false
+  if (table.getRowModel().flatRows.some((row) => !row_getIsExpanded(row))) {
+    return false
+  }
+
+  // They must all be expanded :shrug:
+  return true
+}
+
+/**
+ * Computes the deepest expanded row id depth.
+ *
+ * Row ids are split on `.`; expanded-all state scans the current row model,
+ * while explicit expanded state scans its expanded id keys.
+ *
+ * @example
+ * ```ts
+ * const depth = table_getExpandedDepth(table)
+ * ```
+ */
+export function table_getExpandedDepth<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+>(table: Table_Internal<TFeatures, TData>) {
+  let maxDepth = 0
+
+  const rowIds =
+    table.atoms.expanded?.get() === true
+      ? Object.keys(table.getRowModel().rowsById)
+      : Object.keys(table.atoms.expanded?.get() ?? {})
+
+  rowIds.forEach((id) => {
+    const splitId = id.split('.')
+    maxDepth = Math.max(maxDepth, splitId.length)
+  })
+
+  return maxDepth
+}
+
+/**
+ * Expands or collapses this row.
+ *
+ * Omitting `expanded` toggles the row. If the current state is expanded-all,
+ * the function first materializes that state into a row-id map before applying
+ * the row-specific change.
+ *
+ * @example
+ * ```ts
+ * row_toggleExpanded(row)
+ * ```
+ */
+export function row_toggleExpanded<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+>(row: Row<TFeatures, TData>, expanded?: boolean) {
+  table_setExpanded(row.table, (old) => {
+    const exists = old === true ? true : !!old[row.id]
+
+    let oldExpanded: ExpandedStateList = {}
+
+    if (old === true) {
+      Object.keys(row.table.getRowModel().rowsById).forEach((rowId) => {
+        oldExpanded[rowId] = true
+      })
+    } else {
+      oldExpanded = old
+    }
+
+    expanded = expanded ?? !exists
+
+    if (!exists && expanded) {
+      return {
+        ...oldExpanded,
+        [row.id]: true,
+      }
+    }
+
+    if (exists && !expanded) {
+      const { [row.id]: _, ...rest } = oldExpanded
+      return rest
+    }
+
+    return old
+  })
+}
+
+/**
+ * Checks whether this row is expanded.
+ *
+ * `options.getIsRowExpanded` can override state-derived behavior. Otherwise
+ * the row is expanded when expanded state is `true` or contains this row id.
+ *
+ * @example
+ * ```ts
+ * const expanded = row_getIsExpanded(row)
+ * ```
+ */
+export function row_getIsExpanded<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+>(row: Row<TFeatures, TData>) {
+  const expanded: ExpandedState = row.table.atoms.expanded?.get() ?? {}
+
+  return !!(
+    row.table.options.getIsRowExpanded?.(row) ??
+    (expanded === true || expanded[row.id])
+  )
+}
+
+/**
+ * Checks whether this row can be expanded.
+ *
+ * `options.getRowCanExpand` wins when provided. Otherwise rows can expand when
+ * expanding is enabled and the row has subRows.
+ *
+ * @example
+ * ```ts
+ * const canExpand = row_getCanExpand(row)
+ * ```
+ */
+export function row_getCanExpand<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+>(row: Row<TFeatures, TData>) {
+  return (
+    row.table.options.getRowCanExpand?.(row) ??
+    ((row.table.options.enableExpanding ?? true) && !!row.subRows.length)
+  )
+}
+
+/**
+ * Checks whether every ancestor of this row is expanded.
+ *
+ * The current row is not considered; only its parent chain is walked.
+ *
+ * @example
+ * ```ts
+ * const parentsExpanded = row_getIsAllParentsExpanded(row)
+ * ```
+ */
+export function row_getIsAllParentsExpanded<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+>(row: Row<TFeatures, TData>) {
+  let isFullyExpanded = true
+  let currentRow = row
+
+  while (isFullyExpanded && currentRow.parentId) {
+    currentRow = row.table.getRow(currentRow.parentId, true)
+    isFullyExpanded = row_getIsExpanded(currentRow)
+  }
+
+  return isFullyExpanded
+}
+
+/**
+ * Creates a row control handler that toggles this row's expanded state.
+ *
+ * The handler is a no-op when the row cannot expand.
+ *
+ * @example
+ * ```ts
+ * const onClick = row_getToggleExpandedHandler(row)
+ * ```
+ */
+export function row_getToggleExpandedHandler<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+>(row: Row<TFeatures, TData>) {
+  const canExpand = row_getCanExpand(row)
+
+  return () => {
+    if (!canExpand) return
+    row_toggleExpanded(row)
+  }
+}