@design-edito/tools 0.5.16 → 0.5.18

package/components/Video/index.js

@@ -1,11 +1,7 @@
 import { jsx as _jsx } from "react/jsx-runtime";
-import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
-import { clss } from '../../agnostic/css/clss/index.js';
-import { IntersectionObserverComponent } from '../IntersectionObserver/index.js';
-import { mergeClassNames } from '../utils/index.js';
-import { videoWrapper as publicClassName } from '../public-classnames.js';
-import { muteAttributeWorkaround, shouldRunAutoBehaviour } from './utils.js';
-import cssModule from './styles.module.css';
+import { useCallback, useEffect, useRef, useState } from 'react';
+import { useViewportBehaviours } from '../utils/viewport-behaviours/index.js';
+import { forceJumpTo, muteAttributeWorkaround } from './utils.js';
 import { ControlledVideo } from './index.controlled.js';
 /**
  * Full-featured video player component. Wraps a native `<video>` element with
@@ -28,11 +24,18 @@ import { ControlledVideo } from './index.controlled.js';
  * label: a screen reader announces a video player. Worth a `tag` prop the day that
  * matters more than autoplay — not before.
  *
- * Each viewport-driven behaviour comes in two flavours: `…When…` fires on every
- * crossing, `…Once…` only on the first one. A `…Once…` flag is armed by its own
- * automatic trigger and by nothing else — pressing play does not spend the one
- * automatic play the component still owed. Setting both flavours of the same
- * behaviour is the same as setting the `…When…` one alone.
+ * **Viewport-driven behaviour is declared, not named by a prop.** `whenVisible` and
+ * `whenHidden` take a verb or a list of them, out of {@link VideoAction} — `'play'`,
+ * `'mute'`, `'jump-to:500'` — each optionally suffixed by `':once'` and `':force'`. See
+ * `components/utils/viewport-behaviours` for the grammar and its rules, and the
+ * `visibility…` props for what « visible » means and how long
+ * it has to have been true.
+ *
+ * **An instruction yields to the reader by default.** Touching a control surrenders its
+ * domain for the rest of the mount: playback covers the play and pause buttons, the
+ * picture when it toggles, and the timeline, since seeking is saying where one wants to
+ * be. Sound covers the two sound buttons and the volume slider. Fullscreen and playback
+ * rate surrender nothing, being neither. `':force'` opts out.
  *
  * **`loop` reaches the element untouched**, like every other native media attribute
  * this component does not drive itself. It was once destructured out of the props and
@@ -41,14 +44,14 @@ import { ControlledVideo } from './index.controlled.js';
  * consequence worth knowing: a looping element never fires `ended`, so the `--ended`
  * modifier and the `isEnded` it feeds to `Subtitles` simply never come.
  *
- * Browsers refuse an unmuted `play()` outside a user gesture, so pairing an
- * `autoLoud…` with an `autoPlay…` will usually have the playback rejected. The
+ * Browsers refuse an unmuted `play()` outside a user gesture, so pairing a `'loud'`
+ * instruction with a `'play'` one will usually have the playback rejected. The
  * refusal is caught rather than ignored — the element is read back once the attempt
  * settles, and the play state follows what it says — so the controls stay truthful.
  * The media still won't play, though: autoplay muted, and leave unmuting to the
  * reader.
  */
-export const Video = ({ defaultSubtitlesOn = true, autoPlayWhenVisible, autoPlayOnceVisible, autoPauseWhenHidden, autoPauseOnceHidden, autoMuteWhenHidden, autoMuteOnceHidden, autoLoudWhenVisible, autoLoudOnceVisible, threshold, root, rootMargin, onVisibilityChanged, wrapperClassName, onPlayButtonClicked, onPauseButtonClicked, onLoudButtonClicked, onMuteButtonClicked, onVolumeRangeChanged, onRateRangeChanged, onFullscreenButtonClicked, onSubtitlesButtonClicked, ...controlledProps }) => {
+export const Video = ({ defaultSubtitlesOn = true, visibilityThreshold, visibilityRoot, visibilityRootMargin, visibilityOnAfterMs, visibilityOffAfterMs, whenVisible, whenHidden, onVisibilityChanged, onVideoClicked, onPlayButtonClicked, onPauseButtonClicked, onLoudButtonClicked, onMuteButtonClicked, onVolumeRangeChanged, onRateRangeChanged, onFullscreenButtonClicked, onSubtitlesButtonClicked, ...controlledProps }) => {
     // State & refs
     const [play, setPlay] = useState(false);
     const [volume, setVolume] = useState(1);
@@ -56,38 +59,55 @@ export const Video = ({ defaultSubtitlesOn = true, autoPlayWhenVisible, autoPlay
     const [playbackRate, setPlaybackRate] = useState(1);
     const [fullscreen, setFullscreen] = useState(false);
     const [subtitlesOn, setSubtitlesOn] = useState(defaultSubtitlesOn);
-    // One flag per `…Once…` behaviour, and each is armed by that behaviour's own
-    // automatic trigger. A single shared flag conflated four questions, and being set
-    // on any `play` event — a user click included — meant the first press cancelled
-    // behaviours that had nothing to do with playback.
-    const hasAutoPlayedOnce = useRef(false);
-    const hasAutoPausedOnce = useRef(false);
-    const hasAutoLoudedOnce = useRef(false);
-    const hasAutoMutedOnce = useRef(false);
-    // Several paths below ask for playback — the play button, autoPlayWhenVisible,
-    // autoPlay itself. None of them may win over a parent-owned time, so the
-    // invariant is applied where the state is forwarded rather than guarded at each
-    // of those call sites.
+    // Several paths below ask for playback — the play button, a `'play'` instruction,
+    // `autoPlay` itself. None of them may win over a parent-owned time, so the invariant
+    // is applied where the state is forwarded rather than guarded at each call site.
     const isTimeControlled = controlledProps.currentTimeMs !== undefined;
-    const needsObserve = useMemo(() => onVisibilityChanged !== undefined
-        || autoLoudWhenVisible === true
-        || autoLoudOnceVisible === true
-        || autoMuteWhenHidden === true
-        || autoMuteOnceHidden === true
-        || autoPlayWhenVisible === true
-        || autoPlayOnceVisible === true
-        || autoPauseWhenHidden === true
-        || autoPauseOnceHidden === true, [
-        autoLoudWhenVisible,
-        autoLoudOnceVisible,
-        autoMuteWhenHidden,
-        autoMuteOnceHidden,
-        autoPlayWhenVisible,
-        autoPlayOnceVisible,
-        autoPauseWhenHidden,
-        autoPauseOnceHidden,
+    const rootRef = useRef(null);
+    const videoRef = useRef(null);
+    // Viewport behaviours
+    // What each verb does, and what it competes with. Rebuilt on every render — it closes
+    // over the setters — which is why the generic layer reads it through a ref rather than
+    // a dependency list.
+    //
+    // **Seeking belongs to `playback`.** A reader who has dragged the timeline has said
+    // where they want to be, and an automatic jump would take it back from them.
+    const actions = {
+        play: { kind: 'start', domain: 'playback', run: () => setPlay(true) },
+        pause: { kind: 'stop', domain: 'playback', run: () => setPlay(false) },
+        loud: { kind: 'start', domain: 'sound', run: () => setMute(false) },
+        mute: { kind: 'stop', domain: 'sound', run: () => setMute(true) },
+        // A seek starts nothing on its own — it moves a playhead, playing or not — so a gate
+        // has no reason to hold it back.
+        'jump-to': {
+            kind: 'stop',
+            domain: 'playback',
+            run: arg => {
+                const targetMs = Number(arg);
+                if (!Number.isFinite(targetMs))
+                    return;
+                forceJumpTo(videoRef.current, targetMs);
+            }
+        },
+        'jump-start': { kind: 'stop', domain: 'playback', run: () => forceJumpTo(videoRef.current, 0) },
+        'jump-end': { kind: 'stop', domain: 'playback', run: () => forceJumpTo(videoRef.current, -1) }
+    };
+    const { surrender: surrenderAnyDomain } = useViewportBehaviours(rootRef, {
+        visibilityThreshold,
+        visibilityRoot,
+        visibilityRootMargin,
+        visibilityOnAfterMs,
+        visibilityOffAfterMs,
+        whenVisible,
+        whenHidden,
         onVisibilityChanged
-    ]);
+    }, actions);
+    // Narrowed back to this component's own domains. The generic layer takes a `string`,
+    // having no vocabulary of its own; handing the handlers a typed door means a
+    // misspelled domain fails to compile instead of quietly never surrendering anything.
+    const surrender = useCallback((domain) => {
+        surrenderAnyDomain(domain);
+    }, [surrenderAnyDomain]);
     // Intrisic event handlers
     const handleOnPlayEvent = useCallback((e) => {
         controlledProps.onPlay?.(e);
@@ -125,28 +145,41 @@ export const Video = ({ defaultSubtitlesOn = true, autoPlayWhenVisible, autoPlay
     // User actions
     const handlePlayButtonClick = useCallback((e, isPlaying, video) => {
         onPlayButtonClicked?.(e, isPlaying, video);
+        surrender('playback');
         setPlay(true);
-    }, [onPlayButtonClicked]);
+    }, [onPlayButtonClicked, surrender]);
     const handlePauseButtonClick = useCallback((e, isPlaying, video) => {
         onPauseButtonClicked?.(e, isPlaying, video);
+        surrender('playback');
         setPlay(false);
-    }, [onPauseButtonClicked]);
+    }, [onPauseButtonClicked, surrender]);
+    // The picture toggles, where the two buttons each say one thing. It is the same gesture
+    // as pressing one of them — a consumer tracking whether the reader has taken over
+    // playback has to count this one too, since it is the same decision made elsewhere.
+    const handleVideoClick = useCallback((e, isPlaying, video) => {
+        onVideoClicked?.(e, isPlaying, video);
+        surrender('playback');
+        setPlay(!isPlaying);
+    }, [onVideoClicked, surrender]);
     const handleLoudButtonClick = useCallback((e, isLoud, video) => {
         onLoudButtonClicked?.(e, isLoud, video);
+        surrender('sound');
         setMute(false);
-    }, [onLoudButtonClicked]);
+    }, [onLoudButtonClicked, surrender]);
     const handleMuteButtonClick = useCallback((e, isLoud, video) => {
         onMuteButtonClicked?.(e, isLoud, video);
+        surrender('sound');
         setMute(true);
-    }, [onMuteButtonClicked]);
+    }, [onMuteButtonClicked, surrender]);
     const handleRateRangeChange = useCallback((e, targetRate, currentRate, video) => {
         onRateRangeChanged?.(e, targetRate, currentRate, video);
         setPlaybackRate(targetRate);
     }, [onRateRangeChanged]);
     const handleVolumeRangeChange = useCallback((e, targetVolume, currentVolume, video) => {
         onVolumeRangeChanged?.(e, targetVolume, currentVolume, video);
+        surrender('sound');
         setVolume(targetVolume);
-    }, [onVolumeRangeChanged]);
+    }, [onVolumeRangeChanged, surrender]);
     const handleFullscreenButtonClick = useCallback((e, isFullscreen, video) => {
         onFullscreenButtonClicked?.(e, isFullscreen, video);
         setFullscreen(!isFullscreen);
@@ -159,42 +192,6 @@ export const Video = ({ defaultSubtitlesOn = true, autoPlayWhenVisible, autoPlay
         onSubtitlesButtonClicked?.(e, isSubtitlesOn, video);
         setSubtitlesOn(!isSubtitlesOn);
     }, [onSubtitlesButtonClicked]);
-    // Intersection Observer
-    const onIntersected = useCallback(({ ioEntry }) => {
-        if (ioEntry === undefined)
-            return;
-        const { isIntersecting } = ioEntry;
-        onVisibilityChanged?.(isIntersecting);
-        if (isIntersecting) {
-            if (shouldRunAutoBehaviour(autoPlayWhenVisible, autoPlayOnceVisible, hasAutoPlayedOnce.current)) {
-                hasAutoPlayedOnce.current = true;
-                setPlay(true);
-            }
-            if (shouldRunAutoBehaviour(autoLoudWhenVisible, autoLoudOnceVisible, hasAutoLoudedOnce.current)) {
-                hasAutoLoudedOnce.current = true;
-                setMute(false);
-            }
-            return;
-        }
-        if (shouldRunAutoBehaviour(autoPauseWhenHidden, autoPauseOnceHidden, hasAutoPausedOnce.current)) {
-            hasAutoPausedOnce.current = true;
-            setPlay(false);
-        }
-        if (shouldRunAutoBehaviour(autoMuteWhenHidden, autoMuteOnceHidden, hasAutoMutedOnce.current)) {
-            hasAutoMutedOnce.current = true;
-            setMute(true);
-        }
-    }, [
-        autoPlayWhenVisible,
-        autoPlayOnceVisible,
-        autoPauseWhenHidden,
-        autoPauseOnceHidden,
-        autoMuteWhenHidden,
-        autoMuteOnceHidden,
-        autoLoudWhenVisible,
-        autoLoudOnceVisible,
-        onVisibilityChanged
-    ]);
     // `autoPlay` is forwarded to the element, but the play state is owned here, so
     // it has to be seeded once on mount for the controls to agree with the element.
     useEffect(() => {
@@ -202,10 +199,11 @@ export const Video = ({ defaultSubtitlesOn = true, autoPlayWhenVisible, autoPlay
             setPlay(true);
     }, []);
     // Render
-    const c = clss(publicClassName, { cssModule });
-    const rootClss = mergeClassNames(c(), wrapperClassName);
-    const videoContent = _jsx(ControlledVideo, { ...controlledProps, play: play && !isTimeControlled, volume: volume, mute: mute, playbackRate: playbackRate, fullscreen: fullscreen, subtitlesOn: subtitlesOn, onPlay: handleOnPlayEvent, onPause: handleOnPauseEvent, onIsPlayingChanged: handleIsPlayingChanged, onVolumeChange: handleOnVolumeChangeEvent, onRateChange: handleOnRateChangeEvent, onLoadedMetadata: handleOnLoadedMetadataEvent, onFullscreenChange: handleFullscreenChange, onPlayButtonClicked: handlePlayButtonClick, onPauseButtonClicked: handlePauseButtonClick, onLoudButtonClicked: handleLoudButtonClick, onMuteButtonClicked: handleMuteButtonClick, onVolumeRangeChanged: handleVolumeRangeChange, onRateRangeChanged: handleRateRangeChange, onFullscreenButtonClicked: handleFullscreenButtonClick, onSubtitlesButtonClicked: handleSubtitlesButtonClick });
-    return _jsx("div", { className: rootClss, children: needsObserve
-            ? _jsx(IntersectionObserverComponent, { threshold: threshold, root: root, rootMargin: rootMargin, onIntersected: onIntersected, children: videoContent })
-            : videoContent });
+    //
+    // **The `<figure>` is the root, and there is nothing above it.** The observer runs on
+    // that element rather than on a box built to hold it: a wrapper would take the outer
+    // position — the one a consumer lays out — and leave `className` naming an inner
+    // element, which is the wrong way round. So no wrapper, and no second class-name prop
+    // to reach past it.
+    return _jsx(ControlledVideo, { ...controlledProps, rootRef: rootRef, videoRef: videoRef, play: play && !isTimeControlled, volume: volume, mute: mute, playbackRate: playbackRate, fullscreen: fullscreen, subtitlesOn: subtitlesOn, onPlay: handleOnPlayEvent, onPause: handleOnPauseEvent, onIsPlayingChanged: handleIsPlayingChanged, onVolumeChange: handleOnVolumeChangeEvent, onRateChange: handleOnRateChangeEvent, onLoadedMetadata: handleOnLoadedMetadataEvent, onFullscreenChange: handleFullscreenChange, onVideoClicked: handleVideoClick, onPlayButtonClicked: handlePlayButtonClick, onPauseButtonClicked: handlePauseButtonClick, onLoudButtonClicked: handleLoudButtonClick, onMuteButtonClicked: handleMuteButtonClick, onVolumeRangeChanged: handleVolumeRangeChange, onRateRangeChanged: handleRateRangeChange, onFullscreenButtonClicked: handleFullscreenButtonClick, onSubtitlesButtonClicked: handleSubtitlesButtonClick });
 };

package/components/Video/types.d.ts

@@ -0,0 +1,26 @@
+/**
+ * The verbs a video answers to, as the table keys them.
+ *
+ * `jump-to` is the only one taking an argument, and the table is keyed by the verb
+ * alone — the argument is parsed out of the instruction before the lookup.
+ */
+export type VideoVerb = 'play' | 'pause' | 'loud' | 'mute' | 'jump-to' | 'jump-start' | 'jump-end';
+/**
+ * The instructions a consumer writes in `whenVisible` / `whenHidden`.
+ *
+ * `'jump-to:500'` seeks to 500 ms. **A negative value counts from the end**:
+ * `'jump-to:-1'` is the last reachable timecode, and it is `-1` rather than `-0`
+ * because `-0 === 0` in JavaScript and would collide with the start. `'jump-start'`
+ * and `'jump-end'` are the shorthands for `'jump-to:0'` and `'jump-to:-1'`.
+ *
+ * Every one of them takes the `':once'` and `':force'` suffixes, which are the generic
+ * layer's and are not restated here.
+ */
+export type VideoAction = Exclude<VideoVerb, 'jump-to'> | `jump-to:${number}`;
+/**
+ * What a verb competes with, so that taking one control over doesn't silence the rest.
+ *
+ * Seeking belongs to `'playback'`: a reader who drags the timeline has said where they
+ * want to be, and an automatic jump would take it back from them.
+ */
+export type VideoDomain = 'playback' | 'sound';

package/components/Video/types.js

@@ -0,0 +1 @@
+export {};

package/components/Video/utils.d.ts

@@ -1,3 +1,26 @@
+/**
+ * The two list shapes a `<video>` accepts as children, as records.
+ *
+ * They live here and not next to the component because nothing about them is React:
+ * they describe a `<source>` and a `<track>` element.
+ *
+ * **A video source is not a picture source**, which is why `Image` keeps a shape of its
+ * own rather than sharing this one: a `<source>` inside a `<video>` carries `src`, one
+ * inside a `<picture>` carries `srcSet`, `media` and `sizes`, and neither element accepts
+ * the other's attributes. What the two do share is how a list of them is read — see
+ * `parseSourceList` in `components/utils`.
+ */
+export type SourceData = {
+    src?: string;
+    type?: string;
+};
+export type TrackData = {
+    src?: string;
+    kind?: 'subtitles' | 'captions' | 'descriptions' | 'chapters' | 'metadata';
+    srclang?: string;
+    label?: string;
+    default?: boolean;
+};
 export declare const muteAttributeWorkaround: (video: HTMLVideoElement | null, shouldMute: boolean) => void;
 export declare const forceMute: (video: HTMLVideoElement | null) => void;
 export declare const forceLoud: (video: HTMLVideoElement | null) => void;
@@ -40,4 +63,18 @@ export declare const getTimelineClickProgress: (event: React.MouseEvent<HTMLDivE
  * automatic mute the component still owed.
  * @returns Whether to apply it now.
  */
-export declare const shouldRunAutoBehaviour: (whenCrossed: boolean | undefined, onceOnly: boolean | undefined, hasFired: boolean) => boolean;
+/**
+ * Seeks the element, in milliseconds, counting from the end when asked negatively.
+ *
+ * **A negative target counts back from the duration**, so `-1` is the last reachable
+ * timecode. It is `-1` and not `-0` because `-0 === 0` in JavaScript, which would make
+ * the end of a video indistinguishable from its start.
+ *
+ * Nothing happens before the metadata lands: the duration is `NaN` until then, and a
+ * seek computed against it would land anywhere. An instruction asking for the end of a
+ * video whose length is still unknown is simply not yet answerable.
+ *
+ * @param video - The element, or `null` before it mounts.
+ * @param targetMs - Where to go. Negative counts from the end.
+ */
+export declare const forceJumpTo: (video: HTMLVideoElement | null, targetMs: number) => void;

package/components/Video/utils.js

@@ -131,8 +131,27 @@ export const getTimelineClickProgress = (event) => {
  * automatic mute the component still owed.
  * @returns Whether to apply it now.
  */
-export const shouldRunAutoBehaviour = (whenCrossed, onceOnly, hasFired) => {
-    if (whenCrossed === true)
-        return true;
-    return onceOnly === true && !hasFired;
+/**
+ * Seeks the element, in milliseconds, counting from the end when asked negatively.
+ *
+ * **A negative target counts back from the duration**, so `-1` is the last reachable
+ * timecode. It is `-1` and not `-0` because `-0 === 0` in JavaScript, which would make
+ * the end of a video indistinguishable from its start.
+ *
+ * Nothing happens before the metadata lands: the duration is `NaN` until then, and a
+ * seek computed against it would land anywhere. An instruction asking for the end of a
+ * video whose length is still unknown is simply not yet answerable.
+ *
+ * @param video - The element, or `null` before it mounts.
+ * @param targetMs - Where to go. Negative counts from the end.
+ */
+export const forceJumpTo = (video, targetMs) => {
+    if (video === null)
+        return;
+    const durationMs = secondsToMs(video.duration);
+    if (!Number.isFinite(durationMs))
+        return;
+    const absolute = targetMs < 0 ? durationMs + targetMs : targetMs;
+    // eslint-disable-next-line no-param-reassign
+    video.currentTime = msToSeconds(Math.min(Math.max(absolute, 0), durationMs));
 };

package/components/index.d.ts

@@ -1,11 +1,11 @@
 export * as beforeAfter from './BeforeAfter/index.js'
 export * as button from './Button/index.js'
-export * as clippable from './Clippable/index.js'
 export * as disclaimer from './Disclaimer/index.js'
-export * as drawer from './Drawer/index.js'
+export * as clippable from './Clippable/index.js'
 export * as eventListener from './EventListener/index.js'
-export * as gallery from './Gallery/index.js'
+export * as drawer from './Drawer/index.js'
 export * as iframe from './Iframe/index.js'
+export * as gallery from './Gallery/index.js'
 export * as image from './Image/index.js'
 export * as input from './Input/index.js'
 export * as intersectionObserver from './IntersectionObserver/index.js'
@@ -13,15 +13,15 @@ export * as jsonEditor from './JsonEditor/index.js'
 export * as lightbox from './Lightbox/index.js'
 export * as listLoader from './ListLoader/index.js'
 export * as overlayer from './Overlayer/index.js'
-export * as paginator from './Paginator/index.js'
 export * as resizeObserver from './ResizeObserver/index.js'
+export * as paginator from './Paginator/index.js'
 export * as scrllgngn from './Scrllgngn/index.js'
 export * as scrollListener from './ScrollListener/index.js'
 export * as select from './Select/index.js'
 export * as sequencer from './Sequencer/index.js'
 export * as shadowRoot from './ShadowRoot/index.js'
-export * as subtitles from './Subtitles/index.js'
 export * as textarea from './Textarea/index.js'
+export * as subtitles from './Subtitles/index.js'
 export * as uiModule from './UIModule/index.js'
 export * as video from './Video/index.js'
 export * as wipAudioQuote from './_WIP_AudioQuote/index.js'

package/components/index.js

@@ -1,11 +1,11 @@
 export * as beforeAfter from './BeforeAfter/index.js'
 export * as button from './Button/index.js'
-export * as clippable from './Clippable/index.js'
 export * as disclaimer from './Disclaimer/index.js'
-export * as drawer from './Drawer/index.js'
+export * as clippable from './Clippable/index.js'
 export * as eventListener from './EventListener/index.js'
-export * as gallery from './Gallery/index.js'
+export * as drawer from './Drawer/index.js'
 export * as iframe from './Iframe/index.js'
+export * as gallery from './Gallery/index.js'
 export * as image from './Image/index.js'
 export * as input from './Input/index.js'
 export * as intersectionObserver from './IntersectionObserver/index.js'
@@ -13,15 +13,15 @@ export * as jsonEditor from './JsonEditor/index.js'
 export * as lightbox from './Lightbox/index.js'
 export * as listLoader from './ListLoader/index.js'
 export * as overlayer from './Overlayer/index.js'
-export * as paginator from './Paginator/index.js'
 export * as resizeObserver from './ResizeObserver/index.js'
+export * as paginator from './Paginator/index.js'
 export * as scrllgngn from './Scrllgngn/index.js'
 export * as scrollListener from './ScrollListener/index.js'
 export * as select from './Select/index.js'
 export * as sequencer from './Sequencer/index.js'
 export * as shadowRoot from './ShadowRoot/index.js'
-export * as subtitles from './Subtitles/index.js'
 export * as textarea from './Textarea/index.js'
+export * as subtitles from './Subtitles/index.js'
 export * as uiModule from './UIModule/index.js'
 export * as video from './Video/index.js'
 export * as wipAudioQuote from './_WIP_AudioQuote/index.js'

package/components/public-classnames.d.ts

@@ -24,4 +24,3 @@ export declare const subtitles = "lm-subtitles";
 export declare const textarea = "lm-textarea";
 export declare const uiModule = "lm-ui-module";
 export declare const video = "lm-video";
-export declare const videoWrapper = "lm-video-wrapper";

package/components/public-classnames.js

@@ -24,4 +24,3 @@ export const subtitles = 'lm-subtitles';
 export const textarea = 'lm-textarea';
 export const uiModule = 'lm-ui-module';
 export const video = 'lm-video';
-export const videoWrapper = 'lm-video-wrapper';

package/components/utils/index.d.ts

@@ -21,3 +21,24 @@ export declare function mergeClassNames(...names: Array<string | null | undefine
  * effect fires, so it is never a stale one.
  */
 export declare function useChangeDispatch<T>(value: T, onChange?: (value: T) => void, isEqual?: (a: T, b: T) => boolean): void;
+/**
+ * The three forms a `<source>` list is written in, reduced to the one a render uses.
+ *
+ * A bare string is a single source, an array of strings is several, an array of records
+ * is taken as given. **The array is read as homogeneous** — the first element decides for
+ * all of them —, which is what someone writing one by hand means anyway, and the only
+ * reading a static hyper-json array could support.
+ *
+ * `stringKey` is the whole reason this is shared rather than written twice. The parsing
+ * is identical for `Video` and `Image`, but **the shorthand does not name the same
+ * attribute**: a `<source>` inside a `<video>` carries `src`, one inside a `<picture>`
+ * carries `srcSet`. The two record shapes stay apart for the same reason — the picture
+ * source also takes `media` and `sizes`, which a video source has no use for, and neither
+ * element accepts the other's key. One element, one shape; only the reading is common.
+ *
+ * @template T - The record shape the caller's element accepts.
+ * @param given - What the consumer wrote.
+ * @param stringKey - Where a bare string goes.
+ * @returns The list as records, empty when there is nothing to render.
+ */
+export declare function parseSourceList<T extends Record<string, unknown>>(given: string | string[] | T[] | undefined, stringKey: keyof T & string): T[];

package/components/utils/index.js

@@ -41,3 +41,43 @@ export function useChangeDispatch(value, onChange, isEqual = Object.is) {
         onChange?.(value);
     }, [value]);
 }
+/**
+ * The three forms a `<source>` list is written in, reduced to the one a render uses.
+ *
+ * A bare string is a single source, an array of strings is several, an array of records
+ * is taken as given. **The array is read as homogeneous** — the first element decides for
+ * all of them —, which is what someone writing one by hand means anyway, and the only
+ * reading a static hyper-json array could support.
+ *
+ * `stringKey` is the whole reason this is shared rather than written twice. The parsing
+ * is identical for `Video` and `Image`, but **the shorthand does not name the same
+ * attribute**: a `<source>` inside a `<video>` carries `src`, one inside a `<picture>`
+ * carries `srcSet`. The two record shapes stay apart for the same reason — the picture
+ * source also takes `media` and `sizes`, which a video source has no use for, and neither
+ * element accepts the other's key. One element, one shape; only the reading is common.
+ *
+ * @template T - The record shape the caller's element accepts.
+ * @param given - What the consumer wrote.
+ * @param stringKey - Where a bare string goes.
+ * @returns The list as records, empty when there is nothing to render.
+ */
+export function parseSourceList(given, stringKey) {
+    const fromString = (value) => {
+        const single = { [stringKey]: value };
+        // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion -- a one-key record is the narrowest `T` a bare string can describe; every other field is optional by contract
+        return single;
+    };
+    if (given === undefined)
+        return [];
+    if (typeof given === 'string')
+        return [fromString(given)];
+    if (!Array.isArray(given))
+        return [];
+    if (given.length === 0)
+        return [];
+    // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion -- first element sampled just above; array is read as homogeneous
+    if (typeof given[0] === 'string')
+        return given.map(fromString);
+    // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion -- first element was checked not to be a string just above; array is read as homogeneous
+    return given;
+}

package/components/utils/viewport-behaviours/index.d.ts

@@ -0,0 +1,54 @@
+import { type RefObject } from 'react';
+import type { ActionTable, ViewportBehaviours, VisibilityOptions } from './types.js';
+/**
+ * Whether the element counts as visible — **as a state, not as a crossing**.
+ *
+ * That distinction is the whole point. An `IntersectionObserver` reports an event, and
+ * a behaviour hung on the event only ever runs when the screen is traversed. A
+ * component already visible whose behaviour was held back — behind a lm-link gate,
+ * typically — never gets a second chance, because nothing crosses when the gate lifts.
+ * Held as a state, the condition can be recombined with whatever else gates it.
+ *
+ * The delays are a debounce **on this state**: the element has to hold its new value
+ * for that long before the value is committed. A component crossed while scrolling fast
+ * therefore never counts as seen at all, rather than counting and being undone.
+ *
+ * @param targetRef - The element to watch.
+ * @param options - The observer's settings, plus the two delays.
+ * @param enabled - `false` mounts no observer. A hook can't be skipped; this is how
+ * a caller with nothing to watch for says so.
+ * @returns `true` or `false` once the first observation has settled, `undefined` before.
+ */
+export declare function useVisibilityState(targetRef: RefObject<Element | null>, options?: VisibilityOptions, enabled?: boolean): boolean | undefined;
+/** The shape `useViewportBehaviours` hands back. */
+export type ViewportBehavioursResult = {
+    isVisible: boolean | undefined;
+    /**
+     * Tells the layer that the reader has taken over a domain, and that its instructions
+     * are to stop firing. Call it from the handlers that count as taking over — and only
+     * those: seeking on a timeline or going fullscreen is not deciding about playback.
+     */
+    surrender: (domain: string) => void;
+};
+/**
+ * Runs a component's visibility instructions, and holds everything that decides whether
+ * they may run at all.
+ *
+ * @template A - The component's vocabulary.
+ * @param targetRef - The element to watch.
+ * @param props - The component's visibility props.
+ * @param table - What each of its verbs does. @see {@link ActionTable}
+ * @param suspended - Holds back the verbs that **start** something, and lets through
+ * those that stop something. This is a capability's doing — a lm-link gate — and it is
+ * not the same as a surrender: a gate speaks of consent not yet given, so `':force'`
+ * does not override it.
+ *
+ * @remarks
+ * **An instruction yields to the reader by default.** The failure modes are not
+ * symmetrical: not restarting on its own is a disappointment, restarting against a
+ * reader who has just pressed pause is an hostility they will meet again at every pass.
+ * `':force'` opts out, and is expected to be rare — which is why it is the written form
+ * and yielding is the silent one.
+ */
+export declare function useViewportBehaviours<A extends string>(targetRef: RefObject<Element | null>, props: ViewportBehaviours<A>, table: ActionTable<A>, suspended?: boolean): ViewportBehavioursResult;
+export type { ActionSpec, ActionTable, Instruction, Modifier, ParsedInstruction, ViewportBehaviours, VisibilityOptions } from './types.js';