flowsvg 0.0.0-stage → 0.1.0

package/dist/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.js";
+import { createPlayer } from "./browser.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/package.json

@@ -1,6 +1,89 @@
 {
   "name": "flowsvg",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Declarative SVG player for logic and architecture diagrams, with scenes, beats, static export and browser framework adapters.",
+  "type": "module",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/yokingma/FlowSVG.git",
+    "directory": "packages/flowsvg"
+  },
+  "homepage": "https://github.com/yokingma/FlowSVG#readme",
+  "bugs": {
+    "url": "https://github.com/yokingma/FlowSVG/issues"
+  },
+  "keywords": ["svg", "diagram", "architecture", "animation", "timeline", "web-component", "react", "vue"],
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./styles.css": "./dist/styles.css",
+    "./browser": {
+      "types": "./dist/browser.d.ts",
+      "import": "./dist/browser.js"
+    },
+    "./web-component": {
+      "types": "./dist/web-component.d.ts",
+      "import": "./dist/web-component.js"
+    },
+    "./element": {
+      "types": "./dist/web-component.d.ts",
+      "import": "./dist/web-component.js"
+    },
+    "./react": {
+      "types": "./dist/react.d.ts",
+      "import": "./dist/react.js"
+    },
+    "./vue": {
+      "types": "./dist/vue.d.ts",
+      "import": "./dist/vue.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "README.zh-CN.md",
+    "CHANGELOG.md",
+    "PATTERNS.md",
+    "LICENSE"
+  ],
+  "sideEffects": ["./dist/styles.css"],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "rm -rf dist && tsc -p tsconfig.core.json && tsc -p tsconfig.browser.json && tsc -p tsconfig.react.json && tsc -p tsconfig.vue.json && cp src/styles.css dist/styles.css",
+    "typecheck": "tsc -p tsconfig.core.json --noEmit && tsc -p tsconfig.browser.json --noEmit && tsc -p tsconfig.react.json --noEmit && tsc -p tsconfig.vue.json --noEmit",
+    "test": "vitest run",
+    "prepack": "pnpm --silent build",
+    "prepublishOnly": "pnpm typecheck && pnpm test",
+    "release:verify": "node ../../scripts/verify-release.mjs"
+  },
+  "devDependencies": {
+    "@types/react": "^19.3.0",
+    "@types/react-dom": "^19.3.0",
+    "jsdom": "^26.1.0",
+    "react": "^19.3.0",
+    "react-dom": "^19.3.0",
+    "vue": "3.5.0"
+  },
+  "peerDependencies": {
+    "react": ">=18.0.0",
+    "vue": ">=3.5.0"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    },
+    "vue": {
+      "optional": true
+    }
+  }
+}