@statelyai/layout 0.2.0 → 0.4.0

package/src/layered/end-labels.ts

@@ -0,0 +1,124 @@
+import type { EntityRect, Point } from "@statelyai/graph";
+import type { ExteriorLabelEdge } from "./separate-exterior-labels";
+
+interface PlaceEndLabelsInput<E extends ExteriorLabelEdge> {
+  edges: E[];
+  nodeRects: readonly EntityRect[];
+  spacing: number;
+  placement: (edge: E) => string;
+  inline: (edge: E) => boolean;
+}
+
+const overlaps = (left: EntityRect, right: EntityRect): boolean =>
+  left.x < right.x + right.width &&
+  left.x + left.width > right.x &&
+  left.y < right.y + right.height &&
+  left.y + left.height > right.y;
+
+/** Whether segment a-b passes through the box's interior (Liang-Barsky clipping). */
+const segmentCrosses = (a: Point, b: Point, box: EntityRect): boolean => {
+  let low = 0,
+    high = 1;
+  const dx = b.x - a.x,
+    dy = b.y - a.y;
+  for (const [p, q] of [
+    [-dx, a.x - box.x],
+    [dx, box.x + box.width - a.x],
+    [-dy, a.y - box.y],
+    [dy, box.y + box.height - a.y],
+  ] as const) {
+    if (p === 0) {
+      if (q <= 0) return false;
+      continue;
+    }
+    const t = q / p;
+    if (p < 0) low = Math.max(low, t);
+    else high = Math.min(high, t);
+  }
+  return low < high;
+};
+
+const crosses = (points: readonly Point[], box: EntityRect): boolean =>
+  points.some((a, index) => {
+    const b = points[index + 1];
+    return b !== undefined && segmentCrosses(a, b, box);
+  });
+
+/**
+ * Moves a HEAD or TAIL label that covers a node, another label or a route
+ * beside its route instead: along the segment leaving its endpoint first,
+ * then along later segments, at the first spot clear of all three, or else
+ * the spot with the fewest collisions, nodes and labels weighing most.
+ */
+export function placeEndLabels<E extends ExteriorLabelEdge>({
+  edges,
+  nodeRects,
+  spacing,
+  placement,
+  inline,
+}: PlaceEndLabelsInput<E>): void {
+  const labelled = edges.filter((edge) => edge.width > 0 && edge.height > 0);
+  // Covering a node or another label hides content; a route through a label hides less.
+  const conflicts = (edge: E, box: EntityRect) =>
+    2 * nodeRects.filter((rect) => overlaps(box, rect)).length +
+    2 * labelled.filter((other) => other !== edge && overlaps(box, other)).length +
+    edges.filter((other) => crosses(other.points, box)).length;
+  for (const edge of labelled) {
+    const end = placement(edge);
+    // A CENTER label moves only off a node, another label or another route,
+    // to the clear spot nearest its own.
+    const center = end === "CENTER" && !inline(edge);
+    if (end !== "HEAD" && end !== "TAIL" && !center) continue;
+    const { width, height } = edge;
+    let best = { x: edge.x, y: edge.y, conflicts: conflicts(edge, edge), distance: 0 };
+    if (best.conflicts === 0) continue;
+    if (center && best.conflicts === Number(crosses(edge.points, edge))) continue;
+    const route = end === "HEAD" ? edge.points.toReversed() : edge.points;
+    // Beside each segment from the endpoint on, hugging the route before stepping away from it.
+    search: for (let lateral = spacing; lateral <= spacing + 64; lateral += 8)
+      for (let index = 1; index < route.length; index++) {
+        const a = route[index - 1]!,
+          b = route[index]!;
+        const dx = b.x - a.x,
+          dy = b.y - a.y;
+        if (dx === 0 && dy === 0) continue;
+        const along = Math.abs(dx) >= Math.abs(dy);
+        const length = along ? Math.abs(dx) : Math.abs(dy);
+        const size = along ? width : height;
+        const step = Math.max(4, (length - size) / 16);
+        // Slide from the segment's first point toward its last, below or right first, as ELK does.
+        for (
+          let offset = spacing;
+          offset <= Math.max(spacing, length - size - spacing);
+          offset += step
+        ) {
+          const boxes = along
+            ? [a.y + lateral, a.y - lateral - height].map((y) => ({
+                x: dx > 0 ? a.x + offset : a.x - offset - width,
+                y,
+                width,
+                height,
+              }))
+            : [a.x + lateral, a.x - lateral - width].map((x) => ({
+                x,
+                y: dy > 0 ? a.y + offset : a.y - offset - height,
+                width,
+                height,
+              }));
+          for (const box of boxes) {
+            const count = conflicts(edge, box);
+            const distance = Math.abs(box.x - edge.x) + Math.abs(box.y - edge.y);
+            if (
+              count < best.conflicts ||
+              (center && count === best.conflicts && distance < best.distance)
+            )
+              best = { x: box.x, y: box.y, conflicts: count, distance };
+            if (count === 0 && !center) break search;
+          }
+        }
+      }
+    // Without a clear spot, the spot with the fewest collisions.
+    edge.x = best.x;
+    edge.y = best.y;
+  }
+}

package/src/layered/external-port-dummy.ts

@@ -0,0 +1,137 @@
+/*
+ * Copyright (c) 2011, 2020 Kiel University and others.
+ * Native adaptation of ELK LGraphUtil.createExternalPortDummy, elkjs 0.11.1.
+ * SPDX-License-Identifier: EPL-2.0
+ */
+import type { Point } from "@statelyai/graph";
+
+export type ExternalPortSide = "WEST" | "EAST" | "NORTH" | "SOUTH";
+export type ExternalPortConstraints =
+  | "UNDEFINED"
+  | "FREE"
+  | "FIXED_SIDE"
+  | "FIXED_ORDER"
+  | "FIXED_RATIO"
+  | "FIXED_POS";
+export interface ExternalPortDummyInput {
+  constraints: ExternalPortConstraints;
+  side: ExternalPortSide;
+  direction: "RIGHT" | "LEFT" | "DOWN" | "UP";
+  netFlow: number;
+  borderOffset: number;
+  size: { width: number; height: number };
+  ownerSize?: { width: number; height: number };
+  position?: Point;
+  anchor?: Point;
+  index?: number;
+}
+export interface ExternalPortDummy {
+  type: "EXTERNAL_PORT";
+  /** Parent-scope port identity for a reused compound endpoint. */
+  parentPortId?: string;
+  constraints: "FIXED_POS";
+  side: ExternalPortSide;
+  borderOffset: number;
+  externalSize: { width: number; height: number };
+  width: number;
+  height: number;
+  port: { side: ExternalPortSide; x: number; y: number };
+  anchor: Point;
+  layerConstraint?: "FIRST_SEPARATE" | "LAST_SEPARATE";
+  edgeConstraint?: "OUTGOING_ONLY" | "INCOMING_ONLY";
+  inLayerConstraint?: "TOP" | "BOTTOM";
+  ratioOrPosition?: number;
+}
+const opposite: Record<ExternalPortSide, ExternalPortSide> = {
+  WEST: "EAST",
+  EAST: "WEST",
+  NORTH: "SOUTH",
+  SOUTH: "NORTH",
+};
+
+/** Preserve the upstream pre-direction-transform external boundary representation. */
+export function createExternalPortDummy(input: ExternalPortDummyInput): ExternalPortDummy {
+  const forward = ({ RIGHT: "EAST", LEFT: "WEST", DOWN: "SOUTH", UP: "NORTH" } as const)[
+    input.direction
+  ];
+  const side =
+    input.constraints === "FREE" || input.constraints === "UNDEFINED"
+      ? input.netFlow >= 0
+        ? forward
+        : opposite[forward]
+      : input.side;
+  const anchor = input.anchor
+    ? { ...input.anchor }
+    : { x: input.size.width / 2, y: input.size.height / 2 };
+  const result: ExternalPortDummy = {
+    type: "EXTERNAL_PORT",
+    constraints: "FIXED_POS",
+    side,
+    borderOffset: input.borderOffset,
+    externalSize: { ...input.size },
+    width: 0,
+    height: 0,
+    port: { side: opposite[side], x: 0, y: 0 },
+    anchor,
+  };
+  const depth = input.borderOffset < 0 ? -input.borderOffset : 0;
+  switch (side) {
+    case "WEST":
+      result.layerConstraint = "FIRST_SEPARATE";
+      result.edgeConstraint = "OUTGOING_ONLY";
+      result.height = input.size.height;
+      result.width = depth;
+      if (!input.anchor) anchor.x = input.size.width;
+      anchor.x -= input.size.width;
+      break;
+    case "EAST":
+      result.layerConstraint = "LAST_SEPARATE";
+      result.edgeConstraint = "INCOMING_ONLY";
+      result.height = input.size.height;
+      result.width = depth;
+      if (!input.anchor) anchor.x = 0;
+      break;
+    case "NORTH":
+      result.inLayerConstraint = "TOP";
+      result.width = input.size.width;
+      result.height = depth;
+      if (!input.anchor) anchor.y = input.size.height;
+      anchor.y -= input.size.height;
+      break;
+    case "SOUTH":
+      result.inLayerConstraint = "BOTTOM";
+      result.width = input.size.width;
+      result.height = depth;
+      if (!input.anchor) anchor.y = 0;
+      break;
+  }
+  result.port.x = anchor.x;
+  result.port.y = anchor.y;
+  if (
+    input.constraints === "FIXED_ORDER" ||
+    input.constraints === "FIXED_RATIO" ||
+    input.constraints === "FIXED_POS"
+  ) {
+    let information = 0;
+    if (input.constraints === "FIXED_ORDER" && input.index !== undefined) {
+      information = side === "NORTH" || side === "EAST" ? input.index : -input.index;
+    } else {
+      const horizontalSide = side === "WEST" || side === "EAST";
+      information = horizontalSide ? input.position!.y : input.position!.x;
+      if (input.constraints === "FIXED_RATIO")
+        information /= horizontalSide ? input.ownerSize!.height : input.ownerSize!.width;
+    }
+    result.ratioOrPosition = information;
+  }
+  return result;
+}
+
+// Symbols survive native phase object spreads without becoming public JSON fields.
+const externalPortDummyOrigin = Symbol("externalPortDummyOrigin");
+export function attachExternalPortDummy<T extends object>(node: T, origin: ExternalPortDummy): T {
+  Object.defineProperty(node, externalPortDummyOrigin, { value: origin, enumerable: true });
+  return node;
+}
+export function externalPortDummyOf(node: object): ExternalPortDummy | undefined {
+  return (node as { [externalPortDummyOrigin]?: ExternalPortDummy })[externalPortDummyOrigin];
+}

package/src/layered/feedback-chains.ts

@@ -0,0 +1,114 @@
+import type { EntityRect, Point } from "@statelyai/graph";
+
+export interface FeedbackChain {
+  edgeId: string;
+  /** Center-label dummy on the chain and the cross coordinate where the route meets it. */
+  label?: { id: string; cross: number };
+}
+
+/** Whether two orthogonal polylines run along one line in opposite directions. */
+function opposed(a: readonly Point[], b: readonly Point[]): boolean {
+  for (let i = 1; i < a.length; i++)
+    for (let j = 1; j < b.length; j++) {
+      const s = { a: a[i - 1]!, b: a[i]! },
+        t = { a: b[j - 1]!, b: b[j]! };
+      const dx = s.b.x - s.a.x,
+        dy = s.b.y - s.a.y;
+      if (dx * (t.b.x - t.a.x) + dy * (t.b.y - t.a.y) >= 0) continue;
+      const along = dx !== 0 ? "x" : "y",
+        across = along === "x" ? "y" : "x";
+      if (dx !== 0 && dy !== 0) continue;
+      if (s.a[across] !== s.b[across] || t.a[across] !== t.b[across]) continue;
+      if (Math.abs(s.a[across] - t.a[across]) > 1e-6) continue;
+      const lo = Math.max(Math.min(s.a[along], s.b[along]), Math.min(t.a[along], t.b[along]));
+      const hi = Math.min(Math.max(s.a[along], s.b[along]), Math.max(t.a[along], t.b[along]));
+      if (hi - lo > 1e-6) return true;
+    }
+  return false;
+}
+
+/**
+ * A reversed feedback edge split by label or inverted-port dummies is routed
+ * one segment at a time, so each segment detours to the outer feedback track
+ * and back to the next dummy. Rejoin the chain as one track: the label's own
+ * track, or the outer track with the label moved onto it, whichever is clear.
+ */
+export function straightenFeedbackChains(
+  chains: readonly FeedbackChain[],
+  pointsByEdgeId: Map<string, readonly Point[]>,
+  rectByNodeId: Map<string, EntityRect>,
+  horizontal: boolean,
+): void {
+  const cross = (p: Point) => (horizontal ? p.y : p.x);
+  const flow = (p: Point) => (horizontal ? p.x : p.y);
+  const at = (f: number, c: number): Point => (horizontal ? { x: f, y: c } : { x: c, y: f });
+  const overlaps = (a: EntityRect, b: EntityRect) =>
+    a.x < b.x + b.width && b.x < a.x + a.width && a.y < b.y + b.height && b.y < a.y + a.height;
+  // Degenerate boxes still hit a rect whose interior they pass through.
+  const hits = (a: Point, b: Point, rect: EntityRect) =>
+    rect.width > 0 &&
+    rect.height > 0 &&
+    Math.min(a.x, b.x) < rect.x + rect.width &&
+    Math.max(a.x, b.x) > rect.x &&
+    Math.min(a.y, b.y) < rect.y + rect.height &&
+    Math.max(a.y, b.y) > rect.y;
+  for (const { edgeId, label } of chains) {
+    const points = pointsByEdgeId.get(edgeId);
+    if (!points || points.length < 6) continue;
+    const [start, lead] = points as [Point, Point];
+    const tail = points.at(-2)!,
+      end = points.at(-1)!;
+    const outer = Math.max(...points.map(cross));
+    const labelRect = label && rectByNodeId.get(label.id);
+    for (const track of label ? [label.cross, outer] : [outer]) {
+      const route = [start, lead, at(flow(lead), track), at(flow(tail), track), tail, end];
+      const moved = labelRect && {
+        ...labelRect,
+        ...(horizontal
+          ? { y: labelRect.y + track - label!.cross }
+          : { x: labelRect.x + track - label!.cross }),
+      };
+      const blocked = [...rectByNodeId].some(
+        ([id, rect]) =>
+          id !== label?.id &&
+          (route.slice(1, 4).some((point, index) => hits(point, route[index + 2]!, rect)) ||
+            (moved !== undefined && overlaps(moved, rect))),
+      );
+      const crossed =
+        moved !== undefined &&
+        track !== label!.cross &&
+        [...pointsByEdgeId].some(
+          ([id, other]) =>
+            id !== edgeId &&
+            other.some((point, index) => index > 0 && hits(other[index - 1]!, point, moved)),
+        );
+      if (blocked || crossed) continue;
+      const simple: Point[] = [];
+      for (const point of route) {
+        const previous = simple.at(-1),
+          before = simple.at(-2);
+        if (previous && previous.x === point.x && previous.y === point.y) continue;
+        if (
+          previous &&
+          before &&
+          ((before.x === previous.x && previous.x === point.x) ||
+            (before.y === previous.y && previous.y === point.y))
+        ) {
+          // A collinear turnaround folds the route back onto itself.
+          if ((previous.x - before.x) * (point.x - previous.x) < 0) break;
+          if ((previous.y - before.y) * (point.y - previous.y) < 0) break;
+          simple.pop();
+        }
+        simple.push(point);
+      }
+      if (simple.at(-1) !== end) continue;
+      if (simple.length >= points.length) break;
+      // Never share a track with another route heading the opposite way.
+      if ([...pointsByEdgeId].some(([id, other]) => id !== edgeId && opposed(simple, other)))
+        continue;
+      pointsByEdgeId.set(edgeId, simple);
+      if (moved) rectByNodeId.set(label!.id, moved);
+      break;
+    }
+  }
+}

package/src/layered/fixed-self-loop.ts

@@ -0,0 +1,150 @@
+/* Native fixed-port perimeter routing following ELK self-loop semantics. SPDX-License-Identifier: EPL-2.0 */
+import type { EntityRect, GraphEdge, Point } from "@statelyai/graph";
+import type { LayoutDirection } from "../types";
+type Side = "NORTH" | "EAST" | "SOUTH" | "WEST";
+
+export function fixedSelfLoopSide(value: string | undefined): Side | undefined {
+  return value === "NORTH" || value === "EAST" || value === "SOUTH" || value === "WEST"
+    ? value
+    : undefined;
+}
+
+/** Route fixed anchors around the perimeter; never replace a port with a default loop anchor. */
+export function routeFixedSelfLoop(
+  rect: EntityRect,
+  start: Point,
+  end: Point,
+  sourceSide: Side,
+  targetSide: Side,
+  distance: number,
+  direction: LayoutDirection,
+): Point[] {
+  const horizontal = direction === "right" || direction === "left";
+  const width = horizontal ? rect.width : rect.height;
+  const height = horizontal ? rect.height : rect.width;
+  const reverse = direction === "left" || direction === "up";
+  const canonical = (p: Point): Point => {
+    const flow = horizontal ? p.x - rect.x : p.y - rect.y;
+    return { x: reverse ? width - flow : flow, y: horizontal ? p.y - rect.y : p.x - rect.x };
+  };
+  const physical = (p: Point): Point => {
+    const flow = reverse ? width - p.x : p.x;
+    return { x: rect.x + (horizontal ? flow : p.y), y: rect.y + (horizontal ? p.y : flow) };
+  };
+  const side = (s: Side): Side => {
+    const vectors = {
+      NORTH: { x: 0, y: -1 },
+      EAST: { x: 1, y: 0 },
+      SOUTH: { x: 0, y: 1 },
+      WEST: { x: -1, y: 0 },
+    };
+    const v = vectors[s];
+    const flow = (horizontal ? v.x : v.y) * (reverse ? -1 : 1);
+    const cross = horizontal ? v.y : v.x;
+    return flow > 0 ? "EAST" : flow < 0 ? "WEST" : cross > 0 ? "SOUTH" : "NORTH";
+  };
+  const a = canonical(start),
+    b = canonical(end);
+  const from = side(sourceSide),
+    to = side(targetSide);
+  const outward = (p: Point, s: Side): Point => ({
+    x:
+      s === "WEST"
+        ? Math.min(0, p.x) - distance
+        : s === "EAST"
+          ? Math.max(width, p.x) + distance
+          : p.x,
+    y:
+      s === "NORTH"
+        ? Math.min(0, p.y) - distance
+        : s === "SOUTH"
+          ? Math.max(height, p.y) + distance
+          : p.y,
+  });
+  const first = outward(a, from),
+    last = outward(b, to);
+  // A loop on a single port closes a small square beside the port instead of
+  // retracing its own outward segment.
+  if (from === to && a.x === b.x && a.y === b.y) {
+    const alongY = from === "WEST" || from === "EAST";
+    const step = (alongY ? a.y < height / 2 : a.x < width / 2) ? distance : -distance;
+    const shift = (p: Point): Point =>
+      alongY ? { x: p.x, y: p.y + step } : { x: p.x + step, y: p.y };
+    return [a, first, shift(first), shift(b), b].map(physical);
+  }
+  const points = [a, first];
+  if (from !== to) {
+    const verticalFrom = from === "WEST" || from === "EAST";
+    const verticalTo = to === "WEST" || to === "EAST";
+    if (verticalFrom !== verticalTo) {
+      points.push(verticalFrom ? { x: first.x, y: last.y } : { x: last.x, y: first.y });
+    } else if (verticalFrom) {
+      points.push({ x: first.x, y: height + distance }, { x: last.x, y: height + distance });
+    } else {
+      const track = from === "SOUTH" ? -distance : width + distance;
+      points.push({ x: track, y: first.y }, { x: track, y: last.y });
+    }
+  }
+  points.push(last, b);
+  return points.map(physical);
+}
+
+/**
+ * Spots for a same-side loop's label beyond its outer segment: centered on
+ * the loop, then flush with either end of it so the label clears edges that
+ * meet the loop's ports along their port lines.
+ */
+export function fixedSelfLoopLabels(
+  points: readonly Point[],
+  side: Side,
+  width: number,
+  height: number,
+  spacing: number,
+): Point[] {
+  const xs = points.map((p) => p.x),
+    ys = points.map((p) => p.y);
+  const [left, right, top, bottom] = [
+    Math.min(...xs),
+    Math.max(...xs),
+    Math.min(...ys),
+    Math.max(...ys),
+  ];
+  if (side === "EAST" || side === "WEST") {
+    const x = side === "EAST" ? right + spacing : left - spacing - width;
+    return [(top + bottom - height) / 2, top + spacing, bottom - spacing - height].map((y) => ({
+      x,
+      y,
+    }));
+  }
+  const y = side === "SOUTH" ? bottom + spacing : top - spacing - height;
+  return [(left + right - width) / 2, left + spacing, right - spacing - width].map((x) => ({
+    x,
+    y,
+  }));
+}
+
+/**
+ * ELK combines self loops that share a port into one self hyperloop routed on
+ * a single track. Returns each loop's track index, in order of first loop.
+ */
+export function selfLoopTracks(loops: readonly GraphEdge[]): Map<string, number> {
+  const parent = loops.map((_, index) => index);
+  const root = (index: number): number =>
+    parent[index] === index ? index : (parent[index] = root(parent[index]!));
+  const ownerByPort = new Map<string, number>();
+  for (const [index, loop] of loops.entries())
+    for (const port of [loop.sourcePort, loop.targetPort]) {
+      if (port === undefined) continue;
+      const other = ownerByPort.get(port);
+      if (other === undefined) ownerByPort.set(port, index);
+      else parent[root(index)] = root(other);
+    }
+  const trackByRoot = new Map<number, number>();
+  return new Map(
+    loops.map((loop, index) => {
+      const group = root(index);
+      if (!trackByRoot.has(group)) trackByRoot.set(group, trackByRoot.size);
+      return [loop.id, trackByRoot.get(group)!];
+    }),
+  );
+}