@phin-tech/dottie 0.5.0 → 0.5.1

package/dist/types/clicks.d.ts

@@ -0,0 +1,30 @@
+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 = {
+    scene: number;
+} | {
+    url: string;
+} | {
+    page: number;
+};
+/** The marker called `name`: an exact match, else one that differs only in case. */
+export declare function sceneNamed(name: string, markers: Marker[]): number;
+/** The page's clickable elements and what each click does, by element id. A scene named by no marker, or a link
+ * that isn't allowed, makes nothing clickable. Given the whole file, an element whose `link` points at an element on
+ * another page shows that page (the HTML export holds one page, so it can't). */
+export declare function clickTargets(page: Page, file?: DottieFile): Map<string, Click>;
+/** `e` as it looks hovered (HoverLook.apply). */
+export declare function hoveredElement(e: Element): Element;
+/** `page` with `ids` drawn as they look hovered. */
+export declare function hovered(page: Page, ids: Set<string>): Page;
+export declare function hasHover(e: Element): boolean;
+/** What a screen reader calls the element as a button: the first line of its text, else its anchor, else for a
+ * symbol's copy the symbol's name, else its kind. */
+export declare function buttonLabel(e: Element, symbolName?: string): string;
+/** For each of `instances`, the ids of every element it can expand to, mapped to it, in drawing order
+ * (DottieDocument.parts(of:)). */
+export declare function partsOf(page: Page, instances: Set<string>): Map<string, string>;
+/** How clickable elements look (Exporter.clickStyle): a pointer, their hover look under it or with keyboard focus (a
+ * soft glow when they have none), and a small nudge while pressed. */
+export declare const CLICK_STYLE = "\n.dottie-a { cursor: pointer; outline: none; }\n.dottie-a .dottie-h { display: none; }\n.dottie-a:hover .dottie-h, .dottie-a.dottie-hover .dottie-h, .dottie-a:focus-visible .dottie-h { display: inline; }\n.dottie-a:hover .dottie-n, .dottie-a.dottie-hover .dottie-n, .dottie-a:focus-visible .dottie-n { display: none; }\n.dottie-a:focus-visible { filter: drop-shadow(0 0 3px var(--dottie-focus, #3b82f6)); }\n.dottie-a:not(.dottie-b):active, .dottie-a.dottie-press:not(.dottie-b) { transform: translate(1px, 1px); }\n.dottie-a .dottie-d { display: none; }\n.dottie-b:active .dottie-n, .dottie-b:active .dottie-h, .dottie-b.dottie-press .dottie-n, .dottie-b.dottie-press .dottie-h { display: none; }\n.dottie-b:active .dottie-d, .dottie-b.dottie-press .dottie-d { display: inline; }\n";

package/dist/types/index.d.ts

@@ -18,4 +18,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.5.0";
+export declare const VERSION = "0.5.1";

package/dist/types/model.d.ts

@@ -6,7 +6,8 @@ export interface RGBA {
 }
 export type FillStyle = "solid" | "hachure" | "crossHatch" | "grid";
 export type DashStyle = "solid" | "dashed" | "dotted";
-export type ElementKind = "rectangle" | "ellipse" | "diamond" | "text" | "connector" | "freehand" | "path" | "note" | "image";
+export type ElementKind = "rectangle" | "ellipse" | "diamond" | "text" | "connector" | "freehand" | "path" | "note" | "image" | "symbol";
+export type SymbolPlayback = "loop" | "once" | "still" | "click";
 export type Port = "top" | "right" | "bottom" | "left";
 export type Routing = "straight" | "curved" | "elbow";
 export type Arrowhead = "none" | "arrow" | "triangle" | "dot" | "bar";
@@ -50,6 +51,17 @@ 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. */
+export interface ClickAction {
+    scene: string | null;
+    url: string | null;
+}
+/** How a clickable element looks under the pointer or with keyboard focus; null keeps its own. */
+export interface HoverLook {
+    stroke: RGBA | null;
+    fill: RGBA | null;
+    opacity: number | null;
+}
 export interface Element {
     id: string;
     /** A kind dottie.js doesn't know is kept as written and drawn as a labelled placeholder. */
@@ -71,6 +83,12 @@ export interface Element {
     rotation: number | null;
     link: string | null;
     anchor: string | null;
+    click: ClickAction | null;
+    hover: HoverLook | 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;
+    offset: number | null;
     /** Base64 bytes; an empty `data` is a picture that couldn't be found (drawn crossed out). */
     image: EmbeddedImage | null;
     reveal: number | null;
@@ -148,6 +166,19 @@ export interface Page {
     elements: Element[];
     theme: string | null;
     timeline: Timeline | null;
+    symbols: Symbol[] | null;
+}
+/** A drawing defined once on a page and placed by `symbol` elements, with its own timeline (Symbol). */
+export interface Symbol {
+    id: string;
+    name: string;
+    width: number;
+    height: number;
+    layers: Layer[];
+    elements: Element[];
+    timeline: Timeline | null;
+    /** A Flash-style button: copies show its up scene; on the web, over, down and hit (Symbol.button). */
+    button: boolean | null;
 }
 export interface DottieFile {
     version: number;
@@ -173,6 +204,9 @@ export declare class DottieFormatError extends Error {
 }
 export declare function clampTime(t: number): number;
 export declare function clampFPS(f: number): number;
+/** `url` trimmed, if it is a link a page may open: http, https or mailto, as ClickAction.allowed. A drawing can
+ * play on someone else's site, so nothing else (javascript:, data:) is ever followed. */
+export declare function allowedURL(url: string): string | null;
 export declare function repeatIsValid(r: Repeat): boolean;
 /** Sorts in place by `key`, keeping equal keys in their original order (as Swift's sort happens to for these). */
 export declare function stableSortBy<T>(a: T[], key: (v: T) => number): void;

package/dist/types/player.d.ts

@@ -1,3 +1,4 @@
+import { type Click } from "./clicks.ts";
 import { type DottieFile, type Page, type RGBA } from "./model.ts";
 import { type Plan } from "./svg.ts";
 /** Finds a page by name (any case) or 1-based number; the first page when `spec` is empty or matches nothing. */
@@ -11,20 +12,48 @@ export declare class Playback {
     readonly sceneNames: string[];
     readonly background: RGBA;
     readonly ink: RGBA;
+    /** What clicking each clickable element does, by element id. */
+    readonly clicks: Map<string, Click>;
+    /** Copies of symbols that play through once when clicked (playback "click"), by id, with their clip's length. */
+    readonly replays: Map<string, number>;
+    /** When each replaying copy was clicked (performance.now() milliseconds). */
+    private replayStarts;
+    private hoverIDs;
+    private labels;
+    /** Each drawn part of a clickable copy, to that copy's id; and each copy's parts in drawing order. */
+    private owner;
+    private partsOfOwner;
+    /** The moments of the button copies' over, down and hit states. */
+    private overTimes;
+    private downTimes;
+    private hitTimes;
+    private last;
     private svg;
     private groups;
     private order;
     frame: number;
     onFrame: ((frame: number) => void) | null;
+    /** `file` is the drawing `page` belongs to, so links to its other pages are clickable. */
     constructor(page: Page, into: Element, options?: {
         clean?: boolean;
+        file?: DottieFile;
     });
     get frameCount(): number;
     get posterFrame(): number;
     /** Draws frame `i`, replacing only the pieces whose markup changed since the last frame. */
     show(i: number): void;
+    /** Starts copy `id` replaying from `at` (performance.now() milliseconds; earlier to start partway). */
+    replay(id: string, at: number): void;
+    /** Whether a copy is still playing through after a click. */
+    replaying(now?: number): boolean;
+    /** Draws the last moment drawn again, for copies replaying while the page stands still. */
+    redraw(): void;
     /** Draws the moment `t` (seconds) in the frame-`i` view. */
     drawAt(t: number, i?: number): void;
+    /** What a clickable owner draws as: its normal look, and its hover, over and down looks where they differ. A
+     * symbol's copy keeps its drawing out of the pointer's way and takes clicks on a layer above: its hit state drawn
+     * invisibly, or its frame. `button` is whether it has a down look (the stylesheet nudges the others). */
+    private buttonPart;
     /** The scene frame `i` is in, or -1 before the first. */
     sceneAt(i: number): number;
 }
@@ -47,6 +76,7 @@ export declare class DottiePlayer extends ElementBase {
     private last;
     private acc;
     private raf;
+    private replayRaf;
     private loadToken;
     private visible;
     private observer;
@@ -69,6 +99,11 @@ export declare class DottiePlayer extends ElementBase {
     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;
+    /** 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. */

package/dist/types/symbols.d.ts

@@ -0,0 +1,20 @@
+import { 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;
+export type ButtonState = "up" | "over" | "down" | "hit";
+/** The moment of the symbol's scene named `state`, any case, within its timeline (Symbol.sceneTime). */
+export declare function sceneTime(s: Symbol, state: ButtonState): number | null;
+/** Where a button is in each state (Symbol.buttonTime): over falls back to up, down to over; hit to nothing. */
+export declare function buttonTime(s: Symbol, state: ButtonState): number | null;
+/** Where an instance is in its symbol's timeline at page time `t` (Symbol.localTime). */
+export declare function symbolTime(s: Symbol, t: number, playback: SymbolPlayback | null, offset: number | null): number;
+/** The symbol as a page of its own (Symbol.page). */
+export declare function symbolPage(s: Symbol): Page;
+export declare function hasInstances(page: Page): 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;
+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/timeline.d.ts

@@ -18,8 +18,11 @@ export declare function following(track: Track, e: Element, t: number, page: Pag
 /** Where the dashes of a line marching at `speed` stand at `t`, within one pattern `period` (Timeline.marchOffset):
  * the speed is rounded to a whole number of patterns over the timeline, so a loop is seamless. */
 export declare function marchOffset(tl: Timeline, speed: number, period: number, t: number): number;
-/** The page as a still drawing at `t` seconds (DottieDocument.resolved(at:)). A page without a timeline is returned as is. */
+/** 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;
 /** 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.5.0",
+  "version": "0.5.1",
   "description": "Render, play and compile Dottie (.dottie) drawings and animations in the browser",
   "type": "module",
   "license": "Apache-2.0",