@projektemacher/storymapjs 0.10.7 → 0.11.0

package/src/media/types/Audio.ts

@@ -1,87 +1,14 @@
-import { Media } from "../Media";
-import Dom from "../../dom/Dom";
-import { Language } from "../../language/Language";
+import { HtmlMediaBase, type HtmlMediaKind } from "./HtmlMedia";
 
-/*	Media.Vimeo
+/*	Media.Audio
+	An <audio> element with a single <source> child.
 ================================================== */
 
-export default class Audio extends Media {
-    declare "player_element": HTMLMediaElement;
-
-    /*	Load the media
-	================================================== */
-    _loadMedia() {
-        // Loading Message
-        this.message.updateMessage(Language.messages.loading + " " + this.options.media_name);
-
-        // Create Dom element
-        this._el.content_item = Dom.create(
-            "audio",
-            "vco-media-item vco-media-audio vco-media-shadow",
-            this._el.content,
-        );
-        const media_item = this._el.content_item as HTMLMediaElement;
-        media_item.controls = true;
-        this._el.source_item = Dom.create("source", "", this._el.content_item);
-        const source_item = this._el.source_item as HTMLSourceElement;
-
-        // Media Loaded Event
-        media_item.addEventListener("canplay", () => {
-            this.onLoaded();
-        });
-
-        // Load Error Event (the source element fires it, not the media element)
-        source_item.addEventListener("error", () => {
-            this.loadErrorDisplay(Language.messages.error + " " + this.options.media_name);
-        });
-
-        source_item.src = this.data.url;
-        const media_type = this._getType(this.data.url, this.data.mediatype.match_str);
-        if (media_type) {
-            source_item.type = media_type;
-        }
-        // 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 audio with " + source_item.type,
-            ),
-        );
-        this.player_element = media_item;
-    }
-
-    // Update Media Display
-    _updateMediaDisplay() {
-        // audio height is CSS-driven; nothing to compute here
-    }
-
-    _stopMedia() {
-        if (this.player_element) {
-            this.player_element.pause();
-        }
-    }
-
-    _getType(url: string, reg: string | RegExp) {
-        const ext = url.match(reg);
-        let type = "audio/";
-        if (!ext) {
-            return type;
-        }
-        switch (ext[1]) {
-            case "mp3":
-                type += "mpeg";
-                break;
-            case "wav":
-                type += "wav";
-                break;
-            case "m4a":
-                type += "mp4";
-                break;
-            default:
-                type = "";
-                break;
-        }
-        return type;
+export default class Audio extends HtmlMediaBase {
+    protected spec() {
+        return {
+            kind: "audio" as HtmlMediaKind,
+            extensions: { mp3: "mpeg", wav: "wav", m4a: "mp4" },
+        };
     }
 }

package/src/media/types/Blockquote.ts

@@ -1,6 +1,5 @@
 import { Media } from "../Media";
 import Dom from "../../dom/Dom";
-import { Language } from "../../language/Language";
 import { sanitizeBlockquote } from "../EmbedUtil";
 
 /*	Media.Blockquote
@@ -13,7 +12,7 @@ export default class Blockquote extends Media {
 	================================================== */
     _loadMedia() {
         // Loading Message
-        this.message.updateMessage(Language.messages.loading + " " + this.options.media_name);
+        this.loadingMessage();
 
         // Create Dom element
         this._el.content_item = Dom.create(
@@ -23,7 +22,7 @@ export default class Blockquote extends Media {
         );
 
         // Get Media ID
-        this.media_id = this.data.url;
+        this.media_id = this._url();
 
         // The url field holds user-pasted blockquote markup. Sanitize it
         // instead of injecting the raw markup, which would allow stored

package/src/media/types/DailyMotion.ts

@@ -1,7 +1,6 @@
+import { dailymotionId } from "../embedId";
 import { Media } from "../Media";
 import Dom from "../../dom/Dom";
-import { Language } from "../../language/Language";
-import { ratio } from "../../core/Util";
 
 /*	Media.DailyMotion
 ================================================== */
@@ -13,7 +12,7 @@ export default class DailyMotion extends Media {
 	================================================== */
     _loadMedia() {
         // Loading Message
-        this.message.updateMessage(Language.messages.loading + " " + this.options.media_name);
+        this.loadingMessage();
 
         // Create Dom element
         this._el.content_item = Dom.create(
@@ -23,13 +22,10 @@ export default class DailyMotion extends Media {
         );
 
         // Get Media ID
-        const id = this.data.url.match("video")
-            ? this.data.url.split("video/")[1]
-            : this.data.url.split("embed/")[1];
-        if (!id) {
+        this.media_id = dailymotionId(this._url()) ?? "";
+        if (!this.media_id) {
             throw new Error("Invalid DailyMotion URL");
         }
-        this.media_id = id.split(/[?&]/)[0];
 
         // API URL
         const api_url =
@@ -47,8 +43,7 @@ export default class DailyMotion extends Media {
 
     // Update Media Display
     _updateMediaDisplay() {
-        this._el.content_item.style.height =
-            ratio.r16_9({ w: this._el.content_item.offsetWidth }) + "px";
+        this._sizeContentItemTo16x9();
     }
 
     _stopMedia() {

package/src/media/types/DocumentCloud.ts

@@ -1,41 +1,12 @@
-import { Media } from "../Media";
-import Dom from "../../dom/Dom";
-import { Language } from "../../language/Language";
-import { validateWebURL } from "../EmbedUtil";
+import { WebsiteBase } from "./Website";
 
 /*	Media.DocumentCloud
-	Embeds a DocumentCloud document viewer (issue #437)
+	Embeds a DocumentCloud document viewer (issue #437) — the same iframe
+	embed as the website type, with its own CSS class.
 ================================================= */
 
-export default class DocumentCloud extends Media {
-    /*	Load the media
-	================================================== */
-    _loadMedia() {
-        // Loading Message
-        this.message.updateMessage(Language.messages.loading + " " + this.options.media_name);
-
-        // Create Dom element
-        this._el.content_item = Dom.create(
-            "div",
-            "vco-media-item vco-media-iframe vco-media-documentcloud",
-            this._el.content,
-        );
-
-        // the canonical document URL renders the standalone viewer; rebuilt
-        // from a validated src to keep stored XSS out of the storymap JSON
-        const src = validateWebURL(this.data.url);
-        if (!src) {
-            this.loadErrorDisplay("Invalid URL.");
-            return;
-        }
-        const iframe = document.createElement("iframe");
-        iframe.setAttribute("src", src);
-        this._el.content_item.appendChild(iframe);
-        this.onLoaded();
-    }
-
-    // Update Media Display
-    _updateMediaDisplay() {
-        this._el.content_item.style.height = this.options.height + "px";
+export default class DocumentCloud extends WebsiteBase {
+    protected extraClass(): string {
+        return "vco-media-documentcloud";
     }
 }

package/src/media/types/Facebook.ts

@@ -1,6 +1,5 @@
 import { Media } from "../Media";
 import Dom from "../../dom/Dom";
-import { Language } from "../../language/Language";
 
 /*	Media.Facebook
 	Embeds a Facebook post, video or reel via the plugins endpoint
@@ -12,7 +11,7 @@ export default class Facebook extends Media {
 	================================================== */
     _loadMedia() {
         // Loading Message
-        this.message.updateMessage(Language.messages.loading + " " + this.options.media_name);
+        this.loadingMessage();
 
         // Create Dom element
         this._el.content_item = Dom.create(
@@ -21,7 +20,7 @@ export default class Facebook extends Media {
             this._el.content,
         );
 
-        const url = this.data.url;
+        const url = this._url();
         const href = encodeURIComponent(url);
         const embed =
             /\/videos?\//.test(url) || /\/watch/.test(url) || /\/reel\//.test(url)
@@ -36,6 +35,6 @@ export default class Facebook extends Media {
 
     // Update Media Display
     _updateMediaDisplay() {
-        this._el.content_item.style.height = this.options.height + "px";
+        this._sizeContentItemToOptionHeight();
     }
 }

package/src/media/types/Flickr.ts

@@ -1,6 +1,6 @@
+import { flickrId } from "../embedId";
 import { Media } from "../Media";
 import Dom from "../../dom/Dom";
-import { Language } from "../../language/Language";
 
 /*	Media.Flickr
 
@@ -8,12 +8,14 @@ import { Language } from "../../language/Language";
 
 export default class Flickr extends Media {
     declare "media_id": string;
+    /** The `load` handler on the image, stored so dispose() can detach it. */
+    declare "_onLoad": (() => void) | null;
 
     /*	Load the media
 	================================================== */
     _loadMedia() {
         // Loading Message
-        this.message.updateMessage(Language.messages.loading + " " + this.options.media_name);
+        this.loadingMessage();
 
         // Create Dom element
         this._el.content_item = Dom.create(
@@ -22,10 +24,12 @@ export default class Flickr extends Media {
             this._el.content,
         );
 
-        // Media Loaded Event
-        this._el.content_item.addEventListener("load", (e) => {
+        // Media Loaded Event. The reference is kept so dispose() can detach
+        // it: an inline arrow function has no other handle.
+        this._onLoad = () => {
             this.onMediaLoaded();
-        });
+        };
+        this._el.content_item.addEventListener("load", this._onLoad);
 
         // Get Media ID
         this.establishMediaID();
@@ -55,18 +59,18 @@ export default class Flickr extends Media {
     }
 
     establishMediaID() {
-        const marker = "flickr.com/photos/";
-        const idx = this.data.url.indexOf(marker);
-        if (idx === -1) {
-            throw "Invalid Flickr URL";
+        // threw a bare string (not an Error) and could assign `undefined` when
+        // the URL had the host but no photo segment
+        const id = flickrId(this._url());
+        if (!id) {
+            throw new Error("Invalid Flickr URL");
         }
-        const pos = idx + marker.length;
-        this.media_id = this.data.url.slice(pos).split("/")[1];
+        this.media_id = id;
     }
 
     createMedia(d: unknown) {
         const data = d as { sizes: { size: { label: string; source: string }[] } };
-        const best_size = this.sizes(this.options.height);
+        const best_size = this.sizes(Number(this.options.height ?? 0));
         const sizes = data?.sizes?.size;
         if (!sizes || !sizes.length) {
             this.loadErrorDisplay("Photo not found or private.");
@@ -112,4 +116,11 @@ export default class Flickr extends Media {
 
         return _size;
     }
+
+    _disposeMedia(): void {
+        if (this._onLoad) {
+            this._el.content_item?.removeEventListener("load", this._onLoad);
+            this._onLoad = null;
+        }
+    }
 }

package/src/media/types/GoogleDoc.ts

@@ -1,6 +1,5 @@
 import { Media } from "../Media";
 import Dom from "../../dom/Dom";
-import { Language } from "../../language/Language";
 import { validateWebURL } from "../EmbedUtil";
 
 /*	Media.GoogleDoc
@@ -14,7 +13,7 @@ export default class GoogleDoc extends Media {
 	================================================== */
     _loadMedia() {
         // Loading Message
-        this.message.updateMessage(Language.messages.loading + " " + this.options.media_name);
+        this.loadingMessage();
 
         // Create Dom element
         this._el.content_item = Dom.create(
@@ -24,7 +23,7 @@ export default class GoogleDoc extends Media {
         );
 
         // Get Media ID
-        this.media_id = this.data.url;
+        this.media_id = this._url();
 
         // Rebuild a clean iframe from a validated src: injecting the raw
         // URL into markup would allow stored XSS via the storymap JSON
@@ -54,6 +53,6 @@ export default class GoogleDoc extends Media {
 
     // Update Media Display
     _updateMediaDisplay() {
-        this._el.content_item.style.height = this.options.height + "px";
+        this._sizeContentItemToOptionHeight();
     }
 }

package/src/media/types/HtmlMedia.ts

@@ -0,0 +1,233 @@
+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 captionText =
+            typeof this.data.caption === "string"
+                ? this.data.caption
+                      .replace(/<[^>]*>/g, " ")
+                      .replace(/\s+/g, " ")
+                      .trim()
+                : "";
+        const mediaName =
+            typeof this.options.media_name === "string" ? this.options.media_name : "";
+        media_item.setAttribute(
+            "aria-label",
+            captionText || mediaName || (spec.kind === "audio" ? "Audio" : "Video"),
+        );
+
+        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;
+        // Playback flags (slideshow audio terms): loop repeats, offset seeks
+        // once the metadata is available, play:"auto" starts on load
+        // (absent stays click-to-play with controls, as before). Slideshow
+        // tours only — internal documents ignore the bag even when present.
+        const sourced = (this.options as { slideshow_source?: unknown }).slideshow_source === true;
+        const bag = (
+            sourced
+                ? this.data
+                : ({} as {
+                      loop?: boolean;
+                      offset?: number;
+                      play?: string;
+                  })
+        ) as {
+            loop?: boolean;
+            offset?: number;
+            play?: string;
+        };
+        media_item.loop = bag.loop === true;
+        const offset =
+            typeof bag.offset === "number" && Number.isFinite(bag.offset) && bag.offset > 0
+                ? bag.offset
+                : 0;
+        const seek = () => {
+            if (offset <= 0) return;
+            try {
+                media_item.currentTime = offset;
+            } catch {
+                // pre-metadata seek throws in some browsers; canplay retries
+            }
+        };
+        const autoplay = bag.play === "auto";
+        this._onCanPlay = () => {
+            seek();
+            if (autoplay) {
+                void media_item.play()?.catch?.(() => {
+                    // autoplay policy or missing gesture: controls stay for
+                    // the visitor, like a click-armed slide
+                });
+            }
+            this.onLoaded();
+        };
+        // offset with metadata already present (cached media): seek now too
+        if (offset > 0) {
+            if (media_item.readyState >= 1) {
+                seek();
+            } else {
+                media_item.addEventListener(
+                    "loadedmetadata",
+                    () => {
+                        seek();
+                    },
+                    { once: true },
+                );
+            }
+        }
+        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

@@ -1,6 +1,5 @@
 import { Media } from "../Media";
 import Dom from "../../dom/Dom";
-import { Language } from "../../language/Language";
 import { buildIframe } from "../EmbedUtil";
 
 /*	Media.IFrame
@@ -13,7 +12,7 @@ export default class IFrame extends Media {
 	================================================== */
     _loadMedia() {
         // Loading Message
-        this.message.updateMessage(Language.messages.loading + " " + this.options.media_name);
+        this.loadingMessage();
 
         // Create Dom element
         this._el.content_item = Dom.create(
@@ -23,7 +22,7 @@ export default class IFrame extends Media {
         );
 
         // Get Media ID
-        this.media_id = this.data.url;
+        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,
@@ -46,6 +45,6 @@ export default class IFrame extends Media {
 
     // Update Media Display
     _updateMediaDisplay() {
-        this._el.content_item.style.height = this.options.height + "px";
+        this._sizeContentItemToOptionHeight();
     }
 }