@design-edito/tools 0.5.38 → 0.5.39

package/components/Sequencer/index.js

@@ -1,80 +1,14 @@
 import { jsx as _jsx } from "react/jsx-runtime";
 import { Children, cloneElement, isValidElement, useEffect, useRef, useState } from 'react';
+import { useStateChangeDispatch } from '../../agnostic/@react/effects/use-state-change-dispatch/index.js';
 import { absoluteModulo } from '../../agnostic/numbers/absolute-modulo/index.js';
 import { clamp } from '../../agnostic/numbers/clamp/index.js';
 import { clss } from '../../agnostic/css/clss/index.js';
-import { mergeClassNames, useChangeDispatch } from '../utils/index.js';
+import { mergeClassNames } from '../../agnostic/css/merge-class-names/index.js';
 import { useViewportBehaviours } from '../utils/viewport-behaviours/index.js';
 import { sequencer as publicClassName } from '../public-classnames.js';
 import cssModule from './styles.module.css';
-/**
- * The attribute a child uses to say which steps it belongs to.
- *
- * **Written on the child rather than gathered in a prop**, and that is the whole
- * difference with the `activateOnStep` this component used to take. A parallel array and
- * a children list derive from one another: inserting a child in the middle means
- * reindexing the array, and nothing signals the one time it is forgotten. Carried by the
- * child, the attachment travels with it.
- *
- * It stays in the DOM once read — it costs nothing, it is worth having while debugging,
- * and a stylesheet can select on it.
- */
-const STEPS_ATTRIBUTE = 'data-steps';
-/**
- * The attribute a child uses to say that the sequence ends on it.
- *
- * It answers a shape the positional fallback could not: an article writes the steps in
- * reading order, then — **after** the sequence proper — the children that belong to
- * several steps at once and name them with {@link STEPS_ATTRIBUTE}. Those trailing
- * children would each claim a step of their own in the count, and the sequence would run
- * on into steps where nothing but them is lit.
- *
- * Marking the last step is what separates the two halves, and it is written where the
- * separation is rather than recounted in a prop — the same reason `data-steps` lives on
- * the child. A child after the mark that names no step therefore never lights up, which
- * is the honest reading of « it is not part of the sequence ».
- *
- * Valueless, as an HTML boolean attribute: what matters is that it is there.
- */
-const LAST_STEP_ATTRIBUTE = 'data-last-step';
-/**
- * `data-steps="2, 6"` into the steps it names.
- *
- * Anything unreadable gives back `null`, which the caller reads as « the attribute was
- * not written » and falls back to the child's position. That is lm-link's rule applied
- * here — a typo costs the default behaviour, never a broken one.
- */
-function parseSteps(raw) {
-    if (typeof raw !== 'string')
-        return null;
-    const parts = raw.split(',').map(part => part.trim()).filter(part => part !== '');
-    if (parts.length === 0)
-        return null;
-    const steps = parts.map(Number);
-    if (steps.some(step => !Number.isInteger(step)))
-        return null;
-    return steps;
-}
-/**
- * Whether a child carries {@link LAST_STEP_ATTRIBUTE}.
- *
- * Present is enough — `data-last-step` alone gives `''` through lm-html, and `true`
- * written in JSX. Only an explicit denial is read as one, so that a consumer computing
- * the attribute can write `false` without having to leave it out.
- */
-function isLastStep(child) {
-    // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion -- a React element's props are a record, whatever else they are
-    const raw = child.props[LAST_STEP_ATTRIBUTE];
-    if (raw === undefined || raw === null)
-        return false;
-    return raw !== false && raw !== 'false';
-}
-/** The steps a child answers to: what it declares, or where it sits. */
-function stepsOf(child, elementIndex) {
-    // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion -- a React element's props are a record, whatever else they are
-    const declared = parseSteps(child.props[STEPS_ATTRIBUTE]);
-    return declared ?? [elementIndex];
-}
+import { getChildActiveSteps, hasDataLastStepAttribute } from './utils.js';
 /**
  * A sequencer over its children, which it classifies and never moves.
  *
@@ -118,7 +52,7 @@ function stepsOf(child, elementIndex) {
  * **Nothing surrenders here.** The layer lets a reader's hand switch an instruction off
  * for the rest of the mount, and this component has no control for a hand to touch — so
  * `':force'` has nothing to override, and the single `'playback'` domain is a formality.
- * A gate still holds `'play'` back, which is a different brake. @see {@link SequencerDomain}
+ * @see {@link SequencerDomain}
  *
  * ### On the root
  * `--playing`, `--at-start`, `--at-end`, `--ended`, plus `data-step`, `data-active-step`,
@@ -148,19 +82,14 @@ function stepsOf(child, elementIndex) {
  * therefore `--is-first` at 1 and `--not-first` at 6, and the answer is the same on every
  * lap without anything being reset.
  */
-export const Sequencer = ({ totalSteps, stepMap, step, defaultStep, play, defaultPlay, tempo = 60, loop, onStepChanged, onIsPlayingChanged, onIsEndedChanged, onLooped, onReachedFirstStep, onReachedLastStep, behavioursSuspended, visibilityThreshold, visibilityRoot, visibilityRootMargin, visibilityOnAfterMs, visibilityOffAfterMs, whenVisible, whenHidden, onVisibilityChanged, className, children }) => {
+export const Sequencer = ({ totalSteps, stepMap, step, defaultStep, play, defaultPlay, tempo = 60, loop, onStepChanged, onIsPlayingChanged, onIsEndedChanged, onLooped, onReachedFirstStep, onReachedLastStep, visibilityThreshold, visibilityRoot, visibilityRootMargin, visibilityOnAfterMs, visibilityOffAfterMs, whenVisible, whenHidden, onVisibilityChanged, className, children }) => {
     const [internalStep, setInternalStep] = useState(step ?? defaultStep ?? 0);
     const [internalPlay, setInternalPlay] = useState(defaultPlay ?? false);
     const [hasLapped, setHasLapped] = useState(0);
     const rootRef = useRef(null);
-    // Children, split once: what takes part and what merely renders.
     const childrenArr = Children.toArray(children);
     const elements = childrenArr.filter(isValidElement);
-    // Three answers to « how long is the sequence », in decreasing order of explicitness:
-    // the prop, then the child that says the sequence ends on it, then the count of
-    // element children. The prop wins because it is the one a consumer writes knowing the
-    // whole, where the mark only knows where it sits.
-    const markedLast = elements.findIndex(isLastStep);
+    const markedLast = elements.findIndex(hasDataLastStepAttribute);
     const impliedSteps = markedLast === -1 ? elements.length : markedLast + 1;
     const stepsCount = Math.max(totalSteps ?? impliedSteps, 0);
     // The two numbers
@@ -171,12 +100,8 @@ export const Sequencer = ({ totalSteps, stepMap, step, defaultStep, play, defaul
             : clamp(rawStep, 0, stepsCount - 1))
         : 0;
     const activeStep = stepMap?.[position] ?? position;
-    // **The end is the counter leaving the last step, not arriving on it.** The last step
-    // is owed its beat like every other one, so the counter runs one past the end while
-    // the position clamps to it — which is also what keeps the whole thing derived: nothing
-    // has to be unset when `loop` or `step` changes under it, and `onReachedLastStep` stays
-    // the arrival that this is not. A sequence merely paused on the last step has not
-    // ended, and a consumer driving `step` says so by naming the position after the last.
+    // The counter runs one past the end so the last step gets its beat, and the position
+    // clamps to it. Ended is therefore leaving the last step, not arriving on it.
     const isEnded = loop !== true && stepsCount > 0 && rawStep >= stepsCount;
     const isPlaying = (play ?? internalPlay) && !isEnded;
     useEffect(() => {
@@ -197,18 +122,8 @@ export const Sequencer = ({ totalSteps, stepMap, step, defaultStep, play, defaul
         onLooped?.();
     }, [lap, loop]);
     // Viewport behaviours
-    // A jump names a position and lands on it **within the current lap**: the counter is
-    // absolute, so setting it to a bare position on a looping sequence would count as a
-    // wrap backwards and fire `onLooped` for a move nobody made. `jump-by` is left alone
-    // on purpose — stepping past the last position really is a wrap, and says so.
-    //
-    // **The lap offset is for looping sequences only, and adding it elsewhere was a bug.**
-    // A sequence that does not loop runs its counter one past the end and leaves it there,
-    // so `lap` reads `1` from that moment on — and `jump-start` landed on `1 * stepsCount`,
-    // which is precisely the ended position it was asked to leave. The symptom: a sequence
-    // with `whenVisible='jump-start'` played once, stopped on its last step, and stayed
-    // there however many times it was scrolled past. Nothing is lost by dropping the
-    // offset here: without `loop`, there is no wrap to misread and `onLooped` never fires.
+    // The lap offset only applies while looping: on a sequence that does not loop, `lap`
+    // reads `1` past the end, and adding it would land `jump-start` back on the end.
     const jumpToPosition = (target) => {
         if (step !== undefined || stepsCount <= 0)
             return;
@@ -223,18 +138,12 @@ export const Sequencer = ({ totalSteps, stepMap, step, defaultStep, play, defaul
             return;
         setInternalStep(current => current + offset);
     };
-    // What each verb does. Rebuilt on every render — it closes over the setters — which is
-    // why the generic layer reads it through a ref rather than a dependency list.
-    //
     // `play` and `pause` need no guard against a controlled `play`: the effective state
-    // reads the prop first, so the internal one they write is simply never consulted.
+    // reads the prop first, so the internal one they write is never consulted.
     const actions = {
-        play: { kind: 'start', domain: 'playback', run: () => setInternalPlay(true) },
-        pause: { kind: 'stop', domain: 'playback', run: () => setInternalPlay(false) },
-        // A jump starts nothing on its own — it moves a counter, playing or not — so a gate
-        // has no reason to hold it back.
+        play: { domain: 'playback', run: () => setInternalPlay(true) },
+        pause: { domain: 'playback', run: () => setInternalPlay(false) },
         'jump-to': {
-            kind: 'stop',
             domain: 'playback',
             run: arg => {
                 const target = Number(arg);
@@ -243,10 +152,9 @@ export const Sequencer = ({ totalSteps, stepMap, step, defaultStep, play, defaul
                 jumpToPosition(target);
             }
         },
-        'jump-start': { kind: 'stop', domain: 'playback', run: () => jumpToPosition(0) },
-        'jump-end': { kind: 'stop', domain: 'playback', run: () => jumpToPosition(-1) },
+        'jump-start': { domain: 'playback', run: () => jumpToPosition(0) },
+        'jump-end': { domain: 'playback', run: () => jumpToPosition(-1) },
         'jump-by': {
-            kind: 'stop',
             domain: 'playback',
             run: arg => {
                 const offset = Number(arg);
@@ -256,8 +164,7 @@ export const Sequencer = ({ totalSteps, stepMap, step, defaultStep, play, defaul
             }
         }
     };
-    // The surrender half of the result is dropped, and that is the whole of what this
-    // component's lack of controls changes: nothing here can be taken over by hand.
+    // The surrender half is dropped: this component has no control a hand could take over.
     useViewportBehaviours(rootRef, {
         visibilityThreshold,
         visibilityRoot,
@@ -267,14 +174,14 @@ export const Sequencer = ({ totalSteps, stepMap, step, defaultStep, play, defaul
         whenVisible,
         whenHidden,
         onVisibilityChanged
-    }, actions, behavioursSuspended === true);
+    }, actions);
     // State dispatch
-    useChangeDispatch(position, () => onStepChanged?.({ step: position, activeStep }));
-    useChangeDispatch(isPlaying, onIsPlayingChanged);
-    useChangeDispatch(isEnded, onIsEndedChanged);
-    useChangeDispatch(position === 0, atStart => { if (atStart)
+    useStateChangeDispatch(position, () => onStepChanged?.({ step: position, activeStep }));
+    useStateChangeDispatch(isPlaying, onIsPlayingChanged);
+    useStateChangeDispatch(isEnded, onIsEndedChanged);
+    useStateChangeDispatch(position === 0, atStart => { if (atStart)
         onReachedFirstStep?.(); });
-    useChangeDispatch(stepsCount > 0 && position === stepsCount - 1, atEnd => { if (atEnd)
+    useStateChangeDispatch(stepsCount > 0 && position === stepsCount - 1, atEnd => { if (atEnd)
         onReachedLastStep?.(); });
     // Rendering
     const c = clss(publicClassName, { cssModule });
@@ -284,8 +191,6 @@ export const Sequencer = ({ totalSteps, stepMap, step, defaultStep, play, defaul
         'at-end': stepsCount > 0 && position === stepsCount - 1,
         ended: isEnded
     }), className);
-    // Walked once per render: for each element, the positions of this lap at which it is
-    // active. Cheap, and it is what makes the three pairs answerable without memory.
     const positionsOf = (steps) => {
         const positions = [];
         for (let i = 0; i < stepsCount; i += 1) {
@@ -294,14 +199,9 @@ export const Sequencer = ({ totalSteps, stepMap, step, defaultStep, play, defaul
         }
         return positions;
     };
-    // **The lap count is the wraps, so it is zero without `loop`.** The internal counter
-    // runs one past the end and stays there, which makes `lap` read `1` on a sequence that
-    // never wrapped at all — true of the division, false of the thing it is named after,
-    // and `onLooped` says the same by never firing without `loop`.
+    // A lap is a wrap, so there is none without `loop` — where the internal counter would
+    // report `1` past the end. Both numbers below are rebuilt from it rather than `rawStep`.
     const publishedLap = loop === true ? lap : 0;
-    // Rebuilt from the published lap rather than read off `rawStep`, for that same reason:
-    // at the end of a non-looping sequence the internal counter sits one step past the last
-    // position, and a number meant to drive a transform must not overshoot the picture.
     const rawStepProp = publishedLap * stepsCount + position;
     const cssCustomProps = {
         '--lm-sequencer-step': `${position}`,
@@ -316,7 +216,7 @@ export const Sequencer = ({ totalSteps, stepMap, step, defaultStep, play, defaul
             if (!isValidElement(child))
                 return child;
             elementIndex += 1;
-            const steps = stepsOf(child, elementIndex);
+            const steps = getChildActiveSteps(child, elementIndex);
             const positions = positionsOf(steps);
             const isOn = steps.includes(activeStep);
             const hasEarlier = positions.some(p => p < position);
@@ -331,9 +231,7 @@ export const Sequencer = ({ totalSteps, stepMap, step, defaultStep, play, defaul
             });
             // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion -- a React element's props are a record, whatever else they are
             const ownClassName = child.props.className;
-            // `className` is the whole of what a child is asked to honour, and the only prop
-            // touched here — its own is kept, and comes second so a consumer's class wins a
-            // shorthand conflict.
+            // The child's own class comes second, so a consumer wins a shorthand conflict.
             const nextProps = {
                 key: childPos,
                 className: mergeClassNames(childClss, typeof ownClassName === 'string' ? ownClassName : undefined)

package/components/Sequencer/types.d.ts

@@ -55,3 +55,33 @@ export type SequencerAction = Exclude<SequencerVerb, 'jump-to' | 'jump-by'> | `j
  * there are none.
  */
 export type SequencerDomain = 'playback';
+/**
+ * The attribute a child uses to say which steps it belongs to.
+ *
+ * **Written on the child rather than gathered in a prop**, and that is the whole
+ * difference with the `activateOnStep` this component used to take. A parallel array and
+ * a children list derive from one another: inserting a child in the middle means
+ * reindexing the array, and nothing signals the one time it is forgotten. Carried by the
+ * child, the attachment travels with it.
+ *
+ * It stays in the DOM once read — it costs nothing, it is worth having while debugging,
+ * and a stylesheet can select on it.
+ */
+export declare const STEPS_ATTRIBUTE = "data-steps";
+/**
+ * The attribute a child uses to say that the sequence ends on it.
+ *
+ * It answers a shape the positional fallback could not: an article writes the steps in
+ * reading order, then — **after** the sequence proper — the children that belong to
+ * several steps at once and name them with {@link STEPS_ATTRIBUTE}. Those trailing
+ * children would each claim a step of their own in the count, and the sequence would run
+ * on into steps where nothing but them is lit.
+ *
+ * Marking the last step is what separates the two halves, and it is written where the
+ * separation is rather than recounted in a prop — the same reason `data-steps` lives on
+ * the child. A child after the mark that names no step therefore never lights up, which
+ * is the honest reading of « it is not part of the sequence ».
+ *
+ * Valueless, as an HTML boolean attribute: what matters is that it is there.
+ */
+export declare const LAST_STEP_ATTRIBUTE = "data-last-step";

package/components/Sequencer/types.js

@@ -30,3 +30,33 @@ export const SEQUENCER_VERB_ARGUMENTS = {
     'jump-to': (arg) => /^-?\d+$/v.test(arg),
     'jump-by': (arg) => /^-?\d+$/v.test(arg)
 };
+/**
+ * The attribute a child uses to say which steps it belongs to.
+ *
+ * **Written on the child rather than gathered in a prop**, and that is the whole
+ * difference with the `activateOnStep` this component used to take. A parallel array and
+ * a children list derive from one another: inserting a child in the middle means
+ * reindexing the array, and nothing signals the one time it is forgotten. Carried by the
+ * child, the attachment travels with it.
+ *
+ * It stays in the DOM once read — it costs nothing, it is worth having while debugging,
+ * and a stylesheet can select on it.
+ */
+export const STEPS_ATTRIBUTE = 'data-steps';
+/**
+ * The attribute a child uses to say that the sequence ends on it.
+ *
+ * It answers a shape the positional fallback could not: an article writes the steps in
+ * reading order, then — **after** the sequence proper — the children that belong to
+ * several steps at once and name them with {@link STEPS_ATTRIBUTE}. Those trailing
+ * children would each claim a step of their own in the count, and the sequence would run
+ * on into steps where nothing but them is lit.
+ *
+ * Marking the last step is what separates the two halves, and it is written where the
+ * separation is rather than recounted in a prop — the same reason `data-steps` lives on
+ * the child. A child after the mark that names no step therefore never lights up, which
+ * is the honest reading of « it is not part of the sequence ».
+ *
+ * Valueless, as an HTML boolean attribute: what matters is that it is there.
+ */
+export const LAST_STEP_ATTRIBUTE = 'data-last-step';

package/components/Sequencer/utils.d.ts

@@ -0,0 +1,4 @@
+import type { ReactElement } from 'react';
+export declare function parseDataStepsAttribute(raw: unknown): number[] | null;
+export declare function hasDataLastStepAttribute(child: ReactElement): boolean;
+export declare function getChildActiveSteps(child: ReactElement, elementIndex: number): number[];

package/components/Sequencer/utils.js

@@ -0,0 +1,25 @@
+import { LAST_STEP_ATTRIBUTE, STEPS_ATTRIBUTE } from './types.js';
+export function parseDataStepsAttribute(raw) {
+    if (typeof raw !== 'string')
+        return null;
+    const parts = raw.split(',').map(part => part.trim()).filter(part => part !== '');
+    if (parts.length === 0)
+        return null;
+    const steps = parts.map(Number);
+    if (steps.some(step => !Number.isInteger(step)))
+        return null;
+    return steps;
+}
+export function hasDataLastStepAttribute(child) {
+    // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion -- a React element's props are a record, whatever else they are
+    const raw = child.props[LAST_STEP_ATTRIBUTE];
+    if (raw === undefined || raw === null)
+        return false;
+    return raw !== false && raw !== 'false';
+}
+export function getChildActiveSteps(child, elementIndex) {
+    // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion -- a React element's props are a record, whatever else they are
+    const props = child.props;
+    const declared = parseDataStepsAttribute(props[STEPS_ATTRIBUTE]);
+    return declared ?? [elementIndex];
+}

package/components/ShadowRoot/index.js

@@ -2,8 +2,8 @@ import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-run
 import { useRef, useEffect, useState } from 'react';
 import { createPortal } from 'react-dom';
 import { clss } from '../../agnostic/css/clss/index.js';
+import { mergeClassNames } from '../../agnostic/css/merge-class-names/index.js';
 import { shadowRoot as publicClassName } from '../public-classnames.js';
-import { mergeClassNames } from '../utils/index.js';
 import cssModule from './styles.module.css';
 /**
  * Component that creates a Shadow Root on its host element and renders

package/components/Subtitles/index.js

@@ -1,9 +1,10 @@
 import { jsx as _jsx } from "react/jsx-runtime";
 import { useEffect, useRef, useState } from 'react';
+import { useStateChangeDispatch } from '../../agnostic/@react/effects/use-state-change-dispatch/index.js';
 import { clss } from '../../agnostic/css/clss/index.js';
 import { toError } from '../../agnostic/misc/cast/index.js';
 import { parseSrt } from '../../agnostic/subtitles/parse-srt/index.js';
-import { mergeClassNames, useChangeDispatch } from '../utils/index.js';
+import { mergeClassNames } from '../../agnostic/css/merge-class-names/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';
@@ -44,9 +45,6 @@ export const Subtitles = ({ cues, srtFileContent, src, subsGroups, timecodeMs, i
     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(() => {
@@ -54,7 +52,7 @@ export const Subtitles = ({ cues, srtFileContent, src, subsGroups, timecodeMs, i
         onLoadFailedRef.current = onLoadFailed;
     });
     // State dispatch
-    useChangeDispatch(parsedSubs, onParsed);
+    useStateChangeDispatch(parsedSubs, onParsed);
     // Fx. dep. cues, srtFileContent, src - Load from whichever source is set
     useEffect(() => {
         setIsLoading(false);

package/components/Subtitles/utils.d.ts

@@ -1,60 +1,9 @@
 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

@@ -1,30 +1,9 @@
-/**
- * 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 [];
@@ -37,16 +16,6 @@ export function toSubGroups(boundaries, lastPos) {
     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;
@@ -57,16 +26,6 @@ export function lastElapsedPos(cues, timecodeMs) {
     });
     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];

package/components/Textarea/index.js

@@ -3,7 +3,7 @@ import { useLayoutEffect, useRef, useState } from 'react';
 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 { mergeClassNames } from '../../agnostic/css/merge-class-names/index.js';
 import { textarea as publicClassName } from '../public-classnames.js';
 import cssModule from './styles.module.css';
 /**

package/components/UIModule/index.js

@@ -1,10 +1,11 @@
 import { jsx as _jsx } from "react/jsx-runtime";
 import { useEffect, useRef, useState } from 'react';
+import { useStateChangeDispatch } from '../../agnostic/@react/effects/use-state-change-dispatch/index.js';
 import { clss } from '../../agnostic/css/clss/index.js';
 import { unknownToString } from '../../agnostic/errors/unknown-to-string/index.js';
 import { isNonNullObject } from '../../agnostic/objects/is-object/index.js';
 import { randomHash } from '../../agnostic/random/uuid/index.js';
-import { mergeClassNames, useChangeDispatch } from '../utils/index.js';
+import { mergeClassNames } from '../../agnostic/css/merge-class-names/index.js';
 import { uiModule as publicClassName } from '../public-classnames.js';
 import cssModule from './styles.module.css';
 /**
@@ -56,9 +57,9 @@ export const UIModule = ({ src, props, onIdGenerated, onIsLoadingChanged, onLoad
     // the render it ran on. This is what `init` and `postInit` read instead.
     const propsRef = useRef(props);
     // State dispatch
-    useChangeDispatch(isLoading, onIsLoadingChanged);
-    useChangeDispatch(loadedModule, onLoadedModuleChanged);
-    useChangeDispatch(moduleTarget, onModuleTargetChanged);
+    useStateChangeDispatch(isLoading, onIsLoadingChanged);
+    useStateChangeDispatch(loadedModule, onLoadedModuleChanged);
+    useStateChangeDispatch(moduleTarget, onModuleTargetChanged);
     // Fx. no dep. - keep the latest props reachable from the effects that run outside
     // their own render, declared first so they read this render's value and not the last
     useEffect(() => { propsRef.current = props; });

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

@@ -1,13 +1,7 @@
 import { type FunctionComponent, type PropsWithChildren, type Ref, type RefObject, type VideoHTMLAttributes } from 'react';
 import type { WithClassName } from '../utils/types.js';
 import { type Props as SubsProps } from '../Subtitles/index.js';
-import { type SourceData, type TrackData } from './utils.js';
-/**
- * Describes a single video source.
- *
- * @property src - URL of the video file.
- * @property type - MIME type of the source (e.g. `'video/mp4'`).
- */
+import type { SourceData, TrackData } from './types.js';
 /**
  * Props for the ControlledVideo component.
  *

package/components/Video/index.controlled.js

@@ -1,12 +1,13 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { useMemo, useRef, useState, useCallback, useEffect } from 'react';
+import { useStateChangeDispatch } from '../../agnostic/@react/effects/use-state-change-dispatch/index.js';
 import { clss } from '../../agnostic/css/clss/index.js';
 import { formatDuration } from '../../agnostic/time/duration/format-duration/index.js';
-import { mergeClassNames, parseSourceList, useChangeDispatch } from '../utils/index.js';
+import { mergeClassNames } from '../../agnostic/css/merge-class-names/index.js';
 import cssModule from './styles.module.css';
 import { video as publicClassName } from '../public-classnames.js';
 import { Subtitles } from '../Subtitles/index.js';
-import { forceExitFullscreen, forceFullscreen, forceLoud, forceMute, forcePause, forcePlay, forcePlaybackRate, forceVolume, getTimelineClickProgress, msToSeconds, secondsToMs } from './utils.js';
+import { forceExitFullscreen, forceFullscreen, forceLoud, forceMute, forcePause, forcePlay, forcePlaybackRate, forceVolume, getTimelineClickProgress, msToSeconds, parseSrcSetSourcesList, secondsToMs } from './utils.js';
 /**
  * Full-featured video player component. Wraps a native `<video>` element with
  * playback controls, volume, playback rate, a timeline, optional subtitles
@@ -226,8 +227,8 @@ timeFormat = '{{mm}}:{{ss}}:{{ms}}', onPlayButtonClicked, onPauseButtonClicked,
         '--lm-video-volume-ratio': `${volume}`,
         '--lm-video-playback-rate': `${playbackRate}`
     };
-    const parsedSources = useMemo(() => parseSourceList(sources, 'src'), [sources]);
-    const parsedTracks = useMemo(() => parseSourceList(tracks, 'src'), [tracks]);
+    const parsedSources = useMemo(() => parseSrcSetSourcesList(sources, 'src'), [sources]);
+    const parsedTracks = useMemo(() => parseSrcSetSourcesList(tracks, 'src'), [tracks]);
     const videoClss = c('video');
     const videoControlsClss = c('video-controls');
     const playBtnClss = c('play-btn');
@@ -305,13 +306,13 @@ timeFormat = '{{mm}}:{{ss}}:{{ms}}', onPlayButtonClicked, onPauseButtonClicked,
         return () => { document.removeEventListener('fullscreenchange', onDocumentFullscreenChange); };
     }, [onFullscreenChange]);
     // State handlers
-    useChangeDispatch(currentTimeMs, onCurrentTimeMsChanged);
-    useChangeDispatch(isElementPlaying, onIsPlayingChanged);
-    useChangeDispatch(isFullscreen, onIsFullscreenChanged);
-    useChangeDispatch(isLoud, onIsLoudChanged);
-    useChangeDispatch(subtitlesOn, onIsSubtitlesOnChanged);
-    useChangeDispatch(isEnded, onIsEndedChanged);
-    useChangeDispatch(volume, onVolumeChanged);
-    useChangeDispatch(playbackRate, onPlaybackRateChanged);
+    useStateChangeDispatch(currentTimeMs, onCurrentTimeMsChanged);
+    useStateChangeDispatch(isElementPlaying, onIsPlayingChanged);
+    useStateChangeDispatch(isFullscreen, onIsFullscreenChanged);
+    useStateChangeDispatch(isLoud, onIsLoudChanged);
+    useStateChangeDispatch(subtitlesOn, onIsSubtitlesOnChanged);
+    useStateChangeDispatch(isEnded, onIsEndedChanged);
+    useStateChangeDispatch(volume, onVolumeChanged);
+    useStateChangeDispatch(playbackRate, onPlaybackRateChanged);
     return _jsxs("figure", { ref: rootRef, className: rootClss, style: rootStyles, ...rootAttributes, children: [_jsxs("video", { ref: videoRef, className: videoClss, ...intrinsicVideoAttributes, autoPlay: isTimeControlled ? false : intrinsicVideoAttributes.autoPlay, onClick: handleVideoClick, onLoadedMetadata: handleMetadataLoadEvent, onTimeUpdate: handleOnTimeUpdateEvent, onEnded: handleEndedEvent, onPlay: handlePlayEvent, onPause: handlePauseEvent, children: [parsedSources.map((source, index) => _jsx("source", { src: source.src, type: source.type }, index)), parsedTracks.map((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 }), subtitles !== undefined && _jsx("button", { className: subtitlesBtnClss, onClick: handleSubtitlesButtonClick, children: subtitlesBtnContent }), _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: formatDuration(currentTimeMs, timeFormat) }), _jsx("span", { className: totalTimeClss, children: formatDuration(totalTimeMs, timeFormat) }), _jsx("div", { className: timelineClss, onClick: handleTimelineClick })] }), subtitles !== undefined && _jsx(Subtitles, { ...subtitles, timecodeMs: currentTimeMs, isEnded: isEnded })] });
 };