@pelatform/starter.ui 0.1.0

package/dist/hooks.d.ts

@@ -0,0 +1,1063 @@
+import * as React from 'react';
+import React__default, { DragEvent, ChangeEvent, InputHTMLAttributes, ComponentType, SVGProps, RefObject } from 'react';
+import { META_THEME_COLORS } from '@pelatform/utils';
+
+/**
+ * Body class management hook for React components
+ * Dynamically adds and removes CSS classes from the document body element
+ * Useful for global styling based on component state or route changes
+ */
+/**
+ * Hook to dynamically add and remove CSS classes from the document body
+ *
+ * This hook automatically manages the lifecycle of body classes:
+ * - Adds classes when the component mounts
+ * - Removes classes when the component unmounts
+ * - Updates classes when the className prop changes
+ *
+ * @param className - Space-separated string of CSS class names to apply to body
+ *
+ * @example
+ * ```tsx
+ * // Single class
+ * useBodyClasses('dark-theme');
+ *
+ * // Multiple classes
+ * useBodyClasses('modal-open overflow-hidden');
+ *
+ * // Conditional classes
+ * useBodyClasses(isModalOpen ? 'modal-open' : '');
+ * ```
+ */
+declare const useBodyClasses: (className: string) => void;
+
+/**
+ * Clipboard copy functionality hook for React components
+ * Provides a simple interface for copying text to clipboard with feedback
+ * Includes automatic state management and timeout handling
+ */
+/**
+ * Configuration options for the copy to clipboard hook
+ */
+interface UseCopyToClipboardOptions {
+    /** Duration in milliseconds to show the copied state (default: 2000ms) */
+    timeout?: number;
+    /** Callback function executed after successful copy operation */
+    onCopy?: () => void;
+}
+/**
+ * Hook for copying text to clipboard with automatic state management
+ *
+ * Features:
+ * - Automatic copied state management with timeout
+ * - Browser compatibility checks
+ * - Error handling for failed copy operations
+ * - Optional callback for successful copies
+ *
+ * @param options - Configuration options for the hook
+ * @returns Object containing copied state and copy function
+ *
+ * @example
+ * ```tsx
+ * const { copied, copy } = useCopyToClipboard({
+ *   timeout: 3000,
+ *   onCopy: () => toast.success('Copied to clipboard!')
+ * });
+ *
+ * return (
+ *   <button onClick={() => copy('Hello World')}>
+ *     {copied ? 'Copied!' : 'Copy Text'}
+ *   </button>
+ * );
+ * ```
+ */
+declare function useCopyToClipboard({ timeout, onCopy }?: UseCopyToClipboardOptions): {
+    /** Whether text was recently copied (true for timeout duration) */
+    copied: boolean;
+    /** Function to copy text to clipboard */
+    copy: (value: string) => void;
+};
+
+/**
+ * File upload functionality hook for React components
+ * Provides comprehensive file upload capabilities with drag & drop support
+ * Includes validation, preview generation, and state management
+ */
+
+/**
+ * Metadata structure for uploaded files
+ */
+type FileMetadata = {
+    /** The name of the file */
+    name: string;
+    /** The size of the file in bytes */
+    size: number;
+    /** The MIME type of the file */
+    type: string;
+    /** The URL where the file can be accessed */
+    url: string;
+    /** Unique identifier for the file */
+    id: string;
+};
+/**
+ * File object with preview capabilities
+ */
+type FileWithPreview = {
+    /** The actual file object or metadata */
+    file: File | FileMetadata;
+    /** Unique identifier for the file */
+    id: string;
+    /** Optional preview URL for the file (typically for images) */
+    preview?: string;
+};
+/**
+ * Configuration options for the file upload hook
+ */
+type FileUploadOptions = {
+    /** Maximum number of files allowed (only used when multiple is true, defaults to Infinity) */
+    maxFiles?: number;
+    /** Maximum file size in bytes (defaults to Infinity) */
+    maxSize?: number;
+    /** Accepted file types (MIME types or extensions, defaults to '*') */
+    accept?: string;
+    /** Whether multiple files can be selected (defaults to false) */
+    multiple?: boolean;
+    /** Initial files to populate the upload state */
+    initialFiles?: FileMetadata[];
+    /** Callback function executed when files change */
+    onFilesChange?: (files: FileWithPreview[]) => void;
+    /** Callback function executed when new files are added */
+    onFilesAdded?: (addedFiles: FileWithPreview[]) => void;
+    onError?: (errors: string[]) => void;
+};
+/**
+ * Current state of the file upload component
+ */
+type FileUploadState = {
+    /** Array of files currently selected/uploaded */
+    files: FileWithPreview[];
+    /** Whether the user is currently dragging files over the drop zone */
+    isDragging: boolean;
+    /** Array of validation error messages */
+    errors: string[];
+};
+/**
+ * Actions available for file upload management
+ */
+type FileUploadActions = {
+    /** Add new files to the upload state */
+    addFiles: (files: FileList | File[]) => void;
+    /** Remove a specific file by its ID */
+    removeFile: (id: string) => void;
+    /** Clear all files from the upload state */
+    clearFiles: () => void;
+    /** Clear all error messages */
+    clearErrors: () => void;
+    /** Handle drag enter event for drop zone */
+    handleDragEnter: (e: DragEvent<HTMLElement>) => void;
+    /** Handle drag leave event for drop zone */
+    handleDragLeave: (e: DragEvent<HTMLElement>) => void;
+    /** Handle drag over event for drop zone */
+    handleDragOver: (e: DragEvent<HTMLElement>) => void;
+    /** Handle drop event for drop zone */
+    handleDrop: (e: DragEvent<HTMLElement>) => void;
+    /** Handle file input change event */
+    handleFileChange: (e: ChangeEvent<HTMLInputElement>) => void;
+    /** Programmatically open the file dialog */
+    openFileDialog: () => void;
+    /** Get props for the file input element */
+    getInputProps: (props?: InputHTMLAttributes<HTMLInputElement>) => InputHTMLAttributes<HTMLInputElement> & {
+        ref: React__default.Ref<HTMLInputElement>;
+    };
+};
+/**
+ * Hook for comprehensive file upload functionality with drag & drop support
+ *
+ * Features:
+ * - Single and multiple file upload support
+ * - Drag and drop functionality
+ * - File validation (size, type, count)
+ * - Preview generation for images
+ * - Error handling and state management
+ * - Duplicate file detection
+ * - Memory cleanup for object URLs
+ *
+ * @param options - Configuration options for the file upload hook
+ * @returns Tuple containing current state and available actions
+ *
+ * @example
+ * ```tsx
+ * const [state, actions] = useFileUpload({
+ *   maxFiles: 5,
+ *   maxSize: 10 * 1024 * 1024, // 10MB
+ *   accept: 'image/*',
+ *   multiple: true,
+ *   onFilesChange: (files) => console.log('Files changed:', files),
+ *   onFilesAdded: (newFiles) => console.log('New files added:', newFiles)
+ * });
+ *
+ * return (
+ *   <div
+ *     onDragEnter={actions.handleDragEnter}
+ *     onDragLeave={actions.handleDragLeave}
+ *     onDragOver={actions.handleDragOver}
+ *     onDrop={actions.handleDrop}
+ *   >
+ *     <input {...actions.getInputProps()} />
+ *     <button onClick={actions.openFileDialog}>
+ *       Upload Files
+ *     </button>
+ *     {state.files.map(file => (
+ *       <div key={file.id}>
+ *         {file.file.name}
+ *         <button onClick={() => actions.removeFile(file.id)}>
+ *           Remove
+ *         </button>
+ *       </div>
+ *     ))}
+ *   </div>
+ * );
+ * ```
+ */
+declare const useFileUpload: (options?: FileUploadOptions) => [FileUploadState, FileUploadActions];
+/**
+ * Helper function to format bytes to human-readable format
+ *
+ * @param bytes - The number of bytes to format
+ * @param decimals - Number of decimal places to show (default: 2)
+ * @returns Formatted string with appropriate unit (e.g., "1.5 MB")
+ *
+ * @example
+ * ```tsx
+ * formatBytes(1024); // "1 KB"
+ * formatBytes(1536, 1); // "1.5 KB"
+ * formatBytes(1048576); // "1 MB"
+ * ```
+ */
+declare const formatBytes: (bytes: number, decimals?: number) => string;
+
+/**
+ * Hook that indicates whether code is executing on the client after hydration
+ *
+ * Features:
+ * - SSR-safe: returns `false` on the server to avoid hydration mismatches
+ * - Client-stable: returns `true` after hydration and remains stable
+ * - Minimal overhead: uses a no-op external store subscription
+ *
+ * @returns Boolean indicating hydration state (`true` on client, `false` on server)
+ *
+ * @example
+ * ```tsx
+ * // Conditionally render client-only components safely
+ * function ClientOnly() {
+ *   const hydrated = useHydrated();
+ *   if (!hydrated) return null;
+ *   return <InteractiveChart />;
+ * }
+ * ```
+ *
+ * @since 1.0.0
+ */
+declare function useHydrated(): boolean;
+
+/**
+ * Intersection observer hook for React components
+ * Efficiently observes visibility of DOM elements using a shared IntersectionObserver instance.
+ * Ideal for lazy loading, infinite scrolling, and animating elements when they enter the viewport.
+ */
+
+/**
+ * Configuration options for the `useIntersectionObserver` hook.
+ *
+ * Extends the native `IntersectionObserverInit` options with an additional
+ * convenience flag for freezing the observer state.
+ */
+interface IntersectionObserverOptions extends IntersectionObserverInit {
+    /**
+     * When `true`, the hook stops observing once the element becomes visible
+     * and keeps returning `true` for subsequent renders.
+     *
+     * This is useful for one-time animations or lazy loading where you only
+     * care about the first time an element enters the viewport.
+     */
+    freezeOnceVisible?: boolean;
+}
+/**
+ * React hook that tracks whether a DOM element is currently intersecting the viewport.
+ *
+ * Features:
+ * - Uses a shared `IntersectionObserver` instance for better performance.
+ * - Supports custom `threshold`, `root`, and `rootMargin` options.
+ * - Optional `freezeOnceVisible` flag to stop observing after first intersection.
+ *
+ * @param elementRef - React ref pointing to the DOM element to observe.
+ * @param options - Optional observer configuration and behavior flags.
+ * @param options.threshold - Intersection threshold(s) for triggering visibility changes.
+ * @param options.root - Scrollable ancestor element to use as the viewport (defaults to browser viewport).
+ * @param options.rootMargin - Margin around the root, expressed in CSS units (e.g. `"0px 0px -20% 0px"`).
+ * @param options.freezeOnceVisible - When `true`, stops observing after the element first becomes visible.
+ *
+ * @returns `true` when the element is intersecting based on the given options, otherwise `false`.
+ *
+ * @example
+ * ```tsx
+ * const ref = React.useRef<HTMLDivElement | null>(null);
+ * const isVisible = useIntersectionObserver(ref, {
+ *   threshold: 0.2,
+ *   rootMargin: "0px 0px -10% 0px",
+ *   freezeOnceVisible: true,
+ * });
+ *
+ * return (
+ *   <div ref={ref} className={isVisible ? "animate-in" : "opacity-0"}>
+ *     I will animate when I enter the viewport.
+ *   </div>
+ * );
+ * ```
+ */
+declare function useIntersectionObserver(elementRef: React.RefObject<Element | null>, { threshold, root, rootMargin, freezeOnceVisible, }?: IntersectionObserverOptions): boolean;
+
+/**
+ * Platform detection hook for React components
+ * Determines whether the current user agent is running on a macOS device.
+ * Useful for rendering platform-specific keyboard shortcuts or UI variations.
+ */
+/**
+ * React hook that returns whether the current platform is macOS.
+ *
+ * This hook:
+ * - Runs only on the client (browser) side.
+ * - Checks `navigator.platform` and normalizes the value to uppercase.
+ * - Returns a boolean indicating if the platform contains `"MAC"`.
+ *
+ * @returns `true` if the current platform is macOS, otherwise `false`.
+ *
+ * @example
+ * ```tsx
+ * const isMac = useIsMac();
+ *
+ * return (
+ *   <kbd>
+ *     {isMac ? "⌘" : "Ctrl"} + K
+ *   </kbd>
+ * );
+ * ```
+ */
+declare function useIsMac(): boolean;
+
+/**
+ * Media query hook for responsive React components
+ * Provides real-time tracking of CSS media query matches
+ * with SSR-safe implementation and automatic cleanup
+ */
+/**
+ * Hook for tracking CSS media query matches in React components
+ *
+ * Features:
+ * - Real-time updates when media query state changes
+ * - SSR-safe implementation
+ * - Automatic event listener cleanup
+ * - Supports all standard CSS media queries
+ *
+ * @param query - CSS media query string (e.g., '(min-width: 768px)')
+ * @returns Boolean indicating whether the media query currently matches
+ *
+ * @example
+ * ```tsx
+ * // Basic responsive behavior
+ * const isMobile = useMediaQuery('(max-width: 768px)');
+ * const isTablet = useMediaQuery('(min-width: 769px) and (max-width: 1024px)');
+ * const isDesktop = useMediaQuery('(min-width: 1025px)');
+ *
+ * // Dark mode preference
+ * const prefersDark = useMediaQuery('(prefers-color-scheme: dark)');
+ *
+ * // Reduced motion preference
+ * const prefersReducedMotion = useMediaQuery('(prefers-reduced-motion: reduce)');
+ *
+ * return (
+ *   <div>
+ *     {isMobile && <MobileLayout />}
+ *     {isTablet && <TabletLayout />}
+ *     {isDesktop && <DesktopLayout />}
+ *   </div>
+ * );
+ * ```
+ */
+declare const useMediaQuery: (query: string) => boolean;
+
+/**
+ * Menu navigation utilities hook for dashboard layouts
+ * Provides comprehensive menu state management and navigation helpers
+ * Handles active states, breadcrumbs, and hierarchical menu structures
+ */
+
+/**
+ * Menu item interface
+ */
+interface MenuItem {
+    /** Heading text */
+    heading?: string;
+    /** Menu item title */
+    title?: string;
+    /** Navigation path */
+    path?: string;
+    /** Menu item icon component */
+    icon?: ComponentType<SVGProps<SVGSVGElement>>;
+    /** Whether to show separator */
+    separator?: boolean;
+    /** Root path for active state matching */
+    rootPath?: string;
+    /** Child menu items */
+    children?: MenuConfig;
+    /** Children index for nested items */
+    childrenIndex?: number;
+    /** Whether the item is external */
+    external?: boolean;
+    /** Whether the item is disabled */
+    disabled?: boolean;
+    /** Disable text */
+    disabledText?: string;
+    /** Badge text */
+    badge?: string;
+    /** Badge variant */
+    badgeVariant?: "primary" | "destructive" | "success" | "info" | "warning" | "secondary" | "outline";
+    /** Collapse configuration */
+    collapse?: boolean;
+    /** Title when collapsed */
+    collapseTitle?: string;
+    /** Title when expanded */
+    expandTitle?: string;
+}
+/**
+ * Type aliases for backward compatibility
+ */
+type MenuConfig = MenuItem[];
+/** Return type interface for useMenu hook */
+interface UseMenuReturn {
+    /** Check if a specific path is currently active */
+    isActive: (path: string | undefined) => boolean;
+    /** Check if any child menu item is currently active */
+    hasActiveChild: (children: MenuItem[] | undefined) => boolean;
+    /** Check if a menu item (including its children) is currently active */
+    isItemActive: (item: MenuItem) => boolean;
+    /** Get the currently active menu item from the menu configuration */
+    getCurrentItem: (items: MenuConfig) => MenuItem | undefined;
+    /** Generate breadcrumb trail for the current active path */
+    getBreadcrumb: (items: MenuConfig) => MenuItem[];
+    /** Get child menu items at a specific level for the current active path */
+    getChildren: (items: MenuConfig, level: number) => MenuConfig | null;
+}
+/**
+ * Hook for managing menu navigation state and utilities
+ *
+ * This hook provides comprehensive menu management functionality including:
+ * - Active state detection for menu items and paths
+ * - Hierarchical menu navigation support
+ * - Breadcrumb generation for current navigation path
+ * - Child menu extraction at specific levels
+ * - Support for nested menu structures
+ *
+ * @param pathname - Current pathname from router or location
+ * @returns Object containing menu utility functions
+ *
+ * @example
+ * ```tsx
+ * const { isActive, getBreadcrumb, getCurrentItem } = useMenu(pathname);
+ *
+ * // Check if path is active
+ * const isHomeActive = isActive('/dashboard');
+ *
+ * // Get breadcrumb for current path
+ * const breadcrumb = getBreadcrumb(menuItems);
+ *
+ * // Get current active menu item
+ * const currentItem = getCurrentItem(menuItems);
+ * ```
+ */
+declare const useMenu: (pathname: string) => UseMenuReturn;
+
+/**
+ * Meta theme color management hook for React components
+ * Automatically manages HTML meta theme-color tag based on current theme
+ * Integrates with next-themes for seamless theme switching
+ */
+
+/**
+ * Hook for managing HTML meta theme-color tag based on current theme
+ *
+ * This hook automatically calculates the appropriate meta theme color
+ * based on the current theme (light/dark) and provides utilities for
+ * manual meta color manipulation.
+ *
+ * Features:
+ * - Automatic theme color calculation based on resolved theme
+ * - Support for custom color configurations
+ * - Manual meta color setting capability
+ * - Integration with next-themes
+ *
+ * @param defaultColors - Optional custom color configuration (defaults to META_THEME_COLORS)
+ * @returns Object containing current meta color and setter function
+ *
+ * @example
+ * ```tsx
+ * // Basic usage with default colors (supports light, dark, and system)
+ * function App() {
+ *   const { metaColor, setMetaColor } = useMetaColor();
+ *
+ *   // metaColor automatically updates based on theme (light/dark/system)
+ *   useEffect(() => {
+ *     console.log('Current meta color:', metaColor);
+ *   }, [metaColor]);
+ *
+ *   return <div>App content</div>;
+ * }
+ *
+ * // Custom colors with system theme support
+ * function CustomThemeApp() {
+ *   const customColors = {
+ *     light: '#f0f0f0',
+ *     dark: '#1a1a1a',
+ *     system: 'auto' // Will resolve to light or dark based on OS preference
+ *   };
+ *   const { metaColor } = useMetaColor(customColors);
+ *
+ *   return <div style={{ backgroundColor: metaColor }}>Custom themed app</div>;
+ * }
+ *
+ * // Manual meta color override for special pages
+ * function SpecialPage() {
+ *   const { setMetaColor } = useMetaColor();
+ *
+ *   useEffect(() => {
+ *     // Override meta color for this page
+ *     setMetaColor('#ff0000');
+ *
+ *     // Cleanup: reset to theme color when leaving page
+ *     return () => {
+ *       setMetaColor(''); // This will revert to theme-based color
+ *     };
+ *   }, [setMetaColor]);
+ *
+ *   return <div>Special page with red theme color</div>;
+ * }
+ *
+ * // Integration with theme switcher
+ * function ThemeAwareComponent() {
+ *   const { theme, setTheme } = useTheme();
+ *   const { metaColor } = useMetaColor();
+ *
+ *   return (
+ *     <div>
+ *       <p>Current theme: {theme}</p>
+ *       <p>Meta color: {metaColor}</p>
+ *       <button onClick={() => setTheme('light')}>Light</button>
+ *       <button onClick={() => setTheme('dark')}>Dark</button>
+ *       <button onClick={() => setTheme('system')}>System</button>
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+declare function useMetaColor(defaultColors?: typeof META_THEME_COLORS): {
+    /** Current meta theme color based on resolved theme */
+    metaColor: "#09090b" | "#ffffff";
+    /** Function to manually set meta theme color */
+    setMetaColor: (color: string) => void;
+};
+
+/**
+ * Mobile device detection hook for React components
+ * Provides real-time mobile/desktop state based on configurable viewport width breakpoint
+ * Uses customizable mobile breakpoint with proper SSR handling and hydration safety
+ */
+/**
+ * Hook to detect if the current viewport is mobile-sized based on configurable breakpoint
+ *
+ * This hook provides real-time detection of mobile vs desktop viewports with a customizable
+ * breakpoint threshold. It handles SSR properly by starting with undefined state and updating
+ * on client-side hydration to prevent hydration mismatches.
+ *
+ * The hook uses both `matchMedia` API for efficient media query listening and `window.innerWidth`
+ * for consistent viewport width detection across different browsers and devices.
+ *
+ * Features:
+ * - Real-time viewport size tracking with media query listeners
+ * - SSR-safe implementation preventing hydration mismatches
+ * - Automatic event listener cleanup on unmount
+ * - Configurable mobile breakpoint with sensible default (1024px)
+ * - Performance optimized with proper dependency management
+ * - TypeScript support with proper type definitions
+ *
+ * @param breakpoint - Custom breakpoint in pixels. Viewports smaller than this value are considered mobile. Defaults to 1024px if not provided.
+ * @returns Boolean indicating if current viewport width is smaller than the specified breakpoint (mobile-sized)
+ *
+ * @example
+ * ```tsx
+ * // Basic usage with default breakpoint (1024px)
+ * function ResponsiveComponent() {
+ *   const isMobile = useIsMobile();
+ *
+ *   return (
+ *     <div>
+ *       {isMobile ? (
+ *         <MobileNavigation />
+ *       ) : (
+ *         <DesktopNavigation />
+ *       )}
+ *     </div>
+ *   );
+ * }
+ *
+ * // Custom breakpoint for tablet detection
+ * function TabletResponsiveComponent() {
+ *   const isMobile = useIsMobile(768); // Use 768px breakpoint
+ *   const isTablet = useIsMobile(1024); // Use 1024px for tablet detection
+ *
+ *   return (
+ *     <div className={isMobile ? 'mobile-layout' : isTablet ? 'tablet-layout' : 'desktop-layout'}>
+ *       <Content />
+ *     </div>
+ *   );
+ * }
+ *
+ * // Conditional rendering with custom breakpoint
+ * function AdaptiveLayout() {
+ *   const isSmallScreen = useIsMobile(640); // Custom small screen breakpoint
+ *
+ *   return (
+ *     <div className="container">
+ *       {isSmallScreen ? (
+ *         <div className="flex flex-col space-y-4">
+ *           <MobileHeader />
+ *           <MobileContent />
+ *         </div>
+ *       ) : (
+ *         <div className="grid grid-cols-12 gap-6">
+ *           <aside className="col-span-3">
+ *             <Sidebar />
+ *           </aside>
+ *           <main className="col-span-9">
+ *             <DesktopContent />
+ *           </main>
+ *         </div>
+ *       )}
+ *     </div>
+ *   );
+ * }
+ *
+ * // Multiple breakpoints for different layouts
+ * function MultiBreakpointLayout() {
+ *   const isMobile = useIsMobile(640);   // Mobile: < 640px
+ *   const isTablet = useIsMobile(1024);  // Tablet: < 1024px
+ *   const isDesktop = !isTablet;         // Desktop: >= 1024px
+ *
+ *   if (isMobile) {
+ *     return <MobileLayout />;
+ *   }
+ *
+ *   if (isTablet) {
+ *     return <TabletLayout />;
+ *   }
+ *
+ *   return <DesktopLayout />;
+ * }
+ * ```
+ *
+ * @since 1.0.0
+ */
+declare function useIsMobile(breakpoint?: number): boolean;
+
+/**
+ * Component mount state hook for React components
+ * Provides a reliable way to detect when a component has mounted on the client
+ * Essential for SSR applications to prevent hydration mismatches
+ */
+/**
+ * Hook to detect when a React component has mounted on the client side
+ *
+ * This hook is essential for SSR applications where you need to conditionally
+ * render content only after the component has mounted on the client. It helps
+ * prevent hydration mismatches between server and client rendering.
+ *
+ * Features:
+ * - Starts with false during SSR
+ * - Updates to true after client-side mount
+ * - Prevents hydration mismatches
+ * - Simple boolean state management
+ *
+ * @returns Boolean indicating whether the component has mounted
+ *
+ * @example
+ * ```tsx
+ * function ClientOnlyComponent() {
+ *   const mounted = useMounted();
+ *
+ *   // Prevent rendering until mounted to avoid hydration issues
+ *   if (!mounted) {
+ *     return <div>Loading...</div>;
+ *   }
+ *
+ *   return (
+ *     <div>
+ *       <BrowserOnlyFeature />
+ *       <LocalStorageComponent />
+ *     </div>
+ *   );
+ * }
+ *
+ * // Conditional rendering based on mount state
+ * function ThemeToggle() {
+ *   const mounted = useMounted();
+ *   const { theme, setTheme } = useTheme();
+ *
+ *   // Avoid showing theme toggle until mounted
+ *   if (!mounted) return null;
+ *
+ *   return (
+ *     <button onClick={() => setTheme(theme === 'dark' ? 'light' : 'dark')}>
+ *       Toggle Theme
+ *     </button>
+ *   );
+ * }
+ * ```
+ */
+declare function useMounted(): boolean;
+
+/**
+ * DOM Mutation Observer hook for React components
+ * Provides a React-friendly interface for observing DOM changes
+ * with automatic cleanup and ref integration
+ */
+
+/**
+ * Hook to observe DOM mutations on a referenced element
+ *
+ * This hook provides a React-friendly way to use the MutationObserver API.
+ * It automatically handles observer creation, cleanup, and ref management.
+ * Useful for detecting DOM changes that occur outside of React's control.
+ *
+ * Features:
+ * - Automatic observer lifecycle management
+ * - Configurable observation options
+ * - Ref-based element targeting
+ * - Automatic cleanup on unmount
+ *
+ * @param ref - React ref pointing to the element to observe
+ * @param callback - Function called when mutations are detected
+ * @param options - MutationObserver configuration options
+ *
+ * @example
+ * ```tsx
+ * function DynamicContent() {
+ *   const contentRef = useRef<HTMLDivElement>(null);
+ *
+ *   // Watch for any changes to the content div
+ *   useMutationObserver(
+ *     contentRef,
+ *     (mutations) => {
+ *       mutations.forEach((mutation) => {
+ *         console.log('DOM changed:', mutation.type);
+ *       });
+ *     }
+ *   );
+ *
+ *   return <div ref={contentRef}>Dynamic content here</div>;
+ * }
+ *
+ * // Watch only for attribute changes
+ * function AttributeWatcher() {
+ *   const elementRef = useRef<HTMLElement>(null);
+ *
+ *   useMutationObserver(
+ *     elementRef,
+ *     (mutations) => {
+ *       mutations.forEach((mutation) => {
+ *         if (mutation.type === 'attributes') {
+ *           console.log('Attribute changed:', mutation.attributeName);
+ *         }
+ *       });
+ *     },
+ *     { attributes: true, childList: false, subtree: false }
+ *   );
+ *
+ *   return <div ref={elementRef}>Watched element</div>;
+ * }
+ * ```
+ */
+declare const useMutationObserver: (ref: React.RefObject<HTMLElement | null>, callback: MutationCallback, options?: MutationObserverInit) => void;
+
+/**
+ * Google Analytics linker parameter cleanup hook for React
+ * Safely removes the GA `_gl` query parameter from the URL after GA initialization.
+ */
+/**
+ * Hook to remove the Google Analytics `_gl` query parameter from the current URL.
+ *
+ * GA's cross-domain linker temporarily appends `_gl` to URLs for attribution.
+ * Removing it *too early* can break attribution, so this hook waits briefly
+ * (≈2 seconds) to allow GA to read it, then strips the param using
+ * `history.replaceState` without causing a page reload or React re-render.
+ *
+ * Behavior:
+ * - Runs once on mount.
+ * - If `_gl` is present, schedules its removal after ~2000ms.
+ * - Uses `window.history.replaceState` to avoid navigation/re-render.
+ *
+ * @example
+ * ```tsx
+ * // app/layout.tsx or a top-level client component
+ * import { useRemoveGAParams } from '@/hooks/use-remove-ga-params';
+ *
+ * export default function RootLayout({ children }: { children: React.ReactNode }) {
+ *   useRemoveGAParams();
+ *   return <>{children}</>;
+ * }
+ * ```
+ */
+declare function useRemoveGAParams(): void;
+
+/**
+ * Scroll position tracking hook for React components
+ * Monitors scroll position of window or specific elements
+ * with real-time updates and automatic cleanup
+ */
+
+/**
+ * Configuration options for the scroll position hook
+ */
+interface UseScrollPositionProps {
+    /** Optional ref to a specific scrollable element (defaults to document) */
+    targetRef?: RefObject<HTMLElement | Document | undefined>;
+}
+/**
+ * Hook to track scroll position of window or specific elements
+ *
+ * This hook provides real-time tracking of scroll position with support
+ * for both window scrolling and element-specific scrolling. It automatically
+ * handles event listener management and cleanup.
+ *
+ * Features:
+ * - Real-time scroll position tracking
+ * - Support for window and element scrolling
+ * - Automatic event listener cleanup
+ * - SSR-safe implementation
+ * - Performance optimized
+ *
+ * @param options - Configuration options for the hook
+ * @returns Current scroll position in pixels
+ *
+ * @example
+ * ```tsx
+ * // Track window scroll position
+ * function ScrollIndicator() {
+ *   const scrollPosition = useScrollPosition();
+ *
+ *   return (
+ *     <div className="scroll-indicator">
+ *       Scrolled: {scrollPosition}px
+ *     </div>
+ *   );
+ * }
+ *
+ * // Track specific element scroll position
+ * function ScrollableContent() {
+ *   const contentRef = useRef<HTMLDivElement>(null);
+ *   const scrollPosition = useScrollPosition({ targetRef: contentRef });
+ *
+ *   return (
+ *     <div
+ *       ref={contentRef}
+ *       className="h-96 overflow-y-auto"
+ *     >
+ *       <div className="h-[1000px]">
+ *         <p>Scroll position: {scrollPosition}px</p>
+ *         <p>Long content here...</p>
+ *       </div>
+ *     </div>
+ *   );
+ * }
+ *
+ * // Show/hide header based on scroll
+ * function StickyHeader() {
+ *   const scrollPosition = useScrollPosition();
+ *   const isVisible = scrollPosition < 100;
+ *
+ *   return (
+ *     <header className={`transition-transform ${
+ *       isVisible ? 'translate-y-0' : '-translate-y-full'
+ *     }`}>
+ *       Header content
+ *     </header>
+ *   );
+ * }
+ * ```
+ */
+declare const useScrollPosition: ({ targetRef }?: UseScrollPositionProps) => number;
+
+/**
+ * Dual slider input management hook for React components
+ * Provides synchronized state management between range slider and number inputs
+ * with validation and boundary enforcement
+ */
+
+/**
+ * Configuration options for the slider input hook
+ */
+interface UseSliderInputProps {
+    /** Minimum allowed value for the range */
+    minValue: number;
+    /** Maximum allowed value for the range */
+    maxValue: number;
+    /** Initial values for the range [min, max] */
+    initialValue: [number, number];
+}
+/**
+ * Hook for managing dual slider input with synchronized state
+ *
+ * This hook provides state management for components that need both
+ * a range slider and corresponding number inputs. It handles synchronization
+ * between the two input types, validation, and boundary enforcement.
+ *
+ * Features:
+ * - Synchronized slider and input values
+ * - Automatic validation and boundary enforcement
+ * - Prevents invalid range configurations (min > max)
+ * - Optimized with useCallback for performance
+ *
+ * @param props - Configuration options for the hook
+ * @returns Object containing state and handlers for slider and inputs
+ *
+ * @example
+ * ```tsx
+ * function PriceRangeFilter() {
+ *   const {
+ *     sliderValues,
+ *     inputValues,
+ *     handleSliderChange,
+ *     handleInputChange,
+ *     validateAndUpdateValue
+ *   } = useSliderInput({
+ *     minValue: 0,
+ *     maxValue: 1000,
+ *     initialValue: [100, 500]
+ *   });
+ *
+ *   return (
+ *     <div className="price-range">
+ *       <div className="inputs">
+ *         <input
+ *           type="number"
+ *           value={inputValues[0]}
+ *           onChange={(e) => handleInputChange(e, 0)}
+ *           onBlur={() => validateAndUpdateValue(inputValues[0], 0)}
+ *           placeholder="Min price"
+ *         />
+ *         <input
+ *           type="number"
+ *           value={inputValues[1]}
+ *           onChange={(e) => handleInputChange(e, 1)}
+ *           onBlur={() => validateAndUpdateValue(inputValues[1], 1)}
+ *           placeholder="Max price"
+ *         />
+ *       </div>
+ *
+ *       <Slider
+ *         value={sliderValues}
+ *         onValueChange={handleSliderChange}
+ *         min={0}
+ *         max={1000}
+ *         step={10}
+ *       />
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+declare function useSliderInput({ minValue, maxValue, initialValue }: UseSliderInputProps): {
+    /** Function to manually set slider values */
+    setSliderValues: React.Dispatch<React.SetStateAction<[number, number]>>;
+    /** Function to manually set input values */
+    setInputValues: React.Dispatch<React.SetStateAction<[number, number]>>;
+    /** Current slider values [min, max] */
+    sliderValues: [number, number];
+    /** Current input values [min, max] */
+    inputValues: [number, number];
+    /** Handler for slider value changes */
+    handleSliderChange: (values: [number, number]) => void;
+    /** Handler for input field changes */
+    handleInputChange: (e: React.ChangeEvent<HTMLInputElement>, index: 0 | 1) => void;
+    /** Function to validate and update values from inputs */
+    validateAndUpdateValue: (value: number, index: 0 | 1) => void;
+};
+
+/**
+ * Viewport dimensions tracking hook for React components
+ * Provides real-time viewport width and height with automatic updates
+ * on window resize events with SSR-safe implementation
+ */
+/**
+ * Type definition for viewport dimensions
+ * Returns tuple of [height, width] in pixels
+ */
+type ViewportDimensions = [number, number];
+/**
+ * Hook to track viewport dimensions with real-time updates
+ *
+ * This hook provides the current viewport dimensions and automatically
+ * updates when the window is resized. It's useful for responsive layouts,
+ * conditional rendering based on screen size, and dynamic calculations.
+ *
+ * Features:
+ * - Real-time viewport dimension tracking
+ * - Automatic updates on window resize
+ * - Performance optimized with passive event listeners
+ * - SSR-safe implementation
+ * - Returns both height and width
+ *
+ * @returns Tuple containing [height, width] in pixels
+ *
+ * @example
+ * ```tsx
+ * // Basic usage
+ * function ResponsiveComponent() {
+ *   const [height, width] = useViewport();
+ *
+ *   return (
+ *     <div>
+ *       <p>Viewport: {width}x{height}</p>
+ *       {width > 768 ? <DesktopLayout /> : <MobileLayout />}
+ *     </div>
+ *   );
+ * }
+ *
+ * // Destructured usage
+ * function ViewportInfo() {
+ *   const [height, width] = useViewport();
+ *   const aspectRatio = (width / height).toFixed(2);
+ *
+ *   return (
+ *     <div className="viewport-info">
+ *       <p>Width: {width}px</p>
+ *       <p>Height: {height}px</p>
+ *       <p>Aspect Ratio: {aspectRatio}</p>
+ *     </div>
+ *   );
+ * }
+ *
+ * // Conditional rendering based on viewport
+ * function AdaptiveGrid() {
+ *   const [, width] = useViewport();
+ *   const columns = width > 1200 ? 4 : width > 768 ? 3 : width > 480 ? 2 : 1;
+ *
+ *   return (
+ *     <div className={`grid grid-cols-${columns} gap-4`}>
+ *       {items.map(item => <GridItem key={item.id} {...item} />)}
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+declare const useViewport: () => ViewportDimensions;
+
+export { type FileMetadata, type FileUploadActions, type FileUploadOptions, type FileUploadState, type FileWithPreview, formatBytes, useBodyClasses, useCopyToClipboard, useFileUpload, useHydrated, useIntersectionObserver, useIsMac, useIsMobile, useMediaQuery, useMenu, useMetaColor, useMounted, useMutationObserver, useRemoveGAParams, useScrollPosition, useSliderInput, useViewport };