@tanstack/angular-table 9.0.0-alpha.10 → 9.0.0-alpha.12

package/package.json

@@ -1,12 +1,12 @@
 {
   "name": "@tanstack/angular-table",
-  "version": "9.0.0-alpha.10",
+  "version": "9.0.0-alpha.12",
   "description": "Headless UI for building powerful tables & datagrids for Angular.",
   "author": "Tanner Linsley",
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "https://github.com/TanStack/table.git",
+    "url": "git+https://github.com/TanStack/table.git",
     "directory": "packages/angular-table"
   },
   "homepage": "https://tanstack.com/table",
@@ -21,13 +21,11 @@
     "datagrid"
   ],
   "type": "module",
-  "module": "dist/esm2022/index.mjs",
-  "types": "dist/index.d.ts",
+  "module": "dist/fesm2022/tanstack-angular-table.mjs",
+  "types": "dist/types/tanstack-angular-table.d.ts",
   "exports": {
     ".": {
-      "types": "./dist/index.d.ts",
-      "esm": "./dist/esm2022/index.mjs",
-      "esm2022": "./dist/esm2022/index.mjs",
+      "types": "./dist/types/tanstack-angular-table.d.ts",
       "default": "./dist/fesm2022/tanstack-angular-table.mjs"
     },
     "./package.json": {
@@ -35,26 +33,38 @@
     }
   },
   "engines": {
-    "node": ">=12"
+    "node": ">=18"
   },
   "files": [
     "dist",
     "src"
   ],
   "dependencies": {
-    "tslib": "^2.6.3",
-    "@tanstack/table-core": "9.0.0-alpha.10"
+    "@tanstack/angular-store": "^0.9.1",
+    "tslib": "^2.8.1",
+    "@tanstack/table-core": "9.0.0-alpha.12"
   },
   "devDependencies": {
-    "@analogjs/vite-plugin-angular": "^1.5.0",
-    "@angular/core": "^18.0.3",
-    "@angular/platform-browser": "^18.0.3",
-    "@angular/platform-browser-dynamic": "^18.0.3",
-    "ng-packagr": "^18.0.0"
+    "@analogjs/vite-plugin-angular": "^2.2.2",
+    "@analogjs/vitest-angular": "^2.2.2",
+    "@angular/core": "^21.1.1",
+    "@angular/platform-browser": "^21.1.1",
+    "ng-packagr": "^21.1.0",
+    "typescript": "5.9.3"
   },
   "peerDependencies": {
-    "@angular/core": ">=17"
+    "@angular/core": ">=19"
   },
   "sideEffects": false,
-  "scripts": {}
+  "scripts": {
+    "build": "ng-packagr -p ng-package.json -c tsconfig.build.json && rimraf ./dist/package.json",
+    "build:types": "tsc --emitDeclarationOnly",
+    "clean": "rimraf ./build && rimraf ./dist",
+    "test:build": "publint --strict",
+    "test:eslint": "eslint ./src",
+    "test:lib": "vitest",
+    "test:benchmark": "vitest bench",
+    "test:lib:dev": "vitest --watch",
+    "test:types": "tsc && vitest --typecheck"
+  }
 }

package/src/angularReactivityFeature.ts

@@ -0,0 +1,231 @@
+import { computed, signal } from '@angular/core'
+import { setReactivePropertiesOnObject } from './reactivityUtils'
+import type { Signal } from '@angular/core'
+import type {
+  RowData,
+  Table,
+  TableFeature,
+  TableFeatures,
+} from '@tanstack/table-core'
+
+declare module '@tanstack/table-core' {
+  interface TableOptions_Plugins<
+    TFeatures extends TableFeatures,
+    TData extends RowData,
+  > extends TableOptions_AngularReactivity {}
+
+  interface Table_Plugins<
+    TFeatures extends TableFeatures,
+    TData extends RowData,
+  > extends Table_AngularReactivity<TFeatures, TData> {}
+}
+
+/**
+ * Predicate used to skip/ignore a property name when applying Angular reactivity.
+ *
+ * Returning `true` means the property should NOT be wrapped/made reactive.
+ */
+type SkipPropertyFn = (property: string) => boolean
+
+/**
+ * Fine-grained configuration for Angular reactivity.
+ *
+ * Each key controls whether prototype methods/getters on the corresponding TanStack Table
+ * objects are wrapped with signal-aware access.
+ *
+ * - `true` enables wrapping using the default skip rules.
+ * - `false` disables wrapping entirely for that object type.
+ * - a function allows customizing the skip rules (see {@link SkipPropertyFn}).
+ *
+ * @example
+ * ```ts
+ * const table = injectTable(() => {
+ *  // ...table options,
+ *  reactivity: {
+ *    // fine-grained control over which table objects have reactive properties,
+ *    // and which properties are wrapped
+ *    header: true,
+ *    column: true,
+ *    row: true,
+ *    cell: true,
+ *  }
+ * })
+ * ```
+ */
+export interface AngularReactivityFlags {
+  /** Controls reactive wrapping for `Header` instances. */
+  header: boolean | SkipPropertyFn
+  /** Controls reactive wrapping for `Column` instances. */
+  column: boolean | SkipPropertyFn
+  /** Controls reactive wrapping for `Row` instances. */
+  row: boolean | SkipPropertyFn
+  /** Controls reactive wrapping for `Cell` instances. */
+  cell: boolean | SkipPropertyFn
+}
+
+/**
+ * Table option extension for Angular reactivity.
+ *
+ * Available on `createTable` options via module augmentation in this file.
+ */
+interface TableOptions_AngularReactivity {
+  /**
+   * Enables/disables and configures Angular reactivity on table-related prototypes.
+   *
+   * If omitted, defaults are provided by the feature.
+   */
+  reactivity?: Partial<AngularReactivityFlags>
+}
+
+/**
+ * Table API extension for Angular reactivity.
+ *
+ * Added to the table instance via module augmentation.
+ */
+interface Table_AngularReactivity<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+> {
+  /**
+   * Returns a table signal that updates whenever the table state or options changes.
+   */
+  get: Signal<Table<TFeatures, TData>>
+  /**
+   * Sets the reactive notifier that powers {@link get}.
+   *
+   * @internal Used by the Angular table adapter to connect its notifier to the core table.
+   */
+  setTableNotifier: (signal: Signal<Table<TFeatures, TData>>) => void
+}
+
+/**
+ * Type map describing what this feature adds to TanStack Table constructors.
+ */
+interface AngularReactivityFeatureConstructors<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+> {
+  TableOptions: TableOptions_AngularReactivity
+  Table: Table_AngularReactivity<TFeatures, TData>
+}
+
+/**
+ * Resolves the user-provided `reactivity.*` config to a skip predicate.
+ *
+ * - `false` is handled by callers (feature method returns early)
+ * - `true` selects the default predicate
+ * - a function overrides the default predicate
+ */
+const getUserSkipPropertyFn = (
+  value: undefined | null | boolean | SkipPropertyFn,
+  defaultPropertyFn: SkipPropertyFn,
+) => {
+  if (typeof value === 'boolean') {
+    return defaultPropertyFn
+  }
+
+  return value ?? defaultPropertyFn
+}
+
+function constructAngularReactivityFeature<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+>(): TableFeature<AngularReactivityFeatureConstructors<TFeatures, TData>> {
+  return {
+    getDefaultTableOptions(table) {
+      return {
+        reactivity: {
+          header: true,
+          column: true,
+          row: true,
+          cell: true,
+        },
+      }
+    },
+    constructTableAPIs: (table) => {
+      const rootNotifier = signal<Signal<any> | null>(null)
+      table.setTableNotifier = (notifier) => rootNotifier.set(notifier)
+      table.get = computed(() => rootNotifier()!(), { equal: () => false })
+      setReactivePropertiesOnObject(table.get, table, {
+        overridePrototype: false,
+        skipProperty: skipBaseProperties,
+      })
+    },
+
+    assignCellPrototype: (prototype, table) => {
+      if (table.options.reactivity?.cell === false) {
+        return
+      }
+      setReactivePropertiesOnObject(table.get, prototype, {
+        skipProperty: getUserSkipPropertyFn(
+          table.options.reactivity?.cell,
+          skipBaseProperties,
+        ),
+        overridePrototype: true,
+      })
+    },
+
+    assignColumnPrototype: (prototype, table) => {
+      if (table.options.reactivity?.column === false) {
+        return
+      }
+      setReactivePropertiesOnObject(table.get, prototype, {
+        skipProperty: getUserSkipPropertyFn(
+          table.options.reactivity?.cell,
+          skipBaseProperties,
+        ),
+        overridePrototype: true,
+      })
+    },
+
+    assignHeaderPrototype: (prototype, table) => {
+      if (table.options.reactivity?.header === false) {
+        return
+      }
+      setReactivePropertiesOnObject(table.get, prototype, {
+        skipProperty: getUserSkipPropertyFn(
+          table.options.reactivity?.cell,
+          skipBaseProperties,
+        ),
+        overridePrototype: true,
+      })
+    },
+
+    assignRowPrototype: (prototype, table) => {
+      if (table.options.reactivity?.row === false) {
+        return
+      }
+      setReactivePropertiesOnObject(table.get, prototype, {
+        skipProperty: getUserSkipPropertyFn(
+          table.options.reactivity?.cell,
+          skipBaseProperties,
+        ),
+        overridePrototype: true,
+      })
+    },
+  }
+}
+
+/**
+ * Angular reactivity feature that add reactive signal supports in table core instance.
+ * This is used internally by the Angular table adapter `injectTable`.
+ *
+ * @private
+ */
+export const angularReactivityFeature = constructAngularReactivityFeature()
+
+/**
+ * Default predicate used to skip base/non-reactive properties.
+ */
+function skipBaseProperties(property: string): boolean {
+  return (
+    // equals `getContext`
+    property === 'getContext' ||
+    // start with `_`
+    property[0] === '_' ||
+    // doesn't start with `get`, but faster
+    !(property[0] === 'g' && property[1] === 'e' && property[2] === 't') ||
+    // ends with `Handler`
+    property.endsWith('Handler')
+  )
+}

package/src/flex-render/context.ts

@@ -0,0 +1,14 @@
+import { InjectionToken, inject } from '@angular/core'
+
+export const FlexRenderComponentProps = new InjectionToken<
+  NonNullable<unknown>
+>('[@tanstack/angular-table] Flex render component context props')
+
+/**
+ * Inject the flex render context props.
+ *
+ * Can be used in components rendered via FlexRender directives.
+ */
+export function injectFlexRenderContext<T extends NonNullable<unknown>>(): T {
+  return inject<T>(FlexRenderComponentProps)
+}

package/src/flex-render/flags.ts

@@ -0,0 +1,34 @@
+/**
+ * Flags used to manage and optimize the rendering lifecycle of the content of the cell
+ * while using {@link FlexViewRenderer}.
+ */
+export const FlexRenderFlags = {
+  /**
+   * Indicates that the view is being created for the first time or will be cleared during the next update phase.
+   * This is the initial state and will transition after the first ngDoCheck.
+   */
+  ViewFirstRender: 1 << 0,
+  /**
+   * Indicates the `content` property has been modified or the view requires a complete re-render.
+   * When this flag is enabled, the view will be cleared and recreated from scratch.
+   */
+  ContentChanged: 1 << 1,
+  /**
+   * Indicates that the `props` property reference has changed.
+   * When this flag is enabled, the view context is updated based on the type of the content.
+   *
+   * For Component view, inputs will be updated and view will be marked as dirty.
+   * For TemplateRef and primitive values, view will be marked as dirty
+   */
+  PropsReferenceChanged: 1 << 2,
+  /**
+   * Indicates that the current rendered view needs to be checked for changes.
+   * This will be set to true when `content(props)` result has changed or during
+   * forced update
+   */
+  Dirty: 1 << 3,
+  /**
+   * Indicates that the first render effect has been checked at least one time.
+   */
+  RenderEffectChecked: 1 << 4,
+} as const

package/src/flex-render/flexRenderComponent.ts

@@ -0,0 +1,288 @@
+import { reflectComponentType } from '@angular/core'
+import type {
+  Binding,
+  ComponentMirror,
+  Injector,
+  InputSignal,
+  OutputEmitterRef,
+  Type,
+  createComponent,
+} from '@angular/core'
+
+type CreateComponentOptions = Parameters<typeof createComponent>[1]
+type CreateComponentBindings = CreateComponentOptions['bindings']
+type CreateComponentDirectives = CreateComponentOptions['directives']
+
+interface FlexRenderOptions<
+  TInputs extends Record<string, any>,
+  TOutputs extends Record<string, any>,
+> {
+  /**
+   * Native Angular bindings applied at component creation time via `createComponent`.
+   * Use this option to set inputs, outputs, or two-way bindings at creation time.
+   * Shouldn't be used together with {@link FlexRenderOptions#inputs} or {@link FlexRenderOptions#outputs} option.
+   *
+   * Binding input/outputs at creation time: {@link https://angular.dev/guide/components/programmatic-rendering#binding-inputs-outputs-and-setting-host-directives-at-creation}
+   *
+   * Two-way binding: {@link https://angular.dev/api/core/twoWayBinding}
+   *
+   * Output binding: {@link https://angular.dev/api/core/outputBinding}
+   *
+   * Input binding: {@link https://angular.dev/api/core/inputBinding}
+   *
+   * @example
+   * ```ts
+   * import {flexRenderComponent} from '@tanstack/angular-table';
+   * flexRenderComponent(MyComponent, {
+   *   bindings: [
+   *     // Will update `value` input every time `mySignalValue` changes
+   *     inputBinding('value', mySignalValue),
+   *     // Set myProperty to 1 when the component is created
+   *     inputBinding('myProperty', () => 1),
+   *     // Callback called every time `valueChange` output emit
+   *     outputBinding('valueChange', value => {
+   *       console.log("my value changed to", value)
+   *     }),
+   *     // Two-way binding between `value` input and `valueChange` output
+   *     // Useful while using `model` inputs.
+   *     twoWayBinding('value', mySignal)
+   *   ]
+   * })
+   * ```
+   */
+  readonly bindings?: Array<Binding>
+  /**
+   * Directives to apply to the component at creation time.
+   *
+   * Binding directives at creation time: {@link https://angular.dev/guide/components/programmatic-rendering#binding-inputs-outputs-and-setting-host-directives-at-creation}
+   *
+   * Two-way binding: {@link https://angular.dev/api/core/twoWayBinding}
+   *
+   * Output binding: {@link https://angular.dev/api/core/outputBinding}
+   *
+   * Input binding: {@link https://angular.dev/api/core/inputBinding}
+   *
+   * @example
+   * ```ts
+   * import {flexRenderComponent} from '@tanstack/angular-table';
+   * flexRenderComponent(MyComponent, {
+   *   bindings: [
+   *      // ...
+   *   ],
+   *   directives: [
+   *      DirectiveA,
+   *      {
+   *        type: DirectiveB,
+   *        bindings: [
+   *          inputBinding('value', mySignalValue),
+   *          // ...
+   *        ]
+   *      }
+   *   ]
+   * })
+   * ```
+   */
+  readonly directives?: CreateComponentDirectives
+  /**
+   * Component instance inputs.
+   *
+   * These values are assigned after the component has been created using
+   * [componentRef.setInput API](https://angular.dev/api/core/ComponentRef#setInput).
+   *
+   * Shouldn't be used together with {@link FlexRenderOptions#bindings} option
+   */
+  readonly inputs?: TInputs
+  /**
+   * Component instance outputs.
+   *
+   * Outputs are wired imperatively after component creation using {@link OutputEmitterRef#subscribe}.
+   *
+   * Shouldn't be used together with {@link FlexRenderOptions#bindings} option
+   */
+  readonly outputs?: TOutputs
+  /**
+   * Optional {@link Injector} that will be used when rendering the component
+   */
+  readonly injector?: Injector
+}
+
+type Inputs<T> = {
+  [K in keyof T as T[K] extends InputSignal<infer R>
+    ? K
+    : never]?: T[K] extends InputSignal<infer R> ? R : never
+}
+
+type Outputs<T> = {
+  [K in keyof T as T[K] extends OutputEmitterRef<infer R>
+    ? K
+    : never]?: T[K] extends OutputEmitterRef<infer R>
+    ? OutputEmitterRef<R>['emit']
+    : never
+}
+
+/**
+ * Helper function to create a {@link FlexRenderComponent} instance, with better type-safety.
+ *
+ * @example
+ * ```ts
+ * import {flexRenderComponent} from '@tanstack/angular-table'
+ * import {inputBinding, outputBinding} from '@angular/core';
+ *
+ * const columns = [
+ *   {
+ *     cell: ({ row }) => {
+ *        return flexRenderComponent(MyComponent, {
+ *          inputs: { value: mySignalValue() },
+ *          outputs: { valueChange: (val) => {} }
+ *          // or using angular native createComponent#binding api
+ *          bindings: [
+ *            inputBinding('value', mySignalValue),
+ *            outputBinding('valueChange', value => {
+ *              console.log("my value changed to", value)
+ *            })
+ *          ]
+ *        })
+ *     },
+ *   },
+ * ]
+ * ```
+ */
+export function flexRenderComponent<TComponent = any>(
+  component: Type<TComponent>,
+  options?: FlexRenderOptions<Inputs<TComponent>, Outputs<TComponent>>,
+): FlexRenderComponent<TComponent> {
+  const { inputs, injector, outputs, directives, bindings } = options ?? {}
+  return new FlexRenderComponentInstance(
+    component,
+    inputs,
+    injector,
+    outputs,
+    directives,
+    bindings,
+  )
+}
+
+/**
+ * Wrapper interface for a component that will be used as content for {@link FlexRenderDirective}.
+ * Can be created using {@link flexRenderComponent} helper.
+ *
+ * @example
+ *
+ * ```ts
+ * import {flexRenderComponent} from '@tanstack/angular-table'
+ *
+ * // Usage in cell/header/footer definition
+ * const columns = [
+ *   {
+ *     cell: ({ row }) => {
+ *        return flexRenderComponent(MyComponent, {
+ *          inputs: { value: mySignalValue() },
+ *          outputs: { valueChange: (val) => {} }
+ *          // or using angular createComponent#bindings api
+ *          bindings: [
+ *            inputBinding('value', mySignalValue),
+ *            outputBinding('valueChange', value => {
+ *              console.log("my value changed to", value)
+ *            })
+ *          ]
+ *        })
+ *     },
+ *   },
+ * ]
+ *
+ * import {input, output} from '@angular/core';
+ *
+ * @Component({
+ *  selector: 'my-component',
+ * })
+ * class MyComponent {
+ *    readonly value = input(0);
+ *    readonly valueChange = output<number>();
+ * }
+ *
+ * ```
+ */
+export interface FlexRenderComponent<TComponent = any> {
+  /**
+   * The component type
+   */
+  readonly component: Type<TComponent>
+  /**
+   * Reflected metadata about the component.
+   */
+  readonly mirror: ComponentMirror<TComponent>
+  /**
+   * List of allowed input names.
+   */
+  readonly allowedInputNames: Array<string>
+  /**
+   * List of allowed output names.
+   */
+  readonly allowedOutputNames: Array<string>
+  /**
+   * Component instance outputs. Subscribed via {@link OutputEmitterRef#subscribe}
+   *
+   * @see {@link FlexRenderOptions#outputs}
+   */
+  readonly outputs?: Outputs<TComponent>
+  /**
+   * Component instance inputs. Set via [componentRef.setInput API](https://angular.dev/api/core/ComponentRef#setInput))
+   *
+   * @see {@link FlexRenderOptions#inputs}
+   */
+  readonly inputs?: Inputs<TComponent>
+  /**
+   * Optional {@link Injector} that will be used when rendering the component.
+   *
+   * @see {@link FlexRenderOptions#injector}
+   */
+  readonly injector?: Injector
+  /**
+   * Bindings to apply to the root component
+   *
+   * @see {@link FlexRenderOptions#bindings}
+   */
+  bindings?: CreateComponentBindings
+  /**
+   * Directives that should be applied to the component.
+   *
+   * @see {FlexRenderOptions#directives}
+   */
+  directives?: CreateComponentDirectives
+}
+
+/**
+ * Wrapper class for a component that will be used as content for {@link FlexRenderDirective}
+ *
+ * Prefer {@link flexRenderComponent} helper for better type-safety
+ */
+export class FlexRenderComponentInstance<
+  TComponent = any,
+> implements FlexRenderComponent<TComponent> {
+  readonly mirror: ComponentMirror<TComponent>
+  readonly allowedInputNames: Array<string> = []
+  readonly allowedOutputNames: Array<string> = []
+
+  constructor(
+    readonly component: Type<TComponent>,
+    readonly inputs?: Inputs<TComponent>,
+    readonly injector?: Injector,
+    readonly outputs?: Outputs<TComponent>,
+    readonly directives?: CreateComponentDirectives,
+    readonly bindings?: CreateComponentBindings,
+  ) {
+    const mirror = reflectComponentType(component)
+    if (!mirror) {
+      throw new Error(
+        `[@tanstack-table/angular] The provided symbol is not a component`,
+      )
+    }
+    this.mirror = mirror
+    for (const input of this.mirror.inputs) {
+      this.allowedInputNames.push(input.propName)
+    }
+    for (const output of this.mirror.outputs) {
+      this.allowedOutputNames.push(output.propName)
+    }
+  }
+}