@weasel-js/diagram 1.9.1 → 1.9.2

package/dist/index.d.ts

@@ -1,9 +1,9 @@
-import { P as Port, a as PortsOptions, D as DiagramNodeLike, b as DiagramNodeReader, c as DiagramNode, L as LayoutFn, d as LayoutOptions, F as ForceOptions, e as LayoutResult, G as GraphSource, f as Graph } from './layout.entry-ClWUwH16.js';
-export { B as BodyFloor, g as BodyNodeSpec, h as BodySpec, i as Bounds, j as BuildBodyOptions, k as BuildGraphOptions, C as COMPASS, l as DEFAULT_NODE_GAP, m as DEFAULT_PORTS, n as DEFAULT_RANK_GAP, o as DIAGRAM_TRAIT_KEY, p as DiagramNodeEntry, q as ForceBody, r as ForceRelaxation, s as GraphEdge, t as GraphNode, u as GraphNodeLike, v as LayoutAxes, w as LayoutDirection, M as MeasureRowText, O as Outline, x as PortAnchor, y as PortSpec, R as Row, 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-ClWUwH16.js';
-import { Vec2, DerivedDep, Path, SceneRegistry, PoseDescriptor, ChromeState, FillStyle, Stroke, CursorSpec, Affordance, InvocationCtx, GestureBinding, Action, Contribution, RenderLayer, AddNodeSpec, RectPose, EasingFn, NodeId, Scene, NodeShapeEntry, SelectionApi } from '@weasel-js/core';
+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 { Vec2 as Vec2$1 } from '@weasel-js/core/math';
 import * as react from 'react';
 import '@weasel-js/geom';
-import '@weasel-js/core/math';
 
 /**
  * `DiagramEdge` — a connection between two participants.
@@ -54,9 +54,9 @@ interface RouteRequest {
 /** A router returns the points the edge runs through, `from.point` first and
  *  `to.point` last. Turning those into a `Path` is `edgePath`'s job, so a
  *  router never has to know about path encodings. */
-type Router = (req: RouteRequest) => readonly Vec2[];
+type Router$1 = (req: RouteRequest) => readonly Vec2[];
 /** The straight run between the two ends, through any waypoints. */
-declare const straight: Router;
+declare const straight: Router$1;
 /**
  * An axis-aligned route: leave along the departing end's normal and arrive
  * against the receiving one's.
@@ -67,7 +67,7 @@ declare const straight: Router;
  * shape — a route that lands on a west-facing port from above puts its marker
  * across the corner, which reads as aimed at nothing.
  */
-declare const orthogonal: Router;
+declare const orthogonal: Router$1;
 /**
  * A smooth route, sampled into points.
  *
@@ -79,9 +79,9 @@ declare const orthogonal: Router;
  * every router returns the same thing; `edgePath` is free to emit curves later
  * without changing the contract.
  */
-declare const bezier: Router;
+declare const bezier: Router$1;
 /** The routers this package ships. A consumer's own go in the same shape. */
-declare const ROUTERS: Readonly<Record<string, Router>>;
+declare const ROUTERS: Readonly<Record<string, Router$1>>;
 /** The edge trait on a node's data, or `null`. */
 declare function diagramEdgeOf(node: {
     data: unknown;
@@ -98,7 +98,7 @@ declare function resolveEnd<TPose>(end: EdgeEnd, dep: DerivedDep<TPose>, toward:
 /** Options for {@link edgeDerivePath}. */
 interface EdgeRouteOptions<TPose> extends PortsOptions<TPose> {
     /** Routers by key. Defaults to {@link ROUTERS}. */
-    routers?: Readonly<Record<string, Router>>;
+    routers?: Readonly<Record<string, Router$1>>;
 }
 /**
  * A `derivePath` that routes an edge between its two dependencies.
@@ -272,7 +272,7 @@ interface ConnectActionOptions<TPose> {
     /** Registry key the new edge names, and the router the preview draws with.
      *  Default `'straight'`. */
     router?: string;
-    routers?: Readonly<Record<string, Router>>;
+    routers?: Readonly<Record<string, Router$1>>;
     /**
      * Mints and commits the edge. Called once, on release over a valid port.
      *
@@ -420,18 +420,51 @@ declare const LABEL_DERIVE_POSE: (node: {
 /**
  * `diagramScene` — a laid-out diagram from plain `{ nodes, edges }`.
  *
- * Sizes are estimated from character counts, not measured, so layout runs
- * without a canvas and gives the same answer in node and in a browser.
+ * Every box is a `buildBody` body, so a data node can say anything a body
+ * can: outline, rows, padding, ports. Sizes are estimated from character
+ * counts unless `measure` is given, so layout runs without a canvas and gives
+ * the same answer in node and in a browser.
  */
 
 interface DataNode {
     id: string;
-    lines: readonly string[];
+    /** Shorthand for one `label` row per line. Ignored when `rows` is given. */
+    lines?: readonly string[];
+    rows?: readonly Row[];
+    /** Default `DiagramSceneOptions.outline`, which defaults to `'rect'`. */
+    outline?: Outline;
+    /** Perimeter ports, replacing the four compass midpoints. */
+    ports?: readonly PortSpec[];
+    /** Layout leaves this node at `at`. */
+    pinned?: boolean;
+    /** Where the node starts, before layout. Unset, nodes start on the
+     *  diagonal in source order, which is what within-rank order is seeded
+     *  from. */
+    at?: Vec2$1;
+    /** The smallest the box may be. Its content grows it past this. */
+    width?: number;
+    height?: number;
+    /** Default `DiagramSceneOptions.padding`. */
+    padding?: number;
+    /** Default `DiagramSceneOptions.gap`. */
+    gap?: number;
+    /** Default `DiagramSceneOptions.verticalAlign`. */
+    verticalAlign?: BodySpec['verticalAlign'];
 }
 interface DataEdge {
     from: string;
     to: string;
+    /** The port to leave from or arrive at. Unset, the end facing the other
+     *  node most directly. */
+    fromPort?: string;
+    toPort?: string;
     label?: string;
+    /** Where along the edge the label sits. Default `DiagramSceneOptions.labelPlacement`. */
+    labelPlacement?: DiagramLabel;
+    /** Default `DiagramSceneOptions.router`. */
+    router?: Router;
+    /** World points the route passes through. Layout does not move them. */
+    waypoints?: readonly Vec2$1[];
 }
 interface DiagramData {
     nodes: readonly DataNode[];
@@ -442,11 +475,25 @@ interface NodeStyle {
     stroke: string;
     text: string;
     strokeWidth?: number;
+    dash?: number[];
 }
 interface EdgeStyle {
     stroke: string;
     width?: number;
+    dash?: number[];
+    /** `null` for none. Default none. */
+    markerStart?: MarkerRef | null;
+    /** `null` for none. Default `'arrow'`. */
+    markerEnd?: MarkerRef | null;
+    /** Default `stroke`. */
+    label?: string;
 }
+type Router = 'straight' | 'bezier' | 'orthogonal';
+type TextStyle = {
+    fontFamily: string;
+    fontSize: number;
+    fontWeight?: number;
+};
 interface DiagramSceneData {
     diagram?: DiagramNode | DiagramEdge | {
         label: DiagramLabel;
@@ -456,27 +503,46 @@ interface DiagramSceneData {
     };
     stroke?: Stroke;
     text?: string;
-    style?: {
-        fontFamily: string;
-        fontSize: number;
-    };
+    style?: TextStyle;
 }
 type DiagramSpec = AddNodeSpec<DiagramSceneData, 'main', RectPose>;
 interface DiagramSceneOptions {
-    layout?: LayoutFn;
+    /** A layout by name, or any `LayoutFn`. Default `'layered'`. `'none'`
+     *  leaves every node at its `at`. */
+    layout?: 'layered' | 'tree' | 'force' | 'none' | LayoutFn;
+    /** Merged over `{ order: 'barycenter' }`. */
     layoutOptions?: LayoutOptions;
-    router?: 'straight' | 'bezier' | 'orthogonal';
+    /** Default `'bezier'`. */
+    router?: Router;
+    /** The text style rows fall back on. Default 12px sans-serif. */
     font?: {
         fontFamily: string;
         fontSize: number;
     };
+    /** Measures one run of text. Default an estimate from character count, so
+     *  layout needs no canvas; pass `canvasMeasure(ctx)` for real widths. */
+    measure?: MeasureRowText;
+    /** Default `'rect'`. */
+    outline?: Outline;
+    /** Between a box's outline and its rows. Default 8. */
+    padding?: number;
+    /** Between adjacent rows. Default 4. */
+    gap?: number;
+    /** Where a box's rows sit when it is taller than they need. Default `'center'`. */
+    verticalAlign?: BodySpec['verticalAlign'];
+    /** The narrowest a box may be. Default 64. */
+    minWidth?: number;
+    /** Where edge labels sit. Default `{ at: 'mid', offset: 9 }`. */
+    labelPlacement?: DiagramLabel;
     nodeStyle?: (node: DataNode) => NodeStyle;
     edgeStyle?: (edge: DataEdge) => EdgeStyle;
 }
 declare const edgeIdOf: (e: DataEdge) => string;
-/** 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, 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
  *  end is not a node is dropped, and so is a repeat of an earlier edge with
- *  the same ends and label: it would draw exactly on top of the first. */
+ *  the same ends, ports and label: it would draw exactly on top of the first. */
 declare function diagramScene(data: DiagramData, opts?: DiagramSceneOptions): DiagramSpec[];
 
 /** What a live producer is told, and what it answers with. */
@@ -752,7 +818,17 @@ declare function diagramShape<TPose>(opts?: DiagramShapeOptions<TPose>): NodeSha
  */
 declare function registerDiagramShape<TPose>(opts?: DiagramShapeOptions<TPose>): () => void;
 
+/** Where a moved node now stands. */
+interface NodeMove {
+    id: string;
+    x: number;
+    y: number;
+}
 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
+     *  selection and anything moved since stay put unless the new specs change
+     *  them. Pass a new `key` to start over instead. */
     specs: readonly DiagramSpec[];
     width: number;
     height: number;
@@ -762,20 +838,57 @@ interface DiagramViewProps {
      *  picked node reports it again. The canvas keeps the pick even if
      *  `selected` does not follow it; only a change to `selected` is pushed in. */
     onSelect?: (id: string | null) => void;
+    /** Set to let nodes be dragged. Reports every node a drag or a layout run
+     *  moved. Store each as the data node's `at` with `pinned: true`, or the
+     *  next `diagramScene` lays it out again. */
+    onMove?: (moves: readonly NodeMove[]) => void;
+    /** 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;
+    /** Which ports may be joined. Default: a port may not join itself, and two
+     *  typed ports must share a type. */
+    canConnect?: CanConnect;
+    /** How ports look and answer the pointer, and the router a connect's
+     *  preview draws with. */
+    portOptions?: Pick<DiagramContributionOptions<RectPose>, 'fill' | 'stroke' | 'sizePx' | 'hitRadiusPx' | 'cursor' | 'shows' | 'snapRadius' | 'router'>;
+    /** How a layout run from {@link DiagramViewApi.layout} behaves: its forces,
+     *  how many frames an eased layout takes, its easing. */
+    live?: Omit<UseLiveLayoutOptions<RectPose>, 'scene' | 'source' | 'algorithm'>;
     /** The smallest scale the initial fit may use. Unset, the whole diagram fits
      *  however small that makes it; set, it stops here and the rest is a pan away. */
     minScale?: number;
+    /** The largest scale the initial fit may use. Default 1, so a small
+     *  diagram opens at its own size rather than blown up. */
+    maxScale?: number;
     /** Which part of a diagram too big for the box it opens on: its middle
      *  (default) or its top-left, where a layered flow begins. */
     anchor?: 'center' | 'start';
+    /** Space kept clear around the diagram by the initial fit, in CSS pixels.
+     *  Default 16. */
+    fitPadding?: number;
+    /** What the canvas paints behind the diagram. Unset, it is transparent. */
+    background?: FillStyle;
+    /** The view, controlled. Set it and the initial fit is skipped; pair it
+     *  with `onViewChange` or panning does nothing. */
+    view?: View;
+    /** Every view change, from a pan, a zoom or the initial fit. */
+    onViewChange?: (view: View) => void;
     className?: string;
 }
-/** A read-only diagram: drag or wheel to pan, zoom, and pick a node, nothing else. A new `specs`
- *  array is a new scene, fitted to the box, so memoize it: one built inline
- *  remounts the scene on every render. Labels paint only in a registered font
- *  family; `diagramScene` defaults to sans-serif, so call
+/** What a `ref` on `DiagramView` holds. */
+interface DiagramViewApi {
+    /** Lay the diagram out again from where its nodes stand, animated. `'force'`
+     *  (default) relaxes until it settles; any other layout eases to its answer.
+     *  What moved is reported to `onMove` once the run settles. */
+    layout(algorithm?: 'layered' | 'tree' | 'force' | LayoutFn): void;
+    /** The run `layout` started: stop it where it stands, or cancel it. */
+    live: LiveLayout;
+}
+/** A diagram: drag or wheel to pan, zoom, and pick a node; drag nodes with
+ *  `onMove`, join ports with `onConnect`. Labels paint only in a registered
+ *  font family; `diagramScene` defaults to sans-serif, so call
  *  `registerCanvasFont('sans-serif')` or text renders blank. */
-declare function DiagramView(props: DiagramViewProps): react.JSX.Element;
+declare const DiagramView: react.ForwardRefExoticComponent<DiagramViewProps & react.RefAttributes<DiagramViewApi>>;
 
 /** Keeps a canvas selection and a controlled `selected` prop in step: a prop
  *  change is pushed in, and every click reports what the selection holds after
@@ -783,4 +896,4 @@ declare function DiagramView(props: DiagramViewProps): react.JSX.Element;
  *  `<SceneCanvas onClick>`. */
 declare function useMirroredSelection(selection: Pick<SelectionApi, 'get' | 'set'>, selected: string | null | undefined, onSelect: ((id: string | null) => void) | undefined): () => void;
 
-export { type ApplyLayoutOptions, 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 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, type NodeStyle, PORT_AFFORDANCE_KIND, PORT_LAYER_ID, type ParticipantPose, type ParticipantScene, type ParticipantSource, type PendingEdge, Port, type PortAffordanceOptions, type PortScratch, PortsOptions, ROUTERS, type RouteRequest, type Router, 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 { 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 };