@carlonicora/nextjs-jsonapi 1.98.0 → 1.100.0

package/src/hooks/__tests__/computeLayeredLayout.spec.ts

@@ -0,0 +1,286 @@
+import { describe, expect, it } from "vitest";
+import { computeLayeredLayout, fitLayeredLayoutToAspectRatio } from "../computeLayeredLayout";
+import type { D3Link, D3Node } from "../../interfaces";
+
+function makeNode(id: string, name = id, extra: Partial<D3Node> = {}): D3Node {
+  return { id, name, instanceType: "test", ...extra };
+}
+
+function makeLink(source: string, target: string): D3Link {
+  return { source, target } as D3Link;
+}
+
+const MIN_WIDTH = 80;
+const MIN_HEIGHT = 80;
+
+describe("computeLayeredLayout", () => {
+  it("returns an empty map for an empty graph", () => {
+    const result = computeLayeredLayout([], [], {
+      minNodeWidth: MIN_WIDTH,
+      minNodeHeight: MIN_HEIGHT,
+    });
+    expect(result).not.toBeNull();
+    expect(result!.size).toBe(0);
+  });
+
+  it("places a single isolated node at a finite coordinate", () => {
+    const nodes = [makeNode("a")];
+    const result = computeLayeredLayout(nodes, [], {
+      minNodeWidth: MIN_WIDTH,
+      minNodeHeight: MIN_HEIGHT,
+    });
+    expect(result).not.toBeNull();
+    const pos = result!.get("a");
+    expect(pos).toBeDefined();
+    expect(Number.isFinite(pos!.x)).toBe(true);
+    expect(Number.isFinite(pos!.y)).toBe(true);
+  });
+
+  it("orders a linear chain left-to-right when rankdir=LR", () => {
+    const nodes = [makeNode("a"), makeNode("b"), makeNode("c")];
+    const links = [makeLink("a", "b"), makeLink("b", "c")];
+    const result = computeLayeredLayout(nodes, links, {
+      rankdir: "LR",
+      minNodeWidth: MIN_WIDTH,
+      minNodeHeight: MIN_HEIGHT,
+    });
+    expect(result).not.toBeNull();
+    const a = result!.get("a")!;
+    const b = result!.get("b")!;
+    const c = result!.get("c")!;
+    expect(a.x).toBeLessThan(b.x);
+    expect(b.x).toBeLessThan(c.x);
+  });
+
+  it("orders a linear chain top-to-bottom when rankdir=TB", () => {
+    const nodes = [makeNode("a"), makeNode("b"), makeNode("c")];
+    const links = [makeLink("a", "b"), makeLink("b", "c")];
+    const result = computeLayeredLayout(nodes, links, {
+      rankdir: "TB",
+      minNodeWidth: MIN_WIDTH,
+      minNodeHeight: MIN_HEIGHT,
+    });
+    expect(result).not.toBeNull();
+    const a = result!.get("a")!;
+    const b = result!.get("b")!;
+    const c = result!.get("c")!;
+    expect(a.y).toBeLessThan(b.y);
+    expect(b.y).toBeLessThan(c.y);
+  });
+
+  it("places siblings on the same rank but separated", () => {
+    const nodes = [makeNode("a"), makeNode("b"), makeNode("c")];
+    const links = [makeLink("a", "b"), makeLink("a", "c")];
+    const result = computeLayeredLayout(nodes, links, {
+      rankdir: "LR",
+      nodesep: 50,
+      minNodeWidth: MIN_WIDTH,
+      minNodeHeight: MIN_HEIGHT,
+    });
+    expect(result).not.toBeNull();
+    const a = result!.get("a")!;
+    const b = result!.get("b")!;
+    const c = result!.get("c")!;
+    expect(b.x).toBeGreaterThan(a.x);
+    expect(c.x).toBeGreaterThan(a.x);
+    expect(Math.abs(b.x - c.x)).toBeLessThan(5);
+    expect(Math.abs(b.y - c.y)).toBeGreaterThanOrEqual(50);
+  });
+
+  it("uses label width to widen ranks for long names", () => {
+    const nodes = [makeNode("a", "x"), makeNode("b", "x".repeat(50))];
+    const links = [makeLink("a", "b")];
+    const narrow = computeLayeredLayout(nodes, links, {
+      rankdir: "LR",
+      minNodeWidth: MIN_WIDTH,
+      minNodeHeight: MIN_HEIGHT,
+    });
+    const wider = computeLayeredLayout(
+      [makeNode("a", "x".repeat(50)), makeNode("b", "x".repeat(50))],
+      [makeLink("a", "b")],
+      {
+        rankdir: "LR",
+        minNodeWidth: MIN_WIDTH,
+        minNodeHeight: MIN_HEIGHT,
+      },
+    );
+    const narrowGap = narrow!.get("b")!.x - narrow!.get("a")!.x;
+    const widerGap = wider!.get("b")!.x - wider!.get("a")!.x;
+    expect(widerGap).toBeGreaterThan(narrowGap);
+  });
+
+  it("handles a scene-shaped graph (scene chain + location branches)", () => {
+    const nodes = [
+      makeNode("s1", "Scene 1", { instanceType: "scenes" }),
+      makeNode("s2", "Scene 2", { instanceType: "scenes" }),
+      makeNode("s3", "Scene 3", { instanceType: "scenes" }),
+      makeNode("loc1", "Loc 1", { instanceType: "locations" }),
+      makeNode("loc2", "Loc 2", { instanceType: "locations" }),
+      makeNode("loc3", "Loc 3", { instanceType: "locations" }),
+    ];
+    const links = [
+      makeLink("s1", "s2"),
+      makeLink("s2", "s3"),
+      makeLink("s1", "loc1"),
+      makeLink("s2", "loc2"),
+      makeLink("s3", "loc3"),
+    ];
+    const result = computeLayeredLayout(nodes, links, {
+      rankdir: "LR",
+      minNodeWidth: MIN_WIDTH,
+      minNodeHeight: MIN_HEIGHT,
+    });
+    expect(result).not.toBeNull();
+    expect(result!.size).toBe(6);
+    expect(result!.get("s1")!.x).toBeLessThan(result!.get("s2")!.x);
+    expect(result!.get("s2")!.x).toBeLessThan(result!.get("s3")!.x);
+    expect(result!.get("loc1")!.x).toBeGreaterThan(result!.get("s1")!.x);
+    expect(result!.get("loc2")!.x).toBeGreaterThan(result!.get("s2")!.x);
+    expect(result!.get("loc3")!.x).toBeGreaterThan(result!.get("s3")!.x);
+  });
+
+  it("ignores links to/from unknown nodes", () => {
+    const nodes = [makeNode("a"), makeNode("b")];
+    const links = [makeLink("a", "b"), makeLink("a", "ghost"), makeLink("ghost", "b")];
+    const result = computeLayeredLayout(nodes, links, {
+      minNodeWidth: MIN_WIDTH,
+      minNodeHeight: MIN_HEIGHT,
+    });
+    expect(result).not.toBeNull();
+    expect(result!.size).toBe(2);
+  });
+});
+
+function boundingBoxAspect(positions: Map<string, { x: number; y: number }>): number {
+  if (positions.size <= 1) return NaN;
+  let xMin = Infinity;
+  let xMax = -Infinity;
+  let yMin = Infinity;
+  let yMax = -Infinity;
+  positions.forEach((p) => {
+    xMin = Math.min(xMin, p.x);
+    xMax = Math.max(xMax, p.x);
+    yMin = Math.min(yMin, p.y);
+    yMax = Math.max(yMax, p.y);
+  });
+  const w = xMax - xMin;
+  const h = yMax - yMin;
+  if (h === 0) return Infinity;
+  return w / h;
+}
+
+describe("fitLayeredLayoutToAspectRatio", () => {
+  it("returns an empty map for an empty graph", () => {
+    const result = fitLayeredLayoutToAspectRatio([], [], {
+      minNodeWidth: MIN_WIDTH,
+      minNodeHeight: MIN_HEIGHT,
+      targetAspectRatio: 1.5,
+    });
+    expect(result).not.toBeNull();
+    expect(result!.size).toBe(0);
+  });
+
+  it("returns a single node at finite coords without crashing", () => {
+    const result = fitLayeredLayoutToAspectRatio([makeNode("a")], [], {
+      minNodeWidth: MIN_WIDTH,
+      minNodeHeight: MIN_HEIGHT,
+      targetAspectRatio: 1.5,
+    });
+    expect(result).not.toBeNull();
+    const pos = result!.get("a")!;
+    expect(Number.isFinite(pos.x)).toBe(true);
+    expect(Number.isFinite(pos.y)).toBe(true);
+  });
+
+  it("nudges aspect ratio toward a wider target than single-pass", () => {
+    // A branchy DAG with vertical structure under TB: a -> b1,b2,b3,b4,b5
+    // Single-pass TB makes this tall (5 siblings stacked vertically below a).
+    const nodes = [makeNode("a"), makeNode("b1"), makeNode("b2"), makeNode("b3"), makeNode("b4"), makeNode("b5")];
+    const links = [
+      makeLink("a", "b1"),
+      makeLink("a", "b2"),
+      makeLink("a", "b3"),
+      makeLink("a", "b4"),
+      makeLink("a", "b5"),
+    ];
+    const baseline = computeLayeredLayout(nodes, links, {
+      rankdir: "TB",
+      minNodeWidth: MIN_WIDTH,
+      minNodeHeight: MIN_HEIGHT,
+    });
+    const fitted = fitLayeredLayoutToAspectRatio(nodes, links, {
+      rankdir: "TB",
+      minNodeWidth: MIN_WIDTH,
+      minNodeHeight: MIN_HEIGHT,
+      targetAspectRatio: 4.0,
+    });
+    expect(baseline).not.toBeNull();
+    expect(fitted).not.toBeNull();
+    const baseAspect = boundingBoxAspect(baseline!);
+    const fitAspect = boundingBoxAspect(fitted!);
+    expect(Math.abs(fitAspect - 4.0)).toBeLessThan(Math.abs(baseAspect - 4.0));
+  });
+
+  it("nudges aspect ratio toward a narrower target than single-pass", () => {
+    // A wide LR chain (single rank deep, multi-rank wide); single-pass is
+    // very wide. Target 0.5 (taller than wide) should reduce ranksep and
+    // increase nodesep — though with no siblings the height grows slowly.
+    // We use a graph with one branching point to give the fitter vertical
+    // structure to expand into.
+    const nodes = [makeNode("a"), makeNode("b"), makeNode("c"), makeNode("d"), makeNode("e")];
+    const links = [makeLink("a", "b"), makeLink("a", "c"), makeLink("b", "d"), makeLink("c", "e")];
+    const baseline = computeLayeredLayout(nodes, links, {
+      rankdir: "LR",
+      minNodeWidth: MIN_WIDTH,
+      minNodeHeight: MIN_HEIGHT,
+    });
+    const fitted = fitLayeredLayoutToAspectRatio(nodes, links, {
+      rankdir: "LR",
+      minNodeWidth: MIN_WIDTH,
+      minNodeHeight: MIN_HEIGHT,
+      targetAspectRatio: 0.6,
+    });
+    expect(baseline).not.toBeNull();
+    expect(fitted).not.toBeNull();
+    const baseAspect = boundingBoxAspect(baseline!);
+    const fitAspect = boundingBoxAspect(fitted!);
+    expect(Math.abs(fitAspect - 0.6)).toBeLessThan(Math.abs(baseAspect - 0.6));
+  });
+
+  it("skips fitting for single-rank graphs (zero height in LR)", () => {
+    // Linear LR chain: all nodes on the same y (single rank tall),
+    // bbox height collapses to 0 — fitter should return positions
+    // unchanged from single-pass.
+    const nodes = [makeNode("a"), makeNode("b"), makeNode("c")];
+    const links = [makeLink("a", "b"), makeLink("b", "c")];
+    const fitted = fitLayeredLayoutToAspectRatio(nodes, links, {
+      rankdir: "LR",
+      minNodeWidth: MIN_WIDTH,
+      minNodeHeight: MIN_HEIGHT,
+      targetAspectRatio: 0.5,
+    });
+    expect(fitted).not.toBeNull();
+    expect(fitted!.size).toBe(3);
+  });
+
+  it("treats invalid targetAspectRatio (zero or NaN) as a no-op fit", () => {
+    const nodes = [makeNode("a"), makeNode("b")];
+    const links = [makeLink("a", "b")];
+    const zero = fitLayeredLayoutToAspectRatio(nodes, links, {
+      rankdir: "LR",
+      minNodeWidth: MIN_WIDTH,
+      minNodeHeight: MIN_HEIGHT,
+      targetAspectRatio: 0,
+    });
+    const nan = fitLayeredLayoutToAspectRatio(nodes, links, {
+      rankdir: "LR",
+      minNodeWidth: MIN_WIDTH,
+      minNodeHeight: MIN_HEIGHT,
+      targetAspectRatio: NaN,
+    });
+    expect(zero).not.toBeNull();
+    expect(zero!.size).toBe(2);
+    expect(nan).not.toBeNull();
+    expect(nan!.size).toBe(2);
+  });
+});

package/src/hooks/computeLayeredLayout.ts

@@ -0,0 +1,209 @@
+import * as dagre from "dagre";
+import { D3Link, D3Node } from "../interfaces";
+
+export type LayeredRankDir = "LR" | "RL" | "TB" | "BT";
+
+export interface LayeredLayoutOptions {
+  rankdir?: LayeredRankDir;
+  nodesep?: number;
+  ranksep?: number;
+  minNodeWidth: number;
+  minNodeHeight: number;
+}
+
+export interface LayeredLayoutPosition {
+  x: number;
+  y: number;
+}
+
+export interface FitLayeredLayoutOptions extends LayeredLayoutOptions {
+  targetAspectRatio: number;
+  maxIterations?: number;
+  tolerance?: number;
+}
+
+const DEFAULT_RANKDIR: LayeredRankDir = "LR";
+const DEFAULT_NODESEP = 50;
+const DEFAULT_RANKSEP = 120;
+
+const MIN_NODESEP = 20;
+const MAX_NODESEP = 400;
+const MIN_RANKSEP = 40;
+const MAX_RANKSEP = 600;
+const MIN_FACTOR = 0.25;
+const MAX_FACTOR = 4;
+const DEFAULT_TOLERANCE = 0.05;
+const DEFAULT_MAX_ITERATIONS = 4;
+
+const TITLE_PX_PER_CHAR_16 = 8;
+const NAME_PX_PER_CHAR_12 = 6.5;
+const NAME_PX_PER_CHAR_16_BOLD = 8;
+const SUBTITLE_PX_PER_CHAR_11 = 6;
+const LABEL_PADDING_PX = 16;
+
+function estimateLabelWidth(node: D3Node): number {
+  if (node.subtitle) {
+    const titleWidth = (node.name?.length ?? 0) * TITLE_PX_PER_CHAR_16;
+    const subtitleWidth = node.subtitle.length * SUBTITLE_PX_PER_CHAR_11;
+    return Math.max(titleWidth, subtitleWidth) + LABEL_PADDING_PX;
+  }
+  const perChar = node.bold ? NAME_PX_PER_CHAR_16_BOLD : NAME_PX_PER_CHAR_12;
+  return (node.name?.length ?? 0) * perChar + LABEL_PADDING_PX;
+}
+
+function linkEndpointId(end: D3Link["source"] | D3Link["target"]): string {
+  return typeof end === "string" ? end : end.id;
+}
+
+function clamp(value: number, min: number, max: number): number {
+  return Math.min(Math.max(value, min), max);
+}
+
+interface DagreRunResult {
+  positions: Map<string, LayeredLayoutPosition>;
+  bbox: { width: number; height: number };
+}
+
+/**
+ * Run dagre once for the given nodes/links/opts and return both the
+ * computed positions and the bounding box of the laid-out graph.
+ * Internal helper — callers should use `computeLayeredLayout` or
+ * `fitLayeredLayoutToAspectRatio`.
+ */
+function runDagreOnce(nodes: D3Node[], links: D3Link[], opts: LayeredLayoutOptions): DagreRunResult | null {
+  const rankdir = opts.rankdir ?? DEFAULT_RANKDIR;
+  const nodesep = opts.nodesep ?? DEFAULT_NODESEP;
+  const ranksep = opts.ranksep ?? DEFAULT_RANKSEP;
+
+  const g = new dagre.graphlib.Graph({ directed: true });
+  g.setGraph({ rankdir, nodesep, ranksep, marginx: 20, marginy: 20 });
+  g.setDefaultEdgeLabel(() => ({}));
+
+  for (const node of nodes) {
+    const width = Math.max(opts.minNodeWidth, estimateLabelWidth(node));
+    const height = opts.minNodeHeight;
+    g.setNode(node.id, { width, height });
+  }
+
+  const seen = new Set<string>();
+  for (const link of links) {
+    const sourceId = linkEndpointId(link.source);
+    const targetId = linkEndpointId(link.target);
+    if (!g.hasNode(sourceId) || !g.hasNode(targetId)) continue;
+    const key = `${sourceId}->${targetId}`;
+    if (seen.has(key)) continue;
+    seen.add(key);
+    g.setEdge(sourceId, targetId);
+  }
+
+  try {
+    dagre.layout(g);
+  } catch {
+    return null;
+  }
+
+  const positions = new Map<string, LayeredLayoutPosition>();
+  let xMin = Infinity;
+  let xMax = -Infinity;
+  let yMin = Infinity;
+  let yMax = -Infinity;
+
+  for (const node of nodes) {
+    const laid = g.node(node.id);
+    if (laid && Number.isFinite(laid.x) && Number.isFinite(laid.y)) {
+      positions.set(node.id, { x: laid.x, y: laid.y });
+      const halfW = (laid.width ?? opts.minNodeWidth) / 2;
+      const halfH = (laid.height ?? opts.minNodeHeight) / 2;
+      xMin = Math.min(xMin, laid.x - halfW);
+      xMax = Math.max(xMax, laid.x + halfW);
+      yMin = Math.min(yMin, laid.y - halfH);
+      yMax = Math.max(yMax, laid.y + halfH);
+    }
+  }
+
+  const bbox =
+    positions.size === 0
+      ? { width: 0, height: 0 }
+      : { width: Math.max(0, xMax - xMin), height: Math.max(0, yMax - yMin) };
+
+  return { positions, bbox };
+}
+
+/**
+ * Compute a layered DAG layout using dagre. Pure function: no DOM, no React,
+ * no d3 globals. Returns a Map of node.id -> { x, y } in graph coordinates.
+ *
+ * Returns null if dagre.layout throws (e.g. an unexpected cycle). Callers
+ * should fall back to their previous layout in that case.
+ */
+export function computeLayeredLayout(
+  nodes: D3Node[],
+  links: D3Link[],
+  opts: LayeredLayoutOptions,
+): Map<string, LayeredLayoutPosition> | null {
+  if (nodes.length === 0) return new Map();
+  const result = runDagreOnce(nodes, links, opts);
+  return result ? result.positions : null;
+}
+
+/**
+ * Compute a layered layout, then iteratively re-run dagre with adjusted
+ * `nodesep`/`ranksep` until the bounding-box aspect ratio is within
+ * `tolerance` of `targetAspectRatio` (or `maxIterations` is reached).
+ *
+ * Degenerate cases (empty graph, single-rank graph where one axis has
+ * zero extent, missing target ratio) skip fitting and return the
+ * single-pass result.
+ */
+export function fitLayeredLayoutToAspectRatio(
+  nodes: D3Node[],
+  links: D3Link[],
+  opts: FitLayeredLayoutOptions,
+): Map<string, LayeredLayoutPosition> | null {
+  if (nodes.length === 0) return new Map();
+  if (!Number.isFinite(opts.targetAspectRatio) || opts.targetAspectRatio <= 0) {
+    return computeLayeredLayout(nodes, links, opts);
+  }
+
+  const maxIterations = opts.maxIterations ?? DEFAULT_MAX_ITERATIONS;
+  const tolerance = opts.tolerance ?? DEFAULT_TOLERANCE;
+  const rankdir = opts.rankdir ?? DEFAULT_RANKDIR;
+  const isHorizontalFlow = rankdir === "LR" || rankdir === "RL";
+
+  let nodesep = opts.nodesep ?? DEFAULT_NODESEP;
+  let ranksep = opts.ranksep ?? DEFAULT_RANKSEP;
+
+  let best: DagreRunResult | null = null;
+
+  for (let i = 0; i < maxIterations; i++) {
+    const result = runDagreOnce(nodes, links, {
+      ...opts,
+      nodesep,
+      ranksep,
+    });
+    if (!result) return best ? best.positions : null;
+    best = result;
+
+    if (result.positions.size <= 1) return result.positions;
+
+    const { width, height } = result.bbox;
+    if (width === 0 || height === 0) return result.positions;
+
+    const currentAspect = width / height;
+    const ratio = opts.targetAspectRatio / currentAspect;
+
+    if (Math.abs(ratio - 1) < tolerance) return result.positions;
+
+    const factor = clamp(Math.sqrt(ratio), MIN_FACTOR, MAX_FACTOR);
+
+    if (isHorizontalFlow) {
+      ranksep = clamp(ranksep * factor, MIN_RANKSEP, MAX_RANKSEP);
+      nodesep = clamp(nodesep / factor, MIN_NODESEP, MAX_NODESEP);
+    } else {
+      ranksep = clamp(ranksep / factor, MIN_RANKSEP, MAX_RANKSEP);
+      nodesep = clamp(nodesep * factor, MIN_NODESEP, MAX_NODESEP);
+    }
+  }
+
+  return best ? best.positions : null;
+}

package/src/hooks/index.ts

@@ -35,3 +35,11 @@ export * from "./useNotificationSync";
 export * from "./usePageTracker";
 export * from "./usePushNotifications";
 export * from "./useSocket";
+export {
+  computeLayeredLayout,
+  fitLayeredLayoutToAspectRatio,
+  type FitLayeredLayoutOptions,
+  type LayeredLayoutOptions,
+  type LayeredLayoutPosition,
+  type LayeredRankDir,
+} from "./computeLayeredLayout";