@firecms/ui 3.3.0-canary.1e1cce9 → 3.3.0-canary.289082f

package/src/components/FilterChip.tsx

@@ -0,0 +1,79 @@
+import React from "react";
+import { cls } from "../util";
+
+export interface FilterChipProps extends Omit<React.ButtonHTMLAttributes<HTMLButtonElement>, "children"> {
+    /**
+     * The text label displayed on the chip.
+     */
+    children: React.ReactNode;
+    /**
+     * Whether the chip is currently in an active/selected state.
+     */
+    active?: boolean;
+    /**
+     * Optional icon rendered before the label.
+     */
+    icon?: React.ReactNode;
+    /**
+     * Size variant.
+     * @default "medium"
+     */
+    size?: "small" | "medium";
+    /**
+     * Whether the chip is disabled.
+     */
+    disabled?: boolean;
+}
+
+const sizeClasses = {
+    small: "px-2 py-0.5 text-xs",
+    medium: "px-2.5 py-1 text-xs"
+};
+
+/**
+ * A toggle chip used for filter presets and similar multi-select controls.
+ *
+ * Uses an inset box-shadow for the active ring instead of `border` so the
+ * chip size stays stable across states and the ring cannot be clipped by
+ * parent `overflow-hidden` containers.
+ *
+ * @group Interactive components
+ */
+export const FilterChip = React.forwardRef<HTMLButtonElement, FilterChipProps>(function FilterChip({
+    children,
+    active = false,
+    onClick,
+    icon,
+    size = "medium",
+    className,
+    disabled = false,
+    ...rest
+}: FilterChipProps, ref) {
+    return (
+        <button
+            ref={ref}
+            type="button"
+            onClick={onClick}
+            disabled={disabled}
+            className={cls(
+                "inline-flex items-center gap-1 rounded-full",
+                "font-medium whitespace-nowrap select-none shrink-0",
+                "transition-colors duration-150",
+                "focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-primary/50",
+                sizeClasses[size],
+                active
+                    ? "bg-primary/12 text-primary dark:bg-primary/20 dark:text-primary shadow-[inset_0_0_0_1.5px_var(--color-primary)]"
+                    : cls(
+                        "bg-surface-accent-100 text-text-secondary dark:bg-surface-accent-800 dark:text-text-secondary-dark",
+                        !disabled && "cursor-pointer hover:bg-primary/5 dark:hover:bg-primary/5"
+                    ),
+                disabled && "opacity-50 cursor-not-allowed",
+                className
+            )}
+            {...rest}
+        >
+            {icon}
+            {children}
+        </button>
+    );
+});

package/src/components/IconButton.tsx

@@ -11,16 +11,17 @@ export type IconButtonProps<C extends React.ElementType> =
     disabled?: boolean;
     toggled?: boolean;
     component?: C;
-    onClick?: React.MouseEventHandler<any>
+    onClick?: React.MouseEventHandler<any>;
+    "aria-label"?: string;
 }
 
-const buttonClasses = "hover:bg-surface-accent-200 hover:bg-opacity-75 hover:bg-surface-accent-200/75 dark:hover:bg-surface-accent-800 hover:scale-105 transition-transform";
+const buttonClasses = "hover:bg-surface-accent-200 hover:bg-opacity-75 hover:bg-surface-accent-200/75 dark:hover:bg-surface-accent-800 hover:scale-[1.04] active:scale-95 transition-transform";
 const baseClasses = "inline-flex items-center justify-center p-2 text-sm font-medium focus:outline-none transition-colors ease-in-out duration-150";
-const colorClasses = "text-surface-accent-600 visited:text-surface-accent-600 dark:text-surface-accent-300 dark:visited:text-surface-300";
+const colorClasses = "text-surface-accent-500 visited:text-surface-accent-500 dark:text-surface-accent-300 dark:visited:text-surface-300";
 const sizeClasses = {
     medium: "w-10 !h-10 min-w-10 min-h-10",
     small: "w-8 !h-8 min-w-8 min-h-8",
-    smallest: "w-6 !h-6 min-w-6 min-h-6",
+    smallest: "w-7 !h-7 min-w-7 min-h-7",
     large: "w-12 !h-12 min-w-12 min-h-12"
 }
 const shapeClasses = {
@@ -40,11 +41,15 @@ const IconButtonInner = <C extends React.ElementType = "button">({
                                                                      ...props
                                                                  }: IconButtonProps<C>, ref: React.ForwardedRef<HTMLButtonElement>) => {
 
-    const bgClasses = variant === "ghost" ? "bg-transparent" : "bg-surface-accent-200 bg-opacity-50 bg-surface-accent-200/50 dark:bg-surface-950 dark:bg-opacity-50 dark:bg-surface-950/50";
+    const bgClasses = variant === "ghost" ? "bg-transparent" : "bg-surface-accent-200 bg-opacity-50 bg-surface-accent-200/50 dark:bg-surface-900 dark:bg-opacity-50 dark:bg-surface-900/50";
     const Component: React.ElementType<any> = component || "button";
+    const isNativeButton = Component === "button";
     return (
         <Component
-            type="button"
+            type={isNativeButton ? "button" : undefined}
+            role={isNativeButton ? undefined : "button"}
+            aria-disabled={disabled || undefined}
+            tabIndex={disabled ? -1 : undefined}
             ref={ref}
             {...props}
             className={cls(

package/src/components/InfoLabel.tsx

@@ -16,7 +16,7 @@ export function InfoLabel({
 
     return (
         <div
-            className={cls("my-3 py-2 px-4 rounded", colorClasses[mode])}>
+            className={cls("my-3 py-2 px-4 rounded-xs", colorClasses[mode])}>
             {children}
         </div>
     )

package/src/components/InputLabel.tsx

@@ -10,7 +10,7 @@ export type InputLabelProps = {
 } & React.LabelHTMLAttributes<HTMLLabelElement>;
 
 const defaultClasses = {
-    root: "origin-left transition-transform block whitespace-nowrap overflow-hidden text-overflow-ellipsis max-w-full",
+    root: "origin-left transition-transform block whitespace-nowrap overflow-hidden text-ellipsis max-w-full",
     shrink: "transform translate-y-[2px] scale-75 translate-x-[12px]",
     expanded: "translate-x-[16px] top-0 transform translate-y-[16px] scale-100"
 };
@@ -30,7 +30,7 @@ export const InputLabel = React.forwardRef<HTMLLabelElement, InputLabelProps>(fu
 
     return (
         <label
-            className={cls("text-sm font-medium peer-disabled:cursor-not-allowed peer-disabled:opacity-70",
+            className={cls("text-sm font-medium peer-disabled:cursor-not-allowed",
                 defaultBorderMixin, computedClassName)}
             data-shrink={shrink}
             ref={ref}

package/src/components/Label.tsx

@@ -20,7 +20,7 @@ const Label = React.forwardRef<
     <LabelPrimitive.Root
         ref={ref}
         onClick={onClick}
-        className={cls("text-sm font-medium peer-disabled:cursor-not-allowed peer-disabled:opacity-70",
+        className={cls("text-sm font-medium peer-disabled:cursor-not-allowed",
             border && "border border-surface-300 dark:border-surface-700 rounded-md px-3 py-1.5",
             onClick && "hover:cursor-pointer hover:bg-surface-200 dark:hover:bg-surface-800",
             defaultBorderMixin, className)}

package/src/components/LoadingButton.tsx

@@ -19,7 +19,7 @@ export function LoadingButton<P extends React.ElementType = "button">({
         <Button
             disabled={loading || disabled}
             onClick={onClick}
-            component={props.component as any}
+            component={props.component as React.ElementType}
             {...props}
         >
             {loading && (

package/src/components/Menu.tsx

@@ -102,3 +102,5 @@ export const MenuItem = React.memo(({
         </DropdownMenu.Item>
     );
 });
+
+MenuItem.displayName = "MenuItem";

package/src/components/Popover.tsx

@@ -27,6 +27,8 @@ export interface PopoverProps {
     modal?: boolean;
     className?: string;
     portalContainer?: HTMLElement | null;
+    onMouseEnter?: React.MouseEventHandler<HTMLDivElement>;
+    onMouseLeave?: React.MouseEventHandler<HTMLDivElement>;
 }
 
 export function Popover({
@@ -45,7 +47,9 @@ export function Popover({
                             enabled = true,
                             modal = false,
                             portalContainer,
-                            className
+                            className,
+                            onMouseEnter,
+                            onMouseLeave
                         }: PopoverProps) {
 
     useInjectStyles("Popover", popoverStyles);
@@ -78,10 +82,12 @@ export function Popover({
                 arrowPadding={arrowPadding}
                 sticky={sticky}
                 hideWhenDetached={hideWhenDetached}
-                avoidCollisions={avoidCollisions}>
+                avoidCollisions={avoidCollisions}
+                onMouseEnter={onMouseEnter}
+                onMouseLeave={onMouseLeave}>
 
                 {children}
-                <PopoverPrimitive.Arrow className="fill-white dark:fill-surface-accent-950"/>
+                <PopoverPrimitive.Arrow className="fill-white dark:fill-surface-800"/>
             </PopoverPrimitive.Content>
         </PopoverPrimitive.Portal>
     </PopoverPrimitive.Root>;

package/src/components/RadioGroup.tsx

@@ -58,7 +58,7 @@ const RadioGroupItem = React.forwardRef<
         <RadioGroupPrimitive.Item
             ref={ref}
             className={cls(
-                "aspect-square h-4 w-4 rounded-full border border-primary text-primary ring-offset-background focus:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 disabled:cursor-not-allowed disabled:opacity-50",
+                "aspect-square h-4 w-4 rounded-full border border-primary text-primary ring-offset-background focus:outline-hidden focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 disabled:cursor-not-allowed disabled:opacity-50",
                 className
             )}
             {...props}

package/src/components/Select.tsx

@@ -36,7 +36,7 @@ export type SelectProps<T extends SelectValue = string> = {
     error?: boolean,
     position?: "item-aligned" | "popper",
     endAdornment?: React.ReactNode,
-    inputRef?: React.RefObject<HTMLButtonElement | null>,
+    inputRef?: React.Ref<HTMLButtonElement>,
     padding?: boolean,
     invisible?: boolean,
     children?: React.ReactNode;
@@ -136,7 +136,7 @@ export const Select = forwardRef<HTMLDivElement, SelectProps>(({
             {...props}>
             {typeof label === "string" ? <SelectInputLabel error={error}>{label}</SelectInputLabel> : label}
             <div className={cls(
-                "select-none rounded-md text-sm",
+                "select-none rounded-lg text-sm",
                 invisible ? fieldBackgroundInvisibleMixin : fieldBackgroundMixin,
                 disabled ? fieldBackgroundDisabledMixin : fieldBackgroundHoverMixin,
                 "relative flex items-center",
@@ -155,6 +155,8 @@ export const Select = forwardRef<HTMLDivElement, SelectProps>(({
                     id={id}
                     asChild={false}
                     type="button"
+                    aria-label={typeof label === "string" ? label : (typeof renderValue === "string" ? renderValue : "Select an option")}
+                    aria-invalid={error || undefined}
                     className={cls(
                         "h-full",
                         padding ? {
@@ -164,7 +166,7 @@ export const Select = forwardRef<HTMLDivElement, SelectProps>(({
                         } : "",
                         "outline-hidden focus:outline-hidden",
                         "outline-none focus:outline-none",
-                        "select-none rounded-md text-sm",
+                        "select-none rounded-lg text-sm",
                         error ? "text-red-500 dark:text-red-600" : "focus:text-text-primary dark:focus:text-text-primary-dark",
                         error ? "border border-red-500 dark:border-red-600" : "",
                         disabled ? "text-surface-accent-600 dark:text-surface-accent-400" : "text-surface-accent-800 dark:text-white",
@@ -232,7 +234,7 @@ export const Select = forwardRef<HTMLDivElement, SelectProps>(({
             {/* Pass the calculated finalContainer */}
             <SelectPrimitive.Portal container={finalContainer}>
                 <SelectPrimitive.Content position={position}
-                    className={cls(focusedDisabled, "z-50 relative overflow-hidden border bg-white dark:bg-surface-900 p-2 rounded-lg", defaultBorderMixin)}>
+                    className={cls(focusedDisabled, "z-50 relative overflow-hidden border bg-white dark:bg-surface-800 p-2 rounded-lg shadow-lg", defaultBorderMixin)}>
                     <SelectPrimitive.Viewport className={cls("p-1", viewportClassName)}
                         style={{ maxHeight: "var(--radix-select-content-available-height)" }}>
                         {children}
@@ -270,8 +272,8 @@ export const SelectItem = React.memo(function SelectItem<T extends SelectValue =
             "w-full",
             "relative flex items-center p-2 rounded-md text-sm text-surface-accent-700 dark:text-surface-accent-300",
             "focus:z-10",
-            "data-[state=checked]:bg-surface-accent-100 data-[state=checked]:dark:bg-surface-accent-800 focus:bg-surface-accent-100 dark:focus:bg-surface-950",
-            "data-[state=checked]:focus:bg-surface-accent-200 data-[state=checked]:dark:focus:bg-surface-950",
+            "data-[state=checked]:bg-surface-accent-100 data-[state=checked]:dark:bg-surface-accent-800 focus:bg-surface-accent-100 dark:focus:bg-surface-900",
+            "data-[state=checked]:focus:bg-surface-accent-200 data-[state=checked]:dark:focus:bg-surface-900",
             disabled ? "opacity-50 cursor-not-allowed" : "cursor-pointer",
             "[&>*]:w-full",
             "overflow-visible",

package/src/components/Separator.tsx

@@ -15,12 +15,12 @@ export function Separator({
             <SeparatorPrimitive.Root
                 decorative={decorative}
                 orientation="horizontal"
-                className={cls("dark:bg-opacity-80 dark:bg-surface-800 dark:bg-surface-800/80 bg-surface-100 data-[orientation=horizontal]:h-px data-[orientation=horizontal]:w-full data-[orientation=vertical]:h-full data-[orientation=vertical]:w-px my-4", className)}/>
+                className={cls("dark:bg-surface-700 bg-surface-200 data-[orientation=horizontal]:h-px data-[orientation=horizontal]:w-full data-[orientation=vertical]:h-full data-[orientation=vertical]:w-px my-4", className)}/>
         );
     else
         return (
             <SeparatorPrimitive.Root
-                className={cls("dark:bg-opacity-80 dark:bg-surface-800 dark:bg-surface-800/80 bg-surface-100 data-[orientation=horizontal]:h-px data-[orientation=horizontal]:w-full data-[orientation=vertical]:h-full data-[orientation=vertical]:w-px mx-4", className)}
+                className={cls("dark:bg-surface-700 bg-surface-200 data-[orientation=horizontal]:h-px data-[orientation=horizontal]:w-full data-[orientation=vertical]:h-full data-[orientation=vertical]:w-px mx-4", className)}
                 decorative={decorative}
                 orientation="vertical"
             />

package/src/components/Skeleton.tsx

@@ -1,5 +1,6 @@
 import React from "react";
 import { cls } from "../util";
+import { useInjectStyles } from "../hooks";
 
 export type SkeletonProps = {
     width?: number;
@@ -7,24 +8,40 @@ export type SkeletonProps = {
     className?: string;
 }
 
+const styles = `
+@keyframes shimmer {
+  0% {
+    transform: translateX(-150%);
+  }
+  100% {
+    transform: translateX(150%);
+  }
+}
+`;
+
 export function Skeleton({
                              width,
                              height,
                              className
                          }: SkeletonProps) {
+
+    useInjectStyles("Skeleton", styles);
+
     return <span
         style={{
-            width: width !== undefined ? `${width}px` : undefined,
-            height: height !== undefined ? `${height}px` : undefined
+            width: width ? `${width}px` : "100%",
+            height: height ? `${height}px` : "12px"
         }}
         className={
         cls(
-            "block",
-            "bg-surface-accent-200 dark:bg-surface-accent-800 rounded-md",
-            "animate-pulse",
+            "block relative overflow-hidden",
+            "bg-surface-accent-50 dark:bg-surface-accent-800 rounded-md",
             "max-w-full max-h-full",
-            width === undefined ? "w-full" : "",
-            height === undefined ? "h-3" : "",
             className)
-    }/>;
+    }>
+        <span
+            className="absolute inset-0 bg-gradient-to-r from-transparent via-white/50 dark:via-white/8 to-transparent"
+            style={{ animation: "shimmer 1.8s ease-in-out infinite" }}
+        />
+    </span>;
 }

package/src/components/TextField.tsx

@@ -1,12 +1,12 @@
 "use client";
-import React, { ForwardedRef, forwardRef, useEffect, useRef } from "react";
+import React, { ForwardedRef, forwardRef, useEffect, useId, useRef } from "react";
 
 import {
     fieldBackgroundDisabledMixin,
     fieldBackgroundHoverMixin,
     fieldBackgroundInvisibleMixin,
     fieldBackgroundMixin,
-    focusedInvisibleMixin,
+    focusedInvisibleMixin
 } from "../styles";
 import { InputLabel } from "./InputLabel";
 import { cls } from "../util";
@@ -53,7 +53,7 @@ export type TextFieldProps<T extends string | number> = {
      * @default 1
      */
     minRows?: number | string;
-} & Omit<React.InputHTMLAttributes<HTMLInputElement>, "size">;
+} & Omit<React.InputHTMLAttributes<HTMLInputElement>, "size" | "value">;
 
 export const TextField = forwardRef<HTMLDivElement, TextFieldProps<string | number>>(
     <T extends string | number>(
@@ -82,14 +82,18 @@ export const TextField = forwardRef<HTMLDivElement, TextFieldProps<string | numb
         ref: ForwardedRef<HTMLDivElement>
     ) => {
 
-        const inputRef = inputRefProp ?? useRef(null);
+        const fallbackRef = useRef(null);
+        const inputRef = inputRefProp ?? fallbackRef;
+        const autoId = useId();
+        const inputId = inputProps.id ?? autoId;
+        const labelId = `${inputId}-label`;
 
         const [focused, setFocused] = React.useState(false);
         const hasValue = value !== undefined && value !== null && value !== "";
 
         useEffect(() => {
-            // @ts-ignore
-            if (inputRef.current && document.activeElement === inputRef.current) {
+            const element = inputRef && "current" in inputRef ? inputRef.current : null;
+            if (element && document.activeElement === element) {
                 setFocused(true);
             }
         }, []);
@@ -111,8 +115,12 @@ export const TextField = forwardRef<HTMLDivElement, TextFieldProps<string | numb
 
         const input = multiline ? (
             <textarea
-                {...(inputProps as any)}
+                {...(inputProps as React.TextareaHTMLAttributes<HTMLTextAreaElement>)}
                 ref={inputRef}
+                id={inputId}
+                aria-labelledby={label ? labelId : undefined}
+                aria-invalid={error || undefined}
+                aria-disabled={disabled || undefined}
                 placeholder={focused || hasValue || !label ? placeholder : undefined}
                 autoFocus={autoFocus}
                 rows={typeof minRows === "string" ? parseInt(minRows) : (minRows ?? 3)}
@@ -123,7 +131,7 @@ export const TextField = forwardRef<HTMLDivElement, TextFieldProps<string | numb
                 style={inputStyle}
                 className={cls(
                     invisible ? focusedInvisibleMixin : "",
-                    "rounded-md resize-none w-full outline-none text-base bg-transparent min-h-[64px] px-3",
+                    "rounded-lg resize-none w-full outline-none text-base bg-transparent min-h-[64px] px-3",
                     label ? "pt-8 pb-2" : "py-2",
                     disabled && "outline-none opacity-50 text-surface-accent-600 dark:text-surface-accent-500",
                     inputClassName
@@ -133,11 +141,15 @@ export const TextField = forwardRef<HTMLDivElement, TextFieldProps<string | numb
             <input
                 {...inputProps}
                 ref={inputRef}
+                id={inputId}
+                aria-labelledby={label ? labelId : undefined}
+                aria-invalid={error || undefined}
+                aria-disabled={disabled || undefined}
                 disabled={disabled}
                 style={inputStyle}
                 className={cls(
                     "w-full outline-none bg-transparent leading-normal px-3",
-                    "rounded-md",
+                    "rounded-lg",
                     "focused:text-text-primary focused:dark:text-text-primary-dark",
                     invisible ? focusedInvisibleMixin : "",
                     disabled ? fieldBackgroundDisabledMixin : fieldBackgroundHoverMixin,
@@ -145,7 +157,7 @@ export const TextField = forwardRef<HTMLDivElement, TextFieldProps<string | numb
                         "min-h-[28px]": size === "smallest",
                         "min-h-[32px]": size === "small",
                         "min-h-[44px]": size === "medium",
-                        "min-h-[64px]": size === "large",
+                        "min-h-[64px]": size === "large"
                     },
                     label
                         ? size === "large"
@@ -175,7 +187,7 @@ export const TextField = forwardRef<HTMLDivElement, TextFieldProps<string | numb
             <div
                 ref={ref}
                 className={cls(
-                    "rounded-md relative max-w-full",
+                    "rounded-lg relative max-w-full",
                     invisible ? fieldBackgroundInvisibleMixin : fieldBackgroundMixin,
                     disabled ? fieldBackgroundDisabledMixin : fieldBackgroundHoverMixin,
                     error ? "border border-red-500 dark:border-red-600" : "",
@@ -183,7 +195,7 @@ export const TextField = forwardRef<HTMLDivElement, TextFieldProps<string | numb
                         "min-h-[28px]": size === "smallest",
                         "min-h-[32px]": size === "small",
                         "min-h-[44px]": size === "medium",
-                        "min-h-[64px]": size === "large",
+                        "min-h-[64px]": size === "large"
                     },
                     className
                 )}
@@ -191,6 +203,8 @@ export const TextField = forwardRef<HTMLDivElement, TextFieldProps<string | numb
             >
                 {label && (
                     <InputLabel
+                        id={labelId}
+                        htmlFor={inputId}
                         className={cls(
                             "pointer-events-none absolute",
                             size === "large" ? "top-1" : "top-[-1px]",
@@ -216,7 +230,7 @@ export const TextField = forwardRef<HTMLDivElement, TextFieldProps<string | numb
                             {
                                 "mr-4": size === "large",
                                 "mr-3": size === "medium",
-                                "mr-2": size === "small" || size === "smallest",
+                                "mr-2": size === "small" || size === "smallest"
                             }
                         )}
                     >

package/src/components/ToggleButtonGroup.tsx

@@ -38,11 +38,13 @@ export function ToggleButtonGroup<T extends string = string>({
     className
 }: ToggleButtonGroupProps<T>) {
     return (
-        <div className={cls("inline-flex flex-row bg-surface-100 dark:bg-surface-800 rounded-lg p-1 gap-1", className)}>
+        <div role="group" aria-label="Toggle options" className={cls("inline-flex flex-row bg-surface-100 dark:bg-surface-900 rounded-lg p-1 gap-1", className)}>
             {options.map((option) => (
                 <button
                     key={option.value}
                     type="button"
+                    aria-pressed={value === option.value}
+                    aria-disabled={option.disabled || undefined}
                     onClick={(e) => {
                         e.stopPropagation();
                         if (!option.disabled) {
@@ -53,7 +55,7 @@ export function ToggleButtonGroup<T extends string = string>({
                     className={cls(
                         "flex flex-row items-center justify-center gap-2 py-3 px-4 rounded-md transition-colors",
                         value === option.value
-                            ? "bg-white dark:bg-surface-950 text-primary dark:text-primary-300"
+                            ? "bg-white dark:bg-surface-900 text-primary dark:text-primary-300 shadow-sm"
                             : "text-surface-500 dark:text-surface-400 hover:bg-surface-100 dark:hover:bg-surface-700",
                         option.disabled && "opacity-50 cursor-not-allowed"
                     )}

package/src/components/index.tsx

@@ -11,6 +11,7 @@ export * from "./Collapse";
 export * from "./CircularProgress";
 export * from "./Checkbox";
 export * from "./Chip";
+export * from "./FilterChip";
 export * from "./ColorPicker";
 export * from "./DateTimeField";
 export * from "./Dialog";

package/src/hooks/index.ts

@@ -1,5 +1,6 @@
 export * from "./useInjectStyles";
 export * from "./useOutsideAlerter";
 export * from "./useDebounceValue";
+export * from "./useDebounceCallback";
 export * from "./useIconStyles";
 export * from "./PortalContainerContext";

package/src/hooks/useDebounceCallback.tsx

@@ -0,0 +1,47 @@
+import { useCallback, useEffect, useRef } from "react";
+
+/**
+ * Returns a debounced version of the provided callback. The returned function
+ * keeps the same signature as the input callback; each invocation resets the
+ * timer, so the wrapped callback only runs once calls stop for `delay` ms.
+ *
+ * Unlike {@link useDebounceValue}, which debounces a *value*, this debounces a
+ * *function call* — useful for search inputs, autosave, resize handlers, etc.
+ *
+ * @param callback the function to debounce. May be undefined.
+ * @param delay debounce delay in milliseconds. Defaults to 200ms.
+ * @group Hooks
+ */
+export function useDebounceCallback<T extends (...args: any[]) => unknown>(
+    callback?: T,
+    delay?: number
+): T {
+    const timeoutRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+
+    // Keep the latest callback without recreating the debounced function.
+    const callbackRef = useRef(callback);
+    useEffect(() => {
+        callbackRef.current = callback;
+    }, [callback]);
+
+    // Clear any pending timer on unmount.
+    useEffect(() => {
+        return () => {
+            if (timeoutRef.current !== null) {
+                clearTimeout(timeoutRef.current);
+            }
+        };
+    }, []);
+
+    const debouncedCallback = useCallback((...args: Parameters<T>) => {
+        if (timeoutRef.current !== null) {
+            clearTimeout(timeoutRef.current);
+        }
+
+        timeoutRef.current = setTimeout(() => {
+            callbackRef.current?.(...args);
+        }, delay ?? 200);
+    }, [delay]);
+
+    return debouncedCallback as T;
+}