@weasel-js/diagram 1.10.1 → 1.11.0

package/dist/layout.entry-BoWFcR4G.d.ts

@@ -0,0 +1,285 @@
+import { A as GraphNode, b as PortSpec, h as DiagramNodeReader, g as DiagramNodeLike, f as Port, d as LayoutOptions, G as Graph, i as LayoutResult, c as LayoutFn, L as LayoutPorts, O as Outline, q as Bounds } from './body-2lC7IiIA.js';
+import { SimulationNode, createSimulation } from '@weasel-js/simulation';
+import { PoseDescriptor, Vec2 } from '@weasel-js/core/math';
+
+/** `node` as layout sees it: bounds grown by its margin, ports where they were. */
+declare function footprintNode(node: GraphNode): GraphNode;
+
+/**
+ * Where a node's ports are, in world coordinates.
+ *
+ * A port is placed in the node's **unrotated** bounds, then carried through
+ * the pose's rotation — the same pivot every other kit reader uses, the AABB
+ * center. Bounds come from the pose descriptor rather than from `pose.width`
+ * and friends, so a node whose pose is a path, an ellipse or anything else a
+ * consumer wired is connectable on the same terms as a rect.
+ */
+
+/** The eight anchors almost everything wants, named the way a compass is. */
+declare const COMPASS: {
+    readonly nw: {
+        readonly u: 0;
+        readonly v: 0;
+    };
+    readonly n: {
+        readonly u: 0.5;
+        readonly v: 0;
+    };
+    readonly ne: {
+        readonly u: 1;
+        readonly v: 0;
+    };
+    readonly e: {
+        readonly u: 1;
+        readonly v: 0.5;
+    };
+    readonly se: {
+        readonly u: 1;
+        readonly v: 1;
+    };
+    readonly s: {
+        readonly u: 0.5;
+        readonly v: 1;
+    };
+    readonly sw: {
+        readonly u: 0;
+        readonly v: 1;
+    };
+    readonly w: {
+        readonly u: 0;
+        readonly v: 0.5;
+    };
+};
+/**
+ * What a node carrying no `ports` gets: the four edge midpoints of its own
+ * bounds. Every node has bounds, so every node is connectable without saying
+ * anything.
+ */
+declare const DEFAULT_PORTS: readonly PortSpec[];
+/** How ports are resolved against a node: its bounds, and its trait. */
+interface PortsOptions<TPose> {
+    /** Reads the AABB a port is placed in, and the node's rotation. Defaults to
+     *  the kit's `AUTO_POSE_DESCRIPTOR`, which handles rect and path poses. */
+    geometry?: PoseDescriptor<TPose>;
+    /** How the `DiagramNode` trait is read off a node. */
+    read?: DiagramNodeReader;
+}
+/**
+ * Every port on `node`, resolved against `pose`.
+ *
+ * Pass the pose the node is **painted** at — `effectivePose(scene, node)` —
+ * not `node.pose`. A port that answers from the document pose while the node
+ * is mid-drag puts an edge somewhere the user can see the node is not.
+ */
+declare function portsOf<TPose>(node: DiagramNodeLike, pose: TPose, opts?: PortsOptions<TPose>): Port[];
+/** One named port, or `undefined` when the node has no such port. */
+declare function portOf<TPose>(node: DiagramNodeLike, pose: TPose, portId: string, opts?: PortsOptions<TPose>): Port | undefined;
+/** One named port at each place it may sit: at `at` first, then at each of
+ *  its `sites`. Empty when the node has no such port. */
+declare function portSitesOf<TPose>(node: DiagramNodeLike, pose: TPose, portId: string, opts?: PortsOptions<TPose>): Port[];
+
+/**
+ * `force` — relaxation, for a graph with no direction to read it in.
+ *
+ * Seeded from where the nodes already are rather than from a fresh random
+ * scatter: an author who has arranged half a diagram gets that arrangement
+ * relaxed, not replaced. There is no RNG in it at all — two coincident nodes
+ * are separated along a golden-angle spiral keyed to their index.
+ *
+ * The forces are the naive O(n²) kind — right for tens to hundreds of nodes,
+ * wrong for a 10k-node graph.
+ *
+ * **This is the one layout that is not idempotent.** A relaxation re-run from
+ * its own output keeps relaxing; `direction` means nothing to it. Pins and the
+ * `tolerance` option are what keep a second pass from scrambling a settled
+ * diagram.
+ */
+
+/** Options for {@link force} and {@link forceRelaxation}. `direction` is
+ *  ignored. */
+interface ForceOptions extends LayoutOptions {
+    /** Ticks to run. Default 300 — one full cooling schedule. */
+    iterations?: number;
+    /** Rest length of an edge, in world units. Default 160. */
+    linkDistance?: number;
+    /** How hard an edge pulls, 0..1. Default 0.35. */
+    linkStrength?: number;
+    /** Pairwise repulsion. Negative repels; default -3000. */
+    charge?: number;
+    /** How hard the graph is held around its own centroid. Default 0.02. */
+    gravity?: number;
+    /** Clear space kept between two boxes, in world units. Default 24. */
+    padding?: number;
+    /** How hard a group draws its members together, 0..1. Default 0.2. */
+    groupStrength?: number;
+}
+/** One node as the relaxation sees it: a simulation point centered on the
+ *  node's box. */
+interface ForceBody extends SimulationNode {
+    id: string;
+    /** Half the node's box, so separation can work on the shape the author sees
+     *  rather than on a point. */
+    hw: number;
+    hh: number;
+}
+/**
+ * The bodies and the force list, wound up and ready to tick.
+ */
+interface ForceRelaxation {
+    bodies: ForceBody[];
+    byId: Map<string, ForceBody>;
+    /** Ids the caller must not move: declared pins, held as `fx`/`fy`. */
+    pinned: ReadonlySet<string>;
+    sim: ReturnType<typeof createSimulation<ForceBody>>;
+    /** Where a body's node's top-left sits, given the body's center. */
+    placed(): Map<string, {
+        x: number;
+        y: number;
+    }>;
+}
+/** Wind up a relaxation of `graph` without ticking it: bodies seeded from
+ *  where the nodes are, pins held fixed. Tick `sim` yourself and read the
+ *  top-lefts from `placed()`. */
+declare function forceRelaxation(graph: Graph, opts?: ForceOptions): ForceRelaxation;
+/** The force-directed layout. Unlike the others it is not idempotent: a
+ *  re-run keeps relaxing, so pins and `tolerance` are what hold a settled
+ *  diagram still. */
+declare const force: (graph: Graph, opts?: ForceOptions) => LayoutResult;
+
+/** The chain layout: the nodes `opts.chain` names (or the longest path) on
+ *  one line in order, and every other node hung beside the chain node it is
+ *  fewest edges from, on the `opts.chainSide` side. Its `plan` also routes
+ *  each edge between a chain node and a node hung beside it through a track
+ *  of its own, so a fan of them into one node does not cross itself. */
+declare const chain: LayoutFn;
+
+/** Which edges a layered layout turns around so that no cycle is left. */
+
+/** Edge ids that close a cycle, found by a depth-first walk in graph order.
+ *  Which edges get named depends only on the node order, so it is the same
+ *  every run. A self-loop is not one: it points neither way. */
+declare function backEdges(graph: Graph): Set<string>;
+/** Longest-path rank per node: one past its deepest predecessor, ignoring
+ *  `back`. Every node with no predecessor is rank 0. */
+declare function ranksOf(graph: Graph, back: ReadonlySet<string>): Map<string, number>;
+
+/**
+ * The layered layout's whole answer: where each node goes, and where each long
+ * edge runs, read off where its placeholders were placed.
+ */
+
+/** What {@link layeredPlan} works out. */
+interface LayeredPlan {
+    /** The new top-left of every node that moves, as `layered` returns it. */
+    moves: LayoutResult;
+    /** Each node's rank. */
+    ranks: ReadonlyMap<string, number>;
+    /** Ids of the graph edges laid out pointing the other way. */
+    back: ReadonlySet<string>;
+    /** For each edge spanning ranks, keyed by the edge's id as drawn: points
+     *  from its `from` end to its `to` end, two per rank it crosses, where it
+     *  enters and leaves that rank. */
+    waypoints: ReadonlyMap<string, readonly Vec2[]>;
+    /** For each labeled edge given room, keyed by the edge's id as drawn: the
+     *  point on its route that room is beside, as a `DiagramLabel`'s
+     *  `{ near }` reads it. */
+    labels: ReadonlyMap<string, Vec2>;
+    /** For each edge running between ranks, keyed by the edge's id as drawn:
+     *  the compass ports facing the way it runs (see `layeredPorts`). */
+    ports: ReadonlyMap<string, LayoutPorts>;
+    /** Pinned nodes after the first that the layout could not be built
+     *  around: covering one with its rank's band would bring that band nearer
+     *  another pinned rank's than the bands between them allow with every gap
+     *  at a quarter of `rankGap` beyond its groups' insets, or would put a
+     *  group's box over a pin it does not hold. They stay put, and the rest is
+     *  laid out around the slot each would have had. */
+    unheld: ReadonlySet<string>;
+}
+/** The layered layout, with the ranks and edge routes it settled on. */
+declare function layeredPlan(graph: Graph, opts?: LayoutOptions): LayeredPlan;
+
+/** Ranking by network simplex (Gansner, Koutsofios, North and Vo, 1993: "A
+ *  Technique for Drawing Directed Graphs", the ranking Graphviz dot uses). */
+
+/**
+ * Each node's rank, chosen to make the total edge length as short as it can:
+ * the sum over edges of `rank(to) - rank(from)`, with every edge at least one
+ * rank long and every edge weighing the same.
+ *
+ * An edge in `back` counts as running the other way, so it is ranked and kept
+ * forward like any other; a self-loop is ignored; parallel edges each count.
+ * Each connected component is ranked on its own and starts at rank 0.
+ *
+ * Starts from the longest-path ranking and improves it by network simplex,
+ * stopping after a number of rounds proportional to the edge count. Every
+ * round leaves a valid ranking, so the answer is valid even when the cap is
+ * hit. Ties break by graph order — node index, then edge index — so the same
+ * graph always ranks the same.
+ *
+ * If `back` leaves a cycle, no valid ranking exists; that component keeps its
+ * longest-path start, which `ranksOf` would also give.
+ */
+declare function ranksByLength(graph: Graph, back: ReadonlySet<string>): Map<string, number>;
+
+/**
+ * `layered` — ranks running one way, nodes running across.
+ *
+ * The flowchart / pipeline layout: an edge points from one rank to the next.
+ * The steps live in `./layered/`: edges closing a cycle are turned around
+ * (`cycles`), ranks are chosen to keep edges short (`rank`), an edge spanning
+ * ranks gets a placeholder in each rank it crosses (`expand`), each rank is
+ * ordered (`order`), and nodes are lined up with their neighbors (`place`).
+ * `plan` puts it together.
+ *
+ * Under `order: 'seeded'` (the default) each rank keeps the order its nodes
+ * and edges already sit in, so a re-run moves nothing. `order: 'barycenter'`
+ * reorders to cut crossings. Either way, a placeholder's position routes its
+ * long edge, which `layered.plan` hands back.
+ */
+
+/** The ranked layout: each edge points one rank further along `direction`.
+ *  Under `order: 'seeded'` a re-run moves nothing; `order: 'barycenter'`
+ *  reorders ranks to cut crossings. */
+declare const layered: LayoutFn;
+
+/** A graph read as trees: its roots, each node's children in order, and each node's depth. */
+interface Forest {
+    roots: GraphNode[];
+    children: Map<string, GraphNode[]>;
+    depth: Map<string, number>;
+}
+/** The forest a depth-first walk in graph order finds. Exported because "which
+ *  node ended up whose child" is the question anyone debugging a tree layout
+ *  asks first. */
+declare function forestOf(graph: Graph, crossAxis: 'x' | 'y'): Forest;
+/** The hierarchy layout: each parent centered over its children's block, one
+ *  rank per depth. A graph that is not a tree lays out as the forest
+ *  {@link forestOf} reads from it. */
+declare const tree: LayoutFn;
+
+/** The outline as a closed polyline: `[x0, y0, x1, y1, …]`. */
+declare function outlinePolyline(outline: Outline, bounds: Bounds): number[];
+/**
+ * Where the ray from `center` through `point` last crosses `poly`, or `null`
+ * when it never does.
+ *
+ * The *last* crossing rather than the first: a concave outline can be crossed
+ * more than once, and the far side is the boundary an edge should attach to.
+ */
+declare function rayHit(poly: readonly number[], center: {
+    x: number;
+    y: number;
+}, point: {
+    x: number;
+    y: number;
+}): {
+    x: number;
+    y: number;
+} | null;
+/**
+ * Every port moved onto `outline`. A port the ray misses — one at the node's
+ * dead center, with no direction to cast along — is left where it was.
+ */
+declare function portsOnOutline(ports: readonly Port[], outline: Outline, bounds: Bounds): Port[];
+
+export { COMPASS as C, DEFAULT_PORTS as D, type ForceOptions as F, type LayeredPlan as L, type PortsOptions as P, type ForceBody as a, type ForceRelaxation as b, type Forest as c, backEdges as d, chain as e, footprintNode as f, force as g, forceRelaxation as h, forestOf as i, layeredPlan as j, portSitesOf as k, layered as l, portsOf as m, portsOnOutline as n, outlinePolyline as o, portOf as p, ranksOf as q, ranksByLength as r, rayHit as s, tree as t };

package/dist/layout.js

@@ -1,3 +1,3 @@
-export { COMPASS, DEFAULT_NODE_GAP, DEFAULT_PORTS, DEFAULT_RANK_GAP, axesFor, backEdges, bodyOutline, boxForContent, buildBody, canvasMeasure, contentBox, extent, force, forceRelaxation, forestOf, graphOrder, layered, layoutBody, layoutRowPorts, measureBody, outlinePath, outlinePolyline, packAcross, pinnedSet, portOf, portsOf, portsOnOutline, ranksOf, rayHit, seededOrder, settle, sizeToBody, translated, tree, untilSettled } from './chunk-JZ4CVLAB.js';
+export { COMPASS, DEFAULT_NODE_GAP, DEFAULT_PORTS, DEFAULT_RANK_GAP, PORT_LABEL_GAP, anchorOffset, axesFor, backEdges, bodyOutline, boxForContent, buildBody, canvasMeasure, chain, contentBox, extent, footprintNode, force, forceRelaxation, forestOf, graphOrder, layered, layeredPlan, layoutBody, layoutRowPorts, marginOf, measureBody, outlinePath, outlinePolyline, packAcross, pinnedSet, planOf, plannerPlan, portLabelBox, portOf, portSitesOf, portsOf, portsOnOutline, ranksByLength, ranksOf, rayHit, seededOrder, settle, sizeToBody, translated, tree, untilSettled } from './chunk-NUMMW5BI.js';
 //# sourceMappingURL=layout.js.map
 //# sourceMappingURL=layout.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@weasel-js/diagram",
-  "version": "1.10.1",
+  "version": "1.11.0",
   "description": "Node-link diagramming for weasel: any scene node becomes a diagram participant, with ports on its perimeter and an optional body builder for flowchart-shaped boxes.",
   "license": "MIT",
   "type": "module",
@@ -17,15 +17,19 @@
       "import": "./dist/layout.js",
       "types": "./dist/layout.d.ts"
     },
+    "./effect": {
+      "import": "./dist/effect.js",
+      "types": "./dist/effect.d.ts"
+    },
     "./package.json": "./package.json"
   },
   "peerDependencies": {
     "react": ">=18",
-    "@weasel-js/animator": "1.10.1",
-    "@weasel-js/core": "1.10.1",
-    "@weasel-js/font": "1.10.1",
-    "@weasel-js/geom": "1.10.1",
-    "@weasel-js/simulation": "1.10.1"
+    "@weasel-js/animator": "1.11.0",
+    "@weasel-js/core": "1.11.0",
+    "@weasel-js/font": "1.11.0",
+    "@weasel-js/geom": "1.11.0",
+    "@weasel-js/simulation": "1.11.0"
   },
   "author": "orochi235",
   "homepage": "https://orochi235.github.io/weasel/",