@design-edito/tools 0.5.5 → 0.5.7

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

@@ -69,6 +69,8 @@ type TrackData = {
  * seeks to the target right after, unless the time is controlled.
  * @property onIsPlayingChanged - Called once the playback state has changed.
  * @property onIsFullscreenChanged - Called once the fullscreen state has changed.
+ * @property onIsEndedChanged - Called after playback reached the end, and again
+ * once it left it — a seek back or a new play. Never on mount.
  * @property onIsLoudChanged - Called once the mute state has changed (`true` = unmuted).
  * @property onVolumeChanged - Called once the volume has changed (`0` to `1`).
  * @property onPlaybackRateChanged - Called once the playback rate has changed.
@@ -109,6 +111,7 @@ export type Props = PropsWithChildren<WithClassName<{
     onIsPlayingChanged?: (isPlaying: boolean) => void;
     onIsFullscreenChanged?: (isFullscreen: boolean) => void;
     onIsLoudChanged?: (isLoud: boolean) => void;
+    onIsEndedChanged?: (isEnded: boolean) => void;
     onVolumeChanged?: (volume: number) => void;
     onPlaybackRateChanged?: (playbackRate: number) => void;
     onCurrentTimeMsChanged?: (currentTimeMs: number) => void;
@@ -125,10 +128,12 @@ export type Props = PropsWithChildren<WithClassName<{
  * - `--play-on` / `--play-off` — reflects current playback state.
  * - `--fullscreen-on` / `--fullscreen-off` — reflects fullscreen state.
  * - `--loud` / `--muted` — reflects mute state.
+ * - `--ended` — playback reached the end and has not left it.
  *
  * ### Data attributes on the root element
  * - `data-play-on` — present (empty string) when playing.
  * - `data-play-off` — present (empty string) when paused.
+ * - `data-ended` — present (empty string) once playback reached the end.
  * - `data-fullscreen-on` — present (empty string) when in fullscreen.
  * - `data-fullscreen-off` — present (empty string) when not in fullscreen.
  * - `data-loud` — present (empty string) when unmuted.

package/components/Video/index.controlled.js

@@ -17,10 +17,12 @@ import { forceExitFullscreen, forceFullscreen, forceLoud, forceMute, forcePause,
  * - `--play-on` / `--play-off` — reflects current playback state.
  * - `--fullscreen-on` / `--fullscreen-off` — reflects fullscreen state.
  * - `--loud` / `--muted` — reflects mute state.
+ * - `--ended` — playback reached the end and has not left it.
  *
  * ### Data attributes on the root element
  * - `data-play-on` — present (empty string) when playing.
  * - `data-play-off` — present (empty string) when paused.
+ * - `data-ended` — present (empty string) once playback reached the end.
  * - `data-fullscreen-on` — present (empty string) when in fullscreen.
  * - `data-fullscreen-off` — present (empty string) when not in fullscreen.
  * - `data-loud` — present (empty string) when unmuted.
@@ -41,11 +43,16 @@ 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, onPlayButtonClicked, onPauseButtonClicked, onLoudButtonClicked, onMuteButtonClicked, onVolumeRangeChanged, onRateRangeChanged, onFullscreenButtonClicked, onTimelineClicked, onIsPlayingChanged, onIsFullscreenChanged, onIsLoudChanged, onVolumeChanged, onPlaybackRateChanged, onCurrentTimeMsChanged, onFullscreenChange, children, className, ...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, onIsEndedChanged, onVolumeChanged, onPlaybackRateChanged, onCurrentTimeMsChanged, onFullscreenChange, children, className, ...intrinsicVideoAttributes }) => {
     const videoRef = useRef(null);
     const [totalTime, setTotalTime] = useState(0);
     const totalTimeMs = useMemo(() => secondsToMs(totalTime), [totalTime]);
     const [internalCurrentTimeMs, setInternalCurrentTimeMs] = useState(0);
+    // Unlike play, mute and fullscreen, this one isn't a prop: nothing can *set* a
+    // media to ended, it is something the element reports. So it is read from the
+    // element, and the two events that turn it on and off are joined by a sync on
+    // every time update, which covers a seek away from the end.
+    const [isEnded, setIsEnded] = useState(false);
     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.
@@ -73,9 +80,18 @@ export const ControlledVideo = ({ sources, tracks, subtitles, playBtnContent, pa
         const video = e.currentTarget;
         const newTimeMs = secondsToMs(video.currentTime);
         setInternalCurrentTimeMs(newTimeMs);
+        setIsEnded(video.ended);
         if (intrinsicVideoAttributes.onTimeUpdate !== undefined)
             intrinsicVideoAttributes.onTimeUpdate(e);
     }, [intrinsicVideoAttributes.onTimeUpdate]);
+    const handleEndedEvent = useCallback((e) => {
+        setIsEnded(true);
+        intrinsicVideoAttributes.onEnded?.(e);
+    }, [intrinsicVideoAttributes.onEnded]);
+    const handlePlayEvent = useCallback((e) => {
+        setIsEnded(false);
+        intrinsicVideoAttributes.onPlay?.(e);
+    }, [intrinsicVideoAttributes.onPlay]);
     // Custom action handlers
     const handlePlayButtonClick = useCallback((e) => {
         const wasPlaying = videoRef.current?.paused === false;
@@ -118,6 +134,7 @@ export const ControlledVideo = ({ sources, tracks, subtitles, playBtnContent, pa
     const rootClss = mergeClassNames(c(null, {
         'play-on': isPlaying,
         'play-off': !isPlaying,
+        ended: isEnded,
         'fullscreen-on': isFullscreen,
         'fullscreen-off': !isFullscreen,
         'loud': isLoud,
@@ -129,6 +146,7 @@ export const ControlledVideo = ({ sources, tracks, subtitles, playBtnContent, pa
     const rootAttributes = {
         'data-play-on': isPlaying ? '' : undefined,
         'data-play-off': !isPlaying ? '' : undefined,
+        'data-ended': isEnded ? '' : undefined,
         'data-fullscreen-on': isFullscreen ? '' : undefined,
         'data-fullscreen-off': !isFullscreen ? '' : undefined,
         'data-loud': isLoud ? '' : undefined,
@@ -249,11 +267,12 @@ export const ControlledVideo = ({ sources, tracks, subtitles, playBtnContent, pa
     useChangeDispatch(isPlaying, onIsPlayingChanged);
     useChangeDispatch(isFullscreen, onIsFullscreenChanged);
     useChangeDispatch(isLoud, onIsLoudChanged);
+    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, children: [parsedSources.map((source, index) => typeof source === 'string'
+    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, 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, isEnded: isEnded })] });
 };

package/components/Video/index.d.ts

@@ -1,17 +1,29 @@
 import { type FunctionComponent } from 'react';
+import type { WithViewportObservation } from '../utils/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`, triggers playback the first time the
- * 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.
- * @property autoMuteWhenHidden - When `true`, mutes the video whenever the component
- * leaves the viewport.
+ * @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 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
@@ -23,11 +35,15 @@ 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 = Omit<ControlledProps, 'play' | 'fullscreen' | 'volume' | 'mute' | 'playbackRate'> & {
+export type Props = WithViewportObservation<Omit<ControlledProps, 'play' | 'fullscreen' | 'volume' | 'mute' | 'playbackRate'>> & {
     autoPlayWhenVisible?: boolean;
+    autoPlayOnceVisible?: boolean;
     autoPauseWhenHidden?: boolean;
+    autoPauseOnceHidden?: boolean;
     autoLoudWhenVisible?: boolean;
+    autoLoudOnceVisible?: boolean;
     autoMuteWhenHidden?: boolean;
+    autoMuteOnceHidden?: boolean;
     wrapperClassName?: string;
 };
 /**
@@ -39,5 +55,27 @@ export type Props = Omit<ControlledProps, 'play' | 'fullscreen' | 'volume' | 'mu
  * @see {@link Props}
  * @returns A `<figure>` element containing the video, its controls and optional
  * subtitles.
+ *
+ * @remarks
+ * **Audio-only media belongs here too**, carried by the same `<video>` element.
+ * Everything this component drives — play, mute, volume, rate, time, `ended` — is
+ * `HTMLMediaElement`, shared with `<audio>`; only fullscreen is video's own. And an
+ * `<audio>` tag can't be autoplayed: the muted-autoplay exemption browsers grant is
+ * for video, so an `<audio>` waits for a user gesture whatever its muted state.
+ * `autoPlayWhenVisible` on an audio file therefore needs `muted` and `playsInline`
+ * on a `<video>`, which is what this is. The one thing lost is the assistive-tech
+ * 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.
+ *
+ * Browsers refuse an unmuted `play()` outside a user gesture, so pairing an
+ * `autoLoud…` with an `autoPlay…` will usually have the playback rejected: the
+ * element stays paused while the controls believe otherwise. Autoplay muted, and
+ * leave unmuting to the reader.
  */
 export declare const Video: FunctionComponent<Props>;

package/components/Video/index.js

@@ -4,7 +4,7 @@ import { clss } from '../../agnostic/css/clss/index.js';
 import { IntersectionObserverComponent } from '../IntersectionObserver/index.js';
 import { mergeClassNames } from '../utils/index.js';
 import { videoWrapper as publicClassName } from '../public-classnames.js';
-import { muteAttributeWorkaround } from './utils.js';
+import { muteAttributeWorkaround, shouldRunAutoBehaviour } from './utils.js';
 import cssModule from './styles.module.css';
 import { ControlledVideo } from './index.controlled.js';
 /**
@@ -16,34 +16,72 @@ import { ControlledVideo } from './index.controlled.js';
  * @see {@link Props}
  * @returns A `<figure>` element containing the video, its controls and optional
  * subtitles.
+ *
+ * @remarks
+ * **Audio-only media belongs here too**, carried by the same `<video>` element.
+ * Everything this component drives — play, mute, volume, rate, time, `ended` — is
+ * `HTMLMediaElement`, shared with `<audio>`; only fullscreen is video's own. And an
+ * `<audio>` tag can't be autoplayed: the muted-autoplay exemption browsers grant is
+ * for video, so an `<audio>` waits for a user gesture whatever its muted state.
+ * `autoPlayWhenVisible` on an audio file therefore needs `muted` and `playsInline`
+ * on a `<video>`, which is what this is. The one thing lost is the assistive-tech
+ * 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.
+ *
+ * Browsers refuse an unmuted `play()` outside a user gesture, so pairing an
+ * `autoLoud…` with an `autoPlay…` will usually have the playback rejected: the
+ * element stays paused while the controls believe otherwise. Autoplay muted, and
+ * leave unmuting to the reader.
  */
-export const Video = ({ loop, autoPlayWhenVisible, autoPauseWhenHidden, autoMuteWhenHidden, autoLoudWhenVisible, wrapperClassName, onPlayButtonClicked, onPauseButtonClicked, onLoudButtonClicked, onMuteButtonClicked, onVolumeRangeChanged, onRateRangeChanged, onFullscreenButtonClicked, ...controlledProps }) => {
+export const Video = ({ loop, autoPlayWhenVisible, autoPlayOnceVisible, autoPauseWhenHidden, autoPauseOnceHidden, autoMuteWhenHidden, autoMuteOnceHidden, autoLoudWhenVisible, autoLoudOnceVisible, threshold, root, rootMargin, onVisibilityChanged, 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 hasBeenAutoPlayed = useRef(false);
+    // 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.
     const isTimeControlled = controlledProps.currentTimeMs !== undefined;
-    const needsObserve = useMemo(() => autoLoudWhenVisible === true
+    const needsObserve = useMemo(() => onVisibilityChanged !== undefined
+        || autoLoudWhenVisible === true
+        || autoLoudOnceVisible === true
         || autoMuteWhenHidden === true
+        || autoMuteOnceHidden === true
         || autoPlayWhenVisible === true
-        || autoPauseWhenHidden === true, [
+        || autoPlayOnceVisible === true
+        || autoPauseWhenHidden === true
+        || autoPauseOnceHidden === true, [
         autoLoudWhenVisible,
+        autoLoudOnceVisible,
         autoMuteWhenHidden,
+        autoMuteOnceHidden,
         autoPlayWhenVisible,
-        autoPauseWhenHidden
+        autoPlayOnceVisible,
+        autoPauseWhenHidden,
+        autoPauseOnceHidden,
+        onVisibilityChanged
     ]);
     // Intrisic event handlers
     const handleOnPlayEvent = useCallback((e) => {
         controlledProps.onPlay?.(e);
         setPlay(true);
-        hasBeenAutoPlayed.current = true;
     }, [controlledProps.onPlay]);
     const handleOnPauseEvent = useCallback((e) => {
         setPlay(false);
@@ -100,28 +138,41 @@ export const Video = ({ loop, autoPlayWhenVisible, autoPauseWhenHidden, autoMute
         if (ioEntry === undefined)
             return;
         const { isIntersecting } = ioEntry;
-        if (autoPauseWhenHidden === true && !isIntersecting)
+        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 (autoLoudWhenVisible === true && isIntersecting)
-            setMute(false);
-        if (autoPlayWhenVisible === true
-            && !hasBeenAutoPlayed.current
-            && isIntersecting)
-            setPlay(true);
-        if (autoMuteWhenHidden === true
-            && !hasBeenAutoPlayed.current
-            && !isIntersecting)
+        }
+        if (shouldRunAutoBehaviour(autoMuteWhenHidden, autoMuteOnceHidden, hasAutoMutedOnce.current)) {
+            hasAutoMutedOnce.current = true;
             setMute(true);
+        }
     }, [
         autoPlayWhenVisible,
+        autoPlayOnceVisible,
         autoPauseWhenHidden,
+        autoPauseOnceHidden,
         autoMuteWhenHidden,
-        autoLoudWhenVisible
+        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 && !hasBeenAutoPlayed.current)
+        if (controlledProps.autoPlay === true)
             setPlay(true);
     }, []);
     // Render
@@ -129,6 +180,6 @@ export const Video = ({ loop, autoPlayWhenVisible, autoPauseWhenHidden, autoMute
     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 })
+            ? _jsx(IntersectionObserverComponent, { threshold: threshold, root: root, rootMargin: rootMargin, onIntersected: onIntersected, children: videoContent })
             : videoContent });
 };

package/components/Video/utils.d.ts

@@ -45,3 +45,17 @@ export declare function formatTime(ms: number, format: string, fps?: number): st
  * @returns A ratio between `0` and `1`, clamped to the element's own bounds.
  */
 export declare const getTimelineClickProgress: (event: React.MouseEvent<HTMLDivElement>) => number;
+/**
+ * Whether a viewport-driven behaviour should run on this crossing.
+ *
+ * Each behaviour comes in two flavours: `…When…` on every crossing, `…Once…` on the
+ * first one only. Setting both is the same as setting `…When…` alone.
+ *
+ * @param whenCrossed - The `…When…` prop.
+ * @param onceOnly - The `…Once…` prop.
+ * @param hasFired - Whether this behaviour's own automatic trigger already ran. It
+ * tracks that behaviour and nothing else: a user pressing play must not spend an
+ * 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;

package/components/Video/utils.js

@@ -160,3 +160,21 @@ export const getTimelineClickProgress = (event) => {
     const position = event.clientX - timelineRect.left;
     return Math.min(1, Math.max(0, position / timelineRect.width));
 };
+/**
+ * Whether a viewport-driven behaviour should run on this crossing.
+ *
+ * Each behaviour comes in two flavours: `…When…` on every crossing, `…Once…` on the
+ * first one only. Setting both is the same as setting `…When…` alone.
+ *
+ * @param whenCrossed - The `…When…` prop.
+ * @param onceOnly - The `…Once…` prop.
+ * @param hasFired - Whether this behaviour's own automatic trigger already ran. It
+ * tracks that behaviour and nothing else: a user pressing play must not spend an
+ * 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;
+};

package/components/utils/types.d.ts

@@ -6,3 +6,35 @@
 export type WithClassName<T extends Record<string, unknown>> = T & {
     className?: string | Array<string | null | undefined>;
 };
+/**
+ * The settings of an {@link IntersectionObserver} a component mounts internally.
+ *
+ * A component that offers viewport-driven behaviour has to offer its dial too:
+ * `autoPlayWhenVisible` means little if "visible" can't be told to mean *thirty
+ * percent* visible, and an infinite list wants to start loading before its sentinel
+ * shows, which is `rootMargin`'s job.
+ *
+ * They mirror `ObserverOptions` of the `IntersectionObserver` component, where they
+ * end up. Restated here rather than imported from it: that component reads
+ * {@link WithClassName} from this very file, and the two shouldn't import each other.
+ */
+export type ViewportObserverOptions = {
+    threshold?: number | number[];
+    root?: HTMLElement;
+    rootMargin?: string;
+};
+/**
+ * Extends a type with an internal observer's settings and with what it sees.
+ *
+ * For a component observing **one** element — itself, usually. A component with
+ * several observers takes {@link ViewportObserverOptions} alone, since a single
+ * visibility handler couldn't say which of them crossed.
+ *
+ * `Scrllgngn` deliberately stays out of both: its observers take a `rootMargin`
+ * derived from its `viewportOffset*` props, which are its own version of the dial.
+ *
+ * @template T - The base type to extend.
+ */
+export type WithViewportObservation<T extends Record<string, unknown>> = T & ViewportObserverOptions & {
+    onVisibilityChanged?: (isVisible: boolean) => void;
+};

package/index.d.ts

@@ -1,3 +1,3 @@
 export * as agnostic from './agnostic/index.js'
-export * as components from './components/index.js'
 export * as node from './node/index.js'
+export * as components from './components/index.js'

package/index.js

@@ -1,3 +1,3 @@
 export * as agnostic from './agnostic/index.js'
-export * as components from './components/index.js'
 export * as node from './node/index.js'
+export * as components from './components/index.js'

package/node/@google-cloud/storage/file/index.d.ts

@@ -1,7 +1,7 @@
 export * as copy from './copy/index.js'
 export * as download from './download/index.js'
-export * as exists from './exists/index.js'
 export * as generateSignedUrl from './generate-signed-url/index.js'
+export * as exists from './exists/index.js'
 export * as getMetadata from './get-metadata/index.js'
 export * as getPermissions from './get-permissions/index.js'
 export * as move from './move/index.js'

package/node/@google-cloud/storage/file/index.js

@@ -1,7 +1,7 @@
 export * as copy from './copy/index.js'
 export * as download from './download/index.js'
-export * as exists from './exists/index.js'
 export * as generateSignedUrl from './generate-signed-url/index.js'
+export * as exists from './exists/index.js'
 export * as getMetadata from './get-metadata/index.js'
 export * as getPermissions from './get-permissions/index.js'
 export * as move from './move/index.js'

package/node/files/index.d.ts

@@ -1,4 +1,4 @@
 export * as getSize from './get-size/index.js'
 export * as isInDirectory from './is-in-directory/index.js'
-export * as readWrite from './read-write/index.js'
 export * as subpaths from './subpaths/index.js'
+export * as readWrite from './read-write/index.js'

package/node/files/index.js

@@ -1,4 +1,4 @@
 export * as getSize from './get-size/index.js'
 export * as isInDirectory from './is-in-directory/index.js'
-export * as readWrite from './read-write/index.js'
 export * as subpaths from './subpaths/index.js'
+export * as readWrite from './read-write/index.js'

package/node/images/transform/operations/index.d.ts

@@ -3,8 +3,8 @@ export * as brighten from './brighten/index.js'
 export * as extend from './extend/index.js'
 export * as extract from './extract/index.js'
 export * as flatten from './flatten/index.js'
-export * as flop from './flop/index.js'
 export * as flip from './flip/index.js'
+export * as flop from './flop/index.js'
 export * as hue from './hue/index.js'
 export * as level from './level/index.js'
 export * as lighten from './lighten/index.js'

package/node/images/transform/operations/index.js

@@ -3,8 +3,8 @@ export * as brighten from './brighten/index.js'
 export * as extend from './extend/index.js'
 export * as extract from './extract/index.js'
 export * as flatten from './flatten/index.js'
-export * as flop from './flop/index.js'
 export * as flip from './flip/index.js'
+export * as flop from './flop/index.js'
 export * as hue from './hue/index.js'
 export * as level from './level/index.js'
 export * as lighten from './lighten/index.js'

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@design-edito/tools",
-  "version": "0.5.5",
+  "version": "0.5.7",
   "description": "",
   "author": "Maxime Fabas",
   "license": "ISC",
@@ -1275,6 +1275,31 @@
     "./agnostic/strings/trim/index.js": {
       "import": "./agnostic/strings/trim/index.js"
     },
+    "./agnostic/subtitles": {
+      "import": "./agnostic/subtitles/index.js",
+      "types": "./agnostic/subtitles/index.d.ts"
+    },
+    "./agnostic/subtitles/index.js": {
+      "import": "./agnostic/subtitles/index.js"
+    },
+    "./agnostic/subtitles/parse-srt": {
+      "import": "./agnostic/subtitles/parse-srt/index.js",
+      "types": "./agnostic/subtitles/parse-srt/index.d.ts"
+    },
+    "./agnostic/subtitles/parse-srt/index.js": {
+      "import": "./agnostic/subtitles/parse-srt/index.js"
+    },
+    "./agnostic/subtitles/parse-srt/types.js": {
+      "import": "./agnostic/subtitles/parse-srt/types.js",
+      "types": "./agnostic/subtitles/parse-srt/types.d.ts"
+    },
+    "./agnostic/subtitles/srt-timecode-to-ms": {
+      "import": "./agnostic/subtitles/srt-timecode-to-ms/index.js",
+      "types": "./agnostic/subtitles/srt-timecode-to-ms/index.d.ts"
+    },
+    "./agnostic/subtitles/srt-timecode-to-ms/index.js": {
+      "import": "./agnostic/subtitles/srt-timecode-to-ms/index.js"
+    },
     "./agnostic/time": {
       "import": "./agnostic/time/index.js",
       "types": "./agnostic/time/index.d.ts"