@statelyai/layout 0.2.0 → 0.4.0

package/src/layered/port-distributor.ts

@@ -0,0 +1,192 @@
+/*
+ * Copyright (c) 2016, 2020 Kiel University and others.
+ * Native adaptation of ELK AbstractBarycenterPortDistributor,
+ * NodeRelativePortDistributor and LayerTotalPortDistributor.
+ * SPDX-License-Identifier: EPL-2.0
+ */
+import type { CrossingGraph, CrossingNode, CrossingPort } from "./crossing-counter";
+
+export interface PortDistributionState {
+  ranks: Record<string, number>;
+  barycenters: Record<string, number>;
+  positions: Record<string, number>;
+}
+export interface PortDistributionOptions {
+  nodeRelative: boolean;
+  fixedOrder: ReadonlySet<string>;
+  hierarchical: ReadonlySet<string>;
+}
+
+/** Stateful clockwise port distribution across successive layer sweeps. */
+export class CanonicalPortDistributor {
+  readonly state: PortDistributionState;
+  private topologyGraph?: CrossingGraph;
+  private owner = new Map<string, CrossingNode>();
+  private layerByPort = new Map<string, number>();
+  private nodes = new Map<string, CrossingNode>();
+  private incoming = new Map<string, string[]>();
+  private outgoing = new Map<string, string[]>();
+  constructor(graph: CrossingGraph, state?: PortDistributionState) {
+    this.state = state ? structuredClone(state) : { ranks: {}, barycenters: {}, positions: {} };
+    for (const layer of graph.layers)
+      for (const [position, node] of layer.entries()) {
+        this.state.positions[node.id] ??= position;
+        for (const port of node.ports) {
+          this.state.ranks[port.id] ??= 0;
+          this.state.barycenters[port.id] ??= 0;
+        }
+      }
+  }
+
+  private prepareTopology(graph: CrossingGraph): void {
+    // Sweeps reorder nodes within their layers; connectivity stays constant.
+    // A restored graph object invalidates the topology once, not per layer.
+    if (this.topologyGraph !== graph) {
+      this.topologyGraph = graph;
+      this.owner.clear();
+      this.layerByPort.clear();
+      this.nodes.clear();
+      this.incoming.clear();
+      this.outgoing.clear();
+      for (const [layer, members] of graph.layers.entries())
+        for (const node of members) {
+          this.nodes.set(node.id, node);
+          for (const port of node.ports) {
+            this.owner.set(port.id, node);
+            this.layerByPort.set(port.id, layer);
+            this.incoming.set(port.id, []);
+            this.outgoing.set(port.id, []);
+          }
+        }
+      for (const edge of graph.edges) {
+        this.incoming.get(edge.target)!.push(edge.source);
+        this.outgoing.get(edge.source)!.push(edge.target);
+      }
+    }
+  }
+
+  calculatePortRanks(
+    graph: CrossingGraph,
+    layer: readonly CrossingNode[],
+    input: boolean,
+    nodeRelative: boolean,
+  ): void {
+    this.prepareTopology(graph);
+    let consumed = 0;
+    for (const node of layer) {
+      const ports = node.ports.filter(
+        (port) => (input ? this.incoming : this.outgoing).get(port.id)!.length > 0,
+      );
+      const increment = nodeRelative ? 1 / (ports.length + 1) : 1;
+      if (input) {
+        let north = consumed + ports.filter((port) => port.side === "NORTH").length * increment;
+        let rest = nodeRelative ? consumed + 1 - increment : consumed + ports.length;
+        for (const port of ports) {
+          this.state.ranks[port.id] = port.side === "NORTH" ? north : rest;
+          if (port.side === "NORTH") north -= increment;
+          else rest -= increment;
+        }
+      } else {
+        let position = consumed + increment;
+        for (const port of ports) {
+          this.state.ranks[port.id] = position;
+          position += increment;
+        }
+      }
+      consumed += nodeRelative ? 1 : ports.length;
+    }
+  }
+
+  distribute(
+    graph: CrossingGraph,
+    index: number,
+    forward: boolean,
+    options: PortDistributionOptions,
+  ): void {
+    this.prepareTopology(graph);
+    const { owner, layerByPort, nodes, incoming, outgoing } = this;
+    const degree = (port: string) => incoming.get(port)!.length + outgoing.get(port)!.length;
+    const ranks = (layer: CrossingNode[], input: boolean) =>
+      this.calculatePortRanks(graph, layer, input, options.nodeRelative);
+    const distributeNode = (node: CrossingNode, side: "EAST" | "WEST") => {
+      if (options.fixedOrder.has(node.id)) return;
+      const layerIndex = node.ports.length ? layerByPort.get(node.ports[0]!.id)! : index;
+      const size = graph.layers[layerIndex]!.length;
+      for (const face of [side, "SOUTH", "NORTH"] as const) {
+        let minimum = 0,
+          maximum = 0;
+        const inLayer: CrossingPort[] = [];
+        for (const port of node.ports.filter((port) => port.side === face)) {
+          let sum = 0;
+          const cross = port.side === "NORTH" || port.side === "SOUTH";
+          if (cross) {
+            if (!port.dummy) continue;
+            const dummy = nodes.get(port.dummy)!;
+            let input = false,
+              output = false;
+            for (const peer of dummy.ports) {
+              if (peer.origin !== port.id) continue;
+              if (outgoing.get(peer.id)!.length) output = true;
+              else if (incoming.get(peer.id)!.length) input = true;
+            }
+            const position = this.state.positions[dummy.id]!;
+            const large = 2 * size + 1;
+            if (input && !output) sum += port.side === "NORTH" ? -position : large - position;
+            else if (output && !input) sum += position + 1;
+            else if (input && output) sum += port.side === "NORTH" ? 0 : large / 2;
+          } else {
+            const peers = [...outgoing.get(port.id)!, ...incoming.get(port.id)!];
+            if (peers.some((peer) => layerByPort.get(peer) === layerIndex)) {
+              inLayer.push(port);
+              continue;
+            }
+            for (const peer of outgoing.get(port.id)!) sum += this.state.ranks[peer]!;
+            for (const peer of incoming.get(port.id)!) sum -= this.state.ranks[peer]!;
+          }
+          if (degree(port.id)) {
+            const value = sum / degree(port.id);
+            this.state.barycenters[port.id] = value;
+            minimum = Math.min(minimum, value);
+            maximum = Math.max(maximum, value);
+          } else if (cross) this.state.barycenters[port.id] = sum;
+        }
+        for (const port of inLayer) {
+          const peers = [...incoming.get(port.id)!, ...outgoing.get(port.id)!].filter(
+            (peer) => layerByPort.get(peer) === layerIndex,
+          );
+          const value =
+            peers.reduce((sum, peer) => sum + this.state.positions[owner.get(peer)!.id]! + 1, 0) /
+            peers.length;
+          const above = value < this.state.positions[node.id]! + 1;
+          this.state.barycenters[port.id] =
+            port.side === "EAST"
+              ? above
+                ? minimum - value
+                : maximum + (size + 1 - value)
+              : above
+                ? maximum + value
+                : minimum - (size + 1 - value);
+        }
+      }
+      const sideRank = { NORTH: 0, EAST: 1, SOUTH: 2, WEST: 3 };
+      node.ports.sort((a, b) => {
+        const side = sideRank[a.side] - sideRank[b.side];
+        if (side) return side;
+        const left = this.state.barycenters[a.id]!,
+          right = this.state.barycenters[b.id]!;
+        return left === 0 && right === 0 ? 0 : left === 0 ? -1 : right === 0 ? 1 : left - right;
+      });
+    };
+    const free = graph.layers[index]!;
+    for (const [position, node] of free.entries()) this.state.positions[node.id] = position;
+    const side = forward ? "WEST" : "EAST";
+    const fixed = graph.layers[index + (forward ? -1 : 1)];
+    if (fixed) {
+      ranks(fixed, !forward);
+      for (const node of free) distributeNode(node, side);
+      ranks(free, forward);
+      for (const node of fixed)
+        if (!options.hierarchical.has(node.id)) distributeNode(node, forward ? "EAST" : "WEST");
+    } else for (const node of free) distributeNode(node, side);
+  }
+}

package/src/layered/port-edge-order.ts

@@ -0,0 +1,20 @@
+import type { GraphEdge } from "@statelyai/graph";
+import type { LayeredPhaseInput } from "./types";
+
+/** ELK traverses connected edges through the node's port list, preserving each port's edge order. */
+export function connectedEdgesInPortOrder(input: LayeredPhaseInput, nodeId: string): GraphEdge[] {
+  const node = input.graph.nodes.find((candidate) => candidate.id === nodeId);
+  const portRank = new Map(node?.ports?.map((port, index) => [port.name, index]));
+  const explicitCount = portRank.size;
+  return input.graph.edges
+    .map((edge, index) => ({ edge, index }))
+    .filter(({ edge }) => edge.sourceId === nodeId || edge.targetId === nodeId)
+    .sort((a, b) => {
+      const rank = ({ edge, index }: { edge: GraphEdge; index: number }) => {
+        const port = edge.sourceId === nodeId ? edge.sourcePort : edge.targetPort;
+        return (port === undefined ? undefined : portRank.get(port)) ?? explicitCount + index;
+      };
+      return rank(a) - rank(b) || a.index - b.index;
+    })
+    .map(({ edge }) => edge);
+}

package/src/layered/replace-routing.ts

@@ -0,0 +1,45 @@
+import { worldGeometry } from "../authoring/coordinates";
+import { routeToPoints } from "../routing/adapters";
+import { recordRouteGeometry } from "../routing/layout-cache";
+import type { CompoundVisualGraph } from "./compound";
+import type { LayeredLayoutOptions } from "./types";
+
+/** Run a replacement on finalized geometry, with no initial route hints. */
+export function replaceLayoutRouting<N, E, G, P>(
+  graph: CompoundVisualGraph<N, E, G, P>,
+  options: LayeredLayoutOptions,
+): CompoundVisualGraph<N, E, G, P> {
+  if (!options.routing) return graph;
+  const { compoundRoutes: _routes, compoundGeometry: _geometry, ...geometry } = graph;
+  const world = worldGeometry(geometry);
+  const input = {
+    ...geometry,
+    nodes: world.nodes.map((n) => ({ ...n, ports: n.ports?.map((p) => ({ ...p })) })),
+    edges: world.edges.map(({ points: _points, routing: _routing, ...e }) => e),
+  };
+  const snapshot = options.routing.strategy.route(input, {
+    ...options.routing.settings,
+    coordinateSpace: "world",
+  });
+  if (snapshot instanceof Promise)
+    throw new TypeError(
+      "Layered route replacement must be synchronous; run async routing separately",
+    );
+  if (
+    snapshot.routes.size !== graph.edges.length ||
+    graph.edges.some((e) => !snapshot.routes.has(e.id))
+  )
+    throw new Error("Replacement router must return exactly one route for every edge");
+  const result = {
+    ...graph,
+    edgeCoordinateSpace: "world" as const,
+    edges: graph.edges.map((edge) => ({
+      ...edge,
+      points: routeToPoints(snapshot.routes.get(edge.id)!),
+      routing: "polyline" as const,
+    })),
+    compoundRoutes: snapshot.routes,
+  };
+  recordRouteGeometry(result, result.compoundRoutes);
+  return result;
+}

package/src/layered/routing-coordinates.ts

@@ -0,0 +1,32 @@
+import type { NodePlacement } from "./types";
+
+// ELK routes in the node placer's coordinate space, before graph-padding normalization.
+const coordinateSpaces = new WeakMap<
+  NodePlacement,
+  { raw: NodePlacement; normalized: NodePlacement }
+>();
+
+export function recordRoutingCoordinates(placement: NodePlacement, raw: NodePlacement): void {
+  coordinateSpaces.set(placement, {
+    raw,
+    normalized: { rectByNodeId: new Map(placement.rectByNodeId) },
+  });
+}
+
+export function routingCoordinates(placement: NodePlacement): NodePlacement {
+  const spaces = coordinateSpaces.get(placement);
+  if (!spaces) return placement;
+  return {
+    rectByNodeId: new Map(
+      [...placement.rectByNodeId].map(([id, rect]) => {
+        const original = spaces.normalized.rectByNodeId.get(id),
+          raw = spaces.raw.rectByNodeId.get(id);
+        if (!original || !raw) return [id, rect];
+        return [
+          id,
+          { ...rect, x: raw.x + (rect.x - original.x), y: raw.y + (rect.y - original.y) },
+        ];
+      }),
+    ),
+  };
+}

package/src/layered/separate-exterior-labels.ts

@@ -108,10 +108,31 @@ export function separateExteriorLabels<E extends ExteriorLabelEdge>({
             right.length - left.length,
         )[0];
     if (!routeTrack) return [];
+    // Long-edge joining can retain several collinear points through a label
+    // dummy. They form one track; moving only one fragment creates diagonals
+    // at the retained junctions.
+    const pointCross = (point: Point) => (horizontalFlow ? point.y : point.x);
+    const pointFlow = (point: Point) => (horizontalFlow ? point.x : point.y);
+    let startIndex = routeTrack.startIndex;
+    let endIndex = startIndex + 1;
+    while (startIndex > 0 && pointCross(edge.points[startIndex - 1]!) === routeTrack.cross)
+      startIndex--;
+    while (
+      endIndex + 1 < edge.points.length &&
+      pointCross(edge.points[endIndex + 1]!) === routeTrack.cross
+    )
+      endIndex++;
+    const trackPoints = edge.points.slice(startIndex, endIndex + 1);
     return [
       {
         edge,
-        exteriorTrack: routeTrack,
+        exteriorTrack: {
+          ...routeTrack,
+          startIndex,
+          endIndex,
+          flowStart: Math.min(...trackPoints.map(pointFlow)),
+          flowEnd: Math.max(...trackPoints.map(pointFlow)),
+        },
         preserveAnchors: exteriorTrack === undefined,
         labelRect,
         lowSide:
@@ -222,17 +243,14 @@ export function separateExteriorLabels<E extends ExteriorLabelEdge>({
     else edge.x += totalDelta;
     if (!exteriorTrack) continue;
     edge.points = edge.points.flatMap((point, index) => {
-      if (index !== exteriorTrack.startIndex && index !== exteriorTrack.startIndex + 1)
-        return [point];
+      if (index < exteriorTrack.startIndex || index > exteriorTrack.endIndex) return [point];
       const shifted = horizontalFlow
         ? { ...point, y: point.y + totalDelta }
         : { ...point, x: point.x + totalDelta };
       // Keep authored endpoint anchors attached when the chosen track ends there.
       return preserveAnchors && index === exteriorTrack.startIndex && index === 0
         ? [point, shifted]
-        : preserveAnchors &&
-            index === exteriorTrack.startIndex + 1 &&
-            index === edge.points.length - 1
+        : preserveAnchors && index === exteriorTrack.endIndex && index === edge.points.length - 1
           ? [shifted, point]
           : [shifted];
     });

package/src/layered/spacing.ts

@@ -1,3 +1,4 @@
+import { externalPortDummyOf } from "./external-port-dummy";
 import type { LayeredPhaseInput } from "./types";
 
 export type IndividualSpacing = Readonly<Record<string, number>>;
@@ -10,20 +11,41 @@ export function nodeNodeSpacing(
 ): number {
   const firstBreakingPoint = firstId.startsWith("__layout_breaking:");
   const secondBreakingPoint = secondId.startsWith("__layout_breaking:");
-  const firstDummy = firstId.startsWith("__layout_dummy:") || firstBreakingPoint;
-  const secondDummy = secondId.startsWith("__layout_dummy:") || secondBreakingPoint;
+  const firstLabel = firstId.startsWith("__layout_dummy:label:");
+  const secondLabel = secondId.startsWith("__layout_dummy:label:");
+  const firstNode = input.graph.nodes.find((node) => node.id === firstId);
+  const secondNode = input.graph.nodes.find((node) => node.id === secondId);
+  const firstExternal = firstNode !== undefined && externalPortDummyOf(firstNode) !== undefined;
+  const secondExternal = secondNode !== undefined && externalPortDummyOf(secondNode) !== undefined;
+  const firstDummy = firstId.startsWith("__layout_dummy:") || firstBreakingPoint || firstExternal;
+  const secondDummy =
+    secondId.startsWith("__layout_dummy:") || secondBreakingPoint || secondExternal;
   const spacingName =
-    firstDummy && secondDummy && firstBreakingPoint === secondBreakingPoint
-      ? "spacing.edgeEdge"
-      : firstDummy || secondDummy
-        ? "spacing.edgeNode"
-        : "spacing.node";
+    firstExternal && secondExternal
+      ? "spacing.portPort"
+      : (firstExternal && secondLabel) || (secondExternal && firstLabel)
+        ? "spacing.labelPortVertical"
+        : firstLabel && secondLabel
+          ? "spacing.edgeEdge"
+          : (firstLabel && !secondDummy) || (secondLabel && !firstDummy)
+            ? "spacing.node"
+            : (firstLabel && secondDummy) || (secondLabel && firstDummy)
+              ? "spacing.edgeNode"
+              : firstDummy && secondDummy && firstBreakingPoint === secondBreakingPoint
+                ? "spacing.edgeEdge"
+                : firstDummy || secondDummy
+                  ? "spacing.edgeNode"
+                  : "spacing.node";
   let spacing =
-    spacingName === "spacing.edgeEdge"
-      ? Number(input.settings["spacing.edgeEdge"] ?? 10)
-      : spacingName === "spacing.edgeNode"
-        ? Number(input.settings["spacing.edgeNode"] ?? 10)
-        : input.spacing.node;
+    spacingName === "spacing.portPort"
+      ? Number(input.settings["spacing.portPort"] ?? 10)
+      : spacingName === "spacing.labelPortVertical"
+        ? Number(input.settings["spacing.labelPortVertical"] ?? 1)
+        : spacingName === "spacing.edgeEdge"
+          ? Number(input.settings["spacing.edgeEdge"] ?? 10)
+          : spacingName === "spacing.edgeNode"
+            ? Number(input.settings["spacing.edgeNode"] ?? 10)
+            : input.spacing.node;
   for (const id of [firstId, secondId]) {
     const node = input.graph.nodes.find((candidate) => candidate.id === id);
     if (!node) continue;

package/src/layered/splitter-order.ts

@@ -0,0 +1,106 @@
+import type { GraphEdge } from "@statelyai/graph";
+import type { PortEdgeList } from "./elk-port-lists";
+import type { LongEdgeExpansion } from "./long-edges";
+import type { LayeredPhaseInput } from "./types";
+
+/**
+ * ELK's LongEdgeSplitter appends each dummy to the next layer while visiting
+ * the current layer's nodes, their ports and each port's outgoing edges. That
+ * insertion order is the initial crossing-minimization order, so seed it here.
+ */
+export function withLongEdgeSplitterOrder(
+  unsplit: LayeredPhaseInput,
+  expansion: LongEdgeExpansion,
+  baseOrder: readonly string[],
+  portLists: ReadonlyMap<string, readonly PortEdgeList[]>,
+): LongEdgeExpansion {
+  const { input, orientation, assignment } = expansion;
+  const authoredIds = new Set(unsplit.graph.nodes.map((node) => node.id));
+  const dummyIds = new Set(
+    input.graph.nodes.map((node) => node.id).filter((id) => !authoredIds.has(id)),
+  );
+  if (dummyIds.size === 0) return expansion;
+  const layerOf = (id: string) => assignment.layerByNodeId.get(id) ?? 0;
+  const placed = new Set<string>();
+  const layers: string[][] = [];
+  for (const id of [...baseOrder, ...authoredIds]) {
+    if (placed.has(id) || !authoredIds.has(id)) continue;
+    placed.add(id);
+    (layers[layerOf(id)] ??= []).push(id);
+  }
+  const reversed = (edge: GraphEdge) => orientation.reversedEdgeIds.has(edge.id);
+  const outgoing = new Map<string, GraphEdge[]>();
+  for (const edge of input.graph.edges) {
+    const source = reversed(edge) ? edge.targetId : edge.sourceId;
+    if (edge.sourceId === edge.targetId) continue;
+    if (!outgoing.has(source)) outgoing.set(source, []);
+    outgoing.get(source)!.push(edge);
+  }
+  // Visit ports and their outgoing edges in ELK's simulated list order, which
+  // records reversal history. Expanded segment ids keep the original edge id.
+  const original = (id: string) => id.split("::")[0]!;
+  const targetsInPortOrder = (id: string): string[] => {
+    const edges = outgoing.get(id) ?? [];
+    const lists = portLists.get(id);
+    if (!lists) return edges.map((edge) => (reversed(edge) ? edge.sourceId : edge.targetId));
+    const rank = new Map<string, number>();
+    for (const port of lists) for (const edgeId of port.outgoing) rank.set(edgeId, rank.size);
+    return edges
+      .map((edge, index) => ({
+        edge,
+        index,
+        rank: rank.get(original(edge.id)) ?? rank.size + index,
+      }))
+      .sort((a, b) => a.rank - b.rank || a.index - b.index)
+      .map(({ edge }) => (reversed(edge) ? edge.sourceId : edge.targetId));
+  };
+  for (let index = 0; index < layers.length; index++) {
+    const layer = layers[index] ?? [];
+    for (let position = 0; position < layer.length; position++) {
+      for (const target of targetsInPortOrder(layer[position]!)) {
+        if (!dummyIds.has(target) || placed.has(target) || layerOf(target) !== index + 1) continue;
+        placed.add(target);
+        (layers[index + 1] ??= []).push(target);
+      }
+    }
+  }
+  const seedOrder = layers.flatMap((layer) => layer ?? []);
+  for (const id of dummyIds) if (!placed.has(id)) seedOrder.push(id);
+  return { ...expansion, assignment: { ...assignment, seedOrder } };
+}
+
+/**
+ * Each split re-targets a long edge through a new segment appended to the
+ * target port's incoming edges. Long edges therefore follow retained short
+ * edges, in the order of their final split.
+ */
+export function incomingAfterLongEdgeSplitting(
+  lists: ReadonlyMap<string, readonly PortEdgeList[]>,
+  expansion: LongEdgeExpansion,
+): Map<string, PortEdgeList[]> {
+  const { input, orientation, assignment } = expansion;
+  const seed = new Map((assignment.seedOrder ?? []).map((id, index) => [id, index]));
+  const listed = (id: string) => id.replace(/::segment:\d+$/, "");
+  const finalSplit = new Map<string, number>();
+  for (const edge of input.graph.edges) {
+    const reversed = orientation.reversedEdgeIds.has(edge.id);
+    const [source, target] = reversed
+      ? [edge.targetId, edge.sourceId]
+      : [edge.sourceId, edge.targetId];
+    const at = seed.get(source);
+    if (source.startsWith("__layout_dummy:") && at !== undefined)
+      finalSplit.set(`${target}\0${listed(edge.id)}`, at);
+  }
+  return new Map(
+    [...lists].map(([id, ports]) => [
+      id,
+      ports.map((port) => ({
+        ...port,
+        incoming: port.incoming
+          .map((edgeId, index) => ({ edgeId, index, split: finalSplit.get(`${id}\0${edgeId}`) }))
+          .sort((a, b) => (a.split ?? -1) - (b.split ?? -1) || a.index - b.index)
+          .map(({ edgeId }) => edgeId),
+      })),
+    ]),
+  );
+}