@statelyai/layout 0.5.0 → 0.5.2

package/src/layered/loop-envelopes.ts

@@ -8,6 +8,86 @@ import {
   selfLoopTracks,
 } from "./fixed-self-loop";
 import { findNode } from "./node-lookup";
+import { hiddenLoopPorts } from "./self-loop-ports";
+
+type CanonicalSide = "NORTH" | "SOUTH" | "EAST" | "WEST";
+const crossSide = (side: CanonicalSide) => side === "NORTH" || side === "SOUTH";
+
+/**
+ * Extents of a movable loop's hidden ports in the canonical rightward frame:
+ * along its side, and protruding from it.
+ */
+function loopPortExtents(input: LayeredPhaseInput, edge: GraphEdge, side: CanonicalSide) {
+  const ports = hiddenLoopPorts(input.settings, edge.id);
+  const horizontal = input.direction === "right" || input.direction === "left";
+  const along = (crossSide(side) === horizontal ? "width" : "height") as "width" | "height";
+  const normal = along === "width" ? "height" : "width";
+  return {
+    along: ports ? ports.source[along] + ports.target[along] : 0,
+    normal: ports ? Math.max(ports.source[normal], ports.target[normal]) : 0,
+  };
+}
+
+/** A movable loop's label extent away from its side, in the canonical frame. */
+export function movableLoopLabelExtent(
+  input: LayeredPhaseInput,
+  edge: GraphEdge,
+  side: CanonicalSide,
+): number {
+  const horizontal = input.direction === "right" || input.direction === "left";
+  const size = (crossSide(side) === horizontal ? edge.height : edge.width) ?? 0;
+  return size > 0 ? size + Number(input.settings["spacing.edgeLabel"] ?? 2) : 0;
+}
+
+/**
+ * ELK's OrthogonalSelfLoopRouter routing slot of a movable loop, measured
+ * from its node side in the canonical frame: past the protruding ports and
+ * the self-loop spacing, then one edge spacing plus any label per inner slot.
+ */
+export function movableLoopTrack(
+  input: LayeredPhaseInput,
+  sideLoops: readonly GraphEdge[],
+  edge: GraphEdge,
+  side: CanonicalSide,
+  ordering: string,
+): number {
+  const ordered = ordering === "REVERSE_STACKED" ? [...sideLoops].reverse() : sideLoops;
+  const inner = ordering === "SEQUENCED" ? [] : ordered.slice(0, ordered.indexOf(edge));
+  const edgeSpacing = Number(input.settings["spacing.edgeEdge"] ?? 10);
+  return (
+    Math.max(0, ...sideLoops.map((loop) => loopPortExtents(input, loop, side).normal)) +
+    Number(input.settings["spacing.nodeSelfLoop"] ?? 10) +
+    inner.reduce(
+      (sum, loop) =>
+        sum + edgeSpacing + (crossSide(side) ? movableLoopLabelExtent(input, loop, side) : 0),
+      0,
+    )
+  );
+}
+
+/**
+ * Canonical position of a movable loop port along its side, given its
+ * DISTRIBUTED ratio among the side's implicit ports (ELK's port placement
+ * with equal gaps between hidden ports of their own size).
+ */
+export function movableLoopPortOffset(
+  input: LayeredPhaseInput,
+  sideLoops: readonly GraphEdge[],
+  side: CanonicalSide,
+  length: number,
+  ratio: number,
+): { along: number; normal: number } {
+  const count = sideLoops.length * 2;
+  const extents = sideLoops.map((loop) => loopPortExtents(input, loop, side));
+  const total = extents.reduce((sum, extent) => sum + extent.along, 0);
+  const size = total / count;
+  const index = Math.round(ratio * (count + 1)) - 1;
+  const gap = (length - total) / (count + 1);
+  return {
+    along: gap * (index + 1) + size * index + size / 2,
+    normal: Math.max(0, ...extents.map((extent) => extent.normal)),
+  };
+}
 
 export interface LoopEnvelope {
   before: number;
@@ -125,18 +205,10 @@ export function loopEnvelopes(input: LayeredPhaseInput): ReadonlyMap<string, Loo
       }
     }
     const loops = allLoops.filter((edge) => hasMovableLoopPorts(input, edge));
-    // Inline labels remain owned by the existing labeled-loop phase. Move
-    // the entire node together when that phase is ported, rather than mixing
-    // two different loop distributions and reservations on the same node.
-    if (
-      loops.length === 0 ||
-      loops.some((edge) => input.edgeSettings?.(edge)?.["edgeLabels.inline"] === true)
-    )
-      continue;
+    if (loops.length === 0) continue;
     const settings = input.nodeSettings?.(node);
     const distribution = settings?.["edgeRouting.selfLoopDistribution"] ?? "NORTH";
     const ordering = settings?.["edgeRouting.selfLoopOrdering"] ?? "STACKED";
-    const spacing = Number(input.settings["spacing.nodeSelfLoop"] ?? 10);
     const envelope = { before: 0, after: 0, flowBefore: 0, flowAfter: 0 };
     const sides =
       distribution === "EQUALLY"
@@ -144,25 +216,34 @@ export function loopEnvelopes(input: LayeredPhaseInput): ReadonlyMap<string, Loo
         : distribution === "NORTH_SOUTH"
           ? (["before", "after"] as const)
           : (["before"] as const);
+    const canonicalSides = {
+      before: "NORTH",
+      after: "SOUTH",
+      flowAfter: "EAST",
+      flowBefore: "WEST",
+    } as const;
+    const horizontal = input.direction === "right" || input.direction === "left";
+    const size = input.sizes.get(node.id) ?? { width: 0, height: 0 };
+    const flowSize = horizontal ? size.width : size.height;
     for (const side of sides) {
       const selected = loops.filter((_, index) => sides[index % sides.length] === side);
-      const horizontal = input.direction === "right" || input.direction === "left";
-      const crossSize =
-        side === "before" || side === "after"
-          ? horizontal
-            ? "height"
-            : "width"
-          : horizontal
-            ? "width"
-            : "height";
-      const labelSpacing = Number(input.settings["spacing.edgeLabel"] ?? 2);
-      envelope[side] =
-        spacing * (ordering === "SEQUENCED" ? Math.min(1, selected.length) : selected.length) +
-        selected.reduce(
-          (sum, edge) =>
-            sum + ((edge[crossSize] ?? 0) > 0 ? (edge[crossSize] ?? 0) + labelSpacing : 0),
-          0,
-        );
+      const canonical = canonicalSides[side];
+      envelope[side] = Math.max(
+        envelope[side],
+        ...selected.map(
+          (edge) =>
+            movableLoopTrack(input, selected, edge, canonical, ordering) +
+            movableLoopLabelExtent(input, edge, canonical),
+        ),
+      );
+      if (!crossSide(canonical)) continue;
+      // ELK centers cross-side loop labels on their node along the flow, and
+      // a label longer than its node widens the node's layer by the overhang.
+      for (const edge of selected) {
+        const overhang = ((horizontal ? edge.width : edge.height) ?? 0) - flowSize;
+        envelope.flowBefore = Math.max(envelope.flowBefore, overhang / 2);
+        envelope.flowAfter = Math.max(envelope.flowAfter, overhang / 2);
+      }
     }
     envelopes.set(node.id, envelope);
   }

package/src/layered/self-loop-ports.ts

@@ -0,0 +1,158 @@
+/* ELK self-loop port hiding and restoration. SPDX-License-Identifier: EPL-2.0 */
+import type { Graph, GraphEdge, GraphPort, Point, VisualGraph, VisualPort } from "@statelyai/graph";
+import type { LayeredLayoutOptions } from "./index";
+
+interface PortSize {
+  width: number;
+  height: number;
+}
+export interface HiddenLoopPorts {
+  source: PortSize;
+  target: PortSize;
+}
+
+const hiddenBySettings = new WeakMap<object, ReadonlyMap<string, HiddenLoopPorts>>();
+
+/** Sizes of the ports SelfLoopPreProcessor hid from a loop, if any. */
+export function hiddenLoopPorts(settings: object, edgeId: string): HiddenLoopPorts | undefined {
+  return hiddenBySettings.get(settings)?.get(edgeId);
+}
+
+/**
+ * ELK's SelfLoopPreProcessor removes ports that carry only self loops from
+ * nodes whose port order is not fixed, and SelfLoopPortRestorer later puts
+ * them on the loop's side. The layered phases then see implicit loop ports;
+ * {@link restoreSelfLoopPorts} places the hidden ports at the loop ends.
+ */
+export function hideSelfLoopPorts<N, E, G, P>(
+  graph: Graph<N, E, G, P>,
+  options: LayeredLayoutOptions,
+):
+  | {
+      graph: Graph<N, E, G, P>;
+      options: LayeredLayoutOptions;
+      edges: ReadonlyMap<string, GraphEdge<E>>;
+    }
+  | undefined {
+  const uses = new Map<string, number>();
+  const nonLoop = new Set<string>();
+  for (const edge of graph.edges) {
+    for (const [node, port] of [
+      [edge.sourceId, edge.sourcePort],
+      [edge.targetId, edge.targetPort],
+    ] as const) {
+      if (port === undefined) continue;
+      const key = `${node}\0${port}`;
+      uses.set(key, (uses.get(key) ?? 0) + 1);
+      if (edge.sourceId !== edge.targetId) nonLoop.add(key);
+    }
+  }
+  const nodeById = new Map(graph.nodes.map((node) => [node.id, node]));
+  const hidden = new Map<string, HiddenLoopPorts>();
+  const edges = new Map<string, GraphEdge<E>>();
+  const hiddenPorts = new Set<string>();
+  for (const edge of graph.edges) {
+    if (
+      edge.sourceId !== edge.targetId ||
+      edge.sourcePort === undefined ||
+      edge.targetPort === undefined ||
+      edge.sourcePort === edge.targetPort
+    )
+      continue;
+    const node = nodeById.get(edge.sourceId);
+    const constraints = node && options.nodeSettings?.(node)?.portConstraints;
+    if (
+      !node ||
+      (constraints !== undefined && constraints !== "FREE" && constraints !== "UNDEFINED")
+    )
+      continue;
+    // One loop per port: shared ports would make a self hyperloop.
+    const ports = [edge.sourcePort, edge.targetPort].map((name) =>
+      node.ports?.find((port) => port.name === name),
+    );
+    if (
+      ports.some(
+        (port) =>
+          !port ||
+          uses.get(`${node.id}\0${port.name}`) !== 1 ||
+          nonLoop.has(`${node.id}\0${port.name}`),
+      )
+    )
+      continue;
+    const size = (port: GraphPort<P>) => ({ width: port.width ?? 0, height: port.height ?? 0 });
+    hidden.set(edge.id, { source: size(ports[0]!), target: size(ports[1]!) });
+    edges.set(edge.id, edge);
+    for (const port of ports) hiddenPorts.add(`${node.id}\0${port!.name}`);
+  }
+  if (hidden.size === 0) return undefined;
+  const settings = { ...options.settings };
+  hiddenBySettings.set(settings, hidden);
+  return {
+    graph: {
+      ...graph,
+      nodes: graph.nodes.map((node) =>
+        node.ports?.some((port) => hiddenPorts.has(`${node.id}\0${port.name}`))
+          ? {
+              ...node,
+              ports: node.ports.filter((port) => !hiddenPorts.has(`${node.id}\0${port.name}`)),
+            }
+          : node,
+      ),
+      edges: graph.edges.map((edge) =>
+        hidden.has(edge.id) ? { ...edge, sourcePort: undefined, targetPort: undefined } : edge,
+      ),
+    },
+    options: { ...options, settings },
+    edges,
+  };
+}
+
+/** Put hidden loop ports back, anchored on the side their loop leaves from. */
+export function restoreSelfLoopPorts<N, E, G, P>(
+  graph: Graph<N, E, G, P>,
+  result: VisualGraph<N, E, G, P>,
+  edges: ReadonlyMap<string, GraphEdge<E>>,
+): VisualGraph<N, E, G, P> {
+  const anchors = new Map<string, Point>();
+  for (const edge of result.edges) {
+    const original = edges.get(edge.id);
+    const points = edge.points;
+    if (!original || !points?.length) continue;
+    anchors.set(`${edge.sourceId}\0${original.sourcePort}`, points[0]!);
+    anchors.set(`${edge.targetId}\0${original.targetPort}`, points.at(-1)!);
+  }
+  const originalById = new Map(graph.nodes.map((node) => [node.id, node]));
+  return {
+    ...result,
+    nodes: result.nodes.map((node) => {
+      const original = originalById.get(node.id)?.ports;
+      if (!original?.some((port) => anchors.has(`${node.id}\0${port.name}`))) return node;
+      const placed = new Map(node.ports?.map((port) => [port.name, port]));
+      return {
+        ...node,
+        ports: original.map((port): VisualPort<P> => {
+          const anchor = anchors.get(`${node.id}\0${port.name}`);
+          const width = port.width ?? 0,
+            height = port.height ?? 0;
+          if (!anchor) return placed.get(port.name) ?? { ...port, width, height, x: 0, y: 0 };
+          const x = anchor.x - node.x,
+            y = anchor.y - node.y;
+          // The loop leaves from the port's outer border, centered on it.
+          return {
+            ...port,
+            width,
+            height,
+            x: x <= 0 ? x : x >= node.width ? x - width : x - width / 2,
+            y: x <= 0 || x >= node.width ? y - height / 2 : y <= 0 ? y : y - height,
+          };
+        }),
+      };
+    }),
+    edges: result.edges.map((edge) => {
+      const original = edges.get(edge.id);
+      return original
+        ? { ...edge, sourcePort: original.sourcePort, targetPort: original.targetPort }
+        : edge;
+    }),
+  };
+}

package/src/layered/strategies.ts

@@ -19,6 +19,8 @@ import { routingCoordinates } from "./routing-coordinates";
 import {
   hasMovableLoopPorts,
   hasPlacementLoopEnvelope,
+  movableLoopPortOffset,
+  movableLoopTrack,
   loopEnvelopes,
   preparedLoopEnvelopes,
 } from "./loop-envelopes";
@@ -4337,16 +4339,14 @@ function routeEdges(style: "ORTHOGONAL" | "POLYLINE" | "SPLINES"): EdgeRouter {
       edge: GraphEdge,
       side: string,
       ordering: string,
-      canonical = false,
     ): number => {
-      const crossSide = side === "NORTH" || side === "SOUTH";
-      const axis = crossSide === (!canonical || horizontal) ? "height" : "width";
+      const axis = side === "NORTH" || side === "SOUTH" ? "height" : "width";
       const ordered = ordering === "REVERSE_STACKED" ? [...loops].reverse() : loops;
       const index = ordered.indexOf(edge);
       const spacing = Number(input.settings["spacing.nodeSelfLoop"] ?? 10);
       const labelSpacing = Number(input.settings["spacing.edgeLabel"] ?? 2);
       const size = (candidate: GraphEdge) =>
-        canonical || input.edgeSettings?.(candidate)?.["edgeLabels.inline"] === true
+        input.edgeSettings?.(candidate)?.["edgeLabels.inline"] === true
           ? (candidate[axis] ?? 0)
           : 0;
       return (
@@ -4442,7 +4442,7 @@ function routeEdges(style: "ORTHOGONAL" | "POLYLINE" | "SPLINES"): EdgeRouter {
         for (const [id, loops] of selfLoopsByNodeId) {
           const rect = mutableRects.get(id);
           const node = nodeById.get(id);
-          if (!rect || !node) continue;
+          if (!rect || !node || hasPlacementLoopEnvelope(placement, id)) continue;
           const settings = input.nodeSettings?.(node);
           const distribution = settings?.["edgeRouting.selfLoopDistribution"] ?? "NORTH";
           const ordering = settings?.["edgeRouting.selfLoopOrdering"] ?? "STACKED";
@@ -6146,9 +6146,7 @@ function routeEdges(style: "ORTHOGONAL" | "POLYLINE" | "SPLINES"): EdgeRouter {
             continue;
           }
           const movable =
-            hasMovableLoopPorts(input, edge) &&
-            hasPlacementLoopEnvelope(placement, source.id) &&
-            input.edgeSettings?.(edge)?.["edgeLabels.inline"] !== true;
+            hasMovableLoopPorts(input, edge) && hasPlacementLoopEnvelope(placement, source.id);
           // Route unconstrained loops in the canonical rightward system, then
           // apply the same direction transform as the layer pipeline.
           const loopRect = movable
@@ -6200,7 +6198,21 @@ function routeEdges(style: "ORTHOGONAL" | "POLYLINE" | "SPLINES"): EdgeRouter {
             const sideLoops = loops.filter(
               (candidate, i) => loopSide(distribution, i, candidate) === side,
             );
-            const distance = loopDistance(sideLoops, edge, side, ordering, movable);
+            if (movable) {
+              const track = movableLoopTrack(input, sideLoops, edge, side, ordering);
+              const sign = side === "NORTH" ? -1 : 1;
+              const base = side === "NORTH" ? 0 : loopRect.height;
+              const [first, last] = [startRatio, endRatio].map((ratio) =>
+                movableLoopPortOffset(input, sideLoops, side, loopRect.width, ratio),
+              );
+              return [
+                { x: first!.along, y: base + sign * first!.normal },
+                { x: first!.along, y: base + sign * track },
+                { x: last!.along, y: base + sign * track },
+                { x: last!.along, y: base + sign * last!.normal },
+              ];
+            }
+            const distance = loopDistance(sideLoops, edge, side, ordering);
             const y =
               side === "NORTH" ? loopRect.y - distance : loopRect.y + loopRect.height + distance;
             const start = {
@@ -6224,15 +6236,26 @@ function routeEdges(style: "ORTHOGONAL" | "POLYLINE" | "SPLINES"): EdgeRouter {
             const secondRatio = sequenced ? 1 / denominator : 2 / denominator;
             const startRatio = side === "EAST" ? firstRatio : secondRatio;
             const endRatio = side === "EAST" ? secondRatio : firstRatio;
+            const sideLoops = loops.filter(
+              (candidate, i) => loopSide(distribution, i, candidate) === side,
+            );
+            if (movable) {
+              const track = movableLoopTrack(input, sideLoops, edge, side, ordering);
+              const sign = side === "WEST" ? -1 : 1;
+              const base = side === "WEST" ? 0 : loopRect.width;
+              const [first, last] = [startRatio, endRatio].map((ratio) =>
+                movableLoopPortOffset(input, sideLoops, side, loopRect.height, ratio),
+              );
+              return [
+                { x: base + sign * first!.normal, y: first!.along },
+                { x: base + sign * track, y: first!.along },
+                { x: base + sign * track, y: last!.along },
+                { x: base + sign * last!.normal, y: last!.along },
+              ];
+            }
             const distance =
-              movable || input.edgeSettings?.(edge)?.["edgeLabels.inline"] === true
-                ? loopDistance(
-                    loops.filter((candidate, i) => loopSide(distribution, i, candidate) === side),
-                    edge,
-                    side,
-                    ordering,
-                    movable,
-                  )
+              input.edgeSettings?.(edge)?.["edgeLabels.inline"] === true
+                ? loopDistance(sideLoops, edge, side, ordering)
                 : spacing * (indexOnSide + 1);
             const x =
               side === "EAST" ? loopRect.x + loopRect.width + distance : loopRect.x - distance;