@tanstack/vue-table 9.0.0-beta.4 → 9.0.0-beta.42

package/skills/with-tanstack-query/SKILL.md

@@ -0,0 +1,127 @@
+---
+name: with-tanstack-query
+description: >
+  Compose reactive Vue Query keys and results with Vue Table manual row processing, refs/computed state, server counts, and already-processed pages without duplicating query data into a drifting local ref.
+metadata:
+  type: composition
+  library: '@tanstack/vue-table'
+  framework: vue
+  library_version: '9.0.0-beta.42'
+requires:
+  - '@tanstack/table-core#client-vs-server'
+  - getting-started
+  - table-state
+sources:
+  - 'TanStack/table:examples/vue/with-tanstack-query'
+  - 'TanStack/table:docs/framework/vue/guide/pagination.md'
+---
+
+This skill builds on `@tanstack/table-core#client-vs-server`, `getting-started`, and `table-state`. Name each client- and server-owned processing stage first.
+
+## Setup
+
+```ts
+import { computed, ref } from 'vue'
+import { keepPreviousData, useQuery } from '@tanstack/vue-query'
+import {
+  rowPaginationFeature,
+  tableFeatures,
+  useTable,
+} from '@tanstack/vue-table'
+
+const pagination = ref({ pageIndex: 0, pageSize: 20 })
+const query = useQuery(() => ({
+  queryKey: ['people', pagination.value.pageIndex, pagination.value.pageSize],
+  queryFn: () =>
+    fetch(
+      `/api/people?page=${pagination.value.pageIndex}&size=${pagination.value.pageSize}`,
+    ).then((r) => r.json()),
+  placeholderData: keepPreviousData,
+}))
+const data = computed(() => query.data.value?.rows ?? [])
+const rowCount = computed(() => query.data.value?.rowCount ?? 0)
+const state = computed(() => ({ pagination: pagination.value }))
+const table = useTable({
+  features: tableFeatures({ rowPaginationFeature }),
+  columns,
+  data,
+  rowCount,
+  manualPagination: true,
+  state,
+  onPaginationChange: (next) => {
+    pagination.value =
+      typeof next === 'function' ? next(pagination.value) : next
+  },
+})
+```
+
+## Core Patterns
+
+### Keep query dependencies reactive
+
+Use the Vue Query options function and read refs inside it. Include every manual filter/sort/page input in the query key.
+
+### Pass Query results directly
+
+Expose result fields as computed refs. Introduce a second local data ref only for an explicit editing workflow with a cache-write policy.
+
+## Common Mistakes
+
+### HIGH Unwrapping before query construction
+
+Wrong:
+
+```ts
+const page = pagination.value.pageIndex
+useQuery(() => ({ queryKey: ['people', page], queryFn }))
+```
+
+Correct:
+
+```ts
+useQuery(() => ({ queryKey: ['people', pagination.value.pageIndex], queryFn }))
+```
+
+Only reads inside the reactive options function become query dependencies.
+
+Source: `examples/vue/with-tanstack-query/src/App.tsx`
+
+### HIGH Mirroring Query data locally
+
+Wrong:
+
+```ts
+const rows = ref(query.data.value?.rows ?? [])
+```
+
+Correct:
+
+```ts
+const rows = computed(() => query.data.value?.rows ?? [])
+```
+
+A one-time copy drifts from subsequent cache results.
+
+Source: `examples/vue/with-tanstack-query/src/App.tsx`
+
+### HIGH Omitting server counts
+
+Wrong:
+
+```ts
+useTable({ features, columns, data, manualPagination: true })
+```
+
+Correct:
+
+```ts
+useTable({ features, columns, data, rowCount, manualPagination: true })
+```
+
+One returned page cannot tell Table how many pages the server has.
+
+Source: `docs/framework/vue/guide/pagination.md`
+
+## API Discovery
+
+Inspect installed `@tanstack/vue-table/src/useTable.ts`, installed `@tanstack/vue-query/src`, and the relevant manual Table feature source for exact option types.

package/skills/with-tanstack-virtual/SKILL.md

@@ -0,0 +1,116 @@
+---
+name: with-tanstack-virtual
+description: >
+  Virtualize Vue Table final row or column models with reactive counts and scroll targets, stable keys, measurement, spacer geometry, sticky CSS, grid/flex widths, and infinite server data.
+metadata:
+  type: composition
+  library: '@tanstack/vue-table'
+  framework: vue
+  library_version: '9.0.0-beta.42'
+requires:
+  - '@tanstack/table-core#core'
+  - getting-started
+  - table-state
+sources:
+  - 'TanStack/table:docs/framework/vue/guide/virtualization.md'
+  - 'TanStack/table:examples/vue/virtualized-rows'
+  - 'TanStack/table:examples/vue/virtualized-columns'
+  - 'TanStack/table:examples/vue/virtualized-infinite-scrolling'
+---
+
+This skill builds on `@tanstack/table-core#core`, `getting-started`, and `table-state`. Virtual consumes final Table models; it is not registered in `tableFeatures`.
+
+## Setup
+
+```ts
+import { computed, ref } from 'vue'
+import { useVirtualizer } from '@tanstack/vue-virtual'
+
+const scrollElement = ref<HTMLElement | null>(null)
+const rows = computed(() => table.getRowModel().rows)
+const rowVirtualizer = useVirtualizer(
+  computed(() => ({
+    count: rows.value.length,
+    getScrollElement: () => scrollElement.value,
+    estimateSize: () => 34,
+    getItemKey: (index) => rows.value[index]!.id,
+    overscan: 5,
+  })),
+)
+const virtualRows = computed(() => rowVirtualizer.value.getVirtualItems())
+const totalSize = computed(() => rowVirtualizer.value.getTotalSize())
+```
+
+## Core Patterns
+
+### Derive from current visible models
+
+Rows come from `table.getRowModel().rows`; columns come from `table.getVisibleLeafColumns()`. Use computed options so counts and scroll targets update.
+
+### Implement the geometry
+
+Give the scroll container a bounded height and positioning context, create a spacer using `getTotalSize()`, and translate/measure virtual items. Follow the grid/flex examples for dynamic row heights and sticky headers.
+
+### Coordinate infinite fetching
+
+Fetch near the last virtual item only while `totalFetched < serverRowCount` and no request is active. Manual sorting means the server must return the sorted order and a sort change normally resets pages.
+
+## Common Mistakes
+
+### HIGH Passing a plain options snapshot
+
+Wrong:
+
+```ts
+useVirtualizer({ count: rows.value.length, getScrollElement })
+```
+
+Correct:
+
+```ts
+useVirtualizer(computed(() => ({ count: rows.value.length, getScrollElement })))
+```
+
+Computed options keep the virtual range synchronized with Vue’s current model.
+
+Source: `examples/vue/virtualized-rows/src/App.vue`
+
+### HIGH Virtualizing source arrays
+
+Wrong:
+
+```ts
+const rows = computed(() => data.value)
+```
+
+Correct:
+
+```ts
+const rows = computed(() => table.getRowModel().rows)
+```
+
+Source arrays do not represent Table’s current filtering, sorting, expansion, or pagination.
+
+Source: `docs/framework/vue/guide/virtualization.md`
+
+### HIGH Assuming Virtual provides CSS
+
+Wrong:
+
+```vue
+<div v-for="item in virtualRows" :key="item.key">{{ rows[item.index].id }}</div>
+```
+
+Correct:
+
+```vue
+<div :style="{ height: `${totalSize}px`, position: 'relative' }"><div style="position:absolute"></div></div>
+```
+
+Virtual provides measurements, not spacer layout, transforms, sticky positioning, or Table column widths.
+
+Source: `examples/vue/virtualized-columns/src/App.vue`
+
+## API Discovery
+
+Inspect installed `@tanstack/vue-table/src` and `@tanstack/vue-virtual/src`; use the maintained Vue examples for exact row, column, and infinite layout combinations.

package/src/FlexRender.ts

@@ -1,12 +1,27 @@
 import { defineComponent, h, isVNode } from 'vue'
 import type { PropType } from 'vue'
-import type {
-  Cell,
-  CellData,
-  Header,
-  RowData,
-  TableFeatures,
-} from '@tanstack/table-core'
+
+export interface FlexRenderCell {
+  column: {
+    columnDef: {
+      aggregatedCell?: any
+      cell?: any
+    }
+  }
+  getContext: () => any
+  getIsAggregated?: () => boolean
+  getIsPlaceholder?: () => boolean
+}
+
+export interface FlexRenderHeader {
+  column: {
+    columnDef: {
+      footer?: any
+      header?: any
+    }
+  }
+  getContext: () => any
+}
 
 /**
  * If rendering headers, cells, or footers with custom markup, use flexRender instead of `cell.getValue()` or `cell.renderValue()`.
@@ -60,24 +75,24 @@ export const FlexRender = defineComponent({
       default: undefined,
     },
     cell: {
-      type: Object as PropType<Cell<any, any, any>>,
+      type: Object as PropType<FlexRenderCell>,
       default: undefined,
     },
     header: {
-      type: Object as PropType<Header<any, any, any>>,
+      type: Object as PropType<FlexRenderHeader>,
       default: undefined,
     },
     footer: {
-      type: Object as PropType<Header<any, any, any>>,
+      type: Object as PropType<FlexRenderHeader>,
       default: undefined,
     },
   },
   setup: (props: {
     render?: any
     props?: any
-    cell?: Cell<any, any, any>
-    header?: Header<any, any, any>
-    footer?: Header<any, any, any>
+    cell?: FlexRenderCell
+    header?: FlexRenderHeader
+    footer?: FlexRenderHeader
   }) => {
     return () => {
       // New shorthand pattern: extract render and props from cell/header/footer

package/src/createTableHook.ts

@@ -4,7 +4,8 @@ import { FlexRender } from './FlexRender'
 import { mergeProxy } from './merge-proxy'
 import { useTable } from './useTable'
 import type { TableOptionsWithReactiveData, VueTable } from './useTable'
-import type { Component, InjectionKey, PropType, VNodeChild } from 'vue'
+import type { FlexRenderCell, FlexRenderHeader } from './FlexRender'
+import type { Component, InjectionKey, PropType } from 'vue'
 import type {
   AccessorFn,
   AccessorFnColumnDef,
@@ -25,7 +26,6 @@ import type {
   RowData,
   Table,
   TableFeatures,
-  TableState,
 } from '@tanstack/table-core'
 
 export type ComponentType<T extends Record<string, any>> = Component<T>
@@ -212,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>
@@ -225,19 +224,88 @@ 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: {
     cell: {
-      type: Object as PropType<Cell<any, any, any>>,
+      type: Object as PropType<FlexRenderCell>,
       default: undefined,
     },
     header: {
-      type: Object as PropType<Header<any, any, any>>,
+      type: Object as PropType<FlexRenderHeader>,
       default: undefined,
     },
     footer: {
-      type: Object as PropType<Header<any, any, any>>,
+      type: Object as PropType<FlexRenderHeader>,
       default: undefined,
     },
   },
@@ -280,7 +348,6 @@ export const AppFlexRender = defineComponent({
  * ```ts
  * const { useAppTable, createAppColumnHelper } = createTableHook({
  *   features,
- *   rowModels: {},
  *   tableComponents: {},
  *   cellComponents: {},
  *   headerComponents: {},
@@ -302,7 +369,12 @@ export function createTableHook<
   TTableComponents,
   TCellComponents,
   THeaderComponents
->) {
+>): CreateTableHookResult<
+  TFeatures,
+  TTableComponents,
+  TCellComponents,
+  THeaderComponents
+> {
   const TableContext = Symbol('TableContext') as InjectionKey<
     VueTable<TFeatures, any>
   >
@@ -327,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)
 
@@ -340,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) {
@@ -357,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) {
@@ -373,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({
@@ -403,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
@@ -515,7 +606,6 @@ export function createTableHook<
     }) as AppVueTable<
       TFeatures,
       TData,
-      TableState<TFeatures>,
       TTableComponents,
       TCellComponents,
       THeaderComponents
@@ -523,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