@statelyai/layout 0.3.0 → 0.4.0

package/src/layered/hierarchical-port-routing.ts

@@ -0,0 +1,179 @@
+/*******************************************************************************
+ * Copyright (c) 2010, 2020 Kiel University and others.
+ * Adapted from ELK HierarchicalPortOrthogonalEdgeRouter in elkjs 0.11.1.
+ * SPDX-License-Identifier: EPL-2.0
+ *******************************************************************************/
+import type { EntityRect, Point } from "@statelyai/graph";
+import type { JavaRandom } from "../java-random";
+import type { ExternalPortConstraints, ExternalPortDummy } from "./external-port-dummy";
+import { createOrthogonalHypersegments } from "./orthogonal-hypersegments";
+import { routeOrthogonalSegments } from "./orthogonal-segments";
+import type { LayoutPadding, NodeSize } from "./types";
+
+export interface CanonicalHierarchicalPortRouting {
+  constraints: ExternalPortConstraints;
+  size: NodeSize;
+  offset: Point;
+  padding: LayoutPadding;
+  spacing: { node: number; edge: number; port: number };
+  originals: readonly {
+    id: string;
+    origin: ExternalPortDummy;
+    margin?: { left: number; right: number };
+  }[];
+  helpers: readonly {
+    id: string;
+    originalId: string;
+    rect: EntityRect;
+    incoming: readonly string[];
+    outgoing: readonly string[];
+  }[];
+  bends: ReadonlyMap<string, readonly Point[]>;
+}
+
+/** Operates in ELK's canonical LTR content coordinates, before graph export. */
+export function routeHierarchicalPorts(data: CanonicalHierarchicalPortRouting, random: JavaRandom) {
+  const size = { ...data.size },
+    offset = { ...data.offset };
+  const originals = new Map(data.originals.map((original) => [original.id, original]));
+  const rects = new Map<string, EntityRect>();
+  const bends = new Map(
+    [...data.bends].map(([id, points]) => [id, points.map((point) => ({ ...point }))]),
+  );
+  for (const original of data.originals) {
+    const { origin, id } = original;
+    const connected = data.helpers.filter((helper) => helper.originalId === id);
+    let x = connected.length
+      ? connected.reduce((sum, helper) => sum + helper.rect.x, 0) / connected.length -
+        origin.anchor.x
+      : 0;
+    if (data.constraints === "FIXED_POS" || data.constraints === "FIXED_RATIO") {
+      x =
+        (origin.ratioOrPosition ?? 0) *
+          (data.constraints === "FIXED_RATIO"
+            ? size.width + data.padding.left + data.padding.right
+            : 1) -
+        origin.anchor.x -
+        data.padding.left -
+        offset.x;
+      if (data.constraints === "FIXED_POS") size.width = Math.max(size.width, x + origin.width / 2);
+    }
+    rects.set(id, {
+      x,
+      y:
+        origin.side === "NORTH"
+          ? -data.padding.top - offset.y
+          : size.height + data.padding.top + data.padding.bottom - offset.y,
+      width: origin.width,
+      height: origin.height,
+    });
+  }
+  for (const side of ["NORTH", "SOUTH"] as const) {
+    const ordered = data.originals.filter((original) => original.origin.side === side);
+    if (
+      data.constraints === "FIXED_SIDE" ||
+      data.constraints === "FREE" ||
+      data.constraints === "UNDEFINED"
+    )
+      ordered.sort((a, b) => rects.get(a.id)!.x - rects.get(b.id)!.x);
+    else if (data.constraints === "FIXED_ORDER")
+      ordered.sort((a, b) => (a.origin.ratioOrPosition ?? 0) - (b.origin.ratioOrPosition ?? 0));
+    else continue;
+    let next: number | undefined;
+    for (const original of ordered) {
+      const rect = rects.get(original.id)!;
+      if (next !== undefined) rect.x = Math.max(rect.x, next + (original.margin?.left ?? 0));
+      if (next !== undefined) size.width = Math.max(size.width, rect.x + rect.width);
+      next = rect.x + rect.width + (original.margin?.right ?? 0) + data.spacing.port;
+    }
+  }
+  const connectorBends = new Map<string, Point[]>();
+  const minimumDifference = (values: readonly number[]) => {
+    const sorted = [...new Set(values)].sort((a, b) => a - b);
+    let min = Number.MAX_VALUE;
+    for (let i = 1; i < sorted.length; i++) min = Math.min(min, sorted[i]! - sorted[i - 1]!);
+    return min;
+  };
+  for (const side of ["NORTH", "SOUTH"] as const) {
+    const selectedOriginals = data.originals.filter((original) => original.origin.side === side);
+    const selectedHelpers = selectedOriginals.flatMap((original) =>
+      data.helpers.filter((helper) => helper.originalId === original.id),
+    );
+    if (!selectedHelpers.length) continue;
+    const ports = [
+      ...selectedHelpers.map((helper) => ({
+        id: helper.id,
+        side: "source" as const,
+        position: helper.rect.x,
+      })),
+      ...selectedOriginals.map((original) => ({
+        id: original.id,
+        side: "target" as const,
+        position: rects.get(original.id)!.x + original.origin.port.x,
+      })),
+    ];
+    const grouped = createOrthogonalHypersegments(
+      ports,
+      selectedHelpers.map((helper) => ({ source: helper.id, target: helper.originalId })),
+    );
+    const critical =
+      0.2 *
+      Math.min(
+        minimumDifference(grouped.segments.flatMap((segment) => segment.incoming)),
+        minimumDifference(grouped.segments.flatMap((segment) => segment.outgoing)),
+      );
+    const routed = routeOrthogonalSegments(
+      grouped.segments,
+      0.5 * data.spacing.edge,
+      critical,
+      random,
+    );
+    const start =
+      side === "NORTH" ? -data.spacing.node - offset.y : size.height + data.spacing.node - offset.y;
+    const sign = side === "NORTH" ? -1 : 1;
+    let slots = 0;
+    for (const segment of routed.segments)
+      if (Math.abs(segment.end - segment.start) >= 1e-3) slots = Math.max(slots, segment.slot + 1);
+    for (const helper of selectedHelpers) {
+      const segment = routed.segments[grouped.segmentByPort.get(helper.id)!]!;
+      const target = originals.get(helper.originalId)!,
+        targetX = rects.get(target.id)!.x + target.origin.port.x;
+      const points: Point[] = [];
+      if (Math.abs(helper.rect.x - targetX) > 1e-3) {
+        let track = start + sign * segment.slot * data.spacing.edge;
+        points.push({ x: helper.rect.x, y: track });
+        if (segment.partner !== undefined) {
+          const partner = routed.segments[segment.partner]!;
+          const split = partner.incoming[0]!;
+          points.push({ x: split, y: track });
+          track = start + sign * partner.slot * data.spacing.edge;
+          points.push({ x: split, y: track });
+        }
+        points.push({ x: targetX, y: track });
+      }
+      connectorBends.set(helper.id, points);
+    }
+    if (slots > 0) {
+      const reserve = data.spacing.node + (slots - 1) * data.spacing.edge;
+      size.height += reserve;
+      if (side === "NORTH") offset.y += reserve;
+    }
+  }
+  for (const helper of data.helpers) {
+    const connector = connectorBends.get(helper.id) ?? [];
+    const joint = { x: helper.rect.x, y: helper.rect.y };
+    for (const id of helper.incoming)
+      bends.set(id, [...(bends.get(id) ?? []), joint, ...connector]);
+    for (const id of helper.outgoing)
+      bends.set(id, [...connector.toReversed(), joint, ...(bends.get(id) ?? [])]);
+  }
+  // The real coordinate fixer runs after reserving connector tracks.
+  for (const original of data.originals) {
+    const rect = rects.get(original.id)!;
+    rect.y =
+      original.origin.side === "NORTH"
+        ? -data.padding.top - offset.y
+        : size.height + data.padding.bottom - offset.y;
+  }
+  return { size, offset, rects, bends };
+}

package/src/layered/hierarchy-crossing.ts

@@ -0,0 +1,121 @@
+import { traceLayeredPhase } from "../internal/layered-trace";
+import type { LayerSweepSession } from "./strategies";
+import type { LayerOrder } from "./types";
+
+/** Internal prepared scope; boundary callbacks synchronize parent ports and child dummies. */
+export interface HierarchyCrossingScope {
+  readonly session: LayerSweepSession;
+  readonly childrenByNodeId: ReadonlyMap<string, HierarchyCrossingScope>;
+  readonly useBottomUp: boolean;
+  /** ELK child graph heuristics retain their own graph random stream. */
+  readonly independentRandom?: boolean;
+  /** Returns true when an external first layer was ordered from parent ports. */
+  alignBoundary?(forward: boolean): boolean;
+  publishBoundary?(forward: boolean): void;
+  publishBottomUp?(): void;
+}
+
+/**
+ * ELK's counter-based hierarchy traversal: enter children between parent layers,
+ * count the coupled subtree, and retain all of its node/port orders together.
+ * Scope assembly, sweepiness selection and boundary-port mapping belong to the
+ * caller; this coordinator does not infer them from finalized geometry.
+ */
+export function minimizeHierarchyCrossings(
+  root: HierarchyCrossingScope,
+): ReadonlyMap<HierarchyCrossingScope, LayerOrder> {
+  if (!root.useBottomUp) throw new Error("Root crossing scope must be bottom-up");
+  const scopes = [root],
+    seen = new Set([root]);
+  for (let index = 0; index < scopes.length; index++) {
+    const scope = scopes[index]!;
+    const nodeIds = new Set(scope.session.snapshot().layers.flat());
+    for (const [id, child] of scope.childrenByNodeId) {
+      if (!nodeIds.has(id)) throw new Error(`Missing parent crossing node ${id}`);
+      scope.session.markHierarchicalNode(id);
+      if (seen.has(child)) throw new Error("Crossing scopes must form a tree");
+      seen.add(child);
+      scopes.push(child);
+    }
+  }
+  const initialRandom = root.session.random.clone();
+  const coupled = (scope: HierarchyCrossingScope): HierarchyCrossingScope[] => [
+    scope,
+    ...[...scope.childrenByNodeId.values()].flatMap((child) =>
+      child.useBottomUp ? [] : coupled(child),
+    ),
+  ];
+  const sweep = (scope: HierarchyCrossingScope, forward: boolean, first: boolean): void => {
+    scope.session.sweep(forward, first, (_layer, ids) => {
+      for (const id of ids) {
+        const child = scope.childrenByNodeId.get(id);
+        if (!child || child.useBottomUp) continue;
+        if (!child.alignBoundary?.(forward)) child.session.shuffleFirstLayer(forward);
+        sweep(child, forward, first);
+        child.publishBoundary?.(forward);
+      }
+    });
+  };
+  // ELK prepends every bottom-up scope during breadth-first initialization.
+  for (const scope of [...scopes].reverse().filter((scope) => scope.useBottomUp)) {
+    const stream = initialRandom.clone();
+    for (const scope of scopes) if (!scope.independentRandom) scope.session.useRandom(stream);
+    const subtree = coupled(scope);
+    const snapshot = () => new Map(subtree.map((scope) => [scope, scope.session.snapshot()]));
+    const count = () => subtree.reduce((total, scope) => total + scope.session.countCrossings(), 0);
+    const rollback = subtree.some((scope) => scope.session.restoreRejectedSweep);
+    let bestCount = Number.POSITIVE_INFINITY,
+      best = snapshot();
+    for (let attempt = 0; attempt < scope.session.attempts; attempt++) {
+      let forward = stream.nextBoolean();
+      if (scope.session.usesInitialModelOrder && attempt === 0) {
+        if (attempt === 0 && count() === 0) {
+          bestCount = 0;
+          best = snapshot();
+          break;
+        }
+        // ELK 0.11.1 gives FIRST_TRY and SECOND_TRY the same property id.
+        // Clearing SECOND_TRY therefore clears FIRST_TRY after this attempt.
+        forward = true;
+      } else scope.session.shuffleFirstLayer(forward);
+      sweep(scope, forward, true);
+      scope.session.finishInitialOrderAttempt?.();
+      let crossings = count(),
+        selected = snapshot();
+      const trace = (first: boolean, value: number) =>
+        traceLayeredPhase(() => ({
+          kind: "sweep",
+          scope: scope.session.scope,
+          attempt,
+          forward,
+          firstSweep: first,
+          crossings: value,
+          layers: scope.session.snapshot().layers,
+        }));
+      trace(true, crossings);
+      while (crossings > 0) {
+        forward = !forward;
+        const previous = rollback ? snapshot() : undefined;
+        sweep(scope, forward, false);
+        const next = count();
+        trace(false, next);
+        if (next >= crossings) {
+          // Preserve the legacy wrapped/unzipped standalone rollback policy.
+          for (const [scope, order] of previous ?? [])
+            if (scope.session.restoreRejectedSweep) scope.session.restore(order);
+          break;
+        }
+        crossings = next;
+        selected = snapshot();
+      }
+      if (crossings < bestCount) {
+        bestCount = crossings;
+        best = selected;
+        if (crossings === 0) break;
+      }
+    }
+    for (const [scope, order] of best) scope.session.restore(order);
+    scope.publishBottomUp?.();
+  }
+  return new Map(scopes.map((scope) => [scope, scope.session.finish(scope.session.snapshot())]));
+}

package/src/layered/hierarchy-sweepiness.ts

@@ -0,0 +1,83 @@
+/* Native adaptation of ELK 0.11.1 LayerSweepTypeDecider. SPDX-License-Identifier: EPL-2.0 */
+import { externalPortDummyOf } from "./external-port-dummy";
+import { getCrossingUnits } from "./crossing-constraints";
+import type { AcyclicOrientation, LayeredPhaseInput } from "./types";
+
+export function useBottomUpHierarchySweep(
+  input: LayeredPhaseInput,
+  orientation: AcyclicOrientation,
+  layers: readonly (readonly string[])[],
+  parent: {
+    portOrderFixed: boolean;
+    inputPorts: number;
+    outputPorts: number;
+    deterministic: boolean;
+  },
+): boolean {
+  const boundary = input.settings["crossingMinimization.hierarchicalSweepiness"] ?? 0.1;
+  if (boundary < -1 || parent.portOrderFixed || (parent.inputPorts < 2 && parent.outputPorts < 2))
+    return true;
+  if (parent.deterministic) return false;
+  const nodes = new Map(input.graph.nodes.map((node) => [node.id, node]));
+  const infos = new Map(
+    input.graph.nodes.map((node) => [node.id, { random: 0, hierarchy: 0, edges: 0 }]),
+  );
+  const outgoing = new Map<string, string[]>(),
+    incoming = new Map<string, string[]>();
+  for (const edge of input.graph.edges) {
+    const reversed = orientation.reversedEdgeIds.has(edge.id);
+    const source = reversed ? edge.targetId : edge.sourceId,
+      target = reversed ? edge.sourceId : edge.targetId;
+    outgoing.set(source, [...(outgoing.get(source) ?? []), target]);
+    incoming.set(target, [...(incoming.get(target) ?? []), source]);
+  }
+  const units = getCrossingUnits(input);
+  let randomPaths = 0,
+    hierarchyPaths = 0;
+  const transfer = (source: string, target: string) => {
+    const a = infos.get(source)!,
+      b = infos.get(target)!;
+    b.random += a.random;
+    b.hierarchy += a.hierarchy;
+    b.edges += a.edges + 1;
+  };
+  const outputSide = ({ right: "EAST", left: "WEST", down: "SOUTH", up: "NORTH" } as const)[
+    input.direction
+  ];
+  const passEdges = (id: string) => {
+    const state = infos.get(id)!;
+    for (const target of outgoing.get(id) ?? []) {
+      randomPaths += state.random;
+      hierarchyPaths += state.hierarchy;
+      transfer(id, target);
+    }
+  };
+  for (const layer of layers) {
+    const northSouth: string[] = [];
+    for (const id of layer) {
+      if (id.startsWith("__layout_dummy:north-south:")) {
+        northSouth.push(id);
+        continue;
+      }
+      const node = nodes.get(id)!,
+        state = infos.get(id)!;
+      const external = externalPortDummyOf(node);
+      if (external) {
+        state.hierarchy = 1;
+        if (external.side === outputSide) hierarchyPaths += state.edges;
+      } else {
+        if (!incoming.get(id)?.length) state.random = 1;
+        else if (!outgoing.get(id)?.length) randomPaths += state.edges;
+      }
+      passEdges(id);
+      for (const dummy of units?.associates.get(id) ?? []) {
+        randomPaths += state.random;
+        hierarchyPaths += state.hierarchy;
+        transfer(id, dummy);
+      }
+    }
+    for (const id of northSouth) passEdges(id);
+  }
+  const all = randomPaths + hierarchyPaths;
+  return (all === 0 ? Number.POSITIVE_INFINITY : (randomPaths - hierarchyPaths) / all) >= boundary;
+}