@abuzareal/contour-ui 0.2.1 → 0.4.0

package/README.md

@@ -6,18 +6,20 @@ Use it when you want this visual style with typed controls, feedback, navigation
 
 [Live catalogue](https://contour.abuzr.in/) · [npm package](https://www.npmjs.com/package/@abuzareal/contour-ui) · [Maintainer](https://github.com/abuzareal)
 
-This source checkout targets **0.2.1**. Package publication and application upgrades are separate; check the npm registry for release availability and each application's manifest for its installed version. Catalogue examples include application patterns as well as package components. Check the exports below before treating an example as an importable component.
+This source checkout targets **0.4.0**. Package publication and application upgrades are separate; check the npm registry for release availability and each application's manifest for its installed version. Catalogue examples include application patterns as well as package components. Check the exports below before treating an example as an importable component.
 
 [Public API and maturity register](PUBLIC-API.md) · [Architecture, scope and compatibility](CONTRACTS.md)
 
-Version 0.2.1 documents baseline contracts and limitations and includes compatible Checkbox ARIA and clipboard lifecycle fixes. Export names, prop types, style defaults, dependencies and optional entry boundaries match 0.2.0. It remains an early 0.x library.
+Version 0.3.0 adds native refs for actions/choices and typed root/part props for Dialog, Tabs and Popover. It preserves existing state callbacks, styles, runtime dependencies and optional entry boundaries. See [refs, parts and link composition](COMPOSITION.md). Check npm availability before installing; this remains an early 0.x library.
+
+Version 0.4.0 adds native named/external form submission and controlled/default/reset support for Switch, Slider and RadioGroup, plus caller IDs for Checkbox. See [the form guide](FORMS.md) and the copyable native/RHF source recipes shipped in examples/forms. React Hook Form is an application dependency; no runtime dependency or CSS rewrite is added. New form props are absent from 0.3.0.
 
 ## Install
 
 Use an existing React application with a bundler that resolves package CSS imports. Contour ships ESM and TypeScript declarations. The package declares Node.js 22 or newer; repository tooling uses Vite 8, which needs Node.js 22.12+ or 24+.
 
 ```sh
-npm install @abuzareal/contour-ui@0.2.1 --save-exact
+npm install @abuzareal/contour-ui@0.4.0 --save-exact
 ```
 
 Your app must provide matching `react` and `react-dom` versions: **18.3.1 or React 19**. The compatibility script covers 18.3.1, 19.0.0, and 19.3.0; it doesn't establish support for every framework or React Server Component setup. Put interactive components inside a client boundary when your framework requires one.
@@ -118,7 +120,7 @@ The root entry also exports theme, motion, clipboard, dismissal, navigation, and
 
 Use visible field labels, accessible names for icon buttons, and text alongside status colors. `DataTable` sorts scalar string/number values; `Pagination` expects a positive integer page count and a page within that range. Flip cards use a button and make the hidden face inert.
 
-Props support varies between components. Don't assume every export forwards DOM refs, accepts arbitrary native attributes, supports router `asChild` composition, or integrates with form libraries through refs. Verify the relevant type before adopting it.
+Props support varies between components. Button/IconButton/DepthButton/ThemeToggle, ExternalLink and the native fields/choices expose the targets listed in [the composition guide](COMPOSITION.md#native-ref-targets). Dialog/Tabs/Popover support their documented root and owned parts. Don't assume every wrapper or multi-control group forwards a single DOM ref, accepts arbitrary native attributes, supports router `asChild` composition, or integrates with form libraries through refs. Verify the relevant type before adopting it.
 
 ## Optional scenes and scrolling
 
@@ -164,7 +166,7 @@ Give scenes a sized container and a usable static fallback. `SceneBoundary` hide
 **0.2.0** adds native field refs, controlled tabs and popover/menu open state, menu keyboard improvements, native reset synchronization, Three.js lifecycle fixes and a tested Next.js App Router integration. Existing uncontrolled defaults and React 18/19 support remain. `fonts-latin.css`, introduced in 0.1.2, now uses packaged relative font URLs for webpack resolution. `CHANGELOG.md` is included in the package archive and [npm's Code view](https://www.npmjs.com/package/@abuzareal/contour-ui?activeTab=code); it contains the upgrade details for each version.
 
 ```sh
-npm install @abuzareal/contour-ui@0.2.1 --save-exact
+npm install @abuzareal/contour-ui@0.4.0 --save-exact
 ```
 
 Commit your manifest and lockfile, run your application's checks, and review both themes, dialogs, forms, and motion before deploying. Version 0.1.1 includes a document scroll lock for dialogs and drawers. Review any app-level lock before removing it, including nested dialogs and short screens. Package publication doesn't update deployed consumers automatically.
@@ -184,7 +186,7 @@ npm audit
 npm pack --dry-run
 ```
 
-`validate` checks types, lint, builds, Node/component tests, dialog and Three.js browser behavior, and archive contents. `test:compat` builds packed React 18/19 consumers and compiles the source with React 19 types. `test:consumer` checks one packed consumer, with optional peers absent. `test:optional` verifies strict `/three` and `/scroll` declarations and builds their imports with explicit peers and Three.js types. The compatibility gate runs both checks and verifies the Latin font assets. Compatibility runs need registry access for clean installs.
+`validate` checks types, lint, builds, Node/component tests, dialog, native form/composition and Three.js browser behavior, and archive contents. `test:compat` builds packed React 18/19 consumers and compiles the source with React 19 types. `test:consumer` checks one packed consumer, with optional peers absent. `test:optional` verifies strict `/three` and `/scroll` declarations and builds their imports with explicit peers and Three.js types. The compatibility gate also runs shipped native/RHF recipe browser checks on React 18/19 and compiles the legacy form recipe against npm 0.3.0. It runs both optional/core checks and verifies the Latin font assets. Compatibility runs need registry access for clean installs.
 
 `src/` owns components, hooks, helpers, and public entries. `styles/` owns CSS. `tests/` owns regressions and browser checks; `scripts/` owns builds and package/consumer checks. `dist/` is generated. `RELEASING.md` in the source checkout and package archive covers validation and publication.
 
@@ -192,9 +194,9 @@ MIT licensed. Fontsource fonts and dependencies retain their own licenses.
 
 ## APIs added in 0.2.0
 
-Version 0.2.0 adds native refs to TextField, TextArea and SelectField; synchronizes uncontrolled counters and auto-resize after native form reset; adds controlled Tabs (`activeTabId`, `onTabChange`) and Popover/DropdownMenu (`open`, `defaultOpen`, `onOpenChange`); and adds disabled menu items, stable item ids and typeahead. These additions are absent from 0.1.2. Switching a field/disclosure between controlled and uncontrolled ownership during its lifetime is unsupported.
+Version 0.2.0 adds native refs to TextField, TextArea and SelectField; synchronizes uncontrolled counters and auto-resize after native form reset; adds controlled Tabs (`activeTabId`, `onTabChange`) and Popover/DropdownMenu (`open`, `defaultOpen`, `onOpenChange`); and adds disabled menu items, stable item ids and typeahead. These additions are absent from 0.1.2. Switching a field/open-state control between controlled and uncontrolled ownership during its lifetime is unsupported.
 
-Existing uncontrolled calls remain valid. Use a native ref to focus a field or integrate a form controller; controlled tabs and disclosures require the caller to update the selected id or open state:
+Existing uncontrolled calls remain valid. Use a native ref to focus a field or integrate a form controller; controlled tabs and popover/menu open state require the caller to update the selected id or open state:
 
 ```tsx
 import { useRef, useState } from "react";
@@ -230,7 +232,7 @@ export function AccountControls() {
 }
 ```
 
-Interactive module boundaries retain `use client` in the built package. The pinned Next.js App Router consumer checks the packed 0.2.0 archive. Follow [Next.js setup](NEXTJS.md) for the pinned Next.js 16.4.0 / React 19.3.0 pair. Pure URL/theme-bootstrap helpers remain usable from the server. A separate fixture mode checks lazy optional Three.js loading and navigation cleanup. Lenis integration, other Next versions and alternate bundlers remain separate compatibility questions.
+Interactive module boundaries retain `use client` in the built package. The pinned Next.js App Router consumer checks the packed candidate archive. Follow [Next.js setup](NEXTJS.md) for the pinned Next.js 16.4.0 / React 19.3.0 pair. Pure URL/theme-bootstrap helpers remain usable from the server. A separate fixture mode checks lazy optional Three.js loading and navigation cleanup. Lenis integration, other Next versions and alternate bundlers remain separate compatibility questions.
 
 Custom `useThreeStage` setup can register disposal through `context.onDispose?.(cleanup)` immediately after acquiring each resource, including resources allocated before setup returns. Registered resources are released on failed initialization and unmount; avoid also disposing the same resource in `StageScene.dispose`. A stage may implement `resize()` to reflow after aspect changes while motion is paused.
 

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

@@ -1,5 +1,5 @@
 /** Pill button in four emphasis levels and three sizes, with loading and icon slots. */
-import type { ButtonHTMLAttributes, ReactNode } from "react";
+import { type ButtonHTMLAttributes, type ReactNode } from "react";
 import { type ButtonSize, type ButtonVariant } from "../../lib/classNames.js";
 export type ButtonProps = ButtonHTMLAttributes<HTMLButtonElement> & {
     variant?: ButtonVariant;
@@ -9,4 +9,12 @@ export type ButtonProps = ButtonHTMLAttributes<HTMLButtonElement> & {
     leadingIcon?: ReactNode;
     loading?: boolean;
 };
-export default function Button({ variant, size, icon, leadingIcon, loading, disabled, className, children, type, ...rest }: ButtonProps): import("react").JSX.Element;
+declare const Button: import("react").ForwardRefExoticComponent<ButtonHTMLAttributes<HTMLButtonElement> & {
+    variant?: ButtonVariant;
+    size?: ButtonSize;
+    /** Icon placed after the label; it nudges forward on hover. */
+    icon?: ReactNode;
+    leadingIcon?: ReactNode;
+    loading?: boolean;
+} & import("react").RefAttributes<HTMLButtonElement>>;
+export default Button;

package/dist/components/ui/Button.js

@@ -1,6 +1,10 @@
+"use client";
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+/** Pill button in four emphasis levels and three sizes, with loading and icon slots. */
+import { forwardRef } from "react";
 import { buttonClassName, } from "../../lib/classNames.js";
 import Spinner from "./Spinner.js";
-export default function Button({ variant, size, icon, leadingIcon, loading = false, disabled, className, children, type = "button", ...rest }) {
-    return (_jsxs("button", { ...rest, type: type, className: buttonClassName(variant, size, className), disabled: disabled || loading, "aria-busy": loading || undefined, children: [loading ? _jsx(Spinner, { size: "sm", label: "Loading" }) : leadingIcon, _jsx("span", { children: children }), icon && _jsx("span", { className: "button-icon", children: icon })] }));
-}
+const Button = forwardRef(function Button({ variant, size, icon, leadingIcon, loading = false, disabled, className, children, type = "button", ...rest }, ref) {
+    return (_jsxs("button", { ref: ref, ...rest, type: type, className: buttonClassName(variant, size, className), disabled: disabled || loading, "aria-busy": loading || undefined, children: [loading ? _jsx(Spinner, { size: "sm", label: "Loading" }) : leadingIcon, _jsx("span", { children: children }), icon && _jsx("span", { className: "button-icon", children: icon })] }));
+});
+export default Button;

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

@@ -1,9 +1,15 @@
 /** Square checkbox with an acid check, optional description, error, and indeterminate state. */
 import { type InputHTMLAttributes } from "react";
-export type CheckboxProps = Omit<InputHTMLAttributes<HTMLInputElement>, "type" | "id"> & {
+export type CheckboxProps = Omit<InputHTMLAttributes<HTMLInputElement>, "type"> & {
     label: string;
     description?: string;
     error?: string;
     indeterminate?: boolean;
 };
-export default function Checkbox({ label, description, error, indeterminate, className, ...rest }: CheckboxProps): import("react").JSX.Element;
+declare const Checkbox: import("react").ForwardRefExoticComponent<Omit<InputHTMLAttributes<HTMLInputElement>, "type"> & {
+    label: string;
+    description?: string;
+    error?: string;
+    indeterminate?: boolean;
+} & import("react").RefAttributes<HTMLInputElement>>;
+export default Checkbox;

package/dist/components/ui/Checkbox.js

@@ -1,21 +1,32 @@
 "use client";
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 /** Square checkbox with an acid check, optional description, error, and indeterminate state. */
-import { useEffect, useId, useRef } from "react";
+import { forwardRef, useEffect, useId } from "react";
 import { Check, Minus } from "lucide-react";
+import useControlRef from "../../hooks/useControlRef.js";
+import useFormReset from "../../hooks/useFormReset.js";
 import { cx } from "../../lib/classNames.js";
-export default function Checkbox({ label, description, error, indeterminate = false, className, ...rest }) {
-    const id = useId();
-    const ref = useRef(null);
+const Checkbox = forwardRef(function Checkbox({ label, description, error, indeterminate = false, className, id: providedId, ...rest }, forwardedRef) {
+    const generatedId = useId();
+    const id = providedId ?? generatedId;
+    const { ref, attach } = useControlRef(forwardedRef);
     useEffect(() => {
         if (ref.current)
             ref.current.indeterminate = indeterminate;
-    }, [indeterminate]);
-    return (_jsxs("div", { className: cx("choice", error && "choice-invalid", className), children: [_jsxs("span", { className: "choice-control", children: [_jsx("input", { ...rest, ref: ref, id: id, type: "checkbox", className: "choice-input", "aria-invalid": error ? true : rest["aria-invalid"], "aria-describedby": [
+    }, [indeterminate, ref]);
+    useFormReset(ref, () => {
+        if (!ref.current)
+            return;
+        if (rest.checked !== undefined)
+            ref.current.checked = rest.checked;
+        ref.current.indeterminate = indeterminate;
+    });
+    return (_jsxs("div", { className: cx("choice", error && "choice-invalid", className), children: [_jsxs("span", { className: "choice-control", children: [_jsx("input", { ...rest, ref: attach, id: id, type: "checkbox", className: "choice-input", "aria-invalid": error ? true : rest["aria-invalid"], "aria-describedby": [
                             rest["aria-describedby"],
                             description && `${id}-description`,
                             error && `${id}-error`,
                         ]
                             .filter(Boolean)
                             .join(" ") || undefined }), _jsx("span", { className: "choice-box", "aria-hidden": "true", children: indeterminate ? (_jsx(Minus, { size: 13, strokeWidth: 3 })) : (_jsx(Check, { size: 13, strokeWidth: 3 })) })] }), _jsxs("label", { htmlFor: id, className: "choice-text", children: [_jsx("span", { className: "choice-label", children: label }), description && (_jsx("span", { id: `${id}-description`, className: "choice-description", children: description })), error && (_jsx("span", { id: `${id}-error`, className: "choice-error mono", children: error }))] })] }));
-}
+});
+export default Checkbox;

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

@@ -1,6 +1,9 @@
 /** Physical, layered button that presses down into its base (CSS 3D depth). */
-import type { ButtonHTMLAttributes, ReactNode } from "react";
+import { type ButtonHTMLAttributes, type ReactNode } from "react";
 export type DepthButtonProps = ButtonHTMLAttributes<HTMLButtonElement> & {
     children: ReactNode;
 };
-export default function DepthButton({ children, type, ...rest }: DepthButtonProps): import("react").JSX.Element;
+declare const DepthButton: import("react").ForwardRefExoticComponent<ButtonHTMLAttributes<HTMLButtonElement> & {
+    children: ReactNode;
+} & import("react").RefAttributes<HTMLButtonElement>>;
+export default DepthButton;

package/dist/components/ui/DepthButton.js

@@ -1,4 +1,9 @@
+"use client";
 import { jsx as _jsx } from "react/jsx-runtime";
-export default function DepthButton({ children, type = "button", ...rest }) {
-    return (_jsx("button", { ...rest, type: type, className: "depth-button", children: _jsx("span", { className: "depth-button-face", children: children }) }));
-}
+/** Physical, layered button that presses down into its base (CSS 3D depth). */
+import { forwardRef } from "react";
+import { cx } from "../../lib/classNames.js";
+const DepthButton = forwardRef(function DepthButton({ children, className, type = "button", ...rest }, ref) {
+    return (_jsx("button", { ref: ref, ...rest, type: type, className: cx("depth-button", className), children: _jsx("span", { className: "depth-button-face", children: children }) }));
+});
+export default DepthButton;

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

@@ -1,6 +1,7 @@
-/** Modal dialog on the native <dialog> element; also slides in from either edge as a drawer. */
+/** Native controlled modal, with refs and props for its existing DOM parts. */
 import { type ReactNode } from "react";
-export type DialogProps = {
+import type { NativePartProps } from "../../lib/componentProps.js";
+export type DialogProps = Omit<NativePartProps<"dialog">, "ref" | "open" | "onClose" | "title"> & {
     open: boolean;
     onClose: () => void;
     title: string;
@@ -8,5 +9,22 @@ export type DialogProps = {
     description?: string;
     footer?: ReactNode;
     placement?: "center" | "left" | "right";
+    panelProps?: NativePartProps<"div">;
+    bodyProps?: NativePartProps<"div">;
+    footerProps?: NativePartProps<"footer">;
+    closeButtonProps?: NativePartProps<"button">;
 };
-export default function Dialog({ open, onClose, title, children, description, footer, placement, }: DialogProps): import("react").JSX.Element;
+declare const Dialog: import("react").ForwardRefExoticComponent<Omit<NativePartProps<"dialog">, "title" | "ref" | "onClose" | "open"> & {
+    open: boolean;
+    onClose: () => void;
+    title: string;
+    children: ReactNode;
+    description?: string;
+    footer?: ReactNode;
+    placement?: "center" | "left" | "right";
+    panelProps?: NativePartProps<"div">;
+    bodyProps?: NativePartProps<"div">;
+    footerProps?: NativePartProps<"footer">;
+    closeButtonProps?: NativePartProps<"button">;
+} & import("react").RefAttributes<HTMLDialogElement>>;
+export default Dialog;

package/dist/components/ui/Dialog.js

@@ -1,12 +1,14 @@
 "use client";
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-/** Modal dialog on the native <dialog> element; also slides in from either edge as a drawer. */
-import { useEffect, useId, useRef } from "react";
+/** Native controlled modal, with refs and props for its existing DOM parts. */
+import { forwardRef, useEffect, useId } from "react";
 import { X } from "lucide-react";
 import { cx } from "../../lib/classNames.js";
 import { lockDocumentScroll } from "../../lib/lockDocumentScroll.js";
-export default function Dialog({ open, onClose, title, children, description, footer, placement = "center", }) {
-    const ref = useRef(null);
+import { composeEventHandlers } from "../../lib/composeEventHandlers.js";
+import useControlRef from "../../hooks/useControlRef.js";
+const Dialog = forwardRef(function Dialog({ open, onClose, title, children, description, footer, placement = "center", className, onCancel, onClick, panelProps, bodyProps, footerProps, closeButtonProps, ...rest }, forwardedRef) {
+    const { ref, attach } = useControlRef(forwardedRef);
     const titleId = useId();
     const descriptionId = useId();
     useEffect(() => {
@@ -25,13 +27,17 @@ export default function Dialog({ open, onClose, title, children, description, fo
             dialog.removeEventListener("close", release);
             release();
         };
-    }, [open]);
-    return (_jsx("dialog", { ref: ref, className: cx("dialog", `dialog-${placement}`), "aria-labelledby": titleId, "aria-describedby": description ? descriptionId : undefined, onCancel: (event) => {
+    }, [open, ref]);
+    return (_jsx("dialog", { ...rest, ref: attach, role: "dialog", "aria-modal": open || undefined, className: cx("dialog", `dialog-${placement}`, className), "aria-labelledby": cx(titleId, rest["aria-labelledby"]), "aria-describedby": cx(description && descriptionId, rest["aria-describedby"]) || undefined, onCancel: (event) => {
+            onCancel?.(event);
+            const canceled = event.defaultPrevented;
+            // The browser must never close the element independently of the controlled open prop.
             event.preventDefault();
-            onClose();
-        }, onClick: (event) => {
-            // A click on the element itself (not its panel) is a backdrop click.
+            if (!canceled)
+                onClose();
+        }, onClick: composeEventHandlers(onClick, (event) => {
             if (event.target === event.currentTarget)
                 onClose();
-        }, children: _jsxs("div", { className: "dialog-panel", children: [_jsxs("header", { className: "dialog-header", children: [_jsxs("div", { children: [_jsx("h2", { id: titleId, children: title }), description && (_jsx("p", { id: descriptionId, className: "dialog-description", children: description }))] }), _jsx("button", { type: "button", className: "dialog-close", "aria-label": "Close dialog", onClick: onClose, children: _jsx(X, { size: 18 }) })] }), _jsx("div", { className: "dialog-body", children: children }), footer && _jsx("footer", { className: "dialog-footer", children: footer })] }) }));
-}
+        }), children: _jsxs("div", { ...panelProps, className: cx("dialog-panel", panelProps?.className), children: [_jsxs("header", { className: "dialog-header", children: [_jsxs("div", { children: [_jsx("h2", { id: titleId, children: title }), description && (_jsx("p", { id: descriptionId, className: "dialog-description", children: description }))] }), _jsx("button", { ...closeButtonProps, type: "button", className: cx("dialog-close", closeButtonProps?.className), "aria-label": closeButtonProps?.["aria-label"] ?? "Close dialog", onClick: composeEventHandlers(closeButtonProps?.onClick, () => onClose()), children: _jsx(X, { size: 18 }) })] }), _jsx("div", { ...bodyProps, className: cx("dialog-body", bodyProps?.className), children: children }), footer && (_jsx("footer", { ...footerProps, className: cx("dialog-footer", footerProps?.className), children: footer }))] }) }));
+});
+export default Dialog;

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

@@ -1,4 +1,5 @@
 /** Anchor for off-site destinations; always opens a new tab without leaking the opener. */
-import type { AnchorHTMLAttributes } from "react";
+import { type AnchorHTMLAttributes } from "react";
 export type ExternalLinkProps = Omit<AnchorHTMLAttributes<HTMLAnchorElement>, "target" | "rel">;
-export default function ExternalLink({ href, ...props }: ExternalLinkProps): import("react").JSX.Element;
+declare const ExternalLink: import("react").ForwardRefExoticComponent<ExternalLinkProps & import("react").RefAttributes<HTMLAnchorElement>>;
+export default ExternalLink;

package/dist/components/ui/ExternalLink.js

@@ -1,5 +1,9 @@
+"use client";
 import { jsx as _jsx } from "react/jsx-runtime";
+/** Anchor for off-site destinations; always opens a new tab without leaking the opener. */
+import { forwardRef } from "react";
 import { safeHref } from "../../lib/safeHref.js";
-export default function ExternalLink({ href, ...props }) {
-    return (_jsx("a", { ...props, href: safeHref(href), target: "_blank", rel: "noopener noreferrer" }));
-}
+const ExternalLink = forwardRef(function ExternalLink({ href, ...props }, ref) {
+    return (_jsx("a", { ref: ref, ...props, href: safeHref(href), target: "_blank", rel: "noopener noreferrer" }));
+});
+export default ExternalLink;

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

@@ -1,5 +1,5 @@
 /** Circular icon-only button (the portfolio's source/copy button), with a required accessible label. */
-import type { ButtonHTMLAttributes, ReactNode } from "react";
+import { type ButtonHTMLAttributes, type ReactNode } from "react";
 export type IconButtonProps = ButtonHTMLAttributes<HTMLButtonElement> & {
     label: string;
     children: ReactNode;
@@ -8,4 +8,12 @@ export type IconButtonProps = ButtonHTMLAttributes<HTMLButtonElement> & {
     /** Rotates the icon 45deg on hover, as on the project source links. */
     spin?: boolean;
 };
-export default function IconButton({ label, children, variant, size, spin, className, type, ...rest }: IconButtonProps): import("react").JSX.Element;
+declare const IconButton: import("react").ForwardRefExoticComponent<ButtonHTMLAttributes<HTMLButtonElement> & {
+    label: string;
+    children: ReactNode;
+    variant?: "outline" | "solid" | "accent";
+    size?: "sm" | "md" | "lg";
+    /** Rotates the icon 45deg on hover, as on the project source links. */
+    spin?: boolean;
+} & import("react").RefAttributes<HTMLButtonElement>>;
+export default IconButton;

package/dist/components/ui/IconButton.js

@@ -1,5 +1,9 @@
+"use client";
 import { jsx as _jsx } from "react/jsx-runtime";
+/** Circular icon-only button (the portfolio's source/copy button), with a required accessible label. */
+import { forwardRef } from "react";
 import { cx } from "../../lib/classNames.js";
-export default function IconButton({ label, children, variant = "outline", size = "md", spin = false, className, type = "button", ...rest }) {
-    return (_jsx("button", { ...rest, type: type, "aria-label": label, title: rest.title ?? label, className: cx("icon-button", `icon-button-${variant}`, `icon-button-${size}`, spin && "icon-button-spin", className), children: children }));
-}
+const IconButton = forwardRef(function IconButton({ label, children, variant = "outline", size = "md", spin = false, className, type = "button", ...rest }, ref) {
+    return (_jsx("button", { ref: ref, ...rest, type: type, "aria-label": label, title: rest.title ?? label, className: cx("icon-button", `icon-button-${variant}`, `icon-button-${size}`, spin && "icon-button-spin", className), children: children }));
+});
+export default IconButton;

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

@@ -1,7 +1,8 @@
-/** Non-modal floating panel anchored to a trigger; closes on Escape or an outside press. */
+/** Nonmodal local panel; root and existing trigger/panel props preserve owned state wiring. */
 import { type ReactNode } from "react";
-export type PopoverProps = {
-    /** Text for the trigger button. */
+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. */
     trigger: ReactNode;
     title: string;
     children: ReactNode;
@@ -9,5 +10,19 @@ export type PopoverProps = {
     open?: boolean;
     defaultOpen?: boolean;
     onOpenChange?: (open: boolean) => void;
+    triggerProps?: NativePartProps<"button">;
+    panelProps?: NativePartProps<"div">;
 };
-export default function Popover({ trigger, title, children, align, open: controlledOpen, defaultOpen, onOpenChange, }: PopoverProps): import("react").JSX.Element;
+declare const Popover: import("react").ForwardRefExoticComponent<Omit<NativePartProps<"div">, "title" | "ref"> & {
+    /** Content inside the owned trigger button, not a replacement interactive element. */
+    trigger: ReactNode;
+    title: string;
+    children: ReactNode;
+    align?: "start" | "end";
+    open?: boolean;
+    defaultOpen?: boolean;
+    onOpenChange?: (open: boolean) => void;
+    triggerProps?: NativePartProps<"button">;
+    panelProps?: NativePartProps<"div">;
+} & import("react").RefAttributes<HTMLDivElement>>;
+export default Popover;

package/dist/components/ui/Popover.js

@@ -1,20 +1,27 @@
 "use client";
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-/** Non-modal floating panel anchored to a trigger; closes on Escape or an outside press. */
-import { useCallback, useId, useRef } from "react";
+/** Nonmodal local panel; root and existing trigger/panel props preserve owned state wiring. */
+import { forwardRef, useCallback, useId } from "react";
 import useOpenState from "../../hooks/useOpenState.js";
 import useDismiss from "../../hooks/useDismiss.js";
+import useControlRef from "../../hooks/useControlRef.js";
 import { cx } from "../../lib/classNames.js";
-export default function Popover({ trigger, title, children, align = "start", open: controlledOpen, defaultOpen = false, onOpenChange, }) {
-    const panelId = useId();
+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();
+    const panelId = panelProps?.id ?? generatedPanelId;
     const titleId = useId();
     const [open, setOpen] = useOpenState(controlledOpen, defaultOpen, onOpenChange);
-    const container = useRef(null);
-    const button = useRef(null);
+    const { ref: container, attach: attachContainer } = useControlRef(forwardedRef);
+    const { ref: button, attach: attachButton } = useControlRef(triggerProps?.ref ?? null);
     useDismiss(container, open, useCallback((reason) => {
         setOpen(false);
         if (reason === "escape")
             button.current?.focus();
-    }, [setOpen]));
-    return (_jsxs("div", { ref: container, className: cx("popover", `popover-${align}`), children: [_jsx("button", { ref: button, type: "button", className: "menu-trigger", "aria-expanded": open, "aria-controls": panelId, onClick: () => setOpen(!open), children: trigger }), _jsxs("div", { id: panelId, role: "dialog", "aria-labelledby": titleId, className: "popover-panel", hidden: !open, children: [_jsx("strong", { id: titleId, className: "popover-title", children: title }), children] })] }));
-}
+    }, [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] })] }));
+});
+export default Popover;

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";
+/** 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";
-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));
-            })] }));
+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: 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) => {
+                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
+                                        ? 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 }))] }));
 }

package/dist/components/ui/SelectField.js

@@ -5,10 +5,24 @@ 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: "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" })] }) }));
 });

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

@@ -1,12 +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;
 };
-export default function Slider({ label, value, onChange, min, max, step, format, disabled, }: SliderProps): import("react").JSX.Element;
+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;