@elabs-ai/components-flow 4.0.0

package/src/flow-smart-edge/flow-smart-edge.tsx

@@ -0,0 +1,75 @@
+import {
+  BaseEdge,
+  getBezierPath,
+  useInternalNode,
+  type EdgeProps,
+  type InternalNode,
+} from "@xyflow/react";
+import type { FlowNodeData } from "../flow-node";
+import {
+  pickClosestHandles,
+  rectCenter,
+  sideToPosition,
+  slideAnchor,
+  type NodeRect,
+} from "./smart-edge-geometry";
+
+function toRect(node: InternalNode): NodeRect {
+  return {
+    x: node.internals.positionAbsolute.x,
+    y: node.internals.positionAbsolute.y,
+    width: node.measured.width ?? 0,
+    height: node.measured.height ?? 0,
+  };
+}
+
+/**
+ * Branded edge that picks the closest source/target handle pair (from a node's
+ * multi-side `FlowNodeHandles` config) and routes a bezier between them. Anchors
+ * are recomputed every render, so they flip as nodes are dragged. Register it in
+ * `edgeTypes={{ smart: FlowSmartEdge }}` and give the connected nodes a
+ * `data.handles` config. Uses the `--flow-edge` token, matching `FlowEdge`.
+ */
+export function FlowSmartEdge({ id, source, target, markerEnd, style }: EdgeProps) {
+  const sourceNode = useInternalNode(source);
+  const targetNode = useInternalNode(target);
+  if (!sourceNode || !targetNode) return null;
+
+  const sourceData = sourceNode.internals.userNode.data as FlowNodeData | undefined;
+  const targetData = targetNode.internals.userNode.data as FlowNodeData | undefined;
+
+  const sourceRect = toRect(sourceNode);
+  const targetRect = toRect(targetNode);
+
+  // Pick which side of each node the edge exits/enters (the facing handle side).
+  const { sourceSide, targetSide } = pickClosestHandles(
+    sourceRect,
+    sourceData?.handles?.source ?? [],
+    targetRect,
+    targetData?.handles?.target ?? [],
+  );
+
+  // Then slide each anchor along its chosen side toward the OTHER node, so
+  // edges sharing a side fan out to distinct, target-facing points instead of
+  // stacking on the side midpoint.
+  const sourceAnchor = slideAnchor(sourceRect, sourceSide, rectCenter(targetRect));
+  const targetAnchor = slideAnchor(targetRect, targetSide, rectCenter(sourceRect));
+
+  const [edgePath] = getBezierPath({
+    sourceX: sourceAnchor.x,
+    sourceY: sourceAnchor.y,
+    sourcePosition: sideToPosition[sourceSide],
+    targetX: targetAnchor.x,
+    targetY: targetAnchor.y,
+    targetPosition: sideToPosition[targetSide],
+  });
+
+  return (
+    <BaseEdge
+      id={id}
+      path={edgePath}
+      markerEnd={markerEnd}
+      style={{ stroke: "var(--flow-edge)", strokeWidth: 1.5, ...style }}
+    />
+  );
+}

package/src/flow-smart-edge/index.ts

@@ -0,0 +1,9 @@
+export { FlowSmartEdge } from "./flow-smart-edge";
+export {
+  HANDLE_SIDES,
+  sideToPosition,
+  handlePoint,
+  pickClosestHandles,
+  type NodeRect,
+  type ClosestHandles,
+} from "./smart-edge-geometry";

package/src/flow-smart-edge/smart-edge-geometry.test.ts

@@ -0,0 +1,120 @@
+import { describe, expect, it, vi } from "vitest";
+
+// smart-edge-geometry imports the `Position` enum (a value) from @xyflow/react.
+// Mock it to the Position constants so the pure picker runs in jsdom.
+vi.mock("@xyflow/react", () => ({
+  Position: { Left: "left", Top: "top", Right: "right", Bottom: "bottom" },
+}));
+
+import {
+  handlePoint,
+  pickClosestHandles,
+  rectCenter,
+  sideToPosition,
+  slideAnchor,
+  HANDLE_SIDES,
+  type NodeRect,
+} from "./smart-edge-geometry";
+
+const rect = (x: number, y: number, width = 100, height = 60): NodeRect => ({
+  x,
+  y,
+  width,
+  height,
+});
+
+describe("handlePoint", () => {
+  it("returns the midpoint of each side", () => {
+    const r = rect(0, 0, 100, 60);
+    expect(handlePoint(r, "top")).toEqual({ x: 50, y: 0 });
+    expect(handlePoint(r, "bottom")).toEqual({ x: 50, y: 60 });
+    expect(handlePoint(r, "left")).toEqual({ x: 0, y: 30 });
+    expect(handlePoint(r, "right")).toEqual({ x: 100, y: 30 });
+  });
+});
+
+describe("sideToPosition", () => {
+  it("maps every side to the matching Position value", () => {
+    expect(sideToPosition.top).toBe("top");
+    expect(sideToPosition.right).toBe("right");
+    expect(sideToPosition.bottom).toBe("bottom");
+    expect(sideToPosition.left).toBe("left");
+  });
+});
+
+describe("pickClosestHandles", () => {
+  it("target to the right → source uses its right handle, target its left", () => {
+    const source = rect(0, 0);
+    const target = rect(300, 0);
+    const picked = pickClosestHandles(source, ["right", "left"], target, ["left", "right"]);
+
+    expect(picked.sourceSide).toBe("right");
+    expect(picked.targetSide).toBe("left");
+    expect(picked.sx).toBeCloseTo(100);
+    expect(picked.tx).toBeCloseTo(300);
+  });
+
+  it("target below → source uses bottom, target uses top", () => {
+    const picked = pickClosestHandles(rect(0, 0), ["top", "bottom"], rect(0, 300), [
+      "top",
+      "bottom",
+    ]);
+    expect(picked.sourceSide).toBe("bottom");
+    expect(picked.targetSide).toBe("top");
+  });
+
+  it("target up-and-to-the-left flips to the near corner sides", () => {
+    // Target sits above-left of the source.
+    const picked = pickClosestHandles(rect(300, 300), HANDLE_SIDES, rect(0, 0), HANDLE_SIDES);
+    expect(["top", "left"]).toContain(picked.sourceSide);
+    expect(["bottom", "right"]).toContain(picked.targetSide);
+  });
+
+  it("falls back to all four sides when a side list is empty", () => {
+    const picked = pickClosestHandles(rect(0, 0), [], rect(300, 0), []);
+    expect(picked.sourceSide).toBe("right");
+    expect(picked.targetSide).toBe("left");
+  });
+});
+
+describe("rectCenter", () => {
+  it("returns the node's centre", () => {
+    expect(rectCenter(rect(0, 0, 100, 60))).toEqual({ x: 50, y: 30 });
+  });
+});
+
+describe("slideAnchor", () => {
+  const r = rect(0, 0, 100, 60); // usable right/left span [12, 48], top/bottom span [12, 88]
+
+  it("stays on the chosen side's axis", () => {
+    expect(slideAnchor(r, "right", { x: 999, y: 30 }).x).toBe(100);
+    expect(slideAnchor(r, "left", { x: -999, y: 30 }).x).toBe(0);
+    expect(slideAnchor(r, "top", { x: 30, y: -999 }).y).toBe(0);
+    expect(slideAnchor(r, "bottom", { x: 30, y: 999 }).y).toBe(60);
+  });
+
+  it("slides toward the target and clamps within the inset", () => {
+    // Target far above → clamp to the top of the usable range (inset 12).
+    expect(slideAnchor(r, "right", { x: 100, y: -500 }).y).toBe(12);
+    // Target far below → clamp to the bottom of the usable range.
+    expect(slideAnchor(r, "right", { x: 100, y: 500 }).y).toBe(48);
+    // Target within range → follows it.
+    expect(slideAnchor(r, "right", { x: 100, y: 30 }).y).toBe(30);
+  });
+
+  it("fans two edges on the same side to distinct anchors", () => {
+    // The Ingest→Transform (up) vs Ingest→Publish (down) case, both leaving right.
+    const up = slideAnchor(r, "right", { x: 400, y: -200 });
+    const down = slideAnchor(r, "right", { x: 400, y: 200 });
+    expect(up.y).toBeLessThan(down.y);
+    expect(up.y).not.toBe(down.y);
+  });
+
+  it("never inverts the range on a tiny node", () => {
+    const tiny = rect(0, 0, 10, 10); // inset (12) capped to width/2 = 5
+    const p = slideAnchor(tiny, "right", { x: 100, y: -100 });
+    expect(p.x).toBe(10);
+    expect(p.y).toBeGreaterThanOrEqual(0);
+    expect(p.y).toBeLessThanOrEqual(10);
+  });
+});

package/src/flow-smart-edge/smart-edge-geometry.ts

@@ -0,0 +1,116 @@
+import { Position } from "@xyflow/react";
+import type { FlowHandleSide } from "../flow-node";
+
+/** Axis-aligned node rectangle in absolute flow coordinates. */
+export interface NodeRect {
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+}
+
+/** All four candidate handle sides, in a stable order. */
+export const HANDLE_SIDES: FlowHandleSide[] = ["top", "right", "bottom", "left"];
+
+/** Maps a handle side to the React Flow `Position` used for bezier control. */
+export const sideToPosition: Record<FlowHandleSide, Position> = {
+  top: Position.Top,
+  right: Position.Right,
+  bottom: Position.Bottom,
+  left: Position.Left,
+};
+
+/** Center point of a node rectangle. */
+export function rectCenter(rect: NodeRect): { x: number; y: number } {
+  return { x: rect.x + rect.width / 2, y: rect.y + rect.height / 2 };
+}
+
+/**
+ * The connection point on `side` of `rect`, slid along that side toward
+ * `toward` and clamped `inset` px from the corners. This is what stops two
+ * edges that both leave the same side (e.g. both targets sit to the right)
+ * from piling onto the side's midpoint: each edge's anchor slides toward its
+ * own target, so an up-going edge exits the upper part of the side and a
+ * down-going edge the lower part — each visibly meeting the node on the side
+ * that faces its target instead of stacking in the middle.
+ */
+export function slideAnchor(
+  rect: NodeRect,
+  side: FlowHandleSide,
+  toward: { x: number; y: number },
+  inset = 12,
+): { x: number; y: number } {
+  const clamp = (v: number, lo: number, hi: number) => Math.max(lo, Math.min(hi, v));
+  // Never let the inset invert the usable range on a small node.
+  const ix = Math.min(inset, rect.width / 2);
+  const iy = Math.min(inset, rect.height / 2);
+  switch (side) {
+    case "top":
+      return { x: clamp(toward.x, rect.x + ix, rect.x + rect.width - ix), y: rect.y };
+    case "bottom":
+      return { x: clamp(toward.x, rect.x + ix, rect.x + rect.width - ix), y: rect.y + rect.height };
+    case "left":
+      return { x: rect.x, y: clamp(toward.y, rect.y + iy, rect.y + rect.height - iy) };
+    case "right":
+      return { x: rect.x + rect.width, y: clamp(toward.y, rect.y + iy, rect.y + rect.height - iy) };
+  }
+}
+
+/** Absolute coordinate of a handle on the given side (the side's midpoint). */
+export function handlePoint(rect: NodeRect, side: FlowHandleSide): { x: number; y: number } {
+  switch (side) {
+    case "top":
+      return { x: rect.x + rect.width / 2, y: rect.y };
+    case "bottom":
+      return { x: rect.x + rect.width / 2, y: rect.y + rect.height };
+    case "left":
+      return { x: rect.x, y: rect.y + rect.height / 2 };
+    case "right":
+      return { x: rect.x + rect.width, y: rect.y + rect.height / 2 };
+  }
+}
+
+/** The chosen source/target handle pair plus their absolute anchor points. */
+export interface ClosestHandles {
+  sourceSide: FlowHandleSide;
+  targetSide: FlowHandleSide;
+  sx: number;
+  sy: number;
+  tx: number;
+  ty: number;
+}
+
+/**
+ * Picks the source/target handle pair (one handle per node) with the shortest
+ * straight-line distance between their anchor points. Empty side lists fall
+ * back to all four sides so an edge always resolves to a pair.
+ */
+export function pickClosestHandles(
+  source: NodeRect,
+  sourceSides: FlowHandleSide[],
+  target: NodeRect,
+  targetSides: FlowHandleSide[],
+): ClosestHandles {
+  const srcSides = sourceSides.length ? sourceSides : HANDLE_SIDES;
+  const tgtSides = targetSides.length ? targetSides : HANDLE_SIDES;
+
+  let best: ClosestHandles | undefined;
+  let bestDist = Infinity;
+
+  for (const s of srcSides) {
+    const sp = handlePoint(source, s);
+    for (const t of tgtSides) {
+      const tp = handlePoint(target, t);
+      const dx = tp.x - sp.x;
+      const dy = tp.y - sp.y;
+      const dist = dx * dx + dy * dy;
+      if (dist < bestDist) {
+        bestDist = dist;
+        best = { sourceSide: s, targetSide: t, sx: sp.x, sy: sp.y, tx: tp.x, ty: tp.y };
+      }
+    }
+  }
+
+  // srcSides/tgtSides are non-empty (fallback above), so best is always set.
+  return best as ClosestHandles;
+}

package/src/helper-lines/get-helper-lines.ts

@@ -0,0 +1,98 @@
+/**
+ * Pure alignment-guide geometry for the helper-lines feature.
+ *
+ * Implemented fresh from the documented "helper lines" behaviour (the React Flow
+ * Pro example is paid — only the concept is reused): while a single node drags,
+ * compare its left / horizontal-center / right against every other node's
+ * left / center / right (and top / middle / bottom on the vertical axis). When a
+ * pair falls within `threshold` flow-coordinate pixels, record the guide's
+ * absolute coordinate and the snapped top-left position for the dragged node.
+ *
+ * Everything here is a pure function of plain rectangles so it is unit-testable
+ * without a live React Flow instance.
+ */
+
+/** A node's bounding box in absolute flow coordinates (top-left origin). */
+export interface HelperLineRect {
+  /** Left edge (top-left x) in flow coordinates. */
+  x: number;
+  /** Top edge (top-left y) in flow coordinates. */
+  y: number;
+  width: number;
+  height: number;
+}
+
+export interface HelperLinesResult {
+  /** New top-left x for the dragged node once snapped to the vertical guide. */
+  snapX?: number;
+  /** New top-left y for the dragged node once snapped to the horizontal guide. */
+  snapY?: number;
+  /** Absolute flow-x of the active vertical guide line, if any. */
+  vertical?: number;
+  /** Absolute flow-y of the active horizontal guide line, if any. */
+  horizontal?: number;
+}
+
+/**
+ * Fractional anchor offsets along an axis: 0 = start edge (left/top),
+ * 0.5 = center/middle, 1 = end edge (right/bottom). Comparing all three anchors
+ * of the dragged node against all three of every other node yields
+ * edge-to-edge, edge-to-center and center-to-center alignment.
+ */
+const ANCHORS = [0, 0.5, 1] as const;
+
+/**
+ * Compute the closest vertical + horizontal alignment guides (and the snapped
+ * position) for a dragged rectangle against the other rectangles.
+ *
+ * @param dragged   the dragged node's proposed bounding box (flow coordinates)
+ * @param others    every other node's bounding box
+ * @param threshold max distance (flow px) at which alignment engages; a pair at
+ *                  exactly `threshold` does NOT match (strict boundary)
+ */
+export function getHelperLines(
+  dragged: HelperLineRect,
+  others: Iterable<HelperLineRect>,
+  threshold = 5,
+): HelperLinesResult {
+  const result: HelperLinesResult = {};
+  // Track the closest match on each axis; initialising to `threshold` makes the
+  // boundary strict (a distance equal to threshold never wins).
+  let bestVerticalDist = threshold;
+  let bestHorizontalDist = threshold;
+
+  // Each anchor as { a: fractional offset, pos: absolute coordinate }.
+  const draggedX = ANCHORS.map((a) => ({ a, pos: dragged.x + dragged.width * a }));
+  const draggedY = ANCHORS.map((a) => ({ a, pos: dragged.y + dragged.height * a }));
+
+  for (const other of others) {
+    const otherX = ANCHORS.map((a) => other.x + other.width * a);
+    const otherY = ANCHORS.map((a) => other.y + other.height * a);
+
+    // Vertical guide (align on the X axis).
+    for (const d of draggedX) {
+      for (const oPos of otherX) {
+        const dx = Math.abs(d.pos - oPos);
+        if (dx < bestVerticalDist) {
+          bestVerticalDist = dx;
+          result.vertical = oPos;
+          result.snapX = oPos - dragged.width * d.a;
+        }
+      }
+    }
+
+    // Horizontal guide (align on the Y axis).
+    for (const d of draggedY) {
+      for (const oPos of otherY) {
+        const dy = Math.abs(d.pos - oPos);
+        if (dy < bestHorizontalDist) {
+          bestHorizontalDist = dy;
+          result.horizontal = oPos;
+          result.snapY = oPos - dragged.height * d.a;
+        }
+      }
+    }
+  }
+
+  return result;
+}

package/src/helper-lines/helper-lines.stories.tsx

@@ -0,0 +1,107 @@
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import { useState } from "react";
+import "@xyflow/react/dist/style.css";
+import { ReactFlowProvider, useNodesState, type Edge } from "@xyflow/react";
+import { CanvasShell } from "../canvas-shell";
+import { FlowNode, type BrandFlowNode } from "../flow-node";
+import { ZoomControls } from "../zoom-controls";
+import { HelperLines } from "./helper-lines";
+import { useHelperLines } from "./use-helper-lines";
+
+const nodeTypes = { brand: FlowNode };
+
+const initialNodes: BrandFlowNode[] = [
+  {
+    id: "1",
+    type: "brand",
+    position: { x: 40, y: 40 },
+    data: { kind: "Source", title: "Postgres", subtitle: "orders", tone: "accent" },
+  },
+  {
+    id: "2",
+    type: "brand",
+    position: { x: 320, y: 200 },
+    data: { kind: "Transform", title: "Clean & join", tone: "default" },
+  },
+  {
+    id: "3",
+    type: "brand",
+    position: { x: 120, y: 360 },
+    data: { kind: "Output", title: "Dashboard", tone: "success" },
+  },
+];
+const initialEdges: Edge[] = [];
+
+const meta = {
+  title: "Flow/HelperLines",
+  component: HelperLines,
+  tags: ["autodocs"],
+  parameters: { layout: "fullscreen" },
+} satisfies Meta<typeof HelperLines>;
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+/**
+ * Drag a node so an edge or center aligns with another node — a guide appears
+ * and the node snaps onto it. Wired via the `CanvasShell helperLines` prop.
+ */
+function CanvasShellDemo() {
+  const [nodes, , onNodesChange] = useNodesState(initialNodes);
+  const [edges] = useState(initialEdges);
+  return (
+    <div className="h-[600px]">
+      <CanvasShell
+        helperLines
+        nodes={nodes}
+        edges={edges}
+        onNodesChange={onNodesChange}
+        nodeTypes={nodeTypes}
+      >
+        <ZoomControls />
+      </CanvasShell>
+    </div>
+  );
+}
+
+export const Default: Story = {
+  name: "CanvasShell helperLines",
+  render: () => <CanvasShellDemo />,
+};
+
+/**
+ * The composable path: wire `useHelperLines` around your own `onNodesChange`
+ * and place `<HelperLines>` inside the canvas. Use this for full control (e.g.
+ * a custom threshold, or when you already manage the flow store yourself).
+ */
+function ComposableInner() {
+  const [nodes, , onNodesChange] = useNodesState(initialNodes);
+  const [edges] = useState(initialEdges);
+  const {
+    onNodesChange: handleNodesChange,
+    helperLineHorizontal,
+    helperLineVertical,
+  } = useHelperLines(onNodesChange);
+
+  return (
+    <div className="h-[600px]">
+      <CanvasShell
+        nodes={nodes}
+        edges={edges}
+        onNodesChange={handleNodesChange}
+        nodeTypes={nodeTypes}
+      >
+        <ZoomControls />
+        <HelperLines horizontal={helperLineHorizontal} vertical={helperLineVertical} />
+      </CanvasShell>
+    </div>
+  );
+}
+
+export const Composable: Story = {
+  name: "Composable (useHelperLines + HelperLines)",
+  render: () => (
+    <ReactFlowProvider>
+      <ComposableInner />
+    </ReactFlowProvider>
+  ),
+};

package/src/helper-lines/helper-lines.test.tsx

@@ -0,0 +1,78 @@
+import { describe, expect, it } from "vitest";
+import { getHelperLines, type HelperLineRect } from "./get-helper-lines";
+
+// A fixed 100×40 box; the "other" node the dragged node aligns against.
+const other: HelperLineRect = { x: 100, y: 100, width: 100, height: 40 };
+
+describe("getHelperLines", () => {
+  it("snaps X when left edges are within threshold (left-to-left)", () => {
+    // dragged left at 103, other left at 100 → within 5px.
+    const dragged: HelperLineRect = { x: 103, y: 300, width: 100, height: 40 };
+    const { snapX, vertical } = getHelperLines(dragged, [other]);
+    expect(vertical).toBe(100);
+    expect(snapX).toBe(100); // left aligns → top-left x == other.x
+  });
+
+  it("snaps X when horizontal centers align (center-to-center)", () => {
+    // Narrower box so only its center — not its edges — lands near another anchor.
+    // other centerX = 150; dragged (width 60) center at 150 (x=120), edges far.
+    const dragged: HelperLineRect = { x: 120, y: 300, width: 60, height: 40 };
+    const { snapX, vertical } = getHelperLines(dragged, [other]);
+    expect(vertical).toBe(150);
+    expect(snapX).toBe(120); // centerX 150 → x = 150 - width/2 = 120
+  });
+
+  it("snaps Y when top edges align (top-to-top)", () => {
+    // dragged top at 102, other top at 100 → within 5px.
+    const dragged: HelperLineRect = { x: 400, y: 102, width: 100, height: 40 };
+    const { snapY, horizontal } = getHelperLines(dragged, [other]);
+    expect(horizontal).toBe(100);
+    expect(snapY).toBe(100);
+  });
+
+  it("snaps X to the right edge (right-to-right)", () => {
+    // Wider box (120) at x=80 → right=200 matches other.right=200; left/center far.
+    const dragged: HelperLineRect = { x: 80, y: 300, width: 120, height: 40 };
+    const { snapX, vertical } = getHelperLines(dragged, [other], 5);
+    expect(vertical).toBe(200); // guide at other's right edge
+    expect(snapX).toBe(80); // right 200 → x = 200 - width = 80
+    expect((snapX ?? 0) + 120).toBe(vertical); // dragged right lands on the guide
+  });
+
+  it("does not snap when no anchor is within threshold", () => {
+    const dragged: HelperLineRect = { x: 500, y: 500, width: 100, height: 40 };
+    const result = getHelperLines(dragged, [other]);
+    expect(result.snapX).toBeUndefined();
+    expect(result.snapY).toBeUndefined();
+    expect(result.vertical).toBeUndefined();
+    expect(result.horizontal).toBeUndefined();
+  });
+
+  it("treats the threshold as a strict boundary (distance == threshold does not match)", () => {
+    // dragged left exactly 5px from other left with threshold 5 → no match.
+    const dragged: HelperLineRect = { x: 105, y: 500, width: 100, height: 40 };
+    const result = getHelperLines(dragged, [other], 5);
+    expect(result.vertical).toBeUndefined();
+    expect(result.snapX).toBeUndefined();
+
+    // One pixel closer (distance 4 < 5) → matches.
+    const closer: HelperLineRect = { x: 104, y: 500, width: 100, height: 40 };
+    const matched = getHelperLines(closer, [other], 5);
+    expect(matched.vertical).toBe(100);
+    expect(matched.snapX).toBe(100);
+  });
+
+  it("picks the closest node when several are near", () => {
+    const near: HelperLineRect = { x: 101, y: 300, width: 100, height: 40 }; // dist 1
+    const far: HelperLineRect = { x: 96, y: 300, width: 100, height: 40 }; // dist 4
+    const dragged: HelperLineRect = { x: 100, y: 300, width: 100, height: 40 };
+    const { vertical, snapX } = getHelperLines(dragged, [far, near]);
+    expect(vertical).toBe(101); // the closer node's left wins
+    expect(snapX).toBe(101);
+  });
+
+  it("returns nothing when there are no other nodes", () => {
+    const dragged: HelperLineRect = { x: 100, y: 100, width: 100, height: 40 };
+    expect(getHelperLines(dragged, [])).toEqual({});
+  });
+});

package/src/helper-lines/helper-lines.tsx

@@ -0,0 +1,67 @@
+"use client";
+
+import { forwardRef, type SVGAttributes } from "react";
+import { useViewport } from "@xyflow/react";
+import { cn } from "@elabs-ai/components-ui/lib/cn";
+
+export interface HelperLinesProps extends SVGAttributes<SVGSVGElement> {
+  /** Absolute flow-y of the horizontal guide (from `useHelperLines`). */
+  horizontal?: number;
+  /** Absolute flow-x of the vertical guide (from `useHelperLines`). */
+  vertical?: number;
+}
+
+/**
+ * Decorative alignment-guide overlay. Draws a full-width horizontal line at
+ * `horizontal` and/or a full-height vertical line at `vertical`, coloured with
+ * the `--flow-helper-line` token. It reads the live viewport transform
+ * (zoom + pan) so the guides sit on the real alignment position when the canvas
+ * is zoomed or panned.
+ *
+ * Render as a child of `<CanvasShell>` / `<ReactFlow>` (it must be inside the
+ * flow context to read the viewport). Purely decorative — hidden from AT.
+ */
+export const HelperLines = forwardRef<SVGSVGElement, HelperLinesProps>(function HelperLines(
+  { horizontal, vertical, className, ...props },
+  ref,
+) {
+  const { x, y, zoom } = useViewport();
+
+  if (horizontal == null && vertical == null) return null;
+
+  // flow coordinate → pane pixel: coord * zoom + pan offset.
+  const screenY = horizontal == null ? null : y + horizontal * zoom;
+  const screenX = vertical == null ? null : x + vertical * zoom;
+
+  return (
+    <svg
+      ref={ref}
+      aria-hidden="true"
+      width="100%"
+      height="100%"
+      className={cn("pointer-events-none absolute inset-0 size-full", className)}
+      {...props}
+    >
+      {screenY != null ? (
+        <line
+          x1={0}
+          x2="100%"
+          y1={screenY}
+          y2={screenY}
+          stroke="var(--flow-helper-line, var(--primary))"
+          strokeWidth={1}
+        />
+      ) : null}
+      {screenX != null ? (
+        <line
+          x1={screenX}
+          x2={screenX}
+          y1={0}
+          y2="100%"
+          stroke="var(--flow-helper-line, var(--primary))"
+          strokeWidth={1}
+        />
+      ) : null}
+    </svg>
+  );
+});

package/src/helper-lines/index.ts

@@ -0,0 +1,7 @@
+export { getHelperLines, type HelperLineRect, type HelperLinesResult } from "./get-helper-lines";
+export {
+  useHelperLines,
+  type UseHelperLinesOptions,
+  type UseHelperLinesResult,
+} from "./use-helper-lines";
+export { HelperLines, type HelperLinesProps } from "./helper-lines";