feat(angular): add support to bindings and directives in FlexRender (#6152)

* feat(angular): add support for `bindings` and `directives` in flexRender via createComponent

Author: riccardoperra

packages/angular-table/src/flex-render/flexRenderComponent.ts

@@ -1,48 +1,109 @@
 import { reflectComponentType } from '@angular/core'
 import type {
+  Binding,
   ComponentMirror,
   Injector,
   InputSignal,
   OutputEmitterRef,
   Type,
+  createComponent,
 } from '@angular/core'
 
-interface FlexRenderRequiredInputOptions<
+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>,
 > {
   /**
-   * Component instance inputs.
-   * They will be set via [componentRef.setInput API](https://angular.dev/api/core/ComponentRef#setInput)
+   * 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)
+   *   ]
+   * })
+   * ```
    */
-  inputs: TInputs
+  readonly bindings?: Array<Binding>
   /**
-   * Component instance outputs.
+   * 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),
+   *          // ...
+   *        ]
+   *      }
+   *   ]
+   * })
+   * ```
    */
-  outputs?: TOutputs
-  /**
-   * Optional {@link Injector} that will be used when rendering the component
-   */
-  injector?: Injector
-}
-
-interface FlexRenderOptions<
-  TInputs extends Record<string, any>,
-  TOutputs extends Record<string, any>,
-> {
+  readonly directives?: CreateComponentDirectives
   /**
    * Component instance inputs.
-   * They will be set via [componentRef.setInput API](https://angular.dev/api/core/ComponentRef#setInput)
+   *
+   * 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
    */
-  inputs?: TInputs
+  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
    */
-  outputs?: TOutputs
+  readonly outputs?: TOutputs
   /**
    * Optional {@link Injector} that will be used when rendering the component
    */
-  injector?: Injector
+  readonly injector?: Injector
 }
 
 type Inputs<T> = {
@@ -59,41 +120,145 @@ type Outputs<T> = {
     : never
 }
 
-type OptionalKeys<T, K = keyof T> = K extends keyof T
-  ? T[K] extends Required<T>[K]
-    ? undefined extends T[K]
-      ? K
-      : never
-    : K
-  : never
-
 /**
- * Helper function to create a [@link FlexRenderComponent] instance, with better type-safety.
+ * 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';
  *
- * - options object must be passed when the given component instance contains at least one required signal input.
- * - options/inputs is typed with the given component inputs
- * - options/outputs is typed with the given component outputs
+ * 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,
-  TInputs extends Inputs<TComponent> = Inputs<TComponent>,
-  TOutputs extends Outputs<TComponent> = Outputs<TComponent>,
->(
+export function flexRenderComponent<TComponent = any>(
   component: Type<TComponent>,
-  ...options: OptionalKeys<TInputs> extends never
-    ? [FlexRenderOptions<TInputs, TOutputs>?]
-    : [FlexRenderRequiredInputOptions<TInputs, TOutputs>]
+  options?: FlexRenderOptions<Inputs<TComponent>, Outputs<TComponent>>,
 ): FlexRenderComponent<TComponent> {
-  const { inputs, injector, outputs } = options[0] ?? {}
-  return new FlexRenderComponent(component, inputs, injector, outputs)
+  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 FlexRenderComponent<TComponent = any> {
+export class FlexRenderComponentInstance<
+  TComponent = any,
+> implements FlexRenderComponent<TComponent> {
   readonly mirror: ComponentMirror<TComponent>
   readonly allowedInputNames: Array<string> = []
   readonly allowedOutputNames: Array<string> = []
@@ -103,6 +268,8 @@ export class FlexRenderComponent<TComponent = any> {
     readonly inputs?: Inputs<TComponent>,
     readonly injector?: Injector,
     readonly outputs?: Outputs<TComponent>,
+    readonly directives?: CreateComponentDirectives,
+    readonly bindings?: CreateComponentBindings,
   ) {
     const mirror = reflectComponentType(component)
     if (!mirror) {

packages/angular-table/src/flex-render/flexRenderComponentFactory.ts

@@ -25,7 +25,11 @@ export class FlexRenderComponentFactory {
   ): FlexRenderComponentRef<T> {
     const componentRef = this.#viewContainerRef.createComponent(
       flexRenderComponent.component,
-      { injector: componentInjector },
+      {
+        injector: componentInjector,
+        directives: flexRenderComponent.directives,
+        bindings: flexRenderComponent.bindings ?? [],
+      },
     )
     const view = new FlexRenderComponentRef(
       componentRef,

packages/angular-table/src/flex-render/view.ts

@@ -1,5 +1,6 @@
 import { TemplateRef, Type } from '@angular/core'
-import { FlexRenderComponent } from './flexRenderComponent'
+import { FlexRenderComponentInstance } from './flexRenderComponent'
+import type { FlexRenderComponent } from './flexRenderComponent'
 import type { FlexRenderContent } from './renderer'
 import type { EmbeddedViewRef } from '@angular/core'
 import type { FlexRenderComponentRef } from './flexRenderComponentFactory'
@@ -23,7 +24,7 @@ export function mapToFlexRenderTypedContent(
   if (typeof content === 'string' || typeof content === 'number') {
     return { kind: 'primitive', content }
   }
-  if (content instanceof FlexRenderComponent) {
+  if (content instanceof FlexRenderComponentInstance) {
     return { kind: 'flexRenderComponent', content }
   } else if (content instanceof TemplateRef) {
     return { kind: 'templateRef', content }

packages/angular-table/src/flexRender.ts

@@ -80,7 +80,6 @@ export type {
  */
 @Directive({
   selector: 'ng-template[flexRender]',
-  standalone: true,
 })
 export class FlexRenderDirective<
   TFeatures extends TableFeatures,

packages/angular-table/src/index.ts

@@ -6,7 +6,7 @@ export * from '@tanstack/table-core'
 export * from './angularReactivityFeature'
 export * from './flexRender'
 export * from './injectTable'
-export { flexRenderComponent } from './flex-render/flexRenderComponent'
+export * from './flex-render/flexRenderComponent'
 
 export * from './helpers/cell'
 export * from './helpers/header'

packages/angular-table/tests/flex-render/flex-render-component.test-d.ts

@@ -13,15 +13,3 @@ test('Infer component inputs', () => {
   // Input is optional so we can skip passing the property
   flexRenderComponent(Test, { inputs: {} })
 })
-
-test('Options are mandatory when given component has required inputs', () => {
-  class Test {
-    readonly input1 = input<string>()
-    readonly requiredInput1 = input.required<string>()
-  }
-
-  // @ts-expect-error Required input
-  flexRenderComponent(Test)
-
-  flexRenderComponent(Test, { inputs: { requiredInput1: 'My value' } })
-})