@phin-tech/dottie 0.6.2 → 0.7.0

package/dist/types/clicks.d.ts

@@ -1,12 +1,18 @@
 import { type DottieFile, type Element, type Marker, type Page } from "./model.ts";
 /** Jump to scene `scene` (an index into the page's markers) and play on to the next; open `url` in a new tab; or,
- * in <dottie-player> only, show page `page` (an index into the file's pages), where the element's link points. */
-export type Click = {
+ * in <dottie-player> only, show page `page` (an index into the file's pages), where the element's link points. Any
+ * of them may first `set` and `toggle` page variables (ClickAction.set, .toggle), and a click may do only that. */
+export type Click = ({
     scene: number;
 } | {
     url: string;
 } | {
     page: number;
+} | {
+    state: true;
+}) & {
+    set?: Record<string, boolean>;
+    toggle?: string[];
 };
 /** 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/connector.d.ts

@@ -6,18 +6,18 @@ export declare function portPoint(shape: Element, port: Port): Point;
 /** Where the line from the shape's center toward `target` crosses its outline. */
 export declare function edgePoint(shape: Element, toward: Point): Point;
 export declare function endpoints(e: Element, index: Index): [Point, Point];
+/** A curve is joined cubic Béziers: the start, then two controls and an end per segment. */
 export type Route = {
     kind: "polyline";
     points: Point[];
 } | {
-    kind: "cubic";
-    a: Point;
-    b: Point;
-    c: Point;
-    d: Point;
+    kind: "curve";
+    points: Point[];
 };
-/** A route's centerline as points; a cubic is sampled at 25 points. */
+/** A route's centerline as points; each cubic segment is sampled at 25 points. */
 export declare function routePoints(r: Route): Point[];
+/** Drops repeated points and the middle of three in a line, so dragged bends that fall into line disappear. */
+export declare function simplified(pts: Point[]): Point[];
 export declare function route(e: Element, index: Index): Route;
 /** Arrowhead wing points for a tip at `tip` arriving from `from`. */
 export declare function arrowhead(tip: Point, from: Point, size: number): [Point, Point];

package/dist/types/element.d.ts

@@ -11,6 +11,9 @@ export declare const unrotated: (e: Element, p: Point) => Point;
 export declare function rotatedBounds(e: Element): Rect;
 /** The element with automatic ink drawn as `ink`; a light ink is not used on a light, mostly opaque fill. */
 export declare function resolvingInk(e: Element, ink: RGBA): Element;
+/** What the element's text is drawn in: a text box's and a note's stroke, any other label's `textColor` or,
+ * without one, its stroke. */
+export declare function labelColor(e: Element): RGBA;
 export interface Contour {
     closed: boolean;
     points: Point[];

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.6.2";
+export declare const VERSION = "0.7.0";

package/dist/types/model.d.ts

@@ -27,6 +27,8 @@ export interface Style {
     opacity: number | null;
     /** How far into its dash pattern a dashed or dotted line starts; marching ants set it on every frame. */
     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;
 }
 /** `portIndex` pins the end to one of the bound element's `ports`, and wins over `port`. */
 export interface Endpoint {
@@ -49,6 +51,10 @@ export interface ConnectorData {
     routing: Routing;
     startHead: Arrowhead;
     endHead: Arrowhead;
+    /** Bends on the canvas the line passes through, start to end. */
+    waypoints: StrokePoint[] | null;
+    /** Hops where the line crosses a connector drawn beneath it. */
+    hops: boolean | null;
 }
 export interface PathSubpath {
     closed: boolean;
@@ -62,10 +68,13 @@ export interface EmbeddedImage {
     data: string;
     format: string;
 }
-/** What clicking an element does in a played drawing: a scene to jump to and play on from, or a link. */
+/** What clicking an element does in a played drawing: a scene to jump to and play on from, or a link; and page
+ * variables to set and flip (ClickAction.set, .toggle), which change what shows without touching the playhead. */
 export interface ClickAction {
     scene: string | null;
     url: string | null;
+    set: Record<string, boolean> | null;
+    toggle: string[] | null;
 }
 /** How a clickable element looks under the pointer or with keyboard focus; null keeps its own. */
 export interface HoverLook {
@@ -99,6 +108,8 @@ export interface Element {
     anchor: string | null;
     click: ClickAction | null;
     hover: HoverLook | null;
+    /** A condition on the page's variables: drawn only while it holds (Element.when; see state.ts). */
+    when: string | 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;
@@ -173,9 +184,11 @@ export interface CameraKey {
     height: number;
     ease: Ease | null;
 }
+/** A scene; `loop` plays it round until something leaves it, instead of stopping on it (Marker.loop). */
 export interface Marker {
     t: number;
     name: string;
+    loop: boolean | null;
 }
 export interface Timeline {
     fps: number;
@@ -195,6 +208,8 @@ export interface Page {
     theme: string | null;
     timeline: Timeline | null;
     symbols: Symbol[] | null;
+    /** The page's variables and their starting values (DottieDocument.variables). */
+    variables: Record<string, boolean> | 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

@@ -10,6 +10,10 @@ export declare class Playback {
     readonly plan: Plan;
     readonly scenes: number[];
     readonly sceneNames: string[];
+    /** Whether each scene loops (Marker.loop). */
+    readonly sceneLoops: boolean[];
+    /** The page's variables now: their starting values until clicks change them. */
+    state: Record<string, boolean>;
     readonly background: RGBA;
     readonly ink: RGBA;
     /** What clicking each clickable element does, by element id. */
@@ -56,6 +60,14 @@ export declare class Playback {
     private buttonPart;
     /** The scene frame `i` is in, or -1 before the first. */
     sceneAt(i: number): number;
+    /** The frame after scene `s`'s last: the next scene's, or the frame count after the last scene. */
+    sceneEnd(s: number): number;
+    /** Where playing goes from frame `i`, and whether it stops there: on into a looping scene, round to the start of
+     * the looping scene `i` ends, or a stop at a scene or the end (`loops`: whether the timeline loops at its end). */
+    step(i: number, loops: boolean): {
+        frame: number;
+        stop: boolean;
+    };
 }
 /** HTMLElement where there is a DOM; a stand-in elsewhere, so the library still loads in Node (to render SVG). */
 declare const ElementBase: typeof HTMLElement;
@@ -95,18 +107,23 @@ export declare class DottiePlayer extends ElementBase {
     get duration(): number;
     play(): void;
     pause(): void;
-    /** Plays on to the next scene (from the start after the last). */
+    /** Plays on to the next scene (from the start after the last). Out of a looping scene it jumps to the next. */
     nextScene(): void;
     /** Back to the start of this scene, or the one before if already there. */
     prevScene(): void;
     /** Does what clicking element `id` does: jumps to its scene and plays on to the next (with reduced motion, or in a
      * still, straight to where that stops), opens its link in a new tab, or shows its page. */
     activate(id: string): void;
+    /** The page's variables now. */
+    get variables(): Record<string, boolean>;
+    /** Gives the page's variables these values (the others keep theirs), redraws, and fires `state`. */
+    setState(values: Record<string, boolean>): void;
     /** Redraws, while the page itself stands still, as long as a clicked copy is playing through. */
     private scheduleReplay;
     private setPlaying;
     private schedule;
-    /** Steps whole frames at the timeline's rate; with scenes, playing stops at each one and at the end. */
+    /** Steps whole frames at the timeline's rate; with scenes, playing stops at each one and at the end, except that a
+     * looping scene plays round (Playback.step). */
     private tick;
     private key;
 }

package/dist/types/shapes.d.ts

@@ -1,5 +1,5 @@
-import { type Index } from "./connector.ts";
-import type { DashStyle, Element } from "./model.ts";
+import { type Index, type Route } from "./connector.ts";
+import { type DashStyle, type Element, type Page } from "./model.ts";
 import { Path, type Point } from "./path.ts";
 /** The `.grid` cell size actually drawn. */
 export declare const cellSize: (e: Element) => number;
@@ -13,5 +13,18 @@ export declare function fillPath(e: Element): Path;
 export declare function hachurePath(e: Element): Path;
 /** Dash lengths for a stroke width; null for a solid line. */
 export declare function dashPattern(dash: DashStyle, width: number): number[] | null;
-/** A connector as the stroked line (with open arrowheads) and the closed heads filled in the stroke color. */
-export declare function connectorParts(e: Element, index: Index): [Path, Path];
+/**
+ * A connector as the stroked line (with open arrowheads) and the closed heads filled in the stroke color. `page`
+ * holds the connectors a hopping line hops over; without it a line draws no hops.
+ */
+export declare function connectorParts(e: Element, index: Index, page?: Page): [Path, Path];
+/** How big a hop is for a line `strokeWidth` wide: its radius. */
+export declare function hopRadius(strokeWidth: number): number;
+/** The points a route's segments are measured along: a straight segment's two ends, or a cubic sampled at 25. */
+export declare function hopSamples(r: Route): Point[][];
+/**
+ * Where a hopping connector's segments (straight, or each cubic of a curve) cross the connectors drawn beneath it
+ * (earlier on a visible layer): for each segment, the distances along it, ascending, leaving out crossings too close
+ * to its ends or the hop before.
+ */
+export declare function hopCrossings(e: Element, r: Route, page: Page, index: Index): number[][];

package/dist/types/state.d.ts

@@ -0,0 +1,20 @@
+import type { ClickAction, Page } 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). */
+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;
+/** 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>;
+/** The values `choice` gives each variable; null for "all". */
+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>;
+/** 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>;

package/dist/types/timeline.d.ts

@@ -1,5 +1,6 @@
 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";
 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;
@@ -20,9 +21,10 @@ 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): Page;
-/** The page posed at `t` seconds, instances kept (DottieDocument.posed(at:)). */
-export declare function posed(page: Page, t: number): Page;
+export declare function resolved(page: Page, t: number, state?: StateChoice): 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;
 /** 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.6.2",
+  "version": "0.7.0",
   "description": "Render, play and compile Dottie (.dottie) drawings and animations in the browser",
   "type": "module",
   "license": "Apache-2.0",