@vectoriox/iox-ui 5.37.0 → 5.39.0

package/src/media-core/video-runtime.ts

@@ -0,0 +1,239 @@
+import {
+    CONSENT_COOKIE_NAME, ConsentCategory, ConsentDecision, cookieAttributes, decode, encode, hasConsent, setCategoryDecision,
+} from '@vectoriox/iox-ui/consent-core';
+
+import { VIDEO_PROVIDER_LABEL, VideoAttribute, VideoClass, VideoIcon, VideoKind, VideoMode, VideoRef, VideoSource, videoEmbedUrl, VideoWords, videoWords } from './video';
+
+/**
+ * The Video's RUNTIME (CC3, board 5) — DOM only, ONE copy for both engine paths (the component path attaches it from
+ * its component, the string path from the page's interaction service; `attachVideoAt` is idempotent). It reads the
+ * markup `videoInnerHtml` writes. The builder canvas never attaches it (the canvas shows the poster only).
+ *
+ * - FACADE: play → the visitor's consent grants the category → the player's `<iframe>` replaces the poster, focused,
+ *   autoplaying (the visitor just pressed play). Not granted → the consent prompt: "Allow and play" grants the
+ *   category in the site's ONE consent record (the banner and its preferences read the same cookie) and plays;
+ *   "Privacy settings" opens the site's own preferences dialog.
+ * - FILE: the play button starts the `<video>`; muted autoplay only when motion is allowed.
+ * - BACKGROUND: muted and looped; it plays only when motion is allowed (never under reduced motion), and its
+ *   pause button is always there (WCAG 2.2.2).
+ */
+
+/** Ask the page to record a category the visitor granted (cancelable: the site's consent service handles it). */
+export const CONSENT_GRANT_EVENT = 'iox-consent-grant';
+/** Ask the page to open its consent preferences (cancelable: handled = a dialog opened). */
+export const CONSENT_PREFERENCES_EVENT = 'iox-consent-preferences';
+
+export interface ConsentGrantDetail { category: ConsentCategory }
+
+/** How the runtime reads and writes the visitor's ONE consent record — the page's transport. */
+export interface ConsentTransport {
+    read(): ConsentDecision | null;
+    /** Record the category as granted (synchronously, before the player loads). */
+    grant(category: ConsentCategory): void;
+    /** Open the site's privacy preferences; false when the page has none. */
+    openPreferences(): boolean;
+}
+
+const REDUCED_MOTION = '(prefers-reduced-motion: reduce)';
+const RUNTIME_KEY = '__ioxVideo';
+const IFRAME_ALLOW = 'autoplay; encrypted-media; picture-in-picture; fullscreen';
+
+/** The cookie the consent record lives in, read from a document. */
+export function readConsentRecord(doc: Document): ConsentDecision | null {
+    const raw = (doc.cookie ?? '').split('; ').find(c => c.startsWith(`${CONSENT_COOKIE_NAME}=`));
+    return decode(raw ? decodeURIComponent(raw.slice(CONSENT_COOKIE_NAME.length + 1)) : null);
+}
+
+/**
+ * The default transport: the page's own consent service answers the events (the engine records the decision, tells
+ * Consent Mode, re-syncs the banner's switches); a page with no such service (the admin's Preview) records the cookie
+ * itself, through the same consent-core decision, so the record is the same shape either way.
+ */
+export function documentConsentTransport(doc: Document): ConsentTransport {
+    return {
+        read: () => readConsentRecord(doc),
+        grant: category => {
+            const event = new CustomEvent<ConsentGrantDetail>(CONSENT_GRANT_EVENT, { detail: { category }, cancelable: true });
+            doc.dispatchEvent(event);
+            if (event.defaultPrevented) return;
+            const previous = readConsentRecord(doc);
+            const anonymousId = previous?.anonymousId ?? randomId();
+            const decision = setCategoryDecision(previous, category, true, anonymousId, previous?.policyVersion ?? '1');
+            const secure = doc.location?.protocol === 'https:';
+            doc.cookie = `${CONSENT_COOKIE_NAME}=${encodeURIComponent(encode(decision))}; ${cookieAttributes(12, secure)}`;
+        },
+        openPreferences: () => {
+            const event = new CustomEvent(CONSENT_PREFERENCES_EVENT, { cancelable: true });
+            doc.dispatchEvent(event);
+            return event.defaultPrevented;
+        },
+    };
+}
+
+function randomId(): string {
+    const c = (globalThis as { crypto?: { randomUUID?: () => string } }).crypto;
+    return c?.randomUUID ? c.randomUUID() : Math.random().toString(36).slice(2);
+}
+
+export interface VideoRuntimeOptions {
+    consent?: ConsentTransport;
+    /** True to stop motion (default: the visitor's reduced-motion setting). */
+    reducedMotion?: () => boolean;
+    words?: VideoWords;
+}
+
+/** The embed a facade root names (its provider, id and hash attributes). */
+export function videoRefOf(root: Element): VideoRef | null {
+    const source = root.getAttribute(VideoAttribute.Source);
+    const id = root.getAttribute(VideoAttribute.Id);
+    if ((source !== VideoSource.YouTube && source !== VideoSource.Vimeo) || !id) return null;
+    const hash = root.getAttribute(VideoAttribute.Hash);
+    return { source, id, ...(hash ? { hash } : {}) };
+}
+
+export class VideoRuntime {
+    private readonly cleanups: Array<() => void> = [];
+    private readonly consent: ConsentTransport;
+    private readonly reduced: () => boolean;
+    private readonly words: VideoWords;
+    private readonly doc: Document;
+
+    constructor(readonly root: HTMLElement, options: VideoRuntimeOptions = {}) {
+        this.doc = root.ownerDocument;
+        this.consent = options.consent ?? documentConsentTransport(this.doc);
+        const view = this.doc.defaultView;
+        this.reduced = options.reducedMotion ?? (() => !!view?.matchMedia?.(REDUCED_MOTION)?.matches);
+        this.words = options.words ?? videoWords(this.doc.documentElement?.getAttribute('lang'));
+        const kind = root.getAttribute(VideoAttribute.Root);
+        if (kind === VideoKind.Facade) this.attachFacade();
+        else if (kind === VideoKind.File) this.attachFile();
+    }
+
+    destroy(): void {
+        this.cleanups.splice(0).forEach(fn => fn());
+        delete (this.root as unknown as Record<string, unknown>)[RUNTIME_KEY];
+    }
+
+    /** The category a facade waits for (Marketing unless the node named another). */
+    private get category(): ConsentCategory {
+        const declared = this.root.getAttribute(VideoAttribute.Consent);
+        return declared === ConsentCategory.Analytics ? ConsentCategory.Analytics : ConsentCategory.Marketing;
+    }
+
+    private on(el: Element | null, type: string, fn: (e: Event) => void): void {
+        if (!el) return;
+        el.addEventListener(type, fn);
+        this.cleanups.push(() => el.removeEventListener(type, fn));
+    }
+
+    // ── facade ────────────────────────────────────────────────────────────────────────────────────
+
+    private attachFacade(): void {
+        const play = this.root.querySelector<HTMLButtonElement>(`button.${VideoClass.Play}`);
+        const allow = this.root.querySelector<HTMLButtonElement>(`.${VideoClass.Allow}`);
+        const settings = this.root.querySelector<HTMLButtonElement>(`.${VideoClass.Settings}`);
+        this.on(play, 'click', () => this.requestPlay());
+        this.on(allow, 'click', () => {
+            this.consent.grant(this.category);
+            this.loadPlayer();
+        });
+        this.on(settings, 'click', () => { this.consent.openPreferences(); });
+    }
+
+    /** Play pressed: the player when the category is granted, else the consent prompt. */
+    requestPlay(): void {
+        if (hasConsent(this.consent.read(), this.category)) {
+            this.loadPlayer();
+            return;
+        }
+        const prompt = this.root.querySelector<HTMLElement>(`.${VideoClass.Consent}`);
+        if (!prompt) return;
+        prompt.hidden = false;
+        this.root.setAttribute(VideoAttribute.Asking, '');
+        const play = this.root.querySelector<HTMLElement>(`button.${VideoClass.Play}`);
+        if (play) play.hidden = true;
+        this.root.querySelector<HTMLElement>(`.${VideoClass.Allow}`)?.focus();
+    }
+
+    /** The player — created only now, after the click and the grant. */
+    loadPlayer(): void {
+        const ref = videoRefOf(this.root);
+        if (!ref || this.root.hasAttribute(VideoAttribute.Playing)) return;
+        const frame = this.doc.createElement('iframe');
+        frame.className = VideoClass.Frame;
+        frame.src = videoEmbedUrl(ref);
+        frame.title = this.root.getAttribute(VideoAttribute.Title) || this.words.playUntitled(VIDEO_PROVIDER_LABEL[ref.source]);
+        frame.setAttribute('allow', IFRAME_ALLOW);
+        frame.setAttribute('allowfullscreen', '');
+        frame.setAttribute('referrerpolicy', 'strict-origin-when-cross-origin');
+        this.root.replaceChildren(frame);
+        this.root.removeAttribute(VideoAttribute.Asking);
+        this.root.setAttribute(VideoAttribute.Playing, '');
+        frame.focus();
+    }
+
+    // ── uploaded file ─────────────────────────────────────────────────────────────────────────────
+
+    private attachFile(): void {
+        const video = this.root.querySelector<HTMLVideoElement>(`video.${VideoClass.Media}`);
+        if (!video) return;
+        if (this.root.getAttribute(VideoAttribute.Mode) === VideoMode.Background) {
+            this.attachBackground(video);
+            return;
+        }
+        const play = this.root.querySelector<HTMLButtonElement>(`button.${VideoClass.Play}`);
+        const hidePlay = () => { if (play) play.hidden = true; };
+        this.on(play, 'click', () => { hidePlay(); void video.play()?.catch?.(() => undefined); video.focus(); });
+        this.on(video, 'play', hidePlay);
+        // Autoplay (muted) only while motion is allowed — never under reduced motion.
+        if (this.root.hasAttribute(VideoAttribute.Autoplay) && !this.reduced()) {
+            video.muted = true;
+            void video.play()?.catch?.(() => undefined);
+        }
+    }
+
+    private attachBackground(video: HTMLVideoElement): void {
+        const toggle = this.root.querySelector<HTMLButtonElement>(`.${VideoClass.Toggle}`);
+        video.muted = true;
+        const sync = () => {
+            const paused = video.paused;
+            if (!toggle) return;
+            toggle.setAttribute('aria-pressed', paused ? 'true' : 'false');
+            toggle.setAttribute('aria-label', paused ? this.words.playBackground : this.words.pauseBackground);
+            const icon = toggle.querySelector('i');
+            if (icon) icon.className = paused ? VideoIcon.Play : VideoIcon.Pause;
+        };
+        this.on(video, 'play', sync);
+        this.on(video, 'pause', sync);
+        this.on(toggle, 'click', () => {
+            if (video.paused) void video.play()?.catch?.(() => undefined);
+            else video.pause();
+            sync();
+        });
+        // It moves only when motion is allowed; under reduced motion it rests on its poster, paused.
+        if (!this.reduced()) void video.play()?.catch?.(() => sync());
+        sync();
+    }
+}
+
+/** Run the video at `el` (a `[data-iox-video]` element) once; null when it is not one or already runs. */
+export function attachVideoAt(el: HTMLElement | null | undefined, options: VideoRuntimeOptions = {}): VideoRuntime | null {
+    if (!el?.hasAttribute?.(VideoAttribute.Root)) return null;
+    const host = el as unknown as Record<string, unknown>;
+    if (host[RUNTIME_KEY]) return null;
+    const runtime = new VideoRuntime(el, options);
+    host[RUNTIME_KEY] = runtime;
+    return runtime;
+}
+
+/** Every video under `container` that is not running yet (the string path's globals and pages). */
+export function attachVideos(container: ParentNode, options: VideoRuntimeOptions = {}): VideoRuntime[] {
+    return Array.from(container.querySelectorAll<HTMLElement>(`[${VideoAttribute.Root}]`))
+        .map(el => attachVideoAt(el, options))
+        .filter((r): r is VideoRuntime => !!r);
+}
+
+/** The runtime already running at `el`, if any. */
+export function videoRuntimeOf(el: Element | null | undefined): VideoRuntime | null {
+    return ((el as unknown as Record<string, unknown> | null)?.[RUNTIME_KEY] as VideoRuntime | undefined) ?? null;
+}