@haruhimemoe/ui 0.1.0

package/dist/components/filters/ChipGroup.js

@@ -0,0 +1,44 @@
+/**
+ * @file src/components/filters/ChipGroup.tsx
+ * @desc Labeled multi-select row of Chips (mods, game modes). Each chip is its own toggle button
+ *       in the tab order; the group reports the picked values in the options' order.
+ * @author David @dvhsh (https://dvh.sh)
+ * @created Wed Sep 23, 2026
+ * @modified Wed Sep 23, 2026
+ */
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useId } from "react";
+import { cx } from "../../utils/cx.js";
+import { Chip } from "./Chip.js";
+/**
+ * @function toggleValue
+ * @param value {readonly string[]} the picked values
+ * @param option {string} the value to switch on or off
+ * @param on {boolean} true to add it, false to remove it
+ * @param options {readonly ChipOption[]} the group's options, for ordering
+ * @returns {string[]} the new picked values without duplicates, in option order (values that
+ *          aren't options keep their place at the end)
+ */
+const toggleValue = (value, option, on, options) => {
+    const rest = [...new Set(value)].filter((v) => v !== option);
+    const next = on ? [...rest, option] : rest;
+    const order = new Map(options.map((o, i) => [o.value, i]));
+    const rank = (v) => order.get(v) ?? options.length;
+    return next.sort((a, b) => rank(a) - rank(b));
+};
+/**
+ * @function ChipGroup
+ * @param props {ChipGroupProps} label, options, picked values and a change handler, plus native
+ *        fieldset props (`disabled` turns off every chip). `onChange` is a function, so render
+ *        this from client code.
+ * @returns {JSX.Element} a `<fieldset>` (role group) labeled by its label, one Chip per option.
+ *          With `hideLabel`, the fieldset has role none and no label.
+ */
+export function ChipGroup({ label, hideLabel = false, options, value, onChange, className, ...props }) {
+    const labelId = useId();
+    return (_jsxs("fieldset", { 
+        // Inside a FilterRow (hideLabel), the row's fieldset is the group. A second group with the
+        // same name would be read twice. The fieldset stays, so `disabled` still reaches every chip.
+        role: hideLabel ? "none" : undefined, "aria-labelledby": hideLabel ? undefined : labelId, className: cx("flex flex-col gap-2", className), ...props, children: [hideLabel ? null : (_jsx("span", { id: labelId, className: "font-bold text-c3 text-sm", children: label })), _jsx("div", { className: "flex flex-wrap items-center gap-1", children: options.map((option) => (_jsx(Chip, { pressed: value.includes(option.value), disabled: option.disabled, onPressedChange: (on) => onChange(toggleValue(value, option.value, on, options)), children: option.label }, option.value))) })] }));
+}

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

@@ -0,0 +1,36 @@
+/**
+ * @file src/components/filters/FilterPanel.tsx
+ * @desc Filter panel (osu! beatmap listing style): a titled card of FilterRows with a live result
+ *       count and a "Clear filters" link. On phones the rows fold away behind a disclosure button;
+ *       from `sm` up they are always shown.
+ * @author David @dvhsh (https://dvh.sh)
+ * @created Wed Sep 23, 2026
+ * @modified Wed Sep 23, 2026
+ */
+import { type ComponentProps, type ReactNode } from "react";
+/** Every native `<section>` prop except `title`, plus the panel's title, count and clear action. */
+export type FilterPanelProps = Omit<ComponentProps<"section">, "title"> & {
+    /** The panel heading; it also names the panel and its phone disclosure button. */
+    title: ReactNode;
+    /** Heading level for the title (default 2). */
+    headingLevel?: 2 | 3 | 4 | 5 | 6 | undefined;
+    /** Shown in an `<output aria-live="polite">`, so screen readers hear each new count. */
+    resultCount?: ReactNode;
+    /** True while any filter is set; shows the clear button. */
+    active?: boolean | undefined;
+    /** Called by the clear button. The button shows only when `active` is true and this is set. */
+    onClear?: (() => void) | undefined;
+    /** Text of the clear button (default "Clear filters"). */
+    clearLabel?: ReactNode;
+    /** Whether the rows start open on phones (default false). Ignored from `sm` up. */
+    defaultOpen?: boolean | undefined;
+};
+/**
+ * @function FilterPanel
+ * @param props {FilterPanelProps} title, FilterRows as children, an optional result count and
+ *        clear action, plus native section props. `onClear` is a function, so render this from
+ *        client code.
+ * @returns {JSX.Element} a `<section>` named by its heading. When the clear button is used and
+ *          disappears, focus moves to the heading instead of getting lost.
+ */
+export declare function FilterPanel({ title, headingLevel, resultCount, active, onClear, clearLabel, defaultOpen, className, children, ...props }: FilterPanelProps): import("react").JSX.Element;

package/dist/components/filters/FilterPanel.js

@@ -0,0 +1,45 @@
+/**
+ * @file src/components/filters/FilterPanel.tsx
+ * @desc Filter panel (osu! beatmap listing style): a titled card of FilterRows with a live result
+ *       count and a "Clear filters" link. On phones the rows fold away behind a disclosure button;
+ *       from `sm` up they are always shown.
+ * @author David @dvhsh (https://dvh.sh)
+ * @created Wed Sep 23, 2026
+ * @modified Wed Sep 23, 2026
+ */
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useEffect, useId, useRef, useState } from "react";
+import { cx } from "../../utils/cx.js";
+/**
+ * @function FilterPanel
+ * @param props {FilterPanelProps} title, FilterRows as children, an optional result count and
+ *        clear action, plus native section props. `onClear` is a function, so render this from
+ *        client code.
+ * @returns {JSX.Element} a `<section>` named by its heading. When the clear button is used and
+ *          disappears, focus moves to the heading instead of getting lost.
+ */
+export function FilterPanel({ title, headingLevel = 2, resultCount, active = false, onClear, clearLabel = "Clear filters", defaultOpen = false, className, children, ...props }) {
+    const titleId = useId();
+    const bodyId = useId();
+    const [open, setOpen] = useState(defaultOpen);
+    const headingRef = useRef(null);
+    const cleared = useRef(false);
+    const showClear = active && onClear !== undefined;
+    // The clear button unmounts once the filters are cleared. If it took focus with it (focus fell
+    // back to the body), put focus on the heading so keyboard users keep their place.
+    useEffect(() => {
+        if (showClear)
+            return;
+        const focused = document.activeElement;
+        if (cleared.current && (focused === null || focused === document.body)) {
+            headingRef.current?.focus();
+        }
+        cleared.current = false;
+    }, [showClear]);
+    const Heading = `h${headingLevel}`;
+    return (_jsxs("section", { "aria-labelledby": titleId, className: cx("flex flex-col gap-4 rounded-[10px] bg-b4 p-5 text-c2", className), ...props, children: [_jsxs("div", { className: "flex flex-wrap items-center gap-x-4 gap-y-2", children: [_jsxs("div", { className: "flex items-center gap-1", children: [_jsx(Heading, { id: titleId, ref: headingRef, tabIndex: -1, className: "font-bold text-c1 text-lg", children: title }), _jsx("button", { type: "button", "aria-labelledby": titleId, "aria-expanded": open, "aria-controls": bodyId, onClick: () => setOpen(!open), className: "inline-flex size-8 items-center justify-center rounded-full text-c2 transition-colors hover:bg-b3 hover:text-c1 sm:hidden", children: _jsx("span", { "aria-hidden": "true", children: open ? "▴" : "▾" }) })] }), _jsx("output", { "aria-live": "polite", className: "text-c3 text-sm", children: resultCount }), showClear ? (_jsx("button", { type: "button", onClick: () => {
+                            cleared.current = true;
+                            onClear();
+                        }, className: "ml-auto font-bold text-h1 text-sm transition-colors hover:text-c1", children: clearLabel })) : null] }), _jsx("div", { id: bodyId, className: cx("flex-col gap-3", open ? "flex" : "hidden sm:flex"), children: children })] }));
+}

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

@@ -0,0 +1,22 @@
+/**
+ * @file src/components/filters/FilterRow.tsx
+ * @desc One labeled row of a filter panel (osu! beatmap listing layout): the label in a column on
+ *       the left and the controls on the right from `sm` up, stacked on phones.
+ * @author David @dvhsh (https://dvh.sh)
+ * @created Wed Sep 23, 2026
+ * @modified Wed Sep 23, 2026
+ */
+import { type ComponentProps, type ReactNode } from "react";
+/** Every native `<fieldset>` prop (including `ref`), plus the row's label. */
+export type FilterRowProps = ComponentProps<"fieldset"> & {
+    /** Shown in the label column; names the row (`role="group"` + `aria-labelledby`). */
+    label: ReactNode;
+};
+/**
+ * @function FilterRow
+ * @param props {FilterRowProps} the label, the row's controls as children, and native fieldset
+ *        props
+ * @returns {JSX.Element} a `<fieldset>` (role group) labeled by its label column. Give a
+ *          ChipGroup or RangeSlider inside it `hideLabel`, so the label shows and is read once.
+ */
+export declare function FilterRow({ label, className, children, ...props }: FilterRowProps): import("react").JSX.Element;

package/dist/components/filters/FilterRow.js

@@ -0,0 +1,22 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+/**
+ * @file src/components/filters/FilterRow.tsx
+ * @desc One labeled row of a filter panel (osu! beatmap listing layout): the label in a column on
+ *       the left and the controls on the right from `sm` up, stacked on phones.
+ * @author David @dvhsh (https://dvh.sh)
+ * @created Wed Sep 23, 2026
+ * @modified Wed Sep 23, 2026
+ */
+import { useId } from "react";
+import { cx } from "../../utils/cx.js";
+/**
+ * @function FilterRow
+ * @param props {FilterRowProps} the label, the row's controls as children, and native fieldset
+ *        props
+ * @returns {JSX.Element} a `<fieldset>` (role group) labeled by its label column. Give a
+ *          ChipGroup or RangeSlider inside it `hideLabel`, so the label shows and is read once.
+ */
+export function FilterRow({ label, className, children, ...props }) {
+    const labelId = useId();
+    return (_jsxs("fieldset", { "aria-labelledby": labelId, className: cx("flex flex-col gap-2 sm:flex-row sm:items-baseline sm:gap-4", className), ...props, children: [_jsx("span", { id: labelId, className: "shrink-0 font-bold text-c3 text-sm sm:w-28", children: label }), _jsx("div", { className: "min-w-0 flex-1", children: children })] }));
+}

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

@@ -0,0 +1,62 @@
+/**
+ * @file src/components/filters/RangeSlider.tsx
+ * @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.
+ * @author David @dvhsh (https://dvh.sh)
+ * @created Wed Sep 23, 2026
+ * @modified Wed Sep 23, 2026
+ */
+import { type ComponentProps, type HTMLAttributes } from "react";
+/** A range as `[low, high]`. `high` is `null` for an open top end (no upper limit). */
+export type RangeSliderValue = [number, number | null];
+/** Every native `<fieldset>` prop except `onChange` and `children`, plus the range. */
+export type RangeSliderProps = Omit<ComponentProps<"fieldset">, "onChange" | "children" | "inputMode"> & {
+    /** Names the group, and the ends as "Minimum <label>" and "Maximum <label>". */
+    label: string;
+    /**
+     * Leave the group name to a surrounding FilterRow: no label shows, and the fieldset is not a
+     * group of its own (role none). The ends are still named from `label`.
+     */
+    hideLabel?: boolean | undefined;
+    min: number;
+    max: number;
+    /** Step between values (default 1). Typed values snap to it. */
+    step?: number | undefined;
+    /** The current range. A `null` top end means open (shown at `max`). */
+    value: Readonly<RangeSliderValue>;
+    /** Called with the new range. The top end is `null` when `openEnded` and it reaches `max`. */
+    onChange: (value: RangeSliderValue) => void;
+    /** Turns a value into display text for the boxes and screen readers (default `String`). */
+    format?: ((value: number) => string) | undefined;
+    /**
+     * Reads a typed value back (default: a plain number). It gets the text without a trailing
+     * "+"; return `null` for text it can't read, and the box goes back to the current value.
+     */
+    parse?: ((text: string) => number | null) | undefined;
+    /**
+     * The on-screen keyboard for the boxes. Default "decimal" (digits and a decimal separator), or
+     * "text" when `parse` is set, since formats like m:ss need keys the decimal keypad lacks.
+     */
+    inputMode?: HTMLAttributes<HTMLInputElement>["inputMode"] | undefined;
+    /** When true, the top end at `max` means "no upper limit" and reports `null`. */
+    openEnded?: boolean | undefined;
+    /** Accessible name of the low end (default "Minimum <label>"). */
+    minLabel?: string | undefined;
+    /** Accessible name of the high end (default "Maximum <label>"). */
+    maxLabel?: string | undefined;
+    /** Disables both thumbs and both boxes. */
+    disabled?: boolean | undefined;
+};
+/**
+ * @function RangeSlider
+ * @param props {RangeSliderProps} label, bounds, step, the current range and a change handler,
+ *        plus native fieldset props. `onChange`, `format` and `parse` are functions, so render this
+ *        from client code.
+ * @returns {JSX.Element} a `<fieldset>` (role group, or role none with `hideLabel`) with a low
+ *          box, two slider thumbs on one track, and a high box. Arrow keys move a thumb one step,
+ *          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 declare function RangeSlider({ label, hideLabel, min, max, step, value, onChange, format, parse, inputMode, openEnded, minLabel, maxLabel, disabled, className, ...props }: RangeSliderProps): import("react").JSX.Element;

package/dist/components/filters/RangeSlider.js

@@ -0,0 +1,161 @@
+/**
+ * @file src/components/filters/RangeSlider.tsx
+ * @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.
+ * @author David @dvhsh (https://dvh.sh)
+ * @created Wed Sep 23, 2026
+ * @modified Wed Sep 23, 2026
+ */
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useId, useRef, useState, } 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;
+};
+// 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
+// input keeps a transparent outline (`outline-hidden`) that mode paints instead.
+const RANGE = "pointer-events-none absolute inset-x-0 top-1/2 h-4 w-full -translate-y-1/2 appearance-none bg-transparent focus-visible:outline-hidden disabled:cursor-not-allowed " +
+    "[&::-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,
+ *        plus native fieldset props. `onChange`, `format` and `parse` are functions, so render this
+ *        from client code.
+ * @returns {JSX.Element} a `<fieldset>` (role group, or role none with `hideLabel`) with a low
+ *          box, two slider thumbs on one track, and a high box. Arrow keys move a thumb one step,
+ *          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 });
+    // 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 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 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))
+            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];
+        if (next === undefined)
+            return;
+        event.preventDefault();
+        commit(end, next);
+    };
+    const onThumbPointerDown = () => {
+        drag.current = { end: null };
+        const done = () => {
+            drag.current = null;
+            window.removeEventListener("pointerup", done);
+            window.removeEventListener("pointercancel", done);
+        };
+        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.
+    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;
+        }
+        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")] })] }));
+}

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

@@ -0,0 +1,20 @@
+/**
+ * @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.
+ * @author David @dvhsh (https://dvh.sh)
+ * @created Wed Sep 23, 2026
+ * @modified Wed Sep 23, 2026
+ */
+import type { ComponentProps } from "react";
+import { type FieldProps } from "./FieldFrame.js";
+/** Every native checkbox `<input>` prop (including `ref`), plus an id, label, hint and error. */
+export type CheckboxProps = Omit<ComponentProps<"input">, "id" | "type"> & FieldProps;
+/**
+ * @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 declare function Checkbox({ id, label, hint, error, wrapperClassName, className, "aria-describedby": describedBy, "aria-invalid": invalid, ...props }: CheckboxProps): import("react").JSX.Element;

package/dist/components/forms/Checkbox.js

@@ -0,0 +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";
+/**
+ * @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 }) {
+    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 })] }));
+}

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

@@ -0,0 +1,66 @@
+/**
+ * @file src/components/forms/FieldFrame.tsx
+ * @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.
+ * @author David @dvhsh (https://dvh.sh)
+ * @created Wed Sep 23, 2026
+ * @modified Wed Sep 23, 2026
+ */
+import type { 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`. */
+    id: string;
+    /** Visible label text. */
+    label: ReactNode;
+    /** Help text under the control, linked with aria-describedby. Checkbox shows it inline. */
+    hint?: ReactNode | undefined;
+    /** Error text under the control (a list is fine). Marks the control aria-invalid and links it. */
+    error?: ReactNode | undefined;
+    /** Classes for the wrapper around the label, control, hint and error (layout, width). */
+    wrapperClassName?: string | undefined;
+};
+/**
+ * @function hintId
+ * @param id {string} the control's id
+ * @returns {string} the id of the control's hint element
+ */
+export declare const hintId: (id: string) => string;
+/**
+ * @function errorId
+ * @param id {string} the control's id
+ * @returns {string} the id of the control's error element
+ */
+export declare const errorId: (id: string) => string;
+/**
+ * @function fieldDescribedBy
+ * @param id {string} the control's id
+ * @param hint {ReactNode} the hint, if any
+ * @param error {ReactNode} the error, if any
+ * @param extra {string} the caller's own aria-describedby, kept last
+ * @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;
+/**
+ * @function FieldError
+ * @param props {{ id: string; error?: ReactNode }} the control's id and the error, if any
+ * @returns {JSX.Element | null} the error in a `<div>` (block content like a list is fine), or
+ *          nothing without an error
+ */
+export declare function FieldError({ id, error }: {
+    id: string;
+    error?: ReactNode | undefined;
+}): import("react").JSX.Element | null;
+type FieldFrameProps = Omit<FieldProps, "wrapperClassName"> & {
+    className?: string | undefined;
+    children: ReactNode;
+};
+/**
+ * @function FieldFrame
+ * @param props {FieldFrameProps} the control's id, label, hint, error, wrapper classes and the
+ *        control itself as children
+ * @returns {JSX.Element} the label, control, hint and error stacked in a column
+ */
+export declare function FieldFrame({ id, label, hint, error, className, children }: FieldFrameProps): import("react").JSX.Element;
+export {};

package/dist/components/forms/FieldFrame.js

@@ -0,0 +1,44 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { cx } from "../../utils/cx.js";
+/**
+ * @function hintId
+ * @param id {string} the control's id
+ * @returns {string} the id of the control's hint element
+ */
+export const hintId = (id) => `${id}-hint`;
+/**
+ * @function errorId
+ * @param id {string} the control's id
+ * @returns {string} the id of the control's error element
+ */
+export const errorId = (id) => `${id}-error`;
+/**
+ * @function fieldDescribedBy
+ * @param id {string} the control's id
+ * @param hint {ReactNode} the hint, if any
+ * @param error {ReactNode} the error, if any
+ * @param extra {string} the caller's own aria-describedby, kept last
+ * @returns {string | undefined} the aria-describedby value, or undefined when there is nothing
+ */
+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 FieldError
+ * @param props {{ id: string; error?: ReactNode }} the control's id and the error, if any
+ * @returns {JSX.Element | null} the error in a `<div>` (block content like a list is fine), or
+ *          nothing without an error
+ */
+export function FieldError({ id, error }) {
+    return error ? (_jsx("div", { id: errorId(id), role: "alert", className: "text-rose-300 text-sm", children: error })) : null;
+}
+/**
+ * @function FieldFrame
+ * @param props {FieldFrameProps} the control's id, label, hint, error, wrapper classes and the
+ *        control itself as children
+ * @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 })] }));
+}

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

@@ -0,0 +1,19 @@
+/**
+ * @file src/components/forms/Select.tsx
+ * @desc Labeled native select on the shared field look, with an optional hint and error wired
+ *       through aria-describedby and aria-invalid. Options come in as children. Server-safe.
+ * @author David @dvhsh (https://dvh.sh)
+ * @created Wed Sep 23, 2026
+ * @modified Wed Sep 23, 2026
+ */
+import type { ComponentProps } from "react";
+import { type FieldProps } from "./FieldFrame.js";
+/** Every native `<select>` prop (including `ref`), plus a required id, label, hint and error. */
+export type SelectProps = Omit<ComponentProps<"select">, "id"> & FieldProps;
+/**
+ * @function Select
+ * @param props {SelectProps} native select props with `<option>` children, plus id, label, hint,
+ *        error and wrapperClassName; `className` goes on the `<select>`
+ * @returns {JSX.Element} a label, the select, and the hint and error when given
+ */
+export declare function Select({ id, label, hint, error, wrapperClassName, className, "aria-describedby": describedBy, "aria-invalid": invalid, ...props }: SelectProps): import("react").JSX.Element;

package/dist/components/forms/Select.js

@@ -0,0 +1,12 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { FieldFrame, fieldDescribedBy } from "./FieldFrame.js";
+import { fieldClasses } from "./fieldStyles.js";
+/**
+ * @function Select
+ * @param props {SelectProps} native select props with `<option>` children, plus id, label, hint,
+ *        error and wrapperClassName; `className` goes on the `<select>`
+ * @returns {JSX.Element} a label, the select, and the hint and error when given
+ */
+export function Select({ id, label, hint, error, wrapperClassName, className, "aria-describedby": describedBy, "aria-invalid": invalid, ...props }) {
+    return (_jsx(FieldFrame, { id: id, label: label, hint: hint, error: error, className: wrapperClassName, children: _jsx("select", { ...props, id: id, "aria-describedby": fieldDescribedBy(id, hint, error, describedBy), "aria-invalid": error ? true : invalid, className: fieldClasses(className) }) }));
+}

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

@@ -0,0 +1,19 @@
+/**
+ * @file src/components/forms/TextInput.tsx
+ * @desc Labeled text input on the shared field look, with an optional hint and error wired through
+ *       aria-describedby and aria-invalid. Server-safe: the required id names the hint and error.
+ * @author David @dvhsh (https://dvh.sh)
+ * @created Wed Sep 23, 2026
+ * @modified Wed Sep 23, 2026
+ */
+import type { ComponentProps } from "react";
+import { type FieldProps } from "./FieldFrame.js";
+/** Every native `<input>` prop (including `ref` and `type`), plus an id, label, hint and error. */
+export type TextInputProps = Omit<ComponentProps<"input">, "id"> & FieldProps;
+/**
+ * @function TextInput
+ * @param props {TextInputProps} native input props, plus id, label, hint, error and
+ *        wrapperClassName; `className` goes on the `<input>`
+ * @returns {JSX.Element} a label, the input, and the hint and error when given
+ */
+export declare function TextInput({ id, label, hint, error, wrapperClassName, className, "aria-describedby": describedBy, "aria-invalid": invalid, ...props }: TextInputProps): import("react").JSX.Element;

package/dist/components/forms/TextInput.js

@@ -0,0 +1,12 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { FieldFrame, fieldDescribedBy } from "./FieldFrame.js";
+import { fieldClasses } from "./fieldStyles.js";
+/**
+ * @function TextInput
+ * @param props {TextInputProps} native input props, plus id, label, hint, error and
+ *        wrapperClassName; `className` goes on the `<input>`
+ * @returns {JSX.Element} a label, the input, and the hint and error when given
+ */
+export function TextInput({ id, label, hint, error, wrapperClassName, className, "aria-describedby": describedBy, "aria-invalid": invalid, ...props }) {
+    return (_jsx(FieldFrame, { id: id, label: label, hint: hint, error: error, className: wrapperClassName, children: _jsx("input", { ...props, id: id, "aria-describedby": fieldDescribedBy(id, hint, error, describedBy), "aria-invalid": error ? true : invalid, className: fieldClasses(className) }) }));
+}

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

@@ -0,0 +1,19 @@
+/**
+ * @file src/components/forms/Textarea.tsx
+ * @desc Labeled textarea on the shared field look (at least 6rem tall, resizes vertically), with
+ *       an optional hint and error wired through aria-describedby and aria-invalid. Server-safe.
+ * @author David @dvhsh (https://dvh.sh)
+ * @created Wed Sep 23, 2026
+ * @modified Wed Sep 23, 2026
+ */
+import type { ComponentProps } from "react";
+import { type FieldProps } from "./FieldFrame.js";
+/** Every native `<textarea>` prop (including `ref`), plus a required id, label, hint and error. */
+export type TextareaProps = Omit<ComponentProps<"textarea">, "id"> & FieldProps;
+/**
+ * @function Textarea
+ * @param props {TextareaProps} native textarea props, plus id, label, hint, error and
+ *        wrapperClassName; `className` goes on the `<textarea>`
+ * @returns {JSX.Element} a label, the textarea, and the hint and error when given
+ */
+export declare function Textarea({ id, label, hint, error, wrapperClassName, className, "aria-describedby": describedBy, "aria-invalid": invalid, ...props }: TextareaProps): import("react").JSX.Element;