@statelyai/layout 0.1.3 → 0.3.0

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);
+  }
+}

package/src/index.ts

@@ -71,6 +71,10 @@ export type {
   EdgeRoutes,
   LayerAssigner,
   LayerAssignment,
+  CompoundVisualGraph,
+  CompoundLayoutOptions,
+  CompoundLayoutGeometry,
+  CompoundEdgeAttachment,
   LayeredLayoutOptions,
   LayeredAdvancedOptions,
   ElkLayeredOptionId,
@@ -90,3 +94,18 @@ export type {
   NodePlacer,
   NodeSize,
 } from "./layered";
+
+export { c } from "./constraints";
+export type {
+  LayoutConstraint,
+  GeometryReference,
+  GeometryAttribute,
+  ConstraintStrength,
+  AlignConstraint,
+  DistributeConstraint,
+  PinConstraint,
+  LinearConstraint,
+  WaypointConstraint,
+} from "./constraints";
+
+export * from "./routing";

package/src/internal/elkjs-compatibility.ts

@@ -0,0 +1,17 @@
+import type { VisualGraph } from "@statelyai/graph";
+
+export interface Elkjs0111ResultPolicy {
+  providerBounds?: { width: number; height: number };
+  preserveEdgeSections?: boolean;
+  skipBoundsNormalization?: boolean;
+}
+
+export const elkjs0111ResultPolicy = Symbol("elkjs0111ResultPolicy");
+
+export function setElkjs0111ResultPolicy<N, E, G, P>(
+  graph: VisualGraph<N, E, G, P>,
+  policy: Elkjs0111ResultPolicy,
+): VisualGraph<N, E, G, P> {
+  Object.defineProperty(graph, elkjs0111ResultPolicy, { value: policy });
+  return graph;
+}

package/src/internal/layout-engine.ts

@@ -0,0 +1,126 @@
+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 {
+  elkjs0111RectanglePackingAlgorithm,
+  rectanglePackingAlgorithm,
+  type RectanglePackingLayoutOptions,
+} from "../packing";
+import { elkjs0111RandomAlgorithm, randomAlgorithm, type RandomLayoutOptions } from "../random";
+import {
+  sporeCompactionAlgorithm,
+  sporeOverlapRemovalAlgorithm,
+  type SporeLayoutOptions,
+} from "../spore";
+import type { LayoutAlgorithm, LayoutExecutionContext } from "../types";
+
+export interface BuiltInLayoutOptionsById {
+  box: BoxLayoutOptions;
+  fixed: FixedLayoutOptions;
+  layered: LayeredLayoutOptions;
+  random: RandomLayoutOptions;
+  rectpacking: RectanglePackingLayoutOptions;
+  sporeCompaction: SporeLayoutOptions;
+  sporeOverlap: SporeLayoutOptions;
+}
+
+export type BuiltInLayoutAlgorithmId = keyof BuiltInLayoutOptionsById;
+
+export const builtInLayoutAlgorithms = {
+  box: boxAlgorithm,
+  fixed: fixedAlgorithm,
+  layered: layeredAlgorithm,
+  random: randomAlgorithm,
+  rectpacking: rectanglePackingAlgorithm,
+  sporeCompaction: sporeCompactionAlgorithm,
+  sporeOverlap: sporeOverlapRemovalAlgorithm,
+} satisfies {
+  [Id in BuiltInLayoutAlgorithmId]: LayoutAlgorithm<BuiltInLayoutOptionsById[Id]>;
+};
+
+const elkjs0111LayoutAlgorithms = {
+  ...builtInLayoutAlgorithms,
+  box: elkjs0111BoxAlgorithm,
+  random: elkjs0111RandomAlgorithm,
+  rectpacking: elkjs0111RectanglePackingAlgorithm,
+} satisfies {
+  [Id in BuiltInLayoutAlgorithmId]: LayoutAlgorithm<BuiltInLayoutOptionsById[Id]>;
+};
+
+export function getBuiltInLayoutAlgorithm(id: string): LayoutAlgorithm<unknown> | undefined {
+  if (!Object.hasOwn(builtInLayoutAlgorithms, id)) return undefined;
+  return builtInLayoutAlgorithms[id as BuiltInLayoutAlgorithmId] as
+    | LayoutAlgorithm<unknown>
+    | undefined;
+}
+
+interface ExecuteLayoutAlgorithmRequest<N, E, G, P, O> {
+  algorithm: LayoutAlgorithm<O>;
+  graph: Graph<N, E, G, P> | VisualGraph<N, E, G, P>;
+  options: O;
+  context: LayoutExecutionContext;
+}
+
+/** Execute one algorithm through the shared engine seam. */
+export function executeLayoutAlgorithm<N, E, G, P, O>({
+  algorithm,
+  graph,
+  options,
+  context,
+}: ExecuteLayoutAlgorithmRequest<N, E, G, P, O>):
+  | VisualGraph<N, E, G, P>
+  | Promise<VisualGraph<N, E, G, P>> {
+  return algorithm.layout(graph, options, context);
+}
+
+function createDirectExecutionContext(): LayoutExecutionContext {
+  return {
+    scope: { mode: "full" },
+    diagnostics: [],
+    measurePhase(_id, run) {
+      return run();
+    },
+    throwIfAborted() {},
+  };
+}
+
+interface ExecuteBuiltInLayoutRequest<N, E, G, P, Id extends BuiltInLayoutAlgorithmId> {
+  algorithm: Id;
+  graph: Graph<N, E, G, P> | VisualGraph<N, E, G, P>;
+  options: BuiltInLayoutOptionsById[Id];
+}
+
+/** Execute a built-in algorithm through the shared engine seam. */
+export function executeBuiltInLayout<N, E, G, P, Id extends BuiltInLayoutAlgorithmId>({
+  algorithm,
+  graph,
+  options,
+}: ExecuteBuiltInLayoutRequest<N, E, G, P, Id>):
+  | VisualGraph<N, E, G, P>
+  | Promise<VisualGraph<N, E, G, P>> {
+  return executeLayoutAlgorithm({
+    algorithm: builtInLayoutAlgorithms[algorithm] as LayoutAlgorithm<BuiltInLayoutOptionsById[Id]>,
+    graph,
+    options,
+    context: createDirectExecutionContext(),
+  });
+}
+
+/** Execute through the pinned elkjs 0.11.1 compatibility policy. */
+export function executeElkjs0111Layout<N, E, G, P, Id extends BuiltInLayoutAlgorithmId>({
+  algorithm,
+  graph,
+  options,
+}: ExecuteBuiltInLayoutRequest<N, E, G, P, Id>):
+  | VisualGraph<N, E, G, P>
+  | Promise<VisualGraph<N, E, G, P>> {
+  return executeLayoutAlgorithm({
+    algorithm: elkjs0111LayoutAlgorithms[algorithm] as LayoutAlgorithm<
+      BuiltInLayoutOptionsById[Id]
+    >,
+    graph,
+    options,
+    context: createDirectExecutionContext(),
+  });
+}