@projektemacher/storymapjs 0.10.6 → 0.10.8

package/src/media/types/HtmlMedia.ts

@@ -0,0 +1,167 @@
+import { Media } from "../Media";
+import Dom from "../../dom/Dom";
+import { Language } from "../../language/Language";
+
+/*	Media.HtmlMedia
+	Shared implementation for the <audio> and <video> types. The two differ
+	only in the element name, the CSS class, the fallback text and the
+	file extension -> MIME map, so all of that is data here.
+================================================== */
+
+/** The element this media type plays. */
+export type HtmlMediaKind = "audio" | "video";
+
+interface HtmlMediaSpec {
+    /** The element to create. */
+    kind: HtmlMediaKind;
+    /** File extension (lowercase, no dot) -> MIME subtype. */
+    extensions: Record<string, string>;
+}
+
+const AUDIO_DEFAULT: HtmlMediaSpec = { kind: "audio", extensions: { mp3: "mpeg" } };
+
+/** MIME subtype for a file extension, or "" when it is not recognised. */
+function mimeSubtype(ext: string, spec: HtmlMediaSpec): string {
+    return spec.extensions[ext.toLowerCase()] ?? "";
+}
+
+/** The behaviour shared by the audio and video media types. */
+export class HtmlMediaBase extends Media {
+    declare "player_element": HTMLMediaElement | null;
+    declare "_onCanPlay": (() => void) | null;
+    declare "_onEnded": (() => void) | null;
+    declare "_onSourceError": (() => void) | null;
+
+    /**
+     * The per-kind differences. Overridden by the Audio/Video subclasses; the
+     * base value is never used (an HtmlMediaBase is always subclassed).
+     */
+    protected spec(): HtmlMediaSpec {
+        return AUDIO_DEFAULT;
+    }
+
+    _loadMedia() {
+        const spec = this.spec();
+        this.loadingMessage();
+
+        const media_item = Dom.create(
+            spec.kind,
+            `vco-media-item vco-media-${spec.kind} vco-media-shadow`,
+            this._el.content,
+        ) as HTMLMediaElement;
+        this._el.content_item = media_item;
+        media_item.controls = true;
+
+        const source_item = Dom.create("source", "", media_item) as HTMLSourceElement;
+        this._el.source_item = source_item;
+
+        // Media Loaded Event. The references are kept so dispose() can detach
+        // them: an inline arrow function has no other handle.
+        this._onEnded = null;
+        this._onCanPlay = () => {
+            this.onLoaded();
+        };
+        media_item.addEventListener("canplay", this._onCanPlay);
+
+        // Load Error Event (the source element fires it, not the media element)
+        this._onSourceError = () => {
+            this.loadErrorDisplay(Language.messages.error + " " + this.options.media_name);
+        };
+        source_item.addEventListener("error", this._onSourceError);
+
+        const url = this._url();
+        source_item.src = url;
+        const media_type = this._getType(url, spec);
+        // An unrecognised extension leaves the type unset so the browser can
+        // work it out from the URL — setting a bare "audio/" (as this used to)
+        // is not a valid MIME type and makes the source fail outright.
+        if (media_type) {
+            source_item.type = media_type;
+        }
+        // Subtitles: a WebVTT track, opt-in via media.subtitles. The element
+        // is created before the fallback text node so the fallback stays last.
+        if (spec.kind === "video" || spec.kind === "audio") {
+            const subtitles = (this.data as { subtitles?: string | null }).subtitles;
+            if (typeof subtitles === "string" && subtitles !== "") {
+                const track = Dom.create(
+                    "track",
+                    "vco-media-track",
+                    media_item,
+                ) as HTMLTrackElement;
+                track.kind = "subtitles";
+                track.srclang = "en";
+                track.label = "Subtitles";
+                track.src = subtitles;
+                track.default = true;
+            }
+        }
+
+        // append as a text node: re-serializing innerHTML would replace the
+        // source element and drop its error listener, leaving the loading
+        // message on screen forever
+        media_item.appendChild(
+            document.createTextNode(
+                `Your browser doesn't support HTML5 ${spec.kind} with ` + source_item.type,
+            ),
+        );
+
+        // `ended` is what autoplay_media waits for instead of its timer; the
+        // reference is kept so dispose() can detach it, like the two above
+        this._onEnded = () => {
+            this.fire("media_ended", this.data);
+        };
+        media_item.addEventListener("ended", this._onEnded);
+
+        this.player_element = media_item;
+    }
+
+    // Update Media Display
+    _updateMediaDisplay() {
+        // the height is CSS-driven; nothing to compute here
+    }
+
+    _stopMedia() {
+        this.player_element?.pause();
+    }
+
+    /**
+     * Detach the media listeners and release the source, so a disposed audio
+     * or video element stops buffering instead of playing into a detached
+     * tree. Pausing alone (what `stopMedia()` does per slide change) is not
+     * enough for a full teardown.
+     */
+    _disposeMedia() {
+        if (this._onCanPlay) {
+            this.player_element?.removeEventListener("canplay", this._onCanPlay);
+            this._onCanPlay = null;
+        }
+        if (this._onEnded) {
+            this.player_element?.removeEventListener("ended", this._onEnded);
+            this._onEnded = null;
+        }
+        if (this._onSourceError) {
+            this._el.source_item?.removeEventListener("error", this._onSourceError);
+            this._onSourceError = null;
+        }
+        const el = this.player_element;
+        if (el) {
+            el.pause();
+            // dropping the source stops the network fetch immediately
+            el.removeAttribute("src");
+            el.load();
+        }
+        this.player_element = null;
+
+        this._onCanPlay = null;
+
+        this._onSourceError = null;
+    }
+
+    _getType(url: string, spec: HtmlMediaSpec): string {
+        const ext = url.match((this.data.mediatype as { match_str: string | RegExp }).match_str);
+        if (!ext) {
+            return "";
+        }
+        return mimeSubtype(ext[1], spec);
+    }
+}

package/src/media/types/IFrame.ts

@@ -0,0 +1,50 @@
+import { Media } from "../Media";
+import Dom from "../../dom/Dom";
+import { buildIframe } from "../EmbedUtil";
+
+/*	Media.IFrame
+================================================== */
+
+export default class IFrame extends Media {
+    declare "media_id": string;
+
+    /*	Load the media
+	================================================== */
+    _loadMedia() {
+        // Loading Message
+        this.loadingMessage();
+
+        // Create Dom element
+        this._el.content_item = Dom.create(
+            "div",
+            "vco-media-item vco-media-iframe",
+            this._el.content,
+        );
+
+        // Get Media ID
+        this.media_id = this._url();
+
+        // The url field holds a user-pasted embed snippet. Rebuild a
+        // clean iframe from its src instead of injecting the raw markup,
+        // which would allow stored XSS via the storymap JSON.
+        const iframe = buildIframe(this.media_id);
+
+        if (!iframe) {
+            this.loadErrorDisplay(
+                "Invalid embed code. Paste an iframe embed code with an http(s) source URL.",
+            );
+            return;
+        }
+
+        // API Call
+        this._el.content_item.appendChild(iframe);
+
+        // After Loaded
+        this.onLoaded();
+    }
+
+    // Update Media Display
+    _updateMediaDisplay() {
+        this._sizeContentItemToOptionHeight();
+    }
+}

package/src/media/types/Image.ts

@@ -0,0 +1,115 @@
+import { Media } from "../Media";
+import Dom from "../../dom/Dom";
+import { validateWebURL } from "../EmbedUtil";
+
+/* IIIF Image API 2/3 URL tail: .../region/size/rotation/quality.format
+   (optionally a query string). Used to request container-matched widths
+   instead of the full-size image (perf, backwards-compatible). */
+const IIIF_TAIL =
+    /\/(full|max|pct:[\d.]+|\d+,?\d*)\/(full|max|pct:[\d.]+|\d+,?\d*)\/(\d+|full)\/(default|color|gray|bitonal)\.(jpg|jpeg|png|webp|gif)(\?.*)?$/i;
+
+/**
+ * Rewrite an IIIF Image API URL to the given pixel width (`w,` size
+ * component, height unconstrained). Returns the URL unchanged when it is
+ * not a recognizable IIIF image URL.
+ */
+export function iiifSizedUrl(url: string | null, width: number): string | null {
+    if (!url || !(width > 0)) {
+        return url;
+    }
+    const match = url.match(IIIF_TAIL);
+    if (!match) {
+        return url;
+    }
+    return (
+        url.slice(0, match.index) +
+        `/${match[1]}/${width},/${match[3]}/${match[4]}.${match[5]}${match[6] ?? ""}`
+    );
+}
+
+/*	Media.Image
+	Produces image assets.
+	Takes a data object and populates a dom object
+================================================== */
+
+export default class Image extends Media {
+    /*	Load the media
+	================================================== */
+    _loadMedia() {
+        // Loading Message
+        this.loadingMessage();
+
+        // Link — protocol-checked: a `javascript:` href in the storymap JSON
+        // would be a click-through XSS (see Media._initLayout)
+        const link_href = this.data.link ? validateWebURL(this.data.link) : null;
+        if (link_href) {
+            this._el.content_link = Dom.create("a", "", this._el.content);
+            const content_link = this._el.content_link as HTMLAnchorElement;
+            content_link.href = link_href;
+            content_link.target = "_blank";
+            content_link.rel = "noopener noreferrer";
+            this._el.content_item = Dom.create(
+                "img",
+                "vco-media-item vco-media-image vco-media-shadow",
+                this._el.content_link,
+            );
+        } else {
+            this._el.content_item = Dom.create(
+                "img",
+                "vco-media-item vco-media-image vco-media-shadow",
+                this._el.content,
+            );
+        }
+
+        // Media Loaded Event
+        this._el.content_item.addEventListener("load", (e) => {
+            this.onMediaLoaded();
+        });
+
+        const img = this._el.content_item as HTMLImageElement;
+        // offscreen/preloaded slides stay lazy (the active slide is
+        // upgraded to eager on activation, see Slide.setActive); decoding
+        // is only a hint — old browsers ignore both attributes
+        img.decoding = "async";
+        img.loading = this._state.eager ? "eager" : "lazy";
+        // responsive sizes (perf): IIIF image URLs request a container-
+        // matched width; author-provided srcset/sizes pass through;
+        // everything else renders byte-identically
+        const media_width = Number(this.options.width) || 0;
+        const sized = iiifSizedUrl(this._url(), media_width);
+        img.src = sized ?? this._url();
+        // accessibility: explicit alt text, falling back to the caption as
+        // plain text; an empty string marks a decorative image
+        img.alt = this._altText();
+        if (this.data.srcset) {
+            img.srcset = this.data.srcset as string;
+        }
+        if (this.data.sizes) {
+            img.sizes = this.data.sizes as string;
+        }
+
+        // the element is built and the src is set: hand over to Media so the
+        // loading overlay is hidden and credit/caption are rendered. The
+        // `load` listener above only fires the separate media_loaded event.
+        this.onLoaded();
+    }
+
+    _altText(): string {
+        const alt = this.data.alt as string | undefined;
+        if (alt !== undefined && alt !== "") {
+            return alt;
+        }
+        const caption = this.data.caption as string | null | undefined;
+        if (caption) {
+            return caption
+                .replace(/<[^>]*>/g, " ")
+                .replace(/\s+/g, " ")
+                .trim();
+        }
+        return "";
+    }
+
+    _updateMediaDisplay(layout?: string) {
+        // modern browsers size media correctly without engine-specific fixes
+    }
+}

package/src/media/types/Juxtapose.ts

@@ -0,0 +1,41 @@
+import { Media } from "../Media";
+import Dom from "../../dom/Dom";
+import { buildIframe } from "../EmbedUtil";
+
+/*	Media.Juxtapose
+	Embeds a JuxtaposeJS before/after slider (issue #360)
+================================================== */
+
+export default class Juxtapose extends Media {
+    /*	Load the media
+	================================================== */
+    _loadMedia() {
+        // Loading Message
+        this.loadingMessage();
+
+        // Create Dom element
+        this._el.content_item = Dom.create(
+            "div",
+            "vco-media-item vco-media-iframe vco-media-juxtapose",
+            this._el.content,
+        );
+
+        // Built through buildIframe rather than an `<iframe src="${url}">`
+        // template string: interpolating a storymap-JSON string into markup
+        // is a stored-XSS break-out (`"><img src=x onerror=...>`), and
+        // MediaType routes *any* URL containing "juxtapose" here.
+        const embed = buildIframe(`<iframe src="${String(this._url() ?? "")}"></iframe>`);
+        if (!embed) {
+            this.loadErrorDisplay("Invalid URL.");
+            return;
+        }
+        embed.setAttribute("loading", "lazy");
+        this._el.content_item.appendChild(embed);
+        this.onLoaded();
+    }
+
+    // Update Media Display
+    _updateMediaDisplay() {
+        this._sizeContentItemToOptionHeight();
+    }
+}

package/src/media/types/SoundCloud.ts

@@ -0,0 +1,99 @@
+import { Media } from "../Media";
+import Dom from "../../dom/Dom";
+import { sanitizeSlideText } from "../EmbedUtil";
+
+/*	Media.SoundCloud
+================================================== */
+
+/*	Minimal surface of the SoundCloud widget API used here. */
+interface SoundCloudWidget {
+    pause: () => void;
+    unbind?: () => void;
+}
+
+export default class SoundCloud extends Media {
+    declare "media_id": string;
+    declare "soundCloudCreated": boolean;
+    declare "widget": SoundCloudWidget | null;
+
+    /*	Load the media
+	================================================== */
+    async _loadMedia() {
+        // Loading Message
+        this.loadingMessage();
+
+        // Create Dom element
+        this._el.content_item = Dom.create(
+            "div",
+            "vco-media-item vco-media-iframe vco-media-soundcloud vco-media-shadow",
+            this._el.content,
+        );
+
+        // Get Media ID
+        this.media_id = this._url();
+
+        // API URL
+        const api_url = "https://soundcloud.com/oembed?url=" + this.media_id + "&format=json";
+
+        // API Call
+        try {
+            const r = await fetch(api_url);
+            const d = await r.json();
+            await this.loadScript("https://w.soundcloud.com/player/api.js");
+            //load soundcloud api for pausing.
+            this.createMedia(d);
+        } catch (err) {
+            // aborted loads stay silent (the visitor navigated away);
+            // real failures show the media error display
+            if ((err as DOMException)?.name !== "AbortError") {
+                this.loadErrorDisplay("Unable to load this track.");
+            }
+        }
+    }
+
+    createMedia(d: unknown) {
+        const data = d as { html: string };
+        if (!data?.html) {
+            this.loadErrorDisplay("Unable to load this track.");
+            return;
+        }
+        // The oEmbed response is third-party HTML. It is sanitized like any
+        // other untrusted markup, which in practice keeps the provider's
+        // <iframe> (rebuilt by the sanitizer) and drops its inline script —
+        // the widget is created from the iframe below, so the script was never
+        // needed in the first place.
+        const content_item = this._el.content_item;
+        if (!content_item) {
+            this.loadErrorDisplay("Unable to load this track.");
+            return;
+        }
+        content_item.appendChild(sanitizeSlideText(data.html));
+
+        this.soundCloudCreated = true;
+
+        const sc = SC as { Widget: (iframe: Element | null) => SoundCloudWidget };
+        // per-instance widget: a global would be overwritten by every
+        // SoundCloud slide and _stopMedia would pause the wrong one
+        this.widget = sc.Widget(content_item.querySelector("iframe"));
+
+        // After Loaded
+        this.onLoaded();
+    }
+
+    _stopMedia() {
+        if (this.soundCloudCreated) {
+            this.widget?.pause();
+        }
+    }
+
+    /** Unbind the widget so it stops playing once the slide is gone. */
+    _disposeMedia() {
+        try {
+            this.widget?.unbind?.();
+        } catch (err) {
+            console.log(err);
+        }
+        this.widget = null;
+        this.soundCloudCreated = false;
+    }
+}

package/src/media/types/Text.ts

@@ -0,0 +1,178 @@
+import { mergeData, htmlify, convertUnixTime } from "../../core/Util";
+import { Evented, type EventedInstance } from "../../core/mixins";
+import Dom from "../../dom/Dom";
+import { sanitizeSlideText } from "../EmbedUtil";
+
+interface TextData {
+    uniqueid?: string | null;
+    headline?: string;
+    text?: string;
+    text_align?: string;
+    date?: { created_time?: string; [key: string]: unknown } | null;
+}
+
+interface TextOptions {
+    title?: boolean;
+    text_align?: string;
+}
+
+class TextBase {
+    declare "_el": Record<string, HTMLElement>;
+    declare "data": TextData;
+    declare "options": TextOptions;
+    declare "fire": EventedInstance["fire"];
+
+    /*	Constructor
+	================================================== */
+    constructor(data: TextData, options?: TextOptions, add_to_container?: HTMLElement) {
+        // DOM ELEMENTS
+        this._el = {
+            container: {} as HTMLElement,
+            content_container: {} as HTMLElement,
+            content: {} as HTMLElement,
+            headline: {} as HTMLElement,
+            date: {} as HTMLElement,
+            start_btn: {} as HTMLElement,
+        };
+
+        // Data. The placeholders were the literal strings "headline" and
+        // "text", which mergeData only overwrites when the key is present — so
+        // a slide with body text and no headline rendered an <h2>headline</h2>.
+        // The renderer guards both on `!== ""`, so empty is the real default.
+        this.data = {
+            uniqueid: "",
+            headline: "",
+            text: "",
+        };
+
+        // Options
+        this.options = {
+            title: false,
+        };
+
+        mergeData(this.data, data);
+
+        // Merge Options
+        mergeData(this.options, options);
+
+        this._el.container = Dom.create("div", "vco-text");
+        this._el.container.id = this.data.uniqueid ?? "";
+
+        this._initLayout();
+
+        if (add_to_container) {
+            add_to_container.appendChild(this._el.container);
+        }
+    }
+
+    /*	Adding, Hiding, Showing etc
+	================================================== */
+    show() {}
+
+    hide() {}
+
+    addTo(container: HTMLElement) {
+        container.appendChild(this._el.container);
+        //this.onAdd();
+    }
+
+    removeFrom(container: HTMLElement) {
+        container.removeChild(this._el.container);
+    }
+
+    headlineHeight() {
+        return this._el.headline.offsetHeight + 40;
+    }
+
+    addDateText(str: string) {
+        if (this._el.date) {
+            this._el.date.innerHTML = str;
+        }
+    }
+
+    /*	Events
+	================================================== */
+    onLoaded() {
+        this.fire("loaded", this.data);
+    }
+
+    onAdd() {
+        this.fire("added", this.data);
+    }
+
+    onRemove() {
+        this.fire("removed", this.data);
+    }
+
+    /*	Private Methods
+	================================================== */
+    _initLayout() {
+        // Create Layout
+        this._el.content_container = Dom.create(
+            "div",
+            "vco-text-content-container",
+            this._el.container,
+        );
+
+        // Text alignment: per-slide override wins, then the storymap option
+        // (issue #244)
+        const align =
+            (this.data.text_align as string | undefined) ??
+            (this.options.text_align as string | undefined) ??
+            "left";
+        if (align === "center" || align === "right") {
+            this._el.content_container.classList.add("vco-text-align-" + align);
+        }
+
+        // Date (only rendered when the slide has one; issue #286)
+        if (this.data.date && this.data.date.created_time && this.data.date.created_time !== "") {
+            this._el.date = Dom.create("h3", "vco-headline-date", this._el.content_container);
+            this.addDateText(convertUnixTime(this.data.date.created_time));
+        }
+
+        // Headline (sanitized; issue #358 keeps formatting but drops scripts)
+        const headline = this.data.headline ?? "";
+        if (headline !== "") {
+            let headline_class = "vco-headline";
+            if (this.options.title) {
+                headline_class = "vco-headline vco-headline-title";
+            }
+            this._el.headline = Dom.create("h2", headline_class, this._el.content_container);
+            this._el.headline.appendChild(sanitizeSlideText(headline));
+        }
+
+        // Text (sanitized; issue #358 allows extra iframe media in the text field)
+        const text = this.data.text ?? "";
+        if (text !== "") {
+            let text_content = "";
+
+            text_content += htmlify(text);
+
+            // Date
+            if (
+                this.data.date &&
+                this.data.date.created_time &&
+                this.data.date.created_time !== ""
+            ) {
+                if (this.data.date.created_time.length > 10) {
+                    text_content +=
+                        "<div class='vco-text-date'>" +
+                        convertUnixTime(this.data.date.created_time) +
+                        "</div>";
+                }
+            }
+
+            this._el.content = Dom.create("div", "vco-text-content", this._el.content_container);
+            this._el.content.appendChild(sanitizeSlideText(text_content));
+        }
+
+        // Fire event that the slide is loaded
+        this.onLoaded();
+    }
+}
+
+export default class Text extends Evented(TextBase) {
+    constructor(...args: ConstructorParameters<typeof TextBase>) {
+        super(...args);
+    }
+}