@design-edito/tools 0.5.37 → 0.5.39

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';
 /**
@@ -34,13 +35,13 @@ import cssModule from './styles.module.css';
  *
  * ### Root element attributes
  * - `id` — a stable generated id, assigned once on mount and used to scope the
- * module's `css` entries to this specific instance.
+ * module's `css` to this specific instance.
  *
  * @param props - Component properties.
  * @see {@link Props}
  * @see {@link ModuleData}
  * @returns A host `<div>` into which the module's root `Element` is appended,
- * along with any `<style>` blocks exported by the module.
+ * along with the `<style>` the module exported, if any.
  */
 export const UIModule = ({ src, props, onIdGenerated, onIsLoadingChanged, onLoadedModuleChanged, onModuleTargetChanged, className }) => {
     // State & refs
@@ -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; });
@@ -80,12 +81,8 @@ export const UIModule = ({ src, props, onIdGenerated, onIsLoadingChanged, onLoad
                 return setLoadedModule(new Error('Module exported member `destroy` must be a function'));
             if ('postInit' in data && typeof data.postInit !== 'function')
                 return setLoadedModule(new Error('Module exported member `postInit` must be a function'));
-            if ('css' in data) {
-                if (!Array.isArray(data.css))
-                    return setLoadedModule(new Error('Module exported member `css` must be an array of strings'));
-                if (data.css.some(entry => typeof entry !== 'string'))
-                    return setLoadedModule(new Error('Module exported member `css` must be an array of strings'));
-            }
+            if ('css' in data && typeof data.css !== 'string')
+                return setLoadedModule(new Error('Module exported member `css` must be a string'));
             if ('update' in data && typeof data.update !== 'function')
                 return setLoadedModule(new Error('Module exported member `update` must be a function'));
             // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion -- shape fully validated by the checks above
@@ -162,6 +159,6 @@ export const UIModule = ({ src, props, onIdGenerated, onIsLoadingChanged, onLoad
         'loaded': !isLoading && loadedModule !== null && !hasErrored,
         'initialized': moduleTarget !== null
     }), className);
-    const moduleCss = hasErrored || loadedModule === null ? [] : loadedModule.css ?? [];
-    return _jsx("div", { className: rootClss, ref: rootRef, id: id, children: moduleCss.map((css, cssPos) => _jsx("style", { children: `.${publicClassName}#${id} { ${css} }` }, cssPos)) });
+    const moduleCss = hasErrored || loadedModule === null ? undefined : loadedModule.css;
+    return _jsx("div", { className: rootClss, ref: rootRef, id: id, children: moduleCss !== undefined && _jsx("style", { children: `.${publicClassName}#${id} { ${moduleCss} }` }) });
 };

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

package/components/Video/index.d.ts

@@ -6,13 +6,6 @@ import { type Props as ControlledProps } from './index.controlled.js';
  * Props for the {@link Video} component.
  *
  * Extends all ControlledVideo props except play, mute, fullscreen, volume, playbackRate, and their associated event handlers
- * @property behavioursSuspended - Holds back the instructions that **start** something,
- * and lets through those that stop it. For a consumer withholding the video behind
- * something — a warning to accept, typically: a video kept back that plays anyway is not
- * withheld, it is merely hard to see. What was held back is replayed the moment this
- * goes false, so lifting the veil on an already-visible video does what was asked, which
- * a crossing-based trigger could never do. `':force'` does not override it: it speaks of
- * consent not yet given, where a surrender speaks of an intention already expressed.
  * @property visibilityThreshold - How much of the video has to be on screen to count as
  * seen. See {@link VisibilityOptions} for this and the four that follow it.
  * @property whenVisible - What to do each time it becomes visible.
@@ -39,7 +32,6 @@ import { type Props as ControlledProps } from './index.controlled.js';
  */
 export type Props = Omit<ControlledProps, 'play' | 'fullscreen' | 'volume' | 'mute' | 'playbackRate' | 'subtitlesOn' | 'rootRef' | 'videoRef'> & ViewportBehaviours<VideoAction> & {
     defaultSubtitlesOn?: boolean;
-    behavioursSuspended?: boolean;
 };
 /**
  * Full-featured video player component. Wraps a native `<video>` element with

package/components/Video/index.js

@@ -51,7 +51,7 @@ import { ControlledVideo } from './index.controlled.js';
  * The media still won't play, though: autoplay muted, and leave unmuting to the
  * reader.
  */
-export const Video = ({ defaultSubtitlesOn = true, behavioursSuspended, visibilityThreshold, visibilityRoot, visibilityRootMargin, visibilityOnAfterMs, visibilityOffAfterMs, whenVisible, whenHidden, onVisibilityChanged, onVideoClicked, onPlayButtonClicked, onPauseButtonClicked, onLoudButtonClicked, onMuteButtonClicked, onVolumeRangeChanged, onRateRangeChanged, onFullscreenButtonClicked, onSubtitlesButtonClicked, ...controlledProps }) => {
+export const Video = ({ defaultSubtitlesOn = true, visibilityThreshold, visibilityRoot, visibilityRootMargin, visibilityOnAfterMs, visibilityOffAfterMs, whenVisible, whenHidden, onVisibilityChanged, onVideoClicked, onPlayButtonClicked, onPauseButtonClicked, onLoudButtonClicked, onMuteButtonClicked, onVolumeRangeChanged, onRateRangeChanged, onFullscreenButtonClicked, onSubtitlesButtonClicked, ...controlledProps }) => {
     // State & refs
     const [play, setPlay] = useState(false);
     const [volume, setVolume] = useState(1);
@@ -73,14 +73,11 @@ export const Video = ({ defaultSubtitlesOn = true, behavioursSuspended, visibili
     // **Seeking belongs to `playback`.** A reader who has dragged the timeline has said
     // where they want to be, and an automatic jump would take it back from them.
     const actions = {
-        play: { kind: 'start', domain: 'playback', run: () => setPlay(true) },
-        pause: { kind: 'stop', domain: 'playback', run: () => setPlay(false) },
-        loud: { kind: 'start', domain: 'sound', run: () => setMute(false) },
-        mute: { kind: 'stop', domain: 'sound', run: () => setMute(true) },
-        // A seek starts nothing on its own — it moves a playhead, playing or not — so a gate
-        // has no reason to hold it back.
+        play: { domain: 'playback', run: () => setPlay(true) },
+        pause: { domain: 'playback', run: () => setPlay(false) },
+        loud: { domain: 'sound', run: () => setMute(false) },
+        mute: { domain: 'sound', run: () => setMute(true) },
         'jump-to': {
-            kind: 'stop',
             domain: 'playback',
             run: arg => {
                 const targetMs = Number(arg);
@@ -89,8 +86,8 @@ export const Video = ({ defaultSubtitlesOn = true, behavioursSuspended, visibili
                 forceJumpTo(videoRef.current, targetMs);
             }
         },
-        'jump-start': { kind: 'stop', domain: 'playback', run: () => forceJumpTo(videoRef.current, 0) },
-        'jump-end': { kind: 'stop', domain: 'playback', run: () => forceJumpTo(videoRef.current, -1) }
+        'jump-start': { domain: 'playback', run: () => forceJumpTo(videoRef.current, 0) },
+        'jump-end': { domain: 'playback', run: () => forceJumpTo(videoRef.current, -1) }
     };
     const { surrender: surrenderAnyDomain } = useViewportBehaviours(rootRef, {
         visibilityThreshold,
@@ -101,7 +98,7 @@ export const Video = ({ defaultSubtitlesOn = true, behavioursSuspended, visibili
         whenVisible,
         whenHidden,
         onVisibilityChanged
-    }, actions, behavioursSuspended === true);
+    }, actions);
     // Narrowed back to this component's own domains. The generic layer takes a `string`,
     // having no vocabulary of its own; handing the handlers a typed door means a
     // misspelled domain fails to compile instead of quietly never surrendering anything.
@@ -185,10 +182,9 @@ export const Video = ({ defaultSubtitlesOn = true, behavioursSuspended, visibili
         onFullscreenButtonClicked?.(payload);
         setFullscreen(!payload.isFullscreen);
     }, [onFullscreenButtonClicked]);
-    // Un seul bouton pour les deux sens, contrairement à lecture/pause et son/muet qui en
-    // ont un chacun : ceux-là existent en paire dans le DOM et la feuille en montre un,
-    // parce qu'ils portent deux glyphes opposés. Les sous-titres n'en portent qu'un, dont
-    // seul l'habillage change — inutile d'en rendre deux pour n'en montrer jamais qu'un.
+    // One button for both directions, where play/pause and loud/mute get one each: those
+    // carry two opposed glyphs, so both are rendered and the stylesheet shows one. The
+    // subtitles button carries a single glyph whose styling alone changes.
     const handleSubtitlesButtonClick = useCallback(payload => {
         onSubtitlesButtonClicked?.(payload);
         setSubtitlesOn(!payload.isSubtitlesOn);

package/components/Video/types.d.ts

@@ -40,3 +40,36 @@ export type VideoAction = Exclude<VideoVerb, 'jump-to'> | `jump-to:${number}`;
  * want to be, and an automatic jump would take it back from them.
  */
 export type VideoDomain = 'playback' | 'sound';
+/**
+ * One `<source>` of a `<video>`.
+ *
+ * **Not interchangeable with a picture source**: a `<source>` inside a `<video>` carries
+ * `src`, one inside a `<picture>` carries `srcSet`, `media` and `sizes`, and neither
+ * element accepts the other's attributes.
+ *
+ * @property src - URL of the video file.
+ * @property type - MIME type, so the browser can skip what it cannot play
+ * (`'video/mp4'`).
+ */
+export type SourceData = {
+    src?: string;
+    type?: string;
+};
+/**
+ * One `<track>` of a `<video>` — subtitles, captions, chapters.
+ *
+ * @property src - URL of the WebVTT file.
+ * @property kind - What the track holds. Browsers default to `'subtitles'`.
+ * @property srclang - Its BCP 47 language tag, required by the element whenever `kind`
+ * is `'subtitles'`.
+ * @property label - The name a browser shows in its own track menu.
+ * @property default - Whether it is the one enabled when no preference says otherwise.
+ * At most one track per element may carry it.
+ */
+export type TrackData = {
+    src?: string;
+    kind?: 'subtitles' | 'captions' | 'descriptions' | 'chapters' | 'metadata';
+    srclang?: string;
+    label?: string;
+    default?: boolean;
+};

package/components/Video/utils.d.ts

@@ -1,41 +1,7 @@
-/**
- * The two list shapes a `<video>` accepts as children, as records.
- *
- * They live here and not next to the component because nothing about them is React:
- * they describe a `<source>` and a `<track>` element.
- *
- * **A video source is not a picture source**, which is why `Image` keeps a shape of its
- * own rather than sharing this one: a `<source>` inside a `<video>` carries `src`, one
- * inside a `<picture>` carries `srcSet`, `media` and `sizes`, and neither element accepts
- * the other's attributes. What the two do share is how a list of them is read — see
- * `parseSourceList` in `components/utils`.
- */
-export type SourceData = {
-    src?: string;
-    type?: string;
-};
-export type TrackData = {
-    src?: string;
-    kind?: 'subtitles' | 'captions' | 'descriptions' | 'chapters' | 'metadata';
-    srclang?: string;
-    label?: string;
-    default?: boolean;
-};
 export declare const muteAttributeWorkaround: (video: HTMLVideoElement | null, shouldMute: boolean) => void;
 export declare const forceMute: (video: HTMLVideoElement | null) => void;
 export declare const forceLoud: (video: HTMLVideoElement | null) => void;
 export declare const forceVolume: (video: HTMLVideoElement | null, volume: number) => void;
-/**
- * Asks the element to play, and reports what came of it.
- *
- * A browser may refuse — an unmuted media outside a user gesture, typically — and
- * it refuses **silently**: the promise rejects and no event fires, so this is the
- * only moment the outcome can be known. Hence the return value, and hence no
- * logging: a refusal is not an anomaly to print, it is an answer to hand back.
- *
- * @param video - The element, or `null` before it mounts.
- * @returns Whether it is playing now.
- */
 export declare const forcePlay: (video: HTMLVideoElement | null) => Promise<boolean>;
 export declare const forcePause: (video: HTMLVideoElement | null) => boolean;
 export declare const forcePlaybackRate: (video: HTMLVideoElement | null, rate: number) => void;
@@ -43,38 +9,6 @@ export declare const forceFullscreen: (video: HTMLVideoElement | null) => Promis
 export declare const forceExitFullscreen: (video: HTMLVideoElement | null) => Promise<boolean>;
 export declare function secondsToMs(seconds: number): number;
 export declare function msToSeconds(ms: number): number;
-/**
- * Where along the timeline a click landed.
- *
- * @param event - The click on the timeline element.
- * @returns A ratio between `0` and `1`, clamped to the element's own bounds.
- */
 export declare const getTimelineClickProgress: (event: React.MouseEvent<HTMLDivElement>) => number;
-/**
- * Whether a viewport-driven behaviour should run on this crossing.
- *
- * Each behaviour comes in two flavours: `…When…` on every crossing, `…Once…` on the
- * first one only. Setting both is the same as setting `…When…` alone.
- *
- * @param whenCrossed - The `…When…` prop.
- * @param onceOnly - The `…Once…` prop.
- * @param hasFired - Whether this behaviour's own automatic trigger already ran. It
- * tracks that behaviour and nothing else: a user pressing play must not spend an
- * automatic mute the component still owed.
- * @returns Whether to apply it now.
- */
-/**
- * Seeks the element, in milliseconds, counting from the end when asked negatively.
- *
- * **A negative target counts back from the duration**, so `-1` is the last reachable
- * timecode. It is `-1` and not `-0` because `-0 === 0` in JavaScript, which would make
- * the end of a video indistinguishable from its start.
- *
- * Nothing happens before the metadata lands: the duration is `NaN` until then, and a
- * seek computed against it would land anywhere. An instruction asking for the end of a
- * video whose length is still unknown is simply not yet answerable.
- *
- * @param video - The element, or `null` before it mounts.
- * @param targetMs - Where to go. Negative counts from the end.
- */
 export declare const forceJumpTo: (video: HTMLVideoElement | null, targetMs: number) => void;
+export declare function parseSrcSetSourcesList<T extends Record<string, unknown>>(given: string | string[] | T[] | undefined, stringKey: keyof T & string): T[];

package/components/Video/utils.js

@@ -28,17 +28,8 @@ export const forceVolume = (video, volume) => {
     // eslint-disable-next-line no-param-reassign
     video.volume = volume;
 };
-/**
- * Asks the element to play, and reports what came of it.
- *
- * A browser may refuse — an unmuted media outside a user gesture, typically — and
- * it refuses **silently**: the promise rejects and no event fires, so this is the
- * only moment the outcome can be known. Hence the return value, and hence no
- * logging: a refusal is not an anomaly to print, it is an answer to hand back.
- *
- * @param video - The element, or `null` before it mounts.
- * @returns Whether it is playing now.
- */
+// A browser refuses playback silently: the promise rejects and no event fires, so the
+// return value is the only way the caller learns the outcome.
 export const forcePlay = async (video) => {
     if (video === null)
         return false;
@@ -107,44 +98,13 @@ export function secondsToMs(seconds) {
 export function msToSeconds(ms) {
     return ms / 1000;
 }
-/**
- * Where along the timeline a click landed.
- *
- * @param event - The click on the timeline element.
- * @returns A ratio between `0` and `1`, clamped to the element's own bounds.
- */
 export const getTimelineClickProgress = (event) => {
     const timelineRect = event.currentTarget.getBoundingClientRect();
     const position = event.clientX - timelineRect.left;
     return Math.min(1, Math.max(0, position / timelineRect.width));
 };
-/**
- * Whether a viewport-driven behaviour should run on this crossing.
- *
- * Each behaviour comes in two flavours: `…When…` on every crossing, `…Once…` on the
- * first one only. Setting both is the same as setting `…When…` alone.
- *
- * @param whenCrossed - The `…When…` prop.
- * @param onceOnly - The `…Once…` prop.
- * @param hasFired - Whether this behaviour's own automatic trigger already ran. It
- * tracks that behaviour and nothing else: a user pressing play must not spend an
- * automatic mute the component still owed.
- * @returns Whether to apply it now.
- */
-/**
- * Seeks the element, in milliseconds, counting from the end when asked negatively.
- *
- * **A negative target counts back from the duration**, so `-1` is the last reachable
- * timecode. It is `-1` and not `-0` because `-0 === 0` in JavaScript, which would make
- * the end of a video indistinguishable from its start.
- *
- * Nothing happens before the metadata lands: the duration is `NaN` until then, and a
- * seek computed against it would land anywhere. An instruction asking for the end of a
- * video whose length is still unknown is simply not yet answerable.
- *
- * @param video - The element, or `null` before it mounts.
- * @param targetMs - Where to go. Negative counts from the end.
- */
+// A negative target counts back from the duration, `-1` being the last reachable
+// timecode — not `-0`, which `===` makes indistinguishable from the start.
 export const forceJumpTo = (video, targetMs) => {
     if (video === null)
         return;
@@ -155,3 +115,24 @@ export const forceJumpTo = (video, targetMs) => {
     // eslint-disable-next-line no-param-reassign
     video.currentTime = msToSeconds(Math.min(Math.max(absolute, 0), durationMs));
 };
+/* Source lists */
+export function parseSrcSetSourcesList(given, stringKey) {
+    const fromString = (value) => {
+        const single = { [stringKey]: value };
+        // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion -- a one-key record is the narrowest `T` a bare string can describe; every other field is optional by contract
+        return single;
+    };
+    if (given === undefined)
+        return [];
+    if (typeof given === 'string')
+        return [fromString(given)];
+    if (!Array.isArray(given))
+        return [];
+    if (given.length === 0)
+        return [];
+    // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion -- first element sampled just above; array is read as homogeneous
+    if (typeof given[0] === 'string')
+        return given.map(fromString);
+    // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion -- first element was checked not to be a string just above; array is read as homogeneous
+    return given;
+}

package/components/index.d.ts

@@ -1,9 +1,9 @@
 export * as beforeAfter from './BeforeAfter/index.js'
-export * as clippable from './Clippable/index.js'
 export * as button from './Button/index.js'
+export * as clippable from './Clippable/index.js'
+export * as disclaimer from './Disclaimer/index.js'
 export * as drawer from './Drawer/index.js'
 export * as eventListener from './EventListener/index.js'
-export * as disclaimer from './Disclaimer/index.js'
 export * as gallery from './Gallery/index.js'
 export * as iframe from './Iframe/index.js'
 export * as image from './Image/index.js'
@@ -16,8 +16,8 @@ export * as overlayer from './Overlayer/index.js'
 export * as paginator from './Paginator/index.js'
 export * as resizeObserver from './ResizeObserver/index.js'
 export * as scrllgngn from './Scrllgngn/index.js'
-export * as select from './Select/index.js'
 export * as scrollListener from './ScrollListener/index.js'
+export * as select from './Select/index.js'
 export * as sequencer from './Sequencer/index.js'
 export * as shadowRoot from './ShadowRoot/index.js'
 export * as subtitles from './Subtitles/index.js'

package/components/index.js

@@ -1,9 +1,9 @@
 export * as beforeAfter from './BeforeAfter/index.js'
-export * as clippable from './Clippable/index.js'
 export * as button from './Button/index.js'
+export * as clippable from './Clippable/index.js'
+export * as disclaimer from './Disclaimer/index.js'
 export * as drawer from './Drawer/index.js'
 export * as eventListener from './EventListener/index.js'
-export * as disclaimer from './Disclaimer/index.js'
 export * as gallery from './Gallery/index.js'
 export * as iframe from './Iframe/index.js'
 export * as image from './Image/index.js'
@@ -16,8 +16,8 @@ export * as overlayer from './Overlayer/index.js'
 export * as paginator from './Paginator/index.js'
 export * as resizeObserver from './ResizeObserver/index.js'
 export * as scrllgngn from './Scrllgngn/index.js'
-export * as select from './Select/index.js'
 export * as scrollListener from './ScrollListener/index.js'
+export * as select from './Select/index.js'
 export * as sequencer from './Sequencer/index.js'
 export * as shadowRoot from './ShadowRoot/index.js'
 export * as subtitles from './Subtitles/index.js'

package/components/utils/index.d.ts

@@ -1,44 +1 @@
-export declare function mergeClassNames(...names: Array<string | null | undefined | Array<string | null | undefined>>): string;
-/**
- * Calls `onChange` whenever `value` changes, and only then — never on mount.
- *
- * This is how a component reports one of its state items to its consumer:
- * a bare `useEffect` on the value would also fire on the first render, telling
- * the consumer something changed when nothing did.
- *
- * @template T - Type of the watched value.
- * @param value - The value to watch.
- * @param onChange - Called with the new value, once the change has happened.
- * @param isEqual - Decides whether the value actually changed. Defaults to
- * `Object.is`, which covers booleans, numbers and strings. Pass a custom
- * comparison for values rebuilt on every render, such as an array or an object
- * derived from state, whose identity always differs.
- *
- * @remarks
- * `onChange` is deliberately left out of the effect's dependencies. A consumer
- * passing an inline arrow creates a new function on every render, which would
- * re-run the effect each time and defeat the guard. The handler is read when the
- * effect fires, so it is never a stale one.
- */
-export declare function useChangeDispatch<T>(value: T, onChange?: (value: T) => void, isEqual?: (a: T, b: T) => boolean): void;
-/**
- * The three forms a `<source>` list is written in, reduced to the one a render uses.
- *
- * A bare string is a single source, an array of strings is several, an array of records
- * is taken as given. **The array is read as homogeneous** — the first element decides for
- * all of them —, which is what someone writing one by hand means anyway, and the only
- * reading a static hyper-json array could support.
- *
- * `stringKey` is the whole reason this is shared rather than written twice. The parsing
- * is identical for `Video` and `Image`, but **the shorthand does not name the same
- * attribute**: a `<source>` inside a `<video>` carries `src`, one inside a `<picture>`
- * carries `srcSet`. The two record shapes stay apart for the same reason — the picture
- * source also takes `media` and `sizes`, which a video source has no use for, and neither
- * element accepts the other's key. One element, one shape; only the reading is common.
- *
- * @template T - The record shape the caller's element accepts.
- * @param given - What the consumer wrote.
- * @param stringKey - Where a bare string goes.
- * @returns The list as records, empty when there is nothing to render.
- */
-export declare function parseSourceList<T extends Record<string, unknown>>(given: string | string[] | T[] | undefined, stringKey: keyof T & string): T[];
+export * as viewportBehaviours from './viewport-behaviours/index.js'

package/components/utils/index.js

@@ -1,83 +1 @@
-import { useEffect, useRef } from 'react';
-export function mergeClassNames(...names) {
-    return names.map(name => {
-        if (typeof name !== 'string' && !Array.isArray(name))
-            return false;
-        if (Array.isArray(name))
-            return mergeClassNames(...name);
-        if (name.trim() === '')
-            return false;
-        return name.trim();
-    }).filter((name) => typeof name === 'string')
-        .join(' ');
-}
-/**
- * Calls `onChange` whenever `value` changes, and only then — never on mount.
- *
- * This is how a component reports one of its state items to its consumer:
- * a bare `useEffect` on the value would also fire on the first render, telling
- * the consumer something changed when nothing did.
- *
- * @template T - Type of the watched value.
- * @param value - The value to watch.
- * @param onChange - Called with the new value, once the change has happened.
- * @param isEqual - Decides whether the value actually changed. Defaults to
- * `Object.is`, which covers booleans, numbers and strings. Pass a custom
- * comparison for values rebuilt on every render, such as an array or an object
- * derived from state, whose identity always differs.
- *
- * @remarks
- * `onChange` is deliberately left out of the effect's dependencies. A consumer
- * passing an inline arrow creates a new function on every render, which would
- * re-run the effect each time and defeat the guard. The handler is read when the
- * effect fires, so it is never a stale one.
- */
-export function useChangeDispatch(value, onChange, isEqual = Object.is) {
-    const previousRef = useRef(value);
-    useEffect(() => {
-        if (isEqual(previousRef.current, value))
-            return;
-        previousRef.current = value;
-        onChange?.(value);
-    }, [value]);
-}
-/**
- * The three forms a `<source>` list is written in, reduced to the one a render uses.
- *
- * A bare string is a single source, an array of strings is several, an array of records
- * is taken as given. **The array is read as homogeneous** — the first element decides for
- * all of them —, which is what someone writing one by hand means anyway, and the only
- * reading a static hyper-json array could support.
- *
- * `stringKey` is the whole reason this is shared rather than written twice. The parsing
- * is identical for `Video` and `Image`, but **the shorthand does not name the same
- * attribute**: a `<source>` inside a `<video>` carries `src`, one inside a `<picture>`
- * carries `srcSet`. The two record shapes stay apart for the same reason — the picture
- * source also takes `media` and `sizes`, which a video source has no use for, and neither
- * element accepts the other's key. One element, one shape; only the reading is common.
- *
- * @template T - The record shape the caller's element accepts.
- * @param given - What the consumer wrote.
- * @param stringKey - Where a bare string goes.
- * @returns The list as records, empty when there is nothing to render.
- */
-export function parseSourceList(given, stringKey) {
-    const fromString = (value) => {
-        const single = { [stringKey]: value };
-        // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion -- a one-key record is the narrowest `T` a bare string can describe; every other field is optional by contract
-        return single;
-    };
-    if (given === undefined)
-        return [];
-    if (typeof given === 'string')
-        return [fromString(given)];
-    if (!Array.isArray(given))
-        return [];
-    if (given.length === 0)
-        return [];
-    // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion -- first element sampled just above; array is read as homogeneous
-    if (typeof given[0] === 'string')
-        return given.map(fromString);
-    // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion -- first element was checked not to be a string just above; array is read as homogeneous
-    return given;
-}
+export * as viewportBehaviours from './viewport-behaviours/index.js'