@design-edito/tools 0.5.1 → 0.5.3

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

@@ -0,0 +1,148 @@
+import { describe, it, expect } from 'vitest';
+import { days, minutes, seconds } from '../index.js';
+import { formatDuration } from './index.js';
+import { getDurationParts } from './parts.js';
+const DAY = 86400000;
+describe('formatDuration', () => {
+    describe('template', () => {
+        it('splits the duration across the units the template mentions', () => {
+            expect(formatDuration(seconds(3725), '{{h}}:{{mm}}:{{ss}}')).toBe('1:02:05');
+        });
+        it('puts the whole duration on the only unit a template asks for', () => {
+            expect(formatDuration(seconds(3725), '{{s}}s')).toBe('3725s');
+            expect(formatDuration(days(400), '{{d}} days')).toBe('400 days');
+        });
+        it('accepts a plain number of milliseconds in place of a Duration', () => {
+            expect(formatDuration(3725000, '{{h}}:{{mm}}:{{ss}}')).toBe('1:02:05');
+        });
+        it('pads a doubled token to two digits and leaves its bare twin alone', () => {
+            expect(formatDuration(minutes(5), '{{mm}}:{{ss}}')).toBe('05:00');
+            expect(formatDuration(minutes(5), '{{m}}:{{s}}')).toBe('5:0');
+        });
+        it('pads milliseconds to three digits', () => {
+            expect(formatDuration(1042, '{{s}}.{{ms}}')).toBe('1.042');
+        });
+        it('substitutes every occurrence of a repeated token', () => {
+            expect(formatDuration(seconds(5), '{{s}}/{{s}}')).toBe('5/5');
+        });
+        it('leaves an unknown token untouched, braces included', () => {
+            expect(formatDuration(seconds(5), '{{ZZ}} {{s}}')).toBe('{{ZZ}} 5');
+        });
+        it('does not substitute a bare letter outside a placeholder', () => {
+            expect(formatDuration(seconds(5), 'd h m s {{s}}')).toBe('d h m s 5');
+        });
+    });
+    describe('remainder', () => {
+        it('drops the fraction of the smallest unit by default', () => {
+            expect(formatDuration(119600, '{{m}}:{{s}}')).toBe('1:59');
+        });
+        it('keeps the fraction when floorSmallestUnit is off', () => {
+            expect(formatDuration(119600, '{{m}}:{{s}}', { floorSmallestUnit: false })).toBe('1:59.6');
+        });
+    });
+    describe('month and year approximation', () => {
+        it('counts 365 days as a full year by default', () => {
+            expect(formatDuration(days(365), '{{Y}}')).toBe('1');
+        });
+        it('falls one year short of the Gregorian mean year when the approximation is off', () => {
+            expect(formatDuration(days(365), '{{Y}}', { useApproximateMonthAndYear: false })).toBe('0');
+        });
+    });
+    describe('negative durations', () => {
+        it('signs every part rather than the string as a whole', () => {
+            expect(formatDuration(seconds(-90), '{{m}}:{{ss}}')).toBe('-1:-30');
+        });
+    });
+});
+describe('getDurationParts', () => {
+    describe('breakdown', () => {
+        it('cascades the remainder from each unit down to the next', () => {
+            expect(getDurationParts(days(400), { units: ['Y', 'd'] })).toMatchObject({
+                Y: 1,
+                M: 0,
+                w: 0,
+                d: 35,
+                h: 0,
+                m: 0,
+                s: 0,
+                ms: 0
+            });
+        });
+        it('orders the units itself, whatever order they are given in', () => {
+            expect(getDurationParts(3725000, { units: ['s', 'h', 'm'] })).toMatchObject({ h: 1, m: 2, s: 5 });
+        });
+        it('ignores a unit listed twice', () => {
+            expect(getDurationParts(3725000, { units: ['h', 'm', 's', 'h'] })).toMatchObject({ h: 1, m: 2, s: 5 });
+        });
+        it('reaches every part under its readable name too', () => {
+            const parts = getDurationParts(3725000, { units: ['h', 'm', 's'] });
+            expect(parts).toMatchObject({
+                hours: parts.h,
+                minutes: parts.m,
+                seconds: parts.s,
+                milliseconds: parts.ms,
+                days: parts.d,
+                weeks: parts.w,
+                months: parts.M,
+                years: parts.Y
+            });
+        });
+    });
+    describe('units left out', () => {
+        it('puts the whole duration, fraction included, on the largest unit it reaches', () => {
+            const parts = getDurationParts(days(400));
+            expect(parts.Y).toBeCloseTo(1.0959, 4);
+            expect(parts.d).toBe(0);
+        });
+        it('picks the unit off the duration, not off the largest one that exists', () => {
+            expect(getDurationParts(90000).m).toBe(1.5);
+            expect(getDurationParts(500).ms).toBe(500);
+        });
+        it('falls back to milliseconds for a duration shorter than one', () => {
+            expect(getDurationParts(0.5)).toMatchObject({ ms: 0.5, s: 0 });
+        });
+        it('leaves every part at zero for a zero duration', () => {
+            expect(getDurationParts(0)).toMatchObject({
+                Y: 0, M: 0, w: 0, d: 0, h: 0, m: 0, s: 0, ms: 0
+            });
+        });
+    });
+    describe('floorSmallestUnit', () => {
+        it('leaves the remainder on the smallest unit by default', () => {
+            expect(getDurationParts(119600, { units: ['m', 's'] })).toMatchObject({ m: 1, s: 59.6 });
+        });
+        it('truncates the whole duration, so the missing fraction leaves every part', () => {
+            expect(getDurationParts(119600, { units: ['m', 's'], floorSmallestUnit: true })).toMatchObject({ m: 1, s: 59 });
+        });
+        it('rounds off the floating-point dust the cascade leaves behind', () => {
+            // 30 days on ['M', 'd'] divides exactly, but only in decimal.
+            expect(getDurationParts(30 * DAY, { units: ['M', 'd'], floorSmallestUnit: true })).toMatchObject({ M: 1, d: 0 });
+        });
+    });
+    describe('month and year approximation', () => {
+        it('uses 30-day months and 365-day years by default', () => {
+            expect(getDurationParts(365 * DAY, { units: ['Y', 'd'] })).toMatchObject({ Y: 1, d: 0 });
+            expect(getDurationParts(30 * DAY, { units: ['M', 'd'] })).toMatchObject({ M: 1, d: 0 });
+        });
+        it('uses the Gregorian mean year when the approximation is off', () => {
+            expect(getDurationParts(365 * DAY, {
+                units: ['Y', 'd'],
+                useApproximateMonthAndYear: false
+            })).toMatchObject({ Y: 0, d: 365 });
+            expect(getDurationParts(30 * DAY, {
+                units: ['M'],
+                useApproximateMonthAndYear: false
+            }).M).toBeCloseTo(0.9856, 4);
+        });
+    });
+    describe('negative durations', () => {
+        it('breaks the magnitude down, then negates every part', () => {
+            expect(getDurationParts(seconds(-90), { units: ['m', 's'] })).toMatchObject({ m: -1, s: -30 });
+        });
+        it('leaves an empty part at zero rather than at negative zero', () => {
+            const parts = getDurationParts(-30000, { units: ['m', 's'] });
+            expect(Object.is(parts.m, 0)).toBe(true);
+            expect(parts.s).toBe(-30);
+        });
+    });
+});

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

@@ -0,0 +1,32 @@
+import { Duration } from '../index.js';
+import type { DurationParts, GetDurationPartsOptions } from './types.js';
+/**
+ * Breaks a duration down into its parts, cascading the remainder from each unit
+ * to the next.
+ *
+ * With several units, each one takes its whole part and hands the rest down, so
+ * `['M', 'd', 's']` reads as *X months and Y days and Z.mmm seconds*. With a
+ * single unit — including the one picked when `units` is omitted — that unit
+ * carries the whole duration, fraction included.
+ *
+ * @param duration - The duration to break down, as a {@link Duration} or a
+ * number of milliseconds.
+ * @param options - Which units to use, and how to handle the remainder.
+ * @returns The parts, each one reachable under its unit token and under its
+ * readable name. Units left out of the breakdown are `0`.
+ * @see {@link DurationParts}
+ *
+ * @remarks
+ * A negative duration is broken down by magnitude, then every part is negated.
+ * `floorSmallestUnit` truncates the duration *before* the cascade, so the whole
+ * breakdown describes the truncated duration rather than the original one —
+ * `1m 59.6s` gives `1m 59s`, and the missing `.6s` is gone from every part.
+ *
+ * @example
+ * getDurationParts(days(400), { units: ['Y', 'd'] })
+ * // => { Y: 1, years: 1, d: 35, days: 35, … every other unit at 0 }
+ *
+ * getDurationParts(days(400))
+ * // => { Y: 1.0958…, years: 1.0958…, … } — the largest unit it reaches
+ */
+export declare function getDurationParts(duration: Duration | number, options?: GetDurationPartsOptions): DurationParts;

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

@@ -0,0 +1,107 @@
+import { Duration } from '../index.js';
+const SECOND = 1000;
+const MINUTE = 60 * SECOND;
+const HOUR = 60 * MINUTE;
+const DAY = 24 * HOUR;
+const WEEK = 7 * DAY;
+const APPROXIMATE_YEAR = 365 * DAY;
+const APPROXIMATE_MONTH = 30 * DAY;
+/** The Gregorian mean year — 365.2425 days, the calendar's actual average. */
+const EXACT_YEAR = 365.2425 * DAY;
+const EXACT_MONTH = EXACT_YEAR / 12;
+/** Units from the longest to the shortest, in both approximation modes. */
+const unitsLongestFirst = ['Y', 'M', 'w', 'd', 'h', 'm', 's', 'ms'];
+/** How many milliseconds each unit is worth, under the chosen approximation. */
+function unitLengths(useApproximateMonthAndYear) {
+    return {
+        ms: 1,
+        s: SECOND,
+        m: MINUTE,
+        h: HOUR,
+        d: DAY,
+        w: WEEK,
+        M: useApproximateMonthAndYear ? APPROXIMATE_MONTH : EXACT_MONTH,
+        Y: useApproximateMonthAndYear ? APPROXIMATE_YEAR : EXACT_YEAR
+    };
+}
+/**
+ * The requested units, deduplicated and ordered longest first. Falls back to the
+ * single largest unit the duration reaches, and to `'ms'` for a duration shorter
+ * than a millisecond.
+ */
+function resolveUnits(units, absoluteMs, lengths) {
+    if (units !== undefined && units.length > 0) {
+        return unitsLongestFirst.filter(unit => units.includes(unit));
+    }
+    return [unitsLongestFirst.find(unit => absoluteMs >= lengths[unit]) ?? 'ms'];
+}
+/**
+ * Breaks a duration down into its parts, cascading the remainder from each unit
+ * to the next.
+ *
+ * With several units, each one takes its whole part and hands the rest down, so
+ * `['M', 'd', 's']` reads as *X months and Y days and Z.mmm seconds*. With a
+ * single unit — including the one picked when `units` is omitted — that unit
+ * carries the whole duration, fraction included.
+ *
+ * @param duration - The duration to break down, as a {@link Duration} or a
+ * number of milliseconds.
+ * @param options - Which units to use, and how to handle the remainder.
+ * @returns The parts, each one reachable under its unit token and under its
+ * readable name. Units left out of the breakdown are `0`.
+ * @see {@link DurationParts}
+ *
+ * @remarks
+ * A negative duration is broken down by magnitude, then every part is negated.
+ * `floorSmallestUnit` truncates the duration *before* the cascade, so the whole
+ * breakdown describes the truncated duration rather than the original one —
+ * `1m 59.6s` gives `1m 59s`, and the missing `.6s` is gone from every part.
+ *
+ * @example
+ * getDurationParts(days(400), { units: ['Y', 'd'] })
+ * // => { Y: 1, years: 1, d: 35, days: 35, … every other unit at 0 }
+ *
+ * getDurationParts(days(400))
+ * // => { Y: 1.0958…, years: 1.0958…, … } — the largest unit it reaches
+ */
+export function getDurationParts(duration, options = {}) {
+    const { units, floorSmallestUnit = false, useApproximateMonthAndYear = true } = options;
+    const totalMs = duration instanceof Duration ? duration.toMs() : duration;
+    const sign = totalMs < 0 ? -1 : 1;
+    const lengths = unitLengths(useApproximateMonthAndYear);
+    const usedUnits = resolveUnits(units, Math.abs(totalMs), lengths);
+    // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+    const smallestUnit = usedUnits[usedUnits.length - 1];
+    const smallestLength = lengths[smallestUnit];
+    let remaining = Math.abs(totalMs);
+    if (floorSmallestUnit) {
+        remaining = Math.floor(remaining / smallestLength) * smallestLength;
+    }
+    const values = {
+        ms: 0, s: 0, m: 0, h: 0, d: 0, w: 0, M: 0, Y: 0
+    };
+    usedUnits.forEach((unit, pos) => {
+        const isSmallest = pos === usedUnits.length - 1;
+        const exact = remaining / lengths[unit];
+        // Math.round, not Math.floor, and deliberately so: the truncation already
+        // happened above, on the whole duration, so this value is a whole one by
+        // now. Rounding only clears the floating-point dust the divisions leave —
+        // flooring here would turn a 29.999999999 that means 30 into a 29.
+        const value = isSmallest
+            ? (floorSmallestUnit ? Math.round(exact) : exact)
+            : Math.floor(exact);
+        values[unit] = value === 0 ? 0 : value * sign;
+        remaining -= value * lengths[unit];
+    });
+    return {
+        ...values,
+        milliseconds: values.ms,
+        seconds: values.s,
+        minutes: values.m,
+        hours: values.h,
+        days: values.d,
+        weeks: values.w,
+        months: values.M,
+        years: values.Y
+    };
+}

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