@weasel-js/diagram 1.10.1 → 1.11.0

package/dist/fromData-GKqRgPFs.d.ts

@@ -0,0 +1,379 @@
+import { DerivedDep, PoseDescriptor, NodeShapeEntry, MarkerRef, AddNodeSpec, Stroke, RectPose } from '@weasel-js/core';
+import { P as PortAnchor, D as DiagramGroup, R as RowTextStyle, a as Row, O as Outline, b as PortSpec, B as BodySpec, L as LayoutPorts, c as LayoutFn, d as LayoutOptions, M as MeasureRowText, e as DiagramNode } from './body-2lC7IiIA.js';
+import { Vec2 } from '@weasel-js/core/math';
+
+/**
+ * The label trait: where along its edge a label sits. Data only — placing the
+ * label on the route is `label`'s job, so layout can read one without
+ * reaching the scene.
+ */
+
+/** Where along an edge a label sits. */
+interface DiagramLabel {
+    /** `'start'`, `'mid'` and `'end'` are 0, 0.5 and 1; a number is that
+     *  fraction of the route's length. `{ near }` is the point on the route
+     *  nearest `near`, in world coordinates — where `layered` leaves a label
+     *  room — so a bend added or removed elsewhere leaves the label on the
+     *  stretch it was on. */
+    at: 'start' | 'mid' | 'end' | number | {
+        near: Vec2;
+    };
+    /** World units between the route and the label's near side, to the **left
+     *  of the direction of travel** — above a left-to-right edge. Default 0,
+     *  which centers the label on the line. */
+    offset?: number;
+}
+/** The label trait on a node's data, or `null`. */
+declare function diagramLabelOf(node: {
+    data: unknown;
+}): DiagramLabel | null;
+
+/**
+ * The edge trait: what an edge's `data` says about its ends and its route, and
+ * who owns each. Data only — the routers and the scene wiring are in `edge`,
+ * so layout can read an edge without reaching the scene.
+ */
+
+/** Where an edge attaches at one end. */
+interface EdgeEnd {
+    /** The port to leave from, when the endpoint declares one. Falls back to
+     *  the nearest port, so an edge drawn before ports were thought about still
+     *  meets the shape. */
+    port?: string;
+    /** The port layout last named here. While `port` still equals it, or names
+     *  none, layout owns the end and names it again on its next run. */
+    laidOut?: string;
+}
+/** Whether layout may name this end's port: it names none, or only the one
+ *  layout last named. */
+declare function layoutOwnsPort(end: EdgeEnd): boolean;
+/** The trait on an edge's `data`, under the same key participants use. */
+interface DiagramEdge {
+    from: EdgeEnd;
+    to: EdgeEnd;
+    /** Registry key for the router. Resolved by whoever builds the edge's
+     *  `derivePath`; unknown keys fall back to `straight`. */
+    router?: string;
+    /** Points in world coordinates the route must pass through, in order. The
+     *  author owns these; the router owns everything between them. */
+    waypoints?: readonly Vec2[];
+    /** The waypoints layout last wrote here. While `waypoints` still equals
+     *  them, layout owns the route and rewrites it on its next run; once anyone
+     *  edits them, they are the author's and layout leaves them alone. */
+    laidOut?: readonly Vec2[];
+}
+/** Whether layout may rewrite this edge's route: it has no waypoints, or only
+ *  the ones layout last wrote. */
+declare function layoutOwnsRoute(edge: DiagramEdge): boolean;
+/** The edge trait on a node's data, or `null`. */
+declare function diagramEdgeOf(node: {
+    data: unknown;
+}): DiagramEdge | null;
+
+/**
+ * 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;
+}
+/** 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>;
+}
+/** A `derivePose` function as the scene calls it: the node, then what it depends on, in `dependsOn` order. */
+type DiagramDerivePose<TPose> = (node: {
+    pose: TPose;
+    data: unknown;
+}, deps: readonly (DerivedDep<TPose> | undefined)[]) => TPose | null;
+/**
+ * A `derivePose` that draws a group's box around its members: the union of
+ * what each takes up, its `margin` included, 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>): DiagramDerivePose<TPose>;
+/** A group's box around the union of its members: grown by its inset, and
+ *  widened evenly to its `minWidth`. */
+declare function boxAround(union: {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}, group: DiagramGroup): {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+};
+/**
+ * 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>): DiagramDerivePose<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: DiagramDerivePose<unknown>;
+/** The default anchor derivation, a stable reference for the same reason. */
+declare const ANCHOR_DERIVE_POSE: DiagramDerivePose<unknown>;
+
+/**
+ * Marks: what a data node draws besides its rows. A drawn mark is SVG path
+ * data in a unit square, stretched over the node's box, so it follows the node
+ * wherever layout or a drag puts it. A text mark is pinned to a point on the box.
+ */
+
+/** One mark on a `DataNode`. Colors default to the node's stroke and text. */
+type DataMark = {
+    d: string;
+    fill?: string;
+    stroke?: string;
+    strokeWidth?: number;
+    dash?: number[];
+    opacity?: number;
+} | {
+    text: string;
+    at: PortAnchor;
+    self?: PortAnchor;
+    offset?: Vec2;
+    color?: string;
+    style?: RowTextStyle;
+};
+/** The trait on a drawn mark's `data`: path data in a unit square. */
+interface DiagramMark {
+    d: string;
+}
+/** The mark a scene node carries, or null for a node that is not a drawn
+ *  mark: how `markShape` tells which nodes it paints. */
+declare function diagramMarkOf(node: {
+    data: unknown;
+}): DiagramMark | null;
+/** The painter for a drawn mark. */
+declare function markShape<TPose>(opts?: {
+    geometry?: PoseDescriptor<TPose>;
+}): NodeShapeEntry<unknown, TPose>;
+/** Register {@link markShape}; returns the disposer. */
+declare function registerMarkShape<TPose>(opts?: {
+    geometry?: PoseDescriptor<TPose>;
+}): () => void;
+
+/**
+ * `diagramScene` — a laid-out diagram from plain `{ nodes, edges }`.
+ *
+ * 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.
+ */
+
+/** 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. */
+    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[];
+    /** Labels for the perimeter ports by id, drawn outside the box beside each. */
+    portLabels?: Readonly<Record<string, string>>;
+    /** 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;
+    /** 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'];
+    /** Drawn over the box besides its rows: shapes in a unit square stretched
+     *  over it, and text pinned to a point on it. */
+    marks?: readonly DataMark[];
+}
+/** 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
+     *  node most directly. */
+    fromPort?: string;
+    toPort?: string;
+    label?: string;
+    /** Where along the edge the label sits. Unset or at `'mid'`, under
+     *  `layered` the label sits in the room layout leaves it beside its wire,
+     *  at this placement's offset, else `DiagramSceneOptions.labelPlacement`'s;
+     *  otherwise at the placement. */
+    labelPlacement?: DiagramLabel;
+    /** Default `DiagramSceneOptions.router`. */
+    router?: DiagramRouter;
+    /** World points the route passes through. Layout does not move them. */
+    waypoints?: readonly Vec2[];
+    /** A route a layout run wrote, as `DiagramView`'s `onMove` reports it: drawn
+     *  until layout runs again, which may replace it. `waypoints` wins. */
+    routed?: readonly Vec2[];
+    /** Ports a layout run named, as `onMove` reports them: used like `routed`,
+     *  and not part of the edge's id. `fromPort` and `toPort` win. */
+    routedPorts?: LayoutPorts;
+}
+/** 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; `chain` and `'none'` ignore groups but
+     *  still draw them. */
+    groups?: readonly DataGroup[];
+}
+/** The colors and outline a node is drawn with. */
+interface NodeStyle {
+    fill: string;
+    stroke: string;
+    text: string;
+    strokeWidth?: number;
+    dash?: number[];
+}
+/** The stroke, markers, and label color an edge is drawn with. */
+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;
+}
+/** How an edge is drawn between its ends. */
+type DiagramRouter = 'straight' | 'bezier' | 'orthogonal';
+/** The face a diagram node's text is set in. */
+type DiagramTextStyle = {
+    fontFamily: string;
+    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;
+    } | {
+        mark: DiagramMark;
+    };
+    fill?: {
+        paint: {
+            color: string;
+            opacity?: number;
+        };
+    };
+    stroke?: Stroke;
+    text?: string;
+    style?: DiagramTextStyle;
+    /** What a slot is filled with: an image the kit's image painter draws. */
+    image?: {
+        src: string;
+        opacity?: number;
+    };
+}
+/** 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`. */
+    layout?: 'layered' | 'tree' | 'force' | 'chain' | 'none' | LayoutFn;
+    /** Merged over `{ order: 'barycenter' }`. */
+    layoutOptions?: LayoutOptions;
+    /** Default `'bezier'`. */
+    router?: DiagramRouter;
+    /** 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;
+    /** 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. Two edges differing in any of those get different ids, an empty
+ *  port or label included: a `.`, `>`, `:`, `/` or `\` in one of them is
+ *  escaped with a backslash. */
+declare const edgeIdOf: (e: DataEdge) => string;
+/** Every spec carries an id — a node's own, `<id>/<k>` for its text,
+ *  `<id>/mark:<i>` for its marks, `<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[];
+
+export { ANCHOR_DERIVE_POSE as A, edgeIdOf as B, groupDerivePose as C, type DiagramData as D, type EdgeStyle as E, layoutOwnsPort as F, GROUP_DERIVE_POSE as G, layoutOwnsRoute as H, markShape as I, registerMarkShape as J, type NodeStyle as N, type DiagramSceneOptions as a, type DataEdge as b, type DataNode as c, type DiagramRouter as d, type DiagramSpec as e, type EdgeEnd as f, DIAGRAM_ANCHOR as g, DIAGRAM_GROUP as h, type DataGroup as i, type DataMark as j, type DiagramAnchor as k, type DiagramDerivePose as l, type DiagramEdge as m, type DiagramLabel as n, type DiagramMark as o, type DiagramSceneData as p, type DiagramTextStyle as q, type GroupPoseOptions as r, anchorDerivePose as s, boxAround as t, diagramAnchorOf as u, diagramEdgeOf as v, diagramGroupOf as w, diagramLabelOf as x, diagramMarkOf as y, diagramScene as z };