@design-edito/tools 0.5.1 → 0.5.3

package/components/Sequencer/index.js

@@ -1,43 +1,42 @@
 import { jsx as _jsx } from "react/jsx-runtime";
-import { useState, useEffect, useCallback, Children, useRef } from 'react';
+import { useState, useEffect, useCallback, Children } from 'react';
 import { absoluteModulo } from '../../agnostic/numbers/absolute-modulo/index.js';
 import { clamp } from '../../agnostic/numbers/clamp/index.js';
 import { IntersectionObserverComponent } from '../IntersectionObserver/index.js';
-import { SequencerControlled } from './index.controlled.js';
+import { useChangeDispatch } from '../utils/index.js';
+import { ControlledSequencer } from './index.controlled.js';
 /**
  * Uncontrolled, self-advancing sequencer component. Drives a
- * {@link SequencerControlled} instance with an internal tempo-based interval,
+ * {@link ControlledSequencer} instance with an internal tempo-based interval,
  * optional loop/clamp boundary behaviour, and viewport-driven play/reset triggers
  * via an {@link IntersectionObserverComponent}.
  *
  * Supports mixed controlled/uncontrolled usage: passing `step` disables the
  * internal interval while still applying loop/clamp arithmetic before forwarding
  * to the controlled layer. Passing `play` disables internal play state management
- * while still allowing viewport handlers to fire `actionHandlers.intersected`.
+ * while still allowing viewport handlers to fire `onIntersected`.
  *
- * ### Forwarded modifiers to {@link SequencerControlled}
- * The following `_modifiers` are computed and injected automatically:
- * - `playing` — `true` when the effective play state is active.
- * - `at-start` — `true` when the forwarded step is `0`.
- * - `at-end` — `true` when the forwarded step equals `stepsCount - 1`.
+ * ### Forwarded to {@link ControlledSequencer}
+ * - `step` — the effective step, after loop/clamp arithmetic.
+ * - `isPlaying` — the effective play state, controlled or internal.
+ * - `tempo` — the current tempo, which the controlled layer exposes as `data-tempo`.
  *
- * ### Forwarded data attributes to {@link SequencerControlled}
- * - `data-tempo` — the current `tempo` value.
+ * The `--at-start` and `--at-end` modifiers are derived by the controlled layer
+ * from `step` and the children count.
  *
  * @param props - Component properties.
  * @see {@link Props}
- * @see {@link SequencerControlled}
+ * @see {@link ControlledSequencer}
  * @returns An {@link IntersectionObserverComponent} wrapping a
- * {@link SequencerControlled} with the computed step and modifiers applied.
+ * {@link ControlledSequencer} with the computed step and modifiers applied.
  */
-export const Sequencer = ({ defaultStep, tempo = 60, play, loop, clampFirst, clampLast, resetOnVisible, resetOnHidden, playOnVisible, pauseOnHidden, actionHandlers, stateHandlers, ...controlledProps }) => {
+export const Sequencer = ({ defaultStep, tempo = 60, play, loop, clampFirst, clampLast, resetOnVisible, resetOnHidden, playOnVisible, pauseOnHidden, onIntersected, onIsPlayingChanged, onStepChanged, ...controlledProps }) => {
     // State
     const { step, activateOnStep, children } = controlledProps;
     const [internalPlay, setInternalPlay] = useState(play ?? false);
     const [internalStep, setInternalStep] = useState(step ?? defaultStep ?? 0);
     const actualPlay = play ?? internalPlay;
     const actualStep = step ?? internalStep;
-    const actualPlayRef = useRef(actualPlay);
     // Effects
     useEffect(() => {
         const clampedTempo = Math.max(tempo, 1);
@@ -61,24 +60,15 @@ export const Sequencer = ({ defaultStep, tempo = 60, play, loop, clampFirst, cla
         const rightClamp = clampLast === true ? stepsCount - 1 : Infinity;
         forwardedStep = clamp(actualStep, leftClamp, rightClamp);
     }
-    const forwardedStepRef = useRef(forwardedStep);
-    // State change handlers
-    useEffect(() => {
-        if (actualPlay !== actualPlayRef.current) {
-            actualPlayRef.current = actualPlay;
-            stateHandlers?.isPlaying?.(actualPlay);
-        }
-        if (forwardedStep !== forwardedStepRef.current) {
-            forwardedStepRef.current = forwardedStep;
-            stateHandlers?.stepChanged?.(forwardedStep);
-        }
-    }, [actualPlay, forwardedStep]);
+    // State dispatch
+    useChangeDispatch(actualPlay, onIsPlayingChanged);
+    useChangeDispatch(forwardedStep, onStepChanged);
     // Action handlers
     const handleIntersection = useCallback(({ ioEntry, observer }) => {
+        onIntersected?.({ ioEntry, observer });
         if (play === true || step !== undefined)
             return;
         const { isIntersecting } = ioEntry ?? {};
-        actionHandlers?.intersected?.({ ioEntry, observer });
         if (isIntersecting === true) {
             if (resetOnVisible === true)
                 setInternalStep(0);
@@ -98,12 +88,8 @@ export const Sequencer = ({ defaultStep, tempo = 60, play, loop, clampFirst, cla
         pauseOnHidden,
         play,
         step,
-        actionHandlers
+        onIntersected
     ]);
     // Rendering
-    return _jsx(IntersectionObserverComponent, { onIntersected: handleIntersection, children: _jsx(SequencerControlled, { ...controlledProps, step: forwardedStep, _modifiers: {
-                playing: actualPlay,
-                'at-start': forwardedStep === 0,
-                'at-end': forwardedStep === stepsCount - 1
-            }, _dataAttributes: { tempo } }) });
+    return _jsx(IntersectionObserverComponent, { onIntersected: handleIntersection, children: _jsx(ControlledSequencer, { ...controlledProps, step: forwardedStep, isPlaying: actualPlay, tempo: tempo }) });
 };

package/components/Subtitles/index.d.ts

@@ -1,6 +1,29 @@
 import { type FunctionComponent, type PropsWithChildren } from 'react';
 import type { WithClassName } from '../utils/types.js';
-import type { ParsedSub } from './types.js';
+/**
+ * A single parsed subtitle entry from an SRT file.
+ *
+ * @property id - Sequential subtitle number.
+ * @property start - Start time in milliseconds.
+ * @property end - End time in milliseconds.
+ * @property content - Subtitle text content.
+ */
+export type ParsedSub = {
+    id: number;
+    start?: number;
+    end?: number;
+    content?: string;
+};
+/**
+ * The inclusive ID boundaries of a subtitle group.
+ *
+ * @property startId - ID of the first subtitle in the group.
+ * @property endId - ID of the last subtitle in the group.
+ */
+export type SubGroupBoundaries = {
+    startId: number;
+    endId: number;
+};
 /**
  * Props for the {@link Subtitles} component.
  *
@@ -16,10 +39,11 @@ import type { ParsedSub } from './types.js';
  * @property isEnded - When `true`, forces the last group to be treated as current,
  * regardless of `timecodeMs`. Useful to keep the final subtitle group visible after
  * media playback finishes.
- * @property onLoaded - Callback invoked with the raw SRT string after a successful
- * fetch and parse. Not called when `srtFileContent` is used directly.
- * @property onParsed - Callback invoked with the raw SRT string has been parsed.
- * @property onLoadFailed - Callback invoked with an `Error` if the fetch or parse step fails.
+ * @property onLoaded - Called with the raw SRT string once fetched. Not called
+ * when `srtFileContent` is used directly, since nothing is fetched then.
+ * @property onParsed - Called after the subtitles have been parsed, with the
+ * resulting entries.
+ * @property onLoadFailed - Called with an `Error` when the fetch or the parse fails.
  * @property className - Optional additional class name(s) applied to the root element.
  * @property children - React children rendered inside the root element, after the subtitle groups.
  */

package/components/Subtitles/index.js

@@ -1,12 +1,95 @@
 import { jsx as _jsx } from "react/jsx-runtime";
-import { useCallback, useEffect, useRef, useState } from 'react';
+import { useCallback, useEffect, useState } from 'react';
 import { clss } from '../../agnostic/css/clss/index.js';
 import { toError } from '../../agnostic/misc/cast/index.js';
 import { unknownToString } from '../../agnostic/errors/unknown-to-string/index.js';
-import { mergeClassNames } from '../utils/index.js';
+import { mergeClassNames, useChangeDispatch } from '../utils/index.js';
 import { subtitles as publicClassName } from '../public-classnames.js';
-import { computeSubGroupsWithBoundaries, getCurrentGroup, parseSubs } from './utils.js';
 import cssModule from './styles.module.css';
+/** Converts an SRT timecode (hh:mm:ss,ms) to milliseconds. */
+const getTimecodeToMs = (timecode) => {
+    const [hours = '0', minutes = '0', secondsAndMs = '0,0'] = timecode.split(':');
+    const [seconds = '0', milliseconds = '0'] = secondsAndMs.split(',');
+    let result = parseInt(hours) * 60 * 60 * 1000;
+    result += parseInt(minutes) * 60 * 1000;
+    result += parseInt(seconds) * 1000;
+    result += parseInt(milliseconds);
+    return result;
+};
+/** Parses a raw SRT subtitle text into a list of {@link ParsedSub} entries. */
+const parseSubs = (rawSubs) => {
+    const numberRegex = /^\d+$/v;
+    const timecodeRegex = /^[0-9]+:[0-9]+:[0-9]+,[0-9]+\s*-->\s*[0-9]+:[0-9]+:[0-9]+,[0-9]+$/v;
+    const parsedSubs = [];
+    rawSubs.split('\n').forEach(line => {
+        if (line.trim() === '')
+            return;
+        const lastParsedSub = parsedSubs[parsedSubs.length - 1];
+        const matchId = line.match(numberRegex);
+        const matchTimecode = line.match(timecodeRegex);
+        // id
+        if (matchId !== null) {
+            if (lastParsedSub === undefined
+                || lastParsedSub.content !== undefined) {
+                const parsedSub = { id: parseInt(line) };
+                parsedSubs.push(parsedSub);
+                return;
+            }
+        }
+        // timecode
+        if (matchTimecode !== null) {
+            if (lastParsedSub?.id !== undefined) {
+                const [rawStart = '', rawEnd = ''] = line.split('-->');
+                const startTime = rawStart.trim();
+                const endTime = rawEnd.trim();
+                lastParsedSub.start = getTimecodeToMs(startTime);
+                lastParsedSub.end = getTimecodeToMs(endTime);
+                return;
+            }
+        }
+        // content
+        if (lastParsedSub?.id !== undefined
+            && lastParsedSub.start !== undefined
+            && lastParsedSub.end !== undefined) {
+            if (lastParsedSub.content !== undefined) {
+                lastParsedSub.content += `\n${line}`;
+                return;
+            }
+            lastParsedSub.content = line;
+        }
+    });
+    return parsedSubs;
+};
+/** Computes subtitle groups with their inclusive `startId` / `endId` boundaries. */
+const computeSubGroupsWithBoundaries = (subsGroups, highestSubId) => {
+    const fallback = [{ startId: 1, endId: highestSubId }];
+    if (subsGroups === undefined || subsGroups.length === 0)
+        return fallback;
+    const emptySubGroupBoundaries = [];
+    return subsGroups.reduce((acc, curr, currIndex) => {
+        const lastInAcc = acc[acc.length - 1];
+        const startId = lastInAcc === undefined ? 1 : lastInAcc.endId + 1;
+        const endId = curr;
+        if (currIndex === subsGroups.length - 1
+            && endId !== highestSubId) {
+            return [
+                ...acc,
+                { startId, endId },
+                { startId: endId + 1, endId: highestSubId }
+            ];
+        }
+        return [...acc, { startId, endId }];
+    }, emptySubGroupBoundaries);
+};
+/** Returns the group holding the last elapsed subtitle, or the last group once playback ended. */
+const getCurrentGroup = (subsGroupsWithBoundaries, lastPrevSubId, isEnded) => {
+    const previousGroups = subsGroupsWithBoundaries.filter(group => group.startId <= (lastPrevSubId ?? 0));
+    if (previousGroups.length === 0)
+        return isEnded === true
+            ? subsGroupsWithBoundaries[subsGroupsWithBoundaries.length - 1]
+            : subsGroupsWithBoundaries[0];
+    return previousGroups[previousGroups.length - 1];
+};
 /**
  * Subtitle synchronization component. Fetches or receives an SRT source, parses it,
  * and renders subtitle groups whose individual spans are styled according to the
@@ -34,19 +117,14 @@ export const Subtitles = ({ src, srtFileContent, subsGroups, timecodeMs, isEnded
     const [isLoading, setIsLoading] = useState(false);
     const [loadError, setLoadError] = useState(null);
     const [parsedSubs, setParsedSubs] = useState([]);
-    const pParsedSubs = useRef(parsedSubs);
-    // State change handlers
-    useEffect(() => {
-        if (pParsedSubs.current === parsedSubs)
-            return;
-        onParsed?.(parsedSubs);
-    }, [parsedSubs]);
+    // State dispatch
+    useChangeDispatch(parsedSubs, onParsed);
     // Effects
     const fetchAndParseSubs = useCallback(async (src, srtFileContent) => {
-        if (src === undefined)
-            return;
         if (srtFileContent !== undefined)
             return setParsedSubs(parseSubs(srtFileContent));
+        if (src === undefined)
+            return;
         setIsLoading(true);
         setLoadError(null);
         try {

package/components/Textarea/index.d.ts

@@ -1,20 +1,30 @@
-import { type FunctionComponent } from 'react';
-import { type Props as ControlledProps } from './index.controlled.js';
+import { type FunctionComponent, type ReactNode, type TextareaHTMLAttributes } from 'react';
+import type { WithClassName } from '../utils/types.js';
 /**
  * Props for the {@link Textarea} component.
  *
- * Alias of {@link ControlledProps}.
+ * Extends all native {@link TextareaHTMLAttributes} and {@link WithClassName}
+ * with optional label, error content, and automatic height adjustment.
  *
- * All native textarea attributes remain available, including `value`,
- * `defaultValue`, and `onChange`, allowing the component to operate
- * in either controlled or hybrid mode.
+ * @property label - Content rendered as an associated `<label>`. When omitted, no label is rendered.
+ * @property error - Content rendered as an error message below the textarea. When omitted, no error is rendered.
+ * @property autoHeight - When `true`, grows and shrinks the textarea to fit its
+ * content on every value change. Defaults to `false`.
+ * @property className - Additional class name(s) applied to the textarea element.
  */
-export type Props = ControlledProps;
+export type Props = TextareaHTMLAttributes<HTMLTextAreaElement> & WithClassName<{
+    label?: ReactNode;
+    error?: ReactNode;
+    autoHeight?: boolean;
+}>;
 /**
- * Textarea field component supporting controlled and hybrid usage.
+ * Textarea field supporting controlled and uncontrolled usage.
  *
- * Wraps {@link ControlledTextarea} and automatically manages the textarea
- * value when no `value` prop is provided.
+ * Renders a native `<textarea>` with optional label and error feedback. All
+ * standard textarea attributes are forwarded to the underlying element.
+ *
+ * A stable auto-generated `id` is created on mount and used to associate the
+ * rendered label through the `htmlFor` attribute.
  *
  * ### CSS elements
  * - `label`
@@ -22,17 +32,13 @@ export type Props = ControlledProps;
  *
  * @param props - Component properties.
  * @see {@link Props}
- *
- * @returns A labelled textarea with optional internal value management.
+ * @returns A labelled textarea with optional error feedback.
  *
  * @remarks
- * - In controlled mode (`value` defined), the textarea value is fully driven
- *   by the parent component and internal state is never updated.
- * - In hybrid mode, internal state is initialized from `defaultValue` and
- *   subsequently manages value updates itself.
- * - In hybrid mode, the internal value is updated before forwarding the
- *   `onChange` callback.
- * - `defaultValue` is only used to initialize internal state and is not
- *   forwarded to the underlying controlled component.
+ * - In controlled mode (`value` defined), the displayed value is fully driven
+ *   by the parent and internal state is never updated.
+ * - In uncontrolled mode, internal state is initialized from `defaultValue` and
+ *   updated before `onChange` is forwarded.
+ * - `onChange` fires in both modes.
  */
 export declare const Textarea: FunctionComponent<Props>;

package/components/Textarea/index.js

@@ -1,11 +1,19 @@
-import { jsx as _jsx } from "react/jsx-runtime";
-import { useState } from 'react';
-import { ControlledTextarea } from './index.controlled.js';
+import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
+import { useLayoutEffect, useRef, useState } from 'react';
+import { clss } from '../../agnostic/css/clss/index.js';
+import { isNotFalsy } from '../../agnostic/booleans/is-falsy/index.js';
+import { randomHash } from '../../agnostic/random/uuid/index.js';
+import { mergeClassNames } from '../utils/index.js';
+import { textarea as publicClassName } from '../public-classnames.js';
+import cssModule from './styles.module.css';
 /**
- * Textarea field component supporting controlled and hybrid usage.
+ * Textarea field supporting controlled and uncontrolled usage.
  *
- * Wraps {@link ControlledTextarea} and automatically manages the textarea
- * value when no `value` prop is provided.
+ * Renders a native `<textarea>` with optional label and error feedback. All
+ * standard textarea attributes are forwarded to the underlying element.
+ *
+ * A stable auto-generated `id` is created on mount and used to associate the
+ * rendered label through the `htmlFor` attribute.
  *
  * ### CSS elements
  * - `label`
@@ -13,27 +21,38 @@ import { ControlledTextarea } from './index.controlled.js';
  *
  * @param props - Component properties.
  * @see {@link Props}
- *
- * @returns A labelled textarea with optional internal value management.
+ * @returns A labelled textarea with optional error feedback.
  *
  * @remarks
- * - In controlled mode (`value` defined), the textarea value is fully driven
- *   by the parent component and internal state is never updated.
- * - In hybrid mode, internal state is initialized from `defaultValue` and
- *   subsequently manages value updates itself.
- * - In hybrid mode, the internal value is updated before forwarding the
- *   `onChange` callback.
- * - `defaultValue` is only used to initialize internal state and is not
- *   forwarded to the underlying controlled component.
+ * - In controlled mode (`value` defined), the displayed value is fully driven
+ *   by the parent and internal state is never updated.
+ * - In uncontrolled mode, internal state is initialized from `defaultValue` and
+ *   updated before `onChange` is forwarded.
+ * - `onChange` fires in both modes.
  */
-export const Textarea = ({ defaultValue, value, onChange, ...rest }) => {
+export const Textarea = ({ label, error, autoHeight = false, value, defaultValue, onChange, className, ...rest }) => {
+    // State & refs
+    const [id] = useState(`_${randomHash(12)}`);
+    const [internalValue, setInternalValue] = useState(defaultValue ?? '');
+    const textareaRef = useRef(null);
     const isControlled = value !== undefined;
-    const [internal, setInternal] = useState(defaultValue ?? '');
-    const currentValue = isControlled ? value : internal;
+    const currentValue = isControlled ? value : internalValue;
+    // Fx. dep. `autoHeight`, `currentValue` - fit the height to the content
+    useLayoutEffect(() => {
+        const textarea = textareaRef.current;
+        if (!autoHeight || textarea === null)
+            return;
+        textarea.style.height = 'auto';
+        textarea.style.height = `${textarea.scrollHeight}px`;
+    }, [autoHeight, currentValue]);
+    // User action handlers
     const handleChange = (e) => {
         if (!isControlled)
-            setInternal(e.target.value);
+            setInternalValue(e.target.value);
         onChange?.(e);
     };
-    return _jsx(ControlledTextarea, { ...rest, value: currentValue, onChange: handleChange });
+    // Rendering
+    const c = clss(publicClassName, { cssModule });
+    const rootClss = mergeClassNames(c(), className);
+    return _jsxs(_Fragment, { children: [isNotFalsy(label) && _jsx("label", { className: c('label'), htmlFor: id, children: label }), _jsx("textarea", { ...rest, ref: textareaRef, id: id, className: rootClss, value: currentValue, onChange: handleChange }), isNotFalsy(error) && _jsx("span", { className: c('error'), children: error })] });
 };

package/components/Theatre/index.d.ts

@@ -3,23 +3,24 @@ import type { WithClassName } from '../utils/types.js';
 /**
  * Props for the {@link Theatre} component.
  *
- * @property closeBtnContent - Custom content rendered inside the close/exit button.
- * @property openBtnContent - Custom content rendered inside the open/enter button.
- * @property isOn - Controlled theatre mode state. When provided, overrides the
- * internal state. Use together with {@link Props.onToggleClick} for fully
- * controlled usage.
- * @property defaultIsOn - Default state for the theatre mode.
- * @property exitOnEscape — When uncontrolled and on, toggles internal state to off when 'esc' key is pressed
- * @property exitOnBgClick — When uncontrolled and on, toggles internal state to off when the background is clicked
- * @property stateHandlers - Callbacks called after the internal state changed
- * @property stateHandlers.toggled - Callback invoked after the state changed
- * @property actionHandlers - Callbacks called after a user action on children elements
- * @property actionHandlers.toggleClick - Callback invoked when either the open or close
- * button is clicked, the 'esc' key pressed or the background clicked. Receives the theatre state value (`isOn`) at the time of the click,
- * i.e. the previous state before the toggle.
+ * @property closeBtnContent - Content rendered inside the close/exit button.
+ * @property openBtnContent - Content rendered inside the open/enter button.
+ * @property isOn - Controlled theatre mode state. When defined, the component
+ * behaves as a controlled component and internal state is never updated.
+ * @property defaultIsOn - Initial theatre mode state in uncontrolled mode.
+ * Ignored when `isOn` is provided. Defaults to `false`.
+ * @property exitOnEscape - When `true`, pressing `Escape` while the stage is
+ * open counts as a toggle.
+ * @property exitOnBgClick - When `true`, clicking the stage background — and
+ * not its content — counts as a toggle.
+ * @property onToggleClicked - Called whenever a toggle is requested: the open
+ * or close button, the `Escape` key, or the stage background. Fires before the
+ * theatre reacts, with the state as it was.
+ * @property onIsOnChanged - Called after the theatre mode changed, with the new
+ * value.
  * @property className - Optional additional class name(s) applied to the root element.
- * @property children - Content rendered both in the default slot and, when theatre
- * mode is active, duplicated inside the stage element.
+ * @property children - Content rendered both in the default slot and, when
+ * theatre mode is active, duplicated inside the stage element.
  */
 export type Props = PropsWithChildren<WithClassName<{
     closeBtnContent?: ReactNode;
@@ -28,37 +29,32 @@ export type Props = PropsWithChildren<WithClassName<{
     defaultIsOn?: boolean;
     exitOnEscape?: boolean;
     exitOnBgClick?: boolean;
-    stateHandlers?: {
-        toggled?: (isOn: boolean) => void;
-    };
-    actionHandlers?: {
-        toggleClick?: (prevIsOn: boolean) => void;
-    };
+    onToggleClicked?: (isOn: boolean) => void;
+    onIsOnChanged?: (isOn: boolean) => void;
 }>>;
 /**
  * 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 declare const Theatre: FunctionComponent<Props>;