@eocrm/design-system 0.6.24 → 0.7.0

package/dist/components/FlowCanvas/FlowCanvas.module.js

@@ -0,0 +1,47 @@
+import "./FlowCanvas.css";
+// src/components/FlowCanvas/FlowCanvas.module.scss
+var root = "FlowCanvas__root__HGF7i";
+var rootPanning = "FlowCanvas__rootPanning__CsQ0v";
+var rootMaximized = "FlowCanvas__rootMaximized__s8CQL";
+var stage = "FlowCanvas__stage__O3Xh0";
+var edges = "FlowCanvas__edges__C7hva";
+var edgePath = "FlowCanvas__edgePath__Bz1wV";
+var edgeHit = "FlowCanvas__edgeHit__eGOQy";
+var markerFill = "FlowCanvas__markerFill__5dyHV";
+var markerFillActive = "FlowCanvas__markerFillActive__5pItR";
+var ghostEdge = "FlowCanvas__ghostEdge__9vQzs";
+var endpointHandle = "FlowCanvas__endpointHandle__Yulvb";
+var endpointDot = "FlowCanvas__endpointDot__nuEhT";
+var node = "FlowCanvas__node__Fqkmy";
+var nodeLabel = "FlowCanvas__nodeLabel__PqEtS";
+var handle = "FlowCanvas__handle__NJqV5";
+var chip = "FlowCanvas__chip__HKcJ2";
+var controls = "FlowCanvas__controls__f0VIq";
+var controlsTopLeft = "FlowCanvas__controlsTopLeft__u64nh";
+var controlsTopRight = "FlowCanvas__controlsTopRight__QH1fu";
+var selectionActions = "FlowCanvas__selectionActions__-Xx-6";
+var srOnly = "FlowCanvas__srOnly__qgWAY";
+var FlowCanvas_module_default = {
+	root,
+	rootPanning,
+	rootMaximized,
+	stage,
+	edges,
+	edgePath,
+	edgeHit,
+	markerFill,
+	markerFillActive,
+	ghostEdge,
+	endpointHandle,
+	endpointDot,
+	node,
+	nodeLabel,
+	handle,
+	chip,
+	controls,
+	controlsTopLeft,
+	controlsTopRight,
+	selectionActions,
+	srOnly
+};
+export { chip, controls, controlsTopLeft, controlsTopRight, FlowCanvas_module_default as default, edgeHit, edgePath, edges, endpointDot, endpointHandle, ghostEdge, handle, markerFill, markerFillActive, node, nodeLabel, root, rootMaximized, rootPanning, selectionActions, srOnly, stage };

package/dist/components/FlowCanvas/FlowControls.d.ts

@@ -0,0 +1,8 @@
+interface FlowControlsProps {
+    onZoomIn: () => void;
+    onZoomOut: () => void;
+    onFit: () => void;
+}
+/** Internal: the bottom-left zoom control cluster. */
+export declare function FlowControls({ onZoomIn, onZoomOut, onFit }: FlowControlsProps): import("react").JSX.Element;
+export {};

package/dist/components/FlowCanvas/FlowControls.js

@@ -0,0 +1,51 @@
+'use client';
+import { Button } from "../Button/Button.js";
+import { useTranslation } from "../../i18n/useTranslation.js";
+import FlowCanvas_module_default from "./FlowCanvas.module.js";
+import { jsx, jsxs } from "react/jsx-runtime";
+import { Maximize, ZoomIn, ZoomOut } from "lucide-react";
+// src/components/FlowCanvas/FlowControls.tsx
+/** Internal: the bottom-left zoom control cluster. */
+function FlowControls({ onZoomIn, onZoomOut, onFit }) {
+	const t = useTranslation();
+	return /* @__PURE__ */ jsxs("div", {
+		className: FlowCanvas_module_default.controls,
+		"data-flow-controls": "",
+		children: [
+			/* @__PURE__ */ jsx(Button, {
+				variant: "secondary",
+				size: "sm",
+				iconOnly: true,
+				"aria-label": t("flowCanvas.zoomIn"),
+				onClick: onZoomIn,
+				children: /* @__PURE__ */ jsx(ZoomIn, {
+					size: 16,
+					"aria-hidden": "true"
+				})
+			}),
+			/* @__PURE__ */ jsx(Button, {
+				variant: "secondary",
+				size: "sm",
+				iconOnly: true,
+				"aria-label": t("flowCanvas.zoomOut"),
+				onClick: onZoomOut,
+				children: /* @__PURE__ */ jsx(ZoomOut, {
+					size: 16,
+					"aria-hidden": "true"
+				})
+			}),
+			/* @__PURE__ */ jsx(Button, {
+				variant: "secondary",
+				size: "sm",
+				iconOnly: true,
+				"aria-label": t("flowCanvas.zoomToFit"),
+				onClick: onFit,
+				children: /* @__PURE__ */ jsx(Maximize, {
+					size: 16,
+					"aria-hidden": "true"
+				})
+			})
+		]
+	});
+}
+export { FlowControls };

package/dist/components/FlowCanvas/FlowEdge.d.ts

@@ -0,0 +1,18 @@
+import type { MouseEvent as ReactMouseEvent, PointerEvent as ReactPointerEvent } from 'react';
+import type { EdgeGeometry } from './edgePath.js';
+import type { FlowCanvasEdge } from './types.js';
+interface FlowEdgeProps {
+    edge: FlowCanvasEdge;
+    geometry: EdgeGeometry;
+    active: boolean;
+    markerId: string;
+    markerActiveId: string;
+    ariaLabel: string;
+    roleDescription: string;
+    registerEl: (id: string, el: SVGPathElement | null) => void;
+    onEdgePointerDown: (id: string, event: ReactPointerEvent<SVGPathElement>) => void;
+    onEdgeDoubleClick: (id: string, event: ReactMouseEvent<SVGPathElement>) => void;
+}
+/** Internal: one edge — visible path plus a wide transparent hit/focus path. */
+export declare const FlowEdge: import("react").MemoExoticComponent<({ edge, geometry, active, markerId, markerActiveId, ariaLabel, roleDescription, registerEl, onEdgePointerDown, onEdgeDoubleClick, }: FlowEdgeProps) => import("react").JSX.Element>;
+export {};

package/dist/components/FlowCanvas/FlowEdge.js

@@ -0,0 +1,29 @@
+'use client';
+import FlowCanvas_module_default from "./FlowCanvas.module.js";
+import { memo } from "react";
+import { jsx, jsxs } from "react/jsx-runtime";
+// src/components/FlowCanvas/FlowEdge.tsx
+/** Internal: one edge — visible path plus a wide transparent hit/focus path. */
+var FlowEdge = memo(function FlowEdge({ edge, geometry, active, markerId, markerActiveId, ariaLabel, roleDescription, registerEl, onEdgePointerDown, onEdgeDoubleClick }) {
+	return /* @__PURE__ */ jsxs("g", { children: [/* @__PURE__ */ jsx("path", {
+		className: FlowCanvas_module_default.edgePath,
+		d: geometry.path,
+		"data-active": active || void 0,
+		markerEnd: `url(#${active ? markerActiveId : markerId})`
+	}), /* @__PURE__ */ jsx("path", {
+		ref: (el) => registerEl(edge.id, el),
+		className: FlowCanvas_module_default.edgeHit,
+		d: geometry.path,
+		role: "button",
+		tabIndex: -1,
+		"aria-roledescription": roleDescription,
+		"aria-label": ariaLabel,
+		"data-flow-edge": edge.id,
+		onPointerDown: (event) => onEdgePointerDown(edge.id, event),
+		onDoubleClick: (event) => {
+			event.stopPropagation();
+			onEdgeDoubleClick(edge.id, event);
+		}
+	})] });
+});
+export { FlowEdge };

package/dist/components/FlowCanvas/FlowNode.d.ts

@@ -0,0 +1,19 @@
+import type { MouseEvent as ReactMouseEvent, PointerEvent as ReactPointerEvent } from 'react';
+import type { FlowCanvasNode, FlowCanvasPoint } from './types.js';
+interface FlowNodeProps {
+    node: FlowCanvasNode;
+    position: FlowCanvasPoint;
+    selected: boolean;
+    dragging: boolean;
+    connectTarget: boolean;
+    /** Whether connecting is enabled — gates the connect handle. */
+    canConnect: boolean;
+    roleDescription: string;
+    registerEl: (id: string, el: HTMLDivElement | null) => void;
+    onNodePointerDown: (id: string, event: ReactPointerEvent<HTMLDivElement>) => void;
+    onNodeDoubleClick: (id: string, event: ReactMouseEvent<HTMLDivElement>) => void;
+    onHandlePointerDown: (id: string, event: ReactPointerEvent<HTMLElement>) => void;
+}
+/** Internal: one node card. Positioned absolutely on the stage. */
+export declare const FlowNode: import("react").MemoExoticComponent<({ node, position, selected, dragging, connectTarget, canConnect, roleDescription, registerEl, onNodePointerDown, onNodeDoubleClick, onHandlePointerDown, }: FlowNodeProps) => import("react").JSX.Element>;
+export {};

package/dist/components/FlowCanvas/FlowNode.js

@@ -0,0 +1,48 @@
+'use client';
+import FlowCanvas_module_default from "./FlowCanvas.module.js";
+import { memo } from "react";
+import { jsx, jsxs } from "react/jsx-runtime";
+// src/components/FlowCanvas/FlowNode.tsx
+/** Internal: one node card. Positioned absolutely on the stage. */
+var FlowNode = memo(function FlowNode({ node, position, selected, dragging, connectTarget, canConnect, roleDescription, registerEl, onNodePointerDown, onNodeDoubleClick, onHandlePointerDown }) {
+	const style = {
+		left: position.x,
+		top: position.y
+	};
+	if (node.color) style["--flow-node-color"] = node.color;
+	return /* @__PURE__ */ jsxs("div", {
+		ref: (el) => registerEl(node.id, el),
+		role: "button",
+		tabIndex: -1,
+		"aria-roledescription": roleDescription,
+		"aria-label": node.label,
+		"data-flow-node": node.id,
+		"data-selected": selected || void 0,
+		"data-dragging": dragging || void 0,
+		"data-connect-target": connectTarget || void 0,
+		className: FlowCanvas_module_default.node,
+		style,
+		onPointerDown: (event) => onNodePointerDown(node.id, event),
+		onDoubleClick: (event) => {
+			event.stopPropagation();
+			onNodeDoubleClick(node.id, event);
+		},
+		children: [
+			/* @__PURE__ */ jsx("span", {
+				className: FlowCanvas_module_default.nodeLabel,
+				children: node.label
+			}),
+			node.adornment != null ? /* @__PURE__ */ jsx("span", { children: node.adornment }) : null,
+			canConnect ? /* @__PURE__ */ jsx("span", {
+				"aria-hidden": "true",
+				className: FlowCanvas_module_default.handle,
+				"data-flow-handle": "",
+				onPointerDown: (event) => {
+					event.stopPropagation();
+					onHandlePointerDown(node.id, event);
+				}
+			}) : null
+		]
+	});
+});
+export { FlowNode };

package/dist/components/FlowCanvas/edgePath.d.ts

@@ -0,0 +1,31 @@
+/** Axis-aligned rectangle in canvas coordinates. */
+export interface Rect {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+/** Point in canvas coordinates. */
+export interface Point {
+    x: number;
+    y: number;
+}
+/** SVG path plus the chip anchor point for one edge. */
+export interface EdgeGeometry {
+    /** `d` attribute for the SVG `<path>`. */
+    path: string;
+    /** True cubic midpoint (t = 0.5) — where the label chip is anchored. */
+    midpoint: Point;
+    /** Source anchor point (on the source node's facing side). */
+    source: Point;
+    /** Target anchor point (on the target node's facing side). */
+    target: Point;
+}
+/**
+ * Bezier between two node rects. Anchors on the facing sides (horizontal when
+ * |dx| ≥ |dy|, else vertical). `curvature` (±1) separates an A→B / B→A pair:
+ * pass opposite signs so the two edges bow apart; 0 for a lone edge.
+ */
+export declare function edgeGeometry(source: Rect, target: Rect, curvature?: -1 | 0 | 1): EdgeGeometry;
+/** Small loop arcing over a node's top-right corner, for self-referencing edges. */
+export declare function selfLoopGeometry(rect: Rect): EdgeGeometry;

package/dist/components/FlowCanvas/edgePath.js

@@ -0,0 +1,88 @@
+// src/components/FlowCanvas/edgePath.ts
+var MIN_STRENGTH = 40;
+var PAIR_SHIFT = 8;
+var PAIR_BOW = 24;
+function cubic(p0, c1, c2, p3) {
+	return {
+		path: `M ${p0.x} ${p0.y} C ${c1.x} ${c1.y}, ${c2.x} ${c2.y}, ${p3.x} ${p3.y}`,
+		midpoint: {
+			x: (p0.x + 3 * c1.x + 3 * c2.x + p3.x) / 8,
+			y: (p0.y + 3 * c1.y + 3 * c2.y + p3.y) / 8
+		},
+		source: p0,
+		target: p3
+	};
+}
+/**
+* Bezier between two node rects. Anchors on the facing sides (horizontal when
+* |dx| ≥ |dy|, else vertical). `curvature` (±1) separates an A→B / B→A pair:
+* pass opposite signs so the two edges bow apart; 0 for a lone edge.
+*/
+function edgeGeometry(source, target, curvature = 0) {
+	const sc = {
+		x: source.x + source.width / 2,
+		y: source.y + source.height / 2
+	};
+	const tc = {
+		x: target.x + target.width / 2,
+		y: target.y + target.height / 2
+	};
+	const dx = tc.x - sc.x;
+	const dy = tc.y - sc.y;
+	const bow = curvature * PAIR_BOW;
+	if (Math.abs(dx) >= Math.abs(dy)) {
+		const sign = dx >= 0 ? 1 : -1;
+		const p0 = {
+			x: sc.x + sign * source.width / 2,
+			y: sc.y + curvature * PAIR_SHIFT
+		};
+		const p3 = {
+			x: tc.x - sign * target.width / 2,
+			y: tc.y + curvature * PAIR_SHIFT
+		};
+		const strength = Math.max(MIN_STRENGTH, Math.abs(p3.x - p0.x) / 2);
+		return cubic(p0, {
+			x: p0.x + sign * strength,
+			y: p0.y + bow
+		}, {
+			x: p3.x - sign * strength,
+			y: p3.y + bow
+		}, p3);
+	}
+	const sign = dy >= 0 ? 1 : -1;
+	const p0 = {
+		x: sc.x + curvature * PAIR_SHIFT,
+		y: sc.y + sign * source.height / 2
+	};
+	const p3 = {
+		x: tc.x + curvature * PAIR_SHIFT,
+		y: tc.y - sign * target.height / 2
+	};
+	const strength = Math.max(MIN_STRENGTH, Math.abs(p3.y - p0.y) / 2);
+	return cubic(p0, {
+		x: p0.x + bow,
+		y: p0.y + sign * strength
+	}, {
+		x: p3.x + bow,
+		y: p3.y - sign * strength
+	}, p3);
+}
+/** Small loop arcing over a node's top-right corner, for self-referencing edges. */
+function selfLoopGeometry(rect) {
+	const p0 = {
+		x: rect.x + rect.width * .75,
+		y: rect.y
+	};
+	const p3 = {
+		x: rect.x + rect.width,
+		y: rect.y + rect.height * .25
+	};
+	return cubic(p0, {
+		x: p0.x + 10,
+		y: p0.y - 48
+	}, {
+		x: p3.x + 48,
+		y: p3.y - 10
+	}, p3);
+}
+export { edgeGeometry, selfLoopGeometry };

package/dist/components/FlowCanvas/index.d.ts

@@ -0,0 +1,4 @@
+export { FlowCanvas } from './FlowCanvas.js';
+export { arrangeNodes } from './layout.js';
+export type { FlowCanvasProps } from './FlowCanvas.js';
+export type { FlowCanvasPoint, FlowCanvasNode, FlowCanvasEdge, FlowCanvasSelection } from './types.js';

package/dist/components/FlowCanvas/layout.d.ts

@@ -0,0 +1,35 @@
+import type { FlowCanvasEdge, FlowCanvasNode, FlowCanvasPoint } from './types.js';
+/** Measured (or estimated) rendered size of a node, in canvas units. */
+export interface NodeSize {
+    width: number;
+    height: number;
+}
+/** Fallback node size used before ResizeObserver reports real ones (and in jsdom). */
+export declare const ESTIMATED_NODE_SIZE: NodeSize;
+/**
+ * Layered auto-layout: longest-path ranks from the graph's sources flow
+ * left → right; one barycenter pass orders nodes within a rank to reduce edge
+ * crossings; ranks are vertically centered against the tallest rank.
+ * Pure, deterministic, and cycle-safe (back-edges to on-stack nodes are
+ * skipped). Self-loops and edges to unknown nodes are ignored.
+ * Only nodes without an explicit `position` are laid out; a node WITH a
+ * `position` is pinned by the consumer and is ignored here — it neither
+ * occupies layout space nor anchors edges, so it never shifts the others.
+ */
+export declare function computeLayout(nodes: readonly FlowCanvasNode[], edges: readonly FlowCanvasEdge[], sizes?: ReadonlyMap<string, NodeSize>): Map<string, FlowCanvasPoint>;
+/**
+ * Lay out every node into the layered left→right auto-layout and return the
+ * nodes with `position` filled in — for a consumer-driven "re-arrange / tidy"
+ * action. Unlike {@link computeLayout} (which only places nodes without an
+ * explicit `position`), this re-flows ALL nodes, overwriting any existing
+ * `position`. Pure and deterministic; every other node field is preserved.
+ *
+ * Uses estimated node sizes, so vertical centering can differ by a few pixels
+ * from the live in-canvas layout (a standalone function cannot measure the
+ * rendered DOM). Fine for a tidy action.
+ *
+ * @example
+ * // A "Re-arrange" button in your own UI (e.g. the FlowCanvas `controls` slot):
+ * <Button onClick={() => setNodes((prev) => arrangeNodes(prev, edges))}>Re-arrange</Button>
+ */
+export declare function arrangeNodes(nodes: readonly FlowCanvasNode[], edges: readonly FlowCanvasEdge[]): FlowCanvasNode[];

package/dist/components/FlowCanvas/layout.js

@@ -0,0 +1,119 @@
+// src/components/FlowCanvas/layout.ts
+/** Fallback node size used before ResizeObserver reports real ones (and in jsdom). */
+var ESTIMATED_NODE_SIZE = {
+	width: 160,
+	height: 40
+};
+var RANK_GAP = 96;
+var NODE_GAP = 32;
+/**
+* Layered auto-layout: longest-path ranks from the graph's sources flow
+* left → right; one barycenter pass orders nodes within a rank to reduce edge
+* crossings; ranks are vertically centered against the tallest rank.
+* Pure, deterministic, and cycle-safe (back-edges to on-stack nodes are
+* skipped). Self-loops and edges to unknown nodes are ignored.
+* Only nodes without an explicit `position` are laid out; a node WITH a
+* `position` is pinned by the consumer and is ignored here — it neither
+* occupies layout space nor anchors edges, so it never shifts the others.
+*/
+function computeLayout(nodes, edges, sizes) {
+	const result = /* @__PURE__ */ new Map();
+	if (nodes.length === 0) return result;
+	const autoNodes = nodes.filter((node) => node.position === void 0);
+	if (autoNodes.length === 0) return result;
+	const ids = new Set(autoNodes.map((node) => node.id));
+	const out = /* @__PURE__ */ new Map();
+	const incoming = /* @__PURE__ */ new Map();
+	const indegree = /* @__PURE__ */ new Map();
+	for (const node of autoNodes) {
+		out.set(node.id, []);
+		incoming.set(node.id, []);
+		indegree.set(node.id, 0);
+	}
+	for (const edge of edges) {
+		if (!ids.has(edge.from) || !ids.has(edge.to) || edge.from === edge.to) continue;
+		out.get(edge.from).push(edge.to);
+		incoming.get(edge.to).push(edge.from);
+		indegree.set(edge.to, indegree.get(edge.to) + 1);
+	}
+	const rank = /* @__PURE__ */ new Map();
+	const onStack = /* @__PURE__ */ new Set();
+	const visit = (id, r) => {
+		if (onStack.has(id)) return;
+		const prev = rank.get(id);
+		if (prev !== void 0 && prev >= r) return;
+		rank.set(id, r);
+		onStack.add(id);
+		for (const next of out.get(id)) visit(next, r + 1);
+		onStack.delete(id);
+	};
+	const sources = autoNodes.filter((node) => indegree.get(node.id) === 0);
+	for (const source of sources.length > 0 ? sources : [autoNodes[0]]) visit(source.id, 0);
+	for (const node of autoNodes) if (!rank.has(node.id)) visit(node.id, 0);
+	const ranks = [];
+	for (const node of autoNodes) {
+		const r = rank.get(node.id);
+		(ranks[r] ??= []).push(node);
+	}
+	const orderIndex = /* @__PURE__ */ new Map();
+	for (const bucket of ranks) bucket?.forEach((node, i) => orderIndex.set(node.id, i));
+	for (let r = 1; r < ranks.length; r++) {
+		const bucket = ranks[r];
+		if (!bucket) continue;
+		const score = (node) => {
+			const preds = incoming.get(node.id);
+			if (preds.length === 0) return orderIndex.get(node.id);
+			return preds.reduce((sum, p) => sum + (orderIndex.get(p) ?? 0), 0) / preds.length;
+		};
+		bucket.sort((a, b) => score(a) - score(b) || orderIndex.get(a.id) - orderIndex.get(b.id));
+		bucket.forEach((node, i) => orderIndex.set(node.id, i));
+	}
+	const sizeOf = (id) => sizes?.get(id) ?? ESTIMATED_NODE_SIZE;
+	const rankHeights = ranks.map((bucket) => (bucket ?? []).reduce((sum, node, i) => sum + sizeOf(node.id).height + (i > 0 ? NODE_GAP : 0), 0));
+	const maxHeight = Math.max(0, ...rankHeights);
+	let x = 0;
+	for (let r = 0; r < ranks.length; r++) {
+		const bucket = ranks[r] ?? [];
+		let y = (maxHeight - (rankHeights[r] ?? 0)) / 2;
+		let maxWidth = 0;
+		for (const node of bucket) {
+			result.set(node.id, {
+				x,
+				y
+			});
+			y += sizeOf(node.id).height + NODE_GAP;
+			maxWidth = Math.max(maxWidth, sizeOf(node.id).width);
+		}
+		x += (maxWidth || ESTIMATED_NODE_SIZE.width) + RANK_GAP;
+	}
+	return result;
+}
+/**
+* Lay out every node into the layered left→right auto-layout and return the
+* nodes with `position` filled in — for a consumer-driven "re-arrange / tidy"
+* action. Unlike {@link computeLayout} (which only places nodes without an
+* explicit `position`), this re-flows ALL nodes, overwriting any existing
+* `position`. Pure and deterministic; every other node field is preserved.
+*
+* Uses estimated node sizes, so vertical centering can differ by a few pixels
+* from the live in-canvas layout (a standalone function cannot measure the
+* rendered DOM). Fine for a tidy action.
+*
+* @example
+* // A "Re-arrange" button in your own UI (e.g. the FlowCanvas `controls` slot):
+* <Button onClick={() => setNodes((prev) => arrangeNodes(prev, edges))}>Re-arrange</Button>
+*/
+function arrangeNodes(nodes, edges) {
+	const layout = computeLayout(nodes.map((node) => ({
+		...node,
+		position: void 0
+	})), edges);
+	return nodes.map((node) => {
+		const position = layout.get(node.id);
+		return position ? {
+			...node,
+			position
+		} : node;
+	});
+}
+export { ESTIMATED_NODE_SIZE, arrangeNodes, computeLayout };

package/dist/components/FlowCanvas/spatialNav.d.ts

@@ -0,0 +1,12 @@
+import type { Rect } from './edgePath.js';
+/** Arrow-key direction for spatial node navigation. */
+export type NavDirection = 'up' | 'down' | 'left' | 'right';
+/**
+ * Nearest node in an arrow direction, judged by rect centers. Candidates must
+ * lie strictly in that direction; off-axis distance is penalized 2× so
+ * aligned neighbors win over closer diagonal ones. Returns null when nothing
+ * lies that way.
+ */
+export declare function nearestInDirection(currentId: string, rects: ReadonlyMap<string, Rect>, direction: NavDirection): string | null;
+/** Topmost node, ties broken by leftmost — the initial arrow-key focus target. */
+export declare function topLeftMost(rects: ReadonlyMap<string, Rect>): string | null;

package/dist/components/FlowCanvas/spatialNav.js

@@ -0,0 +1,63 @@
+// src/components/FlowCanvas/spatialNav.ts
+function center(rect) {
+	return {
+		x: rect.x + rect.width / 2,
+		y: rect.y + rect.height / 2
+	};
+}
+/**
+* Nearest node in an arrow direction, judged by rect centers. Candidates must
+* lie strictly in that direction; off-axis distance is penalized 2× so
+* aligned neighbors win over closer diagonal ones. Returns null when nothing
+* lies that way.
+*/
+function nearestInDirection(currentId, rects, direction) {
+	const current = rects.get(currentId);
+	if (!current) return null;
+	const cc = center(current);
+	let best = null;
+	let bestScore = Infinity;
+	for (const [id, rect] of rects) {
+		if (id === currentId) continue;
+		const c = center(rect);
+		const dx = c.x - cc.x;
+		const dy = c.y - cc.y;
+		let primary;
+		let secondary;
+		switch (direction) {
+			case "right":
+				primary = dx;
+				secondary = Math.abs(dy);
+				break;
+			case "left":
+				primary = -dx;
+				secondary = Math.abs(dy);
+				break;
+			case "down":
+				primary = dy;
+				secondary = Math.abs(dx);
+				break;
+			case "up":
+				primary = -dy;
+				secondary = Math.abs(dx);
+		}
+		if (primary <= .5) continue;
+		const score = primary + secondary * 2;
+		if (score < bestScore) {
+			bestScore = score;
+			best = id;
+		}
+	}
+	return best;
+}
+/** Topmost node, ties broken by leftmost — the initial arrow-key focus target. */
+function topLeftMost(rects) {
+	let best = null;
+	let bestRect = null;
+	for (const [id, rect] of rects) if (bestRect === null || rect.y < bestRect.y || rect.y === bestRect.y && rect.x < bestRect.x) {
+		best = id;
+		bestRect = rect;
+	}
+	return best;
+}
+export { nearestInDirection, topLeftMost };

package/dist/components/FlowCanvas/types.d.ts

@@ -0,0 +1,58 @@
+import type { ReactNode } from 'react';
+/** A point in canvas coordinates (px at zoom 1, origin at the stage's top-left). */
+export interface FlowCanvasPoint {
+    /** Horizontal offset in canvas units. */
+    x: number;
+    /** Vertical offset in canvas units. */
+    y: number;
+}
+/** One node (vertex) on the canvas. */
+export interface FlowCanvasNode {
+    /** Stable unique id. Referenced by edges and every intent callback. */
+    id: string;
+    /**
+     * Plain-text label rendered inside the node. Also used verbatim for
+     * screen-reader announcements — keep it human-readable.
+     */
+    label: string;
+    /**
+     * Accent color for the node's left bar as a CSS color (typically `#RRGGBB`).
+     * Defaults to the accent token when omitted.
+     */
+    color?: string;
+    /**
+     * Position in canvas coordinates. When omitted the node is auto-laid-out
+     * (layered, left → right) and remains user-draggable for the session.
+     * A node with an explicit `position` is *pinned*: it stays where you place it
+     * and does not participate in — or perturb — the auto-layout of the other
+     * nodes. Use `arrangeNodes(nodes, edges)` to re-flow the whole graph.
+     */
+    position?: FlowCanvasPoint;
+    /**
+     * Slot rendered after the label — badges, icons, counters. Not announced to
+     * screen readers; keep essential state in `label` or the consumer's own UI.
+     * Avoid interactive elements (buttons, inputs): the node itself is a
+     * `role="button"`, so nested controls are invisible to assistive tech
+     * (nested-interactive) even though their keystrokes are let through.
+     */
+    adornment?: ReactNode;
+}
+/** One directed edge between two nodes. */
+export interface FlowCanvasEdge {
+    /** Stable unique id. Referenced by selection and intent callbacks. */
+    id: string;
+    /** Source node id. */
+    from: string;
+    /** Target node id. */
+    to: string;
+    /**
+     * Slot rendered as a chip at the edge midpoint (e.g. a "Guard" badge).
+     * Not announced to screen readers.
+     */
+    label?: ReactNode;
+}
+/** Current single selection: a node, an edge, or nothing. */
+export type FlowCanvasSelection = {
+    type: 'node' | 'edge';
+    id: string;
+} | null;