@statelyai/layout 0.2.0 → 0.4.0

package/src/elkjs/routes.ts

@@ -0,0 +1,147 @@
+import type { ElkExtendedEdge, ElkNode, ElkPoint } from "./public-types";
+import { pathFromPoints } from "../routing/path";
+import { pathFromSplinePoints } from "../routing/adapters";
+import { freeze } from "../routing/model";
+import type { Route, RouteEndpoint, RoutePath, RoutePoint, RouteSection } from "../routing/types";
+
+export interface ElkRouteOptions {
+  /** ELK stores spline controls in bendPoints; the caller must identify that encoding. */
+  routing?: "ORTHOGONAL" | "POLYLINE" | "SPLINES";
+}
+/** Normalize any ELK layout's section geometry, preserving ports and hyperedge junctions. */
+export function getElkRoutes(
+  graph: ElkNode,
+  options: ElkRouteOptions = {},
+): ReadonlyMap<string, Route> {
+  const shapes = new Map<string, { ref: RouteEndpoint; center: RoutePoint }>(),
+    frames = new Map<string, RoutePoint>();
+  const edges: { edge: ElkExtendedEdge; offset: RoutePoint; routing: string }[] = [];
+  function visit(node: ElkNode, offset: RoutePoint, inherited: string) {
+    const position = { x: offset.x + (node.x ?? 0), y: offset.y + (node.y ?? 0) };
+    const routing =
+      node.layoutOptions?.["elk.edgeRouting"] ??
+      node.layoutOptions?.["org.eclipse.elk.edgeRouting"] ??
+      inherited;
+    frames.set(node.id, position);
+    shapes.set(node.id, {
+      ref: { kind: "node", nodeId: node.id },
+      center: { x: position.x + (node.width ?? 0) / 2, y: position.y + (node.height ?? 0) / 2 },
+    });
+    for (const port of node.ports ?? [])
+      shapes.set(port.id, {
+        ref: { kind: "node", nodeId: node.id, port: port.id },
+        center: {
+          x: position.x + (port.x ?? 0) + (port.width ?? 0) / 2,
+          y: position.y + (port.y ?? 0) + (port.height ?? 0) / 2,
+        },
+      });
+    for (const edge of node.edges ?? [])
+      edges.push({
+        edge,
+        offset: position,
+        routing:
+          edge.layoutOptions?.["elk.edgeRouting"] ??
+          edge.layoutOptions?.["org.eclipse.elk.edgeRouting"] ??
+          routing,
+      });
+    for (const child of node.children ?? []) visit(child, position, routing);
+  }
+  visit(graph, { x: 0, y: 0 }, options.routing ?? "POLYLINE");
+  const result = new Map<string, Route>();
+  for (const { edge, offset: inheritedOffset, routing } of edges) {
+    const offset = edge.container
+      ? (frames.get(edge.container) ?? inheritedOffset)
+      : inheritedOffset;
+    const point = (p: ElkPoint): RoutePoint => ({ x: p.x + offset.x, y: p.y + offset.y });
+    // Join section endpoints by topology, never by equal coordinates alone.
+    const parents = new Map<string, string>();
+    const root = (key: string): string => {
+      let current = key;
+      while (parents.has(current)) current = parents.get(current)!;
+      return current;
+    };
+    const join = (a: string, b: string) => {
+      const x = root(a),
+        y = root(b);
+      if (x !== y) parents.set(x < y ? y : x, x < y ? x : y);
+    };
+    for (const section of edge.sections ?? []) {
+      for (const id of section.outgoingSections ?? []) join(`${section.id}:end`, `${id}:start`);
+      for (const id of section.incomingSections ?? []) join(`${id}:end`, `${section.id}:start`);
+    }
+    const sections: RouteSection[] = [];
+    let malformed = false;
+    for (const section of edge.sections ?? []) {
+      const points = [section.startPoint, ...(section.bendPoints ?? []), section.endPoint].map(
+        point,
+      );
+      let path: RoutePath;
+      if (points.some((p) => !Number.isFinite(p.x) || !Number.isFinite(p.y))) {
+        malformed = true;
+        for (let i = 0; i < points.length; i++)
+          if (!Number.isFinite(points[i]!.x) || !Number.isFinite(points[i]!.y))
+            points[i] = { x: offset.x + i * 20, y: offset.y };
+      }
+      if (routing === "SPLINES") {
+        if ((points.length - 1) % 3 || points.length < 4) {
+          malformed = true;
+          path = pathFromPoints([points[0]!, points.at(-1)!]);
+        } else path = pathFromSplinePoints(points);
+      } else path = pathFromPoints(points);
+      const fromShape =
+        section.incomingShape ??
+        (!section.incomingSections?.length && edge.sources.length === 1
+          ? edge.sources[0]
+          : undefined);
+      const toShape =
+        section.outgoingShape ??
+        (!section.outgoingSections?.length && edge.targets.length === 1
+          ? edge.targets[0]
+          : undefined);
+      sections.push({
+        id: section.id,
+        from: fromShape
+          ? (shapes.get(fromShape)?.ref ?? { kind: "node", nodeId: fromShape })
+          : { kind: "junction", id: `${edge.id}:${root(`${section.id}:start`)}` },
+        to: toShape
+          ? (shapes.get(toShape)?.ref ?? { kind: "node", nodeId: toShape })
+          : { kind: "junction", id: `${edge.id}:${root(`${section.id}:end`)}` },
+        path,
+      });
+    }
+    if (!sections.length) {
+      malformed = true;
+      const source = shapes.get(edge.sources[0] ?? ""),
+        origin = source?.center ?? { x: 0, y: 0 };
+      const targets = [...edge.targets, ...edge.sources.slice(1)];
+      for (const [i, id] of (targets.length ? targets : [""]).entries()) {
+        const target = shapes.get(id);
+        sections.push({
+          id: `${edge.id}:fallback:${i}`,
+          from: source?.ref ?? { kind: "node", nodeId: edge.sources[0] ?? "" },
+          to: target?.ref ?? { kind: "node", nodeId: id },
+          path: pathFromPoints([origin, target?.center ?? { x: origin.x + 40, y: origin.y + 40 }]),
+        });
+      }
+    }
+    result.set(
+      edge.id,
+      freeze({
+        edgeId: edge.id,
+        sections,
+        status: malformed ? "fallback" : "routed",
+        diagnostics: malformed
+          ? [
+              {
+                code: "MISSING_GEOMETRY",
+                edgeId: edge.id,
+                message:
+                  "ELK sections contain missing or invalid geometry; rendered fallback paths",
+              },
+            ]
+          : [],
+      }),
+    );
+  }
+  return result;
+}

package/src/elkjs/statechart.ts

@@ -178,8 +178,14 @@ export function scoreStatechartLayout(
       height: shape.height ?? 0,
     };
   };
-  const visit = (node: ElkNode, x: number, y: number, ancestors: ElkNode[]) => {
-    const direction = String(option(node, "direction") ?? "RIGHT").toUpperCase();
+  const visit = (
+    node: ElkNode,
+    x: number,
+    y: number,
+    ancestors: ElkNode[],
+    inheritedDirection = "RIGHT",
+  ) => {
+    const direction = String(option(node, "direction") ?? inheritedDirection).toUpperCase();
     const horizontal = direction === "RIGHT" || direction === "LEFT";
     const sign = direction === "LEFT" || direction === "UP" ? -1 : 1;
     const path = paths[String(node.id)] ?? [];
@@ -199,7 +205,7 @@ export function scoreStatechartLayout(
       )
         score.invalid++;
       boxes.push({ rect: box, ancestors, node: child });
-      visit(child, box.x, box.y, [...ancestors, child]);
+      visit(child, box.x, box.y, [...ancestors, child], direction);
     }
     for (const edge of node.edges ?? []) {
       if (String(option(edge, "noLayout")).toLowerCase() === "true") continue;

package/src/elkjs/types.ts

@@ -35,6 +35,8 @@ export interface ElkEdgeSection extends ElkGraphElement {
 }
 
 export interface ElkEdge extends ElkGraphElement {
+  /** Node whose coordinate frame contains the exported route. */
+  container?: ElkId;
   sources?: ElkId[];
   targets?: ElkId[];
   source?: ElkId;

package/src/index.ts

@@ -71,6 +71,10 @@ export type {
   EdgeRoutes,
   LayerAssigner,
   LayerAssignment,
+  CompoundVisualGraph,
+  CompoundLayoutOptions,
+  CompoundLayoutGeometry,
+  CompoundEdgeAttachment,
   LayeredLayoutOptions,
   LayeredAdvancedOptions,
   ElkLayeredOptionId,
@@ -92,6 +96,8 @@ export type {
 } from "./layered";
 
 export { c } from "./constraints";
+export { hint, statechartHints } from "./layered/hints";
+export type { AnchorHint, ChainHint, HintStrength, LayoutHint } from "./layered/hints";
 export type {
   LayoutConstraint,
   GeometryReference,
@@ -103,3 +109,5 @@ export type {
   LinearConstraint,
   WaypointConstraint,
 } from "./constraints";
+
+export * from "./routing";

package/src/internal/elkjs-compatibility.ts

@@ -1,6 +1,9 @@
-import type { VisualGraph } from "@statelyai/graph";
+import type { VisualGraph, Point } from "@statelyai/graph";
 
 export interface Elkjs0111ResultPolicy {
+  junctionPointsByEdgeId?: ReadonlyMap<string, readonly Point[]>;
+  placementCrossBounds?: { axis: "x" | "y"; maximum: number };
+  normalizationBounds?: { left: number; top: number; right: number; bottom: number };
   providerBounds?: { width: number; height: number };
   preserveEdgeSections?: boolean;
   skipBoundsNormalization?: boolean;

package/src/internal/layered-trace.ts

@@ -0,0 +1,48 @@
+/** Development-only phase observations for differential tracing against real ELK. */
+export type LayeredTraceEvent =
+  | {
+      kind: "sweep";
+      scope: string;
+      attempt: number;
+      forward: boolean;
+      firstSweep: boolean;
+      crossings: number;
+      layers: readonly (readonly string[])[];
+    }
+  | {
+      kind: "port-lists";
+      scope: string;
+      ports: ReadonlyMap<
+        string,
+        readonly { name?: string; outgoing: readonly string[]; incoming: readonly string[] }[]
+      >;
+    }
+  | {
+      kind: "initial-order";
+      scope: string;
+      layers: readonly (readonly string[])[];
+    }
+  | {
+      kind: "crossing-order";
+      scope: string;
+      edgeIds: readonly string[];
+      reversedEdgeIds: readonly string[];
+      layerByNodeId: ReadonlyMap<string, number>;
+      layers: readonly (readonly string[])[];
+    };
+
+let observer: ((event: LayeredTraceEvent) => void) | undefined;
+
+/** Install an observer and return the previous one. Production code never sets one. */
+export function setLayeredTraceObserver(
+  next: ((event: LayeredTraceEvent) => void) | undefined,
+): ((event: LayeredTraceEvent) => void) | undefined {
+  const previous = observer;
+  observer = next;
+  return previous;
+}
+
+/** Build and emit an event only while an observer is installed. */
+export function traceLayeredPhase(event: () => LayeredTraceEvent): void {
+  observer?.(event());
+}

package/src/internal/layout-engine.ts

@@ -1,7 +1,7 @@
 import type { Graph, VisualGraph } from "@statelyai/graph";
 import { boxAlgorithm, elkjs0111BoxAlgorithm, type BoxLayoutOptions } from "../box";
 import { fixedAlgorithm, type FixedLayoutOptions } from "../fixed";
-import { layeredAlgorithm, type LayeredLayoutOptions } from "../layered";
+import { layeredAlgorithm, elkjs0111LayeredAlgorithm, type LayeredLayoutOptions } from "../layered";
 import {
   elkjs0111RectanglePackingAlgorithm,
   rectanglePackingAlgorithm,
@@ -43,6 +43,7 @@ const elkjs0111LayoutAlgorithms = {
   ...builtInLayoutAlgorithms,
   box: elkjs0111BoxAlgorithm,
   random: elkjs0111RandomAlgorithm,
+  layered: elkjs0111LayeredAlgorithm,
   rectpacking: elkjs0111RectanglePackingAlgorithm,
 } satisfies {
   [Id in BuiltInLayoutAlgorithmId]: LayoutAlgorithm<BuiltInLayoutOptionsById[Id]>;

package/src/java-random.ts

@@ -9,6 +9,12 @@ export class JavaRandom {
     this.#seed = (BigInt(seed) ^ JavaRandom.#multiplier) & JavaRandom.#mask;
   }
 
+  clone(): JavaRandom {
+    const copy = new JavaRandom(0);
+    copy.#seed = this.#seed;
+    return copy;
+  }
+
   #next(bits: number): number {
     this.#seed = (this.#seed * JavaRandom.#multiplier + JavaRandom.#addend) & JavaRandom.#mask;
     return Number(this.#seed >> BigInt(48 - bits));