@design-edito/tools 0.4.6 → 0.4.12

package/agnostic/html/index.d.ts

@@ -1,8 +1,10 @@
 export * as getNodeAncestors from './get-node-ancestors/index.js'
-export * as hyperJson from './hyper-json/index.js'
 export * as getPositionInsideParent from './get-position-inside-parent/index.js'
+export * as hyperJson from './hyper-json/index.js'
 export * as insertNode from './insert-node/index.js'
 export * as placeholders from './placeholders/index.js'
 export * as replaceInElement from './replace-in-element/index.js'
-export * as stringToNodes from './string-to-nodes/index.js'
 export * as selectorToElement from './selector-to-element/index.js'
+export * as deepSelect from './deep-select/index.js'
+export * as stringToNodes from './string-to-nodes/index.js'
+export * as watchSelection from './watch-selection/index.js'

package/agnostic/html/index.js

@@ -1,8 +1,10 @@
 export * as getNodeAncestors from './get-node-ancestors/index.js'
-export * as hyperJson from './hyper-json/index.js'
 export * as getPositionInsideParent from './get-position-inside-parent/index.js'
+export * as hyperJson from './hyper-json/index.js'
 export * as insertNode from './insert-node/index.js'
 export * as placeholders from './placeholders/index.js'
 export * as replaceInElement from './replace-in-element/index.js'
-export * as stringToNodes from './string-to-nodes/index.js'
 export * as selectorToElement from './selector-to-element/index.js'
+export * as deepSelect from './deep-select/index.js'
+export * as stringToNodes from './string-to-nodes/index.js'
+export * as watchSelection from './watch-selection/index.js'

package/agnostic/html/watch-selection/index.d.ts

@@ -0,0 +1,41 @@
+/** Options for `watchSelection`. */
+type Options = {
+    /** Called when a matching element newly appears in the selection. Defaults to a no-op. */
+    watch?: (elt: Element) => void;
+    /** Called when a matching element is no longer in the selection. Defaults to a no-op. */
+    unwatch?: (elt: Element) => void;
+    /** Interval in milliseconds between selection polls. Defaults to `100`. */
+    selectIntervalMs?: number;
+};
+/**
+ * Watches a CSS selector over time and invokes callbacks when the matching set changes.
+ *
+ * Performs an initial `deepSelect`, calls `watch` on every match, then polls on a fixed interval.
+ * On each poll, newly matched elements trigger `watch` and elements that disappeared trigger
+ * `unwatch`. Comparison uses element identity (`===`), not structural equality.
+ *
+ * Requires a browser environment with `window` and `document`.
+ *
+ * @param {string} selector - CSS selector passed to `deepSelect`.
+ * @param {Options} options - Callbacks and polling configuration:
+ *   - `watch`: Handler for elements that enter the selection.
+ *   - `unwatch`: Handler for elements that leave the selection.
+ *   - `selectIntervalMs`: Delay between polls in milliseconds.
+ * @returns {Promise<{ kill: () => void }>}
+ * Resolves after the initial selection is processed. `kill` stops polling and calls `unwatch`
+ * on every element still watched.
+ *
+ * @example
+ * const { kill } = await watchSelection('.widget', {
+ *   watch: elt => elt.classList.add('is-active'),
+ *   unwatch: elt => elt.classList.remove('is-active'),
+ * })
+ *
+ * @example
+ * // later, when tearing down:
+ * kill()
+ */
+export declare const watchSelection: (selector: string, options: Options) => Promise<{
+    kill: () => void;
+}>;
+export {};

package/agnostic/html/watch-selection/index.js

@@ -0,0 +1,50 @@
+import { deepSelect } from '../deep-select/index.js';
+/**
+ * Watches a CSS selector over time and invokes callbacks when the matching set changes.
+ *
+ * Performs an initial `deepSelect`, calls `watch` on every match, then polls on a fixed interval.
+ * On each poll, newly matched elements trigger `watch` and elements that disappeared trigger
+ * `unwatch`. Comparison uses element identity (`===`), not structural equality.
+ *
+ * Requires a browser environment with `window` and `document`.
+ *
+ * @param {string} selector - CSS selector passed to `deepSelect`.
+ * @param {Options} options - Callbacks and polling configuration:
+ *   - `watch`: Handler for elements that enter the selection.
+ *   - `unwatch`: Handler for elements that leave the selection.
+ *   - `selectIntervalMs`: Delay between polls in milliseconds.
+ * @returns {Promise<{ kill: () => void }>}
+ * Resolves after the initial selection is processed. `kill` stops polling and calls `unwatch`
+ * on every element still watched.
+ *
+ * @example
+ * const { kill } = await watchSelection('.widget', {
+ *   watch: elt => elt.classList.add('is-active'),
+ *   unwatch: elt => elt.classList.remove('is-active'),
+ * })
+ *
+ * @example
+ * // later, when tearing down:
+ * kill()
+ */
+export const watchSelection = async (selector, options) => {
+    const watch = options?.watch ?? (() => { });
+    const unwatch = options?.unwatch ?? (() => { });
+    let watched = await deepSelect(selector);
+    watched.forEach(watch);
+    const selectIntervalMs = options?.selectIntervalMs ?? 100;
+    const interval = window.setInterval(() => {
+        void deepSelect(selector).then(watchedNow => {
+            const staleWatched = watched.filter(elt => !watchedNow.includes(elt));
+            const newWatched = watchedNow.filter(elt => !watched.includes(elt));
+            staleWatched.forEach(unwatch);
+            newWatched.forEach(watch);
+            watched = watchedNow;
+        });
+    }, selectIntervalMs);
+    const kill = () => {
+        window.clearInterval(interval);
+        watched.forEach(unwatch);
+    };
+    return { kill };
+};

package/agnostic/index.d.ts

@@ -1,16 +1,16 @@
 export * as arrays from './arrays/index.js'
-export * as booleans from './booleans/index.js'
 export * as colors from './colors/index.js'
 export * as css from './css/index.js'
 export * as errors from './errors/index.js'
-export * as html from './html/index.js'
 export * as misc from './misc/index.js'
+export * as html from './html/index.js'
 export * as numbers from './numbers/index.js'
 export * as objects from './objects/index.js'
+export * as booleans from './booleans/index.js'
 export * as optim from './optim/index.js'
 export * as random from './random/index.js'
+export * as regexps from './regexps/index.js'
 export * as sanitization from './sanitization/index.js'
 export * as strings from './strings/index.js'
 export * as time from './time/index.js'
-export * as regexps from './regexps/index.js'
 export * as typescript from './typescript/index.js'

package/agnostic/index.js

@@ -1,16 +1,16 @@
 export * as arrays from './arrays/index.js'
-export * as booleans from './booleans/index.js'
 export * as colors from './colors/index.js'
 export * as css from './css/index.js'
 export * as errors from './errors/index.js'
-export * as html from './html/index.js'
 export * as misc from './misc/index.js'
+export * as html from './html/index.js'
 export * as numbers from './numbers/index.js'
 export * as objects from './objects/index.js'
+export * as booleans from './booleans/index.js'
 export * as optim from './optim/index.js'
 export * as random from './random/index.js'
+export * as regexps from './regexps/index.js'
 export * as sanitization from './sanitization/index.js'
 export * as strings from './strings/index.js'
 export * as time from './time/index.js'
-export * as regexps from './regexps/index.js'
 export * as typescript from './typescript/index.js'

package/agnostic/misc/index.d.ts

@@ -5,8 +5,8 @@ export * as crawler from './crawler/index.js'
 export * as crossenv from './crossenv/index.js'
 export * as dataSize from './data-size/index.js'
 export * as isConstructorFunction from './is-constructor-function/index.js'
-export * as logs from './logs/index.js'
 export * as isNullish from './is-nullish/index.js'
+export * as logs from './logs/index.js'
 export * as loremIpsum from './lorem-ipsum/index.js'
 export * as normalizeExtension from './normalize-extension/index.js'
 export * as outcome from './outcome/index.js'

package/agnostic/misc/index.js

@@ -5,8 +5,8 @@ export * as crawler from './crawler/index.js'
 export * as crossenv from './crossenv/index.js'
 export * as dataSize from './data-size/index.js'
 export * as isConstructorFunction from './is-constructor-function/index.js'
-export * as logs from './logs/index.js'
 export * as isNullish from './is-nullish/index.js'
+export * as logs from './logs/index.js'
 export * as loremIpsum from './lorem-ipsum/index.js'
 export * as normalizeExtension from './normalize-extension/index.js'
 export * as outcome from './outcome/index.js'

package/agnostic/numbers/index.d.ts

@@ -1,6 +1,6 @@
-export * as absoluteModulo from './absolute-modulo/index.js'
 export * as approximateRational from './approximate-rational/index.js'
+export * as absoluteModulo from './absolute-modulo/index.js'
+export * as geometricProgressions from './geometric-progressions/index.js'
 export * as clamp from './clamp/index.js'
-export * as interpolate from './interpolate/index.js'
 export * as round from './round/index.js'
-export * as geometricProgressions from './geometric-progressions/index.js'
+export * as interpolate from './interpolate/index.js'

package/agnostic/numbers/index.js

@@ -1,6 +1,6 @@
-export * as absoluteModulo from './absolute-modulo/index.js'
 export * as approximateRational from './approximate-rational/index.js'
+export * as absoluteModulo from './absolute-modulo/index.js'
+export * as geometricProgressions from './geometric-progressions/index.js'
 export * as clamp from './clamp/index.js'
-export * as interpolate from './interpolate/index.js'
 export * as round from './round/index.js'
-export * as geometricProgressions from './geometric-progressions/index.js'
+export * as interpolate from './interpolate/index.js'

package/agnostic/objects/index.d.ts

@@ -2,8 +2,8 @@ export * as deepGetProperty from './deep-get-property/index.js'
 export * as enums from './enums/index.js'
 export * as flattenGetters from './flatten-getters/index.js'
 export * as isObject from './is-object/index.js'
-export * as isRecord from './is-record/index.js'
 export * as recordFormat from './record-format/index.js'
-export * as sortKeys from './sort-keys/index.js'
+export * as isRecord from './is-record/index.js'
 export * as recordMap from './record-map/index.js'
+export * as sortKeys from './sort-keys/index.js'
 export * as validation from './validation/index.js'

package/agnostic/objects/index.js

@@ -2,8 +2,8 @@ export * as deepGetProperty from './deep-get-property/index.js'
 export * as enums from './enums/index.js'
 export * as flattenGetters from './flatten-getters/index.js'
 export * as isObject from './is-object/index.js'
-export * as isRecord from './is-record/index.js'
 export * as recordFormat from './record-format/index.js'
-export * as sortKeys from './sort-keys/index.js'
+export * as isRecord from './is-record/index.js'
 export * as recordMap from './record-map/index.js'
+export * as sortKeys from './sort-keys/index.js'
 export * as validation from './validation/index.js'

package/agnostic/optim/index.d.ts

@@ -1,2 +1,2 @@
-export * as throttleDebounce from './throttle-debounce/index.js'
 export * as memoize from './memoize/index.js'
+export * as throttleDebounce from './throttle-debounce/index.js'

package/agnostic/optim/index.js

@@ -1,2 +1,2 @@
-export * as throttleDebounce from './throttle-debounce/index.js'
 export * as memoize from './memoize/index.js'
+export * as throttleDebounce from './throttle-debounce/index.js'

package/agnostic/strings/index.d.ts

@@ -1,7 +1,8 @@
 export * as charCodes from './char-codes/index.js'
 export * as matches from './matches/index.js'
 export * as normalizeIndent from './normalize-indent/index.js'
-export * as parseTable from './parse-table/index.js'
 export * as replaceAll from './replace-all/index.js'
 export * as toAlphanum from './to-alphanum/index.js'
+export * as parseTable from './parse-table/index.js'
+export * as splitTrim from './split-trim/index.js'
 export * as trim from './trim/index.js'

package/agnostic/strings/index.js

@@ -1,7 +1,8 @@
 export * as charCodes from './char-codes/index.js'
 export * as matches from './matches/index.js'
 export * as normalizeIndent from './normalize-indent/index.js'
-export * as parseTable from './parse-table/index.js'
 export * as replaceAll from './replace-all/index.js'
 export * as toAlphanum from './to-alphanum/index.js'
+export * as parseTable from './parse-table/index.js'
+export * as splitTrim from './split-trim/index.js'
 export * as trim from './trim/index.js'

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