@projektemacher/storymapjs 0.10.8 → 0.11.0

package/src/slider/Slide.ts

@@ -1,9 +1,10 @@
-import { mergeData } from "../core/Util";
+import { mergeData, prefersReducedMotion } from "../core/Util";
 import { DomMixed, Evented, type EventedInstance } from "../core/mixins";
 import { DomEvent } from "../dom/DomEvent";
 import Dom from "../dom/Dom";
 import { easeInSpline } from "../animation/easings";
 import MediaType from "../media/MediaType";
+import type { MediaEvents } from "../media/Media";
 import { sanitizeSlideText } from "../media/EmbedUtil";
 import Text from "../media/types/Text";
 import { Browser } from "../core/Browser";
@@ -50,9 +51,26 @@ interface MediaInstance {
     stopMedia: () => void;
     updateDisplay: (w?: number, h?: number, l?: string) => void;
     dispose?: () => void;
-    on?: EventedInstance["on"];
-    off?: EventedInstance["off"];
+    on?: EventedInstance<MediaEvents>["on"];
+    off?: EventedInstance<MediaEvents>["off"];
     _state?: { loaded?: boolean; eager?: boolean };
+    /** Per-item consent identity: each item is built with its own
+        `media_name`/`media_type`, which `hasPlayableMedia` reads back (#358). */
+    options?: { media_type?: string };
+}
+
+export interface SlideBackgroundState {
+    image: boolean;
+    color: boolean;
+    color_value: string;
+}
+
+export interface SlideEvents {
+    background_change: SlideBackgroundState;
+    call_to_action: Event;
+    loaded: StorymapSlide;
+    added: StorymapSlide;
+    removed: StorymapSlide;
 }
 
 interface SlideHas {
@@ -60,32 +78,33 @@ interface SlideHas {
     text: boolean;
     media: boolean;
     title: boolean;
-    background: {
-        image: boolean;
-        color: boolean;
-        color_value: string;
-    };
+    background: SlideBackgroundState;
 }
 
 class SlideBase {
     /** `call_to_action` is only created when the slide shows one. */
     declare "_el": SlideElements;
+    /** The primary media item; always `_medias[0]` when present (#358). */
     declare "_media": MediaInstance | null;
-    declare "_mediaclass": unknown;
+    /** Every media item: `[media, ...media_extra]` with a non-empty url. */
+    declare "_medias": MediaInstance[];
     declare "_text": Text;
     declare "_state": { loaded: boolean };
     declare "_scroll_hint": HTMLElement | null;
     declare "_scroll_hint_dismissed": boolean;
     declare "_onSlideScrollBound": EventListener;
-    /** Every `media_ended` handler registered via `onMediaEnded`, kept so `dispose()` can remove them. */
-    declare "_media_ended_fns": (() => void)[];
+    /** Every `media_ended` handler registered via `onMediaEnded`, with the
+        media it was attached to so `dispose()` can remove them. */
+    declare "_media_ended_fns": { media: MediaInstance; fn: () => void }[];
+    /** The `media_loaded` handlers below, kept for the same reason. */
+    declare "_media_loaded_fns": { media: MediaInstance; fn: () => void }[];
     declare "has": SlideHas;
     declare "title": string;
     declare "data": StorymapSlide;
     declare "options": SlideOptions;
     declare "active": boolean;
     declare "animator": unknown;
-    declare "fire": EventedInstance["fire"];
+    declare "fire": EventedInstance<SlideEvents>["fire"];
     declare "onLoaded": () => void;
 
     //_el: {},
@@ -105,7 +124,7 @@ class SlideBase {
 
         // Components
         this._media = null;
-        this._mediaclass = {};
+        this._medias = [];
         this._text = {} as Text;
 
         // State
@@ -161,6 +180,7 @@ class SlideBase {
 
         this._onSlideScrollBound = null as unknown as EventListener;
         this._media_ended_fns = [];
+        this._media_loaded_fns = [];
         mergeData(this.options, options);
         mergeData(this.data, data);
 
@@ -195,13 +215,17 @@ class SlideBase {
         }
         this._el.container?.getAnimations?.().forEach((a) => a.cancel());
         // the media_ended handlers registered via onMediaEnded() live on the
-        // media object, which outlives this slide once nulled — remove them
+        // media objects, which outlive this slide once nulled — remove them
         // here or a disposed slide's advance closure fires on a later ended
-        for (const fn of this._media_ended_fns) {
-            this._media?.off?.("media_ended", fn);
+        this.clearMediaEnded();
+        for (const { media, fn } of this._media_loaded_fns) {
+            media.off?.("media_loaded", fn);
         }
-        this._media_ended_fns = [];
-        this._media?.dispose?.();
+        this._media_loaded_fns = [];
+        for (const media of this._medias) {
+            media.dispose?.();
+        }
+        this._medias = [];
         this._media = null;
         this._el.container?.remove();
     }
@@ -209,6 +233,19 @@ class SlideBase {
     setActive(is_active: boolean) {
         this.active = is_active;
 
+        // Off-screen slides are translated away but stay in the DOM, so a
+        // screen reader would read every slide's headline, body and caption.
+        // Hide inactive slides from assistive tech next to the flip that
+        // already marks them inactive; `inert` additionally drops their
+        // controls from keyboard reach. Neither affects loading: preloaded
+        // media (including iframes) still builds and fetches underneath.
+        this._el.container.setAttribute("aria-hidden", String(!is_active));
+        if (is_active) {
+            this._el.container.removeAttribute("inert");
+        } else {
+            this._el.container.setAttribute("inert", "");
+        }
+
         if (this.active) {
             if (this.data.background) {
                 this.fire("background_change", this.has.background);
@@ -219,8 +256,10 @@ class SlideBase {
             // the active slide's images load eagerly: media built after this
             // point (the 1200ms load timer) honors the flag, already-built
             // images are upgraded below
-            if (this._media?._state) {
-                this._media._state.eager = true;
+            for (const media of this._medias) {
+                if (media._state) {
+                    media._state.eager = true;
+                }
             }
             this.loadMedia();
             this._eagerLoadImages();
@@ -236,8 +275,10 @@ class SlideBase {
     }
 
     loadMedia() {
-        if (this._media && !this._state.loaded) {
-            this._media.loadMedia();
+        if (this._medias.length > 0 && !this._state.loaded) {
+            for (const media of this._medias) {
+                media.loadMedia();
+            }
             this._state.loaded = true;
         }
     }
@@ -254,29 +295,62 @@ class SlideBase {
     }
 
     stopMedia() {
-        if (this._media && this._state.loaded) {
-            try {
-                this._media.stopMedia();
-            } catch (e: unknown) {
-                // Some sort of race condition or other ordering condition can cause
-                // an error when the preview tab is selected in the editor due to
-                // the stopped media not being properly formed.
-                if (
-                    (e as Error).message === "this._el.content_item.querySelector is not a function"
-                ) {
-                    console.log("Ignoring error in editor context: " + (e as Error).message);
-                } else {
-                    throw e;
+        if (this._medias.length > 0 && this._state.loaded) {
+            for (const media of this._medias) {
+                // An audio bed that outlives its slide
+                // (`media.stopOnExit: false`, slideshow ambient audio) keeps
+                // playing; StoryMap stops it when another slide claims audio.
+                // Slideshow-only: internal documents always stop.
+                const mediaData = (media as unknown as { data?: { stopOnExit?: boolean } }).data;
+                const sourced =
+                    (this.options as { slideshow_source?: unknown }).slideshow_source === true;
+                if (sourced && mediaData?.stopOnExit === false) continue;
+                try {
+                    media.stopMedia();
+                } catch (e: unknown) {
+                    // Some sort of race condition or other ordering condition can cause
+                    // an error when the preview tab is selected in the editor due to
+                    // the stopped media not being properly formed.
+                    if (
+                        (e as Error).message ===
+                        "this._el.content_item.querySelector is not a function"
+                    ) {
+                        console.warn("Ignoring error in editor context: " + (e as Error).message);
+                    } else {
+                        throw e;
+                    }
                 }
             }
-            // If the media load never started (its pending timer was
-            // cancelled on a quick pass-through), allow a revisit to retry
-            if (!this._media._state?.loaded) {
+            // If no media load started (pending timers were cancelled on a
+            // quick pass-through), allow a revisit to retry
+            if (!this._medias.some((media) => media._state?.loaded)) {
                 this._state.loaded = false;
             }
         }
     }
 
+    /**
+     * Stop this slide's ambient audio beds (`media.stopOnExit: false`) —
+     * called by the viewer when another slide claims the audio, not on every
+     * deactivation (see `stopMedia`, which skips them).
+     */
+    stopAmbientMedia() {
+        // Slideshow-only by construction (see stopMedia): without the source
+        // flag no media can be ambient, so there is nothing to stop.
+        if ((this.options as { slideshow_source?: unknown }).slideshow_source !== true) return;
+        if (this._medias.length > 0 && this._state.loaded) {
+            for (const media of this._medias) {
+                const mediaData = (media as unknown as { data?: { stopOnExit?: boolean } }).data;
+                if (mediaData?.stopOnExit !== false) continue;
+                try {
+                    media.stopMedia();
+                } catch {
+                    // same editor-context race stopMedia() already tolerates
+                }
+            }
+        }
+    }
+
     getBackground() {
         return this.has.background;
     }
@@ -287,20 +361,49 @@ class SlideBase {
      * its timer; everything else keeps the timer.
      */
     hasPlayableMedia(): boolean {
-        const kind = this.options.media_type as string | undefined;
-        return kind === "audio" || kind === "video";
+        if (this._medias.length === 0) {
+            const kind = this.options.media_type as string | undefined;
+            return kind === "audio" || kind === "video";
+        }
+        return this._medias.some((media) => {
+            const kind = media.options?.media_type;
+            return kind === "audio" || kind === "video";
+        });
     }
 
     /**
      * Call `fn` when this slide's media finishes playing. A slide with no
      * media — or media that cannot end — never calls it, which is why
      * `autoplay_media` keeps its timer as a fallback rather than waiting on
-     * an event that may not arrive.
+     * an event that may not arrive. Multi-media slides never call it either:
+     * waiting for the last of several items to end would stall autoplay, so
+     * the timer stays the advance for those (#358).
      */
     onMediaEnded(fn: () => void): void {
-        if (!this.hasPlayableMedia() || !this._media?.on) return;
-        this._media.on("media_ended", fn);
-        this._media_ended_fns.push(fn);
+        const playable = this._medias.filter((media) => {
+            const kind = media.options?.media_type;
+            return (kind === "audio" || kind === "video") && media.on;
+        });
+        if (playable.length !== 1) return;
+        playable[0].on?.("media_ended", fn);
+        this._media_ended_fns.push({ media: playable[0], fn });
+    }
+
+    /**
+     * Drop `media_ended` handlers armed by `onMediaEnded()` without waiting
+     * for dispose: re-arming (autoplay revisit) or navigating away must not
+     * accumulate stale advance closures — an ambient bed outliving its slide
+     * would otherwise fire a previous slide's advance on ending.
+     */
+    clearMediaEnded(): void {
+        for (const { media, fn } of this._media_ended_fns) {
+            try {
+                media.off?.("media_ended", fn);
+            } catch {
+                // same editor-context race stopMedia() already tolerates
+            }
+        }
+        this._media_ended_fns = [];
     }
 
     scrollToTop() {
@@ -327,7 +430,10 @@ class SlideBase {
             return;
         }
         if (!this._scroll_hint) {
-            this._scroll_hint = Dom.create("div", "vco-slide-scroll-hint", el);
+            // a real button for keyboard/AT operability (issue #385 wave)
+            this._scroll_hint = Dom.create("button", "vco-slide-scroll-hint", el);
+            this._scroll_hint.setAttribute("type", "button");
+            this._scroll_hint.setAttribute("aria-label", "Scroll down");
             this._scroll_hint.innerHTML = "<span class='vco-icon-arrow-down'></span>";
             DomEvent.addListener(this._scroll_hint, "click", this._onScrollHintClick, this);
         }
@@ -343,7 +449,10 @@ class SlideBase {
     _onScrollHintClick() {
         // scroll down one step, then hide (the scroll event dismisses too)
         const el = this._el.container;
-        el.scrollBy({ top: el.clientHeight * 0.8, behavior: "smooth" });
+        el.scrollBy({
+            top: el.clientHeight * 0.8,
+            behavior: prefersReducedMotion() ? "auto" : "smooth",
+        });
         this._scroll_hint_dismissed = true;
         this._hideScrollHint();
     }
@@ -359,11 +468,14 @@ class SlideBase {
     }
 
     addCallToAction(str: string) {
+        // a real button for keyboard/AT operability (issue #385 wave), like
+        // the menubar buttons; the classes carry the look
         this._el.call_to_action = Dom.create(
-            "div",
+            "button",
             "vco-slide-calltoaction",
             this._el.content_container,
         );
+        this._el.call_to_action.setAttribute("type", "button");
         // The text comes from `call_to_action_text` in the storymap JSON, so
         // it goes through the sanitizer like every other author string
         // instead of being concatenated into markup.
@@ -429,8 +541,13 @@ class SlideBase {
             }
         }
 
-        // Determine Assets for layout and loading
-        if (this.data.media && this.data.media.url && this.data.media.url !== "") {
+        // Determine Assets for layout and loading. A slide has media when
+        // any item — the primary or an extra — carries a non-empty url, so
+        // an empty `media.url` still yields false (#358).
+        const slide_media_items = [this.data.media, ...(this.data.media_extra ?? [])].filter(
+            (item): item is NonNullable<StorymapSlide["media"]> => !!item?.url,
+        );
+        if (slide_media_items.length > 0) {
             this.has.media = true;
         }
         if (this.data.text && this.data.text.text) {
@@ -441,19 +558,35 @@ class SlideBase {
             this.title = this.data.text.headline;
         }
 
-        // Create Media
-        const slide_media = this.data.media;
-        if (this.has.media && slide_media) {
-            // Determine the media type
-            slide_media.mediatype = MediaType(slide_media) as MediaTypeMatch;
-            this.options.media_name = slide_media.mediatype.name;
-            this.options.media_type = slide_media.mediatype.type;
-
-            // Create a media object using the matched class name
-            this._media = new slide_media.mediatype.cls(slide_media, this.options) as MediaInstance;
-            // loaded media changes the content height — the scroll hint
-            // may appear or disappear
-            this._media.on?.("media_loaded", () => this._updateScrollHint());
+        // Create Media (#358): the primary item plus every extra with a
+        // non-empty url, in order. Each item gets its own MediaType match and
+        // its own consent identity (media_name/media_type), so per-slide
+        // consent asks and the audio badge tell items apart.
+        const media_items = slide_media_items;
+        if (media_items.length > 0) {
+            for (const item of media_items) {
+                // Determine the media type
+                item.mediatype = MediaType(item) as MediaTypeMatch;
+                // Item 0 keeps the historical write-back: the marker icon
+                // class reads it off the slide data.
+                if (item === media_items[0]) {
+                    this.options.media_name = item.mediatype.name;
+                    this.options.media_type = item.mediatype.type;
+                }
+                // Create a media object using the matched class name
+                const media = new item.mediatype.cls(item, {
+                    ...this.options,
+                    media_name: item.mediatype.name,
+                    media_type: item.mediatype.type,
+                }) as MediaInstance;
+                // loaded media changes the content height — the scroll hint
+                // may appear or disappear
+                const on_loaded = () => this._updateScrollHint();
+                media.on?.("media_loaded", on_loaded);
+                this._media_loaded_fns.push({ media, fn: on_loaded });
+                this._medias.push(media);
+            }
+            this._media = this._medias[0] ?? null;
         }
 
         // Create Text
@@ -461,20 +594,37 @@ class SlideBase {
             this._text = new Text(this.data.text, {
                 title: this.has.title,
                 text_align: this.options.text_align as string | undefined,
+                language: this.data.language ?? undefined,
             });
         }
 
         // Add to DOM. Each branch has just established the members it uses
-        // (has.media -> _media, has.text/headline -> _text).
+        // (has.media -> _medias, has.text/headline -> _text). The media loop
+        // preserves the historical ordering: media-then-text, or
+        // text-then-media when there is a headline but no body text.
+        const medias = this._medias;
+        if (medias.length > 1) {
+            // `row` seats two items side by side; anything else stacks (D4)
+            const layout =
+                this.data.media_layout === "row" && medias.length === 2 ? "row" : "stack";
+            this._el.container.classList.add("vco-slide-media-multiple");
+            this._el.container.setAttribute("data-layout", layout);
+        }
         if (!this.has.text && !this.has.headline && this.has.media) {
             this._el.container.className += " vco-slide-media-only";
-            this._media?.addTo(this._el.content);
+            for (const media of medias) {
+                media.addTo(this._el.content);
+            }
         } else if (this.has.headline && this.has.media && !this.has.text) {
             this._el.container.className += " vco-slide-media-only";
             this._text.addTo(this._el.content);
-            this._media?.addTo(this._el.content);
+            for (const media of medias) {
+                media.addTo(this._el.content);
+            }
         } else if (this.has.text && this.has.media) {
-            this._media?.addTo(this._el.content);
+            for (const media of medias) {
+                media.addTo(this._el.content);
+            }
             this._text.addTo(this._el.content);
         } else if (this.has.text || this.has.headline) {
             this._el.container.className += " vco-slide-text-only";
@@ -530,15 +680,19 @@ class SlideBase {
             this.options.height = this._el.container.offsetHeight;
         }
 
-        if (this._media) {
+        if (this._medias.length > 0) {
             if (!this.has.text && this.has.headline) {
-                this._media.updateDisplay(
-                    this.options.width,
-                    this.options.height - this._text.headlineHeight(),
-                    layout,
-                );
+                for (const media of this._medias) {
+                    media.updateDisplay(
+                        this.options.width,
+                        this.options.height - this._text.headlineHeight(),
+                        layout,
+                    );
+                }
             } else {
-                this._media.updateDisplay(this.options.width, this.options.height, layout);
+                for (const media of this._medias) {
+                    media.updateDisplay(this.options.width, this.options.height, layout);
+                }
             }
         }
 
@@ -547,7 +701,11 @@ class SlideBase {
     }
 }
 
-export default class Slide extends DomMixed(Evented(SlideBase)) {
+const EventedSlideBase = Evented<SlideEvents, typeof SlideBase>(SlideBase);
+
+export default class Slide extends DomMixed<SlideEvents, typeof EventedSlideBase>(
+    EventedSlideBase,
+) {
     constructor(...args: ConstructorParameters<typeof SlideBase>) {
         super(...args);
     }

package/src/slider/SlideNav.ts

@@ -1,4 +1,4 @@
-import { mergeData } from "../core/Util";
+import { mergeData, prefersReducedMotion } from "../core/Util";
 import { DomMixed, Evented, type EventedInstance } from "../core/mixins";
 import Dom from "../dom/Dom";
 import Animate from "../animation/tween";
@@ -22,6 +22,13 @@ interface SlideNavOptions {
     [key: string]: unknown;
 }
 
+export interface SlideNavEvents {
+    clicked: SlideNavOptions;
+    loaded: SlideNavData;
+    added: SlideNavData;
+    removed: SlideNavData;
+}
+
 class SlideNavBase {
     declare "_el": Record<string, HTMLElement>;
     declare "mediatype": unknown;
@@ -29,7 +36,7 @@ class SlideNavBase {
     declare "options": SlideNavOptions;
     declare "animator": AnimationHandle | null;
     declare "animator_position": AnimationHandle | null;
-    declare "fire": EventedInstance["fire"];
+    declare "fire": EventedInstance<SlideNavEvents>["fire"];
 
     //_el: {},
 
@@ -112,7 +119,7 @@ class SlideNavBase {
         return_to_default: boolean,
     ) {
         const ani: AnimateOptions = {
-            duration: duration,
+            duration: prefersReducedMotion() ? 0 : duration,
             easing: ease,
             complete: () => {
                 this._onUpdatePositionComplete(return_to_default);
@@ -239,7 +246,11 @@ class SlideNavBase {
     }
 }
 
-export default class SlideNav extends DomMixed(Evented(SlideNavBase)) {
+const EventedSlideNavBase = Evented<SlideNavEvents, typeof SlideNavBase>(SlideNavBase);
+
+export default class SlideNav extends DomMixed<SlideNavEvents, typeof EventedSlideNavBase>(
+    EventedSlideNavBase,
+) {
     constructor(...args: ConstructorParameters<typeof SlideNavBase>) {
         super(...args);
     }