refactor(compiler): support matching template elements to foreign components

leonsenft · leonsenft · commit ef66ea27bb69 · 2026-05-11T14:51:51.000-07:00
We extract the identifier name from the `foreignImports` expression in
`ComponentDecoratorHandler` and use a `SelectorlessMatcher` to match element
tags against these names during template binding in `R3TargetBinder`. If an
element matches both a regular Angular directive and a foreign component, a
conflict error is thrown.
diff --git a/packages/compiler-cli/src/ngtsc/annotations/component/src/handler.ts b/packages/compiler-cli/src/ngtsc/annotations/component/src/handler.ts
@@ -45,6 +45,7 @@ import {
   SelectorlessMatcher,
   MatchSource,
   TypeCheckId,
+  ForeignComponentMeta,
 } from '@angular/compiler';
 import ts from 'typescript';
 
@@ -1778,8 +1779,22 @@ export class ComponentDecoratorHandler implements DecoratorHandler<
       }
     }
 
+    // Extract foreign component names and create a matcher.
+    let foreignMatcher: SelectorlessMatcher<ForeignComponentMeta> | null = null;
+    if (analysis.resolvedForeignImports !== null && analysis.resolvedForeignImports.length > 0) {
+      const registry = new Map<string, ForeignComponentMeta[]>();
+      for (const ref of analysis.resolvedForeignImports) {
+        const name = ref.node.name.getText();
+        registry.set(name, [{name, ref}]);
+      }
+      foreignMatcher = new SelectorlessMatcher(registry);
+    }
+
     // Set up the R3TargetBinder.
-    const binder = new R3TargetBinder(createMatcherFromScope(scope, this.hostDirectivesResolver));
+    const binder = new R3TargetBinder(
+      createMatcherFromScope(scope, this.hostDirectivesResolver),
+      foreignMatcher,
+    );
     let allDependencies = dependencies;
     let deferBlockBinder = binder;
 
diff --git a/packages/compiler-cli/src/ngtsc/annotations/component/test/component_spec.ts b/packages/compiler-cli/src/ngtsc/annotations/component/test/component_spec.ts
@@ -1085,6 +1085,52 @@ runInEachFileSystem(() => {
         expect((analysis?.resolvedForeignImports![0].node as any).name.text).toBe('FancyButton');
       });
 
+      it('should match template elements to foreign components', () => {
+        const {program, options, host} = makeProgram([
+          {
+            name: _('/node_modules/@angular/core/index.d.ts'),
+            contents: `
+              export const Component: any;
+              export type ForeignComponent<T> = T & { ɵrender: () => void };
+            `,
+          },
+          {
+            name: _('/entry.ts'),
+            contents: `
+              import {Component, ForeignComponent} from '@angular/core';
+
+              function FancyButton() {}
+
+              function foreignImport<T>(type: T): ForeignComponent<T> {
+                return type as any;
+              }
+
+              @Component({
+                selector: 'main',
+                template: '<FancyButton></FancyButton>',
+                foreignImports: [foreignImport(FancyButton)],
+                standalone: true,
+              }) class TestCmp {}
+            `,
+          },
+        ]);
+        const {reflectionHost, handler} = setup(program, options, host);
+        const TestCmp = getDeclaration(program, _('/entry.ts'), 'TestCmp', isNamedClassDeclaration);
+        const detected = handler.detect(
+          TestCmp,
+          reflectionHost.getDecoratorsOfDeclaration(TestCmp),
+        );
+        if (detected === undefined) {
+          return fail('Failed to recognize @Component');
+        }
+        const {analysis} = handler.analyze(TestCmp, detected.metadata);
+        handler.register(TestCmp, analysis!);
+
+        const symbol = handler.symbol(TestCmp, analysis!);
+        const result = handler.resolve(TestCmp, analysis!, symbol);
+        expect(result.data).toBeDefined();
+      });
+
       it('should produce diagnostic for imports in non-standalone component', () => {
         const {program, options, host} = makeProgram(
           [
diff --git a/packages/compiler-cli/src/ngtsc/typecheck/src/tcb_adapter.ts b/packages/compiler-cli/src/ngtsc/typecheck/src/tcb_adapter.ts
@@ -152,6 +152,8 @@ export function adaptTypeCheckBlockMetadata(
       const dirs = meta.boundTarget.getDirectivesOfNode(node);
       return dirs ? dirs.map(convertDir) : null;
     },
+    getForeignComponentOfNode: (node) => meta.boundTarget.getForeignComponentOfNode(node),
+    getMatchedForeignComponents: () => meta.boundTarget.getMatchedForeignComponents(),
     getReferenceTarget: (ref) => {
       const target = meta.boundTarget.getReferenceTarget(ref);
       if (target && 'directive' in target) {
diff --git a/packages/compiler/src/render3/view/t2_api.ts b/packages/compiler/src/render3/view/t2_api.ts
@@ -172,6 +172,22 @@ export interface DirectiveMeta {
   matchSource: MatchSource;
 }
 
+/**
+ * Metadata regarding a foreign component that's needed to match it against template elements.
+ */
+export interface ForeignComponentMeta {
+  /**
+   * Name of the foreign component (used for matching and debugging).
+   */
+  name: string;
+
+  /** Reference to the foreign component declaration site. */
+  ref: {
+    /** Key that uniquely identifies the reference. */
+    key: string;
+  };
+}
+
 /**
  * Possible ways that a directive can be matched.
  */
@@ -213,6 +229,17 @@ export interface BoundTarget<DirectiveT extends DirectiveMeta> {
    */
   getDirectivesOfNode(node: DirectiveOwner): DirectiveT[] | null;
 
+  /**
+   * For a given template node (usually an `Element`), get the foreign component that matched
+   * the node, if any.
+   */
+  getForeignComponentOfNode(node: DirectiveOwner): ForeignComponentMeta | null;
+
+  /**
+   * Get all foreign components matched in the target.
+   */
+  getMatchedForeignComponents(): ForeignComponentMeta[];
+
   /**
    * For a given `Reference`, get the reference's target - either an `Element`, a `Template`, or
    * a directive on a particular node.
diff --git a/packages/compiler/src/render3/view/t2_binder.ts b/packages/compiler/src/render3/view/t2_binder.ts
@@ -58,6 +58,7 @@ import {
   ConflictingHostDirectiveBinding,
   DirectiveMeta,
   DirectiveOwner,
+  ForeignComponentMeta,
   MatchSource,
   ReferenceTarget,
   ScopedNode,
@@ -170,7 +171,10 @@ export type DirectiveMatcher<DirectiveT extends DirectiveMeta> =
  * target.
  */
 export class R3TargetBinder<DirectiveT extends DirectiveMeta> implements TargetBinder<DirectiveT> {
-  constructor(private directiveMatcher: DirectiveMatcher<DirectiveT> | null) {}
+  constructor(
+    private directiveMatcher: DirectiveMatcher<DirectiveT> | null,
+    private foreignComponentMatcher: SelectorlessMatcher<ForeignComponentMeta> | null = null,
+  ) {}
 
   /**
    * Perform a binding operation on the given `Target` and return a `BoundTarget` which contains
@@ -182,6 +186,7 @@ export class R3TargetBinder<DirectiveT extends DirectiveMeta> implements TargetB
     }
 
     const directives: MatchedDirectives<DirectiveT> = new Map();
+    const foreignComponents = new Map<DirectiveOwner, ForeignComponentMeta>();
     const eagerDirectives: DirectiveT[] = [];
     const missingDirectives = new Set<string>();
     const bindings: BindingsMap<DirectiveT> = new Map();
@@ -214,7 +219,9 @@ export class R3TargetBinder<DirectiveT extends DirectiveMeta> implements TargetB
       DirectiveBinder.apply(
         target.template,
         this.directiveMatcher,
+        this.foreignComponentMatcher,
         directives,
+        foreignComponents,
         eagerDirectives,
         missingDirectives,
         bindings,
@@ -255,6 +262,7 @@ export class R3TargetBinder<DirectiveT extends DirectiveMeta> implements TargetB
     return new R3BoundTarget(
       target,
       directives,
+      foreignComponents,
       eagerDirectives,
       missingDirectives,
       bindings,
@@ -516,7 +524,9 @@ class DirectiveBinder<DirectiveT extends DirectiveMeta> implements Visitor {
 
   private constructor(
     private directiveMatcher: DirectiveMatcher<DirectiveT> | null,
+    private foreignMatcher: SelectorlessMatcher<ForeignComponentMeta> | null,
     private directives: MatchedDirectives<DirectiveT>,
+    private foreignComponents: Map<DirectiveOwner, ForeignComponentMeta>,
     private eagerDirectives: DirectiveT[],
     private missingDirectives: Set<string>,
     private bindings: BindingsMap<DirectiveT>,
@@ -542,7 +552,9 @@ class DirectiveBinder<DirectiveT extends DirectiveMeta> implements Visitor {
   static apply<DirectiveT extends DirectiveMeta>(
     template: Node[],
     directiveMatcher: DirectiveMatcher<DirectiveT> | null,
+    foreignMatcher: SelectorlessMatcher<ForeignComponentMeta> | null,
     directives: MatchedDirectives<DirectiveT>,
+    foreignComponents: Map<DirectiveOwner, ForeignComponentMeta>,
     eagerDirectives: DirectiveT[],
     missingDirectives: Set<string>,
     bindings: BindingsMap<DirectiveT>,
@@ -554,7 +566,9 @@ class DirectiveBinder<DirectiveT extends DirectiveMeta> implements Visitor {
   ): void {
     const matcher = new DirectiveBinder(
       directiveMatcher,
+      foreignMatcher,
       directives,
+      foreignComponents,
       eagerDirectives,
       missingDirectives,
       bindings,
@@ -665,11 +679,12 @@ class DirectiveBinder<DirectiveT extends DirectiveMeta> implements Visitor {
   }
 
   private visitElementOrTemplate(node: Element | Template): void {
+    const matchedDirectives: DirectiveT[] = [];
+
     if (this.directiveMatcher instanceof SelectorMatcher) {
-      const directives: DirectiveT[] = [];
       const cssSelector = createCssSelectorFromNode(node);
-      this.directiveMatcher.match(cssSelector, (_, results) => directives.push(...results));
-      this.trackSelectorBasedBindingsAndDirectives(node, directives);
+      this.directiveMatcher.match(cssSelector, (_, results) => matchedDirectives.push(...results));
+      this.trackSelectorBasedBindingsAndDirectives(node, matchedDirectives);
     } else {
       node.references.forEach((ref) => {
         if (ref.value.trim() === '') {
@@ -678,6 +693,19 @@ class DirectiveBinder<DirectiveT extends DirectiveMeta> implements Visitor {
       });
     }
 
+    if (this.foreignMatcher && node instanceof Element) {
+      const foreignMatches = this.foreignMatcher.match(node.name);
+      if (foreignMatches.length > 0) {
+        if (matchedDirectives.length > 0) {
+          throw new Error(
+            `Conflict: Element '${node.name}' matches both an Angular directive and a foreign component.`,
+          );
+        }
+        // We assume at most one foreign component matches by name.
+        this.foreignComponents.set(node, foreignMatches[0]);
+      }
+    }
+
     node.directives.forEach((directive) => directive.visit(this));
     node.children.forEach((child) => child.visit(this));
   }
@@ -1182,6 +1210,7 @@ class R3BoundTarget<DirectiveT extends DirectiveMeta> implements BoundTarget<Dir
   constructor(
     readonly target: Target<DirectiveT>,
     private directives: MatchedDirectives<DirectiveT>,
+    private foreignComponents: Map<DirectiveOwner, ForeignComponentMeta>,
     private eagerDirectives: DirectiveT[],
     private missingDirectives: Set<string>,
     private bindings: BindingsMap<DirectiveT>,
@@ -1210,6 +1239,14 @@ class R3BoundTarget<DirectiveT extends DirectiveMeta> implements BoundTarget<Dir
     return this.directives.get(node) || null;
   }
 
+  getForeignComponentOfNode(node: DirectiveOwner): ForeignComponentMeta | null {
+    return this.foreignComponents.get(node) || null;
+  }
+
+  getMatchedForeignComponents(): ForeignComponentMeta[] {
+    return Array.from(this.foreignComponents.values());
+  }
+
   getReferenceTarget(ref: Reference): ReferenceTarget<DirectiveT> | null {
     return this.references.get(ref) || null;
   }
diff --git a/packages/compiler/test/render3/view/binding_spec.ts b/packages/compiler/test/render3/view/binding_spec.ts
@@ -8,7 +8,7 @@
 
 import * as e from '../../../src/expression_parser/ast';
 import * as a from '../../../src/render3/r3_ast';
-import {DirectiveMeta, MatchSource} from '../../../src/render3/view/t2_api';
+import {DirectiveMeta, MatchSource, ForeignComponentMeta} from '../../../src/render3/view/t2_api';
 import {ClassPropertyMapping} from '../../../src/property_mapping';
 import {findMatchingDirectivesAndPipes, R3TargetBinder} from '../../../src/render3/view/t2_binder';
 import {parseTemplate, ParseTemplateOptions} from '../../../src/render3/view/template';
@@ -1595,5 +1595,37 @@ describe('t2 binding', () => {
       expect(mergedHost.outputs.toDirectMappedObject()).toEqual({one: 'oneAlias'});
       expect(res.getConflictingHostDirectiveBindings(element)).toBe(null);
     });
+
+    it('should match foreign components by tag name', () => {
+      const template = parseTemplate('<FancyButton></FancyButton>', '', {});
+      const registry = new Map<string, ForeignComponentMeta[]>();
+      registry.set('FancyButton', [{name: 'FancyButton', ref: {key: 'FancyButtonKey'}}]);
+      const foreignMatcher = new SelectorlessMatcher(registry);
+
+      const binder = new R3TargetBinder(new SelectorMatcher<DirectiveMeta[]>(), foreignMatcher);
+      const res = binder.bind({template: template.nodes});
+
+      const el = template.nodes[0] as a.Element;
+      const foreignComp = res.getForeignComponentOfNode(el);
+      expect(foreignComp).not.toBeNull();
+      expect(foreignComp?.name).toBe('FancyButton');
+
+      const allMatched = res.getMatchedForeignComponents();
+      expect(allMatched.length).toBe(1);
+      expect(allMatched[0].name).toBe('FancyButton');
+    });
+
+    it('should throw an error when tag matches both directive and foreign component', () => {
+      const template = parseTemplate('<comp></comp>', '', {});
+      const registry = new Map<string, ForeignComponentMeta[]>();
+      registry.set('comp', [{name: 'comp', ref: {key: 'compKey'}}]);
+      const foreignMatcher = new SelectorlessMatcher(registry);
+
+      const binder = new R3TargetBinder(makeSelectorMatcher(), foreignMatcher);
+
+      expect(() => binder.bind({template: template.nodes})).toThrowError(
+        "Conflict: Element 'comp' matches both an Angular directive and a foreign component.",
+      );
+    });
   });
 });
