@elabs-ai/components-flow 4.0.0

package/src/flow-layout/use-auto-layout.ts

@@ -0,0 +1,26 @@
+import { useMemo } from "react";
+import type { Edge, Node } from "@xyflow/react";
+import { layoutGraph, type LayoutOptions } from "./layout-graph";
+
+/**
+ * Memoized `layoutGraph` — pure graph-geometry layout (no live canvas access,
+ * no side effects). Recomputes only when `nodes`, `edges`, or `options`
+ * change; pass stable references (e.g. from `useNodesState`/`useEdgesState`
+ * and a memoized `options` object) to avoid recomputing every render.
+ *
+ * Use this when you want laid-out nodes to render with (e.g. feeding
+ * `useNodesState`'s initial value, or a derived/read-only view). To apply a
+ * layout to a *live* React Flow instance (read current nodes, set them back,
+ * fit the view), call `layoutGraph` directly from an event handler instead —
+ * see the `LayoutGraph` story.
+ */
+export function useAutoLayout<NodeType extends Node = Node, EdgeType extends Edge = Edge>(
+  nodes: NodeType[],
+  edges: EdgeType[],
+  options: LayoutOptions,
+): NodeType[] {
+  return useMemo(
+    () => layoutGraph<NodeType, EdgeType>(nodes, edges, options),
+    [nodes, edges, options],
+  );
+}

package/src/flow-layout/use-flow-layout.ts

@@ -0,0 +1,60 @@
+import { useCallback, useRef, useState } from "react";
+import { useNodesInitialized, useReactFlow, type Edge, type Node } from "@xyflow/react";
+import { layoutFlow, type FlowLayoutDirection, type FlowLayoutOptions } from "./flow-layout";
+
+export interface UseFlowLayoutResult {
+  /**
+   * Auto-lay-out the current nodes/edges with dagre and fit the view. Safe to
+   * call repeatedly (e.g. from a toolbar button on every click). No-ops until
+   * React Flow has measured every node.
+   */
+  layout: (direction?: FlowLayoutDirection, options?: Omit<FlowLayoutOptions, "direction">) => void;
+  /** Whether nodes are measured and ready to be laid out. */
+  ready: boolean;
+  /** Whether a layout pass is currently running (true only for the duration of `layout()`). */
+  layouting: boolean;
+}
+
+/**
+ * Hook form of `layoutFlow`. Reads the live nodes/edges from `useReactFlow()`,
+ * waits for `useNodesInitialized()` so real (measured) node sizes are used —
+ * never lays out against 0×0 unmeasured nodes — applies the computed
+ * positions via `setNodes`, then calls `fitView()`.
+ *
+ * Must be called from a component rendered inside a `<CanvasShell>` /
+ * `<ReactFlow>` (React Flow context).
+ */
+export function useFlowLayout<
+  NodeType extends Node = Node,
+  EdgeType extends Edge = Edge,
+>(): UseFlowLayoutResult {
+  const { getNodes, getEdges, setNodes, fitView } = useReactFlow<NodeType, EdgeType>();
+  const nodesInitialized = useNodesInitialized();
+  const [layouting, setLayouting] = useState(false);
+  // Avoid overlapping layout passes if `layout()` is invoked in quick succession.
+  const runningRef = useRef(false);
+
+  const layout = useCallback(
+    (direction?: FlowLayoutDirection, options?: Omit<FlowLayoutOptions, "direction">) => {
+      if (!nodesInitialized || runningRef.current) return;
+
+      runningRef.current = true;
+      setLayouting(true);
+      try {
+        const { nodes: layoutedNodes } = layoutFlow<NodeType, EdgeType>(getNodes(), getEdges(), {
+          ...options,
+          direction,
+        });
+        setNodes(layoutedNodes);
+        // Defer fitView one frame so React Flow has committed the new positions first.
+        requestAnimationFrame(() => fitView());
+      } finally {
+        runningRef.current = false;
+        setLayouting(false);
+      }
+    },
+    [nodesInitialized, getNodes, getEdges, setNodes, fitView],
+  );
+
+  return { layout, ready: nodesInitialized, layouting };
+}

package/src/flow-mini-map/flow-mini-map.stories.tsx

@@ -0,0 +1,74 @@
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import "@xyflow/react/dist/style.css";
+import { CanvasShell } from "../canvas-shell";
+import { FlowNode, FLOW_ALL_SIDE_HANDLES, type BrandFlowNode } from "../flow-node";
+import { FlowSmartEdge } from "../flow-smart-edge";
+import { ZoomControls } from "../zoom-controls";
+import { FlowMiniMap } from "./flow-mini-map";
+import type { Edge } from "@xyflow/react";
+
+const nodeTypes = { brand: FlowNode };
+const edgeTypes = { smart: FlowSmartEdge };
+
+// Anchors on all four sides + the smart edge → each connection lands on the side
+// that faces the other node (here the graph runs left→right, so edges attach on
+// the right/left sides), not always top/bottom.
+const nodes: BrandFlowNode[] = [
+  {
+    id: "1",
+    type: "brand",
+    position: { x: 0, y: 0 },
+    data: {
+      kind: "Source",
+      title: "Postgres",
+      subtitle: "orders",
+      tone: "accent",
+      handles: FLOW_ALL_SIDE_HANDLES,
+    },
+  },
+  {
+    id: "2",
+    type: "brand",
+    position: { x: 250, y: 140 },
+    data: {
+      kind: "Transform",
+      title: "Clean & join",
+      tone: "default",
+      handles: FLOW_ALL_SIDE_HANDLES,
+    },
+  },
+  {
+    id: "3",
+    type: "brand",
+    position: { x: 500, y: 0 },
+    data: { kind: "Output", title: "Dashboard", tone: "success", handles: FLOW_ALL_SIDE_HANDLES },
+  },
+];
+const edges: Edge[] = [
+  { id: "e1-2", source: "1", target: "2", type: "smart" },
+  { id: "e2-3", source: "2", target: "3", type: "smart" },
+];
+
+const meta = {
+  title: "Flow/FlowMiniMap",
+  component: FlowMiniMap,
+  tags: ["autodocs"],
+  parameters: { layout: "fullscreen" },
+} satisfies Meta<typeof FlowMiniMap>;
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+/**
+ * FlowMiniMap must render inside a CanvasShell (React Flow context). Node dots
+ * and the viewport mask are token-driven, so they stay legible in every theme.
+ */
+export const Default: Story = {
+  render: () => (
+    <div className="h-[500px]">
+      <CanvasShell nodes={nodes} edges={edges} nodeTypes={nodeTypes} edgeTypes={edgeTypes}>
+        <ZoomControls />
+        <FlowMiniMap />
+      </CanvasShell>
+    </div>
+  ),
+};

package/src/flow-mini-map/flow-mini-map.test.tsx

@@ -0,0 +1,56 @@
+import { cleanup, render } from "@testing-library/react";
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+// @xyflow/react's MiniMap needs real flow context/measurement — mock it and
+// assert the brand wrapper's own output (token-driven color defaults +
+// className merge). Real rendering + a11y are covered by Storybook
+// interaction tests.
+const miniMapSpy = vi.fn();
+
+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 {
+    MiniMap: (props: { className?: string }) => {
+      miniMapSpy(props);
+      return React.createElement("div", {
+        "data-testid": "rf-minimap",
+        className: props.className,
+      });
+    },
+  };
+});
+
+import { FlowMiniMap } from "./flow-mini-map";
+
+afterEach(() => {
+  cleanup();
+  miniMapSpy.mockClear();
+});
+
+describe("FlowMiniMap", () => {
+  it("renders without throwing", () => {
+    const { getByTestId } = render(<FlowMiniMap />);
+    expect(getByTestId("rf-minimap")).toBeInTheDocument();
+  });
+
+  it("defaults nodeColor/nodeStrokeColor/maskColor to the flow-minimap tokens", () => {
+    render(<FlowMiniMap />);
+    const props = miniMapSpy.mock.calls[0]?.[0];
+    expect(props.nodeColor).toBe("var(--flow-minimap-node)");
+    expect(props.nodeStrokeColor).toBe("var(--flow-minimap-node)");
+    expect(props.maskColor).toBe("var(--flow-minimap-mask)");
+  });
+
+  it("lets a caller override nodeColor/maskColor", () => {
+    render(<FlowMiniMap nodeColor="red" maskColor="blue" />);
+    const props = miniMapSpy.mock.calls[0]?.[0];
+    expect(props.nodeColor).toBe("red");
+    expect(props.maskColor).toBe("blue");
+  });
+
+  it("merges a custom className with the branded panel classes", () => {
+    const { getByTestId } = render(<FlowMiniMap className="my-minimap" />);
+    expect(getByTestId("rf-minimap")).toHaveClass("my-minimap");
+  });
+});

package/src/flow-mini-map/flow-mini-map.tsx

@@ -0,0 +1,29 @@
+import { MiniMap, type MiniMapProps, type Node } from "@xyflow/react";
+import { cn } from "@elabs-ai/components-ui/lib/cn";
+
+export type FlowMiniMapProps<NodeType extends Node = Node> = MiniMapProps<NodeType>;
+
+/**
+ * Branded preset over React Flow's `<MiniMap>` — sources node/mask colors from
+ * the `--flow-minimap-*` tokens so the overview stays theme-aware (the raw
+ * `MiniMap` re-export defaults to library colors and renders theme-blind,
+ * especially under a low-chroma theme). Every prop can still be overridden; render
+ * inside a `<CanvasShell>` (it needs the React Flow context via `useStore`).
+ */
+export function FlowMiniMap<NodeType extends Node = Node>({
+  className,
+  nodeColor = "var(--flow-minimap-node)",
+  nodeStrokeColor = "var(--flow-minimap-node)",
+  maskColor = "var(--flow-minimap-mask)",
+  ...props
+}: FlowMiniMapProps<NodeType>) {
+  return (
+    <MiniMap
+      className={cn("!rounded-lg !bg-surface-elevated !shadow-ring-sm", className)}
+      nodeColor={nodeColor}
+      nodeStrokeColor={nodeStrokeColor}
+      maskColor={maskColor}
+      {...props}
+    />
+  );
+}

package/src/flow-mini-map/index.ts

@@ -0,0 +1 @@
+export { FlowMiniMap, type FlowMiniMapProps } from "./flow-mini-map";

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

@@ -0,0 +1,143 @@
+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";
+
+const nodeTypes = { brand: FlowNode };
+
+const meta = {
+  title: "Flow/FlowNode",
+  component: FlowNode,
+  tags: ["autodocs"],
+  parameters: { layout: "fullscreen" },
+} satisfies Meta<typeof FlowNode>;
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+/** Default node with all data fields populated (kind, title, subtitle, tone=accent). */
+export const Default: Story = {
+  render: () => {
+    const nodes: BrandFlowNode[] = [
+      {
+        id: "1",
+        type: "brand",
+        position: { x: 120, y: 80 },
+        data: { kind: "Source", title: "Postgres", subtitle: "orders table", tone: "accent" },
+      },
+    ];
+    return (
+      <div className="h-[300px]">
+        <CanvasShell nodes={nodes} edges={[]} nodeTypes={nodeTypes} />
+      </div>
+    );
+  },
+};
+
+/** Tone variants: default, accent, success, warning, destructive. */
+export const Tones: Story = {
+  render: () => {
+    const nodes: BrandFlowNode[] = [
+      {
+        id: "default",
+        type: "brand",
+        position: { x: 20, y: 20 },
+        data: { kind: "Transform", title: "Clean & join", tone: "default" },
+      },
+      {
+        id: "accent",
+        type: "brand",
+        position: { x: 220, y: 20 },
+        data: { kind: "Source", title: "Postgres", tone: "accent" },
+      },
+      {
+        id: "success",
+        type: "brand",
+        position: { x: 420, y: 20 },
+        data: { kind: "Output", title: "Dashboard", tone: "success" },
+      },
+      {
+        id: "warning",
+        type: "brand",
+        position: { x: 620, y: 20 },
+        data: { kind: "Alert", title: "Latency", tone: "warning" },
+      },
+      {
+        id: "destructive",
+        type: "brand",
+        position: { x: 820, y: 20 },
+        data: { kind: "Error", title: "Failed", tone: "destructive" },
+      },
+    ];
+    return (
+      <div className="h-[200px]">
+        <CanvasShell nodes={nodes} edges={[]} nodeTypes={nodeTypes} />
+      </div>
+    );
+  },
+};
+
+/** Node without optional subtitle or kind — minimal data shape. */
+export const Minimal: Story = {
+  render: () => {
+    const nodes: BrandFlowNode[] = [
+      {
+        id: "1",
+        type: "brand",
+        position: { x: 120, y: 80 },
+        data: { title: "Simple node" },
+      },
+    ];
+    return (
+      <div className="h-[200px]">
+        <CanvasShell nodes={nodes} edges={[]} nodeTypes={nodeTypes} />
+      </div>
+    );
+  },
+};
+
+/** Selected node shows a ring highlight. */
+export const Selected: Story = {
+  render: () => {
+    const nodes: BrandFlowNode[] = [
+      {
+        id: "1",
+        type: "brand",
+        position: { x: 120, y: 80 },
+        selected: true,
+        data: { kind: "Output", title: "Dashboard", subtitle: "analytics", tone: "success" },
+      },
+    ];
+    return (
+      <div className="h-[250px]">
+        <CanvasShell nodes={nodes} edges={[]} nodeTypes={nodeTypes} />
+      </div>
+    );
+  },
+};
+
+/** Two connected nodes to show handles in context. */
+export const Connected: Story = {
+  render: () => {
+    const nodes: BrandFlowNode[] = [
+      {
+        id: "1",
+        type: "brand",
+        position: { x: 80, y: 40 },
+        data: { kind: "Source", title: "Postgres", tone: "accent" },
+      },
+      {
+        id: "2",
+        type: "brand",
+        position: { x: 80, y: 200 },
+        data: { kind: "Output", title: "Dashboard", tone: "success" },
+      },
+    ];
+    const edges: Edge[] = [{ id: "e1-2", source: "1", target: "2" }];
+    return (
+      <div className="h-[350px]">
+        <CanvasShell nodes={nodes} edges={edges} nodeTypes={nodeTypes} />
+      </div>
+    );
+  },
+};

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

@@ -0,0 +1,156 @@
+import { cleanup, render, screen } from "@testing-library/react";
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+// @xyflow/react requires real layout/measurement — mock the engine and assert
+// the brand component's own output. Real rendering + a11y are covered by
+// Storybook interaction tests.
+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,
+      position,
+      className,
+    }: {
+      type: string;
+      position: string;
+      className?: string;
+    }) =>
+      React.createElement("div", {
+        "data-testid": `handle-${type}`,
+        "data-position": position,
+        className,
+      }),
+    Position: { Top: "top", Bottom: "bottom", Left: "left", Right: "right" },
+  };
+});
+
+import { FlowNode, type BrandFlowNode } from "./flow-node";
+import type { NodeProps } from "@xyflow/react";
+
+afterEach(cleanup);
+
+/** Minimal NodeProps factory for FlowNode (BrandFlowNode). */
+function makeProps(
+  data: BrandFlowNode["data"],
+  overrides: Partial<NodeProps<BrandFlowNode>> = {},
+): NodeProps<BrandFlowNode> {
+  return {
+    id: "test-node",
+    data,
+    selected: false,
+    dragging: false,
+    zIndex: 0,
+    isConnectable: true,
+    draggable: true,
+    deletable: true,
+    selectable: true,
+    positionAbsoluteX: 0,
+    positionAbsoluteY: 0,
+    width: 160,
+    height: 48,
+    type: "brand",
+    ...overrides,
+  };
+}
+
+describe("FlowNode", () => {
+  it("renders the title", () => {
+    render(<FlowNode {...makeProps({ title: "My Node" })} />);
+    expect(screen.getByText("My Node")).toBeInTheDocument();
+  });
+
+  it("renders the subtitle when provided", () => {
+    render(<FlowNode {...makeProps({ title: "Node", subtitle: "sub detail" })} />);
+    expect(screen.getByText("sub detail")).toBeInTheDocument();
+  });
+
+  it("renders the kind eyebrow when provided", () => {
+    render(<FlowNode {...makeProps({ title: "Transform", kind: "Source" })} />);
+    expect(screen.getByText("Source")).toBeInTheDocument();
+  });
+
+  it("renders source and target handles", () => {
+    render(<FlowNode {...makeProps({ title: "Node" })} />);
+    expect(screen.getByTestId("handle-target")).toBeInTheDocument();
+    expect(screen.getByTestId("handle-source")).toBeInTheDocument();
+  });
+
+  it("renders an icon when provided", () => {
+    render(
+      <FlowNode
+        {...makeProps({ title: "Node", icon: <svg data-testid="node-icon" aria-hidden="true" /> })}
+      />,
+    );
+    expect(screen.getByTestId("node-icon")).toBeInTheDocument();
+  });
+
+  it("omits the subtitle when not provided", () => {
+    render(<FlowNode {...makeProps({ title: "Node" })} />);
+    // Only the title text should be present
+    expect(screen.queryByText("sub detail")).not.toBeInTheDocument();
+  });
+});
+
+// #387 — `tone` used to be encoded in colour ALONE (a 1px border, no DOM
+// attribute, no icon, no accessible name — WCAG 1.4.1). Every non-default
+// tone now carries a `data-tone` attribute, a distinct-SHAPE Lucide glyph
+// (not just a distinct class string — asserted via each icon's own
+// `lucide-<name>` class, which is the actual rendered shape signature) and a
+// distinct `sr-only` accessible name. `default` deliberately gets none of
+// the three, so an ordinary node stays visually and AT-quiet.
+describe("FlowNode tone — colour is never the only channel (#387)", () => {
+  const TONE_GLYPH_CLASS: Record<string, string | null> = {
+    default: null,
+    accent: "lucide-star",
+    success: "lucide-circle-check",
+    warning: "lucide-clock",
+    destructive: "lucide-circle-alert",
+  };
+  const TONE_LABEL: Record<string, string | null> = {
+    default: null,
+    accent: "Highlighted",
+    success: "Success",
+    warning: "Warning",
+    destructive: "Destructive",
+  };
+  const ALL_GLYPH_CLASSES = Object.values(TONE_GLYPH_CLASS).filter((c): c is string => c !== null);
+
+  it("every tone's glyph is a distinct SHAPE — no two tones share an icon", () => {
+    expect(new Set(ALL_GLYPH_CLASSES).size).toBe(ALL_GLYPH_CLASSES.length);
+  });
+
+  it.each(Object.keys(TONE_GLYPH_CLASS))(
+    "tone=%s exposes data-tone and its own non-colour glyph + accessible name",
+    (tone) => {
+      const { container } = render(
+        <FlowNode {...makeProps({ title: "Node", tone: tone as BrandFlowNode["data"]["tone"] })} />,
+      );
+      expect(container.querySelector(`[data-tone="${tone}"]`)).toBeInTheDocument();
+
+      const expectedGlyph = TONE_GLYPH_CLASS[tone];
+      for (const glyphClass of ALL_GLYPH_CLASSES) {
+        const present = container.querySelector(`svg.${glyphClass}`) !== null;
+        expect(present).toBe(glyphClass === expectedGlyph);
+      }
+
+      const expectedLabel = TONE_LABEL[tone];
+      if (expectedLabel) {
+        expect(container).toHaveTextContent(expectedLabel);
+      } else {
+        for (const label of Object.values(TONE_LABEL)) {
+          if (label) expect(container).not.toHaveTextContent(label);
+        }
+      }
+    },
+  );
+
+  it("the tone glyph is aria-hidden (the sr-only text carries the meaning, not the icon)", () => {
+    const { container } = render(
+      <FlowNode {...makeProps({ title: "Node", tone: "destructive" })} />,
+    );
+    const glyph = container.querySelector("svg.lucide-circle-alert");
+    expect(glyph).toHaveAttribute("aria-hidden", "true");
+  });
+});