@abuzareal/contour-ui 0.3.0 → 0.5.0

package/dist/components/ui/Pagination.js

@@ -1,5 +1,6 @@
 "use client";
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { ccx } from "../../lib/classNames.js";
 /** Page navigation with previous/next controls and a condensed list of two-digit page numbers. */
 import { ArrowLeft, ArrowRight } from "lucide-react";
 import { formatIndex } from "../../lib/format.js";
@@ -11,6 +12,6 @@ function visiblePages(page, pageCount) {
         .sort((a, b) => a - b);
     return sorted.flatMap((value, index) => index > 0 && value - sorted[index - 1] > 1 ? ["gap", value] : [value]);
 }
-export default function Pagination({ page, pageCount, onChange, label = "Pagination", }) {
-    return (_jsxs("nav", { "aria-label": label, className: "pagination", children: [_jsx("button", { type: "button", className: "pagination-step", "aria-label": "Previous page", disabled: page === 1, onClick: () => onChange(page - 1), children: _jsx(ArrowLeft, { size: 16 }) }), _jsx("ol", { className: "mono", children: visiblePages(page, pageCount).map((item, index) => item === "gap" ? (_jsx("li", { "aria-hidden": "true", className: "pagination-gap", children: "\u2026" }, `gap-${index}`)) : (_jsx("li", { children: _jsx("button", { type: "button", className: "pagination-page", "aria-label": `Page ${item}`, "aria-current": item === page ? "page" : undefined, onClick: () => onChange(Number(item)), children: formatIndex(Number(item)) }) }, item))) }), _jsx("button", { type: "button", className: "pagination-step", "aria-label": "Next page", disabled: page === pageCount, onClick: () => onChange(page + 1), children: _jsx(ArrowRight, { size: 16 }) })] }));
+export default function Pagination({ page, pageCount, onChange, label = "Pagination", previousLabel = "Previous page", nextLabel = "Next page", pageLabel = (value) => `Page ${value}`, formatPage = formatIndex, }) {
+    return (_jsxs("nav", { "aria-label": label, className: ccx("pagination"), children: [_jsx("button", { type: "button", className: ccx("pagination-step"), "aria-label": previousLabel, disabled: page === 1, onClick: () => onChange(page - 1), children: _jsx(ArrowLeft, { size: 16 }) }), _jsx("ol", { className: ccx("mono"), children: visiblePages(page, pageCount).map((item, index) => item === "gap" ? (_jsx("li", { "aria-hidden": "true", className: ccx("pagination-gap"), children: "\u2026" }, `gap-${index}`)) : (_jsx("li", { children: _jsx("button", { type: "button", className: ccx("pagination-page"), "aria-label": pageLabel(Number(item)), "aria-current": item === page ? "page" : undefined, onClick: () => onChange(Number(item)), children: formatPage(Number(item)) }) }, item))) }), _jsx("button", { type: "button", className: ccx("pagination-step"), "aria-label": nextLabel, disabled: page === pageCount, onClick: () => onChange(page + 1), children: _jsx(ArrowRight, { size: 16 }) })] }));
 }

package/dist/components/ui/Popover.d.ts

@@ -1,28 +1,38 @@
-/** Nonmodal local panel; root and existing trigger/panel props preserve owned state wiring. */
-import { type ReactNode } from "react";
+import { type ReactNode, type ReactElement } from "react";
+import { type PanelFocusOptions } from "../../hooks/usePanelFocus.js";
+import type { FloatingOptions } from "../../hooks/useFloatingPanel.js";
+import { type DismissReason } from "../../lib/layers.js";
 import type { NativePartProps } from "../../lib/componentProps.js";
-export type PopoverProps = Omit<NativePartProps<"div">, "ref" | "title"> & {
-    /** Content inside the owned trigger button, not a replacement interactive element. */
+export type PopoverProps = Omit<NativePartProps<"div">, "ref" | "title"> & FloatingOptions & PanelFocusOptions & {
     trigger: ReactNode;
     title: string;
     children: ReactNode;
-    align?: "start" | "end";
     open?: boolean;
     defaultOpen?: boolean;
     onOpenChange?: (open: boolean) => void;
     triggerProps?: NativePartProps<"button">;
     panelProps?: NativePartProps<"div">;
+    /** Render one ref-forwarding native button with the supplied owned props. */
+    renderTrigger?: (props: NativePartProps<"button"> & {
+        children: ReactNode;
+    }) => ReactElement;
+    /** preventDefault vetoes dismissal. Native document events still propagate. */
+    onDismiss?: (reason: DismissReason, event: KeyboardEvent | PointerEvent) => void;
 };
-declare const Popover: import("react").ForwardRefExoticComponent<Omit<NativePartProps<"div">, "title" | "ref"> & {
-    /** Content inside the owned trigger button, not a replacement interactive element. */
+declare const Popover: import("react").ForwardRefExoticComponent<Omit<NativePartProps<"div">, "title" | "ref"> & FloatingOptions & PanelFocusOptions & {
     trigger: ReactNode;
     title: string;
     children: ReactNode;
-    align?: "start" | "end";
     open?: boolean;
     defaultOpen?: boolean;
     onOpenChange?: (open: boolean) => void;
     triggerProps?: NativePartProps<"button">;
     panelProps?: NativePartProps<"div">;
+    /** Render one ref-forwarding native button with the supplied owned props. */
+    renderTrigger?: (props: NativePartProps<"button"> & {
+        children: ReactNode;
+    }) => ReactElement;
+    /** preventDefault vetoes dismissal. Native document events still propagate. */
+    onDismiss?: (reason: DismissReason, event: KeyboardEvent | PointerEvent) => void;
 } & import("react").RefAttributes<HTMLDivElement>>;
 export default Popover;

package/dist/components/ui/Popover.js

@@ -1,27 +1,68 @@
 "use client";
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-/** Nonmodal local panel; root and existing trigger/panel props preserve owned state wiring. */
-import { forwardRef, useCallback, useId } from "react";
+import { useContext, useLayoutEffect, forwardRef, useId, useMemo, useRef, useState, } from "react";
 import useOpenState from "../../hooks/useOpenState.js";
-import useDismiss from "../../hooks/useDismiss.js";
+import useDismiss from "../../hooks/useLayerDismiss.js";
 import useControlRef from "../../hooks/useControlRef.js";
-import { cx } from "../../lib/classNames.js";
-import { composeEventHandlers } from "../../lib/composeEventHandlers.js";
-const Popover = forwardRef(function Popover({ trigger, title, children, align = "start", open: controlledOpen, defaultOpen = false, onOpenChange, className, triggerProps, panelProps, ...rest }, forwardedRef) {
-    const generatedPanelId = useId();
+import usePanelFocus from "../../hooks/usePanelFocus.js";
+import { cx, ccx } from "../../lib/classNames.js";
+import { composeRefs } from "../../lib/composeRefs.js";
+import { LayerVisibility, LayerParent, } from "../../lib/layers.js";
+import OverlayTrigger from "./OverlayTrigger.js";
+import FloatingPortal from "./FloatingPortal.js";
+const Popover = forwardRef(function Popover({ trigger, title, children, align = "start", side = "bottom", sideOffset = 8, collisionPadding = 8, portal = true, container: portalContainer, initialFocus, onOpenAutoFocus, onCloseAutoFocus, renderTrigger, onDismiss, open: controlledOpen, defaultOpen = false, onOpenChange, className, triggerProps, panelProps, ...rest }, forwardedRef) {
+    const generatedPanelId = useId(), titleId = useId();
     const panelId = panelProps?.id ?? generatedPanelId;
-    const titleId = useId();
     const [open, setOpen] = useOpenState(controlledOpen, defaultOpen, onOpenChange);
-    const { ref: container, attach: attachContainer } = useControlRef(forwardedRef);
+    const parentVisible = useContext(LayerVisibility);
+    const visibleOpen = open && parentVisible;
+    const { ref: root, attach: attachRoot } = useControlRef(forwardedRef);
     const { ref: button, attach: attachButton } = useControlRef(triggerProps?.ref ?? null);
-    useDismiss(container, open, useCallback((reason) => {
+    const [anchorElement, setAnchorElement] = useState(null);
+    const attachAnchor = useMemo(() => composeRefs(attachButton, setAnchorElement), [attachButton]);
+    const panel = useRef(null);
+    const attachPanel = useMemo(() => composeRefs(panel, panelProps?.ref), [panelProps?.ref]);
+    const reason = useRef({ value: undefined });
+    const layer = useDismiss(root, visibleOpen, (why, event) => {
+        onDismiss?.(why, event);
+        if (event.defaultPrevented)
+            return;
+        reason.current.value = why;
         setOpen(false);
-        if (reason === "escape")
-            button.current?.focus();
-    }, [setOpen, button]));
-    return (_jsxs("div", { ...rest, ref: attachContainer, className: cx("popover", `popover-${align}`, className), children: [_jsx("button", { ...triggerProps, ref: attachButton, type: "button", className: cx("menu-trigger", triggerProps?.className), "aria-haspopup": "dialog", "aria-expanded": open, "aria-controls": panelId, onClick: composeEventHandlers(triggerProps?.onClick, () => {
-                    if (!triggerProps?.disabled)
-                        setOpen(!open);
-                }), children: trigger }), _jsxs("div", { ...panelProps, id: panelId, role: "dialog", "aria-labelledby": cx(titleId, panelProps?.["aria-labelledby"]), className: cx("popover-panel", panelProps?.className), hidden: !open, children: [_jsx("strong", { id: titleId, className: "popover-title", children: title }), children] })] }));
+        if (why === "escape" && !onCloseAutoFocus && button.current?.isConnected)
+            button.current.focus();
+    }, { branches: [panel, button], layerElement: panel });
+    useLayoutEffect(() => {
+        if (visibleOpen)
+            reason.current.value = undefined;
+    }, [visibleOpen, anchorElement]);
+    usePanelFocus(visibleOpen, button, panel, reason, { initialFocus, onOpenAutoFocus, onCloseAutoFocus }, anchorElement, layer);
+    const ownedTrigger = {
+        ...triggerProps,
+        ref: attachAnchor,
+        type: "button",
+        className: ccx("menu-trigger", triggerProps?.className),
+        "aria-haspopup": "dialog",
+        "aria-expanded": visibleOpen,
+        "aria-controls": panelId,
+        children: trigger,
+        onClick: (event) => {
+            triggerProps?.onClick?.(event);
+            if (event.defaultPrevented)
+                return;
+            if (!triggerProps?.disabled) {
+                reason.current.value = "trigger";
+                setOpen(!open);
+            }
+        },
+    };
+    return (_jsx(LayerVisibility.Provider, { value: visibleOpen, children: _jsx(LayerParent.Provider, { value: layer, children: _jsxs("div", { ...rest, ref: attachRoot, className: ccx("popover", `popover-${align}`, className), children: [_jsx(OverlayTrigger, { renderer: renderTrigger, props: ownedTrigger }), _jsx(FloatingPortal, { anchorElement: anchorElement, anchor: button, panel: panel, open: visibleOpen, options: {
+                            side,
+                            align,
+                            sideOffset,
+                            collisionPadding,
+                            portal,
+                            container: portalContainer,
+                        }, children: _jsxs("div", { ...panelProps, ref: attachPanel, id: panelId, role: "dialog", tabIndex: panelProps?.tabIndex ?? -1, "aria-labelledby": cx(titleId, panelProps?.["aria-labelledby"]), className: ccx("popover-panel", panelProps?.className), hidden: !visibleOpen, children: [_jsx("strong", { id: titleId, className: ccx("popover-title"), children: title }), children] }) })] }) }) }));
 });
 export default Popover;

package/dist/components/ui/ProgressBar.js

@@ -1,6 +1,6 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { cx } from "../../lib/classNames.js";
+import { ccx } from "../../lib/classNames.js";
 export default function ProgressBar({ label, value, tone = "accent", }) {
     const indeterminate = value === undefined;
-    return (_jsxs("div", { className: cx("progress", `progress-${tone}`), children: [_jsxs("div", { className: "progress-header mono", children: [_jsx("span", { children: label }), !indeterminate && _jsxs("span", { children: [Math.round(value), "%"] })] }), _jsx("div", { role: "progressbar", "aria-label": label, "aria-valuemin": 0, "aria-valuemax": 100, "aria-valuenow": indeterminate ? undefined : value, className: cx("progress-track", indeterminate && "progress-indeterminate"), style: { "--progress": `${value ?? 0}%` }, children: _jsx("span", { className: "progress-fill" }) })] }));
+    return (_jsxs("div", { className: ccx("progress", `progress-${tone}`), children: [_jsxs("div", { className: ccx("progress-header mono"), children: [_jsx("span", { children: label }), !indeterminate && _jsxs("span", { children: [Math.round(value), "%"] })] }), _jsx("div", { role: "progressbar", "aria-label": label, "aria-valuemin": 0, "aria-valuemax": 100, "aria-valuenow": indeterminate ? undefined : value, className: ccx("progress-track", indeterminate && "progress-indeterminate"), style: { "--progress": `${value ?? 0}%` }, children: _jsx("span", { className: ccx("progress-fill") }) })] }));
 }

package/dist/components/ui/RadioGroup.d.ts

@@ -1,14 +1,22 @@
-export type RadioGroupProps<Value extends string> = {
+/** Native radios with caller form/name, controlled/default selection and option input refs. */
+import { type FieldsetHTMLAttributes } from "react";
+import type { NativePartProps } from "../../lib/componentProps.js";
+export type RadioGroupProps<Value extends string> = Omit<FieldsetHTMLAttributes<HTMLFieldSetElement>, "onChange" | "defaultValue" | "children" | "dangerouslySetInnerHTML"> & {
     legend: string;
     options: {
         value: Value;
         label: string;
         description?: string;
         disabled?: boolean;
+        /** Native focus/blur/ref/ID access for form controllers; selection stays group-owned. */
+        inputProps?: Omit<NativePartProps<"input">, "type" | "name" | "form" | "value" | "defaultValue" | "checked" | "defaultChecked" | "disabled" | "required" | "onChange">;
     }[];
-    value: Value;
-    onChange: (value: Value) => void;
-    /** Lays options out in a row on wider screens. */
+    value?: Value;
+    defaultValue?: Value;
+    onChange?: (value: Value) => void;
     inline?: boolean;
+    required?: boolean;
+    description?: string;
+    error?: string;
 };
-export default function RadioGroup<Value extends string>({ legend, options, value, onChange, inline, }: RadioGroupProps<Value>): import("react").JSX.Element;
+export default function RadioGroup<Value extends string>({ legend, options, value, defaultValue, onChange, inline, name: providedName, form, id: providedId, disabled, required, description, error, className, "aria-describedby": describedBy, ...rest }: RadioGroupProps<Value>): import("react").JSX.Element;

package/dist/components/ui/RadioGroup.js

@@ -1,12 +1,39 @@
 "use client";
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-/** Fieldset of round radio options sharing one name, with a mono legend. */
-import { useId } from "react";
-import { cx } from "../../lib/classNames.js";
-export default function RadioGroup({ legend, options, value, onChange, inline = false, }) {
-    const name = useId();
-    return (_jsxs("fieldset", { className: cx("radio-group", inline && "radio-group-inline"), children: [_jsx("legend", { className: "field-label mono", children: legend }), options.map((option) => {
-                const id = `${name}-${option.value}`;
-                return (_jsxs("div", { className: "choice choice-radio", children: [_jsxs("span", { className: "choice-control", children: [_jsx("input", { id: id, type: "radio", name: name, value: option.value, checked: option.value === value, disabled: option.disabled, className: "choice-input", onChange: () => onChange(option.value) }), _jsx("span", { className: "choice-box", "aria-hidden": "true" })] }), _jsxs("label", { htmlFor: id, className: "choice-text", children: [_jsx("span", { className: "choice-label", children: option.label }), option.description && (_jsx("span", { className: "choice-description", children: option.description }))] })] }, option.value));
-            })] }));
+/** Native radios with caller form/name, controlled/default selection and option input refs. */
+import { useId, useLayoutEffect, useRef, useState, } from "react";
+import { cx, ccx } from "../../lib/classNames.js";
+import useFormReset from "../../hooks/useFormReset.js";
+export default function RadioGroup({ legend, options, value, defaultValue, onChange, inline = false, name: providedName, form, id: providedId, disabled, required, description, error, className, "aria-describedby": describedBy, ...rest }) {
+    const generatedId = useId();
+    const id = providedId ?? generatedId;
+    const name = providedName ?? generatedId;
+    const [initial] = useState(defaultValue ?? value);
+    const ref = useRef(null);
+    const inputs = () => ref.current?.querySelectorAll('input[type="radio"]');
+    useLayoutEffect(() => {
+        inputs()?.forEach((input) => {
+            input.defaultChecked = input.value === initial;
+            if (value !== undefined)
+                input.checked = input.value === value;
+        });
+    });
+    useFormReset(ref, () => {
+        if (value !== undefined)
+            inputs()?.forEach((input) => {
+                input.checked = input.value === value;
+            });
+    });
+    const context = cx(describedBy, description && `${id}-description`, error && `${id}-error`) || undefined;
+    return (_jsxs("fieldset", { ...rest, ref: ref, id: id, name: name, form: form, disabled: disabled, "aria-invalid": error ? true : rest["aria-invalid"], "aria-describedby": context, className: ccx("radio-group", inline && "radio-group-inline", className), children: [_jsx("legend", { className: ccx("field-label mono"), children: legend }), description && (_jsx("span", { id: `${id}-description`, className: ccx("choice-description"), children: description })), options.map((option) => {
+                const optionId = option.inputProps?.id ?? `${id}-${option.value}`;
+                return (_jsxs("div", { className: ccx("choice choice-radio"), children: [_jsxs("span", { className: ccx("choice-control"), children: [_jsx("input", { ...option.inputProps, id: optionId, type: "radio", name: name, form: form, value: option.value, checked: value === undefined ? undefined : option.value === value, defaultChecked: value === undefined ? option.value === initial : undefined, required: required, disabled: disabled || option.disabled, className: ccx("choice-input", option.inputProps?.className), "aria-invalid": error
+                                        ? true
+                                        : (option.inputProps?.["aria-invalid"] ??
+                                            rest["aria-invalid"]), "aria-describedby": cx(option.inputProps?.["aria-describedby"], context, option.description && `${optionId}-description`) || undefined, onChange: (event) => {
+                                        if (!event.currentTarget.checked)
+                                            return;
+                                        onChange?.(option.value);
+                                    } }), _jsx("span", { className: ccx("choice-box"), "aria-hidden": "true" })] }), _jsxs("label", { htmlFor: optionId, className: ccx("choice-text"), children: [_jsx("span", { className: ccx("choice-label"), children: option.label }), option.description && (_jsx("span", { id: `${optionId}-description`, className: ccx("choice-description"), children: option.description }))] })] }, option.value));
+            }), error && (_jsx("span", { id: `${id}-error`, className: ccx("choice-error mono"), children: error }))] }));
 }

package/dist/components/ui/Reveal.d.ts

@@ -1,4 +1,3 @@
-/** Fades and lifts its children into view the first time they enter the viewport. */
 import { type ReactNode } from "react";
 export type RevealProps = {
     children: ReactNode;

package/dist/components/ui/Reveal.js

@@ -1,6 +1,7 @@
 "use client";
 import { jsx as _jsx } from "react/jsx-runtime";
 /** Fades and lifts its children into view the first time they enter the viewport. */
+import { ccx } from "../../lib/classNames.js";
 import { useEffect, useRef } from "react";
 export default function Reveal({ children, className = "", delay = 0, }) {
     const ref = useRef(null);
@@ -9,17 +10,17 @@ export default function Reveal({ children, className = "", delay = 0, }) {
         if (!element)
             return;
         if (typeof IntersectionObserver === "undefined") {
-            element.classList.add("is-visible");
+            element.classList.add("is-visible", "contour-is-visible");
             return;
         }
         const observer = new IntersectionObserver(([entry]) => {
             if (!entry.isIntersecting)
                 return;
-            element.classList.add("is-visible");
+            element.classList.add("is-visible", "contour-is-visible");
             observer.disconnect();
         }, { threshold: 0, rootMargin: "0px 0px -24px 0px" });
         observer.observe(element);
         return () => observer.disconnect();
     }, []);
-    return (_jsx("div", { ref: ref, className: `reveal ${className}`, style: { transitionDelay: `${delay}ms` }, children: children }));
+    return (_jsx("div", { ref: ref, className: ccx("reveal", className), style: { transitionDelay: `${delay}ms` }, children: children }));
 }

package/dist/components/ui/RevealHeading.js

@@ -1,4 +1,5 @@
 import { jsx as _jsx } from "react/jsx-runtime";
+import { ccx } from "../../lib/classNames.js";
 export default function RevealHeading({ id, lines }) {
-    return (_jsx("h2", { id: id, children: lines.map((line, index) => (_jsx("span", { className: line.accent ? "type-line type-accent" : "type-line", children: _jsx("span", { className: "type-run", children: line.text }) }, index))) }));
+    return (_jsx("h2", { id: id, children: lines.map((line, index) => (_jsx("span", { className: ccx(line.accent ? "type-line type-accent" : "type-line"), children: _jsx("span", { className: ccx("type-run"), children: line.text }) }, index))) }));
 }

package/dist/components/ui/ScrollProgress.js

@@ -1,5 +1,6 @@
 "use client";
 import { jsx as _jsx } from "react/jsx-runtime";
+import { ccx } from "../../lib/classNames.js";
 /** Thin acid bar fixed to the top of the viewport that tracks page scroll progress. */
 import { useEffect, useRef } from "react";
 export default function ScrollProgress() {
@@ -24,5 +25,5 @@ export default function ScrollProgress() {
             window.removeEventListener("resize", update);
         };
     }, []);
-    return _jsx("div", { ref: ref, className: "scroll-progress", "aria-hidden": "true" });
+    return (_jsx("div", { ref: ref, className: ccx("scroll-progress"), "aria-hidden": "true" }));
 }

package/dist/components/ui/SectionLabel.js

@@ -1,5 +1,6 @@
 import { jsxs as _jsxs, jsx as _jsx } from "react/jsx-runtime";
+import { ccx } from "../../lib/classNames.js";
 import { formatIndex } from "../../lib/format.js";
 export default function SectionLabel({ section, aside }) {
-    return (_jsxs("div", { className: "section-label mono", children: [_jsxs("span", { children: [formatIndex(section.number), " / ", section.title] }), _jsx("span", { children: aside })] }));
+    return (_jsxs("div", { className: ccx("section-label mono"), children: [_jsxs("span", { children: [formatIndex(section.number), " / ", section.title] }), _jsx("span", { children: aside })] }));
 }

package/dist/components/ui/SegmentedControl.js

@@ -1,16 +1,19 @@
 "use client";
 import { jsx as _jsx } from "react/jsx-runtime";
+import { ccx } from "../../lib/classNames.js";
 /** Single-choice pill group (filter buttons) with arrow-key navigation. */
 import { useRef } from "react";
 import { nextIndexForKey } from "../../lib/keyboard.js";
 export default function SegmentedControl({ label, options, value, onChange, }) {
     const buttons = useRef([]);
-    return (_jsx("div", { className: "segmented", role: "radiogroup", "aria-label": label, children: options.map((option, index) => {
+    return (_jsx("div", { className: ccx("segmented"), role: "radiogroup", "aria-label": label, children: options.map((option, index) => {
             const selected = option.value === value;
             return (_jsx("button", { ref: (element) => {
                     buttons.current[index] = element;
-                }, type: "button", role: "radio", "aria-checked": selected, tabIndex: selected ? 0 : -1, className: "segmented-option", onClick: () => onChange(option.value), onKeyDown: (event) => {
-                    const next = nextIndexForKey(event.key, index, options.length);
+                }, type: "button", role: "radio", "aria-checked": selected, tabIndex: selected ? 0 : -1, className: ccx("segmented-option"), onClick: () => onChange(option.value), onKeyDown: (event) => {
+                    const next = nextIndexForKey(event.key, index, options.length, "horizontal", event.currentTarget.ownerDocument.defaultView?.getComputedStyle(event.currentTarget).direction === "rtl"
+                        ? "rtl"
+                        : "ltr");
                     if (next === null)
                         return;
                     event.preventDefault();

package/dist/components/ui/SelectField.js

@@ -1,15 +1,30 @@
 "use client";
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { ccx } from "../../lib/classNames.js";
 /** Native select styled as an underlined field with a chevron. */
 import { forwardRef, useId } from "react";
 import { ChevronDown } from "lucide-react";
 import { fieldDescribedBy } from "../../lib/a11y.js";
 import Field from "./Field.js";
-const SelectField = forwardRef(function SelectField({ id: providedId, "aria-describedby": describedBy, label, options, hint, error, placeholder, ...rest }, ref) {
+import useControlRef from "../../hooks/useControlRef.js";
+import useFormReset from "../../hooks/useFormReset.js";
+/** Native reset does not preserve React's controlled selection on its own. */
+function restoreSelection(control, value) {
+    const values = new Set(Array.isArray(value) ? value.map(String) : [String(value)]);
+    for (const option of control.options)
+        option.selected = values.has(option.value);
+}
+const SelectField = forwardRef(function SelectField({ id: providedId, "aria-describedby": describedBy, label, options, hint, error, placeholder, ...rest }, forwardedRef) {
     const generatedId = useId();
     const id = providedId ?? generatedId;
-    return (_jsx(Field, { id: id, label: label, hint: hint, error: error, required: rest.required, disabled: rest.disabled, children: _jsxs("div", { className: "field-control field-select", children: [_jsxs("select", { ...rest, ref: ref, id: id, "aria-invalid": error ? true : rest["aria-invalid"], "aria-describedby": [describedBy, fieldDescribedBy(id, hint, error)]
+    const { ref, attach } = useControlRef(forwardedRef);
+    useFormReset(ref, () => {
+        if (!ref.current || rest.value === undefined)
+            return;
+        restoreSelection(ref.current, rest.value);
+    });
+    return (_jsx(Field, { id: id, label: label, hint: hint, error: error, required: rest.required, disabled: rest.disabled, children: _jsxs("div", { className: ccx("field-control field-select"), children: [_jsxs("select", { ...rest, ref: attach, id: id, "aria-invalid": error ? true : rest["aria-invalid"], "aria-describedby": [describedBy, fieldDescribedBy(id, hint, error)]
                         .filter(Boolean)
-                        .join(" ") || undefined, children: [placeholder && (_jsx("option", { value: "", disabled: true, children: placeholder })), options.map((option) => (_jsx("option", { value: option.value, children: option.label }, option.value)))] }), _jsx(ChevronDown, { className: "field-chevron", size: 16, "aria-hidden": "true" })] }) }));
+                        .join(" ") || undefined, children: [placeholder && (_jsx("option", { value: "", disabled: true, children: placeholder })), options.map((option) => (_jsx("option", { value: option.value, children: option.label }, option.value)))] }), _jsx(ChevronDown, { className: ccx("field-chevron"), size: 16, "aria-hidden": "true" })] }) }));
 });
 export default SelectField;

package/dist/components/ui/Skeleton.js

@@ -1,5 +1,5 @@
 import { jsx as _jsx } from "react/jsx-runtime";
-import { cx } from "../../lib/classNames.js";
+import { ccx } from "../../lib/classNames.js";
 export default function Skeleton({ shape = "line", width, height, }) {
-    return (_jsx("span", { "aria-hidden": "true", className: cx("skeleton", `skeleton-${shape}`), style: { width, height } }));
+    return (_jsx("span", { "aria-hidden": "true", className: ccx("skeleton", `skeleton-${shape}`), style: { width, height } }));
 }

package/dist/components/ui/Slider.d.ts

@@ -1,13 +1,29 @@
-export type SliderProps = {
+/** Native range submission with controlled/default state, reset and a formatted readout. */
+import { type InputHTMLAttributes } from "react";
+export type SliderProps = Omit<InputHTMLAttributes<HTMLInputElement>, "type" | "value" | "defaultValue" | "onChange" | "required" | "dangerouslySetInnerHTML" | "children" | "min" | "max" | "step"> & {
     label: string;
-    value: number;
-    onChange: (value: number) => void;
+    value?: number;
+    defaultValue?: number;
+    onChange?: (value: number) => void;
     min?: number;
     max?: number;
-    step?: number;
-    /** Formats the readout, e.g. (value) => `${value}%`. */
+    step?: number | "any";
+    /** Formats the readout and accessible value text. */
     format?: (value: number) => string;
-    disabled?: boolean;
+    hint?: string;
+    error?: string;
 };
-declare const Slider: import("react").ForwardRefExoticComponent<SliderProps & import("react").RefAttributes<HTMLInputElement>>;
+declare const Slider: import("react").ForwardRefExoticComponent<Omit<InputHTMLAttributes<HTMLInputElement>, "children" | "max" | "min" | "type" | "dangerouslySetInnerHTML" | "onChange" | "step" | "value" | "defaultValue" | "required"> & {
+    label: string;
+    value?: number;
+    defaultValue?: number;
+    onChange?: (value: number) => void;
+    min?: number;
+    max?: number;
+    step?: number | "any";
+    /** Formats the readout and accessible value text. */
+    format?: (value: number) => string;
+    hint?: string;
+    error?: string;
+} & import("react").RefAttributes<HTMLInputElement>>;
 export default Slider;

package/dist/components/ui/Slider.js

@@ -1,12 +1,49 @@
 "use client";
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-/** Range slider with a filled acid track and a live value readout. */
-import { forwardRef, useId } from "react";
-const Slider = forwardRef(function Slider({ label, value, onChange, min = 0, max = 100, step = 1, format = String, disabled, }, ref) {
-    const id = useId();
+/** Native range submission with controlled/default state, reset and a formatted readout. */
+import { forwardRef, useId, useLayoutEffect, useState, } from "react";
+import { cx, ccx } from "../../lib/classNames.js";
+import useControlRef from "../../hooks/useControlRef.js";
+import useFormReset from "../../hooks/useFormReset.js";
+const Slider = forwardRef(function Slider({ label, value, defaultValue, onChange, min = 0, max = 100, step = 1, format = String, disabled, id: providedId, className, style, onInput, hint, error, "aria-describedby": describedBy, ...rest }, forwardedRef) {
+    const generatedId = useId();
+    const id = providedId ?? generatedId;
+    const [initial] = useState(defaultValue ?? value ?? (min + Math.max(min, max)) / 2);
+    const [readout, setReadout] = useState(value ?? initial);
+    const { ref, attach } = useControlRef(forwardedRef);
+    useLayoutEffect(() => {
+        const input = ref.current;
+        if (!input)
+            return;
+        input.defaultValue = String(initial);
+        // Read the browser's sanitized value; clamp/step behavior stays native.
+        if (value !== undefined)
+            input.value = String(value);
+        const actual = input.valueAsNumber;
+        if (Number.isFinite(actual))
+            setReadout(actual);
+    }, [readout, initial, min, max, step, ref, value]);
+    useFormReset(ref, () => {
+        const input = ref.current;
+        if (!input)
+            return;
+        if (value !== undefined)
+            input.value = String(value);
+        setReadout(input.valueAsNumber);
+    });
     const progress = max > min
-        ? Math.min(100, Math.max(0, ((value - min) / (max - min)) * 100))
+        ? Math.min(100, Math.max(0, ((readout - min) / (max - min)) * 100))
         : 0;
-    return (_jsxs("div", { className: "slider", children: [_jsxs("div", { className: "slider-header mono", children: [_jsx("label", { htmlFor: id, className: "field-label", children: label }), _jsx("output", { htmlFor: id, children: format(value) })] }), _jsx("input", { ref: ref, id: id, type: "range", min: min, max: max, step: step, value: value, disabled: disabled, "aria-valuetext": format(value), style: { "--progress": `${progress}%` }, onChange: (event) => onChange(Number(event.target.value)) })] }));
+    return (_jsxs("div", { className: ccx("slider"), children: [_jsxs("div", { className: ccx("slider-header mono"), children: [_jsx("label", { htmlFor: id, className: ccx("field-label"), children: label }), _jsx("output", { htmlFor: id, children: format(readout) })] }), _jsx("input", { ...rest, ref: attach, id: id, type: "range", min: min, max: max, step: step, value: value, defaultValue: value === undefined ? initial : undefined, disabled: disabled, className: className, "aria-invalid": error ? true : rest["aria-invalid"], "aria-describedby": cx(describedBy, hint && `${id}-hint`, error && `${id}-error`) ||
+                    undefined, "aria-valuetext": rest["aria-valuetext"] ?? format(readout), style: { ...style, "--progress": `${progress}%` }, onInput: (event) => {
+                    if (value === undefined)
+                        setReadout(event.currentTarget.valueAsNumber);
+                    onInput?.(event);
+                }, onChange: (event) => {
+                    const next = event.currentTarget.valueAsNumber;
+                    if (value === undefined)
+                        setReadout(next);
+                    onChange?.(next);
+                } }), hint && (_jsx("span", { id: `${id}-hint`, className: ccx("choice-description"), children: hint })), error && (_jsx("span", { id: `${id}-error`, className: ccx("choice-error mono"), children: error }))] }));
 });
 export default Slider;

package/dist/components/ui/Spinner.js

@@ -1,8 +1,8 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 /** Brand asterisk that spins as a loading indicator; announces its label to assistive tech. */
 import { Asterisk } from "lucide-react";
-import { cx } from "../../lib/classNames.js";
+import { ccx } from "../../lib/classNames.js";
 const iconSizes = { sm: 16, md: 24, lg: 40 };
 export default function Spinner({ size = "md", label = "Loading", className, }) {
-    return (_jsxs("span", { role: "status", className: cx("spinner", `spinner-${size}`, className), children: [_jsx(Asterisk, { size: iconSizes[size], strokeWidth: 1.6, "aria-hidden": "true" }), _jsx("span", { className: "visually-hidden", children: label })] }));
+    return (_jsxs("span", { role: "status", className: ccx("spinner", `spinner-${size}`, className), children: [_jsx(Asterisk, { size: iconSizes[size], strokeWidth: 1.6, "aria-hidden": "true" }), _jsx("span", { className: ccx("visually-hidden"), children: label })] }));
 }

package/dist/components/ui/Stat.js

@@ -1,4 +1,5 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { ccx } from "../../lib/classNames.js";
 export default function Stat({ value, label, suffix }) {
-    return (_jsxs("div", { className: "stat", children: [_jsxs("strong", { children: [value, suffix && _jsx("span", { className: "stat-suffix", children: suffix })] }), _jsx("span", { className: "mono", children: label })] }));
+    return (_jsxs("div", { className: ccx("stat"), children: [_jsxs("strong", { children: [value, suffix && _jsx("span", { className: ccx("stat-suffix"), children: suffix })] }), _jsx("span", { className: ccx("mono"), children: label })] }));
 }

package/dist/components/ui/Stepper.js

@@ -1,15 +1,15 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 /** Numbered progress steps joined by a rule; completed steps show a check. */
 import { Check } from "lucide-react";
-import { cx } from "../../lib/classNames.js";
+import { ccx } from "../../lib/classNames.js";
 import { formatIndex } from "../../lib/format.js";
 export default function Stepper({ steps, current, label = "Progress", }) {
-    return (_jsx("ol", { className: "stepper", "aria-label": label, children: steps.map((step, index) => {
+    return (_jsx("ol", { className: ccx("stepper"), "aria-label": label, children: steps.map((step, index) => {
             const state = index < current
                 ? "complete"
                 : index === current
                     ? "current"
                     : "upcoming";
-            return (_jsxs("li", { className: cx("stepper-step", `stepper-${state}`), "aria-current": state === "current" ? "step" : undefined, children: [_jsx("span", { className: "stepper-marker mono", "aria-hidden": "true", children: state === "complete" ? (_jsx(Check, { size: 14, strokeWidth: 2.5 })) : (formatIndex(index + 1)) }), _jsxs("span", { className: "stepper-text", children: [_jsx("span", { className: "stepper-label", children: step.label }), step.description && (_jsx("span", { className: "stepper-description mono", children: step.description })), _jsxs("span", { className: "visually-hidden", children: ["(", state, ")"] })] })] }, step.label));
+            return (_jsxs("li", { className: ccx("stepper-step", `stepper-${state}`), "aria-current": state === "current" ? "step" : undefined, children: [_jsx("span", { className: ccx("stepper-marker mono"), "aria-hidden": "true", children: state === "complete" ? (_jsx(Check, { size: 14, strokeWidth: 2.5 })) : (formatIndex(index + 1)) }), _jsxs("span", { className: ccx("stepper-text"), children: [_jsx("span", { className: ccx("stepper-label"), children: step.label }), step.description && (_jsx("span", { className: ccx("stepper-description mono"), children: step.description })), _jsxs("span", { className: ccx("visually-hidden"), children: ["(", state, ")"] })] })] }, step.label));
         }) }));
 }

package/dist/components/ui/Switch.d.ts

@@ -1,9 +1,31 @@
-export type SwitchProps = {
+/** Button switch with a native checkbox backing submission, validation and reset. */
+import { type ButtonHTMLAttributes, type FormEventHandler } from "react";
+export type SwitchProps = Omit<ButtonHTMLAttributes<HTMLButtonElement>, "onChange" | "value" | "defaultValue" | "onInvalid" | "children" | "dangerouslySetInnerHTML"> & {
     label: string;
-    checked: boolean;
-    onChange: (checked: boolean) => void;
+    checked?: boolean;
+    defaultChecked?: boolean;
+    onChange?: (checked: boolean) => void;
+    /** Submitted only when checked; defaults to the native checkbox value "on". */
+    value?: string;
+    required?: boolean;
+    requiredMessage?: string;
     description?: string;
-    disabled?: boolean;
+    error?: string;
+    /** Native invalid event from the backing checkbox; preventDefault owns feedback/focus. */
+    onInvalid?: FormEventHandler<HTMLInputElement>;
 };
-declare const Switch: import("react").ForwardRefExoticComponent<SwitchProps & import("react").RefAttributes<HTMLButtonElement>>;
+declare const Switch: import("react").ForwardRefExoticComponent<Omit<ButtonHTMLAttributes<HTMLButtonElement>, "children" | "dangerouslySetInnerHTML" | "onChange" | "onInvalid" | "value" | "defaultValue"> & {
+    label: string;
+    checked?: boolean;
+    defaultChecked?: boolean;
+    onChange?: (checked: boolean) => void;
+    /** Submitted only when checked; defaults to the native checkbox value "on". */
+    value?: string;
+    required?: boolean;
+    requiredMessage?: string;
+    description?: string;
+    error?: string;
+    /** Native invalid event from the backing checkbox; preventDefault owns feedback/focus. */
+    onInvalid?: FormEventHandler<HTMLInputElement>;
+} & import("react").RefAttributes<HTMLButtonElement>>;
 export default Switch;