fix(core): correct container anchor collection order to match DOM layout

Historically, `collectNativeNodes` collected the container's anchor comment
node (`LContainer[NATIVE]`) before descending into the views contained inside
the `LContainer`. While this worked logically, it did not match the actual
physical layout of the DOM tree, where dynamic view content is inserted before
the container anchor. This discrepancy was particularly visible in projected
`@content` blocks where the anchor comment ended up rendered at the beginning
instead of the end of the content block.

This commit refactors `collectNativeNodes` to push the anchor comment node at
the very end of view collection inside `collectNativeNodesInLContainer`. For
dynamic containers where `lContainer[NATIVE] !== lContainer[HOST]` (e.g., a
`ViewContainerRef` injected on a `div` element), we still push the host element
first before descending to preserve the physical DOM layout.

Associated acceptance tests in `template_ref_spec.ts` are updated to match the
physically correct DOM order.

Author: leonsenft

packages/core/src/render3/collect_native_nodes.ts

@@ -54,14 +54,19 @@ export function collectNativeNodes(
 
     const lNode = lView[tNode.index];
     if (lNode !== null) {
-      result.push(unwrapRNode(lNode));
-    }
+      if (isLContainer(lNode)) {
+        // If this is a dynamic container (ViewContainerRef on an element), the HOST element is a
+        // distinct element node and must be pushed first (before the views are collected) to
+        // preserve DOM order.
+        if (lNode[NATIVE] !== lNode[HOST]) {
+          result.push(unwrapRNode(lNode));
+        }
 
-    // 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)) {
-      collectNativeNodesInLContainer(lNode, result);
+        // Collect the root nodes from the views in this container.
+        collectNativeNodesInLContainer(lNode, result);
+      } else {
+        result.push(unwrapRNode(lNode));
+      }
     }
 
     const tNodeType = tNode.type;
@@ -101,20 +106,7 @@ export function collectNativeNodesInLContainer(lContainer: LContainer, result: a
     }
   }
 
-  // When an LContainer is created, the anchor (comment) node is:
-  // - (1) either reused in case of an ElementContainer (<ng-container>)
-  // - (2) or a new comment node is created
-  // In the first case, the anchor comment node would be added to the final
-  // list by the code in the `collectNativeNodes` function
-  // (see the `result.push(unwrapRNode(lNode))` line), but the second
-  // case requires extra handling: the anchor node needs to be added to the
-  // final list manually. See additional information in the `createAnchorNode`
-  // function in the `view_container_ref.ts`.
-  //
-  // In the first case, the same reference would be stored in the `NATIVE`
-  // and `HOST` slots in an LContainer. Otherwise, this is the second case and
-  // we should add an element to the final list.
-  if (lContainer[NATIVE] !== lContainer[HOST]) {
-    result.push(lContainer[NATIVE]);
-  }
+  // The container's anchor comment node (NATIVE) is always physically positioned
+  // after any views rendered inside the container, so we always push it here at the end.
+  result.push(lContainer[NATIVE]);
 }

packages/core/test/acceptance/template_ref_spec.ts

@@ -115,8 +115,8 @@ describe('TemplateRef', () => {
       </ng-template>`);
 
       expect(rootNodes.length).toBe(3);
-      expect(rootNodes[0].nodeType).toBe(Node.COMMENT_NODE);
-      expect(rootNodes[1].nodeType).toBe(Node.TEXT_NODE);
+      expect(rootNodes[0].nodeType).toBe(Node.TEXT_NODE);
+      expect(rootNodes[1].nodeType).toBe(Node.COMMENT_NODE);
       expect(rootNodes[2].nodeType).toBe(Node.TEXT_NODE);
     });
 
@@ -153,8 +153,8 @@ describe('TemplateRef', () => {
         `);
 
       expect(rootNodes.length).toBe(3);
-      expect(rootNodes[0].nodeType).toBe(Node.COMMENT_NODE);
-      expect(rootNodes[1].nodeType).toBe(Node.TEXT_NODE);
+      expect(rootNodes[0].nodeType).toBe(Node.TEXT_NODE);
+      expect(rootNodes[1].nodeType).toBe(Node.COMMENT_NODE);
       expect(rootNodes[2].nodeType).toBe(Node.TEXT_NODE);
     });