pelatform-ui 1.2.9 → 1.3.1

package/dist/hooks.d.ts

@@ -1,5 +1,643 @@
-export * from '@pelatform/ui.hook';
-import { M as META_THEME_COLORS } from './colors-CUDWvz1g.js';
+import * as React from 'react';
+import React__default, { DragEvent, ChangeEvent, InputHTMLAttributes, ComponentType, SVGProps, RefObject } from 'react';
+import { META_THEME_COLORS } from '@pelatform/utils';
+
+/**
+ * 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
+ */
+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
@@ -85,9 +723,564 @@ import { M as META_THEME_COLORS } from './colors-CUDWvz1g.js';
  */
 declare function useMetaColor(defaultColors?: typeof META_THEME_COLORS): {
     /** Current meta theme color based on resolved theme */
-    metaColor: "#ffffff" | "#09090b";
+    metaColor: "#09090b" | "#ffffff";
     /** Function to manually set meta theme color */
     setMetaColor: (color: string) => void;
 };
 
-export { useMetaColor };
+/**
+ * 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, useIntersectionObserver, useIsMac, useIsMobile, useMediaQuery, useMenu, useMetaColor, useMounted, useMutationObserver, useRecaptchaV2, useRemoveGAParams, useScrollPosition, useSliderInput, useViewport };