@vectoriox/iox-ui 5.72.1 → 5.73.0

package/src/media-core/video.ts

@@ -1,5 +1,7 @@
 import { ConsentCategory, ConsentDecision, hasConsent } from '@vectoriox/iox-ui/consent-core';
 
+import { FrameSequence, FrameSet, frameUrl, normalizeFrameSequence, phoneFrameSrcset } from './frames';
+
 /**
  * VIDEO (CC3 — complex-components plan §7b, board 5). A LEAF type with two sources:
  * - an uploaded FILE renders as a real `<video>` (poster, `preload="metadata"`, captions, controls);
@@ -39,6 +41,8 @@ export enum VideoTrait {
     Captions = 'captions',
     CaptionsLang = 'captionsLang',
     Consent = 'consentCategory',
+    /** Pictures the scroll plays (SC4): a `FrameSequence`. Written by the Scene panel, never typed. */
+    Frames = 'frames',
 }
 
 /** What a plan renders. */
@@ -49,6 +53,8 @@ export enum VideoKind {
     Facade = 'facade',
     /** No address yet: the poster blank (DS3) and nothing to play. */
     Empty = 'empty',
+    /** Pictures the scroll plays: the poster, and the driver's canvas over it. No player, no controls. */
+    Frames = 'frames',
 }
 
 /** A recognised embed: which provider, its video id and (Vimeo, unlisted) its privacy hash. */
@@ -210,6 +216,8 @@ export interface VideoPlan {
     embedUrl: string | null;
     /** "YouTube" / "Vimeo" ('' for a file). */
     providerLabel: string;
+    /** Pictures the scroll plays (Frames). */
+    frames: FrameSequence | null;
 }
 
 /**
@@ -218,6 +226,8 @@ export interface VideoPlan {
  * studio's own image (or the thumbnail the server fetched and stored for it), never a request to a third party.
  */
 export function planVideo(node: VideoNodeLike | null | undefined, consent: ConsentDecision | null): VideoPlan {
+    const frames = normalizeFrameSequence(videoProp(node, VideoTrait.Frames));
+    if (frames) return planFrames(node, frames);
     const rawSrc = str(videoProp(node, VideoTrait.Src));
     const source = videoSourceOf(rawSrc, videoProp(node, VideoTrait.Source));
     const ref = source === VideoSource.File ? null : parseVideoUrl(rawSrc);
@@ -245,6 +255,33 @@ export function planVideo(node: VideoNodeLike | null | undefined, consent: Conse
         granted,
         embedUrl: kind === VideoKind.Facade && granted && ref ? videoEmbedUrl(ref) : null,
         providerLabel: ref ? VIDEO_PROVIDER_LABEL[ref.source] : '',
+        frames: null,
+    };
+}
+
+/** Pictures win over any address the node also holds: it was turned into them. No player, no consent, nothing to press. */
+function planFrames(node: VideoNodeLike | null | undefined, frames: FrameSequence): VideoPlan {
+    const poster = str(videoProp(node, VideoTrait.Poster));
+    return {
+        kind: VideoKind.Frames,
+        source: VideoSource.File,
+        ref: null,
+        src: '',
+        poster: poster && !isThirdPartyPoster(poster) ? poster : frameUrl(frames, FrameSet.Wide, 0),
+        title: str(videoProp(node, VideoTrait.Title)),
+        mode: VideoMode.Inline,
+        background: false,
+        autoplay: false,
+        muted: false,
+        loop: false,
+        controls: false,
+        captions: '',
+        captionsLang: 'en',
+        consentCategory: null,
+        granted: true,
+        embedUrl: null,
+        providerLabel: '',
+        frames,
     };
 }
 
@@ -357,6 +394,8 @@ export enum VideoAttribute {
     Playing = 'data-iox-video-playing',
     /** The consent prompt is showing. */
     Asking = 'data-iox-video-asking',
+    /** The pictures the scroll plays, as JSON: what the driver reads, so it needs no node tree. */
+    Frames = 'data-iox-video-frames',
 }
 
 export enum VideoIcon {
@@ -376,6 +415,7 @@ export function videoRootAttributes(plan: VideoPlan): Record<string, string> {
     if (plan.consentCategory) attrs[VideoAttribute.Consent] = plan.consentCategory;
     if (plan.title) attrs[VideoAttribute.Title] = plan.title;
     if (!plan.poster) attrs[VideoAttribute.PosterEmpty] = '';
+    if (plan.frames) attrs[VideoAttribute.Frames] = JSON.stringify(plan.frames);
     return attrs;
 }
 
@@ -394,6 +434,12 @@ const iconHtml = (cls: string) => `<i class="${cls}" aria-hidden="true"></i>`;
 export function videoInnerHtml(plan: VideoPlan, options: VideoMarkupOptions): string {
     const { esc } = options;
     const words = options.words ?? VIDEO_WORDS.en;
+    // The same on the canvas and on the site: the first picture is real content, so it is fetched at once, named, and the
+    // size a phone needs. A driver's canvas covers it when pictures arrive; with no script it is what there is.
+    if (plan.kind === VideoKind.Frames) {
+        const srcset = plan.frames && !isAuthoredPoster(plan) ? phoneFrameSrcset(plan.frames) : '';
+        return `<img class="${VideoClass.Poster}" src="${esc(plan.poster)}"${srcset ? ` srcset="${esc(srcset)}" sizes="100vw"` : ''} alt="${esc(plan.title)}" decoding="async">`;
+    }
     const poster = plan.poster ? `<img class="${VideoClass.Poster}" src="${esc(plan.poster)}" alt="" loading="lazy" decoding="async">` : '';
     const label = esc(videoPlayLabel(plan, words));
     const playSpan = `<span class="${VideoClass.Play}" aria-hidden="true">${iconHtml(VideoIcon.Play)}</span>`;
@@ -437,6 +483,8 @@ export function videoInnerHtml(plan: VideoPlan, options: VideoMarkupOptions): st
     return `${poster}<button type="button" class="${VideoClass.Play}" aria-label="${label}">${iconHtml(VideoIcon.Play)}</button>${badge}${prompt}`;
 }
 
+const isAuthoredPoster = (plan: VideoPlan): boolean => !!plan.frames && plan.poster !== frameUrl(plan.frames, FrameSet.Wide, 0);
+
 /** Serialise attributes for a string renderer (a present boolean attribute is written bare). */
 export function serializeVideoAttributes(attrs: Readonly<Record<string, string>>, esc: (value: string) => string): string {
     return Object.entries(attrs).map(([name, value]) => (value === '' ? ` ${name}` : ` ${name}="${esc(value)}"`)).join('');

package/src/scene-core/scene-edit.ts

@@ -45,6 +45,7 @@ export const SCENE_TRACK_DEFS: ReadonlyArray<SceneTrackDef> = [
     { prop: SceneProp.Opacity, colour: false, rest: 1, min: 0, max: 100, step: 1, factor: 100, unit: PERCENT },
     { prop: SceneProp.Clip, colour: false, rest: 100, min: 0, max: 100, step: 1, factor: 1, unit: PERCENT },
     { prop: SceneProp.Words, colour: false, rest: 100, min: 0, max: 100, step: 1, factor: 1, unit: PERCENT },
+    { prop: SceneProp.Play, colour: false, rest: 0, min: 0, max: 100, step: 1, factor: 1, unit: PERCENT },
     { prop: SceneProp.Ground, colour: true, rest: 0, min: 0, max: 0, step: 0, factor: 1, unit: '' },
     { prop: SceneProp.Ink, colour: true, rest: 0, min: 0, max: 0, step: 0, factor: 1, unit: '' },
 ];
@@ -111,6 +112,20 @@ export function withSceneRevealFrom(tracks: ReadonlyArray<SceneTrack>, from: Sce
     return tracks.map(track => (track.prop === SceneProp.Clip ? { ...track, from } : track));
 }
 
+/**
+ * A layer's pictures playing across the whole Scene: the start of playing them. Keys the author has set are kept, so
+ * replacing the pictures keeps the timing.
+ */
+export function withScenePlayback(tracks: ReadonlyArray<SceneTrack>): SceneTrack[] {
+    if (trackOf(tracks, SceneProp.Play)) return [...tracks];
+    return [...tracks, { prop: SceneProp.Play, keys: [[0, 0], [1, 100]] }];
+}
+
+/** Stop playing a layer's pictures. */
+export function withoutScenePlayback(tracks: ReadonlyArray<SceneTrack>): SceneTrack[] {
+    return tracks.filter(track => track.prop !== SceneProp.Play);
+}
+
 /**
  * Set a key at `p`, in the author's units. A number is clamped to its bounds; a colour that is no colour changes nothing,
  * because `normalizeTracks` would drop it anyway and the author's other keys must survive.

package/src/scene-core/scene.ts

@@ -24,6 +24,8 @@ export enum SceneProp {
     Clip = 'clip',
     /** How many of the layer's words are lit, in % (100 = all): the word-by-word light-up. Split in the browser only. */
     Words = 'words',
+    /** How much of a Video layer's pictures have played, in % (100 = the last picture). */
+    Play = 'play',
     /** The layer's background colour. */
     Ground = 'ground',
     /** The layer's text colour. */
@@ -226,6 +228,12 @@ export function sceneWordsLit(tracks: ReadonlyArray<SceneTrack>, p: number): num
     return track ? clampPercent(valueAt(track.keys, p)) : null;
 }
 
+/** How far a layer's pictures have played at `p`, in %; null when it has no such track. */
+export function scenePlayed(tracks: ReadonlyArray<SceneTrack>, p: number): number | null {
+    const track = tracks.find(t => t.prop === SceneProp.Play);
+    return track ? clampPercent(valueAt(track.keys, p)) : null;
+}
+
 /** Word `index` of `count`, with `lit` % lit: words light one after the other, each easing in as the last finishes. */
 export function sceneWordOpacity(index: number, count: number, lit: number): number {
     return round(SCENE_WORD_DIM + (1 - SCENE_WORD_DIM) * clamp01((lit / PERCENT) * count - index));

package/src/scene-core/scroll-driver.ts

@@ -1,6 +1,7 @@
 import { SceneRole } from '@vectoriox/iox-ui/composite-core';
+import { FramePlayer, normalizeFrameSequence, VideoAttribute } from '@vectoriox/iox-ui/media-core';
 
-import { normalizeTracks, SCENE_PHONE_MAX_WIDTH, SceneAttribute, sceneFrame, SceneFrame, sceneWordOpacity, sceneWordsLit, SceneTrack } from './scene';
+import { normalizeTracks, SCENE_PHONE_MAX_WIDTH, SceneAttribute, sceneFrame, SceneFrame, scenePlayed, sceneWordOpacity, sceneWordsLit, SceneTrack } from './scene';
 import { LIGHT_UP_PIECE_CAP, SplitText, splitText } from './split-text';
 
 /**
@@ -70,6 +71,9 @@ interface Layer {
     words: SplitText | null;
     /** Too many words to split: it holds as it is, and is not counted again on every frame. */
     wordsRefused: boolean;
+    /** Its pictures, while a Play track plays them, and what they were built from: a change starts a new player. */
+    player: FramePlayer | null;
+    playerKey: string;
 }
 
 interface Scene {
@@ -120,7 +124,7 @@ export class ScrollDriver {
             const Observer = (this.host as Window & { MutationObserver?: typeof MutationObserver }).MutationObserver;
             if (Observer) {
                 scene.mutations = new Observer(() => this.readScene(scene));
-                scene.mutations.observe(root, { childList: true, subtree: true, attributes: true, attributeFilter: [SceneAttribute.Tracks, SceneAttribute.PhoneTracks] });
+                scene.mutations.observe(root, { childList: true, subtree: true, attributes: true, attributeFilter: [SceneAttribute.Tracks, SceneAttribute.PhoneTracks, VideoAttribute.Frames] });
             }
         }
         this.readScene(scene);
@@ -135,6 +139,7 @@ export class ScrollDriver {
         for (const layer of scene.layers) {
             layer.el.style.removeProperty('will-change');
             this.restoreWords(layer);
+            this.stopPlayer(layer);
         }
         this.scenes.delete(root);
     }
@@ -216,6 +221,13 @@ export class ScrollDriver {
         layer.el.style.removeProperty('will-change');
         for (const key of Object.keys(layer.last) as (keyof SceneFrame)[]) layer.el.style[key] = '';
         this.restoreWords(layer);
+        this.stopPlayer(layer);
+    }
+
+    private stopPlayer(layer: Layer): void {
+        layer.player?.destroy();
+        layer.player = null;
+        layer.playerKey = '';
     }
 
     private restoreWords(layer: Layer): void {
@@ -226,7 +238,7 @@ export class ScrollDriver {
     private readLayer(el: HTMLElement, scene: Scene): Layer {
         const previous = scene.layers.find(layer => layer.el === el);
         el.style.setProperty('will-change', TRANSFORM_WILL_CHANGE);
-        return { el, tracks: parseTracks(el.getAttribute(SceneAttribute.Tracks)), phoneTracks: parseTracks(el.getAttribute(SceneAttribute.PhoneTracks)), last: previous?.last ?? {}, stale: true, words: previous?.words ?? null, wordsRefused: false };
+        return { el, tracks: parseTracks(el.getAttribute(SceneAttribute.Tracks)), phoneTracks: parseTracks(el.getAttribute(SceneAttribute.PhoneTracks)), last: previous?.last ?? {}, stale: true, words: previous?.words ?? null, wordsRefused: false, player: previous?.player ?? null, playerKey: previous?.playerKey ?? '' };
     }
 
     private remeasureAll(): void {
@@ -275,6 +287,7 @@ export class ScrollDriver {
         for (const layer of scene.layers) {
             const tracks = scene.phone && layer.phoneTracks.length ? layer.phoneTracks : layer.tracks;
             this.writeWords(layer, sceneWordsLit(tracks, scene.progress));
+            this.writePlayed(layer, scene, scenePlayed(tracks, scene.progress));
             const frame = sceneFrame(tracks, scene.progress, { inlineSign: scene.inlineSign });
             for (const key of Object.keys(frame) as (keyof SceneFrame)[]) {
                 if (layer.stale || frame[key] !== layer.last[key]) layer.el.style[key] = frame[key] ?? '';
@@ -288,6 +301,27 @@ export class ScrollDriver {
         }
     }
 
+    /**
+     * The picture this moment asks for. The attribute sits on the Video's own root, which is the layer on the string path
+     * and inside it on the component path. A layer with no pictures, or no Play track, holds its poster.
+     */
+    private writePlayed(layer: Layer, scene: Scene, played: number | null): void {
+        const target = played === null ? null : (layer.el.hasAttribute(VideoAttribute.Frames) ? layer.el : layer.el.querySelector<HTMLElement>(`[${VideoAttribute.Frames}]`));
+        const raw = target?.getAttribute(VideoAttribute.Frames) ?? '';
+        const sequence = raw ? normalizeFrameSequence(raw) : null;
+        if (!target || !sequence) {
+            if (layer.player) this.stopPlayer(layer);
+            return;
+        }
+        const key = `${scene.phone}|${raw}`;
+        if (layer.player && (layer.playerKey !== key || layer.player.detached)) this.stopPlayer(layer);
+        if (!layer.player) {
+            layer.player = new FramePlayer(target, sequence, { phone: scene.phone, near: scene.root, host: this.host });
+            layer.playerKey = key;
+        }
+        layer.player.seek(played!);
+    }
+
     /** One opacity per word, and a write only for the few the scroll actually changed. */
     private writeWords(layer: Layer, lit: number | null): void {
         if (lit === null) {

package/styles/iox-design.css

@@ -350,7 +350,7 @@ dialog[data-iox-dialog]:not([open]) {
 /* The poster blank (DS3): no poster yet = the token fill, never a request to the provider. */
 .iox-video[data-iox-video-poster-empty]:not([data-iox-video-playing]) { background-color: var(--iox-surface-2); }
 .iox-video[data-iox-video-playing] { background-color: var(--iox-inverse-bg); }
-.iox-video > :is(.iox-video__poster, .iox-video__media, .iox-video__frame) {
+.iox-video > :is(.iox-video__poster, .iox-video__media, .iox-video__frame, .iox-video__frames) {
   position: absolute; inset: 0; width: 100%; height: 100%; border: 0; margin: 0; display: block; object-fit: cover;
 }
 .iox-video > .iox-video__poster { z-index: -1; }