@tanstack/table-core 9.0.0-alpha.42 → 9.0.0-alpha.46

package/src/core/row-models/coreRowModelsFeature.utils.ts

@@ -4,6 +4,16 @@ import type { TableFeatures } from '../../types/TableFeatures'
 import type { RowData } from '../../types/type-utils'
 import type { RowModel } from './coreRowModelsFeature.types'
 
+/**
+ * Returns core row model for the table.
+ *
+ * This reads the relevant table atoms, options, and row-model cache to derive the current table-level value.
+ *
+ * @example
+ * ```ts
+ * const value = table_getCoreRowModel(table)
+ * ```
+ */
 export function table_getCoreRowModel<
   TFeatures extends TableFeatures,
   TData extends RowData,
@@ -17,6 +27,16 @@ export function table_getCoreRowModel<
   return table._rowModels.coreRowModel()
 }
 
+/**
+ * Returns pre filtered row model for the table.
+ *
+ * This reads the relevant table atoms, options, and row-model cache to derive the current table-level value.
+ *
+ * @example
+ * ```ts
+ * const value = table_getPreFilteredRowModel(table)
+ * ```
+ */
 export function table_getPreFilteredRowModel<
   TFeatures extends TableFeatures,
   TData extends RowData,
@@ -24,6 +44,16 @@ export function table_getPreFilteredRowModel<
   return table.getCoreRowModel()
 }
 
+/**
+ * Returns filtered row model for the table.
+ *
+ * This reads the relevant table atoms, options, and row-model cache to derive the current table-level value.
+ *
+ * @example
+ * ```ts
+ * const value = table_getFilteredRowModel(table)
+ * ```
+ */
 export function table_getFilteredRowModel<
   TFeatures extends TableFeatures,
   TData extends RowData,
@@ -40,6 +70,16 @@ export function table_getFilteredRowModel<
   return table._rowModels.filteredRowModel()
 }
 
+/**
+ * Returns pre grouped row model for the table.
+ *
+ * This reads the relevant table atoms, options, and row-model cache to derive the current table-level value.
+ *
+ * @example
+ * ```ts
+ * const value = table_getPreGroupedRowModel(table)
+ * ```
+ */
 export function table_getPreGroupedRowModel<
   TFeatures extends TableFeatures,
   TData extends RowData,
@@ -47,6 +87,16 @@ export function table_getPreGroupedRowModel<
   return table.getFilteredRowModel()
 }
 
+/**
+ * Returns grouped row model for the table.
+ *
+ * This reads the relevant table atoms, options, and row-model cache to derive the current table-level value.
+ *
+ * @example
+ * ```ts
+ * const value = table_getGroupedRowModel(table)
+ * ```
+ */
 export function table_getGroupedRowModel<
   TFeatures extends TableFeatures,
   TData extends RowData,
@@ -63,6 +113,16 @@ export function table_getGroupedRowModel<
   return table._rowModels.groupedRowModel()
 }
 
+/**
+ * Returns pre sorted row model for the table.
+ *
+ * This reads the relevant table atoms, options, and row-model cache to derive the current table-level value.
+ *
+ * @example
+ * ```ts
+ * const value = table_getPreSortedRowModel(table)
+ * ```
+ */
 export function table_getPreSortedRowModel<
   TFeatures extends TableFeatures,
   TData extends RowData,
@@ -70,6 +130,16 @@ export function table_getPreSortedRowModel<
   return table.getGroupedRowModel()
 }
 
+/**
+ * Returns sorted row model for the table.
+ *
+ * This reads the relevant table atoms, options, and row-model cache to derive the current table-level value.
+ *
+ * @example
+ * ```ts
+ * const value = table_getSortedRowModel(table)
+ * ```
+ */
 export function table_getSortedRowModel<
   TFeatures extends TableFeatures,
   TData extends RowData,
@@ -86,6 +156,16 @@ export function table_getSortedRowModel<
   return table._rowModels.sortedRowModel()
 }
 
+/**
+ * Returns pre expanded row model for the table.
+ *
+ * This reads the relevant table atoms, options, and row-model cache to derive the current table-level value.
+ *
+ * @example
+ * ```ts
+ * const value = table_getPreExpandedRowModel(table)
+ * ```
+ */
 export function table_getPreExpandedRowModel<
   TFeatures extends TableFeatures,
   TData extends RowData,
@@ -93,6 +173,16 @@ export function table_getPreExpandedRowModel<
   return table.getSortedRowModel()
 }
 
+/**
+ * Returns expanded row model for the table.
+ *
+ * This reads the relevant table atoms, options, and row-model cache to derive the current table-level value.
+ *
+ * @example
+ * ```ts
+ * const value = table_getExpandedRowModel(table)
+ * ```
+ */
 export function table_getExpandedRowModel<
   TFeatures extends TableFeatures,
   TData extends RowData,
@@ -109,6 +199,16 @@ export function table_getExpandedRowModel<
   return table._rowModels.expandedRowModel()
 }
 
+/**
+ * Returns pre paginated row model for the table.
+ *
+ * This reads the relevant table atoms, options, and row-model cache to derive the current table-level value.
+ *
+ * @example
+ * ```ts
+ * const value = table_getPrePaginatedRowModel(table)
+ * ```
+ */
 export function table_getPrePaginatedRowModel<
   TFeatures extends TableFeatures,
   TData extends RowData,
@@ -116,6 +216,16 @@ export function table_getPrePaginatedRowModel<
   return table.getExpandedRowModel()
 }
 
+/**
+ * Returns paginated row model for the table.
+ *
+ * This reads the relevant table atoms, options, and row-model cache to derive the current table-level value.
+ *
+ * @example
+ * ```ts
+ * const value = table_getPaginatedRowModel(table)
+ * ```
+ */
 export function table_getPaginatedRowModel<
   TFeatures extends TableFeatures,
   TData extends RowData,
@@ -132,6 +242,16 @@ export function table_getPaginatedRowModel<
   return table._rowModels.paginatedRowModel()
 }
 
+/**
+ * Returns row model for the table.
+ *
+ * This reads the relevant table atoms, options, and row-model cache to derive the current table-level value.
+ *
+ * @example
+ * ```ts
+ * const value = table_getRowModel(table)
+ * ```
+ */
 export function table_getRowModel<
   TFeatures extends TableFeatures,
   TData extends RowData,

package/src/core/row-models/createCoreRowModel.ts

@@ -7,6 +7,11 @@ import type { TableFeatures } from '../../types/TableFeatures'
 import type { Row } from '../../types/Row'
 import type { RowData } from '../../types/type-utils'
 
+/**
+ * Creates a memoized core 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 createCoreRowModel<
   TFeatures extends TableFeatures,
   TData extends RowData,

package/src/core/rows/constructRow.ts

@@ -21,6 +21,11 @@ function getRowPrototype<
   return table._rowPrototype
 }
 
+/**
+ * Constructs a row instance from normalized table internals.
+ *
+ * This wires core properties, feature prototype APIs, and instance data used by table rendering and row-model operations.
+ */
 export const constructRow = <
   TFeatures extends TableFeatures,
   TData extends RowData,

package/src/core/rows/coreRowsFeature.ts

@@ -28,6 +28,11 @@ export interface CoreRowsFeatureConstructors<
   // 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,

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

@@ -48,6 +48,9 @@ export interface Row_Row<
   TFeatures extends TableFeatures,
   TData extends RowData,
 > extends Row_CoreProperties<TFeatures, TData> {
+  /**
+   * Returns all of the cells for the row by column id.
+   */
   getAllCellsByColumnId: () => Record<string, Cell<TFeatures, TData, unknown>>
   /**
    * Returns all of the cells for the row.

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

@@ -6,6 +6,16 @@ import type { TableFeatures } from '../../types/TableFeatures'
 import type { Row } from '../../types/Row'
 import type { Cell } from '../../types/Cell'
 
+/**
+ * Returns value for a row.
+ *
+ * This is the static implementation behind the matching row instance API and may read row caches or table state atoms.
+ *
+ * @example
+ * ```ts
+ * const value = row_getValue(row)
+ * ```
+ */
 export function row_getValue<
   TFeatures extends TableFeatures,
   TData extends RowData,
@@ -25,6 +35,16 @@ export function row_getValue<
   return row._valuesCache[columnId]
 }
 
+/**
+ * Returns unique values for a row.
+ *
+ * This is the static implementation behind the matching row instance API and may read row caches or table state atoms.
+ *
+ * @example
+ * ```ts
+ * const value = row_getUniqueValues(row)
+ * ```
+ */
 export function row_getUniqueValues<
   TFeatures extends TableFeatures,
   TData extends RowData,
@@ -52,6 +72,17 @@ export function row_getUniqueValues<
   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)
+ * ```
+ */
 export function row_renderValue<
   TFeatures extends TableFeatures,
   TData extends RowData,
@@ -59,6 +90,16 @@ export function row_renderValue<
   return row.getValue(columnId) ?? row.table.options.renderFallbackValue
 }
 
+/**
+ * Returns leaf rows for a row.
+ *
+ * This is the static implementation behind the matching row instance API and may read row caches or table state atoms.
+ *
+ * @example
+ * ```ts
+ * const value = row_getLeafRows(row)
+ * ```
+ */
 export function row_getLeafRows<
   TFeatures extends TableFeatures,
   TData extends RowData,
@@ -66,6 +107,16 @@ export function row_getLeafRows<
   return flattenBy(row.subRows, (d) => d.subRows)
 }
 
+/**
+ * Returns parent row for a row.
+ *
+ * This is the static implementation behind the matching row instance API and may read row caches or table state atoms.
+ *
+ * @example
+ * ```ts
+ * const value = row_getParentRow(row)
+ * ```
+ */
 export function row_getParentRow<
   TFeatures extends TableFeatures,
   TData extends RowData,
@@ -73,6 +124,16 @@ export function row_getParentRow<
   return row.parentId ? row.table.getRow(row.parentId, true) : undefined
 }
 
+/**
+ * Returns parent rows for a row.
+ *
+ * This is the static implementation behind the matching row instance API and may read row caches or table state atoms.
+ *
+ * @example
+ * ```ts
+ * const value = row_getParentRows(row)
+ * ```
+ */
 export function row_getParentRows<
   TFeatures extends TableFeatures,
   TData extends RowData,
@@ -89,6 +150,16 @@ export function row_getParentRows<
   return parentRows.reverse()
 }
 
+/**
+ * Returns all cells for a row.
+ *
+ * This is the static implementation behind the matching row instance API and may read row caches or table state atoms.
+ *
+ * @example
+ * ```ts
+ * const value = row_getAllCells(row)
+ * ```
+ */
 export function row_getAllCells<
   TFeatures extends TableFeatures,
   TData extends RowData,
@@ -98,19 +169,37 @@ export function row_getAllCells<
   })
 }
 
+/**
+ * Returns all cells by column id for a row.
+ *
+ * This is the static implementation behind the matching row instance API and may read row caches or table state atoms.
+ *
+ * @example
+ * ```ts
+ * const value = row_getAllCellsByColumnId(row)
+ * ```
+ */
 export function row_getAllCellsByColumnId<
   TFeatures extends TableFeatures,
   TData extends RowData,
 >(row: Row<TFeatures, TData>) {
-  return row.getAllCells().reduce(
-    (acc, cell) => {
-      acc[cell.column.id] = cell
-      return acc
-    },
-    {} as Record<string, Cell<TFeatures, TData, unknown>>,
-  )
+  const result: Record<string, Cell<TFeatures, TData, unknown>> = {}
+  for (const cell of row.getAllCells()) {
+    result[cell.column.id] = cell
+  }
+  return result
 }
 
+/**
+ * Returns row id for the table.
+ *
+ * This reads the relevant table atoms, options, and row-model cache to derive the current table-level value.
+ *
+ * @example
+ * ```ts
+ * const value = table_getRowId(table)
+ * ```
+ */
 export function table_getRowId<
   TFeatures extends TableFeatures,
   TData extends RowData,
@@ -126,6 +215,16 @@ export function table_getRowId<
   )
 }
 
+/**
+ * Returns row for the table.
+ *
+ * This reads the relevant table atoms, options, and row-model cache to derive the current table-level value.
+ *
+ * @example
+ * ```ts
+ * const value = table_getRow(table)
+ * ```
+ */
 export function table_getRow<
   TFeatures extends TableFeatures,
   TData extends RowData,

package/src/core/table/constructTable.ts

@@ -1,12 +1,18 @@
 import { coreFeatures } from '../coreFeatures'
 import { cloneState } from '../../utils'
 import { atomToStore } from '../reactivity/coreReactivityFeature.utils'
+import { table_syncExternalStateToBaseAtoms } from './coreTablesFeature.utils'
 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 = {},
@@ -17,6 +23,11 @@ export function getInitialTableState<TFeatures extends TableFeatures>(
   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,
@@ -28,12 +39,6 @@ export function constructTable<
     _features: { ...coreFeatures, ...tableOptions._features },
     _rowModels: {},
     _rowModelFns: {},
-    get options() {
-      return this.optionsStore.get()
-    },
-    set options(value) {
-      this.optionsStore.set(() => value)
-    },
     baseAtoms: {},
     atoms: {},
   } as Table_Internal<TFeatures, TData>
@@ -44,10 +49,26 @@ export function constructTable<
     return Object.assign(obj, feature.getDefaultTableOptions?.(table))
   }, {}) as TableOptions<TFeatures, TData>
 
-  // @ts-ignore - direct set
-  table.optionsStore = _reactivity.createWritableAtom<
-    TableOptions<TFeatures, TData>
-  >({ ...defaultOptions, ...tableOptions }, { debugName: 'table/optionsStore' })
+  const mergedOptions = { ...defaultOptions, ...tableOptions }
+
+  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,
@@ -67,16 +88,10 @@ export function constructTable<
       },
     ) as any
 
-    // create readonly derived atom: on each get(), read current options (state, then external atom, then base)
+    // create readonly derived atom: on each get(), read either external atom or base atom
     ;(table.atoms as any)[key] = _reactivity.createReadonlyAtom(
       () => {
-        // Reading optionsStore.get() keeps this reactive to setOptions
-        const opts = table.optionsStore.get()
-        const state = opts.state
-        if (key in (state ?? {})) {
-          return state![key]
-        }
-        const externalAtom = opts.atoms?.[key]
+        const externalAtom = table.options.atoms?.[key]
         if (externalAtom) {
           return externalAtom.get()
         }
@@ -86,6 +101,8 @@ export function constructTable<
     )
   }
 
+  table_syncExternalStateToBaseAtoms(table)
+
   table.store = atomToStore(
     _reactivity.createReadonlyAtom(
       () => {
@@ -114,7 +131,8 @@ export function constructTable<
 
   Row Models: ${rowModels.length ? rowModels.join('\n              ') : '(none)'}
 
-  States:     ${states.join('\n              ')}`,
+  States:     ${states.join('\n              ')}\n`,
+      { table },
     )
   }
 

package/src/core/table/coreTablesFeature.ts

@@ -12,6 +12,11 @@ export interface CoreTablesFeatureConstructors<
   // 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,

package/src/core/table/coreTablesFeature.types.ts

@@ -76,9 +76,9 @@ export interface TableOptions_Table<
   /**
    * Optionally, provide your own external writable atoms for individual state slices.
    * When an atom is provided for a given slice, it takes precedence over `options.state[key]`
-   * and the internal base atom for that slice. Writes originating from the library are
-   * still routed through the internal base atom; consumers are responsible for
-   * mirroring changes back to their external atom via the corresponding `onXChange` callback.
+   * and the internal base atom for that slice. Feature state update APIs write through
+   * the corresponding atom updater, so external atoms are the preferred v9 ownership
+   * model for app-managed table state slices.
    */
   readonly atoms?: ExternalAtoms<TFeatures>
   /**
@@ -90,8 +90,10 @@ export interface TableOptions_Table<
    */
   readonly data: ReadonlyArray<TData>
   /**
-   * Use this option to optionally pass initial state to the table. This state will be used when resetting various table states either automatically by the table (eg. `options.autoResetPageIndex`) or via functions like `table.resetRowSelection()`. Most reset function allow you optionally pass a flag to reset to a blank/default state instead of the initial state.
-   * Table state will not be reset when this object changes, which also means that the initial state object does not need to be stable.
+   * Optionally provide starting values for registered table state slices.
+   * Feature reset APIs use this value by default, and many reset APIs accept
+   * `true` to reset to that feature's blank/default state instead. Changing this
+   * object later does not reset table state, so it does not need to be stable.
    */
   readonly initialState?: Partial<TableState<TFeatures>>
   /**
@@ -106,7 +108,11 @@ export interface TableOptions_Table<
    */
   readonly meta?: TableMeta<TFeatures, TData>
   /**
-   * Pass in individual self-managed state to the table.
+   * Optionally provide externally managed values for individual state slices.
+   *
+   * Pair each slice with its matching `on[State]Change` callback so table state
+   * updates can be persisted outside the table. External atoms take precedence
+   * over this option when both are provided for the same slice.
    */
   readonly state?: Partial<TableState<TFeatures>>
 }
@@ -167,9 +173,11 @@ export interface Table_CoreProperties<
    */
   readonly options: TableOptions<TFeatures, TData>
   /**
-   * The base store for the table options.
+   * Writable atom for table options. Only created when `createOptionsStore` is
+   * true on the active core reactivity bindings. Adapters that opt out keep
+   * options as plain resolved data instead of backing them with an atom.
    */
-  readonly optionsStore: Atom<TableOptions<TFeatures, TData>>
+  readonly optionsStore?: Atom<TableOptions<TFeatures, TData>> | undefined
   /**
    * The readonly flat store for the table state. Derives from `table.atoms`
    * only; never reads external state directly.
@@ -182,11 +190,16 @@ export interface Table_Table<
   TData extends RowData,
 > extends Table_CoreProperties<TFeatures, TData> {
   /**
-   * Call this function to reset the table state to the initial state.
+   * Resets the table's internal base atoms to `table.initialState`.
+   *
+   * Prefer feature-specific reset APIs, such as `resetPagination`, when a state
+   * slice may be owned by an external atom or needs that feature's blank/default
+   * reset behavior.
    */
   reset: () => void
   /**
-   * This function can be used to update the table options.
+   * Updates the table options by applying a value or updater to the current
+   * resolved options and then merging them through `options.mergeOptions`.
    */
   setOptions: (newOptions: Updater<TableOptions<TFeatures, TData>>) => void
 }