@tanstack/react-table 9.0.0-alpha.33 → 9.0.0-alpha.35

package/src/Subscribe.ts

@@ -1,8 +1,8 @@
 'use client'
 
 import { shallow, useSelector } from '@tanstack/react-store'
+import type { Atom, ReadonlyAtom } from '@tanstack/react-store'
 import type {
-  NoInfer,
   RowData,
   Table,
   TableFeatures,
@@ -10,35 +10,104 @@ import type {
 } from '@tanstack/table-core'
 import type { FunctionComponent, ReactNode } from 'react'
 
-export type SubscribeProps<
+/**
+ * Subscribe to `table.store` (full table state). The selector receives the full
+ * {@link TableState}.
+ */
+export type SubscribePropsWithStore<
   TFeatures extends TableFeatures,
   TData extends RowData,
-  TSelected = {},
+  TSelected,
 > = {
-  /**
-   * The table instance to subscribe to. Required when using as a standalone component.
-   * Not needed when using as `table.Subscribe`.
-   */
   table: Table<TFeatures, TData>
   /**
-   * A selector function that selects the part of the table state to subscribe to.
-   * This allows for fine-grained reactivity by only re-rendering when the selected state changes.
-   */
-  selector: (state: NoInfer<TableState<TFeatures>>) => TSelected
-  /**
-   * The children to render. Can be a function that receives the selected state, or a React node.
+   * Select from full table state. Re-renders when the selected value changes
+   * (shallow compare).
+   *
+   * Required in store mode so you never accidentally subscribe to the whole
+   * store without an explicit projection.
    */
+  selector: (state: TableState<TFeatures>) => TSelected
   children: ((state: TSelected) => ReactNode) | ReactNode
 }
 
+/**
+ * Subscribe to the full value of a source (e.g. `table.atoms.rowSelection` or
+ * `table.optionsStore`). Omitting `selector` is equivalent to the identity
+ * selector — children receive `TSourceValue`.
+ */
+export type SubscribePropsWithSourceIdentity<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+  TSourceValue,
+> = {
+  table: Table<TFeatures, TData>
+  source: Atom<TSourceValue> | ReadonlyAtom<TSourceValue>
+  selector?: undefined
+  children: ((state: TSourceValue) => ReactNode) | ReactNode
+}
+
+/**
+ * Subscribe to a projected value from a source (atom or store). The selector
+ * receives the source value; children receive the projected `TSelected`.
+ */
+export type SubscribePropsWithSourceWithSelector<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+  TSourceValue,
+  TSelected,
+> = {
+  table: Table<TFeatures, TData>
+  source: Atom<TSourceValue> | ReadonlyAtom<TSourceValue>
+  selector: (state: TSourceValue) => TSelected
+  children: ((state: TSelected) => ReactNode) | ReactNode
+}
+
+/**
+ * Subscribe to a single source — atom or store (identity or projected). Prefer
+ * {@link SubscribePropsWithSourceIdentity} or {@link SubscribePropsWithSourceWithSelector}
+ * for clearer inference when `selector` is omitted.
+ */
+export type SubscribePropsWithSource<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+  TSourceValue,
+  TSelected = TSourceValue,
+> =
+  | SubscribePropsWithSourceIdentity<TFeatures, TData, TSourceValue>
+  | SubscribePropsWithSourceWithSelector<
+      TFeatures,
+      TData,
+      TSourceValue,
+      TSelected
+    >
+
+export type SubscribeProps<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+  TSelected = unknown,
+  TSourceValue = unknown,
+> =
+  | SubscribePropsWithStore<TFeatures, TData, TSelected>
+  | SubscribePropsWithSourceIdentity<TFeatures, TData, TSourceValue>
+  | SubscribePropsWithSourceWithSelector<
+      TFeatures,
+      TData,
+      TSourceValue,
+      TSelected
+    >
+
 /**
  * A React component that allows you to subscribe to the table state.
  *
  * This is useful for opting into state re-renders for specific parts of the table state.
  *
+ * For `table.Subscribe` from `useTable`, prefer that API — it uses overloads so JSX
+ * contextual typing works. This standalone component uses a union `props` type.
+ *
  * @example
  * ```tsx
- * // As a standalone component
+ * // As a standalone component — full store
  * <Subscribe table={table} selector={(state) => ({ rowSelection: state.rowSelection })}>
  *   {({ rowSelection }) => (
  *     <div>Selected rows: {Object.keys(rowSelection).length}</div>
@@ -48,6 +117,26 @@ export type SubscribeProps<
  *
  * @example
  * ```tsx
+ * // Entire source (atom or store) — no selector
+ * <Subscribe table={table} source={table.atoms.rowSelection}>
+ *   {(rowSelection) => <div>...</div>}
+ * </Subscribe>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Project source value (e.g. one row’s selection)
+ * <Subscribe
+ *   table={table}
+ *   source={table.atoms.rowSelection}
+ *   selector={(rowSelection) => rowSelection?.[row.id]}
+ * >
+ *   {(selected) => <tr data-selected={!!selected}>...</tr>}
+ * </Subscribe>
+ * ```
+ *
+ * @example
+ * ```tsx
  * // As table.Subscribe (table instance method)
  * <table.Subscribe selector={(state) => ({ rowSelection: state.rowSelection })}>
  *   {({ rowSelection }) => (
@@ -59,15 +148,52 @@ export type SubscribeProps<
 export function Subscribe<
   TFeatures extends TableFeatures,
   TData extends RowData,
-  TSelected = {},
+  TSourceValue,
+>(
+  props: SubscribePropsWithSourceIdentity<TFeatures, TData, TSourceValue>,
+): ReturnType<FunctionComponent>
+export function Subscribe<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+  TSourceValue,
+  TSelected,
+>(
+  props: SubscribePropsWithSourceWithSelector<
+    TFeatures,
+    TData,
+    TSourceValue,
+    TSelected
+  >,
+): ReturnType<FunctionComponent>
+export function Subscribe<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+  TSelected,
 >(
-  props: SubscribeProps<TFeatures, TData, TSelected>,
+  props: SubscribePropsWithStore<TFeatures, TData, TSelected>,
+): ReturnType<FunctionComponent>
+export function Subscribe<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+  TSelected,
+  TSourceValue,
+>(
+  props: SubscribeProps<TFeatures, TData, TSelected, TSourceValue>,
 ): ReturnType<FunctionComponent> {
-  const selected = useSelector(props.table.store, props.selector, {
-    compare: shallow,
-  })
+  const source = 'source' in props ? props.source : props.table.store
+  const selectFn =
+    'source' in props ? (props.selector ?? ((x: unknown) => x)) : props.selector
+
+  const selected = useSelector(
+    // Atom and store share the same selection protocol; union args need a widen for TS.
+    source,
+    selectFn as Parameters<typeof useSelector>[1],
+    {
+      compare: shallow,
+    },
+  ) as TSelected
 
   return typeof props.children === 'function'
-    ? props.children(selected)
+    ? (props.children as (state: TSelected) => ReactNode)(selected)
     : props.children
 }

package/src/static-functions.ts

@@ -0,0 +1 @@
+export * from '@tanstack/table-core/static-functions'

package/src/useLegacyTable.ts

@@ -15,18 +15,21 @@ import {
   sortFns,
   stockFeatures,
 } from '@tanstack/table-core'
-import { useMemo } from 'react'
+import { useCallback, useMemo } from 'react'
 import { useTable } from './useTable'
 import type {
+  AggregationFns,
   Cell,
   Column,
   ColumnDef,
   CreateRowModels_All,
+  FilterFns,
   Header,
   HeaderGroup,
   Row,
   RowData,
   RowModel,
+  SortFns,
   StockFeatures,
   Table,
   TableOptions,
@@ -233,6 +236,21 @@ export interface LegacyRowModelOptions<TData extends RowData> {
    * @deprecated Use `_rowModels.facetedUniqueValues` with `createFacetedUniqueValues()` instead.
    */
   getFacetedUniqueValues?: FacetedUniqueValuesFactory<TData>
+  /**
+   * Additional filter functions to apply to the table.
+   * @deprecated Use `_rowModels.filteredRowModel` with `createFilteredRowModel(filterFns)` instead.
+   */
+  filterFns?: FilterFns
+  /**
+   * Additional sort functions to apply to the table.
+   * @deprecated Use `_rowModels.sortedRowModel` with `createSortedRowModel(sortFns)` instead.
+   */
+  sortFns?: SortFns
+  /**
+   * Additional aggregation functions to apply to the table.
+   * @deprecated Use `_rowModels.groupedRowModel` with `createGroupedRowModel(aggregationFns)` instead.
+   */
+  aggregationFns?: AggregationFns
 }
 
 /**
@@ -264,6 +282,11 @@ export type LegacyReactTable<TData extends RowData> = ReactTable<
    * @deprecated In v9, access state directly via `table.state` or use `table.store.state` for the full state.
    */
   getState: () => TableState<StockFeatures>
+  /**
+   * Sets the current table state.
+   * @deprecated In v9, access state directly via `table.baseAtoms`
+   */
+  setState: (state: TableState<StockFeatures>) => void
 }
 
 // =============================================================================
@@ -386,11 +409,17 @@ export function useLegacyTable<TData extends RowData>(
   // Note: getCoreRowModel is handled automatically in v9, so we ignore it
 
   if (getFilteredRowModel) {
-    _rowModels.filteredRowModel = createFilteredRowModel(filterFns)
+    _rowModels.filteredRowModel = createFilteredRowModel({
+      ...filterFns,
+      ...options.filterFns,
+    })
   }
 
   if (getSortedRowModel) {
-    _rowModels.sortedRowModel = createSortedRowModel(sortFns)
+    _rowModels.sortedRowModel = createSortedRowModel({
+      ...sortFns,
+      ...options.sortFns,
+    })
   }
 
   if (getPaginationRowModel) {
@@ -402,7 +431,10 @@ export function useLegacyTable<TData extends RowData>(
   }
 
   if (getGroupedRowModel) {
-    _rowModels.groupedRowModel = createGroupedRowModel(aggregationFns)
+    _rowModels.groupedRowModel = createGroupedRowModel({
+      ...aggregationFns,
+      ...options.aggregationFns,
+    })
   }
 
   if (getFacetedRowModel) {
@@ -427,12 +459,32 @@ export function useLegacyTable<TData extends RowData>(
     (state) => state,
   )
 
+  const getState = useCallback(() => {
+    // all state except for columns and data
+    return {
+      ...table.state,
+      columns: undefined,
+      data: undefined,
+    }
+  }, [table])
+
+  const setState = useCallback(
+    (state: TableState<StockFeatures>) => {
+      Object.entries(state).forEach(([key, value]) => {
+        // @ts-expect-error - baseAtoms is indexed by dynamic string keys
+        table.baseAtoms[key].set(value)
+      })
+    },
+    [table],
+  )
+
   return useMemo(
     () =>
       ({
         ...table,
-        getState: () => table.state,
+        getState,
+        setState,
       }) as LegacyReactTable<TData>,
-    [table],
+    [table, getState, setState],
   )
 }

package/src/useTable.ts

@@ -7,16 +7,16 @@ import { FlexRender } from './FlexRender'
 import { Subscribe } from './Subscribe'
 import type {
   CellData,
-  NoInfer,
   RowData,
   Table,
   TableFeatures,
   TableOptions,
   TableState,
 } from '@tanstack/table-core'
+import type { Atom, ReadonlyAtom } from '@tanstack/react-store'
 import type { FunctionComponent, ReactNode } from 'react'
 import type { FlexRenderProps } from './FlexRender'
-import type { SubscribeProps } from './Subscribe'
+import type { SubscribePropsWithStore } from './Subscribe'
 
 export type ReactTable<
   TFeatures extends TableFeatures,
@@ -28,19 +28,54 @@ export type ReactTable<
    *
    * This is useful for opting into state re-renders for specific parts of the table state.
    *
+   * Pass `source` to subscribe to a single atom or store (e.g. `table.atoms.rowSelection`
+   * or `table.optionsStore`) instead of the full `table.store`.
+   *
    * @example
    * <table.Subscribe selector={(state) => ({ rowSelection: state.rowSelection })}>
-   *   {({ rowSelection }) => ( // important to include `{() => {()}}` syntax
-   *     <tr key={row.id}>
-            // render the row
-   *     </tr>
-   *   ))}
+   *   {({ rowSelection }) => (
+   *     <tr key={row.id}>...</tr>
+   *   )}
+   * </table.Subscribe>
+   *
+   * @example
+   * <table.Subscribe source={table.atoms.rowSelection}>
+   *   {(rowSelection) => <div>...</div>}
+   * </table.Subscribe>
+   *
+   * @example
+   * <table.Subscribe source={table.atoms.rowSelection} selector={(s) => s?.[row.id]}>
+   *   {() => <tr key={row.id}>...</tr>}
    * </table.Subscribe>
    */
-  Subscribe: <TSelected>(props: {
-    selector: (state: NoInfer<TableState<TFeatures>>) => TSelected
-    children: ((state: TSelected) => ReactNode) | ReactNode
-  }) => ReturnType<FunctionComponent>
+  /**
+   * Overloads (not a single union) so `selector` callbacks get correct contextual
+   * types in JSX; a union of two `selector` signatures degrades to implicit `any`.
+   *
+   * Source **without** `selector` is a separate overload so children receive `TSourceValue`
+   * (identity projection). If `selector` were optional on one overload, `TSubSelected`
+   * would default to `unknown` instead of inferring from the source.
+   *
+   * The **source** overloads are listed first so `TSourceValue` is inferred from `source`.
+   */
+  Subscribe: {
+    <TSourceValue>(props: {
+      source: Atom<TSourceValue> | ReadonlyAtom<TSourceValue>
+      selector?: undefined
+      children: ((state: TSourceValue) => ReactNode) | ReactNode
+    }): ReturnType<FunctionComponent>
+    <TSourceValue, TSubSelected>(props: {
+      source: Atom<TSourceValue> | ReadonlyAtom<TSourceValue>
+      selector: (state: TSourceValue) => TSubSelected
+      children: ((state: TSubSelected) => ReactNode) | ReactNode
+    }): ReturnType<FunctionComponent>
+    <TSubSelected>(
+      props: Omit<
+        SubscribePropsWithStore<TFeatures, TData, TSubSelected>,
+        'table'
+      >,
+    ): ReturnType<FunctionComponent>
+  }
   /**
    * A React component that renders headers, cells, or footers with custom markup.
    * Use this utility component instead of manually calling flexRender.
@@ -92,11 +127,12 @@ export function useTable<
       TSelected
     >
 
-    tableInstance.Subscribe = function SubscribeBound<TSelected>(
-      props: Omit<SubscribeProps<TFeatures, TData, TSelected>, 'table'>,
-    ) {
-      return Subscribe({ ...props, table: tableInstance })
-    }
+    tableInstance.Subscribe = ((props: any) => {
+      return Subscribe({
+        ...props,
+        table: tableInstance,
+      })
+    }) as ReactTable<TFeatures, TData, TSelected>['Subscribe']
 
     tableInstance.FlexRender = FlexRender