@haruhimemoe/ui 0.3.0 → 0.5.0

package/dist/components/filters/RangeSlider.js

@@ -3,26 +3,19 @@
  * @desc Two-thumb range slider with an editable box at each end (star rating, length, BPM). Two
  *       native range inputs share one track; the thumbs can't cross. With `openEnded`, the top
  *       end at `max` means "no upper limit": it shows "max+" and reports `null`. When both thumbs
- *       sit on one value, a drag moves whichever end can go the way the pointer goes.
+ *       sit on one value, a drag moves whichever end can go the way the pointer goes. The math
+ *       lives in rangeMath.ts and the boxes in RangeBox.tsx.
  * @author David @dvhsh (https://dvh.sh)
  * @created Wed Sep 23, 2026
- * @modified Wed Sep 23, 2026
+ * @modified Mon Sep 28, 2026
  */
 "use client";
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { useId, useRef, useState, } from "react";
+import { useRef } from "react";
 import { cx } from "../../utils/cx.js";
-const decimalsOf = (n) => {
-    const text = String(n);
-    const dot = text.indexOf(".");
-    return dot === -1 ? 0 : text.length - dot - 1;
-};
-const clamp = (n, low, high) => Math.min(Math.max(n, low), high);
-// A comma reads as the decimal point: comma-locale keypads (de, fr, pl, pt-BR, ru) type "5,5".
-const defaultParse = (text) => {
-    const n = Number(text.replace(",", "."));
-    return Number.isFinite(n) ? n : null;
-};
+import { GroupFrame } from "./GroupFrame.js";
+import { RangeBox } from "./RangeBox.js";
+import { defaultParse, dragEnd, nextRange, normalizeRange, percent, rangeBounds, readDraft, thumbTarget, } from "./rangeMath.js";
 // Native range inputs, stacked on one track. Only the thumbs take the pointer, so either thumb
 // can be dragged wherever they sit. The focus ring goes on the thumb, not the full-width input:
 // solid h1, so it clears 3:1 on the panel. Forced-colors mode drops box-shadow rings, so the
@@ -31,9 +24,6 @@ const RANGE = "pointer-events-none absolute inset-x-0 top-1/2 h-4 w-full -transl
     "[&::-webkit-slider-thumb]:pointer-events-auto [&::-webkit-slider-thumb]:size-4 [&::-webkit-slider-thumb]:cursor-pointer [&::-webkit-slider-thumb]:appearance-none [&::-webkit-slider-thumb]:box-border [&::-webkit-slider-thumb]:rounded-full [&::-webkit-slider-thumb]:border-2 [&::-webkit-slider-thumb]:border-h1 [&::-webkit-slider-thumb]:bg-c1 " +
     "[&::-moz-range-track]:bg-transparent [&::-moz-range-thumb]:pointer-events-auto [&::-moz-range-thumb]:size-4 [&::-moz-range-thumb]:cursor-pointer [&::-moz-range-thumb]:appearance-none [&::-moz-range-thumb]:box-border [&::-moz-range-thumb]:rounded-full [&::-moz-range-thumb]:border-2 [&::-moz-range-thumb]:border-h1 [&::-moz-range-thumb]:bg-c1 " +
     "focus-visible:[&::-webkit-slider-thumb]:ring-4 focus-visible:[&::-webkit-slider-thumb]:ring-h1 focus-visible:[&::-moz-range-thumb]:ring-4 focus-visible:[&::-moz-range-thumb]:ring-h1";
-// The field look (border b3 on b6, h1 border on focus), sized for a short value. The group dims
-// itself when disabled, so the boxes do not dim twice.
-const BOX = "w-18 shrink-0 rounded-md border border-b3 bg-b6 px-2 py-1 text-center text-c1 text-sm tabular-nums placeholder:text-c4 focus-visible:border-h1 focus-visible:outline-hidden disabled:cursor-not-allowed";
 /**
  * @function RangeSlider
  * @param props {RangeSliderProps} label, bounds, step, the current range and a change handler,
@@ -44,78 +34,26 @@ const BOX = "w-18 shrink-0 rounded-md border border-b3 bg-b6 px-2 py-1 text-cent
  *          Page Up/Down ten steps, Home/End as far as it can go. The boxes commit on blur or
  *          Enter; Escape puts the value back.
  */
-export function RangeSlider({ label, hideLabel = false, min, max, step = 1, value, onChange, format = String, parse = defaultParse, inputMode = parse === defaultParse ? "decimal" : "text", openEnded = false, minLabel = `Minimum ${label}`, maxLabel = `Maximum ${label}`, disabled = false, className, ...props }) {
-    const labelId = useId();
-    const [drafts, setDrafts] = useState({ low: null, high: null });
+export function RangeSlider({ label, min: rawMin, max: rawMax, step: rawStep = 1, value, onChange, format = String, parse = defaultParse, inputMode = parse === defaultParse ? "decimal" : "text", openEnded = false, minLabel = `Minimum ${label}`, maxLabel = `Maximum ${label}`, disabled = false, className, ...props }) {
     // The pointer drag in progress, and the end it moves (picked on its first change).
     const drag = useRef(null);
-    // Normalize what came in (it may come from a URL): inside the bounds, low <= high. A NaN or
-    // infinite end means no limit on that end, like an empty box.
-    const low = Number.isFinite(value[0]) ? clamp(value[0], min, max) : min;
-    const top = value[1] !== null && Number.isFinite(value[1]) ? value[1] : null;
-    const highOpen = openEnded && (top === null || top >= max);
-    const high = top === null ? max : clamp(top, low, max);
-    const highOut = highOpen ? null : high;
-    const decimals = Math.max(decimalsOf(step), decimalsOf(min));
-    const snap = (n) => Number((min + Math.round((n - min) / step) * step).toFixed(decimals));
-    const percent = (n) => (max === min ? 0 : ((n - min) / (max - min)) * 100);
+    const bounds = rangeBounds(rawMin, rawMax, rawStep);
+    const { min, max, step } = bounds;
+    const state = normalizeRange(value, bounds, openEnded);
+    const { low, high, highOpen } = state;
     const openText = `${format(max)}+`;
-    const text = {
-        low: format(low),
-        high: highOpen ? openText : format(high),
-    };
     const commit = (end, n) => {
-        if (end === "low") {
-            const next = clamp(snap(n), min, high);
-            if (next !== low)
-                onChange([next, highOut]);
-            return;
-        }
-        const snapped = clamp(snap(n), low, max);
-        const next = openEnded && (n >= max || snapped >= max) ? null : snapped;
-        if (next !== highOut)
-            onChange([low, next]);
+        const next = nextRange(end, n, state, bounds, openEnded);
+        if (next)
+            onChange(next);
     };
-    const setDraft = (end, draft) => setDrafts((current) => ({ ...current, [end]: draft }));
-    const commitDraft = (end) => {
-        const draft = drafts[end];
-        if (draft === null)
-            return;
-        setDraft(end, null);
-        const trimmed = draft.trim().replace(/\+$/, "").trim();
-        // An empty box means no limit on that end.
-        if (trimmed === "") {
-            commit(end, end === "low" ? min : max);
-            return;
-        }
-        const n = parse(trimmed);
-        if (n !== null && Number.isFinite(n))
+    const commitDraft = (end) => (draft) => {
+        const n = readDraft(draft, end, bounds, parse);
+        if (n !== null)
             commit(end, n);
     };
-    const onBoxKeyDown = (end) => (event) => {
-        if (event.key === "Enter") {
-            event.preventDefault();
-            commitDraft(end);
-        }
-        else if (event.key === "Escape" && drafts[end] !== null) {
-            event.preventDefault();
-            setDraft(end, null);
-        }
-    };
     const onThumbKeyDown = (end) => (event) => {
-        const current = end === "low" ? low : high;
-        const big = step * 10;
-        const moves = {
-            ArrowLeft: current - step,
-            ArrowDown: current - step,
-            ArrowRight: current + step,
-            ArrowUp: current + step,
-            PageDown: current - big,
-            PageUp: current + big,
-            Home: min,
-            End: max,
-        };
-        const next = moves[event.key];
+        const next = thumbTarget(event.key, end === "low" ? low : high, bounds);
         if (next === undefined)
             return;
         event.preventDefault();
@@ -131,31 +69,30 @@ export function RangeSlider({ label, hideLabel = false, min, max, step = 1, valu
         window.addEventListener("pointerup", done);
         window.addEventListener("pointercancel", done);
     };
-    // With both thumbs on one value, only the top one can be grabbed, and it can only move one way.
-    // So a drag's first move picks the end: toward the other thumb's side, the other end moves.
-    // The drag keeps that end until the pointer lifts. Changes without a pointer (assistive tech
-    // stepping a slider) always move their own end.
+    // A drag keeps the end its first move picked until the pointer lifts. Changes without a
+    // pointer (assistive tech stepping a slider) always move their own end.
     const onThumbChange = (end) => (event) => {
         const n = Number(event.currentTarget.value);
         const gesture = drag.current;
-        if (gesture && gesture.end === null) {
-            const parked = low === high;
-            gesture.end =
-                parked && end === "high" && n < low
-                    ? "low"
-                    : parked && end === "low" && n > high
-                        ? "high"
-                        : end;
-        }
+        if (gesture && gesture.end === null)
+            gesture.end = dragEnd(end, n, state);
         commit(gesture?.end ?? end, n);
     };
-    const box = (end) => (_jsx("input", { type: "text", inputMode: inputMode, autoComplete: "off", "aria-label": end === "low" ? minLabel : maxLabel, disabled: disabled, value: drafts[end] ?? text[end], onChange: (event) => setDraft(end, event.currentTarget.value), onBlur: () => commitDraft(end), onKeyDown: onBoxKeyDown(end), className: BOX }));
-    const lowPercent = percent(low);
-    const highPercent = highOpen ? 100 : percent(high);
-    return (_jsxs("fieldset", { 
-        // Inside a FilterRow (hideLabel), the row's fieldset is the group; see ChipGroup.
-        role: hideLabel ? "none" : undefined, "aria-labelledby": hideLabel ? undefined : labelId, disabled: disabled, className: cx("flex flex-col gap-2 disabled:opacity-50", className), ...props, children: [hideLabel ? null : (_jsx("span", { id: labelId, className: "font-bold text-c3 text-sm", children: label })), _jsxs("div", { className: "flex items-center gap-3", children: [box("low"), _jsxs("div", { className: "relative h-5 min-w-0 flex-1", children: [_jsx("div", { "aria-hidden": "true", className: "absolute inset-x-0 top-1/2 h-1.5 -translate-y-1/2 rounded-full bg-b3" }), _jsx("div", { "aria-hidden": "true", className: "absolute inset-x-2 top-1/2 h-1.5 -translate-y-1/2", children: _jsx("div", { "data-range-fill": "", className: "absolute inset-y-0 rounded-full bg-h1 forced-colors:bg-[Highlight]", style: { left: `${lowPercent}%`, right: `${100 - highPercent}%` } }) }), _jsx("input", { type: "range", "aria-label": minLabel, "aria-valuetext": format(low), min: min, max: max, step: step, value: low, disabled: disabled, onChange: onThumbChange("low"), onKeyDown: onThumbKeyDown("low"), onPointerDown: onThumbPointerDown, 
-                                // Past the middle, the low thumb sits on top, so two thumbs parked at the top end can
-                                // still be pulled apart.
-                                className: cx(RANGE, lowPercent > 50 && "z-10") }), _jsx("input", { type: "range", "aria-label": maxLabel, "aria-valuetext": highOpen ? openText : format(high), min: min, max: max, step: step, value: high, disabled: disabled, onChange: onThumbChange("high"), onKeyDown: onThumbKeyDown("high"), onPointerDown: onThumbPointerDown, className: RANGE })] }), box("high")] })] }));
+    const thumb = (end) => ({
+        type: "range",
+        "aria-label": end === "low" ? minLabel : maxLabel,
+        "aria-valuetext": end === "low" ? format(low) : highOpen ? openText : format(high),
+        min,
+        max,
+        step,
+        value: end === "low" ? low : high,
+        disabled,
+        onChange: onThumbChange(end),
+        onKeyDown: onThumbKeyDown(end),
+        onPointerDown: onThumbPointerDown,
+    });
+    const box = (end) => (_jsx(RangeBox, { label: end === "low" ? minLabel : maxLabel, text: end === "low" ? format(low) : highOpen ? openText : format(high), inputMode: inputMode, disabled: disabled, onCommit: commitDraft(end) }));
+    const lowPercent = percent(low, bounds);
+    const highPercent = highOpen ? 100 : percent(high, bounds);
+    return (_jsx(GroupFrame, { label: label, disabled: disabled, className: cx("disabled:opacity-50", className), ...props, children: _jsxs("div", { className: "flex items-center gap-3", children: [box("low"), _jsxs("div", { className: "relative h-5 min-w-0 flex-1", children: [_jsx("div", { "aria-hidden": "true", className: "absolute inset-x-0 top-1/2 h-1.5 -translate-y-1/2 rounded-full bg-b3" }), _jsx("div", { "aria-hidden": "true", className: "absolute inset-x-2 top-1/2 h-1.5 -translate-y-1/2", children: _jsx("div", { "data-range-fill": "", className: "absolute inset-y-0 rounded-full bg-h1 forced-colors:bg-[Highlight]", style: { left: `${lowPercent}%`, right: `${100 - highPercent}%` } }) }), _jsx("input", { ...thumb("low"), className: cx(RANGE, lowPercent > 50 && "z-10") }), _jsx("input", { ...thumb("high"), className: RANGE })] }), box("high")] }) }));
 }

package/dist/components/filters/chipStyles.d.ts

@@ -0,0 +1,17 @@
+/**
+ * @file src/components/filters/chipStyles.ts
+ * @desc The chip look that Chip and ChoiceChips share (the osu! beatmap listing pills): the pill,
+ *       pink when on, b3 when off. In forced-colors mode an "on" chip takes the system highlight
+ *       colors, so on and off still look different.
+ * @author David @dvhsh (https://dvh.sh)
+ * @created Mon Sep 28, 2026
+ * @modified Mon Sep 28, 2026
+ */
+/** The pill: rounded, px-2.5 py-0.5, bold text-xs. */
+export declare const CHIP = "rounded-full px-2.5 py-0.5 font-bold text-xs transition-colors";
+/** A chip that is on (pressed or checked). */
+export declare const CHIP_ON = "bg-h1 text-b6 forced-colors:bg-[Highlight] forced-colors:text-[HighlightText]";
+/** A chip that is off. */
+export declare const CHIP_OFF = "bg-b3 text-c2";
+/** A chip that can't be used right now: dimmed, with a not-allowed cursor. */
+export declare const CHIP_UNAVAILABLE = "cursor-not-allowed opacity-40";

package/dist/components/filters/chipStyles.js

@@ -0,0 +1,17 @@
+/**
+ * @file src/components/filters/chipStyles.ts
+ * @desc The chip look that Chip and ChoiceChips share (the osu! beatmap listing pills): the pill,
+ *       pink when on, b3 when off. In forced-colors mode an "on" chip takes the system highlight
+ *       colors, so on and off still look different.
+ * @author David @dvhsh (https://dvh.sh)
+ * @created Mon Sep 28, 2026
+ * @modified Mon Sep 28, 2026
+ */
+/** The pill: rounded, px-2.5 py-0.5, bold text-xs. */
+export const CHIP = "rounded-full px-2.5 py-0.5 font-bold text-xs transition-colors";
+/** A chip that is on (pressed or checked). */
+export const CHIP_ON = "bg-h1 text-b6 forced-colors:bg-[Highlight] forced-colors:text-[HighlightText]";
+/** A chip that is off. */
+export const CHIP_OFF = "bg-b3 text-c2";
+/** A chip that can't be used right now: dimmed, with a not-allowed cursor. */
+export const CHIP_UNAVAILABLE = "cursor-not-allowed opacity-40";

package/dist/components/filters/rangeMath.d.ts

@@ -0,0 +1,106 @@
+/**
+ * @file src/components/filters/rangeMath.ts
+ * @desc RangeSlider's math (internal), free of React so it tests on its own: guarded bounds and
+ *       step, the incoming range normalized, snapping, the thumbs' keyboard moves, which end a
+ *       drag moves, and what a typed box or a thumb move commits.
+ * @author David @dvhsh (https://dvh.sh)
+ * @created Mon Sep 28, 2026
+ * @modified Mon Sep 28, 2026
+ */
+/** A range as `[low, high]`. `high` is `null` for an open top end (no upper limit). */
+export type RangeSliderValue = [number, number | null];
+/** One end of the range. */
+export type End = "low" | "high";
+/** The bounds and step after guarding: `min <= max`, and a step that is finite and above 0. */
+export type RangeBounds = {
+    min: number;
+    max: number;
+    step: number;
+    decimals: number;
+};
+/** The range as shown: both ends inside the bounds and in order, and whether the top is open. */
+export type RangeState = {
+    low: number;
+    high: number;
+    highOpen: boolean;
+    highOut: number | null;
+};
+/**
+ * @function defaultParse
+ * @param text {string} a typed value, without a trailing "+"
+ * @returns {number | null} the number, reading a comma as the decimal point (comma-locale keypads
+ *          type "5,5"), or null when it isn't one
+ */
+export declare const defaultParse: (text: string) => number | null;
+/**
+ * @function rangeBounds
+ * @param min {number} the low bound as passed
+ * @param max {number} the high bound as passed
+ * @param step {number} the step as passed
+ * @returns {RangeBounds} the bounds in order (swapped when `max < min`) and the step, or 1 when
+ *          the step is 0, negative or not finite, so snapping never divides by zero
+ */
+export declare const rangeBounds: (min: number, max: number, step: number) => RangeBounds;
+/**
+ * @function normalizeRange
+ * @param value {Readonly<RangeSliderValue>} the range as it came in (from a URL, say)
+ * @param bounds {RangeBounds} the guarded bounds
+ * @param openEnded {boolean} whether a top end at `max` means no upper limit
+ * @returns {RangeState} both ends inside the bounds with low <= high. A NaN or infinite end means
+ *          no limit on that end, like an empty box.
+ */
+export declare const normalizeRange: (value: Readonly<RangeSliderValue>, { min, max }: RangeBounds, openEnded: boolean) => RangeState;
+/**
+ * @function snap
+ * @param n {number} a value
+ * @param bounds {RangeBounds} the guarded bounds
+ * @returns {number} the nearest step from `min`, rounded to the step's decimals (no float noise)
+ */
+export declare const snap: (n: number, { min, step, decimals }: RangeBounds) => number;
+/**
+ * @function percent
+ * @param n {number} a value inside the bounds
+ * @param bounds {RangeBounds} the guarded bounds
+ * @returns {number} where it sits on the track, 0 to 100 (0 when `min` equals `max`)
+ */
+export declare const percent: (n: number, { min, max }: RangeBounds) => number;
+/**
+ * @function thumbTarget
+ * @param key {string} the key pressed on a thumb
+ * @param current {number} that thumb's value
+ * @param bounds {RangeBounds} the guarded bounds
+ * @returns {number | undefined} where the key sends the thumb (arrows one step, Page Up/Down ten
+ *          steps, Home and End to the bounds), or undefined for any other key
+ */
+export declare const thumbTarget: (key: string, current: number, { min, max, step }: RangeBounds) => number | undefined;
+/**
+ * @function dragEnd
+ * @param end {End} the thumb the drag started on
+ * @param n {number} the drag's first value
+ * @param state {RangeState} the range before the drag
+ * @returns {End} the end the drag moves. With both thumbs on one value, only the top thumb can be
+ *          grabbed and it can only go one way, so a first move toward the other side moves the
+ *          other end.
+ */
+export declare const dragEnd: (end: End, n: number, { low, high }: RangeState) => End;
+/**
+ * @function nextRange
+ * @param end {End} the end that moves
+ * @param n {number} where it moves to, before snapping
+ * @param state {RangeState} the range now
+ * @param bounds {RangeBounds} the guarded bounds
+ * @param openEnded {boolean} whether a top end at `max` reports null
+ * @returns {RangeSliderValue | null} the new range (snapped, the thumbs uncrossed, an open top
+ *          end as null), or null when nothing changed
+ */
+export declare const nextRange: (end: End, n: number, state: RangeState, bounds: RangeBounds, openEnded: boolean) => RangeSliderValue | null;
+/**
+ * @function readDraft
+ * @param draft {string} what was typed in an end's box
+ * @param end {End} which box
+ * @param bounds {RangeBounds} the guarded bounds
+ * @param parse {(text: string) => number | null} the caller's reader
+ * @returns {number | null} the value to commit: an empty box is no limit on that end (`min` or
+ *          `max`), a trailing "+" is ignored, and text `parse` can't read gives null
+ */
+export declare const readDraft: (draft: string, end: End, { min, max }: RangeBounds, parse: (text: string) => number | null) => number | null;

package/dist/components/filters/rangeMath.js

@@ -0,0 +1,146 @@
+/**
+ * @file src/components/filters/rangeMath.ts
+ * @desc RangeSlider's math (internal), free of React so it tests on its own: guarded bounds and
+ *       step, the incoming range normalized, snapping, the thumbs' keyboard moves, which end a
+ *       drag moves, and what a typed box or a thumb move commits.
+ * @author David @dvhsh (https://dvh.sh)
+ * @created Mon Sep 28, 2026
+ * @modified Mon Sep 28, 2026
+ */
+const decimalsOf = (n) => {
+    const text = String(n);
+    const dot = text.indexOf(".");
+    return dot === -1 ? 0 : text.length - dot - 1;
+};
+const clamp = (n, low, high) => Math.min(Math.max(n, low), high);
+/**
+ * @function defaultParse
+ * @param text {string} a typed value, without a trailing "+"
+ * @returns {number | null} the number, reading a comma as the decimal point (comma-locale keypads
+ *          type "5,5"), or null when it isn't one
+ */
+export const defaultParse = (text) => {
+    const n = Number(text.replace(",", "."));
+    return Number.isFinite(n) ? n : null;
+};
+/**
+ * @function rangeBounds
+ * @param min {number} the low bound as passed
+ * @param max {number} the high bound as passed
+ * @param step {number} the step as passed
+ * @returns {RangeBounds} the bounds in order (swapped when `max < min`) and the step, or 1 when
+ *          the step is 0, negative or not finite, so snapping never divides by zero
+ */
+export const rangeBounds = (min, max, step) => {
+    const [low, high] = min <= max ? [min, max] : [max, min];
+    const safeStep = Number.isFinite(step) && step > 0 ? step : 1;
+    return {
+        min: low,
+        max: high,
+        step: safeStep,
+        decimals: Math.max(decimalsOf(safeStep), decimalsOf(low)),
+    };
+};
+/**
+ * @function normalizeRange
+ * @param value {Readonly<RangeSliderValue>} the range as it came in (from a URL, say)
+ * @param bounds {RangeBounds} the guarded bounds
+ * @param openEnded {boolean} whether a top end at `max` means no upper limit
+ * @returns {RangeState} both ends inside the bounds with low <= high. A NaN or infinite end means
+ *          no limit on that end, like an empty box.
+ */
+export const normalizeRange = (value, { min, max }, openEnded) => {
+    const low = Number.isFinite(value[0]) ? clamp(value[0], min, max) : min;
+    const top = value[1] !== null && Number.isFinite(value[1]) ? value[1] : null;
+    const highOpen = openEnded && (top === null || top >= max);
+    const high = top === null ? max : clamp(top, low, max);
+    return { low, high, highOpen, highOut: highOpen ? null : high };
+};
+/**
+ * @function snap
+ * @param n {number} a value
+ * @param bounds {RangeBounds} the guarded bounds
+ * @returns {number} the nearest step from `min`, rounded to the step's decimals (no float noise)
+ */
+export const snap = (n, { min, step, decimals }) => Number((min + Math.round((n - min) / step) * step).toFixed(decimals));
+/**
+ * @function percent
+ * @param n {number} a value inside the bounds
+ * @param bounds {RangeBounds} the guarded bounds
+ * @returns {number} where it sits on the track, 0 to 100 (0 when `min` equals `max`)
+ */
+export const percent = (n, { min, max }) => max === min ? 0 : ((n - min) / (max - min)) * 100;
+/**
+ * @function thumbTarget
+ * @param key {string} the key pressed on a thumb
+ * @param current {number} that thumb's value
+ * @param bounds {RangeBounds} the guarded bounds
+ * @returns {number | undefined} where the key sends the thumb (arrows one step, Page Up/Down ten
+ *          steps, Home and End to the bounds), or undefined for any other key
+ */
+export const thumbTarget = (key, current, { min, max, step }) => {
+    const moves = {
+        ArrowLeft: current - step,
+        ArrowDown: current - step,
+        ArrowRight: current + step,
+        ArrowUp: current + step,
+        PageDown: current - step * 10,
+        PageUp: current + step * 10,
+        Home: min,
+        End: max,
+    };
+    return moves[key];
+};
+/**
+ * @function dragEnd
+ * @param end {End} the thumb the drag started on
+ * @param n {number} the drag's first value
+ * @param state {RangeState} the range before the drag
+ * @returns {End} the end the drag moves. With both thumbs on one value, only the top thumb can be
+ *          grabbed and it can only go one way, so a first move toward the other side moves the
+ *          other end.
+ */
+export const dragEnd = (end, n, { low, high }) => {
+    if (low !== high)
+        return end;
+    if (end === "high" && n < low)
+        return "low";
+    if (end === "low" && n > high)
+        return "high";
+    return end;
+};
+/**
+ * @function nextRange
+ * @param end {End} the end that moves
+ * @param n {number} where it moves to, before snapping
+ * @param state {RangeState} the range now
+ * @param bounds {RangeBounds} the guarded bounds
+ * @param openEnded {boolean} whether a top end at `max` reports null
+ * @returns {RangeSliderValue | null} the new range (snapped, the thumbs uncrossed, an open top
+ *          end as null), or null when nothing changed
+ */
+export const nextRange = (end, n, state, bounds, openEnded) => {
+    if (end === "low") {
+        const next = clamp(snap(n, bounds), bounds.min, state.high);
+        return next === state.low ? null : [next, state.highOut];
+    }
+    const snapped = clamp(snap(n, bounds), state.low, bounds.max);
+    const next = openEnded && (n >= bounds.max || snapped >= bounds.max) ? null : snapped;
+    return next === state.highOut ? null : [state.low, next];
+};
+/**
+ * @function readDraft
+ * @param draft {string} what was typed in an end's box
+ * @param end {End} which box
+ * @param bounds {RangeBounds} the guarded bounds
+ * @param parse {(text: string) => number | null} the caller's reader
+ * @returns {number | null} the value to commit: an empty box is no limit on that end (`min` or
+ *          `max`), a trailing "+" is ignored, and text `parse` can't read gives null
+ */
+export const readDraft = (draft, end, { min, max }, parse) => {
+    const trimmed = draft.trim().replace(/\+$/, "").trim();
+    if (trimmed === "")
+        return end === "low" ? min : max;
+    const n = parse(trimmed);
+    return n !== null && Number.isFinite(n) ? n : null;
+};

package/dist/components/forms/CharCounter.d.ts

@@ -0,0 +1,25 @@
+/**
+ * @file src/components/forms/CharCounter.tsx
+ * @desc How much of a length limit a text uses ("1,234 / 60,000 characters"), turning rose and
+ *       saying how many to cut once it's over. The caller counts (a BBCode counter, a string's
+ *       length), so it fits any rule. Server-safe. Moved from bb.haruhime.moe.
+ * @author David @dvhsh (https://dvh.sh)
+ * @created Mon Sep 28, 2026
+ * @modified Mon Sep 28, 2026
+ */
+import type { ComponentProps } from "react";
+/** Every native `<p>` prop except children, plus the count, the limit and the unit. */
+export type CharCounterProps = Omit<ComponentProps<"p">, "children"> & {
+    /** How many are used. */
+    count: number;
+    /** The most allowed. */
+    limit: number;
+    /** What is counted (default "characters"). */
+    unit?: string | undefined;
+};
+/**
+ * @function CharCounter
+ * @param props {CharCounterProps} the count, the limit, the unit, and native `<p>` props
+ * @returns {JSX.Element} "count / limit unit" in c3, or in bold rose with ": N over the limit"
+ */
+export declare function CharCounter({ count, limit, unit, className, ...props }: CharCounterProps): import("react").JSX.Element;

package/dist/components/forms/CharCounter.js

@@ -0,0 +1,12 @@
+import { jsxs as _jsxs } from "react/jsx-runtime";
+import { cx } from "../../utils/cx.js";
+const format = (value) => value.toLocaleString("en-US");
+/**
+ * @function CharCounter
+ * @param props {CharCounterProps} the count, the limit, the unit, and native `<p>` props
+ * @returns {JSX.Element} "count / limit unit" in c3, or in bold rose with ": N over the limit"
+ */
+export function CharCounter({ count, limit, unit = "characters", className, ...props }) {
+    const over = count - limit;
+    return (_jsxs("p", { className: cx("text-sm tabular-nums", over > 0 ? "font-bold text-rose-300" : "text-c3", className), ...props, children: [`${format(count)} / ${format(limit)} ${unit}`, over > 0 ? `: ${format(over)} over the limit` : ""] }));
+}

package/dist/components/forms/Checkbox.d.ts

@@ -1,11 +1,12 @@
 /**
  * @file src/components/forms/Checkbox.tsx
  * @desc Checkbox with a bold label and an inline hint (the packs download-options look). The whole
- *       row toggles it; the label alone is its accessible name and the hint its description.
- *       Server-safe: the required id names the label, hint and error.
+ *       row toggles it; the label alone is its accessible name (plus any aria-labelledby the
+ *       caller adds) and the hint its description. Server-safe: the required id names the label,
+ *       hint and error.
  * @author David @dvhsh (https://dvh.sh)
  * @created Wed Sep 23, 2026
- * @modified Wed Sep 23, 2026
+ * @modified Mon Sep 28, 2026
  */
 import type { ComponentProps } from "react";
 import { type FieldProps } from "./FieldFrame.js";
@@ -17,4 +18,4 @@ export type CheckboxProps = Omit<ComponentProps<"input">, "id" | "type"> & Field
  *        plus id, label, hint, error and wrapperClassName; `className` goes on the `<input>`
  * @returns {JSX.Element} the checkbox row, and the error under it when given
  */
-export declare function Checkbox({ id, label, hint, error, wrapperClassName, className, "aria-describedby": describedBy, "aria-invalid": invalid, ...props }: CheckboxProps): import("react").JSX.Element;
+export declare function Checkbox({ id, label, hint, error, wrapperClassName, className, "aria-describedby": describedBy, "aria-invalid": invalid, "aria-labelledby": labelledBy, ...props }: CheckboxProps): import("react").JSX.Element;

package/dist/components/forms/Checkbox.js

@@ -1,13 +1,13 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { cx } from "../../utils/cx.js";
-import { FieldError, fieldDescribedBy, hintId } from "./FieldFrame.js";
+import { FieldError, fieldControlProps, hintId } from "./FieldFrame.js";
 /**
  * @function Checkbox
  * @param props {CheckboxProps} native input props (`checked`, `defaultChecked`, `onChange`...),
  *        plus id, label, hint, error and wrapperClassName; `className` goes on the `<input>`
  * @returns {JSX.Element} the checkbox row, and the error under it when given
  */
-export function Checkbox({ id, label, hint, error, wrapperClassName, className, "aria-describedby": describedBy, "aria-invalid": invalid, ...props }) {
+export function Checkbox({ id, label, hint, error, wrapperClassName, className, "aria-describedby": describedBy, "aria-invalid": invalid, "aria-labelledby": labelledBy, ...props }) {
     const labelId = `${id}-label`;
-    return (_jsxs("div", { className: cx("flex flex-col gap-1", wrapperClassName), children: [_jsxs("label", { htmlFor: id, className: "flex items-start gap-2 text-sm", children: [_jsx("input", { ...props, type: "checkbox", id: id, "aria-labelledby": labelId, "aria-describedby": fieldDescribedBy(id, hint, error, describedBy), "aria-invalid": error ? true : invalid, className: cx("mt-1 accent-h1", className) }), _jsxs("span", { children: [_jsx("span", { id: labelId, className: "font-bold text-c1", children: label }), hint ? (_jsxs("span", { className: "text-c3", children: [" · ", _jsx("span", { id: hintId(id), children: hint })] })) : null] })] }), _jsx(FieldError, { id: id, error: error })] }));
+    return (_jsxs("div", { className: cx("flex flex-col gap-1", wrapperClassName), children: [_jsxs("label", { htmlFor: id, className: "flex items-start gap-2 text-sm", children: [_jsx("input", { ...props, type: "checkbox", ...fieldControlProps({ id, hint, error, describedBy, invalid }), "aria-labelledby": labelledBy ? `${labelId} ${labelledBy}` : labelId, className: cx("mt-1 accent-h1", className) }), _jsxs("span", { children: [_jsx("span", { id: labelId, className: "font-bold text-c1", children: label }), hint ? (_jsxs("span", { className: "text-c3", children: [" · ", _jsx("span", { id: hintId(id), children: hint })] })) : null] })] }), _jsx(FieldError, { id: id, error: error })] }));
 }

package/dist/components/forms/FieldFrame.d.ts

@@ -3,11 +3,13 @@
  * @desc Internal layout shared by the form fields: label on top, the control, then the hint and
  *       the error. Ids derive from the control's required id, so the fields need no useId and stay
  *       server components. The hint and error sit in `<div>`s, so they can hold a list.
+ *       `fieldControlProps` is the one rule for the control's id, aria-describedby and
+ *       aria-invalid.
  * @author David @dvhsh (https://dvh.sh)
  * @created Wed Sep 23, 2026
- * @modified Wed Sep 23, 2026
+ * @modified Mon Sep 28, 2026
  */
-import type { ReactNode } from "react";
+import type { ComponentProps, ReactNode } from "react";
 /** The label, hint and error every form field takes, keyed on the control's required id. */
 export type FieldProps = {
     /** The control's id. The label points at it; the hint and error get `<id>-hint`, `<id>-error`. */
@@ -42,6 +44,30 @@ export declare const errorId: (id: string) => string;
  * @returns {string | undefined} the aria-describedby value, or undefined when there is nothing
  */
 export declare const fieldDescribedBy: (id: string, hint: ReactNode, error: ReactNode, extra: string | undefined) => string | undefined;
+/** What a field knows when it wires up its control: ids, texts, and the caller's own ARIA. */
+type FieldControlInput = {
+    id: string;
+    hint: ReactNode;
+    error: ReactNode;
+    /** The caller's own aria-describedby, kept after the hint and error ids. */
+    describedBy: string | undefined;
+    /** The caller's own aria-invalid, used when there is no error. */
+    invalid: ComponentProps<"input">["aria-invalid"];
+};
+/** The id and ARIA props a field puts on its control. */
+type FieldControlProps = {
+    id: string;
+    "aria-describedby": string | undefined;
+    "aria-invalid": FieldControlInput["invalid"];
+};
+/**
+ * @function fieldControlProps
+ * @param input {FieldControlInput} the control's id, its hint and error, and the caller's
+ *        aria-describedby and aria-invalid
+ * @returns {FieldControlProps} the props every field puts on its control: an error sets
+ *          aria-invalid, and the hint and error are linked before the caller's own descriptions
+ */
+export declare const fieldControlProps: ({ id, hint, error, describedBy, invalid, }: FieldControlInput) => FieldControlProps;
 /**
  * @function FieldError
  * @param props {{ id: string; error?: ReactNode }} the control's id and the error, if any

package/dist/components/forms/FieldFrame.js

@@ -1,5 +1,6 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { cx } from "../../utils/cx.js";
+import { FIELD_LABEL } from "./fieldStyles.js";
 /**
  * @function hintId
  * @param id {string} the control's id
@@ -24,6 +25,18 @@ export const fieldDescribedBy = (id, hint, error, extra) =>
 // A plain join, not cx: these are ids, and cx would treat an id like "text-hint" as a class.
 [hint ? hintId(id) : null, error ? errorId(id) : null, extra].filter(Boolean).join(" ") ||
     undefined;
+/**
+ * @function fieldControlProps
+ * @param input {FieldControlInput} the control's id, its hint and error, and the caller's
+ *        aria-describedby and aria-invalid
+ * @returns {FieldControlProps} the props every field puts on its control: an error sets
+ *          aria-invalid, and the hint and error are linked before the caller's own descriptions
+ */
+export const fieldControlProps = ({ id, hint, error, describedBy, invalid, }) => ({
+    id,
+    "aria-describedby": fieldDescribedBy(id, hint, error, describedBy),
+    "aria-invalid": error ? true : invalid,
+});
 /**
  * @function FieldError
  * @param props {{ id: string; error?: ReactNode }} the control's id and the error, if any
@@ -40,5 +53,5 @@ export function FieldError({ id, error }) {
  * @returns {JSX.Element} the label, control, hint and error stacked in a column
  */
 export function FieldFrame({ id, label, hint, error, className, children }) {
-    return (_jsxs("div", { className: cx("flex flex-col gap-1", className), children: [_jsx("label", { htmlFor: id, className: "font-bold text-c3 text-sm", children: label }), children, hint ? (_jsx("div", { id: hintId(id), className: "text-c4 text-xs", children: hint })) : null, _jsx(FieldError, { id: id, error: error })] }));
+    return (_jsxs("div", { className: cx("flex flex-col gap-1", className), children: [_jsx("label", { htmlFor: id, className: FIELD_LABEL, children: label }), children, hint ? (_jsx("div", { id: hintId(id), className: "text-c4 text-xs", children: hint })) : null, _jsx(FieldError, { id: id, error: error })] }));
 }