@statelyai/layout 0.2.0 → 0.4.0

package/src/layered/types.ts

@@ -1,5 +1,7 @@
+import type { NativeRoutingStrategy, RoutingSettings } from "../routing/types";
 import type { EntityRect, Graph, GraphEdge, GraphNode, GraphPort, Point } from "@statelyai/graph";
 import type { LayoutConstraints } from "@statelyai/graph/layout";
+import type { LayoutHint } from "./hints";
 import type { LayoutDirection } from "../types";
 import type { ElkLayeredOptionValueByName, LayeredAdvancedOptions } from "./elk-options";
 
@@ -21,6 +23,8 @@ export interface LayoutPadding {
 }
 
 export interface LayeredPhaseInput {
+  /** Authored edge order retained through label and long-edge expansion. */
+  modelOrderByEdgeId?: ReadonlyMap<string, number>;
   graph: Graph<unknown, unknown, unknown, unknown>;
   sizes: ReadonlyMap<string, NodeSize>;
   direction: LayoutDirection;
@@ -38,12 +42,15 @@ export interface AcyclicOrientation {
 }
 
 export interface LayerAssignment {
+  layerCount?: number;
   layerByNodeId: ReadonlyMap<string, number>;
   /** Layer-internal seed order produced by layerers whose insertion order is observable. */
   seedOrder?: readonly string[];
 }
 
 export interface LayerOrder {
+  /** Canonical clockwise physical port identities, independent of edge reversal. */
+  physicalPortOrderByNodeId?: ReadonlyMap<string, readonly string[]>;
   layers: readonly (readonly string[])[];
   /** Internal ELK sweep state retained for exact port-aware placement. */
   inputPortOrderByNodeId?: ReadonlyMap<string, readonly string[]>;
@@ -57,6 +64,8 @@ export interface NodePlacement {
 
 export interface EdgeRoutes {
   pointsByEdgeId: ReadonlyMap<string, readonly Point[]>;
+  /** Branch points generated on physical orthogonal hypersegments before restoration. */
+  junctionPointsByEdgeId?: ReadonlyMap<string, readonly Point[]>;
   /** ELK spline segment NUB controls retained until long-edge joining. */
   splineNubControlsByEdgeId?: ReadonlyMap<string, readonly Point[]>;
   /** Reversed fixed-side routes that must stay outside the node envelope during compaction. */
@@ -92,11 +101,36 @@ export interface LayeredStrategies {
   routeEdges?: EdgeRouter;
 }
 
+/** Geometry reserved while laying out a compound, before its ancestors. */
+export interface CompoundLayoutOptions {
+  padding?: number | Partial<LayoutPadding>;
+  direction?: LayoutDirection;
+  header?: NodeSize & { side?: "top" | "right" | "bottom" | "left" };
+  minContentSize?: Partial<NodeSize>;
+}
+export interface CompoundLayoutGeometry {
+  /** Parent-relative outer rectangle; header/content are relative to this rectangle. */
+  bounds: EntityRect;
+  header?: EntityRect;
+  content: EntityRect;
+}
+export interface CompoundEdgeAttachment {
+  /** Content attachments leave toward the interior; outer attachments leave outward. */
+  source?: "content" | "outer";
+  target?: "content" | "outer";
+}
+
 export interface LayeredLayoutOptions {
+  /** Replace initial routes after initial placement and routing, without moving geometry. */
+  routing?: { strategy: Pick<NativeRoutingStrategy, "route">; settings?: RoutingSettings };
   direction?: LayoutDirection;
+  compound?: (node: GraphNode) => CompoundLayoutOptions | undefined;
+  edgeAttachment?: (edge: GraphEdge) => CompoundEdgeAttachment | undefined;
   spacing?: Partial<LayeredSpacing>;
   padding?: number | Partial<LayoutPadding>;
   constraints?: LayoutConstraints;
+  /** Reader-facing preferences applied during layering, ordering and placement. */
+  hints?: readonly LayoutHint[];
   measure?: (node: GraphNode) => NodeSize;
   crossingSweeps?: number;
   strategies?: LayeredStrategies;

package/src/layered/weighted-compaction.ts

@@ -0,0 +1,84 @@
+/*******************************************************************************
+ * Copyright (c) 2017 Kiel University and others.
+ *
+ * Adapted from ELK v0.11.0 NetworkSimplexCompaction.java.
+ * Source commit: 54123e884b1ae743b453260f713b20c9bf5787f2
+ * SPDX-License-Identifier: EPL-2.0
+ *******************************************************************************/
+import { runNetworkSimplex, type SimplexEdge, type SimplexNode } from "./network-simplex";
+import { InfeasibleCompactionError } from "./compaction-errors";
+
+export interface CompactionConstraint {
+  source: string;
+  target: string;
+  delta: number;
+  weight: number;
+}
+
+/** Minimize weighted separation subject to integral lower-bound constraints. */
+export function solveWeightedCompaction(
+  groupIds: readonly string[],
+  constraints: readonly CompactionConstraint[],
+): Map<string, number> {
+  const nodes = groupIds.map((id, order): SimplexNode => ({
+    id,
+    order,
+    layer: 0,
+    incoming: [],
+    outgoing: [],
+    treeNode: false,
+  }));
+  if (nodes.length === 0) return new Map();
+  const byId = new Map(nodes.map((node) => [node.id, node]));
+  const edges: SimplexEdge[] = [];
+  const add = (source: SimplexNode, target: SimplexNode, delta: number, weight: number): void => {
+    const edge: SimplexEdge = {
+      id: `constraint:${edges.length}`,
+      order: edges.length,
+      source,
+      target,
+      delta: Math.max(0, Math.ceil(delta)),
+      weight,
+      treeEdge: false,
+    };
+    edges.push(edge);
+    source.outgoing.push(edge);
+    target.incoming.push(edge);
+  };
+  for (const constraint of constraints) {
+    const source = byId.get(constraint.source);
+    const target = byId.get(constraint.target);
+    if (!source || !target) throw new Error("Unknown compaction group");
+    if (source !== target) add(source, target, constraint.delta, constraint.weight);
+  }
+  // Fail explicitly on invalid constraint cycles rather than hanging tight-tree growth.
+  const remaining = new Map(nodes.map((node) => [node, node.incoming.length]));
+  const queue = nodes.filter((node) => node.incoming.length === 0);
+  let visited = 0;
+  for (let index = 0; index < queue.length; index++) {
+    const node = queue[index]!;
+    visited++;
+    for (const edge of node.outgoing) {
+      const count = remaining.get(edge.target)! - 1;
+      remaining.set(edge.target, count);
+      if (count === 0) queue.push(edge.target);
+    }
+  }
+  if (visited !== nodes.length)
+    throw new InfeasibleCompactionError("Cyclic compaction constraints");
+  const sources = nodes.filter((node) => node.incoming.length === 0);
+  if (sources.length > 1) {
+    const source: SimplexNode = {
+      id: "",
+      order: nodes.length,
+      layer: 0,
+      incoming: [],
+      outgoing: [],
+      treeNode: false,
+    };
+    nodes.push(source);
+    for (const target of sources) add(source, target, 1, 0);
+  }
+  runNetworkSimplex(nodes, edges, Number.MAX_SAFE_INTEGER, undefined, false);
+  return new Map(groupIds.map((id) => [id, byId.get(id)!.layer]));
+}

package/src/routing/adapters.ts

@@ -0,0 +1,143 @@
+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));
+}
+/**
+ * One point list for consumers of `GraphEdge.points`. Sections are joined
+ * through their gaps (an edge label, for example); between orthogonal
+ * sections the join is orthogonal too, so it never adds a diagonal.
+ */
+export function routeToPoints(
+  route: Route,
+  options?: { readonly tolerance?: number },
+): RoutePoint[] {
+  const points: RoutePoint[] = [];
+  const axis = (a: RoutePoint, b: RoutePoint) =>
+    Math.abs(a.y - b.y) < 1e-9 ? "horizontal" : Math.abs(a.x - b.x) < 1e-9 ? "vertical" : undefined;
+  for (const polyline of routeToPolylines(route, options)) {
+    const a = points.at(-1),
+      b = polyline[0];
+    if (a && b && axis(a, b) === undefined) {
+      const before = points.length > 1 ? axis(points.at(-2)!, a) : undefined;
+      const after = polyline.length > 1 ? axis(b, polyline[1]!) : undefined;
+      if (before && after) {
+        if (before === "horizontal" && after === "horizontal") {
+          const x = (a.x + b.x) / 2;
+          points.push({ x, y: a.y }, { x, y: b.y });
+        } else if (before === "vertical" && after === "vertical") {
+          const y = (a.y + b.y) / 2;
+          points.push({ x: a.x, y }, { x: b.x, y });
+        } else points.push(before === "horizontal" ? { x: b.x, y: a.y } : { x: a.x, y: b.y });
+      }
+    }
+    points.push(...polyline.map((point) => ({ ...point })));
+  }
+  return points;
+}
+/** 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" } };
+}