@abuzareal/contour-ui 0.2.1 → 0.3.0

package/README.md

@@ -6,18 +6,18 @@ 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.3.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.
 
 ## 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.3.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 +118,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 +164,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.3.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.
@@ -192,9 +192,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";

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

@@ -6,4 +6,10 @@ export type CheckboxProps = Omit<InputHTMLAttributes<HTMLInputElement>, "type" |
     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>, "id" | "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,23 @@
 "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 { cx } from "../../lib/classNames.js";
-export default function Checkbox({ label, description, error, indeterminate = false, className, ...rest }) {
+const Checkbox = forwardRef(function Checkbox({ label, description, error, indeterminate = false, className, ...rest }, forwardedRef) {
     const id = useId();
-    const ref = useRef(null);
+    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]);
+    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/Slider.d.ts

@@ -9,4 +9,5 @@ export type SliderProps = {
     format?: (value: number) => string;
     disabled?: boolean;
 };
-export default function Slider({ label, value, onChange, min, max, step, format, disabled, }: SliderProps): import("react").JSX.Element;
+declare const Slider: import("react").ForwardRefExoticComponent<SliderProps & import("react").RefAttributes<HTMLInputElement>>;
+export default Slider;

package/dist/components/ui/Slider.js

@@ -1,11 +1,12 @@
 "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 { useId } from "react";
-export default function Slider({ label, value, onChange, min = 0, max = 100, step = 1, format = String, disabled, }) {
+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();
     const progress = max > min
         ? Math.min(100, Math.max(0, ((value - 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", { 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: "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)) })] }));
+});
+export default Slider;

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

@@ -5,4 +5,5 @@ export type SwitchProps = {
     description?: string;
     disabled?: boolean;
 };
-export default function Switch({ label, checked, onChange, description, disabled, }: SwitchProps): import("react").JSX.Element;
+declare const Switch: import("react").ForwardRefExoticComponent<SwitchProps & import("react").RefAttributes<HTMLButtonElement>>;
+export default Switch;

package/dist/components/ui/Switch.js

@@ -1,8 +1,9 @@
 "use client";
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 /** On/off switch (role="switch") with a pill track that fills acid when on. */
-import { useId } from "react";
-export default function Switch({ label, checked, onChange, description, disabled, }) {
+import { forwardRef, useId } from "react";
+const Switch = forwardRef(function Switch({ label, checked, onChange, description, disabled }, ref) {
     const id = useId();
-    return (_jsxs("div", { className: "switch", children: [_jsx("button", { id: id, type: "button", role: "switch", "aria-checked": checked, "aria-describedby": description ? `${id}-description` : undefined, disabled: disabled, className: "switch-track", onClick: () => onChange(!checked), children: _jsx("span", { className: "switch-thumb" }) }), _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 }))] })] }));
-}
+    return (_jsxs("div", { className: "switch", children: [_jsx("button", { ref: ref, id: id, type: "button", role: "switch", "aria-checked": checked, "aria-describedby": description ? `${id}-description` : undefined, disabled: disabled, className: "switch-track", onClick: () => onChange(!checked), children: _jsx("span", { className: "switch-thumb" }) }), _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 }))] })] }));
+});
+export default Switch;

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

@@ -1,16 +1,28 @@
-/** Tabs with a sliding underline indicator, arrow-key navigation, and linked panels. */
+/** Controlled/default tabs, with props and native refs for root/list/buttons/panels. */
 import { type ReactNode } from "react";
+import type { NativePartProps } from "../../lib/componentProps.js";
 export type TabItem = {
     id: string;
     label: string;
     content: ReactNode;
+    /** Native styling/events/ref; disabled-tab semantics are not introduced by this part API. */
+    buttonProps?: Omit<NativePartProps<"button">, "disabled">;
+    panelProps?: NativePartProps<"div">;
 };
-export type TabsProps = {
+export type TabsProps = Omit<NativePartProps<"div">, "ref"> & {
     label: string;
     tabs: TabItem[];
     defaultTabId?: string;
-    /** Controlled selection. The caller must update this after onTabChange. */
     activeTabId?: string;
     onTabChange?: (id: string) => void;
+    listProps?: NativePartProps<"div">;
 };
-export default function Tabs({ label, tabs, defaultTabId, activeTabId, onTabChange, }: TabsProps): import("react").JSX.Element;
+declare const Tabs: import("react").ForwardRefExoticComponent<Omit<NativePartProps<"div">, "ref"> & {
+    label: string;
+    tabs: TabItem[];
+    defaultTabId?: string;
+    activeTabId?: string;
+    onTabChange?: (id: string) => void;
+    listProps?: NativePartProps<"div">;
+} & import("react").RefAttributes<HTMLDivElement>>;
+export default Tabs;

package/dist/components/ui/Tabs.js

@@ -1,48 +1,70 @@
 "use client";
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-/** Tabs with a sliding underline indicator, arrow-key navigation, and linked panels. */
-import { useId, useLayoutEffect, useRef, useState, } from "react";
+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";
-export default function Tabs({ label, tabs, defaultTabId, activeTabId, onTabChange, }) {
-    const baseId = useId();
+import { cx } 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();
+    const baseId = id ?? generatedId;
     const [activeId, setActiveId] = useState(defaultTabId ?? tabs[0]?.id ?? "");
     const [indicator, setIndicator] = useState({ left: 0, width: 0 });
-    const tabRefs = useRef([]);
+    const tabRefs = useRef(new Map());
     const activeIndex = Math.max(0, tabs.findIndex((tab) => tab.id === (activeTabId ?? activeId)));
     const selectedId = tabs[activeIndex]?.id;
+    const buttonRefs = useTabRefs(tabs, tabRefs);
     useLayoutEffect(() => {
         const measure = () => {
-            const tab = tabRefs.current[activeIndex];
-            if (tab)
-                setIndicator({ left: tab.offsetLeft, width: tab.offsetWidth });
+            const tab = selectedId === undefined ? undefined : tabRefs.current.get(selectedId);
+            if (tab) {
+                const next = { left: tab.offsetLeft, width: tab.offsetWidth };
+                setIndicator((current) => current.left === next.left && current.width === next.width
+                    ? current
+                    : next);
+            }
         };
         measure();
         window.addEventListener("resize", measure);
         return () => window.removeEventListener("resize", measure);
-    }, [activeIndex, tabs]);
-    const select = (index) => {
+    }, [
+        selectedId,
+        tabs,
+        className,
+        rest.style,
+        listProps?.className,
+        listProps?.style,
+    ]);
+    const select = (tab, focus = false) => {
         if (activeTabId === undefined)
-            setActiveId(tabs[index].id);
-        onTabChange?.(tabs[index].id);
-        tabRefs.current[index]?.focus();
+            setActiveId(tab.id);
+        onTabChange?.(tab.id);
+        if (focus)
+            tabRefs.current.get(tab.id)?.focus();
     };
-    return (_jsxs("div", { className: "tabs", children: [_jsx("div", { className: "tabs-list", role: "tablist", "aria-label": label, style: {
+    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: {
+                    ...listProps?.style,
                     "--indicator-left": `${indicator.left}px`,
                     "--indicator-width": `${indicator.width}px`,
                 }, children: tabs.map((tab, index) => {
                     const selected = tab.id === selectedId;
-                    return (_jsx("button", { ref: (element) => {
-                            tabRefs.current[index] = element;
-                        }, id: `${baseId}-tab-${tab.id}`, type: "button", role: "tab", "aria-selected": selected, "aria-controls": `${baseId}-panel-${tab.id}`, tabIndex: selected ? 0 : -1, className: "tabs-tab", onClick: () => {
-                            if (activeTabId === undefined)
-                                setActiveId(tab.id);
-                            onTabChange?.(tab.id);
+                    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) => {
+                            tab.buttonProps?.onClick?.(event);
+                            if (!event.defaultPrevented)
+                                select(tab);
                         }, onKeyDown: (event) => {
+                            tab.buttonProps?.onKeyDown?.(event);
+                            if (event.defaultPrevented)
+                                return;
                             const next = nextIndexForKey(event.key, index, tabs.length);
                             if (next === null)
                                 return;
                             event.preventDefault();
-                            select(next);
-                        }, children: tab.label }, tab.id));
-                }) }), tabs.map((tab) => (_jsx("div", { id: `${baseId}-panel-${tab.id}`, role: "tabpanel", "aria-labelledby": `${baseId}-tab-${tab.id}`, hidden: tab.id !== selectedId, tabIndex: 0, className: "tabs-panel", children: tab.content }, tab.id)))] }));
-}
+                            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)))] }));
+});
+export default Tabs;

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

@@ -2,4 +2,5 @@ export type ThemeToggleProps = {
     /** When false the theme switches instantly instead of animating. */
     animate: boolean;
 };
-export default function ThemeToggle({ animate }: ThemeToggleProps): import("react").JSX.Element;
+declare const ThemeToggle: import("react").ForwardRefExoticComponent<ThemeToggleProps & import("react").RefAttributes<HTMLButtonElement>>;
+export default ThemeToggle;

package/dist/components/ui/ThemeToggle.js

@@ -1,10 +1,12 @@
 "use client";
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 /** Header button that switches between the light and dark themes. */
+import { forwardRef } from "react";
 import { Moon, Sun } from "lucide-react";
 import useTheme from "../../hooks/useTheme.js";
-export default function ThemeToggle({ animate }) {
+const ThemeToggle = forwardRef(function ThemeToggle({ animate }, ref) {
     const { theme, toggle } = useTheme(animate);
     const dark = theme === "dark";
-    return (_jsxs("button", { type: "button", className: "theme-toggle", "aria-label": "Dark theme", "aria-pressed": dark, title: dark ? "Switch to light theme" : "Switch to dark theme", onClick: (event) => toggle(event.currentTarget), children: [_jsx(Moon, { className: "theme-icon-moon", size: 16, "aria-hidden": "true" }), _jsx(Sun, { className: "theme-icon-sun", size: 17, "aria-hidden": "true" })] }));
-}
+    return (_jsxs("button", { ref: ref, type: "button", className: "theme-toggle", "aria-label": "Dark theme", "aria-pressed": dark, title: dark ? "Switch to light theme" : "Switch to dark theme", onClick: (event) => toggle(event.currentTarget), children: [_jsx(Moon, { className: "theme-icon-moon", size: 16, "aria-hidden": "true" }), _jsx(Sun, { className: "theme-icon-sun", size: 17, "aria-hidden": "true" })] }));
+});
+export default ThemeToggle;