@elabs-ai/components-flow 4.0.0

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

@@ -0,0 +1,100 @@
+import { cleanup, fireEvent, render, screen } from "@testing-library/react";
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+const setNodes = vi.fn();
+const setEdges = vi.fn();
+const getNodes = vi.fn(() => [
+  { id: "test-group", type: "group", position: { x: 0, y: 0 }, data: { title: "Group" } },
+]);
+const getEdges = vi.fn(() => [] as unknown[]);
+
+// @xyflow/react needs real layout/measurement — mock the engine and assert the
+// brand component's own output. Real rendering + a11y are covered by Storybook
+// interaction tests. The pure grouping logic is covered by group-operations.test.ts.
+vi.mock("@xyflow/react", () => {
+  // eslint-disable-next-line @typescript-eslint/no-require-imports -- a vi.mock factory is hoisted above imports; a lazy require avoids the TDZ a top-level import would hit
+  const React = require("react");
+  return {
+    Handle: ({ type }: { type: string }) =>
+      React.createElement("div", { "data-testid": `handle-${type}` }),
+    NodeResizer: () => React.createElement("div", { "data-testid": "node-resizer" }),
+    Position: { Top: "top", Bottom: "bottom", Left: "left", Right: "right" },
+    useNodes: () => [] as unknown[],
+    useReactFlow: () => ({ getNodes, getEdges, setNodes, setEdges }),
+    getNodesBounds: () => ({ x: 0, y: 0, width: 0, height: 0 }),
+  };
+});
+
+import { FlowGroupNode, type BrandFlowGroupNode } from "./flow-group-node";
+import type { NodeProps } from "@xyflow/react";
+
+afterEach(() => {
+  cleanup();
+  vi.clearAllMocks();
+});
+
+function makeProps(
+  data: BrandFlowGroupNode["data"],
+  overrides: Partial<NodeProps<BrandFlowGroupNode>> = {},
+): NodeProps<BrandFlowGroupNode> {
+  return {
+    id: "test-group",
+    data,
+    selected: false,
+    dragging: false,
+    zIndex: 0,
+    isConnectable: true,
+    draggable: true,
+    deletable: true,
+    selectable: true,
+    positionAbsoluteX: 0,
+    positionAbsoluteY: 0,
+    width: 320,
+    height: 200,
+    type: "group",
+    ...overrides,
+  };
+}
+
+describe("FlowGroupNode", () => {
+  it("renders the title and the child-count badge", () => {
+    render(<FlowGroupNode {...makeProps({ title: "Transforms", childCount: 3 })} />);
+    expect(screen.getByText("Transforms")).toBeInTheDocument();
+    expect(screen.getByText("3")).toBeInTheDocument();
+  });
+
+  it("exposes an accessible collapse toggle (aria-expanded true when expanded)", () => {
+    render(<FlowGroupNode {...makeProps({ title: "G" })} />);
+    const button = screen.getByRole("button", { name: /collapse group g/i });
+    expect(button).toHaveAttribute("aria-expanded", "true");
+  });
+
+  it("shows an expand affordance (aria-expanded false) when collapsed", () => {
+    render(<FlowGroupNode {...makeProps({ title: "G", collapsed: true })} />);
+    const button = screen.getByRole("button", { name: /expand group g/i });
+    expect(button).toHaveAttribute("aria-expanded", "false");
+  });
+
+  it("toggling calls into the store (setNodes/setEdges)", () => {
+    render(<FlowGroupNode {...makeProps({ title: "Group" })} />);
+    fireEvent.click(screen.getByRole("button", { name: /collapse group group/i }));
+    expect(setNodes).toHaveBeenCalledTimes(1);
+    expect(setEdges).toHaveBeenCalledTimes(1);
+  });
+
+  it("renders a NodeResizer only when selected and expanded", () => {
+    const { rerender } = render(
+      <FlowGroupNode {...makeProps({ title: "G" }, { selected: true })} />,
+    );
+    expect(screen.getByTestId("node-resizer")).toBeInTheDocument();
+
+    rerender(<FlowGroupNode {...makeProps({ title: "G", collapsed: true }, { selected: true })} />);
+    expect(screen.queryByTestId("node-resizer")).not.toBeInTheDocument();
+  });
+
+  it("renders group handles so proxy edges can attach", () => {
+    render(<FlowGroupNode {...makeProps({ title: "G" })} />);
+    expect(screen.getByTestId("handle-target")).toBeInTheDocument();
+    expect(screen.getByTestId("handle-source")).toBeInTheDocument();
+  });
+});

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

@@ -0,0 +1,134 @@
+import { type ReactNode } from "react";
+import { Handle, NodeResizer, Position, useNodes, type Node, type NodeProps } from "@xyflow/react";
+import { ChevronDown, ChevronRight } from "lucide-react";
+import { cn } from "@elabs-ai/components-ui/lib/cn";
+import { useFlowGroups } from "../use-flow-groups";
+
+/** Visual accent for a group container. */
+export type FlowGroupTone = "default" | "accent" | "success" | "warning" | "destructive";
+
+export interface FlowGroupNodeData extends Record<string, unknown> {
+  /** Header label for the group. */
+  title: string;
+  /** Optional leading glyph (a Lucide icon element, etc.). */
+  icon?: ReactNode;
+  /**
+   * Whether the group is collapsed to an overview chip. Managed by
+   * `useFlowGroups().collapseGroup` / `expandGroup`; the header toggle flips it.
+   */
+  collapsed?: boolean;
+  /**
+   * Fallback count shown next to the title. When omitted, the node counts its
+   * live direct children from the store, so the badge stays accurate as nodes
+   * are added or removed.
+   */
+  childCount?: number;
+  /** Accent tone for the header rule + count badge. */
+  tone?: FlowGroupTone;
+}
+
+export type BrandFlowGroupNode = Node<FlowGroupNodeData, "group">;
+
+const toneAccent: Record<FlowGroupTone, string> = {
+  default: "text-muted-foreground",
+  // #399 — the group LABEL is text on the canvas, so it takes the on-surface
+  // `-text` rung. (The status rows below stay on their fill rungs; those are a
+  // separate, still-open question, not part of #399's enumerated call sites.)
+  accent: "text-primary-text",
+  success: "text-success",
+  warning: "text-warning",
+  destructive: "text-destructive",
+};
+
+const handleClassName = "!size-2 !border-2 !border-flow-group-border !bg-flow-group";
+
+/**
+ * Branded group container node. Register it as `nodeTypes={{ group: FlowGroupNode }}`
+ * and create nodes with `type: "group"` + typed `data: FlowGroupNodeData`. Children
+ * are re-parented onto it (`parentId`, `extent: "parent"`) — see `useFlowGroups`.
+ *
+ * The header carries the title, a live child-count badge and a collapse/expand
+ * toggle (a real `<button>` with `aria-expanded`) that drives
+ * `useFlowGroups().collapseGroup` / `expandGroup`. When selected (and expanded)
+ * a `<NodeResizer>` lets the group be resized.
+ *
+ * The surface uses the FL-01 tokens `--flow-group` (fill) + `--flow-group-border`
+ * (border). Under a theme whose `--flow-group` is near-transparent, the
+ * drawn border does the work.
+ */
+export function FlowGroupNode({ id, data, selected }: NodeProps<BrandFlowGroupNode>) {
+  const { toggleCollapse } = useFlowGroups();
+  const nodes = useNodes();
+  const collapsed = data.collapsed ?? false;
+  const tone = data.tone ?? "default";
+
+  // Live count of direct children; fall back to the stored count before the
+  // store settles (or in a non-interactive preview).
+  const liveChildCount = nodes.filter((n) => n.parentId === id).length;
+  const childCount = liveChildCount || data.childCount || 0;
+
+  return (
+    <div
+      className={cn(
+        "flex h-full w-full flex-col rounded-lg border bg-flow-group/60 text-foreground",
+        "border-flow-group-border transition-[box-shadow,border-color] duration-fast ease-standard motion-reduce:transition-none",
+        collapsed ? "shadow-sm" : "shadow-none",
+        selected && "ring-2 ring-ring",
+      )}
+    >
+      {!collapsed && selected ? (
+        <NodeResizer
+          minWidth={160}
+          minHeight={96}
+          lineClassName="!border-flow-group-border"
+          handleClassName={handleClassName}
+        />
+      ) : null}
+
+      {/* Handles so proxy edges can attach to the group when collapsed. */}
+      <Handle type="target" position={Position.Top} className={handleClassName} />
+      <Handle type="source" position={Position.Bottom} className={handleClassName} />
+
+      <div
+        className={cn(
+          "flex items-center gap-2 px-3 py-2",
+          !collapsed && "border-b border-flow-group-border",
+        )}
+      >
+        <button
+          type="button"
+          onClick={() => toggleCollapse(id)}
+          aria-label={collapsed ? `Expand group ${data.title}` : `Collapse group ${data.title}`}
+          aria-expanded={!collapsed}
+          className={cn(
+            "-ml-1 grid size-5 shrink-0 place-items-center rounded",
+            "text-muted-foreground hover:bg-muted hover:text-foreground",
+            "focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring",
+          )}
+        >
+          {collapsed ? (
+            <ChevronRight aria-hidden="true" className="size-4" />
+          ) : (
+            <ChevronDown aria-hidden="true" className="size-4" />
+          )}
+        </button>
+
+        {data.icon ? (
+          <span className={cn("[&_svg]:size-4", toneAccent[tone])}>{data.icon}</span>
+        ) : null}
+
+        <span className="min-w-0 flex-1 truncate text-body font-medium">{data.title}</span>
+
+        <span
+          className={cn(
+            "shrink-0 rounded-full bg-muted px-1.5 py-0.5 text-meta font-medium tabular-nums",
+            toneAccent[tone],
+          )}
+          aria-label={`${childCount} ${childCount === 1 ? "node" : "nodes"}`}
+        >
+          {childCount}
+        </span>
+      </div>
+    </div>
+  );
+}

package/src/flow-group-node/index.ts

@@ -0,0 +1,6 @@
+export {
+  FlowGroupNode,
+  type FlowGroupNodeData,
+  type FlowGroupTone,
+  type BrandFlowGroupNode,
+} from "./flow-group-node";

package/src/flow-layout/flow-layout.stories.tsx

@@ -0,0 +1,215 @@
+import { useState } from "react";
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import "@xyflow/react/dist/style.css";
+import { Panel, useEdgesState, useNodesState, useReactFlow, type Edge } from "@xyflow/react";
+import { CanvasShell } from "../canvas-shell";
+import { FlowSmartEdge } from "../flow-smart-edge";
+import { FlowNode, FLOW_ALL_SIDE_HANDLES, type BrandFlowNode } from "../flow-node";
+import { ZoomControls } from "../zoom-controls";
+import { useFlowLayout } from "./use-flow-layout";
+import type { FlowLayoutDirection } from "./flow-layout";
+import { layoutGraph, type LayoutAlgorithm } from "./layout-graph";
+
+const nodeTypes = { brand: FlowNode };
+// Smart edges + all-side anchors: each edge connects on the side facing the other
+// node and RE-picks that side as the layout moves nodes — so anchors flip
+// top/bottom ↔ left/right automatically for any layout (TB, LR, concentric, …).
+const edgeTypes = { smart: FlowSmartEdge };
+
+/** A deliberately messy diamond graph — overlapping, unordered positions. */
+const messyNodes: BrandFlowNode[] = [
+  {
+    id: "ingest",
+    type: "brand",
+    position: { x: 40, y: 260 },
+    data: { kind: "Source", title: "Ingest", subtitle: "Raw data in", tone: "accent" },
+  },
+  {
+    id: "transform",
+    type: "brand",
+    position: { x: 380, y: 20 },
+    data: { kind: "Process", title: "Transform", subtitle: "Normalize & enrich" },
+  },
+  {
+    id: "validate",
+    type: "brand",
+    position: { x: 60, y: 40 },
+    data: { kind: "Process", title: "Validate", subtitle: "Quality checks" },
+  },
+  {
+    id: "enrich",
+    type: "brand",
+    position: { x: 420, y: 340 },
+    data: { kind: "Process", title: "Enrich", subtitle: "Join reference data" },
+  },
+  {
+    id: "publish",
+    type: "brand",
+    position: { x: 150, y: 420 },
+    data: { kind: "Output", title: "Publish", subtitle: "Downstream sink", tone: "success" },
+  },
+].map((n) => ({ ...n, data: { ...n.data, handles: FLOW_ALL_SIDE_HANDLES } }));
+
+const messyEdges: Edge[] = [
+  { id: "e-ingest-transform", source: "ingest", target: "transform", type: "smart" },
+  { id: "e-ingest-validate", source: "ingest", target: "validate", type: "smart" },
+  { id: "e-transform-enrich", source: "transform", target: "enrich", type: "smart" },
+  { id: "e-validate-enrich", source: "validate", target: "enrich", type: "smart" },
+  { id: "e-enrich-publish", source: "enrich", target: "publish", type: "smart" },
+];
+
+function AutoLayoutButton({ direction }: { direction: FlowLayoutDirection }) {
+  const { layout, layouting } = useFlowLayout();
+  return (
+    <button
+      type="button"
+      disabled={layouting}
+      onClick={() => layout(direction)}
+      className="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"
+    >
+      Auto layout ({direction === "TB" ? "top → bottom" : "left → right"})
+    </button>
+  );
+}
+
+function FlowLayoutDemo({ direction }: { direction: FlowLayoutDirection }) {
+  const [nodes, , onNodesChange] = useNodesState(messyNodes);
+  const [edges, , onEdgesChange] = useEdgesState(messyEdges);
+
+  return (
+    <div className="h-[500px]">
+      <CanvasShell
+        nodes={nodes}
+        edges={edges}
+        nodeTypes={nodeTypes}
+        edgeTypes={edgeTypes}
+        onNodesChange={onNodesChange}
+        onEdgesChange={onEdgesChange}
+      >
+        <Panel position="top-left">
+          <AutoLayoutButton direction={direction} />
+        </Panel>
+        <ZoomControls />
+      </CanvasShell>
+    </div>
+  );
+}
+
+const ALGORITHM_LABEL: Record<LayoutAlgorithm, string> = {
+  concentric: "concentric",
+  force: "force",
+  "layered-lr": "layered (left → right)",
+  grid: "grid",
+};
+
+function AutoLayoutGraphButton({ algorithm }: { algorithm: LayoutAlgorithm }) {
+  const { getNodes, getEdges, setNodes, fitView } = useReactFlow();
+  const [layouting, setLayouting] = useState(false);
+
+  const handleClick = () => {
+    setLayouting(true);
+    const laidOut = layoutGraph(getNodes(), getEdges(), {
+      algorithm,
+      centerId: "ingest",
+      ringRadius: 160,
+      iterations: 250,
+      spacing: { x: 220, y: 140 },
+    });
+    setNodes(laidOut);
+    requestAnimationFrame(() => {
+      fitView();
+      setLayouting(false);
+    });
+  };
+
+  return (
+    <button
+      type="button"
+      disabled={layouting}
+      onClick={handleClick}
+      className="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"
+    >
+      Auto layout ({ALGORITHM_LABEL[algorithm]})
+    </button>
+  );
+}
+
+/** Same messy dataset as `FlowLayoutDemo`, laid out via the pure `layoutGraph` helper. */
+function LayoutGraphDemo({ algorithm }: { algorithm: LayoutAlgorithm }) {
+  const [nodes, , onNodesChange] = useNodesState(messyNodes);
+  const [edges, , onEdgesChange] = useEdgesState(messyEdges);
+
+  return (
+    <div className="h-[500px]">
+      <CanvasShell
+        nodes={nodes}
+        edges={edges}
+        nodeTypes={nodeTypes}
+        edgeTypes={edgeTypes}
+        onNodesChange={onNodesChange}
+        onEdgesChange={onEdgesChange}
+      >
+        <Panel position="top-left">
+          <AutoLayoutGraphButton algorithm={algorithm} />
+        </Panel>
+        <ZoomControls />
+      </CanvasShell>
+    </div>
+  );
+}
+
+const meta = {
+  title: "Flow/FlowLayout",
+  tags: ["autodocs"],
+  parameters: { layout: "fullscreen" },
+} satisfies Meta;
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+/**
+ * A messy graph; click "Auto layout" to run `useFlowLayout` (dagre, top → bottom).
+ * Nodes carry all-side anchors and `FlowSmartEdge`, so once stacked vertically the
+ * edges connect **bottom → top** (the facing sides).
+ */
+export const Default: Story = {
+  render: () => <FlowLayoutDemo direction="TB" />,
+};
+
+/**
+ * Same graph, laid out left → right. Because the edges are smart + the nodes have
+ * anchors on every side, the connections **re-pick the facing side automatically**
+ * — now the right (source) / left (target) sides — instead of routing through
+ * top/bottom.
+ */
+export const LeftToRight: Story = {
+  render: () => <FlowLayoutDemo direction="LR" />,
+};
+
+/**
+ * `layoutGraph({ algorithm: "concentric" })` — the "ingest" node is the focal
+ * center; the rest of the graph radiates outward in BFS shells.
+ */
+export const Concentric: Story = {
+  render: () => <LayoutGraphDemo algorithm="concentric" />,
+};
+
+/**
+ * `layoutGraph({ algorithm: "force" })` — a deterministic, seeded `d3-force`
+ * simulation spreads the nodes apart.
+ */
+export const Force: Story = {
+  render: () => <LayoutGraphDemo algorithm="force" />,
+};
+
+/**
+ * `layoutGraph({ algorithm: "layered-lr" })` — delegates to the same dagre
+ * engine as `useFlowLayout`, exposed as a pure function.
+ */
+export const LayeredLR: Story = {
+  render: () => <LayoutGraphDemo algorithm="layered-lr" />,
+};
+
+/** `layoutGraph({ algorithm: "grid" })` — a simple row-major grid. */
+export const Grid: Story = {
+  render: () => <LayoutGraphDemo algorithm="grid" />,
+};

package/src/flow-layout/flow-layout.test.tsx

@@ -0,0 +1,133 @@
+import { describe, expect, it } from "vitest";
+import type { Edge, Node } from "@xyflow/react";
+import { layoutFlow } from "./flow-layout";
+
+function chainNodes(): Node[] {
+  return [
+    { id: "a", type: "brand", position: { x: 0, y: 0 }, data: { title: "A" } },
+    { id: "b", type: "brand", position: { x: 0, y: 0 }, data: { title: "B" } },
+    { id: "c", type: "brand", position: { x: 0, y: 0 }, data: { title: "C" } },
+  ];
+}
+
+function chainEdges(): Edge[] {
+  return [
+    { id: "e-ab", source: "a", target: "b" },
+    { id: "e-bc", source: "b", target: "c" },
+  ];
+}
+
+describe("layoutFlow", () => {
+  it("orders a 3-node chain top-to-bottom for direction=TB (default)", () => {
+    const { nodes } = layoutFlow(chainNodes(), chainEdges());
+    const [a, b, c] = nodes as [Node, Node, Node];
+
+    // Ranks increase down the y axis; x stays roughly aligned per rank.
+    expect(a.position.y).toBeLessThan(b.position.y);
+    expect(b.position.y).toBeLessThan(c.position.y);
+  });
+
+  it("orders a 3-node chain left-to-right for direction=LR", () => {
+    const { nodes } = layoutFlow(chainNodes(), chainEdges(), { direction: "LR" });
+    const [a, b, c] = nodes as [Node, Node, Node];
+
+    expect(a.position.x).toBeLessThan(b.position.x);
+    expect(b.position.x).toBeLessThan(c.position.x);
+  });
+
+  it("moves the handle sides with the direction (TB → bottom/top, LR → right/left)", () => {
+    const tb = layoutFlow(chainNodes(), chainEdges(), { direction: "TB" }).nodes[0]!;
+    expect(tb.sourcePosition).toBe("bottom");
+    expect(tb.targetPosition).toBe("top");
+
+    const lr = layoutFlow(chainNodes(), chainEdges(), { direction: "LR" }).nodes[0]!;
+    expect(lr.sourcePosition).toBe("right");
+    expect(lr.targetPosition).toBe("left");
+
+    const rl = layoutFlow(chainNodes(), chainEdges(), { direction: "RL" }).nodes[0]!;
+    expect(rl.sourcePosition).toBe("left");
+    expect(rl.targetPosition).toBe("right");
+  });
+
+  it("reverses rank order for direction=BT relative to TB", () => {
+    const { nodes: tb } = layoutFlow(chainNodes(), chainEdges(), { direction: "TB" });
+    const { nodes: bt } = layoutFlow(chainNodes(), chainEdges(), { direction: "BT" });
+    const [tbA, tbB] = tb as [Node, Node];
+    const [btA, btB] = bt as [Node, Node];
+
+    // TB: a above b above c. BT: a below b below c.
+    expect(tbA.position.y).toBeLessThan(tbB.position.y);
+    expect(btA.position.y).toBeGreaterThan(btB.position.y);
+  });
+
+  it("preserves node identity and data — only position changes", () => {
+    const original = chainNodes();
+    const { nodes } = layoutFlow(original, chainEdges());
+
+    nodes.forEach((node, i) => {
+      expect(node.id).toBe(original[i]!.id);
+      expect(node.data).toBe(original[i]!.data);
+      expect(node.type).toBe(original[i]!.type);
+    });
+  });
+
+  it("preserves edges unchanged (same reference, same array)", () => {
+    const edges = chainEdges();
+    const { edges: outEdges } = layoutFlow(chainNodes(), edges);
+    expect(outEdges).toBe(edges);
+  });
+
+  it("honors measured size over a stale width/height", () => {
+    const nodes: Node[] = [
+      {
+        id: "a",
+        position: { x: 0, y: 0 },
+        data: {},
+        width: 50,
+        height: 20,
+        measured: { width: 400, height: 200 },
+      },
+      {
+        id: "b",
+        position: { x: 0, y: 0 },
+        data: {},
+        width: 50,
+        height: 20,
+        measured: { width: 400, height: 200 },
+      },
+    ];
+    const edges: Edge[] = [{ id: "e-ab", source: "a", target: "b" }];
+
+    const { nodes: layouted } = layoutFlow(nodes, edges, { direction: "LR" });
+    const [a, b] = layouted;
+
+    // With a 400-wide measured size and default 72px ranksep, b must start at
+    // least a.x + measured.width + ranksep away — a value only reachable if
+    // the (much larger) measured size, not the stale width, drove the layout.
+    expect(b!.position.x - a!.position.x).toBeGreaterThanOrEqual(400 + 72 - 1);
+  });
+
+  it("falls back to a sensible default size when neither measured nor width/height are set", () => {
+    const nodes: Node[] = [
+      { id: "a", position: { x: 0, y: 0 }, data: {} },
+      { id: "b", position: { x: 0, y: 0 }, data: {} },
+    ];
+    const edges: Edge[] = [{ id: "e-ab", source: "a", target: "b" }];
+
+    expect(() => layoutFlow(nodes, edges)).not.toThrow();
+    const { nodes: layouted } = layoutFlow(nodes, edges);
+    expect(Number.isFinite(layouted[0]!.position.x)).toBe(true);
+    expect(Number.isFinite(layouted[0]!.position.y)).toBe(true);
+  });
+
+  it("respects custom nodeSpacing/rankSpacing", () => {
+    const nodes = chainNodes();
+    const edges = chainEdges();
+    const tight = layoutFlow(nodes, edges, { rankSpacing: 10 });
+    const wide = layoutFlow(nodes, edges, { rankSpacing: 500 });
+
+    const tightGap = tight.nodes[1]!.position.y - tight.nodes[0]!.position.y;
+    const wideGap = wide.nodes[1]!.position.y - wide.nodes[0]!.position.y;
+    expect(wideGap).toBeGreaterThan(tightGap);
+  });
+});