@statelyai/graph 1.0.0 → 2.1.0

package/dist/layout/index.mjs

@@ -0,0 +1,181 @@
+import { d as getLCA } from "../queries-BMM0XAv_.mjs";
+
+//#region src/layout/index.ts
+/** Fallback node size when neither `measure` nor node dimensions are set. */
+const DEFAULT_NODE_SIZE = {
+	width: 100,
+	height: 50
+};
+/**
+* Resolve a node's layout size: `options.measure` → node `width`/`height` →
+* {@link DEFAULT_NODE_SIZE}. Zero sizes count as unset (layout engines
+* overlap zero-sized nodes).
+*/
+function getNodeSize(node, options) {
+	const measured = options?.measure?.(node);
+	if (measured) return measured;
+	const width = node.width !== void 0 && node.width > 0 ? node.width : 0;
+	const height = node.height !== void 0 && node.height > 0 ? node.height : 0;
+	return {
+		width: width || DEFAULT_NODE_SIZE.width,
+		height: height || DEFAULT_NODE_SIZE.height
+	};
+}
+/**
+* **Mutable.** Write a {@link LayoutFrame}'s positions onto the graph's nodes
+* in place. Positions are non-structural, so this is safe under the index
+* contract (no `invalidateIndex` needed) and cheap enough for per-animation-
+* frame use. Nodes absent from the frame are left untouched.
+*
+* @example
+* ```ts
+* for (const frame of genForceLayout(graph)) {
+*   applyLayoutFrame(graph, frame);
+*   render(graph);
+* }
+* ```
+*/
+function applyLayoutFrame(graph, frame) {
+	for (const node of graph.nodes) {
+		const position = frame.positions[node.id];
+		if (position !== void 0) {
+			node.x = position.x;
+			node.y = position.y;
+		}
+	}
+}
+/**
+* Bounding rect of all positioned nodes (and edge route points, when
+* present). Returns a zero rect for graphs with no geometry.
+*
+* @example
+* ```ts
+* const bounds = getLayoutBounds(laidOut);
+* svg.setAttribute('viewBox', `${bounds.x} ${bounds.y} ${bounds.width} ${bounds.height}`);
+* ```
+*/
+function getLayoutBounds(graph) {
+	let minX = Infinity;
+	let minY = Infinity;
+	let maxX = -Infinity;
+	let maxY = -Infinity;
+	for (const node of graph.nodes) {
+		if (node.x === void 0 || node.y === void 0) continue;
+		minX = Math.min(minX, node.x);
+		minY = Math.min(minY, node.y);
+		maxX = Math.max(maxX, node.x + (node.width ?? 0));
+		maxY = Math.max(maxY, node.y + (node.height ?? 0));
+	}
+	for (const edge of graph.edges) for (const point of edge.points ?? []) {
+		minX = Math.min(minX, point.x);
+		minY = Math.min(minY, point.y);
+		maxX = Math.max(maxX, point.x);
+		maxY = Math.max(maxY, point.y);
+	}
+	if (minX === Infinity) return {
+		x: 0,
+		y: 0,
+		width: 0,
+		height: 0
+	};
+	return {
+		x: minX,
+		y: minY,
+		width: maxX - minX,
+		height: maxY - minY
+	};
+}
+/**
+* Animate between two layouts of the same graph: yields interpolated
+* {@link LayoutFrame}s from the node positions in `from` to those in `to`
+* (drive them with {@link applyLayoutFrame}, e.g. one per animation frame),
+* and returns `to`. This is what makes layouts swappable live — lay out with
+* one engine, re-lay out with another, and tween between them.
+*
+* Nodes are matched by id; nodes without a position in `from` (or absent from
+* it) start at their `to` position. Edge routes are not interpolated — frames
+* carry node positions only; hide or re-route edges during the transition.
+* `alpha` cools linearly 1 → 0 like the physics layouts.
+*
+* @example
+* ```ts
+* const next = await getElkLayout(graph);
+* for (const frame of genLayoutTransition(graph, next)) {
+*   applyLayoutFrame(graph, frame);
+*   render(graph);
+* }
+* ```
+*/
+function* genLayoutTransition(from, to, options) {
+	const steps = Math.max(1, Math.floor(options?.steps ?? 30));
+	const ease = options?.ease ?? ((t) => t * t * (3 - 2 * t));
+	const fromById = new Map(from.nodes.map((node) => [node.id, node]));
+	const tweens = to.nodes.map((node) => {
+		const fromNode = fromById.get(node.id);
+		const hasStart = fromNode?.x !== void 0 && fromNode.y !== void 0;
+		return {
+			id: node.id,
+			startX: hasStart ? fromNode.x : node.x,
+			startY: hasStart ? fromNode.y : node.y,
+			endX: node.x,
+			endY: node.y
+		};
+	});
+	for (let step = 1; step <= steps; step++) {
+		const t = ease(step / steps);
+		const positions = {};
+		for (const tween of tweens) positions[tween.id] = {
+			x: tween.startX + (tween.endX - tween.startX) * t,
+			y: tween.startY + (tween.endY - tween.startY) * t
+		};
+		yield {
+			positions,
+			alpha: 1 - step / steps
+		};
+	}
+	return to;
+}
+/**
+* **Mutable.** Shift the graph's geometry by `(dx, dy)` in place: node
+* positions, edge route `points`, and edge label rects. Non-structural, so no
+* index invalidation is needed.
+*
+* Hierarchy-aware: child nodes (`parentId` set) use parent-relative
+* coordinates (the ELK/xyflow convention), so only top-level nodes are
+* shifted — children move with their parents. Likewise, an edge's geometry is
+* shifted only when its containing coordinate system is the root (the LCA of
+* its endpoints is no node).
+*/
+function translateGraph(graph, dx, dy) {
+	for (const node of graph.nodes) {
+		if (node.parentId != null) continue;
+		if (node.x !== void 0) node.x += dx;
+		if (node.y !== void 0) node.y += dy;
+	}
+	for (const edge of graph.edges) {
+		if (getLCA(graph, edge.sourceId, edge.targetId) !== void 0) continue;
+		if (edge.x !== void 0) edge.x += dx;
+		if (edge.y !== void 0) edge.y += dy;
+		for (const point of edge.points ?? []) {
+			point.x += dx;
+			point.y += dy;
+		}
+	}
+}
+/**
+* **Mutable.** Translate the graph in place so its {@link getLayoutBounds}
+* center coincides with `rect`'s center — e.g. center a fresh layout in the
+* viewport. Graphs without geometry are left untouched.
+*
+* @example
+* ```ts
+* centerGraph(laidOut, { x: 0, y: 0, width: canvas.width, height: canvas.height });
+* ```
+*/
+function centerGraph(graph, rect) {
+	const bounds = getLayoutBounds(graph);
+	translateGraph(graph, rect.x + rect.width / 2 - (bounds.x + bounds.width / 2), rect.y + rect.height / 2 - (bounds.y + bounds.height / 2));
+}
+
+//#endregion
+export { DEFAULT_NODE_SIZE, applyLayoutFrame, centerGraph, genLayoutTransition, getLayoutBounds, getNodeSize, translateGraph };

package/dist/layout/webcola.d.mts

@@ -0,0 +1,40 @@
+import { I as VisualGraph, f as Graph } from "../types-BAEQTwK_.mjs";
+import { LayoutOptions } from "./index.mjs";
+
+//#region src/layout/webcola.d.ts
+interface ColaLayoutOptions extends LayoutOptions {
+  /** Target distance between linked nodes. Default: 80. */
+  linkDistance?: number;
+}
+/**
+ * Constraint-based layout via WebCola (optional peer dependency). Runs the
+ * solver to convergence synchronously (`keepRunning: false`) and returns a
+ * positioned {@link VisualGraph}.
+ *
+ * - Overlap avoidance is always on: node rects (from `options.measure` →
+ *   node `width`/`height` → defaults) are kept disjoint.
+ * - Deterministic: WebCola itself has no `Math.random` in its 2D solver
+ *   (its descent uses an internally seeded PRNG), so the seeded initial
+ *   scatter (`options.seed`) fully pins the result — same seed, same layout.
+ * - `options.isFixed` pins positioned nodes at their current `x`/`y` (cola's
+ *   `fixed` flag). During overlap projection cola holds fixed nodes with a
+ *   large-but-finite weight, so pinning is within a small tolerance, not
+ *   exact.
+ * - `options.direction ?? graph.direction` set → DAG-flow constraints via
+ *   cola's `flowLayout`: edges are separated along the axis ('down'/'up' →
+ *   `y`, 'left'/'right' → `x`) by at least `spacing.layer` (default 50).
+ *   Note: cola only separates source-before-target along the axis — 'up' and
+ *   'left' flow the same way as 'down'/'right', not reversed.
+ * - Hierarchy is ignored (flat layout); self-loops are skipped by the solver
+ *   but kept in the output graph.
+ *
+ * @example
+ * ```ts
+ * import { getColaLayout } from '@statelyai/graph/layout/webcola';
+ *
+ * const laidOut = getColaLayout(graph, { seed: 42, direction: 'down' });
+ * ```
+ */
+declare function getColaLayout(graph: Graph | VisualGraph, options?: ColaLayoutOptions): VisualGraph;
+//#endregion
+export { ColaLayoutOptions, getColaLayout };

package/dist/layout/webcola.mjs

@@ -0,0 +1,104 @@
+import { f as createVisualGraph, n as toNodeConfig, t as toEdgeConfig } from "../config-Dt5u1gSf.mjs";
+import { getNodeSize } from "./index.mjs";
+import { Layout } from "webcola";
+
+//#region src/layout/webcola.ts
+/** mulberry32 — same seeded PRNG the rest of the library uses. */
+function mulberry32(seed) {
+	let s = seed | 0;
+	return () => {
+		s = s + 1831565813 | 0;
+		let t = Math.imul(s ^ s >>> 15, 1 | s);
+		t = t + Math.imul(t ^ t >>> 7, 61 | t) ^ t;
+		return ((t ^ t >>> 14) >>> 0) / 4294967296;
+	};
+}
+/**
+* Constraint-based layout via WebCola (optional peer dependency). Runs the
+* solver to convergence synchronously (`keepRunning: false`) and returns a
+* positioned {@link VisualGraph}.
+*
+* - Overlap avoidance is always on: node rects (from `options.measure` →
+*   node `width`/`height` → defaults) are kept disjoint.
+* - Deterministic: WebCola itself has no `Math.random` in its 2D solver
+*   (its descent uses an internally seeded PRNG), so the seeded initial
+*   scatter (`options.seed`) fully pins the result — same seed, same layout.
+* - `options.isFixed` pins positioned nodes at their current `x`/`y` (cola's
+*   `fixed` flag). During overlap projection cola holds fixed nodes with a
+*   large-but-finite weight, so pinning is within a small tolerance, not
+*   exact.
+* - `options.direction ?? graph.direction` set → DAG-flow constraints via
+*   cola's `flowLayout`: edges are separated along the axis ('down'/'up' →
+*   `y`, 'left'/'right' → `x`) by at least `spacing.layer` (default 50).
+*   Note: cola only separates source-before-target along the axis — 'up' and
+*   'left' flow the same way as 'down'/'right', not reversed.
+* - Hierarchy is ignored (flat layout); self-loops are skipped by the solver
+*   but kept in the output graph.
+*
+* @example
+* ```ts
+* import { getColaLayout } from '@statelyai/graph/layout/webcola';
+*
+* const laidOut = getColaLayout(graph, { seed: 42, direction: 'down' });
+* ```
+*/
+function getColaLayout(graph, options) {
+	const rng = mulberry32(options?.seed ?? 1);
+	const sizes = /* @__PURE__ */ new Map();
+	const scatterRadius = Math.max(80, 30 * Math.sqrt(graph.nodes.length));
+	const colaNodes = graph.nodes.map((node) => {
+		const size = getNodeSize(node, options);
+		sizes.set(node.id, size);
+		const colaNode = {
+			id: node.id,
+			...size
+		};
+		if (node.x !== void 0 && node.y !== void 0) {
+			colaNode.x = node.x + size.width / 2;
+			colaNode.y = node.y + size.height / 2;
+			if (options?.isFixed?.(node)) colaNode.fixed = 1;
+		} else {
+			const angle = rng() * 2 * Math.PI;
+			const radius = scatterRadius * Math.sqrt(rng());
+			colaNode.x = Math.cos(angle) * radius;
+			colaNode.y = Math.sin(angle) * radius;
+		}
+		return colaNode;
+	});
+	const indexById = new Map(graph.nodes.map((node, i) => [node.id, i]));
+	const colaLinks = graph.edges.filter((edge) => indexById.has(edge.sourceId) && indexById.has(edge.targetId) && edge.sourceId !== edge.targetId).map((edge) => ({
+		source: indexById.get(edge.sourceId),
+		target: indexById.get(edge.targetId)
+	}));
+	const layout = new Layout().nodes(colaNodes).links(colaLinks).linkDistance(options?.linkDistance ?? 80).avoidOverlaps(true);
+	const direction = options?.direction ?? graph.direction;
+	if (direction !== void 0) {
+		const axis = direction === "left" || direction === "right" ? "x" : "y";
+		layout.flowLayout(axis, options?.spacing?.layer ?? 50);
+	}
+	const centerGraph = !colaNodes.some((colaNode) => colaNode.fixed);
+	layout.start(30, 30, 60, 0, false, centerGraph);
+	const byId = new Map(colaNodes.map((colaNode) => [colaNode.id, colaNode]));
+	return createVisualGraph({
+		id: graph.id,
+		mode: graph.mode,
+		initialNodeId: graph.initialNodeId ?? void 0,
+		direction: graph.direction,
+		data: graph.data,
+		...graph.style !== void 0 && { style: graph.style },
+		nodes: graph.nodes.map((node) => {
+			const size = sizes.get(node.id);
+			const colaNode = byId.get(node.id);
+			return {
+				...toNodeConfig(node),
+				...size,
+				x: (colaNode.x ?? 0) - size.width / 2,
+				y: (colaNode.y ?? 0) - size.height / 2
+			};
+		}),
+		edges: graph.edges.map((edge) => toEdgeConfig(edge))
+	});
+}
+
+//#endregion
+export { getColaLayout };

package/dist/{queries-BlkA1HAN.d.mts → queries-B6quF529.d.mts}

@@ -1,4 +1,4 @@
-import { _ as GraphNode, b as GraphPort, p as GraphEdge, u as Graph } from "./types-3-FS9NV2.mjs";
+import { S as GraphPort, f as Graph, h as GraphEdge, y as GraphNode } from "./types-BAEQTwK_.mjs";
 
 //#region src/queries.d.ts
 
@@ -20,7 +20,9 @@ import { _ as GraphNode, b as GraphPort, p as GraphEdge, u as Graph } from "./ty
  */
 declare function getEdgesOf<N, E>(graph: Graph<N, E>, nodeId: string): GraphEdge<E>[];
 /**
- * Returns incoming edges to a node.
+ * Returns incoming edges to a node, by *authored* direction
+ * (`edge.targetId === nodeId`), regardless of edge mode. For mode-aware
+ * traversal use {@link getPredecessors} or {@link getEdgesOf}.
  *
  * @example
  * ```ts
@@ -36,7 +38,9 @@ declare function getEdgesOf<N, E>(graph: Graph<N, E>, nodeId: string): GraphEdge
  */
 declare function getInEdges<N, E>(graph: Graph<N, E>, nodeId: string): GraphEdge<E>[];
 /**
- * Returns outgoing edges from a node.
+ * Returns outgoing edges from a node, by *authored* direction
+ * (`edge.sourceId === nodeId`), regardless of edge mode. For mode-aware
+ * traversal use {@link getSuccessors} or {@link getEdgesOf}.
  *
  * @example
  * ```ts
@@ -69,7 +73,9 @@ declare function getOutEdges<N, E>(graph: Graph<N, E>, nodeId: string): GraphEdg
  */
 declare function getEdgesBetween<N, E>(graph: Graph<N, E>, sourceId: string, targetId: string): GraphEdge<E>[];
 /**
- * Returns direct successor nodes (targets of outgoing edges).
+ * Returns direct successor nodes — nodes reachable by traversing one edge
+ * away from `nodeId`. Edges whose effective mode is not `'directed'` are
+ * traversable both ways, so their other endpoint also counts as a successor.
  *
  * @example
  * ```ts
@@ -86,7 +92,9 @@ declare function getEdgesBetween<N, E>(graph: Graph<N, E>, sourceId: string, tar
  */
 declare function getSuccessors<N>(graph: Graph<N>, nodeId: string): GraphNode<N>[];
 /**
- * Returns direct predecessor nodes (sources of incoming edges).
+ * Returns direct predecessor nodes — nodes from which `nodeId` is reachable
+ * by traversing one edge. Edges whose effective mode is not `'directed'` are
+ * traversable both ways, so their other endpoint also counts as a predecessor.
  *
  * @example
  * ```ts
@@ -120,9 +128,10 @@ declare function getPredecessors<N>(graph: Graph<N>, nodeId: string): GraphNode<
  */
 declare function getNeighbors<N>(graph: Graph<N>, nodeId: string): GraphNode<N>[];
 /**
- * Returns the total degree of a node (inDegree + outDegree).
- * For graphs whose default mode is not `'directed'`, each incident edge is
- * counted once.
+ * Returns the total degree of a node (number of incident edge endpoints).
+ * Each incident edge whose effective mode is not `'directed'` is counted
+ * once (a non-directed self-loop counts once; a directed self-loop counts
+ * twice — once in, once out).
  *
  * @example
  * ```ts
@@ -139,7 +148,9 @@ declare function getNeighbors<N>(graph: Graph<N>, nodeId: string): GraphNode<N>[
  */
 declare function getDegree(graph: Graph, nodeId: string): number;
 /**
- * Returns the in-degree of a node (number of incoming edges).
+ * Returns the in-degree of a node — the number of edges traversable *into*
+ * the node. Edges whose effective mode is not `'directed'` count toward both
+ * endpoints' in-degree (once per edge).
  *
  * @example
  * ```ts
@@ -153,7 +164,9 @@ declare function getDegree(graph: Graph, nodeId: string): number;
  */
 declare function getInDegree(graph: Graph, nodeId: string): number;
 /**
- * Returns the out-degree of a node (number of outgoing edges).
+ * Returns the out-degree of a node — the number of edges traversable *out of*
+ * the node. Edges whose effective mode is not `'directed'` count toward both
+ * endpoints' out-degree (once per edge).
  *
  * @example
  * ```ts
@@ -207,6 +220,10 @@ declare function getParent<N>(graph: Graph<N>, nodeId: string): GraphNode<N> | u
 /**
  * Returns all ancestors from the node up to the root (nearest parent first).
  *
+ * If the parent chain contains a cycle (authored `parentId` cycles are not
+ * rejected by `createGraph`), the walk stops at the first repeated node and
+ * returns the ancestors collected so far — each ancestor appears exactly once.
+ *
  * @example
  * ```ts
  * const graph = createGraph({
@@ -224,6 +241,10 @@ declare function getAncestors<N>(graph: Graph<N>, nodeId: string): GraphNode<N>[
 /**
  * Returns all descendants recursively (depth-first).
  *
+ * If the hierarchy contains a parent cycle (authored `parentId` cycles are
+ * not rejected by `createGraph`), each node is visited at most once: the walk
+ * stops at the first repeated node and returns the descendants collected so far.
+ *
  * @example
  * ```ts
  * const graph = createGraph({
@@ -291,6 +312,10 @@ declare function isLeaf(graph: Graph, nodeId: string): boolean;
  * Depth of a node in the hierarchy (root = 0).
  * Returns -1 if the node is not found.
  *
+ * If the parent chain contains a cycle (authored `parentId` cycles are not
+ * rejected by `createGraph`), the walk stops at the first repeated node and
+ * returns the number of unique ancestors walked up to that point.
+ *
  * @example
  * ```ts
  * const graph = createGraph({
@@ -328,6 +353,10 @@ declare function getSiblings<N>(graph: Graph<N>, nodeId: string): GraphNode<N>[]
  * Least Common Ancestor -- deepest proper ancestor of all given nodes.
  * A proper ancestor excludes the input nodes themselves.
  *
+ * If a parent chain contains a cycle (authored `parentId` cycles are not
+ * rejected by `createGraph`), each chain walk stops at the first repeated
+ * node, so every ancestor is considered exactly once.
+ *
  * @example
  * ```ts
  * const graph = createGraph({
@@ -422,7 +451,8 @@ declare function getRelativeDistanceMap(graph: Graph, parentId: string | null):
  */
 declare function getRelativeDistance(graph: Graph, nodeId: string): number | undefined;
 /**
- * Nodes with no incoming edges (inDegree 0).
+ * Nodes with no incoming edges (inDegree 0). A node incident to an edge whose
+ * effective mode is not `'directed'` is never a source (the edge points in).
  *
  * @example
  * ```ts
@@ -439,7 +469,8 @@ declare function getRelativeDistance(graph: Graph, nodeId: string): number | und
  */
 declare function getSources<N>(graph: Graph<N>): GraphNode<N>[];
 /**
- * Nodes with no outgoing edges (outDegree 0).
+ * Nodes with no outgoing edges (outDegree 0). A node incident to an edge whose
+ * effective mode is not `'directed'` is never a sink (the edge points out).
  *
  * @example
  * ```ts