@design-edito/tools 0.5.17 → 0.5.18

package/components/Video/index.controlled.js

@@ -2,7 +2,7 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { useMemo, useRef, useState, useCallback, useEffect } from 'react';
 import { clss } from '../../agnostic/css/clss/index.js';
 import { formatDuration } from '../../agnostic/time/duration/format-duration/index.js';
-import { mergeClassNames, useChangeDispatch } from '../utils/index.js';
+import { mergeClassNames, parseSourceList, useChangeDispatch } from '../utils/index.js';
 import cssModule from './styles.module.css';
 import { video as publicClassName } from '../public-classnames.js';
 import { Subtitles } from '../Subtitles/index.js';
@@ -57,8 +57,9 @@ subtitlesOn = true, mute, muted, volume = 1, playbackRate = 1, currentTimeMs: gi
 // Milliseconds by default, which is what this component has always rendered — a
 // default that changes under a consumer is a change nobody asked for. An article
 // usually wants `'{{mm}}:{{ss}}'` and says so.
-timeFormat = '{{mm}}:{{ss}}:{{ms}}', onPlayButtonClicked, onPauseButtonClicked, onLoudButtonClicked, onMuteButtonClicked, onVolumeRangeChanged, onRateRangeChanged, onFullscreenButtonClicked, onSubtitlesButtonClicked, onTimelineClicked, onIsPlayingChanged, onIsFullscreenChanged, onIsLoudChanged, onIsSubtitlesOnChanged, onIsEndedChanged, onVolumeChanged, onPlaybackRateChanged, onCurrentTimeMsChanged, onFullscreenChange, children, className, rootRef, ...intrinsicVideoAttributes }) => {
-    const videoRef = useRef(null);
+timeFormat = '{{mm}}:{{ss}}:{{ms}}', onPlayButtonClicked, onPauseButtonClicked, onLoudButtonClicked, onMuteButtonClicked, onVolumeRangeChanged, onRateRangeChanged, onFullscreenButtonClicked, onSubtitlesButtonClicked, onTimelineClicked, onVideoClicked, togglePlayOnClick, onIsPlayingChanged, onIsFullscreenChanged, onIsLoudChanged, onIsSubtitlesOnChanged, onIsEndedChanged, onVolumeChanged, onPlaybackRateChanged, onCurrentTimeMsChanged, onFullscreenChange, children, className, rootRef, videoRef: givenVideoRef, ...intrinsicVideoAttributes }) => {
+    const ownVideoRef = useRef(null);
+    const videoRef = givenVideoRef ?? ownVideoRef;
     const [totalTime, setTotalTime] = useState(0);
     const totalTimeMs = useMemo(() => secondsToMs(totalTime), [totalTime]);
     const [internalCurrentTimeMs, setInternalCurrentTimeMs] = useState(0);
@@ -121,6 +122,20 @@ timeFormat = '{{mm}}:{{ss}}:{{ms}}', onPlayButtonClicked, onPauseButtonClicked,
         const wasPlaying = videoRef.current?.paused === false;
         onPlayButtonClicked?.(e, wasPlaying, videoRef.current);
     }, [onPlayButtonClicked]);
+    // The picture as a play/pause surface. It reports and nothing more, like every other
+    // control here: the uncontrolled layer above owns the play state.
+    //
+    // The listener sits on the element and not on the `<figure>`, so the controls painted
+    // over it are not part of the surface — a click on pause would otherwise toggle twice
+    // and cancel itself. No `role` and no `tabIndex` either: this is a **second** way to
+    // do what the play button already does, and giving it a focus stop would put the same
+    // action twice in the tab order.
+    const handleVideoClick = useCallback((e) => {
+        if (togglePlayOnClick !== true)
+            return;
+        const wasPlaying = videoRef.current?.paused === false;
+        onVideoClicked?.(e, wasPlaying, videoRef.current);
+    }, [togglePlayOnClick, onVideoClicked]);
     const handlePauseButtonClick = useCallback((e) => {
         const wasPlaying = videoRef.current?.paused === false;
         onPauseButtonClicked?.(e, wasPlaying, videoRef.current);
@@ -170,7 +185,11 @@ timeFormat = '{{mm}}:{{ss}}:{{ms}}', onPlayButtonClicked, onPauseButtonClicked,
         // caché, c'est l'absence d'un état. Une feuille qui veut viser ce cas le reconnaît à
         // ce qu'aucun des deux modifieurs n'est là.
         'subtitles-on': subtitles !== undefined && subtitlesOn,
-        'subtitles-off': subtitles !== undefined && !subtitlesOn
+        'subtitles-off': subtitles !== undefined && !subtitlesOn,
+        // A capability rather than a state, and it is here for the same reason the lightbox
+        // carries `--open-on-click`: a surface that answers a click has to be able to say so
+        // with a cursor.
+        'toggle-play-on-click': togglePlayOnClick === true
     }), className);
     // Guarded: the duration is unknown until the metadata lands, and an unguarded
     // division would expose the string 'NaN' on every render until then.
@@ -190,7 +209,8 @@ timeFormat = '{{mm}}:{{ss}}:{{ms}}', onPlayButtonClicked, onPauseButtonClicked,
         'data-playback-rate': playbackRate,
         'data-current-time-ms': currentTimeMs.toFixed(2),
         'data-current-time-ratio': currentTimeRatio.toFixed(8),
-        'data-total-time-ms': totalTimeMs
+        'data-total-time-ms': totalTimeMs,
+        'data-toggle-play-on-click': togglePlayOnClick === true ? '' : undefined
     };
     const rootStyles = {
         '--lm-video-current-time': `${currentTimeMs}ms`,
@@ -201,38 +221,8 @@ timeFormat = '{{mm}}:{{ss}}:{{ms}}', onPlayButtonClicked, onPauseButtonClicked,
         '--lm-video-volume-ratio': `${volume}`,
         '--lm-video-playback-rate': `${playbackRate}`
     };
-    const parsedSources = useMemo(() => {
-        if (sources === undefined)
-            return [];
-        if (typeof sources === 'string')
-            return [{ src: sources }];
-        if (Array.isArray(sources)) {
-            if (sources.length === 0)
-                return [];
-            // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion -- first element sampled just above; array is expected to be homogeneous
-            if (typeof sources[0] === 'string')
-                return sources.map(src => ({ src }));
-            // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion -- first element was checked not to be a string just above; array is expected to be homogeneous
-            return sources;
-        }
-        return [];
-    }, [sources]);
-    const parsedTracks = useMemo(() => {
-        if (tracks === undefined)
-            return [];
-        if (typeof tracks === 'string')
-            return [{ src: tracks }];
-        if (Array.isArray(tracks)) {
-            if (tracks.length === 0)
-                return [];
-            // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion -- first element sampled just above; array is expected to be homogeneous
-            if (typeof tracks[0] === 'string')
-                return tracks.map(src => ({ src }));
-            // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion -- first element was checked not to be a string just above; array is expected to be homogeneous
-            return tracks;
-        }
-        return [];
-    }, [tracks]);
+    const parsedSources = useMemo(() => parseSourceList(sources, 'src'), [sources]);
+    const parsedTracks = useMemo(() => parseSourceList(tracks, 'src'), [tracks]);
     const videoClss = c('video');
     const videoControlsClss = c('video-controls');
     const playBtnClss = c('play-btn');
@@ -318,9 +308,5 @@ timeFormat = '{{mm}}:{{ss}}:{{ms}}', onPlayButtonClicked, onPauseButtonClicked,
     useChangeDispatch(isEnded, onIsEndedChanged);
     useChangeDispatch(volume, onVolumeChanged);
     useChangeDispatch(playbackRate, onPlaybackRateChanged);
-    return _jsxs("figure", { ref: rootRef, className: rootClss, style: rootStyles, ...rootAttributes, children: [_jsxs("video", { ref: videoRef, className: videoClss, ...intrinsicVideoAttributes, autoPlay: isTimeControlled ? false : intrinsicVideoAttributes.autoPlay, onLoadedMetadata: handleMetadataLoadEvent, onTimeUpdate: handleOnTimeUpdateEvent, onEnded: handleEndedEvent, onPlay: handlePlayEvent, onPause: handlePauseEvent, children: [parsedSources.map((source, index) => typeof source === 'string'
-                        ? _jsx("source", { src: source }, index)
-                        : _jsx("source", { src: source.src, type: source.type }, index)), parsedTracks.map((track, index) => typeof track === 'string'
-                        ? _jsx("track", { src: track }, index)
-                        : _jsx("track", { src: track.src, kind: track.kind, srcLang: track.srclang, label: track.label, default: track.default }, index)), children] }), _jsxs("div", { className: videoControlsClss, children: [_jsx("button", { className: playBtnClss, onClick: handlePlayButtonClick, children: playBtnContent }), _jsx("button", { className: pauseBtnClss, onClick: handlePauseButtonClick, children: pauseBtnContent }), _jsx("button", { className: loudBtnClss, onClick: handleLoudButtonClick, children: loudBtnContent }), _jsx("button", { className: muteBtnClss, onClick: handleMuteButtonClick, children: muteBtnContent }), _jsx("input", { type: 'range', className: volumeRangeClss, value: volumePercent, onChange: handleVolumeRangeChange, min: 0, max: 100, step: 1 }), _jsx("span", { className: volumePcntClss, children: Math.round(volumePercent) }), _jsx("button", { className: fullscreenBtnClss, onClick: handleFullscreenButtonClick, children: fullscreenBtnContent }), subtitles !== undefined && _jsx("button", { className: subtitlesBtnClss, onClick: handleSubtitlesButtonClick, children: subtitlesBtnContent }), _jsx("input", { type: 'range', className: playbackRateRangeClss, value: playbackRate, onChange: handleRateRangeChange, min: 0.25, max: 4, step: 0.25 }), _jsx("span", { className: playbackRateClss, children: playbackRate })] }), _jsxs("div", { className: timeControlsClss, children: [_jsx("span", { className: currentTimeClss, children: formatDuration(currentTimeMs, timeFormat) }), _jsx("span", { className: totalTimeClss, children: formatDuration(totalTimeMs, timeFormat) }), _jsx("div", { className: timelineClss, onClick: handleTimelineClick })] }), subtitles !== undefined && _jsx(Subtitles, { ...subtitles, timecodeMs: currentTimeMs, isEnded: isEnded })] });
+    return _jsxs("figure", { ref: rootRef, className: rootClss, style: rootStyles, ...rootAttributes, children: [_jsxs("video", { ref: videoRef, className: videoClss, ...intrinsicVideoAttributes, autoPlay: isTimeControlled ? false : intrinsicVideoAttributes.autoPlay, onClick: handleVideoClick, onLoadedMetadata: handleMetadataLoadEvent, onTimeUpdate: handleOnTimeUpdateEvent, onEnded: handleEndedEvent, onPlay: handlePlayEvent, onPause: handlePauseEvent, children: [parsedSources.map((source, index) => _jsx("source", { src: source.src, type: source.type }, index)), parsedTracks.map((track, index) => _jsx("track", { src: track.src, kind: track.kind, srcLang: track.srclang, label: track.label, default: track.default }, index)), children] }), _jsxs("div", { className: videoControlsClss, children: [_jsx("button", { className: playBtnClss, onClick: handlePlayButtonClick, children: playBtnContent }), _jsx("button", { className: pauseBtnClss, onClick: handlePauseButtonClick, children: pauseBtnContent }), _jsx("button", { className: loudBtnClss, onClick: handleLoudButtonClick, children: loudBtnContent }), _jsx("button", { className: muteBtnClss, onClick: handleMuteButtonClick, children: muteBtnContent }), _jsx("input", { type: 'range', className: volumeRangeClss, value: volumePercent, onChange: handleVolumeRangeChange, min: 0, max: 100, step: 1 }), _jsx("span", { className: volumePcntClss, children: Math.round(volumePercent) }), _jsx("button", { className: fullscreenBtnClss, onClick: handleFullscreenButtonClick, children: fullscreenBtnContent }), subtitles !== undefined && _jsx("button", { className: subtitlesBtnClss, onClick: handleSubtitlesButtonClick, children: subtitlesBtnContent }), _jsx("input", { type: 'range', className: playbackRateRangeClss, value: playbackRate, onChange: handleRateRangeChange, min: 0.25, max: 4, step: 0.25 }), _jsx("span", { className: playbackRateClss, children: playbackRate })] }), _jsxs("div", { className: timeControlsClss, children: [_jsx("span", { className: currentTimeClss, children: formatDuration(currentTimeMs, timeFormat) }), _jsx("span", { className: totalTimeClss, children: formatDuration(totalTimeMs, timeFormat) }), _jsx("div", { className: timelineClss, onClick: handleTimelineClick })] }), subtitles !== undefined && _jsx(Subtitles, { ...subtitles, timecodeMs: currentTimeMs, isEnded: isEnded })] });
 };

package/components/Video/index.d.ts

@@ -1,35 +1,27 @@
 import { type FunctionComponent } from 'react';
-import type { WithViewportObservation } from '../utils/types.js';
+import { type ViewportBehaviours } from '../utils/viewport-behaviours/index.js';
+import type { VideoAction } from './types.js';
 import { type Props as ControlledProps } from './index.controlled.js';
 /**
  * Props for the {@link Video} component.
  *
  * Extends all ControlledVideo props except play, mute, fullscreen, volume, playbackRate, and their associated event handlers
- * @property autoPlayWhenVisible - When `true`, starts playback every time the
- * component enters the viewport.
- * @property autoPlayOnceVisible - Same, but only the first time it does.
- * @property autoPauseWhenHidden - When `true`, pauses playback every time the
- * component leaves the viewport.
- * @property autoPauseOnceHidden - Same, but only the first time it does.
- * @property autoLoudWhenVisible - When `true`, unmutes every time the component
- * enters the viewport.
- * @property autoLoudOnceVisible - Same, but only the first time it does.
- * @property autoMuteWhenHidden - When `true`, mutes every time the component leaves
- * the viewport.
- * @property autoMuteOnceHidden - Same, but only the first time it does.
- * @property threshold - How much of the component has to be in view before it
- * counts as visible, forwarded to the internal {@link IntersectionObserver}. `0.3`
- * to start on a third of it; omitted, a single pixel is enough.
- * @property root - The observer's root. Defaults to the viewport.
- * @property rootMargin - Grows or shrinks that root before measuring.
- * @property onVisibilityChanged - Called on every crossing with the new value,
- * whether or not an `auto…` behaviour is bound to it. Never on mount.
+ * @property visibilityThreshold - How much of the video has to be on screen to count as
+ * seen. See {@link VisibilityOptions} for this and the four that follow it.
+ * @property whenVisible - What to do each time it becomes visible.
+ * @property whenHidden - The same, on the way out.
+ * @property onVisibilityChanged - Called with the new value once it has settled — the
+ * delays included, so this and the instructions are told the same story. Never on mount.
  * @property currentTimeMs - When provided, hands ownership of the current time
  * (in milliseconds) to the parent, which is then responsible for updating it —
  * typically to scrub the video from scroll position. A controlled time implies a
  * stopped video, since a playing element would advance a value it does not own:
- * `autoPlay`, `autoPlayWhenVisible` and the play button have no effect for as
+ * `autoPlay`, a `'play'` instruction and the play button have no effect for as
  * long as this prop is provided.
+ * @property togglePlayOnClick - When `true`, a click on the picture plays or pauses it.
+ * A **second** way to reach what the play and pause buttons already do, never the only
+ * one: the element takes no focus stop, so the keyboard keeps using the buttons. The
+ * controls painted over the picture are not part of the surface.
  * @property defaultSubtitlesOn - Whether the subtitles start shown. `true` by default —
  * an article that supplies cues means them to be read. The reader's button takes it from
  * there, so this is a starting point and not a setting: `default…` and never `initial…`,
@@ -38,16 +30,8 @@ import { type Props as ControlledProps } from './index.controlled.js';
  * @property children - React children rendered inside the `<video>` element itself
  * (e.g. fallback content).
  */
-export type Props = WithViewportObservation<Omit<ControlledProps, 'play' | 'fullscreen' | 'volume' | 'mute' | 'playbackRate' | 'subtitlesOn' | 'rootRef'>> & {
+export type Props = Omit<ControlledProps, 'play' | 'fullscreen' | 'volume' | 'mute' | 'playbackRate' | 'subtitlesOn' | 'rootRef' | 'videoRef'> & ViewportBehaviours<VideoAction> & {
     defaultSubtitlesOn?: boolean;
-    autoPlayWhenVisible?: boolean;
-    autoPlayOnceVisible?: boolean;
-    autoPauseWhenHidden?: boolean;
-    autoPauseOnceHidden?: boolean;
-    autoLoudWhenVisible?: boolean;
-    autoLoudOnceVisible?: boolean;
-    autoMuteWhenHidden?: boolean;
-    autoMuteOnceHidden?: boolean;
 };
 /**
  * Full-featured video player component. Wraps a native `<video>` element with
@@ -70,11 +54,18 @@ export type Props = WithViewportObservation<Omit<ControlledProps, 'play' | 'full
  * 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
@@ -83,8 +74,8 @@ export type Props = WithViewportObservation<Omit<ControlledProps, 'play' | 'full
  * 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

package/components/Video/index.js

@@ -1,7 +1,7 @@
 import { jsx as _jsx } from "react/jsx-runtime";
-import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
-import { useIntersectionObserver } from '../IntersectionObserver/index.js';
-import { muteAttributeWorkaround, shouldRunAutoBehaviour } from './utils.js';
+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
@@ -24,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
@@ -37,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, 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);
@@ -52,39 +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 rootRef = useRef(null);
-    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 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);
@@ -122,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);
@@ -156,53 +192,12 @@ 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(() => {
         if (controlledProps.autoPlay === true)
             setPlay(true);
     }, []);
-    // The observer watches the `<figure>` itself. `needsObserve` says whether anything
-    // asked for it — a hook cannot be skipped, so the condition is passed in rather than
-    // wrapped around the call, and no `IntersectionObserver` is created without a reason
-    // to create one.
-    useIntersectionObserver(rootRef, { threshold, root, rootMargin }, onIntersected, needsObserve);
     // Render
     //
     // **The `<figure>` is the root, and there is nothing above it.** The observer runs on
@@ -210,5 +205,5 @@ export const Video = ({ defaultSubtitlesOn = true, autoPlayWhenVisible, autoPlay
     // 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, 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(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 gallery from './Gallery/index.js'
+export * as clippable from './Clippable/index.js'
 export * as eventListener from './EventListener/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'