@abuzareal/contour-ui 0.2.0 → 0.3.0

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;

package/dist/hooks/useClipboardCopy.js

@@ -3,20 +3,43 @@
 import { useCallback, useEffect, useRef, useState } from "react";
 const resetDelay = 4000;
 export default function useClipboardCopy(text) {
-    const [status, setStatus] = useState("idle");
+    const [feedback, setFeedback] = useState({
+        text,
+        status: "idle",
+    });
+    // Feedback belongs to the current value, even before effects synchronize.
+    if (feedback.text !== text)
+        setFeedback({ text, status: "idle" });
+    const status = feedback.text === text ? feedback.status : "idle";
     const resetTimer = useRef(undefined);
-    useEffect(() => () => clearTimeout(resetTimer.current), []);
+    const active = useRef(false);
+    const request = useRef(0);
+    useEffect(() => {
+        active.current = true;
+        return () => {
+            active.current = false;
+            request.current += 1;
+            clearTimeout(resetTimer.current);
+        };
+    }, [text]);
     const copy = useCallback(async () => {
+        if (!active.current)
+            return;
+        const currentRequest = ++request.current;
         clearTimeout(resetTimer.current);
-        setStatus("copying");
+        setFeedback({ text, status: "copying" });
+        let outcome = "copied";
         try {
             await navigator.clipboard.writeText(text);
-            setStatus("copied");
         }
         catch {
-            setStatus("error");
+            outcome = "error";
         }
-        resetTimer.current = setTimeout(() => setStatus("idle"), resetDelay);
+        // Clipboard writes cannot be cancelled; discard obsolete completions.
+        if (!active.current || currentRequest !== request.current)
+            return;
+        setFeedback({ text, status: outcome });
+        resetTimer.current = setTimeout(() => setFeedback({ text, status: "idle" }), resetDelay);
     }, [text]);
     return { status, copy };
 }

package/dist/hooks/useControlRef.js

@@ -6,8 +6,8 @@ export default function useControlRef(forwarded) {
     useImperativeHandle(forwarded, () => {
         const element = ref.current;
         if (!element)
-            throw new Error("The field control must be mounted before exposing its ref.");
+            throw new Error("The native target must be mounted before exposing its ref.");
         return element;
-    });
+    }, []);
     return { ref, attach: ref };
 }

package/dist/hooks/useTabRefs.d.ts

@@ -0,0 +1,4 @@
+import { type RefObject } from "react";
+import type { TabItem } from "../components/ui/Tabs.js";
+/** Keep ID-based internal focus targets and caller button refs in the same lifecycle. */
+export default function useTabRefs(tabs: TabItem[], targets: RefObject<Map<string, HTMLButtonElement>>): import("react").RefCallback<HTMLButtonElement>[];

package/dist/hooks/useTabRefs.js

@@ -0,0 +1,12 @@
+"use client";
+import { useMemo } from "react";
+import { composeRefs } from "../lib/composeRefs.js";
+/** Keep ID-based internal focus targets and caller button refs in the same lifecycle. */
+export default function useTabRefs(tabs, targets) {
+    return useMemo(() => tabs.map((tab) => composeRefs((element) => {
+        if (element)
+            targets.current?.set(tab.id, element);
+        else
+            targets.current?.delete(tab.id);
+    }, tab.buttonProps?.ref)), [tabs, targets]);
+}

package/dist/lib/componentProps.d.ts

@@ -0,0 +1,5 @@
+import type { ComponentPropsWithRef, JSX } from "react";
+/** Props customize existing owned DOM parts; children and raw markup stay component-owned. */
+export type NativePartProps<Tag extends keyof JSX.IntrinsicElements> = Omit<ComponentPropsWithRef<Tag>, "children" | "dangerouslySetInnerHTML"> & {
+    [name: `data-${string}`]: string | number | boolean | undefined;
+};

package/dist/lib/componentProps.js

@@ -0,0 +1 @@
+export {};

package/dist/lib/composeEventHandlers.d.ts

@@ -0,0 +1,4 @@
+/** Caller vetoes an internal action without replacing required state/ARIA wiring. */
+export declare function composeEventHandlers<Event extends {
+    defaultPrevented: boolean;
+}>(caller: ((event: Event) => void) | undefined, internal: (event: Event) => void): (event: Event) => void;

package/dist/lib/composeEventHandlers.js

@@ -0,0 +1,8 @@
+/** Caller vetoes an internal action without replacing required state/ARIA wiring. */
+export function composeEventHandlers(caller, internal) {
+    return (event) => {
+        caller?.(event);
+        if (!event.defaultPrevented)
+            internal(event);
+    };
+}

package/dist/lib/composeRefs.d.ts

@@ -0,0 +1,3 @@
+import type { Ref, RefCallback } from "react";
+/** Retain internal nodes and caller refs, honoring React 19 cleanup callbacks on detach. */
+export declare function composeRefs<Element>(...refs: (Ref<Element> | undefined)[]): RefCallback<Element>;

package/dist/lib/composeRefs.js

@@ -0,0 +1,24 @@
+/** Retain internal nodes and caller refs, honoring React 19 cleanup callbacks on detach. */
+export function composeRefs(...refs) {
+    let cleanups = [];
+    return (element) => {
+        for (const cleanup of cleanups)
+            cleanup();
+        cleanups = [];
+        if (element === null)
+            return;
+        for (const ref of refs) {
+            if (typeof ref === "function") {
+                const cleanup = ref(element);
+                cleanups.push(typeof cleanup === "function" ? () => cleanup() : () => ref(null));
+            }
+            else if (ref) {
+                // RefObject is read-only in React 18's consumer types; assigning is React's ref contract.
+                Object.assign(ref, { current: element });
+                cleanups.push(() => {
+                    Object.assign(ref, { current: null });
+                });
+            }
+        }
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@abuzareal/contour-ui",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "private": false,
   "description": "Editorial React components, themes, restrained motion, and optional Three.js objects.",
   "type": "module",
@@ -13,7 +13,10 @@
     "RELEASING.md",
     "CONTRIBUTING.md",
     "CODE_OF_CONDUCT.md",
-    "NEXTJS.md"
+    "NEXTJS.md",
+    "CONTRACTS.md",
+    "PUBLIC-API.md",
+    "COMPOSITION.md"
   ],
   "sideEffects": [
     "**/*.css"