@design-edito/tools 0.5.2 → 0.5.3

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

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}