@projektemacher/storymapjs 0.10.7 → 0.11.0

package/src/media/Media.ts

@@ -1,16 +1,65 @@
-import { mergeData } from "../core/Util";
+import { mergeData, ratio, clearTimer } from "../core/Util";
 import { Evented, type EventedInstance } from "../core/mixins";
 import Dom from "../dom/Dom";
 import Message from "../ui/Message";
 import { Browser } from "../core/Browser";
 import { MediaState, StorymapSlideMedia } from "../types";
-import { consentManagerOf, consentMessage } from "../storymap/Consent";
+import { Language } from "../language/Language";
+import { consentManagerOf, consentMessage, mediaService } from "../storymap/Consent";
+import { validateWebURL, sanitizeSlideText } from "./EmbedUtil";
 import { loadJS } from "../core/Load";
 /*	VCO.Media
 	Main media template for media assets.
 	Takes a data object and populates a dom object
 ================================================== */
 
+/**
+ * The icon glyph each media type shows in its error state.
+ *
+ * The icon font does not carry a glyph for every registered type, and the
+ * class used to be built straight from `media_type`, so dailymotion, audio,
+ * googledocs, iframe, documentcloud, juxtapose and website rendered an empty
+ * box next to the error text. The mapping is explicit rather than derived, so
+ * a type added later falls back to a real glyph instead of a blank one —
+ * `tests/embed-util-media.test.ts` checks the whole table against the font.
+ */
+const LOAD_ERROR_ICONS: Record<string, string> = {
+    youtube: "youtube",
+    vimeo: "vimeo",
+    dailymotion: "video",
+    soundcloud: "soundcloud",
+    twitter: "twitter",
+    flickr: "flickr",
+    image: "image",
+    video: "video",
+    audio: "music",
+    googledocs: "doc",
+    wikipedia: "wikipedia",
+    iframe: "web",
+    facebook: "facebook",
+    documentcloud: "doc",
+    juxtapose: "image",
+    blockquote: "blockquote",
+    website: "web",
+};
+
+const GENERIC_LOAD_ERROR_ICON = "web";
+
+export function loadErrorIcon(media_type: unknown): string {
+    const type = typeof media_type === "string" ? media_type : "";
+    return LOAD_ERROR_ICONS[type] ?? GENERIC_LOAD_ERROR_ICON;
+}
+
+/**
+ * Whether media captions/credits render: `show_info: false` hides them, but
+ * only for slideshow tours (`slideshow_source`) — internal documents always
+ * show their captions. Pure for testability.
+ */
+export function shouldShowInfo(options: MediaOptions): boolean {
+    if (options.slideshow_source !== true) return true;
+    return options.show_info !== false;
+}
+
 /*	Options for Media and its subclasses: the fields Media itself sets
 	or reads. Everything else merged in via mergeData is absorbed by the
 	index signature. */
@@ -29,29 +78,57 @@ export interface MediaOptions {
 /*	Data for media assets: the shared exchange format plus the link
 	fields the base layout renders. */
 export interface MediaData extends StorymapSlideMedia {
-    uniqueid?: string;
-    link?: string;
-    link_target?: string;
+    uniqueid?: string | null;
+    link?: string | null;
+    link_target?: string | null;
     [key: string]: unknown;
 }
 
+export interface MediaEvents {
+    loaded: MediaData;
+    media_loaded: MediaData;
+    media_ended: MediaData;
+    added: MediaData;
+    removed: MediaData;
+}
+
+/**
+ * The media element cache.
+ *
+ * `content_item`, `content_link`, `caption` and `credit` are only created
+ * once `_loadMedia()` / `showMeta()` have run, so they start out null rather
+ * than as an empty element — that is what the "did the load happen?" check is
+ * for, and pretending otherwise with `{} as HTMLElement` is what let the
+ * consent-denied path dereference `undefined.style`.
+ */
+type MediaElements = {
+    container: HTMLElement;
+    content_container: HTMLElement;
+    content: HTMLElement;
+    content_item: HTMLElement | null;
+    content_link: HTMLElement | null;
+    source_item: HTMLSourceElement | null;
+    caption: HTMLElement | null;
+    credit: HTMLElement | null;
+    parent: HTMLElement;
+    link: HTMLElement | null;
+};
+
 export class MediaBase {
-    declare "_el": Record<string, HTMLElement>;
+    declare "_el": MediaElements;
     declare "player": unknown;
-    declare "timer": ReturnType<typeof setTimeout>;
-    declare "load_timer": ReturnType<typeof setTimeout>;
+    declare "timer": ReturnType<typeof setTimeout> | null;
+    declare "load_timer": ReturnType<typeof setTimeout> | null;
     declare "load_controller": AbortController | null;
-    declare "message": Message;
+    declare "message": Message | null;
     declare "media_id": unknown;
     declare "_state": MediaState;
+    declare "_disposed": boolean;
     declare "data": MediaData;
     declare "options": MediaOptions;
     declare "animator": unknown;
     declare "_media": unknown;
-    declare "_": (key: string) => string;
-    declare "fire": EventedInstance["fire"];
-
-    //_el: {},
+    declare "fire": EventedInstance<MediaEvents>["fire"];
 
     /*	Constructor
 	================================================== */
@@ -61,8 +138,9 @@ export class MediaBase {
             container: {} as HTMLElement,
             content_container: {} as HTMLElement,
             content: {} as HTMLElement,
-            content_item: {} as HTMLElement,
-            content_link: {} as HTMLElement,
+            content_item: null,
+            content_link: null,
+            source_item: null,
             caption: null,
             credit: null,
             parent: {} as HTMLElement,
@@ -89,6 +167,7 @@ export class MediaBase {
             show_meta: false,
             media_loaded: false,
         };
+        this._disposed = false;
 
         // Data
         this.data = {
@@ -132,8 +211,14 @@ export class MediaBase {
             const manager = consentManagerOf(this.options);
             if (this.options.consent_required && manager && this.options.media_type) {
                 // GDPR consent mode: ask before loading anything from this
-                // external service
-                const service = this.options.media_type as string;
+                // external service. media_type is the stable identity (the
+                // MediaType slug) and media_name is the display name — using
+                // the slug as the label made this panel ask "Load content from
+                // youtube?" where the start-of-story dialog said "YouTube".
+                const service = mediaService(
+                    this.options.media_type,
+                    (this.options.media_name as string | undefined) ?? "",
+                );
                 let host = "";
                 try {
                     host = new URL((this.data as { url?: string })?.url ?? "").host;
@@ -163,8 +248,7 @@ export class MediaBase {
                 this._state.loaded = true;
                 this._updateDisplay();
             } catch (e) {
-                console.log("Error loading media for ", this._media);
-                console.log(e);
+                console.warn("StoryMapJS: error loading media.", e);
                 this.loadErrorDisplay("Error loading media.");
             }
         }, 1200);
@@ -175,49 +259,65 @@ export class MediaBase {
         const target = (this._el.content_container ?? this._el.container) as HTMLElement;
         const blocked = document.createElement("div");
         blocked.className = "vco-consent-blocked";
+        // the display name, not the slug — see loadMedia()
+        const service_name =
+            (this.options.media_name as string | undefined) ||
+            (this.options.media_type as string | undefined) ||
+            "";
         blocked.textContent = (
             consentMessage("consent_blocked", "Content from {service} is blocked.") as string
-        ).replace("{service}", (this.options.media_type as string) ?? "");
+        ).replace("{service}", service_name);
         target.append(blocked);
         this.onLoaded(true);
     }
 
-    loadingMessage() {
-        this.message.updateMessage(this._("loading") + " " + this.options.media_name);
+    /**
+     * Look up a UI string for the active language, falling back to the
+     * English default (which `setLanguage` already merges in) and finally to
+     * the key itself, so a missing translation degrades to something visible
+     * rather than "undefined".
+     */
+    _(key: string): string {
+        return Language.messages[key] ?? key;
+    }
+
+    /** Show the loading overlay for this media item. */
+    loadingMessage(): void {
+        this.message?.updateMessage(this._("loading") + " " + this.options.media_name);
     }
 
     updateMediaDisplay(layout?: string) {
-        if (this._state.loaded) {
-            this._updateMediaDisplay(layout);
+        // `content_item` only exists once a media type's `_loadMedia()` has
+        // run. It stays null when a consent decision blocked the load, so the
+        // sizing below has to be skipped rather than dereference a
+        // placeholder — that was the crash on the denied path.
+        const content_item = this._el.content_item;
+        if (!this._state.loaded || !content_item) {
+            return;
+        }
 
-            if (!Browser.mobile && layout !== "portrait") {
-                this._el.content_item.style.maxHeight = this.options.height / 2 + "px";
-            }
+        this._updateMediaDisplay(layout);
 
-            if (this._state.media_loaded) {
-                if (this._el.credit) {
-                    this._el.credit.style.width = "auto";
-                }
-                if (this._el.caption) {
-                    this._el.caption.style.width = "auto";
-                }
-            }
+        if (!Browser.mobile && layout !== "portrait") {
+            content_item.style.maxHeight = Number(this.options.height ?? 0) / 2 + "px";
+        }
 
-            if (layout === "portrait") {
-                this._el.content_item.style.maxHeight = "none";
+        if (layout === "portrait") {
+            content_item.style.maxHeight = "none";
+        }
+        if (this._state.media_loaded) {
+            const width = content_item.offsetWidth + "px";
+            if (this._el.credit) {
+                this._el.credit.style.width = width;
             }
-            if (this._state.media_loaded) {
-                if (this._el.credit) {
-                    this._el.credit.style.width = this._el.content_item.offsetWidth + "px";
-                }
-                if (this._el.caption) {
-                    this._el.caption.style.width = this._el.content_item.offsetWidth + "px";
-                }
+            if (this._el.caption) {
+                this._el.caption.style.width = width;
             }
         }
     }
 
-    /*	Media Specific
+    /**
+     * Media Specific
 	================================================== */
     _loadMedia() {}
 
@@ -225,6 +325,24 @@ export class MediaBase {
         //this._el.content_item.style.maxHeight = (this.options.height - this.options.credit_height - this.options.caption_height - 16) + "px";
     }
 
+    /** Size the media box to the `height` option, in pixels. */
+    _sizeContentItemToOptionHeight(): void {
+        if (this._el.content_item) {
+            this._el.content_item.style.height = Number(this.options.height ?? 0) + "px";
+        }
+    }
+
+    /**
+     * Size the media box to a 16:9 box matching its current width — the
+     * aspect ratio every video provider embeds at.
+     */
+    _sizeContentItemTo16x9(): void {
+        const item = this._el.content_item;
+        if (item) {
+            item.style.height = ratio.r16_9({ w: item.offsetWidth }) + "px";
+        }
+    }
+
     /*	Public
 	================================================== */
     show() {}
@@ -241,6 +359,45 @@ export class MediaBase {
         this.onRemove();
     }
 
+    /**
+     * Terminal teardown: cancel pending work, stop playback, release the
+     * media-specific player and drop the DOM. Called by `Slide.dispose()`;
+     * the media must not be used afterwards.
+     */
+    dispose() {
+        if (this._disposed) {
+            return;
+        }
+        this._disposed = true;
+
+        // a load queued by loadMedia() that never started
+        if (this.load_timer) {
+            clearTimer(this.load_timer);
+            this.load_timer = null;
+        }
+        if (this.timer) {
+            clearTimer(this.timer);
+            this.timer = null;
+        }
+        // an external script still in flight (YouTube, Vimeo, Twitter, ...)
+        this.load_controller?.abort();
+        this.load_controller = null;
+
+        // let the concrete type tear down its player before the DOM goes away
+        this._disposeMedia();
+
+        this._el.container?.getAnimations?.().forEach((a) => a.cancel());
+        this.message?.dispose?.();
+        this.message = null;
+        this._el.container?.remove();
+    }
+
+    /**
+     * Media-specific teardown. Overridden by types that own a player, an
+     * embedded document or a listening widget.
+     */
+    _disposeMedia() {}
+
     // Update Display
     updateDisplay(w?: number, h?: number, l?: string) {
         this._updateDisplay(w, h, l);
@@ -251,7 +408,8 @@ export class MediaBase {
         // load delay): avoids building iframes and injecting scripts for a
         // slide the visitor already skipped past
         if (!this._state.loaded && this.load_timer) {
-            clearTimeout(this.load_timer);
+            clearTimer(this.load_timer);
+            this.load_timer = null;
             this.load_timer = null;
         }
         // Abort an in-flight external script load, if any
@@ -288,8 +446,21 @@ export class MediaBase {
             "vco-media-item vco-media-loaderror",
             this._el.content,
         );
-        this._el.content_item.innerHTML =
-            "<div class='vco-icon-" + this.options.media_type + "'></div><p>" + message + "</p>";
+        // The icon font has no glyph for every media type (dailymotion, audio,
+        // googledocs, iframe, documentcloud, juxtapose and website had none),
+        // and the class was built by string concatenation, so those error
+        // states rendered an empty box. Map the missing ones to a glyph that
+        // exists, and fall back to a generic "web" icon for anything added
+        // later.
+        this._el.content_item.appendChild(
+            Dom.create("div", `vco-icon-${loadErrorIcon(this.options.media_type)}`),
+        );
+        const text = Dom.create("p", "");
+        text.appendChild(document.createTextNode(message));
+        this._el.content_item.appendChild(text);
+        // announced, not just shown: load failures otherwise pass silently
+        // for screen-reader visitors
+        this._el.content_item.setAttribute("role", "alert");
 
         // After Loaded
         this.onLoaded(true);
@@ -312,27 +483,38 @@ export class MediaBase {
     onMediaLoaded(e?: unknown) {
         this._state.media_loaded = true;
         this.fire("media_loaded", this.data);
+        const width = (this._el.content_item?.offsetWidth ?? 0) + "px";
         if (this._el.credit) {
-            this._el.credit.style.width = this._el.content_item.offsetWidth + "px";
+            this._el.credit.style.width = width;
         }
         if (this._el.caption) {
-            this._el.caption.style.width = this._el.content_item.offsetWidth + "px";
+            this._el.caption.style.width = width;
         }
     }
 
-    showMeta(credit?: unknown, caption?: unknown) {
+    /** Render the media credit and caption, if the slide has them. */
+    showMeta(): void {
+        // slideshow tours may hide the info block (show_info: false);
+        // internal documents always render it
+        if (!shouldShowInfo(this.options)) return;
         this._state.show_meta = true;
-        // Credit
-        if (this.data.credit && this.data.credit !== "" && !this._el.credit) {
+        // Credit and caption are author-supplied strings that may legitimately
+        // contain formatting (they are documented as HTML), so they go through
+        // the same sanitizer as the slide text rather than straight to
+        // innerHTML — the JSON is untrusted input, and these were the two
+        // easiest stored-XSS sinks in the viewer.
+        const credit = this._credit();
+        if (credit && credit !== "" && !this._el.credit) {
             this._el.credit = Dom.create("div", "vco-credit", this._el.content_container);
-            this._el.credit.innerHTML = this.data.credit;
+            this._el.credit.appendChild(sanitizeSlideText(credit));
             this.options.credit_height = this._el.credit.offsetHeight;
         }
 
         // Caption
-        if (this.data.caption && this.data.caption !== "" && !this._el.caption) {
+        const caption = this._caption();
+        if (caption && caption !== "" && !this._el.caption) {
             this._el.caption = Dom.create("div", "vco-caption", this._el.content_container);
-            this._el.caption.innerHTML = this.data.caption;
+            this._el.caption.appendChild(sanitizeSlideText(caption));
             this.options.caption_height = this._el.caption.offsetHeight;
         }
     }
@@ -347,6 +529,21 @@ export class MediaBase {
 
     /*	Private Methods
 	================================================== */
+    /** The media URL, normalised to a string. */
+    _url(): string {
+        return typeof this.data.url === "string" ? this.data.url : "";
+    }
+
+    /** The media caption, or null when the slide has none. */
+    _caption(): string | null {
+        return typeof this.data.caption === "string" ? this.data.caption : null;
+    }
+
+    /** The media credit, or null when the slide has none. */
+    _credit(): string | null {
+        return typeof this.data.credit === "string" ? this.data.credit : null;
+    }
+
     _initLayout() {
         // Message
         this.message = new Message({}, this.options);
@@ -360,15 +557,29 @@ export class MediaBase {
         );
 
         // Link
-        if (this.data.link && this.data.link !== "") {
+        // The link target comes from the storymap JSON, so it has to pass the
+        // same protocol check as every other author-supplied URL — otherwise a
+        // `javascript:` href is a click-through XSS. A rejected link falls
+        // through to the unlinked layout below rather than rendering a
+        // dead anchor.
+        // (`_el.content` starts as a truthy `{}` placeholder, so the branch is
+        // tracked with a local flag rather than a truthiness test.)
+        const raw_link = this.data.link;
+        const href = typeof raw_link === "string" ? validateWebURL(raw_link) : null;
+        if (href) {
             this._el.link = Dom.create("a", "vco-media-link", this._el.content_container);
             const link = this._el.link as HTMLAnchorElement;
-            link.href = this.data.link;
+            link.href = href;
             if (this.data.link_target && this.data.link_target !== "") {
                 link.target = this.data.link_target;
             } else {
                 link.target = "_blank";
             }
+            if (link.target === "_blank") {
+                // rel=noopener so the opened page cannot reach back through
+                // window.opener
+                link.rel = "noopener noreferrer";
+            }
 
             this._el.content = Dom.create("div", "vco-media-content", this._el.link);
         } else {
@@ -402,7 +613,7 @@ export class MediaBase {
     _stopMedia() {}
 }
 
-export class Media extends Evented(MediaBase) {
+export class Media extends Evented<MediaEvents, typeof MediaBase>(MediaBase) {
     constructor(...args: ConstructorParameters<typeof MediaBase>) {
         super(...args);
     }

package/src/media/embedId.ts

@@ -0,0 +1,110 @@
+/*	embedId
+	Provider id extraction.
+
+	Each media type used to roll its own: six different ways of stripping the
+	query string, three different failure modes (throw an Error, throw a bare
+	string, or log a warning and carry on with `undefined`), and a fourth
+	divergence between the URL shapes the code accepted and the ones
+	`MediaType`'s routing regex actually matched.
+
+	These helpers are the single implementation. Each returns null when the
+	url does not carry that provider's id, and the caller decides how to
+	report it.
+================================================== */
+
+/** Strip the query string and fragment. */
+function withoutQuery(url: string): string {
+    return url.split(/[?#]/)[0];
+}
+
+/**
+ * The first path segment after any of `markers`, with the query string
+ * removed. Returns null when none of the markers is present.
+ */
+export function segmentAfter(url: string, ...markers: RegExp[]): string | null {
+    for (const marker of markers) {
+        const match = url.match(marker);
+        if (match) {
+            const rest = url.slice((match.index ?? 0) + match[0].length);
+            const segment = withoutQuery(rest).split("/")[0];
+            if (segment) {
+                return segment;
+            }
+        }
+    }
+    return null;
+}
+
+/** A query parameter, via the platform parser rather than a hand-rolled split. */
+export function queryParam(url: string, name: string): string | null {
+    try {
+        return new URL(url).searchParams.get(name);
+    } catch {
+        // not an absolute URL; fall back to the raw query string
+        const query = url.split("?")[1];
+        if (!query) return null;
+        for (const pair of query.split("&")) {
+            const [key, value] = pair.split("=");
+            if (key === name) {
+                return value ?? "";
+            }
+        }
+        return null;
+    }
+}
+
+/** YouTube video id: watch, embed, short, shorts, live and youtu.be links. */
+export function youtubeId(url: string): string | null {
+    const fromQuery = queryParam(url, "v");
+    if (fromQuery) {
+        return fromQuery;
+    }
+    return segmentAfter(
+        url,
+        /youtu\.be\//i,
+        /\/embed\//i,
+        /\/shorts\//i,
+        /\/live\//i,
+        /\/v\//i,
+        /[?&]v=/i,
+    );
+}
+
+/**
+ * Vimeo video id. Watch URLs are the bare `vimeo.com/<id>` form, so the
+ * explicit `/video/` path alone is not enough — the previous implementation
+ * split on `video\/|\/\/vimeo\.com\//` and relied on the second alternative.
+ * Non-numeric pages (channels, albums, showcases) are rejected.
+ */
+export function vimeoId(url: string): string | null {
+    const explicit = segmentAfter(url, /vimeo\.com\/video\//i, /player\.vimeo\.com\/video\//i);
+    if (explicit) {
+        return explicit;
+    }
+    return url.match(/vimeo\.com\/(\d+)(?:$|[/?#])/i)?.[1] ?? null;
+}
+
+/** Dailymotion video id from a watch or embed link. */
+export function dailymotionId(url: string): string | null {
+    return segmentAfter(url, /dailymotion\.com\/video\//i, /dai\.ly\//i, /\/embed\/video\//i);
+}
+
+/** Flickr photo id from a photo page URL. */
+export function flickrId(url: string): string | null {
+    const id = segmentAfter(url, /flickr\.com\/photos\/[^/]+\//i);
+    if (id && /^\d+$/.test(id)) {
+        return id;
+    }
+    return null;
+}
+
+/** Tweet id from a twitter.com or x.com status URL. */
+export function tweetId(url: string): string | null {
+    return segmentAfter(url, /\/status(?:es)?\//i);
+}
+
+/** Tweet author (the profile segment before `/status/<id>`), or null. */
+export function tweetAuthor(url: string): string | null {
+    const match = /(?:twitter\.com|x\.com)\/([^\s/?#]+)\/status(?:es)?\//i.exec(url);
+    return match ? match[1] : null;
+}