@elabs-ai/components-flow 4.0.0

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

@@ -0,0 +1,100 @@
+import { describe, expect, it, vi } from "vitest";
+
+// getEdgeParams imports the `Position` enum (a value) from @xyflow/react. The
+// real package needs browser layout; mock it down to the Position constants so
+// the PURE geometry can be exercised in jsdom.
+vi.mock("@xyflow/react", () => ({
+  Position: { Left: "left", Top: "top", Right: "right", Bottom: "bottom" },
+}));
+
+import { getEdgeParams, type FloatingNodeGeometry } from "./floating-edge-geometry";
+
+/** 100×60 node whose top-left sits at (x, y). */
+function node(x: number, y: number, width = 100, height = 60): FloatingNodeGeometry {
+  return { internals: { positionAbsolute: { x, y } }, measured: { width, height } };
+}
+
+describe("getEdgeParams (floating edge border intersection)", () => {
+  it("target directly to the right → source exits right, target enters left", () => {
+    const source = node(0, 0);
+    const target = node(300, 0);
+    const p = getEdgeParams(source, target);
+
+    expect(p.sourcePos).toBe("right");
+    expect(p.targetPos).toBe("left");
+    // Source border point is on the right edge (x = 100), target on left (x = 300).
+    expect(p.sx).toBeCloseTo(100);
+    expect(p.tx).toBeCloseTo(300);
+    // Both attach at the vertical center (y = 30).
+    expect(p.sy).toBeCloseTo(30);
+    expect(p.ty).toBeCloseTo(30);
+  });
+
+  it("target directly to the left → source exits left, target enters right", () => {
+    const p = getEdgeParams(node(300, 0), node(0, 0));
+    expect(p.sourcePos).toBe("left");
+    expect(p.targetPos).toBe("right");
+    expect(p.sx).toBeCloseTo(300);
+    expect(p.tx).toBeCloseTo(100);
+  });
+
+  it("target directly below → source exits bottom, target enters top", () => {
+    const source = node(0, 0);
+    const target = node(0, 300);
+    const p = getEdgeParams(source, target);
+
+    expect(p.sourcePos).toBe("bottom");
+    expect(p.targetPos).toBe("top");
+    // Source bottom edge (y = 60), target top edge (y = 300).
+    expect(p.sy).toBeCloseTo(60);
+    expect(p.ty).toBeCloseTo(300);
+    // Horizontal center (x = 50).
+    expect(p.sx).toBeCloseTo(50);
+    expect(p.tx).toBeCloseTo(50);
+  });
+
+  it("target directly above → source exits top, target enters bottom", () => {
+    const p = getEdgeParams(node(0, 300), node(0, 0));
+    expect(p.sourcePos).toBe("top");
+    expect(p.targetPos).toBe("bottom");
+    expect(p.sy).toBeCloseTo(300);
+    expect(p.ty).toBeCloseTo(60);
+  });
+
+  it("diagonal placement → the point lands EXACTLY on a border (not inside)", () => {
+    const source = node(0, 0);
+    const target = node(300, 300);
+    const p = getEdgeParams(source, target);
+
+    // Facing down-right, this 100×60 node exits its BOTTOM edge (y = 60) at x = 80.
+    expect(p.sourcePos).toBe("bottom");
+    expect(p.sy).toBeCloseTo(60); // exactly on the border, never a hair inside
+    expect(p.sx).toBeCloseTo(80);
+    // The target (up-left of its own centre) enters its TOP edge (y = 300).
+    expect(p.targetPos).toBe("top");
+    expect(p.ty).toBeCloseTo(300);
+    expect(p.tx).toBeCloseTo(320);
+  });
+
+  it("wide node (story aspect ratio) → the near-horizontal edge exits the right side on-border", () => {
+    // ~176×80 card (min-w-44) with a target up and to the right.
+    const source = node(0, 0, 180, 80);
+    const target = node(500, -200, 180, 80);
+    const p = getEdgeParams(source, target);
+
+    expect(p.sourcePos).toBe("right");
+    expect(p.sx).toBeCloseTo(180); // exactly the right border, not inside the card
+    expect(p.sy).toBeGreaterThanOrEqual(0);
+    expect(p.sy).toBeLessThanOrEqual(80);
+  });
+
+  it("an unmeasured node does not throw and yields finite coordinates", () => {
+    const source: FloatingNodeGeometry = {
+      internals: { positionAbsolute: { x: 0, y: 0 } },
+      measured: {},
+    };
+    const p = getEdgeParams(source, node(300, 0));
+    expect(Number.isFinite(p.sx)).toBe(true);
+    expect(Number.isFinite(p.sy)).toBe(true);
+  });
+});

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

@@ -0,0 +1,128 @@
+import { Position } from "@xyflow/react";
+
+/**
+ * The minimal live node geometry `getEdgeParams` needs. A React Flow
+ * `InternalNode` satisfies this structurally (`internals.positionAbsolute` +
+ * `measured`), so you can pass one directly; tests can pass a plain fake.
+ */
+export interface FloatingNodeGeometry {
+  internals: { positionAbsolute: { x: number; y: number } };
+  measured: { width?: number; height?: number };
+}
+
+interface Point {
+  x: number;
+  y: number;
+}
+
+/**
+ * The point where the line from `intersectionNode`'s center to `targetNode`'s
+ * center crosses `intersectionNode`'s rectangle border. Standard React Flow
+ * floating-edge math (ellipse-normalized).
+ */
+function getNodeIntersection(
+  intersectionNode: FloatingNodeGeometry,
+  targetNode: FloatingNodeGeometry,
+): Point {
+  const w = (intersectionNode.measured.width ?? 0) / 2;
+  const h = (intersectionNode.measured.height ?? 0) / 2;
+  const pos = intersectionNode.internals.positionAbsolute;
+  const targetPos = targetNode.internals.positionAbsolute;
+
+  const x2 = pos.x + w;
+  const y2 = pos.y + h;
+  const x1 = targetPos.x + (targetNode.measured.width ?? 0) / 2;
+  const y1 = targetPos.y + (targetNode.measured.height ?? 0) / 2;
+
+  // A not-yet-measured node has w/h = 0; guard the divisions so we return the
+  // node's position (finite) instead of NaN (which would break the edge path and
+  // make the line appear to end at a random spot until measurement lands).
+  const safeW = w || 1;
+  const safeH = h || 1;
+
+  const xx1 = (x1 - x2) / (2 * safeW) - (y1 - y2) / (2 * safeH);
+  const yy1 = (x1 - x2) / (2 * safeW) + (y1 - y2) / (2 * safeH);
+  const a = 1 / (Math.abs(xx1) + Math.abs(yy1) || 1);
+  const xx3 = a * xx1;
+  const yy3 = a * yy1;
+  const x = safeW * (xx3 + yy3) + x2;
+  const y = safeH * (-xx3 + yy3) + y2;
+
+  return { x, y };
+}
+
+/**
+ * Snap `point` exactly onto `node`'s nearest border side. The intersection math
+ * already lands on the border for a measured node; this guarantees it (removing
+ * any sub-pixel drift that would leave the anchor a hair inside the node) and
+ * gives a sensible on-border fallback if a point ever lands inside. Returns the
+ * point unchanged when the node has no measured size yet.
+ */
+function clampToBorder(point: Point, node: FloatingNodeGeometry): Point {
+  const x0 = node.internals.positionAbsolute.x;
+  const y0 = node.internals.positionAbsolute.y;
+  const w = node.measured.width ?? 0;
+  const h = node.measured.height ?? 0;
+  if (w <= 0 || h <= 0) return point;
+
+  const cx = Math.min(Math.max(point.x, x0), x0 + w);
+  const cy = Math.min(Math.max(point.y, y0), y0 + h);
+  // Distance from the (clamped-inside) point to each side; snap to the nearest.
+  const dLeft = cx - x0;
+  const dRight = x0 + w - cx;
+  const dTop = cy - y0;
+  const dBottom = y0 + h - cy;
+  const nearest = Math.min(dLeft, dRight, dTop, dBottom);
+  if (nearest === dLeft) return { x: x0, y: cy };
+  if (nearest === dRight) return { x: x0 + w, y: cy };
+  if (nearest === dTop) return { x: cx, y: y0 };
+  return { x: cx, y: y0 + h };
+}
+
+/** Which border of `node` the intersection `point` sits on. */
+function getEdgeBorderPosition(node: FloatingNodeGeometry, point: Point): Position {
+  const nx = Math.round(node.internals.positionAbsolute.x);
+  const ny = Math.round(node.internals.positionAbsolute.y);
+  const px = Math.round(point.x);
+  const py = Math.round(point.y);
+  const w = node.measured.width ?? 0;
+  const h = node.measured.height ?? 0;
+
+  if (px <= nx + 1) return Position.Left;
+  if (px >= nx + w - 1) return Position.Right;
+  if (py <= ny + 1) return Position.Top;
+  if (py >= ny + h - 1) return Position.Bottom;
+  return Position.Top;
+}
+
+/** Border anchor points + `Position`s for a floating edge between two nodes. */
+export interface EdgeParams {
+  sx: number;
+  sy: number;
+  tx: number;
+  ty: number;
+  sourcePos: Position;
+  targetPos: Position;
+}
+
+/**
+ * Computes where a floating edge attaches to each node's border — the
+ * intersection of the center-to-center line with each rectangle — plus the
+ * border `Position`. Recompute per render so anchors track dragging nodes.
+ */
+export function getEdgeParams(
+  source: FloatingNodeGeometry,
+  target: FloatingNodeGeometry,
+): EdgeParams {
+  const sourceIntersection = clampToBorder(getNodeIntersection(source, target), source);
+  const targetIntersection = clampToBorder(getNodeIntersection(target, source), target);
+
+  return {
+    sx: sourceIntersection.x,
+    sy: sourceIntersection.y,
+    tx: targetIntersection.x,
+    ty: targetIntersection.y,
+    sourcePos: getEdgeBorderPosition(source, sourceIntersection),
+    targetPos: getEdgeBorderPosition(target, targetIntersection),
+  };
+}

package/src/flow-floating-edge/flow-floating-edge.stories.tsx

@@ -0,0 +1,81 @@
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import "@xyflow/react/dist/style.css";
+import { type Edge } from "@xyflow/react";
+import { CanvasShell } from "../canvas-shell";
+import { FlowNode, type BrandFlowNode } from "../flow-node";
+import { FlowFloatingEdge } from "./flow-floating-edge";
+
+const nodeTypes = { brand: FlowNode };
+const edgeTypes = { floating: FlowFloatingEdge };
+
+const meta = {
+  title: "Flow/FlowFloatingEdge",
+  component: FlowFloatingEdge,
+  tags: ["autodocs"],
+  parameters: { layout: "fullscreen" },
+} satisfies Meta<typeof FlowFloatingEdge>;
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+const flowNodes: BrandFlowNode[] = [
+  {
+    id: "a",
+    type: "brand",
+    position: { x: 120, y: 160 },
+    data: { kind: "Source", title: "Ingest", tone: "accent" },
+  },
+  {
+    id: "b",
+    type: "brand",
+    position: { x: 460, y: 80 },
+    data: { kind: "Process", title: "Transform" },
+  },
+  {
+    id: "c",
+    type: "brand",
+    position: { x: 460, y: 300 },
+    data: { kind: "Output", title: "Publish", tone: "success" },
+  },
+];
+
+/**
+ * Plain nodes (default handles) connected by `FlowFloatingEdge`. The edge attaches
+ * to the node border at the point facing the other node (no fixed handle), so it
+ * slides around the border as nodes are dragged. A small **anchor dot** marks each
+ * connection point on the node's closest side, so the line clearly terminates on
+ * the border (not at a bare, unanchored spot). Drag a node to watch the anchors
+ * and the edge slide around the border together.
+ */
+export const Default: Story = {
+  render: () => {
+    const edges: Edge[] = [
+      { id: "a-b", source: "a", target: "b", type: "floating" },
+      { id: "a-c", source: "a", target: "c", type: "floating" },
+      { id: "b-c", source: "b", target: "c", type: "floating" },
+    ];
+    return (
+      <div className="h-[480px]">
+        <CanvasShell nodes={flowNodes} edges={edges} nodeTypes={nodeTypes} edgeTypes={edgeTypes} />
+      </div>
+    );
+  },
+};
+
+/**
+ * The anchor dot is on by default; hide it per edge with `data: { anchors: false }`
+ * for a plain hairline that still floats to the border.
+ */
+export const AnchorsHidden: Story = {
+  render: () => {
+    const edges: Edge[] = [
+      { id: "a-b", source: "a", target: "b", type: "floating", data: { anchors: false } },
+      { id: "a-c", source: "a", target: "c", type: "floating", data: { anchors: false } },
+      { id: "b-c", source: "b", target: "c", type: "floating", data: { anchors: false } },
+    ];
+    return (
+      <div className="h-[480px]">
+        <CanvasShell nodes={flowNodes} edges={edges} nodeTypes={nodeTypes} edgeTypes={edgeTypes} />
+      </div>
+    );
+  },
+};

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

@@ -0,0 +1,82 @@
+import { BaseEdge, getBezierPath, useInternalNode, type EdgeProps } from "@xyflow/react";
+import { getEdgeParams } from "./floating-edge-geometry";
+
+/** Optional per-edge `data` for {@link FlowFloatingEdge}. */
+export interface FloatingEdgeData {
+  /**
+   * Show a small anchor dot at each border connection point. On by default so the
+   * edge visibly terminates on the node's closest side (rather than a bare line
+   * touching the border with no anchor). Set `false` to hide.
+   */
+  anchors?: boolean;
+  [key: string]: unknown;
+}
+
+/** Radius of the connection anchor dot (matches the `FlowNode` handle size). */
+const ANCHOR_RADIUS = 4;
+
+/**
+ * Branded floating edge: it attaches to the node **border** at the point facing
+ * the other node (no fixed handle), recomputed as nodes drag. Register it in
+ * `edgeTypes={{ floating: FlowFloatingEdge }}`; the connected nodes need no
+ * handle config. Uses the `--flow-edge` token, matching `FlowEdge`.
+ *
+ * A small **anchor dot** is drawn at each connection point (on by default) so the
+ * line clearly terminates on the node's closest border side — not at a bare,
+ * unanchored spot. Toggle per edge with `data.anchors: false`.
+ */
+export function FlowFloatingEdge({ id, source, target, markerEnd, style, data }: EdgeProps) {
+  const sourceNode = useInternalNode(source);
+  const targetNode = useInternalNode(target);
+  if (!sourceNode || !targetNode) return null;
+
+  const { sx, sy, tx, ty, sourcePos, targetPos } = getEdgeParams(sourceNode, targetNode);
+
+  const [edgePath] = getBezierPath({
+    sourceX: sx,
+    sourceY: sy,
+    sourcePosition: sourcePos,
+    targetX: tx,
+    targetY: ty,
+    targetPosition: targetPos,
+  });
+
+  const showAnchors = (data as FloatingEdgeData | undefined)?.anchors !== false;
+
+  return (
+    <>
+      <BaseEdge
+        id={id}
+        path={edgePath}
+        markerEnd={markerEnd}
+        style={{ stroke: "var(--flow-edge)", strokeWidth: 1.5, ...style }}
+      />
+      {showAnchors ? (
+        <g
+          className="brand-floating-edge__anchors"
+          fill="var(--flow-node)"
+          stroke="var(--flow-edge)"
+        >
+          {/* Decorative rings matching the FlowNode handle look; never intercept
+              pointer events so nodes stay draggable through them. */}
+          <circle
+            cx={sx}
+            cy={sy}
+            r={ANCHOR_RADIUS}
+            strokeWidth={2}
+            style={{ pointerEvents: "none" }}
+            aria-hidden="true"
+          />
+          <circle
+            cx={tx}
+            cy={ty}
+            r={ANCHOR_RADIUS}
+            strokeWidth={2}
+            style={{ pointerEvents: "none" }}
+            aria-hidden="true"
+          />
+        </g>
+      ) : null}
+    </>
+  );
+}

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

@@ -0,0 +1,6 @@
+export { FlowFloatingEdge, type FloatingEdgeData } from "./flow-floating-edge";
+export {
+  getEdgeParams,
+  type EdgeParams,
+  type FloatingNodeGeometry,
+} from "./floating-edge-geometry";

package/src/flow-group-node/flow-group-node.stories.tsx

@@ -0,0 +1,283 @@
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import "@xyflow/react/dist/style.css";
+import { Panel, useEdgesState, useNodesState, type Edge, type Node } from "@xyflow/react";
+import { Boxes } from "lucide-react";
+import { CanvasShell } from "../canvas-shell";
+import { FlowNode } from "../flow-node";
+import { ZoomControls } from "../zoom-controls";
+import { useFlowGroups } from "../use-flow-groups";
+import { FlowGroupNode } from "./flow-group-node";
+
+const nodeTypes = { brand: FlowNode, group: FlowGroupNode };
+
+const toolbarButton =
+  "rounded-md border border-input bg-surface-elevated px-3 py-1.5 text-body shadow-sm hover:bg-accent focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring disabled:opacity-50";
+
+const meta = {
+  title: "Flow/FlowGroupNode",
+  component: FlowGroupNode,
+  tags: ["autodocs"],
+  parameters: { layout: "fullscreen" },
+} satisfies Meta<typeof FlowGroupNode>;
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+/* --------------------------------------------------------------------------
+ * Group & ungroup — select nodes, then group / dissolve them from a toolbar.
+ * ------------------------------------------------------------------------ */
+
+const looseNodes: Node[] = [
+  {
+    id: "extract",
+    type: "brand",
+    position: { x: 60, y: 60 },
+    data: { kind: "Source", title: "Extract" },
+  },
+  {
+    id: "clean",
+    type: "brand",
+    position: { x: 300, y: 60 },
+    data: { kind: "Transform", title: "Clean" },
+  },
+  {
+    id: "join",
+    type: "brand",
+    position: { x: 300, y: 200 },
+    data: { kind: "Transform", title: "Join" },
+  },
+  {
+    id: "load",
+    type: "brand",
+    position: { x: 560, y: 130 },
+    data: { kind: "Output", title: "Load" },
+  },
+];
+
+const looseEdges: Edge[] = [
+  { id: "e1", source: "extract", target: "clean" },
+  { id: "e2", source: "clean", target: "join" },
+  { id: "e3", source: "join", target: "load" },
+];
+
+function GroupToolbar() {
+  const { groupSelection, ungroup } = useFlowGroups();
+  return (
+    <div className="flex gap-2">
+      <button
+        type="button"
+        className={toolbarButton}
+        onClick={() => groupSelection({ title: "Transforms", tone: "accent" })}
+      >
+        Group selection
+      </button>
+      <button type="button" className={toolbarButton} onClick={() => ungroup("group-transforms")}>
+        Ungroup
+      </button>
+    </div>
+  );
+}
+
+function GroupAndUngroupDemo() {
+  const [nodes, , onNodesChange] = useNodesState(looseNodes);
+  const [edges, , onEdgesChange] = useEdgesState(looseEdges);
+  return (
+    <div className="h-[520px]">
+      <CanvasShell
+        nodes={nodes}
+        edges={edges}
+        nodeTypes={nodeTypes}
+        onNodesChange={onNodesChange}
+        onEdgesChange={onEdgesChange}
+      >
+        <Panel position="top-left">
+          <GroupToolbar />
+        </Panel>
+        <ZoomControls />
+      </CanvasShell>
+    </div>
+  );
+}
+
+/**
+ * Shift-click to select the `Clean` + `Join` nodes, then **Group selection** wraps
+ * them in a `FlowGroupNode` parent. **Ungroup** dissolves the group with the id
+ * `group-transforms` (this demo generates a random id, so use the header toggle
+ * for collapse and the toolbar mainly to see grouping).
+ */
+export const GroupAndUngroup: Story = {
+  render: () => <GroupAndUngroupDemo />,
+};
+
+/* --------------------------------------------------------------------------
+ * Expand & collapse — a pre-built group with edges crossing the boundary.
+ * ------------------------------------------------------------------------ */
+
+function preGroupedGraph(): { nodes: Node[]; edges: Edge[] } {
+  const nodes: Node[] = [
+    {
+      id: "pipeline",
+      type: "group",
+      position: { x: 80, y: 80 },
+      width: 420,
+      height: 240,
+      data: { title: "ETL pipeline", tone: "accent", icon: <Boxes /> },
+    },
+    {
+      id: "extract",
+      type: "brand",
+      parentId: "pipeline",
+      extent: "parent",
+      position: { x: 24, y: 70 },
+      data: { kind: "Source", title: "Extract" },
+    },
+    {
+      id: "transform",
+      type: "brand",
+      parentId: "pipeline",
+      extent: "parent",
+      position: { x: 230, y: 130 },
+      data: { kind: "Transform", title: "Transform" },
+    },
+    {
+      id: "warehouse",
+      type: "brand",
+      position: { x: 640, y: 160 },
+      data: { kind: "Output", title: "Warehouse" },
+    },
+  ];
+  const edges: Edge[] = [
+    { id: "e-ex-tr", source: "extract", target: "transform" }, // fully inside
+    { id: "e-tr-wh", source: "transform", target: "warehouse" }, // crosses boundary
+  ];
+  return { nodes, edges };
+}
+
+function CollapseToolbar({ groupId }: { groupId: string }) {
+  const { collapseGroup, expandGroup } = useFlowGroups();
+  return (
+    <div className="flex gap-2">
+      <button type="button" className={toolbarButton} onClick={() => collapseGroup(groupId)}>
+        Collapse
+      </button>
+      <button type="button" className={toolbarButton} onClick={() => expandGroup(groupId)}>
+        Expand
+      </button>
+    </div>
+  );
+}
+
+function ExpandAndCollapseDemo() {
+  const initial = preGroupedGraph();
+  const [nodes, , onNodesChange] = useNodesState(initial.nodes);
+  const [edges, , onEdgesChange] = useEdgesState(initial.edges);
+  return (
+    <div className="h-[520px]">
+      <CanvasShell
+        nodes={nodes}
+        edges={edges}
+        nodeTypes={nodeTypes}
+        onNodesChange={onNodesChange}
+        onEdgesChange={onEdgesChange}
+      >
+        <Panel position="top-left">
+          <CollapseToolbar groupId="pipeline" />
+        </Panel>
+        <ZoomControls />
+      </CanvasShell>
+    </div>
+  );
+}
+
+/**
+ * Collapse the group to an overview chip via the header chevron (or the toolbar).
+ * The `Transform → Warehouse` edge crosses the collapse boundary, so it is
+ * re-routed to a **proxy edge** from the group node to `Warehouse`; the
+ * fully-inside `Extract → Transform` edge is simply hidden. Expanding restores the
+ * exact original graph.
+ */
+export const ExpandAndCollapse: Story = {
+  render: () => <ExpandAndCollapseDemo />,
+};
+
+/* --------------------------------------------------------------------------
+ * Nested groups — a subgroup inside a group, each independently collapsible.
+ * ------------------------------------------------------------------------ */
+
+function nestedGraph(): { nodes: Node[]; edges: Edge[] } {
+  const nodes: Node[] = [
+    {
+      id: "outer",
+      type: "group",
+      position: { x: 60, y: 60 },
+      width: 520,
+      height: 320,
+      data: { title: "Region: EU", tone: "accent" },
+    },
+    {
+      id: "ingest",
+      type: "brand",
+      parentId: "outer",
+      extent: "parent",
+      position: { x: 24, y: 90 },
+      data: { kind: "Source", title: "Ingest" },
+    },
+    {
+      id: "inner",
+      type: "group",
+      parentId: "outer",
+      extent: "parent",
+      position: { x: 230, y: 70 },
+      width: 250,
+      height: 200,
+      data: { title: "Enrichment", tone: "success" },
+    },
+    {
+      id: "geo",
+      type: "brand",
+      parentId: "inner",
+      extent: "parent",
+      position: { x: 24, y: 90 },
+      data: { kind: "Transform", title: "Geocode" },
+    },
+    {
+      id: "sink",
+      type: "brand",
+      position: { x: 700, y: 180 },
+      data: { kind: "Output", title: "Sink" },
+    },
+  ];
+  const edges: Edge[] = [
+    { id: "e-in-geo", source: "ingest", target: "geo" }, // crosses inner boundary
+    { id: "e-geo-sink", source: "geo", target: "sink" }, // crosses both boundaries
+  ];
+  return { nodes, edges };
+}
+
+function NestedGroupsDemo() {
+  const initial = nestedGraph();
+  const [nodes, , onNodesChange] = useNodesState(initial.nodes);
+  const [edges, , onEdgesChange] = useEdgesState(initial.edges);
+  return (
+    <div className="h-[560px]">
+      <CanvasShell
+        nodes={nodes}
+        edges={edges}
+        nodeTypes={nodeTypes}
+        onNodesChange={onNodesChange}
+        onEdgesChange={onEdgesChange}
+      >
+        <ZoomControls />
+      </CanvasShell>
+    </div>
+  );
+}
+
+/**
+ * A subgroup (`Enrichment`) nested inside an outer group (`Region: EU`). Collapse
+ * the inner group first, then the outer — each header toggle works independently,
+ * and expanding the outer keeps the inner collapsed (no double-unhide). Edges that
+ * cross either boundary re-route to proxy edges on the relevant group.
+ */
+export const NestedGroups: Story = {
+  render: () => <NestedGroupsDemo />,
+};