refactor(compiler-cli): disallow @content (children) in favor of implicit children

Defining a `@content (children)` block explicitly is unnecessary because
children should always be passed implicitly as direct nested content of the
foreign component. Using an explicit block could also lead to conflicts and
silent template rendering issues where implicit content (like whitespace)
accidentally overwrote the explicit block in the compiler's template
representation.

This change introduces a compilation error
(`FOREIGN_COMPONENT_CONTENT_UNNECESSARY_FOR_CHILDREN`) when an explicit
`@content (children)` block is detected, guiding developers to pass children
implicitly instead.

Author: leonsenft

goldens/public-api/compiler-cli/error_code.api.md

@@ -55,6 +55,7 @@ export enum ErrorCode {
     DUPLICATE_DECORATED_PROPERTIES = 1012,
     DUPLICATE_VARIABLE_DECLARATION = 8006,
     FORBIDDEN_REQUIRED_INITIALIZER_INVOCATION = 8118,
+    FOREIGN_COMPONENT_CONTENT_UNNECESSARY_FOR_CHILDREN = 8027,
     FOREIGN_COMPONENT_UNSUPPORTED_BINDING = 8025,
     FORM_FIELD_UNSUPPORTED_BINDING = 8022,
     HOST_BINDING_PARSE_ERROR = 5001,

packages/compiler-cli/src/ngtsc/annotations/component/src/foreign_component.ts

@@ -206,7 +206,21 @@ class ForeignComponentFeatureAnalyzer extends TmplAstRecursiveVisitor {
   }
 
   override visitContentBlock(block: TmplAstContentBlock): void {
-    if (!this.parentNodeIsForeignComponent()) {
+    if (this.parentNodeIsForeignComponent()) {
+      if (block.name === 'children') {
+        this.diagnostics.push(
+          makeTemplateDiagnostic(
+            '' as TypeCheckId,
+            this.sourceMapping,
+            block.sourceSpan,
+            ts.DiagnosticCategory.Error,
+            ngErrorCode(ErrorCode.FOREIGN_COMPONENT_CONTENT_UNNECESSARY_FOR_CHILDREN),
+            'Defining a @content (children) block is unnecessary. ' +
+              'Pass children as direct nested content of the foreign component instead.',
+          ),
+        );
+      }
+    } else {
       this.diagnostics.push(
         makeTemplateDiagnostic(
           '' as TypeCheckId,

packages/compiler-cli/src/ngtsc/diagnostics/src/error_code.ts

@@ -469,6 +469,12 @@ export enum ErrorCode {
    */
   INVALID_CONTENT_PLACEMENT = 8026,
 
+  /**
+   * Raised when a `@content` block is named 'children', which is unnecessary because children should be passed
+   * implicitly.
+   */
+  FOREIGN_COMPONENT_CONTENT_UNNECESSARY_FOR_CHILDREN = 8027,
+
   /**
    * A two way binding in a template has an incorrect syntax,
    * parentheses outside brackets. For example:

packages/compiler-cli/test/ngtsc/template_typecheck_spec.ts

@@ -2404,6 +2404,31 @@ runInEachFileSystem(() => {
           '@content blocks are only valid as direct children of foreign components.',
         );
       });
+
+      it('should detect unnecessary @content (children) block on a foreign component', () => {
+        env.write(
+          'test.ts',
+          `
+          ${foreignSetupCode}
+
+          @Component({
+            selector: 'test',
+            template: '<FancyButton> @content (children) {} </FancyButton>',
+            foreignImports: [frameworkImport(FancyButton)],
+          })
+          export class TestCmp {}
+        `,
+        );
+        const diags = env.driveDiagnostics();
+        expect(diags.length).toEqual(1);
+        expect(diags[0].code).toEqual(
+          ngErrorCode(ErrorCode.FOREIGN_COMPONENT_CONTENT_UNNECESSARY_FOR_CHILDREN),
+        );
+        expect(diags[0].messageText).toEqual(
+          'Defining a @content (children) block is unnecessary. ' +
+            'Pass children as direct nested content of the foreign component instead.',
+        );
+      });
     });
 
     it('should detect a duplicate variable declaration', () => {