@true-tech-team/react-components 0.0.9 → 1.0.0

package/lib/components/navigation/Navbar/NavbarBrand.d.ts

@@ -25,5 +25,7 @@ export interface NavbarBrandProps extends BaseComponentProps {
  * </NavbarBrand>
  * ```
  */
-export declare const NavbarBrand: React.ForwardRefExoticComponent<NavbarBrandProps & React.RefAttributes<HTMLDivElement>>;
+export declare const NavbarBrand: ({ ref, children, href, onClick, className, "data-testid": testId, style, ...restProps }: NavbarBrandProps & {
+    ref?: React.Ref<HTMLDivElement>;
+}) => import("react/jsx-runtime").JSX.Element;
 export default NavbarBrand;

package/lib/components/navigation/Navbar/NavbarCollapse.d.ts

@@ -22,5 +22,7 @@ export interface NavbarCollapseProps extends BaseComponentProps {
  * </NavbarCollapse>
  * ```
  */
-export declare const NavbarCollapse: React.ForwardRefExoticComponent<NavbarCollapseProps & React.RefAttributes<HTMLDivElement>>;
+export declare const NavbarCollapse: ({ ref, children, className, "data-testid": testId, style, ...restProps }: NavbarCollapseProps & {
+    ref?: React.Ref<HTMLDivElement>;
+}) => import("react/jsx-runtime").JSX.Element;
 export default NavbarCollapse;

package/lib/components/navigation/Navbar/NavbarNav.d.ts

@@ -18,5 +18,7 @@ export interface NavbarNavProps extends BaseComponentProps {
  * </NavbarNav>
  * ```
  */
-export declare const NavbarNav: React.ForwardRefExoticComponent<NavbarNavProps & React.RefAttributes<HTMLElement>>;
+export declare const NavbarNav: ({ ref, children, className, "data-testid": testId, style, ...restProps }: NavbarNavProps & {
+    ref?: React.Ref<HTMLElement>;
+}) => import("react/jsx-runtime").JSX.Element;
 export default NavbarNav;

package/lib/components/navigation/Navbar/NavbarToggle.d.ts

@@ -17,5 +17,7 @@ export interface NavbarToggleProps extends BaseComponentProps {
  * <NavbarToggle icon={<CustomIcon />} />
  * ```
  */
-export declare const NavbarToggle: React.ForwardRefExoticComponent<NavbarToggleProps & React.RefAttributes<HTMLButtonElement>>;
+export declare const NavbarToggle: ({ ref, icon, className, "data-testid": testId, "aria-label": ariaLabel, style, ...restProps }: NavbarToggleProps & {
+    ref?: React.Ref<HTMLButtonElement>;
+}) => import("react/jsx-runtime").JSX.Element;
 export default NavbarToggle;

package/lib/components/navigation/Pagination/Pagination.d.ts

@@ -95,5 +95,7 @@ export interface PaginationProps extends BaseComponentProps {
  * />
  * ```
  */
-export declare const Pagination: React.ForwardRefExoticComponent<PaginationProps & React.RefAttributes<HTMLElement>>;
+export declare const Pagination: ({ ref, totalPages, currentPage, onPageChange, siblingCount, boundaryCount, showFirstLast, showPrevNext, size, variant, shape, disabled, labels, className, "data-testid": testId, "aria-label": ariaLabel, style, ...restProps }: PaginationProps & {
+    ref?: React.Ref<HTMLElement>;
+}) => import("react/jsx-runtime").JSX.Element | null;
 export default Pagination;

package/lib/components/navigation/SideNav/SideNav.d.ts

@@ -85,5 +85,7 @@ export interface SideNavProps extends BaseComponentProps {
  * </SideNav>
  * ```
  */
-export declare const SideNav: React.ForwardRefExoticComponent<SideNavProps & React.RefAttributes<HTMLElement>>;
+export declare const SideNav: ({ ref, position, collapsed: controlledCollapsed, defaultCollapsed, onCollapsedChange, expandedWidth, collapsedWidth, selectedValue: controlledSelectedValue, defaultSelectedValue, onSelect, header, footer, children, className, "data-testid": testId, "aria-label": ariaLabel, style, ...restProps }: SideNavProps & {
+    ref?: React.Ref<HTMLElement>;
+}) => import("react/jsx-runtime").JSX.Element;
 export default SideNav;

package/lib/components/navigation/SideNav/SideNavDivider.d.ts

@@ -18,5 +18,7 @@ export interface SideNavDividerProps extends Omit<BaseComponentProps, 'children'
  * <SideNavDivider label="Settings" />
  * ```
  */
-export declare const SideNavDivider: React.ForwardRefExoticComponent<SideNavDividerProps & React.RefAttributes<HTMLDivElement>>;
+export declare const SideNavDivider: ({ ref, label, className, "data-testid": testId, style, ...restProps }: SideNavDividerProps & {
+    ref?: React.Ref<HTMLDivElement>;
+}) => import("react/jsx-runtime").JSX.Element;
 export default SideNavDivider;

package/lib/components/navigation/SideNav/SideNavGroup.d.ts

@@ -40,5 +40,7 @@ export interface SideNavGroupProps extends BaseComponentProps {
  * </SideNavGroup>
  * ```
  */
-export declare const SideNavGroup: React.ForwardRefExoticComponent<SideNavGroupProps & React.RefAttributes<HTMLDivElement>>;
+export declare const SideNavGroup: ({ ref, groupId, label, icon, expanded: controlledExpanded, defaultExpanded, children, className, "data-testid": testId, style, ...restProps }: SideNavGroupProps & {
+    ref?: React.Ref<HTMLDivElement>;
+}) => import("react/jsx-runtime").JSX.Element;
 export default SideNavGroup;

package/lib/components/navigation/SideNav/SideNavItem.d.ts

@@ -67,5 +67,7 @@ export interface SideNavItemProps extends BaseComponentProps {
  * />
  * ```
  */
-export declare const SideNavItem: React.ForwardRefExoticComponent<SideNavItemProps & React.RefAttributes<HTMLElement>>;
+export declare const SideNavItem: ({ ref, value, icon, label, tooltip, disabled, href, onClick, badge, endAdornment, level, className, "data-testid": testId, style, ...restProps }: SideNavItemProps & {
+    ref?: React.Ref<HTMLElement>;
+}) => import("react/jsx-runtime").JSX.Element;
 export default SideNavItem;

package/lib/components/navigation/Stepper/Step.d.ts

@@ -53,5 +53,7 @@ export interface StepProps extends BaseComponentProps {
  * <Step title="Payment" error errorMessage="Please fix payment details" />
  * ```
  */
-export declare const Step: React.ForwardRefExoticComponent<StepProps & React.RefAttributes<HTMLDivElement>>;
+export declare const Step: ({ ref, title, description, icon, optional, error, errorMessage, children, className, "data-testid": testId, style, _stepIndex, ...restProps }: StepProps & {
+    ref?: React.Ref<HTMLDivElement>;
+}) => import("react/jsx-runtime").JSX.Element;
 export default Step;

package/lib/components/navigation/Stepper/Stepper.d.ts

@@ -76,5 +76,7 @@ export interface StepperProps extends BaseComponentProps {
  * </Stepper>
  * ```
  */
-export declare const Stepper: React.ForwardRefExoticComponent<StepperProps & React.RefAttributes<HTMLDivElement>>;
+export declare const Stepper: ({ ref, currentStep, onStepChange, orientation, variant, size, allowStepClick, onlyPreviousClickable, completedSteps, children, className, "data-testid": testId, "aria-label": ariaLabel, style, ...restProps }: StepperProps & {
+    ref?: React.Ref<HTMLDivElement>;
+}) => import("react/jsx-runtime").JSX.Element;
 export default Stepper;

package/lib/components/overlays/Alert/Alert.d.ts

@@ -98,5 +98,7 @@ export interface AlertProps extends Omit<DialogProps, 'actions' | 'renderHeader'
  * />
  * ```
  */
-export declare const Alert: React.ForwardRefExoticComponent<AlertProps & React.RefAttributes<HTMLDivElement>>;
+export declare const Alert: ({ ref, variant, icon, hideIcon, title, description, children, confirmText, cancelText, onConfirm, onCancel, loading, confirmDisabled, confirmVariant, extraActions, size, showCancel, onClose, className, "data-testid": testId, ...restProps }: AlertProps & {
+    ref?: React.Ref<HTMLDivElement>;
+}) => import("react/jsx-runtime").JSX.Element;
 export default Alert;

package/lib/components/overlays/Alert/AlertProvider.d.ts

@@ -34,7 +34,4 @@ export interface AlertProviderProps {
  * };
  * ```
  */
-export declare function AlertProvider({ children, defaultAlertProps, }: AlertProviderProps): import("react/jsx-runtime").JSX.Element;
-export declare namespace AlertProvider {
-    var displayName: string;
-}
+export declare function AlertProvider({ children, defaultAlertProps }: AlertProviderProps): import("react/jsx-runtime").JSX.Element;

package/lib/components/overlays/Alert/index.d.ts

@@ -5,7 +5,7 @@ export { Alert } from './Alert';
 export type { AlertProps } from './Alert';
 export { AlertProvider } from './AlertProvider';
 export type { AlertProviderProps } from './AlertProvider';
-export { AlertContext, useAlertContext, useAlertContextStrict, } from './AlertContext';
-export type { AlertContextValue, AlertQueueItem, } from './AlertContext';
-export { ALERT_PRESETS, getAlertPreset, } from './AlertPresets';
-export type { AlertVariant, AlertPreset, } from './AlertPresets';
+export { AlertContext, useAlertContext, useAlertContextStrict } from './AlertContext';
+export type { AlertContextValue, AlertQueueItem } from './AlertContext';
+export { ALERT_PRESETS, getAlertPreset } from './AlertPresets';
+export type { AlertVariant, AlertPreset } from './AlertPresets';

package/lib/components/overlays/Dialog/Dialog.d.ts

@@ -193,5 +193,7 @@ export declare const DialogFooter: React.FC<DialogFooterProps>;
  * Dialog component
  * Modal dialog for user interactions with customizable content
  */
-export declare const Dialog: React.ForwardRefExoticComponent<DialogProps & React.RefAttributes<HTMLDivElement>>;
+export declare const Dialog: ({ ref, isOpen: controlledIsOpen, defaultOpen, onOpenChange, onClose, title, children, actions, size, width, maxHeight, closeOnBackdropClick, closeOnEscape, showCloseButton, trapFocus, blockScroll, blurBackdrop, backdropOpacity, zIndex, animationDuration, role, "aria-labelledby": ariaLabelledby, "aria-describedby": ariaDescribedby, modal, renderHeader, renderFooter, backdropClassName, contentClassName, onOpenComplete, onCloseComplete, className, "data-testid": testId, style: customStyle, ...restProps }: DialogProps & {
+    ref?: React.Ref<HTMLDivElement>;
+}) => import("react/jsx-runtime").JSX.Element | null;
 export default Dialog;

package/lib/components/overlays/Dialog/DialogProvider.d.ts

@@ -24,7 +24,4 @@ export interface DialogProviderProps {
  * </DialogProvider>
  * ```
  */
-export declare function DialogProvider({ children, defaultDialogProps, }: DialogProviderProps): import("react/jsx-runtime").JSX.Element;
-export declare namespace DialogProvider {
-    var displayName: string;
-}
+export declare function DialogProvider({ children, defaultDialogProps }: DialogProviderProps): import("react/jsx-runtime").JSX.Element;

package/lib/components/overlays/Dialog/index.d.ts

@@ -1,9 +1,9 @@
 /**
  * Dialog component exports
  */
-export { Dialog, DialogHeader, DialogBody, DialogFooter, } from './Dialog';
+export { Dialog, DialogHeader, DialogBody, DialogFooter } from './Dialog';
 export type { DialogProps, DialogSize, DialogHeaderProps, DialogBodyProps, DialogFooterProps, } from './Dialog';
 export { DialogProvider } from './DialogProvider';
 export type { DialogProviderProps } from './DialogProvider';
-export { DialogContext, useDialogContext, useDialogContextStrict, } from './DialogContext';
-export type { DialogContextValue, DialogStackItem, } from './DialogContext';
+export { DialogContext, useDialogContext, useDialogContextStrict } from './DialogContext';
+export type { DialogContextValue, DialogStackItem } from './DialogContext';

package/lib/components/overlays/LoadingOverlay/LoadingOverlay.d.ts

@@ -97,5 +97,7 @@ export interface LoadingOverlayProps extends BaseComponentProps {
  * </LoadingOverlay>
  * ```
  */
-export declare const LoadingOverlay: React.ForwardRefExoticComponent<LoadingOverlayProps & React.RefAttributes<HTMLDivElement>>;
+export declare const LoadingOverlay: ({ ref, children, visible, mode, spinnerStyle, spinnerSize, spinnerVariant, spinnerSpeed, message, blur, backdropOpacity, zIndex, transitionDuration, customSpinner, borderRadius, className, "data-testid": testId, style, ...restProps }: LoadingOverlayProps & {
+    ref?: React.Ref<HTMLDivElement>;
+}) => import("react/jsx-runtime").JSX.Element | null;
 export default LoadingOverlay;

package/lib/components/overlays/Popover/Popover.d.ts

@@ -47,7 +47,7 @@ export interface PopoverProps extends Omit<BaseComponentProps, 'children'> {
      * Trigger element (render prop or ReactNode)
      */
     trigger: ReactNode | ((props: {
-        ref: RefObject<HTMLElement>;
+        ref: RefObject<HTMLElement | null>;
     }) => ReactNode);
     /**
      * Popover content

package/lib/components/overlays/Toast/ToastProvider.d.ts

@@ -66,6 +66,3 @@ export interface ToastProviderProps {
  * ```
  */
 export declare function ToastProvider({ children, position, maxVisible, gap, offset, defaultDuration, animationDuration, defaultToastProps, zIndex, }: ToastProviderProps): import("react/jsx-runtime").JSX.Element;
-export declare namespace ToastProvider {
-    var displayName: string;
-}

package/lib/components/overlays/Toast/index.d.ts

@@ -2,10 +2,10 @@
  * Toast component exports
  */
 export { Toast } from './Toast';
-export type { ToastProps, ToastPosition, ToastVariant, ToastAnimationState, } from './Toast';
+export type { ToastProps, ToastPosition, ToastVariant, ToastAnimationState } from './Toast';
 export { ToastContainer } from './ToastContainer';
 export type { ToastContainerProps } from './ToastContainer';
 export { ToastProvider } from './ToastProvider';
 export type { ToastProviderProps } from './ToastProvider';
-export { ToastContext, useToastContext, useToastContextStrict, } from './ToastContext';
+export { ToastContext, useToastContext, useToastContextStrict } from './ToastContext';
 export type { ToastContextValue, ToastData, ToastInstance, PromiseToastOptions, } from './ToastContext';

package/lib/decorators/ComponentDecorator/ComponentDecorator.d.ts

@@ -1,4 +1,4 @@
-import { default as React } from 'react';
+import { default as React, JSX } from 'react';
 import { CSSVariables } from '../../types';
 export interface ComponentDecoratorProps {
     /**
@@ -53,5 +53,10 @@ export interface ComponentDecoratorProps {
  * );
  * ```
  */
-export declare function withComponentDecorator<P extends object>(Component: React.ComponentType<P>, componentName: string, defaultClassName?: string): React.ForwardRefExoticComponent<React.PropsWithoutRef<P & Omit<ComponentDecoratorProps, "componentName">> & React.RefAttributes<HTMLDivElement>>;
+export declare function withComponentDecorator<P extends object>(Component: React.ComponentType<P>, componentName: string, defaultClassName?: string): {
+    ({ ref, ...props }: P & Omit<ComponentDecoratorProps, "componentName"> & {
+        ref?: React.Ref<HTMLDivElement>;
+    }): import("react/jsx-runtime").JSX.Element;
+    displayName: string;
+};
 export default withComponentDecorator;

package/lib/hooks/index.d.ts

@@ -5,7 +5,7 @@ export { useClickOutside } from './useClickOutside';
 export { useEscapeKey } from './useEscapeKey';
 export { useFocusTrap } from './useFocusTrap';
 export { usePopoverPosition } from './usePopoverPosition';
-export type { UsePopoverPositionOptions, UsePopoverPositionReturn, } from './usePopoverPosition';
+export type { UsePopoverPositionOptions, UsePopoverPositionReturn } from './usePopoverPosition';
 export { useHover } from './useHover';
 export type { UseHoverOptions, UseHoverReturn, HoverProps } from './useHover';
 export { useDebounce } from './useDebounce';
@@ -19,3 +19,18 @@ export { useAsyncToast } from './useAsyncToast';
 export type { UseAsyncToastReturn, AsyncToastConfig } from './useAsyncToast';
 export { useResizeObserver } from './useResizeObserver';
 export type { UseResizeObserverOptions, UseResizeObserverReturn } from './useResizeObserver';
+export { useUrlState, urlStateSerializers } from './useUrlState';
+export type { UseUrlStateOptions, UseUrlStateReturn, UrlStateSerializer } from './useUrlState';
+export { useIntersectionObserver } from './useIntersectionObserver';
+export type { UseIntersectionObserverOptions, UseIntersectionObserverReturn, } from './useIntersectionObserver';
+export { useLocalStorage } from './useLocalStorage';
+export type { UseLocalStorageOptions, UseLocalStorageReturn, LocalStorageSerializer, } from './useLocalStorage';
+export { useMediaQuery } from './useMediaQuery';
+export type { UseMediaQueryOptions, UseMediaQueryReturn } from './useMediaQuery';
+export { usePrevious } from './usePrevious';
+export { useClipboard } from './useClipboard';
+export type { UseClipboardOptions, UseClipboardReturn } from './useClipboard';
+export { useTimeout } from './useTimeout';
+export type { UseTimeoutOptions, UseTimeoutReturn } from './useTimeout';
+export { useInterval } from './useInterval';
+export type { UseIntervalOptions, UseIntervalReturn } from './useInterval';

package/lib/hooks/useClickOutside/useClickOutside.d.ts

@@ -6,4 +6,4 @@ import { RefObject } from 'react';
  * @param enabled - Whether the hook is active
  * @param excludeRefs - Additional refs to exclude from outside click detection (e.g., trigger elements)
  */
-export declare function useClickOutside<T extends HTMLElement>(ref: RefObject<T>, handler: (event: MouseEvent | TouchEvent) => void, enabled?: boolean, excludeRefs?: Array<RefObject<HTMLElement>>): void;
+export declare function useClickOutside<T extends HTMLElement>(ref: RefObject<T | null>, handler: (event: MouseEvent | TouchEvent) => void, enabled?: boolean, excludeRefs?: Array<RefObject<HTMLElement | null>>): void;

package/lib/hooks/useClipboard/index.d.ts

@@ -0,0 +1,2 @@
+export { useClipboard, default } from './useClipboard';
+export type { UseClipboardOptions, UseClipboardReturn } from './useClipboard';

package/lib/hooks/useClipboard/useClipboard.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Options for clipboard hook
+ */
+export interface UseClipboardOptions {
+    /**
+     * Duration to show success state (ms)
+     * @default 2000
+     */
+    successDuration?: number;
+    /**
+     * Callback on successful copy
+     */
+    onSuccess?: (text: string) => void;
+    /**
+     * Callback on copy error
+     */
+    onError?: (error: Error) => void;
+}
+/**
+ * Return type for clipboard hook
+ */
+export interface UseClipboardReturn {
+    /**
+     * Copy text to clipboard
+     */
+    copy: (text: string) => Promise<boolean>;
+    /**
+     * Whether copy was recently successful
+     */
+    copied: boolean;
+    /**
+     * Error if copy failed
+     */
+    error: Error | null;
+    /**
+     * Reset copied state
+     */
+    reset: () => void;
+}
+/**
+ * Hook for copying text to clipboard with feedback
+ *
+ * @example
+ * ```tsx
+ * function CopyButton({ text }: { text: string }) {
+ *   const { copy, copied } = useClipboard();
+ *
+ *   return (
+ *     <Button onClick={() => copy(text)}>
+ *       {copied ? 'Copied!' : 'Copy'}
+ *     </Button>
+ *   );
+ * }
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // With callbacks
+ * const { copy, copied, error } = useClipboard({
+ *   successDuration: 3000,
+ *   onSuccess: () => toast.success('Copied!'),
+ *   onError: (err) => toast.error(err.message),
+ * });
+ * ```
+ */
+export declare function useClipboard(options?: UseClipboardOptions): UseClipboardReturn;
+export default useClipboard;

package/lib/hooks/useFocusTrap/useFocusTrap.d.ts

@@ -5,4 +5,4 @@ import { RefObject } from 'react';
  * @param enabled - Whether the focus trap is active
  * @param autoFocus - Whether to automatically focus the first element on mount
  */
-export declare function useFocusTrap<T extends HTMLElement>(ref: RefObject<T>, enabled?: boolean, autoFocus?: boolean): void;
+export declare function useFocusTrap<T extends HTMLElement>(ref: RefObject<T | null>, enabled?: boolean, autoFocus?: boolean): void;

package/lib/hooks/useIntersectionObserver/index.d.ts

@@ -0,0 +1,2 @@
+export { useIntersectionObserver, default } from './useIntersectionObserver';
+export type { UseIntersectionObserverOptions, UseIntersectionObserverReturn, } from './useIntersectionObserver';

package/lib/hooks/useIntersectionObserver/useIntersectionObserver.d.ts

@@ -0,0 +1,103 @@
+/**
+ * Options for intersection observer hook
+ */
+export interface UseIntersectionObserverOptions {
+    /**
+     * Element that is used as the viewport for checking visibility
+     * @default null (browser viewport)
+     */
+    root?: Element | null;
+    /**
+     * Margin around the root element
+     * @default '0px'
+     */
+    rootMargin?: string;
+    /**
+     * Threshold(s) at which to trigger callback (0-1)
+     * @default 0
+     */
+    threshold?: number | number[];
+    /**
+     * Callback when intersection changes
+     */
+    onChange?: (entry: IntersectionObserverEntry) => void;
+    /**
+     * Whether to disconnect after first intersection
+     * Useful for lazy loading
+     * @default false
+     */
+    triggerOnce?: boolean;
+    /**
+     * Whether the observer is disabled
+     * @default false
+     */
+    disabled?: boolean;
+    /**
+     * Initial value for isIntersecting before observation starts
+     * @default false
+     */
+    initialIsIntersecting?: boolean;
+}
+/**
+ * Return type for intersection observer hook
+ */
+export interface UseIntersectionObserverReturn {
+    /**
+     * Ref callback to attach to observed element
+     */
+    ref: (node: Element | null) => void;
+    /**
+     * Whether element is currently intersecting
+     */
+    isIntersecting: boolean;
+    /**
+     * The full IntersectionObserverEntry (null before first observation)
+     */
+    entry: IntersectionObserverEntry | null;
+    /**
+     * The observed element
+     */
+    element: Element | null;
+}
+/**
+ * Hook that observes element intersection using IntersectionObserver
+ *
+ * @example
+ * ```tsx
+ * // Basic visibility detection
+ * const { ref, isIntersecting } = useIntersectionObserver();
+ *
+ * return (
+ *   <div ref={ref}>
+ *     {isIntersecting ? 'Visible!' : 'Not visible'}
+ *   </div>
+ * );
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Lazy loading with triggerOnce
+ * const { ref, isIntersecting } = useIntersectionObserver({
+ *   triggerOnce: true,
+ *   rootMargin: '100px',
+ * });
+ *
+ * return (
+ *   <div ref={ref}>
+ *     {isIntersecting ? <img src={src} /> : <Skeleton />}
+ *   </div>
+ * );
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Multiple thresholds for scroll animations
+ * const { ref, entry } = useIntersectionObserver({
+ *   threshold: [0, 0.25, 0.5, 0.75, 1],
+ * });
+ *
+ * const opacity = entry?.intersectionRatio ?? 0;
+ * ```
+ */
+export declare function useIntersectionObserver(options?: UseIntersectionObserverOptions): UseIntersectionObserverReturn;
+export default useIntersectionObserver;

package/lib/hooks/useInterval/index.d.ts

@@ -0,0 +1,2 @@
+export { useInterval, default } from './useInterval';
+export type { UseIntervalOptions, UseIntervalReturn } from './useInterval';

package/lib/hooks/useInterval/useInterval.d.ts

@@ -0,0 +1,82 @@
+/**
+ * Options for interval hook
+ */
+export interface UseIntervalOptions {
+    /**
+     * Callback to execute on each interval
+     */
+    callback: () => void;
+    /**
+     * Interval in milliseconds (null to pause/disable)
+     */
+    delay: number | null;
+    /**
+     * Whether to run callback immediately on start
+     * @default false
+     */
+    immediate?: boolean;
+}
+/**
+ * Return type for interval hook
+ */
+export interface UseIntervalReturn {
+    /**
+     * Reset the interval (restart timing)
+     */
+    reset: () => void;
+    /**
+     * Clear the interval (stop)
+     */
+    clear: () => void;
+}
+/**
+ * Declarative interval hook with cleanup
+ *
+ * @example
+ * ```tsx
+ * // Auto-refresh data
+ * function Dashboard() {
+ *   const [data, setData] = useState(null);
+ *
+ *   useInterval({
+ *     callback: async () => {
+ *       const fresh = await fetchData();
+ *       setData(fresh);
+ *     },
+ *     delay: 30000, // Every 30 seconds
+ *     immediate: true, // Fetch immediately on mount
+ *   });
+ *
+ *   return <DataDisplay data={data} />;
+ * }
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Countdown timer
+ * function Countdown({ seconds }: { seconds: number }) {
+ *   const [remaining, setRemaining] = useState(seconds);
+ *
+ *   useInterval({
+ *     callback: () => setRemaining(r => r - 1),
+ *     delay: remaining > 0 ? 1000 : null, // Stop at 0
+ *   });
+ *
+ *   return <span>{remaining}s</span>;
+ * }
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Pausable animation
+ * const [isPaused, setIsPaused] = useState(false);
+ * const [frame, setFrame] = useState(0);
+ *
+ * const { reset } = useInterval({
+ *   callback: () => setFrame(f => f + 1),
+ *   delay: isPaused ? null : 16, // ~60fps when not paused
+ * });
+ * ```
+ */
+export declare function useInterval(options: UseIntervalOptions): UseIntervalReturn;
+export default useInterval;

package/lib/hooks/useLocalStorage/index.d.ts

@@ -0,0 +1,2 @@
+export { useLocalStorage, default } from './useLocalStorage';
+export type { UseLocalStorageOptions, UseLocalStorageReturn, LocalStorageSerializer, } from './useLocalStorage';

package/lib/hooks/useLocalStorage/useLocalStorage.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Serializer for localStorage values
+ */
+export interface LocalStorageSerializer<T> {
+    /**
+     * Serialize value to string
+     */
+    serialize: (value: T) => string;
+    /**
+     * Deserialize string to value
+     */
+    deserialize: (value: string) => T;
+}
+/**
+ * Options for localStorage hook
+ */
+export interface UseLocalStorageOptions<T> {
+    /**
+     * Custom serializer/deserializer
+     * @default JSON.stringify/parse
+     */
+    serializer?: LocalStorageSerializer<T>;
+    /**
+     * Sync value across browser tabs
+     * @default true
+     */
+    syncTabs?: boolean;
+}
+/**
+ * Return type for localStorage hook
+ */
+export type UseLocalStorageReturn<T> = [
+    /** Current value */
+    T,
+    /** Setter function (like useState) */
+    (value: T | ((prev: T) => T)) => void,
+    /** Remove from localStorage */
+    () => void
+];
+/**
+ * Hook that persists state to localStorage with cross-tab synchronization
+ *
+ * @example
+ * ```tsx
+ * // Basic usage
+ * const [theme, setTheme] = useLocalStorage('theme', 'light');
+ *
+ * // With object
+ * const [user, setUser, clearUser] = useLocalStorage<User | null>('user', null);
+ *
+ * // Disable cross-tab sync
+ * const [draft, setDraft] = useLocalStorage('draft', '', { syncTabs: false });
+ * ```
+ */
+export declare function useLocalStorage<T>(key: string, defaultValue: T, options?: UseLocalStorageOptions<T>): UseLocalStorageReturn<T>;
+export default useLocalStorage;

package/lib/hooks/useMediaQuery/index.d.ts

@@ -0,0 +1,2 @@
+export { useMediaQuery, default } from './useMediaQuery';
+export type { UseMediaQueryOptions, UseMediaQueryReturn } from './useMediaQuery';