@principal-ai/subsystems-react 0.51.4 → 0.52.0

package/src/utils/elkLayout.ts

@@ -10,7 +10,7 @@ import type { Node, Edge } from '@xyflow/react';
 import {
   EDGE_LABEL_WIDTH,
   EDGE_LABEL_HEIGHT,
-  EDGE_LABEL_EDGE_GAP,
+  EDGE_LABEL_SIDE_PADDING,
 } from './edgeLabel';
 
 /** ELK layout options for different routing styles */
@@ -76,6 +76,22 @@ export interface ElkLayoutOptions {
     enabled?: boolean;
     /** Placement of inline labels. @default 'CENTER' */
     placement?: 'CENTER' | 'TAIL' | 'HEAD';
+    /**
+     * Width of the reserved label box, in flow px. This is what actually sets
+     * the between-layer run for a labelled edge — ELK's CENTER_LAYER creates a
+     * label layer of this width, which dominates the layering spacing. Defaults
+     * to the shared `EDGE_LABEL_WIDTH`; a caller with shorter labels passes a
+     * smaller value to tighten its edges.
+     */
+    width?: number;
+    /**
+     * Per-label width, computed from the label text. When supplied, wins over
+     * `width` for each edge, so the reserved box tracks content instead of one
+     * fixed width. The overlay must use the same function.
+     */
+    measure?: (text: string) => number;
+    /** Height of the reserved label box. Defaults to `EDGE_LABEL_HEIGHT`. */
+    height?: number;
   };
 
   /**
@@ -121,6 +137,34 @@ export interface ElkLayoutOptions {
    * on the duplicate. @default false
    */
   keepSingletonGroups?: boolean;
+
+  /**
+   * Lay a group's members out at the root instead of nesting them inside an
+   * ELK parent, then synthesize the frame's bounds as the bounding box of its
+   * members.
+   *
+   * A nested frame is a real ELK parent, so edges wholly inside it inherit the
+   * frame's padding and its own between-layer spacing on top — which makes an
+   * in-frame edge run longer than a root-level one touching the same nodes.
+   * Flattening removes that: every edge uses one spacing, and the frame is pure
+   * decoration drawn around wherever the members landed.
+   *
+   * Only for groups whose members need no parent-relative positioning (C4's
+   * system frame). @default false
+   */
+  flatGroups?: boolean;
+
+  /**
+   * ELK partition per node id. Nodes are banded by `partition` — ELK places all
+   * of partition 0, then partition 1, etc., in the layout direction — so a
+   * group of nodes can be kept apart from the rest without nesting them in a
+   * parent. C4 uses this to push out-of-boundary nodes (external systems,
+   * people) into their own band, away from the framed containers.
+   *
+   * Requires every laid-out node to have a partition; unknown ids are ignored,
+   * unlisted nodes get partition 0. @default undefined (partitioning off)
+   */
+  partitionByNode?: ReadonlyMap<string, number>;
 }
 
 /** Result of ELK layout computation */
@@ -397,7 +441,7 @@ export function fractionAlongPath(points: Point[], at: Point): number {
 /**
  * Get ELK layout options based on configuration
  */
-function getElkOptions(options: ElkLayoutOptions): LayoutOptions {
+export function getElkOptions(options: ElkLayoutOptions): LayoutOptions {
   const {
     routingStyle = 'orthogonal',
     nodeSpacing = 50,
@@ -421,6 +465,12 @@ function getElkOptions(options: ElkLayoutOptions): LayoutOptions {
     'elk.spacing.edgeNode': String(edgeNodeSpacing),
     'elk.layered.spacing.edgeEdgeBetweenLayers': String(edgeSpacing),
     'elk.layered.spacing.edgeNodeBetweenLayers': String(edgeNodeSpacing),
+    // Edges host inline labels and `CENTER_LAYER` already reserves a label
+    // layer, so this is EXTRA space stacked on top of that layer — not a
+    // replacement for it. Reserving the full label box here double-counts and
+    // the run balloons (measured: w=140 + 204 here = 548px between two nodes).
+    // `interLayerSpacing` is the only caller-set value; otherwise this is the
+    // small clearance the label layer can't express.
     'elk.layered.spacing.nodeNodeBetweenLayers': String(interLayerSpacing),
     // Port constraints - edges connect at specific sides
     'elk.portConstraints': 'FIXED_SIDE',
@@ -598,7 +648,12 @@ export async function computeElkLayout(
   edges: Edge[],
   options: ElkLayoutOptions = {}
 ): Promise<ElkLayoutResult> {
-  const { preserveNodePositions = true, keepSingletonGroups = false } = options;
+  const {
+    preserveNodePositions = true,
+    keepSingletonGroups = false,
+    flatGroups = false,
+    partitionByNode,
+  } = options;
   const edgeLabels = options.edgeLabels;
   const endpointInset = options.endpointInset ?? 0;
   const direction = options.direction ?? 'RIGHT';
@@ -648,6 +703,7 @@ export async function computeElkLayout(
       properties: {
         'portConstraints': 'FIXED_SIDE',
         ...(layer !== undefined ? { 'layering.layer': String(layer) } : {}),
+        ...(partitionByNode ? { partition: String(partitionByNode.get(node.id) ?? 0) } : {}),
       },
     };
   });
@@ -745,11 +801,20 @@ export async function computeElkLayout(
       sources: [sourcePort],
       targets: [targetPort],
     };
-    // Reserve the fixed label box so ELK leaves the same room for every label,
-    // regardless of text length. The overlay renders into this exact box.
+    // Reserve the label box. ELK's `CENTER_LAYER` sizes a dedicated label layer
+    // from this and adds no clearance of its own, so the box carries the chip
+    // width PLUS the clearance we want on each side — that is the only place
+    // the side padding can take effect. The overlay draws the chip at the
+    // narrower `edgeLabels.width`, centred in this reserved run.
     if (edgeLabels?.enabled !== false && typeof edge.label === 'string') {
+      const chipWidth =
+        edgeLabels?.measure?.(edge.label) ?? edgeLabels?.width ?? EDGE_LABEL_WIDTH;
       elkEdge.labels = [
-        { text: edge.label, width: EDGE_LABEL_WIDTH, height: EDGE_LABEL_HEIGHT },
+        {
+          text: edge.label,
+          width: chipWidth + EDGE_LABEL_SIDE_PADDING * 2,
+          height: edgeLabels?.height ?? EDGE_LABEL_HEIGHT,
+        },
       ];
     }
     return elkEdge;
@@ -778,7 +843,9 @@ export async function computeElkLayout(
     // the full reserved width (label box + clearance at each end); labels off
     // falls back to a plain between-layer gap.
     'elk.layered.spacing.nodeNodeBetweenLayers': String(
-      edgeLabels?.enabled === false ? 40 : EDGE_LABEL_EDGE_GAP,
+      edgeLabels?.enabled === false
+        ? 40
+        : (edgeLabels?.width ?? EDGE_LABEL_WIDTH) + EDGE_LABEL_SIDE_PADDING * 2,
     ),
   };
   // Match the root's inline-label reservation, so ELK inside the frame leaves a
@@ -793,7 +860,15 @@ export async function computeElkLayout(
   const plan = planCompoundGroups(groupDefs, elkById.keys(), keepSingletonGroups);
   const skippedGroups = new Set(plan.skipped);
   const builtGroups = new Map<string, ElkNode>();
+  // Flat groups are not ELK parents at all: their members lay out at the root,
+  // and the frame is synthesized from the members' bounds after layout. This
+  // keeps every edge on one spacing instead of inheriting a nested frame's.
+  const flatGroupIds = new Set<string>();
+  if (flatGroups) {
+    for (const g of plan.built) flatGroupIds.add(g.id);
+  }
   for (const g of plan.built) {
+    if (flatGroups) break;
     const children: ElkNode[] = [];
     for (const cid of g.childIds) {
       const leaf = elkById.get(cid);
@@ -857,6 +932,9 @@ export async function computeElkLayout(
 
   // Create ELK graph
   const rootOptions = getElkOptions(options);
+  if (partitionByNode) {
+    rootOptions['elk.partitioning.activate'] = 'true';
+  }
   if (elkParents.length > 0 || builtGroups.size > 0) {
     rootOptions['elk.hierarchyHandling'] = 'INCLUDE_CHILDREN';
   }
@@ -929,6 +1007,40 @@ export async function computeElkLayout(
     }
   }
 
+  // Flat groups: synthesize each frame from the bounding box of its members.
+  // `plan.built` is bottom-up, so a nested frame's bounds already exist when its
+  // parent is computed — a frame containing frames unions the child frames, not
+  // just leaves. Without that, an outer frame (the system) would omit the
+  // container frames inside it and mis-size.
+  if (flatGroupIds.size > 0) {
+    const FLAT_PAD = 24;
+    const FLAT_TOP = 64;
+    /** Absolute rect of a group member: a leaf rect, or an already-built frame. */
+    const rectOf = (id: string) =>
+      absoluteRects.get(id) ??
+      (() => {
+        const b = groupBounds.get(id);
+        return b ? { x: b.x, y: b.y, width: b.width, height: b.height } : undefined;
+      })();
+    for (const g of plan.built) {
+      if (!flatGroupIds.has(g.id)) continue;
+      const rects = g.childIds
+        .map(rectOf)
+        .filter((r): r is { x: number; y: number; width: number; height: number } => !!r);
+      if (rects.length === 0) continue;
+      const minX = Math.min(...rects.map((r) => r.x));
+      const minY = Math.min(...rects.map((r) => r.y));
+      const maxX = Math.max(...rects.map((r) => r.x + r.width));
+      const maxY = Math.max(...rects.map((r) => r.y + r.height));
+      groupBounds.set(g.id, {
+        x: minX - FLAT_PAD,
+        y: minY - FLAT_TOP,
+        width: maxX - minX + FLAT_PAD * 2,
+        height: maxY - minY + FLAT_TOP + FLAT_PAD,
+      });
+    }
+  }
+
   // Extract results
   const edgePaths = new Map<string, string>();
   const edgeLabelPositions = new Map<string, { x: number; y: number }>();