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 collect container nodes in the expected order:

1. Push the host element for dynamic containers where where `lContainer[NATIVE]
   !== lContainer[HOST]` (e.g., a `ViewContainerRef` injected on a `div` element).
2. Collect nodes in the container.
3. _Unconditionally_ push the container anchor comment.

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

Author: leonsenft

packages/core/src/hydration/annotate.ts

@@ -337,12 +337,11 @@ function serializeLContainer(
       // host element was used as a ViewContainerRef anchor (e.g. a `ViewContainerRef`
       // was injected within the component class). This case requires special handling.
       if (isLContainer(childLView)) {
-        // Calculate the number of root nodes in all views in a given container
-        // and increment by one to account for an anchor node itself, i.e. in this
-        // scenario we'll have a layout that would look like this:
+        // Calculate the number of root nodes in all attached views and add 2 to account for the
+        // component's host node and the container's anchor node. i.e. in this scenario we'll have a
+        // layout that would look like this:
         // `<app-root /><#VIEW1><#VIEW2>...<!--container-->`
-        // The `+1` is to capture the `<app-root />` element.
-        numRootNodes = calcNumRootNodesInLContainer(childLView) + 1;
+        numRootNodes = calcNumRootNodesInLContainer(childLView) + 2;
 
         annotateLContainerForHydration(childLView, context);
 

packages/core/src/render3/collect_native_nodes.ts

@@ -54,14 +54,24 @@ export function collectNativeNodes(
 
     const lNode = lView[tNode.index];
     if (lNode !== null) {
-      result.push(unwrapRNode(lNode));
-    }
+      if (isLContainer(lNode)) {
+        const anchor = lNode[NATIVE];
+        // 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 (anchor !== lNode[HOST]) {
+          result.push(unwrapRNode(lNode));
+        }
+
+        // Collect the root nodes from the views in this container.
+        collectNativeNodesInLContainer(lNode, result);
 
-    // 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);
+        // The container's anchor comment node is always physically positioned after any views
+        // rendered inside the container, so we always push it here at the end.
+        result.push(anchor);
+      } else {
+        result.push(unwrapRNode(lNode));
+      }
     }
 
     const tNodeType = tNode.type;
@@ -100,21 +110,4 @@ export function collectNativeNodesInLContainer(lContainer: LContainer, result: a
       collectNativeNodes(lViewInAContainer[TVIEW], lViewInAContainer, lViewFirstChildTNode, result);
     }
   }
-
-  // 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]);
-  }
 }

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);
     });