@design-edito/tools 0.5.2 → 0.5.3

package/components/Select/index.d.ts

@@ -1,20 +1,28 @@
-import { type FunctionComponent } from 'react';
-import { type Props as ControlledProps } from './index.controlled.js';
+import { type FunctionComponent, type PropsWithChildren, type ReactNode, type SelectHTMLAttributes } from 'react';
+import type { WithClassName } from '../utils/types.js';
 /**
  * Props for the {@link Select} component.
  *
- * Alias of {@link ControlledProps}.
+ * Extends all native {@link SelectHTMLAttributes} and {@link WithClassName}
+ * with optional label, error content, and option children.
  *
- * All native select attributes remain available, including `value`,
- * `defaultValue`, and `onChange`, allowing the component to operate
- * in either controlled or hybrid mode.
+ * @property label - Content rendered as an associated `<label>`. When omitted, no label is rendered.
+ * @property error - Content rendered as an error message below the select. When omitted, no error is rendered.
+ * @property className - Additional class name(s) applied to the select element.
+ * @property children - `<option>` or `<optgroup>` elements rendered inside the select.
  */
-export type Props = ControlledProps;
+export type Props = SelectHTMLAttributes<HTMLSelectElement> & PropsWithChildren<WithClassName<{
+    label?: ReactNode;
+    error?: ReactNode;
+}>>;
 /**
- * Select field component supporting controlled and hybrid usage.
+ * Select field supporting controlled and uncontrolled usage.
  *
- * Wraps {@link ControlledSelect} and automatically manages the selected
- * value when no `value` prop is provided.
+ * Renders a native `<select>` with optional label and error feedback. All
+ * standard select attributes are forwarded to the underlying element.
+ *
+ * A stable auto-generated `id` is created on mount and used to associate the
+ * rendered label through the `htmlFor` attribute.
  *
  * ### CSS elements
  * - `label`
@@ -22,17 +30,13 @@ export type Props = ControlledProps;
  *
  * @param props - Component properties.
  * @see {@link Props}
- *
- * @returns A labelled select with optional internal selection management.
+ * @returns A labelled select with optional error feedback.
  *
  * @remarks
- * - In controlled mode (`value` defined), the selected value is fully driven
- *   by the parent component and internal state is never updated.
- * - In hybrid mode, internal state is initialized from `defaultValue` and
- *   subsequently manages selection updates itself.
- * - In hybrid mode, the internal value is updated before forwarding the
- *   `onChange` callback.
- * - `defaultValue` is only used to initialize internal state and is not
- *   forwarded to the underlying controlled component.
+ * - In controlled mode (`value` defined), the selection is fully driven by the
+ *   parent and internal state is never updated.
+ * - In uncontrolled mode, internal state is initialized from `defaultValue` and
+ *   updated before `onChange` is forwarded.
+ * - `onChange` fires in both modes.
  */
 export declare const Select: FunctionComponent<Props>;

package/components/Select/index.js

@@ -1,11 +1,19 @@
-import { jsx as _jsx } from "react/jsx-runtime";
+import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
 import { useState } from 'react';
-import { ControlledSelect } from './index.controlled.js';
+import { clss } from '../../agnostic/css/clss/index.js';
+import { isNotFalsy } from '../../agnostic/booleans/is-falsy/index.js';
+import { randomHash } from '../../agnostic/random/uuid/index.js';
+import { mergeClassNames } from '../utils/index.js';
+import { select as publicClassName } from '../public-classnames.js';
+import cssModule from './styles.module.css';
 /**
- * Select field component supporting controlled and hybrid usage.
+ * Select field supporting controlled and uncontrolled usage.
  *
- * Wraps {@link ControlledSelect} and automatically manages the selected
- * value when no `value` prop is provided.
+ * Renders a native `<select>` with optional label and error feedback. All
+ * standard select attributes are forwarded to the underlying element.
+ *
+ * A stable auto-generated `id` is created on mount and used to associate the
+ * rendered label through the `htmlFor` attribute.
  *
  * ### CSS elements
  * - `label`
@@ -13,27 +21,29 @@ import { ControlledSelect } from './index.controlled.js';
  *
  * @param props - Component properties.
  * @see {@link Props}
- *
- * @returns A labelled select with optional internal selection management.
+ * @returns A labelled select with optional error feedback.
  *
  * @remarks
- * - In controlled mode (`value` defined), the selected value is fully driven
- *   by the parent component and internal state is never updated.
- * - In hybrid mode, internal state is initialized from `defaultValue` and
- *   subsequently manages selection updates itself.
- * - In hybrid mode, the internal value is updated before forwarding the
- *   `onChange` callback.
- * - `defaultValue` is only used to initialize internal state and is not
- *   forwarded to the underlying controlled component.
+ * - In controlled mode (`value` defined), the selection is fully driven by the
+ *   parent and internal state is never updated.
+ * - In uncontrolled mode, internal state is initialized from `defaultValue` and
+ *   updated before `onChange` is forwarded.
+ * - `onChange` fires in both modes.
  */
-export const Select = ({ defaultValue, value, onChange, ...rest }) => {
+export const Select = ({ label, error, value, defaultValue, onChange, className, children, ...rest }) => {
+    // State
+    const [id] = useState(`_${randomHash(12)}`);
+    const [internalValue, setInternalValue] = useState(defaultValue ?? '');
     const isControlled = value !== undefined;
-    const [internal, setInternal] = useState(defaultValue ?? '');
-    const currentValue = isControlled ? value : internal;
+    const currentValue = isControlled ? value : internalValue;
+    // User action handlers
     const handleChange = (e) => {
         if (!isControlled)
-            setInternal(e.target.value);
+            setInternalValue(e.target.value);
         onChange?.(e);
     };
-    return _jsx(ControlledSelect, { ...rest, value: currentValue, onChange: handleChange });
+    // Rendering
+    const c = clss(publicClassName, { cssModule });
+    const rootClss = mergeClassNames(c(), className);
+    return _jsxs(_Fragment, { children: [isNotFalsy(label) && _jsx("label", { className: c('label'), htmlFor: id, children: label }), _jsx("select", { ...rest, id: id, className: rootClss, value: currentValue, onChange: handleChange, children: children }), isNotFalsy(error) && _jsx("span", { className: c('error'), children: error })] });
 };

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

@@ -1,7 +1,7 @@
 import { type FunctionComponent, type PropsWithChildren } from 'react';
 import type { WithClassName } from '../utils/types.js';
 /**
- * Props for the {@link SequencerControlled} component.
+ * Props for the {@link ControlledSequencer} component.
  *
  * This is the low-level controlled interface. All state is driven externally —
  * the component holds no internal state of its own. For the uncontrolled
@@ -16,32 +16,22 @@ import type { WithClassName } from '../utils/types.js';
  * child indices that should be active when `step === i`, allowing multiple
  * children to be simultaneously active on a given step. When omitted, exactly
  * one child is active at a time (the child at index `step`).
- * @property _modifiers - Internal modifier flags forwarded directly to the
- * BEM class builder on the root element. Intended to be injected by the
- * uncontrolled wrapper; avoid setting manually in consumer code.
- * - `playing` — sequence is currently progressing.
- * - `at-start` — current step is the first step.
- * - `at-end` — current step is the last step.
- * @property _dataAttributes - Internal data attribute values forwarded to the
- * root element as `data-<key>`. Intended to be injected by the uncontrolled
- * wrapper; avoid setting manually in consumer code.
- * - `tempo` — exposed as `data-tempo`, reflects the current playback tempo.
+ * @property isPlaying - Whether the sequence is currently progressing. The
+ * controlled layer never advances on its own; this only drives the `--playing`
+ * modifier. Defaults to `false`.
+ * @property tempo - Playback speed in beats per minute, exposed as `data-tempo`
+ * for styling and scripting. Purely informational here — the interval itself
+ * lives in the uncontrolled wrapper. When omitted, no attribute is rendered.
  * @property className - Optional additional class name(s) applied to the root element.
  * @property children - The items to sequence. Each child is wrapped in a
  * classifier `<div>` and receives one of the `--active`, `--previous`, or
  * `--next` modifiers depending on its position relative to the current `step`.
  */
-export type ControlledProps = PropsWithChildren<WithClassName<{
+export type Props = PropsWithChildren<WithClassName<{
     step?: number;
     activateOnStep?: number[][];
-    _modifiers?: {
-        playing?: boolean;
-        'at-start'?: boolean;
-        'at-end'?: boolean;
-    };
-    _dataAttributes?: {
-        tempo?: number;
-    };
+    isPlaying?: boolean;
+    tempo?: number;
 }>>;
 /**
  * Controlled sequencer component. Renders each child inside a classifier
@@ -54,14 +44,14 @@ export type ControlledProps = PropsWithChildren<WithClassName<{
  *
  * ### Root element modifiers
  * The root `<div>` receives the public class name defined by `sequencer` and
- * the following BEM-style modifier classes, sourced from `_modifiers`:
- * - `--playing` — when the sequence is actively progressing.
+ * the following BEM-style modifier classes:
+ * - `--playing` — when `isPlaying` is `true`.
  * - `--at-start` — when the current step is the first step.
  * - `--at-end` — when the current step is the last step.
  *
  * ### Data attributes on the root element
- * Derived from `_dataAttributes`, each key is prefixed with `data-`:
- * - `data-tempo` — current playback tempo, when provided.
+ * - `data-step` — the current step index.
+ * - `data-tempo` — current playback tempo, when `tempo` is provided.
  *
  * ### Child wrapper elements
  * Each child is wrapped in a `<div>` with the `__child` element class and
@@ -72,7 +62,7 @@ export type ControlledProps = PropsWithChildren<WithClassName<{
  * - `--next` — this child has not yet been reached.
  *
  * @param props - Component properties.
- * @see {@link ControlledProps}
+ * @see {@link Props}
  * @returns A root `<div>` containing one classifier wrapper per child.
  */
-export declare const SequencerControlled: FunctionComponent<ControlledProps>;
+export declare const ControlledSequencer: FunctionComponent<Props>;

package/components/Sequencer/index.controlled.js

@@ -15,14 +15,14 @@ import cssModule from './styles.module.css';
  *
  * ### Root element modifiers
  * The root `<div>` receives the public class name defined by `sequencer` and
- * the following BEM-style modifier classes, sourced from `_modifiers`:
- * - `--playing` — when the sequence is actively progressing.
+ * the following BEM-style modifier classes:
+ * - `--playing` — when `isPlaying` is `true`.
  * - `--at-start` — when the current step is the first step.
  * - `--at-end` — when the current step is the last step.
  *
  * ### Data attributes on the root element
- * Derived from `_dataAttributes`, each key is prefixed with `data-`:
- * - `data-tempo` — current playback tempo, when provided.
+ * - `data-step` — the current step index.
+ * - `data-tempo` — current playback tempo, when `tempo` is provided.
  *
  * ### Child wrapper elements
  * Each child is wrapped in a `<div>` with the `__child` element class and
@@ -33,17 +33,20 @@ import cssModule from './styles.module.css';
  * - `--next` — this child has not yet been reached.
  *
  * @param props - Component properties.
- * @see {@link ControlledProps}
+ * @see {@link Props}
  * @returns A root `<div>` containing one classifier wrapper per child.
  */
-export const SequencerControlled = ({ step = 0, activateOnStep, _modifiers, _dataAttributes, className, children }) => {
+export const ControlledSequencer = ({ step = 0, activateOnStep, isPlaying = false, tempo, className, children }) => {
+    const childrenArr = Children.toArray(children);
+    const stepsCount = activateOnStep?.length ?? childrenArr.length;
     // Rendering
     const c = clss(publicClassName, { cssModule });
-    const rootClss = mergeClassNames(c(null, _modifiers), className);
-    const rootAttributes = Object
-        .entries({ ..._dataAttributes })
-        .reduce((acc, [key, val]) => ({ ...acc, [`data-${key}`]: val }), { 'data-step': step });
-    return _jsx("div", { className: rootClss, ...rootAttributes, children: Children.toArray(children)
+    const rootClss = mergeClassNames(c(null, {
+        playing: isPlaying,
+        'at-start': step === 0,
+        'at-end': step === stepsCount - 1
+    }), className);
+    return _jsx("div", { className: rootClss, "data-step": step, "data-tempo": tempo, children: childrenArr
             .map((child, childPos) => {
             const thisStepActivateOnStep = activateOnStep?.[step];
             const isPrevious = activateOnStep === undefined
@@ -62,6 +65,6 @@ export const SequencerControlled = ({ step = 0, activateOnStep, _modifiers, _dat
                 prev: isPrevious,
                 next: isNext
             });
-            return _jsx("div", { className: childClss, children: child });
+            return _jsx("div", { className: childClss, children: child }, childPos);
         }) });
 };

package/components/Sequencer/index.d.ts

@@ -1,11 +1,12 @@
 import { type FunctionComponent } from 'react';
 import { type Props as IOCompProps } from '../IntersectionObserver/index.js';
-import { type ControlledProps } from './index.controlled.js';
+import { type Props as ControlledProps } from './index.controlled.js';
 /**
  * Props for the {@link Sequencer} component.
  *
- * Extends {@link ControlledProps} (minus `_modifiers`, which are derived
- * internally) with uncontrolled playback and viewport-driven behaviour.
+ * Extends {@link ControlledProps} — minus `isPlaying` and `tempo`, which this
+ * component derives itself — with uncontrolled playback and viewport-driven
+ * behaviour.
  *
  * @property defaultStep - Initial step index when running in uncontrolled mode.
  * Ignored if `step` is provided. Defaults to `0`.
@@ -28,16 +29,15 @@ import { type 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 actionHandlers - Optional handlers for imperative actions triggered
- * by external events:
- * - `intersected` — forwarded verbatim to the internal
- * {@link IntersectionObserverComponent}'s `onIntersected`, called on every
- * intersection change regardless of controlled state.
- * @property stateHandlers - Optional callbacks invoked when derived state changes:
- * - `isPlaying` — called with the new play state whenever it changes.
- * - `stepChanged` — called with the new forwarded step index whenever it changes.
+ * @property onIntersected - Forwarded verbatim to the internal
+ * {@link IntersectionObserverComponent}, and called on every intersection
+ * change whichever mode the sequencer runs in.
+ * @property onIsPlayingChanged - Called after the effective play state changed,
+ * with the new value.
+ * @property onStepChanged - Called after the forwarded step changed, with the
+ * new value.
  */
-export type Props = Omit<ControlledProps, '_modifiers'> & {
+export type Props = Omit<ControlledProps, 'isPlaying' | 'tempo'> & {
     defaultStep?: number;
     tempo?: number;
     play?: boolean;
@@ -48,38 +48,33 @@ export type Props = Omit<ControlledProps, '_modifiers'> & {
     resetOnHidden?: boolean;
     playOnVisible?: boolean;
     pauseOnHidden?: boolean;
-    actionHandlers?: {
-        intersected?: IOCompProps['onIntersected'];
-    };
-    stateHandlers?: {
-        isPlaying?: (isPlaying: boolean) => void;
-        stepChanged?: (step: number) => void;
-    };
+    onIntersected?: IOCompProps['onIntersected'];
+    onIsPlayingChanged?: (isPlaying: boolean) => void;
+    onStepChanged?: (step: number) => void;
 };
 /**
  * Uncontrolled, self-advancing sequencer component. Drives a
- * {@link SequencerControlled} instance with an internal tempo-based interval,
+ * {@link ControlledSequencer} instance with an internal tempo-based interval,
  * optional loop/clamp boundary behaviour, and viewport-driven play/reset triggers
  * via an {@link IntersectionObserverComponent}.
  *
  * Supports mixed controlled/uncontrolled usage: passing `step` disables the
  * internal interval while still applying loop/clamp arithmetic before forwarding
  * to the controlled layer. Passing `play` disables internal play state management
- * while still allowing viewport handlers to fire `actionHandlers.intersected`.
+ * while still allowing viewport handlers to fire `onIntersected`.
  *
- * ### Forwarded modifiers to {@link SequencerControlled}
- * The following `_modifiers` are computed and injected automatically:
- * - `playing` — `true` when the effective play state is active.
- * - `at-start` — `true` when the forwarded step is `0`.
- * - `at-end` — `true` when the forwarded step equals `stepsCount - 1`.
+ * ### Forwarded to {@link ControlledSequencer}
+ * - `step` — the effective step, after loop/clamp arithmetic.
+ * - `isPlaying` — the effective play state, controlled or internal.
+ * - `tempo` — the current tempo, which the controlled layer exposes as `data-tempo`.
  *
- * ### Forwarded data attributes to {@link SequencerControlled}
- * - `data-tempo` — the current `tempo` value.
+ * The `--at-start` and `--at-end` modifiers are derived by the controlled layer
+ * from `step` and the children count.
  *
  * @param props - Component properties.
  * @see {@link Props}
- * @see {@link SequencerControlled}
+ * @see {@link ControlledSequencer}
  * @returns An {@link IntersectionObserverComponent} wrapping a
- * {@link SequencerControlled} with the computed step and modifiers applied.
+ * {@link ControlledSequencer} with the computed step and modifiers applied.
  */
 export declare const Sequencer: FunctionComponent<Props>;

package/components/Sequencer/index.js

@@ -1,43 +1,42 @@
 import { jsx as _jsx } from "react/jsx-runtime";
-import { useState, useEffect, useCallback, Children, useRef } from 'react';
+import { useState, useEffect, useCallback, Children } from 'react';
 import { absoluteModulo } from '../../agnostic/numbers/absolute-modulo/index.js';
 import { clamp } from '../../agnostic/numbers/clamp/index.js';
 import { IntersectionObserverComponent } from '../IntersectionObserver/index.js';
-import { SequencerControlled } from './index.controlled.js';
+import { useChangeDispatch } from '../utils/index.js';
+import { ControlledSequencer } from './index.controlled.js';
 /**
  * Uncontrolled, self-advancing sequencer component. Drives a
- * {@link SequencerControlled} instance with an internal tempo-based interval,
+ * {@link ControlledSequencer} instance with an internal tempo-based interval,
  * optional loop/clamp boundary behaviour, and viewport-driven play/reset triggers
  * via an {@link IntersectionObserverComponent}.
  *
  * Supports mixed controlled/uncontrolled usage: passing `step` disables the
  * internal interval while still applying loop/clamp arithmetic before forwarding
  * to the controlled layer. Passing `play` disables internal play state management
- * while still allowing viewport handlers to fire `actionHandlers.intersected`.
+ * while still allowing viewport handlers to fire `onIntersected`.
  *
- * ### Forwarded modifiers to {@link SequencerControlled}
- * The following `_modifiers` are computed and injected automatically:
- * - `playing` — `true` when the effective play state is active.
- * - `at-start` — `true` when the forwarded step is `0`.
- * - `at-end` — `true` when the forwarded step equals `stepsCount - 1`.
+ * ### Forwarded to {@link ControlledSequencer}
+ * - `step` — the effective step, after loop/clamp arithmetic.
+ * - `isPlaying` — the effective play state, controlled or internal.
+ * - `tempo` — the current tempo, which the controlled layer exposes as `data-tempo`.
  *
- * ### Forwarded data attributes to {@link SequencerControlled}
- * - `data-tempo` — the current `tempo` value.
+ * The `--at-start` and `--at-end` modifiers are derived by the controlled layer
+ * from `step` and the children count.
  *
  * @param props - Component properties.
  * @see {@link Props}
- * @see {@link SequencerControlled}
+ * @see {@link ControlledSequencer}
  * @returns An {@link IntersectionObserverComponent} wrapping a
- * {@link SequencerControlled} with the computed step and modifiers applied.
+ * {@link ControlledSequencer} with the computed step and modifiers applied.
  */
-export const Sequencer = ({ defaultStep, tempo = 60, play, loop, clampFirst, clampLast, resetOnVisible, resetOnHidden, playOnVisible, pauseOnHidden, actionHandlers, stateHandlers, ...controlledProps }) => {
+export const Sequencer = ({ defaultStep, tempo = 60, play, loop, clampFirst, clampLast, resetOnVisible, resetOnHidden, playOnVisible, pauseOnHidden, onIntersected, onIsPlayingChanged, onStepChanged, ...controlledProps }) => {
     // State
     const { step, activateOnStep, children } = controlledProps;
     const [internalPlay, setInternalPlay] = useState(play ?? false);
     const [internalStep, setInternalStep] = useState(step ?? defaultStep ?? 0);
     const actualPlay = play ?? internalPlay;
     const actualStep = step ?? internalStep;
-    const actualPlayRef = useRef(actualPlay);
     // Effects
     useEffect(() => {
         const clampedTempo = Math.max(tempo, 1);
@@ -61,24 +60,15 @@ export const Sequencer = ({ defaultStep, tempo = 60, play, loop, clampFirst, cla
         const rightClamp = clampLast === true ? stepsCount - 1 : Infinity;
         forwardedStep = clamp(actualStep, leftClamp, rightClamp);
     }
-    const forwardedStepRef = useRef(forwardedStep);
-    // State change handlers
-    useEffect(() => {
-        if (actualPlay !== actualPlayRef.current) {
-            actualPlayRef.current = actualPlay;
-            stateHandlers?.isPlaying?.(actualPlay);
-        }
-        if (forwardedStep !== forwardedStepRef.current) {
-            forwardedStepRef.current = forwardedStep;
-            stateHandlers?.stepChanged?.(forwardedStep);
-        }
-    }, [actualPlay, forwardedStep]);
+    // State dispatch
+    useChangeDispatch(actualPlay, onIsPlayingChanged);
+    useChangeDispatch(forwardedStep, onStepChanged);
     // Action handlers
     const handleIntersection = useCallback(({ ioEntry, observer }) => {
+        onIntersected?.({ ioEntry, observer });
         if (play === true || step !== undefined)
             return;
         const { isIntersecting } = ioEntry ?? {};
-        actionHandlers?.intersected?.({ ioEntry, observer });
         if (isIntersecting === true) {
             if (resetOnVisible === true)
                 setInternalStep(0);
@@ -98,12 +88,8 @@ export const Sequencer = ({ defaultStep, tempo = 60, play, loop, clampFirst, cla
         pauseOnHidden,
         play,
         step,
-        actionHandlers
+        onIntersected
     ]);
     // Rendering
-    return _jsx(IntersectionObserverComponent, { onIntersected: handleIntersection, children: _jsx(SequencerControlled, { ...controlledProps, step: forwardedStep, _modifiers: {
-                playing: actualPlay,
-                'at-start': forwardedStep === 0,
-                'at-end': forwardedStep === stepsCount - 1
-            }, _dataAttributes: { tempo } }) });
+    return _jsx(IntersectionObserverComponent, { onIntersected: handleIntersection, children: _jsx(ControlledSequencer, { ...controlledProps, step: forwardedStep, isPlaying: actualPlay, tempo: tempo }) });
 };

package/components/Subtitles/index.d.ts

@@ -1,6 +1,29 @@
 import { type FunctionComponent, type PropsWithChildren } from 'react';
 import type { WithClassName } from '../utils/types.js';
-import type { ParsedSub } from './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.
  *
@@ -16,10 +39,11 @@ import type { ParsedSub } from './types.js';
  * @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 - Callback invoked with the raw SRT string after a successful
- * fetch and parse. Not called when `srtFileContent` is used directly.
- * @property onParsed - Callback invoked with the raw SRT string has been parsed.
- * @property onLoadFailed - Callback invoked with an `Error` if the fetch or parse step fails.
+ * @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.
  * @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.
  */

package/components/Subtitles/index.js

@@ -1,12 +1,95 @@
 import { jsx as _jsx } from "react/jsx-runtime";
-import { useCallback, useEffect, useRef, useState } from 'react';
+import { useCallback, useEffect, 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 { mergeClassNames } from '../utils/index.js';
+import { mergeClassNames, useChangeDispatch } from '../utils/index.js';
 import { subtitles as publicClassName } from '../public-classnames.js';
-import { computeSubGroupsWithBoundaries, getCurrentGroup, parseSubs } 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
@@ -34,19 +117,14 @@ export const Subtitles = ({ src, srtFileContent, subsGroups, timecodeMs, isEnded
     const [isLoading, setIsLoading] = useState(false);
     const [loadError, setLoadError] = useState(null);
     const [parsedSubs, setParsedSubs] = useState([]);
-    const pParsedSubs = useRef(parsedSubs);
-    // State change handlers
-    useEffect(() => {
-        if (pParsedSubs.current === parsedSubs)
-            return;
-        onParsed?.(parsedSubs);
-    }, [parsedSubs]);
+    // State dispatch
+    useChangeDispatch(parsedSubs, onParsed);
     // Effects
     const fetchAndParseSubs = useCallback(async (src, srtFileContent) => {
-        if (src === undefined)
-            return;
         if (srtFileContent !== undefined)
             return setParsedSubs(parseSubs(srtFileContent));
+        if (src === undefined)
+            return;
         setIsLoading(true);
         setLoadError(null);
         try {