@tanstack/angular-table 9.0.0-alpha.4 → 9.0.0-alpha.42

package/src/helpers/flexRenderCell.ts

@@ -0,0 +1,136 @@
+import {
+  DestroyRef,
+  Directive,
+  Injector,
+  TemplateRef,
+  ViewContainerRef,
+  computed,
+  inject,
+  input,
+} from '@angular/core'
+import {
+  Cell,
+  CellData,
+  Header,
+  RowData,
+  TableFeatures,
+} from '@tanstack/table-core'
+import { FlexViewRenderer } from '../flex-render/renderer'
+import type { FlexRenderInputContent } from '../flex-render/renderer'
+import type { CellContext, HeaderContext } from '@tanstack/table-core'
+
+/**
+ * Simplified directive wrapper of `*flexRender`.
+ *
+ * Use this utility component to render headers, cells, or footers with custom markup.
+ *
+ * Only one prop (`cell`, `header`, or `footer`) may be passed based on the used selector.
+ *
+ * @example
+ * ```html
+ * <td *flexRenderCell="cell; let cell">{{cell}}</td>
+ * <th *flexRenderHeader="header; let header">{{header}}</th>
+ * <th *flexRenderFooter="footer; let footer">{{footer}}</th>
+ * ```
+ *
+ * This replaces calling `*flexRender` directly like this:
+ * ```html
+ * <td *flexRender="cell.column.columnDef.cell; props: cell.getContext(); let cell">{{cell}}</td>
+ * <td *flexRender="header.column.columnDef.header; props: header.getContext(); let header">{{header}}</td>
+ * <td *flexRender="footer.column.columnDef.footer; props: footer.getContext(); let footer">{{footer}}</td>
+ * ```
+ *
+ * Can be imported through {@link FlexRenderCell} or {@link FlexRender} import,
+ * which the latter is preferred.
+ *
+ * @example
+ * ```ts
+ * import {FlexRender} from '@tanstack/angular-table
+ *
+ * @Component({
+ *  // ...
+ *  imports: [
+ *    FlexRender
+ *  ]
+ * })
+ * ```
+ */
+@Directive({
+  selector:
+    'ng-template[flexRenderCell], ng-template[flexRenderFooter], ng-template[flexRenderHeader]',
+})
+export class FlexRenderCell<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+  TValue extends CellData,
+> {
+  readonly cell = input<Cell<TFeatures, TData, TValue>>(undefined, {
+    alias: 'flexRenderCell',
+  })
+
+  readonly header = input<Header<TFeatures, TData, TValue>>(undefined, {
+    alias: 'flexRenderHeader',
+  })
+
+  readonly footer = input<Header<TFeatures, TData, TValue>>(undefined, {
+    alias: 'flexRenderFooter',
+  })
+
+  readonly #renderData = computed<
+    | [
+        content: FlexRenderInputContent<CellContext<TFeatures, TData, TValue>>,
+        props: CellContext<TFeatures, TData, TValue>,
+      ]
+    | [
+        content: FlexRenderInputContent<
+          HeaderContext<TFeatures, TData, TValue>
+        >,
+        props: HeaderContext<TFeatures, TData, TValue>,
+      ]
+    | [content: null, props: null]
+  >(
+    () => {
+      const cell = this.cell()
+      const header = this.header()
+      const footer = this.footer()
+      if (cell) {
+        return [cell.column.columnDef.cell, cell.getContext()]
+      }
+      if (header) {
+        return [header.column.columnDef.header, header.getContext()]
+      }
+      if (footer) {
+        return [footer.column.columnDef.footer, footer.getContext()]
+      }
+      return [null, null]
+    },
+    {
+      equal: (a, b) => {
+        return a[0] === b[0] && a[1] === b[1]
+      },
+    },
+  )
+
+  readonly #injector = inject(Injector)
+  readonly #templateRef = inject(TemplateRef)
+  readonly #viewContainerRef = inject(ViewContainerRef)
+
+  constructor() {
+    const content = computed(() => this.#renderData()[0])
+    const props = computed(() => this.#renderData()[1])
+
+    const renderer = new FlexViewRenderer<TFeatures, TData, TValue, any>({
+      content: content,
+      props: props,
+      injector: () => this.#injector,
+      templateRef: this.#templateRef,
+      viewContainerRef: this.#viewContainerRef,
+    })
+
+    renderer.mount()
+
+    inject(DestroyRef).onDestroy(() => {
+      renderer.destroy()
+    })
+  }
+}

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,87 @@
+import { Directive, InjectionToken, inject, input } from '@angular/core'
+import { RowData, TableFeatures, TableState } 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,
+  TSelected extends {} = TableState<TFeatures>,
+> {
+  /**
+   * 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, TSelected>>({
+    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,
+  TSelected extends {} = TableState<TFeatures>,
+>(): Signal<AngularTable<TFeatures, TData, TSelected>> {
+  return inject(TanStackTableToken)
+}

package/src/index.ts

@@ -1,73 +1,24 @@
-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

package/src/injectTable.ts

@@ -0,0 +1,189 @@
+import {
+  Injector,
+  assertInInjectionContext,
+  computed,
+  effect,
+  inject,
+  untracked,
+} from '@angular/core'
+import { constructTable } from '@tanstack/table-core'
+import { lazyInit } from './lazySignalInitializer'
+import { angularReactivity } from './reactivity'
+import type { Atom, ReadonlyAtom } from '@tanstack/angular-store'
+import type {
+  RowData,
+  Table,
+  TableFeatures,
+  TableOptions,
+  TableState,
+} from '@tanstack/table-core'
+import type { Signal, ValueEqualityFn } from '@angular/core'
+
+/**
+ * Store mode: pass `selector` (required) to project from full table state.
+ * Source mode: pass `source` (atom or store); omit `selector` for the whole value
+ * (identity), or pass `selector` to project. Split overloads match React `Subscribe`
+ * inference.
+ */
+export interface AngularTableComputed<TFeatures extends TableFeatures> {
+  <TSourceValue>(props: {
+    source: Atom<TSourceValue> | ReadonlyAtom<TSourceValue>
+    selector?: undefined
+    equal?: ValueEqualityFn<TSourceValue>
+  }): Signal<Readonly<TSourceValue>>
+  <TSourceValue, TSubSelected>(props: {
+    source: Atom<TSourceValue> | ReadonlyAtom<TSourceValue>
+    selector: (state: TSourceValue) => TSubSelected
+    equal?: ValueEqualityFn<TSubSelected>
+  }): Signal<Readonly<TSubSelected>>
+  <TSubSelected>(props: {
+    selector: (state: TableState<TFeatures>) => TSubSelected
+    equal?: ValueEqualityFn<TSubSelected>
+  }): Signal<Readonly<TSubSelected>>
+}
+
+export type AngularTable<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+  TSelected = TableState<TFeatures>,
+> = Table<TFeatures, TData> & {
+  /**
+   * The selected state from the table store, based on the selector provided.
+   */
+  readonly state: Signal<Readonly<TSelected>>
+  /**
+   * A signal that returns the entire table instance. Will update on table/options change.
+   */
+  readonly value: Signal<AngularTable<TFeatures, TData, TSelected>>
+  /**
+   * Creates a computed that subscribe to changes in the table store with a custom selector.
+   * Default equality function is "shallow".
+   */
+  computed: <TSubSelected = {}>(props: {
+    selector: (state: TableState<TFeatures>) => TSubSelected
+    equal?: ValueEqualityFn<TSubSelected>
+  }) => Signal<Readonly<TSubSelected>>
+}
+
+/**
+ * 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,
+  TSelected = TableState<TFeatures>,
+>(
+  options: () => TableOptions<TFeatures, TData>,
+  selector: (state: TableState<TFeatures>) => TSelected = (state) =>
+    state as TSelected,
+): AngularTable<TFeatures, TData, TSelected> {
+  assertInInjectionContext(injectTable)
+  const injector = inject(Injector)
+
+  return lazyInit(() => {
+    const table = constructTable({
+      ...options(),
+      _features: {
+        coreReativityFeature: angularReactivity(injector),
+        ...options()._features,
+      },
+    }) as AngularTable<TFeatures, TData, TSelected>
+
+    let isMount = true
+    effect(
+      () => {
+        const newOptions = options()
+        if (isMount) {
+          isMount = false
+          return
+        }
+        untracked(() =>
+          table.setOptions((previous) => ({
+            ...previous,
+            ...newOptions,
+          })),
+        )
+      },
+      { injector, debugName: 'tableOptionsUpdate' },
+    )
+
+    table.computed = function Subscribe<TSubSelected = {}>(props: {
+      selector: (state: TableState<TFeatures>) => TSubSelected
+      equal?: ValueEqualityFn<TSubSelected>
+    }) {
+      return computed(() => props.selector(table.store.get()), {
+        equal: props.equal,
+      })
+    }
+
+    Object.defineProperty(table, 'state', {
+      value: computed(() => selector(table.store.get())),
+    })
+
+    Object.defineProperty(table, 'value', {
+      value: computed(
+        () => {
+          table.store.get()
+          table.optionsStore.get()
+          return table
+        },
+        { equal: () => false },
+      ),
+    })
+
+    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,65 @@
+import { computed, signal, untracked } from '@angular/core'
+import { toObservable } from '@angular/core/rxjs-interop'
+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'
+
+function signalToReadonlyAtom<T>(
+  signal: Signal<T>,
+  injector: Injector,
+): ReadonlyAtom<T> {
+  return Object.assign(signal, {
+    get: () => signal(),
+    subscribe: (observer: Observer<T>) => {
+      return toObservable(computed(signal), { injector: injector }).subscribe(
+        observer,
+      )
+    },
+  })
+}
+
+function signalToWritableAtom<T>(
+  signal: WritableSignal<T>,
+  injector: Injector,
+): Atom<T> {
+  return Object.assign(signal.asReadonly(), {
+    set: (updater: T | ((prevVal: T) => T)) => {
+      typeof updater === 'function'
+        ? signal.update(updater as (val: T) => T)
+        : signal.set(updater)
+    },
+    get: () => signal(),
+    subscribe: (observer: Observer<T>) => {
+      return toObservable(computed(signal), { injector: injector }).subscribe(
+        observer,
+      )
+    },
+  })
+}
+
+export function angularReactivity(injector: Injector): TableReactivityBindings {
+  return {
+    createReadonlyAtom: <T>(fn: () => T, options?: TableAtomOptions<T>) => {
+      const signal = computed(() => fn(), {
+        equal: options?.compare,
+        debugName: options?.debugName,
+      })
+      return signalToReadonlyAtom(signal, injector)
+    },
+    createWritableAtom: <T>(
+      value: T,
+      options?: TableAtomOptions<T>,
+    ): Atom<T> => {
+      const writableSignal = signal(value, {
+        equal: options?.compare,
+        debugName: options?.debugName,
+      })
+      return signalToWritableAtom(writableSignal, injector)
+    },
+    untrack: untracked,
+    batch: (fn) => fn(),
+  }
+}

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"
+  }
+}