@tanstack/ember-table 9.0.0-beta.0

package/skills/getting-started/SKILL.md

@@ -0,0 +1,160 @@
+---
+name: getting-started
+description: >
+  Create a TanStack Ember Table v9 table with useTable, a tracked options thunk, stable tableFeatures and columns, .gts templates, FlexRenderCell/Header/Footer, and correctly bound template helpers. Load for first-table setup, Glimmer reactivity, component cell renderers, or adapting another framework's example to Ember.
+metadata:
+  type: framework
+  library: '@tanstack/ember-table'
+  framework: ember
+  library_version: '9.0.0-beta.38'
+requires:
+  - '@tanstack/table-core#core'
+  - '@tanstack/table-core#table-features'
+sources:
+  - 'TanStack/table:docs/framework/ember/quick-start.md'
+  - 'TanStack/table:examples/ember/basic-table'
+  - 'TanStack/table:packages/ember-table/src/index.ts'
+  - 'TanStack/table:packages/ember-table/src/use-table.ts'
+  - 'TanStack/table:packages/ember-table/src/FlexRender.gts'
+---
+
+This skill builds on `@tanstack/table-core#core` and `@tanstack/table-core#table-features`. Ember Table is headless: it supplies reactive table models and renderer helpers, while the application owns semantic markup, CSS, accessibility, and design-system components.
+
+The v9 addon requires Ember 5.8 or newer with Embroider or ember-auto-import v2. Prefer `.gts`/`.gjs` template-tag components with Glint.
+
+## Setup
+
+```gts
+import Component from '@glimmer/component'
+import { tracked } from '@glimmer/tracking'
+import { on } from '@ember/modifier'
+import {
+  FlexRenderCell,
+  FlexRenderHeader,
+  createColumnHelper,
+  tableFeatures,
+  useTable,
+  type Cell,
+  type Row,
+} from '@tanstack/ember-table'
+
+type Person = { id: string; name: string }
+
+const features = tableFeatures({})
+const columnHelper = createColumnHelper<typeof features, Person>()
+const columns = columnHelper.columns([
+  columnHelper.accessor('name', { header: 'Name' }),
+])
+const initialData: Person[] = [{ id: '1', name: 'Ada' }]
+const getRowId = (row: Person) => row.id
+
+const getAllCells = (
+  row: Row<typeof features, Person>,
+): Array<Cell<typeof features, Person>> => row.getAllCells()
+
+export default class PeopleTable extends Component {
+  @tracked data = initialData
+
+  table = useTable(() => ({
+    features,
+    columns,
+    data: this.data,
+    getRowId,
+  }))
+
+  get headerGroups() {
+    return this.table.getHeaderGroups()
+  }
+
+  get rows() {
+    return this.table.getRowModel().rows
+  }
+
+  addPerson = () => {
+    this.data = [...this.data, { id: '2', name: 'Grace' }]
+  }
+
+  <template>
+    <button type='button' {{on 'click' this.addPerson}}>Add person</button>
+    <table>
+      <thead>
+        {{#each this.headerGroups as |group|}}
+          <tr>
+            {{#each group.headers as |header|}}
+              <th colspan={{header.colSpan}}>
+                {{#unless header.isPlaceholder}}
+                  <FlexRenderHeader @header={{header}} />
+                {{/unless}}
+              </th>
+            {{/each}}
+          </tr>
+        {{/each}}
+      </thead>
+      <tbody>
+        {{#each this.rows as |row|}}
+          <tr>
+            {{#each (getAllCells row) as |cell|}}
+              <td><FlexRenderCell @cell={{cell}} /></td>
+            {{/each}}
+          </tr>
+        {{/each}}
+      </tbody>
+    </table>
+  </template>
+}
+```
+
+`useTable` takes an options thunk. Tracked properties read by that thunk update table options, and table API reads inside getters/templates participate in Glimmer tracking. Keep `features` and `columns` at stable module or component-lifetime scope; replace `@tracked data` only when data meaningfully changes.
+
+## Ember-Specific Patterns
+
+### Preserve method receivers in templates
+
+V9 table, column, row, cell, and header methods live on prototypes and require their receiver. Ember templates extract function references, so call methods in a getter or a small module-level helper:
+
+```gts
+const getCanSort = (column: Column<typeof features, Person>) =>
+  column.getCanSort()
+
+const toggleSort =
+  (column: Column<typeof features, Person>) => (event: Event) =>
+    column.getToggleSortingHandler()?.(event)
+```
+
+Pass `toggleSort header.column` to `{{on}}`; do not pass an extracted Table method directly.
+
+### Render definitions through the matching component
+
+Use `FlexRenderCell`, `FlexRenderHeader`, and `FlexRenderFooter` with their matching object. A definition may return a primitive or `flexRenderComponent(Component, options)`. The rendered component receives `@ctx` and optional `@options`; Table does not instantiate arbitrary component-library markup for you.
+
+## Common Mistakes
+
+### HIGH Passing an options object instead of a thunk
+
+Wrong: `useTable({ features, columns, data: this.data })`.
+
+Correct: `useTable(() => ({ features, columns, data: this.data }))`.
+
+The thunk is how tracked option reads are connected to the table.
+
+### HIGH Passing an unbound prototype method to a template modifier
+
+Wrong: `{{on 'click' header.column.getToggleSortingHandler}}`.
+
+Correct: wrap the call in a helper that invokes the method on `header.column`, as shown above.
+
+An extracted v9 prototype method loses `this` and can throw or silently target the wrong receiver.
+
+### HIGH Recreating model inputs inside the options thunk
+
+Wrong: `columns: columnHelper.columns(...)` or `data: this.data.slice()` inside `useTable(() => ...)`.
+
+Correct: keep columns stable and pass the tracked data reference directly. The thunk may rerun; it should not manufacture new model inputs on every tracked update.
+
+### MEDIUM Using a visibility-aware API without its feature
+
+With `tableFeatures({})`, render `row.getAllCells()`. Add `columnVisibilityFeature` before using `row.getVisibleCells()`.
+
+## API Discovery
+
+Inspect `node_modules/@tanstack/ember-table/src/index.ts` for exports, `use-table.ts` for options/reactivity behavior, `FlexRender.gts` and `flex-render.ts` for renderer contracts, and `node_modules/@tanstack/table-core/src/features/<feature>/` for feature-gated APIs. Do not substitute React hooks, subscriptions, or component signatures.

package/skills/table-state/SKILL.md

@@ -0,0 +1,187 @@
+---
+name: table-state
+description: >
+  Read, track, initialize, control, and reset TanStack Ember Table v9 state through Glimmer-reactive table APIs, baseAtoms, atoms, store, Ember createAtom, or @tracked state plus on*Change. Load for ownership precedence, updater callbacks, stale template state, options-thunk reactivity, or incorrect table.Subscribe/store.subscribe usage.
+metadata:
+  type: framework
+  library: '@tanstack/ember-table'
+  framework: ember
+  library_version: '9.0.0-beta.38'
+requires:
+  - '@tanstack/table-core#core'
+  - getting-started
+sources:
+  - 'TanStack/table:docs/framework/ember/guide/table-state.md'
+  - 'TanStack/table:examples/ember/basic-external-atoms'
+  - 'TanStack/table:examples/ember/basic-external-state'
+  - 'TanStack/table:packages/ember-table/src/use-table.ts'
+  - 'TanStack/table:packages/ember-table/src/reactivity.ts'
+  - 'TanStack/table:packages/ember-table/src/signal.ts'
+---
+
+This skill builds on `@tanstack/table-core#core` and `getting-started`. Keep state internal unless another part of the application must read, persist, validate, or drive a slice.
+
+## State Surfaces
+
+State exists only for registered features:
+
+- `table.baseAtoms` are the table's internal writable atoms.
+- `table.atoms` are readonly, ownership-aware atoms for each registered slice.
+- `table.store.state` exposes the current flat state.
+- Feature methods such as `setSorting`, `setPageSize`, and `row.toggleSelected()` are the preferred write path.
+
+Ember's reactivity feature bridges these reads into Glimmer tracking. There is no `table.Subscribe`, no selector argument to `useTable`, and no need to subscribe during rendering. Read the relevant API inside a template-consumed getter:
+
+```gts
+get rows() {
+  return this.table.getRowModel().rows
+}
+
+get pageIndex() {
+  return this.table.atoms.pagination.get().pageIndex
+}
+```
+
+`table.store.subscribe` is not the Ember rendering mechanism. The adapter's store is pull-based; Glimmer tracks individual property and atom reads.
+
+`features` and `atoms` are construct-time inputs in this adapter. Create them once before `useTable`; rerunning the options thunk updates ordinary live options but does not swap the table's feature set or atom owners.
+
+## Choose One Owner Per Slice
+
+For a slice such as pagination, choose one source of truth:
+
+1. Internal `baseAtoms` by default.
+2. `initialState.pagination` for an internally owned starting value.
+3. An external writable atom in `atoms.pagination`.
+4. A `@tracked` value in `state.pagination`, paired with `onPaginationChange`.
+
+Read precedence is `atoms[key]` over `state[key]` over the internal `baseAtoms[key]`. Do not configure multiple owners merely as fallbacks.
+
+## Internal and Initial State
+
+With no `initialState`, `atoms`, `state`, or `on[State]Change`, Table owns registered state internally. Use `initialState` when only the starting/reset value differs:
+
+```gts
+table = useTable(() => ({
+  features,
+  columns,
+  data: this.data,
+  initialState: {
+    pagination: { pageIndex: 0, pageSize: 25 },
+  },
+}))
+```
+
+Changing `initialState` later does not reset existing state. Prefer feature reset methods such as `resetPagination()`; passing `true` requests that feature's blank/default state. Core `table.reset()` resets internal base atoms and is not the primary reset path for externally owned atoms.
+
+## External Ember Atoms
+
+Use the adapter's re-exported `createAtom` when a slice should be shared or read directly outside Table. It satisfies the TanStack Store atom contract and its reads are Glimmer-reactive:
+
+```gts
+import {
+  createAtom,
+  useTable,
+  type PaginationState,
+} from '@tanstack/ember-table'
+
+paginationAtom = createAtom<PaginationState>({
+  pageIndex: 0,
+  pageSize: 10,
+})
+
+table = useTable(() => ({
+  features,
+  columns,
+  data: this.data,
+  atoms: { pagination: this.paginationAtom },
+}))
+
+get pagination() {
+  return this.paginationAtom.get()
+}
+```
+
+Feature APIs write through the external atom, so do not add `onPaginationChange` for the same atom-owned slice. Write the external atom itself when using the low-level path.
+
+## Controlled Tracked State
+
+Use `state` plus the matching callback when a `@tracked` property owns a slice. Resolve both raw values and updater functions:
+
+```gts
+import {
+  createPaginatedRowModel,
+  rowPaginationFeature,
+  tableFeatures,
+  type PaginationState,
+} from '@tanstack/ember-table'
+
+const features = tableFeatures({
+  rowPaginationFeature,
+  paginatedRowModel: createPaginatedRowModel(),
+})
+
+@tracked pagination: PaginationState = { pageIndex: 0, pageSize: 10 }
+
+table = useTable(() => ({
+  features,
+  columns,
+  data: this.data,
+  state: { pagination: this.pagination },
+  onPaginationChange: (updater) => {
+    this.pagination =
+      typeof updater === 'function' ? updater(this.pagination) : updater
+  },
+}))
+```
+
+The pagination feature owns the state and APIs; the row-model slot enables client-side pagination. For server-owned pagination, keep `rowPaginationFeature`, omit the client row-model slot, and configure the matching manual/server data options. The options thunk must read `this.pagination`; assigning the tracked field reruns the thunk and feeds the controlled value back into Table. V9 has no global `onStateChange` option.
+
+## Low-Level Writes and Types
+
+Use a feature method first. If internally owned state truly needs a low-level update:
+
+```ts
+this.table.baseAtoms.pagination.set((old) => ({ ...old, pageIndex: 0 }))
+```
+
+Do not write `table.atoms.pagination`; it is readonly and may point at an external owner. Infer the complete registered shape with `TableState<typeof features>` and use feature-specific types such as `PaginationState` or `SortingState` for owned fields.
+
+## Common Mistakes
+
+### CRITICAL Controlling a slice without writing callbacks back
+
+Wrong:
+
+```gts
+state: { pagination: this.pagination },
+onPaginationChange: () => {},
+```
+
+Correct: apply the value-or-updater to the tracked owner. Otherwise the slice is frozen at the controlled value.
+
+### HIGH Expecting a snapshot read or subscription component
+
+Wrong: invent `<table.Subscribe>`, call `table.store.subscribe(...)` for rendering, or cache `table.store.state.pagination` outside a tracked getter.
+
+Correct: read `table.atoms.pagination.get()`, `table.store.state.pagination`, or the relevant Table API inside a template-consumed getter.
+
+`table.getState()` is removed v8 API, not an Ember state-read alternative.
+
+### HIGH Mixing atom and state ownership
+
+If both `atoms.pagination` and `state.pagination` are present, the atom wins. Choose one owner so resets and writes have an unambiguous destination.
+
+### HIGH Mutating controlled objects in place
+
+Wrong: `this.pagination.pageIndex++`.
+
+Correct: assign a new tracked value or let `table.setPageIndex(...)` invoke the controlled updater. Glimmer and the options thunk need an observable owner update.
+
+### MEDIUM Writing the internal base atom for an external owner
+
+When `atoms.pagination` owns the slice, changing `baseAtoms.pagination` does not replace the active value. Write the external atom or use the feature API.
+
+## API Discovery
+
+Inspect `node_modules/@tanstack/ember-table/src/use-table.ts` for option/state precedence and the Glimmer bridge, `signal.ts` for `createAtom` behavior, and `reactivity.ts` for scheduling/tracking. Inspect the registered feature under `node_modules/@tanstack/table-core/src/features/<feature>/` for its state type, update API, and reset semantics.

package/src/FlexRender.gts

@@ -0,0 +1,267 @@
+import Component from '@glimmer/component'
+import { FlexRenderComponentConfig } from './flex-render-helpers.ts'
+import { flexRender } from '@tanstack/table-core/flex-render'
+import type {
+  Cell_Core,
+  CellContext,
+  CellData,
+  Header_Core,
+  HeaderContext,
+  RowData,
+  TableFeatures,
+} from '@tanstack/table-core'
+import type { ComponentLike, ContentValue } from '@glint/template'
+
+type RenderOptions = Record<string, unknown> | undefined
+
+type CellRenderResult<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+  TValue extends CellData = CellData,
+> =
+  | string
+  | number
+  | null
+  | FlexRenderComponentConfig<TFeatures, TData, TValue, RenderOptions>
+
+type HeaderRenderResult<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+  TValue extends CellData = CellData,
+> =
+  | string
+  | number
+  | null
+  | FlexRenderComponentConfig<TFeatures, TData, TValue, RenderOptions>
+
+interface CellRenderSignature<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+  TValue extends CellData,
+> {
+  Args: {
+    ctx: CellContext<TFeatures, TData, TValue>
+    options?: Record<string, unknown>
+  }
+}
+
+interface HeaderRenderSignature<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+  TValue extends CellData,
+> {
+  Args: {
+    ctx: HeaderContext<TFeatures, TData, TValue>
+    options?: Record<string, unknown>
+  }
+}
+
+// --- FlexRenderCell ---
+
+export interface FlexRenderCellSignature<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+  TValue extends CellData = CellData,
+> {
+  Args: {
+    cell: Cell_Core<TFeatures, TData, TValue>
+  }
+  Element: null
+}
+
+export class FlexRenderCell<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+  TValue extends CellData = CellData,
+> extends Component<FlexRenderCellSignature<TFeatures, TData, TValue>> {
+  get result(): CellRenderResult<TFeatures, TData, TValue> {
+    const cell = this.args.cell
+    return flexRender(
+      cell.column.columnDef.cell,
+      cell.getContext(),
+    ) as CellRenderResult<TFeatures, TData, TValue>
+  }
+
+  get resolvedContext(): CellContext<TFeatures, TData, TValue> {
+    return this.args.cell.getContext()
+  }
+
+  get isComponent(): boolean {
+    return this.result instanceof FlexRenderComponentConfig
+  }
+
+  get componentToRender():
+    | ComponentLike<CellRenderSignature<TFeatures, TData, TValue>>
+    | undefined {
+    const result = this.result
+    if (result instanceof FlexRenderComponentConfig) {
+      return result.component
+    }
+    return undefined
+  }
+
+  get componentOptions(): RenderOptions {
+    const result = this.result
+    if (result instanceof FlexRenderComponentConfig) {
+      return result.options
+    }
+    return undefined
+  }
+
+  get content(): ContentValue {
+    return this.result as ContentValue
+  }
+
+  <template>
+    {{#if this.isComponent}}
+      <this.componentToRender
+        @ctx={{this.resolvedContext}}
+        @options={{this.componentOptions}}
+      />
+    {{else}}
+      {{this.content}}
+    {{/if}}
+  </template>
+}
+
+// --- FlexRenderHeader ---
+
+export interface FlexRenderHeaderSignature<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+  TValue extends CellData = CellData,
+> {
+  Args: {
+    header: Header_Core<TFeatures, TData, TValue>
+  }
+  Element: null
+}
+
+export class FlexRenderHeader<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+  TValue extends CellData = CellData,
+> extends Component<FlexRenderHeaderSignature<TFeatures, TData, TValue>> {
+  get result(): HeaderRenderResult<TFeatures, TData, TValue> {
+    const header = this.args.header
+    if (header.isPlaceholder) return null
+    return flexRender(
+      header.column.columnDef.header,
+      header.getContext(),
+    ) as HeaderRenderResult<TFeatures, TData, TValue>
+  }
+
+  get resolvedContext(): HeaderContext<TFeatures, TData, TValue> {
+    return this.args.header.getContext()
+  }
+
+  get isComponent(): boolean {
+    return this.result instanceof FlexRenderComponentConfig
+  }
+
+  get componentToRender():
+    | ComponentLike<HeaderRenderSignature<TFeatures, TData, TValue>>
+    | undefined {
+    const result = this.result
+    if (result instanceof FlexRenderComponentConfig) {
+      return result.component as unknown as ComponentLike<
+        HeaderRenderSignature<TFeatures, TData, TValue>
+      >
+    }
+    return undefined
+  }
+
+  get componentOptions(): RenderOptions {
+    const result = this.result
+    if (result instanceof FlexRenderComponentConfig) {
+      return result.options
+    }
+    return undefined
+  }
+
+  get content(): ContentValue {
+    return this.result as ContentValue
+  }
+
+  <template>
+    {{#if this.isComponent}}
+      <this.componentToRender
+        @ctx={{this.resolvedContext}}
+        @options={{this.componentOptions}}
+      />
+    {{else}}
+      {{this.content}}
+    {{/if}}
+  </template>
+}
+
+// --- FlexRenderFooter ---
+
+export interface FlexRenderFooterSignature<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+  TValue extends CellData = CellData,
+> {
+  Args: {
+    footer: Header_Core<TFeatures, TData, TValue>
+  }
+  Element: null
+}
+
+export class FlexRenderFooter<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+  TValue extends CellData = CellData,
+> extends Component<FlexRenderFooterSignature<TFeatures, TData, TValue>> {
+  get result(): HeaderRenderResult<TFeatures, TData, TValue> {
+    const footer = this.args.footer
+    if (footer.isPlaceholder) return null
+    return flexRender(
+      footer.column.columnDef.footer,
+      footer.getContext(),
+    ) as HeaderRenderResult<TFeatures, TData, TValue>
+  }
+
+  get resolvedContext(): HeaderContext<TFeatures, TData, TValue> {
+    return this.args.footer.getContext()
+  }
+
+  get isComponent(): boolean {
+    return this.result instanceof FlexRenderComponentConfig
+  }
+
+  get componentToRender():
+    | ComponentLike<HeaderRenderSignature<TFeatures, TData, TValue>>
+    | undefined {
+    const result = this.result
+    if (result instanceof FlexRenderComponentConfig) {
+      return result.component as unknown as ComponentLike<
+        HeaderRenderSignature<TFeatures, TData, TValue>
+      >
+    }
+    return undefined
+  }
+
+  get componentOptions(): RenderOptions {
+    const result = this.result
+    if (result instanceof FlexRenderComponentConfig) {
+      return result.options
+    }
+    return undefined
+  }
+
+  get content(): ContentValue {
+    return this.result as ContentValue
+  }
+
+  <template>
+    {{#if this.isComponent}}
+      <this.componentToRender
+        @ctx={{this.resolvedContext}}
+        @options={{this.componentOptions}}
+      />
+    {{else}}
+      {{this.content}}
+    {{/if}}
+  </template>
+}

package/src/create-table-hook.ts

@@ -0,0 +1,83 @@
+import { createColumnHelper as coreCreateColumnHelper } from '@tanstack/table-core'
+import { useTable } from './use-table.ts'
+import type {
+  RowData,
+  Table,
+  TableFeatures,
+  TableOptions,
+} from '@tanstack/table-core'
+
+export type CreateTableHookOptions<TFeatures extends TableFeatures> = Omit<
+  // `any` (not `RowData`) is intentional and matches the other adapters'
+  // createTableHook: shared defaults are declared before any specific TData is
+  // known, and TData-dependent options like `getRowId` and `meta` are
+  // contravariant in TData, so a narrower type would reject them here.
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  TableOptions<TFeatures, any>,
+  'columns' | 'data' | 'state'
+>
+
+export type AppEmberTable<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+> = Table<TFeatures, TData>
+
+export type AppColumnHelper<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+> = ReturnType<typeof coreCreateColumnHelper<TFeatures, TData>>
+
+/**
+ * Bundles a feature set and shared default options once so every table in your
+ * app can be created without repeating them. Returns a typed column helper
+ * factory and a `createAppTable` that wraps {@link useTable}.
+ *
+ * Unlike the React adapter's hook, this does not pre-bind cell/header
+ * components onto the table; render with the `FlexRenderCell`,
+ * `FlexRenderHeader`, and `FlexRenderFooter` components as usual.
+ *
+ * @example
+ * ```ts
+ * const { createAppTable, createAppColumnHelper } = createTableHook({
+ *   features: tableFeatures({ rowSortingFeature, sortedRowModel: createSortedRowModel(), sortFns }),
+ * })
+ *
+ * const columnHelper = createAppColumnHelper<Person>()
+ * const columns = columnHelper.columns([...])
+ *
+ * // inside a Glimmer component; options stay a thunk so tracked reads are reactive
+ * table = createAppTable(() => ({ columns, data: this.data }))
+ * ```
+ */
+export function createTableHook<TFeatures extends TableFeatures>({
+  ...defaultTableOptions
+}: CreateTableHookOptions<TFeatures>) {
+  function createAppColumnHelper<TData extends RowData>(): AppColumnHelper<
+    TFeatures,
+    TData
+  > {
+    return coreCreateColumnHelper<TFeatures, TData>()
+  }
+
+  function createAppTable<TData extends RowData>(
+    getTableOptions: () => Omit<TableOptions<TFeatures, TData>, 'features'>,
+  ): AppEmberTable<TFeatures, TData> {
+    // Keep options a thunk: the merge runs inside `useTable`'s options thunk,
+    // so tracked properties read in `getTableOptions` stay reactive. Per-table
+    // options take precedence over the shared defaults (except `features`,
+    // which only the hook provides).
+    return useTable<TFeatures, TData>(
+      () =>
+        ({
+          ...defaultTableOptions,
+          ...getTableOptions(),
+        }) as TableOptions<TFeatures, TData>,
+    )
+  }
+
+  return {
+    appFeatures: defaultTableOptions.features as TFeatures,
+    createAppColumnHelper,
+    createAppTable,
+  }
+}

package/src/experimental-worker-plugin.ts

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