@statelyai/layout 0.1.3 → 0.2.0

package/src/elkjs/index.ts

@@ -1,15 +1,12 @@
 import { createGraph, type Graph } from "@statelyai/graph";
-import { getBoxLayout } from "../box";
-import { getFixedLayout } from "../fixed";
-import { getLayeredLayout } from "../layered";
+import type { getLayeredLayout } from "../layered";
 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 +22,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 +36,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 +124,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 +263,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 +378,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 +544,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 +598,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 +681,8 @@ export default class ELK {
                           ),
                         } as ElkLayeredOptionValueByName;
                       },
-                    });
+                    },
+                  }));
     if (hierarchyRestorations.length > 0) {
       const direction = getDirection(layoutOptions);
       const horizontal = direction === "right" || direction === "left";
@@ -750,7 +794,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 +824,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,
@@ -1338,6 +1391,7 @@ function applyLayout(
   graph: ReturnType<typeof getLayeredLayout>,
   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 +1415,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 +1478,9 @@ function applyLayout(
       labelY += (label.height ?? 0) + labelLabelSpacing;
     }
   }
-  normalizeElkGraphBounds(root, padding, layoutOptions);
+  if (!resultPolicy?.skipBoundsNormalization) {
+    normalizeElkGraphBounds(root, padding, layoutOptions);
+  }
 }
 
 function normalizeElkGraphBounds(

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/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";

package/src/elkjs/worker-client.ts

@@ -0,0 +1,138 @@
+import type {
+  ELK as ElkInterface,
+  ELKConstructorArguments,
+  ElkLayoutAlgorithmDescription,
+  ElkLayoutArguments,
+  ElkLayoutCategoryDescription,
+  ElkLayoutOptionDescription,
+  ElkNode,
+  LaidOutElkNode,
+  LayoutOptions,
+} from "./public-types";
+
+interface WorkerRequest {
+  id?: number;
+  cmd: "register" | "layout" | "algorithms" | "options" | "categories";
+  algorithms?: string[];
+  graph?: ElkNode;
+  layoutOptions?: LayoutOptions;
+  options?: Pick<ElkLayoutArguments, "logging" | "measureExecutionTime">;
+}
+
+interface WorkerAnswer {
+  id: number;
+  data?: unknown;
+  error?: unknown;
+}
+
+interface WorkerLike {
+  onmessage: ((event: MessageEvent<WorkerAnswer>) => void) | null;
+  onerror: ((event: ErrorEvent) => void) | null;
+  onmessageerror: ((event: MessageEvent) => void) | null;
+  postMessage(message: WorkerRequest): void;
+  terminate(): void;
+}
+
+class PromisedWorker {
+  readonly #worker: WorkerLike;
+  readonly #resolvers = new Map<
+    number,
+    { resolve(value: unknown): void; reject(reason?: unknown): void }
+  >();
+  #id = 0;
+  #failure: Error | undefined;
+
+  constructor(worker: WorkerLike) {
+    this.#worker = worker;
+    worker.onmessage = (event) => {
+      const resolver = this.#resolvers.get(event.data.id);
+      if (!resolver) return;
+      this.#resolvers.delete(event.data.id);
+      if (event.data.error !== undefined) resolver.reject(event.data.error);
+      else resolver.resolve(event.data.data);
+    };
+    worker.onerror = (event) => this.#rejectAll(event.error ?? event.message);
+    worker.onmessageerror = (event) => this.#rejectAll(event.data);
+  }
+
+  postMessage<T>(message: WorkerRequest): Promise<T> {
+    if (this.#failure) return Promise.reject(this.#failure);
+    const id = this.#id++;
+    return new Promise<T>((resolve, reject) => {
+      this.#resolvers.set(id, { resolve: resolve as (value: unknown) => void, reject });
+      this.#worker.postMessage({ ...message, id });
+    });
+  }
+
+  terminate(): void {
+    this.#worker.terminate();
+  }
+
+  #rejectAll(reason: unknown): void {
+    const error = reason instanceof Error ? reason : new Error(String(reason ?? "Worker failed"));
+    this.#failure = error;
+    for (const resolver of this.#resolvers.values()) resolver.reject(error);
+    this.#resolvers.clear();
+  }
+}
+
+export class WorkerELK implements ElkInterface {
+  readonly #defaultLayoutOptions: LayoutOptions;
+  readonly #worker: PromisedWorker;
+  readonly #ready: Promise<unknown>;
+
+  constructor({
+    defaultLayoutOptions = {},
+    algorithms,
+    workerFactory,
+    workerUrl,
+  }: ELKConstructorArguments = {}) {
+    if (workerUrl === undefined && workerFactory === undefined) {
+      throw new Error("Cannot construct an ELK without both 'workerUrl' and 'workerFactory'.");
+    }
+    const factory = workerFactory ?? ((url?: string) => new globalThis.Worker(url!));
+    const worker = factory(workerUrl) as WorkerLike;
+    if (!worker || typeof worker.postMessage !== "function") {
+      throw new TypeError("Created worker does not provide the required 'postMessage' function.");
+    }
+    this.#defaultLayoutOptions = defaultLayoutOptions;
+    this.#worker = new PromisedWorker(worker);
+    this.#ready = this.#worker.postMessage({ cmd: "register", algorithms });
+  }
+
+  async layout<T extends ElkNode>(
+    graph: T,
+    args: ElkLayoutArguments = {},
+  ): Promise<LaidOutElkNode<T>> {
+    if (!graph) throw new Error("Missing mandatory parameter 'graph'.");
+    await this.#ready;
+    return this.#worker.postMessage({
+      cmd: "layout",
+      graph,
+      layoutOptions: { ...this.#defaultLayoutOptions, ...args.layoutOptions },
+      options: {
+        logging: args.logging ?? false,
+        measureExecutionTime: args.measureExecutionTime ?? false,
+      },
+    });
+  }
+
+  async knownLayoutAlgorithms(): Promise<ElkLayoutAlgorithmDescription[]> {
+    await this.#ready;
+    return this.#worker.postMessage({ cmd: "algorithms" });
+  }
+
+  async knownLayoutOptions(): Promise<ElkLayoutOptionDescription[]> {
+    await this.#ready;
+    return this.#worker.postMessage({ cmd: "options" });
+  }
+
+  async knownLayoutCategories(): Promise<ElkLayoutCategoryDescription[]> {
+    await this.#ready;
+    return this.#worker.postMessage({ cmd: "categories" });
+  }
+
+  terminateWorker(): void {
+    this.#worker.terminate();
+  }
+}

package/src/elkjs/worker.ts

@@ -0,0 +1,117 @@
+/*******************************************************************************
+ * Copyright (c) 2019 Kiel University and others.
+ *
+ * Adapted from elkjs 0.11.1 lib/elk-worker.js.
+ * SPDX-License-Identifier: EPL-2.0
+ *******************************************************************************/
+import ELK from "./index";
+import type { ElkLayoutArguments, ElkNode } from "./types";
+
+type WorkerCommand =
+  | { id: number; cmd: "register"; algorithms?: string[] }
+  | {
+      id: number;
+      cmd: "layout";
+      graph: ElkNode;
+      layoutOptions?: Record<string, unknown>;
+      options?: ElkLayoutArguments;
+    }
+  | { id: number; cmd: "algorithms" | "options" | "categories" };
+
+type WorkerAnswer = { id: number; data?: unknown; error?: unknown };
+
+/** In-process implementation of the message interface shipped by elkjs workers. */
+export class Worker implements globalThis.Worker {
+  onerror: ((this: AbstractWorker, event: ErrorEvent) => unknown) | null = null;
+  onmessage: ((this: globalThis.Worker, event: MessageEvent) => unknown) | null = null;
+  onmessageerror: ((this: globalThis.Worker, event: MessageEvent) => unknown) | null = null;
+
+  readonly #listeners = new Map<string, Set<EventListenerOrEventListenerObject>>();
+  #elk = new ELK();
+  #terminated = false;
+
+  constructor(_url?: string) {}
+
+  postMessage(message: unknown, _transfer: Transferable[]): void;
+  postMessage(message: unknown, _options?: StructuredSerializeOptions): void;
+  postMessage(message: unknown): void {
+    if (this.#terminated) return;
+    queueMicrotask(() => void this.#handle(message as WorkerCommand));
+  }
+
+  terminate(): void {
+    this.#terminated = true;
+  }
+
+  addEventListener<K extends keyof WorkerEventMap>(
+    type: K,
+    listener: (this: globalThis.Worker, event: WorkerEventMap[K]) => unknown,
+    options?: boolean | AddEventListenerOptions,
+  ): void;
+  addEventListener(
+    type: string,
+    listener: EventListenerOrEventListenerObject,
+    _options?: boolean | AddEventListenerOptions,
+  ): void {
+    const listeners = this.#listeners.get(type) ?? new Set();
+    listeners.add(listener);
+    this.#listeners.set(type, listeners);
+  }
+
+  removeEventListener<K extends keyof WorkerEventMap>(
+    type: K,
+    listener: (this: globalThis.Worker, event: WorkerEventMap[K]) => unknown,
+    options?: boolean | EventListenerOptions,
+  ): void;
+  removeEventListener(
+    type: string,
+    listener: EventListenerOrEventListenerObject,
+    _options?: boolean | EventListenerOptions,
+  ): void {
+    this.#listeners.get(type)?.delete(listener);
+  }
+
+  dispatchEvent(event: Event): boolean {
+    for (const listener of this.#listeners.get(event.type) ?? []) {
+      if (typeof listener === "function") listener.call(this, event);
+      else listener.handleEvent(event);
+    }
+    return !event.defaultPrevented;
+  }
+
+  async #handle(message: WorkerCommand): Promise<void> {
+    try {
+      let data: unknown;
+      switch (message.cmd) {
+        case "register":
+          this.#elk = new ELK({ algorithms: message.algorithms });
+          break;
+        case "layout":
+          data = await this.#elk.layout(message.graph, {
+            ...message.options,
+            layoutOptions: message.layoutOptions,
+          });
+          break;
+        case "algorithms":
+          data = await this.#elk.knownLayoutAlgorithms();
+          break;
+        case "options":
+          data = await this.#elk.knownLayoutOptions();
+          break;
+        case "categories":
+          data = await this.#elk.knownLayoutCategories();
+          break;
+      }
+      this.#answer({ id: message.id, data });
+    } catch (error) {
+      this.#answer({ id: message.id, error });
+    }
+  }
+
+  #answer(answer: WorkerAnswer): void {
+    if (this.#terminated) return;
+    const event = { data: answer, type: "message" } as MessageEvent<WorkerAnswer>;
+    this.onmessage?.call(this, event);
+    this.dispatchEvent(event);
+  }
+}