@design-edito/tools 0.5.2 → 0.5.3

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 })] });
 };

package/components/Drawer/index.d.ts

@@ -1,45 +1,65 @@
 import { type PropsWithChildren, type FunctionComponent, type ReactNode } from 'react';
 import type { WithClassName } from '../utils/types.js';
 /**
- * Props for the Drawer component.
+ * Props for the {@link Drawer} component.
  *
  * @property openerContent - Content rendered inside the opener control.
  * @property closerContent - Content rendered inside the closer control.
- * @property initialIsOpened - Initial open state in uncontrolled mode.
- * Ignored when `isOpened` is provided.
+ * @property defaultIsOpened - Initial open state in uncontrolled mode.
+ * Ignored when `isOpened` is provided. Defaults to `false`.
  * @property isOpened - Controlled open state. When defined, the component
- * behaves as a controlled component and internal state is ignored.
- * @property stateHandlers - Callbacks invoked after the state changes
- * @property stateHandlers.toggled - Callbacks invoked after the isOpened state has changed
+ * behaves as a controlled component and internal state is never updated.
+ * @property onOpenerClicked - Called when the opener is clicked, before the
+ * drawer reacts, with the open state as it was.
+ * @property onCloserClicked - Called when the closer is clicked, before the
+ * drawer reacts, with the open state as it was.
+ * @property onIsOpenedChanged - Called after the open state changed, with the
+ * new value.
  * @property className - Additional class name(s) applied to the root element.
  * @property children - Drawer content.
  */
 export type Props = PropsWithChildren<WithClassName<{
     openerContent?: ReactNode;
     closerContent?: ReactNode;
-    initialIsOpened?: boolean;
+    defaultIsOpened?: boolean;
     isOpened?: boolean;
-    stateHandlers?: {
-        toggled?: (isOpen: boolean) => void;
-    };
+    onOpenerClicked?: (isOpened: boolean) => void;
+    onCloserClicked?: (isOpened: boolean) => void;
+    onIsOpenedChanged?: (isOpened: boolean) => void;
 }>>;
 /**
- * Drawer component with optional controlled and uncontrolled behavior.
+ * Drawer component supporting controlled and uncontrolled usage.
+ *
+ * The content is measured through a {@link ResizeObserverComponent} so its
+ * dimensions can drive the open/close transition from CSS alone.
+ *
+ * ### CSS modifiers
+ * - `opened` — the drawer is open.
+ * - `closed` — the drawer is closed.
+ *
+ * ### CSS elements
+ * - `opener`
+ * - `closer`
+ * - `content`
+ *
+ * ### CSS custom properties on the root element
+ * - `--lm-drawer-content-width` / `--lm-drawer-content-width-raw`
+ * - `--lm-drawer-content-height` / `--lm-drawer-content-height-raw`
+ * Absent until the first measurement lands.
+ *
+ * ### Data attributes on the root element
+ * - `data-content-width`, `data-content-height` — the measured content size.
+ * Absent until the first measurement lands.
+ *
+ * @param props - Component properties.
+ * @see {@link Props}
+ * @returns A root `<div>` holding the opener, the closer and the measured content.
  *
  * @remarks
- * - In controlled mode (`isOpened` defined), visibility is fully driven by the prop.
- * - In uncontrolled mode, internal state is initialized from `initialIsOpened`.
- * - The component measures its content using `ResizeObserverComponent`
- *   and exposes the dimensions:
- *   - As CSS custom properties:
- *     --{prefix}-content-height
- *     --{prefix}-content-height-px
- *     --{prefix}-content-width
- *     --{prefix}-content-width-px
- *   - As `data-content-width` and `data-content-height` attributes.
- *
- * CSS modifier classes:
- * - `opened` when open
- * - `closed` when closed
+ * - In controlled mode (`isOpened` defined), the open state is fully driven by
+ *   the parent and internal state is never updated.
+ * - `onOpenerClicked` and `onCloserClicked` fire in both modes — a controlled
+ *   parent needs them to know a click happened at all.
+ * - `onIsOpenedChanged` fires in both modes too, and never on mount.
  */
 export declare const Drawer: FunctionComponent<Props>;