@elabs-ai/components-flow 4.0.0 → 4.1.0

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

@@ -11,7 +11,7 @@ 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";
+  "rounded-md border border-input bg-surface-elevated px-3 py-1.5 text-body shadow-sm hover:bg-accent focus-ring disabled:opacity-50";
 
 const meta = {
   title: "Flow/FlowGroupNode",

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

@@ -3,6 +3,7 @@ import { Handle, NodeResizer, Position, useNodes, type Node, type NodeProps } fr
 import { ChevronDown, ChevronRight } from "lucide-react";
 import { cn } from "@elabs-ai/components-ui/lib/cn";
 import { useFlowGroups } from "../use-flow-groups";
+import { FLOW_HANDLE_ANCHOR_CLASS } from "../flow-handle/flow-handle-anchor";
 
 /** Visual accent for a group container. */
 export type FlowGroupTone = "default" | "accent" | "success" | "warning" | "destructive";
@@ -29,18 +30,33 @@ export interface FlowGroupNodeData extends Record<string, unknown> {
 
 export type BrandFlowGroupNode = Node<FlowGroupNodeData, "group">;
 
-const toneAccent: Record<FlowGroupTone, string> = {
+// #124 split this map in two: it used to serve both the icon slot (a MARK,
+// >=3:1) and the child-count text badge (running text, >=4.5:1) from one set
+// of values, which is exactly the fill-rung-as-text shape #124 fixes
+// elsewhere. `accent` is unchanged (`#399` already put it on the ink rung for
+// both slots — legal, since the ink rung clears the 3:1 mark bar trivially).
+
+/** Icon-slot tone (the leading glyph next to the title) — the 3:1 mark rung. */
+const toneMark: 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";
+/** Child-count badge tone — running text, so it takes the >=4.5:1 ink rung. */
+const toneInk: Record<FlowGroupTone, string> = {
+  default: "text-muted-foreground",
+  accent: "text-primary-text",
+  success: "text-success-text",
+  warning: "text-warning-text",
+  destructive: "text-destructive-text",
+};
+
+// `FLOW_HANDLE_ANCHOR_CLASS` last: a connector dot must never be in flight when React
+// Flow measures it. See `flow-handle/flow-handle-anchor.ts`.
+const handleClassName = `!size-2 !border-2 !border-flow-group-border !bg-flow-group ${FLOW_HANDLE_ANCHOR_CLASS}`;
 
 /**
  * Branded group container node. Register it as `nodeTypes={{ group: FlowGroupNode }}`
@@ -103,7 +119,7 @@ export function FlowGroupNode({ id, data, selected }: NodeProps<BrandFlowGroupNo
           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",
+            "focus-ring",
           )}
         >
           {collapsed ? (
@@ -114,7 +130,7 @@ export function FlowGroupNode({ id, data, selected }: NodeProps<BrandFlowGroupNo
         </button>
 
         {data.icon ? (
-          <span className={cn("[&_svg]:size-4", toneAccent[tone])}>{data.icon}</span>
+          <span className={cn("[&_svg]:size-4", toneMark[tone])}>{data.icon}</span>
         ) : null}
 
         <span className="min-w-0 flex-1 truncate text-body font-medium">{data.title}</span>
@@ -122,7 +138,7 @@ export function FlowGroupNode({ id, data, selected }: NodeProps<BrandFlowGroupNo
         <span
           className={cn(
             "shrink-0 rounded-full bg-muted px-1.5 py-0.5 text-meta font-medium tabular-nums",
-            toneAccent[tone],
+            toneInk[tone],
           )}
           aria-label={`${childCount} ${childCount === 1 ? "node" : "nodes"}`}
         >

package/src/flow-handle/flow-handle-anchor.test.tsx

@@ -0,0 +1,97 @@
+import { cleanup, render, screen } from "@testing-library/react";
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+/**
+ * The engine is mocked so the handle's CLASS LIST is observable in jsdom, which has no
+ * layout and therefore cannot reproduce the defect itself. The real lock on the picture
+ * is `Process/ProcessMap > Left To Right`, a Chromium story test that measures every
+ * edge endpoint against the dot it should terminate on; this file locks the mechanism
+ * that story exposed — a connector dot that carries no transition, so it is never in
+ * flight when React Flow measures `handleBounds`.
+ */
+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, className }: { type: string; className?: string }) =>
+      React.createElement("div", { "data-testid": `handle-${type}`, className }),
+    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 type { Node, NodeProps } from "@xyflow/react";
+import { FlowGroupNode, type BrandFlowGroupNode } from "../flow-group-node/flow-group-node";
+import { FlowNode, type BrandFlowNode } from "../flow-node/flow-node";
+import {
+  FlowPlaceholderNode,
+  type BrandFlowPlaceholderNode,
+} from "../flow-placeholder-node/flow-placeholder-node";
+import { FLOW_HANDLE_ANCHOR_CLASS } from "./flow-handle-anchor";
+
+afterEach(cleanup);
+
+function makeProps<NodeType extends Node>(id: string, data: NodeType["data"]): NodeProps<NodeType> {
+  return {
+    id,
+    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",
+  } as NodeProps<NodeType>;
+}
+
+describe("FLOW_HANDLE_ANCHOR_CLASS", () => {
+  it("switches transitions off rather than shortening them", () => {
+    // A duration is not enough: the tokens reduced-motion backstop already forces
+    // `transition-duration: 0.01ms !important` on every element, and it is that
+    // one-frame transition — on `transition-property: all` — which the handle has to
+    // be out of. Only `transition-property: none` takes a dot out of it.
+    expect(FLOW_HANDLE_ANCHOR_CLASS).toBe("transition-none");
+  });
+
+  it.each([
+    [
+      "FlowNode",
+      () => render(<FlowNode {...makeProps<BrandFlowNode>("node", { title: "Node" })} />),
+    ],
+    [
+      "FlowGroupNode",
+      () =>
+        render(<FlowGroupNode {...makeProps<BrandFlowGroupNode>("group", { title: "Group" })} />),
+    ],
+    [
+      "FlowPlaceholderNode",
+      () =>
+        render(
+          <FlowPlaceholderNode
+            {...makeProps<BrandFlowPlaceholderNode>("placeholder", { label: "Add node" })}
+          />,
+        ),
+    ],
+  ])("%s renders every handle as a static anchor", (_name, renderNode) => {
+    renderNode();
+    const handles = screen.getAllByTestId(/^handle-/);
+    expect(handles.length).toBeGreaterThan(0);
+    for (const handle of handles) {
+      expect(handle.className.split(/\s+/)).toContain(FLOW_HANDLE_ANCHOR_CLASS);
+    }
+  });
+});

package/src/flow-handle/flow-handle-anchor.ts

@@ -0,0 +1,36 @@
+/**
+ * The class every React Flow `<Handle>` in this package carries — and the one a
+ * consumer's own custom node must carry too.
+ *
+ * A connector dot is a MEASUREMENT ANCHOR, not a moving part. React Flow measures
+ * `handleBounds` from the DOM exactly once per layout change (`updateNodeInternals`,
+ * fired from the effect that sees `sourcePosition`/`targetPosition` change) and then
+ * draws every edge endpoint from that stored number until something invalidates it.
+ * So a dot that is still ON ITS WAY to its new side when that measurement is taken is
+ * measured at the wrong place — permanently, because nothing measures again.
+ *
+ * That is not hypothetical, and it is not only about author-written transitions:
+ *
+ * - `@elabs-ai/components-tokens`' reduced-motion backstop (`themes.css`, MOTION GATE)
+ *   sets `transition-duration: 0.01ms !important` on `*` so third-party engines that
+ *   ignore the `--t-*` tokens (Monaco, `@xyflow/react`, Streamdown) cannot animate.
+ *   `transition-property` is left at its initial value, `all` — so under
+ *   `prefers-reduced-motion: reduce` that rule does not remove a transition from a
+ *   handle, it CREATES one: every geometric property of every element becomes
+ *   transitioned, for one frame.
+ * - One frame is all it takes. Measured on `ProcessMap direction="LR"`: at the commit
+ *   that flips the handles from top/bottom to left/right, the dot's computed box was
+ *   still the OLD one (`getAnimations()` on it returned live `left`+`top`+`transform`
+ *   transitions), React Flow measured `{ x: 164, y: 45.5 }` where the settled DOM has
+ *   `{ x: 172, y: 37.5 }`, and every edge on the map then terminated up to 67 px away
+ *   from the dot it points at — for reduced-motion readers only, forever.
+ *
+ * `transition-property: none` is the fix at the right layer: it costs nothing under
+ * normal motion (no rule animates a handle there anyway) and it makes the reposition
+ * synchronous, so whenever React Flow measures, it measures the settled dot.
+ *
+ * The literal is written out here rather than assembled, because Tailwind extracts
+ * candidates from source TEXT: this file is scanned, so the utility is emitted, and
+ * components may interpolate the constant freely.
+ */
+export const FLOW_HANDLE_ANCHOR_CLASS = "transition-none";

package/src/flow-handle/index.ts

@@ -0,0 +1 @@
+export { FLOW_HANDLE_ANCHOR_CLASS } from "./flow-handle-anchor";

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

@@ -65,7 +65,7 @@ function AutoLayoutButton({ direction }: { direction: FlowLayoutDirection }) {
       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"
+      className="rounded-md border border-input bg-surface-elevated px-3 py-1.5 text-body shadow-sm hover:bg-accent focus-ring disabled:opacity-50"
     >
       Auto layout ({direction === "TB" ? "top → bottom" : "left → right"})
     </button>
@@ -127,7 +127,7 @@ function AutoLayoutGraphButton({ algorithm }: { algorithm: LayoutAlgorithm }) {
       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"
+      className="rounded-md border border-input bg-surface-elevated px-3 py-1.5 text-body shadow-sm hover:bg-accent focus-ring disabled:opacity-50"
     >
       Auto layout ({ALGORITHM_LABEL[algorithm]})
     </button>

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

@@ -130,4 +130,95 @@ describe("layoutFlow", () => {
     const wideGap = wide.nodes[1]!.position.y - wide.nodes[0]!.position.y;
     expect(wideGap).toBeGreaterThan(tightGap);
   });
+  describe("back edges and self-loops (RM-044)", () => {
+    /** The canonical rework fixture: A → B → C, C loops back to B, and B repeats itself. */
+    function reworkGraph(): { nodes: Node[]; edges: Edge[] } {
+      return {
+        nodes: chainNodes(),
+        edges: [
+          { 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" },
+        ],
+      };
+    }
+
+    it("reports the reversed edge in backEdges and the self-loop in selfLoops", () => {
+      const { nodes, edges } = reworkGraph();
+      const result = layoutFlow(nodes, edges);
+
+      expect(result.backEdges).toEqual(["e-cb"]);
+      expect(result.selfLoops).toEqual(["e-bb"]);
+      // Both classifications are disjoint — a self-loop is never a back edge.
+      expect(result.backEdges).not.toContain("e-bb");
+    });
+
+    it("keeps the self-loop out of the rank computation", () => {
+      const { nodes, edges } = reworkGraph();
+      const withLoop = layoutFlow(nodes, edges);
+      const withoutLoop = layoutFlow(
+        nodes,
+        edges.filter((e) => e.id !== "e-bb"),
+      );
+
+      // Identical positions: the loop contributed nothing to the layout.
+      expect(withLoop.nodes.map((n) => n.position)).toEqual(
+        withoutLoop.nodes.map((n) => n.position),
+      );
+    });
+
+    it("returns every edge untouched, self-loops included", () => {
+      const { nodes, edges } = reworkGraph();
+      const result = layoutFlow(nodes, edges);
+      expect(result.edges).toBe(edges);
+      expect(result.edges.map((e) => e.id)).toContain("e-bb");
+    });
+
+    it("produces no NaN position on the rework fixture", () => {
+      const { nodes, edges } = reworkGraph();
+      for (const n of layoutFlow(nodes, edges).nodes) {
+        expect(Number.isFinite(n.position.x)).toBe(true);
+        expect(Number.isFinite(n.position.y)).toBe(true);
+      }
+    });
+
+    it("classifies the same edge as a back edge in every direction", () => {
+      const { nodes, edges } = reworkGraph();
+      for (const direction of ["TB", "BT", "LR", "RL"] as const) {
+        expect(layoutFlow(nodes, edges, { direction }).backEdges).toEqual(["e-cb"]);
+      }
+    });
+
+    it("reports nothing for an acyclic, loop-free graph", () => {
+      const result = layoutFlow(chainNodes(), chainEdges());
+      expect(result.backEdges).toEqual([]);
+      expect(result.selfLoops).toEqual([]);
+    });
+
+    it("counts a same-rank edge as a back edge — it does not advance the process", () => {
+      const nodes: Node[] = [
+        { id: "a", position: { x: 0, y: 0 }, data: {} },
+        { id: "b", position: { x: 0, y: 0 }, data: {} },
+      ];
+      // Two mutually-referencing nodes: dagre has to break the cycle somewhere.
+      const result = layoutFlow(nodes, [
+        { id: "e-ab", source: "a", target: "b" },
+        { id: "e-ba", source: "b", target: "a" },
+      ]);
+      expect(result.backEdges).toEqual(["e-ba"]);
+    });
+
+    it("pins node positions on the rework fixture (regression snapshot)", () => {
+      const { nodes, edges } = reworkGraph();
+      const positions = Object.fromEntries(
+        layoutFlow(nodes, edges).nodes.map((n) => [n.id, n.position]),
+      );
+      expect(positions).toEqual({
+        a: { x: 0, y: 0 },
+        b: { x: 0, y: 112 },
+        c: { x: 0, y: 224 },
+      });
+    });
+  });
 });

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

@@ -2,6 +2,20 @@ import dagre from "@dagrejs/dagre";
 import { Position } from "@xyflow/react";
 import type { Edge, Node } from "@xyflow/react";
 
+/** The graphlib graph `dagre.graphlib.Graph` produces — dagre exports no standalone type for it. */
+type DagreGraph = InstanceType<typeof dagre.graphlib.Graph>;
+
+/**
+ * The fields dagre writes back onto a node label during `layout()`. `rank` is
+ * absent from dagre's own `.d.ts` (it is documented output, not declared
+ * output), so it is narrowed here rather than asserted at the call site.
+ */
+interface DagreNodeLabel {
+  x: number;
+  y: number;
+  rank?: number;
+}
+
 /** Direction dagre lays the graph out in — top-to-bottom, left-to-right, etc. */
 export type FlowLayoutDirection = "TB" | "LR" | "BT" | "RL";
 
@@ -35,6 +49,22 @@ export interface FlowLayoutOptions {
 export interface FlowLayoutResult<NodeType extends Node = Node, EdgeType extends Edge = Edge> {
   nodes: NodeType[];
   edges: EdgeType[];
+  /**
+   * Ids of edges that run **against** the layout direction — a rework / retry
+   * loop in a process graph. dagre breaks cycles by reversing such edges
+   * internally and never surfaces which ones it reversed, so this is derived
+   * from the ranks dagre stamps on the laid-out graph: an edge whose source
+   * ranks at or after its target went backwards. Render these with
+   * `FlowWeightedEdge`'s `variant="back"`.
+   */
+  backEdges: string[];
+  /**
+   * Ids of edges whose `source === target`. dagre does not lay out self-loops,
+   * so they are withheld from the graph entirely (never `setEdge`-ed) and are
+   * returned unchanged in `edges` — they take part in no rank computation and
+   * cannot distort the layout. Render these with `FlowSelfLoopEdge`.
+   */
+  selfLoops: string[];
 }
 
 /** Fallback size used when a node hasn't been measured yet (React Flow's own default node width). */
@@ -58,6 +88,11 @@ function nodeSize(node: Node): { width: number; height: number } {
  * `node.height`, then a sensible default. Node identity and `data` are left
  * untouched — only `position` changes.
  *
+ * Also reports the graph's two structural signals — `backEdges` (edges that run
+ * against the layout direction) and `selfLoops` (`source === target`). Both are
+ * additive fields on the result; a caller that only destructures
+ * `{ nodes, edges }` is unaffected.
+ *
  * Pair with `useFlowLayout` to apply the result to a live canvas.
  */
 export function layoutFlow<NodeType extends Node = Node, EdgeType extends Edge = Edge>(
@@ -76,12 +111,22 @@ export function layoutFlow<NodeType extends Node = Node, EdgeType extends Edge =
     graph.setNode(node.id, { width, height });
   }
 
+  // Self-loops are withheld from dagre entirely: dagre does not lay them out,
+  // and feeding them in only perturbs the ranks of a graph they say nothing
+  // about. They are re-attached untouched in the returned `edges`.
+  const selfLoops: string[] = [];
   for (const edge of edges) {
+    if (edge.source === edge.target) {
+      selfLoops.push(edge.id);
+      continue;
+    }
     graph.setEdge(edge.source, edge.target);
   }
 
   dagre.layout(graph);
 
+  const backEdges = collectBackEdges(graph, edges);
+
   const handles = HANDLE_BY_DIRECTION[direction];
   const layoutedNodes = nodes.map((node) => {
     const dagreNode = graph.node(node.id);
@@ -100,5 +145,36 @@ export function layoutFlow<NodeType extends Node = Node, EdgeType extends Edge =
     };
   });
 
-  return { nodes: layoutedNodes, edges };
+  return { nodes: layoutedNodes, edges, backEdges, selfLoops };
+}
+
+/**
+ * Which edges dagre had to run backwards, derived from the ranks it stamps on
+ * the laid-out graph (`graph.node(id).rank`).
+ *
+ * The obvious alternative — reading `graph.edge(e).reversed` after dagre's
+ * `acyclic.run` — is **not usable on the pinned `@dagrejs/dagre` 3.0.0**:
+ * cycle breaking happens on an internal copy of the graph, and the caller's
+ * graph carries no `reversed` flag once `dagre.layout()` returns (verified
+ * against the installed version — every edge label is bare `{ points }`).
+ * `rank` *is* on the public graph, and is direction-independent: it counts up
+ * along the flow for every `rankdir`, so `rank(source) >= rank(target)` means
+ * "this edge does not advance the process" in TB, BT, LR and RL alike.
+ *
+ * `>=` rather than `>` on purpose: a same-rank edge between two siblings is
+ * not forward progress either, and dagre would have had to reverse or flatten
+ * it. Self-loops never reach here — they are filtered out before layout.
+ * An edge naming a node that isn't in the graph has no ranks to compare and is
+ * left out rather than guessed at.
+ */
+function collectBackEdges(graph: DagreGraph, edges: Edge[]): string[] {
+  const backEdges: string[] = [];
+  for (const edge of edges) {
+    if (edge.source === edge.target) continue;
+    const sourceRank = (graph.node(edge.source) as DagreNodeLabel | undefined)?.rank;
+    const targetRank = (graph.node(edge.target) as DagreNodeLabel | undefined)?.rank;
+    if (typeof sourceRank !== "number" || typeof targetRank !== "number") continue;
+    if (sourceRank >= targetRank) backEdges.push(edge.id);
+  }
+  return backEdges;
 }

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

@@ -36,7 +36,13 @@ function distance(p: { x: number; y: number }, q: { x: number; y: number } = { x
 describe("layoutGraph", () => {
   describe("empty / disconnected input", () => {
     it("returns [] for an empty graph, for every algorithm", () => {
-      for (const algorithm of ["concentric", "force", "layered-lr", "grid"] as const) {
+      for (const algorithm of [
+        "concentric",
+        "force",
+        "layered-lr",
+        "layered-tb",
+        "grid",
+      ] as const) {
         expect(layoutGraph([], [], { algorithm })).toEqual([]);
       }
     });
@@ -45,7 +51,13 @@ describe("layoutGraph", () => {
       const nodes = ["a", "b", "c", "isolated1", "isolated2"].map(node);
       const edges = [edge("a", "b"), edge("b", "c")];
 
-      for (const algorithm of ["concentric", "force", "layered-lr", "grid"] as const) {
+      for (const algorithm of [
+        "concentric",
+        "force",
+        "layered-lr",
+        "layered-tb",
+        "grid",
+      ] as const) {
         const laidOut = layoutGraph(nodes, edges, { algorithm, iterations: 20 });
         for (const n of laidOut) {
           expect(Number.isFinite(n.position.x)).toBe(true);
@@ -254,4 +266,73 @@ describe("layoutGraph", () => {
       expect(first.map((n) => n.position)).toEqual(second.map((n) => n.position));
     });
   });
+  describe("layered-tb", () => {
+    it("delegates to layoutFlow direction=TB, ordering a chain top-to-bottom", () => {
+      const { nodes, edges } = chainGraph();
+      const laidOut = layoutGraph(nodes, edges, { algorithm: "layered-tb" });
+      const [a, b, c] = laidOut as [Node, Node, Node];
+      expect(a.position.y).toBeLessThan(b.position.y);
+      expect(b.position.y).toBeLessThan(c.position.y);
+    });
+
+    it("stamps bottom-out / top-in handle sides (not just position)", () => {
+      const { nodes, edges } = chainGraph();
+      const [a] = layoutGraph(nodes, edges, { algorithm: "layered-tb" }) as [Node];
+      expect(a.sourcePosition).toBe("bottom");
+      expect(a.targetPosition).toBe("top");
+    });
+
+    it("maps spacing.y onto rank spacing (the axis TB ranks along)", () => {
+      const { nodes, edges } = chainGraph();
+      const tight = layoutGraph(nodes, edges, {
+        algorithm: "layered-tb",
+        spacing: { x: 10, y: 10 },
+      });
+      const wide = layoutGraph(nodes, edges, {
+        algorithm: "layered-tb",
+        spacing: { x: 10, y: 500 },
+      });
+      const tightGap = tight[1]!.position.y - tight[0]!.position.y;
+      const wideGap = wide[1]!.position.y - wide[0]!.position.y;
+      expect(wideGap).toBeGreaterThan(tightGap);
+    });
+
+    it("respects a custom nodeSize without permanently resizing the nodes", () => {
+      const nodes: Node[] = [
+        { id: "a", type: "brand", position: { x: 0, y: 0 }, data: {} },
+        { id: "b", type: "brand", position: { x: 0, y: 0 }, data: {} },
+      ];
+      const laidOut = layoutGraph(nodes, [edge("a", "b")], {
+        algorithm: "layered-tb",
+        nodeSize: () => ({ width: 200, height: 400 }),
+      });
+      expect(laidOut[1]!.position.y - laidOut[0]!.position.y).toBeGreaterThanOrEqual(400 + 72 - 1);
+      expect(laidOut[0]).not.toHaveProperty("measured");
+    });
+
+    it("is the same layout as layered-lr with the axes swapped", () => {
+      // A fork exercises BOTH axes: a rank progression and a within-rank stack.
+      // Square nodes + isotropic spacing make the two layouts exact mirrors, so
+      // the assertion is "x and y trade places", not "the numbers look similar".
+      const nodes = ["a", "b", "c"].map(node);
+      const edges = [edge("a", "b"), edge("a", "c")];
+      const options = {
+        spacing: { x: 150, y: 150 },
+        nodeSize: () => ({ width: 100, height: 100 }),
+      };
+      const lr = layoutGraph(nodes, edges, { ...options, algorithm: "layered-lr" });
+      const tb = layoutGraph(nodes, edges, { ...options, algorithm: "layered-tb" });
+
+      expect(tb.map((n) => n.position)).toEqual(
+        lr.map((n) => ({ x: n.position.y, y: n.position.x })),
+      );
+    });
+
+    it("is deterministic", () => {
+      const { nodes, edges } = chainGraph();
+      const first = layoutGraph(nodes, edges, { algorithm: "layered-tb" });
+      const second = layoutGraph(nodes, edges, { algorithm: "layered-tb" });
+      expect(first.map((n) => n.position)).toEqual(second.map((n) => n.position));
+    });
+  });
 });

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

@@ -8,12 +8,12 @@ import {
   type SimulationNodeDatum,
 } from "d3-force";
 import type { Edge, Node } from "@xyflow/react";
-import { HANDLE_BY_DIRECTION, layoutFlow } from "./flow-layout";
+import { HANDLE_BY_DIRECTION, layoutFlow, type FlowLayoutDirection } from "./flow-layout";
 
 /** Which generic graph-geometry algorithm `layoutGraph` should run. */
-export type LayoutAlgorithm = "concentric" | "force" | "layered-lr" | "grid";
+export type LayoutAlgorithm = "concentric" | "force" | "layered-lr" | "layered-tb" | "grid";
 
-/** Horizontal/vertical gap used by the `"grid"` and `"layered-lr"` algorithms. */
+/** Horizontal/vertical gap used by the `"grid"` and `"layered-*"` algorithms. */
 export interface LayoutSpacing {
   x: number;
   y: number;
@@ -31,7 +31,7 @@ export interface LayoutOptions {
   ringRadius?: number;
   /** `"force"` only — number of synchronous simulation ticks to run. @default 300 */
   iterations?: number;
-  /** `"grid"` / `"layered-lr"` — gap between nodes. @default {x:200,y:120} for grid. */
+  /** `"grid"` / `"layered-lr"` / `"layered-tb"` — gap between nodes. @default {x:200,y:120} for grid. */
   spacing?: LayoutSpacing;
   /** Resolve a node's size by id. Falls back to `measured`/`width`/`height`/a sensible default. */
   nodeSize?: (id: string) => { width: number; height: number };
@@ -66,7 +66,10 @@ function resolveNodeSize(
  * Node identity and `data` are left untouched — only `position` changes.
  * Pair with `useAutoLayout` for a memoized hook form.
  *
- * - `"layered-lr"` delegates to the dagre-powered `layoutFlow` (direction `"LR"`).
+ * - `"layered-lr"` / `"layered-tb"` delegate to the dagre-powered `layoutFlow`
+ *   (direction `"LR"` / `"TB"`). `spacing.x` is always the horizontal gap and
+ *   `spacing.y` the vertical one, so the two differ only in which axis carries
+ *   the ranks.
  * - `"concentric"` places `centerId` (or the highest-degree node) at the
  *   origin, with BFS shells at `ring × ringRadius`; disconnected nodes land in
  *   one extra outer ring so positions are never `NaN`.
@@ -83,7 +86,9 @@ export function layoutGraph<NodeType extends Node = Node, EdgeType extends Edge
 
   switch (options.algorithm) {
     case "layered-lr":
-      return layoutLayeredLr(nodes, edges, options);
+      return layoutLayered(nodes, edges, options, "LR");
+    case "layered-tb":
+      return layoutLayered(nodes, edges, options, "TB");
     case "concentric":
       return layoutConcentric(nodes, edges, options);
     case "force":
@@ -97,10 +102,11 @@ export function layoutGraph<NodeType extends Node = Node, EdgeType extends Edge
   }
 }
 
-function layoutLayeredLr<NodeType extends Node, EdgeType extends Edge>(
+function layoutLayered<NodeType extends Node, EdgeType extends Edge>(
   nodes: NodeType[],
   edges: EdgeType[],
   options: LayoutOptions,
+  direction: FlowLayoutDirection,
 ): NodeType[] {
   const { spacing, nodeSize } = options;
 
@@ -114,17 +120,19 @@ function layoutLayeredLr<NodeType extends Node, EdgeType extends Edge>(
       })
     : nodes;
 
+  // Ranks progress along the layout axis and nodes stack across it, so the two
+  // directions map the SAME `spacing.x`/`spacing.y` onto dagre's rank/node sep
+  // with the axes swapped: LR ranks horizontally (x), TB ranks vertically (y).
+  const horizontalRanks = direction === "LR" || direction === "RL";
   const { nodes: laidOut } = layoutFlow(sizedNodes, edges, {
-    direction: "LR",
-    // For an LR flow, ranks progress horizontally (x) and nodes within a rank
-    // stack vertically (y) — map spacing accordingly onto dagre's rank/node sep.
-    nodeSpacing: spacing?.y,
-    rankSpacing: spacing?.x,
+    direction,
+    nodeSpacing: horizontalRanks ? spacing?.y : spacing?.x,
+    rankSpacing: horizontalRanks ? spacing?.x : spacing?.y,
   });
 
-  // Carry the LR handle sides (right-out / left-in) that layoutFlow stamped on,
-  // not just the position — otherwise the layout flips positions but leaves the
-  // anchors on top/bottom.
+  // Carry the handle sides layoutFlow stamped on (LR right-out/left-in, TB
+  // bottom-out/top-in), not just the position — otherwise the layout moves the
+  // nodes but leaves the anchors on the wrong sides.
   return nodes.map((node, i) => ({
     ...node,
     sourcePosition: laidOut[i]!.sourcePosition,