@design-edito/tools 0.5.1 → 0.5.3

package/components/BeforeAfter/index.controlled.js

@@ -9,15 +9,14 @@ import cssModule from './styles.module.css';
 /**
  * Controlled before/after comparison component.
  *
- * Renders two content panels separated by a draggable divider whose position
- * is expressed as a ratio between `0` and `1`. Supports both mouse and touch
- * interactions, distinguishing clicks from drags.
+ * Renders two content panels separated by a divider whose position is expressed
+ * as a ratio between `0` and `1`. Handles both mouse and touch input, telling a
+ * click apart from a drag.
  *
  * The active ratio is exposed as:
- * - CSS custom properties:
- *   - `--{prefix}-ratio`
- *   - `--{prefix}-ratio-percent`
- * - A `data-ratio` attribute on the root element.
+ * - CSS custom properties `--lm-before-after-ratio` and
+ * `--lm-before-after-ratio-percent`,
+ * - a `data-ratio` attribute on the root element.
  *
  * ### CSS modifiers
  * - `horizontal` — applied when `mode` is `'horizontal'`.
@@ -26,14 +25,18 @@ import cssModule from './styles.module.css';
  * ### CSS elements
  * - `before`
  * - `after`
+ * - `separator`
  *
  * @param props - Component properties.
  * @see {@link Props}
- * @returns A split-panel container with pointer interaction handlers and ratio state applied.
+ * @returns A split-panel container reporting pointer interactions as ratios.
+ *
+ * @remarks
+ * The component holds no ratio state: it only reports where the pointer is, and
+ * renders whatever `ratio` it is given. Turning one into the other is the
+ * uncontrolled wrapper's job.
  */
-export const BeforeAfterControlled = ({ mode = 'horizontal', ratio = 0, before, after, className, children, actionHandlers }) => {
-    // eslint-disable-next-line no-param-reassign
-    ratio = clamp(ratio, 0, 1);
+export const ControlledBeforeAfter = ({ mode = 'horizontal', ratio = 0, before, after, className, children, onDragged, onClicked }) => {
     // State & refs
     const rootRef = useRef(null);
     const isPointerDown = useRef(false);
@@ -48,71 +51,62 @@ export const BeforeAfterControlled = ({ mode = 'horizontal', ratio = 0, before,
             yRatio: (clientY - rect.top) / rect.height
         };
     };
-    // Handlers
-    const handleMouseDown = event => {
+    const reportDrag = (clientX, clientY) => {
+        const ratios = getRatios(clientX, clientY);
+        if (ratios !== null)
+            onDragged?.(ratios.xRatio, ratios.yRatio);
+    };
+    const reportClick = (clientX, clientY) => {
+        const ratios = getRatios(clientX, clientY);
+        if (ratios !== null)
+            onClicked?.(ratios.xRatio, ratios.yRatio);
+    };
+    // User action handlers
+    const handlePointerDown = () => {
         isPointerDown.current = true;
         hasDragged.current = false;
     };
+    const handlePointerUp = () => {
+        isPointerDown.current = false;
+        hasDragged.current = false;
+    };
     const handleMouseMove = event => {
         if (!isPointerDown.current)
             return;
         hasDragged.current = true;
-        const ratios = getRatios(event.clientX, event.clientY);
-        if (ratios !== null)
-            actionHandlers?.dragged?.(ratios.xRatio, ratios.yRatio);
+        reportDrag(event.clientX, event.clientY);
     };
     const handleMouseUp = event => {
-        if (!hasDragged.current) {
-            const ratios = getRatios(event.clientX, event.clientY);
-            if (ratios !== null)
-                actionHandlers?.clicked?.(ratios.xRatio, ratios.yRatio);
-        }
-        isPointerDown.current = false;
-        hasDragged.current = false;
-    };
-    const handleTouchStart = event => {
-        isPointerDown.current = true;
-        hasDragged.current = false;
+        if (!hasDragged.current)
+            reportClick(event.clientX, event.clientY);
+        handlePointerUp();
     };
     const handleTouchMove = event => {
-        const t = event.touches[0];
-        if (t === undefined)
+        const touch = event.touches[0];
+        if (touch === undefined)
             return;
         if (!isPointerDown.current)
             return;
         hasDragged.current = true;
-        const ratios = getRatios(t.clientX, t.clientY);
-        if (ratios !== null)
-            actionHandlers?.dragged?.(ratios.xRatio, ratios.yRatio);
+        reportDrag(touch.clientX, touch.clientY);
     };
     const handleTouchEnd = event => {
-        if (!hasDragged.current) {
-            const t = event.changedTouches[0];
-            if (t !== undefined) {
-                const ratios = getRatios(t.clientX, t.clientY);
-                if (ratios !== null)
-                    actionHandlers?.clicked?.(ratios.xRatio, ratios.yRatio);
-            }
-        }
-        isPointerDown.current = false;
-        hasDragged.current = false;
+        const touch = event.changedTouches[0];
+        if (!hasDragged.current && touch !== undefined)
+            reportClick(touch.clientX, touch.clientY);
+        handlePointerUp();
     };
-    // Classes & attributes
+    // Rendering
+    const clampedRatio = clamp(ratio, 0, 1);
     const c = clss(publicClassName, { cssModule });
     const rootClss = mergeClassNames(c(null, {
         horizontal: mode === 'horizontal',
         vertical: mode === 'vertical'
     }), className);
-    const beforeClass = c('before');
-    const afterClass = c('after');
-    const separatorClass = c('separator');
+    const roundedRatio = round(clampedRatio, 4);
     const customProps = {
-        [`--${publicClassName}-ratio`]: `${round(ratio, 4)}`,
-        [`--${publicClassName}-ratio-percent`]: `${round(ratio * 100, 2)}%`
+        '--lm-before-after-ratio': `${roundedRatio}`,
+        '--lm-before-after-ratio-percent': `${round(clampedRatio * 100, 2)}%`
     };
-    const dataAttributes = {
-        'data-ratio': `${round(ratio, 4)}`
-    };
-    // Rendering
-    return _jsxs("div", { ref: rootRef, className: rootClss, onMouseDown: handleMouseDown, onMouseMove: handleMouseMove, onMouseUp: handleMouseUp, onTouchStart: handleTouchStart, onTouchMove: handleTouchMove, onTouchEnd: handleTouchEnd, style: { ...customProps }, ...dataAttributes, children: [_jsx("div", { className: beforeClass, children: before }), _jsx("div", { className: afterClass, children: after }), _jsx("div", { className: separatorClass }), children] });
+    return _jsxs("div", { ref: rootRef, className: rootClss, onMouseDown: handlePointerDown, onMouseMove: handleMouseMove, onMouseUp: handleMouseUp, onTouchStart: handlePointerDown, onTouchMove: handleTouchMove, onTouchEnd: handleTouchEnd, style: { ...customProps }, "data-ratio": roundedRatio, children: [_jsx("div", { className: c('before'), children: before }), _jsx("div", { className: c('after'), children: after }), _jsx("div", { className: c('separator') }), children] });
 };

package/components/BeforeAfter/index.d.ts

@@ -3,39 +3,36 @@ import { type Props as ControlledProps } from './index.controlled.js';
 /**
  * Props for the {@link BeforeAfter} component.
  *
- * Extends {@link ControlledProps} with uncontrolled defaults and state callbacks.
- * When `ratio` is provided (inherited from {@link ControlledProps}), the component
- * operates in controlled mode and internal state is ignored.
+ * Extends {@link ControlledProps} with uncontrolled divider positioning. When
+ * `ratio` is provided, the component operates in controlled mode.
  *
- * @property defaultRatio - Initial divider position in uncontrolled mode, as a value
+ * @property defaultRatio - Initial divider position in uncontrolled mode,
  * between `0` and `1`. Ignored when `ratio` is provided. Defaults to `0.5`.
- * @property stateHandlers - Optional callbacks invoked when derived state changes:
- *   - `ratioChanged` — called after the internal ratio has been updated, with the new ratio value.
+ * @property onRatioChanged - Called after the divider position changed, with the
+ * new ratio.
  */
 export type Props = ControlledProps & {
     defaultRatio?: number;
-    stateHandlers?: {
-        ratioChanged?: (ratio: number) => void;
-    };
+    onRatioChanged?: (ratio: number) => void;
 };
 /**
- * Before/after comparison component with optional controlled and uncontrolled behavior.
+ * Before/after comparison component supporting controlled and uncontrolled usage.
  *
- * Wraps {@link BeforeAfterControlled} and manages internal divider position when
- * operating in uncontrolled mode. The active axis used to derive the ratio from
- * pointer position depends on `mode`: horizontal interactions use the x ratio,
- * vertical interactions use the y ratio.
- *
- * @remarks
- * - In controlled mode (`ratio` defined), divider position is fully driven by the prop
- *   and internal state is never updated.
- * - In uncontrolled mode, internal state is initialized from `defaultRatio` and updated
- *   on both drag and click interactions.
- * - `actionHandlers.dragged` and `actionHandlers.clicked` are always forwarded to the
- *   underlying controlled component, regardless of mode.
+ * Turns the pointer ratios reported by {@link ControlledBeforeAfter} into a
+ * divider position, reading the axis that matches `mode`: the x ratio when
+ * horizontal, the y ratio when vertical.
  *
  * @param props - Component properties.
  * @see {@link Props}
- * @returns A {@link BeforeAfterControlled} instance with ratio state managed internally when uncontrolled.
+ * @see {@link ControlledBeforeAfter} for the rendered markup and CSS elements.
+ * @returns A {@link ControlledBeforeAfter} with the divider position managed
+ * internally when uncontrolled.
+ *
+ * @remarks
+ * - In controlled mode (`ratio` defined), the divider position is fully driven
+ *   by the parent and internal state is never updated.
+ * - `onDragged` and `onClicked` fire in both modes — a controlled parent needs
+ *   them to know where the pointer went.
+ * - `onRatioChanged` fires in both modes too, and never on mount.
  */
 export declare const BeforeAfter: FunctionComponent<Props>;

package/components/BeforeAfter/index.js

@@ -1,54 +1,62 @@
 import { jsx as _jsx } from "react/jsx-runtime";
 import { useState } from 'react';
-import { BeforeAfterControlled } from './index.controlled.js';
+import { useChangeDispatch } from '../utils/index.js';
+import { ControlledBeforeAfter } from './index.controlled.js';
 /**
- * Before/after comparison component with optional controlled and uncontrolled behavior.
- *
- * Wraps {@link BeforeAfterControlled} and manages internal divider position when
- * operating in uncontrolled mode. The active axis used to derive the ratio from
- * pointer position depends on `mode`: horizontal interactions use the x ratio,
- * vertical interactions use the y ratio.
+ * Pointer ratios are stretched by this much on each side before becoming the
+ * divider position, so the very edges stay reachable without having to land the
+ * pointer exactly on the component's border.
+ */
+const edgeOvershoot = 0.01;
+/** Turns a raw pointer ratio into a divider position, edges included. */
+function toDividerRatio(pointerRatio) {
+    return pointerRatio * (1 + 2 * edgeOvershoot) - edgeOvershoot;
+}
+/**
+ * Before/after comparison component supporting controlled and uncontrolled usage.
  *
- * @remarks
- * - In controlled mode (`ratio` defined), divider position is fully driven by the prop
- *   and internal state is never updated.
- * - In uncontrolled mode, internal state is initialized from `defaultRatio` and updated
- *   on both drag and click interactions.
- * - `actionHandlers.dragged` and `actionHandlers.clicked` are always forwarded to the
- *   underlying controlled component, regardless of mode.
+ * Turns the pointer ratios reported by {@link ControlledBeforeAfter} into a
+ * divider position, reading the axis that matches `mode`: the x ratio when
+ * horizontal, the y ratio when vertical.
  *
  * @param props - Component properties.
  * @see {@link Props}
- * @returns A {@link BeforeAfterControlled} instance with ratio state managed internally when uncontrolled.
+ * @see {@link ControlledBeforeAfter} for the rendered markup and CSS elements.
+ * @returns A {@link ControlledBeforeAfter} with the divider position managed
+ * internally when uncontrolled.
+ *
+ * @remarks
+ * - In controlled mode (`ratio` defined), the divider position is fully driven
+ *   by the parent and internal state is never updated.
+ * - `onDragged` and `onClicked` fire in both modes — a controlled parent needs
+ *   them to know where the pointer went.
+ * - `onRatioChanged` fires in both modes too, and never on mount.
  */
-export const BeforeAfter = ({ mode = 'horizontal', actionHandlers, stateHandlers, ratio, defaultRatio = 0.5, ...controlledProps }) => {
+export const BeforeAfter = ({ mode = 'horizontal', ratio, defaultRatio = 0.5, onDragged, onClicked, onRatioChanged, ...controlledProps }) => {
+    // State
     const [internalRatio, setInternalRatio] = useState(defaultRatio);
     const isControlled = ratio !== undefined;
     const effectiveRatio = isControlled ? ratio : internalRatio;
-    const handleDrag = (x, y) => {
-        // eslint-disable-next-line no-param-reassign
-        x = 1.02 * x - 0.01;
-        // eslint-disable-next-line no-param-reassign
-        y = 1.02 * y - 0.01;
-        actionHandlers?.dragged?.(x, y);
-        if (!isControlled) {
-            setInternalRatio(mode === 'horizontal' ? x : y);
-            stateHandlers?.ratioChanged?.(mode === 'horizontal' ? x : y);
-        }
+    // State dispatch
+    useChangeDispatch(effectiveRatio, onRatioChanged);
+    // User action handlers
+    const moveDividerTo = (xRatio, yRatio) => {
+        if (isControlled)
+            return;
+        setInternalRatio(mode === 'horizontal' ? xRatio : yRatio);
+    };
+    const handleDrag = (xRatio, yRatio) => {
+        const x = toDividerRatio(xRatio);
+        const y = toDividerRatio(yRatio);
+        onDragged?.(x, y);
+        moveDividerTo(x, y);
     };
-    const handleClick = (x, y) => {
-        // eslint-disable-next-line no-param-reassign
-        x = 1.02 * x - 0.01;
-        // eslint-disable-next-line no-param-reassign
-        y = 1.02 * y - 0.01;
-        actionHandlers?.clicked?.(x, y);
-        if (!isControlled) {
-            setInternalRatio(mode === 'horizontal' ? x : y);
-            stateHandlers?.ratioChanged?.(mode === 'horizontal' ? x : y);
-        }
+    const handleClick = (xRatio, yRatio) => {
+        const x = toDividerRatio(xRatio);
+        const y = toDividerRatio(yRatio);
+        onClicked?.(x, y);
+        moveDividerTo(x, y);
     };
-    return _jsx(BeforeAfterControlled, { ...controlledProps, mode: mode, ratio: effectiveRatio, actionHandlers: {
-            dragged: handleDrag,
-            clicked: handleClick
-        } });
+    // Rendering
+    return _jsx(ControlledBeforeAfter, { ...controlledProps, mode: mode, ratio: effectiveRatio, onDragged: handleDrag, onClicked: handleClick });
 };

package/components/Button/index.js

@@ -15,6 +15,6 @@ import cssModule from './styles.module.css';
  */
 export const Button = ({ className, ...rest }) => {
     const c = clss(publicClassName, { cssModule });
-    const rootClss = mergeClassNames(c(null), className);
+    const rootClss = mergeClassNames(c(), className);
     return _jsx("button", { ...rest, className: rootClss });
 };

package/components/Clippable/index.d.ts

@@ -3,40 +3,27 @@ import type { WithClassName } from '../utils/types.js';
 /**
  * Props for the {@link Clippable} component.
  *
- * Extends {@link WithClassName} with clipboard-related configuration and callbacks.
- *
- * @property toClip - Content written to the clipboard. When omitted, the current
- * content container's `innerHTML` is used. A function may be provided to transform
- * the current content before it is written.
- * @property actionHandlers - Optional user action callbacks:
- *   - `clicked` — called when the copy button is clicked, before clipboard content is resolved.
- * @property stateHandlers - Optional callbacks invoked when derived state changes:
- *   - `clipped` — called after content has been successfully written to the clipboard.
+ * @property toClip - Content written to the clipboard. When omitted, the
+ * content container's `innerHTML` is used. A function may be provided to
+ * transform that current content before it is written.
+ * @property onCopyClicked - Called when the copy button is clicked, before the
+ * clipboard content is resolved, with the container's raw HTML.
+ * @property onClipped - Called once content has been written to the clipboard.
+ * Not called when the write fails.
  * @property className - Additional class name(s) applied to the root element.
  * @property children - Content rendered inside the copyable container.
  */
 export type Props = PropsWithChildren<WithClassName<{
     toClip?: string | ((curr: string | undefined) => string | undefined);
-    actionHandlers?: {
-        clicked?: (e: MouseEvent<HTMLButtonElement, globalThis.MouseEvent>, rawContent: string | undefined) => void;
-    };
-    stateHandlers?: {
-        clipped?: (content: string) => void;
-    };
+    onCopyClicked?: (e: MouseEvent<HTMLButtonElement, globalThis.MouseEvent>, rawContent: string | undefined) => void;
+    onClipped?: (content: string) => void;
 }>>;
 /**
- * Clipboard-enabled container component.
- *
- * Renders arbitrary content alongside a copy control. When activated,
- * the component writes HTML content to the clipboard using the
- * `text/html` MIME type.
- *
- * Supports content overriding and transformation through the `toClip`
- * prop, as well as action and state callbacks.
+ * Clipboard-enabled container. Renders arbitrary content alongside a copy
+ * control that writes it to the clipboard, as both `text/html` and `text/plain`.
  *
  * ### CSS modifiers
- * The following modifiers are applied automatically:
- * - `clipped` — `true` during the 3 seconds following a successful clipboard write.
+ * - `clipped` — on during the 3 seconds following a successful write.
  *
  * ### CSS elements
  * - `copy`
@@ -44,6 +31,10 @@ export type Props = PropsWithChildren<WithClassName<{
  *
  * @param props - Component properties.
  * @see {@link Props}
- * @returns A copy-enabled content container with clipboard state modifiers applied.
+ * @returns A copy-enabled content container.
+ *
+ * @remarks
+ * A failed clipboard write is logged and leaves the component untouched:
+ * neither `onClipped` nor the `clipped` modifier fires.
  */
 export declare const Clippable: FunctionComponent<Props>;

package/components/Clippable/index.js

@@ -4,19 +4,14 @@ import { clss } from '../../agnostic/css/clss/index.js';
 import { mergeClassNames } from '../utils/index.js';
 import { clippable as publicClassName } from '../public-classnames.js';
 import cssModule from './styles.module.css';
+/** How long the `clipped` modifier stays on after a successful write. */
+const clippedModifierDurationMs = 3000;
 /**
- * Clipboard-enabled container component.
- *
- * Renders arbitrary content alongside a copy control. When activated,
- * the component writes HTML content to the clipboard using the
- * `text/html` MIME type.
- *
- * Supports content overriding and transformation through the `toClip`
- * prop, as well as action and state callbacks.
+ * Clipboard-enabled container. Renders arbitrary content alongside a copy
+ * control that writes it to the clipboard, as both `text/html` and `text/plain`.
  *
  * ### CSS modifiers
- * The following modifiers are applied automatically:
- * - `clipped` — `true` during the 3 seconds following a successful clipboard write.
+ * - `clipped` — on during the 3 seconds following a successful write.
  *
  * ### CSS elements
  * - `copy`
@@ -24,22 +19,26 @@ import cssModule from './styles.module.css';
  *
  * @param props - Component properties.
  * @see {@link Props}
- * @returns A copy-enabled content container with clipboard state modifiers applied.
+ * @returns A copy-enabled content container.
+ *
+ * @remarks
+ * A failed clipboard write is logged and leaves the component untouched:
+ * neither `onClipped` nor the `clipped` modifier fires.
  */
-export const Clippable = ({ className, children, toClip, actionHandlers, stateHandlers }) => {
+export const Clippable = ({ className, children, toClip, onCopyClicked, onClipped }) => {
     // State & refs
-    const [beenRecentlyClipped, setBeenRecentlyClipped] = useState(false);
+    const [hasBeenRecentlyClipped, setHasBeenRecentlyClipped] = useState(false);
     const contentRef = useRef(null);
     const clippedTimeoutRef = useRef(null);
     // User action handlers
     const handleCopyClick = async (e) => {
-        const rawhHtml = contentRef.current?.innerHTML;
-        actionHandlers?.clicked?.(e, rawhHtml);
+        const rawHtml = contentRef.current?.innerHTML;
+        onCopyClicked?.(e, rawHtml);
         const html = typeof toClip === 'string'
             ? toClip
             : typeof toClip === 'function'
-                ? toClip(rawhHtml)
-                : rawhHtml;
+                ? toClip(rawHtml)
+                : rawHtml;
         if (html === undefined)
             return;
         try {
@@ -53,19 +52,18 @@ export const Clippable = ({ className, children, toClip, actionHandlers, stateHa
         catch (err) {
             // eslint-disable-next-line no-console
             console.error(err);
+            return;
         }
-        stateHandlers?.clipped?.(html);
-        setBeenRecentlyClipped(true);
+        onClipped?.(html);
+        setHasBeenRecentlyClipped(true);
         if (clippedTimeoutRef.current !== null)
             clearTimeout(clippedTimeoutRef.current);
-        clippedTimeoutRef.current = setTimeout(() => {
-            setBeenRecentlyClipped(false);
-        }, 3000);
+        clippedTimeoutRef.current = setTimeout(() => setHasBeenRecentlyClipped(false), clippedModifierDurationMs);
     };
     // Rendering
     const c = clss(publicClassName, { cssModule });
     const rootClss = mergeClassNames(c(null, {
-        clipped: beenRecentlyClipped
+        clipped: hasBeenRecentlyClipped
     }), className);
     const copyClss = c('copy');
     const contentClss = c('content');

package/components/Disclaimer/index.d.ts

@@ -1,45 +1,52 @@
 import { type ReactNode, type PropsWithChildren, type FunctionComponent } from 'react';
 import type { WithClassName } from '../utils/types.js';
 /**
- * Props for the Disclaimer component.
+ * Props for the {@link Disclaimer} component.
  *
  * @property content - Content displayed inside the disclaimer panel.
  * @property togglerContent - Content rendered inside the dismiss toggler.
- * If not provided, the toggler is not rendered.
- * @property isOn - Controls the visibility state. When defined, the component
- * behaves as a controlled component.
- * @property defaultIsOn - Default visibility state for uncontrolled mode.
- * @property stateHandlers - Callbacks invoked after state changes.
- * @property stateHandlers.toggled - Callback invoked after the disclaimer state changes.
- * @property actionHandlers - Callbacks invoked before actions are committed.
- * @property actionHandlers.dismissClick - Callback invoked before the disclaimer is dismissed.
+ * When omitted, the toggler is not rendered.
+ * @property isOn - Controlled visibility state. When defined, the component
+ * behaves as a controlled component and internal state is never updated.
+ * @property defaultIsOn - Initial visibility state in uncontrolled mode.
+ * Ignored when `isOn` is provided. Defaults to `true`.
+ * @property onDismissClicked - Called when the toggler is clicked, before the
+ * disclaimer reacts, with the visibility state as it was.
+ * @property onIsOnChanged - Called after the visibility state changed, with the
+ * new value.
  * @property className - Optional additional class name(s) applied to the root element.
- * @property children - Additional content rendered below the disclaimer panel.
+ * @property children - The content the disclaimer gates, rendered below the panel.
  */
 export type Props = PropsWithChildren<WithClassName<{
     content?: ReactNode;
     togglerContent?: ReactNode;
     isOn?: boolean;
     defaultIsOn?: boolean;
-    stateHandlers?: {
-        toggled?: (isOn: boolean) => void;
-    };
-    actionHandlers?: {
-        dismissClick?: (prevIsOn: boolean) => void;
-    };
+    onDismissClicked?: (isOn: boolean) => void;
+    onIsOnChanged?: (isOn: boolean) => void;
 }>>;
 /**
- * Component that displays a dismissible disclaimer panel.
+ * Dismissible disclaimer panel, gating the content it wraps.
  *
- * Supports both controlled (`isOn` provided) and uncontrolled modes.
+ * ### CSS modifiers
+ * - `on` — the disclaimer is showing.
+ * - `off` — the disclaimer has been dismissed.
+ *
+ * ### CSS elements
+ * - `panel`
+ * - `content`
+ * - `toggler`
+ * - `sensitive` — wraps `children`.
  *
  * @param props - Component properties.
  * @see {@link Props}
+ * @returns A root `<div>` holding the disclaimer panel and the gated content.
  *
  * @remarks
- * - In controlled mode, visibility is driven by `isOn` and internal state
- *   does not toggle automatically.
- * - In uncontrolled mode, the component manages its own visibility state.
- * - Applies `on` and `off` modifier classes depending on visibility state.
+ * - In controlled mode (`isOn` defined), visibility is fully driven by the
+ *   parent and internal state is never updated.
+ * - `onDismissClicked` fires in both modes — a controlled parent needs it to
+ *   know a click happened at all.
+ * - `onIsOnChanged` fires in both modes too, and never on mount.
  */
 export declare const Disclaimer: FunctionComponent<Props>;

package/components/Disclaimer/index.js

@@ -1,39 +1,44 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { useState, useEffect, useRef } from 'react';
+import { useState } from 'react';
 import { clss } from '../../agnostic/css/clss/index.js';
-import { mergeClassNames } from '../utils/index.js';
+import { mergeClassNames, useChangeDispatch } from '../utils/index.js';
 import { disclaimer as publicClassName } from '../public-classnames.js';
 import cssModule from './styles.module.css';
 /**
- * Component that displays a dismissible disclaimer panel.
+ * Dismissible disclaimer panel, gating the content it wraps.
  *
- * Supports both controlled (`isOn` provided) and uncontrolled modes.
+ * ### CSS modifiers
+ * - `on` — the disclaimer is showing.
+ * - `off` — the disclaimer has been dismissed.
+ *
+ * ### CSS elements
+ * - `panel`
+ * - `content`
+ * - `toggler`
+ * - `sensitive` — wraps `children`.
  *
  * @param props - Component properties.
  * @see {@link Props}
+ * @returns A root `<div>` holding the disclaimer panel and the gated content.
  *
  * @remarks
- * - In controlled mode, visibility is driven by `isOn` and internal state
- *   does not toggle automatically.
- * - In uncontrolled mode, the component manages its own visibility state.
- * - Applies `on` and `off` modifier classes depending on visibility state.
+ * - In controlled mode (`isOn` defined), visibility is fully driven by the
+ *   parent and internal state is never updated.
+ * - `onDismissClicked` fires in both modes — a controlled parent needs it to
+ *   know a click happened at all.
+ * - `onIsOnChanged` fires in both modes too, and never on mount.
  */
-export const Disclaimer = ({ content, togglerContent, isOn: isOnProp, defaultIsOn: defaultIsOnProp, stateHandlers, actionHandlers, children, className }) => {
-    // State & refs
-    const [internalIsOn, setInternalIsOn] = useState(isOnProp ?? defaultIsOnProp ?? true);
+export const Disclaimer = ({ content, togglerContent, isOn: isOnProp, defaultIsOn = true, onDismissClicked, onIsOnChanged, children, className }) => {
+    // State
+    const [internalIsOn, setInternalIsOn] = useState(defaultIsOn);
+    const isControlled = isOnProp !== undefined;
     const isOn = isOnProp ?? internalIsOn;
-    const pIsOn = useRef(isOn);
-    // State change handlers
-    useEffect(() => {
-        if (pIsOn.current === isOn)
-            return;
-        stateHandlers?.toggled?.(isOn);
-        pIsOn.current = isOn;
-    }, [isOn]);
-    // User actions handlers
+    // State dispatch
+    useChangeDispatch(isOn, onIsOnChanged);
+    // User action handlers
     const handleDismissClick = () => {
-        actionHandlers?.dismissClick?.(isOn);
-        if (isOnProp !== undefined)
+        onDismissClicked?.(isOn);
+        if (isControlled)
             return;
         setInternalIsOn(false);
     };
@@ -45,7 +50,7 @@ export const Disclaimer = ({ content, togglerContent, isOn: isOnProp, defaultIsO
     }), className);
     const panelClss = c('panel');
     const contentClss = c('content');
-    const btnClss = c('toggler');
+    const togglerClss = c('toggler');
     const sensitiveClss = c('sensitive');
-    return _jsxs("div", { className: rootClss, children: [_jsxs("div", { className: panelClss, children: [content !== undefined && _jsx("div", { className: contentClss, children: content }), togglerContent !== undefined && _jsx("div", { className: btnClss, onClick: handleDismissClick, children: togglerContent })] }), _jsx("div", { className: sensitiveClss, children: children })] });
+    return _jsxs("div", { className: rootClss, children: [_jsxs("div", { className: panelClss, children: [content !== undefined && _jsx("div", { className: contentClss, children: content }), togglerContent !== undefined && _jsx("div", { className: togglerClss, onClick: handleDismissClick, children: togglerContent })] }), _jsx("div", { className: sensitiveClss, children: children })] });
 };