@design-edito/tools 0.5.6 → 0.5.8

package/components/Subtitles/utils.js

@@ -0,0 +1,76 @@
+/**
+ * Puts a consumer's group boundaries in a state the group builder can use.
+ *
+ * Out-of-range, duplicate and unordered boundaries all produce overlapping or
+ * inverted groups downstream — the same cue rendered twice, colliding keys. Rather
+ * than demand a sorted array and break quietly when it isn't, normalise here.
+ *
+ * @param boundaries - The positions a consumer asked to split on, in any order.
+ * @param lastPos - Position of the last cue.
+ * @returns The usable boundaries, ascending, without duplicates, and without the
+ * last position — which ends the final group anyway.
+ */
+export function normalizeGroupBoundaries(boundaries, lastPos) {
+    if (boundaries === undefined)
+        return [];
+    const usable = boundaries.filter(pos => Number.isInteger(pos) && pos >= 0 && pos < lastPos);
+    return [...new Set(usable)].sort((a, b) => a - b);
+}
+/**
+ * Cuts the cue array into groups.
+ *
+ * @param boundaries - Normalised boundaries, each the position of a group's last cue.
+ * See {@link normalizeGroupBoundaries}.
+ * @param lastPos - Position of the last cue.
+ * @returns One group per section, in order. A single group spanning everything when
+ * no boundary is given, and nothing at all when there is no cue to group.
+ */
+export function toSubGroups(boundaries, lastPos) {
+    if (lastPos < 0)
+        return [];
+    const groups = [];
+    let startPos = 0;
+    for (const endPos of boundaries) {
+        groups.push({ startPos, endPos });
+        startPos = endPos + 1;
+    }
+    groups.push({ startPos, endPos: lastPos });
+    return groups;
+}
+/**
+ * Finds the last cue the playhead has already reached.
+ *
+ * @param cues - The parsed cues, in order.
+ * @param timecodeMs - Current media position, absent while nothing plays.
+ * @returns Its position, or `-1` when the playhead sits before the first cue. One
+ * number, computed once: `--prev` on a cue and the current group both read from it,
+ * and deriving them separately lets them disagree on a file with duplicate or
+ * out-of-order start times.
+ */
+export function lastElapsedPos(cues, timecodeMs) {
+    if (timecodeMs === undefined)
+        return -1;
+    let found = -1;
+    cues.forEach((cue, pos) => {
+        if (cue.start < timecodeMs)
+            found = pos;
+    });
+    return found;
+}
+/**
+ * Picks the group the reader is in.
+ *
+ * @param groups - The groups, in order.
+ * @param lastElapsedPos - Position of the last elapsed cue, `-1` before the first.
+ * @param isEnded - Whether playback is over.
+ * @returns The group holding that cue. Once playback has ended, the last group
+ * whatever the timecode says — which is what `isEnded` is for. The first group
+ * before anything has elapsed.
+ */
+export function toCurrentGroup(groups, lastElapsedPos, isEnded) {
+    if (isEnded === true)
+        return groups[groups.length - 1];
+    if (lastElapsedPos < 0)
+        return groups[0];
+    return groups.find(group => group.startPos <= lastElapsedPos && lastElapsedPos <= group.endPos);
+}

package/components/Textarea/index.d.ts

@@ -26,6 +26,10 @@ export type Props = TextareaHTMLAttributes<HTMLTextAreaElement> & WithClassName<
  * A stable auto-generated `id` is created on mount and used to associate the
  * rendered label through the `htmlFor` attribute.
  *
+ * ### Root element modifiers
+ * - `--controlled` — the value comes from the parent, not from inside.
+ * - `--empty` / `--filled` — whether the current value is the empty string.
+ *
  * ### CSS elements
  * - `label`
  * - `error`

package/components/Textarea/index.js

@@ -15,6 +15,10 @@ import cssModule from './styles.module.css';
  * A stable auto-generated `id` is created on mount and used to associate the
  * rendered label through the `htmlFor` attribute.
  *
+ * ### Root element modifiers
+ * - `--controlled` — the value comes from the parent, not from inside.
+ * - `--empty` / `--filled` — whether the current value is the empty string.
+ *
  * ### CSS elements
  * - `label`
  * - `error`
@@ -53,6 +57,10 @@ export const Textarea = ({ label, error, autoHeight = false, value, defaultValue
     };
     // Rendering
     const c = clss(publicClassName, { cssModule });
-    const rootClss = mergeClassNames(c(), className);
+    const rootClss = mergeClassNames(c(null, {
+        controlled: isControlled,
+        empty: currentValue === '',
+        filled: currentValue !== ''
+    }), className);
     return _jsxs(_Fragment, { children: [isNotFalsy(label) && _jsx("label", { className: c('label'), htmlFor: id, children: label }), _jsx("textarea", { ...rest, ref: textareaRef, id: id, className: rootClss, value: currentValue, onChange: handleChange }), isNotFalsy(error) && _jsx("span", { className: c('error'), children: error })] });
 };

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.
@@ -141,8 +146,14 @@ export type Props = PropsWithChildren<WithClassName<{
  * - `data-total-time-ms` — total duration in milliseconds.
  *
  * ### CSS custom properties on the root element
- * - `--video-current-time-ratio` — current / total ratio, fixed to 8 decimals.
- * Useful for driving progress-bar animations purely in CSS.
+ * Durations come as a `ms` time under the bare name and as a plain number under a
+ * `-raw` twin; ratios are unitless and have no twin.
+ * - `--lm-video-current-time` / `--lm-video-current-time-raw`
+ * - `--lm-video-total-time` / `--lm-video-total-time-raw`
+ * - `--lm-video-current-time-ratio` — how far through the media the playhead is.
+ * What a progress bar animates on, with no JavaScript of its own.
+ * - `--lm-video-volume-ratio`
+ * - `--lm-video-playback-rate` — a multiplier, not a ratio: `1` is normal speed.
  *
  * @param props - Component properties.
  * @see {@link Props}

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.
@@ -33,19 +35,30 @@ import { forceExitFullscreen, forceFullscreen, forceLoud, forceMute, forcePause,
  * - `data-total-time-ms` — total duration in milliseconds.
  *
  * ### CSS custom properties on the root element
- * - `--video-current-time-ratio` — current / total ratio, fixed to 8 decimals.
- * Useful for driving progress-bar animations purely in CSS.
+ * Durations come as a `ms` time under the bare name and as a plain number under a
+ * `-raw` twin; ratios are unitless and have no twin.
+ * - `--lm-video-current-time` / `--lm-video-current-time-raw`
+ * - `--lm-video-total-time` / `--lm-video-total-time-raw`
+ * - `--lm-video-current-time-ratio` — how far through the media the playhead is.
+ * What a progress bar animates on, with no JavaScript of its own.
+ * - `--lm-video-volume-ratio`
+ * - `--lm-video-playback-rate` — a multiplier, not a ratio: `1` is normal speed.
  *
  * @param props - Component properties.
  * @see {@link Props}
  * @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 +86,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 +140,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 +152,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,
@@ -141,7 +165,13 @@ export const ControlledVideo = ({ sources, tracks, subtitles, playBtnContent, pa
         'data-total-time-ms': totalTimeMs
     };
     const rootStyles = {
-        [`--${publicClassName}-current-time-ratio`]: currentTimeRatio.toFixed(8)
+        '--lm-video-current-time': `${currentTimeMs}ms`,
+        '--lm-video-current-time-raw': `${currentTimeMs}`,
+        '--lm-video-total-time': `${totalTimeMs}ms`,
+        '--lm-video-total-time-raw': `${totalTimeMs}`,
+        '--lm-video-current-time-ratio': `${currentTimeRatio}`,
+        '--lm-video-volume-ratio': `${volume}`,
+        '--lm-video-playback-rate': `${playbackRate}`
     };
     const parsedSources = useMemo(() => {
         if (sources === undefined)
@@ -249,11 +279,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/index.d.ts

@@ -10,16 +10,16 @@ export * as image from './Image/index.js'
 export * as input from './Input/index.js'
 export * as intersectionObserver from './IntersectionObserver/index.js'
 export * as jsonEditor from './JsonEditor/index.js'
-export * as listLoader from './ListLoader/index.js'
 export * as overlayer from './Overlayer/index.js'
-export * as paginator from './Paginator/index.js'
-export * as resizeObserver from './ResizeObserver/index.js'
-export * as scrllgngn from './Scrllgngn/index.js'
+export * as listLoader from './ListLoader/index.js'
 export * as scrollListener from './ScrollListener/index.js'
-export * as select from './Select/index.js'
+export * as paginator from './Paginator/index.js'
 export * as sequencer from './Sequencer/index.js'
+export * as select from './Select/index.js'
+export * as scrllgngn from './Scrllgngn/index.js'
 export * as shadowRoot from './ShadowRoot/index.js'
 export * as subtitles from './Subtitles/index.js'
+export * as resizeObserver from './ResizeObserver/index.js'
 export * as textarea from './Textarea/index.js'
 export * as theatre from './Theatre/index.js'
 export * as uiModule from './UIModule/index.js'

package/components/index.js

@@ -10,16 +10,16 @@ export * as image from './Image/index.js'
 export * as input from './Input/index.js'
 export * as intersectionObserver from './IntersectionObserver/index.js'
 export * as jsonEditor from './JsonEditor/index.js'
-export * as listLoader from './ListLoader/index.js'
 export * as overlayer from './Overlayer/index.js'
-export * as paginator from './Paginator/index.js'
-export * as resizeObserver from './ResizeObserver/index.js'
-export * as scrllgngn from './Scrllgngn/index.js'
+export * as listLoader from './ListLoader/index.js'
 export * as scrollListener from './ScrollListener/index.js'
-export * as select from './Select/index.js'
+export * as paginator from './Paginator/index.js'
 export * as sequencer from './Sequencer/index.js'
+export * as select from './Select/index.js'
+export * as scrllgngn from './Scrllgngn/index.js'
 export * as shadowRoot from './ShadowRoot/index.js'
 export * as subtitles from './Subtitles/index.js'
+export * as resizeObserver from './ResizeObserver/index.js'
 export * as textarea from './Textarea/index.js'
 export * as theatre from './Theatre/index.js'
 export * as uiModule from './UIModule/index.js'

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'