@design-edito/tools 0.5.17 → 0.5.19

package/components/Video/index.d.ts

@@ -1,35 +1,34 @@
 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 behavioursSuspended - Holds back the instructions that **start** something,
+ * and lets through those that stop it. For a consumer withholding the video behind
+ * something — a warning to accept, typically: a video kept back that plays anyway is not
+ * withheld, it is merely hard to see. What was held back is replayed the moment this
+ * goes false, so lifting the veil on an already-visible video does what was asked, which
+ * a crossing-based trigger could never do. `':force'` does not override it: it speaks of
+ * consent not yet given, where a surrender speaks of an intention already expressed.
+ * @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 +37,9 @@ 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;
+    behavioursSuspended?: boolean;
 };
 /**
  * Full-featured video player component. Wraps a native `<video>` element with
@@ -70,11 +62,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 +82,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, behavioursSuspended, 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, behavioursSuspended === true);
+    // 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,42 @@
+/**
+ * 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 declare const VIDEO_VERBS: readonly ["play", "pause", "loud", "mute", "jump-to", "jump-start", "jump-end"];
+export type VideoVerb = typeof VIDEO_VERBS[number];
+/**
+ * How to read the argument of each verb that takes one.
+ *
+ * **Exported because a consumer has to validate what it is handed**, and a type gives a
+ * runtime validator nothing to compare against. lm-link reads an article's props out of
+ * static XML and has to reject `'jump-to:banana'` before it ever reaches here — with the
+ * list restated on its side, the day a verb is added is the day an article writing it
+ * silently gets nothing.
+ *
+ * A digit string, and deliberately not `Number`: that would take `'1e3'` and `'0x10'`,
+ * which nobody means to write in an article.
+ */
+export declare const VIDEO_VERB_ARGUMENTS: {
+    readonly 'jump-to': (arg: string) => boolean;
+};
+/**
+ * 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,30 @@
+/**
+ * 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 const VIDEO_VERBS = [
+    'play',
+    'pause',
+    'loud',
+    'mute',
+    'jump-to',
+    'jump-start',
+    'jump-end'
+];
+/**
+ * How to read the argument of each verb that takes one.
+ *
+ * **Exported because a consumer has to validate what it is handed**, and a type gives a
+ * runtime validator nothing to compare against. lm-link reads an article's props out of
+ * static XML and has to reject `'jump-to:banana'` before it ever reaches here — with the
+ * list restated on its side, the day a verb is added is the day an article writing it
+ * silently gets nothing.
+ *
+ * A digit string, and deliberately not `Number`: that would take `'1e3'` and `'0x10'`,
+ * which nobody means to write in an article.
+ */
+export const VIDEO_VERB_ARGUMENTS = {
+    'jump-to': (arg) => /^-?\d+$/v.test(arg)
+};

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

@@ -3,8 +3,8 @@ 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 eventListener from './EventListener/index.js'
+export * as gallery from './Gallery/index.js'
 export * as iframe from './Iframe/index.js'
 export * as image from './Image/index.js'
 export * as input from './Input/index.js'

package/components/index.js

@@ -3,8 +3,8 @@ 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 eventListener from './EventListener/index.js'
+export * as gallery from './Gallery/index.js'
 export * as iframe from './Iframe/index.js'
 export * as image from './Image/index.js'
 export * as input from './Input/index.js'

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;
+}