From 759175abad82df23a83e85a089aa3c6df4f83b23 Mon Sep 17 00:00:00 2001 From: Victor Navarro Date: Mon, 5 Oct 2026 13:22:09 +0200 Subject: [PATCH] fix(tui): untangle crossing branches in mermaid flowcharts (#53325) --- .../merman/src/flowchart/flowchart.test.ts | 57 +++++++++++ packages/merman/src/flowchart/layout.ts | 98 +++++++++++++++++++ .../merman/src/test/layout-audit/fixtures.ts | 22 +++++ 3 files changed, 177 insertions(+) diff --git a/packages/merman/src/flowchart/flowchart.test.ts b/packages/merman/src/flowchart/flowchart.test.ts index 3de47135da1..e955d1630e2 100644 --- a/packages/merman/src/flowchart/flowchart.test.ts +++ b/packages/merman/src/flowchart/flowchart.test.ts @@ -875,6 +875,63 @@ describe("FlowchartDiagram", () => { expect(output.match(/[▼◀]/g)).toHaveLength(3) }) + test("orders rank nodes to remove crossings between branches", () => { + const content = `flowchart TD + A{Question} -->|Path one| B[Step one] + A -->|Path two| C[Step two] + B --> D{Check one} + D -->|No| E{Retry one} + E -->|No| B + C --> F{Check two} + F -->|No| G{Retry two} + G -->|No| C + E -->|Yes| H[Rethink] + G -->|Yes| H + H --> A + D -->|Yes| I([Done]) + F -->|Yes| I` + const layout = layoutFlowchartDiagram(content, { compact: true, layoutMaxWidth: 120 }) + const left = (id: string) => layout.bounds.get(id)!.left + + expect(left("E")).toBeLessThan(left("I")) + expect(left("I")).toBeLessThan(left("G")) + expectDiagram(renderFlowchartDiagram(content, { compact: true, layoutMaxWidth: 120 })).toEqualDiagram(` + ╭─────────╮ + ╭─╯ ╰─╮ + │ Question │◀──────────────────────────╮ + ╰─╮ ╭─╯ │ + ╰────┬────╯ │ + ╭─ Path one ──┴── Path two ───╮ │ + │ │ │ + ▼ ▼ │ + ╭──────────╮ ╭──────────╮ │ + ╭──── No ─────▶│ Step one │ │ Step two │◀──── No ────┤ + │ ╰─────┬────╯ ╰─────┬────╯ │ + │ │ │ │ + │ │ ╭─╯ │ + │ ▼ ▼ │ + │ ╭─────────╮ ╭─────────╮ │ + │ ╭─╯ ╰─╮ ╭─╯ ╰─╮ │ + │ │ Check one │ │ Check two │ │ + │ ╰─╮ ╭─╯ ╰─╮ ╭─╯ │ + │ ╰────┬────╯ ╰────┬────╯ │ + │ ╭── No ───┴──── Yes ─────┬─── Yes ────┴─── No ───╮ │ + │ │ │ │ │ + │ ▼ │ ▼ │ + │ ╭─────────╮ ▼ ╭─────────╮ │ + │ ╭─╯ ╰─╮ ╭──────╮ ╭─╯ ╰─╮ │ + ╰───┤ Retry one │ │ Done │ │ Retry two ├──┤ + ╰─╮ ╭─╯ ╰──────╯ ╰─╮ ╭─╯ │ + ╰────┬────╯ ╰────┬────╯ │ + │ │ │ + ╰───────── Yes ─────────┬───────── Yes ──────────╯ │ + ▼ │ + ╭─────────╮ │ + │ Rethink ├─────────────────────────────╯ + ╰─────────╯ + `) + }) + test("routes transitive horizontal shortcuts around intermediate stages", () => { const content = `flowchart LR A[Start] --> B[Validate] diff --git a/packages/merman/src/flowchart/layout.ts b/packages/merman/src/flowchart/layout.ts index ad552ef5eb3..32348c8a1c4 100644 --- a/packages/merman/src/flowchart/layout.ts +++ b/packages/merman/src/flowchart/layout.ts @@ -381,6 +381,7 @@ function layoutRankedNodes( nodes.push(node) ranksByIndex.set(normalizedRank, nodes) } + reduceRankCrossings(diagram, ranks, normalizedRanks, ranksByIndex) const spaciousNodeGap = Math.max(minNodeGap, DEFAULT_MIN_BRANCH_LABEL_GAP) const widestUnlabeledRank = Math.max( @@ -523,6 +524,103 @@ function layoutRankedNodes( return { bounds, wrapped } } +const CROSSING_SWEEPS = 8 + +// Barycenter ordering within ranks. Source order is kept unless a sweep strictly reduces crossings, so +// crossing-free diagrams render exactly as authored. +function reduceRankCrossings( + diagram: FlowchartDiagram, + ranks: ReadonlyMap, + normalizedRanks: ReadonlyMap, + ranksByIndex: Map, +): void { + // Reordering could interleave members of different subgraphs and break their frames. + if (diagram.subgraphs?.length) return + const rankKeys = [...ranksByIndex.keys()].sort((a, b) => a - b) + const layerByRank = new Map(rankKeys.map((rank, index) => [rank, index])) + // Feedback edges route around the diagram, so only forward edges between adjacent ranks can cross. + const links = diagram.edges.flatMap((edge) => { + const fromRank = ranks.get(edge.from) + const toRank = ranks.get(edge.to) + if (edge.orderOnly || fromRank === undefined || toRank === undefined || toRank !== fromRank + 1) return [] + const from = normalizedRanks.get(edge.from)! + const to = normalizedRanks.get(edge.to)! + if (Math.abs(from - to) !== 1) return [] + return [ + from < to + ? { layer: layerByRank.get(from)!, upper: edge.from, lower: edge.to } + : { layer: layerByRank.get(to)!, upper: edge.to, lower: edge.from }, + ] + }) + const original = rankKeys.map((rank) => ranksByIndex.get(rank)!.map((node) => node.id)) + const initialCrossings = layerCrossings(original, links) + if (initialCrossings === 0) return + + const best = Array.from({ length: CROSSING_SWEEPS }).reduce( + (state: { current: string[][]; best: string[][]; crossings: number }, _, sweep) => { + const current = sweepLayers(state.current, links, sweep % 2 === 0) + const crossings = layerCrossings(current, links) + return crossings < state.crossings ? { current, best: current, crossings } : { ...state, current } + }, + { current: original, best: original, crossings: initialCrossings }, + ).best + if (best === original) return + + const nodeById = new Map(diagram.nodes.map((node) => [node.id, node])) + for (const [index, rank] of rankKeys.entries()) { + ranksByIndex.set( + rank, + best[index]!.map((id) => nodeById.get(id)!), + ) + } +} + +function sweepLayers( + layers: readonly string[][], + links: readonly { layer: number; upper: string; lower: string }[], + down: boolean, +): string[][] { + const next = layers.map((layer) => [...layer]) + const indices = next.map((_, index) => index) + for (const index of down ? indices.slice(1) : indices.slice(0, -1).reverse()) { + const fixed = next[down ? index - 1 : index + 1]! + const keys = new Map( + next[index]!.map((id, position) => { + const neighbors = links.flatMap((link) => { + if (down && link.layer === index - 1 && link.lower === id) return [fixed.indexOf(link.upper)] + if (!down && link.layer === index && link.upper === id) return [fixed.indexOf(link.lower)] + return [] + }) + if (neighbors.length === 0) return [id, position] + return [id, neighbors.reduce((total, neighbor) => total + neighbor, 0) / neighbors.length] + }), + ) + next[index] = next[index]!.toSorted((a, b) => keys.get(a)! - keys.get(b)!) + } + return next +} + +function layerCrossings( + layers: readonly string[][], + links: readonly { layer: number; upper: string; lower: string }[], +): number { + const position = new Map(layers.flatMap((layer) => layer.map((id, index) => [id, index] as const))) + return links.reduce( + (total, link, index) => + total + + links + .slice(index + 1) + .filter( + (other) => + other.layer === link.layer && + (position.get(link.upper)! - position.get(other.upper)!) * + (position.get(link.lower)! - position.get(other.lower)!) < + 0, + ).length, + 0, + ) +} + function layoutLocalSubgraphDirections( diagram: FlowchartDiagram, nodeBounds: Map, diff --git a/packages/merman/src/test/layout-audit/fixtures.ts b/packages/merman/src/test/layout-audit/fixtures.ts index d1638415214..3de83a123da 100644 --- a/packages/merman/src/test/layout-audit/fixtures.ts +++ b/packages/merman/src/test/layout-audit/fixtures.ts @@ -153,6 +153,28 @@ const flowFamilies = { ], ) }, + "decision-loops"(direction: FlowchartDirection, profile: LabelProfile) { + return flowSource( + direction, + profile, + ["A", "B", "C", "D", "E", "F", "G", "H", "I"], + [ + ["A", "B", "E01"], + ["A", "C", "E02"], + ["B", "D", "E03"], + ["D", "E", "E04"], + ["E", "B", "E05"], + ["C", "F", "E06"], + ["F", "G", "E07"], + ["G", "C", "E08"], + ["E", "H", "E09"], + ["G", "H", "E10"], + ["H", "A", "E11"], + ["D", "I", "E12"], + ["F", "I", "E13"], + ], + ) + }, parallel(direction: FlowchartDirection, profile: LabelProfile) { return flowSource( direction,