flowsvg 0.1.0 → 0.1.1

package/dist/adapters/web-component.js

@@ -0,0 +1,396 @@
+/**
+ * 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 the four 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"
+    ];
+    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();
+    }
+    /** 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);
+    }
+    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":
+                this.rebuildForOptions();
+                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;
+    }
+    /** 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", "error"]) {
+            const listener = (event) => {
+                const source = event;
+                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,
+            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/browser/player.d.ts

@@ -0,0 +1,69 @@
+import type { DiagramDocument, DiagramFrameState, DiagramPoint, EvaluateOptions, HitObject, ThemeName } from "../core/model.js";
+/** Creation options: controls default on, motion follows browser preferences, and theme falls back to the document/light. */
+export interface PlayerOptions extends EvaluateOptions {
+    controls?: boolean;
+    /** Hover highlights borders by default; true also paints the background and adjusts content ink. Applies to groups too. */
+    hoverFill?: boolean;
+}
+/** Player snapshot: times are milliseconds, speed is a positive multiplier, and frame is the core result without hover. */
+export interface PlayerState {
+    timeMs: number;
+    totalDuration: number;
+    playing: boolean;
+    speed: number;
+    frame: DiagramFrameState;
+}
+/** Object interaction detail; point uses document coordinates and time/beat IDs reflect the event-time player state. */
+export interface PlayerInteractionDetail extends HitObject {
+    point: DiagramPoint;
+    timeMs: number;
+    sceneId: string | null;
+    beatId: string | null;
+}
+/** Imperative browser player; creation/successful load pause at zero, and controls become inert after destruction. */
+export interface FlowPlayer {
+    /** The supplied host, also used as the CustomEvent dispatch target. */
+    readonly element: HTMLElement;
+    /** Play from the current position; do not start for static diagrams, at the end, or while the page is hidden. */
+    play(): void;
+    /** Stop time advancement, retaining the current frame. */
+    pause(): void;
+    /** Seek to a clamped millisecond time; preserve playback except at the end. Non-finite times become zero. */
+    seek(timeMs: number): void;
+    /** Pause and jump to the adjacent start; backward goes to this beat's start from inside it, or the preceding start. */
+    step(direction: 1 | -1): void;
+    /** Set a finite positive speed multiplier; ignore invalid values. */
+    setSpeed(speed: number): void;
+    /** Compile before replacing; reset/pause at zero on success, or emit error and retain the old document/time/playback. */
+    load(document: DiagramDocument): void;
+    /** Read current player state; the last state remains readable after destruction. */
+    getState(): PlayerState;
+    /** Silently and idempotently release frames/listeners/host content; no further player events are dispatched. */
+    destroy(): void;
+}
+/** Retained state and original load error; DiagramValidationError.issues provides field paths for validation failures. */
+export interface PlayerErrorDetail extends PlayerState {
+    error: Error;
+}
+/**
+ * Host events and their detail types. Frame updates emit stepchange when needed, then timeupdate.
+ * hover/click use null for no hit; objecthover/objectclick report the same interactions under alternate names.
+ * Hover also changes when a frame update changes the object under a stationary pointer.
+ */
+export type PlayerEventMap = {
+    stepchange: CustomEvent<PlayerState>;
+    timeupdate: CustomEvent<PlayerState>;
+    playstatechange: CustomEvent<PlayerState>;
+    error: CustomEvent<PlayerErrorDetail>;
+    hover: CustomEvent<PlayerInteractionDetail | null>;
+    click: CustomEvent<PlayerInteractionDetail | null>;
+    objecthover: CustomEvent<PlayerInteractionDetail | null>;
+    objectclick: CustomEvent<PlayerInteractionDetail | null>;
+};
+/**
+ * Mount a player using the host document and observe browser motion preferences unless explicitly overridden.
+ * Replaces host children; destroy an existing player before replacing it on the same host.
+ * @throws {DiagramValidationError} For an invalid initial document, before an instance exists to emit error.
+ */
+export declare function createPlayer(host: HTMLElement, document: DiagramDocument, options?: PlayerOptions): FlowPlayer;
+export type { ThemeName };