@pelatform/ui.hook 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,1111 @@
+import * as React from 'react';
+import React__default, { DragEvent, ChangeEvent, InputHTMLAttributes, ComponentType, SVGProps, RefObject } from 'react';
+
+/**
+ * Analytics tracking hook for React components
+ * Provides utilities for tracking CRUD operations and user interactions
+ * with Google Analytics integration
+ */
+/**
+ * Type definition for window with Google Analytics gtag function
+ * This extends the Window interface to include the gtag function
+ * that's injected by the Google Analytics script
+ * This implementation matches the global declaration in analytics.ts
+ */
+interface GtagWindow extends Window {
+    gtag?: (command: "event" | "config" | "set", targetId: string, config?: Record<string, string | number | boolean | object | null | undefined>) => void;
+}
+/**
+ * Main application modules for analytics tracking
+ * Comprehensive SaaS platform modules
+ */
+type ModuleType = "workspace" | "user" | "billing" | "analytics" | "integration" | "content" | "communication" | "system" | "security" | "automation" | "ecommerce";
+/**
+ * Workspace module specific submodules
+ * Core workspace management functionality
+ */
+type WorkspaceSubModuleType = "workspaces" | "projects" | "teams" | "collaboration" | "templates" | "workflows" | "dashboard" | "kanban" | "calendar" | "files";
+/**
+ * User module specific submodules
+ * User management and authentication
+ */
+type UserSubModuleType = "users" | "profiles" | "roles" | "permissions" | "groups" | "invitations" | "authentication" | "sessions" | "preferences" | "activity";
+/**
+ * Billing module specific submodules
+ * Subscription and payment management
+ */
+type BillingSubModuleType = "subscriptions" | "plans" | "invoices" | "payments" | "credits" | "usage" | "discounts" | "taxes" | "refunds" | "billing_history";
+/**
+ * Analytics module specific submodules
+ * Data analytics and reporting
+ */
+type AnalyticsSubModuleType = "reports" | "dashboards" | "metrics" | "events" | "funnels" | "cohorts" | "segments" | "exports" | "real_time" | "custom_reports";
+/**
+ * Integration module specific submodules
+ * Third-party integrations and APIs
+ */
+type IntegrationSubModuleType = "api_keys" | "webhooks" | "oauth" | "connectors" | "sync" | "imports" | "exports" | "marketplace" | "custom_integrations" | "rate_limits";
+/**
+ * Content module specific submodules
+ * Content management and media
+ */
+type ContentSubModuleType = "documents" | "media" | "assets" | "libraries" | "versions" | "comments" | "reviews" | "publishing" | "cdn" | "storage";
+/**
+ * Communication module specific submodules
+ * Messaging and notification systems
+ */
+type CommunicationSubModuleType = "notifications" | "emails" | "sms" | "chat" | "announcements" | "broadcasts" | "templates" | "campaigns" | "channels" | "delivery";
+/**
+ * System module specific submodules
+ * System administration and maintenance
+ */
+type SystemSubModuleType = "settings" | "configurations" | "logs" | "monitoring" | "backups" | "maintenance" | "health_checks" | "performance" | "database" | "cache";
+/**
+ * Security module specific submodules
+ * Security and compliance features
+ */
+type SecuritySubModuleType = "audit_logs" | "access_control" | "encryption" | "compliance" | "threats" | "vulnerabilities" | "certificates" | "firewall" | "monitoring" | "incidents";
+/**
+ * Automation module specific submodules
+ * Workflow automation and triggers
+ */
+type AutomationSubModuleType = "workflows" | "triggers" | "actions" | "conditions" | "schedules" | "pipelines" | "bots" | "scripts" | "rules" | "execution_logs";
+/**
+ * E-commerce module specific submodules
+ * Online store and transaction management
+ */
+type EcommerceSubModuleType = "products" | "categories" | "inventory" | "orders" | "customers" | "payments" | "shipping" | "discounts" | "reviews" | "analytics";
+/**
+ * Union type of all possible submodules
+ * Combines all module-specific submodule types for comprehensive tracking
+ */
+type SubModuleType = WorkspaceSubModuleType | UserSubModuleType | BillingSubModuleType | AnalyticsSubModuleType | IntegrationSubModuleType | ContentSubModuleType | CommunicationSubModuleType | SystemSubModuleType | SecuritySubModuleType | AutomationSubModuleType | EcommerceSubModuleType;
+/**
+ * Hook for tracking analytics events in React components
+ *
+ * This hook provides methods for tracking CRUD operations
+ * with proper typing and structure for Google Analytics.
+ *
+ * @returns Object containing tracking methods for different CRUD operations
+ *
+ * @example
+ * ```tsx
+ * // Workspace management tracking
+ * function WorkspaceManagement() {
+ *   const { trackCreate, trackUpdate, trackDelete, trackView } = useAnalytics();
+ *
+ *   const handleCreateWorkspace = async (workspaceData) => {
+ *     const workspace = await createWorkspace(workspaceData);
+ *     trackCreate('workspace', 'workspaces', 'workspace', workspace.id);
+ *   };
+ *
+ *   const handleViewProject = (projectId) => {
+ *     trackView('workspace', 'projects', 'project', projectId);
+ *   };
+ *
+ *   return <WorkspaceForm onSubmit={handleCreateWorkspace} />;
+ * }
+ *
+ * // Billing and subscription tracking
+ * function BillingDashboard() {
+ *   const { trackUpdate, trackView } = useAnalytics();
+ *
+ *   const handleUpgradePlan = async (planId) => {
+ *     await upgradePlan(planId);
+ *     trackUpdate('billing', 'subscriptions', 'plan', planId);
+ *   };
+ *
+ *   const handleViewInvoice = (invoiceId) => {
+ *     trackView('billing', 'invoices', 'invoice', invoiceId);
+ *   };
+ *
+ *   return <BillingInterface onUpgrade={handleUpgradePlan} />;
+ * }
+ *
+ * // User management tracking
+ * function UserManagement() {
+ *   const { trackCreate, trackUpdate } = useAnalytics();
+ *
+ *   const handleInviteUser = async (email, role) => {
+ *     const invitation = await inviteUser(email, role);
+ *     trackCreate('user', 'invitations', 'invitation', invitation.id);
+ *   };
+ *
+ *   const handleUpdatePermissions = async (userId, permissions) => {
+ *     await updateUserPermissions(userId, permissions);
+ *     trackUpdate('user', 'permissions', 'permission', userId);
+ *   };
+ *
+ *   return <UserInviteForm onInvite={handleInviteUser} />;
+ * }
+ *
+ * // Integration and automation tracking
+ * function IntegrationSettings() {
+ *   const { trackCreate, trackUpdate } = useAnalytics();
+ *
+ *   const handleCreateWebhook = async (webhookData) => {
+ *     const webhook = await createWebhook(webhookData);
+ *     trackCreate('integration', 'webhooks', 'webhook', webhook.id);
+ *   };
+ *
+ *   const handleUpdateWorkflow = async (workflowId, updates) => {
+ *     await updateWorkflow(workflowId, updates);
+ *     trackUpdate('automation', 'workflows', 'workflow', workflowId);
+ *   };
+ *
+ *   return <IntegrationPanel onCreate={handleCreateWebhook} />;
+ * }
+ * ```
+ */
+declare const useAnalytics: () => {
+    trackCreate: (module: ModuleType, submodule: SubModuleType, itemType: string, itemId?: string) => void;
+    trackUpdate: (module: ModuleType, submodule: SubModuleType, itemType: string, itemId: string) => void;
+    trackDelete: (module: ModuleType, submodule: SubModuleType, itemType: string, itemId: string, isHardDelete?: boolean) => void;
+};
+
+/**
+ * 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
+ */
+interface 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
+ */
+interface 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
+ */
+interface 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
+ */
+interface 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
+ */
+interface 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;
+
+/**
+ * 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;
+
+/**
+ * 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 reCAPTCHA v2 integration hook for React components
+ * Provides a complete solution for implementing reCAPTCHA v2 with automatic
+ * script loading, widget management, and token retrieval
+ */
+/**
+ * Hook for integrating Google reCAPTCHA v2 into React components
+ *
+ * This hook provides a complete solution for reCAPTCHA v2 integration including:
+ * - Automatic script loading and initialization
+ * - Widget rendering and management
+ * - Token retrieval and validation
+ * - Cleanup and reset functionality
+ *
+ * @param siteKey - Your Google reCAPTCHA site key
+ * @returns Object containing ref, token getter, reset function, and initializer
+ *
+ * @example
+ * ```tsx
+ * function ContactForm() {
+ *   const { containerRef, getToken, resetCaptcha } = useRecaptchaV2('your-site-key');
+ *
+ *   const handleSubmit = async (e) => {
+ *     e.preventDefault();
+ *
+ *     try {
+ *       const token = getToken();
+ *       if (!token) {
+ *         alert('Please complete the reCAPTCHA');
+ *         return;
+ *       }
+ *
+ *       // Submit form with token
+ *       await submitForm({ token, ...formData });
+ *       resetCaptcha(); // Reset after successful submission
+ *     } catch (error) {
+ *       console.error('Submission failed:', error);
+ *     }
+ *   };
+ *
+ *   return (
+ *     <form onSubmit={handleSubmit}>
+ *       <input type="email" placeholder="Email" />
+ *       <div ref={containerRef}></div>
+ *       <button type="submit">Submit</button>
+ *     </form>
+ *   );
+ * }
+ * ```
+ */
+declare function useRecaptchaV2(siteKey: string): {
+    /** Ref to attach to the container div where reCAPTCHA will be rendered */
+    containerRef: React.RefObject<HTMLDivElement | null>;
+    /** Function to get the reCAPTCHA response token */
+    getToken: () => string;
+    /** Function to reset the reCAPTCHA widget */
+    resetCaptcha: () => void;
+    /** Function to manually initialize reCAPTCHA (usually not needed) */
+    initializeRecaptcha: () => Promise<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, type GtagWindow, formatBytes, useAnalytics, useBodyClasses, useCopyToClipboard, useFileUpload, useHydrated, useIsMobile, useMediaQuery, useMenu, useMounted, useMutationObserver, useRecaptchaV2, useRemoveGAParams, useScrollPosition, useSliderInput, useViewport };