@arolariu/components 1.0.0 → 1.1.0

package/src/components/ui/progress.tsx

@@ -33,13 +33,14 @@ export interface ProgressProps extends Omit<React.ComponentPropsWithRef<typeof B
  *
  * @see {@link https://base-ui.com/react/components/progress | Base UI Documentation}
  */
-function Progress(props: Readonly<Progress.Props>): React.ReactElement {
+const Progress = React.forwardRef<HTMLDivElement, Progress.Props>(function Progress(props, forwardedRef) {
   const {className, render, value = 0, ...otherProps} = props;
 
   return (
     <BaseProgress.Root
       value={value}
       {...otherProps}
+      ref={forwardedRef}
       render={useRender({
         defaultTagName: "div",
         render: render as never,
@@ -49,7 +50,7 @@ function Progress(props: Readonly<Progress.Props>): React.ReactElement {
       </BaseProgress.Track>
     </BaseProgress.Root>
   );
-}
+});
 Progress.displayName = "Progress";
 
 // eslint-disable-next-line no-redeclare -- required for the canonical component namespace typing API

package/src/components/ui/radio-group.tsx

@@ -10,9 +10,6 @@ import * as React from "react";
 import {cn} from "@/lib/utilities";
 import styles from "./radio-group.module.css";
 
-type RadioGroupProps = React.ComponentPropsWithRef<typeof BaseRadioGroup>;
-type RadioGroupItemProps = React.ComponentPropsWithRef<typeof Radio.Root>;
-
 /**
  * Coordinates radio group state and selection behavior.
  *
@@ -84,13 +81,13 @@ const RadioGroupItem = React.forwardRef<React.ComponentRef<typeof Radio.Root>, R
 
 // eslint-disable-next-line no-redeclare -- required for the canonical component namespace typing API
 namespace RadioGroup {
-  export type Props = RadioGroupProps;
+  export type Props = React.ComponentPropsWithRef<typeof BaseRadioGroup>;
   export type State = BaseRadioGroup.State;
 }
 
 // eslint-disable-next-line no-redeclare -- required for the canonical component namespace typing API
 namespace RadioGroupItem {
-  export type Props = RadioGroupItemProps;
+  export type Props = React.ComponentPropsWithRef<typeof Radio.Root>;
   export type State = Radio.Root.State;
 }
 

package/src/components/ui/resizable.tsx

@@ -4,14 +4,14 @@
 
 import {GripVertical} from "lucide-react";
 import * as React from "react";
-import type {ImperativePanelGroupHandle, ImperativePanelHandle} from "react-resizable-panels";
+import type {ImperativePanelGroupHandle} from "react-resizable-panels";
 import * as ResizablePrimitive from "react-resizable-panels";
 
 import {cn} from "@/lib/utilities";
 
 import styles from "./resizable.module.css";
 
-export type {ImperativePanelGroupHandle, ImperativePanelHandle};
+export type {ImperativePanelGroupHandle, ImperativePanelHandle} from "react-resizable-panels";
 
 /**
  * Props for the {@link ResizablePanelGroup} component.

package/src/components/ui/scratcher.tsx

@@ -43,15 +43,10 @@ const ignoreAnimationError = (): null => null;
  *
  * @see {@link ScratcherProps} for available props
  */
-export const Scratcher: React.FC<ScratcherProps> = ({
-  width,
-  height,
-  minScratchPercentage = 50,
-  onComplete,
-  children,
-  className,
-  gradientColors = defaultGradientColors,
-}): React.JSX.Element => {
+export const Scratcher = React.forwardRef<HTMLDivElement, ScratcherProps>(function Scratcher(
+  {width, height, minScratchPercentage = 50, onComplete, children, className, gradientColors = defaultGradientColors},
+  forwardedRef,
+) {
   const canvasRef = useRef<HTMLCanvasElement>(null);
   const [isScratching, setIsScratching] = useState(false);
   const [isComplete, setIsComplete] = useState(false);
@@ -173,6 +168,7 @@ export const Scratcher: React.FC<ScratcherProps> = ({
 
   return (
     <motion.div
+      ref={forwardedRef}
       className={cn(styles.root, className)}
       style={{
         width,
@@ -192,6 +188,6 @@ export const Scratcher: React.FC<ScratcherProps> = ({
       {children}
     </motion.div>
   );
-};
+});
 
 Scratcher.displayName = "Scratcher";

package/src/components/ui/scroll-area.tsx

@@ -8,9 +8,6 @@ import * as React from "react";
 import {cn} from "@/lib/utilities";
 import styles from "./scroll-area.module.css";
 
-type ScrollAreaProps = React.ComponentPropsWithRef<typeof BaseScrollArea.Root>;
-type ScrollBarProps = React.ComponentPropsWithRef<typeof BaseScrollArea.Scrollbar>;
-
 /**
  * Coordinates scroll area layout and scrolling behavior.
  *
@@ -88,13 +85,13 @@ function ScrollBar(props: Readonly<ScrollBar.Props>): React.ReactElement {
 
 // eslint-disable-next-line no-redeclare -- required for the canonical component namespace typing API
 namespace ScrollArea {
-  export type Props = ScrollAreaProps;
+  export type Props = React.ComponentPropsWithRef<typeof BaseScrollArea.Root>;
   export type State = BaseScrollArea.Root.State;
 }
 
 // eslint-disable-next-line no-redeclare -- required for the canonical component namespace typing API
 namespace ScrollBar {
-  export type Props = ScrollBarProps;
+  export type Props = React.ComponentPropsWithRef<typeof BaseScrollArea.Scrollbar>;
   export type State = BaseScrollArea.Scrollbar.State;
 }
 

package/src/components/ui/separator.tsx

@@ -36,13 +36,14 @@ export interface SeparatorProps extends Omit<React.ComponentPropsWithRef<typeof
  *
  * @see {@link https://base-ui.com/react/components/separator | Base UI Documentation}
  */
-function Separator(props: Readonly<Separator.Props>): React.ReactElement {
-  const {className, decorative: _decorative = true, orientation = "horizontal", render, ...otherProps} = props;
+const Separator = React.forwardRef<HTMLDivElement, Separator.Props>(function Separator(props, forwardedRef) {
+  const {className, orientation = "horizontal", render, ...otherProps} = props;
 
   return (
     <BaseSeparator
       orientation={orientation}
       {...otherProps}
+      ref={forwardedRef}
       render={useRender({
         defaultTagName: "div",
         render: render as never,
@@ -55,7 +56,7 @@ function Separator(props: Readonly<Separator.Props>): React.ReactElement {
       })}
     />
   );
-}
+});
 Separator.displayName = "Separator";
 
 // eslint-disable-next-line no-redeclare -- required for the canonical component namespace typing API

package/src/components/ui/sheet.tsx

@@ -171,6 +171,7 @@ const SheetClose = BaseDialog.Close;
  */
 const SheetTrigger = React.forwardRef<HTMLButtonElement, SheetTrigger.Props>(
   (props: Readonly<SheetTrigger.Props>, ref): React.ReactElement => {
+    // eslint-disable-next-line sonarjs/deprecation -- backward-compatible asChild API
     const {asChild = false, children, className, render, ...otherProps} = props;
     const renderProp = asChild && React.isValidElement(children) ? children : render;
 
@@ -277,6 +278,7 @@ const SheetContent = React.forwardRef<React.ComponentRef<typeof BaseDialog.Popup
  * @see {@link https://base-ui.com/react/components/dialog | Base UI Documentation}
  */
 function SheetHeader(props: Readonly<SheetHeader.Props>): React.ReactElement {
+  // eslint-disable-next-line sonarjs/deprecation -- backward-compatible asChild API
   const {asChild = false, children, className, render, ...otherProps} = props;
   const renderProp = asChild && React.isValidElement(children) ? children : render;
 
@@ -305,6 +307,7 @@ function SheetHeader(props: Readonly<SheetHeader.Props>): React.ReactElement {
  * @see {@link https://base-ui.com/react/components/dialog | Base UI Documentation}
  */
 function SheetFooter(props: Readonly<SheetFooter.Props>): React.ReactElement {
+  // eslint-disable-next-line sonarjs/deprecation -- backward-compatible asChild API
   const {asChild = false, children, className, render, ...otherProps} = props;
   const renderProp = asChild && React.isValidElement(children) ? children : render;
 

package/src/components/ui/sidebar.tsx

@@ -1,3 +1,4 @@
+/* eslint-disable max-lines */
 "use client";
 
 import {PanelLeft} from "lucide-react";

package/src/components/ui/sonner.tsx

@@ -384,7 +384,7 @@ function updateToast(toastId: ToastIdentifier, options: ToastUpdateOptions): str
   const normalizedToastId = String(toastId);
   const existingRecord = toastRecords.get(normalizedToastId);
   const mergedOptions: ToastOptions = {
-    ...(existingRecord?.options ?? {}),
+    ...existingRecord?.options,
     ...options,
   };
   const variant = options.variant ?? existingRecord?.snapshot.variant ?? "default";
@@ -594,16 +594,23 @@ function ToastViewportContent(): React.JSX.Element {
  *
  * @see {@link https://base-ui.com/react/components/toast | Base UI Toast Docs}
  */
-function Toaster({
-  className,
-  closeButton = true,
-  containerAriaLabel = DEFAULT_VIEWPORT_ARIA_LABEL,
-  duration = DEFAULT_TOAST_DURATION,
-  position = "bottom-right",
-  style,
-  toastOptions,
-  visibleToasts = DEFAULT_TOAST_LIMIT,
-}: Readonly<ToasterProps>): React.JSX.Element {
+/**
+ * Toaster is the root viewport container for displaying toast notifications.
+ * It should be rendered once at the app root level.
+ */
+const Toaster = React.forwardRef<HTMLDivElement, ToasterProps>(function Toaster(
+  {
+    className,
+    closeButton = true,
+    containerAriaLabel = DEFAULT_VIEWPORT_ARIA_LABEL,
+    duration = DEFAULT_TOAST_DURATION,
+    position = "bottom-right",
+    style,
+    toastOptions,
+    visibleToasts = DEFAULT_TOAST_LIMIT,
+  },
+  forwardedRef,
+) {
   const toasterId = React.useId();
 
   React.useEffect(() => {
@@ -624,6 +631,7 @@ function Toaster({
       toastManager={toastManager}>
       <Toast.Portal>
         <Toast.Viewport
+          ref={forwardedRef}
           aria-label={containerAriaLabel}
           className={cn(styles.viewport, positionStyles[position], className)}
           style={style}>
@@ -632,7 +640,7 @@ function Toaster({
       </Toast.Portal>
     </Toast.Provider>
   );
-}
+});
 
 Toaster.displayName = "Toaster";
 

package/src/components/ui/toggle-group.tsx

@@ -63,12 +63,13 @@ export interface ToggleGroupItemProps extends Omit<ToggleProps, "pressed" | "def
  *
  * @see {@link https://base-ui.com/react/components/toggle-group | Base UI Toggle Group Docs}
  */
-function ToggleGroup(props: Readonly<ToggleGroup.Props>): React.ReactElement {
+const ToggleGroup = React.forwardRef<HTMLDivElement, ToggleGroup.Props>(function ToggleGroup(props, forwardedRef) {
   const {className, children, render, size, variant, ...otherProps} = props;
 
   return (
     <BaseToggleGroup
       {...otherProps}
+      ref={forwardedRef}
       render={useRender({
         defaultTagName: "div",
         render: render as never,
@@ -77,7 +78,7 @@ function ToggleGroup(props: Readonly<ToggleGroup.Props>): React.ReactElement {
       <ToggleGroupContext.Provider value={{variant, size}}>{children}</ToggleGroupContext.Provider>
     </BaseToggleGroup>
   );
-}
+});
 
 /**
  * Renders an individual toggle item within a toggle group.
@@ -96,12 +97,13 @@ function ToggleGroup(props: Readonly<ToggleGroup.Props>): React.ReactElement {
  *
  * @see {@link https://base-ui.com/react/components/toggle-group | Base UI Toggle Group Docs}
  */
-function ToggleGroupItem(props: Readonly<ToggleGroupItem.Props>): React.ReactElement {
+const ToggleGroupItem = React.forwardRef<HTMLButtonElement, ToggleGroupItem.Props>(function ToggleGroupItem(props, forwardedRef) {
   const {className, size, variant, ...otherProps} = props;
   const context = React.useContext(ToggleGroupContext);
 
   return (
     <Toggle
+      ref={forwardedRef}
       className={cn(
         toggleVariants({
           variant: variant ?? context.variant,
@@ -114,7 +116,7 @@ function ToggleGroupItem(props: Readonly<ToggleGroupItem.Props>): React.ReactEle
       {...otherProps}
     />
   );
-}
+});
 
 // eslint-disable-next-line no-redeclare -- required for the canonical component namespace typing API
 namespace ToggleGroup {

package/src/components/ui/toolbar.tsx

@@ -8,12 +8,6 @@ import * as React from "react";
 import {cn} from "@/lib/utilities";
 import styles from "./toolbar.module.css";
 
-type ToolbarProps = React.ComponentPropsWithRef<typeof BaseToolbar.Root>;
-type ToolbarButtonProps = React.ComponentPropsWithRef<typeof BaseToolbar.Button>;
-type ToolbarGroupProps = React.ComponentPropsWithRef<typeof BaseToolbar.Group>;
-type ToolbarSeparatorProps = React.ComponentPropsWithRef<typeof BaseToolbar.Separator>;
-type ToolbarLinkProps = React.ComponentPropsWithRef<typeof BaseToolbar.Link>;
-
 /**
  * Arranges related actions into a keyboard-accessible toolbar.
  *
@@ -32,12 +26,13 @@ type ToolbarLinkProps = React.ComponentPropsWithRef<typeof BaseToolbar.Link>;
  *
  * @see {@link https://base-ui.com/react/components/toolbar | Base UI Toolbar Docs}
  */
-function Toolbar(props: Readonly<Toolbar.Props>): React.ReactElement {
+const Toolbar = React.forwardRef<HTMLDivElement, Toolbar.Props>(function Toolbar(props, forwardedRef) {
   const {className, children, render, ...otherProps} = props;
 
   return (
     <BaseToolbar.Root
       {...otherProps}
+      ref={forwardedRef}
       render={useRender({
         defaultTagName: "div",
         render: render as never,
@@ -46,7 +41,7 @@ function Toolbar(props: Readonly<Toolbar.Props>): React.ReactElement {
       {children}
     </BaseToolbar.Root>
   );
-}
+});
 
 /**
  * Renders an interactive button within a toolbar.
@@ -63,12 +58,13 @@ function Toolbar(props: Readonly<Toolbar.Props>): React.ReactElement {
  *
  * @see {@link https://base-ui.com/react/components/toolbar | Base UI Toolbar Docs}
  */
-function ToolbarButton(props: Readonly<ToolbarButton.Props>): React.ReactElement {
+const ToolbarButton = React.forwardRef<HTMLButtonElement, ToolbarButton.Props>(function ToolbarButton(props, forwardedRef) {
   const {className, children, render, ...otherProps} = props;
 
   return (
     <BaseToolbar.Button
       {...otherProps}
+      ref={forwardedRef}
       render={useRender({
         defaultTagName: "button",
         render: render as never,
@@ -77,7 +73,7 @@ function ToolbarButton(props: Readonly<ToolbarButton.Props>): React.ReactElement
       {children}
     </BaseToolbar.Button>
   );
-}
+});
 
 /**
  * Groups related toolbar controls into a single visual cluster.
@@ -96,12 +92,13 @@ function ToolbarButton(props: Readonly<ToolbarButton.Props>): React.ReactElement
  *
  * @see {@link https://base-ui.com/react/components/toolbar | Base UI Toolbar Docs}
  */
-function ToolbarGroup(props: Readonly<ToolbarGroup.Props>): React.ReactElement {
+const ToolbarGroup = React.forwardRef<HTMLDivElement, ToolbarGroup.Props>(function ToolbarGroup(props, forwardedRef) {
   const {className, children, render, ...otherProps} = props;
 
   return (
     <BaseToolbar.Group
       {...otherProps}
+      ref={forwardedRef}
       render={useRender({
         defaultTagName: "div",
         render: render as never,
@@ -110,7 +107,7 @@ function ToolbarGroup(props: Readonly<ToolbarGroup.Props>): React.ReactElement {
       {children}
     </BaseToolbar.Group>
   );
-}
+});
 
 /**
  * Renders a visual separator between toolbar items or groups.
@@ -126,12 +123,13 @@ function ToolbarGroup(props: Readonly<ToolbarGroup.Props>): React.ReactElement {
  *
  * @see {@link https://base-ui.com/react/components/toolbar | Base UI Toolbar Docs}
  */
-function ToolbarSeparator(props: Readonly<ToolbarSeparator.Props>): React.ReactElement {
+const ToolbarSeparator = React.forwardRef<HTMLDivElement, ToolbarSeparator.Props>(function ToolbarSeparator(props, forwardedRef) {
   const {className, render, ...otherProps} = props;
 
   return (
     <BaseToolbar.Separator
       {...otherProps}
+      ref={forwardedRef}
       render={useRender({
         defaultTagName: "div",
         render: render as never,
@@ -139,7 +137,7 @@ function ToolbarSeparator(props: Readonly<ToolbarSeparator.Props>): React.ReactE
       })}
     />
   );
-}
+});
 
 /**
  * Renders a link that visually matches toolbar buttons.
@@ -155,12 +153,13 @@ function ToolbarSeparator(props: Readonly<ToolbarSeparator.Props>): React.ReactE
  *
  * @see {@link https://base-ui.com/react/components/toolbar | Base UI Toolbar Docs}
  */
-function ToolbarLink(props: Readonly<ToolbarLink.Props>): React.ReactElement {
+const ToolbarLink = React.forwardRef<HTMLAnchorElement, ToolbarLink.Props>(function ToolbarLink(props, forwardedRef) {
   const {className, children, render, ...otherProps} = props;
 
   return (
     <BaseToolbar.Link
       {...otherProps}
+      ref={forwardedRef}
       render={useRender({
         defaultTagName: "a",
         render: render as never,
@@ -169,35 +168,35 @@ function ToolbarLink(props: Readonly<ToolbarLink.Props>): React.ReactElement {
       {children}
     </BaseToolbar.Link>
   );
-}
+});
 
 // eslint-disable-next-line no-redeclare -- required for the canonical component namespace typing API
 namespace Toolbar {
-  export type Props = ToolbarProps;
+  export type Props = React.ComponentPropsWithRef<typeof BaseToolbar.Root>;
   export type State = BaseToolbar.Root.State;
 }
 
 // eslint-disable-next-line no-redeclare -- required for the canonical component namespace typing API
 namespace ToolbarButton {
-  export type Props = ToolbarButtonProps;
+  export type Props = React.ComponentPropsWithRef<typeof BaseToolbar.Button>;
   export type State = BaseToolbar.Button.State;
 }
 
 // eslint-disable-next-line no-redeclare -- required for the canonical component namespace typing API
 namespace ToolbarGroup {
-  export type Props = ToolbarGroupProps;
+  export type Props = React.ComponentPropsWithRef<typeof BaseToolbar.Group>;
   export type State = BaseToolbar.Group.State;
 }
 
 // eslint-disable-next-line no-redeclare -- required for the canonical component namespace typing API
 namespace ToolbarSeparator {
-  export type Props = ToolbarSeparatorProps;
+  export type Props = React.ComponentPropsWithRef<typeof BaseToolbar.Separator>;
   export type State = BaseToolbar.Separator.State;
 }
 
 // eslint-disable-next-line no-redeclare -- required for the canonical component namespace typing API
 namespace ToolbarLink {
-  export type Props = ToolbarLinkProps;
+  export type Props = React.ComponentPropsWithRef<typeof BaseToolbar.Link>;
   export type State = BaseToolbar.Link.State;
 }
 

package/src/hooks/useClipboard.tsx

@@ -0,0 +1,137 @@
+"use client";
+
+import * as React from "react";
+
+/**
+ * Options for the `useClipboard` hook.
+ */
+export interface UseClipboardOptions {
+  /**
+   * The duration in milliseconds after which the `copied` state resets to `false`.
+   *
+   * @defaultValue 2000
+   */
+  timeout?: number;
+}
+
+/**
+ * Return type for the `useClipboard` hook.
+ */
+export interface UseClipboardReturn {
+  /**
+   * Whether the text was successfully copied to the clipboard.
+   */
+  copied: boolean;
+
+  /**
+   * Copies the provided text to the clipboard.
+   *
+   * @param text - The text to copy.
+   * @returns A promise that resolves when the copy operation completes.
+   */
+  copy: (text: string) => Promise<void>;
+
+  /**
+   * The error that occurred during the copy operation, or `null` if no error occurred.
+   */
+  error: Error | null;
+}
+
+/**
+ * Copies text to the clipboard with success/error state management.
+ *
+ * @remarks
+ * This hook provides a simple interface for copying text to the clipboard using
+ * the Clipboard API. It manages the `copied` state that automatically resets
+ * after a configurable timeout, and handles errors gracefully when the Clipboard
+ * API is unavailable or the operation fails.
+ *
+ * The hook is SSR-safe and will handle the case where `navigator.clipboard` is
+ * not available (e.g., in non-secure contexts or older browsers).
+ *
+ * @param options - Configuration options for the hook.
+ * @returns An object containing the copied state, copy function, and any error.
+ *
+ * @example
+ * ```tsx
+ * function CopyButton({textToCopy}: {textToCopy: string}) {
+ *   const {copied, copy, error} = useClipboard({timeout: 3000});
+ *
+ *   return (
+ *     <div>
+ *       <button onClick={() => copy(textToCopy)}>
+ *         {copied ? "Copied!" : "Copy to clipboard"}
+ *       </button>
+ *       {error && <span>Failed to copy: {error.message}</span>}
+ *     </div>
+ *   );
+ * }
+ * ```
+ *
+ * @example
+ * ```tsx
+ * function ShareLink({url}: {url: string}) {
+ *   const {copied, copy} = useClipboard();
+ *
+ *   return (
+ *     <button onClick={() => copy(url)} disabled={copied}>
+ *       {copied ? "✓ Copied" : "Share link"}
+ *     </button>
+ *   );
+ * }
+ * ```
+ */
+export function useClipboard(options: UseClipboardOptions = {}): UseClipboardReturn {
+  const {timeout = 2000} = options;
+
+  const [copied, setCopied] = React.useState(false);
+  const [error, setError] = React.useState<Error | null>(null);
+  const timeoutRef = React.useRef<ReturnType<typeof setTimeout> | null>(null);
+
+  const copy = React.useCallback(
+    async (text: string): Promise<void> => {
+      // Clear any existing timeout
+      if (timeoutRef.current !== null) {
+        clearTimeout(timeoutRef.current);
+        timeoutRef.current = null;
+      }
+
+      // Reset error state
+      setError(null);
+
+      try {
+        // Check if Clipboard API is available
+        if (typeof globalThis.navigator === "undefined" || !globalThis.navigator.clipboard) {
+          throw new Error("Clipboard API is not available");
+        }
+
+        await globalThis.navigator.clipboard.writeText(text);
+        setCopied(true);
+
+        // Reset copied state after timeout
+        timeoutRef.current = setTimeout(() => {
+          setCopied(false);
+          timeoutRef.current = null;
+        }, timeout);
+      } catch (err) {
+        const errorMessage = err instanceof Error ? err : new Error("Failed to copy to clipboard");
+
+        setError(errorMessage);
+        setCopied(false);
+        console.error("Copy to clipboard failed:", errorMessage);
+      }
+    },
+    [timeout],
+  );
+
+  // Cleanup timeout on unmount
+  React.useEffect(() => {
+    return () => {
+      if (timeoutRef.current !== null) {
+        clearTimeout(timeoutRef.current);
+      }
+    };
+  }, []);
+
+  return {copied, copy, error};
+}

package/src/hooks/useControllableState.tsx

@@ -0,0 +1,81 @@
+"use client";
+
+import * as React from "react";
+
+/**
+ * Options for configuring controllable state behavior.
+ *
+ * @typeParam T - The type of the state value.
+ */
+export interface UseControllableStateOptions<T> {
+  /**
+   * The controlled value from props. When provided, the component operates in controlled mode.
+   */
+  controlled?: T;
+  /**
+   * The default value used when the component is uncontrolled.
+   */
+  defaultValue: T;
+  /**
+   * Callback fired when the internal state changes in controlled mode.
+   *
+   * @param value - The new state value.
+   */
+  onChange?: (value: T) => void;
+}
+
+/**
+ * Manages state that can be either controlled or uncontrolled.
+ *
+ * @remarks
+ * This hook enables components to support both controlled and uncontrolled patterns
+ * seamlessly. When a `controlled` value is provided, it takes precedence; otherwise,
+ * the hook manages internal state initialized with `defaultValue`.
+ *
+ * @typeParam T - The type of the state value.
+ * @param options - Configuration object for controllable state.
+ * @returns A tuple containing the current state value and a setter function.
+ *
+ * @example
+ * ```tsx
+ * function CustomInput({value, defaultValue = "", onChange}) {
+ *   const [internalValue, setValue] = useControllableState({
+ *     controlled: value,
+ *     defaultValue,
+ *     onChange,
+ *   });
+ *
+ *   return (
+ *     <input
+ *       type="text"
+ *       value={internalValue}
+ *       onChange={(e) => setValue(e.target.value)}
+ *     />
+ *   );
+ * }
+ * ```
+ */
+export function useControllableState<T>(options: UseControllableStateOptions<T>): [T, (value: T | ((prev: T) => T)) => void] {
+  const {controlled, defaultValue, onChange} = options;
+  const [uncontrolledState, setUncontrolledState] = React.useState<T>(defaultValue);
+  const isControlled = controlled !== undefined;
+  const value = isControlled ? controlled : uncontrolledState;
+
+  const setValue = React.useCallback(
+    (nextValue: T | ((prev: T) => T)) => {
+      if (!isControlled) {
+        setUncontrolledState((currentValue) => {
+          const resolvedValue = typeof nextValue === "function" ? (nextValue as (prev: T) => T)(currentValue) : nextValue;
+          onChange?.(resolvedValue);
+          return resolvedValue;
+        });
+      } else {
+        const resolvedValue = typeof nextValue === "function" ? (nextValue as (prev: T) => T)(controlled as T) : nextValue;
+        onChange?.(resolvedValue);
+      }
+    },
+    [isControlled, onChange, controlled],
+  );
+
+  return [value, setValue];
+}