FlowWeave ができるまで — サンキーレイアウトを自前実装する

FlowWeave は、「給与 [38] 手取り」のように一行書くだけでサンキーダイアグラムを描くツールです。ノードの層分け、流量に比例した高さ、線の交差を減らす並べ替え ── レイアウトのエンジンを自前で実装しました。

#🎯 サンキーは「書く手間」で使われなくなる

サンキーダイアグラム(流れの太さで量を表す図)は、収支やコンバージョンの説明に非常に強い図です。でも既存のツールは、ノードとリンクを JSON で定義したり、GUI でドラッグしたりする必要があって面倒でした。

なので入力を一行一リンクに決めました。

給与 [38] 手取り
給与 [7] 税金
給与 [5] 社会保険
手取り [12] 家賃
手取り [8] 食費

これだけで図になります。ノードは自動で作られ、位置も自動で決まります。書くコストが下がれば使われる、という判断です。

#🔗 パースは「ノードを見つけたら登録」

行の解析は素直な正規表現ですが、ノードの管理に一工夫あります。

const indexOf = new Map<string, number>()
const names: string[] = []
const id = (n: string) => {
  if (!indexOf.has(n)) {
    indexOf.set(n, names.length)
    names.push(n)
  }
  return indexOf.get(n)!
}

名前を見た瞬間に番号を振る関数を用意しておくと、ノードの事前定義が不要になります。以降のアルゴリズムは番号(整数)だけで扱えるので、配列でグラフを持てて速くなります。

#🚫 循環を最初に弾く

サンキーは DAG(閉路のない有向グラフ) でないと描けません。A → B → A のような入力が来ると、層分けが無限ループします。

なので先に深さ優先探索で循環を検出します。

const mark = new Array(N).fill(0)   // 0 白 / 1 灰 / 2 黒
// 探索中(灰)のノードに再訪したら 閉路
if (mark[nx] === 1) { cyclic = true; break }

白・灰・黒の三色塗り分けという、閉路検出の定石です。灰は「今たどっている経路の上にいる」状態で、そこへ戻ってきたら循環しています。

再帰ではなく明示的なスタックで書いているのは、ノードが増えたときにスタックオーバーフローさせないためです。

const st: Array<{ node: number; ei: number }> = [{ node: start, ei: 0 }]

各フレームに「どの辺まで見たか」(ei)を持たせることで、再帰の続きを手動で管理しています。

循環を見つけたらエラーとして画面に出します。黙って壊れた図を出すより、何が悪いか言うほうが親切です。

#📐 層(レイヤー)を決める

各ノードが左から何番目に来るかは、「入ってくる辺の元ノードの層 + 1」の最大値で決まります。トポロジカル順に処理すれば一度で決まります。

流入も流出もあるノードは、その最大値に置かれます。こうするとすべての矢印が左から右へ向くようになり、図が読める向きに揃います。

#📏 高さは流量に比例させる

サンキーの本質は「太さ = 量」です。ノードの高さは、そのノードを通る流量の合計(流入と流出の大きいほう)に比例します。

同じ層のノードを縦に積み、間にパディングを入れる。使える高さから パディングの合計を引いた残りを、流量の比で配分します。ここを間違えると、ノードが画面からはみ出るか、上に寄って下が空きます。

#〰️ 交差を減らす

同じ層の中で、ノードをどの順に積むかで線の交差が変わります。完全な最小化は難しい問題なので、ヒューリスティックを使います。

つながっている相手ノードの位置の平均(重心)を計算して、その順に並べ替える。これを層をまたいで数回繰り返すと、交差がかなり減ります。

厳密解を目指さないのがここの判断です。数回まわして「見て分かる程度」になればよく、完全な最小化のために計算時間を使う価値はありませんでした。

#🎀 リボンはベジェ曲線で

リンクは 3 次ベジェで描きます。

export function linkPath(l: SankeyLink, curvature = 0.5): string

始点と終点の中間に制御点を置いて、水平に出て水平に入る形にします。制御点の x を「始点と終点の中間」に取ると、両端が水平になり、サンキーらしい滑らかなリボンになります。曲率をパラメータにして、直線寄りにも強い曲線にもできます。

#😓 苦労したところ

同じ名前のノードが上流と下流に出てくる。 「給与 → 手取り → 貯蓄」で、貯蓄がまた別の何かへ流れるとき、層の計算が意図とずれることがあります。これは循環でなくても起きるので、層決めのルール(入力元の最大 + 1)を明示して、想定と違ったら書き方で調整してもらう形にしました。

エラーメッセージを行番号付きで出す。 一行一リンクなので、書式ミスは「何行目が悪いか」で伝えられます。まとめて「入力が不正です」と出すのは、テキスト入力のツールでは不親切でした。

数値の書式。 38 と 38000 と 3.8 が混ざると、桁で潰れます。単位は書かせず、そのまま比率として扱う割り切りにしました。金額でも人数でも同じ図が描けます。

#🔭 今後の拡張

• ノードの手動並べ替え(交差の自動削減で不満なとき)
• 色をノードごとに指定する記法
• 損失(どこにも流れない差分)の自動検出と表示
• CSV からの取り込み

#💡 このサービスから言えること

入力の書式を決めるところが、このツールの設計のほぼ全部でした。 一行一リンクにしたから、パースが単純になり、エラーを行番号で言えて、コピペで共有できます。JSON や GUI にしていたら、レイアウトのアルゴリズムが同じでも別のツールになっていたはずです。

そしてグラフを扱うなら、閉路検出を最初に入れること。DAG を前提にしたアルゴリズムは、閉路が入ると無限ループか無言の破綻をします。入口で弾いて理由を言うのが一番安全でした。