flowsvg 0.1.0 → 0.1.1

package/dist/browser.js

@@ -1,353 +1,2 @@
-/**
- * Browser player: own the clock, DOM, controls and input, forwarding time and visual options to the core.
- * Importing does not access the DOM; createPlayer allocates mount resources and destroy releases them.
- */
-import { paintContentHighlight } from "./node-content-paint.js";
-import { updateSvgDom } from "./svg-dom.js";
-import { attachPlayerLifecycle } from "./player-lifecycle.js";
-import { observeKeyboard, observeReducedMotion } from "./player-accessibility.js";
-import { PlayerControls } from "./player-controls.js";
-import { resolveThemePalette } from "./theme.js";
-import { createDiagram } from "./core.js";
-/**
- * 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 function createPlayer(host, document, options = {}) {
-    const initial = createDiagram(document);
-    return new BrowserPlayer(host, initial, document, options);
-}
-/**
- * Own one compiled Diagram and advance time with RAF; core results drive the canvas, caption and controls.
- * Retain cleanup callbacks for lifecycle, media preferences and pointer listeners, releasing them on destroy.
- */
-class BrowserPlayer {
-    element;
-    diagram;
-    options;
-    timeMs = 0;
-    speed = 1;
-    playing = false;
-    destroyed = false;
-    frameHandle;
-    lastTimestamp;
-    frame;
-    canvas;
-    caption;
-    controls;
-    scenes;
-    beatStarts;
-    detachLifecycle;
-    stopKeyboard;
-    stopMotion;
-    stopPointer;
-    themeOverride;
-    pointerPosition;
-    hoveredHit = null;
-    constructor(host, diagram, document, options) {
-        this.element = host;
-        this.diagram = diagram;
-        this.beatStarts = collectBeatStarts(document);
-        this.scenes = collectScenes(document);
-        const owner = host.ownerDocument;
-        const motion = observeReducedMotion(owner, options.reducedMotion, (reducedMotion) => {
-            if (this.destroyed)
-                return;
-            this.options = { ...this.options, reducedMotion };
-            this.updateFrame();
-        });
-        this.stopMotion = motion.cleanup;
-        this.themeOverride = options.theme;
-        this.options = { ...options, theme: options.theme ?? document.theme ?? "light", reducedMotion: motion.value };
-        this.frame = diagram.evaluateAt(0, this.options);
-        this.canvas = owner.createElement("div");
-        this.canvas.className = "flowsvg-canvas";
-        this.stopKeyboard = observeKeyboard(this.canvas, { toggle: this.togglePlayback, step: (direction) => this.step(direction) });
-        this.caption = owner.createElement("p");
-        this.caption.className = "flowsvg-caption";
-        this.caption.setAttribute("aria-live", "polite");
-        this.caption.setAttribute("aria-atomic", "true");
-        if (options.controls !== false) {
-            this.controls = new PlayerControls(owner, {
-                toggle: this.togglePlayback,
-                step: (direction) => this.step(direction),
-                seek: (timeMs) => this.seek(timeMs),
-                setSpeed: (speed) => this.setSpeed(speed)
-            });
-        }
-        host.replaceChildren(this.canvas, this.caption, ...(this.controls ? [this.controls.element] : []));
-        this.render();
-        this.stopPointer = observePointer(this.canvas, {
-            move: (event) => this.handlePointer("hover", event),
-            leave: () => this.clearPointer(),
-            click: (event) => this.handlePointer("click", event)
-        });
-        this.detachLifecycle = attachPlayerLifecycle(host, this.canvas, () => this.pause());
-    }
-    play() {
-        if (this.destroyed || this.playing || this.element.ownerDocument.visibilityState === "hidden" || this.diagram.totalDuration <= this.timeMs)
-            return;
-        this.playing = true;
-        this.lastTimestamp = undefined;
-        this.renderControls();
-        this.emit("playstatechange");
-        this.scheduleFrame();
-    }
-    pause() {
-        if (this.destroyed || !this.playing)
-            return;
-        this.playing = false;
-        if (this.frameHandle !== undefined)
-            cancelAnimationFrame(this.frameHandle);
-        this.frameHandle = undefined;
-        this.renderControls();
-        this.emit("playstatechange");
-    }
-    seek(timeMs) {
-        if (this.destroyed)
-            return;
-        this.timeMs = clamp(timeMs, 0, this.diagram.totalDuration);
-        this.lastTimestamp = undefined;
-        this.updateFrame();
-        if (this.timeMs >= this.diagram.totalDuration)
-            this.pause();
-    }
-    step(direction) {
-        if (this.destroyed)
-            return;
-        this.pause();
-        const starts = direction > 0 ? this.beatStarts : [...this.beatStarts].reverse();
-        const target = starts.find((start) => direction > 0 ? start > this.timeMs : start < this.timeMs);
-        this.seek(target ?? (direction > 0 ? this.diagram.totalDuration : 0));
-    }
-    setSpeed(speed) {
-        if (this.destroyed || !Number.isFinite(speed) || speed <= 0)
-            return;
-        this.speed = speed;
-        this.renderControls();
-    }
-    load(document) {
-        if (this.destroyed)
-            return;
-        try {
-            // Keep the old player intact until compilation succeeds so invalid loads do not interrupt valid playback.
-            const diagram = createDiagram(document);
-            this.pause();
-            if (this.destroyed)
-                return;
-            this.diagram = diagram;
-            this.options = { ...this.options, theme: this.themeOverride ?? document.theme ?? "light" };
-            this.beatStarts = collectBeatStarts(document);
-            this.scenes = collectScenes(document);
-            this.timeMs = 0;
-            // A replacement document owns new interaction targets, even when it reuses the same node IDs.
-            this.pointerPosition = undefined;
-            this.updateFrame();
-        }
-        catch (error) {
-            this.emit("error", { ...this.state(), error: error instanceof Error ? error : new Error(String(error)) });
-        }
-    }
-    getState() {
-        return this.state();
-    }
-    destroy() {
-        if (this.destroyed)
-            return;
-        // Block dispatch/rescheduling before releasing resources; do not call pause, which would emit an event.
-        this.destroyed = true;
-        this.playing = false;
-        if (this.frameHandle !== undefined)
-            cancelAnimationFrame(this.frameHandle);
-        this.frameHandle = undefined;
-        this.lastTimestamp = undefined;
-        this.detachLifecycle();
-        this.stopKeyboard();
-        this.stopMotion();
-        this.stopPointer();
-        this.pointerPosition = undefined;
-        this.hoveredHit = null;
-        this.element.replaceChildren();
-    }
-    /** The first RAF establishes a baseline; seek clears it so elapsed time from the old position is not reused. */
-    tick = (timestamp) => {
-        if (!this.playing || this.destroyed)
-            return;
-        this.frameHandle = undefined;
-        const previous = this.lastTimestamp ?? timestamp;
-        this.lastTimestamp = timestamp;
-        this.timeMs += (timestamp - previous) * this.speed;
-        if (this.timeMs >= this.diagram.totalDuration) {
-            this.timeMs = this.diagram.totalDuration;
-            this.updateFrame();
-            this.pause();
-            return;
-        }
-        this.updateFrame();
-        this.scheduleFrame();
-    };
-    /** Event listeners may restart playback synchronously; never queue a second frame owned by the same player. */
-    scheduleFrame() {
-        if (this.destroyed || !this.playing || this.frameHandle !== undefined)
-            return;
-        this.frameHandle = requestAnimationFrame(this.tick);
-    }
-    /** Update the frame before notifying consumers so listeners observe the rendered position. */
-    updateFrame() {
-        const previousBeat = this.frame.beatId;
-        const previousScene = this.frame.sceneId;
-        this.frame = this.diagram.evaluateAt(this.timeMs, this.options);
-        this.render();
-        if (previousBeat !== this.frame.beatId || previousScene !== this.frame.sceneId)
-            this.emit("stepchange");
-        this.emit("timeupdate");
-    }
-    togglePlayback = () => {
-        if (this.playing)
-            this.pause();
-        else
-            this.play();
-    };
-    render() {
-        updateSvgDom(this.canvas, this.diagram.renderSvg(this.timeMs, this.options));
-        this.canvas.style.aspectRatio = `${this.frame.camera.width} / ${this.frame.camera.height}`;
-        this.updateHover();
-        this.caption.textContent = this.frame.caption ?? "";
-        this.renderControls();
-    }
-    renderControls() {
-        this.controls?.render({ ...this.state(), sceneId: this.frame.sceneId, scenes: this.scenes });
-    }
-    state() {
-        return { timeMs: this.timeMs, totalDuration: this.diagram.totalDuration, playing: this.playing, speed: this.speed, frame: this.frame };
-    }
-    handlePointer(type, event) {
-        if (this.destroyed)
-            return;
-        if (type === "hover") {
-            this.pointerPosition = { clientX: event.clientX, clientY: event.clientY };
-            updateSvgDom(this.canvas, this.diagram.renderSvg(this.timeMs, this.options));
-            this.updateHover(true);
-            return;
-        }
-        if (type === "click")
-            event.stopPropagation();
-        const point = pointerToDiagramPoint(this.canvas, this.frame.camera, event);
-        const hit = this.diagram.hitTest(this.timeMs, point, this.options);
-        const detail = hit ? { ...hit, point, timeMs: this.timeMs, sceneId: this.frame.sceneId, beatId: this.frame.beatId } : null;
-        this.emit("click", detail);
-        this.emit("objectclick", detail);
-    }
-    /** Re-hit the saved screen position after camera/geometry updates; hover never changes the core hit geometry. */
-    updateHover(emitAlways = false) {
-        const point = this.pointerPosition ? pointerToDiagramPoint(this.canvas, this.frame.camera, this.pointerPosition) : undefined;
-        const hit = point ? this.diagram.hitTest(this.timeMs, point, this.options) : null;
-        if (hit?.type === "node") {
-            const shape = Array.from(this.canvas.querySelectorAll("[data-id]")).find((element) => element.getAttribute("data-id") === hit.id);
-            const color = resolveThemePalette(this.options.theme).highlight;
-            const node = this.frame.nodes.find((candidate) => candidate.id === hit.id);
-            // Border-only hover preserves all current timeline and content paint unless fill feedback is explicitly enabled.
-            if (this.options.hoverFill)
-                shape?.setAttribute("fill", color);
-            shape?.setAttribute("stroke", color);
-            const layout = node?.contentLayout;
-            const content = Array.from(this.canvas.querySelectorAll("[data-content-id]")).find((element) => element.getAttribute("data-content-id") === hit.id);
-            if (this.options.hoverFill && content && layout)
-                paintHoveredContent(content, paintContentHighlight(layout, 1, color));
-        }
-        const changed = hit?.id !== this.hoveredHit?.id || hit?.type !== this.hoveredHit?.type;
-        this.hoveredHit = hit;
-        if (!emitAlways && !changed)
-            return;
-        const detail = hit && point ? { ...hit, point, timeMs: this.timeMs, sceneId: this.frame.sceneId, beatId: this.frame.beatId } : null;
-        this.emit("hover", detail);
-        this.emit("objecthover", detail);
-    }
-    clearPointer() {
-        if (this.destroyed)
-            return;
-        this.pointerPosition = undefined;
-        updateSvgDom(this.canvas, this.diagram.renderSvg(this.timeMs, this.options));
-        this.updateHover(true);
-    }
-    emit(type, detail) {
-        if (!this.destroyed)
-            this.element.dispatchEvent(new CustomEvent(type, { detail: detail === undefined ? this.state() : detail }));
-    }
-}
-/** Apply the shared paint result to current decorative children; no child receives a separate interaction identity. */
-function paintHoveredContent(content, layout) {
-    const tags = content.querySelectorAll("rect");
-    layout.tags.forEach((tag, index) => tags[index]?.setAttribute("fill", tag.fill));
-    const texts = content.querySelectorAll("text");
-    layout.lines.forEach((line, index) => {
-        const text = texts[index];
-        text?.setAttribute("fill", line.color);
-        const spans = text?.querySelectorAll("tspan");
-        line.spans.forEach((span, spanIndex) => spans?.[spanIndex]?.setAttribute("fill", span.color));
-    });
-    const graphs = content.querySelectorAll("[data-content-graph]");
-    layout.graphs?.forEach((graph, index) => {
-        const circles = graphs[index]?.querySelectorAll("circle");
-        const edges = graphs[index]?.querySelectorAll("line");
-        graph.nodes.forEach((node, nodeIndex) => circles?.[nodeIndex]?.setAttribute("fill", node.fill));
-        graph.edges.forEach((edge, edgeIndex) => edges?.[edgeIndex]?.setAttribute("stroke", edge.color));
-    });
-}
-function clamp(value, min, max) {
-    return Number.isFinite(value) ? Math.min(max, Math.max(min, value)) : min;
-}
-function collectBeatStarts(document) {
-    let startMs = 0;
-    return document.scenes.flatMap((scene) => scene.beats.map((beat) => {
-        const start = startMs;
-        startMs += beat.durationMs;
-        return start;
-    }));
-}
-function collectScenes(document) {
-    let startMs = 0;
-    return document.scenes.map((scene) => {
-        const choice = { id: scene.id, label: scene.label, startMs };
-        startMs += scene.beats.reduce((duration, beat) => duration + beat.durationMs, 0);
-        return choice;
-    });
-}
-function observePointer(canvas, handlers) {
-    const onMove = (event) => handlers.move(event);
-    const onLeave = () => handlers.leave();
-    const onClick = (event) => handlers.click(event);
-    canvas.addEventListener("pointermove", onMove);
-    canvas.addEventListener("pointerleave", onLeave);
-    canvas.addEventListener("pointercancel", onLeave);
-    canvas.addEventListener("click", onClick);
-    return () => {
-        canvas.removeEventListener("pointermove", onMove);
-        canvas.removeEventListener("pointerleave", onLeave);
-        canvas.removeEventListener("pointercancel", onLeave);
-        canvas.removeEventListener("click", onClick);
-    };
-}
-/**
- * Prefer the inverse SVG screen transform for scaling/letterboxing; otherwise map the element rectangle to the camera.
- * The rectangle fallback lacks full SVG transform information and is only an approximation.
- */
-function pointerToDiagramPoint(canvas, camera, event) {
-    const svg = canvas.querySelector("svg");
-    const matrix = svg?.getScreenCTM?.();
-    if (matrix) {
-        const inverse = matrix.inverse();
-        return {
-            x: event.clientX * inverse.a + event.clientY * inverse.c + inverse.e,
-            y: event.clientX * inverse.b + event.clientY * inverse.d + inverse.f
-        };
-    }
-    const bounds = svg?.getBoundingClientRect() ?? canvas.getBoundingClientRect();
-    const width = bounds.width || 1;
-    const height = bounds.height || 1;
-    return {
-        x: camera.x + ((event.clientX - bounds.left) / width) * camera.width,
-        y: camera.y + ((event.clientY - bounds.top) / height) * camera.height
-    };
-}
+/** Public browser entry: expose the player contract while keeping its implementation under the browser module. */
+export { createPlayer } from "./browser/player.js";

package/dist/core/color.d.ts

@@ -0,0 +1,3 @@
+/** Pure color interpolation shared by timeline visuals and node-content painting. */
+/** Interpolate validated hexadecimal RGB/RGBA channels; preserve endpoint strings and normalize intermediate colors. */
+export declare function mixColor(source: string, target: string, progress: number): string;

package/dist/core/color.js

@@ -0,0 +1,18 @@
+/** Pure color interpolation shared by timeline visuals and node-content painting. */
+/** Interpolate validated hexadecimal RGB/RGBA channels; preserve endpoint strings and normalize intermediate colors. */
+export function mixColor(source, target, progress) {
+    if (progress === 0)
+        return source;
+    if (progress === 1)
+        return target;
+    const channels = (color) => {
+        const hex = color.slice(1);
+        const expanded = hex.length <= 4 ? [...hex].map((digit) => digit + digit).join("") : hex;
+        return [0, 2, 4, 6].map((offset) => offset < expanded.length ? parseInt(expanded.slice(offset, offset + 2), 16) : 255);
+    };
+    const from = channels(source);
+    const to = channels(target);
+    const values = from.map((value, index) => Math.round(value + (to[index] - value) * progress));
+    const hex = values.map((value) => value.toString(16).padStart(2, "0"));
+    return `#${hex.slice(0, values[3] === 255 ? 3 : 4).join("")}`;
+}

package/dist/core/diagram.d.ts

@@ -0,0 +1,38 @@
+import type { DiagramDocument, EvaluateOptions, HitObject, DiagramPoint, DiagramFrameState } from "./model.js";
+/**
+ * Validate and copy a document, then compile its timeline; later input mutations cannot affect evaluation.
+ * @throws {DiagramValidationError} If document structure, values or references are invalid.
+ */
+export declare function createDiagram(input: DiagramDocument): Diagram;
+/** One-shot static SVG export; use createDiagram to reuse compilation across repeated evaluations or exports. */
+export declare function renderSvg(document: DiagramDocument, timeMs?: number, options?: EvaluateOptions): string;
+/** Compiled diagram independent of the DOM, network and clock; each query evaluates from its time and options. */
+export interface Diagram {
+    /** Global timeline duration in milliseconds; zero for static diagrams. */
+    readonly totalDuration: number;
+    /**
+     * Evaluate a frame; finite times clamp to [0, totalDuration], and non-finite times become zero.
+     * Beat intervals include their start and exclude their end; totalDuration returns the completed final beat.
+     */
+    evaluateAt(timeMs: number, options?: EvaluateOptions): DiagramFrameState;
+    /** Serialize the same frame as self-contained static SVG with escaped text and resolved colors, without controls. */
+    renderSvg(timeMs?: number, options?: EvaluateOptions): string;
+    /**
+     * Hit-test document coordinates in paint order: ordinary nodes, then edges, then group backgrounds.
+     * Objects within each layer are searched in reverse document order.
+     * Node hits include their visible label area. Hidden/zero-opacity objects are excluded.
+     * Return null for no hit or non-finite coordinates.
+     */
+    hitTest(timeMs: number, point: DiagramPoint, options?: EvaluateOptions): HitObject | null;
+}
+interface Typography {
+    fontSize: number;
+    lineHeight: number;
+    charWidth: number;
+}
+/**
+ * Estimate wrapping with fixed code-point widths, preserving explicit empty lines and preferring spaces as breaks.
+ * No font/DOM measurement is used; this handles width only, while frame evaluation reports height overflow.
+ */
+export declare function wrapText(label: string, maxWidth: number, typography?: Typography): string[];
+export {};