@statelyai/layout 0.1.2 → 0.2.0

package/src/authoring/routing.ts

@@ -0,0 +1,211 @@
+import type { EntityRect, Point, VisualNode, GraphEdge } from "@statelyai/graph";
+import { LayoutError } from "../errors";
+import type { LayoutDirection } from "../types";
+
+export function overlaps(a: EntityRect, b: EntityRect, gap = 0): boolean {
+  return (
+    a.width > 0 &&
+    a.height > 0 &&
+    b.width > 0 &&
+    b.height > 0 &&
+    a.x < b.x + b.width + gap &&
+    a.x + a.width + gap > b.x &&
+    a.y < b.y + b.height + gap &&
+    a.y + a.height + gap > b.y
+  );
+}
+
+/** Open-interior intersection: travelling along a rectangle boundary is allowed. */
+export function crossesRect(a: Point, b: Point, rect: EntityRect): boolean {
+  let low = 0,
+    high = 1;
+  for (const axis of ["x", "y"] as const) {
+    const delta = b[axis] - a[axis];
+    const min = rect[axis],
+      max = min + (axis === "x" ? rect.width : rect.height);
+    if (Math.abs(delta) < 1e-10) {
+      if (a[axis] <= min || a[axis] >= max) return false;
+    } else {
+      const t1 = (min - a[axis]) / delta,
+        t2 = (max - a[axis]) / delta;
+      low = Math.max(low, Math.min(t1, t2));
+      high = Math.min(high, Math.max(t1, t2));
+    }
+  }
+  return low < high - 1e-10;
+}
+
+export function routeCrosses(points: readonly Point[] | undefined, rect: EntityRect): boolean {
+  return points?.some((point, i) => i > 0 && crossesRect(points[i - 1]!, point, rect)) ?? false;
+}
+
+export function endpoint(
+  node: VisualNode,
+  portName: string | undefined,
+  direction: LayoutDirection,
+  source: boolean,
+): Point {
+  if (portName !== undefined) {
+    const port = node.ports?.find((p) => p.name === portName);
+    if (port?.x !== undefined && port.y !== undefined) {
+      return {
+        x: node.x + port.x + (port.width ?? 0) / 2,
+        y: node.y + port.y + (port.height ?? 0) / 2,
+      };
+    }
+    throw new LayoutError(
+      `Port ${portName} on ${node.id} requires positioned geometry`,
+      "MISSING_GEOMETRY",
+    );
+  }
+  const horizontal = direction === "left" || direction === "right";
+  const forward = direction === "right" || direction === "down";
+  const far = source === forward;
+  return horizontal
+    ? { x: node.x + (far ? node.width : 0), y: node.y + node.height / 2 }
+    : { x: node.x + node.width / 2, y: node.y + (far ? node.height : 0) };
+}
+
+/** Deterministic orthogonal visibility-grid search around fixed rectangles. */
+function connect(
+  start: Point,
+  end: Point,
+  obstacles: readonly EntityRect[],
+  check: () => void,
+): Point[] | undefined {
+  if (start.x === end.x && start.y === end.y) return [start];
+  // Distant geometry must not exhaust the local grid budget. Each attempt still
+  // collision-checks against the entire scene, including excluded rectangles.
+  for (let attempt = 0; attempt < 8; attempt++) {
+    check();
+    const margin = 64 * 2 ** attempt;
+    const left = Math.min(start.x, end.x) - margin;
+    const right = Math.max(start.x, end.x) + margin;
+    const top = Math.min(start.y, end.y) - margin;
+    const bottom = Math.max(start.y, end.y) + margin;
+    const local = obstacles.filter(
+      (r) => r.x <= right && r.x + r.width >= left && r.y <= bottom && r.y + r.height >= top,
+    );
+    const result = search(start, end, local, obstacles, check);
+    if (result || local.length === obstacles.length) return result;
+  }
+  return undefined;
+}
+
+function search(
+  start: Point,
+  end: Point,
+  gridObstacles: readonly EntityRect[],
+  obstacles: readonly EntityRect[],
+  check: () => void,
+): Point[] | undefined {
+  const xs = [
+    ...new Set([start.x, end.x, ...gridObstacles.flatMap((r) => [r.x, r.x + r.width])]),
+  ].sort((a, b) => a - b);
+  const ys = [
+    ...new Set([start.y, end.y, ...gridObstacles.flatMap((r) => [r.y, r.y + r.height])]),
+  ].sort((a, b) => a - b);
+  // Bound interactive work; the caller returns a diagnostic without inventing a route.
+  if (xs.length * ys.length > 40000) return undefined;
+  const width = xs.length;
+  const point = (id: number): Point => ({ x: xs[id % width]!, y: ys[Math.floor(id / width)]! });
+  const from = ys.indexOf(start.y) * width + xs.indexOf(start.x);
+  const to = ys.indexOf(end.y) * width + xs.indexOf(end.x);
+  const distances = new Map<number, number>([[from, 0]]);
+  const previous = new Map<number, number>();
+  const queue: { id: number; cost: number }[] = [];
+  function push(item: { id: number; cost: number }) {
+    queue.push(item);
+    let i = queue.length - 1;
+    while (i > 0) {
+      const parent = (i - 1) >> 1;
+      if (queue[parent]!.cost <= item.cost) break;
+      queue[i] = queue[parent]!;
+      i = parent;
+    }
+    queue[i] = item;
+  }
+  function pop() {
+    const first = queue[0]!;
+    const last = queue.pop()!;
+    if (queue.length) {
+      let i = 0;
+      while (i * 2 + 1 < queue.length) {
+        let child = i * 2 + 1;
+        if (child + 1 < queue.length && queue[child + 1]!.cost < queue[child]!.cost) child++;
+        if (last.cost <= queue[child]!.cost) break;
+        queue[i] = queue[child]!;
+        i = child;
+      }
+      queue[i] = last;
+    }
+    return first;
+  }
+  push({ id: from, cost: 0 });
+  let visits = 0;
+  while (queue.length) {
+    if (++visits % 128 === 0) check();
+    const current = pop();
+    if (current.cost !== distances.get(current.id)) continue;
+    if (current.id === to) {
+      const result = [end];
+      let id = to;
+      while (id !== from) {
+        id = previous.get(id)!;
+        result.push(point(id));
+      }
+      return result.reverse();
+    }
+    const x = current.id % width,
+      y = Math.floor(current.id / width);
+    const neighbors = [
+      x > 0 ? current.id - 1 : -1,
+      x + 1 < width ? current.id + 1 : -1,
+      y > 0 ? current.id - width : -1,
+      y + 1 < ys.length ? current.id + width : -1,
+    ];
+    const a = point(current.id);
+    for (const next of neighbors) {
+      if (next < 0) continue;
+      const b = point(next);
+      if (obstacles.some((rect) => crossesRect(a, b, rect))) continue;
+      const cost = current.cost + Math.abs(a.x - b.x) + Math.abs(a.y - b.y);
+      if (cost >= (distances.get(next) ?? Infinity)) continue;
+      distances.set(next, cost);
+      previous.set(next, current.id);
+      push({ id: next, cost });
+    }
+  }
+  return undefined;
+}
+
+export function routeOrthogonal(
+  edge: GraphEdge,
+  source: VisualNode,
+  target: VisualNode,
+  direction: LayoutDirection,
+  obstacles: readonly EntityRect[],
+  waypoints: readonly Point[],
+  check: () => void,
+): Point[] | undefined {
+  const anchors = [
+    endpoint(source, edge.sourcePort, direction, true),
+    ...waypoints,
+    endpoint(target, edge.targetPort, direction, false),
+  ];
+  const points: Point[] = [];
+  for (let i = 1; i < anchors.length; i++) {
+    const segment = connect(anchors[i - 1]!, anchors[i]!, obstacles, check);
+    if (!segment) return undefined;
+    points.push(...(points.length ? segment.slice(1) : segment));
+  }
+  return points.filter((p, i) => {
+    if (i === 0 || i === points.length - 1) return true;
+    const before = points[i - 1]!,
+      after = points[i + 1]!;
+    return !(
+      (before.x === p.x && p.x === after.x && (p.y - before.y) * (after.y - p.y) >= 0) ||
+      (before.y === p.y && p.y === after.y && (p.x - before.x) * (after.x - p.x) >= 0)
+    );
+  });
+}

package/src/box.ts

@@ -8,6 +8,7 @@
 import type { Graph, GraphNode, VisualGraph, VisualNode } from "@statelyai/graph";
 import { getNodeSize, type LayoutOptions } from "@statelyai/graph/layout";
 import { getFixedLayout } from "./fixed";
+import { setElkjs0111ResultPolicy } from "./internal/elkjs-compatibility";
 import type { LayoutPadding } from "./layered";
 import type { LayoutAlgorithm } from "./types";
 
@@ -133,3 +134,24 @@ export const boxAlgorithm: LayoutAlgorithm<BoxLayoutOptions> = {
     return getBoxLayout(graph, options ?? {});
   },
 };
+
+/** Pinned behavior used only by the elkjs 0.11.1 compatibility adapter. */
+export const elkjs0111BoxAlgorithm: LayoutAlgorithm<BoxLayoutOptions> = {
+  ...boxAlgorithm,
+  layout(graph, options = {}) {
+    const result = getBoxLayout(graph, options);
+    const padding = getPadding(options.padding);
+    return setElkjs0111ResultPolicy(result, {
+      providerBounds:
+        result.nodes.length === 0
+          ? { width: 0, height: 0 }
+          : {
+              width: Math.max(...result.nodes.map((node) => node.x + node.width)) + padding.right,
+              height:
+                Math.max(...result.nodes.map((node) => node.y + node.height)) + padding.bottom,
+            },
+      preserveEdgeSections: true,
+      skipBoundsNormalization: true,
+    });
+  },
+};

package/src/constraints.ts

@@ -0,0 +1,222 @@
+import { Constraint, Expression, Operator, Solver, Strength, Variable } from "@lume/kiwi";
+import type { VisualGraph } from "@statelyai/graph";
+import { LayoutError } from "./errors";
+import type { LayoutDiagnostic } from "./types";
+
+export type GeometryReference = { nodeId: string } | { edgeId: string; part: "label" };
+export type ConstraintStrength = "required" | "strong" | "medium" | "weak";
+export type GeometryAttribute = "x" | "y" | "centerX" | "centerY" | "right" | "bottom";
+interface ConstraintBase {
+  id: string;
+  strength?: ConstraintStrength;
+}
+export interface AlignConstraint extends ConstraintBase {
+  kind: "align";
+  entities: readonly GeometryReference[];
+  axis: "x" | "y";
+  anchor?: "start" | "center" | "end";
+}
+export interface DistributeConstraint extends ConstraintBase {
+  kind: "distribute";
+  entities: readonly GeometryReference[];
+  axis: "x" | "y";
+  spacing?: "gaps" | "centers";
+  gap?: number;
+}
+export interface PinConstraint extends ConstraintBase {
+  kind: "pin";
+  entity: GeometryReference;
+  x?: number;
+  y?: number;
+}
+export interface LinearConstraint extends ConstraintBase {
+  kind: "linear";
+  terms: readonly {
+    entity: GeometryReference;
+    attribute: GeometryAttribute;
+    coefficient: number;
+  }[];
+  relation: "eq" | "le" | "ge";
+  value: number;
+}
+export interface WaypointConstraint extends ConstraintBase {
+  kind: "waypoint";
+  edgeId: string;
+  point: { x: number; y: number };
+}
+export type LayoutConstraint =
+  | AlignConstraint
+  | DistributeConstraint
+  | PinConstraint
+  | LinearConstraint
+  | WaypointConstraint;
+
+/** Serializable constraint constructors; graph geometry stays in @statelyai/graph. */
+export const c = {
+  align: (value: Omit<AlignConstraint, "kind">): AlignConstraint => ({ ...value, kind: "align" }),
+  distribute: (value: Omit<DistributeConstraint, "kind">): DistributeConstraint => ({
+    ...value,
+    kind: "distribute",
+  }),
+  pin: (value: Omit<PinConstraint, "kind">): PinConstraint => ({ ...value, kind: "pin" }),
+  linear: (value: Omit<LinearConstraint, "kind">): LinearConstraint => ({
+    ...value,
+    kind: "linear",
+  }),
+  waypoint: (value: Omit<WaypointConstraint, "kind">): WaypointConstraint => ({
+    ...value,
+    kind: "waypoint",
+  }),
+};
+
+export function constraintFailure(constraint: LayoutConstraint, message: string): never {
+  throw new LayoutError(`${constraint.id}: ${message}`, "UNSATISFIED_CONSTRAINT");
+}
+
+/** Solve positions only. Fixed geometry is represented by constants, never edit variables. */
+export function solveGeometryConstraints<N, E, G, P>(
+  graph: VisualGraph<N, E, G, P>,
+  constraints: readonly LayoutConstraint[],
+  movableNodes: ReadonlySet<string>,
+  movableLabels: ReadonlySet<string>,
+  diagnostics: LayoutDiagnostic[],
+): VisualGraph<N, E, G, P> {
+  const solver = new Solver();
+  const variables = new Map<string, { x: Variable; y: Variable }>();
+  const nodes = new Map(graph.nodes.map((n) => [n.id, n]));
+  const edges = new Map(graph.edges.map((e) => [e.id, e]));
+  function geometry(ref: GeometryReference) {
+    const node = "nodeId" in ref;
+    const id = node ? ref.nodeId : ref.edgeId;
+    const rect = node ? nodes.get(id) : edges.get(id);
+    if (!rect) throw new LayoutError(`Unknown constraint entity: ${id}`, "INVALID_CONSTRAINT");
+    const key = JSON.stringify([node ? "node" : "label", id]);
+    const movable = (node ? movableNodes : movableLabels).has(id);
+    if (movable && !variables.has(key)) {
+      const pair = { x: new Variable(`${key}.x`), y: new Variable(`${key}.y`) };
+      variables.set(key, pair);
+      solver.addConstraint(new Constraint(pair.x, Operator.Eq, rect.x, Strength.weak / 10));
+      solver.addConstraint(new Constraint(pair.y, Operator.Eq, rect.y, Strength.weak / 10));
+    }
+    return { rect, variables: variables.get(key) };
+  }
+  function expression(ref: GeometryReference, attribute: GeometryAttribute): Expression {
+    const { rect, variables: pair } = geometry(ref);
+    const axis = attribute === "y" || attribute === "centerY" || attribute === "bottom" ? "y" : "x";
+    const extent = axis === "x" ? rect.width : rect.height;
+    const offset = attribute.startsWith("center")
+      ? extent / 2
+      : attribute === "right" || attribute === "bottom"
+        ? extent
+        : 0;
+    return new Expression(pair?.[axis] ?? rect[axis], offset);
+  }
+  const checks: { constraint: LayoutConstraint; expression: Expression; operator: Operator }[] = [];
+  const ids = new Set<string>();
+  for (const constraint of constraints) {
+    if (ids.has(constraint.id))
+      throw new LayoutError(`Duplicate constraint ID: ${constraint.id}`, "INVALID_CONSTRAINT");
+    ids.add(constraint.id);
+    if (constraint.kind === "waypoint") continue;
+    const strength = Strength[constraint.strength ?? "required"];
+    const add = (lhs: Expression, operator = Operator.Eq, rhs: Expression | number = 0) => {
+      const difference = lhs.minus(rhs);
+      if (
+        !Number.isFinite(difference.constant()) ||
+        !difference.terms().array.every((item) => Number.isFinite(item.second))
+      ) {
+        throw new LayoutError(`${constraint.id}: non-finite expression`, "INVALID_CONSTRAINT");
+      }
+      try {
+        solver.addConstraint(new Constraint(difference, operator, 0, strength));
+      } catch {
+        constraintFailure(
+          constraint,
+          "conflicts with fixed geometry or another required constraint",
+        );
+      }
+      checks.push({ constraint, expression: difference, operator });
+    };
+    if (constraint.kind === "linear") {
+      let value = new Expression();
+      for (const term of constraint.terms)
+        value = value.plus(expression(term.entity, term.attribute).multiply(term.coefficient));
+      add(
+        value,
+        { eq: Operator.Eq, le: Operator.Le, ge: Operator.Ge }[constraint.relation],
+        constraint.value,
+      );
+    } else if (constraint.kind === "pin") {
+      geometry(constraint.entity);
+      if (constraint.x !== undefined)
+        add(expression(constraint.entity, "x"), Operator.Eq, constraint.x);
+      if (constraint.y !== undefined)
+        add(expression(constraint.entity, "y"), Operator.Eq, constraint.y);
+    } else {
+      const refs = constraint.entities;
+      // Validate even a singleton reference.
+      for (const ref of refs) geometry(ref);
+      const axis = constraint.axis;
+      const end = axis === "x" ? "right" : "bottom";
+      const center = axis === "x" ? "centerX" : "centerY";
+      if (constraint.kind === "align") {
+        const attr =
+          constraint.anchor === "start" ? axis : constraint.anchor === "end" ? end : center;
+        for (const ref of refs.slice(1))
+          add(expression(ref, attr), Operator.Eq, expression(refs[0]!, attr));
+      } else {
+        const gaps = refs
+          .slice(1)
+          .map((ref, i) =>
+            constraint.spacing === "centers"
+              ? expression(ref, center).minus(expression(refs[i]!, center))
+              : expression(ref, axis).minus(expression(refs[i]!, end)),
+          );
+        for (const gap of gaps) {
+          add(gap, Operator.Ge, 0);
+          add(gap, Operator.Eq, constraint.gap ?? gaps[0]!);
+        }
+      }
+    }
+  }
+  solver.updateVariables();
+  const warned = new Set<string>();
+  for (const check of checks) {
+    const residual = check.expression.value();
+    const violated =
+      check.operator === Operator.Eq
+        ? Math.abs(residual) > 1e-6
+        : check.operator === Operator.Le
+          ? residual > 1e-6
+          : residual < -1e-6;
+    if (violated && !warned.has(check.constraint.id)) {
+      warned.add(check.constraint.id);
+      diagnostics.push({
+        severity: "warning",
+        code: "CONSTRAINT_VIOLATION",
+        message: `Constraint ${check.constraint.id} could not be satisfied`,
+        constraintIds: [check.constraint.id],
+      });
+    }
+  }
+  const coordinate = (variable: Variable): number => {
+    const value = variable.value();
+    if (!Number.isFinite(value))
+      throw new LayoutError(
+        "Constraint solution contains non-finite geometry",
+        "INVALID_CONSTRAINT",
+      );
+    return value === 0 ? 0 : value;
+  };
+  return {
+    ...graph,
+    nodes: graph.nodes.map((node) => {
+      const pair = variables.get(JSON.stringify(["node", node.id]));
+      return pair ? { ...node, x: coordinate(pair.x), y: coordinate(pair.y) } : node;
+    }),
+    edges: graph.edges.map((edge) => {
+      const pair = variables.get(JSON.stringify(["label", edge.id]));
+      return pair ? { ...edge, x: coordinate(pair.x), y: coordinate(pair.y) } : edge;
+    }),
+  };
+}