@phin-tech/dottie 0.8.0 → 0.10.0

package/dist/types/compile.d.ts

@@ -1,5 +1,5 @@
 import type { Face } from "./metrics.ts";
-/** What follows the runtime; DOTTIE_DATA and DOTTIE_OPTIONS are replaced with JSON. Plain ES5, unminified. */
+/** What follows the runtime; DOTTIE_DATA, DOTTIE_OPTIONS and DOTTIE_FONTS are replaced with JSON. Plain ES5, unminified. */
 export declare const LOADER = ";(function () {\n  var data = DOTTIE_DATA, options = DOTTIE_OPTIONS, fonts = DOTTIE_FONTS;\n  var script = document.currentScript;\n  if (window.Dottie.addFonts) window.Dottie.addFonts(Object.keys(fonts), fonts);\n  function attr(el, name, value) { el.setAttribute(name.replace(/[A-Z]/g, function (c) { return \"-\" + c.toLowerCase(); }), value); }\n  function mount() {\n    var player = document.createElement(\"dottie-player\"), k;\n    for (k in options) attr(player, k, options[k]);\n    if (script) for (k in script.dataset) if (k !== \"target\") attr(player, k, script.dataset[k]);\n    var target = script && script.dataset.target ? document.querySelector(script.dataset.target) : null;\n    if (target) target.appendChild(player);\n    else if (script && script.parentNode && script.parentNode !== document.head) script.parentNode.insertBefore(player, script);\n    else document.body.appendChild(player);\n    player.setFile(window.Dottie.parseDottie(data));\n  }\n  if (document.readyState === \"loading\" && (!script || script.parentNode === document.head || script.dataset.target)) {\n    document.addEventListener(\"DOMContentLoaded\", mount);\n  } else {\n    mount();\n  }\n})();\n";
 export interface CompileOptions {
     /** Page name or 1-based number; only that page goes in. The first page by default. */

package/dist/types/connector.d.ts

@@ -24,5 +24,9 @@ export declare function arrowhead(tip: Point, from: Point, size: number): [Point
 export declare function connectorBounds(e: Element, index: Index): Rect;
 /** Point halfway along the route, where a label sits. */
 export declare function midpoint(e: Element, index: Index): Point;
+/** Each element by id, the first with an id winning. Kept per elements array, so every follow, trace and render of
+ * one frame shares it; checked against the array's members each time, so a page changed in place is indexed anew. */
+/** Whether `index` is the one `indexOf` last built for this page's elements (without checking them again). */
+export declare function isIndexOf(page: Page, index: Index): boolean;
 export declare function indexOf(page: Page): Index;
 export { angle };

package/dist/types/elbow.d.ts

@@ -0,0 +1,18 @@
+import type { Element } from "./model.ts";
+import type { Point, Rect } from "./path.ts";
+/** How far a route keeps from the shapes it goes round. */
+export declare const MARGIN = 16;
+/** What a bend costs, in points of length. */
+export declare const BEND = 24;
+/** Shapes smaller than this either way (packets, dots, small icons) aren't in the way. */
+export declare const SMALLEST = 24;
+/** More shapes in the way than this, and the plain route is kept. */
+export declare const MOST = 48;
+/** The box of `e` if a route goes round it: not a connector, text, freehand line or plain path, not invisible, and
+ * not small. */
+export declare function obstacle(e: Element): Rect | null;
+/** Whether the right-angled line through `points` passes through the inside of `r` (not just along its edge). */
+export declare function crosses(points: Point[], r: Rect): boolean;
+/** `plain` (the Z or L from `a` to `b`), or a way round the shapes among `elements` it crosses, leaving out `except`
+ * (the connector's own ends). */
+export declare function avoiding(plain: Point[], a: Point, b: Point, startVertical: boolean, endVertical: boolean, elements: Iterable<Element>, except: Set<string>): Point[];

package/dist/types/flows.d.ts

@@ -4,9 +4,13 @@ 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;
+/** `cost` as routing uses it: 1 for null, kept within 0...1,000,000 (ConnectorData.routeCost). */
+export declare const routeCost: (cost: number | null) => number;
+/** Every shape traffic from `from` can reach in `frame`, with the cheapest way to each:
+ * by the connectors' cost (1 each unless set), ties to the shape reached first, earlier connectors first.
+ * With `until`, the search stops once that shape is settled: its way is final then, and it is the first goal of any
+ * list it heads, but the tree holds only the shapes settled before it. */
+export declare function flowTree(from: string, frame: Page, offline?: Set<string>, until?: string): FlowTree | null;
 export declare class FlowTree {
     settled: Set<string>;
     came: Map<string, {

package/dist/types/index.d.ts

@@ -5,7 +5,7 @@ export { BUNDLED_FONTS } from "./text.ts";
 export { inspect, inspectFrame, inspectPage, sampleTimes } from "./inspect.ts";
 export { DottiePlayer, Playback, definePlayer, pageIndex, withRoughness } from "./player.ts";
 export { bounds, plan, svg, svgParts, type Plan, type Part } from "./svg.ts";
-export { themeNamed, themes, type Theme } from "./theme.ts";
+export { pageTheme, paletteColor, themeNamed, themes, type Theme } from "./theme.ts";
 export { cameraView, frameTimes, posterTime, resolved, sceneAt, still, transientElements } from "./timeline.ts";
 export interface RenderOptions {
     /** Page name or 1-based number; the first page by default. */
@@ -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.8.0";
+export declare const VERSION = "0.10.0";

package/dist/types/measure.d.ts

@@ -28,20 +28,46 @@ export declare const emptyMetrics: () => FrameMetrics;
 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;
+/** One way a flow's traffic takes in a frame (`flowFrame`'s routes): to `goal` over the connectors `hops`
+ * ([connector, backwards]), carrying `amount` of its volume at a cost of `cost`; `waits` when it goes only as far as
+ * the queue it waits in. */
+export interface FlowRoute {
+    goal: string;
+    hops: [string, boolean][];
+    amount: number;
+    waits: boolean;
+    cost: 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
+ * and the frame's metrics. `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;
+    routes: Map<string, FlowRoute[]>;
 };
 /** 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;
+/** What finishing does to one element: which of its overrides that compare metrics hold (their looks apply, in
+ * order), and, for a gauge, the reading it shows. */
+export interface Finish {
+    applied: number[];
+    gauge: {
+        value: number | null;
+    } | null;
+}
+/** For each of `elements`, the overrides that compare metrics that hold and the reading a gauge shows (easing, over
+ * `GAUGE_EASE` seconds since the state changed, from its reading then, `carried`); with no values ("all", the
+ * editor), nothing. The readings come back to carry over. */
+export declare function finishPlan(elements: Element[], metrics: FrameMetrics, values: Record<string, boolean> | null, frame: Page, since?: number, carried?: Record<string, number>): {
+    plan: Finish[];
+    readings: Record<string, number>;
+};
 /** `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). */
+ * no values ("all", the editor), both are left as they are (`finishPlan`). */
 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>;
@@ -54,5 +80,5 @@ export declare const GAUGE_BLUE: RGBA, GAUGE_TRACK: RGBA, GAUGE_GRAY: RGBA;
 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). */
+/** A gauge drawn: its frame as a `.path` carrying the label, then the bar or dial. */
 export declare function gauge(e: Element, g: Gauge, value: number | null, frame: Page, flows: Flow[]): Element[];

package/dist/types/model.d.ts

@@ -29,6 +29,27 @@ export interface Style {
     dashOffset: number | null;
     /** The color of a shape's or connector's label; null follows `stroke`. Text boxes and notes ignore it. */
     textColor: RGBA | null;
+    /** Which colors are palette colors, by name (ADR 0005); set from the page's palette when it is read. */
+    named?: ColorNames | null;
+}
+/** Palette names for an element's colors (Theme.swift's ColorNames). */
+export interface ColorNames {
+    fill: string | null;
+    stroke: string | null;
+    textColor: string | null;
+}
+/** A named color in a theme's palette. */
+export interface PaletteColor {
+    name: string;
+    color: RGBA;
+}
+/** A theme made in the drawing (CustomTheme): it takes the place of the page's `theme`. */
+export interface CustomTheme {
+    name: string;
+    background: RGBA;
+    ink: RGBA;
+    palette: PaletteColor[];
+    base: string | null;
 }
 /** `portIndex` pins the end to one of the bound element's `ports`, and wins over `port`. */
 export interface Endpoint {
@@ -55,6 +76,8 @@ export interface ConnectorData {
     waypoints: StrokePoint[] | null;
     /** Hops where the line crosses a connector drawn beneath it. */
     hops: boolean | null;
+    /** An elbow line goes round the shapes in its way instead of through them (elbow.ts). */
+    avoid?: boolean | null;
     /** What a flow's traffic pays to take this connector (ADR 0002); null is 1. */
     cost: number | null;
 }
@@ -163,6 +186,13 @@ export interface Element {
     delay?: number | null;
     /** A shape that is a queue: backlog waits at the nearest one before whatever is full. */
     queue?: boolean | null;
+    /** The container this element is in (ADR 0006). */
+    containerID?: string | null;
+    /** On a rectangle: it's a container. Its title band is its `labelRect`, kept by the app, so drawing needs nothing more. */
+    container?: {
+        fixed: boolean | null;
+        lanes: "rows" | "columns" | null;
+    } | null;
     /** Shows a metric; drawn as plain paths and a label when the page is posed (metrics.ts). */
     gauge?: Gauge | null;
 }
@@ -250,6 +280,8 @@ export interface Page {
     layers: Layer[];
     elements: Element[];
     theme: string | null;
+    /** A theme of the page's own (ADR 0005), in place of `theme`. */
+    customTheme?: CustomTheme | null;
     timeline: Timeline | null;
     symbols: Symbol[] | null;
     /** The page's variables and their starting values (DottieDocument.variables). */

package/dist/types/planner.d.ts

@@ -0,0 +1,12 @@
+import type { Page } from "./model.ts";
+/** Frames times elements below which planning in place is quicker than starting a worker. */
+export declare const WORKER_WORK = 30000;
+/** Roughly how much resolving every frame of `page` takes: none with a camera, which plans without resolving. */
+export declare function planWork(page: Page): number;
+/** Whether `page` is worth planning in a worker, and one can be had. */
+export declare function plansInWorker(page: Page): boolean;
+/** Plans `page` in the worker; when it resolves, `plan(page)` returns that plan at once. On any failure it resolves
+ * all the same, and `plan(page)` then plans in place. */
+export declare function planInWorker(page: Page): Promise<void>;
+/** In a worker started by `planInWorker`, answers its requests. Elsewhere it does nothing. */
+export declare function servePlans(): void;

package/dist/types/player.d.ts

@@ -101,6 +101,10 @@ export declare class DottiePlayer extends ElementBase {
     private raf;
     private replayRaf;
     private loadToken;
+    /** Counts mounts, so a plan that comes back from a worker after a newer one is dropped. */
+    private mountToken;
+    /** The time a still shows; null while the drawing is animated. */
+    private stillTime;
     private visible;
     private observer;
     constructor();
@@ -111,8 +115,13 @@ export declare class DottiePlayer extends ElementBase {
     load(): Promise<void>;
     /** Shows an already-parsed file. */
     setFile(file: DottieFile): void;
+    private showFile;
+    /** Shows the file's page; then `mounted`. A big animation is planned in a worker first (planner.ts), and what was
+     * showing stays until it is ready; a newer mount, file or failed load in the meantime wins. */
     private mount;
+    private mountPage;
     get paused(): boolean;
+    /** The moment shown: a still's own time (its `at`, or the poster), else the current frame's. */
     get currentTime(): number;
     set currentTime(t: number);
     get duration(): number;

package/dist/types/sim-entry.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/types/svg.d.ts

@@ -17,6 +17,12 @@ export interface Plan {
 /** What an animation shows over time (Exporter.animation): with a camera, its view at each frame, widened to
  * the first key's shape; without, the bounds of the whole animation for every frame. */
 export declare function plan(page: Page): Plan;
+/** Whether `plan(page)` would return at once. */
+export declare function hasPlan(page: Page): boolean;
+/** Has `plan(page)` return `made`, a plan of this page made elsewhere (in a worker, planner.ts). */
+export declare function rememberPlan(page: Page, made: Plan): void;
+/** Whether `page` still holds exactly the fields it had when `fields` was copied from it. */
+export declare function unchanged(page: Page, fields: Page): boolean;
 /** The opening `<svg>` tag for `b`, with the page color behind everything when `paint`. */
 export declare function svgOpen(b: Rect, background: RGBA | null, paint: boolean): string;
 export interface Part {
@@ -25,8 +31,9 @@ export interface Part {
 }
 /** The SVG for each thing drawn, back to front, keyed by element id (rock hatching as "rock"). With `links`, an
  * element whose click or `url` is a web address is wrapped in an `<a>` that opens it, the click's first (the players
- * make their own clickable groups). */
-export declare function svgParts(page: Page, background: RGBA | null, fixed?: Rect, links?: boolean): {
+ * make their own clickable groups). With `only`, just the parts whose keys it accepts, drawn as they are on the
+ * whole page (connectors still meet and hop the rest). */
+export declare function svgParts(page: Page, background: RGBA | null, fixed?: Rect, links?: boolean, only?: (key: string) => boolean): {
     bounds: Rect;
     parts: Part[];
 };

package/dist/types/symbols.d.ts

@@ -1,4 +1,4 @@
-import { type Page, type Symbol, type SymbolPlayback } from "./model.ts";
+import { type Element, type Page, type Symbol, type SymbolPlayback } from "./model.ts";
 /** The deepest instances nest, and the most elements expanding one page may make (Symbol.maxDepth, .maxElements). */
 export declare const MAX_DEPTH = 8;
 export declare const MAX_ELEMENTS = 20000;
@@ -15,9 +15,25 @@ export declare function filled(s: Symbol, args: Record<string, string> | null):
 /** The symbol as a page of its own (Symbol.page). */
 export declare function symbolPage(s: Symbol): Page;
 export declare function hasInstances(page: Page): boolean;
+/** What each instance on a page expanded into, kept so that expanding the same page again at the same moment with
+ * a few instances' times changed (a button's other states) redoes only those. */
+export declare class Expansions {
+    readonly page: Page;
+    readonly t: number;
+    readonly posing: boolean;
+    /** For each instance: its time override, the budget it found and left, and what it made. */
+    readonly made: Map<Element, {
+        override: number | undefined;
+        before: number;
+        after: number;
+        out: Element[];
+    }>;
+    constructor(page: Page, t: number, posing: boolean);
+}
 /** The page with every instance replaced by what it shows at page time `t` (DottieDocument.expandingSymbols). `times`
- * puts instances on the page at a moment of their symbol's own: a button's other states, or a clip replaying. */
-export declare function expandingSymbols(page: Page, t: number, posing?: boolean, times?: Map<string, number>): Page;
+ * puts instances on the page at a moment of their symbol's own: a button's other states, or a clip replaying.
+ * `memo` records what each instance made, or, made for this page and moment, reuses it where nothing differs. */
+export declare function expandingSymbols(page: Page, t: number, posing?: boolean, times?: Map<string, number>, memo?: Expansions): Page;
 export declare function symbolTable(page: Page): Map<string, Symbol>;
 /** The id an element of a symbol has inside instance `instance` (DottieDocument.derivedID). */
 export declare function derivedID(instance: string, inner: string): string;

package/dist/types/theme.d.ts

@@ -1,10 +1,22 @@
-import type { RGBA } from "./model.ts";
+import type { Page, PaletteColor, RGBA } from "./model.ts";
 export interface Theme {
     id: string;
     name: string;
     background: RGBA;
     ink: RGBA;
+    palette: PaletteColor[];
 }
+/** The palette names every built-in theme has, in order. */
+export declare const PALETTE_NAMES: string[];
+/** Light pages. */
+export declare const LIGHT_PALETTE: PaletteColor[];
 export declare const themes: Theme[];
 /** The theme a page names, or null (white page, black ink) for none or one this version doesn't know. */
 export declare function themeNamed(id: string | null | undefined): Theme | null;
+/** The theme `page` is drawn in: its own, else the built-in it names, else null. */
+export declare function pageTheme(page: Pick<Page, "theme" | "customTheme">): Theme | null;
+/** The palette color `name` names on `page`, ignoring case. */
+export declare function paletteColor(page: Pick<Page, "theme" | "customTheme">, name: string): RGBA | null;
+/** `page` with every named color set from its palette (DottieDocument.resolvingPalette); a name the palette doesn't
+ * have keeps the color it had. */
+export declare function resolvingPalette(page: Page): Page;

package/dist/types/timeline.d.ts

@@ -1,3 +1,4 @@
+import { type Index } from "./connector.ts";
 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";
@@ -13,8 +14,9 @@ export declare function isVisible(track: Track, t: number): boolean;
 export declare function applyTrack(track: Track, e: Element, t: number): Element;
 /** The path span placing the element at `t`, unless an x or y key after it has taken the element back. */
 export declare function followSpan(track: Track, t: number): Follow | null;
-/** The clean route of a connector, or the clean, rotated outline of any other element. */
-export declare function tracing(e: Element, page: Page): Polyline;
+/** The clean route of a connector, or the clean, rotated outline of any other element. `index` is the page's,
+ * passed by callers that already have it. */
+export declare function tracing(e: Element, page: Page, index?: Index): Polyline;
 /** `e` moved onto the path it is following at `t`, if any. `page` has every key applied. */
 export declare function following(track: Track, e: Element, t: number, page: Page): Element;
 /** Where the dashes of a line marching at `speed` stand at `t`, within one pattern `period` (Timeline.marchOffset):

package/package.json

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