@weasel-js/diagram 1.10.1 → 1.11.0

package/dist/effect.d.ts

@@ -0,0 +1,417 @@
+import { D as DiagramData, a as DiagramSceneOptions, N as NodeStyle, b as DataEdge, E as EdgeStyle, c as DataNode, d as DiagramRouter, e as DiagramSpec } from './fromData-GKqRgPFs.js';
+import { a as Row, M as MeasureRowText } from './body-2lC7IiIA.js';
+import * as react from 'react';
+import { Paint } from '@weasel-js/core';
+import '@weasel-js/core/math';
+import '@weasel-js/geom';
+
+/** 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;
+    inputs?: readonly EffectPort[];
+    outputs?: readonly EffectPort[];
+    /** Settings worth showing, in order. */
+    params?: readonly {
+        label: string;
+        value: string;
+    }[];
+    /** 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 {
+    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>>;
+}
+/** 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. */
+    values?: Readonly<Record<string, string>>;
+    /** What each output 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>>;
+}
+/** 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;
+}
+
+/** One thing wrong with a pipeline, and where. */
+interface EffectProblem {
+    kind: 'missing-stage' | 'missing-port' | 'wrong-direction' | 'type-mismatch' | 'duplicate-stage' | 'duplicate-port' | 'duplicate-group' | 'missing-member' | 'bad-split';
+    message: string;
+    stage?: string;
+    port?: string;
+    /** Index into `pipeline.wires`. */
+    wire?: number;
+    group?: string;
+}
+/** Everything wrong with `pipeline`. Never throws. */
+declare function checkPipeline(pipeline: EffectPipeline): EffectProblem[];
+
+/** What every look shares: how a type is colored, how a stage and a wire are
+ *  styled, and the lookups a look does over a pipeline. */
+
+/** The color of a value type, for a port or a wire. Answers `undefined`, a
+ *  port with no type, with a neutral color. */
+type TypeColor = (type: string | undefined) => string;
+/** What a look hands back: `diagramScene`'s two arguments, and its colors. */
+interface EffectLookResult {
+    data: DiagramData;
+    scene: DiagramSceneOptions;
+    color: TypeColor;
+    /** Edges standing in for a decision's exits where the look draws no
+     *  decision, keyed by edge id: which stage chose, and by which output. A
+     *  run reads that stage's `taken` for them. */
+    exits?: ReadonlyMap<string, {
+        stage: string;
+        port: string;
+    }>;
+}
+/** One way of drawing a pipeline. Unparameterized, a look whose options are
+ *  not known: any look fits it, and it is called with none. */
+type EffectLook<TOptions = never> = (pipeline: EffectPipeline, options?: TOptions) => EffectLookResult;
+/** The color `wireStyle` draws a wire in when `checkPipeline` reported it. */
+declare const PROBLEM_COLOR = "#ff5d5d";
+/** A color per type: the one given, or the next in the palette in the order
+ *  types first appear on the pipeline's ports. */
+declare function typeColors(pipeline: EffectPipeline, given?: Readonly<Record<string, string>>): TypeColor;
+/** Whether `type` is one the pipeline's `types` mark as `control`. */
+declare function isControl(pipeline: EffectPipeline, type: string | undefined): boolean;
+/** The node style the shipped looks give a stage: dashed and dim when it is bypassed. */
+declare function stageStyle(stage: EffectStage): NodeStyle;
+/** The edge style the shipped looks give a wire: `color`, dashed for a
+ *  control wire, and `PROBLEM_COLOR` in place of `color` for a flagged one. */
+declare function wireStyle(color: string, control: boolean, problem: boolean): EdgeStyle;
+/** Stages with the repeats dropped, first one kept. `diagramScene` throws on
+ *  a repeated id, so a look builds its nodes from these. */
+declare function uniqueStages(pipeline: EffectPipeline): EffectStage[];
+/** Groups with the repeats dropped, first one kept, and none that has the id
+ *  of a stage: `diagramScene` throws on an id that names two things. */
+declare function uniqueGroups(pipeline: EffectPipeline): EffectGroup[];
+/** The port called `id` among a stage's inputs and outputs, inputs first. */
+declare function portOn(stage: EffectStage | undefined, id: string): EffectPort | undefined;
+/** A stage's `kind` as the shipped looks read it: any value they do not know is `'stage'`. */
+declare function kindOf(stage: EffectStage): 'stage' | 'decision' | 'source' | 'sink';
+/** A wire with both ends present, and what a look needs to draw it. */
+interface DrawableWire {
+    wire: EffectWire;
+    /** Index into `pipeline.wires`. */
+    index: number;
+    /** The value type of the port the wire leaves. */
+    type: string | undefined;
+    /** `checkPipeline` reported it. */
+    problem: boolean;
+    fromStage: EffectStage;
+    toStage: EffectStage;
+}
+/** The wires a look can draw: each one whose two stages and two ports exist,
+ *  in the pipeline's order. A wire `checkPipeline` reported and that still has
+ *  both ends is kept, with `problem` set. */
+declare function drawableWires(pipeline: EffectPipeline): DrawableWire[];
+/** What a value row shows before a run fills it in. */
+declare const NO_VALUE = "\u2013";
+/** The row id of the value row for an output, under its stage's body. */
+declare const valueRowId: (port: string) => string;
+/** The row id of the preview slot for an output, under its stage's body. */
+declare const previewRowId: (port: string) => string;
+/** `RunRowOptions.previewSize`'s default: a 48-unit square. */
+declare const PREVIEW_SIZE = 48;
+/** The rows a look keeps on each stage for what an `EffectRun` shows there.
+ *  Kept from the start, so a run fills them in without the chart laying out
+ *  again. A decision's symbol keeps neither. */
+interface RunRowOptions {
+    /** A row per output for its value. Default false. */
+    showValues?: boolean;
+    /** A slot per output for its preview, after its value row. Default false. */
+    showPreviews?: boolean;
+    /** The preview slot's size: a square's side, or a width and height. A
+     *  preview is stretched to fill it. Default `PREVIEW_SIZE`. */
+    previewSize?: number | {
+        width: number;
+        height: number;
+    };
+}
+/** The body rows of an ordinary stage: its title, a row of its ports when
+ *  `withPorts` (inputs left, outputs right), then for each output its value
+ *  row when `showValues` and its preview slot when `showPreviews`, then its
+ *  params when `showParams`. */
+declare function stageRows(stage: EffectStage, opts: {
+    showParams: boolean;
+    withPorts: boolean;
+} & RunRowOptions): Row[];
+/** What a wire is called: its own label, or for a wire leaving a decision the
+ *  exit's label, which defaults to the exit's id. Any other wire has no name. */
+declare function exitLabel(d: DrawableWire): string | undefined;
+/** One edge per drawable wire, from port to port, named by `exitLabel` and
+ *  styled by `wireStyle` in its type's color. */
+declare function wireEdges(pipeline: EffectPipeline, color: TypeColor): {
+    edge: DataEdge;
+    style: EdgeStyle;
+}[];
+
+/** What every branch symbol is built from: its types, where its ports go, and
+ *  the diamond each one falls back to. */
+
+/** What a branch symbol draws: a data node without its id or style, which the look adds. */
+type BranchNode = Pick<DataNode, 'outline' | 'lines' | 'rows' | 'ports' | 'marks' | 'width' | 'height' | 'padding'>;
+/** How a look wants a branch symbol drawn. */
+interface BranchOptions {
+    /** The edge control inputs enter by: the side the stages driving them sit
+     *  on. Default `'top'`. */
+    controlSide?: 'top' | 'bottom';
+    /** The style the look draws the stage's node in: lines, dots and ticks
+     *  take its `text` color. Default `stageStyle(stage)`. */
+    style?: NodeStyle;
+    /** The colors of a `bar`'s bands and a `crossover`'s curves, lowest
+     *  first, repeating. Default a palette of four, or for a bypassed stage
+     *  `style.stroke` for every band. */
+    tints?: readonly string[];
+}
+/** Draws one decision stage, with a port for each of its inputs and outputs. */
+type BranchSymbol = (stage: EffectStage, pipeline: EffectPipeline, options?: BranchOptions) => BranchNode;
+
+/** Which symbol a decision draws as: one by name, or `'auto'` for a bar when
+ *  the stage has a sound `split` and a diamond otherwise. */
+type BranchChoice = 'auto' | 'diamond' | 'bar' | 'demux' | 'switch' | 'hexagon' | 'step' | 'comparator' | 'crossover' | 'fork';
+/** Each branch symbol by name. One called on a stage it cannot draw draws
+ *  the `diamond` instead: a `bar`, `step` or `crossover` with no sound split,
+ *  or a `switch` or `comparator` without exactly two exits. */
+declare const BRANCH_SYMBOLS: Readonly<Record<Exclude<BranchChoice, 'auto'>, BranchSymbol>>;
+/** The symbol `choice` comes to for `stage`: `'auto'` a bar for a sound
+ *  split, and any symbol that cannot draw the stage the diamond. */
+declare function symbolNameFor(stage: EffectStage, choice?: BranchChoice): Exclude<BranchChoice, 'auto'>;
+/** The node a decision stage draws as, by the symbol `choice` comes to. */
+declare function branchNode(stage: EffectStage, pipeline: EffectPipeline, choice?: BranchChoice, options?: BranchOptions): BranchNode;
+
+/** Options for the `compact` look. */
+interface CompactOptions {
+    /** Default `'bezier'`. */
+    router?: DiagramRouter;
+    /** Default 16. */
+    nodeGap?: number;
+    /** Default 48. */
+    rankGap?: number;
+    /** A color per value type, over the palette's own. */
+    colors?: Readonly<Record<string, string>>;
+    /** Default `'hexagon'`, the one symbol that keeps a decision one row tall. */
+    branch?: BranchChoice;
+}
+/** Between a compact stage's outline and its title. */
+declare const COMPACT_PADDING = 4;
+/** The compact look: each stage one line, its title alone, and no ports
+ *  drawn; the wires between two stages one line between them. For a
+ *  pipeline too big to read as a node graph. */
+declare const compact: EffectLook<CompactOptions>;
+
+/** Props for `EffectChart`. */
+interface EffectChartProps<TOptions = never> {
+    /** Compared by its JSON, so it may be rebuilt on every render: the chart
+     *  lays out again only when that changes. A value JSON drops or flattens
+     *  in a stage's `data` (a function, a `Map`) is not seen changing. */
+    pipeline: EffectPipeline;
+    /** One run of the pipeline, drawn over it: stages it never reached and
+     *  branches it did not take faded, each stage's cost above its corner, and
+     *  each output's value and preview in the rows a look keeps for them
+     *  (`showValues`, `showPreviews`). It may change every frame: the chart
+     *  neither lays out again nor refits, and repaints only what changed. A
+     *  preview the next run no longer shows has its texture freed then. */
+    run?: EffectRun;
+    /** How the pipeline is drawn. Default `nodeGraph`. */
+    look?: EffectLook<TOptions>;
+    /** The look's options. Keep the object's identity steady between renders,
+     *  or the chart lays out again on each one. */
+    options?: TOptions;
+    /** CSS pixels. Omit both to fill the parent, which then needs a size of
+     *  its own. The chart refits when its size changes, until the user pans or
+     *  zooms. */
+    width?: number;
+    height?: number;
+    /** The smallest scale the chart opens at. A chart that does not fit whole
+     *  at it opens at it anyway, anchored at its start, and the rest is a pan
+     *  away. Default `EFFECT_MIN_SCALE`. */
+    minScale?: number;
+    /** What the canvas paints behind the chart. Unset, it is transparent; the
+     *  shipped looks are drawn for a dark ground. */
+    background?: Paint;
+    /** A stage id, or null for none. */
+    selected?: string | null;
+    /** Hears each pick: a stage's id, or `null` for anything else. Only a
+     *  stage can be picked: a click on a group box or a lane lands on the
+     *  canvas behind it. The canvas keeps its own highlight on the stage picked;
+     *  only a change to `selected` moves it. */
+    onSelect?: (stage: string | null) => void;
+    /** What `checkPipeline` found. Called once on mount, and again each time
+     *  the pipeline's content changes. */
+    onProblems?: (problems: readonly EffectProblem[]) => void;
+    /** A class for the canvas element. */
+    className?: string;
+}
+/** `EffectChart`'s default `minScale`: the shipped looks' 12px titles at 6px, the smallest still legible. */
+declare const EFFECT_MIN_SCALE = 0.5;
+/** A chart of an effects pipeline: pan, zoom, and pick a stage. Text paints
+ *  only in a registered font family, so call `registerCanvasFont('sans-serif')`
+ *  once before mounting one. */
+declare function EffectChart<TOptions = never>({ pipeline: given, run, look, options, width, height, minScale, background, selected, onSelect, onProblems, className, }: EffectChartProps<TOptions>): react.JSX.Element;
+
+/** Options for the `lanes` look. */
+interface LanesOptions extends RunRowOptions {
+    /** The value types whose lanes come first, top down. The rest follow in
+     *  the order their types first appear on the pipeline's ports. */
+    lanes?: readonly string[];
+    /** The least height of a lane. A lane grows past it until what stands in
+     *  it fits. Default 48. */
+    laneHeight?: number;
+    /** Between one column of stages and the next. Default 40. */
+    rankGap?: number;
+    /** Default `'bezier'`. */
+    router?: DiagramRouter;
+    /** A color per value type, over the palette's own. */
+    colors?: Readonly<Record<string, string>>;
+    /** Whether a stage lists its `params`. Default true. */
+    showParams?: boolean;
+    /** Default `'auto'`. */
+    branch?: BranchChoice;
+    /** Measures text, as `diagramScene` takes it, for sizing stages before
+     *  the lanes are cut to fit them. It is handed on in the look's `scene`. */
+    measure?: MeasureRowText;
+}
+/** How far a stage stands inside the first and last lane it touches, at
+ *  least: more beside a lane edge that wires run along on several tracks. */
+declare const LANE_INSET = 6;
+/** The node id of the lane for a value type. */
+declare const laneId: (type: string) => string;
+/** The lanes look: a horizontal lane per value type, and each stage standing
+ *  across the lanes of the types it reads and writes, as tall as they are,
+ *  its ports in their own lanes. A decision keeps its symbol's size, centered
+ *  across its lanes. Columns run left to right in the order the signal flows.
+ *  A wire runs around the stages between its ends along the lane edges, each
+ *  sharing one on a track of its own. */
+declare const lanes: EffectLook<LanesOptions>;
+
+/** Options for the `rack` look. */
+interface RackOptions extends RunRowOptions {
+    /** The stage ids on the line, in order. Default the longest path over data wires. */
+    chain?: readonly string[];
+    /** Where what feeds the chain from the side sits. Default `'below'`. */
+    side?: 'below' | 'above';
+    nodeGap?: number;
+    rankGap?: number;
+    /** A color per value type, over the palette's own. */
+    colors?: Readonly<Record<string, string>>;
+    /** Whether a stage lists its `params`. Default true. A decision's symbol
+     *  does not show params either way. */
+    showParams?: boolean;
+    /** Default `'auto'`. */
+    branch?: BranchChoice;
+    /** Draw a decision that only skips ahead as an arc over what it skips. Default true. */
+    collapseSkips?: boolean;
+}
+/** The rack look: the main signal on one straight line with its stages in
+ *  order, and whatever feeds a stage from the side hung beside it. */
+declare const rack: EffectLook<RackOptions>;
+
+/** Options for the `nodeGraph` look. */
+interface NodeGraphOptions extends RunRowOptions {
+    /** Default `'bezier'`. */
+    router?: DiagramRouter;
+    nodeGap?: number;
+    rankGap?: number;
+    /** A color per value type, over the palette's own. */
+    colors?: Readonly<Record<string, string>>;
+    /** Whether a stage lists its `params`. Default true. A decision's symbol
+     *  does not show params either way. */
+    showParams?: boolean;
+    /** Default `'auto'`. */
+    branch?: BranchChoice;
+}
+/** The node-graph look: every port a named row on its stage, a wire from port
+ *  to port in the color of what it carries, flowing left to right. */
+declare const nodeGraph: EffectLook<NodeGraphOptions>;
+
+/** The looks that ship, by name. */
+declare const EFFECT_LOOKS: Readonly<{
+    nodeGraph: EffectLook<NodeGraphOptions>;
+    rack: EffectLook<RackOptions>;
+    lanes: EffectLook<LanesOptions>;
+    compact: EffectLook<CompactOptions>;
+}>;
+
+/** Which stages a pipeline's main signal runs through, and which decisions on
+ *  that run only choose between going on and skipping ahead. */
+
+/** Stage ids of the longest path over data wires, sources first. */
+declare function mainChain(pipeline: EffectPipeline): string[];
+
+/**
+ * `specs` as `run` leaves them: a stage the run never reached faded, with its
+ * wires; a decision's wires to the outputs it did not take faded; each value
+ * row a look kept filled in; a `switch` thrown to the output its decision
+ * took; and each stage's cost written above its corner.
+ * No run, no change.
+ */
+declare function paintRun(pipeline: EffectPipeline, specs: readonly DiagramSpec[], run: EffectRun | undefined, exits?: EffectLookResult['exits']): DiagramSpec[];
+/** A cost in milliseconds, to three figures. */
+declare function costText(ms: number): string;
+
+export { BRANCH_SYMBOLS, type BranchChoice, type BranchNode, type BranchOptions, type BranchSymbol, COMPACT_PADDING, type CompactOptions, type DrawableWire, EFFECT_LOOKS, EFFECT_MIN_SCALE, EffectChart, type EffectChartProps, type EffectGroup, type EffectLook, type EffectLookResult, type EffectPipeline, type EffectPort, type EffectProblem, type EffectRun, type EffectStage, type EffectStageRun, type EffectType, type EffectWire, LANE_INSET, type LanesOptions, NO_VALUE, type NodeGraphOptions, PREVIEW_SIZE, PROBLEM_COLOR, type RackOptions, type RunRowOptions, type TypeColor, branchNode, checkPipeline, compact, costText, drawableWires, exitLabel, isControl, kindOf, laneId, lanes, mainChain, nodeGraph, paintRun, portOn, previewRowId, rack, stageRows, stageStyle, symbolNameFor, typeColors, uniqueGroups, uniqueStages, valueRowId, wireEdges, wireStyle };