@statelyai/layout 0.4.3 → 0.5.1

package/dist/{types-CT2akdK0.d.mts → types-D8pYSn8I.d.cts}

@@ -1,5 +1,25 @@
 import { EntityRect, Graph, GraphDiff, Point } from "@statelyai/graph";
 
+//#region src/routing/bezier-fit.d.ts
+interface BezierGuide {
+  readonly points: readonly RoutePoint[];
+  readonly sourceDirection: RouteSide;
+  readonly targetDirection: RouteSide;
+  readonly path?: RoutePath;
+}
+type BezierEndpoint = {
+  kind: "floating";
+  bounds: RouteBounds;
+  sides: readonly RouteSide[];
+} | {
+  kind: "port";
+  point: RoutePoint;
+  direction: RouteSide;
+  escape: RoutePoint;
+  owner: RouteBounds;
+};
+declare function trimBezierPathStart(path: string, maximum?: number): string | undefined;
+//#endregion
 //#region src/routing/types.d.ts
 type RoutePoint = Readonly<Point>;
 type RouteSegment = {
@@ -43,16 +63,26 @@ interface RouteSection {
   readonly from: RouteEndpoint;
   readonly to: RouteEndpoint;
   readonly path: RoutePath;
+  readonly fromSide?: RouteSide;
+  readonly toSide?: RouteSide;
   /** Same ID denotes a shared trunk; render it once. */
   readonly sharedId?: string;
 }
-type RoutingDiagnosticCode = "MISSING_GEOMETRY" | "MISSING_PORT" | "ROUTE_CONFLICT" | "ROUTE_BLOCKED" | "SEARCH_BUDGET" | "CONSTRAINT_VIOLATION";
+type RoutingDiagnosticCode = "MISSING_GEOMETRY" | "MISSING_PORT" | "ROUTE_CONFLICT" | "ROUTE_BLOCKED" | "SEARCH_BUDGET" | "CONSTRAINT_VIOLATION" | "LABEL_OVERLAP";
 interface RoutingDiagnostic {
   readonly code: RoutingDiagnosticCode;
   readonly edgeId: string;
   readonly message: string;
+  readonly constraint?: "source-tangent" | "target-tangent" | "label-tangent" | "waypoints" | "node-clearance" | "label-clearance" | "monotonicity" | "bundle";
+  readonly relatedIds?: readonly string[];
+}
+interface RouteLabelPlacement {
+  readonly bounds: RouteBounds;
+  readonly anchor: RoutePoint;
+  readonly tangent: RoutePoint;
 }
 interface Route {
+  readonly label?: RouteLabelPlacement;
   readonly edgeId: string;
   readonly sections: readonly RouteSection[];
   readonly status: "routed" | "fallback";
@@ -73,7 +103,84 @@ interface RouteAttachment {
   readonly bounds: RouteBounds;
   readonly facing?: "inward" | "outward";
 }
+interface BezierRoutingOptions {
+  readonly avoidObstacles?: boolean;
+  readonly attachmentMode?: "floating" | "orthogonal";
+  readonly targetClearance?: number;
+}
+interface BezierEdgeSettings extends BezierRoutingOptions {
+  readonly source?: BezierEndpoint;
+  readonly target?: Extract<BezierEndpoint, {
+    kind: "floating";
+  }>;
+  readonly guides?: {
+    readonly source: BezierGuide;
+    readonly target: BezierGuide;
+  };
+  readonly obstacles?: readonly RouteBounds[];
+  readonly terminalBounds?: readonly RouteBounds[];
+  readonly labelTangent?: RoutePoint;
+  readonly disabled?: boolean;
+}
+type RoutingTangent = {
+  readonly kind: "automatic";
+} | {
+  readonly kind: "border-normal";
+} | {
+  readonly kind: "vector";
+  readonly direction: RoutePoint;
+};
+type RoutingCurve = {
+  readonly kind: "polyline";
+} | {
+  readonly kind: "bezier";
+  readonly curvature?: number;
+} | {
+  readonly kind: "catmull-rom";
+} | {
+  readonly kind: "rounded-orthogonal";
+  readonly radius?: number;
+};
+type RoutingLabel = {
+  readonly kind: "follow";
+  readonly fraction?: number;
+  readonly offset?: number;
+} | {
+  readonly kind: "fixed";
+} | {
+  readonly kind: "through";
+  readonly tangent?: RoutingTangent;
+} | {
+  readonly kind: "gap";
+  readonly tangent?: RoutingTangent;
+};
+interface RoutingPolicy {
+  readonly curve?: RoutingCurve;
+  readonly sourceTangent?: RoutingTangent;
+  readonly targetTangent?: RoutingTangent;
+  readonly label?: RoutingLabel;
+  readonly collisions?: {
+    readonly nodes?: "avoid" | "allow";
+    readonly labels?: "avoid" | "allow";
+    readonly crossingPenalty?: number;
+    readonly overlapPenalty?: number;
+  };
+  readonly monotonic?: {
+    readonly axis: "x" | "y" | "both";
+    readonly strength: "prefer" | "require";
+  };
+  readonly stability?: {
+    readonly kind: "recompute" | "preserve-valid";
+  };
+}
 interface EdgeRoutingSettings {
+  readonly policy?: RoutingPolicy;
+  /** Resolve the source from this edge label in the current graph geometry. */
+  readonly sourceLabel?: string;
+  readonly sourceSides?: readonly RouteSide[];
+  readonly targetSides?: readonly RouteSide[];
+  readonly labelSides?: readonly RouteSide[];
+  readonly bezier?: BezierEdgeSettings;
   readonly sourceAttachment?: RouteAttachment;
   readonly targetAttachment?: RouteAttachment;
   readonly sourceSide?: RouteSide;
@@ -83,6 +190,9 @@ interface EdgeRoutingSettings {
   readonly group?: string;
 }
 interface RoutingSettings {
+  readonly policy?: RoutingPolicy;
+  /** Opt into center-tangent Bézier routing and floating attachments. */
+  readonly bezier?: BezierRoutingOptions;
   /** Native compound geometry is parent-relative; adapters may supply resolved world geometry. */
   readonly coordinateSpace?: "parent" | "world";
   readonly clearance?: number;
@@ -130,4 +240,4 @@ interface NativeRoutingStrategy extends RoutingStrategy {
 }
 type RouteBounds = Readonly<EntityRect>;
 //#endregion
-export { RoutingMetrics as _, RouteBounds as a, RoutingStrategy as b, RoutePath as c, RouteSegment as d, RouteSide as f, RoutingGraph as g, RoutingDiagnosticCode as h, RouteAttachment as i, RoutePoint as l, RoutingDiagnostic as m, NativeRoutingStrategy as n, RouteEndpoint as o, RouteStyle as p, Route as r, RoutePatch as s, EdgeRoutingSettings as t, RouteSection as u, RoutingSettings as v, RoutingUpdate as x, RoutingSnapshot as y };
+export { BezierGuide as A, RoutingPolicy as C, RoutingTangent as D, RoutingStrategy as E, RoutingUpdate as O, RoutingMetrics as S, RoutingSnapshot as T, RoutingCurve as _, Route as a, RoutingGraph as b, RouteEndpoint as c, RoutePath as d, RoutePoint as f, RouteStyle as g, RouteSide as h, NativeRoutingStrategy as i, trimBezierPathStart as j, BezierEndpoint as k, RouteLabelPlacement as l, RouteSegment as m, BezierRoutingOptions as n, RouteAttachment as o, RouteSection as p, EdgeRoutingSettings as r, RouteBounds as s, BezierEdgeSettings as t, RoutePatch as u, RoutingDiagnostic as v, RoutingSettings as w, RoutingLabel as x, RoutingDiagnosticCode as y };

package/dist/{types-uxPlGRof.d.cts → types-MAUtJfKQ.d.mts}

@@ -1,5 +1,25 @@
 import { EntityRect, Graph, GraphDiff, Point } from "@statelyai/graph";
 
+//#region src/routing/bezier-fit.d.ts
+interface BezierGuide {
+  readonly points: readonly RoutePoint[];
+  readonly sourceDirection: RouteSide;
+  readonly targetDirection: RouteSide;
+  readonly path?: RoutePath;
+}
+type BezierEndpoint = {
+  kind: "floating";
+  bounds: RouteBounds;
+  sides: readonly RouteSide[];
+} | {
+  kind: "port";
+  point: RoutePoint;
+  direction: RouteSide;
+  escape: RoutePoint;
+  owner: RouteBounds;
+};
+declare function trimBezierPathStart(path: string, maximum?: number): string | undefined;
+//#endregion
 //#region src/routing/types.d.ts
 type RoutePoint = Readonly<Point>;
 type RouteSegment = {
@@ -43,16 +63,26 @@ interface RouteSection {
   readonly from: RouteEndpoint;
   readonly to: RouteEndpoint;
   readonly path: RoutePath;
+  readonly fromSide?: RouteSide;
+  readonly toSide?: RouteSide;
   /** Same ID denotes a shared trunk; render it once. */
   readonly sharedId?: string;
 }
-type RoutingDiagnosticCode = "MISSING_GEOMETRY" | "MISSING_PORT" | "ROUTE_CONFLICT" | "ROUTE_BLOCKED" | "SEARCH_BUDGET" | "CONSTRAINT_VIOLATION";
+type RoutingDiagnosticCode = "MISSING_GEOMETRY" | "MISSING_PORT" | "ROUTE_CONFLICT" | "ROUTE_BLOCKED" | "SEARCH_BUDGET" | "CONSTRAINT_VIOLATION" | "LABEL_OVERLAP";
 interface RoutingDiagnostic {
   readonly code: RoutingDiagnosticCode;
   readonly edgeId: string;
   readonly message: string;
+  readonly constraint?: "source-tangent" | "target-tangent" | "label-tangent" | "waypoints" | "node-clearance" | "label-clearance" | "monotonicity" | "bundle";
+  readonly relatedIds?: readonly string[];
+}
+interface RouteLabelPlacement {
+  readonly bounds: RouteBounds;
+  readonly anchor: RoutePoint;
+  readonly tangent: RoutePoint;
 }
 interface Route {
+  readonly label?: RouteLabelPlacement;
   readonly edgeId: string;
   readonly sections: readonly RouteSection[];
   readonly status: "routed" | "fallback";
@@ -73,7 +103,84 @@ interface RouteAttachment {
   readonly bounds: RouteBounds;
   readonly facing?: "inward" | "outward";
 }
+interface BezierRoutingOptions {
+  readonly avoidObstacles?: boolean;
+  readonly attachmentMode?: "floating" | "orthogonal";
+  readonly targetClearance?: number;
+}
+interface BezierEdgeSettings extends BezierRoutingOptions {
+  readonly source?: BezierEndpoint;
+  readonly target?: Extract<BezierEndpoint, {
+    kind: "floating";
+  }>;
+  readonly guides?: {
+    readonly source: BezierGuide;
+    readonly target: BezierGuide;
+  };
+  readonly obstacles?: readonly RouteBounds[];
+  readonly terminalBounds?: readonly RouteBounds[];
+  readonly labelTangent?: RoutePoint;
+  readonly disabled?: boolean;
+}
+type RoutingTangent = {
+  readonly kind: "automatic";
+} | {
+  readonly kind: "border-normal";
+} | {
+  readonly kind: "vector";
+  readonly direction: RoutePoint;
+};
+type RoutingCurve = {
+  readonly kind: "polyline";
+} | {
+  readonly kind: "bezier";
+  readonly curvature?: number;
+} | {
+  readonly kind: "catmull-rom";
+} | {
+  readonly kind: "rounded-orthogonal";
+  readonly radius?: number;
+};
+type RoutingLabel = {
+  readonly kind: "follow";
+  readonly fraction?: number;
+  readonly offset?: number;
+} | {
+  readonly kind: "fixed";
+} | {
+  readonly kind: "through";
+  readonly tangent?: RoutingTangent;
+} | {
+  readonly kind: "gap";
+  readonly tangent?: RoutingTangent;
+};
+interface RoutingPolicy {
+  readonly curve?: RoutingCurve;
+  readonly sourceTangent?: RoutingTangent;
+  readonly targetTangent?: RoutingTangent;
+  readonly label?: RoutingLabel;
+  readonly collisions?: {
+    readonly nodes?: "avoid" | "allow";
+    readonly labels?: "avoid" | "allow";
+    readonly crossingPenalty?: number;
+    readonly overlapPenalty?: number;
+  };
+  readonly monotonic?: {
+    readonly axis: "x" | "y" | "both";
+    readonly strength: "prefer" | "require";
+  };
+  readonly stability?: {
+    readonly kind: "recompute" | "preserve-valid";
+  };
+}
 interface EdgeRoutingSettings {
+  readonly policy?: RoutingPolicy;
+  /** Resolve the source from this edge label in the current graph geometry. */
+  readonly sourceLabel?: string;
+  readonly sourceSides?: readonly RouteSide[];
+  readonly targetSides?: readonly RouteSide[];
+  readonly labelSides?: readonly RouteSide[];
+  readonly bezier?: BezierEdgeSettings;
   readonly sourceAttachment?: RouteAttachment;
   readonly targetAttachment?: RouteAttachment;
   readonly sourceSide?: RouteSide;
@@ -83,6 +190,9 @@ interface EdgeRoutingSettings {
   readonly group?: string;
 }
 interface RoutingSettings {
+  readonly policy?: RoutingPolicy;
+  /** Opt into center-tangent Bézier routing and floating attachments. */
+  readonly bezier?: BezierRoutingOptions;
   /** Native compound geometry is parent-relative; adapters may supply resolved world geometry. */
   readonly coordinateSpace?: "parent" | "world";
   readonly clearance?: number;
@@ -130,4 +240,4 @@ interface NativeRoutingStrategy extends RoutingStrategy {
 }
 type RouteBounds = Readonly<EntityRect>;
 //#endregion
-export { RoutingMetrics as _, RouteBounds as a, RoutingStrategy as b, RoutePath as c, RouteSegment as d, RouteSide as f, RoutingGraph as g, RoutingDiagnosticCode as h, RouteAttachment as i, RoutePoint as l, RoutingDiagnostic as m, NativeRoutingStrategy as n, RouteEndpoint as o, RouteStyle as p, Route as r, RoutePatch as s, EdgeRoutingSettings as t, RouteSection as u, RoutingSettings as v, RoutingUpdate as x, RoutingSnapshot as y };
+export { BezierGuide as A, RoutingPolicy as C, RoutingTangent as D, RoutingStrategy as E, RoutingUpdate as O, RoutingMetrics as S, RoutingSnapshot as T, RoutingCurve as _, Route as a, RoutingGraph as b, RouteEndpoint as c, RoutePath as d, RoutePoint as f, RouteStyle as g, RouteSide as h, NativeRoutingStrategy as i, trimBezierPathStart as j, BezierEndpoint as k, RouteLabelPlacement as l, RouteSegment as m, BezierRoutingOptions as n, RouteAttachment as o, RouteSection as p, EdgeRoutingSettings as r, RouteBounds as s, BezierEdgeSettings as t, RoutePatch as u, RoutingDiagnostic as v, RoutingSettings as w, RoutingLabel as x, RoutingDiagnosticCode as y };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@statelyai/layout",
-  "version": "0.4.3",
+  "version": "0.5.1",
   "description": "Extensible, graph-native layout algorithms for @statelyai/graph",
   "license": "EPL-2.0 OR GPL-3.0-or-later",
   "repository": {
@@ -128,6 +128,9 @@
     "typecheck:repo": "tsc --project tsconfig.repo.json",
     "verify": "oxfmt --check . && oxlint && tsc --noEmit && tsc --project tsconfig.repo.json && tsc --project demo/tsconfig.json && tsc --project stories/tsconfig.json && tsx scripts/generate-elk-layered-options.ts --check && tsx scripts/generate-demo-corpus.ts --check && vitest --run && tsdown && vite build --config demo/vite.config.ts && storybook build -o dist-storybook --quiet && publint --pack npm && tsx scripts/smoke-package.ts",
     "validate:package": "publint --pack npm && tsx scripts/smoke-package.ts",
+    "verify:routing-policies": "tsx scripts/check-routing-policies.ts",
+    "routing:gallery": "tsx scripts/render-routing-policies.ts",
+    "routing:quality": "tsx scripts/render-routing-quality.ts",
     "storybook": "storybook dev -p 6018 --host 127.0.0.1 --no-open",
     "storybook:build": "storybook build -o dist-storybook",
     "storybook:typecheck": "tsc --project stories/tsconfig.json",

package/src/authoring/partial.ts

@@ -363,13 +363,7 @@ export function runPartialLayout<N, E, G, P>(
             "Partial layout supports its built-in orthogonal router only",
           );
         const ancestorIds = new Set([...ancestors(source.id), ...ancestors(target.id)]);
-        const nodeObstacles = graph.nodes
-          .filter((n) => !ancestorIds.has(n.id))
-          .map((n) =>
-            n.id === source.id || n.id === target.id
-              ? n
-              : { ...n, x: n.x - 1, y: n.y - 1, width: n.width + 2, height: n.height + 2 },
-          );
+        const nodeObstacles = graph.nodes.filter((n) => !ancestorIds.has(n.id));
         const labelObstacles = [...edgeById.values()].filter(
           (e) => e.id !== edge.id && e.width > 0 && e.height > 0,
         );

package/src/authoring/routing.ts

@@ -191,24 +191,69 @@ export function routeOrthogonal(
   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)
+  const start = endpoint(source, edge.sourcePort, direction, true);
+  const end = endpoint(target, edge.targetPort, direction, false);
+  const normal = (node: VisualNode, point: Point): Point => {
+    const sides = [
+      { distance: Math.abs(point.x - node.x), x: -1, y: 0 },
+      { distance: Math.abs(point.x - node.x - node.width), x: 1, y: 0 },
+      { distance: Math.abs(point.y - node.y), x: 0, y: -1 },
+      { distance: Math.abs(point.y - node.y - node.height), x: 0, y: 1 },
+    ];
+    return sides.sort((a, b) => a.distance - b.distance)[0]!;
+  };
+  const startNormal = normal(source, start);
+  const endNormal = normal(target, end);
+  for (const clearance of [8, 4, 1, 0]) {
+    check();
+    const padded = obstacles.map((rect) => ({
+      ...rect,
+      x: rect.x - clearance,
+      y: rect.y - clearance,
+      width: rect.width + clearance * 2,
+      height: rect.height + clearance * 2,
+    }));
+    const startLead = {
+      x: start.x + startNormal.x * clearance,
+      y: start.y + startNormal.y * clearance,
+    };
+    const endLead = {
+      x: end.x + endNormal.x * clearance,
+      y: end.y + endNormal.y * clearance,
+    };
+    if (
+      obstacles.some(
+        (rect, i) =>
+          (rect !== source && crossesRect(start, startLead, padded[i]!)) ||
+          (rect !== target && crossesRect(end, endLead, padded[i]!)),
+      )
+    )
+      continue;
+    const anchors = [startLead, ...waypoints, endLead];
+    const points: Point[] = [start];
+    let routed = true;
+    for (let i = 1; i < anchors.length; i++) {
+      const segment = connect(anchors[i - 1]!, anchors[i]!, padded, check);
+      if (!segment) {
+        routed = false;
+        break;
+      }
+      points.push(...(i === 1 ? segment : segment.slice(1)));
+    }
+    if (!routed) continue;
+    points.push(end);
+    const unique = points.filter(
+      (p, i) => i === 0 || p.x !== points[i - 1]!.x || p.y !== points[i - 1]!.y,
     );
-  });
+    return unique.filter((p, i) => {
+      if (i === 0 || i === unique.length - 1) return true;
+      const before = unique[i - 1]!,
+        after = unique[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)
+      );
+    });
+  }
+  return undefined;
 }

package/src/layered/feedback-chains.ts

@@ -31,13 +31,15 @@ function opposed(a: readonly Point[], b: readonly Point[]): boolean {
  * 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.
+ * track, or the outer track with the label moved onto it, whichever is clear;
+ * failing both, a fresh track past everything else with the label on it.
  */
 export function straightenFeedbackChains(
   chains: readonly FeedbackChain[],
   pointsByEdgeId: Map<string, readonly Point[]>,
   rectByNodeId: Map<string, EntityRect>,
   horizontal: boolean,
+  spacing: number,
 ): void {
   const cross = (p: Point) => (horizontal ? p.y : p.x);
   const flow = (p: Point) => (horizontal ? p.x : p.y);
@@ -60,7 +62,19 @@ export function straightenFeedbackChains(
       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 tracks = label ? [label.cross, outer] : [outer];
+    if (labelRect) {
+      // Other feedback routes may share the outer track; past everything, the
+      // moved label is clear of them.
+      const farthest = Math.max(
+        ...[...pointsByEdgeId.values()].flatMap((other) => other.map(cross)),
+        ...[...rectByNodeId.values()].map((rect) =>
+          horizontal ? rect.y + rect.height : rect.x + rect.width,
+        ),
+      );
+      tracks.push(farthest + spacing + label!.cross - (horizontal ? labelRect.y : labelRect.x));
+    }
+    for (const track of tracks) {
       const route = [start, lead, at(flow(lead), track), at(flow(tail), track), tail, end];
       const moved = labelRect && {
         ...labelRect,
@@ -103,8 +117,12 @@ export function straightenFeedbackChains(
       }
       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)))
+      // Never newly share a track with another route heading the opposite way.
+      if (
+        [...pointsByEdgeId].some(
+          ([id, other]) => id !== edgeId && opposed(simple, other) && !opposed(points, other),
+        )
+      )
         continue;
       pointsByEdgeId.set(edgeId, simple);
       if (moved) rectByNodeId.set(label!.id, moved);