@tanstack/angular-table 9.0.0-alpha.5 → 9.0.0-alpha.52

package/src/helpers/header.ts

@@ -0,0 +1,99 @@
+import { Directive, InjectionToken, inject, input } from '@angular/core'
+import { CellData, Header, RowData, TableFeatures } from '@tanstack/table-core'
+import type { Signal } from '@angular/core'
+
+/**
+ * DI context shape for a TanStack Table header.
+ *
+ * This exists to make the current `Header` injectable by any nested component/directive
+ * without passing it through inputs/props.
+ */
+export interface TanStackTableHeaderContext<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+  TValue extends CellData,
+> {
+  /** Signal that returns the current header instance. */
+  header: Signal<Header<TFeatures, TData, TValue>>
+}
+
+/**
+ * Injection token that provides access to the current header.
+ *
+ * This token is provided by the {@link TanStackTableHeader} directive.
+ */
+export const TanStackTableHeaderToken = new InjectionToken<
+  TanStackTableHeaderContext<any, any, any>['header']
+>('[TanStack Table] HeaderContext')
+
+/**
+ * Provides a TanStack Table `Header` instance in Angular DI.
+ *
+ * The header can be injected by:
+ * - any descendant of an element using `[tanStackTableHeader]="..."`
+ * - any component instantiated by `*flexRender` when the render props contains `header`
+ *
+ * @example
+ * ```html
+ * <th [tanStackTableHeader]="header">
+ *   <app-sort-indicator />
+ * </th>
+ * ```
+ *
+ * ```ts
+ * @Component({
+ *   selector: 'app-sort-indicator',
+ *   template: `
+ *     <button (click)="toggle()">
+ *       {{ header().column.id }}
+ *     </button>
+ *   `,
+ * })
+ * export class SortIndicatorComponent {
+ *   readonly header = injectTableHeaderContext()
+ *
+ *   toggle() {
+ *     this.header().column.toggleSorting()
+ *   }
+ * }
+ * ```
+ */
+@Directive({
+  selector: '[tanStackTableHeader]',
+  exportAs: 'header',
+  providers: [
+    {
+      provide: TanStackTableHeaderToken,
+      useFactory: () => inject(TanStackTableHeader).header,
+    },
+  ],
+})
+export class TanStackTableHeader<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+  TValue extends CellData,
+> implements TanStackTableHeaderContext<TFeatures, TData, TValue> {
+  /**
+   * The current TanStack Table header.
+   *
+   * Provided as a required signal input so DI consumers always read the latest value.
+   */
+  readonly header = input.required<Header<TFeatures, TData, TValue>>({
+    alias: 'tanStackTableHeader',
+  })
+}
+
+/**
+ * Injects the current TanStack Table header signal.
+ *
+ * Available when:
+ * - there is a nearest `[tanStackTableHeader]` directive in the DI tree, or
+ * - the caller is rendered via `*flexRender` with render props containing `header`
+ */
+export function injectTableHeaderContext<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+  TValue extends CellData,
+>(): TanStackTableHeaderContext<TFeatures, TData, TValue>['header'] {
+  return inject(TanStackTableHeaderToken)
+}

package/src/helpers/table.ts

@@ -0,0 +1,85 @@
+import { Directive, InjectionToken, inject, input } from '@angular/core'
+import { RowData, TableFeatures } from '@tanstack/table-core'
+import { AngularTable } from '../injectTable'
+import type { Signal } from '@angular/core'
+
+/**
+ * Injection token that provides access to the current {@link AngularTable} instance.
+ *
+ * This token is provided by the {@link TanStackTable} directive.
+ */
+export const TanStackTableToken = new InjectionToken<
+  Signal<AngularTable<any, any>>
+>('[TanStack Table] Table Context')
+
+/**
+ * Provides a TanStack Table instance (`AngularTable`) in Angular DI.
+ *
+ * The table can be injected by:
+ * - any descendant of an element using `[tanStackTable]="..."`
+ * - any component instantiated by `*flexRender` when the render props contains `table`
+ *
+ * @example
+ * ```html
+ * <div [tanStackTable]="table">
+ *   <app-pagination />
+ * </div>
+ * ```
+ *
+ * ```ts
+ * @Component({
+ *   selector: 'app-pagination',
+ *   template: `
+ *     <button (click)="prev()" [disabled]="!table().getCanPreviousPage()">Prev</button>
+ *     <button (click)="next()" [disabled]="!table().getCanNextPage()">Next</button>
+ *   `,
+ * })
+ * export class PaginationComponent {
+ *   readonly table = injectTableContext()
+ *
+ *   prev() {
+ *     this.table().previousPage()
+ *   }
+ *   next() {
+ *     this.table().nextPage()
+ *   }
+ * }
+ * ```
+ */
+@Directive({
+  selector: '[tanStackTable]',
+  exportAs: 'table',
+  providers: [
+    {
+      provide: TanStackTableToken,
+      useFactory: () => inject(TanStackTable).table,
+    },
+  ],
+})
+export class TanStackTable<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+> {
+  /**
+   * The current TanStack Table instance.
+   *
+   * Provided as a required signal input so DI consumers always read the latest value.
+   */
+  readonly table = input.required<AngularTable<TFeatures, TData>>({
+    alias: 'tanStackTable',
+  })
+}
+
+/**
+ * Injects the current TanStack Table instance signal.
+ *
+ * Available when:
+ * - there is a nearest `[tanStackTable]` directive in the DI tree, or
+ * - the caller is rendered via `*flexRender` with render props containing `table`
+ */
+export function injectTableContext<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+>(): Signal<AngularTable<TFeatures, TData>> {
+  return inject(TanStackTableToken)
+}

package/src/index.ts

@@ -1,73 +1,26 @@
-import { computed, type Signal, signal } from '@angular/core'
-import {
-  RowData,
-  TableOptions,
-  TableOptionsResolved,
-  TableState,
-  createTable,
-  type Table,
-} from '@tanstack/table-core'
-import { lazyInit } from './lazy-signal-initializer'
-import { proxifyTable } from './proxy'
+import { FlexRenderCell } from './helpers/flexRenderCell'
+import { FlexRenderDirective } from './flexRender'
 
 export * from '@tanstack/table-core'
 
-export {
-  type FlexRenderContent,
-  FlexRenderComponent,
-  FlexRenderDirective,
-  injectFlexRenderContext,
-} from './flex-render'
-
-export function createAngularTable<TData extends RowData>(
-  options: () => TableOptions<TData>
-): Table<TData> & Signal<Table<TData>> {
-  return lazyInit(() => {
-    const resolvedOptions = {
-      state: {},
-      onStateChange: () => {},
-      renderFallbackValue: null,
-      ...options(),
-    }
-
-    const table = createTable(resolvedOptions)
-
-    // By default, manage table state here using the table's initial state
-    const state = signal<TableState>(table.initialState)
-
-    // Compose table options using computed.
-    // This is to allow `tableSignal` to listen and set table option
-    const updatedOptions = computed<TableOptionsResolved<TData>>(() => {
-      // listen to table state changed
-      const tableState = state()
-      // listen to input options changed
-      const tableOptions = options()
-      return {
-        ...table.options,
-        ...resolvedOptions,
-        ...tableOptions,
-        state: { ...tableState, ...tableOptions.state },
-        onStateChange: updater => {
-          const value =
-            updater instanceof Function ? updater(tableState) : updater
-          state.set(value)
-          resolvedOptions.onStateChange?.(updater)
-        },
-      }
-    })
-
-    // convert table instance to signal for proxify to listen to any table state and options changes
-    const tableSignal = computed(
-      () => {
-        table.setOptions(updatedOptions())
-        return table
-      },
-      {
-        equal: () => false,
-      }
-    )
-
-    // proxify Table instance to provide ability for consumer to listen to any table state changes
-    return proxifyTable(tableSignal)
-  })
-}
+export * from './flexRender'
+export * from './injectTable'
+export * from './flex-render/flexRenderComponent'
+
+export * from './helpers/cell'
+export * from './helpers/header'
+export * from './helpers/table'
+export * from './helpers/createTableHook'
+export * from './helpers/flexRenderCell'
+
+/**
+ * Constant helper to import FlexRender directives.
+ *
+ * You should prefer to use this constant over importing the directives separately,
+ * as it ensures you always have the correct set of directives over library updates.
+ *
+ * @see {@link FlexRenderDirective} and {@link FlexRenderCell} for more details on the directives included in this export.
+ */
+export const FlexRender = [FlexRenderDirective, FlexRenderCell] as const
+
+export { shallow } from '@tanstack/angular-store'

package/src/injectTable.ts

@@ -0,0 +1,206 @@
+import {
+  Injector,
+  NgZone,
+  assertInInjectionContext,
+  effect,
+  inject,
+  untracked,
+} from '@angular/core'
+import { constructTable } from '@tanstack/table-core'
+import { lazyInit } from './lazySignalInitializer'
+import { angularReactivity } from './reactivity'
+import type {
+  Atom,
+  ReadonlyAtom,
+  ReadonlyStore,
+  Store,
+} from '@tanstack/angular-store'
+import type {
+  RowData,
+  Table,
+  TableFeatures,
+  TableOptions,
+  TableState,
+} from '@tanstack/table-core'
+
+export type SubscribeSource<TValue> =
+  | Atom<TValue>
+  | ReadonlyAtom<TValue>
+  | Store<TValue>
+  | ReadonlyStore<TValue>
+
+export type AngularTable<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+> = Table<TFeatures, TData> & {
+  /**
+   * @deprecated Prefer `table.atoms.<slice>.get()` for template/render reads
+   * of a specific state slice, `table.state` for full-state debug snapshots, or
+   * Angular computed values around explicit selectors. `table.store.state` is a
+   * current-value snapshot and is easy to misuse in render code.
+   */
+  readonly store: Table<TFeatures, TData>['store']
+  /**
+   * The current table state exposed as a flat proxy. Prefer
+   * `table.atoms.<slice>.get()` when reading a specific slice.
+   */
+  readonly state: Readonly<TableState<TFeatures>>
+}
+
+function createStateProxy<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+>(table: Table<TFeatures, TData>): Readonly<TableState<TFeatures>> {
+  const getSnapshot = () => {
+    const snapshot = {} as TableState<TFeatures>
+    const stateKeys = Object.keys(table.initialState) as Array<
+      keyof TableState<TFeatures>
+    >
+
+    for (const key of stateKeys) {
+      snapshot[key] = table.atoms[key].get()
+    }
+
+    return snapshot
+  }
+
+  const target = {} as TableState<TFeatures>
+
+  return new Proxy(target, {
+    get(target, prop, receiver) {
+      if (prop === 'toJSON') {
+        return getSnapshot
+      }
+
+      if (typeof prop === 'string' && prop in table.initialState) {
+        return table.atoms[prop as keyof TableState<TFeatures>]?.get()
+      }
+
+      return Reflect.get(target, prop, receiver)
+    },
+    has(_, prop) {
+      return typeof prop === 'string' && prop in table.initialState
+    },
+    ownKeys() {
+      return Reflect.ownKeys(table.initialState)
+    },
+    getOwnPropertyDescriptor(_, prop) {
+      if (typeof prop !== 'string' || !(prop in table.initialState)) {
+        return undefined
+      }
+
+      return {
+        enumerable: true,
+        configurable: true,
+      }
+    },
+  })
+}
+
+/**
+ * Creates and returns an Angular-reactive table instance.
+ *
+ * The initializer is intentionally re-evaluated whenever any signal read inside it changes.
+ * This is how the adapter keeps the table in sync with Angular's reactivity model.
+ *
+ * Because of that behavior, keep expensive/static values (for example `columns`, feature setup, row models)
+ * as stable references outside the initializer, and only read reactive state (`data()`, pagination/filter/sorting signals, etc.)
+ * inside it.
+ *
+ * The returned table is also signal-reactive: table state and table APIs are wired for Angular signals, so you can safely consume table methods inside `computed(...)` and `effect(...)`.
+ *
+ * @example
+ * 1. Register the table features you need
+ * ```ts
+ * // Register only the features you need
+ * import {tableFeatures, rowPaginationFeature} from '@tanstack/angular-table';
+ * const _features = tableFeatures({
+ *  rowPaginationFeature,
+ *  // ...all other features you need
+ * })
+ *
+ * // Use all table core features
+ * import {stockFeatures} from '@tanstack/angular-table';
+ * const _features = tableFeatures(stockFeatures);
+ * ```
+ * 2. Prepare the table columns
+ * ```ts
+ * import {ColumnDef} from '@tanstack/angular-table';
+ *
+ * type MyData = {}
+ *
+ * const columns: ColumnDef<typeof _features, MyData>[] = [
+ *   // ...column definitions
+ * ]
+ *
+ * // or using createColumnHelper
+ * import {createColumnHelper} from '@tanstack/angular-table';
+ * const columnHelper = createColumnHelper<typeof _features, MyData>();
+ * const columns = columnHelper.columns([
+ *  columnHelper.accessor(...),
+ *  // ...other columns
+ * ])
+ * ```
+ * 3. Create the table instance with `injectTable`
+ * ```ts
+ * const table = injectTable(() => {
+ *   // ...table options,
+ *   _features,
+ *   columns: columns,
+ *   data: myDataSignal(),
+ * })
+ * ```
+ *
+ * @returns An Angular-reactive TanStack Table instance.
+ */
+export function injectTable<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+>(
+  options: () => TableOptions<TFeatures, TData>,
+): AngularTable<TFeatures, TData> {
+  assertInInjectionContext(injectTable)
+  const injector = inject(Injector)
+  const ngZone = inject(NgZone)
+
+  return ngZone.runOutsideAngular(() =>
+    lazyInit(() => {
+      const table = constructTable({
+        ...options(),
+        _features: {
+          coreReativityFeature: angularReactivity(injector),
+          ...options()._features,
+        },
+      }) as AngularTable<TFeatures, TData>
+      const stateProxy = createStateProxy(table)
+
+      Object.defineProperty(table, 'state', {
+        get() {
+          return stateProxy
+        },
+        configurable: true,
+        enumerable: true,
+      })
+
+      let isMount = true
+      effect(
+        () => {
+          const newOptions = options()
+          if (isMount) {
+            isMount = false
+            return
+          }
+          untracked(() =>
+            table.setOptions((previous) => ({
+              ...previous,
+              ...newOptions,
+            })),
+          )
+        },
+        { injector, debugName: 'tableOptionsUpdate' },
+      )
+
+      return table
+    }),
+  )
+}

package/src/{lazy-signal-initializer.ts → lazySignalInitializer.ts}

@@ -2,7 +2,7 @@ import { untracked } from '@angular/core'
 
 /**
  * Implementation from @tanstack/angular-query
- * {@link https://github.com/TanStack/query/blob/main/packages/angular-query-experimental/src/util/lazy-init/lazy-init.ts}
+ * {https://github.com/TanStack/query/blob/main/packages/angular-query-experimental/src/util/lazy-init/lazy-init.ts}
  */
 export function lazyInit<T extends object>(initializer: () => T): T {
   let object: T | null = null
@@ -18,7 +18,7 @@ export function lazyInit<T extends object>(initializer: () => T): T {
   const table = () => {}
 
   return new Proxy<T>(table as T, {
-    apply(target: T, thisArg: any, argArray: any[]): any {
+    apply(target: T, thisArg: any, argArray: Array<any>): any {
       initializeObject()
       if (typeof object === 'function') {
         return Reflect.apply(object, thisArg, argArray)

package/src/reactivity.ts

@@ -0,0 +1,147 @@
+import {
+  DestroyRef,
+  NgZone,
+  computed,
+  effect,
+  signal,
+  untracked,
+} from '@angular/core'
+import { batch, createAtom } from '@tanstack/angular-store'
+import type { Atom, Observer, ReadonlyAtom } from '@tanstack/angular-store'
+import type {
+  TableAtomOptions,
+  TableReactivityBindings,
+} from '@tanstack/table-core/reactivity'
+import type { Injector, Signal, WritableSignal } from '@angular/core'
+
+const optionsStoreDebugName = 'table/optionsStore'
+
+function observerToCallback<T>(
+  observerOrNext: Observer<T> | ((value: T) => void),
+): (value: T) => void {
+  return typeof observerOrNext === 'function'
+    ? observerOrNext
+    : (value) => observerOrNext.next?.(value)
+}
+
+function signalToReadonlyAtom<T>(
+  source: Signal<T>,
+  getSource: () => T,
+  subscribeSource: (observerOrNext: Observer<T> | ((value: T) => void)) => {
+    unsubscribe: () => void
+  },
+): ReadonlyAtom<T> {
+  return Object.assign(source, {
+    get: () => {
+      const value = getSource()
+      source()
+      return value
+    },
+    subscribe: subscribeSource as ReadonlyAtom<T>['subscribe'],
+  })
+}
+
+function signalToWritableAtom<T>(
+  source: WritableSignal<T>,
+  injector: Injector,
+): Atom<T> {
+  const observers = new Set<(value: T) => void>()
+  let observed = false
+  effect(
+    () => {
+      const value = source()
+      if (!observed) {
+        observed = true
+        return
+      }
+      observers.forEach((observer) => observer(value))
+    },
+    { injector },
+  )
+
+  return Object.assign(source.asReadonly(), {
+    set: (updater: T | ((prevVal: T) => T)) => {
+      typeof updater === 'function'
+        ? source.update(updater as (val: T) => T)
+        : source.set(updater)
+    },
+    get: () => source(),
+    subscribe: ((observerOrNext: Observer<T> | ((value: T) => void)) => {
+      const observer = observerToCallback(observerOrNext)
+      observers.add(observer)
+
+      return {
+        unsubscribe: () => observers.delete(observer),
+      }
+    }) as Atom<T>['subscribe'],
+  })
+}
+
+/**
+ * Creates the table-core reactivity bindings used by the Angular adapter.
+ *
+ * Table state atoms are backed by TanStack Store atoms. The options store stays
+ * framework-native because row-model APIs read `table.options` directly during
+ * render. Readonly table atoms bridge Store dependency tracking into Angular
+ * computed signals.
+ */
+export function angularReactivity(injector: Injector): TableReactivityBindings {
+  const ngZone = injector.get(NgZone)
+  const destroyRef = injector.get(DestroyRef)
+
+  return {
+    createOptionsStore: true,
+    schedule: (fn) => ngZone.runOutsideAngular(() => queueMicrotask(fn)),
+    createReadonlyAtom: <T>(fn: () => T, options?: TableAtomOptions<T>) => {
+      const storeAtom = createAtom(() => fn(), {
+        compare: options?.compare,
+      })
+      const version = signal(0, {
+        equal: () => false,
+      })
+      const subscription = storeAtom.subscribe(() => {
+        version.update((value) => value + 1)
+      })
+      destroyRef.onDestroy(() => subscription.unsubscribe())
+
+      const value = computed(
+        () => {
+          version()
+          return storeAtom.get()
+        },
+        {
+          equal: options?.compare,
+          debugName: options?.debugName,
+        },
+      )
+      return signalToReadonlyAtom(
+        value,
+        () => storeAtom.get(),
+        (observerOrNext) => {
+          const observer = observerToCallback(observerOrNext)
+          return storeAtom.subscribe(() => {
+            observer(storeAtom.get())
+          })
+        },
+      )
+    },
+    createWritableAtom: <T>(
+      value: T,
+      options?: TableAtomOptions<T>,
+    ): Atom<T> => {
+      if (options?.debugName === optionsStoreDebugName) {
+        const writableSignal = signal(value, {
+          equal: options.compare,
+          debugName: options.debugName,
+        })
+        return signalToWritableAtom(writableSignal, injector)
+      }
+
+      return createAtom(value, {
+        compare: options?.compare,
+      })
+    },
+    untrack: untracked,
+    batch,
+  }
+}

package/static-functions/index.ts

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

package/static-functions/ng-package.json

@@ -0,0 +1,6 @@
+{
+  "$schema": "../node_modules/ng-packagr/ng-package.schema.json",
+  "lib": {
+    "entryFile": "index.ts"
+  }
+}