@design-edito/tools 0.5.16 → 0.5.18

package/components/IntersectionObserver/index.js

@@ -5,23 +5,29 @@ import { mergeClassNames } from '../utils/index.js';
 import { intersectionObserver as publicClassName } from '../public-classnames.js';
 import cssModule from './styles.module.css';
 /**
- * Component that observes its root element using the IntersectionObserver API
- * and notifies consumers about visibility changes.
+ * Observes an element a caller already renders, rather than one wrapped in a div of
+ * our own.
  *
- * @param props - Component properties.
- * @see {@link Props}
+ * This is the whole of the behaviour; {@link IntersectionObserverComponent} is this
+ * hook plus a div to hang it on. Reach for the hook when the element to watch is
+ * already in the tree — a component's own root, typically — and for the component
+ * when there is nothing to watch yet and a box has to be created.
  *
- * @returns A div element wrapping `children`, observed for intersection changes.
+ * @param targetRef - The element to observe. Nothing happens until it is attached.
+ * @param options - See {@link ObserverOptions}.
+ * @param onIntersected - Called on every intersection change.
+ * @param enabled - `false` skips the observer entirely, for a caller whose need for
+ * it depends on its own props. A hook cannot be called conditionally; this is how
+ * the condition is expressed.
+ *
+ * @returns The latest {@link IntersectionObserverEntry}, or `null` before the first.
  *
  * @remarks
  * - Automatically creates and disconnects the {@link IntersectionObserver} instance.
  * - Re-observes the element shortly after mount to handle late layout changes.
- * - Adds an `is-intersecting` modifier class when the element is intersecting.
  */
-export const IntersectionObserverComponent = ({ onIntersected, root, rootMargin, threshold, className, children }) => {
-    // Refs, handlers and effects
+export function useIntersectionObserver(targetRef, { root, rootMargin, threshold }, onIntersected, enabled = true) {
     const [ioEntry, setIoEntry] = useState(null);
-    const rootRef = useRef(null);
     const observerRef = useRef(null);
     const observation = useCallback((entries, observer) => {
         const thisEntry = entries[0];
@@ -31,33 +37,58 @@ export const IntersectionObserverComponent = ({ onIntersected, root, rootMargin,
         setIoEntry(thisEntry);
     }, [onIntersected]);
     const forceObservation = useCallback(() => {
-        const rootEl = rootRef.current;
+        const targetEl = targetRef.current;
         const observer = observerRef.current;
-        if (rootEl === null || observer === null)
+        if (targetEl === null || observer === null)
             return;
-        observer.unobserve(rootEl);
-        observer.observe(rootEl);
-    }, []);
+        observer.unobserve(targetEl);
+        observer.observe(targetEl);
+    }, [targetRef]);
     useEffect(() => {
-        const rootEl = rootRef.current;
-        if (rootEl === null) {
+        if (!enabled)
+            return;
+        const targetEl = targetRef.current;
+        if (targetEl === null) {
             // eslint-disable-next-line no-console
-            console.warn('rootRef.current should not be null');
+            console.warn('targetRef.current should not be null');
             return;
         }
         const observer = new IntersectionObserver(observation, { root, rootMargin, threshold });
         observerRef.current = observer;
-        observer.observe(rootEl);
+        observer.observe(targetEl);
         return () => observer.disconnect();
-    }, [root, rootMargin, threshold, observation]);
+    }, [enabled, targetRef, root, rootMargin, threshold, observation]);
     useEffect(() => {
+        if (!enabled)
+            return;
         const timeout1 = window.setTimeout(forceObservation, 100);
         const timeout2 = window.setTimeout(forceObservation, 500);
         return () => {
             window.clearTimeout(timeout1);
             window.clearTimeout(timeout2);
         };
-    }, [forceObservation]);
+    }, [enabled, forceObservation]);
+    return ioEntry;
+}
+/**
+ * Component that observes its root element using the IntersectionObserver API
+ * and notifies consumers about visibility changes.
+ *
+ * A div and {@link useIntersectionObserver}, and nothing else. A component that
+ * already renders the element it wants watched should use the hook and keep its own
+ * root, rather than gain a wrapper it has no other use for.
+ *
+ * @param props - Component properties.
+ * @see {@link Props}
+ *
+ * @returns A div element wrapping `children`, observed for intersection changes.
+ *
+ * @remarks
+ * - Adds an `is-intersecting` modifier class when the element is intersecting.
+ */
+export const IntersectionObserverComponent = ({ onIntersected, root, rootMargin, threshold, className, children }) => {
+    const rootRef = useRef(null);
+    const ioEntry = useIntersectionObserver(rootRef, { root, rootMargin, threshold }, onIntersected);
     // Rendering
     const c = clss(publicClassName, { cssModule });
     const isIntersecting = ioEntry?.isIntersecting ?? false;

package/components/Video/index.controlled.d.ts

@@ -1,32 +1,13 @@
-import { type FunctionComponent, type PropsWithChildren, type VideoHTMLAttributes } from 'react';
+import { type FunctionComponent, type PropsWithChildren, type Ref, type RefObject, type VideoHTMLAttributes } from 'react';
 import type { WithClassName } from '../utils/types.js';
 import { type Props as SubsProps } from '../Subtitles/index.js';
+import { type SourceData, type TrackData } from './utils.js';
 /**
  * Describes a single video source.
  *
  * @property src - URL of the video file.
  * @property type - MIME type of the source (e.g. `'video/mp4'`).
  */
-type SourceData = {
-    src?: string;
-    type?: string;
-};
-/**
- * Describes a single text track (subtitles, captions, chapters, etc.).
- *
- * @property src - URL of the track file.
- * @property kind - Track type, maps directly to the `<track>` `kind` attribute.
- * @property srclang - Language of the track content (e.g. `'fr'`, `'en'`).
- * @property label - Human-readable label shown in the browser's track selector.
- * @property default - When `true`, marks this track as the default selection.
- */
-type TrackData = {
-    src?: string;
-    kind?: 'subtitles' | 'captions' | 'descriptions' | 'chapters' | 'metadata';
-    srclang?: string;
-    label?: string;
-    default?: boolean;
-};
 /**
  * Props for the ControlledVideo component.
  *
@@ -113,6 +94,9 @@ type TrackData = {
  * Also inherits all standard HTML props for a <video> element.
  */
 export type Props = PropsWithChildren<WithClassName<{
+    rootRef?: Ref<HTMLElement>;
+    videoRef?: RefObject<HTMLVideoElement | null>;
+    togglePlayOnClick?: boolean;
     sources?: string | string[] | SourceData[];
     tracks?: string | string[] | TrackData[];
     subtitles?: SubsProps;
@@ -139,6 +123,7 @@ export type Props = PropsWithChildren<WithClassName<{
     onFullscreenButtonClicked?: (e: React.MouseEvent<HTMLButtonElement>, isFullscreen: boolean, video: HTMLVideoElement | null) => void;
     onSubtitlesButtonClicked?: (e: React.MouseEvent<HTMLButtonElement>, isSubtitlesOn: boolean, video: HTMLVideoElement | null) => void;
     onTimelineClicked?: (e: React.MouseEvent<HTMLDivElement>, targetTime: number, currentTime: number, video: HTMLVideoElement | null) => void;
+    onVideoClicked?: (e: React.MouseEvent<HTMLVideoElement>, isPlaying: boolean, video: HTMLVideoElement | null) => void;
     onIsPlayingChanged?: (isPlaying: boolean) => void;
     onIsFullscreenChanged?: (isFullscreen: boolean) => void;
     onIsLoudChanged?: (isLoud: boolean) => void;
@@ -193,4 +178,3 @@ export type Props = PropsWithChildren<WithClassName<{
  * subtitles.
  */
 export declare const ControlledVideo: FunctionComponent<Props>;
-export {};

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, ...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", { 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,36 +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 wrapperClassName - Optional additional class name(s) applied to the root wrapper element.
+ * @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…`,
@@ -39,17 +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'>> & {
+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;
-    wrapperClassName?: string;
 };
 /**
  * Full-featured video player component. Wraps a native `<video>` element with
@@ -72,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
@@ -85,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