@weasel-js/diagram 1.9.2 → 1.9.4

package/dist/index.d.ts

@@ -1,6 +1,6 @@
-import { P as Port, a as PortsOptions, D as DiagramNodeLike, b as DiagramNodeReader, R as Row, O as Outline, c as PortSpec, B as BodySpec, d as DiagramNode, L as LayoutFn, e as LayoutOptions, M as MeasureRowText, G as GraphSource, F as ForceOptions, f as LayoutResult, g as Graph } from './layout.entry-W-8PYfGM.js';
-export { h as BodyFloor, i as BodyNodeSpec, j as Bounds, k as BuildBodyOptions, l as BuildGraphOptions, C as COMPASS, m as DEFAULT_NODE_GAP, n as DEFAULT_PORTS, o as DEFAULT_RANK_GAP, p as DIAGRAM_TRAIT_KEY, q as DiagramNodeEntry, r as ForceBody, s as ForceRelaxation, t as GraphEdge, u as GraphNode, v as GraphNodeLike, w as LayoutAxes, x as LayoutDirection, y as PortAnchor, z as RowBox, A as RowNodeData, E as RowPort, H as RowPortBox, I as RowTextStyle, S as Slot, J as axesFor, K as backEdges, N as bodyOutline, Q as bodyTrait, T as boxForContent, U as buildBody, V as buildGraph, W as canvasMeasure, X as contentBox, Y as createDiagramNodes, Z as dataKeyReader, _ as diagramNodeOf, $ as force, a0 as forceRelaxation, a1 as forestOf, a2 as graphOrder, a3 as isPinned, a4 as layered, a5 as layoutBody, a6 as layoutRowPorts, a7 as measureBody, a8 as outlinePath, a9 as outlinePolyline, aa as packAcross, ab as pinnedSet, ac as portOf, ad as portsOf, ae as portsOnOutline, af as ranksOf, ag as rayHit, ah as seededOrder, ai as settle, aj as sizeToBody, ak as translated, al as tree } from './layout.entry-W-8PYfGM.js';
-import { Vec2, DerivedDep, Path, SceneRegistry, PoseDescriptor, ChromeState, FillStyle, Stroke, CursorSpec, Affordance, InvocationCtx, GestureBinding, Action, Contribution, RenderLayer, MarkerRef, AddNodeSpec, RectPose, Scene, EasingFn, NodeId, NodeShapeEntry, View, SelectionApi } from '@weasel-js/core';
+import { P as Port, a as PortsOptions, D as DiagramNodeLike, b as DiagramNodeReader, c as PortAnchor, d as DiagramGroup, R as Row, O as Outline, e as PortSpec, B as BodySpec, f as DiagramNode, L as LayoutFn, g as LayoutOptions, M as MeasureRowText, G as GraphSource, F as ForceOptions, h as LayoutResult, i as Graph } from './layout.entry-DyKFfHG5.js';
+export { j as BodyFloor, k as BodyNodeSpec, l as Bounds, m as BuildBodyOptions, n as BuildGraphOptions, C as COMPASS, o as DEFAULT_GROUP_INSET, p as DEFAULT_NODE_GAP, q as DEFAULT_PORTS, r as DEFAULT_RANK_GAP, s as DIAGRAM_TRAIT_KEY, t as DiagramNodeEntry, u as ForceBody, v as ForceRelaxation, w as GraphEdge, x as GraphGroup, y as GraphNode, z as GraphNodeLike, A as GroupInset, E as LayoutAxes, H as LayoutDirection, I as RowBox, J as RowNodeData, K as RowPort, N as RowPortBox, Q as RowTextStyle, S as Slot, T as axesFor, U as backEdges, V as bodyOutline, W as bodyTrait, X as boxForContent, Y as buildBody, Z as buildGraph, _ as canvasMeasure, $ as contentBox, a0 as createDiagramNodes, a1 as dataKeyReader, a2 as diagramNodeOf, a3 as expandGroupEdges, a4 as force, a5 as forceRelaxation, a6 as forestOf, a7 as graphOrder, a8 as insetOf, a9 as isPinned, aa as layered, ab as layoutBody, ac as layoutRowPorts, ad as measureBody, ae as outlinePath, af as outlinePolyline, ag as packAcross, ah as packClusters, ai as pinnedSet, aj as portOf, ak as portsOf, al as portsOnOutline, am as rankGaps, an as ranksOf, ao as rayHit, ap as seededOrder, aq as settle, ar as sizeToBody, as as translated, at as tree, au as untilSettled } from './layout.entry-DyKFfHG5.js';
+import { Vec2, DerivedDep, Path, SceneRegistry, PoseDescriptor, ChromeState, CommandFill, CommandStroke, CursorSpec, Affordance, InvocationCtx, Stroke, GestureBinding, Action, Contribution, RenderLayer, MarkerRef, AddNodeSpec, RectPose, Scene, EasingFn, NodeId, FillStyle, NodeShapeEntry, View, SelectionApi } from '@weasel-js/core';
 import { Vec2 as Vec2$1 } from '@weasel-js/core/math';
 import * as react from 'react';
 import '@weasel-js/geom';
@@ -99,10 +99,17 @@ declare function resolveEnd<TPose>(end: EdgeEnd, dep: DerivedDep<TPose>, toward:
 interface EdgeRouteOptions<TPose> extends PortsOptions<TPose> {
     /** Routers by key. Defaults to {@link ROUTERS}. */
     routers?: Readonly<Record<string, Router$1>>;
+    /** How far outside its node a self-edge with no ports named turns, in
+     *  world units. Defaults to half the node's shorter side. */
+    selfLoopStandoff?: number;
 }
 /**
  * A `derivePath` that routes an edge between its two dependencies.
  *
+ * An edge from a node to itself that names no ports leaves and returns by the
+ * sides {@link selfLoop} picks, and where the author set no waypoints the
+ * router is handed that rule's point outside the node as one.
+ *
  * Returns `null` — nothing to draw — when the node is not an edge, when either
  * dependency is gone, or when an endpoint offers no ports at all. A dangling
  * edge painting a line to the origin is worse than a dangling edge painting
@@ -187,8 +194,8 @@ interface PortAffordanceOptions<TPose> {
     /** Screen-pixel side of the painted square. Default 7. Omit `paint` entirely
      *  by passing 0 — a port the consumer draws itself is still hittable. */
     sizePx?: number;
-    fill?: FillStyle;
-    stroke?: Stroke;
+    fill?: CommandFill;
+    stroke?: CommandStroke;
     cursor?: CursorSpec;
     /** Default `'exclusive'` on pointer gestures: a drag from a port is a
      *  connect, never a move of the node underneath it. */
@@ -367,6 +374,25 @@ declare function diagramPorts<TPose>(opts: DiagramContributionOptions<TPose>): {
     contribution: Contribution;
 };
 
+/** How a self-edge with no ports named leaves its node and comes back. */
+interface SelfLoop {
+    from: Port;
+    to: Port;
+    /** A point outside the node, off the corner between the two sides. */
+    via: Vec2;
+}
+/**
+ * The route a self-edge takes when neither end names a port: out by one side
+ * and back by the next one round, past a point `standoff` clear of both.
+ *
+ * Both ends of such an edge aim at their own node's center, so every port
+ * faces it equally, both pick the same one, and the edge has no length. The
+ * sides are taken by where they face on the page, east and then north, so the
+ * loop sits at the same corner of every node however its ports are listed.
+ * `null` where the node has no two ports facing different ways.
+ */
+declare function selfLoop(ports: readonly Port[], standoff: number): SelfLoop | null;
+
 /**
  * A label on an edge: an ordinary leaf node that derives its *pose* from the
  * route it sits on.
@@ -417,6 +443,65 @@ declare const LABEL_DERIVE_POSE: (node: {
     data: unknown;
 }, deps: readonly (DerivedDep<unknown, unknown, string> | undefined)[]) => unknown;
 
+/**
+ * A group's box, and anything pinned to a point on another node.
+ *
+ * The box is an ordinary node that depends on its members and derives its pose
+ * from theirs: their union, grown by the inset. Drag a member and the box
+ * follows; lay the diagram out and the box lands around wherever the members
+ * went. Nothing has to keep it in sync, because nothing stores it.
+ *
+ * An anchored node — a group's title is the first — derives its pose from one
+ * dependency's bounds the same way, so it travels with the box it labels.
+ */
+
+/** Where an anchored node sits on its dependency. */
+interface DiagramAnchor {
+    /** The point on the dependency's bounds, normalized as a port's is. */
+    at: PortAnchor;
+    /** The point on the node's own bounds that lands there. Default `at`, so
+     *  `{ u: 0, v: 0 }` puts the node's top-left on the dependency's. */
+    self?: PortAnchor;
+    /** Then moved by this much, in world units. */
+    offset?: Vec2$1;
+}
+/** The group trait on a node's data, or `null`. */
+declare function diagramGroupOf(node: {
+    data: unknown;
+}): DiagramGroup | null;
+/** The anchor trait on a node's data, or `null`. */
+declare function diagramAnchorOf(node: {
+    data: unknown;
+}): DiagramAnchor | null;
+/** Options for {@link groupDerivePose} and {@link anchorDerivePose}.
+ *  `geometry` defaults to the kit's `AUTO_POSE_DESCRIPTOR`. */
+interface GroupPoseOptions<TPose> {
+    geometry?: PoseDescriptor<TPose>;
+}
+type DerivePose<TPose> = (node: {
+    pose: TPose;
+    data: unknown;
+}, deps: readonly (DerivedDep<TPose> | undefined)[]) => TPose | null;
+/**
+ * A `derivePose` that draws a group's box around its members: their union,
+ * grown by the trait's inset. `null` — the authored pose stands — when the node
+ * carries no group trait or every member is gone.
+ */
+declare function groupDerivePose<TPose>(opts?: GroupPoseOptions<TPose>): DerivePose<TPose>;
+/**
+ * A `derivePose` that keeps a node at a point on its dependency's bounds.
+ * `null` when the node carries no anchor trait or the dependency is gone.
+ */
+declare function anchorDerivePose<TPose>(opts?: GroupPoseOptions<TPose>): DerivePose<TPose>;
+/** Registry key for {@link GROUP_DERIVE_POSE}. */
+declare const DIAGRAM_GROUP = "diagram:group";
+/** Registry key for {@link ANCHOR_DERIVE_POSE}. */
+declare const DIAGRAM_ANCHOR = "diagram:anchor";
+/** The default group derivation, a stable reference so `toJSON` can find its key. */
+declare const GROUP_DERIVE_POSE: DerivePose<unknown>;
+/** The default anchor derivation, a stable reference for the same reason. */
+declare const ANCHOR_DERIVE_POSE: DerivePose<unknown>;
+
 /**
  * `diagramScene` — a laid-out diagram from plain `{ nodes, edges }`.
  *
@@ -426,6 +511,7 @@ declare const LABEL_DERIVE_POSE: (node: {
  * the same answer in node and in a browser.
  */
 
+/** One node of a {@link DiagramData}: its rows of text, and optionally its outline, ports, size, and starting place. */
 interface DataNode {
     id: string;
     /** Shorthand for one `label` row per line. Ignored when `rows` is given. */
@@ -451,7 +537,9 @@ interface DataNode {
     /** Default `DiagramSceneOptions.verticalAlign`. */
     verticalAlign?: BodySpec['verticalAlign'];
 }
+/** One edge of a {@link DiagramData}, between two nodes or groups by id. */
 interface DataEdge {
+    /** A node's id, or a group's: an edge naming a group meets its box. */
     from: string;
     to: string;
     /** The port to leave from or arrive at. Unset, the end facing the other
@@ -466,10 +554,30 @@ interface DataEdge {
     /** World points the route passes through. Layout does not move them. */
     waypoints?: readonly Vec2$1[];
 }
+/** A box drawn around some nodes, which layout keeps together. */
+interface DataGroup {
+    /** Shares one namespace with node ids. */
+    id: string;
+    /** Node ids, and the ids of groups nested in this one. A node or group a
+     *  later group also names stays in this one; an id that is neither is
+     *  ignored, and so is one that would put a group inside itself. */
+    members: readonly string[];
+    /** Drawn inside the box, above its members. */
+    label?: string;
+    /** Between the box and its members, and around the label. Default
+     *  `DiagramSceneOptions.groupPadding`. */
+    padding?: number;
+}
+/** A diagram as plain data, the input to `diagramScene`. */
 interface DiagramData {
     nodes: readonly DataNode[];
     edges: readonly DataEdge[];
+    /** A group may be a member of another. `layered`, `tree`, and `force` keep
+     *  each group's members together; `'none'` ignores groups but still draws
+     *  them. */
+    groups?: readonly DataGroup[];
 }
+/** The colors and outline a node is drawn with. */
 interface NodeStyle {
     fill: string;
     stroke: string;
@@ -477,6 +585,7 @@ interface NodeStyle {
     strokeWidth?: number;
     dash?: number[];
 }
+/** The stroke, markers, and label color an edge is drawn with. */
 interface EdgeStyle {
     stroke: string;
     width?: number;
@@ -494,9 +603,12 @@ type TextStyle = {
     fontSize: number;
     fontWeight?: number;
 };
+/** The `data` of a scene node `diagramScene` makes: its diagram role, and what it paints. */
 interface DiagramSceneData {
     diagram?: DiagramNode | DiagramEdge | {
         label: DiagramLabel;
+    } | {
+        anchor: DiagramAnchor;
     };
     fill?: {
         color: string;
@@ -505,7 +617,9 @@ interface DiagramSceneData {
     text?: string;
     style?: TextStyle;
 }
+/** A scene node spec, as `diagramScene` returns them. */
 type DiagramSpec = AddNodeSpec<DiagramSceneData, 'main', RectPose>;
+/** How `diagramScene` lays out, routes, and styles a {@link DiagramData}. */
 interface DiagramSceneOptions {
     /** A layout by name, or any `LayoutFn`. Default `'layered'`. `'none'`
      *  leaves every node at its `at`. */
@@ -535,12 +649,18 @@ interface DiagramSceneOptions {
     /** Where edge labels sit. Default `{ at: 'mid', offset: 9 }`. */
     labelPlacement?: DiagramLabel;
     nodeStyle?: (node: DataNode) => NodeStyle;
+    /** Default 12. */
+    groupPadding?: number;
+    /** A group's box and label. `text` colors the label. */
+    groupStyle?: (group: DataGroup) => NodeStyle;
     edgeStyle?: (edge: DataEdge) => EdgeStyle;
 }
+/** The scene node id `diagramScene` gives an edge, built from its ends, ports, and label. */
 declare const edgeIdOf: (e: DataEdge) => string;
-/** Every spec carries an id — a node's own, `<id>/<k>` for its text, and
- *  `<edge id>/label` — so a later call's specs can be reconciled against this
- *  one's. Throws on a repeated node id, which names two nodes as one. An edge whose
+/** Every spec carries an id — a node's own, `<id>/<k>` for its text,
+ *  `<edge id>/label`, a group's own and `<group id>/label` — so a later call's
+ *  specs can be reconciled against this one's. Throws on a repeated id among
+ *  nodes and groups, which names two things as one. An edge whose
  *  end is not a node is dropped, and so is a repeat of an earlier edge with
  *  the same ends, ports and label: it would draw exactly on top of the first. */
 declare function diagramScene(data: DiagramData, opts?: DiagramSceneOptions): DiagramSpec[];
@@ -824,6 +944,7 @@ interface NodeMove {
     x: number;
     y: number;
 }
+/** Props for `DiagramView`. */
 interface DiagramViewProps {
     /** Every spec needs an id, which `diagramScene` gives them. A new array is
      *  reconciled into the scene the view already holds, so the view, the
@@ -845,6 +966,11 @@ interface DiagramViewProps {
     /** Set to make ports grabbable. Dragging one port onto another reports the
      *  edge it describes and draws nothing; add it to the data to keep it. */
     onConnect?: (edge: DataEdge) => void;
+    /** Whether the canvas's keyboard shortcuts — held Space to pan among them —
+     *  run. They listen page-wide, so a view-only diagram beside other UI would
+     *  claim keys meant for the page. Default: on when `onMove` or `onConnect`
+     *  is set. */
+    enableKeybindings?: boolean;
     /** Which ports may be joined. Default: a port may not join itself, and two
      *  typed ports must share a type. */
     canConnect?: CanConnect;
@@ -896,4 +1022,4 @@ declare const DiagramView: react.ForwardRefExoticComponent<DiagramViewProps & re
  *  `<SceneCanvas onClick>`. */
 declare function useMirroredSelection(selection: Pick<SelectionApi, 'get' | 'set'>, selected: string | null | undefined, onSelect: ((id: string | null) => void) | undefined): () => void;
 
-export { type ApplyLayoutOptions, BodySpec, CONNECT_ACTION_ID, type CanConnect, type ConnectActionOptions, DEFAULT_EDGE_STROKE, DIAGRAM_EDGE, DIAGRAM_LABEL, type DataEdge, type DataNode, type DiagramContributionOptions, type DiagramData, type DiagramEdge, type DiagramLabel, DiagramNode, DiagramNodeLike, DiagramNodeReader, type DiagramSceneData, type DiagramSceneOptions, type DiagramShapeOptions, type DiagramSpec, DiagramView, type DiagramViewApi, type DiagramViewProps, EASED_LAYOUTS, EDGE_DERIVE_PATH, type EasedProducerOptions, type EdgeEnd, type EdgeRouteOptions, type EdgeStyle, ForceOptions, type ForceProducerOptions, GRAB_PORT_ACTION_ID, Graph, GraphSource, LABEL_DERIVE_POSE, LAYOUTS, LAYOUT_ACTION_ID, type LabelPoseOptions, type LayoutActionOptions, LayoutFn, LayoutOptions, LayoutResult, type LiveLayout, type LiveLayoutCtx, type LiveLayoutFrame, type LiveLayoutProducer, MeasureRowText, type NodeMove, type NodeStyle, Outline, PORT_AFFORDANCE_KIND, PORT_LAYER_ID, type ParticipantPose, type ParticipantScene, type ParticipantSource, type PendingEdge, Port, type PortAffordanceOptions, type PortScratch, PortSpec, PortsOptions, ROUTERS, type RouteRequest, type Router$1 as Router, Row, type UseLiveLayoutOptions, applyLayout, bezier, commitEdgeToScene, connectBinding, createConnectAction, createDiagramContribution, createLayoutAction, createPortAffordance, defaultCanConnect, diagramEdgeOf, diagramLabelOf, diagramPorts, diagramScene, diagramShape, easedProducer, edgeDerivePath, edgeIdOf, forceProducer, grabPortAction, grabPortBindings, labelDerivePose, layoutPoses, orthogonal, portLayer, portScratchOf, registerDiagramShape, resolveEnd, sceneParticipants, straight, useLiveLayout, useMirroredSelection, withDiagramRegistry };
+export { ANCHOR_DERIVE_POSE, type ApplyLayoutOptions, BodySpec, CONNECT_ACTION_ID, type CanConnect, type ConnectActionOptions, DEFAULT_EDGE_STROKE, DIAGRAM_ANCHOR, DIAGRAM_EDGE, DIAGRAM_GROUP, DIAGRAM_LABEL, type DataEdge, type DataGroup, type DataNode, type DiagramAnchor, type DiagramContributionOptions, type DiagramData, type DiagramEdge, DiagramGroup, type DiagramLabel, DiagramNode, DiagramNodeLike, DiagramNodeReader, type DiagramSceneData, type DiagramSceneOptions, type DiagramShapeOptions, type DiagramSpec, DiagramView, type DiagramViewApi, type DiagramViewProps, EASED_LAYOUTS, EDGE_DERIVE_PATH, type EasedProducerOptions, type EdgeEnd, type EdgeRouteOptions, type EdgeStyle, ForceOptions, type ForceProducerOptions, GRAB_PORT_ACTION_ID, GROUP_DERIVE_POSE, Graph, GraphSource, type GroupPoseOptions, LABEL_DERIVE_POSE, LAYOUTS, LAYOUT_ACTION_ID, type LabelPoseOptions, type LayoutActionOptions, LayoutFn, LayoutOptions, LayoutResult, type LiveLayout, type LiveLayoutCtx, type LiveLayoutFrame, type LiveLayoutProducer, MeasureRowText, type NodeMove, type NodeStyle, Outline, PORT_AFFORDANCE_KIND, PORT_LAYER_ID, type ParticipantPose, type ParticipantScene, type ParticipantSource, type PendingEdge, Port, type PortAffordanceOptions, PortAnchor, type PortScratch, PortSpec, PortsOptions, ROUTERS, type RouteRequest, type Router$1 as Router, Row, type SelfLoop, type UseLiveLayoutOptions, anchorDerivePose, applyLayout, bezier, commitEdgeToScene, connectBinding, createConnectAction, createDiagramContribution, createLayoutAction, createPortAffordance, defaultCanConnect, diagramAnchorOf, diagramEdgeOf, diagramGroupOf, diagramLabelOf, diagramPorts, diagramScene, diagramShape, easedProducer, edgeDerivePath, edgeIdOf, forceProducer, grabPortAction, grabPortBindings, groupDerivePose, labelDerivePose, layoutPoses, orthogonal, portLayer, portScratchOf, registerDiagramShape, resolveEnd, sceneParticipants, selfLoop, straight, useLiveLayout, useMirroredSelection, withDiagramRegistry };