@phin-tech/dottie 0.7.0 → 0.8.0

package/dist/types/clicks.d.ts

@@ -13,6 +13,7 @@ export type Click = ({
 }) & {
     set?: Record<string, boolean>;
     toggle?: string[];
+    reset?: true;
 };
 /** The marker called `name`: an exact match, else one that differs only in case. */
 export declare function sceneNamed(name: string, markers: Marker[]): number;

package/dist/types/flows.d.ts

@@ -0,0 +1,26 @@
+import type { Page, RGBA } from "./model.ts";
+export declare const DEFAULT_EVERY = 0.5, DEFAULT_SPEED = 160, DEFAULT_SIZE = 12;
+export declare const DEFAULT_COLOR: RGBA;
+export declare const clamp: (v: number | null, fallback: number, lo: number, hi: number) => number;
+/** The id of a flow's packet `k`: the flow's id with its last twelve digits standing for `k` (Flow.packetID). */
+export declare function packetID(flow: string, k: number): string;
+/** Every shape traffic from `from` can reach in `frame`, with the cheapest way to each (DottieDocument.flowTree):
+ * by the connectors' cost (1 each unless set), ties to the shape reached first, earlier connectors first. */
+export declare function flowTree(from: string, frame: Page, offline?: Set<string>): FlowTree | null;
+export declare class FlowTree {
+    settled: Set<string>;
+    came: Map<string, {
+        from: string;
+        via: string;
+        back: boolean;
+    }>;
+    readonly from: string;
+    constructor(from: string);
+    /** The first of `to` that can be reached; with `spread`, when the first can't be, every other one that can. */
+    goals(to: string[], spread: boolean): string[];
+    /** The connectors to `goal`, as [connector, backwards] hops. */
+    hops(goal: string): [string, boolean][];
+}
+/** The connectors traffic takes from `from` to the first of `to` it reaches in `frame`, as [connector, backwards]
+ * hops; null when none can be reached. */
+export declare function flowRoute(from: string, to: string[], frame: Page, offline?: Set<string>): [string, boolean][] | null;

package/dist/types/index.d.ts

@@ -20,4 +20,4 @@ export interface RenderOptions {
 /** One page of a drawing as an SVG document, as Dottie's own SVG export draws it. */
 export declare function render(source: string | DottieFile | unknown, options?: RenderOptions): string;
 /** The library's version. */
-export declare const VERSION = "0.7.0";
+export declare const VERSION = "0.8.0";

package/dist/types/measure.d.ts

@@ -0,0 +1,58 @@
+import type { Element, Flow, Gauge, Page, RGBA } from "./model.ts";
+import { type MetricTerm } from "./state.ts";
+/** A connector's or shape's metrics in one frame (ElementMetrics). */
+export interface ElementMetrics {
+    throughput: number;
+    load: number | null;
+    delay: number;
+    backlog: number;
+    inFlight: number;
+    depth: number;
+}
+/** A flow's metrics in one frame (FlowMetrics). */
+export interface FlowMetrics {
+    volume: number;
+    placed: number;
+    backlog: number;
+    backup: number;
+    transit: number | null;
+}
+/** Every metric of one frame (FrameMetrics). */
+export interface FrameMetrics {
+    elements: Map<string, ElementMetrics>;
+    flows: Map<string, FlowMetrics>;
+    carry: Record<string, number>;
+}
+export declare const emptyMetrics: () => FrameMetrics;
+/** `metric` of the element or flow `id`, or null when it has none. */
+export declare function metricValue(m: FrameMetrics, metric: string, id: string): number | null;
+/** A shape's delay as traffic feels it: 0...3600 seconds. */
+export declare function delayOf(e: Element): number;
+/** The key of a flow's queue at a shape in `FrameMetrics.carry` and `carried` (DottieDocument.queueKey). */
+export declare const queueKey: (shape: string, flow: string) => string;
+/** The packets the page's flows draw in `frame` (the page posed at `t`), with these values (null: every flow runs),
+ * and the frame's metrics (DottieDocument.flowFrame). `since` is the seconds since the page's state last changed
+ * (null: `t`), and `carried` how much each flow's queue held at that moment: since then a queue grows by its
+ * backlog, or drains at the room its way on has left. */
+export declare function flowFrame(flows: Flow[] | null, frame: Page, t: number, values: Record<string, boolean> | null, offline?: Set<string>, sinceChange?: number | null, carried?: Record<string, number>): {
+    packets: Element[];
+    metrics: FrameMetrics;
+};
+/** The frame's metric for a condition's comparison: its target an element's anchor, or an element's or flow's id. */
+export declare function metricLookup(m: FrameMetrics, frame: Page): (t: MetricTerm, own: string | null) => number | null;
+/** `elements` with the looks of overrides that compare metrics applied, and gauges drawn as plain elements; with
+ * no values ("all", the editor), both are left as they are (DottieDocument.finishing). */
+export declare function finishing(elements: Element[], metrics: FrameMetrics, values: Record<string, boolean> | null, frame: Page, flows: Flow[], since?: number, carried?: Record<string, number>): {
+    elements: Element[];
+    readings: Record<string, number>;
+};
+/** The key of a gauge's reading in `FrameMetrics.carry` and `carried` (DottieDocument.gaugeKey). */
+export declare const gaugeKey: (id: string) => string;
+export declare const GAUGE_GREEN: RGBA, GAUGE_AMBER: RGBA, GAUGE_RED: RGBA;
+export declare const GAUGE_BLUE: RGBA, GAUGE_TRACK: RGBA, GAUGE_GRAY: RGBA;
+/** A metric's value as a gauge shows it: a percentage for load and backup, seconds for transit and delay. */
+export declare function formatted(metric: string, v: number | null): string;
+/** `v` to `places` decimals, halves away from zero, trailing zeros dropped (DottieDocument.number). */
+export declare function formatNumber(v: number, places: number): string;
+/** A gauge drawn: its frame as a `.path` carrying the label, then the bar or dial (DottieDocument.gauge). */
+export declare function gauge(e: Element, g: Gauge, value: number | null, frame: Page, flows: Flow[]): Element[];

package/dist/types/model.d.ts

@@ -55,6 +55,8 @@ export interface ConnectorData {
     waypoints: StrokePoint[] | null;
     /** Hops where the line crosses a connector drawn beneath it. */
     hops: boolean | null;
+    /** What a flow's traffic pays to take this connector (ADR 0002); null is 1. */
+    cost: number | null;
 }
 export interface PathSubpath {
     closed: boolean;
@@ -75,8 +77,31 @@ export interface ClickAction {
     url: string | null;
     set: Record<string, boolean> | null;
     toggle: string[] | null;
+    /** Puts every page variable back to its starting value first. */
+    reset?: boolean | null;
 }
 /** How a clickable element looks under the pointer or with keyboard focus; null keeps its own. */
+/** A change to an element while `when` holds (StateOverride): a field left null keeps the element's own. */
+export interface StateOverride {
+    when: string;
+    stroke: RGBA | null;
+    fill: RGBA | null;
+    textColor: RGBA | null;
+    /** Multiplies the element's opacity. */
+    opacity: number | null;
+    strokeWidth: number | null;
+    dash: DashStyle | null;
+    text: string | null;
+    /** Connector ids (uppercase) to the connectors a following element takes instead. */
+    reroute: Record<string, string> | null;
+    /** Still drawn, but carries no flow traffic. */
+    offline: boolean | null;
+    /** A connector's cost for flow traffic meanwhile. */
+    cost: number | null;
+    /** Its capacity and delay meanwhile (ADR 0003). */
+    capacity: number | null;
+    delay: number | null;
+}
 export interface HoverLook {
     stroke: RGBA | null;
     fill: RGBA | null;
@@ -110,6 +135,8 @@ export interface Element {
     hover: HoverLook | null;
     /** A condition on the page's variables: drawn only while it holds (Element.when; see state.ts). */
     when: string | null;
+    /** Changes to the element while a condition holds, in order (Element.overrides; see state.ts). */
+    overrides: StateOverride[] | null;
     /** For a `symbol` element: the page's symbol it shows, how it plays it, and from how far in. */
     symbol: string | null;
     playback: SymbolPlayback | null;
@@ -131,6 +158,23 @@ export interface Element {
         height: number;
     } | null;
     extension?: ExtensionRef | null;
+    /** The most flow volume it carries, and a shape's delay in seconds (ADR 0003). */
+    capacity?: number | null;
+    delay?: number | null;
+    /** A shape that is a queue: backlog waits at the nearest one before whatever is full. */
+    queue?: boolean | null;
+    /** Shows a metric; drawn as plain paths and a label when the page is posed (metrics.ts). */
+    gauge?: Gauge | null;
+}
+/** A metric shown in an element's frame (Gauge, ADR 0003). */
+export interface Gauge {
+    metric: string;
+    of: string;
+    max: number | null;
+    warn: number | null;
+    alarm: number | null;
+    style: "number" | "bar" | "dial" | null;
+    label: string | null;
 }
 export interface Layer {
     id: string;
@@ -210,6 +254,28 @@ export interface Page {
     symbols: Symbol[] | null;
     /** The page's variables and their starting values (DottieDocument.variables). */
     variables: Record<string, boolean> | null;
+    /** Traffic routed over the connectors drawn in each frame (DottieDocument.flows; see flows.ts). */
+    flows: Flow[] | null;
+}
+/** Traffic from one shape to the first of `to` it can reach (Flow, ADR 0002). Numbers left null take defaults. */
+export interface Flow {
+    id: string;
+    from: string;
+    to: string[];
+    every: number | null;
+    speed: number | null;
+    color: RGBA | null;
+    size: number | null;
+    when: string | null;
+    /** When the first destination can't be reached, deal packets across every other one that can. */
+    spread: boolean | null;
+    /** How much it carries (ADR 0003); null is 1. */
+    volume: number | null;
+    /** Its volume while a condition holds, the last that holds winning. */
+    overrides?: {
+        when: string;
+        volume: number | null;
+    }[] | null;
 }
 /** A drawing defined once on a page and placed by `symbol` elements, with its own timeline (Symbol). */
 export interface Symbol {

package/dist/types/player.d.ts

@@ -14,6 +14,14 @@ export declare class Playback {
     readonly sceneLoops: boolean[];
     /** The page's variables now: their starting values until clicks change them. */
     state: Record<string, boolean>;
+    /** When the variables last changed (performance.now() milliseconds): backlog piles up from then (ADR 0003). */
+    stateSince: number;
+    /** A still (the `at` attribute): backlog is drawn for the page time, not the wall clock. */
+    still: boolean;
+    /** What each queue held when the variables last changed, which it drains from (FrameMetrics.carry). */
+    carried: Record<string, number>;
+    /** Seconds since the variables last changed, or null for a still. */
+    sinceChange(now?: number): number | null;
     readonly background: RGBA;
     readonly ink: RGBA;
     /** What clicking each clickable element does, by element id. */
@@ -31,7 +39,10 @@ export declare class Playback {
     private overTimes;
     private downTimes;
     private hitTimes;
-    private last;
+    last: {
+        t: number;
+        i: number;
+    };
     private svg;
     private groups;
     private order;

package/dist/types/state.d.ts

@@ -1,12 +1,25 @@
-import type { ClickAction, Page } from "./model.ts";
+import { type ClickAction, type Element, type Page, type StateOverride } from "./model.ts";
 /** Whether `name` can name a variable: a letter or underscore, then letters, digits and underscores. */
 export declare function isName(name: string): boolean;
-/** The variable names `condition` reads, or null when it isn't one: names, each optionally after `!`, joined by
- * `&&` and `||` (`&&` binds tighter). */
+/** The metrics a condition can compare (ADR 0003), as `load(workers) > 0.9`. */
+export declare const METRIC_NAMES: string[];
+/** A comparison of a metric in a condition (PageState.MetricTerm). */
+export interface MetricTerm {
+    metric: string;
+    target: string;
+    op: string;
+    value: number;
+}
+/** `term` (trimmed) read as a metric comparison, or null. */
+export declare function metricTerm(term: string): MetricTerm | null;
+/** Whether `condition` compares a metric anywhere. */
+export declare function mentionsMetric(condition: string): boolean;
+/** The variable names `condition` reads, or null when it isn't one: names, each optionally after `!`, or metric
+ * comparisons, joined by `&&` and `||` (`&&` binds tighter). */
 export declare function conditionNames(condition: string): string[] | null;
-/** Whether `condition` holds with these values. A missing variable is false; a condition that can't be read never
- * holds. */
-export declare function holds(condition: string, state: Record<string, boolean>): boolean;
+/** Whether `condition` holds with these values, and `metric` giving the frame's metrics. A missing variable is
+ * false, and so is a comparison whose metric can't be had; a condition that can't be read never holds. */
+export declare function holds(condition: string, state: Record<string, boolean>, metric?: ((m: MetricTerm) => number | null) | null): boolean;
 /** Which elements a page shows as far as its variables go: their starting values ("initial"), these values (a
  * missing one takes its starting value), or every element ("all"). */
 export type StateChoice = "initial" | "all" | Record<string, boolean>;
@@ -14,7 +27,14 @@ export type StateChoice = "initial" | "all" | Record<string, boolean>;
 export declare function stateValues(page: Page, choice: StateChoice): Record<string, boolean> | null;
 /** The ids of the elements whose `when` doesn't hold under `choice`. */
 export declare function stateHidden(page: Page, choice: StateChoice): Set<string>;
+/** The overrides of `e` that hold under `values`, in order; none for null ("all", the editor). */
+export declare function activeOverrides(e: Element, values: Record<string, boolean> | null): StateOverride[];
+/** Only what an override comparing metrics may change: its looks (ADR 0003). */
+export declare function looksOnly(o: StateOverride): StateOverride;
+/** `e` with `o` applied (StateOverride.apply): opacity multiplies, the rest replaces. */
+export declare function applyOverride(o: StateOverride, e: Element): Element;
 /** Whether a click sets or flips a variable. */
 export declare function changesState(c: ClickAction | null): boolean;
-/** `state` after the click: its `set` values, then each `toggle` flipped (a missing variable starts false). */
-export declare function applyClick(c: ClickAction, state: Record<string, boolean>): Record<string, boolean>;
+/** `state` after the click: the starting values (`initial`) back if it resets, then its `set` values, then each
+ * `toggle` flipped (a missing variable starts false). */
+export declare function applyClick(c: ClickAction, state: Record<string, boolean>, initial?: Record<string, boolean>): Record<string, boolean>;

package/dist/types/timeline.d.ts

@@ -1,6 +1,7 @@
 import { type Ease, type Element, type Follow, type Page, type Timeline, type Track } from "./model.ts";
 import { Polyline, type Point, type Rect } from "./path.ts";
 import { type StateChoice } from "./state.ts";
+import { type FrameMetrics } from "./measure.ts";
 export declare function applyEase(ease: Ease, u: number): number;
 /** The time inside the track's own keys that `t` plays (repeats folded back). */
 export declare function localTime(track: Track, t: number): number;
@@ -21,10 +22,17 @@ export declare function following(track: Track, e: Element, t: number, page: Pag
 export declare function marchOffset(tl: Timeline, speed: number, period: number, t: number): number;
 /** The page as a still drawing at `t` seconds, symbol instances expanded (DottieDocument.resolved(at:)). A page with
  * no timeline and no instances is returned as is. */
-export declare function resolved(page: Page, t: number, state?: StateChoice): Page;
+export declare function resolved(page: Page, t: number, state?: StateChoice, since?: number | null, carried?: Record<string, number>): Page;
 /** The page posed at `t` seconds, instances kept, and the elements whose `when` doesn't hold under `state` left out
  * with their connectors (DottieDocument.posed(at:state:)). */
-export declare function posed(page: Page, t: number, state?: StateChoice): Page;
+export declare function posed(page: Page, t: number, state?: StateChoice, since?: number | null, carried?: Record<string, number>): Page;
+/** `posed`, and the frame's metrics (ADR 0003). `since` is the seconds since the page's state last changed, which
+ * backlog has been piling up for: the player passes the time since the last click; null is `t`, as exports draw it.
+ * `carried` is what each queue held when the state last changed (`FrameMetrics.carry` then), which it drains from. */
+export declare function posedWithMetrics(page: Page, t: number, state?: StateChoice, since?: number | null, carried?: Record<string, number>): {
+    frame: Page;
+    metrics: FrameMetrics;
+};
 /** The moment a still picture of the page shows: its poster, else the end. */
 export declare function posterTime(page: Page): number;
 /** The page as a still picture (its poster frame when animated). */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@phin-tech/dottie",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "description": "Render, play and compile Dottie (.dottie) drawings and animations in the browser",
   "type": "module",
   "license": "Apache-2.0",