@projektemacher/storymapjs 0.10.7 → 0.11.0

package/src/media/types/Image.ts

@@ -1,6 +1,31 @@
 import { Media } from "../Media";
 import Dom from "../../dom/Dom";
-import { Language } from "../../language/Language";
+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.
@@ -8,18 +33,24 @@ import { Language } from "../../language/Language";
 ================================================== */
 
 export default class Image extends Media {
+    /** 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();
 
-        // Link
-        if (this.data.link) {
+        // 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 = this.data.link;
+            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",
@@ -33,17 +64,64 @@ export default class Image extends Media {
             );
         }
 
-        // 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);
 
-        (this._el.content_item as HTMLImageElement).src = this.data.url;
+        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
     }
+
+    _disposeMedia(): void {
+        if (this._onLoad) {
+            this._el.content_item?.removeEventListener("load", this._onLoad);
+            this._onLoad = null;
+        }
+    }
 }

package/src/media/types/Juxtapose.ts

@@ -1,6 +1,6 @@
 import { Media } from "../Media";
 import Dom from "../../dom/Dom";
-import { Language } from "../../language/Language";
+import { buildIframe } from "../EmbedUtil";
 
 /*	Media.Juxtapose
 	Embeds a JuxtaposeJS before/after slider (issue #360)
@@ -11,7 +11,7 @@ export default class Juxtapose 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(
@@ -20,13 +20,22 @@ export default class Juxtapose extends Media {
             this._el.content,
         );
 
-        // published Juxtapose URLs are iframe-ready embeds
-        this._el.content_item.innerHTML = `<iframe src="${this.data.url}" />`;
+        // 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._el.content_item.style.height = this.options.height + "px";
+        this._sizeContentItemToOptionHeight();
     }
 }

package/src/media/types/SoundCloud.ts

@@ -1,6 +1,6 @@
 import { Media } from "../Media";
 import Dom from "../../dom/Dom";
-import { Language } from "../../language/Language";
+import { sanitizeSlideText } from "../EmbedUtil";
 
 /*	Media.SoundCloud
 ================================================== */
@@ -8,18 +8,19 @@ import { Language } from "../../language/Language";
 /*	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;
+    declare "widget": SoundCloudWidget | null;
 
     /*	Load the media
 	================================================== */
     async _loadMedia() {
         // Loading Message
-        this.message.updateMessage(Language.messages.loading + " " + this.options.media_name);
+        this.loadingMessage();
 
         // Create Dom element
         this._el.content_item = Dom.create(
@@ -29,7 +30,7 @@ export default class SoundCloud extends Media {
         );
 
         // Get Media ID
-        this.media_id = this.data.url;
+        this.media_id = this._url();
 
         // API URL
         const api_url = "https://soundcloud.com/oembed?url=" + this.media_id + "&format=json";
@@ -56,14 +57,24 @@ export default class SoundCloud extends Media {
             this.loadErrorDisplay("Unable to load this track.");
             return;
         }
-        this._el.content_item.innerHTML = data.html;
+        // 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(this._el.content_item.querySelector("iframe"));
+        this.widget = sc.Widget(content_item.querySelector("iframe"));
 
         // After Loaded
         this.onLoaded();
@@ -74,4 +85,15 @@ export default class SoundCloud extends Media {
             this.widget?.pause();
         }
     }
+
+    /** Unbind the widget so it stops playing once the slide is gone. */
+    _disposeMedia() {
+        try {
+            this.widget?.unbind?.();
+        } catch (err) {
+            console.warn("StoryMapJS: error unbinding SoundCloud widget.", err);
+        }
+        this.widget = null;
+        this.soundCloudCreated = false;
+    }
 }

package/src/media/types/Text.ts

@@ -1,6 +1,7 @@
-import { mergeData, setData, htmlify, convertUnixTime } from "../../core/Util";
+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;
@@ -13,13 +14,21 @@ interface TextData {
 interface TextOptions {
     title?: boolean;
     text_align?: string;
+    /** BCP 47 tag for the slide text (from `StorymapSlide.language`). */
+    language?: string;
+}
+
+export interface TextEvents {
+    loaded: TextData;
+    added: TextData;
+    removed: TextData;
 }
 
 class TextBase {
     declare "_el": Record<string, HTMLElement>;
     declare "data": TextData;
     declare "options": TextOptions;
-    declare "fire": EventedInstance["fire"];
+    declare "fire": EventedInstance<TextEvents>["fire"];
 
     /*	Constructor
 	================================================== */
@@ -34,11 +43,14 @@ class TextBase {
             start_btn: {} as HTMLElement,
         };
 
-        // Data
+        // 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: "headline",
-            text: "text",
+            headline: "",
+            text: "",
         };
 
         // Options
@@ -46,13 +58,22 @@ class TextBase {
             title: false,
         };
 
-        setData(this, data);
+        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._el.container.id = this.data.uniqueid ?? "";
+        // Pronounce mixed-language slides correctly: the reader reports
+        // which language map it picked, and the DOM should say so too.
+        if (
+            typeof this.options.language === "string" &&
+            this.options.language !== "" &&
+            this.options.language !== "none"
+        ) {
+            this._el.container.setAttribute("lang", this.options.language);
+        }
 
         this._initLayout();
 
@@ -120,27 +141,31 @@ class TextBase {
             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
-        if (this.data.headline !== "") {
+        // 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.innerHTML = this.data.headline;
+            this._el.headline.appendChild(sanitizeSlideText(headline));
+        }
+
+        // Date (only rendered when the slide has one; issue #286). Emitted
+        // after the headline and as a <p> (issue #385 wave): an <h3> before
+        // the <h2> was a heading-order skip
+        if (this.data.date && this.data.date.created_time && this.data.date.created_time !== "") {
+            this._el.date = Dom.create("p", "vco-headline-date", this._el.content_container);
+            this.addDateText(convertUnixTime(this.data.date.created_time));
         }
 
-        // Text
-        if (this.data.text !== "") {
+        // 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(this.data.text);
+            text_content += htmlify(text);
 
             // Date
             if (
@@ -157,7 +182,7 @@ class TextBase {
             }
 
             this._el.content = Dom.create("div", "vco-text-content", this._el.content_container);
-            this._el.content.innerHTML = text_content;
+            this._el.content.appendChild(sanitizeSlideText(text_content));
         }
 
         // Fire event that the slide is loaded
@@ -165,7 +190,7 @@ class TextBase {
     }
 }
 
-export default class Text extends Evented(TextBase) {
+export default class Text extends Evented<TextEvents, typeof TextBase>(TextBase) {
     constructor(...args: ConstructorParameters<typeof TextBase>) {
         super(...args);
     }

package/src/media/types/Twitter.ts

@@ -1,6 +1,7 @@
 import { Media } from "../Media";
 import Dom from "../../dom/Dom";
-import { Language } from "../../language/Language";
+import { sanitizeSlideText } from "../EmbedUtil";
+import { tweetAuthor, tweetId } from "../embedId";
 import { loadJSONP, uniqueGlobalName } from "../../core/Load";
 
 /*	Media.Twitter
@@ -15,18 +16,21 @@ export default class Twitter 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("div", "vco-media-twitter", this._el.content);
 
-        // Get Media ID
-
-        const r = /(?:twitter\.com|x\.com)\/(.+?)\/status\/(\d+)/;
-        const match = r.exec(this.data.url);
-        if (match) {
-            this.user_id = match[1];
-            this.media_id = match[2];
+        // Get Media ID — routed here by MediaType, extracted by the shared
+        // helpers so the accepted shapes cannot diverge again. The id stays
+        // numeric-only, as before: anything else is not a status URL.
+        const media_id = tweetId(this._url());
+        const user_id = tweetAuthor(this._url());
+        if (media_id && user_id && /^\d+$/.test(media_id)) {
+            this.user_id = user_id;
+            this.media_id = media_id;
+        } else {
+            throw new Error("Invalid Twitter URL");
         }
         const callbackName = uniqueGlobalName(`twitterCallback_${this.media_id}`);
         const api_url = `https://api.twitter.com/1/statuses/oembed.json?id=${this.media_id}&include_entities=true&callback=${callbackName}`;
@@ -43,17 +47,22 @@ export default class Twitter extends Media {
 
     createMedia(d: unknown) {
         const data = d as { html: string; author_url: string; author_name: string };
-        let tweet = "",
-            tweet_text;
-
+        if (!data?.html) {
+            this.loadErrorDisplay("Unable to load this post.");
+            return;
+        }
+        // The oEmbed markup is positional: the date link follows the tweet text
+        // after a "—" separator. Every step below is optional so a markup
+        // change upstream degrades to a missing date/link rather than throwing.
+        const afterText = data.html.split("</p>&mdash;")[1] ?? "";
+        const tweetuser = data.author_url.split(/twitter\.com|x\.com\//)[1] ?? "";
+        const statusLink = afterText.split('<a href="')[1] ?? "";
+        const tweet_status_url = statusLink.split('">')[0] ?? "";
+        const tweet_status_date = (statusLink.split('">')[1] ?? "").split("</a>")[0] ?? "";
+
+        let tweet = "";
         //	TWEET CONTENT
-        tweet_text = data.html.split("</p>&mdash;")[0] + "</p></blockquote>";
-        // the oembed endpoint returns x.com URLs since the rebrand — parse both
-        const tweetuser = data.author_url.split(/twitter\.com|x\.com\//)[1];
-        const tweet_status_temp = data.html.split("</p>&mdash;")[1].split('<a href="')[1];
-        const tweet_status_url = tweet_status_temp.split('">')[0];
-        const tweet_status_date = tweet_status_temp.split('">')[1].split("</a>")[0];
-
+        let tweet_text = afterText ? data.html.split("</p>&mdash;")[0] + "</p></blockquote>" : "";
         // Open links in new window
         tweet_text = tweet_text.replace(/<a href/gi, '<a target="_blank" href');
 
@@ -84,7 +93,13 @@ export default class Twitter extends Media {
         tweet += "</div>";
 
         // Add to DOM
-        this._el.content_item.innerHTML = tweet;
+        // The whole tweet is assembled from the oEmbed response's own HTML
+        // plus five string-concatenated fields, and that API does not escape
+        // HTML — so the result is untrusted third-party markup and goes
+        // through the sanitizer. It also repairs the four unguarded
+        // positional splits above: a markup change upstream now degrades to a
+        // missing date instead of throwing.
+        this._el.content_item?.appendChild(sanitizeSlideText(tweet));
 
         // After Loaded
         this.onLoaded();

package/src/media/types/Video.ts

@@ -1,84 +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.Video
+	A <video> element with a single <source> child.
 ================================================== */
 
-export default class Video 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(
-            "video",
-            "vco-media-item vco-media-video 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 video with " + source_item.type,
-            ),
-        );
-        this.player_element = media_item;
-    }
-
-    // Update Media Display
-    _updateMediaDisplay() {
-        // video 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 = "video/";
-        if (!ext) {
-            return type;
-        }
-        switch (ext[1]) {
-            case "mp4":
-                type += "mp4";
-                break;
-            case "webm":
-                type += "webm";
-                break;
-            default:
-                type = "";
-                break;
-        }
-        return type;
+export default class Video extends HtmlMediaBase {
+    protected spec() {
+        return {
+            kind: "video" as HtmlMediaKind,
+            extensions: { mp4: "mp4", webm: "webm" },
+        };
     }
 }

package/src/media/types/Vimeo.ts

@@ -1,7 +1,6 @@
+import { vimeoId } from "../embedId";
 import { Media } from "../Media";
 import Dom from "../../dom/Dom";
-import { Language } from "../../language/Language";
-import { ratio } from "../../core/Util";
 
 /*	Media.Vimeo
 ================================================== */
@@ -14,7 +13,7 @@ export default class Vimeo 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,17 +23,19 @@ export default class Vimeo extends Media {
         );
 
         // Get Media ID
-        const parts = this.data.url.split(/video\/|\/\/vimeo\.com\//);
-        if (!parts[1]) {
+        this.media_id = vimeoId(this._url()) ?? "";
+        if (!this.media_id) {
             throw new Error("Invalid Vimeo URL");
         }
-        this.media_id = parts[1].split(/[?&]/)[0];
 
-        // API URL
+        // API URL — plain `&` separators. The HTML entity `&` is correct
+        // inside markup but is not decoded in a URL property, so Vimeo was
+        // receiving params literally named `amp;byline` / `amp;color` and
+        // ignoring them.
         const api_url =
             "https://player.vimeo.com/video/" +
             this.media_id +
-            "?api=1&title=0&byline=0&portrait=0&color=ffffff";
+            "?api=1&title=0&byline=0&portrait=0&color=ffffff";
 
         this.player = Dom.create("iframe", "", this._el.content_item) as HTMLIFrameElement;
         this.player.width = "100%";
@@ -48,8 +49,7 @@ export default class Vimeo 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() {
@@ -59,7 +59,7 @@ export default class Vimeo extends Media {
                 "https://player.vimeo.com",
             );
         } catch (err) {
-            console.log(err);
+            console.warn("StoryMapJS: error pausing Vimeo player.", err);
         }
     }
 }