@statelyai/layout 0.1.3 → 0.3.0

package/src/layout.ts

@@ -1,11 +1,10 @@
 import { getGraphIssues, type Graph, type GraphPatch, type VisualGraph } from "@statelyai/graph";
 import { LayoutError, UnsupportedLayoutError } from "./errors";
-import { boxAlgorithm } from "./box";
-import { fixedAlgorithm } from "./fixed";
-import { layeredAlgorithm } from "./layered";
-import { rectanglePackingAlgorithm } from "./packing";
-import { randomAlgorithm } from "./random";
-import { sporeCompactionAlgorithm, sporeOverlapRemovalAlgorithm } from "./spore";
+import {
+  builtInLayoutAlgorithms,
+  executeLayoutAlgorithm,
+  getBuiltInLayoutAlgorithm,
+} from "./internal/layout-engine";
 import type {
   LayoutAlgorithm,
   LayoutDiagnostic,
@@ -16,15 +15,12 @@ import type {
   LayoutScope,
 } from "./types";
 
-const algorithms = new Map<string, LayoutAlgorithm<never>>([
-  ["box", boxAlgorithm as LayoutAlgorithm<never>],
-  ["layered", layeredAlgorithm as LayoutAlgorithm<never>],
-  ["fixed", fixedAlgorithm as LayoutAlgorithm<never>],
-  ["rectpacking", rectanglePackingAlgorithm as LayoutAlgorithm<never>],
-  ["random", randomAlgorithm as LayoutAlgorithm<never>],
-  ["sporeCompaction", sporeCompactionAlgorithm as LayoutAlgorithm<never>],
-  ["sporeOverlap", sporeOverlapRemovalAlgorithm as LayoutAlgorithm<never>],
-]);
+const algorithms = new Map<string, LayoutAlgorithm<never>>(
+  Object.entries(builtInLayoutAlgorithms).map(([id, algorithm]) => [
+    id,
+    algorithm as LayoutAlgorithm<never>,
+  ]),
+);
 
 function supportsScope(algorithm: LayoutAlgorithm<unknown>, scope: LayoutScope): boolean {
   switch (scope.mode) {
@@ -73,11 +69,11 @@ function getLayoutPatches<N, E, G, P>(
         op: "updateNode",
         id: node.id,
         data: {
-          x: next.x,
-          y: next.y,
-          width: next.width,
-          height: next.height,
-          ...(next.ports === undefined ? {} : { ports: next.ports }),
+          ...(node.x === next.x ? {} : { x: next.x ?? null }),
+          ...(node.y === next.y ? {} : { y: next.y ?? null }),
+          ...(node.width === next.width ? {} : { width: next.width ?? null }),
+          ...(node.height === next.height ? {} : { height: next.height ?? null }),
+          ...(node.ports === next.ports ? {} : { ports: next.ports ?? null }),
         },
         description: "Apply layout geometry",
       });
@@ -98,12 +94,12 @@ function getLayoutPatches<N, E, G, P>(
         op: "updateEdge",
         id: edge.id,
         data: {
-          x: next.x,
-          y: next.y,
-          width: next.width,
-          height: next.height,
-          ...(next.routing === undefined ? {} : { routing: next.routing }),
-          ...(next.points === undefined ? {} : { points: next.points }),
+          ...(edge.x === next.x ? {} : { x: next.x ?? null }),
+          ...(edge.y === next.y ? {} : { y: next.y ?? null }),
+          ...(edge.width === next.width ? {} : { width: next.width ?? null }),
+          ...(edge.height === next.height ? {} : { height: next.height ?? null }),
+          ...(edge.routing === next.routing ? {} : { routing: next.routing ?? null }),
+          ...(samePoints(edge.points, next.points) ? {} : { points: next.points ?? null }),
         },
         description: "Apply layout geometry",
       });
@@ -123,7 +119,9 @@ export function registerLayoutAlgorithm<O>(algorithm: LayoutAlgorithm<O>): () =>
 }
 
 export function getLayoutAlgorithm(id: string): LayoutAlgorithm<unknown> | undefined {
-  return algorithms.get(id) as LayoutAlgorithm<unknown> | undefined;
+  return (
+    (algorithms.get(id) as LayoutAlgorithm<unknown> | undefined) ?? getBuiltInLayoutAlgorithm(id)
+  );
 }
 
 /**
@@ -152,6 +150,9 @@ export async function getLayout<N, E, G, P, O = unknown>(
     throw new UnsupportedLayoutError(`${algorithm.id} does not support ${scope.mode} layout yet`);
   }
 
+  if (request.constraints?.length && !algorithm.capabilities.constraints) {
+    throw new UnsupportedLayoutError(`${algorithm.id} does not support geometry constraints`);
+  }
   const issues = getGraphIssues(request.graph as Graph);
   if (issues.length > 0) {
     throw new LayoutError(issues.map((issue) => issue.message).join("; "), "INVALID_GRAPH");
@@ -159,6 +160,7 @@ export async function getLayout<N, E, G, P, O = unknown>(
 
   const context: LayoutExecutionContext = {
     scope,
+    constraints: request.constraints,
     diagnostics,
     ...(request.signal === undefined ? {} : { signal: request.signal }),
     measurePhase(id, run) {
@@ -185,7 +187,12 @@ export async function getLayout<N, E, G, P, O = unknown>(
     },
   };
   context.throwIfAborted();
-  const graph = await algorithm.layout(request.graph, request.options as O, context);
+  const graph = await executeLayoutAlgorithm({
+    algorithm: algorithm as LayoutAlgorithm<O>,
+    graph: request.graph,
+    options: request.options as O,
+    context,
+  });
   context.throwIfAborted();
 
   return {

package/src/packing.ts

@@ -1,6 +1,7 @@
 import type { Graph, VisualGraph, VisualNode } from "@statelyai/graph";
 import { getNodeSize, type LayoutOptions } from "@statelyai/graph/layout";
 import { getFixedLayout } from "./fixed";
+import { setElkjs0111ResultPolicy } from "./internal/elkjs-compatibility";
 import type { LayoutPadding } from "./layered";
 import type { LayoutAlgorithm } from "./types";
 
@@ -72,3 +73,24 @@ export const rectanglePackingAlgorithm: LayoutAlgorithm<RectanglePackingLayoutOp
     return getRectanglePackingLayout(graph, options ?? {});
   },
 };
+
+/** Pinned output policy used only by the elkjs 0.11.1 compatibility adapter. */
+export const elkjs0111RectanglePackingAlgorithm: LayoutAlgorithm<RectanglePackingLayoutOptions> = {
+  ...rectanglePackingAlgorithm,
+  layout(graph, options = {}) {
+    const result = getRectanglePackingLayout(graph, options);
+    const padding = getPadding(options.padding);
+    return setElkjs0111ResultPolicy(result, {
+      providerBounds:
+        result.nodes.length === 0
+          ? { width: 0, height: 0 }
+          : {
+              width: Math.max(...result.nodes.map((node) => node.x + node.width)) + padding.right,
+              height:
+                Math.max(...result.nodes.map((node) => node.y + node.height)) + padding.bottom,
+            },
+      preserveEdgeSections: true,
+      skipBoundsNormalization: true,
+    });
+  },
+};

package/src/random.ts

@@ -8,6 +8,7 @@
 import type { Graph, Point, VisualGraph, VisualNode } from "@statelyai/graph";
 import { getNodeSize, type LayoutOptions } from "@statelyai/graph/layout";
 import { getFixedLayout } from "./fixed";
+import { setElkjs0111ResultPolicy } from "./internal/elkjs-compatibility";
 import { JavaRandom } from "./java-random";
 import type { LayoutPadding } from "./layered";
 import type { LayoutAlgorithm } from "./types";
@@ -19,6 +20,21 @@ export interface RandomLayoutOptions extends Pick<LayoutOptions, "direction" | "
   seed?: number;
 }
 
+interface RandomLayoutBehavior {
+  elkjs0111EdgeTargetBug: boolean;
+  preserveProviderBounds: boolean;
+}
+
+const nativeBehavior: RandomLayoutBehavior = {
+  elkjs0111EdgeTargetBug: false,
+  preserveProviderBounds: false,
+};
+
+const elkjs0111Behavior: RandomLayoutBehavior = {
+  elkjs0111EdgeTargetBug: true,
+  preserveProviderBounds: true,
+};
+
 function getPadding(value: RandomLayoutOptions["padding"]): LayoutPadding {
   if (typeof value === "number") {
     return { top: value, right: value, bottom: value, left: value };
@@ -54,6 +70,14 @@ function borderPoint(source: VisualNode, target: VisualNode): Point {
 export function getRandomLayout<N, E, G, P>(
   graph: Graph<N, E, G, P> | VisualGraph<N, E, G, P>,
   options: RandomLayoutOptions = {},
+): VisualGraph<N, E, G, P> {
+  return getRandomLayoutWithBehavior(graph, options, nativeBehavior);
+}
+
+function getRandomLayoutWithBehavior<N, E, G, P>(
+  graph: Graph<N, E, G, P> | VisualGraph<N, E, G, P>,
+  options: RandomLayoutOptions,
+  behavior: RandomLayoutBehavior,
 ): VisualGraph<N, E, G, P> {
   if (graph.nodes.length === 0) return getFixedLayout(graph, options);
   const random = new JavaRandom(options.seed && options.seed !== 0 ? options.seed : Date.now());
@@ -82,10 +106,36 @@ export function getRandomLayout<N, E, G, P>(
   const nodeById = new Map(nodes.map((node) => [node.id, node]));
   const totalWidth = drawWidth + padding.left + padding.right;
   const totalHeight = drawHeight + padding.top + padding.bottom;
-  const edges = graph.edges.map((edge) => {
+  const layoutEdge = (edge: (typeof graph.edges)[number]) => {
     const source = nodeById.get(edge.sourceId);
     const target = nodeById.get(edge.targetId);
     if (!source || !target) return edge;
+    if (behavior.elkjs0111EdgeTargetBug) {
+      const start = { x: source.x + source.width, y: source.y + source.height / 2 };
+      const end = { x: source.x + source.width / 2, y: source.y + source.height };
+      const bendCount = random.nextInt(5) + 1;
+      const xDifference = end.x - start.x;
+      const yDifference = end.y - start.y;
+      const maximumDeviation = Math.hypot(xDifference, yDifference) * Math.fround(0.2);
+      const xIncrement = xDifference / (bendCount + 1);
+      const yIncrement = yDifference / (bendCount + 1);
+      let x = start.x;
+      let y = start.y;
+      const points: Point[] = [start];
+      for (let index = 0; index < bendCount; index++) {
+        x += xIncrement;
+        y += yIncrement;
+        let randomX = x + random.nextFloat() * maximumDeviation - maximumDeviation / 2;
+        if (randomX < 0) randomX = 1;
+        else if (randomX > totalWidth) randomX = totalWidth - 1;
+        let randomY = y + random.nextFloat() * maximumDeviation - maximumDeviation / 2;
+        if (randomY < 0) randomY = 1;
+        else if (randomY > totalHeight) randomY = totalHeight - 1;
+        points.push({ x: randomX, y: randomY });
+      }
+      points.push(end);
+      return { ...edge, points, routing: "polyline" as const };
+    }
     const start = borderPoint(source, target);
     const end = borderPoint(target, source);
     const bendCount = random.nextInt(5) + (source === target ? 1 : 0);
@@ -119,11 +169,25 @@ export function getRandomLayout<N, E, G, P>(
     }
     points.push(end);
     return { ...edge, points, routing: "polyline" as const };
-  });
-  return getFixedLayout(
+  };
+  const edges = behavior.elkjs0111EdgeTargetBug
+    ? graph.nodes.flatMap((node) =>
+        graph.edges.filter((edge) => edge.sourceId === node.id).map(layoutEdge),
+      )
+    : graph.edges.map(layoutEdge);
+  const result = getFixedLayout(
     { ...graph, nodes, edges },
     { direction: options.direction ?? graph.direction },
   );
+  if (behavior.preserveProviderBounds) {
+    setElkjs0111ResultPolicy(result, {
+      providerBounds: {
+        width: drawWidth + 2 * (padding.left + padding.right),
+        height: drawHeight + 2 * (padding.top + padding.bottom),
+      },
+    });
+  }
+  return result;
 }
 
 export const randomAlgorithm: LayoutAlgorithm<RandomLayoutOptions> = {
@@ -140,3 +204,11 @@ export const randomAlgorithm: LayoutAlgorithm<RandomLayoutOptions> = {
     return getRandomLayout(graph, options ?? {});
   },
 };
+
+/** Pinned behavior used only by the elkjs 0.11.1 compatibility adapter. */
+export const elkjs0111RandomAlgorithm: LayoutAlgorithm<RandomLayoutOptions> = {
+  ...randomAlgorithm,
+  layout(graph, options) {
+    return getRandomLayoutWithBehavior(graph, options ?? {}, elkjs0111Behavior);
+  },
+};

package/src/routing/adapters.ts

@@ -0,0 +1,111 @@
+import type { GraphPatch, Point, VisualGraph } from "@statelyai/graph";
+import { hasCurrentRouteGeometry } from "./layout-cache";
+import { worldGeometry } from "../authoring/coordinates";
+import { freeze } from "./model";
+import { flattenPath, pathFromPoints } from "./path";
+import { PersistentMap } from "./persistent";
+import type { Route, RoutePath, RoutePoint, RouteSegment } from "./types";
+
+/** ELK/native spline output: start, then repeating control1/control2/end triples. */
+export function pathFromSplinePoints(points: readonly RoutePoint[]): RoutePath {
+  if (points.length < 4 || (points.length - 1) % 3 !== 0)
+    throw new RangeError("Cubic spline points require a start and control1/control2/end triples");
+  const segments: RouteSegment[] = [];
+  for (let i = 1; i < points.length; i += 3)
+    segments.push({
+      kind: "cubic",
+      control1: { ...points[i]! },
+      control2: { ...points[i + 1]! },
+      to: { ...points[i + 2]! },
+    });
+  return { start: { ...points[0]! }, segments };
+}
+/** Normalize routes from any native layout algorithm, without running layout again. */
+export function getLayoutRoutes(graph: VisualGraph): ReadonlyMap<string, Route> {
+  const compound = graph as VisualGraph & { compoundRoutes?: ReadonlyMap<string, Route> };
+  if (compound.compoundRoutes?.size && hasCurrentRouteGeometry(graph, compound.compoundRoutes))
+    return compound.compoundRoutes;
+  const world = worldGeometry(graph),
+    nodes = new Map(world.nodes.map((n) => [n.id, n]));
+  let result = new PersistentMap<Route>();
+  for (const edge of world.edges) {
+    const points = edge.points;
+    let path: RoutePath | undefined;
+    if (points?.length && points.every((p) => Number.isFinite(p.x) && Number.isFinite(p.y))) {
+      if (edge.routing === "splines") {
+        if (points.length >= 4 && (points.length - 1) % 3 === 0)
+          path = pathFromSplinePoints(points);
+      } else path = pathFromPoints(points);
+    }
+    const routed = path !== undefined;
+    if (!path) {
+      const a = nodes.get(edge.sourceId),
+        b = nodes.get(edge.targetId);
+      path = pathFromPoints([
+        { x: a ? a.x + a.width : 0, y: a ? a.y + a.height / 2 : 0 },
+        { x: b?.x ?? 40, y: b ? b.y + b.height / 2 : 40 },
+      ]);
+    }
+    result = result.set(
+      edge.id,
+      freeze({
+        edgeId: edge.id,
+        status: routed ? "routed" : "fallback",
+        diagnostics: routed
+          ? []
+          : [
+              {
+                code: "MISSING_GEOMETRY",
+                edgeId: edge.id,
+                message: "Layout has no valid route; rendered a fallback connection",
+              },
+            ],
+        sections: [
+          {
+            id: `${edge.id}:0`,
+            from: {
+              kind: "node",
+              nodeId: edge.sourceId,
+              ...(edge.sourcePort === undefined ? {} : { port: edge.sourcePort }),
+            },
+            to: {
+              kind: "node",
+              nodeId: edge.targetId,
+              ...(edge.targetPort === undefined ? {} : { port: edge.targetPort }),
+            },
+            path,
+          },
+        ],
+      }),
+    );
+  }
+  return result;
+}
+/** One polyline per section preserves label gaps and branching for simple renderers. */
+export function routeToPolylines(
+  route: Route,
+  options?: { readonly tolerance?: number },
+): readonly (readonly RoutePoint[])[] {
+  return route.sections.map((s) => flattenPath(s.path, options));
+}
+/** Compatibility for single-section native consumers. Refuses to erase gaps or topology. */
+export function routeToGraphPatch(
+  route: Route,
+  options: { readonly tolerance?: number; readonly offset?: RoutePoint } = {},
+): GraphPatch {
+  if (
+    route.sections.length !== 1 ||
+    route.sections[0]!.sharedId ||
+    route.sections[0]!.from.kind !== "node" ||
+    route.sections[0]!.to.kind !== "node"
+  )
+    throw new Error(
+      "This route requires section-aware rendering; a single GraphEdge.points array would lose topology",
+    );
+  const offset = options.offset ?? { x: 0, y: 0 };
+  const points: Point[] = flattenPath(route.sections[0]!.path, options).map((p) => ({
+    x: p.x - offset.x,
+    y: p.y - offset.y,
+  }));
+  return { op: "updateEdge", id: route.edgeId, data: { points, routing: "polyline" } };
+}