@design-edito/tools 0.5.1 → 0.5.3

package/components/Video/index.controlled.js

@@ -1,7 +1,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 { mergeClassNames } from '../utils/index.js';
+import { mergeClassNames, 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';
@@ -41,79 +41,79 @@ import { forceExitFullscreen, forceFullscreen, forceLoud, forceMute, forcePause,
  * @returns A `<figure>` element containing the video, its controls, optional
  * subtitles.
  */
-export const ControlledVideo = ({ sources, tracks, subtitles, playBtnContent, pauseBtnContent, loudBtnContent, muteBtnContent, fullscreenBtnContent, play, fullscreen, mute, muted, volume = 1, playbackRate = 1, currentTimeMs: givenCurrentTimeMs, actionHandlers, stateHandlers, children, className, _modifiers, ...intrinsicVideoAttributes }) => {
+export const ControlledVideo = ({ sources, tracks, subtitles, playBtnContent, pauseBtnContent, loudBtnContent, muteBtnContent, fullscreenBtnContent, play, fullscreen, mute, muted, volume = 1, playbackRate = 1, currentTimeMs: givenCurrentTimeMs, onPlayButtonClicked, onPauseButtonClicked, onLoudButtonClicked, onMuteButtonClicked, onVolumeRangeChanged, onRateRangeChanged, onFullscreenButtonClicked, onTimelineClicked, onIsPlayingChanged, onIsFullscreenChanged, onIsLoudChanged, onVolumeChanged, onPlaybackRateChanged, onCurrentTimeMsChanged, onFullscreenChange, children, className, ...intrinsicVideoAttributes }) => {
     const videoRef = useRef(null);
     const [totalTime, setTotalTime] = useState(0);
     const totalTimeMs = useMemo(() => secondsToMs(totalTime), [totalTime]);
-    const [currentTimeMs, setCurrentTimeMs] = useState(0);
+    const [internalCurrentTimeMs, setInternalCurrentTimeMs] = useState(0);
+    const isTimeControlled = givenCurrentTimeMs !== undefined;
+    // The parent owns the time as soon as it provides one, so that is what gets
+    // displayed — not what the element reported one render later.
+    const currentTimeMs = givenCurrentTimeMs ?? internalCurrentTimeMs;
     const currentTime = useMemo(() => msToSeconds(currentTimeMs), [currentTimeMs]);
-    const isTimeControlled = useMemo(() => givenCurrentTimeMs !== undefined, [givenCurrentTimeMs]);
     const volumePercent = useMemo(() => volume * 100, [volume]);
+    // Every state item this component displays is read from its props, never from
+    // the element: it is the parent's job to keep them in sync.
+    const isPlaying = play ?? false;
+    const isLoud = !(mute ?? false);
+    const isFullscreen = fullscreen ?? false;
     // Intrinsic event handler
     const handleMetadataLoadEvent = useCallback((e) => {
         if (videoRef.current === null)
             return;
         const video = videoRef.current;
         setTotalTime(video.duration);
+        // A seek asked for before the metadata landed was silently dropped by the
+        // element — replay it now that it can be honoured.
+        if (givenCurrentTimeMs !== undefined)
+            video.currentTime = msToSeconds(givenCurrentTimeMs);
         intrinsicVideoAttributes.onLoadedMetadata?.(e);
-    }, [intrinsicVideoAttributes.onLoadedMetadata]);
+    }, [intrinsicVideoAttributes.onLoadedMetadata, givenCurrentTimeMs]);
     const handleOnTimeUpdateEvent = useCallback((e) => {
         const video = e.currentTarget;
         const newTimeMs = secondsToMs(video.currentTime);
-        setCurrentTimeMs(newTimeMs);
+        setInternalCurrentTimeMs(newTimeMs);
         if (intrinsicVideoAttributes.onTimeUpdate !== undefined)
             intrinsicVideoAttributes.onTimeUpdate(e);
     }, [intrinsicVideoAttributes.onTimeUpdate]);
-    const handleOnPlayEvent = useCallback((e) => {
-        /* We must never play a video that has controlled time */
-        if (isTimeControlled) {
-            videoRef.current?.pause();
-            return;
-        }
-        intrinsicVideoAttributes.onPlay?.(e);
-    }, [isTimeControlled, intrinsicVideoAttributes.onPlay]);
     // Custom action handlers
     const handlePlayButtonClick = useCallback((e) => {
-        const isPlaying = videoRef.current !== null ? videoRef.current.paused : false;
-        actionHandlers?.playButtonClick?.(e, isPlaying, videoRef.current);
-    }, [actionHandlers?.playButtonClick]);
+        const wasPlaying = videoRef.current?.paused === false;
+        onPlayButtonClicked?.(e, wasPlaying, videoRef.current);
+    }, [onPlayButtonClicked]);
     const handlePauseButtonClick = useCallback((e) => {
-        const isPlaying = videoRef.current !== null ? videoRef.current.paused : false;
-        actionHandlers?.pauseButtonClick?.(e, isPlaying, videoRef.current);
-    }, [actionHandlers?.pauseButtonClick]);
+        const wasPlaying = videoRef.current?.paused === false;
+        onPauseButtonClicked?.(e, wasPlaying, videoRef.current);
+    }, [onPauseButtonClicked]);
     const handleLoudButtonClick = useCallback((e) => {
-        const isLoud = mute !== undefined ? !mute : false;
-        actionHandlers?.loudButtonClick?.(e, isLoud, videoRef.current);
-    }, [actionHandlers?.loudButtonClick, mute]);
+        onLoudButtonClicked?.(e, isLoud, videoRef.current);
+    }, [onLoudButtonClicked, isLoud]);
     const handleMuteButtonClick = useCallback((e) => {
-        const isLoud = mute !== undefined ? !mute : false;
-        actionHandlers?.muteButtonClick?.(e, isLoud, videoRef.current);
-    }, [actionHandlers?.muteButtonClick, mute]);
+        onMuteButtonClicked?.(e, isLoud, videoRef.current);
+    }, [onMuteButtonClicked, isLoud]);
     const handleFullscreenButtonClick = useCallback((e) => {
-        actionHandlers?.fullscreenButtonClick?.(e, fullscreen ?? false, videoRef.current);
-    }, [actionHandlers?.fullscreenButtonClick, fullscreen]);
+        onFullscreenButtonClicked?.(e, isFullscreen, videoRef.current);
+    }, [onFullscreenButtonClicked, isFullscreen]);
     const handleVolumeRangeChange = useCallback((e) => {
         const targetVolume = Number(e.currentTarget.value) / 100;
-        actionHandlers?.volumeRangeChange?.(e, targetVolume, volume, videoRef.current);
-    }, [actionHandlers?.volumeRangeChange, volume]);
+        onVolumeRangeChanged?.(e, targetVolume, volume, videoRef.current);
+    }, [onVolumeRangeChanged, volume]);
     const handleRateRangeChange = useCallback((e) => {
-        actionHandlers?.rateRangeChange?.(e, Number(e.currentTarget.value), playbackRate, videoRef.current);
-    }, [actionHandlers?.rateRangeChange, playbackRate]);
+        onRateRangeChanged?.(e, Number(e.currentTarget.value), playbackRate, videoRef.current);
+    }, [onRateRangeChanged, playbackRate]);
     const handleTimelineClick = useCallback((e) => {
         if (videoRef.current === null)
             return;
-        const progress = getTimelineClickProgress(e, e.currentTarget, videoRef.current);
+        const progress = getTimelineClickProgress(e);
         const targetTime = progress * totalTime;
-        actionHandlers?.timelineClick?.(e, targetTime, currentTime, videoRef.current);
-        /* If we are given a currentTimeMs prop, we consider that the current time is controlled by the parent component, and we should not attempt to set it here on timeline click, as it would create conflicts. The parent comp should update the currentTimeMs prop itself */
+        onTimelineClicked?.(e, targetTime, currentTime, videoRef.current);
+        // A controlled time is the parent's to move: it is expected to update the
+        // prop in response to this very handler.
         if (!isTimeControlled) {
             videoRef.current.currentTime = targetTime;
         }
-    }, [actionHandlers?.timelineClick, totalTime, currentTime, isTimeControlled]);
+    }, [onTimelineClicked, totalTime, currentTime, isTimeControlled]);
     // Rendering
-    const isPlaying = play ?? false;
-    const isLoud = mute ?? false;
-    const isFullscreen = fullscreen ?? false;
     const c = clss(publicClassName, { cssModule });
     const rootClss = mergeClassNames(c(null, {
         'play-on': isPlaying,
@@ -121,10 +121,11 @@ export const ControlledVideo = ({ sources, tracks, subtitles, playBtnContent, pa
         'fullscreen-on': isFullscreen,
         'fullscreen-off': !isFullscreen,
         'loud': isLoud,
-        'muted': !isLoud,
-        ..._modifiers
+        'muted': !isLoud
     }), className);
-    const appliedVolume = volume;
+    // Guarded: the duration is unknown until the metadata lands, and an unguarded
+    // division would expose the string 'NaN' on every render until then.
+    const currentTimeRatio = totalTime > 0 ? currentTime / totalTime : 0;
     const rootAttributes = {
         'data-play-on': isPlaying ? '' : undefined,
         'data-play-off': !isPlaying ? '' : undefined,
@@ -132,15 +133,15 @@ export const ControlledVideo = ({ sources, tracks, subtitles, playBtnContent, pa
         'data-fullscreen-off': !isFullscreen ? '' : undefined,
         'data-loud': isLoud ? '' : undefined,
         'data-muted': !isLoud ? '' : undefined,
-        'data-volume': appliedVolume.toFixed(8),
+        'data-volume': volume.toFixed(8),
         'data-volume-percent': volumePercent,
         'data-playback-rate': playbackRate,
         'data-current-time-ms': currentTimeMs.toFixed(2),
-        'data-current-time-ratio': (currentTime / totalTime).toFixed(8),
+        'data-current-time-ratio': currentTimeRatio.toFixed(8),
         'data-total-time-ms': totalTimeMs
     };
     const rootStyles = {
-        [`--${publicClassName}-current-time-ratio`]: (currentTime / totalTime).toFixed(8)
+        [`--${publicClassName}-current-time-ratio`]: currentTimeRatio.toFixed(8)
     };
     const parsedSources = useMemo(() => {
         if (sources === undefined)
@@ -201,8 +202,13 @@ export const ControlledVideo = ({ sources, tracks, subtitles, playBtnContent, pa
         };
     }, [fullscreen]);
     useEffect(() => {
-        if (isTimeControlled)
+        // A controlled time belongs to the parent, and a playing element advances
+        // the time on its own — so the two cannot coexist. Applied once, on entering
+        // the mode, rather than fought on every tick.
+        if (isTimeControlled) {
+            void forcePause(videoRef.current);
             return;
+        }
         if (play === true) {
             void forcePlay(videoRef.current);
         }
@@ -214,10 +220,9 @@ export const ControlledVideo = ({ sources, tracks, subtitles, playBtnContent, pa
         forceVolume(videoRef.current, volume);
     }, [volume]);
     useEffect(() => {
-        if (givenCurrentTimeMs !== undefined && videoRef.current !== null) {
-            void forcePause(videoRef.current);
-            videoRef.current.currentTime = msToSeconds(givenCurrentTimeMs);
-        }
+        if (givenCurrentTimeMs === undefined || videoRef.current === null)
+            return;
+        videoRef.current.currentTime = msToSeconds(givenCurrentTimeMs);
     }, [givenCurrentTimeMs]);
     useEffect(() => {
         if (mute === true) {
@@ -227,30 +232,28 @@ export const ControlledVideo = ({ sources, tracks, subtitles, playBtnContent, pa
             forceLoud(videoRef.current);
         }
     }, [mute]);
-    // State handlers
-    useEffect(() => {
-        if (stateHandlers?.currentTime !== undefined) {
-            stateHandlers.currentTime(msToSeconds(currentTimeMs));
-        }
-    }, [currentTimeMs, stateHandlers?.currentTime]);
-    useEffect(() => {
-        stateHandlers?.isPlaying?.(isPlaying);
-    }, [isPlaying, stateHandlers?.isPlaying]);
-    useEffect(() => {
-        stateHandlers?.isFullscreen?.(isFullscreen);
-    }, [isFullscreen, stateHandlers?.isFullscreen]);
+    // The browser can leave fullscreen without going through our button — Escape,
+    // or the platform's own exit gesture. Nothing in React reports it, so the real
+    // event is the only way for a parent to keep its `fullscreen` prop truthful.
     useEffect(() => {
-        stateHandlers?.isLoud?.(isLoud);
-    }, [isLoud, stateHandlers?.isLoud]);
-    useEffect(() => {
-        stateHandlers?.volume?.(volume);
-    }, [volume, stateHandlers?.volume]);
-    useEffect(() => {
-        stateHandlers?.playbackRate?.(playbackRate);
-    }, [playbackRate, stateHandlers?.playbackRate]);
-    return _jsxs("figure", { className: rootClss, style: rootStyles, ...rootAttributes, children: [_jsxs("video", { ref: videoRef, className: videoClss, ...intrinsicVideoAttributes, onLoadedMetadata: handleMetadataLoadEvent, onPlay: handleOnPlayEvent, onTimeUpdate: handleOnTimeUpdateEvent, children: [parsedSources.map((source, index) => typeof source === 'string'
+        if (onFullscreenChange === undefined)
+            return;
+        const onDocumentFullscreenChange = () => {
+            onFullscreenChange(document.fullscreenElement !== null);
+        };
+        document.addEventListener('fullscreenchange', onDocumentFullscreenChange);
+        return () => { document.removeEventListener('fullscreenchange', onDocumentFullscreenChange); };
+    }, [onFullscreenChange]);
+    // State handlers
+    useChangeDispatch(currentTimeMs, onCurrentTimeMsChanged);
+    useChangeDispatch(isPlaying, onIsPlayingChanged);
+    useChangeDispatch(isFullscreen, onIsFullscreenChanged);
+    useChangeDispatch(isLoud, onIsLoudChanged);
+    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, 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 }), _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: formatTime(currentTimeMs, 'mm:ss:ms') }), _jsx("span", { className: totalTimeClss, children: formatTime(totalTimeMs, 'mm:ss:ms') }), _jsx("div", { className: timelineClss, onClick: handleTimelineClick })] }), subtitles !== undefined && _jsx(Subtitles, { ...subtitles, timecodeMs: currentTimeMs })] });
+                        : _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 }), _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: formatTime(currentTimeMs, 'mm:ss:ms') }), _jsx("span", { className: totalTimeClss, children: formatTime(totalTimeMs, 'mm:ss:ms') }), _jsx("div", { className: timelineClss, onClick: handleTimelineClick })] }), subtitles !== undefined && _jsx(Subtitles, { ...subtitles, timecodeMs: currentTimeMs })] });
 };

package/components/Video/index.d.ts

@@ -1,31 +1,29 @@
 import { type FunctionComponent } from 'react';
-import { type Props as DisclaimerProps } from '../Disclaimer/index.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 disclaimer - Props forwarded to the internal {@link Disclaimer} component.
- * While the disclaimer is active, `autoPlay` and `muted` are suppressed on the
- * underlying `<video>` element.
  * @property autoPlayWhenVisible - When `true`, triggers playback the first time the
- * component intersects the viewport, provided no disclaimer is active.
+ * component intersects the viewport.
  * @property autoPauseWhenHidden - When `true`, pauses playback whenever the component
  * leaves the viewport.
  * @property autoLoudWhenVisible - When `true`, unmutes the video the first time the
- * component intersects the viewport, provided no disclaimer is active.
+ * component intersects the viewport.
  * @property autoMuteWhenHidden - When `true`, mutes the video whenever the component
  * leaves the viewport.
- * @property currentTimeMs - When provided, forces the video's current time to the given value (in milliseconds). Giving the currentTimeMs prop puts the component in a controlled state for the current time, meaning that the parent component is responsible for updating the current time. In this mode, user interactions that would normally change the current time (play, pause, timeline click) will not have an effect unless the parent component updates the currentTimeMs prop accordingly.
+ * @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
+ * long as this prop is provided.
  * @property wrapperClassName - Optional additional class name(s) applied to the root wrapper element.
- * @property stateHandlers - Optional callbacks invoked whenever the corresponding
- * state changes. Useful for synchronizing external state with the internal video state.
  * @property className - Optional additional class name(s) applied to the root element.
  * @property children - React children rendered inside the `<video>` element itself
  * (e.g. fallback content).
  */
 export type Props = Omit<ControlledProps, 'play' | 'fullscreen' | 'volume' | 'mute' | 'playbackRate'> & {
-    disclaimer?: DisclaimerProps;
     autoPlayWhenVisible?: boolean;
     autoPauseWhenHidden?: boolean;
     autoLoudWhenVisible?: boolean;
@@ -34,12 +32,12 @@ export type Props = Omit<ControlledProps, 'play' | 'fullscreen' | 'volume' | 'mu
 };
 /**
  * Full-featured video player component. Wraps a native `<video>` element with
- * playback controls, volume, playback rate, a timeline, optional subtitles,
- * an optional disclaimer gate, and viewport-driven auto-play/mute behaviours.
+ * playback controls, volume, playback rate, a timeline, optional subtitles, and
+ * viewport-driven auto-play/mute behaviours.
  *
  * @param props - Component properties.
  * @see {@link Props}
- * @returns A `<figure>` element containing the video, its controls, optional
- * subtitles, and an optional disclaimer overlay.
+ * @returns A `<figure>` element containing the video, its controls and optional
+ * subtitles.
  */
 export declare const Video: FunctionComponent<Props>;

package/components/Video/index.js

@@ -1,7 +1,6 @@
 import { jsx as _jsx } from "react/jsx-runtime";
 import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
 import { clss } from '../../agnostic/css/clss/index.js';
-import { Disclaimer } from '../Disclaimer/index.js';
 import { IntersectionObserverComponent } from '../IntersectionObserver/index.js';
 import { mergeClassNames } from '../utils/index.js';
 import { videoWrapper as publicClassName } from '../public-classnames.js';
@@ -10,33 +9,27 @@ import cssModule from './styles.module.css';
 import { ControlledVideo } from './index.controlled.js';
 /**
  * Full-featured video player component. Wraps a native `<video>` element with
- * playback controls, volume, playback rate, a timeline, optional subtitles,
- * an optional disclaimer gate, and viewport-driven auto-play/mute behaviours.
+ * playback controls, volume, playback rate, a timeline, optional subtitles, and
+ * viewport-driven auto-play/mute behaviours.
  *
  * @param props - Component properties.
  * @see {@link Props}
- * @returns A `<figure>` element containing the video, its controls, optional
- * subtitles, and an optional disclaimer overlay.
+ * @returns A `<figure>` element containing the video, its controls and optional
+ * subtitles.
  */
-export const Video = ({ loop, disclaimer, autoPlayWhenVisible, autoPauseWhenHidden, autoMuteWhenHidden, autoLoudWhenVisible, wrapperClassName, ...controlledProps }) => {
+export const Video = ({ loop, autoPlayWhenVisible, autoPauseWhenHidden, autoMuteWhenHidden, autoLoudWhenVisible, wrapperClassName, onPlayButtonClicked, onPauseButtonClicked, onLoudButtonClicked, onMuteButtonClicked, onVolumeRangeChanged, onRateRangeChanged, onFullscreenButtonClicked, ...controlledProps }) => {
     // State & refs
     const [play, setPlay] = useState(false);
     const [volume, setVolume] = useState(1);
     const [mute, setMute] = useState(false);
     const [playbackRate, setPlaybackRate] = useState(1);
     const [fullscreen, setFullscreen] = useState(false);
-    const [isDisclaimerOn, setIsDisclaimerOn] = useState(disclaimer?.isOn === true
-        || disclaimer?.defaultIsOn === true
-        || (disclaimer !== undefined && disclaimer.defaultIsOn === undefined));
     const hasBeenAutoPlayed = useRef(false);
-    const needsDisclaimer = useMemo(() => disclaimer !== undefined, [disclaimer]);
-    const shouldDisclaimerBeOn = useMemo(() => {
-        if (disclaimer?.isOn === false)
-            return false;
-        if (disclaimer?.isOn === true)
-            return true;
-        return isDisclaimerOn;
-    }, [disclaimer, isDisclaimerOn]);
+    // 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.
+    const isTimeControlled = controlledProps.currentTimeMs !== undefined;
     const needsObserve = useMemo(() => autoLoudWhenVisible === true
         || autoMuteWhenHidden === true
         || autoPlayWhenVisible === true
@@ -49,13 +42,9 @@ export const Video = ({ loop, disclaimer, autoPlayWhenVisible, autoPauseWhenHidd
     // Intrisic event handlers
     const handleOnPlayEvent = useCallback((e) => {
         controlledProps.onPlay?.(e);
-        if (shouldDisclaimerBeOn) {
-            setPlay(false);
-            return;
-        }
         setPlay(true);
         hasBeenAutoPlayed.current = true;
-    }, [controlledProps.onPlay, shouldDisclaimerBeOn]);
+    }, [controlledProps.onPlay]);
     const handleOnPauseEvent = useCallback((e) => {
         setPlay(false);
         controlledProps.onPause?.(e);
@@ -69,45 +58,44 @@ export const Video = ({ loop, disclaimer, autoPlayWhenVisible, autoPauseWhenHidd
         setPlaybackRate(e.currentTarget.playbackRate);
         controlledProps.onRateChange?.(e);
     }, [controlledProps.onRateChange]);
-    const handleOnFullscreenChangeEvent = useCallback((e) => {
-        if (document.fullscreenElement === null || shouldDisclaimerBeOn) {
+    const handleFullscreenChange = useCallback((isFullscreen) => {
+        if (!isFullscreen)
             setFullscreen(false);
-        }
-    }, [shouldDisclaimerBeOn]);
+    }, []);
     const handleOnLoadedMetadataEvent = useCallback((e) => {
         muteAttributeWorkaround(e.currentTarget, controlledProps.muted ?? false);
         controlledProps.onLoadedMetadata?.(e);
     }, [controlledProps.onLoadedMetadata, controlledProps.muted]);
     // User actions
     const handlePlayButtonClick = useCallback((e, isPlaying, video) => {
-        controlledProps.actionHandlers?.playButtonClick?.(e, isPlaying, video);
-        setPlay(!shouldDisclaimerBeOn);
-    }, [controlledProps.actionHandlers, shouldDisclaimerBeOn]);
+        onPlayButtonClicked?.(e, isPlaying, video);
+        setPlay(true);
+    }, [onPlayButtonClicked]);
     const handlePauseButtonClick = useCallback((e, isPlaying, video) => {
-        controlledProps.actionHandlers?.pauseButtonClick?.(e, isPlaying, video);
+        onPauseButtonClicked?.(e, isPlaying, video);
         setPlay(false);
-    }, [controlledProps.actionHandlers]);
+    }, [onPauseButtonClicked]);
     const handleLoudButtonClick = useCallback((e, isLoud, video) => {
-        controlledProps.actionHandlers?.loudButtonClick?.(e, isLoud, video);
+        onLoudButtonClicked?.(e, isLoud, video);
         setMute(false);
-    }, [controlledProps.actionHandlers]);
+    }, [onLoudButtonClicked]);
     const handleMuteButtonClick = useCallback((e, isLoud, video) => {
-        controlledProps.actionHandlers?.muteButtonClick?.(e, isLoud, video);
+        onMuteButtonClicked?.(e, isLoud, video);
         setMute(true);
-    }, [controlledProps.actionHandlers]);
+    }, [onMuteButtonClicked]);
     const handleRateRangeChange = useCallback((e, targetRate, currentRate, video) => {
-        controlledProps.actionHandlers?.rateRangeChange?.(e, targetRate, currentRate, video);
+        onRateRangeChanged?.(e, targetRate, currentRate, video);
         setPlaybackRate(targetRate);
-    }, [controlledProps.actionHandlers]);
+    }, [onRateRangeChanged]);
     const handleVolumeRangeChange = useCallback((e, targetVolume, currentVolume, video) => {
-        controlledProps.actionHandlers?.volumeRangeChange?.(e, targetVolume, currentVolume, video);
+        onVolumeRangeChanged?.(e, targetVolume, currentVolume, video);
         setVolume(targetVolume);
-    }, [controlledProps.actionHandlers]);
+    }, [onVolumeRangeChanged]);
     const handleFullscreenButtonClick = useCallback((e, isFullscreen, video) => {
-        controlledProps.actionHandlers?.fullscreenButtonClick?.(e, isFullscreen, video);
-        setFullscreen((prev) => shouldDisclaimerBeOn ? false : !isFullscreen);
-    }, [controlledProps.actionHandlers, shouldDisclaimerBeOn]);
-    // Intersection Observer + Disclaimer
+        onFullscreenButtonClicked?.(e, isFullscreen, video);
+        setFullscreen(!isFullscreen);
+    }, [onFullscreenButtonClicked]);
+    // Intersection Observer
     const onIntersected = useCallback(({ ioEntry }) => {
         if (ioEntry === undefined)
             return;
@@ -117,12 +105,10 @@ export const Video = ({ loop, disclaimer, autoPlayWhenVisible, autoPauseWhenHidd
         if (autoLoudWhenVisible === true && isIntersecting)
             setMute(false);
         if (autoPlayWhenVisible === true
-            && !shouldDisclaimerBeOn
             && !hasBeenAutoPlayed.current
             && isIntersecting)
             setPlay(true);
         if (autoMuteWhenHidden === true
-            && !shouldDisclaimerBeOn
             && !hasBeenAutoPlayed.current
             && !isIntersecting)
             setMute(true);
@@ -130,50 +116,19 @@ export const Video = ({ loop, disclaimer, autoPlayWhenVisible, autoPauseWhenHidd
         autoPlayWhenVisible,
         autoPauseWhenHidden,
         autoMuteWhenHidden,
-        autoLoudWhenVisible,
-        shouldDisclaimerBeOn
+        autoLoudWhenVisible
     ]);
-    const handleDiclaimerDismiss = useCallback((prevIsOn) => {
-        setIsDisclaimerOn(false);
-        if (controlledProps.autoPlay === true && !hasBeenAutoPlayed.current) {
-            setPlay(true);
-        }
-        disclaimer?.actionHandlers?.dismissClick?.(prevIsOn);
-    }, [controlledProps.autoPlay, disclaimer?.actionHandlers?.dismissClick]);
+    // `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 (isDisclaimerOn !== shouldDisclaimerBeOn)
-            setIsDisclaimerOn(shouldDisclaimerBeOn);
-    }, [isDisclaimerOn, shouldDisclaimerBeOn]);
-    useEffect(() => {
-        if (shouldDisclaimerBeOn) {
-            setMute(true);
-            setPlay(false);
-            setFullscreen(false);
-        }
-        else if (controlledProps.autoPlay === true && !hasBeenAutoPlayed.current) {
+        if (controlledProps.autoPlay === true && !hasBeenAutoPlayed.current)
             setPlay(true);
-        }
-    }, [shouldDisclaimerBeOn]);
+    }, []);
     // Render
     const c = clss(publicClassName, { cssModule });
-    const rootClss = mergeClassNames(c(null, {}), wrapperClassName);
-    const sensitiveContent = _jsx(ControlledVideo, { ...controlledProps, play: play, volume: volume, mute: mute, playbackRate: playbackRate, fullscreen: fullscreen, onPlay: handleOnPlayEvent, onPause: handleOnPauseEvent, onVolumeChange: handleOnVolumeChangeEvent, onRateChange: handleOnRateChangeEvent, onLoadedMetadata: handleOnLoadedMetadataEvent, onFullscreenChange: handleOnFullscreenChangeEvent, actionHandlers: {
-            ...controlledProps.actionHandlers,
-            playButtonClick: handlePlayButtonClick,
-            pauseButtonClick: handlePauseButtonClick,
-            loudButtonClick: handleLoudButtonClick,
-            muteButtonClick: handleMuteButtonClick,
-            volumeRangeChange: handleVolumeRangeChange,
-            rateRangeChange: handleRateRangeChange,
-            fullscreenButtonClick: handleFullscreenButtonClick
-        } });
-    const disclaimedContent = needsDisclaimer
-        ? _jsx(Disclaimer, { ...disclaimer, actionHandlers: {
-                ...disclaimer?.actionHandlers,
-                dismissClick: handleDiclaimerDismiss
-            }, children: sensitiveContent })
-        : sensitiveContent;
-    return (_jsx("div", { className: rootClss, children: needsObserve
-            ? _jsx(IntersectionObserverComponent, { onIntersected: onIntersected, children: disclaimedContent })
-            : disclaimedContent }));
+    const rootClss = mergeClassNames(c(), wrapperClassName);
+    const videoContent = _jsx(ControlledVideo, { ...controlledProps, play: play && !isTimeControlled, volume: volume, mute: mute, playbackRate: playbackRate, fullscreen: fullscreen, onPlay: handleOnPlayEvent, onPause: handleOnPauseEvent, onVolumeChange: handleOnVolumeChangeEvent, onRateChange: handleOnRateChangeEvent, onLoadedMetadata: handleOnLoadedMetadataEvent, onFullscreenChange: handleFullscreenChange, onPlayButtonClicked: handlePlayButtonClick, onPauseButtonClicked: handlePauseButtonClick, onLoudButtonClicked: handleLoudButtonClick, onMuteButtonClicked: handleMuteButtonClick, onVolumeRangeChanged: handleVolumeRangeChange, onRateRangeChanged: handleRateRangeChange, onFullscreenButtonClicked: handleFullscreenButtonClick });
+    return _jsx("div", { className: rootClss, children: needsObserve
+            ? _jsx(IntersectionObserverComponent, { onIntersected: onIntersected, children: videoContent })
+            : videoContent });
 };

package/components/Video/utils.d.ts

@@ -1,9 +1,7 @@
-import type { Dispatch, SetStateAction } from 'react';
 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;
 export declare const forceVolume: (video: HTMLVideoElement | null, volume: number) => void;
-export declare const forceCurrentTime: (video: HTMLVideoElement | null, time: number, setCurrentTime: Dispatch<SetStateAction<number>>) => void;
 export declare const forcePlay: (video: HTMLVideoElement | null) => Promise<boolean>;
 export declare const forcePause: (video: HTMLVideoElement | null) => boolean;
 export declare const forcePlaybackRate: (video: HTMLVideoElement | null, rate: number) => void;
@@ -11,5 +9,39 @@ export declare const forceFullscreen: (video: HTMLVideoElement | null) => Promis
 export declare const forceExitFullscreen: (video: HTMLVideoElement | null) => Promise<boolean>;
 export declare function secondsToMs(seconds: number): number;
 export declare function msToSeconds(ms: number): number;
+/**
+ * Renders a duration into a caller-defined pattern.
+ *
+ * The pattern is a free-form string in which the following tokens are replaced,
+ * longest first, so that `mm` is consumed before `m`:
+ *
+ * - `hh`, `mm`, `ss` — hours, minutes and seconds, zero-padded to two digits.
+ * - `ms` — the remaining milliseconds, zero-padded to three digits.
+ * - `frame` — the remaining milliseconds expressed in frames, zero-padded to two
+ *   digits.
+ * - `h`, `m`, `s`, `f` — the same four values, unpadded.
+ *
+ * @param ms - The duration, in milliseconds.
+ * @param format - The pattern to fill, e.g. `'mm:ss:ms'`.
+ * @param fps - Frame rate used to derive the `frame` and `f` tokens. Defaults to `25`.
+ * @returns The formatted duration.
+ *
+ * @remarks
+ * Every field is a remainder of the one above it, never a total: at one hour and
+ * a half, `mm` is `30`, not `90`. A pattern that omits `hh` therefore loses the
+ * hours rather than folding them into the minutes.
+ *
+ * Since `h`, `m`, `s` and `f` are tokens on their own, **every** occurrence of
+ * those letters is substituted, wherever it sits: `'mm min ss'` renders as
+ * `'01 1in 01'`. Separate the fields with punctuation. This is what
+ * `agnostic/time/dates/format-date` avoids by delimiting its tokens with
+ * `{{…}}` — worth aligning on the day this one is made public.
+ */
 export declare function formatTime(ms: number, format: string, fps?: number): string;
-export declare const getTimelineClickProgress: (event: React.MouseEvent<HTMLDivElement>, timeline: HTMLDivElement | null, video: HTMLVideoElement | null) => number;
+/**
+ * Where along the timeline a click landed.
+ *
+ * @param event - The click on the timeline element.
+ * @returns A ratio between `0` and `1`, clamped to the element's own bounds.
+ */
+export declare const getTimelineClickProgress: (event: React.MouseEvent<HTMLDivElement>) => number;

package/components/Video/utils.js

@@ -28,13 +28,6 @@ export const forceVolume = (video, volume) => {
     // eslint-disable-next-line no-param-reassign
     video.volume = volume;
 };
-export const forceCurrentTime = (video, time, setCurrentTime) => {
-    if (video === null)
-        return;
-    // eslint-disable-next-line no-param-reassign
-    video.currentTime = time;
-    setCurrentTime(time);
-};
 export const forcePlay = async (video) => {
     if (video === null)
         return false;
@@ -105,6 +98,34 @@ export function secondsToMs(seconds) {
 export function msToSeconds(ms) {
     return ms / 1000;
 }
+/**
+ * Renders a duration into a caller-defined pattern.
+ *
+ * The pattern is a free-form string in which the following tokens are replaced,
+ * longest first, so that `mm` is consumed before `m`:
+ *
+ * - `hh`, `mm`, `ss` — hours, minutes and seconds, zero-padded to two digits.
+ * - `ms` — the remaining milliseconds, zero-padded to three digits.
+ * - `frame` — the remaining milliseconds expressed in frames, zero-padded to two
+ *   digits.
+ * - `h`, `m`, `s`, `f` — the same four values, unpadded.
+ *
+ * @param ms - The duration, in milliseconds.
+ * @param format - The pattern to fill, e.g. `'mm:ss:ms'`.
+ * @param fps - Frame rate used to derive the `frame` and `f` tokens. Defaults to `25`.
+ * @returns The formatted duration.
+ *
+ * @remarks
+ * Every field is a remainder of the one above it, never a total: at one hour and
+ * a half, `mm` is `30`, not `90`. A pattern that omits `hh` therefore loses the
+ * hours rather than folding them into the minutes.
+ *
+ * Since `h`, `m`, `s` and `f` are tokens on their own, **every** occurrence of
+ * those letters is substituted, wherever it sits: `'mm min ss'` renders as
+ * `'01 1in 01'`. Separate the fields with punctuation. This is what
+ * `agnostic/time/dates/format-date` avoids by delimiting its tokens with
+ * `{{…}}` — worth aligning on the day this one is made public.
+ */
 export function formatTime(ms, format, fps = 25) {
     const totalSeconds = Math.floor(ms / 1000);
     const hours = Math.floor(totalSeconds / 3600);
@@ -123,17 +144,19 @@ export function formatTime(ms, format, fps = 25) {
         s: seconds,
         f: frames
     };
-    const result = Object
+    return Object
         .keys(tokens)
         .sort((a, b) => b.length - a.length)
         .reduce((acc, t) => acc.replace(new RegExp(t, 'gv'), String(tokens[t])), format);
-    return result;
 }
-export const getTimelineClickProgress = (event, timeline, video) => {
-    if (video === null || timeline === null)
-        return 0;
+/**
+ * Where along the timeline a click landed.
+ *
+ * @param event - The click on the timeline element.
+ * @returns A ratio between `0` and `1`, clamped to the element's own bounds.
+ */
+export const getTimelineClickProgress = (event) => {
     const timelineRect = event.currentTarget.getBoundingClientRect();
     const position = event.clientX - timelineRect.left;
-    const progress = Math.min(1, Math.max(0, position / timelineRect.width));
-    return progress;
+    return Math.min(1, Math.max(0, position / timelineRect.width));
 };