@projektemacher/storymapjs 0.10.7 → 0.10.8

package/src/slider/StorySlider.ts

@@ -1,15 +1,22 @@
-import { mergeData, unique_ID, findArrayNumberByUniqueID, parseCssColor, slideTransitionDuration } from "../core/Util";
+import {
+    mergeData,
+    unique_ID,
+    findArrayNumberByUniqueID,
+    parseCssColor,
+    slideTransitionDuration,
+    prefersReducedMotion,
+} from "../core/Util";
 import { Evented, type EventedInstance } from "../core/mixins";
 import Dom from "../dom/Dom";
 import { DomEvent } from "../dom/DomEvent";
 import { easeInOutQuint } from "../animation/easings";
 import SlideNav from "./SlideNav";
 import Slide from "./Slide";
-import Animate from "morpheus";
+import Animate from "../animation/tween";
 import Swipable from "../ui/Swipable";
 import Message from "../ui/Message";
 import { Browser } from "../core/Browser";
-import { Language } from "../language/Language";
+import { Language, isRtl } from "../language/Language";
 import { AnimationHandle, StorymapData, StorymapSlide } from "../types";
 
 /*	StorySlider
@@ -43,23 +50,37 @@ interface StorySliderOptions {
     skinny_size?: number;
     call_to_action?: boolean;
     call_to_action_text?: string;
-    dragging?: boolean;
     trackResize?: boolean;
     [key: string]: unknown;
 }
 
+/**
+ * The slider's element cache. `live_region` only exists when the slide
+ * announcements are enabled (the `a11y` option), so it starts out null.
+ */
+type StorySliderElements = {
+    container: HTMLElement;
+    /** Created in `_initLayout`; the slide background layer. */
+    background: HTMLElement;
+    slider_container_mask: HTMLElement;
+    slider_container: HTMLElement;
+    slider_item_container: HTMLElement;
+    live_region: HTMLElement | null;
+};
+
 interface SlideBackgroundChange {
     color_value?: string;
     image?: boolean;
 }
 
 class StorySliderBase {
-    declare "_el": Record<string, HTMLElement>;
+    declare "_el": StorySliderElements;
     declare "_nav": { previous: SlideNav; next: SlideNav };
     declare "slide_spacing": number;
     declare "_slides": Slide[];
     declare "_swipable": Swipable;
-    declare "preloadTimer": ReturnType<typeof setTimeout>;
+    declare "preloadTimer": ReturnType<typeof setTimeout> | undefined;
+    declare "preloadIdleHandle": number | undefined;
     declare "_message": Message;
     declare "current_slide": number;
     declare "current_bg_color": string | null;
@@ -82,10 +103,11 @@ class StorySliderBase {
         // DOM ELEMENTS
         this._el = {
             container: {} as HTMLElement,
-            background: {} as HTMLElement,
             slider_container_mask: {} as HTMLElement,
             slider_container: {} as HTMLElement,
             slider_item_container: {} as HTMLElement,
+            background: {} as HTMLElement,
+            live_region: null,
         };
 
         this._nav = {
@@ -120,8 +142,6 @@ class StorySliderBase {
             // animation
             duration: 1000,
             ease: easeInOutQuint,
-            // interaction
-            dragging: true,
             trackResize: true,
         };
 
@@ -131,7 +151,11 @@ class StorySliderBase {
             this.options.id = unique_ID(6, "vco");
         } else {
             this.options.id = elem;
-            this._el.container = Dom.get(elem);
+            const found = Dom.get(elem);
+            if (!found) {
+                throw new Error("StoryMapJS: no element with id " + elem);
+            }
+            this._el.container = found;
         }
 
         if (!this._el.container.id) {
@@ -142,6 +166,10 @@ class StorySliderBase {
         this.animator = null;
         this.animator_background = null;
 
+        // Preload scheduling handles, at most one of which is ever live
+        this.preloadTimer = undefined;
+        this.preloadIdleHandle = undefined;
+
         // Merge Data and Options
         mergeData(this.options, options);
         mergeData(this.data, data);
@@ -183,14 +211,31 @@ class StorySliderBase {
     /*	Create Slides
 	================================================== */
     _createSlides(array: StorymapData["slides"]) {
+        // a storymap with no slides array is a valid (if empty) document —
+        // the schema allows it and the map still renders
+        if (!array || array.length === 0) {
+            return;
+        }
         for (let i = 0; i < array.length; i++) {
-            if (array[i].uniqueid === "") {
-                array[i].uniqueid = unique_ID(6, "vco-slide");
-            }
+            // The id is generated into a per-slide copy, not written back into
+            // `array`. StoryMap hands its own `this.data` down without cloning
+            // it, so writing here would be visible to every other viewer built
+            // from the same parsed document: the second one would find the id
+            // already set, adopt it, and emit a duplicate element id — the id
+            // becomes a DOM id in Slide, Text and Media.
+            //
+            // The guard is falsy rather than `=== ""`: `uniqueid` is optional
+            // in the schema and absent from 47 of the 48 bundled fixtures, so
+            // an empty-string test never fired and every slide ended up with
+            // an empty id.
+            const needs_id = !array[i].uniqueid;
+            const slide_data = needs_id
+                ? { ...array[i], uniqueid: unique_ID(6, "vco-slide") }
+                : array[i];
             if (i === 0) {
-                this._createSlide(array[i], true);
+                this._createSlide(slide_data, true);
             } else {
-                this._createSlide(array[i], false);
+                this._createSlide(slide_data, false);
             }
         }
     }
@@ -213,26 +258,70 @@ class StorySliderBase {
     /*	Navigation
 	================================================== */
     goToId(n: string | number, fast?: boolean, displayupdate?: boolean) {
-        let _n;
+        let _n: number;
         if (typeof n == "string" || (n as unknown) instanceof String) {
             _n = findArrayNumberByUniqueID(String(n), this._slides, "uniqueid");
+            if (_n === -1) {
+                // unknown id: stay where we are rather than jumping to slide 0
+                console.warn("StoryMapJS: no slide with uniqueid", n);
+                return;
+            }
         } else {
             _n = n;
         }
         this.goTo(_n, fast, displayupdate);
     }
 
-    goTo(n: number, fast?: boolean, displayupdate?: boolean) {
-        this.changeBackground({ color_value: "", image: false });
-
-        // Clear Preloader Timer (covers both the setTimeout fallback and
-        // the requestIdleCallback handle below — both are numbers)
-        if (this.preloadTimer) {
+    /**
+     * Cancel the pending preload, whichever scheduling primitive queued it.
+     *
+     * The two handles are kept apart deliberately: they are both numbers, so
+     * calling `clearTimeout` on an idle-callback handle "works" by accident
+     * while actually leaking the callback, and the reverse leaves a live
+     * timeout behind.
+     */
+    _cancelPreload() {
+        if (this.preloadTimer !== undefined) {
             clearTimeout(this.preloadTimer);
+            this.preloadTimer = undefined;
+        }
+        if (this.preloadIdleHandle !== undefined) {
             (
                 window as unknown as { cancelIdleCallback?: (handle: number) => void }
-            ).cancelIdleCallback?.(this.preloadTimer as unknown as number);
+            ).cancelIdleCallback?.(this.preloadIdleHandle);
+            this.preloadIdleHandle = undefined;
         }
+    }
+
+    /**
+     * Release listeners, timers and running animations. Called by
+     * `StoryMap.dispose()`; the slider must not be used afterwards.
+     */
+    dispose() {
+        this._cancelPreload();
+        if (this._swipable) {
+            this._swipable.dispose();
+        }
+        DomEvent.removeListener(this._el.container, "keydown", this._onKeyDown, this);
+        // Web Animations API (morpheus replacement): stop slide transitions
+        // mid-flight so they don't keep running against a detached tree
+        for (const el of [this._el.container, this._el.slider_container, this._el.background]) {
+            el?.getAnimations?.().forEach((a) => a.cancel());
+        }
+        for (const slide of this._slides) {
+            slide.dispose();
+        }
+        this._nav.previous?.dispose();
+        this._nav.next?.dispose();
+        this._message?.dispose();
+        this._slides = [];
+    }
+
+    goTo(n: number, fast?: boolean, displayupdate?: boolean) {
+        this.changeBackground({ color_value: "", image: false });
+
+        // Clear Preloader Timer
+        this._cancelPreload();
 
         // Set Slide Active State
         for (let i = 0; i < this._slides.length; i++) {
@@ -255,7 +344,7 @@ class StorySliderBase {
                 this._swipable.stopMomentum();
             }
 
-            if (fast) {
+            if (fast || prefersReducedMotion()) {
                 this._el.slider_container.style.left = -(this.slide_spacing * n) + "px";
                 this._onSlideChange(displayupdate);
             } else {
@@ -274,6 +363,14 @@ class StorySliderBase {
                 this._slides[this.current_slide].setActive(true);
             }
 
+            // Announce the slide change to assistive tech (issue #385 wave):
+            // the headline or the slide number, replacing the previous text
+            if (this._el.live_region) {
+                const headline = this._slides[this.current_slide]?.title;
+                this._el.live_region.textContent =
+                    headline || `Slide ${this.current_slide + 1} of ${this._slides.length}`;
+            }
+
             // Preload the next slide's media right away so its load clock,
             // network and iframe build elapse during this transition (and the
             // dwell time) instead of starting after arrival
@@ -304,9 +401,9 @@ class StorySliderBase {
                 requestIdleCallback?: (cb: () => void, opts?: { timeout: number }) => number;
             };
             if (w.requestIdleCallback) {
-                this.preloadTimer = w.requestIdleCallback(() => this.preloadSlides(), {
+                this.preloadIdleHandle = w.requestIdleCallback(() => this.preloadSlides(), {
                     timeout: this.options.duration,
-                }) as unknown as ReturnType<typeof setTimeout>;
+                });
             } else {
                 this.preloadTimer = setTimeout(() => {
                     this.preloadSlides();
@@ -495,8 +592,6 @@ class StorySliderBase {
 
         this.options.layout = _layout;
 
-        this.slide_spacing = this.options.width * 2;
-
         if (width) {
             this.options.width = width;
         } else {
@@ -509,6 +604,13 @@ class StorySliderBase {
             this.options.height = this._el.container.offsetHeight;
         }
 
+        // Slide positions and the goTo() translation are both derived from
+        // slide_spacing, so it has to be recomputed *after* the new width is
+        // known. Reading it before meant a bare updateDisplay() (no explicit
+        // width, i.e. after a container resize) positioned every slide for the
+        // previous width.
+        this.slide_spacing = this.options.width * 2;
+
         // position navigation
         const nav_pos = this.options.height / 2;
         this._nav.next.setPosition({ top: nav_pos });
@@ -525,18 +627,19 @@ class StorySliderBase {
     }
 
     _introInterface() {
-        if (this.options.call_to_action) {
-            let _str = Language.messages.start;
-            if (this.options.call_to_action_text !== "") {
-                _str = this.options.call_to_action_text;
-            }
-            this._slides[0].addCallToAction(_str);
-            this._slides[0].on("call_to_action", this.next, this);
-        }
-
-        if (this.options.width <= this.options.skinny_size) {
-            // hidden when skinny
-        } else {
+        if (this.options.call_to_action && this._slides.length > 0) {
+            // `!== ""` treated an absent key as a custom string, so a
+            // standalone StorySlider rendered the literal text "undefined".
+            const _str =
+                typeof this.options.call_to_action_text === "string" &&
+                this.options.call_to_action_text !== ""
+                    ? this.options.call_to_action_text
+                    : Language.messages.start;
+            this._slides[0]?.addCallToAction(_str);
+            this._slides[0]?.on("call_to_action", this.next, this);
+        }
+
+        if (!(this.options.width <= (this.options.skinny_size ?? 0))) {
             this._nav.next.updatePosition(
                 { right: "130" },
                 false,
@@ -579,6 +682,12 @@ class StorySliderBase {
             this._el.slider_container,
         );
 
+        // Accessibility: a polite live region announcing slide changes to
+        // screen readers (visually hidden)
+        this._el.live_region = Dom.create("div", "vco-sr-only", this._el.container) as HTMLElement;
+        this._el.live_region.setAttribute("aria-live", "polite");
+        this._el.live_region.setAttribute("role", "status");
+
         // Update Size
         this.options.width = this._el.container.offsetWidth;
         this.options.height = this._el.container.offsetHeight;
@@ -611,11 +720,13 @@ class StorySliderBase {
             this._swipable.enable();
 
             // Message
+            // the swipe hint icon mirrors in right-to-left locales (issue #269)
+            const rtl = isRtl();
             this._message = new Message(
                 {},
                 {
                     message_class: "vco-message-full",
-                    message_icon_class: "vco-icon-swipe-left",
+                    message_icon_class: rtl ? "vco-icon-swipe-right" : "vco-icon-swipe-left",
                 },
             );
             this._message.updateMessage(Language.buttons.swipe_to_navigate);
@@ -666,7 +777,7 @@ class StorySliderBase {
 
     _initData() {
         // Create Slides and then add them
-        this._createSlides(this.data.slides);
+        this._createSlides(this.data.slides ?? []);
     }
 
     /*	Events