@invana/graph-layout-d3-sankey 0.0.2

package/dist/index.d.ts

@@ -0,0 +1,122 @@
+import { Layout } from '@invana/canvas';
+import { GraphLayer } from '@invana/graph';
+import { SankeyNodeMinimal, SankeyLinkMinimal } from 'd3-sankey';
+
+/**
+ * Column-alignment strategy. Mirrors d3-sankey's `nodeAlign` setters:
+ *
+ * - `'left'` — push every node as far left as possible (depth = longest path
+ *   from a source). Sources column together on the left, sinks float toward
+ *   the right depending on their depth.
+ * - `'right'` — mirror of `'left'`: sinks together on the right, sources
+ *   float toward the left.
+ * - `'center'` — average of left and right; tidy when the graph is roughly
+ *   symmetric.
+ * - `'justify'` (default) — sources on the left, sinks on the right; every
+ *   node is pushed to the latest column it can occupy without rerouting.
+ *   This is the d3 example's default and the one to pick first.
+ */
+type D3SankeyNodeAlign = 'left' | 'right' | 'center' | 'justify';
+/**
+ * Working types used by the layout when handing data to `d3-sankey`. They
+ * mirror the original `GraphNode` / `GraphEdge` ids so we can map the
+ * `d3-sankey` output back onto the store after the run.
+ */
+interface SankeyNodeRef extends SankeyNodeMinimal<SankeyNodeRef, SankeyLinkRef> {
+    id: string;
+}
+interface SankeyLinkRef extends SankeyLinkMinimal<SankeyNodeRef, SankeyLinkRef> {
+    id: string;
+    source: string | SankeyNodeRef;
+    target: string | SankeyNodeRef;
+    value: number;
+}
+/**
+ * `D3SankeyLayout` options.
+ *
+ * Mirrors `d3-sankey`'s configuration surface 1:1. All fields are optional;
+ * defaults follow d3's defaults except `size`, which defaults to
+ * `[1000, 600]` so a fresh layout has somewhere to draw.
+ */
+interface D3SankeyLayoutOptions {
+    /**
+     * Viewport size `[width, height]` the layout fills. Translated to
+     * `d3.sankey().extent([[0, 0], [width, height]])`. Default `[1000, 600]`.
+     */
+    size?: [number, number];
+    /** Column rectangle width in pixels. Default `24` (d3's default). */
+    nodeWidth?: number;
+    /** Vertical padding between nodes within a column. Default `8` (d3's default). */
+    nodePadding?: number;
+    /** Relaxation iterations. More = tighter packing, slower run. Default `6`. */
+    iterations?: number;
+    /** Column-alignment strategy. See {@link D3SankeyNodeAlign}. Default `'justify'`. */
+    nodeAlign?: D3SankeyNodeAlign;
+    /**
+     * Sibling node sort within a column. `null` preserves d3's default
+     * (ascending by incoming flow); `undefined` falls back to the default;
+     * a function sorts explicitly.
+     */
+    nodeSort?: ((a: SankeyNodeRef, b: SankeyNodeRef) => number) | null;
+    /**
+     * Link sort within each node's source-side / target-side stack. `null`
+     * preserves d3's default order; `undefined` falls back to the default.
+     */
+    linkSort?: ((a: SankeyLinkRef, b: SankeyLinkRef) => number) | null;
+    /**
+     * Translate the projected coordinates by `(x, y)` after layout. Default
+     * `{ x: 0, y: 0 }`. Useful for centring the diagram around the world
+     * origin so a fresh `fitContent` frames it naturally.
+     */
+    center?: {
+        x?: number;
+        y?: number;
+    };
+}
+
+/**
+ * `D3SankeyLayout` — `Layout` for `@invana/graph` that wraps `d3-sankey`.
+ *
+ * Treats the graph as a DAG of flows: edges carry a numeric `value` (read
+ * from `edge.data.value`), `d3-sankey` arranges nodes into columns and
+ * solves for vertical positions that minimise link crossings.
+ *
+ * One-shot synchronous: `apply()` snapshots the store, runs the sankey
+ * solver once, bulk-writes positions plus per-edge anchor opts, emits
+ * `start` → `tick` → `end`, and resolves. No tick loop.
+ *
+ * The layout writes:
+ *  - per node: position (centre of the d3-sankey rect), and into `data`:
+ *    `shape: 'rect'`, `size: rectWidth`, `height: rectHeight`.
+ *  - per edge: into `data`: `strokeWidth: link.width`,
+ *    `pathType: 'bump-horizontal'`, plus per-endpoint anchor opts
+ *    (`sourceAnchor: 'edge-port'` with `{ side: 'right', offset }`,
+ *    `targetAnchor: 'edge-port'` with `{ side: 'left', offset }`) so the
+ *    ribbons attach at the correct y on each rect face.
+ *
+ * Pair with `edge: { style: { shape: { pathType: 'bump-horizontal' }, strokeAlpha: 0.5, arrowTargetShape: 'none' } }`
+ * on the `GraphLayer` to reproduce d3-sankey's SVG appearance.
+ *
+ * @example
+ * const layout = new D3SankeyLayout({ size: [1200, 720], nodeWidth: 15, nodePadding: 10 });
+ * await layout.apply(graphLayer);
+ */
+
+declare class D3SankeyLayout extends Layout<GraphLayer> {
+    private readonly opts;
+    /** True while a run is active. Guards `stop()` so `end` only fires once. */
+    private running;
+    constructor(opts?: D3SankeyLayoutOptions);
+    /**
+     * Run the layout against `layer`. Resolves once positions and per-edge
+     * hints have been written. Lifecycle events fire in order:
+     * `start` → `tick` (once) → `end`.
+     */
+    apply(layer: GraphLayer): Promise<void>;
+    /** Cancel a run. The synchronous body of `apply()` rarely yields long
+     *  enough for this to fire, but it keeps the contract symmetric with
+     *  iterative layouts. */
+    stop(): void;
+}
+
+export { D3SankeyLayout, type D3SankeyLayoutOptions, type D3SankeyNodeAlign };

package/dist/index.js

@@ -0,0 +1,145 @@
+import { sankey, sankeyJustify, sankeyCenter, sankeyRight, sankeyLeft } from 'd3-sankey';
+import { Layout } from '@invana/canvas';
+
+// src/D3SankeyLayout.ts
+var DEFAULT_SIZE = [1e3, 600];
+var NODE_ALIGN_FNS = {
+  left: sankeyLeft,
+  right: sankeyRight,
+  center: sankeyCenter,
+  justify: sankeyJustify
+};
+function pickAlign(name) {
+  return NODE_ALIGN_FNS[name ?? "justify"];
+}
+var D3SankeyLayout = class extends Layout {
+  opts;
+  /** True while a run is active. Guards `stop()` so `end` only fires once. */
+  running = false;
+  constructor(opts = {}) {
+    super();
+    this.opts = opts;
+  }
+  /**
+   * Run the layout against `layer`. Resolves once positions and per-edge
+   * hints have been written. Lifecycle events fire in order:
+   * `start` → `tick` (once) → `end`.
+   */
+  async apply(layer) {
+    this.stop();
+    const store = layer.store;
+    const ids = [];
+    const nodes = [];
+    for (const n of store.nodes()) {
+      ids.push(n.id);
+      nodes.push({ id: n.id });
+    }
+    if (ids.length === 0) return;
+    const links = [];
+    for (const e of store.edges()) {
+      const data = e.data;
+      const value = data && typeof data.value === "number" ? data.value : void 0;
+      if (value === void 0 || !Number.isFinite(value) || value <= 0) {
+        throw new Error(
+          `D3SankeyLayout: edge "${e.id}" is missing a positive numeric \`data.value\` \u2014 sankey needs per-link weights.`
+        );
+      }
+      links.push({
+        id: e.id,
+        source: e.source,
+        target: e.target,
+        value
+      });
+    }
+    const [w, h] = this.opts.size ?? DEFAULT_SIZE;
+    const sankey$1 = sankey().nodeId((d) => d.id).nodeAlign(pickAlign(this.opts.nodeAlign)).nodeWidth(this.opts.nodeWidth ?? 24).nodePadding(this.opts.nodePadding ?? 8).extent([
+      [0, 0],
+      [w, h]
+    ]);
+    if (this.opts.iterations !== void 0) sankey$1.iterations(this.opts.iterations);
+    if (this.opts.nodeSort !== void 0) sankey$1.nodeSort(this.opts.nodeSort);
+    if (this.opts.linkSort !== void 0) sankey$1.linkSort(this.opts.linkSort);
+    sankey$1({ nodes, links });
+    const cx = (this.opts.center?.x ?? 0) - w / 2;
+    const cy = (this.opts.center?.y ?? 0) - h / 2;
+    const buffer = new Float32Array(ids.length * 2);
+    const sizes = /* @__PURE__ */ new Map();
+    for (let i = 0; i < nodes.length; i++) {
+      const node = nodes[i];
+      const x0 = node.x0 ?? 0;
+      const x1 = node.x1 ?? 0;
+      const y0 = node.y0 ?? 0;
+      const y1 = node.y1 ?? 0;
+      const width = x1 - x0;
+      const height = y1 - y0;
+      const centreX = (x0 + x1) / 2 + cx;
+      const centreY = (y0 + y1) / 2 + cy;
+      buffer[i * 2] = centreX;
+      buffer[i * 2 + 1] = centreY;
+      sizes.set(node.id, { width, height, cx: centreX, cy: centreY });
+    }
+    this.running = true;
+    this.events.emit("start", {});
+    store.batch(() => {
+      store.setPositionsBulk(ids, buffer);
+      for (const id of ids) {
+        const size = sizes.get(id);
+        if (!size) continue;
+        const existing = store.getNode(id);
+        if (!existing) continue;
+        const existingStyle = existing.style && typeof existing.style === "object" ? existing.style : {};
+        store.updateNode(id, {
+          style: {
+            ...existingStyle,
+            shape: { kind: "rect", width: size.width, height: size.height }
+          }
+        });
+      }
+      for (const link of links) {
+        const srcId = typeof link.source === "string" ? link.source : link.source.id;
+        const tgtId = typeof link.target === "string" ? link.target : link.target.id;
+        const src = sizes.get(srcId);
+        const tgt = sizes.get(tgtId);
+        if (!src || !tgt) continue;
+        const linkWidth = link.width ?? 1;
+        const linkY0 = (link.y0 ?? 0) + cy;
+        const linkY1 = (link.y1 ?? 0) + cy;
+        const sourceOffset = linkY0 - src.cy;
+        const targetOffset = linkY1 - tgt.cy;
+        const existing = store.getEdge(link.id);
+        if (!existing) continue;
+        const existingStyle = existing.style && typeof existing.style === "object" ? existing.style : {};
+        store.updateEdge(link.id, {
+          style: {
+            ...existingStyle,
+            shape: {
+              pathType: "bump-horizontal",
+              sourceAnchor: "edge-port",
+              sourceAnchorOpts: { side: "right", offset: sourceOffset },
+              targetAnchor: "edge-port",
+              targetAnchorOpts: { side: "left", offset: targetOffset }
+            },
+            strokeWidth: Math.max(1, linkWidth)
+          }
+        });
+      }
+    });
+    this.events.emit("tick", {});
+    if (this.running) {
+      this.running = false;
+      this.events.emit("end", { reason: "completed" });
+    }
+  }
+  /** Cancel a run. The synchronous body of `apply()` rarely yields long
+   *  enough for this to fire, but it keeps the contract symmetric with
+   *  iterative layouts. */
+  stop() {
+    if (!this.running) return;
+    this.running = false;
+    this.events.emit("end", { reason: "stopped" });
+  }
+};
+
+export { D3SankeyLayout };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/D3SankeyLayout.ts"],"names":["sankey","d3sankey"],"mappings":"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","file":"index.js","sourcesContent":["/**\n * `D3SankeyLayout` — `Layout` for `@invana/graph` that wraps `d3-sankey`.\n *\n * Treats the graph as a DAG of flows: edges carry a numeric `value` (read\n * from `edge.data.value`), `d3-sankey` arranges nodes into columns and\n * solves for vertical positions that minimise link crossings.\n *\n * One-shot synchronous: `apply()` snapshots the store, runs the sankey\n * solver once, bulk-writes positions plus per-edge anchor opts, emits\n * `start` → `tick` → `end`, and resolves. No tick loop.\n *\n * The layout writes:\n *  - per node: position (centre of the d3-sankey rect), and into `data`:\n *    `shape: 'rect'`, `size: rectWidth`, `height: rectHeight`.\n *  - per edge: into `data`: `strokeWidth: link.width`,\n *    `pathType: 'bump-horizontal'`, plus per-endpoint anchor opts\n *    (`sourceAnchor: 'edge-port'` with `{ side: 'right', offset }`,\n *    `targetAnchor: 'edge-port'` with `{ side: 'left', offset }`) so the\n *    ribbons attach at the correct y on each rect face.\n *\n * Pair with `edge: { style: { shape: { pathType: 'bump-horizontal' }, strokeAlpha: 0.5, arrowTargetShape: 'none' } }`\n * on the `GraphLayer` to reproduce d3-sankey's SVG appearance.\n *\n * @example\n * const layout = new D3SankeyLayout({ size: [1200, 720], nodeWidth: 15, nodePadding: 10 });\n * await layout.apply(graphLayer);\n */\n\nimport {\n  sankey as d3sankey,\n  sankeyCenter,\n  sankeyJustify,\n  sankeyLeft,\n  sankeyRight,\n} from 'd3-sankey';\n\nimport { Layout } from '@invana/canvas';\nimport type { GraphLayer } from '@invana/graph';\n\nimport type {\n  D3SankeyLayoutOptions,\n  D3SankeyNodeAlign,\n  SankeyLinkRef,\n  SankeyNodeRef,\n} from './types';\n\nconst DEFAULT_SIZE: [number, number] = [1000, 600];\n\nconst NODE_ALIGN_FNS = {\n  left: sankeyLeft,\n  right: sankeyRight,\n  center: sankeyCenter,\n  justify: sankeyJustify,\n} as const;\n\nfunction pickAlign(name: D3SankeyNodeAlign | undefined): (typeof NODE_ALIGN_FNS)[keyof typeof NODE_ALIGN_FNS] {\n  return NODE_ALIGN_FNS[name ?? 'justify'];\n}\n\nexport class D3SankeyLayout extends Layout<GraphLayer> {\n  private readonly opts: D3SankeyLayoutOptions;\n  /** True while a run is active. Guards `stop()` so `end` only fires once. */\n  private running = false;\n\n  constructor(opts: D3SankeyLayoutOptions = {}) {\n    super();\n    this.opts = opts;\n  }\n\n  /**\n   * Run the layout against `layer`. Resolves once positions and per-edge\n   * hints have been written. Lifecycle events fire in order:\n   * `start` → `tick` (once) → `end`.\n   */\n  async apply(layer: GraphLayer): Promise<void> {\n    this.stop();\n    const store = layer.store;\n\n    // 1. Snapshot store → d3-sankey inputs. Sankey expects nodes with an\n    //    arbitrary opaque id and links with `{source, target, value}` —\n    //    string ids work directly via `nodeId`.\n    const ids: string[] = [];\n    const nodes: SankeyNodeRef[] = [];\n    for (const n of store.nodes()) {\n      ids.push(n.id);\n      nodes.push({ id: n.id });\n    }\n    if (ids.length === 0) return;\n\n    const links: SankeyLinkRef[] = [];\n    for (const e of store.edges()) {\n      const data = e.data as { value?: unknown } | undefined;\n      const value = data && typeof data.value === 'number' ? data.value : undefined;\n      if (value === undefined || !Number.isFinite(value) || value <= 0) {\n        throw new Error(\n          `D3SankeyLayout: edge \"${e.id}\" is missing a positive numeric \\`data.value\\` — sankey needs per-link weights.`,\n        );\n      }\n      links.push({\n        id: e.id,\n        source: e.source,\n        target: e.target,\n        value,\n      });\n    }\n\n    // 2. Configure and run d3-sankey.\n    const [w, h] = this.opts.size ?? DEFAULT_SIZE;\n    const sankey = d3sankey<SankeyNodeRef, SankeyLinkRef>()\n      .nodeId((d) => d.id)\n      .nodeAlign(pickAlign(this.opts.nodeAlign))\n      .nodeWidth(this.opts.nodeWidth ?? 24)\n      .nodePadding(this.opts.nodePadding ?? 8)\n      .extent([\n        [0, 0],\n        [w, h],\n      ]);\n    if (this.opts.iterations !== undefined) sankey.iterations(this.opts.iterations);\n    if (this.opts.nodeSort !== undefined) sankey.nodeSort(this.opts.nodeSort);\n    if (this.opts.linkSort !== undefined) sankey.linkSort(this.opts.linkSort);\n\n    sankey({ nodes, links });\n\n    // 3. Project results back onto the store. Centre the diagram around the\n    //    world origin so `fitContent` frames it naturally without the caller\n    //    knowing the layout viewport.\n    const cx = (this.opts.center?.x ?? 0) - w / 2;\n    const cy = (this.opts.center?.y ?? 0) - h / 2;\n    const buffer = new Float32Array(ids.length * 2);\n    const sizes = new Map<string, { width: number; height: number; cx: number; cy: number }>();\n    for (let i = 0; i < nodes.length; i++) {\n      const node = nodes[i]!;\n      const x0 = node.x0 ?? 0;\n      const x1 = node.x1 ?? 0;\n      const y0 = node.y0 ?? 0;\n      const y1 = node.y1 ?? 0;\n      const width = x1 - x0;\n      const height = y1 - y0;\n      const centreX = (x0 + x1) / 2 + cx;\n      const centreY = (y0 + y1) / 2 + cy;\n      buffer[i * 2] = centreX;\n      buffer[i * 2 + 1] = centreY;\n      sizes.set(node.id, { width, height, cx: centreX, cy: centreY });\n    }\n\n    // 4. Mark running, fire start, write positions + per-node + per-edge\n    //    hints in one batch so subscribers see a single coalesced flush.\n    this.running = true;\n    this.events.emit('start', {});\n\n    store.batch(() => {\n      store.setPositionsBulk(ids, buffer);\n\n      // Per-node geometry — write the discriminated `style.shape` as a rect\n      // with the d3-sankey-solved `{ width, height }`. Merge over existing\n      // `style` so caller-provided colour / label fields survive.\n      for (const id of ids) {\n        const size = sizes.get(id);\n        if (!size) continue;\n        const existing = store.getNode(id);\n        if (!existing) continue;\n        const existingStyle =\n          existing.style && typeof existing.style === 'object'\n            ? (existing.style as Record<string, unknown>)\n            : {};\n        store.updateNode(id, {\n          style: {\n            ...existingStyle,\n            shape: { kind: 'rect', width: size.width, height: size.height },\n          },\n        });\n      }\n\n      // Per-edge geometry — stroke thickness ∝ flow value (d3-sankey sets\n      // `link.width` from the solver), plus per-endpoint anchor opts\n      // pointing at the right `edge-port`.\n      //\n      // `link.y0` is the absolute world-y of the link's centre at the\n      // source's right face; `sourceCentreY` is the rect's centre y. The\n      // `edge-port` anchor receives the delta as its `offset`.\n      for (const link of links) {\n        const srcId = typeof link.source === 'string' ? link.source : link.source.id;\n        const tgtId = typeof link.target === 'string' ? link.target : link.target.id;\n        const src = sizes.get(srcId);\n        const tgt = sizes.get(tgtId);\n        if (!src || !tgt) continue;\n        const linkWidth = link.width ?? 1;\n        const linkY0 = (link.y0 ?? 0) + cy;\n        const linkY1 = (link.y1 ?? 0) + cy;\n        const sourceOffset = linkY0 - src.cy;\n        const targetOffset = linkY1 - tgt.cy;\n\n        const existing = store.getEdge(link.id);\n        if (!existing) continue;\n        const existingStyle =\n          existing.style && typeof existing.style === 'object'\n            ? (existing.style as Record<string, unknown>)\n            : {};\n        store.updateEdge(link.id, {\n          style: {\n            ...existingStyle,\n            shape: {\n              pathType: 'bump-horizontal',\n              sourceAnchor: 'edge-port',\n              sourceAnchorOpts: { side: 'right', offset: sourceOffset },\n              targetAnchor: 'edge-port',\n              targetAnchorOpts: { side: 'left', offset: targetOffset },\n            },\n            strokeWidth: Math.max(1, linkWidth),\n          },\n        });\n      }\n    });\n\n    this.events.emit('tick', {});\n\n    if (this.running) {\n      this.running = false;\n      this.events.emit('end', { reason: 'completed' });\n    }\n  }\n\n  /** Cancel a run. The synchronous body of `apply()` rarely yields long\n   *  enough for this to fire, but it keeps the contract symmetric with\n   *  iterative layouts. */\n  stop(): void {\n    if (!this.running) return;\n    this.running = false;\n    this.events.emit('end', { reason: 'stopped' });\n  }\n}\n"]}

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "@invana/graph-layout-d3-sankey",
+  "version": "0.0.2",
+  "description": "D3 Sankey Layout for @invana/graph.",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "typedocOptions": {
+    "entryPoints": [
+      "src/index.ts"
+    ]
+  },
+  "dependencies": {
+    "d3-sankey": "^0.12.3"
+  },
+  "peerDependencies": {
+    "@invana/graph": "0.0.2",
+    "@invana/canvas": "0.0.2"
+  },
+  "devDependencies": {
+    "@types/d3-sankey": "^0.12.4",
+    "tsup": "^8.3.5",
+    "typescript": "5.9.2",
+    "vitest": "^2.1.8",
+    "@invana/canvas": "0.0.2",
+    "@invana/graph": "0.0.2",
+    "@repo/typescript-config": "0.0.0"
+  },
+  "keywords": [
+    "canvas",
+    "graph",
+    "layout",
+    "d3",
+    "d3-sankey",
+    "sankey",
+    "flow"
+  ],
+  "license": "Apache-2.0",
+  "module": "./dist/index.js",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "lint": "eslint src/",
+    "check-types": "tsc --noEmit",
+    "clean": "rm -rf dist",
+    "test": "vitest run"
+  }
+}