fix(core): introduce logical-only containers for foreign content

This commit introduces a logical-only container flag (`LContainerFlags.LogicalOnly`)
to support Angular features (like change detection and queries) on projected content
within foreign components, while relinquishing control over their placement in the DOM.

When content is projected into a foreign component via `ɵɵforeignContent`, the foreign
component receives the native DOM nodes directly and assumes control over their DOM
placement. Therefore, Angular must skip all platform-level view operations (insert,
move, delete) on these projected views.

To achieve this:
1. Introduce Logical-Only Containers:
   - Added `LContainerFlags.LogicalOnly` to represent view containers whose nodes are
     managed logically (by the consuming foreign component) rather than by the renderer.
   - Flagged `ɵɵforeignContent` containers with the `LogicalOnly` annotation.
   - Updated `applyContainer` in `node_manipulation.ts` to return early and skip platform
     DOM manipulations (insert, detach, destroy) on containers marked as logical-only.

2. Guard `collectNativeNodes`:
   - Updated `collectNativeNodes` in `collect_native_nodes.ts` to skip descending into
     logical-only containers. This prevents nested projected child elements (which are
     already claimed and placed inside nested foreign components) from being re-collected
     at the parent component's projection root level.

3. Unit and Acceptance Tests:
   - Added a comprehensive set of categorized acceptance tests in `foreign_component_spec.ts`
     covering nested foreign projections, projecting foreign components into Angular components,
     Signal-based view queries (`viewChildren`), event handlers, and change detection.

Author: leonsenft

packages/core/src/render3/collect_native_nodes.ts

@@ -8,11 +8,19 @@
 
 import {assertParentView} from './assert';
 import {icuContainerIterate} from './i18n/i18n_tree_shaking';
-import {CONTAINER_HEADER_OFFSET, LContainer, NATIVE} from './interfaces/container';
+import {CONTAINER_HEADER_OFFSET, LContainer, LContainerFlags, NATIVE} from './interfaces/container';
 import {TIcuContainerNode, TNode, TNodeType} from './interfaces/node';
 import {RNode} from './interfaces/renderer_dom';
 import {isLContainer} from './interfaces/type_checks';
-import {DECLARATION_COMPONENT_VIEW, HOST, LView, TVIEW, TView, TViewType} from './interfaces/view';
+import {
+  DECLARATION_COMPONENT_VIEW,
+  FLAGS,
+  HOST,
+  LView,
+  TVIEW,
+  TView,
+  TViewType,
+} from './interfaces/view';
 import {assertTNodeType} from './node_assert';
 import {getProjectionNodes} from './node_manipulation';
 import {getLViewParent, unwrapRNode} from './util/view_utils';
@@ -60,7 +68,7 @@ export function collectNativeNodes(
     // A given lNode can represent either a native node or a LContainer (when it is a host of a
     // ViewContainerRef). When we find a LContainer we need to descend into it to collect root nodes
     // from the views in this container.
-    if (isLContainer(lNode)) {
+    if (isLContainer(lNode) && !(lNode[FLAGS] & LContainerFlags.LogicalOnly)) {
       collectNativeNodesInLContainer(lNode, result);
     }
 

packages/core/src/render3/instructions/foreign_component.ts

@@ -10,7 +10,7 @@ import {ForeignComponent, RENDER} from '../../interface/foreign_component';
 import {attachPatchData} from '../context_discovery';
 import {createForeignView} from '../foreign_view';
 import {TContainerNode, TNodeType} from '../interfaces/node';
-import {HEADER_OFFSET, RENDERER, TVIEW} from '../interfaces/view';
+import {HEADER_OFFSET, RENDERER, TVIEW, FLAGS} from '../interfaces/view';
 import {appendChild} from '../node_manipulation';
 import {nativeInsertBefore} from '../dom_node_manipulation';
 import {getLView, getTView, setCurrentTNode, setCurrentTNodeAsNotParent} from '../state';
@@ -20,11 +20,11 @@ import {createLContainer, addLViewToLContainer} from '../view/container';
 import {NodeInjector} from '../di';
 import {runInInjectionContext} from '../../di';
 import {Renderer} from '../interfaces/renderer';
-import {RNode} from '../interfaces/renderer_dom';
+import {RElement, RNode} from '../interfaces/renderer_dom';
 import {createAndRenderEmbeddedLView} from '../view_manipulation';
 import {collectNativeNodes} from '../collect_native_nodes';
 import {assertLContainer} from '../assert';
-import {LContainer} from '../interfaces/container';
+import {LContainer, LContainerFlags} from '../interfaces/container';
 
 /**
  * Creation phase instruction to render a foreign component.
@@ -77,7 +77,7 @@ export function ɵɵforeignComponent(
   const parent = tail.parentNode;
   if (parent) {
     for (let i = 0; i < nodes.length; i++) {
-      nativeInsertBefore(renderer, parent, nodes[i], tail, false);
+      nativeInsertBefore(renderer, parent, nodes[i], tail, true);
     }
   }
 
@@ -101,12 +101,13 @@ export function ɵɵforeignContent(index: number): any[] {
   // The template is already declared at adjustedIndex, so lContainer must exist.
   const lContainer = lView[adjustedIndex] as LContainer;
   ngDevMode && assertLContainer(lContainer);
+  lContainer[FLAGS] |= LContainerFlags.LogicalOnly;
 
   const tView = getTView();
   const tNode = tView.data[adjustedIndex] as TContainerNode;
 
-  // Instantiate and render the embedded view inside the container,
-  // but do NOT add its elements to the DOM at the container anchor.
+  // Instantiate and render the embedded view inside the container, but do not add its elements to
+  // the DOM at the container anchor since the nodes will be projected into a foreign view.
   const embeddedLView = createAndRenderEmbeddedLView(lView, tNode, null);
   addLViewToLContainer(lContainer, embeddedLView, 0, /* addToDOM */ false);
 

packages/core/src/render3/interfaces/container.ts

@@ -127,4 +127,10 @@ export const enum LContainerFlags {
    * This flag, once set, is never unset for the `LContainer`.
    */
   HasTransplantedViews = 1 << 1,
+
+  /**
+   * Flag to signify that this `LContainer` is logical-only and its views should not be added
+   * to or removed from the rendering tree by the platform renderer.
+   */
+  LogicalOnly = 1 << 2,
 }

packages/core/src/render3/node_manipulation.ts

@@ -35,7 +35,13 @@ import {
   nativeRemoveNode,
 } from './dom_node_manipulation';
 import {icuContainerIterate} from './i18n/i18n_tree_shaking';
-import {CONTAINER_HEADER_OFFSET, LContainer, MOVED_VIEWS, NATIVE} from './interfaces/container';
+import {
+  CONTAINER_HEADER_OFFSET,
+  LContainer,
+  LContainerFlags,
+  MOVED_VIEWS,
+  NATIVE,
+} from './interfaces/container';
 import {ComponentDef} from './interfaces/definition';
 import {NodeInjectorFactory} from './interfaces/injector';
 import {unregisterLView} from './interfaces/lview_tracking';
@@ -1082,6 +1088,9 @@ function applyContainer(
       beforeNode,
     );
   }
+  if ((lContainer[FLAGS] & LContainerFlags.LogicalOnly) !== 0) {
+    return;
+  }
   for (let i = CONTAINER_HEADER_OFFSET; i < lContainer.length; i++) {
     const lView = lContainer[i] as LView;
     applyView(lView[TVIEW], lView, renderer, action, parentRElement, anchor);

packages/core/test/acceptance/foreign_component/BUILD.bazel

@@ -0,0 +1,29 @@
+load("//tools:defaults.bzl", "angular_jasmine_test", "ng_project", "ng_web_test_suite")
+
+package(default_visibility = ["//visibility:private"])
+
+ng_project(
+    name = "foreign_component_test_lib",
+    testonly = True,
+    srcs = glob(["**/*.ts"]),
+    visibility = ["//:__pkg__"],
+    deps = [
+        "//packages/core",
+        "//packages/core/testing",
+    ],
+)
+
+angular_jasmine_test(
+    name = "foreign_component",
+    data = [
+        ":foreign_component_test_lib",
+        "//:node_modules/source-map",
+    ],
+)
+
+ng_web_test_suite(
+    name = "foreign_component_web",
+    deps = [
+        ":foreign_component_test_lib",
+    ],
+)