@design-edito/tools 0.4.22 → 0.4.23

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

@@ -0,0 +1,42 @@
+import { type FunctionComponent, type InputHTMLAttributes, type ReactNode } from 'react';
+import type { WithClassName } from '../utils/types.js';
+/**
+ * Props for the {@link Input} component.
+ *
+ * Extends all native {@link InputHTMLAttributes} and {@link WithClassName}
+ * with optional label and error content.
+ *
+ * @property label - Content rendered as an associated `<label>`. When omitted, no label is rendered.
+ * @property error - Content rendered as an error message below the input. When omitted, no error is rendered.
+ * @property className - Additional class name(s) applied to the root element.
+ */
+export type Props = InputHTMLAttributes<HTMLInputElement> & WithClassName<{
+    label?: ReactNode;
+    error?: ReactNode;
+}>;
+/**
+ * Controlled input field component.
+ *
+ * Renders a native `<input>` element with optional label and error feedback.
+ * The input value is entirely driven by the provided `value` prop and all
+ * native input 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`
+ * - `error`
+ *
+ * @param props - Component properties.
+ * @see {@link Props}
+ *
+ * @returns A labelled controlled input with optional error feedback.
+ *
+ * @remarks
+ * - The component does not manage its own value state.
+ * - Consumers are responsible for updating `value` in response to `onChange`.
+ * - Additional `className` values are merged with the component public class name
+ *   and applied to the underlying `<input>` element.
+ */
+export declare const ControlledInput: FunctionComponent<Props>;

package/components/Input/index.controlled.js

@@ -0,0 +1,53 @@
+import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
+import { 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 { input as publicClassName } from '../public-classnames.js';
+import { mergeClassNames } from '../utils/index.js';
+import cssModule from './styles.module.css';
+/**
+ * Controlled input field component.
+ *
+ * Renders a native `<input>` element with optional label and error feedback.
+ * The input value is entirely driven by the provided `value` prop and all
+ * native input 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`
+ * - `error`
+ *
+ * @param props - Component properties.
+ * @see {@link Props}
+ *
+ * @returns A labelled controlled input with optional error feedback.
+ *
+ * @remarks
+ * - The component does not manage its own value state.
+ * - Consumers are responsible for updating `value` in response to `onChange`.
+ * - Additional `className` values are merged with the component public class name
+ *   and applied to the underlying `<input>` element.
+ */
+export const ControlledInput = ({ label, error, value, className, ...rest }) => {
+    const [id] = useState(`_${randomHash(12)}`);
+    const c = clss(publicClassName, { cssModule });
+    const rootClss = mergeClassNames(c(null), className);
+    return _jsxs(_Fragment, { children: [isNotFalsy(label) && _jsx("label", { className: c('label'), htmlFor: id, children: label }), _jsx("input", { ...rest, id: id, className: rootClss, value: value ?? '', onChange: e => {
+                    rest.onChange?.(e);
+                    if (value === undefined)
+                        return;
+                    if (typeof value === 'number') {
+                        e.target.value = `${value}`;
+                    }
+                    else if (typeof value === 'string') {
+                        e.target.value = value;
+                    }
+                    else {
+                        // value is readonly string[]
+                        // not supported for <input>; ignore or normalize if needed
+                    }
+                } }), isNotFalsy(error) && _jsx("span", { className: c('error'), children: error })] });
+};

package/components/Input/index.d.ts

@@ -1,33 +1,37 @@
-import { type FunctionComponent, type InputHTMLAttributes, type ReactNode } from 'react';
-import type { WithClassName } from '../utils/types.js';
+import { type FunctionComponent } from 'react';
+import { type Props as ControlledProps } from './index.controlled.js';
 /**
  * Props for the {@link Input} component.
  *
- * Extends all native {@link InputHTMLAttributes} and {@link WithClassName}
- * with optional label and error content.
+ * Alias of {@link ControlledProps}.
  *
- * @property label - Content rendered as an associated `<label>`. When omitted, no label is rendered.
- * @property error - Content rendered as an error message below the input. When omitted, no error is rendered.
- * @property className - Additional class name(s) applied to the root element.
+ * All native input attributes remain available, including `value`
+ * and `onChange`, allowing the component to operate in either
+ * controlled or hybrid mode.
  */
-export type Props = InputHTMLAttributes<HTMLInputElement> & WithClassName<{
-    label?: ReactNode;
-    error?: ReactNode;
-}>;
+export type Props = ControlledProps;
 /**
- * Input field component with optional label and error message.
+ * Input field component supporting controlled and hybrid usage.
  *
- * Renders a native `<input>` element inside a wrapper, with a stable
- * auto-generated `id` used to associate the label via `htmlFor`.
- * All standard input attributes are forwarded to the underlying element.
+ * Wraps {@link ControlledInput} and automatically manages the input value
+ * when no `value` prop is provided.
  *
  * ### CSS elements
  * - `label`
- * - `input`
  * - `error`
  *
  * @param props - Component properties.
  * @see {@link Props}
- * @returns A labelled input wrapper with optional error feedback.
+ *
+ * @returns A labelled input with optional internal value management.
+ *
+ * @remarks
+ * - When `value` is defined, the component behaves as a controlled component:
+ *   displayed value updates are entirely driven by the parent component.
+ * - When `value` is omitted, the component behaves in hybrid mode:
+ *   it initializes an internal state from the initial `value` prop and
+ *   subsequently manages value updates itself.
+ * - In hybrid mode, the internal value is updated before forwarding
+ *   the `onChange` callback.
  */
 export declare const Input: FunctionComponent<Props>;

package/components/Input/index.js

@@ -1,30 +1,39 @@
-import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
+import { jsx as _jsx } from "react/jsx-runtime";
 import { 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 { input as publicClassName } from '../public-classnames.js';
-import { mergeClassNames } from '../utils/index.js';
-import cssModule from './styles.module.css';
+import { ControlledInput } from './index.controlled.js';
 /**
- * Input field component with optional label and error message.
+ * Input field component supporting controlled and hybrid usage.
  *
- * Renders a native `<input>` element inside a wrapper, with a stable
- * auto-generated `id` used to associate the label via `htmlFor`.
- * All standard input attributes are forwarded to the underlying element.
+ * Wraps {@link ControlledInput} and automatically manages the input value
+ * when no `value` prop is provided.
  *
  * ### CSS elements
  * - `label`
- * - `input`
  * - `error`
  *
  * @param props - Component properties.
  * @see {@link Props}
- * @returns A labelled input wrapper with optional error feedback.
+ *
+ * @returns A labelled input with optional internal value management.
+ *
+ * @remarks
+ * - When `value` is defined, the component behaves as a controlled component:
+ *   displayed value updates are entirely driven by the parent component.
+ * - When `value` is omitted, the component behaves in hybrid mode:
+ *   it initializes an internal state from the initial `value` prop and
+ *   subsequently manages value updates itself.
+ * - In hybrid mode, the internal value is updated before forwarding
+ *   the `onChange` callback.
  */
-export const Input = ({ label, error, className, ...rest }) => {
-    const [id] = useState(`_${randomHash(12)}`);
-    const c = clss(publicClassName, { cssModule });
-    const rootClss = mergeClassNames(c(null), className);
-    return _jsxs(_Fragment, { children: [isNotFalsy(label) && _jsx("label", { className: c('label'), htmlFor: id, children: label }), _jsx("input", { ...rest, className: rootClss, id: id }), isNotFalsy(error) && _jsx("span", { className: c('error'), children: error })] });
+export const Input = (props) => {
+    const { value, defaultValue, onChange, ...rest } = props;
+    const isControlled = value !== undefined;
+    const [internal, setInternal] = useState(defaultValue ?? '');
+    const currentValue = isControlled ? value : internal;
+    const handleChange = (e) => {
+        if (!isControlled)
+            setInternal(e.target.value);
+        onChange?.(e);
+    };
+    return _jsx(ControlledInput, { ...rest, value: currentValue, onChange: handleChange });
 };

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

@@ -0,0 +1,43 @@
+import { type FunctionComponent, type SelectHTMLAttributes, type ReactNode, type PropsWithChildren } from 'react';
+import type { WithClassName } from '../utils/types.js';
+/**
+ * Props for the {@link ControlledSelect} component.
+ *
+ * Extends all native {@link SelectHTMLAttributes} and {@link WithClassName}
+ * with optional label, error content, and option children.
+ *
+ * @property label - Content rendered as an associated `<label>`. When omitted, no label is rendered.
+ * @property error - Content rendered as an error message below the select. When omitted, no error is rendered.
+ * @property className - Additional class name(s) applied to the select element.
+ * @property children - `<option>` or `<optgroup>` elements rendered inside the select.
+ */
+export type Props = SelectHTMLAttributes<HTMLSelectElement> & PropsWithChildren<WithClassName<{
+    label?: ReactNode;
+    error?: ReactNode;
+}>>;
+/**
+ * Controlled select field component.
+ *
+ * Renders a native `<select>` element with optional label and error feedback.
+ * The selected value is entirely driven by the provided `value` prop and all
+ * native select 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`
+ * - `error`
+ *
+ * @param props - Component properties.
+ * @see {@link Props}
+ *
+ * @returns A labelled controlled select with optional error feedback.
+ *
+ * @remarks
+ * - The component does not manage its own selection state.
+ * - Consumers are responsible for updating `value` in response to `onChange`.
+ * - Additional `className` values are merged with the component public class name
+ *   and applied to the underlying `<select>` element.
+ */
+export declare const ControlledSelect: FunctionComponent<Props>;

package/components/Select/index.controlled.js

@@ -0,0 +1,53 @@
+import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
+import { 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 { select as publicClassName } from '../public-classnames.js';
+import { mergeClassNames } from '../utils/index.js';
+import cssModule from './styles.module.css';
+/**
+ * Controlled select field component.
+ *
+ * Renders a native `<select>` element with optional label and error feedback.
+ * The selected value is entirely driven by the provided `value` prop and all
+ * native select 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`
+ * - `error`
+ *
+ * @param props - Component properties.
+ * @see {@link Props}
+ *
+ * @returns A labelled controlled select with optional error feedback.
+ *
+ * @remarks
+ * - The component does not manage its own selection state.
+ * - Consumers are responsible for updating `value` in response to `onChange`.
+ * - Additional `className` values are merged with the component public class name
+ *   and applied to the underlying `<select>` element.
+ */
+export const ControlledSelect = ({ label, error, value, className, children, ...rest }) => {
+    const [id] = useState(`_${randomHash(12)}`);
+    const c = clss(publicClassName, { cssModule });
+    const rootClss = mergeClassNames(c(null), className);
+    return _jsxs(_Fragment, { children: [isNotFalsy(label) && _jsx("label", { className: c('label'), htmlFor: id, children: label }), _jsx("select", { ...rest, className: rootClss, id: id, value: value, onChange: e => {
+                    rest.onChange?.(e);
+                    if (value === undefined)
+                        return;
+                    if (typeof value === 'number') {
+                        e.target.value = `${value}`;
+                    }
+                    else if (typeof value === 'string') {
+                        e.target.value = value;
+                    }
+                    else {
+                        // value is readonly string[]
+                        // not supported for <select>; ignore or normalize if needed
+                    }
+                }, children: children }), isNotFalsy(error) && _jsx("span", { className: c('error'), children: error })] });
+};

package/components/Select/index.d.ts

@@ -1,34 +1,38 @@
-import { type FunctionComponent, type SelectHTMLAttributes, type ReactNode, type PropsWithChildren } from 'react';
-import type { WithClassName } from '../utils/types.js';
+import { type FunctionComponent } from 'react';
+import { type Props as ControlledProps } from './index.controlled.js';
 /**
  * Props for the {@link Select} component.
  *
- * Extends all native {@link SelectHTMLAttributes} and {@link WithClassName}
- * with optional label, error content, and option children.
+ * Alias of {@link ControlledProps}.
  *
- * @property label - Content rendered as an associated `<label>`. When omitted, no label is rendered.
- * @property error - Content rendered as an error message below the select. When omitted, no error is rendered.
- * @property className - Additional class name(s) applied to the root element.
- * @property children - `<option>` or `<optgroup>` elements rendered inside the select.
+ * All native select attributes remain available, including `value`,
+ * `defaultValue`, and `onChange`, allowing the component to operate
+ * in either controlled or hybrid mode.
  */
-export type Props = SelectHTMLAttributes<HTMLSelectElement> & PropsWithChildren<WithClassName<{
-    label?: ReactNode;
-    error?: ReactNode;
-}>>;
+export type Props = ControlledProps;
 /**
- * Select field component with optional label and error message.
+ * Select field component supporting controlled and hybrid usage.
  *
- * Renders a native `<select>` element inside a wrapper, with a stable
- * auto-generated `id` used to associate the label via `htmlFor`.
- * All standard select attributes are forwarded to the underlying element.
+ * Wraps {@link ControlledSelect} and automatically manages the selected
+ * value when no `value` prop is provided.
  *
  * ### CSS elements
  * - `label`
- * - `select`
  * - `error`
  *
  * @param props - Component properties.
  * @see {@link Props}
- * @returns A labelled select wrapper with optional error feedback.
+ *
+ * @returns A labelled select with optional internal selection management.
+ *
+ * @remarks
+ * - In controlled mode (`value` defined), the selected 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 selection 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.
  */
 export declare const Select: FunctionComponent<Props>;

package/components/Select/index.js

@@ -1,30 +1,39 @@
-import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
+import { jsx as _jsx } from "react/jsx-runtime";
 import { 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 { select as publicClassName } from '../public-classnames.js';
-import { mergeClassNames } from '../utils/index.js';
-import cssModule from './styles.module.css';
+import { ControlledSelect } from './index.controlled.js';
 /**
- * Select field component with optional label and error message.
+ * Select field component supporting controlled and hybrid usage.
  *
- * Renders a native `<select>` element inside a wrapper, with a stable
- * auto-generated `id` used to associate the label via `htmlFor`.
- * All standard select attributes are forwarded to the underlying element.
+ * Wraps {@link ControlledSelect} and automatically manages the selected
+ * value when no `value` prop is provided.
  *
  * ### CSS elements
  * - `label`
- * - `select`
  * - `error`
  *
  * @param props - Component properties.
  * @see {@link Props}
- * @returns A labelled select wrapper with optional error feedback.
+ *
+ * @returns A labelled select with optional internal selection management.
+ *
+ * @remarks
+ * - In controlled mode (`value` defined), the selected 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 selection 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.
  */
-export const Select = ({ label, error, className, children, ...rest }) => {
-    const [id] = useState(`_${randomHash(12)}`);
-    const c = clss(publicClassName, { cssModule });
-    const rootClss = mergeClassNames(c(null), className);
-    return _jsxs(_Fragment, { children: [isNotFalsy(label) && _jsx("label", { className: c('label'), htmlFor: id, children: label }), _jsx("select", { ...rest, className: rootClss, id: id, children: children }), isNotFalsy(error) && _jsx("span", { className: c('error'), children: error })] });
+export const Select = ({ defaultValue, value, onChange, ...rest }) => {
+    const isControlled = value !== undefined;
+    const [internal, setInternal] = useState(defaultValue ?? '');
+    const currentValue = isControlled ? value : internal;
+    const handleChange = (e) => {
+        if (!isControlled)
+            setInternal(e.target.value);
+        onChange?.(e);
+    };
+    return _jsx(ControlledSelect, { ...rest, value: currentValue, onChange: handleChange });
 };

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

@@ -0,0 +1,50 @@
+import { type FunctionComponent, type TextareaHTMLAttributes, type ReactNode } from 'react';
+import type { WithClassName } from '../utils/types.js';
+/**
+ * Props for the {@link ControlledTextarea} component.
+ *
+ * Extends all native {@link TextareaHTMLAttributes} and {@link WithClassName}
+ * with optional label, error content, and automatic height adjustment.
+ *
+ * @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`, automatically adjusts the textarea height
+ * to fit its content. Defaults to `false`.
+ * @property className - Additional class name(s) applied to the textarea element.
+ */
+export type Props = TextareaHTMLAttributes<HTMLTextAreaElement> & WithClassName<{
+    label?: ReactNode;
+    error?: ReactNode;
+    autoHeight?: boolean;
+}>;
+/**
+ * Controlled textarea field component.
+ *
+ * Renders a native `<textarea>` element with optional label and error feedback.
+ * The textarea value is entirely driven by the provided `value` prop and all
+ * native 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.
+ *
+ * When `autoHeight` is enabled, the textarea height automatically expands or
+ * shrinks to match its content.
+ *
+ * ### CSS elements
+ * - `label`
+ * - `error`
+ *
+ * @param props - Component properties.
+ * @see {@link Props}
+ *
+ * @returns A labelled controlled textarea with optional error feedback.
+ *
+ * @remarks
+ * - The component does not manage its own value state.
+ * - Consumers are responsible for updating `value` in response to `onChange`.
+ * - Additional `className` values are merged with the component public class name
+ *   and applied to the underlying `<textarea>` element.
+ * - When `autoHeight` is enabled, height recalculation occurs whenever the
+ *   textarea value changes and every 500ms thereafter.
+ */
+export declare const ControlledTextarea: FunctionComponent<Props>;

package/components/Textarea/index.controlled.js

@@ -0,0 +1,74 @@
+import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
+import { useState, useLayoutEffect, useRef } 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 { textarea as publicClassName } from '../public-classnames.js';
+import { mergeClassNames } from '../utils/index.js';
+import cssModule from './styles.module.css';
+/**
+ * Controlled textarea field component.
+ *
+ * Renders a native `<textarea>` element with optional label and error feedback.
+ * The textarea value is entirely driven by the provided `value` prop and all
+ * native 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.
+ *
+ * When `autoHeight` is enabled, the textarea height automatically expands or
+ * shrinks to match its content.
+ *
+ * ### CSS elements
+ * - `label`
+ * - `error`
+ *
+ * @param props - Component properties.
+ * @see {@link Props}
+ *
+ * @returns A labelled controlled textarea with optional error feedback.
+ *
+ * @remarks
+ * - The component does not manage its own value state.
+ * - Consumers are responsible for updating `value` in response to `onChange`.
+ * - Additional `className` values are merged with the component public class name
+ *   and applied to the underlying `<textarea>` element.
+ * - When `autoHeight` is enabled, height recalculation occurs whenever the
+ *   textarea value changes and every 500ms thereafter.
+ */
+export const ControlledTextarea = ({ label, error, autoHeight = false, value, className, ...rest }) => {
+    const [id] = useState(`_${randomHash(12)}`);
+    const textareaRef = useRef(null);
+    // Handlers
+    const adjustHeight = () => {
+        const textarea = textareaRef.current;
+        if (textarea === null)
+            return;
+        textarea.style.height = 'auto';
+        textarea.style.height = `${textarea.scrollHeight}px`;
+    };
+    // Fx. dep `authHeight`, `value` - Compute content height
+    useLayoutEffect(() => {
+        if (!autoHeight)
+            return;
+        adjustHeight();
+    }, [autoHeight, value]);
+    // Rendering
+    const c = clss(publicClassName, { cssModule });
+    const rootClss = mergeClassNames(c(null), className);
+    return _jsxs(_Fragment, { children: [isNotFalsy(label) && _jsx("label", { className: c('label'), htmlFor: id, children: label }), _jsx("textarea", { ...rest, ref: textareaRef, className: rootClss, id: id, value: value, onChange: e => {
+                    rest.onChange?.(e);
+                    if (value === undefined)
+                        return;
+                    if (typeof value === 'number') {
+                        e.target.value = `${value}`;
+                    }
+                    else if (typeof value === 'string') {
+                        e.target.value = value;
+                    }
+                    else {
+                        // value is readonly string[]
+                        // not supported for <select>; ignore or normalize if needed
+                    }
+                } }), isNotFalsy(error) && _jsx("span", { className: c('error'), children: error })] });
+};

package/components/Textarea/index.d.ts

@@ -1,33 +1,38 @@
-import { type FunctionComponent, type TextareaHTMLAttributes, type ReactNode } from 'react';
-import type { WithClassName } from '../utils/types.js';
+import { type FunctionComponent } from 'react';
+import { type Props as ControlledProps } from './index.controlled.js';
 /**
  * Props for the {@link Textarea} component.
  *
- * Extends all native {@link TextareaHTMLAttributes} and {@link WithClassName}
- * with optional label and error content.
+ * Alias of {@link ControlledProps}.
  *
- * @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 className - Additional class name(s) applied to the root element.
+ * All native textarea attributes remain available, including `value`,
+ * `defaultValue`, and `onChange`, allowing the component to operate
+ * in either controlled or hybrid mode.
  */
-export type Props = TextareaHTMLAttributes<HTMLTextAreaElement> & WithClassName<{
-    label?: ReactNode;
-    error?: ReactNode;
-}>;
+export type Props = ControlledProps;
 /**
- * Textarea field component with optional label and error message.
+ * Textarea field component supporting controlled and hybrid usage.
  *
- * Renders a native `<textarea>` element inside a wrapper, with a stable
- * auto-generated `id` used to associate the label via `htmlFor`.
- * All standard textarea attributes are forwarded to the underlying element.
+ * Wraps {@link ControlledTextarea} and automatically manages the textarea
+ * value when no `value` prop is provided.
  *
  * ### CSS elements
  * - `label`
- * - `textarea`
  * - `error`
  *
  * @param props - Component properties.
  * @see {@link Props}
- * @returns A labelled textarea wrapper with optional error feedback.
+ *
+ * @returns A labelled textarea with optional internal value management.
+ *
+ * @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.
  */
 export declare const Textarea: FunctionComponent<Props>;