@projektemacher/storymapjs 0.10.6 → 0.10.8

package/src/slider/Slide.ts

@@ -0,0 +1,554 @@
+import { mergeData } 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 { sanitizeSlideText } from "../media/EmbedUtil";
+import Text from "../media/types/Text";
+import { Browser } from "../core/Browser";
+import { MediaTypeMatch, StorymapSlide, StorymapSlideBackground } from "../types";
+/*	VCO.Slide
+	Creates a slide. Takes a data object and
+	populates the slide with content.
+================================================== */
+
+/*	Slide options: the fields Slide itself sets or reads; everything
+	else merged in from the StorySlider options is absorbed by the
+	index signature. */
+interface SlideOptions {
+    duration: number;
+    slide_padding_lr: number;
+    ease: unknown;
+    width: number;
+    height: number;
+    skinny_size: number;
+    media_name?: string;
+    media_type?: string;
+    [key: string]: unknown;
+}
+
+/**
+ * The slide's element cache. `call_to_action` is null until the slide is told
+ * to show one (`addCallToAction`).
+ */
+type SlideElements = {
+    container: HTMLElement;
+    scroll_container: HTMLElement;
+    background: HTMLElement;
+    content_container: HTMLElement;
+    content: HTMLElement;
+    call_to_action: HTMLElement | null;
+};
+
+/*	Media instance surface as used by Slide; instances are created
+	dynamically via the matched MediaTypeMatch.cls constructor. Media is
+	Evented — "media_loaded" signals that content heights may have changed. */
+interface MediaInstance {
+    addTo: (container: HTMLElement) => void;
+    loadMedia: () => void;
+    stopMedia: () => void;
+    updateDisplay: (w?: number, h?: number, l?: string) => void;
+    dispose?: () => void;
+    on?: EventedInstance["on"];
+    off?: EventedInstance["off"];
+    _state?: { loaded?: boolean; eager?: boolean };
+}
+
+interface SlideHas {
+    headline: boolean;
+    text: boolean;
+    media: boolean;
+    title: boolean;
+    background: {
+        image: boolean;
+        color: boolean;
+        color_value: string;
+    };
+}
+
+class SlideBase {
+    /** `call_to_action` is only created when the slide shows one. */
+    declare "_el": SlideElements;
+    declare "_media": MediaInstance | null;
+    declare "_mediaclass": unknown;
+    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)[];
+    declare "has": SlideHas;
+    declare "title": string;
+    declare "data": StorymapSlide;
+    declare "options": SlideOptions;
+    declare "active": boolean;
+    declare "animator": unknown;
+    declare "fire": EventedInstance["fire"];
+    declare "onLoaded": () => void;
+
+    //_el: {},
+
+    /*	Constructor
+	================================================== */
+    constructor(data: StorymapSlide, options: Record<string, unknown>, title_slide?: boolean) {
+        // DOM Elements
+        this._el = {
+            container: {} as HTMLElement,
+            scroll_container: {} as HTMLElement,
+            background: {} as HTMLElement,
+            content_container: {} as HTMLElement,
+            content: {} as HTMLElement,
+            call_to_action: null,
+        };
+
+        // Components
+        this._media = null;
+        this._mediaclass = {};
+        this._text = {} as Text;
+
+        // State
+        this._state = {
+            loaded: false,
+        };
+        this._scroll_hint = null;
+        this._scroll_hint_dismissed = false;
+
+        this.has = {
+            headline: false,
+            text: false,
+            media: false,
+            title: false,
+            background: {
+                image: false,
+                color: false,
+                color_value: "",
+            },
+        };
+
+        this.has.title = title_slide === true;
+
+        this.title = "";
+
+        // Data
+        this.data = {
+            uniqueid: null,
+            background: null,
+            date: null,
+            location: null,
+            text: null,
+            media: null,
+        };
+
+        // Options
+        this.options = {
+            // animation
+            duration: 1000,
+            slide_padding_lr: 40,
+            ease: easeInSpline,
+            width: 600,
+            height: 600,
+            skinny_size: 650,
+            media_name: "",
+        };
+
+        // Actively Displaying
+        this.active = false;
+
+        // Animation Object
+        this.animator = {};
+
+        this._onSlideScrollBound = null as unknown as EventListener;
+        this._media_ended_fns = [];
+        mergeData(this.options, options);
+        mergeData(this.data, data);
+
+        this._initLayout();
+    }
+
+    /*	Adding, Hiding, Showing etc
+	================================================== */
+    show() {
+        // Positioning is handled by StorySlider._updateDisplay
+    }
+
+    hide() {}
+
+    /**
+     * Release the slide's listeners, media and DOM. Called by
+     * `StorySlider.dispose()`; the slide must not be used afterwards.
+     */
+    dispose() {
+        // the scroll listener was registered against a bound copy, so this
+        // only works because that reference was kept
+        if (this._onSlideScrollBound) {
+            this._el.container?.removeEventListener("scroll", this._onSlideScrollBound);
+            this._onSlideScrollBound = null as unknown as EventListener;
+        }
+        if (this._el.call_to_action) {
+            DomEvent.removeListener(this._el.call_to_action, "click", this._onCallToAction, this);
+        }
+        if (this._scroll_hint) {
+            DomEvent.removeListener(this._scroll_hint, "click", this._onScrollHintClick, this);
+            this._scroll_hint = null;
+        }
+        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
+        // 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._media_ended_fns = [];
+        this._media?.dispose?.();
+        this._media = null;
+        this._el.container?.remove();
+    }
+
+    setActive(is_active: boolean) {
+        this.active = is_active;
+
+        if (this.active) {
+            if (this.data.background) {
+                this.fire("background_change", this.has.background);
+            }
+            // the hint may re-appear on a revisit if the content still
+            // overflows (the dismissed flag resets per activation)
+            this._scroll_hint_dismissed = false;
+            // 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;
+            }
+            this.loadMedia();
+            this._eagerLoadImages();
+            this._updateScrollHint();
+        } else {
+            this.stopMedia();
+            this._hideScrollHint();
+        }
+    }
+
+    updateDisplay(w?: number, h?: number, l?: string) {
+        this._updateDisplay(w, h, l);
+    }
+
+    loadMedia() {
+        if (this._media && !this._state.loaded) {
+            this._media.loadMedia();
+            this._state.loaded = true;
+        }
+    }
+
+    /*  Perf: preloaded slide images are `lazy`; make them `eager` the
+        moment the slide becomes active so navigation never waits on a
+        deferred fetch (loading starts now, not on intersection). */
+    _eagerLoadImages() {
+        this._el.container
+            .querySelectorAll<HTMLImageElement>("img.vco-media-image")
+            .forEach((img) => {
+                img.loading = "eager";
+            });
+    }
+
+    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 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) {
+                this._state.loaded = false;
+            }
+        }
+    }
+
+    getBackground() {
+        return this.has.background;
+    }
+
+    /**
+     * True when this slide's media is a timed, playable one (audio or video).
+     * `autoplay_media` waits for such a slide's media to end instead of using
+     * its timer; everything else keeps the timer.
+     */
+    hasPlayableMedia(): boolean {
+        const kind = this.options.media_type as string | undefined;
+        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.
+     */
+    onMediaEnded(fn: () => void): void {
+        if (!this.hasPlayableMedia() || !this._media?.on) return;
+        this._media.on("media_ended", fn);
+        this._media_ended_fns.push(fn);
+    }
+
+    scrollToTop() {
+        this._el.container.scrollTop = 0;
+    }
+
+    /*	Scroll hint
+    ================================================== */
+    /**
+     * Show a bouncing downward arrow when the slide content overflows
+     * (scrollable) — the hint of "more below" for scrollbars that are not
+     * visible until touched. Hidden after the first scroll of any kind;
+     * tappable to scroll down one step.
+     */
+    _updateScrollHint() {
+        if (!this.active || this._scroll_hint_dismissed) {
+            this._hideScrollHint();
+            return;
+        }
+        const el = this._el.container;
+        const overflows = el.scrollHeight > el.clientHeight + 1;
+        if (!overflows) {
+            this._hideScrollHint();
+            return;
+        }
+        if (!this._scroll_hint) {
+            this._scroll_hint = Dom.create("div", "vco-slide-scroll-hint", el);
+            this._scroll_hint.innerHTML = "<span class='vco-icon-arrow-down'></span>";
+            DomEvent.addListener(this._scroll_hint, "click", this._onScrollHintClick, this);
+        }
+        this._scroll_hint.style.display = "flex";
+    }
+
+    _hideScrollHint() {
+        if (this._scroll_hint) {
+            this._scroll_hint.style.display = "none";
+        }
+    }
+
+    _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" });
+        this._scroll_hint_dismissed = true;
+        this._hideScrollHint();
+    }
+
+    _onSlideScroll() {
+        // programmatic scrollToTop on preloaded (inactive) slides must not
+        // dismiss the hint
+        if (!this.active || this._scroll_hint_dismissed) {
+            return;
+        }
+        this._scroll_hint_dismissed = true;
+        this._hideScrollHint();
+    }
+
+    addCallToAction(str: string) {
+        this._el.call_to_action = Dom.create(
+            "div",
+            "vco-slide-calltoaction",
+            this._el.content_container,
+        );
+        // 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.
+        const button_text = Dom.create("span", "vco-slide-calltoaction-button-text");
+        button_text.appendChild(sanitizeSlideText(str));
+        this._el.call_to_action?.appendChild(button_text);
+        DomEvent.addListener(this._el.call_to_action, "click", this._onCallToAction, this);
+    }
+
+    /*	Events
+	================================================== */
+    _onCallToAction(e: Event) {
+        this.fire("call_to_action", e);
+    }
+
+    /*	Private Methods
+	================================================== */
+    _initLayout() {
+        // Create Layout
+        this._el.container = Dom.create("div", "vco-slide");
+        if (this.data.uniqueid) {
+            this._el.container.id = this.data.uniqueid;
+        }
+        this._el.scroll_container = Dom.create(
+            "div",
+            "vco-slide-scrollable-container",
+            this._el.container,
+        );
+        this._el.content_container = Dom.create(
+            "div",
+            "vco-slide-content-container",
+            this._el.scroll_container,
+        );
+        this._el.content = Dom.create("div", "vco-slide-content", this._el.content_container);
+        this._el.background = Dom.create("div", "vco-slide-background", this._el.container);
+        // first scroll of any kind hides the scroll hint (passive: the
+        // listener never prevents default). The reference is kept because
+        // `.bind()` returns a new function each call, so the listener could
+        // otherwise never be removed again.
+        this._onSlideScrollBound = this._onSlideScroll.bind(this);
+        this._el.container.addEventListener("scroll", this._onSlideScrollBound, {
+            passive: true,
+        });
+        // Style Slide Background
+        if (this.data.background) {
+            const background = this.data.background as StorymapSlideBackground & {
+                text_background?: unknown;
+            };
+            if (background.url) {
+                this.has.background.image = true;
+                this._el.container.className += " vco-full-image-background";
+                this.has.background.color_value = "#000";
+                this._el.background.style.backgroundImage = "url('" + background.url + "')";
+                this._el.background.style.display = "block";
+            }
+            if (background.color) {
+                this.has.background.color = true;
+                this._el.container.className += " vco-full-color-background";
+                this.has.background.color_value = background.color;
+            }
+            if (background.text_background) {
+                this._el.container.className += " vco-text-background";
+            }
+        }
+
+        // Determine Assets for layout and loading
+        if (this.data.media && this.data.media.url && this.data.media.url !== "") {
+            this.has.media = true;
+        }
+        if (this.data.text && this.data.text.text) {
+            this.has.text = true;
+        }
+        if (this.data.text?.headline) {
+            this.has.headline = true;
+            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 Text
+        if ((this.has.text || this.has.headline) && this.data.text) {
+            this._text = new Text(this.data.text, {
+                title: this.has.title,
+                text_align: this.options.text_align as string | undefined,
+            });
+        }
+
+        // Add to DOM. Each branch has just established the members it uses
+        // (has.media -> _media, has.text/headline -> _text).
+        if (!this.has.text && !this.has.headline && this.has.media) {
+            this._el.container.className += " vco-slide-media-only";
+            this._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);
+        } else if (this.has.text && this.has.media) {
+            this._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";
+            this._text.addTo(this._el.content);
+        }
+
+        // Fire event that the slide is loaded
+        this.onLoaded();
+    }
+
+    // Update Display
+    _updateDisplay(width?: number, height?: number, layout?: string) {
+        let pad_left, pad_right, new_width;
+
+        if (width) {
+            this.options.width = width;
+        } else {
+            this.options.width = this._el.container.offsetWidth;
+        }
+
+        if (Browser.mobile && this.options.width <= this.options.skinny_size) {
+            pad_left = 0 + "px";
+            pad_right = 0 + "px";
+            new_width = this.options.width - 0 + "px";
+        } else if (layout === "landscape") {
+            pad_left = 40 + "px";
+            pad_right = 75 + "px";
+            new_width = this.options.width - (75 + 40) + "px";
+        } else if (this.options.width <= this.options.skinny_size) {
+            pad_left = this.options.slide_padding_lr + "px";
+            pad_right = this.options.slide_padding_lr + "px";
+            new_width = this.options.width - this.options.slide_padding_lr * 2 + "px";
+        } else {
+            pad_left = this.options.slide_padding_lr + "px";
+            pad_right = this.options.slide_padding_lr + "px";
+            new_width = this.options.width - this.options.slide_padding_lr * 2 + "px";
+        }
+
+        this._el.content.style.paddingLeft = pad_left;
+        this._el.content.style.paddingRight = pad_right;
+        this._el.content.style.width = new_width;
+
+        if (this._el.call_to_action) {
+            this._el.call_to_action.style.paddingLeft = pad_left;
+            this._el.call_to_action.style.paddingRight = pad_right;
+            this._el.call_to_action.style.width = new_width;
+        }
+
+        if (height) {
+            this.options.height = height;
+            //this._el.scroll_container.style.height		= this.options.height + "px";
+        } else {
+            this.options.height = this._el.container.offsetHeight;
+        }
+
+        if (this._media) {
+            if (!this.has.text && this.has.headline) {
+                this._media.updateDisplay(
+                    this.options.width,
+                    this.options.height - this._text.headlineHeight(),
+                    layout,
+                );
+            } else {
+                this._media.updateDisplay(this.options.width, this.options.height, layout);
+            }
+        }
+
+        // layout/resize changes move the overflow boundary
+        this._updateScrollHint();
+    }
+}
+
+export default class Slide extends DomMixed(Evented(SlideBase)) {
+    constructor(...args: ConstructorParameters<typeof SlideBase>) {
+        super(...args);
+    }
+}