refactor(core): abstract control flow discovery utilities

Work in progress.

Author: hawkgs

devtools/projects/ng-devtools-backend/src/lib/client-event-subscribers.ts

@@ -387,8 +387,10 @@ export interface SerializableComponentInstanceType extends ComponentType {
   id: number;
 }
 
-export interface SerializableComponentTreeNode
-  extends DevToolsNode<SerializableDirectiveInstanceType, SerializableComponentInstanceType> {
+export interface SerializableComponentTreeNode extends DevToolsNode<
+  SerializableDirectiveInstanceType,
+  SerializableComponentInstanceType
+> {
   children: SerializableComponentTreeNode[];
   nativeElement?: never;
   // Since the nativeElement is not serializable, we will use this boolean as backup
@@ -436,8 +438,7 @@ const prepareForestForSerialization = (
       })),
       children: prepareForestForSerialization(node.children, includeResolutionPath),
       hydration: node.hydration,
-      defer: node.defer,
-      forLoop: node.forLoop,
+      controlFlowBlock: node.controlFlowBlock,
       onPush: node.component ? isOnPushDirective(node.component) : false,
 
       // native elements are not serializable

devtools/projects/ng-devtools-backend/src/lib/component-tree/component-tree.ts

@@ -689,7 +689,7 @@ export const queryDirectiveForest = (
     }
     forest = node.children;
   }
-  if (node?.defer) {
+  if (node?.controlFlowBlock) {
     return null;
   }
   return node;

devtools/projects/ng-devtools-backend/src/lib/directive-forest/control-flow.ts

@@ -0,0 +1,134 @@
+/**
+ * @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 {
+  ɵDeferBlockData as DeferBlockDataInternal,
+  ɵControlFlowBlock as ControlFlowBlockInternal,
+  ɵControlFlowBlockType as ControlFlowBlockTypeInternal,
+} from '@angular/core';
+import {
+  ControlFlowBlock,
+  ControlFlowBlockType,
+  ForLoopBlock,
+  DeferBlock,
+  RenderedDeferBlock,
+} from '../../../../protocol';
+import {ComponentTreeNode} from '../interfaces';
+import {serializeValue} from '../state-serializer/state-serializer';
+
+const ELEMENT_NAME_MAP: {[key in ControlFlowBlockType]: string} = {
+  [ControlFlowBlockType.Defer]: '@defer',
+  [ControlFlowBlockType.For]: '@for',
+};
+
+export function isControlFlowBlock(node: Node, iterator: ControlFlowBlocksIterator) {
+  const currentBlock = iterator.currentBlock;
+  // Handles the case where the @defer is still unresolved but doesn't
+  // have a placeholder, for instance, by which children we mark
+  // the position of the block normally. In this case, we use the host.
+  return node === currentBlock?.hostNode || node === currentBlock?.rootNodes[0];
+}
+
+export function mapToDevtoolsControlFlowModel(
+  block: ControlFlowBlockInternal,
+  iterator: ControlFlowBlocksIterator,
+  rootId: number,
+): ControlFlowBlock {
+  switch (block.type) {
+    case ControlFlowBlockTypeInternal.For:
+      const serializedItems = block.items.map((item) => serializeValue(item, 5));
+
+      return {
+        id: `forId-${rootId}-${iterator.currentIndex}`,
+        type: ControlFlowBlockType.For,
+        hasEmptyBlock: block.hasEmptyBlock,
+        items: serializedItems,
+        trackExpression: block.trackExpression,
+      } satisfies ForLoopBlock as ForLoopBlock;
+
+    case ControlFlowBlockTypeInternal.Defer:
+      return {
+        id: `deferId-${rootId}-${iterator.currentIndex}`,
+        type: ControlFlowBlockType.Defer,
+        state: block.state,
+        renderedBlock: getRenderedBlock(block),
+        triggers: groupTriggers(block.triggers),
+        blocks: {
+          hasErrorBlock: block.hasErrorBlock,
+          placeholderBlock: block.placeholderBlock,
+          loadingBlock: block.loadingBlock,
+        },
+      } satisfies DeferBlock as DeferBlock;
+  }
+}
+
+/**
+ * Creates a synthetic ComponentTreeNode for control flow blocks (@defer, @for).
+ */
+export function createControlFlowTreeNode(
+  controlFlowBlock: ControlFlowBlockInternal,
+  children: ComponentTreeNode[],
+  iterator: ControlFlowBlocksIterator,
+  rootId: number,
+): ComponentTreeNode {
+  return {
+    children,
+    component: null,
+    directives: [],
+    element: ELEMENT_NAME_MAP[controlFlowBlock.type],
+    nativeElement: undefined,
+    hydration: null,
+    controlFlowBlock: mapToDevtoolsControlFlowModel(controlFlowBlock, iterator, rootId),
+  };
+}
+
+export class ControlFlowBlocksIterator<
+  T extends ControlFlowBlockInternal = ControlFlowBlockInternal,
+> {
+  public currentIndex = 0;
+  private blocks: T[] = [];
+
+  constructor(blocks: T[]) {
+    this.blocks = blocks;
+  }
+
+  advance() {
+    this.currentIndex++;
+  }
+
+  get currentBlock(): T | undefined {
+    return this.blocks[this.currentIndex];
+  }
+}
+
+function groupTriggers(triggers: string[]) {
+  const defer: string[] = [];
+  const hydrate: string[] = [];
+  const prefetch: string[] = [];
+
+  for (let trigger of triggers) {
+    if (trigger.startsWith('hydrate')) {
+      hydrate.push(trigger);
+    } else if (trigger.startsWith('prefetch')) {
+      prefetch.push(trigger);
+    } else {
+      defer.push(trigger);
+    }
+  }
+  return {defer, hydrate, prefetch};
+}
+
+function getRenderedBlock(deferBlock: DeferBlockDataInternal): RenderedDeferBlock | null {
+  if (['placeholder', 'loading', 'error'].includes(deferBlock.state)) {
+    return deferBlock.state as 'placeholder' | 'loading' | 'error';
+  }
+  if (deferBlock.state === 'complete') {
+    return 'defer';
+  }
+  return null;
+}

devtools/projects/ng-devtools-backend/src/lib/directive-forest/ltree.ts

@@ -91,8 +91,7 @@ export class LTreeStrategy {
         directives: [],
         component: null,
         hydration: null, // We know there is no hydration if we use the LTreeStrategy
-        defer: null, // neither there will be any defer
-        forLoop: null, // neither there will be any @for
+        controlFlowBlock: null, // neither there will be any control flow block
       };
     }
     for (let i = tNode.directiveStart; i < tNode.directiveEnd; i++) {
@@ -118,8 +117,7 @@ export class LTreeStrategy {
       directives,
       component,
       hydration: null, // We know there is no hydration if we use the LTreeStrategy
-      defer: null, // neither there will be any defer
-      forLoop: null, // neither there will be any @for
+      controlFlowBlock: null, // neither there will be any control flow block
     };
   }