@design-edito/tools 0.5.2 → 0.5.4

package/components/Theatre/index.js

@@ -1,90 +1,78 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { useEffect, useState, useRef } from 'react';
 import { clss } from '../../agnostic/css/clss/index.js';
-import { mergeClassNames } from '../utils/index.js';
+import { mergeClassNames, useChangeDispatch } from '../utils/index.js';
 import { theatre as publicClassName } from '../public-classnames.js';
 import cssModule from './styles.module.css';
 /**
  * Theatre mode component. Wraps content in a toggleable fullscreen-like "stage"
- * overlay. Supports both controlled and uncontrolled usage.
+ * overlay.
  *
- * When `isOn` is not provided the component manages its own open/closed state
- * internally. When `isOn` is provided it acts as the source of truth and the
- * internal state is ignored.
+ * ### CSS modifiers
+ * - `on` — theatre mode is active.
+ * - `off` — theatre mode is inactive.
  *
- * ### Root element modifiers
- * The root `<div>` receives the public class name defined by `theatre` and the
- * following BEM-style modifier classes:
- * - `--on` — when theatre mode is active.
- * - `--off` — when theatre mode is inactive.
- *
- * ### Child elements
- * - `__stage` — container rendered inside the root that holds the duplicated
- * `children` when theatre mode is active. Only mounted when `isOn` is `true`.
- * - `__open-btn` — clickable element that activates theatre mode.
- * - `__close-btn` — clickable element that deactivates theatre mode.
+ * ### CSS elements
+ * - `stage` — holds the duplicated `children`, mounted only when `isOn`.
+ * - `open-btn`
+ * - `close-btn`
  *
  * @param props - Component properties.
  * @see {@link Props}
  * @returns A root `<div>` containing the children in their original position,
- * a stage overlay with the duplicated children (when active), and the open/close
- * toggle buttons.
+ * a stage overlay with the duplicated children when active, and both toggles.
+ *
+ * @remarks
+ * - In controlled mode (`isOn` defined), the state is fully driven by the
+ *   parent and internal state is never updated.
+ * - `onToggleClicked` fires in both modes, for all four toggle sources — a
+ *   controlled parent needs it to know a toggle was requested at all.
+ * - `onIsOnChanged` fires in both modes too, and never on mount.
  */
-export const Theatre = ({ closeBtnContent, openBtnContent, isOn, defaultIsOn, exitOnEscape, exitOnBgClick, stateHandlers, actionHandlers, children, className }) => {
+export const Theatre = ({ closeBtnContent, openBtnContent, isOn: isOnProp, defaultIsOn = false, exitOnEscape, exitOnBgClick, onToggleClicked, onIsOnChanged, children, className }) => {
     // State & refs
-    const [internalIsOn, setInternalIsOn] = useState(defaultIsOn ?? false);
+    const [internalIsOn, setInternalIsOn] = useState(defaultIsOn);
     const stageRef = useRef(null);
-    const isTheatreOn = isOn ?? internalIsOn;
-    const prevIsTheatreOnRef = useRef(isTheatreOn);
-    // Handlers
-    const handleCloseBtnClick = () => {
-        actionHandlers?.toggleClick?.(isTheatreOn);
-        if (isOn === undefined)
-            setInternalIsOn(false);
-    };
-    const handleOpenBtnClick = () => {
-        actionHandlers?.toggleClick?.(isTheatreOn);
-        if (isOn === undefined)
-            setInternalIsOn(true);
+    const isControlled = isOnProp !== undefined;
+    const isOn = isOnProp ?? internalIsOn;
+    // State dispatch
+    useChangeDispatch(isOn, onIsOnChanged);
+    // User action handlers
+    const requestToggle = (targetIsOn) => {
+        onToggleClicked?.(isOn);
+        if (isControlled)
+            return;
+        setInternalIsOn(targetIsOn);
     };
+    const handleOpenBtnClick = () => requestToggle(true);
+    const handleCloseBtnClick = () => requestToggle(false);
     const handleStageBgClick = e => {
         if (exitOnBgClick !== true)
             return;
         if (e.target !== stageRef.current)
             return;
-        actionHandlers?.toggleClick?.(isTheatreOn);
-        if (isOn === undefined)
-            setInternalIsOn(false);
+        requestToggle(false);
     };
-    // Effects
-    useEffect(() => {
-        if (prevIsTheatreOnRef.current !== isTheatreOn) {
-            stateHandlers?.toggled?.(isTheatreOn);
-            prevIsTheatreOnRef.current = isTheatreOn;
-        }
-    }, [isTheatreOn, stateHandlers]);
+    // Fx. dep. `exitOnEscape`, `isOn` - close the stage on the Escape key
     useEffect(() => {
-        if (exitOnEscape === true
-            || !isTheatreOn
-            || isOn !== undefined)
+        if (exitOnEscape !== true || !isOn)
             return;
-        const listener = (e) => {
+        const handleKeyDown = (e) => {
             if (e.key !== 'Escape')
                 return;
-            actionHandlers?.toggleClick?.(isTheatreOn);
-            setInternalIsOn(false);
+            requestToggle(false);
         };
-        window.addEventListener('keydown', listener);
-        return () => window.removeEventListener('keydown', listener);
-    }, [exitOnEscape, isTheatreOn, isOn]);
-    // Render
+        window.addEventListener('keydown', handleKeyDown);
+        return () => window.removeEventListener('keydown', handleKeyDown);
+    }, [exitOnEscape, isOn, isControlled]);
+    // Rendering
     const c = clss(publicClassName, { cssModule });
     const rootClss = mergeClassNames(c(null, {
-        'on': isTheatreOn,
-        'off': !isTheatreOn
+        'on': isOn,
+        'off': !isOn
     }), className);
-    const stageClass = c('stage');
-    const openBtnClass = c('open-btn');
-    const closeBtnClass = c('close-btn');
-    return _jsxs("div", { className: rootClss, children: [children, _jsx("div", { className: stageClass, onClick: handleStageBgClick, ref: stageRef, children: isTheatreOn && children }), _jsx("div", { className: closeBtnClass, onClick: handleCloseBtnClick, children: closeBtnContent }), _jsx("div", { className: openBtnClass, onClick: handleOpenBtnClick, children: openBtnContent })] });
+    const stageClss = c('stage');
+    const openBtnClss = c('open-btn');
+    const closeBtnClss = c('close-btn');
+    return _jsxs("div", { className: rootClss, children: [children, _jsx("div", { className: stageClss, onClick: handleStageBgClick, ref: stageRef, children: isOn && children }), _jsx("div", { className: closeBtnClss, onClick: handleCloseBtnClick, children: closeBtnContent }), _jsx("div", { className: openBtnClss, onClick: handleOpenBtnClick, children: openBtnContent })] });
 };

package/components/UIModule/index.d.ts

@@ -31,49 +31,45 @@ type ModuleData = {
  * component stays in the `--no-module` state.
  * @property props - Arbitrary key-value object forwarded verbatim to the
  * module's `init` call and, on subsequent changes, to `update` (if exported).
- * @property stateHandlers - Optional callbacks invoked whenever internal state changes:
- * - `idChanged` — called with the stable instance ID once on mount.
- * - `isLoadingChanged` — called with the new loading state on every transition.
- * - `loadedModuleChanged` — called with the new module value (`ModuleData`, `Error`, or `null`)
- * after each load attempt or teardown.
- * - `moduleTargetChanged` — called with the `Element` returned by `init`, or `null`
- * when the module is unloaded or errored.
+ * @property onIdGenerated - Called once on mount with the instance's generated
+ * `id`. The id never changes afterwards, so this fires exactly once.
+ * @property onIsLoadingChanged - Called after the loading state changed, with
+ * the new value.
+ * @property onLoadedModuleChanged - Called after the loaded module changed, with
+ * the new value: the validated {@link ModuleData}, an `Error`, or `null`.
+ * @property onModuleTargetChanged - Called after the hosted element changed,
+ * with the `Element` returned by `init`, or `null` once unloaded or errored.
  * @property className - Optional additional class name(s) applied to the root element.
  */
 export type Props = WithClassName<{
     src?: string;
     props?: Record<string, unknown>;
-    stateHandlers?: {
-        idChanged?: (id: string) => void;
-        isLoadingChanged?: (isLoading: boolean) => void;
-        loadedModuleChanged?: (loadedModule: ModuleData | Error | null) => void;
-        moduleTargetChanged?: (moduleTarget: Element | null) => void;
-    };
+    onIdGenerated?: (id: string) => void;
+    onIsLoadingChanged?: (isLoading: boolean) => void;
+    onLoadedModuleChanged?: (loadedModule: ModuleData | Error | null) => void;
+    onModuleTargetChanged?: (moduleTarget: Element | null) => void;
 }>;
 /**
- * Dynamic UI module host component. Asynchronously imports an ES module by URL,
- * validates its exported interface, calls its `init` lifecycle to obtain a DOM
- * `Element`, and appends that element to its own root `<div>`. Handles loading,
- * error, and teardown states automatically.
+ * Dynamic UI module host. Asynchronously imports an ES module by URL, validates
+ * its exported interface, calls its `init` lifecycle to obtain a DOM `Element`,
+ * and appends that element to its own root `<div>`.
  *
  * The imported module is expected to conform to the {@link ModuleData} interface.
  * Any violation (missing exports, wrong types, `init` not returning an `Element`)
  * transitions the component into the `--error` state and logs to `console.error`.
  *
- * ### Root element modifiers
- * The root `<div>` receives the public class name defined by `uiModule` and
- * the following BEM-style modifier classes reflecting the current load lifecycle:
- * - `--loading` — the module fetch is in progress.
- * - `--no-module` — no module has been loaded yet (`src` is undefined or the
- * effect has not run).
- * - `--error` — the import, validation, or `init` call failed.
- * - `--loaded` — the module passed validation and `init` returned successfully.
- * - `--initialized` — the `Element` returned by `init` has been appended to the
- * host `<div>`.
+ * ### CSS modifiers
+ * Reflecting the current load lifecycle:
+ * - `loading` — the module fetch is in progress.
+ * - `no-module` — nothing has been loaded yet (`src` is undefined, or the
+ *   effect has not run).
+ * - `error` — the import, the validation, or the `init` call failed.
+ * - `loaded` — the module passed validation and `init` returned successfully.
+ * - `initialized` — the `Element` returned by `init` has been appended.
  *
  * ### Root element attributes
- * - `id` — a stable randomly generated ID (prefixed `f`) assigned once on mount.
- * Used to scope the module's `css` entries to this specific instance.
+ * - `id` — a stable generated id, assigned once on mount and used to scope the
+ * module's `css` entries to this specific instance.
  *
  * @param props - Component properties.
  * @see {@link Props}

package/components/UIModule/index.js

@@ -1,36 +1,33 @@
-import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { jsx as _jsx } from "react/jsx-runtime";
 import { useEffect, useRef, useState } from 'react';
 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 } from '../utils/index.js';
+import { mergeClassNames, useChangeDispatch } from '../utils/index.js';
 import { uiModule as publicClassName } from '../public-classnames.js';
 import cssModule from './styles.module.css';
 /**
- * Dynamic UI module host component. Asynchronously imports an ES module by URL,
- * validates its exported interface, calls its `init` lifecycle to obtain a DOM
- * `Element`, and appends that element to its own root `<div>`. Handles loading,
- * error, and teardown states automatically.
+ * Dynamic UI module host. Asynchronously imports an ES module by URL, validates
+ * its exported interface, calls its `init` lifecycle to obtain a DOM `Element`,
+ * and appends that element to its own root `<div>`.
  *
  * The imported module is expected to conform to the {@link ModuleData} interface.
  * Any violation (missing exports, wrong types, `init` not returning an `Element`)
  * transitions the component into the `--error` state and logs to `console.error`.
  *
- * ### Root element modifiers
- * The root `<div>` receives the public class name defined by `uiModule` and
- * the following BEM-style modifier classes reflecting the current load lifecycle:
- * - `--loading` — the module fetch is in progress.
- * - `--no-module` — no module has been loaded yet (`src` is undefined or the
- * effect has not run).
- * - `--error` — the import, validation, or `init` call failed.
- * - `--loaded` — the module passed validation and `init` returned successfully.
- * - `--initialized` — the `Element` returned by `init` has been appended to the
- * host `<div>`.
+ * ### CSS modifiers
+ * Reflecting the current load lifecycle:
+ * - `loading` — the module fetch is in progress.
+ * - `no-module` — nothing has been loaded yet (`src` is undefined, or the
+ *   effect has not run).
+ * - `error` — the import, the validation, or the `init` call failed.
+ * - `loaded` — the module passed validation and `init` returned successfully.
+ * - `initialized` — the `Element` returned by `init` has been appended.
  *
  * ### Root element attributes
- * - `id` — a stable randomly generated ID (prefixed `f`) assigned once on mount.
- * Used to scope the module's `css` entries to this specific instance.
+ * - `id` — a stable generated id, assigned once on mount and used to scope the
+ * module's `css` entries to this specific instance.
  *
  * @param props - Component properties.
  * @see {@link Props}
@@ -38,107 +35,81 @@ import cssModule from './styles.module.css';
  * @returns A host `<div>` into which the module's root `Element` is appended,
  * along with any `<style>` blocks exported by the module.
  */
-export const UIModule = ({ src, props, stateHandlers, className }) => {
+export const UIModule = ({ src, props, onIdGenerated, onIsLoadingChanged, onLoadedModuleChanged, onModuleTargetChanged, className }) => {
     // State & refs
-    const [id] = useState(`f${randomHash(10)}`);
-    const [loading, setLoading] = useState(false);
-    const [loadedModule, _setLoadedModule] = useState(null);
-    const [moduleTarget, _setModuleTarget] = useState(null);
+    const [id] = useState(() => `f${randomHash(10)}`);
+    const [isLoading, setIsLoading] = useState(false);
+    const [loadedModule, setLoadedModule] = useState(null);
+    const [moduleTarget, setModuleTarget] = useState(null);
     const rootRef = useRef(null);
-    const loadedModuleRef = useRef(null);
-    const moduleTargetRef = useRef(null);
-    const setLoadedModule = (data) => {
-        loadedModuleRef.current = data;
-        _setLoadedModule(data);
-    };
-    const setModuleTarget = (data) => {
-        moduleTargetRef.current = data;
-        _setModuleTarget(data);
-    };
-    // State changes dispatch
-    useEffect(() => { stateHandlers?.idChanged?.(id); }, [id, stateHandlers]);
-    useEffect(() => { stateHandlers?.isLoadingChanged?.(loading); }, [loading, stateHandlers]);
-    useEffect(() => { stateHandlers?.loadedModuleChanged?.(loadedModule); }, [loadedModule, stateHandlers]);
-    useEffect(() => { stateHandlers?.moduleTargetChanged?.(moduleTarget); }, [moduleTarget, stateHandlers]);
-    // Fx dep. `src` - load & init module effect
+    // What the teardown needs, held outside state so the load effect can depend on
+    // `src` alone and still destroy whatever is actually live at cleanup time.
+    const liveInstanceRef = useRef(null);
+    // State dispatch
+    useChangeDispatch(isLoading, onIsLoadingChanged);
+    useChangeDispatch(loadedModule, onLoadedModuleChanged);
+    useChangeDispatch(moduleTarget, onModuleTargetChanged);
+    // Fx. no dep. - report the generated id, which never changes afterwards
+    useEffect(() => { onIdGenerated?.(id); }, []);
+    // Fx. dep. `src` - import, validate and initialize the module
     useEffect(() => {
         if (src === undefined)
             return;
-        try {
-            setLoading(true);
-            import(src)
-                .then(data => {
-                setLoading(false);
-                const errs = {
-                    notMod: new Error('Not a module'),
-                    initFunc: new Error('Module exported member `init` must be a function'),
-                    destroyFunc: new Error('Module exported member `destroy` must be a function'),
-                    cssStrArr: new Error('Module exported member `css` must be an array of strings'),
-                    updFunc: new Error('Module exported member `update` must be a function'),
-                    initRetElt: new Error('Module exported function `init` must return an Element'),
-                    initRetFirstElt: new Error('Module exported function `init` must return an array containing an Element in its first position')
-                };
-                if (!isNonNullObject(data))
-                    return setLoadedModule(errs.notMod);
-                if (!('init' in data))
-                    return setLoadedModule(errs.initFunc);
-                if (typeof data.init !== 'function')
-                    return setLoadedModule(errs.initFunc);
-                if (!('destroy' in data) || typeof data.destroy !== 'function')
-                    return setLoadedModule(errs.destroyFunc);
-                if ('css' in data) {
-                    if (!Array.isArray(data.css))
-                        return setLoadedModule(errs.cssStrArr);
-                    if (data.css.some(i => typeof i !== 'string'))
-                        return setLoadedModule(errs.cssStrArr);
-                }
-                if ('update' in data && typeof data.update !== 'function')
-                    return setLoadedModule(errs.updFunc);
-                // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion -- shape fully validated by the checks above
-                const module = data;
-                setLoadedModule(module);
-                try {
-                    const target = module.init(props ?? {});
-                    if (!(target instanceof Element))
-                        return setLoadedModule(errs.initRetElt);
-                    setModuleTarget(target);
-                }
-                catch (err) {
-                    setModuleTarget(null);
-                    const e = err instanceof Error
-                        ? err
-                        : new Error(unknownToString(err));
-                    setLoadedModule(e);
-                }
-            }).catch((err) => {
-                setLoading(false);
-                setLoadedModule(err instanceof Error ? err : new Error(unknownToString(err)));
+        setIsLoading(true);
+        void import(src)
+            .then(data => {
+            setIsLoading(false);
+            if (!isNonNullObject(data))
+                return setLoadedModule(new Error('Not a module'));
+            if (!('init' in data) || typeof data.init !== 'function')
+                return setLoadedModule(new Error('Module exported member `init` must be a function'));
+            if (!('destroy' in data) || typeof data.destroy !== 'function')
+                return setLoadedModule(new Error('Module exported member `destroy` 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 ('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
+            const module = data;
+            setLoadedModule(module);
+            try {
+                const target = module.init(props ?? {});
+                if (!(target instanceof Element))
+                    return setLoadedModule(new Error('Module exported function `init` must return an Element'));
+                liveInstanceRef.current = { module, target };
+                setModuleTarget(target);
+            }
+            catch (err) {
+                liveInstanceRef.current = null;
                 setModuleTarget(null);
-            });
-        }
-        catch (err) {
-            if (err instanceof Error)
-                return setLoadedModule(err);
-            const errStr = unknownToString(err);
-            return setLoadedModule(new Error(errStr));
-        }
+                setLoadedModule(err instanceof Error ? err : new Error(unknownToString(err)));
+            }
+        })
+            .catch((err) => {
+            setIsLoading(false);
+            liveInstanceRef.current = null;
+            setLoadedModule(err instanceof Error ? err : new Error(unknownToString(err)));
+            setModuleTarget(null);
+        });
         return () => {
-            if (moduleTargetRef.current === null)
-                return;
-            if (loadedModuleRef.current instanceof Error)
-                return;
-            if (loadedModuleRef.current === null)
+            const liveInstance = liveInstanceRef.current;
+            if (liveInstance === null)
                 return;
-            loadedModuleRef.current.destroy(moduleTargetRef.current);
+            liveInstance.module.destroy(liveInstance.target);
+            liveInstanceRef.current = null;
         };
     }, [src]);
-    // Fx dep. `loadedModule` - log load errors
+    // Fx. dep. `loadedModule` - surface load errors
     useEffect(() => {
         // eslint-disable-next-line no-console
         if (loadedModule instanceof Error)
             console.error(loadedModule);
     }, [loadedModule]);
-    // Fx dep. `moduleTarget` - append the rendered module
+    // Fx. dep. `moduleTarget` - append the element the module built
     useEffect(() => {
         if (moduleTarget === null)
             return;
@@ -148,14 +119,14 @@ export const UIModule = ({ src, props, stateHandlers, className }) => {
     }, [moduleTarget]);
     // Rendering
     const c = clss(publicClassName, { cssModule });
+    const hasErrored = loadedModule instanceof Error;
     const rootClss = mergeClassNames(c(null, {
-        loading,
+        'loading': isLoading,
         'no-module': loadedModule === null,
-        'error': loadedModule instanceof Error,
-        'loaded': !loading && loadedModule !== null && !(loadedModule instanceof Error),
+        'error': hasErrored,
+        'loaded': !isLoading && loadedModule !== null && !hasErrored,
         'initialized': moduleTarget !== null
     }), className);
-    return _jsxs("div", { className: rootClss, ref: rootRef, id: id, children: [loadedModule === null && '', loadedModule !== null
-                && !(loadedModule instanceof Error)
-                && loadedModule.css?.map(css => _jsx("style", { children: `.${publicClassName}#${id} { ${css} }` }))] });
+    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)) });
 };

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

@@ -1,4 +1,4 @@
-import { type FunctionComponent, type PropsWithChildren, type VideoHTMLAttributes, type ReactEventHandler } from 'react';
+import { type FunctionComponent, type PropsWithChildren, type VideoHTMLAttributes } from 'react';
 import type { WithClassName } from '../utils/types.js';
 import { type Props as SubsProps } from '../Subtitles/index.js';
 /**
@@ -27,47 +27,6 @@ type TrackData = {
     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.
  *
@@ -84,11 +43,41 @@ export type StateHandlersProps = {
  * @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 currentTimeMs - External control of current time (in ms). Providing
+ * it hands ownership of the time to the parent: the value is displayed as given,
+ * the element is seeked to it on every change, and user interactions that would
+ * otherwise move the time (timeline click) no longer do — the parent is expected
+ * to update the prop instead. Because a playing element advances the time by
+ * itself, a controlled time also implies a stopped video: `play` and `autoPlay`
+ * are ignored for as long as this prop is provided.
+ * @property onPlayButtonClicked - Called when the play button is clicked, before
+ * the component reacts, with the playback state as it was.
+ * @property onPauseButtonClicked - Called when the pause button is clicked, before
+ * the component reacts, with the playback state as it was.
+ * @property onLoudButtonClicked - Called when the unmute button is clicked, before
+ * the component reacts, with the mute state as it was (`true` = unmuted).
+ * @property onMuteButtonClicked - Called when the mute button is clicked, before
+ * the component reacts, with the mute state as it was (`true` = unmuted).
+ * @property onVolumeRangeChanged - Called when the volume slider moves, before the
+ * component reacts, with the target and current volumes (both `0` to `1`).
+ * @property onRateRangeChanged - Called when the playback rate slider moves, before
+ * the component reacts, with the target and current rates.
+ * @property onFullscreenButtonClicked - Called when the fullscreen button is
+ * clicked, before the component reacts, with the fullscreen state as it was.
+ * @property onTimelineClicked - Called when the timeline is clicked, before the
+ * component reacts, with the target and current times (in seconds). The component
+ * seeks to the target right after, unless the time is controlled.
+ * @property onIsPlayingChanged - Called once the playback state has changed.
+ * @property onIsFullscreenChanged - Called once the fullscreen state has changed.
+ * @property onIsLoudChanged - Called once the mute state has changed (`true` = unmuted).
+ * @property onVolumeChanged - Called once the volume has changed (`0` to `1`).
+ * @property onPlaybackRateChanged - Called once the playback rate has changed.
+ * @property onCurrentTimeMsChanged - Called once the current time has changed, in
+ * milliseconds, to match the `currentTimeMs` prop.
+ * @property onFullscreenChange - Called when the *browser* enters or leaves
+ * fullscreen on its own — pressing Escape, typically — with the new state. This is
+ * the signal a parent needs to update its `fullscreen` prop, and it is distinct
+ * from `onIsFullscreenChanged`, which merely echoes that prop back once changed.
  * @property className - Additional CSS class for the root element.
  * @property children - React content inserted into the <video> tag (fallback, etc).
  *
@@ -109,10 +98,21 @@ export type Props = PropsWithChildren<WithClassName<{
     mute?: boolean;
     playbackRate?: number;
     currentTimeMs?: number;
-    onFullscreenChange?: ReactEventHandler<HTMLVideoElement>;
-    actionHandlers?: ActionHandlersProps;
-    stateHandlers?: StateHandlersProps;
-    _modifiers?: Record<string, boolean>;
+    onPlayButtonClicked?: (e: React.MouseEvent<HTMLButtonElement>, isPlaying: boolean, video: HTMLVideoElement | null) => void;
+    onPauseButtonClicked?: (e: React.MouseEvent<HTMLButtonElement>, isPlaying: boolean, video: HTMLVideoElement | null) => void;
+    onLoudButtonClicked?: (e: React.MouseEvent<HTMLButtonElement>, isLoud: boolean, video: HTMLVideoElement | null) => void;
+    onMuteButtonClicked?: (e: React.MouseEvent<HTMLButtonElement>, isLoud: boolean, video: HTMLVideoElement | null) => void;
+    onVolumeRangeChanged?: (e: React.ChangeEvent<HTMLInputElement>, targetVolume: number, currentVolume: number, video: HTMLVideoElement | null) => void;
+    onRateRangeChanged?: (e: React.ChangeEvent<HTMLInputElement>, targetRate: number, currentRate: number, video: HTMLVideoElement | null) => void;
+    onFullscreenButtonClicked?: (e: React.MouseEvent<HTMLButtonElement>, isFullscreen: boolean, video: HTMLVideoElement | null) => void;
+    onTimelineClicked?: (e: React.MouseEvent<HTMLDivElement>, targetTime: number, currentTime: number, video: HTMLVideoElement | null) => void;
+    onIsPlayingChanged?: (isPlaying: boolean) => void;
+    onIsFullscreenChanged?: (isFullscreen: boolean) => void;
+    onIsLoudChanged?: (isLoud: boolean) => void;
+    onVolumeChanged?: (volume: number) => void;
+    onPlaybackRateChanged?: (playbackRate: number) => void;
+    onCurrentTimeMsChanged?: (currentTimeMs: number) => void;
+    onFullscreenChange?: (isFullscreen: boolean) => void;
 }> & VideoHTMLAttributes<HTMLVideoElement>>;
 /**
  * Full-featured video player component. Wraps a native `<video>` element with