@design-edito/tools 0.5.2 → 0.5.3

package/components/Video/index.d.ts

@@ -1,31 +1,29 @@
 import { type FunctionComponent } from 'react';
-import { type Props as DisclaimerProps } from '../Disclaimer/index.js';
 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 disclaimer - Props forwarded to the internal {@link Disclaimer} component.
- * While the disclaimer is active, `autoPlay` and `muted` are suppressed on the
- * underlying `<video>` element.
  * @property autoPlayWhenVisible - When `true`, triggers playback the first time the
- * component intersects the viewport, provided no disclaimer is active.
+ * component intersects the viewport.
  * @property autoPauseWhenHidden - When `true`, pauses playback whenever the component
  * leaves the viewport.
  * @property autoLoudWhenVisible - When `true`, unmutes the video the first time the
- * component intersects the viewport, provided no disclaimer is active.
+ * component intersects the viewport.
  * @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 currentTimeMs - When provided, hands ownership of the current time
+ * (in milliseconds) to the parent, which is then responsible for updating it —
+ * typically to scrub the video from scroll position. A controlled time implies a
+ * stopped video, since a playing element would advance a value it does not own:
+ * `autoPlay`, `autoPlayWhenVisible` and the play button have no effect for as
+ * long as this prop is provided.
  * @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 = Omit<ControlledProps, 'play' | 'fullscreen' | 'volume' | 'mute' | 'playbackRate'> & {
-    disclaimer?: DisclaimerProps;
     autoPlayWhenVisible?: boolean;
     autoPauseWhenHidden?: boolean;
     autoLoudWhenVisible?: boolean;
@@ -34,12 +32,12 @@ export type Props = Omit<ControlledProps, 'play' | 'fullscreen' | 'volume' | 'mu
 };
 /**
  * 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.
+ * playback controls, volume, playback rate, a timeline, optional subtitles, and
+ * viewport-driven auto-play/mute behaviours.
  *
  * @param props - Component properties.
  * @see {@link Props}
- * @returns A `<figure>` element containing the video, its controls, optional
- * subtitles, and an optional disclaimer overlay.
+ * @returns A `<figure>` element containing the video, its controls and optional
+ * subtitles.
  */
 export declare const Video: FunctionComponent<Props>;

package/components/Video/index.js

@@ -1,7 +1,6 @@
 import { jsx as _jsx } from "react/jsx-runtime";
 import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
 import { clss } from '../../agnostic/css/clss/index.js';
-import { Disclaimer } from '../Disclaimer/index.js';
 import { IntersectionObserverComponent } from '../IntersectionObserver/index.js';
 import { mergeClassNames } from '../utils/index.js';
 import { videoWrapper as publicClassName } from '../public-classnames.js';
@@ -10,33 +9,27 @@ import cssModule from './styles.module.css';
 import { ControlledVideo } from './index.controlled.js';
 /**
  * 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.
+ * playback controls, volume, playback rate, a timeline, optional subtitles, and
+ * viewport-driven auto-play/mute behaviours.
  *
  * @param props - Component properties.
  * @see {@link Props}
- * @returns A `<figure>` element containing the video, its controls, optional
- * subtitles, and an optional disclaimer overlay.
+ * @returns A `<figure>` element containing the video, its controls and optional
+ * subtitles.
  */
-export const Video = ({ loop, disclaimer, autoPlayWhenVisible, autoPauseWhenHidden, autoMuteWhenHidden, autoLoudWhenVisible, wrapperClassName, ...controlledProps }) => {
+export const Video = ({ loop, autoPlayWhenVisible, autoPauseWhenHidden, autoMuteWhenHidden, autoLoudWhenVisible, wrapperClassName, onPlayButtonClicked, onPauseButtonClicked, onLoudButtonClicked, onMuteButtonClicked, onVolumeRangeChanged, onRateRangeChanged, onFullscreenButtonClicked, ...controlledProps }) => {
     // State & refs
     const [play, setPlay] = useState(false);
     const [volume, setVolume] = useState(1);
     const [mute, setMute] = useState(false);
     const [playbackRate, setPlaybackRate] = useState(1);
     const [fullscreen, setFullscreen] = useState(false);
-    const [isDisclaimerOn, setIsDisclaimerOn] = useState(disclaimer?.isOn === true
-        || disclaimer?.defaultIsOn === true
-        || (disclaimer !== undefined && disclaimer.defaultIsOn === undefined));
     const hasBeenAutoPlayed = useRef(false);
-    const needsDisclaimer = useMemo(() => disclaimer !== undefined, [disclaimer]);
-    const shouldDisclaimerBeOn = useMemo(() => {
-        if (disclaimer?.isOn === false)
-            return false;
-        if (disclaimer?.isOn === true)
-            return true;
-        return isDisclaimerOn;
-    }, [disclaimer, isDisclaimerOn]);
+    // Several paths below ask for playback — the play button, autoPlayWhenVisible,
+    // autoPlay itself. None of them may win over a parent-owned time, so the
+    // invariant is applied where the state is forwarded rather than guarded at each
+    // of those call sites.
+    const isTimeControlled = controlledProps.currentTimeMs !== undefined;
     const needsObserve = useMemo(() => autoLoudWhenVisible === true
         || autoMuteWhenHidden === true
         || autoPlayWhenVisible === true
@@ -49,13 +42,9 @@ export const Video = ({ loop, disclaimer, autoPlayWhenVisible, autoPauseWhenHidd
     // Intrisic event handlers
     const handleOnPlayEvent = useCallback((e) => {
         controlledProps.onPlay?.(e);
-        if (shouldDisclaimerBeOn) {
-            setPlay(false);
-            return;
-        }
         setPlay(true);
         hasBeenAutoPlayed.current = true;
-    }, [controlledProps.onPlay, shouldDisclaimerBeOn]);
+    }, [controlledProps.onPlay]);
     const handleOnPauseEvent = useCallback((e) => {
         setPlay(false);
         controlledProps.onPause?.(e);
@@ -69,45 +58,44 @@ export const Video = ({ loop, disclaimer, autoPlayWhenVisible, autoPauseWhenHidd
         setPlaybackRate(e.currentTarget.playbackRate);
         controlledProps.onRateChange?.(e);
     }, [controlledProps.onRateChange]);
-    const handleOnFullscreenChangeEvent = useCallback((e) => {
-        if (document.fullscreenElement === null || shouldDisclaimerBeOn) {
+    const handleFullscreenChange = useCallback((isFullscreen) => {
+        if (!isFullscreen)
             setFullscreen(false);
-        }
-    }, [shouldDisclaimerBeOn]);
+    }, []);
     const handleOnLoadedMetadataEvent = useCallback((e) => {
         muteAttributeWorkaround(e.currentTarget, controlledProps.muted ?? false);
         controlledProps.onLoadedMetadata?.(e);
     }, [controlledProps.onLoadedMetadata, controlledProps.muted]);
     // User actions
     const handlePlayButtonClick = useCallback((e, isPlaying, video) => {
-        controlledProps.actionHandlers?.playButtonClick?.(e, isPlaying, video);
-        setPlay(!shouldDisclaimerBeOn);
-    }, [controlledProps.actionHandlers, shouldDisclaimerBeOn]);
+        onPlayButtonClicked?.(e, isPlaying, video);
+        setPlay(true);
+    }, [onPlayButtonClicked]);
     const handlePauseButtonClick = useCallback((e, isPlaying, video) => {
-        controlledProps.actionHandlers?.pauseButtonClick?.(e, isPlaying, video);
+        onPauseButtonClicked?.(e, isPlaying, video);
         setPlay(false);
-    }, [controlledProps.actionHandlers]);
+    }, [onPauseButtonClicked]);
     const handleLoudButtonClick = useCallback((e, isLoud, video) => {
-        controlledProps.actionHandlers?.loudButtonClick?.(e, isLoud, video);
+        onLoudButtonClicked?.(e, isLoud, video);
         setMute(false);
-    }, [controlledProps.actionHandlers]);
+    }, [onLoudButtonClicked]);
     const handleMuteButtonClick = useCallback((e, isLoud, video) => {
-        controlledProps.actionHandlers?.muteButtonClick?.(e, isLoud, video);
+        onMuteButtonClicked?.(e, isLoud, video);
         setMute(true);
-    }, [controlledProps.actionHandlers]);
+    }, [onMuteButtonClicked]);
     const handleRateRangeChange = useCallback((e, targetRate, currentRate, video) => {
-        controlledProps.actionHandlers?.rateRangeChange?.(e, targetRate, currentRate, video);
+        onRateRangeChanged?.(e, targetRate, currentRate, video);
         setPlaybackRate(targetRate);
-    }, [controlledProps.actionHandlers]);
+    }, [onRateRangeChanged]);
     const handleVolumeRangeChange = useCallback((e, targetVolume, currentVolume, video) => {
-        controlledProps.actionHandlers?.volumeRangeChange?.(e, targetVolume, currentVolume, video);
+        onVolumeRangeChanged?.(e, targetVolume, currentVolume, video);
         setVolume(targetVolume);
-    }, [controlledProps.actionHandlers]);
+    }, [onVolumeRangeChanged]);
     const handleFullscreenButtonClick = useCallback((e, isFullscreen, video) => {
-        controlledProps.actionHandlers?.fullscreenButtonClick?.(e, isFullscreen, video);
-        setFullscreen((prev) => shouldDisclaimerBeOn ? false : !isFullscreen);
-    }, [controlledProps.actionHandlers, shouldDisclaimerBeOn]);
-    // Intersection Observer + Disclaimer
+        onFullscreenButtonClicked?.(e, isFullscreen, video);
+        setFullscreen(!isFullscreen);
+    }, [onFullscreenButtonClicked]);
+    // Intersection Observer
     const onIntersected = useCallback(({ ioEntry }) => {
         if (ioEntry === undefined)
             return;
@@ -117,12 +105,10 @@ export const Video = ({ loop, disclaimer, autoPlayWhenVisible, autoPauseWhenHidd
         if (autoLoudWhenVisible === true && isIntersecting)
             setMute(false);
         if (autoPlayWhenVisible === true
-            && !shouldDisclaimerBeOn
             && !hasBeenAutoPlayed.current
             && isIntersecting)
             setPlay(true);
         if (autoMuteWhenHidden === true
-            && !shouldDisclaimerBeOn
             && !hasBeenAutoPlayed.current
             && !isIntersecting)
             setMute(true);
@@ -130,50 +116,19 @@ export const Video = ({ loop, disclaimer, autoPlayWhenVisible, autoPauseWhenHidd
         autoPlayWhenVisible,
         autoPauseWhenHidden,
         autoMuteWhenHidden,
-        autoLoudWhenVisible,
-        shouldDisclaimerBeOn
+        autoLoudWhenVisible
     ]);
-    const handleDiclaimerDismiss = useCallback((prevIsOn) => {
-        setIsDisclaimerOn(false);
-        if (controlledProps.autoPlay === true && !hasBeenAutoPlayed.current) {
-            setPlay(true);
-        }
-        disclaimer?.actionHandlers?.dismissClick?.(prevIsOn);
-    }, [controlledProps.autoPlay, disclaimer?.actionHandlers?.dismissClick]);
+    // `autoPlay` is forwarded to the element, but the play state is owned here, so
+    // it has to be seeded once on mount for the controls to agree with the element.
     useEffect(() => {
-        if (isDisclaimerOn !== shouldDisclaimerBeOn)
-            setIsDisclaimerOn(shouldDisclaimerBeOn);
-    }, [isDisclaimerOn, shouldDisclaimerBeOn]);
-    useEffect(() => {
-        if (shouldDisclaimerBeOn) {
-            setMute(true);
-            setPlay(false);
-            setFullscreen(false);
-        }
-        else if (controlledProps.autoPlay === true && !hasBeenAutoPlayed.current) {
+        if (controlledProps.autoPlay === true && !hasBeenAutoPlayed.current)
             setPlay(true);
-        }
-    }, [shouldDisclaimerBeOn]);
+    }, []);
     // Render
     const c = clss(publicClassName, { cssModule });
-    const rootClss = mergeClassNames(c(null, {}), wrapperClassName);
-    const sensitiveContent = _jsx(ControlledVideo, { ...controlledProps, play: play, volume: volume, mute: mute, playbackRate: playbackRate, fullscreen: fullscreen, onPlay: handleOnPlayEvent, onPause: handleOnPauseEvent, onVolumeChange: handleOnVolumeChangeEvent, onRateChange: handleOnRateChangeEvent, onLoadedMetadata: handleOnLoadedMetadataEvent, onFullscreenChange: handleOnFullscreenChangeEvent, actionHandlers: {
-            ...controlledProps.actionHandlers,
-            playButtonClick: handlePlayButtonClick,
-            pauseButtonClick: handlePauseButtonClick,
-            loudButtonClick: handleLoudButtonClick,
-            muteButtonClick: handleMuteButtonClick,
-            volumeRangeChange: handleVolumeRangeChange,
-            rateRangeChange: handleRateRangeChange,
-            fullscreenButtonClick: handleFullscreenButtonClick
-        } });
-    const disclaimedContent = needsDisclaimer
-        ? _jsx(Disclaimer, { ...disclaimer, actionHandlers: {
-                ...disclaimer?.actionHandlers,
-                dismissClick: handleDiclaimerDismiss
-            }, children: sensitiveContent })
-        : sensitiveContent;
-    return (_jsx("div", { className: rootClss, children: needsObserve
-            ? _jsx(IntersectionObserverComponent, { onIntersected: onIntersected, children: disclaimedContent })
-            : disclaimedContent }));
+    const rootClss = mergeClassNames(c(), wrapperClassName);
+    const videoContent = _jsx(ControlledVideo, { ...controlledProps, play: play && !isTimeControlled, volume: volume, mute: mute, playbackRate: playbackRate, fullscreen: fullscreen, onPlay: handleOnPlayEvent, onPause: handleOnPauseEvent, onVolumeChange: handleOnVolumeChangeEvent, onRateChange: handleOnRateChangeEvent, onLoadedMetadata: handleOnLoadedMetadataEvent, onFullscreenChange: handleFullscreenChange, onPlayButtonClicked: handlePlayButtonClick, onPauseButtonClicked: handlePauseButtonClick, onLoudButtonClicked: handleLoudButtonClick, onMuteButtonClicked: handleMuteButtonClick, onVolumeRangeChanged: handleVolumeRangeChange, onRateRangeChanged: handleRateRangeChange, onFullscreenButtonClicked: handleFullscreenButtonClick });
+    return _jsx("div", { className: rootClss, children: needsObserve
+            ? _jsx(IntersectionObserverComponent, { onIntersected: onIntersected, children: videoContent })
+            : videoContent });
 };

package/components/Video/utils.d.ts

@@ -1,9 +1,7 @@
-import type { Dispatch, SetStateAction } from 'react';
 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;
-export declare const forceCurrentTime: (video: HTMLVideoElement | null, time: number, setCurrentTime: Dispatch<SetStateAction<number>>) => void;
 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;
@@ -11,5 +9,39 @@ 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;
+/**
+ * Renders a duration into a caller-defined pattern.
+ *
+ * The pattern is a free-form string in which the following tokens are replaced,
+ * longest first, so that `mm` is consumed before `m`:
+ *
+ * - `hh`, `mm`, `ss` — hours, minutes and seconds, zero-padded to two digits.
+ * - `ms` — the remaining milliseconds, zero-padded to three digits.
+ * - `frame` — the remaining milliseconds expressed in frames, zero-padded to two
+ *   digits.
+ * - `h`, `m`, `s`, `f` — the same four values, unpadded.
+ *
+ * @param ms - The duration, in milliseconds.
+ * @param format - The pattern to fill, e.g. `'mm:ss:ms'`.
+ * @param fps - Frame rate used to derive the `frame` and `f` tokens. Defaults to `25`.
+ * @returns The formatted duration.
+ *
+ * @remarks
+ * Every field is a remainder of the one above it, never a total: at one hour and
+ * a half, `mm` is `30`, not `90`. A pattern that omits `hh` therefore loses the
+ * hours rather than folding them into the minutes.
+ *
+ * Since `h`, `m`, `s` and `f` are tokens on their own, **every** occurrence of
+ * those letters is substituted, wherever it sits: `'mm min ss'` renders as
+ * `'01 1in 01'`. Separate the fields with punctuation. This is what
+ * `agnostic/time/dates/format-date` avoids by delimiting its tokens with
+ * `{{…}}` — worth aligning on the day this one is made public.
+ */
 export declare function formatTime(ms: number, format: string, fps?: number): string;
-export declare const getTimelineClickProgress: (event: React.MouseEvent<HTMLDivElement>, timeline: HTMLDivElement | null, video: HTMLVideoElement | null) => 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;

package/components/Video/utils.js

@@ -28,13 +28,6 @@ export const forceVolume = (video, volume) => {
     // eslint-disable-next-line no-param-reassign
     video.volume = volume;
 };
-export const forceCurrentTime = (video, time, setCurrentTime) => {
-    if (video === null)
-        return;
-    // eslint-disable-next-line no-param-reassign
-    video.currentTime = time;
-    setCurrentTime(time);
-};
 export const forcePlay = async (video) => {
     if (video === null)
         return false;
@@ -105,6 +98,34 @@ export function secondsToMs(seconds) {
 export function msToSeconds(ms) {
     return ms / 1000;
 }
+/**
+ * Renders a duration into a caller-defined pattern.
+ *
+ * The pattern is a free-form string in which the following tokens are replaced,
+ * longest first, so that `mm` is consumed before `m`:
+ *
+ * - `hh`, `mm`, `ss` — hours, minutes and seconds, zero-padded to two digits.
+ * - `ms` — the remaining milliseconds, zero-padded to three digits.
+ * - `frame` — the remaining milliseconds expressed in frames, zero-padded to two
+ *   digits.
+ * - `h`, `m`, `s`, `f` — the same four values, unpadded.
+ *
+ * @param ms - The duration, in milliseconds.
+ * @param format - The pattern to fill, e.g. `'mm:ss:ms'`.
+ * @param fps - Frame rate used to derive the `frame` and `f` tokens. Defaults to `25`.
+ * @returns The formatted duration.
+ *
+ * @remarks
+ * Every field is a remainder of the one above it, never a total: at one hour and
+ * a half, `mm` is `30`, not `90`. A pattern that omits `hh` therefore loses the
+ * hours rather than folding them into the minutes.
+ *
+ * Since `h`, `m`, `s` and `f` are tokens on their own, **every** occurrence of
+ * those letters is substituted, wherever it sits: `'mm min ss'` renders as
+ * `'01 1in 01'`. Separate the fields with punctuation. This is what
+ * `agnostic/time/dates/format-date` avoids by delimiting its tokens with
+ * `{{…}}` — worth aligning on the day this one is made public.
+ */
 export function formatTime(ms, format, fps = 25) {
     const totalSeconds = Math.floor(ms / 1000);
     const hours = Math.floor(totalSeconds / 3600);
@@ -123,17 +144,19 @@ export function formatTime(ms, format, fps = 25) {
         s: seconds,
         f: frames
     };
-    const result = Object
+    return Object
         .keys(tokens)
         .sort((a, b) => b.length - a.length)
         .reduce((acc, t) => acc.replace(new RegExp(t, 'gv'), String(tokens[t])), format);
-    return result;
 }
-export const getTimelineClickProgress = (event, timeline, video) => {
-    if (video === null || timeline === null)
-        return 0;
+/**
+ * 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;
-    const progress = Math.min(1, Math.max(0, position / timelineRect.width));
-    return progress;
+    return Math.min(1, Math.max(0, position / timelineRect.width));
 };

package/components/index.d.ts

@@ -1,7 +1,7 @@
 export * as beforeAfter from './BeforeAfter/index.js'
 export * as button from './Button/index.js'
-export * as disclaimer from './Disclaimer/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 gallery from './Gallery/index.js'

package/components/index.js

@@ -1,7 +1,7 @@
 export * as beforeAfter from './BeforeAfter/index.js'
 export * as button from './Button/index.js'
-export * as disclaimer from './Disclaimer/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 gallery from './Gallery/index.js'

package/components/utils/index.d.ts

@@ -1 +1,23 @@
 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;

package/components/utils/index.js

@@ -1,3 +1,4 @@
+import { useEffect, useRef } from 'react';
 export function mergeClassNames(...names) {
     return names.map(name => {
         if (typeof name !== 'string' && !Array.isArray(name))
@@ -10,3 +11,33 @@ export function mergeClassNames(...names) {
     }).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]);
+}

package/index.d.ts

@@ -1,3 +1,3 @@
+export * as agnostic from './agnostic/index.js'
 export * as components from './components/index.js'
 export * as node from './node/index.js'
-export * as agnostic from './agnostic/index.js'

package/index.js

@@ -1,3 +1,3 @@
+export * as agnostic from './agnostic/index.js'
 export * as components from './components/index.js'
 export * as node from './node/index.js'
-export * as agnostic from './agnostic/index.js'

package/node/@aws-s3/storage/file/index.d.ts

@@ -1,6 +1,6 @@
 export * as copy from './copy/index.js'
-export * as exists from './exists/index.js'
 export * as download from './download/index.js'
+export * as exists from './exists/index.js'
 export * as move from './move/index.js'
 export * as remove from './remove/index.js'
 export * as stat from './stat/index.js'

package/node/@aws-s3/storage/file/index.js

@@ -1,6 +1,6 @@
 export * as copy from './copy/index.js'
-export * as exists from './exists/index.js'
 export * as download from './download/index.js'
+export * as exists from './exists/index.js'
 export * as move from './move/index.js'
 export * as remove from './remove/index.js'
 export * as stat from './stat/index.js'

package/node/@google-cloud/storage/index.d.ts

@@ -1,3 +1,3 @@
-export * as directory from './directory/index.js'
 export * as bucket from './bucket/index.js'
+export * as directory from './directory/index.js'
 export * as file from './file/index.js'

package/node/@google-cloud/storage/index.js

@@ -1,3 +1,3 @@
-export * as directory from './directory/index.js'
 export * as bucket from './bucket/index.js'
+export * as directory from './directory/index.js'
 export * as file from './file/index.js'

package/node/images/index.d.ts

@@ -1,5 +1,5 @@
 export * as create from './create/index.js'
-export * as metadata from './metadata/index.js'
 export * as format from './format/index.js'
+export * as metadata from './metadata/index.js'
 export * as transform from './transform/index.js'
 export * as utils from './utils/index.js'

package/node/images/index.js

@@ -1,5 +1,5 @@
 export * as create from './create/index.js'
-export * as metadata from './metadata/index.js'
 export * as format from './format/index.js'
+export * as metadata from './metadata/index.js'
 export * as transform from './transform/index.js'
 export * as utils from './utils/index.js'

package/node/images/transform/operations/index.d.ts

@@ -1,6 +1,6 @@
 export * as blur from './blur/index.js'
-export * as extend from './extend/index.js'
 export * as brighten from './brighten/index.js'
+export * as extend from './extend/index.js'
 export * as extract from './extract/index.js'
 export * as flatten from './flatten/index.js'
 export * as flip from './flip/index.js'

package/node/images/transform/operations/index.js

@@ -1,6 +1,6 @@
 export * as blur from './blur/index.js'
-export * as extend from './extend/index.js'
 export * as brighten from './brighten/index.js'
+export * as extend from './extend/index.js'
 export * as extract from './extract/index.js'
 export * as flatten from './flatten/index.js'
 export * as flip from './flip/index.js'

package/node/index.d.ts

@@ -4,8 +4,8 @@ export * as express from './@express/index.js'
 export * as googleCloud from './@google-cloud/index.js'
 export * as cloudStorage from './cloud-storage/index.js'
 export * as encryption from './encryption/index.js'
-export * as ftps from './ftps/index.js'
 export * as files from './files/index.js'
+export * as ftps from './ftps/index.js'
 export * as images from './images/index.js'
 export * as process from './process/index.js'
 export * as sftp from './sftp/index.js'

package/node/index.js

@@ -4,8 +4,8 @@ export * as express from './@express/index.js'
 export * as googleCloud from './@google-cloud/index.js'
 export * as cloudStorage from './cloud-storage/index.js'
 export * as encryption from './encryption/index.js'
-export * as ftps from './ftps/index.js'
 export * as files from './files/index.js'
+export * as ftps from './ftps/index.js'
 export * as images from './images/index.js'
 export * as process from './process/index.js'
 export * as sftp from './sftp/index.js'

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@design-edito/tools",
-  "version": "0.5.2",
+  "version": "0.5.3",
   "description": "",
   "author": "Maxime Fabas",
   "license": "ISC",
@@ -1290,6 +1290,10 @@
     "./agnostic/time/dates/format-date/index.js": {
       "import": "./agnostic/time/dates/format-date/index.js"
     },
+    "./agnostic/time/dates/format-date/types.js": {
+      "import": "./agnostic/time/dates/format-date/types.js",
+      "types": "./agnostic/time/dates/format-date/types.d.ts"
+    },
     "./agnostic/time/dates/index.js": {
       "import": "./agnostic/time/dates/index.js"
     },
@@ -1308,6 +1312,17 @@
       "import": "./agnostic/time/duration/index.js",
       "types": "./agnostic/time/duration/index.d.ts"
     },
+    "./agnostic/time/duration/format-duration": {
+      "import": "./agnostic/time/duration/format-duration/index.js",
+      "types": "./agnostic/time/duration/format-duration/index.d.ts"
+    },
+    "./agnostic/time/duration/format-duration/index.js": {
+      "import": "./agnostic/time/duration/format-duration/index.js"
+    },
+    "./agnostic/time/duration/format-duration/types.js": {
+      "import": "./agnostic/time/duration/format-duration/types.js",
+      "types": "./agnostic/time/duration/format-duration/types.d.ts"
+    },
     "./agnostic/time/duration/index.js": {
       "import": "./agnostic/time/duration/index.js"
     },
@@ -1451,6 +1466,10 @@
     "./components/JsonEditor/index.js": {
       "import": "./components/JsonEditor/index.js"
     },
+    "./components/JsonEditor/types.js": {
+      "import": "./components/JsonEditor/types.js",
+      "types": "./components/JsonEditor/types.d.ts"
+    },
     "./components/ListLoader": {
       "import": "./components/ListLoader/index.js",
       "types": "./components/ListLoader/index.d.ts"
@@ -1521,10 +1540,6 @@
     "./components/Subtitles/index.js": {
       "import": "./components/Subtitles/index.js"
     },
-    "./components/Subtitles/types.js": {
-      "import": "./components/Subtitles/types.js",
-      "types": "./components/Subtitles/types.d.ts"
-    },
     "./components/Textarea": {
       "import": "./components/Textarea/index.js",
       "types": "./components/Textarea/index.d.ts"