flowsvg 0.1.0 → 0.2.0

package/dist/adapters/web-component.js

@@ -0,0 +1,425 @@
+/**
+ * Web Component boundary: convert attributes/objects/URLs and manage lifecycle while reusing browser playback/rendering.
+ * Imports do not register the element; DOM-free imports use a placeholder base, so real registration needs a browser load.
+ */
+import { createDiagram } from "../core/diagram.js";
+import { createPlayer } from "../browser/player.js";
+/** Default custom-element name registered by {@link defineFlowPlayer}. */
+export const FLOW_PLAYER_TAG = "flowsvg-player";
+// typeof permits DOM-free imports, but the base is fixed at evaluation time; load this entry with a DOM to create elements.
+const HTMLElementBase = (typeof HTMLElement === "undefined"
+    ? class {
+    }
+    : HTMLElement);
+/**
+ * Custom-element adapter for attribute conversion, URL requests and playback/error events.
+ * The document property may be assigned before connection; disconnect releases the player/requests but retains the document.
+ * Rendering/timeline behavior delegates to createPlayer; registration requires an explicit defineFlowPlayer call.
+ */
+export class FlowPlayerElement extends HTMLElementBase {
+    static observedAttributes = [
+        "document",
+        "src",
+        "autoplay",
+        "controls",
+        "speed",
+        "theme",
+        "reduced-motion",
+        "hover-fill",
+        "gif-export",
+        "loop"
+    ];
+    player;
+    playerHost;
+    sourceAbort;
+    requestToken = 0;
+    connected = false;
+    manuallyDestroyed = false;
+    currentDocument;
+    controlsOverride;
+    forwardedEvents = [];
+    /** Current object document; assigning undefined clears it, cancels requests and unmounts the player. */
+    get document() {
+        return this.currentDocument;
+    }
+    set document(value) {
+        if (value === undefined) {
+            this.currentDocument = undefined;
+            this.cancelSourceLoad();
+            this.unmountPlayer();
+            return;
+        }
+        this.setDocument(value);
+    }
+    /** Document URL resolved against ownerDocument.baseURI; changes cancel obsolete loads. */
+    get src() {
+        return this.getAttribute?.("src") ?? undefined;
+    }
+    set src(value) {
+        if (value === undefined || value === "")
+            this.removeAttribute("src");
+        else
+            this.setAttribute("src", value);
+    }
+    /** Whether to autoplay; false pauses a mounted player. */
+    get autoplay() {
+        return readBooleanAttribute(this, "autoplay", false);
+    }
+    set autoplay(value) {
+        setBooleanAttribute(this, "autoplay", value);
+        this.applyAutoplay();
+    }
+    /** Live loop mode, reflected by the loop attribute; changes retain time and play state. */
+    get loop() {
+        return readBooleanAttribute(this, "loop", false);
+    }
+    set loop(value) {
+        setBooleanAttribute(this, "loop", value);
+    }
+    /** Controls default on; an explicit false is retained in HTML as controls="false". */
+    get controls() {
+        return this.controlsOverride ?? readBooleanAttribute(this, "controls", true);
+    }
+    set controls(value) {
+        this.controlsOverride = value;
+        // An omitted attribute enables controls, so disabling must preserve the false text rather than remove the attribute.
+        if (value)
+            this.setAttribute("controls", "");
+        else
+            this.setAttribute("controls", "false");
+        this.rebuildForOptions();
+    }
+    /** Positive speed multiplier; invalid attribute text reads as 1, while invalid property assignments are ignored. */
+    get speed() {
+        return readPositiveNumber(this.getAttribute?.("speed"), 1);
+    }
+    set speed(value) {
+        if (!Number.isFinite(value) || value <= 0)
+            return;
+        this.setAttribute("speed", String(value));
+        this.player?.setSpeed(value);
+    }
+    /** Explicit light/dark theme; the player falls back to the document theme or light when unset. */
+    get theme() {
+        const value = this.getAttribute?.("theme");
+        return value === "light" || value === "dark" ? value : undefined;
+    }
+    set theme(value) {
+        if (value === undefined)
+            this.removeAttribute("theme");
+        else
+            this.setAttribute("theme", value);
+    }
+    /** undefined follows the system preference; true/false explicitly override it via reduced-motion. */
+    get reducedMotion() {
+        const value = this.getAttribute?.("reduced-motion");
+        if (value === null || value === undefined)
+            return undefined;
+        return parseBooleanValue(value, true);
+    }
+    set reducedMotion(value) {
+        if (value === undefined)
+            this.removeAttribute("reduced-motion");
+        else
+            this.setAttribute("reduced-motion", String(value));
+    }
+    /** Hover paints only borders by default. The hover-fill attribute enables background and content feedback. */
+    get hoverFill() {
+        return readBooleanAttribute(this, "hover-fill", false);
+    }
+    set hoverFill(value) {
+        setBooleanAttribute(this, "hover-fill", value);
+    }
+    /** Opt-in GIF controls, reflected by the gif-export attribute; defaults to false. */
+    get gifExport() {
+        return readBooleanAttribute(this, "gif-export", false);
+    }
+    set gifExport(value) {
+        setBooleanAttribute(this, "gif-export", value);
+    }
+    connectedCallback() {
+        this.connected = true;
+        this.manuallyDestroyed = false;
+        if (this.player)
+            return;
+        if (this.currentDocument) {
+            this.mountPlayer(this.currentDocument);
+            return;
+        }
+        const documentAttribute = this.getAttribute("document");
+        if (documentAttribute !== null) {
+            this.loadDocumentAttribute(documentAttribute);
+            return;
+        }
+        const source = this.getAttribute("src");
+        if (source)
+            void this.loadSource(source);
+    }
+    disconnectedCallback() {
+        this.connected = false;
+        this.cancelSourceLoad();
+        this.unmountPlayer();
+    }
+    attributeChangedCallback(name, _oldValue, value) {
+        if (_oldValue === value || !this.connected)
+            return;
+        switch (name) {
+            case "document":
+                if (value === null) {
+                    this.currentDocument = undefined;
+                    this.unmountPlayer();
+                }
+                else
+                    this.loadDocumentAttribute(value);
+                break;
+            case "src":
+                this.cancelSourceLoad();
+                if (value)
+                    void this.loadSource(value);
+                break;
+            case "controls":
+                this.controlsOverride = value === null ? undefined : parseBooleanValue(value, true);
+            case "theme":
+            case "reduced-motion":
+            case "hover-fill":
+            case "gif-export":
+                this.rebuildForOptions();
+                break;
+            case "loop":
+                this.player?.setLoop(this.loop);
+                break;
+            case "speed":
+                this.player?.setSpeed(this.speed);
+                break;
+            case "autoplay":
+                this.applyAutoplay();
+                break;
+            default:
+                break;
+        }
+    }
+    /** Forward controls to the mounted player; calls are inert when no player is mounted. */
+    play() {
+        this.player?.play();
+    }
+    /** Pause the mounted player, retaining its current frame; do nothing before mounting. */
+    pause() {
+        this.player?.pause();
+    }
+    /** Seek in milliseconds using browser-player clamping; do nothing before mounting. */
+    seek(timeMs) {
+        this.player?.seek(timeMs);
+    }
+    /** Pause and jump to a beat boundary; backward from inside a beat goes to that beat's start. */
+    step(direction) {
+        this.player?.step(direction);
+    }
+    /** Set the speed property, retaining it for future mounts; ignore non-finite or non-positive values. */
+    setSpeed(value) {
+        this.speed = value;
+    }
+    /** Set loop mode and retain it for future mounts. */
+    setLoop(value) {
+        this.loop = value;
+    }
+    /** Return undefined before mounting or after destruction. */
+    getState() {
+        return this.player?.getState();
+    }
+    /** Explicitly release the player and requests; the manual-destruction flag resets on the next connection. */
+    destroy() {
+        this.manuallyDestroyed = true;
+        this.cancelSourceLoad();
+        this.unmountPlayer();
+    }
+    setDocument(value) {
+        this.cancelSourceLoad();
+        try {
+            // Validate before replacement so an invalid document does not discard the last valid frame.
+            createDiagram(value);
+            this.currentDocument = value;
+            if (this.connected && !this.manuallyDestroyed) {
+                if (this.player)
+                    this.player.load(value);
+                else
+                    this.mountPlayer(value);
+                this.applyAutoplay();
+            }
+        }
+        catch (error) {
+            this.dispatchError(toError(error));
+        }
+    }
+    loadDocumentAttribute(value) {
+        try {
+            const parsed = JSON.parse(value);
+            this.setDocument(parsed);
+        }
+        catch (error) {
+            this.dispatchError(toError(error));
+        }
+    }
+    /** AbortController cancels network work; the token also rejects obsolete results already received but not yet applied. */
+    async loadSource(source) {
+        const token = ++this.requestToken;
+        const controller = new AbortController();
+        this.sourceAbort?.abort();
+        this.sourceAbort = controller;
+        try {
+            const owner = this.ownerDocument;
+            const url = new URL(source, owner.baseURI).href;
+            const response = await fetch(url, { signal: controller.signal });
+            if (!response.ok)
+                throw new Error(`Failed to load diagram source (${response.status})`);
+            const parsed = await response.json();
+            // Recheck connection and request ownership after parsing so stale responses cannot replace a newer document/src.
+            if (!this.connected || token !== this.requestToken || controller.signal.aborted)
+                return;
+            this.setDocument(parsed);
+        }
+        catch (error) {
+            if (controller.signal.aborted || token !== this.requestToken)
+                return;
+            this.dispatchError(toError(error));
+        }
+        finally {
+            if (this.sourceAbort === controller)
+                this.sourceAbort = undefined;
+        }
+    }
+    /** Restore an existing playback state during option rebuilds; autoplay applies only to a fresh mount. */
+    mountPlayer(document, previous) {
+        if (!this.connected || this.manuallyDestroyed || this.player)
+            return;
+        const owner = this.ownerDocument;
+        const host = owner.createElement("div");
+        host.className = "flowsvg-element-host";
+        this.playerHost = host;
+        this.append(host);
+        try {
+            this.player = createPlayer(host, document, this.playerOptions());
+            this.forwardPlayerEvents(host);
+            this.player.setSpeed(this.speed);
+            if (previous) {
+                this.player.seek(previous.timeMs);
+                if (previous.playing)
+                    this.player.play();
+            }
+            else
+                this.applyAutoplay();
+        }
+        catch (error) {
+            this.unmountPlayer();
+            this.dispatchError(toError(error));
+        }
+    }
+    /** Rebuild for option changes and restore time/playback; document replacement instead follows load's reset-to-zero rule. */
+    rebuildForOptions() {
+        if (!this.connected || !this.currentDocument || this.manuallyDestroyed)
+            return;
+        const previous = this.player?.getState();
+        this.unmountPlayer();
+        this.mountPlayer(this.currentDocument, previous);
+    }
+    /** Detach forwarding before destruction so teardown cannot forward events from the old instance. */
+    unmountPlayer() {
+        this.removeForwardedEvents();
+        this.player?.destroy();
+        this.player = undefined;
+        this.playerHost?.remove();
+        this.playerHost = undefined;
+    }
+    forwardPlayerEvents(host) {
+        this.removeForwardedEvents();
+        for (const name of ["stepchange", "timeupdate", "playstatechange", "loopchange", "error"]) {
+            const listener = (event) => {
+                const source = event;
+                if (name === "loopchange") {
+                    setBooleanAttribute(this, "loop", source.detail.loop);
+                }
+                this.dispatchEvent(new CustomEvent(name, {
+                    detail: source.detail,
+                    bubbles: true,
+                    composed: true
+                }));
+            };
+            host.addEventListener(name, listener);
+            this.forwardedEvents.push({ name, listener });
+        }
+    }
+    removeForwardedEvents() {
+        if (!this.playerHost) {
+            this.forwardedEvents.length = 0;
+            return;
+        }
+        for (const { name, listener } of this.forwardedEvents)
+            this.playerHost.removeEventListener(name, listener);
+        this.forwardedEvents.length = 0;
+    }
+    playerOptions() {
+        return {
+            controls: this.controls,
+            loop: this.loop,
+            gifExport: this.gifExport,
+            hoverFill: this.hoverFill,
+            ...(this.theme ? { theme: this.theme } : {}),
+            ...(this.reducedMotion === undefined ? {} : { reducedMotion: this.reducedMotion })
+        };
+    }
+    applyAutoplay() {
+        if (!this.player)
+            return;
+        if (this.autoplay)
+            this.player.play();
+        else
+            this.player.pause();
+    }
+    cancelSourceLoad() {
+        this.requestToken += 1;
+        this.sourceAbort?.abort();
+        this.sourceAbort = undefined;
+    }
+    dispatchError(error) {
+        const detail = { error, ...(this.player ? this.player.getState() : {}) };
+        this.dispatchEvent(new CustomEvent("error", { detail, bubbles: true, composed: true }));
+    }
+}
+/**
+ * Register explicitly; repeated calls for the default name return the existing constructor, or undefined without customElements.
+ * Load the module with a DOM for real registration, since the HTMLElement base is fixed at module evaluation.
+ * @throws {DOMException} From the registry for invalid names or reusing the constructor under another name.
+ */
+export function defineFlowPlayer(tagName = FLOW_PLAYER_TAG) {
+    if (typeof customElements === "undefined")
+        return undefined;
+    const existing = customElements.get(tagName);
+    if (existing)
+        return existing;
+    customElements.define(tagName, FlowPlayerElement);
+    return FlowPlayerElement;
+}
+function readBooleanAttribute(element, name, fallback) {
+    const value = element.getAttribute(name);
+    return value === null ? fallback : parseBooleanValue(value, true);
+}
+function parseBooleanValue(value, fallback) {
+    const normalized = value.trim().toLowerCase();
+    if (normalized === "false" || normalized === "0" || normalized === "no")
+        return false;
+    if (normalized === "true" || normalized === "1" || normalized === "yes" || normalized === "")
+        return true;
+    return fallback;
+}
+function setBooleanAttribute(element, name, value) {
+    if (value)
+        element.setAttribute(name, "");
+    else
+        element.removeAttribute(name);
+}
+function readPositiveNumber(value, fallback) {
+    const parsed = Number(value);
+    return Number.isFinite(parsed) && parsed > 0 ? parsed : fallback;
+}
+function toError(error) {
+    return error instanceof Error ? error : new Error(String(error));
+}

package/dist/{player-controls.d.ts → browser/controls.d.ts}

@@ -1,4 +1,3 @@
-/** Built-in controls consume state and forward actions; the browser player owns evaluation and scheduling. */
 /** Scene selection metadata with its global start time in milliseconds. */
 interface SceneChoice {
     id: string;
@@ -11,23 +10,26 @@ interface ControlActions {
     step(direction: 1 | -1): void;
     seek(timeMs: number): void;
     setSpeed(speed: number): void;
+    toggleLoop(): void;
 }
 /** Player-state projection for controls; the scene list is replaced on document load. */
 interface ControlState {
     timeMs: number;
     totalDuration: number;
     playing: boolean;
+    loop: boolean;
     speed: number;
     sceneId: string | null;
     scenes: readonly SceneChoice[];
 }
 /**
  * Persistent control DOM translates input to commands; render synchronizes labels, progress and disabled states.
- * Own no clock or independent position; time-related controls are disabled for static documents.
+ * Own no clock or independent position; Time-related controls are disabled for static documents.
  */
 export declare class PlayerControls {
     readonly element: HTMLDivElement;
     private readonly play;
+    private readonly loop;
     private readonly previous;
     private readonly next;
     private readonly progress;
@@ -35,7 +37,9 @@ export declare class PlayerControls {
     private readonly speed;
     private sceneChoices;
     constructor(owner: Document, actions: ControlActions);
-    /** Update existing controls; scene choices change by reference and custom speeds are added as options. */
+    /** Update existing controls; custom speeds join the default choices without changing committed state. */
     render(state: ControlState): void;
+    /** Release menu listeners before the player removes its DOM. */
+    destroy(): void;
 }
 export type { SceneChoice };

package/dist/{player-controls.js → browser/controls.js}

@@ -1,11 +1,14 @@
+/** Built-in controls consume state and forward actions; the browser player owns evaluation and scheduling. */
+import { SelectControl } from "./select-control.js";
 const DEFAULT_SPEEDS = [0.5, 1, 1.5, 2];
 /**
  * Persistent control DOM translates input to commands; render synchronizes labels, progress and disabled states.
- * Own no clock or independent position; time-related controls are disabled for static documents.
+ * Own no clock or independent position; Time-related controls are disabled for static documents.
  */
 export class PlayerControls {
     element;
     play;
+    loop;
     previous;
     next;
     progress;
@@ -16,6 +19,9 @@ export class PlayerControls {
         this.element = owner.createElement("div");
         this.element.className = "flowsvg-controls";
         this.play = createButton(owner, "Play", actions.toggle);
+        this.play.className = "flowsvg-play-toggle";
+        this.loop = createButton(owner, "Loop", actions.toggleLoop);
+        this.loop.className = "flowsvg-loop-toggle";
         this.previous = createButton(owner, "Previous step", () => actions.step(-1));
         this.next = createButton(owner, "Next step", () => actions.step(1));
         this.progress = owner.createElement("input");
@@ -24,39 +30,36 @@ export class PlayerControls {
         this.progress.step = "any";
         this.progress.setAttribute("aria-label", "Progress");
         this.progress.addEventListener("input", () => actions.seek(Number(this.progress.value)));
-        this.scene = createSelect(owner, "Scene");
-        this.scene.addEventListener("change", () => {
-            const choice = this.sceneChoices?.find((scene) => scene.id === this.scene.value);
+        this.scene = new SelectControl(owner, "Scene", (value) => {
+            const choice = this.sceneChoices?.find((scene) => scene.id === value);
             if (choice)
                 actions.seek(choice.startMs);
         });
-        this.speed = createSelect(owner, "Speed");
-        this.speed.addEventListener("change", () => actions.setSpeed(Number(this.speed.value)));
-        this.element.append(this.previous, this.play, this.next, this.progress, this.scene, this.speed);
+        this.speed = new SelectControl(owner, "Speed", (value) => actions.setSpeed(Number(value)));
+        this.element.append(this.previous, this.play, this.next, this.progress, this.scene.element, this.speed.element, this.loop);
     }
-    /** Update existing controls; scene choices change by reference and custom speeds are added as options. */
+    /** Update existing controls; custom speeds join the default choices without changing committed state. */
     render(state) {
         const isStatic = state.totalDuration === 0;
         this.play.textContent = state.playing ? "Pause" : "Play";
         this.play.setAttribute("aria-label", this.play.textContent);
-        this.play.disabled = isStatic || (!state.playing && state.timeMs >= state.totalDuration);
+        this.play.disabled = isStatic || (!state.playing && !state.loop && state.timeMs >= state.totalDuration);
+        this.loop.setAttribute("aria-pressed", String(state.loop));
+        this.loop.disabled = isStatic;
         this.previous.disabled = isStatic || state.timeMs <= 0;
         this.next.disabled = isStatic || state.timeMs >= state.totalDuration;
         this.progress.disabled = isStatic;
         this.progress.max = String(state.totalDuration);
         this.progress.value = String(state.timeMs);
-        this.scene.disabled = isStatic;
-        this.speed.disabled = isStatic;
-        if (this.sceneChoices !== state.scenes) {
-            this.sceneChoices = state.scenes;
-            this.scene.replaceChildren(...state.scenes.map((scene) => createOption(this.scene.ownerDocument, scene.id, scene.label)));
-        }
-        this.scene.value = state.sceneId ?? "";
+        this.sceneChoices = state.scenes;
+        this.scene.render(state.scenes.map((scene) => ({ value: scene.id, label: scene.label })), state.sceneId ?? "", isStatic);
         const speeds = [...new Set([...DEFAULT_SPEEDS, state.speed])].sort((left, right) => left - right);
-        if (!Array.from(this.speed.options).some((option) => Number(option.value) === state.speed)) {
-            this.speed.replaceChildren(...speeds.map((speed) => createOption(this.speed.ownerDocument, String(speed), `${speed}×`)));
-        }
-        this.speed.value = String(state.speed);
+        this.speed.render(speeds.map((speed) => ({ value: String(speed), label: `${speed}×` })), String(state.speed), isStatic);
+    }
+    /** Release menu listeners before the player removes its DOM. */
+    destroy() {
+        this.scene.destroy();
+        this.speed.destroy();
     }
 }
 function createButton(owner, label, click) {
@@ -67,14 +70,3 @@ function createButton(owner, label, click) {
     button.addEventListener("click", click);
     return button;
 }
-function createSelect(owner, label) {
-    const select = owner.createElement("select");
-    select.setAttribute("aria-label", label);
-    return select;
-}
-function createOption(owner, value, label) {
-    const option = owner.createElement("option");
-    option.value = value;
-    option.textContent = label;
-    return option;
-}

package/dist/browser/export-controls.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Optional player GIF UI. One task owns its input, abort signal and download resources independently of playback.
+ * The browser exporter stays behind a dynamic import; portable builds replace only that import with an inline bridge.
+ */
+import type { DiagramDocument, ThemeName } from "../core/model.js";
+interface ExportInput {
+    document: DiagramDocument;
+    theme: ThemeName;
+}
+/** Own the visible export state and one cancellable task; destroy silences asynchronous results and releases downloads. */
+export declare class GifExportControls {
+    private readonly owner;
+    private readonly captureInput;
+    readonly element: HTMLSpanElement;
+    private readonly startButton;
+    private readonly cancelButton;
+    private readonly status;
+    private readonly progress;
+    private task;
+    private destroyed;
+    private readonly downloadUrls;
+    constructor(owner: Document, captureInput: () => ExportInput);
+    destroy(): void;
+    /** Reserve the slot and capture input before loading code so repeated clicks and document loads cannot race the import. */
+    private start;
+    private cancel;
+    private run;
+    private isActive;
+    private renderProgress;
+    private download;
+}
+export {};