@design-edito/tools 0.5.2 → 0.5.3

package/agnostic/time/duration/format-duration/types.d.ts

@@ -0,0 +1,93 @@
+/**
+ * The units a duration can be broken down into, keyed the way `format-date`
+ * tokens are — `'m'` is minutes, `'M'` is months.
+ */
+export type DurationUnit = 'ms' | 's' | 'm' | 'h' | 'd' | 'w' | 'M' | 'Y';
+/** Every token `formatDuration` substitutes in a template. */
+export type DurationToken = 'Y' | 'YY' | 'M' | 'MM' | 'w' | 'ww' | 'd' | 'dd' | 'h' | 'hh' | 'm' | 'mm' | 's' | 'ss' | 'ms';
+/** Options for `getDurationParts`. */
+export type GetDurationPartsOptions = {
+    /**
+     * The units to break the duration down into, in any order. Omitted or empty,
+     * a single unit is picked: the largest one the duration reaches.
+     */
+    units?: DurationUnit[];
+    /**
+     * Truncates the duration to a whole number of the smallest requested unit, so
+     * no part comes out fractional. Defaults to `false`, which leaves the
+     * remainder on the smallest unit.
+     */
+    floorSmallestUnit?: boolean;
+    /**
+     * Months and years have no fixed length, so they are approximated. `true`
+     * (the default) uses 30-day months and 365-day years, matching what
+     * `Duration` itself computes. `false` uses the Gregorian mean year of
+     * 365.2425 days and a month of exactly a twelfth of it.
+     */
+    useApproximateMonthAndYear?: boolean;
+};
+/**
+ * A duration's parts, keyed by unit token.
+ *
+ * Every unit is present: those left out of the breakdown are `0`. All parts
+ * carry the sign of the input duration.
+ */
+export type DurationTokenParts = {
+    /** Milliseconds. */
+    ms: number;
+    /** Seconds. */
+    s: number;
+    /** Minutes. */
+    m: number;
+    /** Hours. */
+    h: number;
+    /** Days. */
+    d: number;
+    /** Weeks. */
+    w: number;
+    /** Months. */
+    M: number;
+    /** Years. */
+    Y: number;
+};
+/**
+ * The same parts as {@link DurationTokenParts}, under names that read on their
+ * own — one per token, same value.
+ */
+export type NamedDurationParts = {
+    /** {@link DurationTokenParts.ms} */
+    milliseconds: number;
+    /** {@link DurationTokenParts.s} */
+    seconds: number;
+    /** {@link DurationTokenParts.m} */
+    minutes: number;
+    /** {@link DurationTokenParts.h} */
+    hours: number;
+    /** {@link DurationTokenParts.d} */
+    days: number;
+    /** {@link DurationTokenParts.w} */
+    weeks: number;
+    /** {@link DurationTokenParts.M} */
+    months: number;
+    /** {@link DurationTokenParts.Y} */
+    years: number;
+};
+/** Every part of a duration, reachable both by unit token and by name. */
+export type DurationParts = DurationTokenParts & NamedDurationParts;
+/** Options for `formatDuration`. */
+export type FormatDurationOptions = {
+    /**
+     * Truncates the duration to a whole number of the smallest unit the template
+     * uses. Defaults to `true` here, unlike {@link GetDurationPartsOptions} — a
+     * template asks to be displayed, and `0:01:59.60000000001` is not a display.
+     * Set it to `false` to keep the fraction.
+     */
+    floorSmallestUnit?: boolean;
+    /**
+     * Months and years have no fixed length, so they are approximated. `true`
+     * (the default) uses 30-day months and 365-day years, matching what
+     * `Duration` itself computes. `false` uses the Gregorian mean year of
+     * 365.2425 days and a month of exactly a twelfth of it.
+     */
+    useApproximateMonthAndYear?: boolean;
+};

package/agnostic/time/duration/format-duration/types.js

@@ -0,0 +1 @@
+export {};

package/agnostic/time/duration/index.d.ts

@@ -4,8 +4,13 @@
 export type DurationType = 'milliseconds' | 'seconds' | 'minutes' | 'hours' | 'days' | 'weeks' | 'months' | 'years';
 /**
  * Supported duration types (short form aliases).
+ *
+ * @remarks
+ * `'M'` and `'Y'` are the `format-date` style tokens, and the ones
+ * {@link DurationUnit} is keyed on; `'mo'`, `'mth'` and `'y'` predate them and
+ * stay accepted. Mind the casing: `'m'` is minutes, `'M'` is months.
  */
-export type DurationTypeShort = 'ms' | 's' | 'sec' | 'min' | 'm' | 'h' | 'd' | 'w' | 'mo' | 'mth' | 'y';
+export type DurationTypeShort = 'ms' | 's' | 'sec' | 'min' | 'm' | 'h' | 'd' | 'w' | 'mo' | 'mth' | 'M' | 'y' | 'Y';
 /**
  * Represents a duration in a specific unit and allows conversion to other units.
  */

package/agnostic/time/duration/index.js

@@ -38,11 +38,11 @@ export class Duration {
         else if (type === 'w' || type === 'weeks') {
             this.type = 'weeks';
         }
-        else if (type === 'mo' || type === 'mth' || type === 'months') {
+        else if (type === 'mo' || type === 'mth' || type === 'M' || type === 'months') {
             this.type = 'months';
         }
         // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
-        else if (type === 'y' || type === 'years') {
+        else if (type === 'y' || type === 'Y' || type === 'years') {
             this.type = 'years';
         }
         else {

package/agnostic/time/duration/index.test.d.ts

@@ -0,0 +1 @@
+export {};

package/agnostic/time/duration/index.test.js

@@ -0,0 +1,168 @@
+import { describe, it, expect } from 'vitest';
+import { Duration, d, days, h, hours, m, milliseconds, min, minutes, months, ms, mth, s, sec, seconds, w, weeks, y, years, yr } from './index.js';
+describe('Duration', () => {
+    describe('unit normalisation', () => {
+        it('keeps a long form as it is given', () => {
+            expect(new Duration(1, 'milliseconds').type).toBe('milliseconds');
+            expect(new Duration(1, 'seconds').type).toBe('seconds');
+            expect(new Duration(1, 'minutes').type).toBe('minutes');
+            expect(new Duration(1, 'hours').type).toBe('hours');
+            expect(new Duration(1, 'days').type).toBe('days');
+            expect(new Duration(1, 'weeks').type).toBe('weeks');
+            expect(new Duration(1, 'months').type).toBe('months');
+            expect(new Duration(1, 'years').type).toBe('years');
+        });
+        it('expands a short form to its long form', () => {
+            expect(new Duration(1, 'ms').type).toBe('milliseconds');
+            expect(new Duration(1, 's').type).toBe('seconds');
+            expect(new Duration(1, 'sec').type).toBe('seconds');
+            expect(new Duration(1, 'min').type).toBe('minutes');
+            expect(new Duration(1, 'h').type).toBe('hours');
+            expect(new Duration(1, 'd').type).toBe('days');
+            expect(new Duration(1, 'w').type).toBe('weeks');
+        });
+        it('tells minutes from months by the case of the token', () => {
+            expect(new Duration(1, 'm').type).toBe('minutes');
+            expect(new Duration(1, 'M').type).toBe('months');
+        });
+        it('still accepts the month and year aliases that predate the format-date tokens', () => {
+            expect(new Duration(1, 'mo').type).toBe('months');
+            expect(new Duration(1, 'mth').type).toBe('months');
+            expect(new Duration(1, 'y').type).toBe('years');
+            expect(new Duration(1, 'Y').type).toBe('years');
+        });
+        it('falls back to milliseconds on a unit it does not know', () => {
+            // The fallback is unreachable through the types — only a caller in plain JS
+            // gets there, and it is that caller the test stands in for.
+            const duration = new Duration(5, 'fortnights');
+            expect(duration.type).toBe('milliseconds');
+            expect(duration.toMs()).toBe(5);
+        });
+    });
+    describe('toMilliseconds', () => {
+        it('converts each unit by its fixed length', () => {
+            expect(milliseconds(1).toMilliseconds()).toBe(1);
+            expect(seconds(1).toMilliseconds()).toBe(1000);
+            expect(minutes(1).toMilliseconds()).toBe(60000);
+            expect(hours(1).toMilliseconds()).toBe(3600000);
+            expect(days(1).toMilliseconds()).toBe(86400000);
+            expect(weeks(1).toMilliseconds()).toBe(604800000);
+        });
+        it('approximates a month as 30 days and a year as 365', () => {
+            expect(months(1).toMilliseconds()).toBe(30 * 86400000);
+            expect(years(1).toMilliseconds()).toBe(365 * 86400000);
+        });
+        it('carries the sign and the fraction of the value it was given', () => {
+            expect(seconds(-90).toMilliseconds()).toBe(-90000);
+            expect(hours(1.5).toMilliseconds()).toBe(5400000);
+        });
+    });
+    describe('conversions to other units', () => {
+        it('reads a duration back in a larger unit', () => {
+            expect(seconds(90).toMinutes()).toBe(1.5);
+            expect(minutes(90).toHours()).toBe(1.5);
+            expect(hours(36).toDays()).toBe(1.5);
+            expect(days(14).toWeeks()).toBe(2);
+        });
+        it('reads a duration back in a smaller unit', () => {
+            expect(hours(2).toSeconds()).toBe(7200);
+            expect(days(1).toMinutes()).toBe(1440);
+        });
+        it('divides by the same month and year approximations it multiplies by', () => {
+            expect(days(30).toMonths()).toBe(1);
+            expect(days(365).toYear()).toBe(1);
+        });
+        it('yields a fractional value rather than a truncated one', () => {
+            expect(seconds(30).toMinutes()).toBe(0.5);
+            expect(days(400).toYear()).toBeCloseTo(1.0959, 4);
+        });
+    });
+    describe('shorthand aliases', () => {
+        it('exposes a shorthand for every conversion', () => {
+            const duration = minutes(3);
+            expect(duration.toMs()).toBe(duration.toMilliseconds());
+            expect(duration.toS()).toBe(duration.toSeconds());
+            expect(duration.toSec()).toBe(duration.toSeconds());
+            expect(duration.toM()).toBe(duration.toMinutes());
+            expect(duration.toMin()).toBe(duration.toMinutes());
+            expect(duration.toH()).toBe(duration.toHours());
+            expect(duration.toD()).toBe(duration.toDays());
+            expect(duration.toW()).toBe(duration.toWeeks());
+            expect(duration.toMth()).toBe(duration.toMonths());
+            expect(duration.toY()).toBe(duration.toYear());
+            expect(duration.toYr()).toBe(duration.toYear());
+        });
+        it('keeps its conversions bound once they are detached from the instance', () => {
+            const { toMs, toMinutes } = hours(2);
+            expect(toMs()).toBe(7200000);
+            expect(toMinutes()).toBe(120);
+        });
+    });
+});
+describe('milliseconds', () => {
+    it('builds a duration counted in milliseconds', () => {
+        expect(milliseconds(250)).toMatchObject({ value: 250, type: 'milliseconds' });
+    });
+    it('is also exported as ms', () => {
+        expect(ms).toBe(milliseconds);
+    });
+});
+describe('seconds', () => {
+    it('builds a duration counted in seconds', () => {
+        expect(seconds(30)).toMatchObject({ value: 30, type: 'seconds' });
+    });
+    it('is also exported as s and sec', () => {
+        expect(s).toBe(seconds);
+        expect(sec).toBe(seconds);
+    });
+});
+describe('minutes', () => {
+    it('builds a duration counted in minutes', () => {
+        expect(minutes(45)).toMatchObject({ value: 45, type: 'minutes' });
+    });
+    it('is also exported as m and min', () => {
+        expect(m).toBe(minutes);
+        expect(min).toBe(minutes);
+    });
+});
+describe('hours', () => {
+    it('builds a duration counted in hours', () => {
+        expect(hours(12)).toMatchObject({ value: 12, type: 'hours' });
+    });
+    it('is also exported as h', () => {
+        expect(h).toBe(hours);
+    });
+});
+describe('days', () => {
+    it('builds a duration counted in days', () => {
+        expect(days(7)).toMatchObject({ value: 7, type: 'days' });
+    });
+    it('is also exported as d', () => {
+        expect(d).toBe(days);
+    });
+});
+describe('weeks', () => {
+    it('builds a duration counted in weeks', () => {
+        expect(weeks(3)).toMatchObject({ value: 3, type: 'weeks' });
+    });
+    it('is also exported as w', () => {
+        expect(w).toBe(weeks);
+    });
+});
+describe('months', () => {
+    it('builds a duration counted in months', () => {
+        expect(months(2)).toMatchObject({ value: 2, type: 'months' });
+    });
+    it('is also exported as mth', () => {
+        expect(mth).toBe(months);
+    });
+});
+describe('years', () => {
+    it('builds a duration counted in years', () => {
+        expect(years(1)).toMatchObject({ value: 1, type: 'years' });
+    });
+    it('is also exported as y and yr', () => {
+        expect(y).toBe(years);
+        expect(yr).toBe(years);
+    });
+});

package/agnostic/time/index.d.ts

@@ -1,5 +1,5 @@
 export * as dates from './dates/index.js'
-export * as timeout from './timeout/index.js'
 export * as duration from './duration/index.js'
+export * as timeout from './timeout/index.js'
 export * as transitions from './transitions/index.js'
 export * as wait from './wait/index.js'

package/agnostic/time/index.js

@@ -1,5 +1,5 @@
 export * as dates from './dates/index.js'
-export * as timeout from './timeout/index.js'
 export * as duration from './duration/index.js'
+export * as timeout from './timeout/index.js'
 export * as transitions from './transitions/index.js'
 export * as wait from './wait/index.js'

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

@@ -1,45 +1,39 @@
-import { type ReactNode, type FunctionComponent, type PropsWithChildren } from 'react';
+import { type FunctionComponent, type PropsWithChildren, type ReactNode } from 'react';
 import type { WithClassName } from '../utils/types.js';
 /**
- * Props for the {@link BeforeAfterControlled} component.
- *
- * Extends {@link WithClassName} with layout, content, and interaction configuration.
+ * Props for the {@link ControlledBeforeAfter} component.
  *
  * @property mode - Layout orientation of the split. Defaults to `'horizontal'`.
- * @property ratio - Position of the divider as a value between `0` and `1`.
- * Values outside this range are clamped automatically. Defaults to `0`.
+ * @property ratio - Position of the divider, between `0` and `1`. Values outside
+ * that range are clamped. Defaults to `0`.
  * @property before - Content rendered in the first (before) panel.
  * @property after - Content rendered in the second (after) panel.
- * @property actionHandlers - Optional user action callbacks:
- *   - `dragged` — called on each pointer move while dragging, with the current
- *     x and y ratios relative to the component bounds.
- *   - `clicked` — called on pointer release when no drag occurred, with the
- *     x and y ratios of the release position.
+ * @property onDragged - Called on each pointer move while dragging, with the
+ * pointer's x and y ratios relative to the component's bounds.
+ * @property onClicked - Called on pointer release when no drag occurred, with
+ * the release position's x and y ratios.
  * @property className - Additional class name(s) applied to the root element.
- * @property children - Arbitrary content to inject inside the component
+ * @property children - Arbitrary content to inject inside the component.
  */
 export type Props = PropsWithChildren<WithClassName<{
     mode?: 'vertical' | 'horizontal';
     ratio?: number;
     before?: ReactNode;
     after?: ReactNode;
-    actionHandlers?: {
-        dragged?: (xRatio: number, yRatio: number) => void;
-        clicked?: (xRatio: number, yRatio: number) => void;
-    };
+    onDragged?: (xRatio: number, yRatio: number) => void;
+    onClicked?: (xRatio: number, yRatio: number) => void;
 }>>;
 /**
  * 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'`.
@@ -48,9 +42,15 @@ export type Props = PropsWithChildren<WithClassName<{
  * ### 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 declare const BeforeAfterControlled: FunctionComponent<Props>;
+export declare const ControlledBeforeAfter: FunctionComponent<Props>;

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