@elabs-ai/components-flow 4.2.0 → 5.0.0

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

@@ -0,0 +1,154 @@
+import { useEffect, useState } from "react";
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import "@xyflow/react/dist/style.css";
+import type { Edge } from "@xyflow/react";
+import { expect, waitFor } from "storybook/test";
+import { CanvasShell } from "../canvas-shell";
+import { FlowNode, type BrandFlowNode } from "../flow-node";
+import { FlowSmartEdge } from "../flow-smart-edge";
+import { ZoomControls } from "../zoom-controls";
+import { pinBackbone } from "./backbone";
+import {
+  layoutFlowElk,
+  type FlowLayoutElkOptions,
+  type FlowLayoutElkResult,
+} from "./layout-flow-elk";
+
+const nodeTypes = { brand: FlowNode };
+const edgeTypes = { smart: FlowSmartEdge };
+
+/** A small order-to-cash process with a skip path and a rework loop. */
+const processNodes: BrandFlowNode[] = [
+  { id: "start", title: "Order received", tone: "accent" as const },
+  { id: "check", title: "Check credit" },
+  { id: "info", title: "Request info" },
+  { id: "approve", title: "Approve order" },
+  { id: "ship", title: "Ship goods" },
+  { id: "invoice", title: "Send invoice", tone: "success" as const },
+].map(({ id, title, tone }) => ({
+  id,
+  type: "brand",
+  position: { x: 0, y: 0 },
+  data: { kind: "Activity", title, ...(tone ? { tone } : {}) },
+}));
+
+const processEdges: Edge[] = [
+  ["start", "check"],
+  ["check", "approve"],
+  ["approve", "ship"],
+  ["ship", "invoice"],
+  ["start", "approve"],
+  ["check", "info"],
+  ["info", "check"],
+].map(([source, target]) => ({
+  id: `${source}-${target}`,
+  source: source!,
+  target: target!,
+  type: "smart",
+}));
+
+type Options = Omit<FlowLayoutElkOptions, "backbone"> & { pinTopVariant?: boolean };
+
+function ElkLayoutDemo({ pinTopVariant, ...options }: Options) {
+  const [result, setResult] = useState<FlowLayoutElkResult<BrandFlowNode, Edge> | null>(null);
+
+  useEffect(() => {
+    let current = true;
+    const backbone = pinTopVariant
+      ? pinBackbone(processNodes, processEdges, ["start", "check", "approve", "ship", "invoice"])
+      : undefined;
+    void layoutFlowElk(processNodes, processEdges, {
+      ...options,
+      ...(backbone ? { backbone } : {}),
+    }).then((next) => {
+      if (current) setResult(next);
+    });
+    return () => {
+      current = false;
+    };
+    // The story's args never change after mount.
+    // eslint-disable-next-line react-hooks/exhaustive-deps -- args are static per story
+  }, []);
+
+  return (
+    <div className="flex h-[500px] flex-col gap-2 p-4">
+      <p role="status" aria-live="polite" className="text-caption text-muted-foreground">
+        {result ? `Laid out by ${result.engine}` : "Laying out…"}
+      </p>
+      <div className="min-h-0 flex-1" data-engine={result?.engine}>
+        {result ? (
+          <CanvasShell
+            nodes={result.nodes}
+            edges={result.edges}
+            nodeTypes={nodeTypes}
+            edgeTypes={edgeTypes}
+            fitView
+          >
+            <ZoomControls />
+          </CanvasShell>
+        ) : null}
+      </div>
+    </div>
+  );
+}
+
+const meta = {
+  title: "Flow/FlowLayoutElk",
+  component: ElkLayoutDemo,
+  tags: ["autodocs"],
+  parameters: {
+    layout: "fullscreen",
+    docs: {
+      description: {
+        component:
+          "`layoutFlowElk` lays a graph out with ELK’s layered algorithm — same result " +
+          "shape as `layoutFlow`, plus the engine that answered. elkjs is an optional " +
+          "peer loaded with `import()` on first call, run in a web worker when one is " +
+          "available; without it the call falls back to dagre with a development-only " +
+          "warning.",
+      },
+    },
+  },
+} satisfies Meta<typeof ElkLayoutDemo>;
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+/** ELK, left to right, with orthogonal routing requested. */
+export const ElkLayout: Story = {
+  args: { direction: "LR", edgeRouting: "orthogonal" },
+  play: async ({ canvasElement }) => {
+    await waitFor(() => expect(canvasElement.querySelector('[data-engine="elk"]')).toBeTruthy(), {
+      timeout: 10_000,
+    });
+    await waitFor(() =>
+      expect(canvasElement.querySelectorAll(".react-flow__node")).toHaveLength(processNodes.length),
+    );
+  },
+};
+
+/** The most frequent variant pinned to one straight row with `pinBackbone`. */
+export const Backbone: Story = {
+  args: { direction: "LR", pinTopVariant: true },
+  play: async ({ canvasElement }) => {
+    await waitFor(() => expect(canvasElement.querySelector('[data-engine="elk"]')).toBeTruthy(), {
+      timeout: 10_000,
+    });
+  },
+};
+
+/**
+ * elkjs unavailable: the engine loader rejects the way a missing optional peer does, and
+ * the graph is laid out by dagre instead — a console warning in development, never a crash.
+ */
+export const DagreFallback: Story = {
+  args: {
+    direction: "LR",
+    loadEngine: () => Promise.reject(new Error("Cannot find module 'elkjs'")),
+  },
+  play: async ({ canvasElement }) => {
+    await waitFor(() => expect(canvasElement.querySelector('[data-engine="dagre"]')).toBeTruthy());
+    await waitFor(() =>
+      expect(canvasElement.querySelectorAll(".react-flow__node")).toHaveLength(processNodes.length),
+    );
+  },
+};

package/src/flow-layout/layout-flow-elk.test.ts

@@ -0,0 +1,152 @@
+import { readdirSync, readFileSync, statSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import type { Edge, Node } from "@xyflow/react";
+import { layoutFlow } from "./flow-layout";
+import { layoutFlowElk } from "./layout-flow-elk";
+
+function chainNodes(): Node[] {
+  return ["a", "b", "c"].map((id) => ({
+    id,
+    type: "brand",
+    position: { x: 0, y: 0 },
+    data: { title: id.toUpperCase() },
+  }));
+}
+
+/** RM-044's canonical rework fixture: A → B → C, C loops back to B, and B repeats itself. */
+function reworkEdges(): Edge[] {
+  return [
+    { id: "e-ab", source: "a", target: "b" },
+    { id: "e-bc", source: "b", target: "c" },
+    { id: "e-cb", source: "c", target: "b" },
+    { id: "e-bb", source: "b", target: "b" },
+  ];
+}
+
+afterEach(() => {
+  vi.restoreAllMocks();
+});
+
+describe("layoutFlowElk", () => {
+  it("lays the rework fixture out with ELK: no NaN, same node order as dagre", async () => {
+    const nodes = chainNodes();
+    const edges = reworkEdges();
+    const elk = await layoutFlowElk(nodes, edges);
+    const dagre = layoutFlow(nodes, edges);
+
+    expect(elk.engine).toBe("elk");
+    for (const node of elk.nodes) {
+      expect(Number.isFinite(node.position.x)).toBe(true);
+      expect(Number.isFinite(node.position.y)).toBe(true);
+    }
+    const order = (list: Node[]) =>
+      [...list].sort((p, q) => p.position.y - q.position.y).map((n) => n.id);
+    expect(order(elk.nodes)).toEqual(order(dagre.nodes));
+    expect(elk.backEdges).toEqual(dagre.backEdges);
+    expect(elk.selfLoops).toEqual(["e-bb"]);
+    expect(elk.edges).toBe(edges);
+  });
+
+  it("classifies the back edge in every direction and moves handles with it", async () => {
+    for (const direction of ["TB", "BT", "LR", "RL"] as const) {
+      const result = await layoutFlowElk(chainNodes(), reworkEdges(), { direction });
+      expect(result.backEdges).toEqual(["e-cb"]);
+    }
+    const lr = await layoutFlowElk(chainNodes(), reworkEdges(), { direction: "LR" });
+    expect(lr.nodes[0]!.sourcePosition).toBe("right");
+    expect(lr.nodes[0]!.targetPosition).toBe("left");
+  });
+
+  it("round-trips groups to parentId + relative positions, sizing the group", async () => {
+    const nodes: Node[] = [
+      { id: "g", type: "group", position: { x: 0, y: 0 }, data: {} },
+      ...chainNodes(),
+    ];
+    const result = await layoutFlowElk(nodes, reworkEdges(), {
+      edgeRouting: "orthogonal",
+      groups: [{ id: "g", children: ["b", "c"] }],
+    });
+    const byId = new Map(result.nodes.map((n) => [n.id, n]));
+    expect(byId.get("b")!.parentId).toBe("g");
+    expect(byId.get("c")!.parentId).toBe("g");
+    expect(byId.get("a")!.parentId).toBeUndefined();
+    expect(byId.get("g")!.width).toBeGreaterThan(172);
+    expect(byId.get("b")!.position.x).toBeGreaterThanOrEqual(0);
+  });
+
+  it("falls back to dagre with a warning when the engine cannot load", async () => {
+    const warn = vi.spyOn(console, "warn").mockImplementation(() => undefined);
+    const nodes = chainNodes();
+    const edges = reworkEdges();
+    const result = await layoutFlowElk(nodes, edges, {
+      loadEngine: () => Promise.reject(new Error("Cannot find module 'elkjs'")),
+    });
+    expect(result.engine).toBe("dagre");
+    expect(result.nodes).toEqual(layoutFlow(nodes, edges).nodes);
+    expect(warn).toHaveBeenCalledTimes(1);
+  });
+
+  it("falls back to dagre when ELK itself throws", async () => {
+    vi.spyOn(console, "warn").mockImplementation(() => undefined);
+    const result = await layoutFlowElk(chainNodes(), reworkEdges(), {
+      loadEngine: async () => ({ layout: () => Promise.reject(new Error("bad graph")) }),
+    });
+    expect(result.engine).toBe("dagre");
+  });
+});
+
+describe("elkjs lazy boundary (RM-067)", () => {
+  const srcDir = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+
+  /** Every non-test, non-story source file statically reachable from the package barrel. */
+  function staticGraph(entry: string): Set<string> {
+    const seen = new Set<string>();
+    const queue = [entry];
+    while (queue.length > 0) {
+      const file = queue.pop()!;
+      if (seen.has(file)) continue;
+      seen.add(file);
+      const source = readFileSync(file, "utf8");
+      const re = /^\s*(?:import|export)\s+(?!type\s)(?:[\s\S]*?\sfrom\s*)?["'](\.[^"']*)["']/gm;
+      for (const match of source.matchAll(re)) {
+        const base = join(dirname(file), match[1]!);
+        const hit = [
+          `${base}.ts`,
+          `${base}.tsx`,
+          join(base, "index.ts"),
+          join(base, "index.tsx"),
+        ].find((candidate) => {
+          try {
+            return statSync(candidate).isFile();
+          } catch {
+            return false;
+          }
+        });
+        if (hit) queue.push(hit);
+      }
+    }
+    return seen;
+  }
+
+  it("never imports elkjs statically from anything the barrel reaches", () => {
+    const reachable = staticGraph(join(srcDir, "index.ts"));
+    expect(reachable.has(join(srcDir, "flow-layout", "layout-flow-elk.ts"))).toBe(true);
+    const offenders = [...reachable].filter((file) =>
+      /^\s*(?:import|export)\s+(?!type\s)(?:[\s\S]*?\sfrom\s*)?["']elkjs(?:\/[^"']*)?["']/m.test(
+        readFileSync(file, "utf8"),
+      ),
+    );
+    expect(offenders).toEqual([]);
+  });
+
+  it("ships no worker entry the tsup build would not emit", () => {
+    // A `new Worker(new URL("./x", import.meta.url))` to an unemitted file breaks some
+    // consumer bundlers; off-thread layout is the host's `loadEngine` instead.
+    expect(readdirSync(join(srcDir, "flow-layout"))).not.toContain("elk-worker.ts");
+    expect(readFileSync(join(srcDir, "flow-layout", "layout-flow-elk.ts"), "utf8")).not.toMatch(
+      /new Worker\(new URL\("\.\//,
+    );
+  });
+});