@design-edito/tools 0.5.6 → 0.5.7

package/components/Subtitles/index.js

@@ -1,188 +1,120 @@
 import { jsx as _jsx } from "react/jsx-runtime";
-import { useCallback, useEffect, useState } from 'react';
+import { useEffect, useRef, useState } from 'react';
 import { clss } from '../../agnostic/css/clss/index.js';
 import { toError } from '../../agnostic/misc/cast/index.js';
-import { unknownToString } from '../../agnostic/errors/unknown-to-string/index.js';
+import { parseSrt } from '../../agnostic/subtitles/parse-srt/index.js';
 import { mergeClassNames, useChangeDispatch } from '../utils/index.js';
 import { subtitles as publicClassName } from '../public-classnames.js';
+import { lastElapsedPos as toLastElapsedPos, normalizeGroupBoundaries, toCurrentGroup, toSubGroups } from './utils.js';
 import cssModule from './styles.module.css';
-/** Converts an SRT timecode (hh:mm:ss,ms) to milliseconds. */
-const getTimecodeToMs = (timecode) => {
-    const [hours = '0', minutes = '0', secondsAndMs = '0,0'] = timecode.split(':');
-    const [seconds = '0', milliseconds = '0'] = secondsAndMs.split(',');
-    let result = parseInt(hours) * 60 * 60 * 1000;
-    result += parseInt(minutes) * 60 * 1000;
-    result += parseInt(seconds) * 1000;
-    result += parseInt(milliseconds);
-    return result;
-};
-/** Parses a raw SRT subtitle text into a list of {@link ParsedSub} entries. */
-const parseSubs = (rawSubs) => {
-    const numberRegex = /^\d+$/v;
-    const timecodeRegex = /^[0-9]+:[0-9]+:[0-9]+,[0-9]+\s*-->\s*[0-9]+:[0-9]+:[0-9]+,[0-9]+$/v;
-    const parsedSubs = [];
-    rawSubs.split('\n').forEach(line => {
-        if (line.trim() === '')
-            return;
-        const lastParsedSub = parsedSubs[parsedSubs.length - 1];
-        const matchId = line.match(numberRegex);
-        const matchTimecode = line.match(timecodeRegex);
-        // id
-        if (matchId !== null) {
-            if (lastParsedSub === undefined
-                || lastParsedSub.content !== undefined) {
-                const parsedSub = { id: parseInt(line) };
-                parsedSubs.push(parsedSub);
-                return;
-            }
-        }
-        // timecode
-        if (matchTimecode !== null) {
-            if (lastParsedSub?.id !== undefined) {
-                const [rawStart = '', rawEnd = ''] = line.split('-->');
-                const startTime = rawStart.trim();
-                const endTime = rawEnd.trim();
-                lastParsedSub.start = getTimecodeToMs(startTime);
-                lastParsedSub.end = getTimecodeToMs(endTime);
-                return;
-            }
-        }
-        // content
-        if (lastParsedSub?.id !== undefined
-            && lastParsedSub.start !== undefined
-            && lastParsedSub.end !== undefined) {
-            if (lastParsedSub.content !== undefined) {
-                lastParsedSub.content += `\n${line}`;
-                return;
-            }
-            lastParsedSub.content = line;
-        }
-    });
-    return parsedSubs;
-};
-/** Computes subtitle groups with their inclusive `startId` / `endId` boundaries. */
-const computeSubGroupsWithBoundaries = (subsGroups, highestSubId) => {
-    const fallback = [{ startId: 1, endId: highestSubId }];
-    if (subsGroups === undefined || subsGroups.length === 0)
-        return fallback;
-    const emptySubGroupBoundaries = [];
-    return subsGroups.reduce((acc, curr, currIndex) => {
-        const lastInAcc = acc[acc.length - 1];
-        const startId = lastInAcc === undefined ? 1 : lastInAcc.endId + 1;
-        const endId = curr;
-        if (currIndex === subsGroups.length - 1
-            && endId !== highestSubId) {
-            return [
-                ...acc,
-                { startId, endId },
-                { startId: endId + 1, endId: highestSubId }
-            ];
-        }
-        return [...acc, { startId, endId }];
-    }, emptySubGroupBoundaries);
-};
-/** Returns the group holding the last elapsed subtitle, or the last group once playback ended. */
-const getCurrentGroup = (subsGroupsWithBoundaries, lastPrevSubId, isEnded) => {
-    const previousGroups = subsGroupsWithBoundaries.filter(group => group.startId <= (lastPrevSubId ?? 0));
-    if (previousGroups.length === 0)
-        return isEnded === true
-            ? subsGroupsWithBoundaries[subsGroupsWithBoundaries.length - 1]
-            : subsGroupsWithBoundaries[0];
-    return previousGroups[previousGroups.length - 1];
-};
 /**
- * Subtitle synchronization component. Fetches or receives an SRT source, parses it,
- * and renders subtitle groups whose individual spans are styled according to the
- * current media timecode.
+ * Subtitle synchronization component. Takes an SRT source — parsed cues, a raw
+ * string, or a URL to fetch — and renders its cues in groups, marking where the
+ * media currently is.
  *
- * ### Group elements
- * Each subtitle group is a `<div>` with the following:
- * - `--curr` modifier when the group contains the subtitle at the current timecode.
- * - `data-start-sub-pos` — ID of the first subtitle in the group.
- * - `data-end-sub-pos` — ID of the last subtitle in the group.
+ * ### CSS elements
+ * - `lm-subtitles` — the root. Carries `--loading` while a fetch is in flight, and
+ * `--error` once one failed. Both are cleared when a new source starts loading.
+ * - `lm-subtitles__group` — one per group. Carries `--curr` when the reader is in it.
+ * - `lm-subtitles__sub` — one per cue. Carries `--prev` once the playhead has passed
+ * its start, and `--curr` while the playhead is inside its interval.
  *
- * ### Subtitle span elements
- * Each individual subtitle is a `<span>` with the following:
- * - `--prev` modifier when the subtitle's start time is at or before the last elapsed subtitle.
- * - `--curr` modifier when `timecodeMs` falls within the subtitle's `[start, end]` interval.
- * - `data-sub-pos` — the subtitle's numeric ID from the SRT source.
+ * ### Data attributes
+ * On a group: `data-start-sub-pos` and `data-end-sub-pos`, its bounds as positions
+ * in the cue array. On a cue: `data-sub-pos`, its position, and `data-sub-id`, the
+ * number written in the file.
  *
  * @param props - Component properties.
  * @see {@link Props}
- * @returns A root `<div>` containing the rendered subtitle groups, or an empty `<div>`
- * when `timecodeMs` is undefined or no subtitles have been parsed yet.
+ * @returns A root `<div>` holding the subtitle groups, empty while there is no
+ * timecode or no cue.
+ *
+ * @remarks
+ * Uncontrolled only. The cues are state, fed by whichever source is set: there is no
+ * controlled variant, because a consumer holding its own cues passes them as `cues`
+ * and owns them outright.
+ *
+ * Cues are rendered back to back with no separator — the space between two of them
+ * is presentation, and belongs in a stylesheet (`lm-subtitles__sub + …::before`, a
+ * `word-spacing`, whatever suits) rather than in the text content, where it would
+ * come back out of `textContent`.
  */
-export const Subtitles = ({ src, srtFileContent, subsGroups, timecodeMs, isEnded, className, onLoaded, onParsed, onLoadFailed }) => {
+export const Subtitles = ({ cues, srtFileContent, src, subsGroups, timecodeMs, isEnded, className, onLoaded, onParsed, onLoadFailed }) => {
     // State
     const [isLoading, setIsLoading] = useState(false);
     const [loadError, setLoadError] = useState(null);
     const [parsedSubs, setParsedSubs] = useState([]);
+    // The load handlers are read through refs so the effect below can depend on the
+    // source alone. Depending on their identity re-fetches on every parent render —
+    // and `Video` re-renders several times a second as the timecode moves.
+    const onLoadedRef = useRef(onLoaded);
+    const onLoadFailedRef = useRef(onLoadFailed);
+    useEffect(() => {
+        onLoadedRef.current = onLoaded;
+        onLoadFailedRef.current = onLoadFailed;
+    });
     // State dispatch
     useChangeDispatch(parsedSubs, onParsed);
-    // Effects
-    const fetchAndParseSubs = useCallback(async (src, srtFileContent) => {
+    // Fx. dep. cues, srtFileContent, src - Load from whichever source is set
+    useEffect(() => {
+        setIsLoading(false);
+        setLoadError(null);
+        if (cues !== undefined)
+            return setParsedSubs(cues);
         if (srtFileContent !== undefined)
-            return setParsedSubs(parseSubs(srtFileContent));
+            return setParsedSubs(parseSrt(srtFileContent));
         if (src === undefined)
-            return;
+            return setParsedSubs([]);
+        let isCurrent = true;
         setIsLoading(true);
-        setLoadError(null);
-        try {
-            const response = await fetch(src);
-            const srtContent = await response.text();
-            onLoaded?.(srtContent);
-            const parsedSubs = parseSubs(srtContent);
-            setParsedSubs(parsedSubs);
-        }
-        catch (error) {
-            setLoadError(error instanceof Error
-                ? error
-                : new Error(unknownToString(error)));
-            // eslint-disable-next-line no-console
-            console.error(error);
-            onLoadFailed?.(toError(error));
-        }
-        finally {
-            setIsLoading(false);
-        }
-    }, [onLoadFailed, onLoaded]);
-    useEffect(() => {
-        fetchAndParseSubs(src, srtFileContent)
-            // eslint-disable-next-line no-console
-            .catch((error) => { console.error(error); });
-    }, [fetchAndParseSubs, src, srtFileContent]);
+        const load = async () => {
+            try {
+                const response = await fetch(src);
+                // A 404 serves an HTML page: `text()` resolves, the parse yields nothing, and
+                // without this the component would report a success it never had.
+                if (!response.ok)
+                    throw new Error(`Could not load ${src}: ${response.status} ${response.statusText}`);
+                const srtContent = await response.text();
+                if (!isCurrent)
+                    return;
+                onLoadedRef.current?.(srtContent);
+                setParsedSubs(parseSrt(srtContent));
+            }
+            catch (error) {
+                if (!isCurrent)
+                    return;
+                const asError = toError(error);
+                setLoadError(asError);
+                setParsedSubs([]);
+                onLoadFailedRef.current?.(asError);
+            }
+            finally {
+                if (isCurrent)
+                    setIsLoading(false);
+            }
+        };
+        void load();
+        return () => { isCurrent = false; };
+    }, [cues, srtFileContent, src]);
     // Rendering
     const c = clss(publicClassName, { cssModule });
     const rootClss = mergeClassNames(c(null, {
         loading: isLoading,
         error: loadError !== null
     }), className);
-    const prevSubs = parsedSubs.filter(({ start }) => start !== undefined && start < (timecodeMs ?? 0));
-    const lastPrevSub = prevSubs[prevSubs.length - 1];
-    const highestSubId = Math.max(...parsedSubs.map(sub => sub.id));
-    const subsGroupsWithBoundaries = computeSubGroupsWithBoundaries(subsGroups, highestSubId);
-    const currentGroup = getCurrentGroup(subsGroupsWithBoundaries, lastPrevSub?.id, isEnded);
-    return _jsx("div", { className: rootClss, children: timecodeMs !== undefined
-            && parsedSubs.length > 0
-            && subsGroupsWithBoundaries.map(group => {
-                const groupSubs = parsedSubs.filter(sub => sub.id >= group.startId && sub.id <= group.endId);
-                const totalSubs = groupSubs.length;
-                const groupClass = c('group', { curr: currentGroup?.startId === group.startId });
-                const subsNodes = groupSubs.map((sub, subIndex) => {
-                    let subText = sub.content?.trim() ?? '';
-                    if (subIndex !== totalSubs - 1)
-                        subText += ' ';
-                    const subClass = c('sub', {
-                        prev: sub.start !== undefined
-                            && lastPrevSub?.start !== undefined
-                            && sub.start <= lastPrevSub.start,
-                        curr: sub.start !== undefined
-                            && timecodeMs >= sub.start
-                            && sub.end !== undefined
-                            && timecodeMs <= sub.end
+    const lastElapsedPos = toLastElapsedPos(parsedSubs, timecodeMs);
+    const boundaries = normalizeGroupBoundaries(subsGroups, parsedSubs.length - 1);
+    const groups = toSubGroups(boundaries, parsedSubs.length - 1);
+    const currentGroup = toCurrentGroup(groups, lastElapsedPos, isEnded);
+    return _jsx("div", { className: rootClss, children: timecodeMs !== undefined && groups.map(group => {
+            const groupClss = c('group', { curr: currentGroup?.startPos === group.startPos });
+            return _jsx("div", { className: groupClss, "data-start-sub-pos": group.startPos, "data-end-sub-pos": group.endPos, children: parsedSubs.slice(group.startPos, group.endPos + 1).map((sub, indexInGroup) => {
+                    const subPos = group.startPos + indexInGroup;
+                    const subClss = c('sub', {
+                        prev: subPos <= lastElapsedPos,
+                        curr: timecodeMs >= sub.start && timecodeMs <= sub.end
                     });
-                    return _jsx("span", { className: subClass, "data-sub-pos": sub.id, children: subText }, sub.id);
-                });
-                return _jsx("div", { className: groupClass, "data-start-sub-pos": group.startId, "data-end-sub-pos": group.endId, children: subsNodes }, group.startId);
-            }) });
+                    return _jsx("span", { className: subClss, "data-sub-pos": subPos, "data-sub-id": sub.id, children: sub.content }, subPos);
+                }) }, group.startPos);
+        }) });
 };

package/components/Subtitles/utils.d.ts

@@ -0,0 +1,60 @@
+import type { SrtCue } from '../../agnostic/subtitles/parse-srt/types.js';
+/**
+ * The inclusive bounds of a subtitle group, as **positions** in the cue array.
+ *
+ * Positions rather than file ids: an SRT concatenated from several files, or edited
+ * by hand, numbers its cues however it likes, and nothing guarantees a run starting
+ * at 1. A consumer shouldn't have to know a file's numbering to split it.
+ *
+ * @property startPos - Position of the group's first cue.
+ * @property endPos - Position of its last cue.
+ */
+export type SubGroupBounds = {
+    startPos: number;
+    endPos: number;
+};
+/**
+ * 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 declare function normalizeGroupBoundaries(boundaries: number[] | undefined, lastPos: number): number[];
+/**
+ * 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 declare function toSubGroups(boundaries: number[], lastPos: number): SubGroupBounds[];
+/**
+ * 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 declare function lastElapsedPos(cues: SrtCue[], timecodeMs?: number): number;
+/**
+ * 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 declare function toCurrentGroup(groups: SubGroupBounds[], lastElapsedPos: number, isEnded?: boolean): SubGroupBounds | undefined;

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/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>;