@statelyai/layout 0.1.3 → 0.2.0

package/src/index.ts

@@ -90,3 +90,16 @@ export type {
   NodePlacer,
   NodeSize,
 } from "./layered";
+
+export { c } from "./constraints";
+export type {
+  LayoutConstraint,
+  GeometryReference,
+  GeometryAttribute,
+  ConstraintStrength,
+  AlignConstraint,
+  DistributeConstraint,
+  PinConstraint,
+  LinearConstraint,
+  WaypointConstraint,
+} from "./constraints";

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

package/src/layered/index.ts

@@ -1,4 +1,5 @@
 import type { Graph, GraphEdge, GraphNode, Point, VisualGraph, VisualNode } from "@statelyai/graph";
+import { labelReferences, runPartialLayout } from "../authoring/partial";
 import { UnsupportedLayoutError } from "../errors";
 import type { LayoutAlgorithm, LayoutExecutionContext } from "../types";
 import { separateExteriorLabels } from "./separate-exterior-labels";
@@ -2679,12 +2680,39 @@ export const layeredAlgorithm: LayoutAlgorithm<LayeredLayoutOptions> = {
   capabilities: {
     full: true,
     incremental: false,
-    partial: false,
-    routeOnly: false,
+    partial: true,
+    routeOnly: true,
+    constraints: true,
     hierarchy: true,
     ports: true,
   },
   layout(graph, options, context) {
-    return runLayeredPipeline(graph, options ?? {}, context);
+    if (context.scope.mode === "partial" || context.scope.mode === "route-only") {
+      return context.measurePhase("partial-layout", () =>
+        runPartialLayout(graph, options ?? {}, context, getLayeredLayout),
+      );
+    }
+    if (context.constraints?.length && graph.nodes.some((node) => node.parentId != null))
+      throw new UnsupportedLayoutError(
+        "Full layout with geometry constraints does not support containers; use partial leaf constraints or full layout without geometry constraints",
+      );
+    const result = runLayeredPipeline(graph, options ?? {}, context);
+    if (!context.constraints?.length) return result;
+    return context.measurePhase("constraints", () =>
+      runPartialLayout(
+        result,
+        options ?? {},
+        {
+          ...context,
+          scope: {
+            mode: "partial",
+            nodeIds: result.nodes.map((n) => n.id),
+            edgeIds: [...labelReferences(context.constraints ?? [])],
+          },
+        },
+        getLayeredLayout,
+        "constraints",
+      ),
+    );
   },
 };

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/types.ts

@@ -1,4 +1,5 @@
 import type { Graph, GraphPatch, VisualGraph } from "@statelyai/graph";
+import type { LayoutConstraint } from "./constraints";
 
 export type AnyGraph = Graph<unknown, unknown, unknown, unknown>;
 
@@ -12,8 +13,16 @@ export type LayoutScope =
     }
   | {
       mode: "partial";
-      previous: VisualGraph;
-      nodeIds: readonly string[];
+      /** Missing current geometry falls back to these matching entity IDs. */
+      previous?: VisualGraph;
+      /** Position permission only. Omitted or empty selects no nodes. */
+      nodeIds?: readonly string[];
+      /** Edge selection never grants permission to move endpoints. */
+      edgeIds?: readonly string[];
+      /** Defaults to affected; automatic changes obey edgeGeometry. */
+      routing?: "selected" | "affected";
+      /** Defaults to both; dimensions remain fixed. */
+      edgeGeometry?: "routes" | "labels" | "both";
     }
   | {
       mode: "route-only";
@@ -27,6 +36,8 @@ export interface LayoutDiagnostic {
   message: string;
   entityIds?: readonly string[];
   phase?: string;
+  constraintIds?: readonly string[];
+  geometry?: "node" | "routes" | "labels";
 }
 
 export interface LayoutPhaseMetrics {
@@ -42,6 +53,8 @@ export interface LayoutMetrics {
 }
 
 export interface LayoutCapabilities {
+  /** Common geometry constraints; absent means unsupported. */
+  constraints?: boolean;
   full: boolean;
   incremental: boolean;
   partial: boolean;
@@ -62,6 +75,7 @@ export interface LayoutAlgorithm<Options = unknown> {
 
 export interface LayoutExecutionContext {
   readonly scope: LayoutScope;
+  readonly constraints?: readonly LayoutConstraint[];
   readonly signal?: AbortSignal;
   readonly diagnostics: LayoutDiagnostic[];
   measurePhase<T>(id: string, run: () => T): T;
@@ -73,6 +87,7 @@ export interface LayoutRequest<N = unknown, E = unknown, G = unknown, P = unknow
   algorithm?: string | LayoutAlgorithm<O>;
   options?: O;
   scope?: LayoutScope;
+  constraints?: readonly LayoutConstraint[];
   signal?: AbortSignal;
 }