@statelyai/layout 0.4.3 → 0.5.1

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";
@@ -72,6 +74,24 @@ const modelSweepInputs = new WeakSet<LayeredPhaseInput>();
 
 const nodeRelativePortRanksByInput = new WeakMap<LayeredPhaseInput, boolean>();
 
+const labelPortSideFeedbackByInput = new WeakMap<
+  LayeredPhaseInput,
+  { exempt: ReadonlySet<string>; routed: Set<string> }
+>();
+
+/**
+ * @internal Collect the feedback segments routed to a center-label dummy's port
+ * sides. Exempt segments keep the plain feedback detour instead.
+ */
+export function trackLabelPortSideFeedback(
+  input: LayeredPhaseInput,
+  exempt: ReadonlySet<string>,
+): ReadonlySet<string> {
+  const routed = new Set<string>();
+  labelPortSideFeedbackByInput.set(input, { exempt, routed });
+  return routed;
+}
+
 function getOrientedEndpoints(
   edge: GraphEdge,
   orientation: AcyclicOrientation,
@@ -1794,6 +1814,8 @@ function sortLayerByAdjacentPosition(
   sameLayerNeighbors: ReadonlyMap<string, readonly string[]> = new Map(),
   orderedVisits?: ReadonlyMap<string, readonly (number | string)[]>,
   forcedCompare?: (left: string, right: string) => number,
+  /** Nodes ELK's forced model-order comparator ties with everything. */
+  forcedTies?: ReadonlySet<string>,
 ): void {
   const originalIndex = new Map(layer.map((nodeId, index) => [nodeId, index] as const));
   const adjacentPosition = new Map<string, number | undefined>();
@@ -1870,6 +1892,7 @@ function sortLayerByAdjacentPosition(
   }
 
   const compare = (a: string, b: string) => {
+    if (forcedTies?.has(a) || forcedTies?.has(b)) return 0;
     return (
       forcedCompare?.(a, b) ||
       (adjacentPosition.get(a) ?? 0) - (adjacentPosition.get(b) ?? 0) ||
@@ -2185,6 +2208,18 @@ export function createLayerSweepSession(
     usesInitialModelOrder && input.settings["crossingMinimization.forceNodeModelOrder"] === true
       ? normalModelComparator(input)
       : undefined;
+  // ELK's forced comparator returns 0 for separate-layer nodes before
+  // consulting barycenters, so insertion sort never moves past them.
+  const forcedTies = forcedCompare
+    ? new Set(
+        input.graph.nodes
+          .filter((node) => {
+            const constraint = input.nodeSettings?.(node)?.["layering.layerConstraint"];
+            return constraint === "FIRST_SEPARATE" || constraint === "LAST_SEPARATE";
+          })
+          .map((node) => node.id),
+      )
+    : undefined;
   const usePortRanks = true;
   const medianWeights = new Map<string, number>();
   const listedEdgeIds = new Map<string, string>();
@@ -2440,8 +2475,10 @@ export function createLayerSweepSession(
       (working[firstLayerIndex] ?? []).map((id) => [id, random.nextDouble()]),
     );
     const compare = (left: string, right: string) =>
-      forcedCompare?.(left, right) ||
-      (firstLayerWeights.get(left) ?? 0) - (firstLayerWeights.get(right) ?? 0);
+      forcedTies?.has(left) || forcedTies?.has(right)
+        ? 0
+        : forcedCompare?.(left, right) ||
+          (firstLayerWeights.get(left) ?? 0) - (firstLayerWeights.get(right) ?? 0);
     const first = working[firstLayerIndex];
     if (first) {
       if (forcedCompare)
@@ -2596,6 +2633,7 @@ export function createLayerSweepSession(
               sameLayerNeighbors(isForward),
               adjacent.visits,
               forcedCompare,
+              forcedTies,
             );
           }
           groupMixedPortDirections(current, previous, working[layer + 1]);
@@ -2625,6 +2663,7 @@ export function createLayerSweepSession(
               sameLayerNeighbors(isForward),
               adjacent.visits,
               forcedCompare,
+              forcedTies,
             );
           }
           groupMixedPortDirections(current, next, working[layer - 1]);
@@ -4300,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 (
@@ -4405,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";
@@ -5845,6 +5882,25 @@ function routeEdges(style: "ORTHOGONAL" | "POLYLINE" | "SPLINES"): EdgeRouter {
               input,
             )
           : targetFallback;
+        // A reversed chain enters a center-label dummy through its forward-side
+        // port and leaves through its backward-side port: route to those sides.
+        const [forwardSide, backwardSide] = (
+          {
+            right: ["EAST", "WEST"],
+            left: ["WEST", "EAST"],
+            down: ["SOUTH", "NORTH"],
+            up: ["NORTH", "SOUTH"],
+          } as const
+        )[input.direction];
+        const labelPortSides = labelPortSideFeedbackByInput.get(input);
+        const faces = (node: GraphNode, side: unknown, away: string) =>
+          !fixedSideFeedback &&
+          !labelPortSides?.exempt.has(edge.id) &&
+          node.id.startsWith("__layout_dummy:label:") &&
+          side === away;
+        const sourceFace = faces(source, feedbackSourcePortSide, backwardSide) ? -1 : 1;
+        const targetFace = faces(target, feedbackTargetPortSide, forwardSide) ? -1 : 1;
+        if (sourceFace < 0 || targetFace < 0) labelPortSides?.routed.add(edge.id);
         if (horizontal) {
           const sign = fixedSideFeedback
             ? Math.sign(sourceRect.x - targetRect.x) || 1
@@ -5859,16 +5915,16 @@ function routeEdges(style: "ORTHOGONAL" | "POLYLINE" | "SPLINES"): EdgeRouter {
             fixedSideFeedback && input.settings.unnecessaryBendpoints === true;
           pointsByEdgeId.set(edge.id, [
             start,
-            { x: start.x + sign * flowSpacing, y: start.y },
-            { x: start.x + sign * flowSpacing, y: outerCross },
+            { x: start.x + sourceFace * sign * flowSpacing, y: start.y },
+            { x: start.x + sourceFace * sign * flowSpacing, y: outerCross },
             ...(preserveCenters
               ? [
                   { x: sourceRect.x + sourceRect.width / 2, y: outerCross },
                   { x: targetRect.x + targetRect.width / 2, y: outerCross },
                 ]
               : []),
-            { x: end.x - sign * flowSpacing, y: outerCross },
-            { x: end.x - sign * flowSpacing, y: end.y },
+            { x: end.x - targetFace * sign * flowSpacing, y: outerCross },
+            { x: end.x - targetFace * sign * flowSpacing, y: end.y },
             end,
           ]);
         } else {
@@ -5885,16 +5941,16 @@ function routeEdges(style: "ORTHOGONAL" | "POLYLINE" | "SPLINES"): EdgeRouter {
             fixedSideFeedback && input.settings.unnecessaryBendpoints === true;
           pointsByEdgeId.set(edge.id, [
             start,
-            { x: start.x, y: start.y + sign * flowSpacing },
-            { x: outerCross, y: start.y + sign * flowSpacing },
+            { x: start.x, y: start.y + sourceFace * sign * flowSpacing },
+            { x: outerCross, y: start.y + sourceFace * sign * flowSpacing },
             ...(preserveCenters
               ? [
                   { x: outerCross, y: sourceRect.y + sourceRect.height / 2 },
                   { x: outerCross, y: targetRect.y + targetRect.height / 2 },
                 ]
               : []),
-            { x: outerCross, y: end.y - sign * flowSpacing },
-            { x: end.x, y: end.y - sign * flowSpacing },
+            { x: outerCross, y: end.y - targetFace * sign * flowSpacing },
+            { x: end.x, y: end.y - targetFace * sign * flowSpacing },
             end,
           ]);
         }
@@ -6090,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
@@ -6144,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 = {
@@ -6168,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;
@@ -6528,6 +6607,67 @@ export const routeEdgesOrthogonally = routeEdges("ORTHOGONAL");
 export const routeEdgesWithPolylines = routeEdges("POLYLINE");
 export const routeEdgesWithSplines = routeEdges("SPLINES");
 
+type PortSide = "NORTH" | "SOUTH" | "WEST" | "EAST";
+const sweptPortRanks = new WeakMap<
+  readonly GraphPort<unknown>[],
+  (port: GraphPort<unknown>, side: PortSide) => number | undefined
+>();
+
+/**
+ * Order movable ports along each physical side as crossing minimization left
+ * them, as ELK places ports from its swept port lists. The lists are
+ * clockwise per canonical side.
+ */
+export function recordSweptPortOrder(
+  graph: Pick<LayeredPhaseInput["graph"], "nodes" | "edges">,
+  direction: LayeredPhaseInput["direction"],
+  order: LayerOrder,
+): void {
+  // Unconnected ports carry no swept decision.
+  const connected = new Set(
+    graph.edges.flatMap((edge) => [
+      JSON.stringify([edge.sourceId, edge.sourcePort]),
+      JSON.stringify([edge.targetId, edge.targetPort]),
+    ]),
+  );
+  const vertical = direction === "down" || direction === "up";
+  const reverse = direction === "up" || direction === "left";
+  const canonical: Record<PortSide, PortSide> =
+    direction === "right"
+      ? { NORTH: "NORTH", EAST: "EAST", SOUTH: "SOUTH", WEST: "WEST" }
+      : direction === "left"
+        ? { NORTH: "NORTH", EAST: "WEST", SOUTH: "SOUTH", WEST: "EAST" }
+        : direction === "down"
+          ? { NORTH: "WEST", EAST: "SOUTH", SOUTH: "EAST", WEST: "NORTH" }
+          : { NORTH: "EAST", EAST: "SOUTH", SOUTH: "WEST", WEST: "NORTH" };
+  for (const node of graph.nodes) {
+    if (!node.ports) continue;
+    const swept = order.physicalPortOrderByNodeId?.get(node.id);
+    if (!swept) {
+      sweptPortRanks.delete(node.ports);
+      continue;
+    }
+    const index = new Map(swept.flatMap((id, i) => (connected.has(id) ? [[id, i] as const] : [])));
+    const rankByPort = new Map(
+      node.ports.map((port) => [port, index.get(JSON.stringify([node.id, port.name]))]),
+    );
+    sweptPortRanks.set(node.ports, (port, side) => {
+      const rank = rankByPort.get(port);
+      if (rank === undefined) return undefined;
+      // Canonical clockwise ranks rise with the flow coordinate on NORTH,
+      // with the cross coordinate on EAST, and fall on SOUTH and WEST.
+      const alongFlow = (side === "NORTH" || side === "SOUTH") !== vertical;
+      const c = canonical[side];
+      const sign = alongFlow
+        ? (c === "NORTH" ? 1 : -1) * (reverse ? -1 : 1)
+        : c === "EAST"
+          ? 1
+          : -1;
+      return sign * rank;
+    });
+  }
+}
+
 export function placePorts<P>(
   ports: readonly GraphPort<P>[] | undefined,
   rect: EntityRect,
@@ -6573,13 +6713,24 @@ export function placePorts<P>(
     group.push(port);
     grouped.set(side, group);
   }
+  const swept =
+    constraints === "FIXED_ORDER" || constraints === "FIXED_POS" || constraints === "FIXED_RATIO"
+      ? undefined
+      : sweptPortRanks.get(ports as readonly GraphPort<unknown>[]);
   for (const group of grouped.values()) {
-    group.sort(
-      (left, right) =>
-        Number(portSettings?.(left)?.["port.index"] ?? ports.indexOf(left)) -
-        Number(portSettings?.(right)?.["port.index"] ?? ports.indexOf(right)),
-    );
     const side = sideByPort.get(group[0]!);
+    const ranks = swept && group.map((port) => swept(port as GraphPort<unknown>, side!));
+    const ranked =
+      ranks?.every((rank) => rank !== undefined) &&
+      group.every((port) => portSettings?.(port)?.["port.index"] === undefined)
+        ? new Map(group.map((port, i) => [port, ranks[i]!]))
+        : undefined;
+    group.sort((left, right) =>
+      ranked
+        ? ranked.get(left)! - ranked.get(right)!
+        : Number(portSettings?.(left)?.["port.index"] ?? ports.indexOf(left)) -
+          Number(portSettings?.(right)?.["port.index"] ?? ports.indexOf(right)),
+    );
     if (constraints === "FIXED_ORDER" && (side === "SOUTH" || side === "WEST")) {
       group.reverse();
     }