@design-edito/tools 0.4.11 → 0.4.12

package/agnostic/strings/split-trim/index.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Splits a string into segments, trims whitespace from each part, and optionally removes empty segments.
+ *
+ * Each segment is trimmed with `String.prototype.trim`. When `removeEmpty` is `true`, segments that
+ * become empty after trimming are filtered out.
+ *
+ * When `splitter` is an array, each separator is applied in order: every current segment is split
+ * with the next separator before moving on to the following one.
+ *
+ * @param toSplit - The string to split.
+ * @param splitter - A single separator, or an ordered list of separators passed to `String.prototype.split`.
+ * @param removeEmpty - When `true`, drops segments that are empty after trimming. Defaults to `false`.
+ * @returns An array of trimmed string segments.
+ *
+ * @example
+ * splitTrim(' foo , bar , baz ', ',')
+ * // => ['foo', 'bar', 'baz']
+ *
+ * @example
+ * splitTrim('foo,,bar', ',', true)
+ * // => ['foo', 'bar']
+ *
+ * @example
+ * splitTrim('foo bar,baz', [' ', ','])
+ * // => ['foo', 'bar', 'baz']
+ */
+export declare const splitTrim: (toSplit: string, splitter: string | RegExp | Array<string | RegExp>, removeEmpty?: boolean) => string[];

package/agnostic/strings/split-trim/index.js

@@ -0,0 +1,36 @@
+/**
+ * Splits a string into segments, trims whitespace from each part, and optionally removes empty segments.
+ *
+ * Each segment is trimmed with `String.prototype.trim`. When `removeEmpty` is `true`, segments that
+ * become empty after trimming are filtered out.
+ *
+ * When `splitter` is an array, each separator is applied in order: every current segment is split
+ * with the next separator before moving on to the following one.
+ *
+ * @param toSplit - The string to split.
+ * @param splitter - A single separator, or an ordered list of separators passed to `String.prototype.split`.
+ * @param removeEmpty - When `true`, drops segments that are empty after trimming. Defaults to `false`.
+ * @returns An array of trimmed string segments.
+ *
+ * @example
+ * splitTrim(' foo , bar , baz ', ',')
+ * // => ['foo', 'bar', 'baz']
+ *
+ * @example
+ * splitTrim('foo,,bar', ',', true)
+ * // => ['foo', 'bar']
+ *
+ * @example
+ * splitTrim('foo bar,baz', [' ', ','])
+ * // => ['foo', 'bar', 'baz']
+ */
+export const splitTrim = (toSplit, splitter, removeEmpty = false) => {
+    const splitters = Array.isArray(splitter) ? splitter : [splitter];
+    let returned = [toSplit];
+    for (const s of splitters) {
+        returned = returned.flatMap(e => e.split(s));
+    }
+    return returned
+        .map(e => e.trim())
+        .filter(e => !removeEmpty || e !== '');
+};

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

@@ -0,0 +1,153 @@
+import { type FunctionComponent, type PropsWithChildren, type VideoHTMLAttributes, type ReactEventHandler } from 'react';
+import { type WithClassName } from '../utils/types.js';
+import { type Props as SubsProps } from '../Subtitles/index.js';
+/**
+ * Describes a single video source.
+ *
+ * @property src - URL of the video file.
+ * @property type - MIME type of the source (e.g. `'video/mp4'`).
+ */
+type SourceData = {
+    src?: string;
+    type?: string;
+};
+/**
+ * Describes a single text track (subtitles, captions, chapters, etc.).
+ *
+ * @property src - URL of the track file.
+ * @property kind - Track type, maps directly to the `<track>` `kind` attribute.
+ * @property srclang - Language of the track content (e.g. `'fr'`, `'en'`).
+ * @property label - Human-readable label shown in the browser's track selector.
+ * @property default - When `true`, marks this track as the default selection.
+ */
+type TrackData = {
+    src?: string;
+    kind?: 'subtitles' | 'captions' | 'descriptions' | 'chapters' | 'metadata';
+    srclang?: string;
+    label?: string;
+    default?: boolean;
+};
+/**
+ * Callbacks for user actions on the video player controls.
+ * Allows you to intercept user actions on the player's buttons and sliders.
+ *
+ * @property playButtonClick - Called when the play button is clicked. Receives the event, isPlaying state and HTMLVideoElement before any change happens. If the time is not controlled by parent (no currentTime given as props), the component will play to the target time right after.
+ * @property pauseButtonClick - Called when the pause button is clicked. Receives the event, isPlaying state and HTMLVideoElement before any change happens. If the time is not controlled by parent (no currentTime given as props), the component will pause to the target time right after.
+ * @property loudButtonClick - Called when the "loud" (unmute) button is clicked. Receives the event, isLoud state and HTMLVideoElement before any change happens.
+ * @property muteButtonClick - Called when the mute button is clicked. Receives the event, isLoud state and HTMLVideoElement before any change happens.
+ * @property volumeRangeChange - Called when the volume slider is changed. Receives the event, target volume (0 to 1), current volume (0 to 1) and HTMLVideoElement before any change happens.
+ * @property fullscreenButtonClick - Called when the fullscreen button is clicked. Receives the event, isFullscreen state and HTMLVideoElement before any change happens.
+ * @property rateRangeChange - Called when the playback rate slider is changed. Receives the event, target rate, current rate and HTMLVideoElement before any change happens.
+ * @property timelineClick - Called when the timeline is clicked. Receives the event, target time (in seconds), current time (in seconds) and HTMLVideoElement before any change happens. If the time is not controlled by parent (no currentTime given as props), the component will update the video current time to the target time right after.
+ */
+export type ActionHandlersProps = {
+    playButtonClick?: (e: React.MouseEvent<HTMLButtonElement>, isPlaying: boolean, video: HTMLVideoElement | null) => void;
+    pauseButtonClick?: (e: React.MouseEvent<HTMLButtonElement>, isPlaying: boolean, video: HTMLVideoElement | null) => void;
+    loudButtonClick?: (e: React.MouseEvent<HTMLButtonElement>, isLoud: boolean, video: HTMLVideoElement | null) => void;
+    muteButtonClick?: (e: React.MouseEvent<HTMLButtonElement>, isLoud: boolean, video: HTMLVideoElement | null) => void;
+    volumeRangeChange?: (e: React.ChangeEvent<HTMLInputElement>, targetVolumePercent: number, currentVolumePercent: number, video: HTMLVideoElement | null) => void;
+    fullscreenButtonClick?: (e: React.MouseEvent<HTMLButtonElement>, isFullscreen: boolean, video: HTMLVideoElement | null) => void;
+    rateRangeChange?: (e: React.ChangeEvent<HTMLInputElement>, targetRate: number, rate: number, video: HTMLVideoElement | null) => void;
+    timelineClick?: (e: React.MouseEvent<HTMLDivElement>, time: number, currentTime: number, video: HTMLVideoElement | null) => void;
+};
+/**
+ * Callbacks to synchronize the internal player state with the outside.
+ *
+ * @property isPlaying - Called whenever the play/pause state changes.
+ * @property isFullscreen - Called whenever the fullscreen state changes.
+ * @property isLoud - Called whenever the mute/unmute state changes (true = unmuted, false = muted).
+ * @property volume - Called whenever the volume changes (value between 0 and 1).
+ * @property playbackRate - Called whenever the playback speed changes.
+ * @property currentTime - Called on every change of the current time (in seconds).
+ */
+export type StateHandlersProps = {
+    isPlaying?: (isPlaying: boolean) => void;
+    isFullscreen?: (isFullscreen: boolean) => void;
+    isLoud?: (isLoud: boolean) => void;
+    volume?: (volume: number) => void;
+    playbackRate?: (rate: number) => void;
+    currentTime?: (currentTime: number) => void;
+};
+/**
+ * Props for the ControlledVideo component.
+ *
+ * @property sources - List of video sources (string, array of strings, or SourceData objects).
+ * @property tracks - List of tracks (subtitles, captions, etc.), string, array of strings, or TrackData objects.
+ * @property subtitles - Props for the Subtitles component.
+ * @property playBtnContent - React content for the play button.
+ * @property pauseBtnContent - React content for the pause button.
+ * @property loudBtnContent - React content for the "loud" (unmute) button.
+ * @property muteBtnContent - React content for the mute button.
+ * @property fullscreenBtnContent - React content for the fullscreen button.
+ * @property play - External control of play state (true = play, false = pause).
+ * @property fullscreen - External control of fullscreen mode.
+ * @property volume - External control of volume (0 to 1).
+ * @property mute - External control of mute (true = muted).
+ * @property playbackRate - External control of playback speed.
+ * @property currentTimeMs - External control of current time (in ms). If given, the component considers the current time to be controlled by the parent, and will not attempt to update it internally on user interactions (play, timeline click, etc.), leaving it up to the parent to update this prop accordingly.
+ * @property actionHandlers - Callbacks for user actions on the controls.
+ * @property stateHandlers - Callbacks to synchronize internal state with the outside.
+ * @property onFullscreenChange - Callback for native fullscreen mode changes.
+ * @property _modifiers - Optional CSS modifiers for the root element.
+ * @property className - Additional CSS class for the root element.
+ * @property children - React content inserted into the <video> tag (fallback, etc).
+ *
+ * Also inherits all standard HTML props for a <video> element.
+ */
+export type Props = PropsWithChildren<WithClassName<{
+    sources?: string | string[] | SourceData[];
+    tracks?: string | string[] | TrackData[];
+    subtitles?: SubsProps;
+    playBtnContent?: React.ReactNode;
+    pauseBtnContent?: React.ReactNode;
+    loudBtnContent?: React.ReactNode;
+    muteBtnContent?: React.ReactNode;
+    fullscreenBtnContent?: React.ReactNode;
+    play?: boolean;
+    fullscreen?: boolean;
+    volume?: number;
+    mute?: boolean;
+    playbackRate?: number;
+    currentTimeMs?: number;
+    onFullscreenChange?: ReactEventHandler<HTMLVideoElement>;
+    actionHandlers?: ActionHandlersProps;
+    stateHandlers?: StateHandlersProps;
+    _modifiers?: Record<string, boolean>;
+}> & VideoHTMLAttributes<HTMLVideoElement>>;
+/**
+ * Full-featured video player component. Wraps a native `<video>` element with
+ * playback controls, volume, playback rate, a timeline, optional subtitles
+ * and viewport-driven auto-play/mute behaviours.
+ *
+ * ### Root element modifiers
+ * The root `<figure>` receives the public class name defined by `video` and
+ * the following BEM-style modifier classes:
+ * - `--play-on` / `--play-off` — reflects current playback state.
+ * - `--fullscreen-on` / `--fullscreen-off` — reflects fullscreen state.
+ * - `--loud` / `--muted` — reflects mute state.
+ *
+ * ### Data attributes on the root element
+ * - `data-play-on` — present (empty string) when playing.
+ * - `data-play-off` — present (empty string) when paused.
+ * - `data-fullscreen-on` — present (empty string) when in fullscreen.
+ * - `data-fullscreen-off` — present (empty string) when not in fullscreen.
+ * - `data-loud` — present (empty string) when unmuted.
+ * - `data-muted` — present (empty string) when muted.
+ * - `data-volume` — current volume as a `0–1` float.
+ * - `data-volume-percent` — current volume as a `0–100` float.
+ * - `data-playback-rate` — current playback rate (e.g. `1`, `1.5`).
+ * - `data-current-time-ms` — current time in milliseconds, fixed to 2 decimals.
+ * - `data-current-time-ratio` — current / total ratio, fixed to 8 decimals.
+ * - `data-total-time-ms` — total duration in milliseconds.
+ *
+ * ### CSS custom properties on the root element
+ * - `--video-current-time-ratio` — current / total ratio, fixed to 8 decimals.
+ * Useful for driving progress-bar animations purely in CSS.
+ *
+ * @param props - Component properties.
+ * @see {@link Props}
+ * @returns A `<figure>` element containing the video, its controls, optional
+ * subtitles.
+ */
+export declare const ControlledVideo: FunctionComponent<Props>;
+export {};

package/components/Video/index.controlled.js

@@ -0,0 +1,255 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useMemo, useRef, useState, useCallback, useEffect } from 'react';
+import { clss } from '../../agnostic/css/clss/index.js';
+import { mergeClassNames } from '../utils/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, formatTime, getTimelineClickProgress, msToSeconds, secondsToMs } from './utils.js';
+/**
+ * Full-featured video player component. Wraps a native `<video>` element with
+ * playback controls, volume, playback rate, a timeline, optional subtitles
+ * and viewport-driven auto-play/mute behaviours.
+ *
+ * ### Root element modifiers
+ * The root `<figure>` receives the public class name defined by `video` and
+ * the following BEM-style modifier classes:
+ * - `--play-on` / `--play-off` — reflects current playback state.
+ * - `--fullscreen-on` / `--fullscreen-off` — reflects fullscreen state.
+ * - `--loud` / `--muted` — reflects mute state.
+ *
+ * ### Data attributes on the root element
+ * - `data-play-on` — present (empty string) when playing.
+ * - `data-play-off` — present (empty string) when paused.
+ * - `data-fullscreen-on` — present (empty string) when in fullscreen.
+ * - `data-fullscreen-off` — present (empty string) when not in fullscreen.
+ * - `data-loud` — present (empty string) when unmuted.
+ * - `data-muted` — present (empty string) when muted.
+ * - `data-volume` — current volume as a `0–1` float.
+ * - `data-volume-percent` — current volume as a `0–100` float.
+ * - `data-playback-rate` — current playback rate (e.g. `1`, `1.5`).
+ * - `data-current-time-ms` — current time in milliseconds, fixed to 2 decimals.
+ * - `data-current-time-ratio` — current / total ratio, fixed to 8 decimals.
+ * - `data-total-time-ms` — total duration in milliseconds.
+ *
+ * ### CSS custom properties on the root element
+ * - `--video-current-time-ratio` — current / total ratio, fixed to 8 decimals.
+ * Useful for driving progress-bar animations purely in CSS.
+ *
+ * @param props - Component properties.
+ * @see {@link Props}
+ * @returns A `<figure>` element containing the video, its controls, optional
+ * subtitles.
+ */
+export const ControlledVideo = ({ sources, tracks, subtitles, playBtnContent, pauseBtnContent, loudBtnContent, muteBtnContent, fullscreenBtnContent, play, fullscreen, mute, muted, volume = 1, playbackRate = 1, currentTimeMs: givenCurrentTimeMs, actionHandlers, stateHandlers, children, className, _modifiers, ...intrinsicVideoAttributes }) => {
+    const videoRef = useRef(null);
+    const [totalTime, setTotalTime] = useState(0);
+    const totalTimeMs = useMemo(() => secondsToMs(totalTime), [totalTime]);
+    const [currentTimeMs, setCurrentTimeMs] = useState(0);
+    const currentTime = useMemo(() => msToSeconds(currentTimeMs), [currentTimeMs]);
+    const isTimeControlled = useMemo(() => givenCurrentTimeMs !== undefined, [givenCurrentTimeMs]);
+    const volumePercent = useMemo(() => volume * 100, [volume]);
+    // Intrinsic event handler
+    const handleMetadataLoadEvent = useCallback((e) => {
+        if (videoRef.current === null)
+            return;
+        const video = videoRef.current;
+        setTotalTime(Number(video.duration));
+        intrinsicVideoAttributes.onLoadedMetadata?.(e);
+    }, [intrinsicVideoAttributes.onLoadedMetadata]);
+    const handleOnTimeUpdateEvent = useCallback((e) => {
+        const video = e.currentTarget;
+        const newTimeMs = secondsToMs(Number(video.currentTime));
+        setCurrentTimeMs(newTimeMs);
+        if (intrinsicVideoAttributes?.onTimeUpdate !== undefined) {
+            intrinsicVideoAttributes.onTimeUpdate(e);
+        }
+    }, [intrinsicVideoAttributes.onTimeUpdate]);
+    const handleOnPlayEvent = useCallback((e) => {
+        /* We must never play a video that has controlled time */
+        if (isTimeControlled) {
+            videoRef.current?.pause();
+            return;
+        }
+        intrinsicVideoAttributes.onPlay?.(e);
+    }, [isTimeControlled, intrinsicVideoAttributes.onPlay]);
+    // Custom action handlers
+    const handlePlayButtonClick = useCallback((e) => {
+        const isPlaying = videoRef.current !== null ? Boolean(videoRef.current.paused) : false;
+        actionHandlers?.playButtonClick?.(e, isPlaying, videoRef.current);
+    }, [actionHandlers?.playButtonClick]);
+    const handlePauseButtonClick = useCallback((e) => {
+        const isPlaying = videoRef.current !== null ? Boolean(videoRef.current.paused) : false;
+        actionHandlers?.pauseButtonClick?.(e, isPlaying, videoRef.current);
+    }, [actionHandlers?.pauseButtonClick]);
+    const handleLoudButtonClick = useCallback((e) => {
+        const isLoud = mute !== undefined ? !mute : false;
+        actionHandlers?.loudButtonClick?.(e, isLoud, videoRef.current);
+    }, [actionHandlers?.loudButtonClick, mute]);
+    const handleMuteButtonClick = useCallback((e) => {
+        const isLoud = mute !== undefined ? !mute : false;
+        actionHandlers?.muteButtonClick?.(e, isLoud, videoRef.current);
+    }, [actionHandlers?.muteButtonClick, mute]);
+    const handleFullscreenButtonClick = useCallback((e) => {
+        actionHandlers?.fullscreenButtonClick?.(e, fullscreen ?? false, videoRef.current);
+    }, [actionHandlers?.fullscreenButtonClick, fullscreen]);
+    const handleVolumeRangeChange = useCallback((e) => {
+        const targetVolume = Number(e.currentTarget.value) / 100;
+        actionHandlers?.volumeRangeChange?.(e, targetVolume, volume, videoRef.current);
+    }, [actionHandlers?.volumeRangeChange, volume]);
+    const handleRateRangeChange = useCallback((e) => {
+        actionHandlers?.rateRangeChange?.(e, Number(e.currentTarget.value), playbackRate, videoRef.current);
+    }, [actionHandlers?.rateRangeChange, playbackRate]);
+    const handleTimelineClick = useCallback((e) => {
+        if (videoRef.current === null)
+            return;
+        const progress = getTimelineClickProgress(e, e.currentTarget, videoRef.current);
+        const targetTime = progress * totalTime;
+        actionHandlers?.timelineClick?.(e, targetTime, currentTime, videoRef.current);
+        /* If we are given a currentTimeMs prop, we consider that the current time is controlled by the parent component, and we should not attempt to set it here on timeline click, as it would create conflicts. The parent comp should update the currentTimeMs prop itself */
+        if (!isTimeControlled) {
+            videoRef.current.currentTime = targetTime;
+        }
+    }, [actionHandlers?.timelineClick, totalTime, currentTime, isTimeControlled]);
+    // Rendering
+    const isPlaying = play ?? false;
+    const isLoud = mute ?? false;
+    const isFullscreen = fullscreen ?? false;
+    const c = clss(publicClassName, { cssModule });
+    const rootClss = mergeClassNames(c(null, {
+        'play-on': isPlaying,
+        'play-off': !isPlaying,
+        'fullscreen-on': isFullscreen,
+        'fullscreen-off': !isFullscreen,
+        'loud': isLoud,
+        'muted': !isLoud,
+        ..._modifiers
+    }), className);
+    const appliedVolume = volume ?? 0;
+    const rootAttributes = {
+        'data-play-on': isPlaying ? '' : undefined,
+        'data-play-off': !isPlaying ? '' : undefined,
+        'data-fullscreen-on': isFullscreen ? '' : undefined,
+        'data-fullscreen-off': !isFullscreen ? '' : undefined,
+        'data-loud': isLoud ? '' : undefined,
+        'data-muted': !isLoud ? '' : undefined,
+        'data-volume': appliedVolume.toFixed(8),
+        'data-volume-percent': volumePercent,
+        'data-playback-rate': playbackRate,
+        'data-current-time-ms': currentTimeMs.toFixed(2),
+        'data-current-time-ratio': (currentTime / totalTime).toFixed(8),
+        'data-total-time-ms': totalTimeMs
+    };
+    const rootStyles = {
+        [`--${publicClassName}-current-time-ratio`]: (currentTime / totalTime).toFixed(8)
+    };
+    const parsedSources = useMemo(() => {
+        if (sources === undefined)
+            return [];
+        if (typeof sources === 'string')
+            return [{ src: sources }];
+        if (Array.isArray(sources)) {
+            if (sources.length === 0)
+                return [];
+            if (typeof sources[0] === 'string')
+                return sources.map(src => ({ src }));
+            return sources;
+        }
+        return [];
+    }, [sources]);
+    const parsedTracks = useMemo(() => {
+        if (tracks === undefined)
+            return [];
+        if (typeof tracks === 'string')
+            return [{ src: tracks }];
+        if (Array.isArray(tracks)) {
+            if (tracks.length === 0)
+                return [];
+            if (typeof tracks[0] === 'string')
+                return tracks.map(src => ({ src }));
+            return tracks;
+        }
+        return [];
+    }, [tracks]);
+    const videoClss = c('video');
+    const videoControlsClss = c('video-controls');
+    const playBtnClss = c('play-btn');
+    const pauseBtnClss = c('pause-btn');
+    const loudBtnClss = c('loud-btn');
+    const muteBtnClss = c('mute-btn');
+    const volumePcntClss = c('volume-percent');
+    const fullscreenBtnClss = c('fullscreen-btn');
+    const volumeRangeClss = c('volume-range');
+    const playbackRateRangeClss = c('playback-rate-range');
+    const playbackRateClss = c('playback-rate');
+    const timeControlsClss = c('time-controls');
+    const currentTimeClss = c('current-time');
+    const totalTimeClss = c('total-time');
+    const timelineClss = c('timeline');
+    useEffect(() => {
+        forcePlaybackRate(videoRef.current, playbackRate);
+    }, [playbackRate]);
+    useEffect(() => {
+        if (fullscreen === true) {
+            void forceFullscreen(videoRef.current);
+        }
+        return () => {
+            void forceExitFullscreen(videoRef.current);
+        };
+    }, [fullscreen]);
+    useEffect(() => {
+        if (isTimeControlled)
+            return;
+        if (play === true) {
+            void forcePlay(videoRef.current);
+        }
+        else {
+            void forcePause(videoRef.current);
+        }
+    }, [play, isTimeControlled]);
+    useEffect(() => {
+        if (volume !== undefined) {
+            forceVolume(videoRef.current, volume);
+        }
+    }, [volume]);
+    useEffect(() => {
+        if (givenCurrentTimeMs !== undefined && videoRef.current !== null) {
+            void forcePause(videoRef.current);
+            videoRef.current.currentTime = msToSeconds(givenCurrentTimeMs);
+        }
+    }, [givenCurrentTimeMs]);
+    useEffect(() => {
+        if (mute === true) {
+            forceMute(videoRef.current);
+        }
+        else {
+            forceLoud(videoRef.current);
+        }
+    }, [mute]);
+    // State handlers
+    useEffect(() => {
+        if (stateHandlers?.currentTime !== undefined) {
+            stateHandlers.currentTime(msToSeconds(currentTimeMs));
+        }
+    }, [currentTimeMs, stateHandlers?.currentTime]);
+    useEffect(() => {
+        stateHandlers?.isPlaying?.(isPlaying);
+    }, [isPlaying, stateHandlers?.isPlaying]);
+    useEffect(() => {
+        stateHandlers?.isFullscreen?.(isFullscreen);
+    }, [isFullscreen, stateHandlers?.isFullscreen]);
+    useEffect(() => {
+        stateHandlers?.isLoud?.(isLoud);
+    }, [isLoud, stateHandlers?.isLoud]);
+    useEffect(() => {
+        stateHandlers?.volume?.(volume);
+    }, [volume, stateHandlers?.volume]);
+    useEffect(() => {
+        stateHandlers?.playbackRate?.(playbackRate);
+    }, [playbackRate, stateHandlers?.playbackRate]);
+    return _jsxs("figure", { className: rootClss, style: rootStyles, ...rootAttributes, children: [_jsxs("video", { ref: videoRef, className: videoClss, ...intrinsicVideoAttributes, onLoadedMetadata: handleMetadataLoadEvent, onPlay: handleOnPlayEvent, onTimeUpdate: handleOnTimeUpdateEvent, children: [parsedSources.map((source, index) => typeof source === 'string'
+                        ? _jsx("source", { src: source }, index)
+                        : _jsx("source", { src: source.src, type: source.type }, index)), parsedTracks.map((track, index) => typeof track === 'string'
+                        ? _jsx("track", { src: track }, index)
+                        : _jsx("track", { src: track.src, kind: track.kind, srcLang: track.srclang, label: track.label, default: track.default }, index)), children] }), _jsxs("div", { className: videoControlsClss, children: [_jsx("button", { className: playBtnClss, onClick: handlePlayButtonClick, children: playBtnContent }), _jsx("button", { className: pauseBtnClss, onClick: handlePauseButtonClick, children: pauseBtnContent }), _jsx("button", { className: loudBtnClss, onClick: handleLoudButtonClick, children: loudBtnContent }), _jsx("button", { className: muteBtnClss, onClick: handleMuteButtonClick, children: muteBtnContent }), _jsx("input", { type: "range", className: volumeRangeClss, value: volumePercent, onChange: handleVolumeRangeChange, min: 0, max: 100, step: 1 }), _jsx("span", { className: volumePcntClss, children: Math.round(volumePercent) }), _jsx("button", { className: fullscreenBtnClss, onClick: handleFullscreenButtonClick, children: fullscreenBtnContent }), _jsx("input", { type: "range", className: playbackRateRangeClss, value: playbackRate, onChange: handleRateRangeChange, min: 0.25, max: 4, step: 0.25 }), _jsx("span", { className: playbackRateClss, children: playbackRate })] }), _jsxs("div", { className: timeControlsClss, children: [_jsx("span", { className: currentTimeClss, children: formatTime(currentTimeMs, 'mm:ss:ms') }), _jsx("span", { className: totalTimeClss, children: formatTime(totalTimeMs, 'mm:ss:ms') }), _jsx("div", { className: timelineClss, onClick: handleTimelineClick })] }), subtitles !== undefined && _jsx(Subtitles, { ...subtitles, timecodeMs: currentTimeMs })] });
+};

package/components/Video/index.d.ts

@@ -1,83 +1,10 @@
-import { type FunctionComponent, type PropsWithChildren, type VideoHTMLAttributes } from 'react';
+import { type FunctionComponent } from 'react';
 import { type Props as DisclaimerProps } from '../Disclaimer/index.js';
-import { type Props as SubsProps } from '../Subtitles/index.js';
-import type { WithClassName } from '../utils/types.js';
-/**
- * Describes a single video source.
- *
- * @property src - URL of the video file.
- * @property type - MIME type of the source (e.g. `'video/mp4'`).
- */
-type SourceData = {
-    src?: string;
-    type?: string;
-};
-/**
- * Describes a single text track (subtitles, captions, chapters, etc.).
- *
- * @property src - URL of the track file.
- * @property kind - Track type, maps directly to the `<track>` `kind` attribute.
- * @property srclang - Language of the track content (e.g. `'fr'`, `'en'`).
- * @property label - Human-readable label shown in the browser's track selector.
- * @property default - When `true`, marks this track as the default selection.
- */
-type TrackData = {
-    src?: string;
-    kind?: 'subtitles' | 'captions' | 'descriptions' | 'chapters' | 'metadata';
-    srclang?: string;
-    label?: string;
-    default?: boolean;
-};
-type ActionHandlersProps = {
-    playButtonClick?: (e: React.MouseEvent<HTMLButtonElement>, isPlaying: boolean, video: HTMLVideoElement | null) => void;
-    pauseButtonClick?: (e: React.MouseEvent<HTMLButtonElement>, isPlaying: boolean, video: HTMLVideoElement | null) => void;
-    loudButtonClick?: (e: React.MouseEvent<HTMLButtonElement>, isLoud: boolean, video: HTMLVideoElement | null) => void;
-    muteButtonClick?: (e: React.MouseEvent<HTMLButtonElement>, isLoud: boolean, video: HTMLVideoElement | null) => void;
-    volumeRangeChange?: (e: React.ChangeEvent<HTMLInputElement>, targetRangeVolume: number, volume: number, video: HTMLVideoElement | null) => void;
-    fullscreenButtonClick?: (e: React.MouseEvent<HTMLButtonElement>, isFullscreen: boolean, video: HTMLVideoElement | null) => void;
-    rateRangeChange?: (e: React.ChangeEvent<HTMLInputElement>, targetRangeRate: number, rate: number, video: HTMLVideoElement | null) => void;
-    timelineClick?: (e: React.MouseEvent<HTMLDivElement>, targetTimeSec: number, timeSec: number, video: HTMLVideoElement | null) => void;
-};
-type StateHandlersProps = {
-    isPlaying?: (isPlaying: boolean) => void;
-    isFullScreen?: (isFullScreen: boolean) => void;
-    isLoud?: (isLoud: boolean) => void;
-    volume?: (volume: number) => void;
-    currentTime?: (currentTime: number) => void;
-    playbackRate?: (rate: number) => void;
-};
-/**
- * - play?: boolean
- * - mute?: boolean
- * - fullScreen?: boolean
- * - volume?: number
- * - playbackRate?: number
- * - currentTimeMs:? number
- * - PLUS TARD =
- * - onPlay, onLoud, etc...
- */
+import { type Props as ControlledProps } from './index.controlled.js';
 /**
  * Props for the {@link Video} component.
  *
- * Extends all native `VideoHTMLAttributes<HTMLVideoElement>`, so any standard
- * video attribute (`autoPlay`, `muted`, `loop`, `poster`, etc.) can be passed
- * and will be forwarded to the underlying `<video>` element.
- *
- * @property sources - One or more video sources. Accepts:
- * - a single URL string,
- * - an array of URL strings,
- * - an array of {@link SourceData} objects for fine-grained `type` control.
- * @property tracks - One or more text tracks. Accepts:
- * - a single URL string,
- * - an array of URL strings,
- * - an array of {@link TrackData} objects.
- * @property playBtnContent - Custom content for the play button.
- * @property pauseBtnContent - Custom content for the pause button.
- * @property loudBtnContent - Custom content for the unmute button.
- * @property muteBtnContent - Custom content for the mute button.
- * @property fullScreenBtnContent - Custom content for the fullScreen button.
- * @property subtitles - Props forwarded to the internal {@link Subtitles} component.
- * `timecodeMs` is injected automatically from the current playback position.
+ * Extends all ControlledVideo props except play, mute, fullscreen, volume, playbackRate, and their associated event handlers
  * @property disclaimer - Props forwarded to the internal {@link Disclaimer} component.
  * While the disclaimer is active, `autoPlay` and `muted` are suppressed on the
  * underlying `<video>` element.
@@ -89,61 +16,30 @@ type StateHandlersProps = {
  * component intersects the viewport, provided no disclaimer is active.
  * @property autoMuteWhenHidden - When `true`, mutes the video whenever the component
  * leaves the viewport.
+ * @property currentTimeMs - When provided, forces the video's current time to the given value (in milliseconds). Giving the currentTimeMs prop puts the component in a controlled state for the current time, meaning that the parent component is responsible for updating the current time. In this mode, user interactions that would normally change the current time (play, pause, timeline click) will not have an effect unless the parent component updates the currentTimeMs prop accordingly.
+ * @property wrapperClassName - Optional additional class name(s) applied to the root wrapper element.
+ * @property stateHandlers - Optional callbacks invoked whenever the corresponding
+ * state changes. Useful for synchronizing external state with the internal video state.
  * @property className - Optional additional class name(s) applied to the root element.
  * @property children - React children rendered inside the `<video>` element itself
  * (e.g. fallback content).
  */
-export type Props = PropsWithChildren<WithClassName<{
-    sources?: string | string[] | SourceData[];
-    tracks?: string | string[] | TrackData[];
-    playBtnContent?: React.ReactNode;
-    pauseBtnContent?: React.ReactNode;
-    loudBtnContent?: React.ReactNode;
-    muteBtnContent?: React.ReactNode;
-    fullScreenBtnContent?: React.ReactNode;
-    subtitles?: SubsProps;
+export type Props = Omit<ControlledProps, 'play' | 'fullscreen' | 'volume' | 'mute' | 'playbackRate'> & {
     disclaimer?: DisclaimerProps;
     autoPlayWhenVisible?: boolean;
     autoPauseWhenHidden?: boolean;
     autoLoudWhenVisible?: boolean;
     autoMuteWhenHidden?: boolean;
-    actionHandlers: ActionHandlersProps;
-    stateHandlers: StateHandlersProps;
-}> & VideoHTMLAttributes<HTMLVideoElement>>;
+    wrapperClassName?: string;
+};
 /**
  * Full-featured video player component. Wraps a native `<video>` element with
  * playback controls, volume, playback rate, a timeline, optional subtitles,
  * an optional disclaimer gate, and viewport-driven auto-play/mute behaviours.
  *
- * ### Root element modifiers
- * The root `<figure>` receives the public class name defined by `video` and
- * the following BEM-style modifier classes:
- * - `--play-on` / `--play-off` — reflects current playback state.
- * - `--fullscreen-on` / `--fullscreen-off` — reflects fullscreen state.
- * - `--loud` / `--muted` — reflects mute state.
- *
- * ### Data attributes on the root element
- * - `data-play-on` — present (empty string) when playing.
- * - `data-play-off` — present (empty string) when paused.
- * - `data-fullscreen-on` — present (empty string) when in fullScreen.
- * - `data-fullscreen-off` — present (empty string) when not in fullScreen.
- * - `data-loud` — present (empty string) when unmuted.
- * - `data-muted` — present (empty string) when muted.
- * - `data-volume` — current volume as a `0–1` float.
- * - `data-volume-percent` — current volume as a `0–100` float.
- * - `data-playback-rate` — current playback rate (e.g. `1`, `1.5`).
- * - `data-current-time-ms` — current time in milliseconds, fixed to 2 decimals.
- * - `data-current-time-ratio` — current / total ratio, fixed to 8 decimals.
- * - `data-total-time-ms` — total duration in milliseconds.
- *
- * ### CSS custom properties on the root element
- * - `--video-current-time-ratio` — current / total ratio, fixed to 8 decimals.
- * Useful for driving progress-bar animations purely in CSS.
- *
  * @param props - Component properties.
  * @see {@link Props}
  * @returns A `<figure>` element containing the video, its controls, optional
  * subtitles, and an optional disclaimer overlay.
  */
 export declare const Video: FunctionComponent<Props>;
-export {};