@tanstack/vue-table 9.0.0-beta.5 → 9.0.0-beta.50

package/src/createTableHook.ts

@@ -5,7 +5,7 @@ import { mergeProxy } from './merge-proxy'
 import { useTable } from './useTable'
 import type { TableOptionsWithReactiveData, VueTable } from './useTable'
 import type { FlexRenderCell, FlexRenderHeader } from './FlexRender'
-import type { Component, InjectionKey, PropType, VNodeChild } from 'vue'
+import type { Component, InjectionKey, PropType } from 'vue'
 import type {
   AccessorFn,
   AccessorFnColumnDef,
@@ -26,7 +26,6 @@ import type {
   RowData,
   Table,
   TableFeatures,
-  TableState,
 } from '@tanstack/table-core'
 
 export type ComponentType<T extends Record<string, any>> = Component<T>
@@ -213,10 +212,9 @@ export interface AppHeaderProps<
 export type AppVueTable<
   TFeatures extends TableFeatures,
   TData extends RowData,
-  TSelected,
   TTableComponents extends Record<string, ComponentType<any>>,
-  TCellComponents extends Record<string, ComponentType<any>>,
-  THeaderComponents extends Record<string, ComponentType<any>>,
+  _TCellComponents extends Record<string, ComponentType<any>>,
+  _THeaderComponents extends Record<string, ComponentType<any>>,
 > = VueTable<TFeatures, TData> &
   NoInfer<TTableComponents> & {
     AppTable: Component<AppTableProps>
@@ -226,6 +224,75 @@ export type AppVueTable<
     FlexRender: typeof AppFlexRender
   }
 
+export interface CreateTableHookResult<
+  TFeatures extends TableFeatures,
+  TTableComponents extends Record<string, ComponentType<any>>,
+  TCellComponents extends Record<string, ComponentType<any>>,
+  THeaderComponents extends Record<string, ComponentType<any>>,
+> {
+  /** The features object that was passed to `createTableHook`. */
+  appFeatures: TFeatures
+  /**
+   * A column helper pre-bound to `TFeatures` and the registered components, so
+   * the cell/header/footer render props expose the bound components.
+   */
+  createAppColumnHelper: <TData extends RowData>() => AppColumnHelper<
+    TFeatures,
+    TData,
+    TCellComponents,
+    THeaderComponents
+  >
+  /**
+   * Creates a table with the `App*` wrapper components and registered
+   * `tableComponents` attached. `TData` is inferred from the `data` option.
+   */
+  useAppTable: <TData extends RowData>(
+    tableOptions: Omit<
+      TableOptionsWithReactiveData<TFeatures, TData>,
+      'features'
+    >,
+  ) => AppVueTable<
+    TFeatures,
+    TData,
+    TTableComponents,
+    TCellComponents,
+    THeaderComponents
+  >
+  /**
+   * Reads the table provided by the nearest `<table.AppTable>`. This is the same
+   * extended instance `useAppTable` returns, so the `App*` components and your
+   * `tableComponents` are available on it.
+   */
+  useTableContext: <TData extends RowData = RowData>() => AppVueTable<
+    TFeatures,
+    TData,
+    TTableComponents,
+    TCellComponents,
+    THeaderComponents
+  >
+  /**
+   * Reads the cell provided by the nearest `<table.AppCell>`, extended with your
+   * `cellComponents` and a context-bound `FlexRender`.
+   */
+  useCellContext: <TValue extends CellData = CellData>() => Cell<
+    TFeatures,
+    any,
+    TValue
+  > &
+    TCellComponents & { FlexRender: Component }
+  /**
+   * Reads the header provided by the nearest `<table.AppHeader>` /
+   * `<table.AppFooter>`, extended with your `headerComponents` and a
+   * context-bound `FlexRender`.
+   */
+  useHeaderContext: <TValue extends CellData = CellData>() => Header<
+    TFeatures,
+    any,
+    TValue
+  > &
+    THeaderComponents & { FlexRender: Component }
+}
+
 export const AppFlexRender = defineComponent({
   name: 'TableFlexRender',
   props: {
@@ -281,7 +348,6 @@ export const AppFlexRender = defineComponent({
  * ```ts
  * const { useAppTable, createAppColumnHelper } = createTableHook({
  *   features,
- *   rowModels: {},
  *   tableComponents: {},
  *   cellComponents: {},
  *   headerComponents: {},
@@ -303,7 +369,12 @@ export function createTableHook<
   TTableComponents,
   TCellComponents,
   THeaderComponents
->) {
+>): CreateTableHookResult<
+  TFeatures,
+  TTableComponents,
+  TCellComponents,
+  THeaderComponents
+> {
   const TableContext = Symbol('TableContext') as InjectionKey<
     VueTable<TFeatures, any>
   >
@@ -328,9 +399,12 @@ export function createTableHook<
     >
   }
 
-  function useTableContext<TData extends RowData = RowData>(): VueTable<
+  function useTableContext<TData extends RowData = RowData>(): AppVueTable<
     TFeatures,
-    TData
+    TData,
+    TTableComponents,
+    TCellComponents,
+    THeaderComponents
   > {
     const table = inject(TableContext)
 
@@ -341,14 +415,24 @@ export function createTableHook<
       )
     }
 
-    return table as VueTable<TFeatures, TData>
+    // The value provided by `<table.AppTable>` is the extended table (the App*
+    // wrapper components and `tableComponents` are Object.assign-ed onto the same
+    // instance `useAppTable` returns), so this asserts the runtime shape.
+    return table as unknown as AppVueTable<
+      TFeatures,
+      TData,
+      TTableComponents,
+      TCellComponents,
+      THeaderComponents
+    >
   }
 
   function useCellContext<TValue extends CellData = CellData>(): Cell<
     TFeatures,
     any,
     TValue
-  > {
+  > &
+    TCellComponents & { FlexRender: Component } {
     const cell = inject(CellContext)
 
     if (!cell) {
@@ -358,14 +442,18 @@ export function createTableHook<
       )
     }
 
-    return cell as Cell<TFeatures, any, TValue>
+    // `<table.AppCell>` Object.assign-es `cellComponents` and `FlexRender` onto
+    // the same cell instance it provides, so this asserts the runtime shape.
+    return cell as unknown as Cell<TFeatures, any, TValue> &
+      TCellComponents & { FlexRender: Component }
   }
 
   function useHeaderContext<TValue extends CellData = CellData>(): Header<
     TFeatures,
     any,
     TValue
-  > {
+  > &
+    THeaderComponents & { FlexRender: Component } {
     const header = inject(HeaderContext)
 
     if (!header) {
@@ -374,7 +462,10 @@ export function createTableHook<
       )
     }
 
-    return header as Header<TFeatures, any, TValue>
+    // `<table.AppHeader>` / `<table.AppFooter>` Object.assign `headerComponents`
+    // and `FlexRender` onto the same header instance they provide.
+    return header as unknown as Header<TFeatures, any, TValue> &
+      THeaderComponents & { FlexRender: Component }
   }
 
   const CellFlexRender = defineComponent({
@@ -404,12 +495,11 @@ export function createTableHook<
   function useAppTable<TData extends RowData>(
     tableOptions: Omit<
       TableOptionsWithReactiveData<TFeatures, TData>,
-      'features' | 'rowModels'
+      'features'
     >,
   ): AppVueTable<
     TFeatures,
     TData,
-    TableState<TFeatures>,
     TTableComponents,
     TCellComponents,
     THeaderComponents
@@ -516,7 +606,6 @@ export function createTableHook<
     }) as AppVueTable<
       TFeatures,
       TData,
-      TableState<TFeatures>,
       TTableComponents,
       TCellComponents,
       THeaderComponents
@@ -524,6 +613,8 @@ export function createTableHook<
   }
 
   return {
+    // `TableOptionsWithReactiveData` widens `features` to allow a reactive ref,
+    // so this narrows it back to the resolved `TFeatures` for `appFeatures`.
     appFeatures: defaultTableOptions.features as TFeatures,
     createAppColumnHelper,
     useAppTable,

package/src/experimental-worker-plugin.ts

@@ -0,0 +1 @@
+export * from '@tanstack/table-core/experimental-worker-plugin'

package/src/reactivity.ts

@@ -1,5 +1,4 @@
 import { computed, shallowRef, watch } from 'vue'
-import { batch } from '@tanstack/store'
 import type {
   TableAtomOptions,
   TableReactivityBindings,
@@ -84,6 +83,6 @@ export function vueReactivity(): TableReactivityBindings {
       return refToWritableAtom(shallowRef(value) as ShallowRef<T>)
     },
     untrack: (fn) => fn(),
-    batch,
+    batch: (fn) => fn(),
   }
 }

package/src/useTable.ts

@@ -7,7 +7,6 @@ import type {
   Table,
   TableFeatures,
   TableOptions,
-  TableState,
 } from '@tanstack/table-core'
 import type { MaybeRef, VNode } from 'vue'
 
@@ -47,13 +46,7 @@ function getReactiveOptionDeps<
 export type VueTable<
   TFeatures extends TableFeatures,
   TData extends RowData,
-> = Omit<Table<TFeatures, TData>, 'store'> & {
-  /**
-   * @deprecated Prefer `table.atoms.<slice>.get()` for slice snapshots, or
-   * `table.Subscribe` for explicit subscriptions. `table.store.state` is a
-   * current-value snapshot and is easy to misuse in render code.
-   */
-  readonly store: Table<TFeatures, TData>['store']
+> = Table<TFeatures, TData> & {
   /** Creates a reactive render boundary. The child function reads the table
    * atoms it needs, so Vue only tracks those atom reads.
    */
@@ -75,7 +68,6 @@ export type VueTable<
  * const table = useTable(
  *   {
  *     features,
- *     rowModels: {},
  *     columns,
  *     data,
  *   },
@@ -103,7 +95,7 @@ export function useTable<
 
   const mergedOptions = mergeProxy(tableOptions, {
     features: {
-      coreReativityFeature: reactivity,
+      coreReactivityFeature: reactivity,
       ...(unref(tableOptions.features) ?? {}),
     },
   }) as TableOptionsWithReactiveData<TFeatures, TData>
@@ -174,7 +166,7 @@ export function useTable<
   table.Subscribe = (props: {
     children: (atoms: Table<TFeatures, TData>['atoms']) => VNode | Array<VNode>
   }) => {
-    return props.children(table.atoms)
+    return props.children(table.atoms as Table<TFeatures, TData>['atoms'])
   }
 
   return table

package/skills/vue/client-to-server/SKILL.md

@@ -1,365 +0,0 @@
----
-name: vue/client-to-server
-description: >
-  Convert a client-side `@tanstack/vue-table` to server-side. Set `manualPagination` /
-  `manualSorting` / `manualFiltering` / `manualGrouping` / `manualExpanding` for whichever
-  slices the server owns; drop the matching `rowModels` factories (don't ship
-  `paginatedRowModel` when the server paginates); supply `rowCount` so `table.getPageCount()`
-  works; own the relevant state slices via either external atoms (`@tanstack/vue-store`
-  `createAtom` + `options.atoms`) or `state` + `on[State]Change` with getter wrappers. Key any
-  data fetch (TanStack Query / fetch / rxResource alternative) on the controlled state and use
-  `placeholderData: keepPreviousData` (or equivalent) to avoid a 0-rows flash between pages.
-type: lifecycle
-library: tanstack-table
-framework: vue
-library_version: '9.0.0-alpha.48'
-requires:
-  - state-management
-  - pagination
-  - filtering
-  - sorting
-sources:
-  - examples/vue/basic-external-atoms/
-  - examples/vue/basic-external-state/
-  - examples/vue/with-tanstack-query/
-  - docs/framework/vue/guide/table-state.md
----
-
-# Client-to-Server Conversion (Vue)
-
-## Dependencies
-
-```bash
-pnpm add @tanstack/vue-table @tanstack/vue-store
-# Recommended fetch layer:
-pnpm add @tanstack/vue-query
-```
-
-External atoms (`@tanstack/vue-store`) are recommended for server-managed slices. They cut the
-`on[State]Change` plumbing entirely — the table writes to the atom; the query keys on the atom.
-
-## Setup — minimal server-paginated table
-
-```vue
-<script setup lang="ts">
-import { computed, ref, watchEffect } from 'vue'
-import { createAtom, useSelector } from '@tanstack/vue-store'
-import { keepPreviousData, useQuery } from '@tanstack/vue-query'
-import {
-  FlexRender,
-  createColumnHelper,
-  rowPaginationFeature,
-  tableFeatures,
-  useTable,
-  type PaginationState,
-} from '@tanstack/vue-table'
-import { fetchPeople } from './api'
-
-type Person = { firstName: string; lastName: string; age: number }
-
-const features = tableFeatures({ rowPaginationFeature })
-const columnHelper = createColumnHelper<typeof features, Person>()
-const columns = columnHelper.columns([
-  columnHelper.accessor('firstName', { header: 'First' }),
-  columnHelper.accessor('lastName', { header: 'Last' }),
-  columnHelper.accessor('age', { header: 'Age' }),
-])
-
-// 1) Own pagination in an external atom. Cheap for the table to write through.
-const paginationAtom = createAtom<PaginationState>({
-  pageIndex: 0,
-  pageSize: 10,
-})
-const pagination = useSelector(paginationAtom)
-
-// 2) Key the query on the atom value. table.setPageIndex(...) writes to the atom
-//    → useSelector re-evaluates → useQuery refetches.
-const dataQuery = useQuery(() => ({
-  queryKey: ['people', pagination.value],
-  queryFn: () => fetchPeople(pagination.value),
-  placeholderData: keepPreviousData, // avoid "0 rows" flash between pages
-}))
-
-const tableData = computed<Person[]>(() => dataQuery.data.value?.rows ?? [])
-const rowCount = ref(0)
-watchEffect(() => {
-  const next = dataQuery.data.value?.rowCount
-  if (next != null) rowCount.value = next // keep last known total for pager UI
-})
-
-// 3) Manual pagination + `rowCount`. NO paginatedRowModel in `rowModels` — server paginates.
-const table = useTable({
-  features,
-  rowModels: {},
-  columns,
-  data: tableData,
-  rowCount,
-  atoms: { pagination: paginationAtom },
-  manualPagination: true,
-})
-</script>
-```
-
-Source: `examples/vue/with-tanstack-query/src/App.tsx`, `examples/vue/basic-external-atoms/`.
-
-## Core Patterns
-
-### 1. The `manual*` flag + `rowModels` drop pair
-
-Pick which slices live server-side and flip the matching `manual*` flag. **Also drop the
-matching `rowModels` factory** — otherwise the table re-processes server-processed rows.
-
-| Server owns | Set                      | Drop from `rowModels` |
-| ----------- | ------------------------ | --------------------- |
-| Pagination  | `manualPagination: true` | `paginatedRowModel`   |
-| Sorting     | `manualSorting: true`    | `sortedRowModel`      |
-| Filtering   | `manualFiltering: true`  | `filteredRowModel`    |
-| Grouping    | `manualGrouping: true`   | `groupedRowModel`     |
-| Expanding   | `manualExpanding: true`  | `expandedRowModel`    |
-
-Column visibility / ordering / pinning / row selection are client-side state and stay as-is.
-
-### 2. `rowCount` so `getPageCount()` works
-
-Without `rowCount`, `getPageCount()` falls back to `Math.ceil(data.length / pageSize)` — i.e.
-`1` if the server already paginated. The pager locks at "Page 1 of 1".
-
-```ts
-useTable({
-  features,
-  rowModels: {},
-  columns,
-  data: tableData,
-  rowCount: dataQuery.data.value?.rowCount, // or a stable ref/computed
-  atoms: { pagination: paginationAtom },
-  manualPagination: true,
-})
-```
-
-If `rowCount` isn't immediately available, hold the last known value in a `ref` and update via
-`watchEffect` so the pager doesn't reset to 0 during refetches.
-
-### 3. Two state-ownership shapes (pick one per slice)
-
-**External atoms (recommended with Query).** Table writes through to the atom. No
-`on[State]Change` needed.
-
-```ts
-const paginationAtom = createAtom<PaginationState>({
-  pageIndex: 0,
-  pageSize: 10,
-})
-useTable({
-  features,
-  rowModels: {},
-  columns,
-  data,
-  rowCount,
-  atoms: { pagination: paginationAtom },
-  manualPagination: true,
-})
-```
-
-**Classic `state` + `on[State]Change` with getters.** Required when migrating from v8 or
-integrating with existing Vue ref-based state. Each slice must be a getter so Vue tracks
-`.value`.
-
-```ts
-const pagination = ref<PaginationState>({ pageIndex: 0, pageSize: 10 })
-
-useTable({
-  features,
-  rowModels: {},
-  columns,
-  data,
-  rowCount,
-  state: {
-    get pagination() {
-      return pagination.value
-    },
-  },
-  onPaginationChange: (u) => {
-    pagination.value = typeof u === 'function' ? u(pagination.value) : u
-  },
-  manualPagination: true,
-})
-```
-
-**Precedence:** `atoms[slice]` > `state[slice]` > internal `baseAtoms[slice]`. Don't pass the
-same slice through both — the atoms wins silently.
-
-### 4. Cache keys must include controlled state
-
-```ts
-const sortingAtom = createAtom<SortingState>([])
-const paginationAtom = createAtom<PaginationState>({
-  pageIndex: 0,
-  pageSize: 10,
-})
-const sorting = useSelector(sortingAtom)
-const pagination = useSelector(paginationAtom)
-
-const dataQuery = useQuery(() => ({
-  queryKey: [
-    'people',
-    { sorting: sorting.value, pagination: pagination.value },
-  ],
-  queryFn: () =>
-    fetchPeople({ sorting: sorting.value, pagination: pagination.value }),
-  placeholderData: keepPreviousData,
-}))
-```
-
-If pagination/sort/filter aren't in `queryKey`, Query won't refetch when the user clicks a
-pager button — the buttons "do nothing" from the user's POV.
-
-### 5. Mixed client + server features still work
-
-Column visibility, ordering, pinning, and row selection are client state — they don't depend
-on the row model and continue to function with `manualPagination`/`manualSorting`/`manualFiltering`.
-You can have a server-paginated table where the user pins or hides columns locally.
-
-## Common Mistakes
-
-### Forgetting `manualPagination` / `manualSorting` / `manualFiltering` (CRITICAL)
-
-The table double-processes server-processed rows. If the server returned page 2 of 50,
-the table will paginate that 10-row slice again and show "Page 1 of 1".
-
-```ts
-// ❌
-useTable({
-  features,
-  rowModels: {},
-  columns,
-  data: serverPage.rows,
-  rowCount,
-  atoms: { pagination: paginationAtom },
-  // missing: manualPagination: true
-})
-```
-
-### Leaving `paginatedRowModel` registered when server paginates (CRITICAL)
-
-```ts
-// ❌ Factory ships for nothing AND the table re-paginates server-sliced data.
-rowModels: {
-  paginatedRowModel: createPaginatedRowModel()
-}
-
-// ✅
-rowModels: {
-}
-```
-
-Same applies to `sortedRowModel`, `filteredRowModel`, `groupedRowModel`, `expandedRowModel`
-when the server owns the slice.
-
-### Omitting `rowCount` (CRITICAL)
-
-`getPageCount()` returns `1` if the server already paginated. The pager UI locks at
-"Page 1 of 1" and users can't navigate.
-
-### Passing `state.pagination` without `onPaginationChange` (CRITICAL)
-
-```ts
-// ❌ table.setPageIndex(2) is a no-op — no writeback handler.
-const pagination = ref({ pageIndex: 0, pageSize: 10 })
-useTable({
-  features,
-  rowModels: {},
-  columns,
-  data,
-  rowCount,
-  state: {
-    get pagination() {
-      return pagination.value
-    },
-  },
-  manualPagination: true,
-})
-
-// ✅ Either pair `state` with `on[State]Change`, OR use `atoms`.
-```
-
-### Mixing `state.pagination` AND `atoms.pagination` for the same slice (HIGH)
-
-```ts
-useTable({
-  // ...
-  state: {
-    get pagination() {
-      return localPagination.value
-    },
-  }, // silently ignored
-  onPaginationChange: setLocalPagination, // silently ignored
-  atoms: { pagination: paginationAtom }, // wins
-})
-```
-
-Atoms beat `state`; the `state` plumbing is dead but lingering in the code. Pick one mechanism.
-
-### Forgetting to include controlled state in `queryKey` (CRITICAL)
-
-```ts
-// ❌ Never refetches when pagination changes.
-useQuery(() => ({
-  queryKey: ['people'],
-  queryFn: () => fetchPeople(pagination.value),
-}))
-
-// ✅
-useQuery(() => ({
-  queryKey: ['people', pagination.value],
-  queryFn: () => fetchPeople(pagination.value),
-}))
-```
-
-### Skipping `placeholderData: keepPreviousData` (HIGH)
-
-Between fetches the table collapses to 0 rows, the row container collapses, and scroll
-position jumps. `keepPreviousData` keeps the previous page visible during the refetch.
-
-### Passing a raw `ref` to `state.pagination` without a getter (CRITICAL — Vue-specific)
-
-```ts
-// ❌ Vue can't track .value changes on the captured ref object.
-state: { pagination: pagination }
-
-// ✅
-state: { get pagination() { return pagination.value } }
-```
-
-### Hand-rolling sort/page state instead of using the API (CRITICAL — #1 AI tell)
-
-```ts
-// ❌ Manual state machine.
-const pageIndex = ref(0)
-const next = () => {
-  pageIndex.value++
-  refetch()
-}
-
-// ✅ Built-ins.
-table.nextPage()
-table.setPageIndex(0)
-table.setSorting([{ id: 'age', desc: true }])
-table.setColumnFilters(/* ... */)
-```
-
-### "API missing" because the feature isn't in `features` (CRITICAL — v9-specific)
-
-Server-side pagination still needs `rowPaginationFeature` in `tableFeatures({...})` — that's
-what surfaces `table.setPageIndex`, `table.nextPage`, `table.getPageCount`. The factory in
-`rowModels` is what you drop; the feature stays.
-
-```ts
-const features = tableFeatures({ rowPaginationFeature }) // ✅ even with manualPagination
-```
-
-## See Also
-
-- `tanstack-table/vue/compose-with-tanstack-query` — the Query-specific wiring
-- `tanstack-table/vue/compose-with-tanstack-store` — external atoms in depth
-- `tanstack-table/vue/table-state` — getter rule, atom precedence
-- `tanstack-table/table-core/pagination` — `manualPagination` / `rowCount` semantics