@projektemacher/storymapjs 0.10.6 → 0.10.8

package/src/animation/tween.ts

@@ -0,0 +1,186 @@
+import type { AnimateOptions, AnimationHandle } from "../types";
+
+/**
+ * A ~60 line Web Animations API tween, replacing the `morpheus` dependency.
+ *
+ * Why: morpheus was 4.3% of the shipped bundle (an inlined UMD build, ~37 kB
+ * minified) and shipped no types, so `src/animation/morpheus.d.ts` was a
+ * hand-maintained 41-line stub describing a surface the viewer barely used.
+ * The whole requirement is: animate `left`/`top`/`height`/`opacity` on one
+ * element, then `stop()` it. The platform does that natively.
+ *
+ * The shape deliberately matches the old call sites
+ * (`Animate(element, {left, top, height, opacity, duration, easing, complete})`
+ * returning `{stop()}`), so nothing above this file had to change.
+ */
+
+/**
+ * Properties whose values are plain numbers, not lengths. Appending "px" to
+ * these produces an invalid keyframe — `opacity: "0px"` is rejected by the
+ * platform and the animation silently does not run.
+ */
+const UNITLESS = new Set(["opacity", "zIndex", "flexGrow", "flexShrink", "order", "lineHeight"]);
+
+/** Normalise a target value for a keyframe, adding a unit only where needed. */
+function toKeyframeValue(property: string, value: string | number): string {
+    if (typeof value === "number") {
+        return UNITLESS.has(property) ? String(value) : value + "px";
+    }
+    // percentages and other units pass through to the platform unchanged
+    return value;
+}
+
+export default function Animate(
+    element: HTMLElement | HTMLElement[] | NodeListOf<HTMLElement>,
+    options: AnimateOptions,
+): AnimationHandle {
+    const elements =
+        element instanceof HTMLElement ? [element] : Array.from(element as ArrayLike<HTMLElement>);
+
+    // The properties to tween are every key except the lifecycle options.
+    const LIFECYCLE = new Set(["duration", "easing", "complete", "delay", "bezier"]);
+    const properties: Array<[string, string]> = [];
+    for (const [name, value] of Object.entries(options)) {
+        if (LIFECYCLE.has(name) || value === undefined || value === null) {
+            continue;
+        }
+        properties.push([name, toKeyframeValue(name, value as string | number)]);
+    }
+
+    const from: Keyframe = {};
+    const to: Keyframe = {};
+    for (const [name, value] of properties) {
+        from[name] = readCurrentValue(elements[0], name);
+        to[name] = value;
+    }
+
+    const duration = (options.duration as number) ?? 1000;
+    // `easing` is a function from src/animation/easings.ts; see cssEasing().
+    const easing = cssEasing(options.easing);
+    const complete = options.complete as (() => void) | undefined;
+
+    // No Web Animations API (jsdom, an ancient engine, or a host that has
+    // disabled it): apply the end state immediately. Every caller treats the
+    // result the same way it treats a completed animation, so this degrades
+    // to an instant transition rather than a broken one.
+    if (typeof elements[0]?.animate !== "function") {
+        for (const el of elements) {
+            for (const [name, value] of properties) {
+                el.style.setProperty(name, value);
+            }
+        }
+        complete?.();
+        return { stop: () => {} };
+    }
+
+    const animations: Animation[] = [];
+    for (const el of elements) {
+        const animation = el.animate([from, to], {
+            duration: duration,
+            easing: easing,
+            fill: "forwards",
+        });
+        animations.push(animation);
+    }
+
+    const handle: AnimationHandle = {
+        stop: (jump?: boolean) => {
+            for (const animation of animations) {
+                // `commitStyles()` is the important part: it folds the current
+                // animated value into the element's inline style *before* the
+                // animation is torn down. Without it, cancelling snaps the
+                // element back to whatever it was before the animation — and
+                // three call sites depend on the post-stop value: the slider
+                // writes `style.left` directly on its fast path, SlideNav
+                // resets left/right to "" when it completes, and Swipable
+                // restarts momentum from the current position.
+                try {
+                    animation.commitStyles();
+                } catch {
+                    // an animation that never started (or already finished)
+                    // has nothing to commit
+                }
+                animation.cancel();
+            }
+            // `stop(true)` used to mean "jump to the end"; keep that meaning
+            if (jump) {
+                for (const animation of animations) {
+                    animation.finish();
+                }
+            }
+        },
+    };
+
+    if (complete) {
+        const first = animations[0];
+        if (first) {
+            first.addEventListener("finish", () => complete());
+        } else {
+            complete();
+        }
+    }
+
+    return handle;
+}
+
+/** The element's current inline or computed value for a property. */
+function readCurrentValue(element: HTMLElement | undefined, property: string): string {
+    if (!element) {
+        return "0px";
+    }
+    const inline = element.style.getPropertyValue(property);
+    if (inline) {
+        return inline;
+    }
+    const computed = window.getComputedStyle(element).getPropertyValue(property);
+    return computed || "0px";
+}
+
+/**
+ * Translate the caller's easing into something `element.animate()` accepts.
+ *
+ * The call sites pass a *sampled* easing function from
+ * src/animation/easings.ts (a quintic, an exponential, a cubic-bezier), and
+ * CSS can only name a handful of curves. Dropping to the platform default
+ * would visibly change the slider glide, so instead the function is sampled
+ * into a CSS `linear()` easing — which reproduces the curve exactly.
+ *
+ * `linear()` is not universally supported, so it is feature-detected; where it
+ * is missing the platform default applies. That is a visual regression, not a
+ * functional one, which is why it is a graceful fallback rather than an error.
+ */
+function cssEasing(easing: unknown): string {
+    if (typeof easing === "string") {
+        return easing;
+    }
+    if (typeof easing === "function" && supportsLinearEasing()) {
+        const stops: string[] = [];
+        for (let i = 0; i <= EASING_SAMPLES; i++) {
+            const t = i / EASING_SAMPLES;
+            const value = (easing as (t: number) => number)(t);
+            stops.push(String(Number(value.toFixed(4))));
+        }
+        return `linear(${stops.join(",")})`;
+    }
+    return "ease";
+}
+
+/** Enough samples to be visually indistinguishable from the source curve. */
+const EASING_SAMPLES = 24;
+
+let _linearEasing: boolean | undefined;
+
+/** Cached `CSS.supports` probe for the linear() easing function. */
+function supportsLinearEasing(): boolean {
+    if (_linearEasing === undefined) {
+        try {
+            _linearEasing =
+                typeof CSS !== "undefined" &&
+                typeof CSS.supports === "function" &&
+                CSS.supports("animation-timing-function", "linear(0, 0.5, 1)");
+        } catch {
+            _linearEasing = false;
+        }
+    }
+    return _linearEasing;
+}

package/src/core/Browser.ts

@@ -0,0 +1,20 @@
+/*
+ * Browser - the only feature detection StoryMapJS still needs.
+ * 2022+ browsers only: no vendor sniffing, no legacy engine flags.
+ */
+
+/** Touch-capable pointer - drives the swipe gesture and the mobile layouts. */
+const touch = "ontouchstart" in window || navigator.maxTouchPoints > 0;
+
+/** Coarse-pointer devices (phones, tablets) - drives the mobile/skinny layouts. */
+const mobile = window.matchMedia?.("(pointer: coarse)").matches ?? false;
+
+export const Browser = {
+    touch: touch,
+    mobile: mobile,
+    orientation: function (): "landscape" | "portrait" {
+        const w = window.innerWidth;
+        const h = window.innerHeight;
+        return w > h ? "landscape" : "portrait";
+    },
+};

package/src/core/Load.ts

@@ -0,0 +1,232 @@
+/*	Load
+    Loads external Javascript and CSS using plain DOM element injection.
+    Modern browsers preserve execution order for dynamically inserted
+    scripts with async=false, so no queueing machinery is needed.
+================================================== */
+
+export interface LoadOptions {
+    /** Abort the load (removes the element, rejects the promise). */
+    signal?: AbortSignal;
+}
+
+function loadElement(
+    tag: "script" | "link",
+    attrs: Record<string, string>,
+    options?: LoadOptions,
+): Promise<void> {
+    return new Promise((resolve, reject) => {
+        if (options?.signal?.aborted) {
+            reject(new DOMException("Load aborted", "AbortError"));
+            return;
+        }
+        const node = document.createElement(tag);
+        for (const attr in attrs) {
+            if (Object.hasOwn(attrs, attr)) {
+                node.setAttribute(attr, attrs[attr]);
+            }
+        }
+        if (tag === "script") {
+            (node as HTMLScriptElement).async = false;
+        }
+        const cleanup = () => {
+            node.onload = null;
+            node.onerror = null;
+            options?.signal?.removeEventListener("abort", onAbort);
+        };
+        const onAbort = () => {
+            cleanup();
+            node.remove();
+            reject(new DOMException("Load aborted", "AbortError"));
+        };
+        node.onload = () => {
+            cleanup();
+            resolve();
+        };
+        node.onerror = () => {
+            cleanup();
+            reject(new Error(`Failed to load ${attrs.src ?? attrs.href}`));
+        };
+        options?.signal?.addEventListener("abort", onAbort, { once: true });
+        document.head.appendChild(node);
+    });
+}
+
+/**
+ * In-flight and completed loads, keyed by URL.
+ *
+ * A page can hold more than one viewer, and they all need the same third-party
+ * scripts (the YouTube and SoundCloud APIs) and the same font stylesheet.
+ * Injecting those once per viewer re-defines `window.YT`/`window.SC` and
+ * re-applies the theme, so the second viewer awaits the first load instead.
+ *
+ * This is per bundle copy: two separately bundled copies of StoryMapJS on one
+ * page each keep their own map and would still both inject.
+ */
+const sharedLoads = new Map<string, Promise<void>>();
+
+/** Reject `promise` early if `signal` aborts, without touching the load. */
+function withAbort(promise: Promise<void>, signal: AbortSignal): Promise<void> {
+    if (signal.aborted) {
+        return Promise.reject(new DOMException("Load aborted", "AbortError"));
+    }
+    return new Promise<void>((resolve, reject) => {
+        const onAbort = () => {
+            reject(new DOMException("Load aborted", "AbortError"));
+        };
+        signal.addEventListener("abort", onAbort, { once: true });
+        promise.then(resolve, reject).then(() => {
+            signal.removeEventListener("abort", onAbort);
+        });
+    });
+}
+
+function loadOnce(url: string, load: () => Promise<void>, options?: LoadOptions): Promise<void> {
+    let shared = sharedLoads.get(url);
+    if (!shared) {
+        shared = load().catch((err: unknown) => {
+            // never cache a failure: the next viewer should get a fresh try
+            sharedLoads.delete(url);
+            throw err;
+        });
+        sharedLoads.set(url, shared);
+    }
+    if (!options?.signal) {
+        return shared;
+    }
+    // A viewer aborts its own media loads when it is torn down. That must
+    // reject this caller's promise without cancelling the load a sibling
+    // viewer is still waiting on, so the shared load gets no signal at all.
+    return withAbort(shared, options.signal);
+}
+
+/**
+ * Append a script to the document head.
+ *
+ * Concurrent and repeat requests for the same URL share one injected script.
+ *
+ * @param url - The script URL.
+ * @param options - Optional AbortSignal to cancel an in-flight load.
+ * @returns Resolves when the script has loaded, rejects on error or abort.
+ */
+function loadJS(url: string, options?: LoadOptions): Promise<void> {
+    return loadOnce(url, () => loadElement("script", { src: url }), options);
+}
+
+/**
+ * Append one stylesheet to the document head.
+ *
+ * Concurrent and repeat requests for the same URL share one `<link>`.
+ *
+ * @param url - The stylesheet URL.
+ * @param options - Optional AbortSignal to cancel an in-flight load.
+ * @returns Resolves when the stylesheet has loaded, rejects on error or abort.
+ */
+function loadCSS(url: string, options?: LoadOptions): Promise<void> {
+    return loadOnce(url, () => loadElement("link", { href: url, rel: "stylesheet" }), options);
+}
+
+export interface JSONPOptions extends LoadOptions {
+    /** Milliseconds to wait for the callback before rejecting (default 15000). */
+    timeout?: number;
+}
+
+let globalNameCounter = 0;
+
+/**
+ * Claim a free global callback slot: names derived from content (e.g. a
+ * Wikipedia article title) are not unique per request, and concurrent loads
+ * sharing a name would clobber each other's handler — delivering payloads to
+ * the wrong promise and leaving the loser's script calling a deleted global
+ * (Uncaught ReferenceError).
+ *
+ * @param base - The preferred global function name.
+ * @returns `base` when free, otherwise `base` with a numeric suffix.
+ */
+function uniqueGlobalName(base: string): string {
+    const globals = window as unknown as Record<string, unknown>;
+    if (!Object.hasOwn(globals, base)) {
+        return base;
+    }
+    let candidate: string;
+    do {
+        globalNameCounter += 1;
+        candidate = `${base}_${globalNameCounter}`;
+    } while (Object.hasOwn(globals, candidate));
+    return candidate;
+}
+
+/**
+ * Load a JSONP endpoint: injects a script that calls a global function with
+ * its payload, and resolves with that payload. The global is removed and the
+ * script element detached once settled.
+ *
+ * @param url - The full JSONP URL (must include the callback parameter).
+ * @param callbackName - The global function name the endpoint will invoke.
+ *   Must be claimed via uniqueGlobalName when concurrent loads may share it.
+ * @param options - Optional AbortSignal and timeout.
+ * @returns Resolves with the JSONP payload, rejects on error, abort or timeout.
+ */
+function loadJSONP<T>(url: string, callbackName: string, options?: JSONPOptions): Promise<T> {
+    return new Promise((resolve, reject) => {
+        if (options?.signal?.aborted) {
+            reject(new DOMException("Load aborted", "AbortError"));
+            return;
+        }
+        const globals = window as unknown as Record<string, unknown>;
+        const script = document.createElement("script");
+        let settled = false;
+        const cleanup = () => {
+            settled = true;
+            clearTimeout(timer);
+            script.remove();
+            if (globals[callbackName] === onCallback) {
+                delete globals[callbackName];
+            }
+            options?.signal?.removeEventListener("abort", onAbort);
+        };
+        // Abandon without deleting: an already-fetched script may still
+        // execute afterwards, and calling a deleted global throws an
+        // Uncaught ReferenceError. The self-deleting stub swallows it.
+        const abandon = () => {
+            settled = true;
+            clearTimeout(timer);
+            script.remove();
+            if (globals[callbackName] === onCallback) {
+                globals[callbackName] = () => {
+                    delete globals[callbackName];
+                };
+            }
+            options?.signal?.removeEventListener("abort", onAbort);
+        };
+        const onAbort = () => {
+            if (!settled) {
+                abandon();
+                reject(new DOMException("Load aborted", "AbortError"));
+            }
+        };
+        const onCallback = (data: T) => {
+            if (!settled) {
+                cleanup();
+                resolve(data);
+            }
+        };
+        const timer = setTimeout(() => {
+            if (!settled) {
+                abandon();
+                reject(new Error(`JSONP request timed out: ${url}`));
+            }
+        }, options?.timeout ?? 15000);
+        globals[callbackName] = onCallback;
+        script.onerror = () => {
+            if (!settled) {
+                abandon();
+                reject(new Error(`Failed to load ${url}`));
+            }
+        };
+        options?.signal?.addEventListener("abort", onAbort, { once: true });
+        script.src = url;
+        document.body.appendChild(script);
+    });
+}
+
+export { loadJS, loadCSS, loadJSONP, uniqueGlobalName };