@weasel-js/diagram 1.11.0 → 1.11.1

package/dist/stageTypes-DvnR8cKQ.d.ts

@@ -0,0 +1,189 @@
+import { Page } from '@weasel-js/core';
+import { Vec2 } from '@weasel-js/core/math';
+
+/** An effects pipeline as plain data. It says what is wired to what and
+ *  nothing about how any of it is drawn. */
+interface EffectPipeline {
+    stages: readonly EffectStage[];
+    wires: readonly EffectWire[];
+    groups?: readonly EffectGroup[];
+    /** What the value types mean. A type no entry names is plain data. */
+    types?: Readonly<Record<string, EffectType>>;
+}
+/** One step of a pipeline: what it reads and writes, and what its box shows. */
+interface EffectStage {
+    id: string;
+    title: string;
+    /** What sort of stage this is, for a look to read. The shipped looks know
+     *  'stage' (default), 'decision', 'source' and 'sink', and draw any other
+     *  value as 'stage'. */
+    kind?: string;
+    /** Which palette entry or template made this stage. A tag for an editor to
+     *  read: no shipped look draws differently for it. */
+    type?: string;
+    inputs?: readonly EffectPort[];
+    outputs?: readonly EffectPort[];
+    /** Settings worth showing, in order. */
+    params?: readonly EffectParam[];
+    /** For a decision that splits on a number: the input it compares, and the
+     *  cut points in ascending order. N cuts need N + 1 outputs, the lowest
+     *  band first. */
+    split?: {
+        input: string;
+        at: readonly number[];
+    };
+    /** The stage is in the pipeline and switched off. */
+    bypassed?: boolean;
+    /** Anything else a look wants. No shipped look reads it. */
+    data?: Readonly<Record<string, unknown>>;
+}
+/** One input or output of a stage, carrying a value of one type. */
+interface EffectPort {
+    /** Unique among the stage's inputs and outputs together. */
+    id: string;
+    /** Default the id. */
+    label?: string;
+    type: string;
+}
+/** A connection from one stage's output to another stage's input. */
+interface EffectWire {
+    /** Carried to the drawn edge's `DataEdge.id`, so the wire can be found again. */
+    id?: string;
+    from: {
+        stage: string;
+        port: string;
+    };
+    to: {
+        stage: string;
+        port: string;
+    };
+    /** Drawn on the wire. */
+    label?: string;
+}
+/** A box drawn around some stages, and around other groups. */
+interface EffectGroup {
+    id: string;
+    label?: string;
+    /** Stage ids and group ids. */
+    members: readonly string[];
+}
+/** One run of a pipeline: what happened, beside the pipeline rather than in
+ *  it, so it can change every frame while the pipeline and its layout stay
+ *  put. A stage the run has no entry for is one it never reached. */
+interface EffectRun {
+    stages: Readonly<Record<string, EffectStageRun>>;
+    /** The stage a run taken a step at a time is on, drawn outlined. */
+    at?: string;
+}
+/** What one stage did in a run. */
+interface EffectStageRun {
+    /** How long it took, in milliseconds. */
+    cost?: number;
+    /** For a decision: the output it chose. */
+    taken?: string;
+    /** What each output carried, by port id, as text to show; for a stage with
+     *  no outputs, what reached each input. */
+    values?: Readonly<Record<string, string>>;
+    /** What each port `values` covers carried, by port id, as a picture, drawn in the slot a
+     *  look keeps for it (`showPreviews`). A bitmap rather than a canvas
+     *  because its pixels cannot change: hand back the same one and nothing is
+     *  uploaded again; draw new pixels into a new one. */
+    previews?: Readonly<Record<string, ImageBitmap>>;
+    /** Why the stage failed, written where its cost goes. What it feeds is
+     *  left unreached. */
+    error?: string;
+}
+/** What a value type means, as `EffectPipeline.types` records it. */
+interface EffectType {
+    /** A control value: a condition, a gate, a modulation source. Looks draw
+     *  its wires apart from data wires. */
+    control?: boolean;
+}
+/** How a param is edited, and the value it holds. */
+type EffectParamControl = {
+    kind: 'number';
+    value: number;
+    min?: number;
+    max?: number;
+    step?: number;
+    unit?: string;
+} | {
+    kind: 'enum';
+    value: string;
+    options: readonly {
+        value: string;
+        label?: string;
+    }[];
+} | {
+    kind: 'boolean';
+    value: boolean;
+} | {
+    kind: 'string';
+    value: string;
+};
+/** One setting a stage shows. `value` is the display string; `control`, when
+ *  present, is what an editor changes and `value` is its formatted form. */
+interface EffectParam {
+    /** Addresses the param when labels repeat; the label stands in when absent. */
+    id?: string;
+    label: string;
+    value: string;
+    control?: EffectParamControl;
+}
+/** Where each stage sits, by stage id, beside the pipeline rather than in it. */
+type EffectPlaces = Readonly<Record<string, Vec2>>;
+/** A pipeline and where its stages sit: what an editor holds and changes. */
+interface EffectDoc {
+    pipeline: EffectPipeline;
+    places: EffectPlaces;
+    /** The pages the stages are drawn across under `nodeGraph`, beside the
+     *  pipeline as `places` is. A wire between stages on different pages is
+     *  drawn as two stubs with off-page tags. The other looks ignore them. */
+    pages?: readonly Page[];
+    /** The value types whose lanes the `lanes` look draws first, top down. */
+    laneOrder?: readonly string[];
+    /** The waypoints a person routed each wire through under `nodeGraph`, by
+     *  wire id, beside the pipeline as `places` is. */
+    routes?: Readonly<Record<string, readonly Vec2[]>>;
+    /** The routes a person drew under `rack` and `lanes`, by look, then by wire id. */
+    lookRoutes?: LookRoutes;
+    /** Each group's box under `nodeGraph`, by group id, beside the pipeline as
+     *  `places` is. A group with none fits its members. */
+    groupBoxes?: Readonly<Record<string, EffectBox>>;
+}
+/** A box on the page, in world units. */
+interface EffectBox {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+/** A wire's route under a look that places its stages itself. */
+interface LookRoute {
+    waypoints: readonly Vec2[];
+    /** Where the wire's from and to ports were when it was routed. The route
+     *  is drawn only while they are still there: a reorder or an added stage
+     *  moves stages, and a route drawn for one arrangement means nothing in another. */
+    ends: readonly [Vec2, Vec2];
+}
+/** `EffectDoc.lookRoutes`. */
+interface LookRoutes {
+    rack?: Readonly<Record<string, LookRoute>>;
+    lanes?: Readonly<Record<string, LookRoute>>;
+}
+
+/** A palette entry: a stage's ports and params, ready to be copied into a pipeline. */
+interface EffectStageType {
+    type: string;
+    title: string;
+    kind?: string;
+    inputs?: readonly EffectPort[];
+    outputs?: readonly EffectPort[];
+    params?: readonly EffectParam[];
+}
+/** A stage of type `t` with its own copy of the ports and params; no link back. */
+declare function stageFromType(t: EffectStageType, id: string): EffectStage;
+/** The display string for a control's value, to as many places as its `step` has (one without a step). */
+declare function formatParam(control: EffectParamControl): string;
+
+export { type EffectPipeline as E, type LookRoutes as L, type EffectRun as a, type EffectStageType as b, type EffectDoc as c, type EffectWire as d, type EffectStage as e, type EffectPort as f, type EffectGroup as g, type EffectParamControl as h, type EffectBox as i, type EffectParam as j, type EffectPlaces as k, type EffectStageRun as l, type EffectType as m, type LookRoute as n, formatParam as o, stageFromType as s };

package/dist/{body-2lC7IiIA.d.ts → types-BbHunLXm.d.ts}

@@ -1,12 +1,12 @@
-import * as _weasel_js_geom from '@weasel-js/geom';
 import { Path, Vec2, PoseDescriptor } from '@weasel-js/core/math';
+import * as _weasel_js_geom from '@weasel-js/geom';
 
 /**
  * The shapes a built body can wear, as paths in the node's bounds.
  *
  * These are the flowchart vocabulary — a decision is a diamond, an I/O step a
- * parallelogram, a terminator a stadium, a demultiplexer a trapezoid, a preparation step a hexagon —
- * plus `'rect'` for everything else and
+ * parallelogram, a terminator a stadium, a demultiplexer a trapezoid, a preparation step a hexagon,
+ * a connector an ellipse — plus `'rect'` for everything else and
  * a `Path` escape hatch for a shape the vocabulary does not have. The path is
  * built in world coordinates from the bounds it is given, the same way the
  * kit's own `clipFromPose` factories are; a custom `Path` is drawn in a unit
@@ -26,7 +26,7 @@ interface Bounds {
 /** A named flowchart shape, or a path a consumer built themselves in a unit
  *  square — `(0, 0)` the box's top-left, `(1, 1)` its bottom-right — so it
  *  follows its node wherever layout or a drag puts it. */
-type Outline = 'rect' | 'diamond' | 'stadium' | 'parallelogram' | 'trapezoid' | 'hexagon' | Path;
+type Outline = 'rect' | 'diamond' | 'stadium' | 'ellipse' | 'parallelogram' | 'trapezoid' | 'hexagon' | Path;
 /** The path `outline` describes inside `bounds`. A zero-area box gives a
  *  zero-area rect rather than a degenerate polygon. */
 declare function outlinePath(outline: Outline, bounds: Bounds): Path;
@@ -57,6 +57,97 @@ declare function boxForContent(outline: Outline, content: {
     height: number;
 };
 
+/**
+ * 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;
+    /** Where label placement moved it, off a station something covered:
+     *  `at` a fraction of the route's length, `offset` as above. Read in place
+     *  of `at` and `offset`, which stay the author's preference. Written only
+     *  by placement (`installLabelPlacement`). */
+    placed?: LabelSpot;
+    /** `false` keeps placement from ever moving this label. */
+    dodge?: false;
+}
+/** A station placement chose: a fraction of the route's length, and the
+ *  offset from the line. */
+interface LabelSpot {
+    at: number;
+    offset: number;
+}
+/** Where an edge label sits when neither the edge nor the scene says. */
+declare const LABEL_PLACEMENT: DiagramLabel;
+/** The label trait on a node's data, or `null`. */
+declare function diagramLabelOf(node: {
+    data: unknown;
+}): DiagramLabel | null;
+
+/**
+ * The container trait: what makes a core `ContainerNode` a diagram container,
+ * a pool, or one of a pool's lanes, and where its header is.
+ *
+ * A container's title is a text child in its header, named
+ * `<container id>/title`. The layouts find it by that name, because a layout
+ * strategy sees only ids and poses.
+ */
+
+/** Which kind of region a container is. */
+type ContainerRole = 'container' | 'pool' | 'lane';
+/** The strip a container's title sits in, along one side. */
+interface ContainerHeader {
+    side: 'top' | 'left';
+    /** Its depth into the container, in world units. */
+    size: number;
+}
+/** The container half of a diagram node's trait, under `data.diagram.container`. */
+interface DiagramContainer {
+    role: ContainerRole;
+    header?: ContainerHeader;
+    /** Its box is fitted to its members each time the diagram is built from data
+     *  (`DataContainer` with no `box`), so a move that carries it along is no edit of its own. */
+    fitted?: true;
+}
+type Box = {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+};
+/** The container trait on a node's data, or `null`. */
+declare function diagramContainerOf(node: {
+    data: unknown;
+}): DiagramContainer | null;
+/** The id of a container's title node. */
+declare const titleIdOf: (containerId: string) => string;
+/** The header strip of a container at `bounds`; null with no header. */
+declare function headerBox(bounds: Box, header: ContainerHeader | undefined): Box | null;
+/** What a container at `bounds` holds members in: everything past its header. */
+declare function bodyBox(bounds: Box, header: ContainerHeader | undefined): Box;
+
+/** A color on a shape or connector that the author can set by hand, and a theme then leaves alone.
+ *  On a connector, `text` is its label's color. */
+type StyleField = 'fill' | 'stroke' | 'text';
+/** A part of a shape's or connector's text face the author can set by hand, which a theme then
+ *  leaves alone. Kept apart from {@link StyleField}, so choosing a role, which hands back the
+ *  colors, keeps it. */
+type FontField = 'size';
+
 /**
  * Where a port sits on its node, in **normalized bounds coordinates**:
  * `(0, 0)` is the top-left corner of the node's AABB and `(1, 1)` the
@@ -119,9 +210,28 @@ interface DiagramNode {
      *  itself is never laid out — it derives its pose from its members — but an
      *  edge can attach to it like any participant. */
     group?: DiagramGroup;
+    /** Present on a container, a pool, or a lane: a `ContainerNode` holding
+     *  members (`containers/trait.ts`). */
+    container?: DiagramContainer;
     /** How far past its bounds something drawn with it reaches, on each side —
      *  a built body's port labels. Layout keeps neighbors that far off too. */
     margin?: GroupInset;
+    /** The theme role it is drawn in. Unset, the theme's default role. */
+    style?: string;
+    /** The colors the author set by hand, which a theme leaves as they are. */
+    ownStyle?: readonly StyleField[];
+    /** The parts of its text face the author set by hand, which a theme leaves as they are. */
+    ownFont?: readonly FontField[];
+    /** On a built body whose rows are all text: how it stacks them, so it can be laid out again when
+     *  their text changes size. Each row's text node carries its place as `bodyRow`. */
+    body?: BodyLayout;
+}
+/** How a built body stacks its text rows: the `BodySpec` fields its layout reads, and how many rows. */
+interface BodyLayout {
+    padding: number;
+    gap: number;
+    verticalAlign: 'top' | 'center' | 'bottom';
+    rows: number;
 }
 /** The group half of a {@link DiagramNode}. */
 interface DiagramGroup {
@@ -131,6 +241,8 @@ interface DiagramGroup {
     /** The narrowest the box may be, in world units, as room for its label.
      *  A box its members leave narrower grows evenly on both sides. */
     minWidth?: number;
+    /** The axis its members can be dragged along to change their order. */
+    reorder?: 'x' | 'y';
 }
 /** A port resolved against a node's current pose: where it is in world
  *  coordinates, and which way an edge leaves it. */
@@ -190,7 +302,7 @@ interface DiagramNodeEntry {
  *  the two apart. Without that test an edge reads as a participant declaring
  *  no ports, and collects the four defaults on the degenerate pose an edge
  *  carries. An edge label's `label` trait and an anchored node's `anchor` are
- *  excluded the same way. */
+ *  excluded the same way, and so is a pool's lane, which takes no connectors. */
 declare const dataKeyReader: DiagramNodeReader;
 /**
  * A reader over declared kinds. A trait on the node's own data still wins, so
@@ -257,6 +369,9 @@ interface GraphGroup {
     minWidth?: number;
     /** The group this one is directly inside. */
     parent?: string;
+    /** Its direct members, nodes and groups, in the order a layered layout
+     *  keeps them across every rank: set for a group that reorders. */
+    ordered?: readonly string[];
 }
 /** One connection. `id` is the edge node's own id, so a caller can go back to
  *  the scene for its trait. */
@@ -520,7 +635,7 @@ declare const DEFAULT_GROUP_INSET = 12;
  * across it. A group's inset there includes that of any group nested in it
  * that ends, or starts, at the same rank. `rows` is the nodes of each rank.
  */
-declare function rankGaps(graph: Graph, rows: readonly (readonly GraphNode[])[], axes: LayoutAxes, rankGap: number): number[];
+declare function rankGaps(graph: Pick<Graph, 'groups'>, rows: readonly (readonly Pick<GraphNode, 'id'>[])[], axes: LayoutAxes, rankGap: number): number[];
 /**
  * Cross positions for every node, with each group's members kept in a column
  * of their own, and a nested group in a column inside its parent's.
@@ -783,4 +898,29 @@ declare function buildBody<TData, TLayer extends string, TPose extends Bounds>(s
     specs: BodyNodeSpec<TData, TLayer, TPose>[];
 };
 
-export { buildGraph as $, type GraphNode as A, type BodySpec as B, type GroupInset as C, type DiagramGroup as D, type EdgeLabelRoom as E, type LayoutAxes as F, type Graph as G, PORT_LABEL_GAP as H, type PerimeterPortLabelBox as I, type PortLabelPlacement as J, type PortSite as K, type LayoutPorts as L, type MeasureRowText as M, type RowBox as N, type Outline as O, type PortAnchor as P, type RowNodeData as Q, type RowTextStyle as R, type RowPort as S, type RowPortBox as T, type Slot as U, anchorOffset as V, axesFor as W, bodyOutline as X, bodyTrait as Y, boxForContent as Z, buildBody as _, type Row as a, canvasMeasure as a0, contentBox as a1, createDiagramNodes as a2, dataKeyReader as a3, diagramNodeOf as a4, expandGroupEdges as a5, graphOrder as a6, insetOf as a7, isPinned as a8, layoutBody as a9, layoutRowPorts as aa, marginOf as ab, measureBody as ac, outlinePath as ad, packAcross as ae, packClusters as af, pinnedSet as ag, planOf as ah, plannerPlan as ai, portLabelBox as aj, portLabelsOf as ak, rankGaps as al, seededOrder as am, settle as an, sizeToBody as ao, translated as ap, untilSettled as aq, extent as ar, type PortSpec as b, type LayoutFn as c, type LayoutOptions as d, type DiagramNode as e, type Port as f, type DiagramNodeLike as g, type DiagramNodeReader as h, type LayoutResult as i, type GraphSource as j, type LayoutPlanner as k, type LayoutDirection as l, type LayoutPlan as m, type GraphNodeLike as n, type BodyFloor as o, type BodyNodeSpec as p, type Bounds as q, type BuildBodyOptions as r, type BuildGraphOptions as s, DEFAULT_GROUP_INSET as t, DEFAULT_NODE_GAP as u, DEFAULT_RANK_GAP as v, DIAGRAM_TRAIT_KEY as w, type DiagramNodeEntry as x, type GraphEdge as y, type GraphGroup as z };
+/**
+ * Line jumps as data: the document value that turns them on, and the hops a
+ * connector carries. Plain data, so layout and any reader can use it.
+ */
+
+/** The document value (`scene.doc`) holding the line-jump setting: present
+ *  while hops are on, absent while off. */
+declare const HOPS_DOC_KEY = "diagram:hops";
+/** The line-jump setting while it is on. */
+interface HopsDocValue {
+    /** A hop's radius, in world units. */
+    size: number;
+}
+/** The radius a hop takes when nothing sets one. */
+declare const DEFAULT_HOP_SIZE = 5;
+/** Where a connector bows over others: a half circle of radius `r` centered
+ *  on `at`, which lies on the connector's route. `over` names the connectors
+ *  it passes over; hops closer than `2r` merge into one, which passes over all
+ *  of theirs. */
+interface EdgeHop {
+    at: Vec2;
+    over: readonly string[];
+    r: number;
+}
+
+export { type PortSite as $, DEFAULT_RANK_GAP as A, type BodySpec as B, type ContainerRole as C, type DiagramGroup as D, type EdgeHop as E, type FontField as F, type Graph as G, DIAGRAM_TRAIT_KEY as H, type DiagramNodeEntry as I, type EdgeLabelRoom as J, type GraphEdge as K, type LayoutPorts as L, type MeasureRowText as M, type GraphGroup as N, type Outline as O, type PortAnchor as P, type GraphNode as Q, type RowTextStyle as R, type StyleField as S, type GroupInset as T, HOPS_DOC_KEY as U, type HopsDocValue as V, LABEL_PLACEMENT as W, type LayoutAxes as X, PORT_LABEL_GAP as Y, type PerimeterPortLabelBox as Z, type PortLabelPlacement as _, type Row as a, type RowBox as a0, type RowNodeData as a1, type RowPort as a2, type RowPortBox as a3, type Slot as a4, anchorOffset as a5, axesFor as a6, bodyBox as a7, bodyOutline as a8, bodyTrait as a9, portLabelsOf as aA, rankGaps as aB, seededOrder as aC, settle as aD, sizeToBody as aE, titleIdOf as aF, translated as aG, untilSettled as aH, extent as aI, boxForContent as aa, buildBody as ab, buildGraph as ac, canvasMeasure as ad, contentBox as ae, createDiagramNodes as af, dataKeyReader as ag, diagramContainerOf as ah, diagramLabelOf as ai, diagramNodeOf as aj, expandGroupEdges as ak, graphOrder as al, headerBox as am, insetOf as an, isPinned as ao, layoutBody as ap, layoutRowPorts as aq, marginOf as ar, measureBody as as, outlinePath as at, packAcross as au, packClusters as av, pinnedSet as aw, planOf as ax, plannerPlan as ay, portLabelBox as az, type PortSpec as b, type DiagramLabel as c, type LayoutFn as d, type LayoutOptions as e, type DiagramNode as f, type Port as g, type DiagramNodeLike as h, type DiagramNodeReader as i, type DiagramContainer as j, type ContainerHeader as k, type LabelSpot as l, type Bounds as m, type LayoutResult as n, type GraphSource as o, type LayoutPlanner as p, type LayoutDirection as q, type LayoutPlan as r, type GraphNodeLike as s, type BodyFloor as t, type BodyNodeSpec as u, type BuildBodyOptions as v, type BuildGraphOptions as w, DEFAULT_GROUP_INSET as x, DEFAULT_HOP_SIZE as y, DEFAULT_NODE_GAP as z };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@weasel-js/diagram",
-  "version": "1.11.0",
+  "version": "1.11.1",
   "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",
@@ -21,15 +21,36 @@
       "import": "./dist/effect.js",
       "types": "./dist/effect.d.ts"
     },
+    "./effect-audio": {
+      "import": "./dist/effect-audio.js",
+      "types": "./dist/effect-audio.d.ts"
+    },
+    "./icons": {
+      "import": "./dist/icons.table.js",
+      "types": "./dist/icons.table.d.ts"
+    },
     "./package.json": "./package.json"
   },
   "peerDependencies": {
     "react": ">=18",
-    "@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"
+    "@weasel-js/animator": "1.11.1",
+    "@weasel-js/audio": "1.11.1",
+    "@weasel-js/core": "1.11.1",
+    "@weasel-js/font": "1.11.1",
+    "@weasel-js/geom": "1.11.1",
+    "@weasel-js/react": "1.11.1",
+    "@weasel-js/simulation": "1.11.1"
+  },
+  "peerDependenciesMeta": {
+    "@weasel-js/audio": {
+      "optional": true
+    }
+  },
+  "weaselIcons": {
+    "table": "./dist/icons.table.json"
+  },
+  "dependencies": {
+    "@weasel-js/icons": "1.11.1"
   },
   "author": "orochi235",
   "homepage": "https://orochi235.github.io/weasel/",
@@ -50,7 +71,7 @@
     "LICENSE"
   ],
   "scripts": {
-    "build": "tsup"
+    "build": "tsup && cp src/icons.table.json dist/"
   },
   "publishConfig": {
     "access": "public",