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

package/package.json

@@ -1,12 +1,12 @@
 {
   "name": "@tanstack/angular-table",
-  "version": "9.0.0-alpha.4",
+  "version": "9.0.0-alpha.41",
   "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,19 @@
     "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"
+    },
+    "./static-functions": {
+      "types": "./dist/types/tanstack-angular-table-static-functions.d.ts",
+      "default": "./dist/fesm2022/tanstack-angular-table-static-functions.mjs"
+    },
+    "./flex-render": {
+      "types": "./dist/types/tanstack-angular-table.d.ts",
       "default": "./dist/fesm2022/tanstack-angular-table.mjs"
     },
     "./package.json": {
@@ -35,26 +41,39 @@
     }
   },
   "engines": {
-    "node": ">=12"
+    "node": ">=18"
   },
   "files": [
     "dist",
-    "src"
+    "src",
+    "static-functions"
   ],
   "dependencies": {
-    "tslib": "^2.6.2",
-    "@tanstack/table-core": "9.0.0-alpha.4"
+    "@tanstack/angular-store": "^0.11.0",
+    "tslib": "^2.8.1",
+    "@tanstack/table-core": "9.0.0-alpha.41"
   },
   "devDependencies": {
-    "@analogjs/vite-plugin-angular": "^1.3.1",
-    "@angular/core": "^17.3.9",
-    "@angular/platform-browser": "^17.3.9",
-    "@angular/platform-browser-dynamic": "^17.3.9",
-    "ng-packagr": "^17.3.0"
+    "@analogjs/vite-plugin-angular": "^2.5.0",
+    "@analogjs/vitest-angular": "^2.5.0",
+    "@angular/core": "^21.2.11",
+    "@angular/platform-browser": "^21.2.11",
+    "ng-packagr": "^21.2.3",
+    "typescript": "6.0.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/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)
+    }
+  }
+}

package/src/flex-render/flexRenderComponentFactory.ts

@@ -0,0 +1,241 @@
+import {
+  ChangeDetectorRef,
+  ComponentRef,
+  Injectable,
+  Injector,
+  KeyValueDiffer,
+  KeyValueDiffers,
+  OutputEmitterRef,
+  OutputRefSubscription,
+  ViewContainerRef,
+} from '@angular/core'
+import { FlexRenderComponent } from './flexRenderComponent'
+
+@Injectable()
+export class FlexRenderComponentFactory {
+  readonly #viewContainerRef: ViewContainerRef
+
+  constructor(viewContainerRef: ViewContainerRef) {
+    this.#viewContainerRef = viewContainerRef
+  }
+
+  createComponent<T>(
+    flexRenderComponent: FlexRenderComponent<T>,
+    componentInjector: Injector,
+  ): FlexRenderComponentRef<T> {
+    const componentRef = this.#viewContainerRef.createComponent(
+      flexRenderComponent.component,
+      {
+        injector: componentInjector,
+        directives: flexRenderComponent.directives,
+        bindings: flexRenderComponent.bindings ?? [],
+      },
+    )
+    const view = new FlexRenderComponentRef(
+      componentRef,
+      flexRenderComponent,
+      componentInjector,
+    )
+
+    const { inputs, outputs } = flexRenderComponent
+
+    if (inputs) view.setInputs(inputs)
+    if (outputs) view.setOutputs(outputs)
+
+    return view
+  }
+}
+
+export class FlexRenderComponentRef<T> {
+  readonly #keyValueDiffersFactory: KeyValueDiffers
+  #componentData: FlexRenderComponent<T>
+  #inputValueDiffer: KeyValueDiffer<string, unknown>
+
+  readonly #outputRegistry: FlexRenderComponentOutputManager
+
+  constructor(
+    readonly componentRef: ComponentRef<T>,
+    componentData: FlexRenderComponent<T>,
+    readonly componentInjector: Injector,
+  ) {
+    this.#componentData = componentData
+    this.#keyValueDiffersFactory = componentInjector.get(KeyValueDiffers)
+
+    this.#outputRegistry = new FlexRenderComponentOutputManager(
+      this.#keyValueDiffersFactory,
+      this.outputs,
+    )
+
+    this.#inputValueDiffer = this.#keyValueDiffersFactory
+      .find(this.inputs)
+      .create()
+    this.#inputValueDiffer.diff(this.inputs)
+
+    this.componentRef.onDestroy(() => this.#outputRegistry.unsubscribeAll())
+  }
+
+  get component() {
+    return this.#componentData.component
+  }
+
+  get inputs() {
+    return this.#componentData.inputs ?? {}
+  }
+
+  get outputs() {
+    return this.#componentData.outputs ?? {}
+  }
+
+  /**
+   * Get component input and output diff by the given item
+   */
+  diff(item: FlexRenderComponent<T>) {
+    return {
+      inputDiff: this.#inputValueDiffer.diff(item.inputs ?? {}),
+      outputDiff: this.#outputRegistry.diff(item.outputs ?? {}),
+    }
+  }
+  /**
+   *
+   * @param compare Whether the current ref component instance is the same as the given one
+   */
+  eqType(compare: FlexRenderComponent<T>): boolean {
+    return compare.component === this.component
+  }
+
+  /**
+   * Tries to update current component refs input by the new given content component.
+   */
+  update(content: FlexRenderComponent<T>) {
+    const eq = this.eqType(content)
+    if (!eq) return
+    const { inputDiff, outputDiff } = this.diff(content)
+    if (inputDiff) {
+      inputDiff.forEachAddedItem((item) =>
+        this.setInput(item.key, item.currentValue),
+      )
+      inputDiff.forEachChangedItem((item) =>
+        this.setInput(item.key, item.currentValue),
+      )
+      inputDiff.forEachRemovedItem((item) => this.setInput(item.key, undefined))
+    }
+    if (outputDiff) {
+      outputDiff.forEachAddedItem((item) => {
+        this.setOutput(item.key, item.currentValue)
+      })
+      outputDiff.forEachChangedItem((item) => {
+        if (item.currentValue) {
+          this.#outputRegistry.setListener(item.key, item.currentValue)
+        } else {
+          this.#outputRegistry.unsubscribe(item.key)
+        }
+      })
+      outputDiff.forEachRemovedItem((item) => {
+        this.#outputRegistry.unsubscribe(item.key)
+      })
+    }
+
+    this.#componentData = content
+  }
+
+  markAsDirty(): void {
+    this.componentRef.injector.get(ChangeDetectorRef).markForCheck()
+  }
+
+  setInputs(inputs: Record<string, unknown>) {
+    for (const prop in inputs) {
+      this.setInput(prop, inputs[prop])
+    }
+  }
+
+  setInput(key: string, value: unknown) {
+    if (this.#componentData.allowedInputNames.includes(key)) {
+      this.componentRef.setInput(key, value)
+    }
+  }
+
+  setOutputs(
+    outputs: Record<
+      string,
+      OutputEmitterRef<unknown>['emit'] | null | undefined
+    >,
+  ) {
+    this.#outputRegistry.unsubscribeAll()
+    for (const prop in outputs) {
+      this.setOutput(prop, outputs[prop])
+    }
+  }
+
+  setOutput(
+    outputName: string,
+    emit: OutputEmitterRef<unknown>['emit'] | undefined | null,
+  ): void {
+    if (!this.#componentData.allowedOutputNames.includes(outputName)) return
+    if (!emit) {
+      this.#outputRegistry.unsubscribe(outputName)
+      return
+    }
+
+    const hasListener = this.#outputRegistry.hasListener(outputName)
+    this.#outputRegistry.setListener(outputName, emit)
+
+    if (hasListener) {
+      return
+    }
+
+    const instance = this.componentRef.instance
+    const output = instance[outputName as keyof typeof instance]
+    if (output && output instanceof OutputEmitterRef) {
+      output.subscribe((value) => {
+        this.#outputRegistry.getListener(outputName)?.(value)
+      })
+    }
+  }
+}
+
+class FlexRenderComponentOutputManager {
+  readonly #outputSubscribers: Record<string, OutputRefSubscription> = {}
+  readonly #outputListeners: Record<string, (...args: Array<any>) => void> = {}
+
+  readonly #valueDiffer: KeyValueDiffer<
+    string,
+    undefined | null | OutputEmitterRef<unknown>['emit']
+  >
+
+  constructor(keyValueDiffers: KeyValueDiffers, initialOutputs: any) {
+    this.#valueDiffer = keyValueDiffers.find(initialOutputs).create()
+    if (initialOutputs) {
+      this.#valueDiffer.diff(initialOutputs)
+    }
+  }
+
+  hasListener(outputName: string) {
+    return outputName in this.#outputListeners
+  }
+
+  setListener(outputName: string, callback: (...args: Array<any>) => void) {
+    this.#outputListeners[outputName] = callback
+  }
+
+  getListener(outputName: string) {
+    return this.#outputListeners[outputName]
+  }
+
+  unsubscribeAll(): void {
+    for (const prop in this.#outputSubscribers) {
+      this.unsubscribe(prop)
+    }
+  }
+
+  unsubscribe(outputName: string) {
+    if (outputName in this.#outputSubscribers) {
+      this.#outputSubscribers[outputName]?.unsubscribe()
+      delete this.#outputSubscribers[outputName]
+      delete this.#outputListeners[outputName]
+    }
+  }
+
+  diff(outputs: Record<string, OutputEmitterRef<unknown>['emit'] | undefined>) {
+    return this.#valueDiffer.diff(outputs)
+  }
+}