@abuzareal/contour-ui 0.4.0 → 0.5.0

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.js

@@ -2,7 +2,7 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 /** Native radios with caller form/name, controlled/default selection and option input refs. */
 import { useId, useLayoutEffect, useRef, useState, } from "react";
-import { cx } from "../../lib/classNames.js";
+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();
@@ -25,15 +25,15 @@ export default function RadioGroup({ legend, options, value, defaultValue, onCha
             });
     });
     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: cx("radio-group", inline && "radio-group-inline", className), children: [_jsx("legend", { className: "field-label mono", children: legend }), description && (_jsx("span", { id: `${id}-description`, className: "choice-description", children: description })), options.map((option) => {
+    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: "choice choice-radio", children: [_jsxs("span", { className: "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: cx("choice-input", option.inputProps?.className), "aria-invalid": error
+                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: "choice-box", "aria-hidden": "true" })] }), _jsxs("label", { htmlFor: optionId, className: "choice-text", children: [_jsx("span", { className: "choice-label", children: option.label }), option.description && (_jsx("span", { id: `${optionId}-description`, className: "choice-description", children: option.description }))] })] }, option.value));
-            }), error && (_jsx("span", { id: `${id}-error`, className: "choice-error mono", children: error }))] }));
+                                    } }), _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,5 +1,6 @@
 "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";
@@ -22,8 +23,8 @@ const SelectField = forwardRef(function SelectField({ id: providedId, "aria-desc
             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: "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)]
+    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.js

@@ -2,7 +2,7 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 /** Native range submission with controlled/default state, reset and a formatted readout. */
 import { forwardRef, useId, useLayoutEffect, useState, } from "react";
-import { cx } from "../../lib/classNames.js";
+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) {
@@ -34,7 +34,7 @@ const Slider = forwardRef(function Slider({ label, value, defaultValue, onChange
     const progress = max > min
         ? 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(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`) ||
+    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);
@@ -44,6 +44,6 @@ const Slider = forwardRef(function Slider({ label, value, defaultValue, onChange
                     if (value === undefined)
                         setReadout(next);
                     onChange?.(next);
-                } }), hint && (_jsx("span", { id: `${id}-hint`, className: "choice-description", children: hint })), error && (_jsx("span", { id: `${id}-error`, className: "choice-error mono", children: error }))] }));
+                } }), 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

@@ -8,6 +8,7 @@ export type SwitchProps = Omit<ButtonHTMLAttributes<HTMLButtonElement>, "onChang
     /** 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. */
@@ -21,6 +22,7 @@ declare const Switch: import("react").ForwardRefExoticComponent<Omit<ButtonHTMLA
     /** 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. */

package/dist/components/ui/Switch.js

@@ -2,10 +2,10 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 /** Button switch with a native checkbox backing submission, validation and reset. */
 import { forwardRef, useId, useLayoutEffect, useRef, useState, } from "react";
-import { cx } from "../../lib/classNames.js";
+import { cx, ccx } from "../../lib/classNames.js";
 import useControlRef from "../../hooks/useControlRef.js";
 import useFormReset from "../../hooks/useFormReset.js";
-const Switch = forwardRef(function Switch({ label, checked, defaultChecked, onChange, description, error, disabled, required, name, form, value = "on", id: providedId, className, onClick, onInvalid, "aria-describedby": describedBy, ...rest }, forwardedRef) {
+const Switch = forwardRef(function Switch({ label, checked, defaultChecked, onChange, description, error, disabled, required, requiredMessage = "Turn on this option to continue.", name, form, value = "on", id: providedId, className, onClick, onInvalid, "aria-describedby": describedBy, ...rest }, forwardedRef) {
     const generatedId = useId();
     const id = providedId ?? generatedId;
     const [initial] = useState(defaultChecked ?? checked ?? false);
@@ -14,8 +14,7 @@ const Switch = forwardRef(function Switch({ label, checked, defaultChecked, onCh
     const current = checked ?? localChecked;
     const { ref: button, attach } = useControlRef(forwardedRef);
     const input = useRef(null);
-    const message = error ??
-        (invalid && !current ? "Turn on this option to continue." : undefined);
+    const message = error ?? (invalid && !current ? requiredMessage : undefined);
     useLayoutEffect(() => {
         if (input.current) {
             input.current.defaultChecked = initial;
@@ -29,7 +28,7 @@ const Switch = forwardRef(function Switch({ label, checked, defaultChecked, onCh
             input.current.checked = checked;
         setInvalid(false);
     });
-    return (_jsxs("div", { className: "switch", children: [_jsx("button", { ...rest, ref: attach, id: id, name: undefined, form: form, type: "button", role: "switch", "aria-labelledby": cx(`${id}-label`, rest["aria-labelledby"]), "aria-checked": current, "aria-required": required || undefined, "aria-invalid": message ? true : rest["aria-invalid"], "aria-describedby": cx(describedBy, description && `${id}-description`, message && `${id}-error`) || undefined, disabled: disabled, className: cx("switch-track", className), onClick: (event) => {
+    return (_jsxs("div", { className: ccx("switch"), children: [_jsx("button", { ...rest, ref: attach, id: id, name: undefined, form: form, type: "button", role: "switch", "aria-labelledby": cx(`${id}-label`, rest["aria-labelledby"]), "aria-checked": current, "aria-required": required || undefined, "aria-invalid": message ? true : rest["aria-invalid"], "aria-describedby": cx(describedBy, description && `${id}-description`, message && `${id}-error`) || undefined, disabled: disabled, className: ccx("switch-track", className), onClick: (event) => {
                     onClick?.(event);
                     if (event.defaultPrevented)
                         return;
@@ -42,7 +41,7 @@ const Switch = forwardRef(function Switch({ label, checked, defaultChecked, onCh
                     }
                     setInvalid(false);
                     onChange?.(!current);
-                }, children: _jsx("span", { className: "switch-thumb" }) }), _jsx("input", { ref: input, type: "checkbox", hidden: true, "aria-hidden": "true", tabIndex: -1, name: name, form: form, value: value, disabled: disabled, required: required, checked: checked, defaultChecked: checked === undefined ? initial : undefined, onChange: () => { }, onInvalid: (event) => {
+                }, children: _jsx("span", { className: ccx("switch-thumb") }) }), _jsx("input", { ref: input, type: "checkbox", hidden: true, "aria-hidden": "true", tabIndex: -1, name: name, form: form, value: value, disabled: disabled, required: required, checked: checked, defaultChecked: checked === undefined ? initial : undefined, onChange: () => { }, onInvalid: (event) => {
                     onInvalid?.(event);
                     const canceled = event.defaultPrevented;
                     // Native validation must never try to focus the noninteractive backing control.
@@ -51,6 +50,6 @@ const Switch = forwardRef(function Switch({ label, checked, defaultChecked, onCh
                         setInvalid(true);
                         button.current?.focus();
                     }
-                } }), _jsxs("label", { htmlFor: id, className: "choice-text", children: [_jsx("span", { id: `${id}-label`, className: "choice-label", children: label }), description && (_jsx("span", { id: `${id}-description`, className: "choice-description", children: description })), message && (_jsx("span", { id: `${id}-error`, className: "choice-error mono", children: message }))] })] }));
+                } }), _jsxs("label", { htmlFor: id, className: ccx("choice-text"), children: [_jsx("span", { id: `${id}-label`, className: ccx("choice-label"), children: label }), description && (_jsx("span", { id: `${id}-description`, className: ccx("choice-description"), children: description })), message && (_jsx("span", { id: `${id}-error`, className: ccx("choice-error mono"), children: message }))] })] }));
 });
 export default Switch;

package/dist/components/ui/Tabs.js

@@ -4,7 +4,7 @@ import { createElement as _createElement } from "react";
 /** Controlled/default tabs, with props and native refs for root/list/buttons/panels. */
 import { forwardRef, useId, useLayoutEffect, useRef, useState, } from "react";
 import { nextIndexForKey } from "../../lib/keyboard.js";
-import { cx } from "../../lib/classNames.js";
+import { cx, ccx } from "../../lib/classNames.js";
 import useTabRefs from "../../hooks/useTabRefs.js";
 const Tabs = forwardRef(function Tabs({ label, tabs, defaultTabId, activeTabId, onTabChange, listProps, className, id, ...rest }, ref) {
     const generatedId = useId();
@@ -45,13 +45,13 @@ const Tabs = forwardRef(function Tabs({ label, tabs, defaultTabId, activeTabId,
     };
     const buttonId = (tab) => tab.buttonProps?.id ?? `${baseId}-tab-${tab.id}`;
     const panelId = (tab) => tab.panelProps?.id ?? `${baseId}-panel-${tab.id}`;
-    return (_jsxs("div", { ...rest, ref: ref, id: id, className: cx("tabs", className), children: [_jsx("div", { ...listProps, className: cx("tabs-list", listProps?.className), role: "tablist", "aria-label": label, style: {
+    return (_jsxs("div", { ...rest, ref: ref, id: id, className: ccx("tabs", className), children: [_jsx("div", { ...listProps, className: ccx("tabs-list", listProps?.className), role: "tablist", "aria-label": label, style: {
                     ...listProps?.style,
                     "--indicator-left": `${indicator.left}px`,
                     "--indicator-width": `${indicator.width}px`,
                 }, children: tabs.map((tab, index) => {
                     const selected = tab.id === selectedId;
-                    return (_createElement("button", { ...tab.buttonProps, key: tab.id, ref: buttonRefs[index], id: buttonId(tab), type: "button", role: "tab", "aria-selected": selected, "aria-controls": panelId(tab), tabIndex: selected ? 0 : -1, className: cx("tabs-tab", tab.buttonProps?.className), onClick: (event) => {
+                    return (_createElement("button", { ...tab.buttonProps, key: tab.id, ref: buttonRefs[index], id: buttonId(tab), type: "button", role: "tab", "aria-selected": selected, "aria-controls": panelId(tab), tabIndex: selected ? 0 : -1, className: ccx("tabs-tab", tab.buttonProps?.className), onClick: (event) => {
                             tab.buttonProps?.onClick?.(event);
                             if (!event.defaultPrevented)
                                 select(tab);
@@ -59,12 +59,14 @@ const Tabs = forwardRef(function Tabs({ label, tabs, defaultTabId, activeTabId,
                             tab.buttonProps?.onKeyDown?.(event);
                             if (event.defaultPrevented)
                                 return;
-                            const next = nextIndexForKey(event.key, index, tabs.length);
+                            const next = nextIndexForKey(event.key, index, tabs.length, "horizontal", event.currentTarget.ownerDocument.defaultView?.getComputedStyle(event.currentTarget).direction === "rtl"
+                                ? "rtl"
+                                : "ltr");
                             if (next === null)
                                 return;
                             event.preventDefault();
                             select(tabs[next], true);
                         } }, tab.label));
-                }) }), tabs.map((tab) => (_createElement("div", { ...tab.panelProps, key: tab.id, id: panelId(tab), role: "tabpanel", "aria-labelledby": cx(buttonId(tab), tab.panelProps?.["aria-labelledby"]), hidden: tab.id !== selectedId, tabIndex: 0, className: cx("tabs-panel", tab.panelProps?.className) }, tab.content)))] }));
+                }) }), tabs.map((tab) => (_createElement("div", { ...tab.panelProps, key: tab.id, id: panelId(tab), role: "tabpanel", "aria-labelledby": cx(buttonId(tab), tab.panelProps?.["aria-labelledby"]), hidden: tab.id !== selectedId, tabIndex: 0, className: ccx("tabs-panel", tab.panelProps?.className) }, tab.content)))] }));
 });
 export default Tabs;

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

@@ -1,5 +1,6 @@
 export type TagProps = {
     children: string;
+    removeLabel?: string;
     onRemove?: () => void;
 };
-export default function Tag({ children, onRemove }: TagProps): import("react").JSX.Element;
+export default function Tag({ children, onRemove, removeLabel }: TagProps): import("react").JSX.Element;

package/dist/components/ui/Tag.js

@@ -1,9 +1,10 @@
 "use client";
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { ccx } from "../../lib/classNames.js";
 /** Mono "+ tag" label (as in project notes); becomes a removable chip when given onRemove. */
 import { X } from "lucide-react";
-export default function Tag({ children, onRemove }) {
+export default function Tag({ children, onRemove, removeLabel }) {
     if (!onRemove)
-        return _jsx("span", { className: "tag mono", children: children });
-    return (_jsxs("span", { className: "tag tag-removable mono", children: [children, _jsx("button", { type: "button", className: "tag-remove", "aria-label": `Remove ${children}`, onClick: onRemove, children: _jsx(X, { size: 12 }) })] }));
+        return _jsx("span", { className: ccx("tag mono"), children: children });
+    return (_jsxs("span", { className: ccx("tag tag-removable mono"), children: [children, _jsx("button", { type: "button", className: ccx("tag-remove"), "aria-label": removeLabel ?? `Remove ${children}`, onClick: onRemove, children: _jsx(X, { size: 12 }) })] }));
 }

package/dist/components/ui/TextArea.js

@@ -1,5 +1,6 @@
 "use client";
 import { jsx as _jsx } from "react/jsx-runtime";
+import { ccx } from "../../lib/classNames.js";
 /** Multi-line text input with optional auto-resize and character counter. */
 import { forwardRef, useId, useLayoutEffect, useState, } from "react";
 import { fieldDescribedBy } from "../../lib/a11y.js";
@@ -27,7 +28,7 @@ const TextArea = forwardRef(function TextArea({ id: providedId, "aria-describedb
     });
     return (_jsx(Field, { id: id, label: label, hint: hint, error: error, required: rest.required, disabled: rest.disabled, counter: maxLength !== undefined
             ? `${rest.value !== undefined ? String(rest.value).length : length}/${maxLength}`
-            : undefined, children: _jsx("div", { className: "field-control", children: _jsx("textarea", { ...rest, ref: attach, id: id, rows: rows, maxLength: maxLength, "data-auto-resize": autoResize || undefined, "aria-invalid": error ? true : rest["aria-invalid"], "aria-describedby": [describedBy, fieldDescribedBy(id, hint, error)]
+            : undefined, children: _jsx("div", { className: ccx("field-control"), children: _jsx("textarea", { ...rest, ref: attach, id: id, rows: rows, maxLength: maxLength, "data-auto-resize": autoResize || undefined, "aria-invalid": error ? true : rest["aria-invalid"], "aria-describedby": [describedBy, fieldDescribedBy(id, hint, error)]
                     .filter(Boolean)
                     .join(" ") || undefined, 
                 // Native input also runs when React deduplicates a repeated value after form.reset().

package/dist/components/ui/TextField.js

@@ -1,5 +1,6 @@
 "use client";
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { ccx } from "../../lib/classNames.js";
 /** Single-line text input with underline styling, optional icon/adornment, and character counter. */
 import { forwardRef, useId, useState, } from "react";
 import { fieldDescribedBy } from "../../lib/a11y.js";
@@ -18,7 +19,7 @@ const TextField = forwardRef(function TextField({ id: providedId, "aria-describe
     });
     return (_jsx(Field, { id: id, label: label, hint: hint, error: error, required: rest.required, hideLabel: hideLabel, disabled: rest.disabled, counter: maxLength !== undefined
             ? `${rest.value !== undefined ? String(rest.value).length : length}/${maxLength}`
-            : undefined, children: _jsxs("div", { className: "field-control", children: [leadingIcon && _jsx("span", { className: "field-icon", children: leadingIcon }), _jsx("input", { ...rest, ref: attach, id: id, maxLength: maxLength, "aria-invalid": error ? true : rest["aria-invalid"], "aria-describedby": [describedBy, fieldDescribedBy(id, hint, error)]
+            : undefined, children: _jsxs("div", { className: ccx("field-control"), children: [leadingIcon && (_jsx("span", { className: ccx("field-icon"), children: leadingIcon })), _jsx("input", { ...rest, ref: attach, id: id, maxLength: maxLength, "aria-invalid": error ? true : rest["aria-invalid"], "aria-describedby": [describedBy, fieldDescribedBy(id, hint, error)]
                         .filter(Boolean)
                         .join(" ") || undefined, 
                     // Native input also runs when React deduplicates a repeated value after form.reset().
@@ -28,6 +29,6 @@ const TextField = forwardRef(function TextField({ id: providedId, "aria-describe
                     }, onChange: (event) => {
                         setLength(event.target.value.length);
                         onChange?.(event);
-                    } }), trailing && _jsx("span", { className: "field-trailing", children: trailing })] }) }));
+                    } }), trailing && (_jsx("span", { className: ccx("field-trailing"), children: trailing }))] }) }));
 });
 export default TextField;

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

@@ -0,0 +1,13 @@
+import type { HTMLAttributes } from "react";
+import type { Theme } from "../../hooks/useTheme.js";
+export type ThemeScopeProps = HTMLAttributes<HTMLDivElement> & {
+    theme: Theme;
+    /** Caller owns persistence; omitting this makes embedded theme controls read-only. */
+    onThemeChange?: (theme: Theme) => void;
+};
+declare const ThemeScope: import("react").ForwardRefExoticComponent<HTMLAttributes<HTMLDivElement> & {
+    theme: Theme;
+    /** Caller owns persistence; omitting this makes embedded theme controls read-only. */
+    onThemeChange?: (theme: Theme) => void;
+} & import("react").RefAttributes<HTMLDivElement>>;
+export default ThemeScope;

package/dist/components/ui/ThemeScope.js

@@ -0,0 +1,10 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+import { forwardRef, useMemo } from "react";
+import { ThemeScopeContext } from "../../lib/themeScope.js";
+import { cx } from "../../lib/classNames.js";
+const ThemeScope = forwardRef(function ThemeScope({ theme, onThemeChange, className, children, ...rest }, ref) {
+    const context = useMemo(() => ({ theme, onThemeChange }), [theme, onThemeChange]);
+    return (_jsx(ThemeScopeContext.Provider, { value: context, children: _jsx("div", { ...rest, ref: ref, "data-contour-theme": theme, className: cx("contour-root", className), children: children }) }));
+});
+export default ThemeScope;

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

@@ -1,6 +1,9 @@
 export type ThemeToggleProps = {
     /** When false the theme switches instantly instead of animating. */
     animate: boolean;
+    darkLabel?: string;
+    lightTitle?: string;
+    darkTitle?: string;
 };
 declare const ThemeToggle: import("react").ForwardRefExoticComponent<ThemeToggleProps & import("react").RefAttributes<HTMLButtonElement>>;
 export default ThemeToggle;