@statelyai/layout 0.2.0 → 0.4.0

package/src/layered/hints.ts

@@ -0,0 +1,371 @@
+import type { GraphNode, VisualGraph } from "@statelyai/graph";
+import { worldGeometry } from "../authoring/coordinates";
+import type { LayoutDiagnostic } from "../types";
+import type { LayerOrder, LayeredPhaseInput, NodePlacement } from "./types";
+
+/**
+ * Hints steer the layered phases toward a reader's expectations. They are
+ * preferences unless marked `require`, and never at the cost of a defect: a
+ * hint that would make nodes overlap is relaxed and reported instead.
+ */
+export type HintStrength = "prefer" | "require";
+interface HintBase {
+  id: string;
+  strength?: HintStrength;
+}
+/** Place a node at the start (top-left) or end of its container. */
+export interface AnchorHint extends HintBase {
+  kind: "anchor";
+  nodeId: string;
+  corner: "start" | "end";
+}
+/** Align the centers of nodes that follow each other, such as sequential states. */
+export interface ChainHint extends HintBase {
+  kind: "chain";
+  nodeIds: readonly string[];
+}
+export type LayoutHint = AnchorHint | ChainHint;
+
+/** Serializable hint constructors, alongside the `c` geometry constraint constructors. */
+export const hint = {
+  anchor: (value: Omit<AnchorHint, "kind">): AnchorHint => ({ ...value, kind: "anchor" }),
+  chain: (value: Omit<ChainHint, "kind">): ChainHint => ({ ...value, kind: "chain" }),
+};
+
+const relaxed = (
+  diagnostics: LayoutDiagnostic[] | undefined,
+  item: LayoutHint,
+  message: string,
+): void => {
+  diagnostics?.push({
+    severity: "info",
+    code: "HINT_RELAXED",
+    message: `Hint ${item.id}: ${message}`,
+    entityIds: item.kind === "anchor" ? [item.nodeId] : [...item.nodeIds],
+  });
+};
+
+/** Layering: an anchored node takes the first or last layer of its scope. */
+export function hintLayerConstraint(
+  hints: readonly LayoutHint[] | undefined,
+  node: GraphNode,
+): "FIRST" | "LAST" | undefined {
+  const anchor = hints?.find(
+    (item): item is AnchorHint => item.kind === "anchor" && item.nodeId === node.id,
+  );
+  return anchor ? (anchor.corner === "start" ? "FIRST" : "LAST") : undefined;
+}
+
+/**
+ * Ordering: an anchored node, with any helper nodes kept beside it, moves to
+ * the start or end of its layer. A preferred anchor yields when the move
+ * would add crossings.
+ */
+export function applyOrderHints(
+  hints: readonly LayoutHint[] | undefined,
+  order: LayerOrder,
+  unitOf: (id: string) => readonly string[],
+  crossings: (layers: LayerOrder["layers"]) => number,
+  diagnostics?: LayoutDiagnostic[],
+): LayerOrder {
+  let layers = order.layers;
+  for (const item of hints ?? []) {
+    if (item.kind !== "anchor") continue;
+    const index = layers.findIndex((layer) => layer.includes(item.nodeId));
+    if (index < 0) continue;
+    const unit = new Set([item.nodeId, ...unitOf(item.nodeId)]);
+    const layer = layers[index]!;
+    const members = layer.filter((id) => unit.has(id)),
+      rest = layer.filter((id) => !unit.has(id));
+    const moved = item.corner === "start" ? [...members, ...rest] : [...rest, ...members];
+    if (moved.every((id, position) => id === layer[position])) continue;
+    const candidate = layers.map((current, position) => (position === index ? moved : current));
+    if ((item.strength ?? "prefer") === "prefer" && crossings(candidate) > crossings(layers)) {
+      relaxed(diagnostics, item, "kept its layer position to avoid adding crossings");
+      continue;
+    }
+    layers = candidate;
+  }
+  return layers === order.layers ? order : { ...order, layers };
+}
+
+/**
+ * Placement: an anchored node moves to the start (or end) of its scope on the
+ * cross axis, and chained nodes move onto the first member's center line,
+ * each only as far as its layer neighbors allow.
+ */
+export function applyPlacementHints(
+  hints: readonly LayoutHint[] | undefined,
+  input: LayeredPhaseInput,
+  order: LayerOrder,
+  placement: NodePlacement,
+  diagnostics?: LayoutDiagnostic[],
+): void {
+  if (!hints?.length) return;
+  const rects = placement.rectByNodeId as Map<
+    string,
+    { x: number; y: number; width: number; height: number }
+  >;
+  const horizontal = input.direction === "right" || input.direction === "left";
+  const cross = (id: string) => {
+    const rect = rects.get(id)!;
+    return horizontal ? { start: rect.y, size: rect.height } : { start: rect.x, size: rect.width };
+  };
+  const setCross = (id: string, start: number) => {
+    const rect = rects.get(id)!;
+    rects.set(id, horizontal ? { ...rect, y: start } : { ...rect, x: start });
+  };
+  const position = new Map<string, { layer: readonly string[]; index: number }>();
+  for (const layer of order.layers)
+    for (const [index, id] of layer.entries()) position.set(id, { layer, index });
+  const gap = (id: string) => (id.startsWith("__") ? 10 : input.spacing.node);
+  // The free interval for a node's cross start between its layer neighbors.
+  const room = (id: string) => {
+    const at = position.get(id);
+    const own = cross(id);
+    if (!at) return { low: own.start, high: own.start };
+    const before = at.layer[at.index - 1],
+      after = at.layer[at.index + 1];
+    const low = before
+      ? cross(before).start + cross(before).size + Math.max(gap(before), gap(id))
+      : Number.NEGATIVE_INFINITY;
+    const high = after
+      ? cross(after).start - own.size - Math.max(gap(after), gap(id))
+      : Number.POSITIVE_INFINITY;
+    // Never grow the scope: stay within its current cross extent.
+    const bounded = {
+      low: Math.max(low, extent.start),
+      high: Math.min(high, extent.end - own.size),
+    };
+    return {
+      low: Math.min(bounded.low, own.start),
+      high: Math.max(bounded.high, own.start),
+    };
+  };
+  const real = [...rects.keys()].filter((id) => !id.startsWith("__"));
+  const extent = {
+    start: Math.min(...[...rects.keys()].map((id) => cross(id).start)),
+    end: Math.max(...[...rects.keys()].map((id) => cross(id).start + cross(id).size)),
+  };
+  for (const item of hints) {
+    if (item.kind === "anchor") {
+      if (!rects.has(item.nodeId)) continue;
+      const own = cross(item.nodeId);
+      const target =
+        item.corner === "start"
+          ? Math.min(...real.map((id) => cross(id).start))
+          : Math.max(...real.map((id) => cross(id).start + cross(id).size)) - own.size;
+      const { low, high } = room(item.nodeId);
+      const placed = Math.min(high, Math.max(low, target));
+      setCross(item.nodeId, placed);
+      if (Math.abs(placed - target) > 1e-6)
+        relaxed(diagnostics, item, "a neighbor in its layer kept it from the corner");
+    } else {
+      const members = item.nodeIds.filter((id) => rects.has(id));
+      if (members.length < 2) continue;
+      const anchored = members.find((id) =>
+        hints.some((other) => other.kind === "anchor" && other.nodeId === id),
+      );
+      // Find the center line every member can reach, nearest the first member
+      // (or the anchored one, which stays put).
+      const reach = members.map((id) => {
+        const own = cross(id);
+        if (id === anchored) {
+          const center = own.start + own.size / 2;
+          return { low: center, high: center };
+        }
+        const { low, high } = room(id);
+        return { low: low + own.size / 2, high: high + own.size / 2 };
+      });
+      const line = cross(anchored ?? members[0]!);
+      const preferred = line.start + line.size / 2;
+      const low = Math.max(...reach.map((range) => range.low)),
+        high = Math.min(...reach.map((range) => range.high));
+      const center = low <= high ? Math.min(high, Math.max(low, preferred)) : preferred;
+      let blocked = low > high;
+      for (const [index, id] of members.entries()) {
+        if (id === anchored) continue;
+        const own = cross(id);
+        const range = reach[index]!;
+        const placed = Math.min(range.high, Math.max(range.low, center)) - own.size / 2;
+        setCross(id, placed);
+        if (Math.abs(placed + own.size / 2 - center) > 1e-6) blocked = true;
+      }
+      if (blocked) relaxed(diagnostics, item, "layer neighbors kept some members off the line");
+    }
+  }
+}
+
+/**
+ * Hints for statecharts: each container's initial state (and the graph's)
+ * is required at the start, and each run of states joined one-to-one within
+ * the same parent forms a preferred chain. Callers can filter or extend the
+ * result.
+ */
+export function statechartHints(graph: {
+  initialNodeId?: string | null;
+  nodes: readonly { id: string; parentId?: string | null; initialNodeId?: string | null }[];
+  edges: readonly { sourceId: string; targetId: string }[];
+}): LayoutHint[] {
+  const nodes = new Map(graph.nodes.map((node) => [node.id, node]));
+  const hints: LayoutHint[] = [];
+  const initials = [
+    ...(graph.initialNodeId ? [{ scope: "root", id: graph.initialNodeId }] : []),
+    ...graph.nodes.flatMap((node) =>
+      node.initialNodeId ? [{ scope: node.id, id: node.initialNodeId }] : [],
+    ),
+  ];
+  for (const { scope, id } of initials)
+    if (nodes.has(id))
+      hints.push(
+        hint.anchor({ id: `initial:${scope}`, nodeId: id, corner: "start", strength: "require" }),
+      );
+  // One-to-one transitions between siblings, ignoring self loops.
+  const outgoing = new Map<string, Set<string>>(),
+    incoming = new Map<string, Set<string>>();
+  for (const edge of graph.edges) {
+    if (edge.sourceId === edge.targetId) continue;
+    outgoing.set(edge.sourceId, (outgoing.get(edge.sourceId) ?? new Set()).add(edge.targetId));
+    incoming.set(edge.targetId, (incoming.get(edge.targetId) ?? new Set()).add(edge.sourceId));
+  }
+  const next = (id: string) => {
+    const targets = outgoing.get(id);
+    if (targets?.size !== 1) return undefined;
+    const [target] = targets;
+    const node = nodes.get(id),
+      other = nodes.get(target!);
+    return other &&
+      (other.parentId ?? null) === (node?.parentId ?? null) &&
+      incoming.get(target!)?.size === 1
+      ? target
+      : undefined;
+  };
+  const previous = new Set(
+    graph.nodes.flatMap((node) => {
+      const target = next(node.id);
+      return target ? [target] : [];
+    }),
+  );
+  for (const node of graph.nodes) {
+    if (previous.has(node.id)) continue;
+    const chain = [node.id];
+    for (let id = next(node.id); id && !chain.includes(id); id = next(id)) chain.push(id);
+    if (chain.length >= 2) hints.push(hint.chain({ id: `chain:${node.id}`, nodeIds: chain }));
+  }
+  return hints;
+}
+
+interface SoftQuality {
+  crossings: number;
+  bends: number;
+  length: number;
+  area: number;
+}
+/** Soft measures of a finished layout, in world coordinates. */
+export function measureSoftQuality(graph: VisualGraph): SoftQuality {
+  const world = worldGeometry(graph);
+  const rects = new Map(world.nodes.map((node) => [node.id, node]));
+  const routes = world.edges.map((edge) => {
+    const points = edge.points ?? [];
+    return {
+      ends: [edge.sourceId, edge.targetId],
+      segments: points.slice(1).map((b, index) => ({ a: points[index]!, b })),
+    };
+  });
+  let bends = 0,
+    length = 0;
+  for (const { segments } of routes)
+    for (const [index, { a, b }] of segments.entries()) {
+      length += Math.abs(b.x - a.x) + Math.abs(b.y - a.y);
+      const previous = segments[index - 1];
+      if (previous && Math.abs(previous.a.x - previous.b.x) < 1e-9 !== Math.abs(a.x - b.x) < 1e-9)
+        bends++;
+    }
+  let crossings = 0;
+  for (const [index, first] of routes.entries())
+    for (const second of routes.slice(index + 1)) {
+      const shared = first.ends
+        .filter((id) => second.ends.includes(id))
+        .flatMap((id) => {
+          const rect = rects.get(id);
+          return rect ? [rect] : [];
+        });
+      for (const s of first.segments)
+        for (const t of second.segments) {
+          const sHorizontal = Math.abs(s.a.y - s.b.y) < 1e-9,
+            tHorizontal = Math.abs(t.a.y - t.b.y) < 1e-9;
+          if (sHorizontal === tHorizontal) continue;
+          const h = sHorizontal ? s : t,
+            v = sHorizontal ? t : s;
+          const x = v.a.x,
+            y = h.a.y;
+          if (
+            x > Math.min(h.a.x, h.b.x) + 1e-6 &&
+            x < Math.max(h.a.x, h.b.x) - 1e-6 &&
+            y > Math.min(v.a.y, v.b.y) + 1e-6 &&
+            y < Math.max(v.a.y, v.b.y) - 1e-6 &&
+            shared.every(
+              (rect) =>
+                x < rect.x - 12 ||
+                x > rect.x + rect.width + 12 ||
+                y < rect.y - 12 ||
+                y > rect.y + rect.height + 12,
+            )
+          )
+            crossings++;
+        }
+    }
+  const xs = world.nodes.flatMap((node) => [node.x, node.x + node.width]),
+    ys = world.nodes.flatMap((node) => [node.y, node.y + node.height]);
+  const area = xs.length
+    ? (Math.max(...xs) - Math.min(...xs)) * (Math.max(...ys) - Math.min(...ys))
+    : 0;
+  return { crossings, bends, length, area };
+}
+
+/** True when `candidate` is worse at the first soft measure where the two differ. */
+export function isSoftRegression(candidate: SoftQuality, baseline: SoftQuality): boolean {
+  for (const key of ["crossings", "bends", "length", "area"] as const) {
+    const limit = key === "length" || key === "area" ? 0.02 * Math.abs(baseline[key]) : 0;
+    if (Math.abs(candidate[key] - baseline[key]) > limit) return candidate[key] > baseline[key];
+  }
+  return false;
+}
+
+/**
+ * Lay out with every hint, keeping preferred hints only while they do not
+ * make the layout worse than one without them. Usually two layouts; when the
+ * full set regresses, preferred hints are added back one at a time.
+ */
+export function layoutWithHints<T extends VisualGraph>(
+  hints: readonly LayoutHint[] | undefined,
+  run: (hints: readonly LayoutHint[] | undefined, diagnostics: LayoutDiagnostic[]) => T,
+  diagnostics?: LayoutDiagnostic[],
+): T {
+  const preferred = hints?.filter((item) => (item.strength ?? "prefer") === "prefer") ?? [];
+  if (!preferred.length) return run(hints, diagnostics ?? []);
+  const required = hints!.filter((item) => item.strength === "require");
+  const attempt = (selected: readonly LayoutHint[]) => {
+    const own: LayoutDiagnostic[] = [];
+    const graph = run(selected, own);
+    return { graph, own, quality: measureSoftQuality(graph) };
+  };
+  let best = attempt(required);
+  const all = attempt(hints!);
+  let kept: LayoutHint[] = [...required];
+  if (!isSoftRegression(all.quality, best.quality)) {
+    best = all;
+    kept = [...hints!];
+  } else
+    for (const item of preferred) {
+      const candidate = attempt([...kept, item]);
+      if (isSoftRegression(candidate.quality, best.quality)) continue;
+      best = candidate;
+      kept.push(item);
+    }
+  diagnostics?.push(...best.own);
+  for (const item of preferred)
+    if (!kept.includes(item))
+      relaxed(diagnostics, item, "dropped because it made the layout worse");
+  return best.graph;
+}

package/src/layered/hyperedge-dummy-merger.ts

@@ -0,0 +1,195 @@
+/*
+ * Copyright (c) 2015, 2020 Kiel University and others.
+ * Native adaptation of ELK HyperedgeDummyMerger (v0.11.0).
+ * SPDX-License-Identifier: EPL-2.0
+ */
+import type { LayeredPhaseInput, LayerOrder } from "./types";
+import type { LongEdgeExpansion } from "./long-edges";
+
+const mergedNodes = new WeakMap<LayeredPhaseInput, Set<string>>();
+export const isMergedHyperedgeDummy = (input: LayeredPhaseInput, id: string): boolean =>
+  mergedNodes.get(input)?.has(id) ?? false;
+
+/**
+ * ELK schedules HyperedgeDummyMerger only when import finds a port with more
+ * than one incoming or outgoing edge (or a hypernode). Hierarchy scopes keep
+ * the merger: their imported edges are not visible here.
+ */
+export function importsHyperedges(input: LayeredPhaseInput): boolean {
+  const { graph } = input;
+  if (
+    graph.nodes.some(
+      (node) =>
+        node.id.startsWith("__native_hierarchy") || input.nodeSettings?.(node)?.hypernode === true,
+    ) ||
+    graph.edges.some((edge) => edge.id.startsWith("__native_hierarchy"))
+  )
+    return true;
+  const counts = new Map<string, number>();
+  const exceeds = (nodeId: string, port: string | undefined, kind: string, edgeId: string) => {
+    const key =
+      port !== undefined
+        ? `${nodeId}\0${port}\0${kind}`
+        : nodeId.startsWith("__") || input.settings.mergeEdges === true
+          ? `${nodeId}\0\0${kind}`
+          : `\0${edgeId}\0${kind}`;
+    const count = (counts.get(key) ?? 0) + 1;
+    counts.set(key, count);
+    return count > 1;
+  };
+  let found = false;
+  for (const edge of graph.edges) {
+    const source = exceeds(edge.sourceId, edge.sourcePort, "out", edge.id);
+    const target = exceeds(edge.targetId, edge.targetPort, "in", edge.id);
+    found ||= source || target;
+  }
+  return found;
+}
+
+/** Merge adjacent long-edge dummies connected through the same physical hyperedge. */
+export function mergeHyperedgeDummies(expansion: LongEdgeExpansion, order: LayerOrder): LayerOrder {
+  const { input } = expansion;
+  const labelNodes = new Set(expansion.labelDummyIdByEdgeId.values());
+  const longDummy = (id: string) =>
+    id.startsWith("__layout_dummy:") &&
+    !id.startsWith("__layout_dummy:north-south:") &&
+    !id.startsWith("__layout_dummy:label:") &&
+    !labelNodes.has(id);
+  const parent = new Map<string, string>();
+  const root = (id: string): string => {
+    const next = parent.get(id);
+    if (next === undefined) {
+      parent.set(id, id);
+      return id;
+    }
+    if (next === id) return id;
+    const result = root(next);
+    parent.set(id, result);
+    return result;
+  };
+  const port = (id: string, name: string | undefined, edge: string, endpoint: string) =>
+    longDummy(id)
+      ? JSON.stringify(["dummy", id])
+      : name !== undefined
+        ? JSON.stringify(["port", id, name])
+        : input.settings.mergeEdges === true
+          ? JSON.stringify(["implicit", id, endpoint])
+          : JSON.stringify(["edge", edge, endpoint]);
+  for (const edge of input.graph.edges) {
+    const source = port(edge.sourceId, edge.sourcePort, edge.id, "source");
+    const target = port(edge.targetId, edge.targetPort, edge.id, "target");
+    parent.set(root(source), root(target));
+  }
+  // Label-bearing chains merge only before a shared source or after a shared target.
+  type Metadata = {
+    source?: string;
+    target?: string;
+    label?: boolean;
+    before?: boolean;
+    reversed?: boolean;
+  };
+  const metadata = new Map<string, Metadata>();
+  const edges = new Map(input.graph.edges.map((edge) => [edge.id, edge]));
+  for (const [edgeId, ids] of expansion.segmentIdsByEdgeId) {
+    const chain = ids.map((id) => edges.get(id)).filter((edge) => edge !== undefined);
+    if (!chain.length) continue;
+    const first = chain[0]!,
+      last = chain.at(-1)!;
+    const reversed =
+      (expansion.assignment.layerByNodeId.get(first.sourceId) ?? 0) >
+      (expansion.assignment.layerByNodeId.get(last.targetId) ?? 0);
+    const source = port(
+      reversed ? last.targetId : first.sourceId,
+      reversed ? last.targetPort : first.sourcePort,
+      edgeId,
+      "source",
+    );
+    const target = port(
+      reversed ? first.sourceId : last.targetId,
+      reversed ? first.sourcePort : last.targetPort,
+      edgeId,
+      "target",
+    );
+    const labelId = expansion.labelDummyIdByEdgeId.get(edgeId);
+    const labelLayer =
+      labelId === undefined ? undefined : expansion.assignment.layerByNodeId.get(labelId);
+    for (const edge of chain)
+      for (const id of [edge.sourceId, edge.targetId]) {
+        if (!longDummy(id)) continue;
+        metadata.set(id, {
+          source,
+          target,
+          label: labelId !== undefined,
+          reversed,
+          before:
+            labelLayer !== undefined &&
+            (expansion.assignment.layerByNodeId.get(id) ?? 0) < labelLayer,
+        });
+      }
+  }
+  const aliases = new Map<string, string>(),
+    merged = new Set<string>();
+  const layers = order.layers.map((layer) => {
+    const result: string[] = [];
+    for (const id of layer) {
+      const previous = result.at(-1);
+      if (previous !== undefined && longDummy(id) && longDummy(previous)) {
+        const currentInfo = metadata.get(id) ?? {},
+          priorInfo = metadata.get(previous) ?? {};
+        const sameSource =
+          currentInfo.source !== undefined && currentInfo.source === priorInfo.source;
+        const sameTarget =
+          currentInfo.target !== undefined && currentInfo.target === priorInfo.target;
+        // Opposite-direction chains never share a track.
+        const allowed =
+          currentInfo.reversed === priorInfo.reversed &&
+          (!currentInfo.label && !priorInfo.label
+            ? root(JSON.stringify(["dummy", id])) === root(JSON.stringify(["dummy", previous]))
+            : (sameSource &&
+                (!currentInfo.label || currentInfo.before) &&
+                (!priorInfo.label || priorInfo.before)) ||
+              (sameTarget &&
+                (!currentInfo.label || !currentInfo.before) &&
+                (!priorInfo.label || !priorInfo.before)));
+        if (allowed) {
+          aliases.set(id, previous);
+          merged.add(previous);
+          metadata.set(previous, {
+            ...priorInfo,
+            source: sameSource ? priorInfo.source : undefined,
+            target: sameTarget ? priorInfo.target : undefined,
+          });
+          continue;
+        }
+      }
+      result.push(id);
+    }
+    return result;
+  });
+  if (!aliases.size) return order;
+  input.graph = {
+    ...input.graph,
+    nodes: input.graph.nodes.filter((node) => !aliases.has(node.id)),
+    edges: input.graph.edges.map((edge) => ({
+      ...edge,
+      sourceId: aliases.get(edge.sourceId) ?? edge.sourceId,
+      targetId: aliases.get(edge.targetId) ?? edge.targetId,
+    })),
+  } as LayeredPhaseInput["graph"];
+  mergedNodes.set(input, merged);
+  const portOrders = (original: ReadonlyMap<string, readonly string[]> | undefined) => {
+    if (!original) return undefined;
+    const result = new Map(original);
+    for (const [removed, kept] of aliases) {
+      result.set(kept, [...(result.get(kept) ?? []), ...(result.get(removed) ?? [])]);
+      result.delete(removed);
+    }
+    return result;
+  };
+  return {
+    ...order,
+    layers,
+    inputPortOrderByNodeId: portOrders(order.inputPortOrderByNodeId),
+    outputPortOrderByNodeId: portOrders(order.outputPortOrderByNodeId),
+  };
+}