@statelyai/layout 0.4.2 → 0.5.0

package/src/routing/engine.ts

@@ -1,4 +1,5 @@
 import type { GraphDiff } from "@statelyai/graph";
+import { expandLabelFamilies, labelFamily, routeBezierEdge } from "./bezier";
 import { conflictCost, reservations, reservationBounds, outsideTerminal } from "./coordination";
 import { segmentBounds } from "./search";
 import { routeBounds, routeEdge, type Metrics, type Batch } from "./algorithms";
@@ -6,7 +7,8 @@ import {
   edgeGeometry,
   freeze,
   groupKey,
-  labelRect,
+  obstacleLabelRect,
+  effectivePolicy,
   members,
   nodeGeometry,
   settings,
@@ -85,7 +87,7 @@ function initialState(graph: RoutingGraph, config: RoutingSettings, style: Route
     state = { ...state, obstacles: state.obstacles.set(`n:${id}`, worldRect(n, state)) };
   for (const [id, e] of edges) {
     state = edgeMembership(state, e, style, true);
-    state = { ...state, obstacles: state.obstacles.set(`e:${id}`, labelRect(e, state)) };
+    state = { ...state, obstacles: state.obstacles.set(`e:${id}`, obstacleLabelRect(e, state)) };
   }
   return state;
 }
@@ -111,12 +113,30 @@ function calculate(
       plans: new Map(),
     };
   const pending = new Set(affected);
+  expandLabelFamilies(pending, input);
+  if (previous) expandLabelFamilies(pending, previous);
   const processed = new Set<string>();
+  const familyDepth = new Map<string, number>();
+  const familyRoots = new Map<string, string>();
+  for (const [id, config] of Object.entries(state.settings.edges)) {
+    if (config.sourceLabel === undefined) continue;
+    const family = labelFamily(id, input);
+    for (let index = 0; index < family.length; index++) {
+      const member = family[index]!;
+      familyRoots.set(member, family.at(-1)!);
+      familyDepth.set(member, family.length - index);
+    }
+  }
   const priorities = new Map<string, string>();
   const priority = (id: string) => {
     let result = priorities.get(id);
     if (result !== undefined) return result;
     const edge = state.edges.get(id) ?? previous?.edges.get(id);
+    const familyRoot = familyRoots.get(id);
+    if (familyRoot !== undefined) {
+      priorities.set(id, familyRoot);
+      return familyRoot;
+    }
     const key = edge && groupKey(edge, style, state.settings);
     result = key
       ? ((state.edges.has(id) ? state.groups : previous?.groups)?.get(key)?.keys().next().value ??
@@ -125,12 +145,17 @@ function calculate(
     priorities.set(id, result);
     return result;
   };
-  const later = (candidate: string, id: string) =>
-    priority(candidate) > priority(id) || (priority(candidate) === priority(id) && candidate > id);
+  const compare = (a: string, b: string) =>
+    (priority(a) < priority(b) ? -1 : priority(a) > priority(b) ? 1 : 0) ||
+    (familyDepth.get(a) ?? 1) - (familyDepth.get(b) ?? 1) ||
+    (a < b ? -1 : a > b ? 1 : 0);
+  const later = (candidate: string, id: string) => compare(candidate, id) > 0;
   const invalidate = (id: string, bounds: ReturnType<typeof routeBounds>) => {
     for (const candidate of routeIndex.query(inflate(bounds, state.settings.edgeSpacing))) {
       if (!later(candidate, id) || processed.has(candidate)) continue;
       pending.add(candidate);
+      expandLabelFamilies(pending, input);
+      for (const done of processed) pending.delete(done);
       const edge = state.edges.get(candidate);
       const key = edge && groupKey(edge, style, state.settings);
       if (key)
@@ -160,11 +185,7 @@ function calculate(
     }
   const segmentCache = new Map<string, ReturnType<typeof reservations>>();
   while (pending.size) {
-    const id = [...pending].sort(
-      (a, b) =>
-        (priority(a) < priority(b) ? -1 : priority(a) > priority(b) ? 1 : 0) ||
-        (a < b ? -1 : a > b ? 1 : 0),
-    )[0]!;
+    const id = [...pending].sort(compare)[0]!;
     pending.delete(id);
     processed.add(id);
     const edge = state.edges.get(id),
@@ -200,7 +221,14 @@ function calculate(
             const node = state.nodes.get(id),
               bounds = node && worldRect(node, state);
             return bounds
-              ? [inflate(bounds, state.settings.clearance + state.settings.edgeSpacing * 2 + 1)]
+              ? [
+                  inflate(
+                    bounds,
+                    state.settings.clearance +
+                      (style === "organic" ? 0 : state.settings.edgeSpacing * 2) +
+                      1,
+                  ),
+                ]
               : [];
           });
         let segments = segmentCache.get(otherId);
@@ -224,9 +252,11 @@ function calculate(
       }
       return result;
     };
+    batch.policy = effectivePolicy(state.settings, id);
+    const costSettings = { ...state.settings, ...batch.policy?.collisions };
     batch.edgeCost = (a, b) =>
       query(segmentBounds(a, b)).reduce(
-        (cost, other) => cost + conflictCost(a, b, other, state.settings),
+        (cost, other) => cost + conflictCost(a, b, other, costSettings),
         0,
       );
     batch.conflicts = (a, b) =>
@@ -237,7 +267,27 @@ function calculate(
       );
     batch.guides = (bounds) =>
       query(bounds).map((segment) => reservationBounds(segment, state.settings.edgeSpacing));
-    let route = routeEdge(edge, input, style, counts, batch);
+    batch.labelOverlaps = (bounds) => {
+      batch.dependencyBounds = batch.dependencyBounds
+        ? union(batch.dependencyBounds, bounds)
+        : bounds;
+      return routeIndex
+        .query(bounds)
+        .filter((otherId) => {
+          const label = routes.get(otherId)?.label;
+          return later(id, otherId) && label && intersects(bounds, label.bounds);
+        })
+        .map((otherId) => `e:${otherId}`);
+    };
+    batch.routes = routes;
+    batch.previous = oldRoute;
+    batch.previousSettings = previous?.settings;
+    let route =
+      style === "bezier" &&
+      !batch.policy &&
+      !routes.get(state.settings.edges[id]?.sourceLabel ?? "")?.label
+        ? routeBezierEdge(edge, input, routes, counts, batch)
+        : routeEdge(edge, input, style, counts, batch);
     if (oldRoute && JSON.stringify(oldRoute) === JSON.stringify(route)) route = oldRoute;
     const drawnBounds = routeBounds(route);
     if (route !== oldRoute) {
@@ -390,7 +440,7 @@ function updateState(
   }
   for (const id of changedEdges) {
     const edge = state.edges.get(id);
-    invalidateObstacle(`e:${id}`, edge && labelRect(edge, state));
+    invalidateObstacle(`e:${id}`, edge && obstacleLabelRect(edge, state));
     affected.add(id);
   }
   // Terminal placement depends on current incident edges, including neighbors
@@ -426,6 +476,8 @@ function updateState(
       if (key !== undefined)
         for (const peer of version.groups.get(key)?.keys() ?? []) affected.add(peer);
     }
+  expandLabelFamilies(affected, prior);
+  expandLabelFamilies(affected, state);
   return { state, affected };
 }
 export function createRoutingStrategy(id: RouteStyle): NativeRoutingStrategy {

package/src/routing/index.ts

@@ -34,9 +34,14 @@ export {
   getTangentAtLength,
   pathFromPoints,
   roundCorners,
+  segmentCrossesRect,
   toSvgPath,
 } from "./path";
 export type {
+  BezierEndpoint,
+  BezierGuide,
+  BezierRoutingOptions,
+  BezierEdgeSettings,
   RouteAttachment,
   EdgeRoutingSettings,
   NativeRoutingStrategy,
@@ -55,6 +60,11 @@ export type {
   RoutingGraph,
   RoutingMetrics,
   RoutingSettings,
+  RoutingPolicy,
+  RoutingCurve,
+  RoutingTangent,
+  RoutingLabel,
+  RouteLabelPlacement,
   RoutingSnapshot,
   RoutingStrategy,
   RoutingUpdate,
@@ -67,3 +77,7 @@ export {
   routeToPolylines,
   routeToPoints,
 } from "./adapters";
+
+export { trimBezierPathStart } from "./bezier-fit";
+
+export { routingPolicies } from "./model";

package/src/routing/model.ts

@@ -1,7 +1,15 @@
 import type { GraphEdge } from "@statelyai/graph";
 import { PersistentMap } from "./persistent";
 import { SpatialIndex } from "./spatial";
-import type { Route, RouteBounds, RoutePoint, RoutingSettings, RouteSide } from "./types";
+import type {
+  Route,
+  RouteBounds,
+  RoutePoint,
+  RoutingSettings,
+  RouteSide,
+  RoutingPolicy,
+  RoutingTangent,
+} from "./types";
 export interface NodeGeometry {
   readonly id: string;
   readonly parentId?: string | null;
@@ -29,6 +37,8 @@ export interface EdgeGeometry {
   readonly height?: number;
 }
 export interface Settings {
+  readonly policy?: RoutingPolicy;
+  readonly bezier: RoutingSettings["bezier"];
   readonly coordinateSpace: "parent" | "world";
   readonly clearance: number;
   readonly radius: number;
@@ -42,6 +52,8 @@ export interface Settings {
 }
 export function settings(input: RoutingSettings = {}): Settings {
   const result = {
+    policy: normalizePolicy(input.policy),
+    bezier: structuredClone(input.bezier),
     coordinateSpace: input.coordinateSpace ?? "parent",
     clearance: input.clearance ?? 8,
     radius: input.radius ?? 10,
@@ -62,6 +74,27 @@ export function settings(input: RoutingSettings = {}): Settings {
     !Number.isInteger(result.organicIterations)
   )
     throw new RangeError("Search and iteration budgets must be integers");
+  for (const config of [result.bezier, ...Object.values(result.edges).map((edge) => edge.bezier)]) {
+    if (
+      config?.targetClearance !== undefined &&
+      (!Number.isFinite(config.targetClearance) || config.targetClearance < 0)
+    )
+      throw new RangeError("Bézier targetClearance must be finite and non-negative");
+  }
+  for (const edge of Object.values(result.edges)) {
+    if (edge.policy) Object.assign(edge, { policy: normalizePolicy(edge.policy) });
+    for (const point of edge.waypoints ?? [])
+      if (!Number.isFinite(point.x) || !Number.isFinite(point.y))
+        throw new RangeError("Waypoints must be finite");
+    const tangent = edge.bezier?.labelTangent;
+    if (
+      tangent &&
+      (!Number.isFinite(tangent.x) ||
+        !Number.isFinite(tangent.y) ||
+        !Math.hypot(tangent.x, tangent.y))
+    )
+      throw new RangeError("Bézier labelTangent must be finite and nonzero");
+  }
   return freeze(result);
 }
 export function freeze<T>(value: T): T {
@@ -216,3 +249,154 @@ export function groupKey(edge: EdgeGeometry, style: string, config: Settings): s
       : `source:${JSON.stringify([edge.sourceId, edge.sourcePort ?? null])}`;
   return `pair:${JSON.stringify([edge.sourceId, edge.targetId].sort())}`;
 }
+
+function normalizePolicy(input: RoutingPolicy | undefined): RoutingPolicy | undefined {
+  if (!input) return;
+  const value = structuredClone(input);
+  const oneOf = (value: unknown, allowed: readonly string[], name: string) => {
+    if (typeof value !== "string" || !allowed.includes(value))
+      throw new RangeError(`Invalid ${name}`);
+  };
+  if (value.curve)
+    oneOf(
+      value.curve.kind,
+      ["polyline", "bezier", "catmull-rom", "rounded-orthogonal"],
+      "curve kind",
+    );
+  if (value.label) oneOf(value.label.kind, ["follow", "fixed", "through", "gap"], "label kind");
+  if (value.monotonic) {
+    oneOf(value.monotonic.axis, ["x", "y", "both"], "monotonic axis");
+    oneOf(value.monotonic.strength, ["prefer", "require"], "monotonic strength");
+  }
+  if (value.stability)
+    oneOf(value.stability.kind, ["recompute", "preserve-valid"], "stability kind");
+  for (const name of ["nodes", "labels"] as const)
+    if (value.collisions?.[name] !== undefined)
+      oneOf(value.collisions[name], ["avoid", "allow"], `${name} collision mode`);
+
+  const nonnegative = (n: number | undefined, name: string) => {
+    if (n !== undefined && (!Number.isFinite(n) || n < 0))
+      throw new RangeError(`${name} must be finite and non-negative`);
+  };
+  function tangent(t: RoutingTangent | undefined): RoutingTangent | undefined {
+    if (t) oneOf(t.kind, ["automatic", "border-normal", "vector"], "tangent kind");
+    if (t?.kind !== "vector") return t;
+    const { x, y } = t.direction,
+      length = Math.hypot(x, y);
+    if (!Number.isFinite(x) || !Number.isFinite(y) || !Number.isFinite(length) || !length)
+      throw new RangeError("Tangent direction must be finite and nonzero");
+    return { kind: "vector", direction: { x: x / length, y: y / length } };
+  }
+  if (value.curve?.kind === "bezier") nonnegative(value.curve.curvature, "curvature");
+  if (value.curve?.kind === "rounded-orthogonal") nonnegative(value.curve.radius, "radius");
+  nonnegative(value.collisions?.crossingPenalty, "crossingPenalty");
+  nonnegative(value.collisions?.overlapPenalty, "overlapPenalty");
+  if (value.label?.kind === "follow") {
+    const { fraction = 0.5, offset = 0 } = value.label;
+    if (!Number.isFinite(fraction) || fraction < 0 || fraction > 1)
+      throw new RangeError("Label fraction must be in [0, 1]");
+    if (!Number.isFinite(offset)) throw new RangeError("Label offset must be finite");
+  }
+  return freeze({
+    ...value,
+    ...(value.sourceTangent ? { sourceTangent: tangent(value.sourceTangent) } : {}),
+    ...(value.targetTangent ? { targetTangent: tangent(value.targetTangent) } : {}),
+    ...(value.label?.kind === "through" || value.label?.kind === "gap"
+      ? {
+          label: {
+            ...value.label,
+            ...(value.label.tangent ? { tangent: tangent(value.label.tangent) } : {}),
+          },
+        }
+      : {}),
+  });
+}
+export function effectivePolicy(config: Settings, edgeId: string): RoutingPolicy | undefined {
+  const edge = config.edges[edgeId],
+    local = edge?.policy,
+    global = config.policy;
+  if (!local && !global) return;
+  const legacyAttachment = edge?.bezier?.attachmentMode;
+  const legacyTangent: RoutingTangent | undefined =
+    legacyAttachment === "orthogonal"
+      ? { kind: "border-normal" }
+      : legacyAttachment === "floating"
+        ? { kind: "automatic" }
+        : undefined;
+  let label = local?.label ?? global?.label;
+  const legacyLabel = edge?.bezier?.labelTangent;
+  if (!local?.label && legacyLabel && (label?.kind === "through" || label?.kind === "gap")) {
+    const length = Math.hypot(legacyLabel.x, legacyLabel.y);
+    label = {
+      ...label,
+      tangent: {
+        kind: "vector",
+        direction: { x: legacyLabel.x / length, y: legacyLabel.y / length },
+      },
+    };
+  }
+  return {
+    curve: local?.curve ?? global?.curve,
+    sourceTangent: local?.sourceTangent ?? legacyTangent ?? global?.sourceTangent,
+    targetTangent: local?.targetTangent ?? legacyTangent ?? global?.targetTangent,
+    label,
+    collisions: {
+      nodes: local?.collisions?.nodes ?? global?.collisions?.nodes ?? "avoid",
+      labels: local?.collisions?.labels ?? global?.collisions?.labels ?? "avoid",
+      crossingPenalty:
+        local?.collisions?.crossingPenalty ??
+        global?.collisions?.crossingPenalty ??
+        config.crossingPenalty,
+      overlapPenalty:
+        local?.collisions?.overlapPenalty ??
+        global?.collisions?.overlapPenalty ??
+        config.overlapPenalty,
+    },
+    monotonic: local?.monotonic ?? global?.monotonic,
+    stability: local?.stability ?? global?.stability,
+  };
+}
+export function obstacleLabelRect(
+  edge: EdgeGeometry,
+  state: Pick<State, "nodes" | "settings">,
+): RouteBounds | undefined {
+  return effectivePolicy(state.settings, edge.id)?.label?.kind === "follow"
+    ? undefined
+    : labelRect(edge, state);
+}
+const presetCollisions = {
+  nodes: "avoid",
+  labels: "avoid",
+  crossingPenalty: 80,
+  overlapPenalty: 8,
+} as const;
+export const routingPolicies: Readonly<{
+  smooth: RoutingPolicy;
+  diagram: RoutingPolicy;
+  authored: RoutingPolicy;
+}> = freeze({
+  smooth: {
+    curve: { kind: "bezier", curvature: 0.5 },
+    sourceTangent: { kind: "automatic" },
+    targetTangent: { kind: "automatic" },
+    label: { kind: "follow", fraction: 0.5 },
+    collisions: presetCollisions,
+    stability: { kind: "recompute" },
+  },
+  diagram: {
+    curve: { kind: "rounded-orthogonal", radius: 10 },
+    sourceTangent: { kind: "border-normal" },
+    targetTangent: { kind: "border-normal" },
+    label: { kind: "follow", fraction: 0.5 },
+    collisions: presetCollisions,
+    stability: { kind: "recompute" },
+  },
+  authored: {
+    curve: { kind: "catmull-rom" },
+    sourceTangent: { kind: "automatic" },
+    targetTangent: { kind: "automatic" },
+    label: { kind: "follow", fraction: 0.5 },
+    collisions: presetCollisions,
+    stability: { kind: "recompute" },
+  },
+});

package/src/routing/path.ts

@@ -22,7 +22,7 @@ function pointLineDistance(p: RoutePoint, a: RoutePoint, b: RoutePoint): number
 }
 type Arc = Extract<RouteSegment, { kind: "arc" }>;
 /** SVG endpoint-to-center conversion, including SVG's radius correction. */
-function arcCenter(start: RoutePoint, arc: Arc) {
+export function arcCenter(start: RoutePoint, arc: Arc) {
   let rx = Math.abs(arc.rx),
     ry = Math.abs(arc.ry);
   if (!rx || !ry || distance(start, arc.to) === 0) return undefined;