@statelyai/layout 0.1.3 → 0.3.0

package/src/elkjs/index.ts

@@ -1,15 +1,11 @@
-import { createGraph, type Graph } from "@statelyai/graph";
-import { getBoxLayout } from "../box";
-import { getFixedLayout } from "../fixed";
-import { getLayeredLayout } from "../layered";
+import { createGraph, type Graph, type VisualGraph } from "@statelyai/graph";
 import {
   elkLayeredOptionDefinitions,
   type ElkLayeredOptionValueByName,
   type LayeredAdvancedOptions,
 } from "../layered/elk-options";
-import { getRectanglePackingLayout } from "../packing";
-import { getRandomLayout } from "../random";
-import { getSporeCompactionLayout, getSporeOverlapRemovalLayout } from "../spore";
+import { executeElkjs0111Layout } from "../internal/layout-engine";
+import { elkjs0111ResultPolicy, type Elkjs0111ResultPolicy } from "../internal/elkjs-compatibility";
 import type {
   ElkConstructorArguments,
   ElkLayoutAlgorithmDescription,
@@ -25,6 +21,11 @@ import type {
   ElkShape,
   LaidOutElkNode,
 } from "./types";
+import type {
+  ElkLayoutArguments as PublicElkLayoutArguments,
+  ElkNode as PublicElkNode,
+  LaidOutElkNode as PublicLaidOutElkNode,
+} from "./public-types";
 
 function isLayoutEdgeLabel(label: ElkLabel): boolean {
   return (
@@ -34,24 +35,27 @@ function isLayoutEdgeLabel(label: ElkLabel): boolean {
 }
 
 export type {
-  ElkConstructorArguments,
+  ELK,
+  ELKConstructorArguments,
   ElkCommonDescription,
-  ElkGraphElement,
-  ElkId,
   ElkEdge,
   ElkEdgeSection,
+  ElkExtendedEdge,
+  ElkGraphElement,
   ElkLabel,
   ElkLayoutArguments,
   ElkLayoutAlgorithmDescription,
   ElkLayoutCategoryDescription,
   ElkLayoutOptionDescription,
-  ElkLogging,
   ElkNode,
   ElkPoint,
   ElkPort,
+  ElkPrimitiveEdge,
   ElkShape,
+  LayoutOptions,
   LaidOutElkNode,
-} from "./types";
+} from "./public-types";
+export type { ElkId, ElkLogging } from "./types";
 
 export default class ELK {
   readonly #options: ElkConstructorArguments;
@@ -119,7 +123,19 @@ export default class ELK {
 
   terminateWorker(): void {}
 
-  async layout<T extends ElkNode>(
+  layout<T extends PublicElkNode>(
+    graph: T,
+    arguments_?: PublicElkLayoutArguments,
+  ): Promise<PublicElkNode & PublicLaidOutElkNode<T>>;
+  layout<T extends ElkNode>(graph: T, arguments_?: ElkLayoutArguments): Promise<LaidOutElkNode<T>>;
+  layout<T extends ElkNode>(
+    graph: T,
+    arguments_: ElkLayoutArguments = {},
+  ): Promise<LaidOutElkNode<T>> {
+    return this.#layout(graph, arguments_);
+  }
+
+  async #layout<T extends ElkNode>(
     graph: T,
     arguments_: ElkLayoutArguments = {},
   ): Promise<LaidOutElkNode<T>> {
@@ -246,7 +262,7 @@ export default class ELK {
       }
       for (const child of graph.children ?? []) {
         if ((child.children?.length ?? 0) === 0) continue;
-        await this.layout(child, {
+        await this.#layout(child, {
           ...arguments_,
           layoutOptions: {
             ...arguments_.layoutOptions,
@@ -361,7 +377,7 @@ export default class ELK {
           children: [...(child.children ?? []), ...proxyByKind.values()],
           edges: temporaryEdges,
         };
-        await this.layout(temporaryChild, {
+        await this.#layout(temporaryChild, {
           ...arguments_,
           layoutOptions: {
             ...arguments_.layoutOptions,
@@ -527,31 +543,49 @@ export default class ELK {
       getOption(layoutOptions, "padding"),
       algorithm === "layered" ? 12 : 0,
     );
-    const laidOut =
-      algorithm === "sporeCompaction"
-        ? getSporeCompactionLayout(graph_, {
+    const laidOut = await (algorithm === "sporeCompaction"
+      ? executeElkjs0111Layout({
+          algorithm: "sporeCompaction",
+          graph: graph_,
+          options: {
             padding,
             spacing: getNumberOption(layoutOptions, "spacing.nodeNode"),
-          })
-        : algorithm === "sporeOverlap"
-          ? getSporeOverlapRemovalLayout(graph_, {
+          },
+        })
+      : algorithm === "sporeOverlap"
+        ? executeElkjs0111Layout({
+            algorithm: "sporeOverlap",
+            graph: graph_,
+            options: {
               padding,
               spacing: getNumberOption(layoutOptions, "spacing.nodeNode"),
+            },
+          })
+        : algorithm === "rectpacking"
+          ? executeElkjs0111Layout({
+              algorithm: "rectpacking",
+              graph: graph_,
+              options: {
+                padding: getOption(layoutOptions, "padding") === undefined ? 15 : padding,
+                spacing: getNumberOption(layoutOptions, "spacing.nodeNode") ?? 15,
+              },
             })
-          : algorithm === "rectpacking"
-            ? getRectanglePackingLayout(graph_, {
-                padding,
-                spacing: getNumberOption(layoutOptions, "spacing.nodeNode"),
-              })
-            : algorithm === "random"
-              ? getRandomLayout(graph_, {
+          : algorithm === "random"
+            ? executeElkjs0111Layout({
+                algorithm: "random",
+                graph: graph_,
+                options: {
                   padding: getOption(layoutOptions, "padding") === undefined ? 15 : padding,
                   spacing: getNumberOption(layoutOptions, "spacing.nodeNode"),
                   aspectRatio: getNumberOption(layoutOptions, "aspectRatio"),
                   seed: getNumberOption(layoutOptions, "randomSeed"),
-                })
-              : algorithm === "box"
-                ? getBoxLayout(graph_, {
+                },
+              })
+            : algorithm === "box"
+              ? executeElkjs0111Layout({
+                  algorithm: "box",
+                  graph: graph_,
+                  options: {
                     padding: getOption(layoutOptions, "padding") === undefined ? 15 : padding,
                     spacing: getNumberOption(layoutOptions, "spacing.nodeNode"),
                     aspectRatio: getNumberOption(layoutOptions, "aspectRatio"),
@@ -563,10 +597,18 @@ export default class ELK {
                       );
                       return getNumberOption(child?.layoutOptions ?? {}, "priority");
                     },
+                  },
+                })
+              : algorithm === "fixed"
+                ? executeElkjs0111Layout({
+                    algorithm: "fixed",
+                    graph: graph_,
+                    options: { direction: getDirection(layoutOptions) },
                   })
-                : algorithm === "fixed"
-                  ? getFixedLayout(graph_, { direction: getDirection(layoutOptions) })
-                  : getLayeredLayout(graph_, {
+                : executeElkjs0111Layout({
+                    algorithm: "layered",
+                    graph: graph_,
+                    options: {
                       direction: getDirection(layoutOptions),
                       spacing: {
                         node:
@@ -638,7 +680,8 @@ export default class ELK {
                           ),
                         } as ElkLayeredOptionValueByName;
                       },
-                    });
+                    },
+                  }));
     if (hierarchyRestorations.length > 0) {
       const direction = getDirection(layoutOptions);
       const horizontal = direction === "right" || direction === "left";
@@ -750,7 +793,16 @@ export default class ELK {
         );
       }
     }
-    applyLayout(graph, laidOut, padding, layoutOptions);
+    const resultPolicy = (
+      laidOut as typeof laidOut & {
+        [elkjs0111ResultPolicy]?: Elkjs0111ResultPolicy;
+      }
+    )[elkjs0111ResultPolicy];
+    applyLayout(graph, laidOut, padding, layoutOptions, resultPolicy);
+    if (resultPolicy?.providerBounds) {
+      graph.width = resultPolicy.providerBounds.width;
+      graph.height = resultPolicy.providerBounds.height;
+    }
     for (const restoration of hierarchyRestorations) {
       restoration.edge.sources = restoration.sources;
       restoration.edge.targets = restoration.targets;
@@ -771,7 +823,7 @@ export default class ELK {
       for (const child of graph.children ?? []) {
         if ((child.children?.length ?? 0) === 0) continue;
         const position = { x: child.x, y: child.y };
-        await this.layout(child, {
+        await this.#layout(child, {
           ...arguments_,
           logging: false,
           measureExecutionTime: false,
@@ -1335,9 +1387,10 @@ function toSection(edge: ElkEdge, points: readonly ElkPoint[]) {
 
 function applyLayout(
   root: ElkNode,
-  graph: ReturnType<typeof getLayeredLayout>,
+  graph: VisualGraph,
   padding: { top: number; right: number; bottom: number; left: number },
   layoutOptions: Readonly<Record<string, unknown>>,
+  resultPolicy?: Elkjs0111ResultPolicy,
 ): void {
   const nodeById = new Map(graph.nodes.map((node) => [node.id, node]));
   const edgeById = new Map(graph.edges.map((edge) => [edge.id, edge]));
@@ -1361,6 +1414,13 @@ function applyLayout(
     placePortLabels(child, layoutOptions);
   }
   for (const edge of root.edges ?? []) {
+    if (resultPolicy?.preserveEdgeSections) {
+      for (const section of edge.sections ?? []) {
+        section.incomingShape ??= edge.sources?.[0] ?? edge.source;
+        section.outgoingShape ??= edge.targets?.[0] ?? edge.target;
+      }
+      continue;
+    }
     const laidOutEdge = edgeById.get(String(edge.id));
     if (!laidOutEdge) {
       if (getBooleanOption(edge.layoutOptions ?? {}, "noLayout") === true) {
@@ -1417,7 +1477,9 @@ function applyLayout(
       labelY += (label.height ?? 0) + labelLabelSpacing;
     }
   }
-  normalizeElkGraphBounds(root, padding, layoutOptions);
+  if (!resultPolicy?.skipBoundsNormalization) {
+    normalizeElkGraphBounds(root, padding, layoutOptions);
+  }
 }
 
 function normalizeElkGraphBounds(
@@ -1838,3 +1900,6 @@ export type {
   StatechartLayoutScore,
   StatechartLayoutPlan,
 } from "./statechart";
+
+export { getElkRoutes } from "./routes";
+export type { ElkRouteOptions } from "./routes";

package/src/elkjs/main.ts

@@ -0,0 +1,19 @@
+/*******************************************************************************
+ * Copyright (c) 2021 Kiel University and others.
+ *
+ * Adapted from elkjs 0.11.1 lib/main.js.
+ * SPDX-License-Identifier: EPL-2.0
+ *******************************************************************************/
+import type { ELKConstructorArguments } from "./public-types";
+import { Worker } from "./worker";
+import { WorkerELK } from "./worker-client";
+
+/** Node-compatible elkjs entry point with an in-process worker fallback. */
+export default class ELK extends WorkerELK {
+  constructor(options: ELKConstructorArguments = {}) {
+    super({
+      ...options,
+      workerFactory: options.workerFactory ?? ((url?: string) => new Worker(url)),
+    });
+  }
+}

package/src/elkjs/public-types.ts

@@ -0,0 +1,125 @@
+/*******************************************************************************
+ * Copyright (c) 2019 TypeFox and others.
+ *
+ * Adapted from elkjs 0.11.1 typings/elk-api.d.ts.
+ * SPDX-License-Identifier: EPL-2.0
+ *******************************************************************************/
+
+export interface LayoutOptions {
+  [key: string]: string;
+}
+
+export interface ElkPoint {
+  x: number;
+  y: number;
+}
+
+export interface ElkGraphElement {
+  id?: string;
+  labels?: ElkLabel[];
+  layoutOptions?: LayoutOptions;
+}
+
+export interface ElkShape extends ElkGraphElement {
+  x?: number;
+  y?: number;
+  width?: number;
+  height?: number;
+}
+
+export interface ElkNode extends ElkShape {
+  id: string;
+  children?: ElkNode[];
+  ports?: ElkPort[];
+  edges?: ElkExtendedEdge[];
+}
+
+export interface ElkPort extends ElkShape {
+  id: string;
+}
+
+export interface ElkLabel extends ElkShape {
+  text?: string;
+}
+
+/** @deprecated Use ElkExtendedEdge directly. */
+export interface ElkEdge extends ElkGraphElement {
+  id: string;
+  container?: string;
+  junctionPoints?: ElkPoint[];
+}
+
+/** @deprecated Use ElkExtendedEdge instead. */
+export interface ElkPrimitiveEdge extends ElkEdge {
+  source: string;
+  sourcePort?: string;
+  target: string;
+  targetPort?: string;
+  sourcePoint?: ElkPoint;
+  targetPoint?: ElkPoint;
+  bendPoints?: ElkPoint[];
+}
+
+export interface ElkExtendedEdge extends ElkEdge {
+  sources: string[];
+  targets: string[];
+  sections?: ElkEdgeSection[];
+}
+
+export interface ElkEdgeSection extends ElkGraphElement {
+  id: string;
+  startPoint: ElkPoint;
+  endPoint: ElkPoint;
+  bendPoints?: ElkPoint[];
+  incomingShape?: string;
+  outgoingShape?: string;
+  incomingSections?: string[];
+  outgoingSections?: string[];
+}
+
+export interface ElkLayoutArguments {
+  layoutOptions?: LayoutOptions;
+  logging?: boolean;
+  measureExecutionTime?: boolean;
+}
+
+export interface ElkCommonDescription {
+  id?: string;
+  name?: string;
+  description?: string;
+}
+
+export interface ElkLayoutAlgorithmDescription extends ElkCommonDescription {
+  category?: string;
+  knownOptions?: string[];
+  supportedFeatures?: string[];
+}
+
+export interface ElkLayoutOptionDescription extends ElkCommonDescription {
+  group?: string;
+  type?: string;
+  targets?: string[];
+}
+
+export interface ElkLayoutCategoryDescription extends ElkCommonDescription {
+  knownLayouters?: string[];
+}
+
+export type LaidOutElkNode<T extends ElkNode> = Omit<T, "children"> & {
+  children?: Array<NonNullable<T["children"]>[number] & ElkNode>;
+};
+
+export interface ELK {
+  layout<T extends ElkNode>(graph: T, args?: ElkLayoutArguments): Promise<LaidOutElkNode<T>>;
+  knownLayoutAlgorithms(): Promise<ElkLayoutAlgorithmDescription[]>;
+  knownLayoutOptions(): Promise<ElkLayoutOptionDescription[]>;
+  knownLayoutCategories(): Promise<ElkLayoutCategoryDescription[]>;
+  terminateWorker(): void;
+}
+
+export interface ELKConstructorArguments {
+  defaultLayoutOptions?: LayoutOptions;
+  algorithms?: string[];
+  workerUrl?: string;
+  workerFactory?: (url?: string) => Worker;
+}

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/worker-api.ts

@@ -0,0 +1,29 @@
+/*******************************************************************************
+ * Copyright (c) 2017 Kiel University and others.
+ *
+ * Adapted from elkjs 0.11.1 lib/elk-api.js.
+ * SPDX-License-Identifier: EPL-2.0
+ *******************************************************************************/
+export { WorkerELK as default } from "./worker-client";
+
+export type {
+  ELK,
+  ELKConstructorArguments,
+  ElkCommonDescription,
+  ElkEdge,
+  ElkEdgeSection,
+  ElkExtendedEdge,
+  ElkGraphElement,
+  ElkLabel,
+  ElkLayoutArguments,
+  ElkLayoutAlgorithmDescription,
+  ElkLayoutCategoryDescription,
+  ElkLayoutOptionDescription,
+  ElkNode,
+  ElkPoint,
+  ElkPort,
+  ElkPrimitiveEdge,
+  ElkShape,
+  LayoutOptions,
+  LaidOutElkNode,
+} from "./public-types";