refactor(compiler): support passing content to specific foreign component props

Add `@content(propName)` blocks for passing template content to foreign
component properties by name. Previously, only a single set of direct children
could be passed to a foreign component via the default `children` property.
With this change, developers can project distinct template content to multiple
specific properties on the foreign component:

```html
<FancyButton [label]="title">
  @content(icon) {
    <span>Icon</span>
  }
  @content(description) {
    <span>Description text</span>
  }
  <span>Other children</span>
</FancyButton>
```

Specifically:
- Add support to the HTML lexer for `@content` blocks.
- Introduce `ContentBlock` AST node to represent `@content` blocks.
- Implement validation ensuring `@content` blocks have exactly one parameter
  representing a valid JS identifier.
- Throw an error during ingestion if a `@content` block is placed anywhere
  other than as a direct child of a foreign component.
- Map `@content` blocks to properties of the props object passed to
  `ɵɵforeignComponent`.
- Update compliance and unit tests to cover these changes.
```

Author: leonsenft

packages/compiler-cli/test/compliance/test_cases/r3_compiler_compliance/components_and_directives/standalone/GOLDEN_PARTIAL.js

@@ -421,7 +421,13 @@ export class TestCmpChildren {
     static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "0.0.0-PLACEHOLDER", ngImport: i0, type: TestCmpChildren, deps: [], target: i0.ɵɵFactoryTarget.Component });
     static ɵcmp = i0.ɵɵngDeclareComponent({ minVersion: "14.0.0", version: "0.0.0-PLACEHOLDER", type: TestCmpChildren, isStandalone: true, selector: "main-children", ngImport: i0, template: `
     <FancyButton [label]="title">
-      <span>Click me!</span>
+      @content(icon) {
+        <span>Icon!</span>
+      }
+      @content(description) {
+        <span>Description text</span>
+      }
+      <span>Other children</span>
     </FancyButton>
   `, isInline: true });
 }
@@ -431,7 +437,13 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "0.0.0-PLACEHOLDE
                     selector: 'main-children',
                     template: `
     <FancyButton [label]="title">
-      <span>Click me!</span>
+      @content(icon) {
+        <span>Icon!</span>
+      }
+      @content(description) {
+        <span>Description text</span>
+      }
+      <span>Other children</span>
     </FancyButton>
   `,
                     // @ts-ignore: @angular/core does not expose the `foreignImports` property.

packages/compiler-cli/test/compliance/test_cases/r3_compiler_compliance/components_and_directives/standalone/foreign_component.js

@@ -1,7 +1,23 @@
-function TestCmpChildren_Children_0_Template(rf, ctx) {
+function TestCmpChildren_Icon_0_Template(rf, ctx) {
   if (rf & 1) {
     i0.ɵɵdomElementStart(0, "span");
-    i0.ɵɵtext(1, "Click me!");
+    i0.ɵɵtext(1, "Icon!");
+    i0.ɵɵdomElementEnd();
+  }
+}
+
+function TestCmpChildren_Description_1_Template(rf, ctx) {
+  if (rf & 1) {
+    i0.ɵɵdomElementStart(0, "span");
+    i0.ɵɵtext(1, "Description text");
+    i0.ɵɵdomElementEnd();
+  }
+}
+
+function TestCmpChildren_Children_2_Template(rf, ctx) {
+  if (rf & 1) {
+    i0.ɵɵdomElementStart(0, "span");
+    i0.ɵɵtext(1, "Other children");
     i0.ɵɵdomElementEnd();
   }
 }
@@ -31,12 +47,12 @@ export class TestCmpChildren {
   static ɵcmp = /*@__PURE__*/ i0.ɵɵdefineComponent({
     type: TestCmpChildren,
     selectors: [["main-children"]],
-    decls: 2,
+    decls: 4,
     vars: 0,
     template: function TestCmpChildren_Template(rf, ctx) {
       if (rf & 1) {
-        i0.ɵɵdomTemplate(0, TestCmpChildren_Children_0_Template, 2, 0);
-        i0.ɵɵforeignComponent(1, frameworkImport(FancyButton), { label: ctx.title, children: i0.ɵɵforeignContent(0) });
+        i0.ɵɵdomTemplate(0, TestCmpChildren_Icon_0_Template, 2, 0)(1, TestCmpChildren_Description_1_Template, 2, 0)(2, TestCmpChildren_Children_2_Template, 2, 0);
+        i0.ɵɵforeignComponent(3, frameworkImport(FancyButton), { label: ctx.title, icon: i0.ɵɵforeignContent(0), description: i0.ɵɵforeignContent(1), children: i0.ɵɵforeignContent(2) });
       }
     },
     encapsulation: 2

packages/compiler-cli/test/compliance/test_cases/r3_compiler_compliance/components_and_directives/standalone/foreign_component.local.js

@@ -1,7 +1,23 @@
-function TestCmpChildren_Children_0_Template(rf, ctx) {
+function TestCmpChildren_Icon_0_Template(rf, ctx) {
   if (rf & 1) {
     i0.ɵɵelementStart(0, "span");
-    i0.ɵɵtext(1, "Click me!");
+    i0.ɵɵtext(1, "Icon!");
+    i0.ɵɵelementEnd();
+  }
+}
+
+function TestCmpChildren_Description_1_Template(rf, ctx) {
+  if (rf & 1) {
+    i0.ɵɵelementStart(0, "span");
+    i0.ɵɵtext(1, "Description text");
+    i0.ɵɵelementEnd();
+  }
+}
+
+function TestCmpChildren_Children_2_Template(rf, ctx) {
+  if (rf & 1) {
+    i0.ɵɵelementStart(0, "span");
+    i0.ɵɵtext(1, "Other children");
     i0.ɵɵelementEnd();
   }
 }
@@ -31,12 +47,12 @@ export class TestCmpChildren {
   static ɵcmp = /*@__PURE__*/ i0.ɵɵdefineComponent({
     type: TestCmpChildren,
     selectors: [["main-children"]],
-    decls: 2,
+    decls: 4,
     vars: 0,
     template: function TestCmpChildren_Template(rf, ctx) {
       if (rf & 1) {
-        i0.ɵɵtemplate(0, TestCmpChildren_Children_0_Template, 2, 0);
-        i0.ɵɵforeignComponent(1, frameworkImport(FancyButton), { label: ctx.title, children: i0.ɵɵforeignContent(0) });
+        i0.ɵɵtemplate(0, TestCmpChildren_Icon_0_Template, 2, 0)(1, TestCmpChildren_Description_1_Template, 2, 0)(2, TestCmpChildren_Children_2_Template, 2, 0);
+        i0.ɵɵforeignComponent(3, frameworkImport(FancyButton), { label: ctx.title, icon: i0.ɵɵforeignContent(0), description: i0.ɵɵforeignContent(1), children: i0.ɵɵforeignContent(2) });
       }
     },
     encapsulation: 2

packages/compiler-cli/test/compliance/test_cases/r3_compiler_compliance/components_and_directives/standalone/foreign_component.ts

@@ -31,7 +31,13 @@ export class TestCmp {
   selector: 'main-children',
   template: `
     <FancyButton [label]="title">
-      <span>Click me!</span>
+      @content(icon) {
+        <span>Icon!</span>
+      }
+      @content(description) {
+        <span>Description text</span>
+      }
+      <span>Other children</span>
     </FancyButton>
   `,
   // @ts-ignore: @angular/core does not expose the `foreignImports` property.

packages/compiler/src/combined_visitor.ts

@@ -46,6 +46,10 @@ export class CombinedRecursiveAstVisitor extends RecursiveAstVisitor implements
     this.visitAllTemplateNodes(content.children);
   }
 
+  visitContentBlock(block: t.ContentBlock): void {
+    this.visitAllTemplateNodes(block.children);
+  }
+
   visitBoundAttribute(attribute: t.BoundAttribute): void {
     this.visit(attribute.value);
   }

packages/compiler/src/compiler.ts

@@ -188,6 +188,7 @@ export {
   HostElement as TmplAstHostElement,
   Component as TmplAstComponent,
   Directive as TmplAstDirective,
+  ContentBlock as TmplAstContentBlock,
   visitAll as tmplAstVisitAll,
   Visitor as TmplAstVisitor,
 } from './render3/r3_ast';

packages/compiler/src/ml_parser/lexer.ts

@@ -153,6 +153,7 @@ const SUPPORTED_BLOCKS = [
   '@placeholder',
   '@loading',
   '@error',
+  '@content',
 ] as const;
 
 const INTERPOLATION = {start: '{{', end: '}}'} as const;

packages/compiler/src/render3/r3_ast.ts

@@ -339,6 +339,24 @@ export class DeferredBlockError extends BlockNode implements Node {
   }
 }
 
+export class ContentBlock extends BlockNode implements Node {
+  constructor(
+    public name: string,
+    public children: Node[],
+    nameSpan: ParseSourceSpan,
+    sourceSpan: ParseSourceSpan,
+    startSourceSpan: ParseSourceSpan,
+    endSourceSpan: ParseSourceSpan | null,
+    public i18n?: I18nMeta,
+  ) {
+    super(nameSpan, sourceSpan, startSourceSpan, endSourceSpan);
+  }
+
+  visit<Result>(visitor: Visitor<Result>): Result {
+    return visitor.visitContentBlock(this);
+  }
+}
+
 export interface DeferredBlockTriggers {
   when?: BoundDeferredTrigger;
   idle?: IdleDeferredTrigger;
@@ -762,6 +780,7 @@ export interface Visitor<Result = any> {
   visitLetDeclaration(decl: LetDeclaration): Result;
   visitComponent(component: Component): Result;
   visitDirective(directive: Directive): Result;
+  visitContentBlock(block: ContentBlock): Result;
 }
 
 export class RecursiveVisitor implements Visitor<void> {
@@ -846,6 +865,9 @@ export class RecursiveVisitor implements Visitor<void> {
   visitDeferredTrigger(trigger: DeferredTrigger): void {}
   visitUnknownBlock(block: UnknownBlock): void {}
   visitLetDeclaration(decl: LetDeclaration): void {}
+  visitContentBlock(block: ContentBlock): void {
+    visitAll(this, block.children);
+  }
 }
 
 export function visitAll<Result>(visitor: Visitor<Result>, nodes: Node[]): Result[] {

packages/compiler/src/render3/r3_content_blocks.ts

@@ -0,0 +1,60 @@
+/**
+ * @license
+ * Copyright Google LLC All Rights Reserved.
+ *
+ * Use of this source code is governed by an MIT-style license that can be
+ * found in the LICENSE file at https://angular.dev/license
+ */
+
+import * as html from '../ml_parser/ast';
+import {ParseError} from '../parse_util';
+
+import * as t from './r3_ast';
+import {IDENTIFIER_PATTERN} from './util';
+
+/** Creates a content block from an HTML AST node. */
+export function createContentBlock(
+  ast: html.Block,
+  visitor: html.Visitor,
+): {node: t.ContentBlock | null; errors: ParseError[]} {
+  const errors: ParseError[] = [];
+  if (ast.parameters.length !== 1) {
+    errors.push(
+      new ParseError(ast.startSourceSpan, '@content block must have exactly one parameter'),
+    );
+    return {node: null, errors};
+  }
+
+  const param = ast.parameters[0];
+  let expr = param.expression.trim();
+  if (expr.startsWith('(') && expr.endsWith(')')) {
+    expr = expr.slice(1, -1).trim();
+  }
+
+  const parts = expr.split(',').map((p) => p.trim());
+  if (parts.length !== 1 || parts[0] === '') {
+    errors.push(
+      new ParseError(ast.startSourceSpan, '@content block must have exactly one parameter'),
+    );
+    return {node: null, errors};
+  }
+
+  const name = parts[0];
+  if (!IDENTIFIER_PATTERN.test(name)) {
+    errors.push(
+      new ParseError(param.sourceSpan, '@content name must be a valid JavaScript identifier'),
+    );
+    return {node: null, errors};
+  }
+
+  const node = new t.ContentBlock(
+    name,
+    html.visitAll(visitor, ast.children, ast.children),
+    ast.nameSpan,
+    ast.sourceSpan,
+    ast.startSourceSpan,
+    ast.endSourceSpan,
+    ast.i18n,
+  );
+  return {node, errors};
+}

packages/compiler/src/render3/r3_control_flow.ts

@@ -12,6 +12,7 @@ import {ParseError, ParseSourceSpan} from '../parse_util';
 import {BindingParser} from '../template_parser/binding_parser';
 
 import * as t from './r3_ast';
+import {IDENTIFIER_PATTERN} from './util';
 
 /** Pattern for the expression in a for loop block. */
 const FOR_LOOP_EXPRESSION_PATTERN = /^\s*([0-9A-Za-z_$]*)\s+of\s+([\S\s]*)/;
@@ -28,9 +29,6 @@ const ELSE_IF_PATTERN = /^else[^\S\r\n]+if/;
 /** Pattern used to identify a `let` parameter. */
 const FOR_LOOP_LET_PATTERN = /^let\s+([\S\s]*)/;
 
-/** Pattern used to validate a JavaScript identifier. */
-const IDENTIFIER_PATTERN = /^[$A-Z_][0-9A-Z_$]*$/i;
-
 /**
  * Pattern to group a string into leading whitespace, non whitespace, and trailing whitespace.
  * Useful for getting the variable name span when a span can contain leading and trailing space.