@design-edito/tools 0.4.6 → 0.4.12

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 {};