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

package/src/core/rows/coreRowsFeature.ts

@@ -0,0 +1,89 @@
+import { assignPrototypeAPIs, assignTableAPIs } from '../../utils'
+import {
+  row_getAllCells,
+  row_getAllCellsByColumnId,
+  row_getLeafRows,
+  row_getParentRow,
+  row_getParentRows,
+  row_getUniqueValues,
+  row_getValue,
+  row_renderValue,
+  table_getRow,
+  table_getRowId,
+} from './coreRowsFeature.utils'
+import type { RowData } from '../../types/type-utils'
+import type { TableFeature, TableFeatures } from '../../types/TableFeatures'
+// import type {
+//   Row_Row,
+//   TableOptions_Rows,
+//   Table_Rows,
+// } from './coreRowsFeature.types'
+
+export interface CoreRowsFeatureConstructors<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+> {
+  // Row: Row_Row<TFeatures, TData>
+  // TableOptions: TableOptions_Rows<TFeatures, TData>
+  // Table: Table_Rows<TFeatures, TData>
+}
+
+/**
+ * Creates the stock core rows feature.
+ *
+ * The returned feature registers its state defaults, option defaults, and instance APIs so it can be included in a `tableFeatures({ ... })` call.
+ */
+export function constructCoreRowsFeature<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+>(): TableFeature<CoreRowsFeatureConstructors<TFeatures, TData>> {
+  return {
+    assignRowPrototype: (prototype, table) => {
+      assignPrototypeAPIs('coreRowsFeature', prototype, table, {
+        row_getAllCellsByColumnId: {
+          fn: (row) => row_getAllCellsByColumnId(row),
+          memoDeps: (row) => [row.getAllCells()],
+        },
+        row_getAllCells: {
+          fn: (row) => row_getAllCells(row),
+          memoDeps: (row) => [row.table.getAllLeafColumns()],
+        },
+        row_getLeafRows: {
+          fn: (row) => row_getLeafRows(row),
+        },
+        row_getParentRow: {
+          fn: (row) => row_getParentRow(row),
+        },
+        row_getParentRows: {
+          fn: (row) => row_getParentRows(row),
+        },
+        row_getUniqueValues: {
+          fn: (row, columnId) => row_getUniqueValues(row, columnId),
+        },
+        row_getValue: {
+          fn: (row, columnId) => row_getValue(row, columnId),
+        },
+        row_renderValue: {
+          fn: (row, columnId) => row_renderValue(row, columnId),
+        },
+      })
+    },
+    constructTableAPIs: (table) => {
+      assignTableAPIs('coreRowsFeature', table, {
+        table_getRowId: {
+          fn: (originalRow, index, parent) =>
+            table_getRowId(originalRow, table, index, parent),
+        },
+        table_getRow: {
+          fn: (id: string, searchAll?: boolean) =>
+            table_getRow(table, id, searchAll),
+        },
+      })
+    },
+  }
+}
+
+/**
+ * The Core Rows feature provides the core row functionality.
+ */
+export const coreRowsFeature = constructCoreRowsFeature()

package/src/core/rows/coreRowsFeature.types.ts

@@ -0,0 +1,117 @@
+import type { Table_Internal } from '../../types/Table'
+import type { RowData } from '../../types/type-utils'
+import type { TableFeatures } from '../../types/TableFeatures'
+import type { Row } from '../../types/Row'
+import type { Cell } from '../../types/Cell'
+
+export interface Row_CoreProperties<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+> {
+  _uniqueValuesCache: Record<string, unknown>
+  _valuesCache: Record<string, unknown>
+  /**
+   * The depth of the row (if nested or grouped) relative to the root row array.
+   */
+  depth: number
+  /**
+   * The resolved unique identifier for the row resolved via the `options.getRowId` option. Defaults to the row's index (or relative index if it is a subRow).
+   */
+  id: string
+  /**
+   * The index of the row within its parent array (or the root data array).
+   */
+  index: number
+  /**
+   * The original row object provided to the table. If the row is a grouped row, the original row object will be the first original in the group.
+   */
+  original: TData
+  /**
+   * An array of the original subRows as returned by the `options.getSubRows` option.
+   */
+  originalSubRows?: ReadonlyArray<TData>
+  /**
+   * If nested, this row's parent row id.
+   */
+  parentId?: string
+  /**
+   * An array of subRows for the row as returned and created by the `options.getSubRows` option.
+   */
+  subRows: Array<Row<TFeatures, TData>>
+  /**
+   * Reference to the parent table instance.
+   */
+  table: Table_Internal<TFeatures, TData>
+}
+
+export interface Row_Row<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+> extends Row_CoreProperties<TFeatures, TData> {
+  /**
+   * Builds a lookup of this row's cells keyed by leaf column id.
+   */
+  getAllCellsByColumnId: () => Record<string, Cell<TFeatures, TData, unknown>>
+  /**
+   * Builds one cell for each leaf column, including cells for hidden columns.
+   */
+  getAllCells: () => Array<Cell<TFeatures, TData, unknown>>
+  /**
+   * Returns the leaf rows for the row, not including any parent rows.
+   */
+  getLeafRows: () => Array<Row<TFeatures, TData>>
+  /**
+   * Returns the parent row for the row, if it exists.
+   */
+  getParentRow: () => Row<TFeatures, TData> | undefined
+  /**
+   * Returns the parent rows for the row, all the way up to a root row.
+   */
+  getParentRows: () => Array<Row<TFeatures, TData>>
+  /**
+   * Reads the values this row contributes to faceting/grouping for a column.
+   */
+  getUniqueValues: <TValue>(columnId: string) => Array<TValue>
+  /**
+   * Reads this row's accessor value for a column id and caches the result.
+   */
+  getValue: <TValue>(columnId: string) => TValue
+  /**
+   * Renders the value for the row in a given columnId the same as `getValue`, but will return the `renderFallbackValue` if no value is found.
+   */
+  renderValue: <TValue>(columnId: string) => TValue
+}
+
+export interface TableOptions_Rows<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+> {
+  /**
+   * This optional function is used to derive a unique ID for any given row. If not provided the rows index is used (nested rows join together with `.` using their grandparents' index eg. `index.index.index`). If you need to identify individual rows that are originating from any server-side operations, it's suggested you use this function to return an ID that makes sense regardless of network IO/ambiguity eg. a userId, taskId, database ID field, etc.
+   * @example getRowId: row => row.userId
+   */
+  getRowId?: (
+    originalRow: TData,
+    index: number,
+    parent?: Row<TFeatures, TData>,
+  ) => string
+  /**
+   * This optional function is used to access the sub rows for any given row. If you are using nested rows, you will need to use this function to return the sub rows object (or undefined) from the row.
+   * @example getSubRows: row => row.subRows
+   */
+  getSubRows?: (
+    originalRow: TData,
+    index: number,
+  ) => undefined | ReadonlyArray<TData>
+}
+
+export interface Table_Rows<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+> {
+  getRowId: (_: TData, index: number, parent?: Row<TFeatures, TData>) => string
+  /**
+   * Returns the row with the given ID.
+   */
+  getRow: (id: string, searchAll?: boolean) => Row<TFeatures, TData>
+}

package/src/core/rows/coreRowsFeature.utils.ts

@@ -0,0 +1,264 @@
+import { flattenBy } from '../../utils'
+import { constructCell } from '../cells/constructCell'
+import type { Table_Internal } from '../../types/Table'
+import type { RowData } from '../../types/type-utils'
+import type { TableFeatures } from '../../types/TableFeatures'
+import type { Row } from '../../types/Row'
+import type { Cell } from '../../types/Cell'
+
+/**
+ * Reads and caches this row's value for a column.
+ *
+ * The value is produced by the column accessor. Missing columns or display
+ * columns without an accessor return `undefined`.
+ *
+ * @example
+ * ```ts
+ * const firstName = row_getValue(row, 'firstName')
+ * ```
+ */
+export function row_getValue<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+>(row: Row<TFeatures, TData>, columnId: string) {
+  if (row._valuesCache.hasOwnProperty(columnId)) {
+    return row._valuesCache[columnId]
+  }
+
+  const column = row.table.getColumn(columnId)
+
+  if (!column?.accessorFn) {
+    return undefined
+  }
+
+  row._valuesCache[columnId] = column.accessorFn(row.original, row.index)
+
+  return row._valuesCache[columnId]
+}
+
+/**
+ * Reads and caches the values used by faceting/grouping for a column.
+ *
+ * If the column defines `getUniqueValues`, that result is used. Otherwise the
+ * row's accessor value is wrapped in a single-item array.
+ *
+ * @example
+ * ```ts
+ * const values = row_getUniqueValues(row, 'tags')
+ * ```
+ */
+export function row_getUniqueValues<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+>(row: Row<TFeatures, TData>, columnId: string) {
+  if (row._uniqueValuesCache.hasOwnProperty(columnId)) {
+    return row._uniqueValuesCache[columnId]
+  }
+
+  const column = row.table.getColumn(columnId)
+
+  if (!column?.accessorFn) {
+    return undefined
+  }
+
+  if (!column.columnDef.getUniqueValues) {
+    row._uniqueValuesCache[columnId] = [row.getValue(columnId)]
+    return row._uniqueValuesCache[columnId]
+  }
+
+  row._uniqueValuesCache[columnId] = column.columnDef.getUniqueValues(
+    row.original,
+    row.index,
+  )
+
+  return row._uniqueValuesCache[columnId]
+}
+
+/**
+ * Returns a renderable row value for a column.
+ *
+ * If the accessor value is nullish, the table's `renderFallbackValue` is used
+ * instead.
+ *
+ * @example
+ * ```ts
+ * const value = row_renderValue(row, 'firstName')
+ * ```
+ */
+export function row_renderValue<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+>(row: Row<TFeatures, TData>, columnId: string) {
+  return row.getValue(columnId) ?? row.table.options.renderFallbackValue
+}
+
+/**
+ * Flattens this row's descendant tree into leaf rows.
+ *
+ * The row itself is not included; only nested `subRows` are walked.
+ *
+ * @example
+ * ```ts
+ * const descendants = row_getLeafRows(row)
+ * ```
+ */
+export function row_getLeafRows<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+>(row: Row<TFeatures, TData>): Array<Row<TFeatures, TData>> {
+  return flattenBy(row.subRows, (d) => d.subRows)
+}
+
+/**
+ * Looks up this row's direct parent, if it has one.
+ *
+ * Parent lookup searches the pre-pagination row model so parent relationships
+ * are available even when the parent is not on the current page.
+ *
+ * @example
+ * ```ts
+ * const parent = row_getParentRow(row)
+ * ```
+ */
+export function row_getParentRow<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+>(row: Row<TFeatures, TData>) {
+  return row.parentId ? row.table.getRow(row.parentId, true) : undefined
+}
+
+/**
+ * Collects this row's ancestor chain from root to direct parent.
+ *
+ * The current row is not included. Rows without a parent return an empty array.
+ *
+ * @example
+ * ```ts
+ * const ancestors = row_getParentRows(row)
+ * ```
+ */
+export function row_getParentRows<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+>(row: Row<TFeatures, TData>) {
+  const parentRows: Array<Row<TFeatures, TData>> = []
+  let currentRow = row
+  // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+  while (true) {
+    const parentRow = currentRow.getParentRow()
+    if (!parentRow) break
+    parentRows.push(parentRow)
+    currentRow = parentRow
+  }
+  return parentRows.reverse()
+}
+
+/**
+ * Constructs one cell for each leaf column in this row.
+ *
+ * The result follows `table.getAllLeafColumns()` order and includes hidden
+ * columns; visibility-specific APIs filter this list later.
+ *
+ * @example
+ * ```ts
+ * const cells = row_getAllCells(row)
+ * ```
+ */
+export function row_getAllCells<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+>(row: Row<TFeatures, TData>): Array<Cell<TFeatures, TData, unknown>> {
+  const columns = row.table.getAllLeafColumns()
+  const cells: Array<Cell<TFeatures, TData, unknown>> = new Array(
+    columns.length,
+  )
+  for (let i = 0; i < columns.length; i++) {
+    cells[i] = constructCell(columns[i]!, row, row.table)
+  }
+  return cells
+}
+
+/**
+ * Builds a lookup map of this row's cells keyed by column id.
+ *
+ * This is the static implementation behind `row.getAllCellsByColumnId()`.
+ *
+ * @example
+ * ```ts
+ * const cellsById = row_getAllCellsByColumnId(row)
+ * ```
+ */
+export function row_getAllCellsByColumnId<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+>(row: Row<TFeatures, TData>) {
+  const result: Record<string, Cell<TFeatures, TData, unknown>> = {}
+  const cells = row.getAllCells()
+  for (let i = 0; i < cells.length; i++) {
+    const cell = cells[i]!
+    result[cell.column.id] = cell
+  }
+  return result
+}
+
+/**
+ * Resolves the stable id for a row.
+ *
+ * `options.getRowId` wins when provided. Otherwise root rows use their index
+ * and child rows append their index to the parent id, such as `0.2`.
+ *
+ * @example
+ * ```ts
+ * const id = table_getRowId(originalRow, table, index, parentRow)
+ * ```
+ */
+export function table_getRowId<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+>(
+  originalRow: TData,
+  table: Table_Internal<TFeatures, TData>,
+  index: number,
+  parent?: Row<TFeatures, TData>,
+) {
+  return (
+    table.options.getRowId?.(originalRow, index, parent) ??
+    `${parent ? [parent.id, index].join('.') : index}`
+  )
+}
+
+/**
+ * Looks up a row by id from the current or full row model.
+ *
+ * By default this searches `table.getRowModel()`. Passing `searchAll` searches
+ * the pre-pagination model first, then falls back to the core model.
+ *
+ * @example
+ * ```ts
+ * const row = table_getRow(table, rowId, true)
+ * ```
+ */
+export function table_getRow<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+>(
+  table: Table_Internal<TFeatures, TData>,
+  rowId: string,
+  searchAll?: boolean,
+): Row<TFeatures, TData> {
+  // TODO - simplify this across different row models
+  let row = (searchAll ? table.getPrePaginatedRowModel() : table.getRowModel())
+    .rowsById[rowId]
+
+  if (!row) {
+    row = table.getCoreRowModel().rowsById[rowId]
+    if (!row) {
+      if (process.env.NODE_ENV === 'development') {
+        throw new Error(`getRow could not find row with ID: ${rowId}`)
+      }
+      throw new Error()
+    }
+  }
+
+  return row
+}

package/src/core/table/constructTable.ts

@@ -0,0 +1,169 @@
+import { coreFeatures } from '../coreFeatures'
+import { cloneState } from '../../utils'
+import { atomToStore } from '../reactivity/coreReactivityFeature.utils'
+import { table_syncExternalStateToBaseAtoms } from './coreTablesFeature.utils'
+import type { Atom } from '@tanstack/store'
+import type { RowData } from '../../types/type-utils'
+import type { TableFeature, TableFeatures } from '../../types/TableFeatures'
+import type { Table, Table_Internal } from '../../types/Table'
+import type { TableOptions } from '../../types/TableOptions'
+import type { TableState } from '../../types/TableState'
+
+/**
+ * Builds the initial table state from registered features and user initial state.
+ *
+ * Each feature contributes its default state before user-provided `initialState` values are merged in.
+ */
+export function getInitialTableState<TFeatures extends TableFeatures>(
+  features: TFeatures,
+  initialState: Partial<TableState<TFeatures>> | undefined = {},
+): TableState<TFeatures> {
+  Object.values(features).forEach((feature) => {
+    initialState = feature.getInitialState?.(initialState) ?? initialState
+  })
+  return cloneState(initialState) as TableState<TFeatures>
+}
+
+/**
+ * Constructs a table instance from normalized table internals.
+ *
+ * This wires core properties, feature prototype APIs, and instance data used by table rendering and row-model operations.
+ */
+export function constructTable<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+>(tableOptions: TableOptions<TFeatures, TData>): Table<TFeatures, TData> {
+  const _reactivity = tableOptions.features.coreReativityFeature!
+
+  const table = {
+    _reactivity,
+    _features: { ...coreFeatures, ...tableOptions.features },
+    _rowModels: {},
+    _rowModelFns: {},
+    baseAtoms: {},
+    atoms: {},
+  } as Table_Internal<TFeatures, TData>
+
+  const featuresList: Array<TableFeature<{}>> = Object.values(table._features)
+
+  const defaultOptions = featuresList.reduce((obj, feature) => {
+    return Object.assign(obj, feature.getDefaultTableOptions?.(table))
+  }, {}) as TableOptions<TFeatures, TData>
+
+  const mergedOptions = { ...defaultOptions, ...tableOptions }
+
+  if (_reactivity.wrapExternalAtoms && mergedOptions.atoms) {
+    for (const [atomKey, _atom] of Object.entries(mergedOptions.atoms)) {
+      const atom = _atom as Atom<any>
+      const wrappedAtom = _reactivity.createWritableAtom(atom.get(), {
+        debugName: `externalAtom/${atomKey}`,
+      })
+      ;(mergedOptions.atoms as any)[atomKey] = wrappedAtom
+      // Two-way syncing between the original atom and the wrapped one.
+      let syncExternal = false
+      const syncAtomToWrappedSub = atom.subscribe((value) => {
+        if (syncExternal) return
+        wrappedAtom.set(value)
+      })
+      const syncWrappedToAtomSub = wrappedAtom.subscribe((value) => {
+        syncExternal = true
+        atom.set(value)
+        syncExternal = false
+      })
+      _reactivity.addSubscription(syncAtomToWrappedSub)
+      _reactivity.addSubscription(syncWrappedToAtomSub)
+    }
+  }
+
+  if (_reactivity.createOptionsStore) {
+    // @ts-ignore - direct set
+    table.optionsStore = _reactivity.createWritableAtom<
+      TableOptions<TFeatures, TData>
+    >(mergedOptions, { debugName: 'table/optionsStore' })
+    Object.defineProperty(table, 'options', {
+      configurable: true,
+      enumerable: true,
+      get() {
+        return table.optionsStore!.get()
+      },
+      set(value) {
+        table.optionsStore!.set(() => value) // or your real update shape
+      },
+    })
+  } else {
+    table.options = mergedOptions
+  }
+
+  table.initialState = getInitialTableState(
+    table._features,
+    table.options.initialState,
+  )
+
+  const stateKeys = Object.keys(table.initialState) as Array<
+    string & keyof TableState<TFeatures>
+  >
+
+  for (let i = 0; i < stateKeys.length; i++) {
+    const key = stateKeys[i]!
+    table.baseAtoms[key] = _reactivity.createWritableAtom(
+      table.initialState[key],
+      {
+        debugName: `table/baseAtoms/${key}`,
+      },
+    ) as any
+
+    // create readonly derived atom: on each get(), read either external atom or base atom
+    ;(table.atoms as any)[key] = _reactivity.createReadonlyAtom(
+      () => {
+        const externalAtom = table.options.atoms?.[key]
+        if (externalAtom) {
+          return externalAtom.get()
+        }
+        return table.baseAtoms[key].get()
+      },
+      { debugName: `table/atoms/${key}` },
+    )
+  }
+
+  table_syncExternalStateToBaseAtoms(table)
+
+  table.store = atomToStore(
+    _reactivity.createReadonlyAtom(
+      () => {
+        const snapshot = {} as TableState<TFeatures>
+        for (let i = 0; i < stateKeys.length; i++) {
+          const key = stateKeys[i]!
+          ;(snapshot as Record<string, unknown>)[key] = table.atoms[key].get()
+        }
+        return snapshot
+      },
+      { debugName: 'table/store' },
+    ),
+  )
+
+  if (
+    process.env.NODE_ENV === 'development' &&
+    (tableOptions.debugAll || tableOptions.debugTable)
+  ) {
+    const features = Object.keys(table._features)
+    const rowModels = Object.keys(table.options.rowModels || {})
+    const states = Object.keys(table.initialState)
+
+    console.log(
+      `Constructing Table Instance
+
+  Features:   ${features.join('\n              ')}
+
+  Row Models: ${rowModels.length ? rowModels.join('\n              ') : '(none)'}
+
+  States:     ${states.join('\n              ')}\n`,
+      { table },
+    )
+  }
+
+  for (let i = 0; i < featuresList.length; i++) {
+    featuresList[i]!.constructTableAPIs?.(table)
+  }
+
+  return table
+}

package/src/core/table/coreTablesFeature.ts

@@ -0,0 +1,41 @@
+import { assignTableAPIs } from '../../utils'
+import { table_reset, table_setOptions } from './coreTablesFeature.utils'
+import type { RowData } from '../../types/type-utils'
+import type { TableFeature, TableFeatures } from '../../types/TableFeatures'
+// import type { TableOptions_Table, Table_Table } from './coreTablesFeature.types'
+
+export interface CoreTablesFeatureConstructors<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+> {
+  // Table: Table_Table<TFeatures, TData>
+  // TableOptions: TableOptions_Table<TFeatures, TData>
+}
+
+/**
+ * Creates the stock core tables feature.
+ *
+ * The returned feature registers its state defaults, option defaults, and instance APIs so it can be included in a `tableFeatures({ ... })` call.
+ */
+export function constructCoreTablesFeature<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+>(): TableFeature<CoreTablesFeatureConstructors<TFeatures, TData>> {
+  return {
+    constructTableAPIs: (table) => {
+      assignTableAPIs('coreTablesFeature', table, {
+        table_reset: {
+          fn: () => table_reset(table),
+        },
+        table_setOptions: {
+          fn: (updater) => table_setOptions(table, updater),
+        },
+      })
+    },
+  }
+}
+
+/**
+ * The Core Tables feature provides the core table functionality for handling state and options.
+ */
+export const coreTablesFeature = constructCoreTablesFeature()