@design-edito/tools 0.5.5 → 0.5.7

package/components/Sequencer/index.d.ts

@@ -1,5 +1,6 @@
 import { type FunctionComponent } from 'react';
 import { type Props as IOCompProps } from '../IntersectionObserver/index.js';
+import type { ViewportObserverOptions } from '../utils/types.js';
 import { type Props as ControlledProps } from './index.controlled.js';
 /**
  * Props for the {@link Sequencer} component.
@@ -29,6 +30,13 @@ import { type Props as ControlledProps } from './index.controlled.js';
  * component enters the viewport. No-op when `play` is controlled.
  * @property pauseOnHidden - When `true`, pauses internal playback when the
  * component leaves the viewport. No-op when `play` is controlled.
+ * @property threshold - How much of the component has to be in view before it
+ * counts as visible, forwarded to the internal {@link IntersectionObserver}.
+ * @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.
+ * `onIntersected` is the raw form of the same event, carrying the entry and the
+ * observer; this one carries the answer.
  * @property onIntersected - Forwarded verbatim to the internal
  * {@link IntersectionObserverComponent}, and called on every intersection
  * change whichever mode the sequencer runs in.
@@ -42,7 +50,7 @@ import { type Props as ControlledProps } from './index.controlled.js';
  * @property onReachedLastStep - Called when the forwarded step becomes the last
  * one.
  */
-export type Props = Omit<ControlledProps, 'isPlaying' | 'tempo'> & {
+export type Props = ViewportObserverOptions & Omit<ControlledProps, 'isPlaying' | 'tempo'> & {
     defaultStep?: number;
     tempo?: number;
     play?: boolean;
@@ -54,6 +62,7 @@ export type Props = Omit<ControlledProps, 'isPlaying' | 'tempo'> & {
     playOnVisible?: boolean;
     pauseOnHidden?: boolean;
     onIntersected?: IOCompProps['onIntersected'];
+    onVisibilityChanged?: (isVisible: boolean) => void;
     onIsPlayingChanged?: (isPlaying: boolean) => void;
     onStepChanged?: (step: number) => void;
     onLooped?: () => void;

package/components/Sequencer/index.js

@@ -30,7 +30,7 @@ import { ControlledSequencer } from './index.controlled.js';
  * @returns An {@link IntersectionObserverComponent} wrapping a
  * {@link ControlledSequencer} with the computed step and modifiers applied.
  */
-export const Sequencer = ({ defaultStep, tempo = 60, play, loop, clampFirst, clampLast, resetOnVisible, resetOnHidden, playOnVisible, pauseOnHidden, onIntersected, onIsPlayingChanged, onStepChanged, onLooped, onReachedFirstStep, onReachedLastStep, ...controlledProps }) => {
+export const Sequencer = ({ defaultStep, tempo = 60, play, loop, clampFirst, clampLast, resetOnVisible, resetOnHidden, playOnVisible, pauseOnHidden, onIntersected, onVisibilityChanged, threshold, root, rootMargin, onIsPlayingChanged, onStepChanged, onLooped, onReachedFirstStep, onReachedLastStep, ...controlledProps }) => {
     // State
     const { step, activateOnStep, children } = controlledProps;
     const [internalPlay, setInternalPlay] = useState(play ?? false);
@@ -83,9 +83,13 @@ export const Sequencer = ({ defaultStep, tempo = 60, play, loop, clampFirst, cla
     // Action handlers
     const handleIntersection = useCallback(({ ioEntry, observer }) => {
         onIntersected?.({ ioEntry, observer });
+        const { isIntersecting } = ioEntry ?? {};
+        if (isIntersecting !== undefined)
+            onVisibilityChanged?.(isIntersecting);
+        // Both handlers fire whatever the mode: a controlled sequencer still wants to
+        // hear about the viewport, it just doesn't let it drive the step.
         if (play === true || step !== undefined)
             return;
-        const { isIntersecting } = ioEntry ?? {};
         if (isIntersecting === true) {
             if (resetOnVisible === true)
                 setInternalStep(0);
@@ -108,5 +112,5 @@ export const Sequencer = ({ defaultStep, tempo = 60, play, loop, clampFirst, cla
         onIntersected
     ]);
     // Rendering
-    return _jsx(IntersectionObserverComponent, { onIntersected: handleIntersection, children: _jsx(ControlledSequencer, { ...controlledProps, step: forwardedStep, isPlaying: actualPlay, tempo: tempo }) });
+    return _jsx(IntersectionObserverComponent, { threshold: threshold, root: root, rootMargin: rootMargin, onIntersected: handleIntersection, children: _jsx(ControlledSequencer, { ...controlledProps, step: forwardedStep, isPlaying: actualPlay, tempo: tempo }) });
 };

package/components/Subtitles/index.d.ts

@@ -1,82 +1,73 @@
-import { type FunctionComponent, type PropsWithChildren } from 'react';
+import { type FunctionComponent } from 'react';
+import type { SrtCue } from '../../agnostic/subtitles/parse-srt/types.js';
 import type { WithClassName } from '../utils/types.js';
-/**
- * A single parsed subtitle entry from an SRT file.
- *
- * @property id - Sequential subtitle number.
- * @property start - Start time in milliseconds.
- * @property end - End time in milliseconds.
- * @property content - Subtitle text content.
- */
-export type ParsedSub = {
-    id: number;
-    start?: number;
-    end?: number;
-    content?: string;
-};
-/**
- * The inclusive ID boundaries of a subtitle group.
- *
- * @property startId - ID of the first subtitle in the group.
- * @property endId - ID of the last subtitle in the group.
- */
-export type SubGroupBoundaries = {
-    startId: number;
-    endId: number;
-};
 /**
  * Props for the {@link Subtitles} component.
  *
- * @property src - URL of an SRT file to fetch. Ignored if `srtFileContent` is provided.
- * If both are undefined, no subtitles are loaded.
- * @property srtFileContent - Raw SRT string used directly, bypassing any network fetch.
- * Takes precedence over `src`.
- * @property subsGroups - Optional array of subtitle IDs that act as group boundaries,
- * splitting the full subtitle list into named sections. If omitted, all subtitles
- * belong to a single group.
- * @property timecodeMs - Current media position in milliseconds. Drives which subtitles
- * receive the `--prev` and `--curr` modifiers. When `undefined`, nothing is rendered.
- * @property isEnded - When `true`, forces the last group to be treated as current,
- * regardless of `timecodeMs`. Useful to keep the final subtitle group visible after
- * media playback finishes.
- * @property onLoaded - Called with the raw SRT string once fetched. Not called
- * when `srtFileContent` is used directly, since nothing is fetched then.
- * @property onParsed - Called after the subtitles have been parsed, with the
- * resulting entries.
- * @property onLoadFailed - Called with an `Error` when the fetch or the parse fails.
+ * The three sources are tried in order — `cues`, then `srtFileContent`, then `src` —
+ * and the first one present wins. With none of them, nothing is rendered.
+ *
+ * @property cues - Already parsed cues, used as they are. Spares a consumer that
+ * holds them — from a previous `onParsed`, or from its own call to `parseSrt` —
+ * having to serialise them back to SRT.
+ * @property srtFileContent - A raw SRT string, parsed directly with no network call.
+ * @property src - URL of an SRT file to fetch and parse.
+ * @property subsGroups - Positions to split the cues on, each the **position** of a
+ * group's last cue — not the id written in the file. Order doesn't matter, and
+ * duplicate or out-of-range positions are ignored. Omitted, every cue belongs to one
+ * group.
+ * @property timecodeMs - Current media position in milliseconds. Drives the `--prev`
+ * and `--curr` modifiers. While it is `undefined`, no group is rendered.
+ * @property isEnded - When `true`, the last group is the current one whatever
+ * `timecodeMs` says, so the closing subtitles stay up once playback is over.
+ * @property onLoaded - Called with the raw SRT string once fetched. Only fires for
+ * `src`, since the other two sources fetch nothing.
+ * @property onParsed - Called with the cues after they changed. Never on mount.
+ * @property onLoadFailed - Called with an `Error` when the fetch fails, the response
+ * is not ok, or the parse throws.
  * @property className - Optional additional class name(s) applied to the root element.
- * @property children - React children rendered inside the root element, after the subtitle groups.
  */
-export type Props = PropsWithChildren<WithClassName<{
-    src?: string;
+export type Props = WithClassName<{
+    cues?: SrtCue[];
     srtFileContent?: string;
+    src?: string;
     subsGroups?: number[];
     timecodeMs?: number;
     isEnded?: boolean;
     onLoaded?: (subs: string) => void;
-    onParsed?: (subs: ParsedSub[]) => void;
+    onParsed?: (subs: SrtCue[]) => void;
     onLoadFailed?: (error: Error) => void;
-}>>;
+}>;
 /**
- * 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 declare const Subtitles: FunctionComponent<Props>;

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);
+}