@djangocfg/ui-nextjs 2.1.103 → 2.1.104

package/dist/hooks.d.mts

@@ -1,364 +0,0 @@
-export * from '@djangocfg/ui-core/hooks';
-import { RefObject } from 'react';
-import { Keys, HotkeyCallback, Options } from 'react-hotkeys-hook';
-export { HotkeyCallback, HotkeysProvider, Keys, isHotkeyPressed, useHotkeysContext } from 'react-hotkeys-hook';
-
-type ResolvedTheme = 'light' | 'dark';
-/**
- * Hook to detect the current resolved theme (light or dark)
- *
- * Standalone hook - doesn't require ThemeProvider.
- * Detects theme from:
- * 1. 'dark' class on html element
- * 2. System preference (prefers-color-scheme)
- *
- * For full theme control (setTheme, toggleTheme), use useThemeContext instead.
- *
- * @example
- * ```tsx
- * const theme = useResolvedTheme(); // 'light' | 'dark'
- * ```
- */
-declare const useResolvedTheme: () => ResolvedTheme;
-
-/**
- * useQueryParams Hook
- *
- * Safe hook to access URL query parameters without requiring Suspense boundary.
- * Works on client-side only, returns empty URLSearchParams during SSR/prerendering.
- *
- * @example
- * ```tsx
- * const params = useQueryParams();
- * const flow = params.get('flow');
- * const hasFlow = params.has('flow');
- * const allTags = params.getAll('tags');
- * ```
- */
-/**
- * Hook to safely access URL query parameters without useSearchParams()
- *
- * This hook reads query parameters directly from window.location.search,
- * avoiding the need for Suspense boundaries that useSearchParams() requires.
- *
- * Automatically updates when URL changes (navigation, back/forward, etc.)
- * Uses pathname from Next.js to detect route changes and polls for query param changes.
- *
- * Returns a URLSearchParams object with get(), getAll(), has(), etc.
- *
- * @returns URLSearchParams object (empty during SSR)
- */
-declare function useQueryParams(): URLSearchParams;
-
-/**
- * Universal Router Hook with BasePath Support
- *
- * Wrapper around Next.js useRouter that automatically handles basePath
- * for static builds served via iframe or subdirectory
- *
- * IMPORTANT: In Next.js 15 App Router, router.push() does NOT automatically
- * handle basePath (unlike Pages Router). This is a breaking change in App Router.
- *
- * This hook ensures basePath is always included when navigating, especially
- * important for static exports served via iframe where basePath is critical.
- *
- * @see https://nextjs.org/docs/app/building-your-application/upgrading/app-router-migration
- */
-/**
- * Router with basePath support
- *
- * Automatically adds basePath to all navigation methods when basePath is configured.
- * In Next.js 15 App Router, router.push() doesn't handle basePath automatically,
- * so this hook uses window.location to ensure basePath is always included.
- *
- * @example
- * ```tsx
- * const router = useCfgRouter();
- *
- * // With basePath='/cfg/admin':
- * router.push('/dashboard');     // Client-side navigation to '/cfg/admin/dashboard'
- * router.replace('/auth');       // Client-side replace with '/cfg/admin/auth'
- * router.hardPush('/dashboard'); // Full page reload to '/cfg/admin/dashboard'
- * router.hardReplace('/auth');   // Full page replace with '/cfg/admin/auth'
- * ```
- */
-declare function useCfgRouter(): {
-    push: (href: string, options?: {
-        scroll?: boolean;
-    }) => void;
-    replace: (href: string, options?: {
-        scroll?: boolean;
-    }) => void;
-    hardPush: (href: string) => void;
-    hardReplace: (href: string) => void;
-    prefetch: (href: string) => void;
-    back: () => void;
-    forward: () => void;
-    refresh: () => void;
-};
-
-/**
- * Options for the useHotkey hook
- */
-interface UseHotkeyOptions extends Omit<Options, 'enabled'> {
-    /** Whether the hotkey is enabled (default: true) */
-    enabled?: boolean;
-    /** Scope for the hotkey - useful for context-specific shortcuts */
-    scope?: string;
-    /** Only trigger when focus is within a specific element */
-    scopes?: string[];
-    /** Prevent default browser behavior */
-    preventDefault?: boolean;
-    /** Enable in input fields and textareas */
-    enableOnFormTags?: boolean | readonly ('input' | 'textarea' | 'select')[];
-    /** Enable when contentEditable element is focused */
-    enableOnContentEditable?: boolean;
-    /** Split key for multiple hotkey combinations (default: ',') */
-    splitKey?: string;
-    /** Key up/down events */
-    keyup?: boolean;
-    keydown?: boolean;
-    /** Description for the hotkey (useful for help dialogs) */
-    description?: string;
-}
-/**
- * Simple wrapper hook for react-hotkeys-hook
- *
- * @example
- * // Single key
- * useHotkey('escape', () => closeModal());
- *
- * @example
- * // Key combination
- * useHotkey('ctrl+s', (e) => {
- *   e.preventDefault();
- *   saveDocument();
- * });
- *
- * @example
- * // Multiple keys (any of them will trigger)
- * useHotkey(['ArrowLeft', '['], () => goToPrevious());
- * useHotkey(['ArrowRight', ']'], () => goToNext());
- *
- * @example
- * // With options
- * useHotkey('/', () => focusSearch(), {
- *   preventDefault: true,
- *   enableOnFormTags: false,
- *   description: 'Focus search input'
- * });
- *
- * @example
- * // Scoped hotkeys
- * useHotkey('delete', () => deleteItem(), { scopes: ['list-view'] });
- *
- * @param keys - Hotkey or array of hotkeys (e.g., 'ctrl+s', 'ArrowLeft', ['[', 'ArrowLeft'])
- * @param callback - Function to call when hotkey is pressed
- * @param options - Configuration options
- * @returns Ref to attach to element for scoped hotkeys
- */
-declare function useHotkey<T extends HTMLElement = HTMLElement>(keys: Keys, callback: HotkeyCallback, options?: UseHotkeyOptions): RefObject<T | null>;
-
-/**
- * Device detection hook wrapper for react-device-detect
- *
- * Provides a convenient interface to access device information including:
- * - Device type (mobile, tablet, desktop, etc.)
- * - Browser information (name, version, etc.)
- * - OS information (name, version, etc.)
- * - Orientation (portrait/landscape)
- *
- * @param userAgent - Optional user agent string (useful for SSR)
- * @returns Device detection object with all available information
- *
- * @example
- * ```tsx
- * const device = useDeviceDetect();
- *
- * if (device.isMobile) {
- *   return <MobileView />;
- * }
- *
- * return <DesktopView />;
- * ```
- */
-declare function useDeviceDetect(userAgent?: string): {
-    isMobile: boolean;
-    isTablet: boolean;
-    isDesktop: boolean;
-    isBrowser: boolean;
-    isMobileOnly: boolean;
-    isSmartTV: boolean;
-    isConsole: boolean;
-    isWearable: boolean;
-    isEmbedded: boolean;
-    isAndroid: boolean;
-    isIOS: boolean;
-    isWindows: boolean;
-    isMacOs: boolean;
-    isWinPhone: boolean;
-    isChrome: boolean;
-    isFirefox: boolean;
-    isSafari: boolean;
-    isOpera: boolean;
-    isIE: boolean;
-    isEdge: boolean;
-    isEdgeChromium: boolean;
-    isLegacyEdge: boolean;
-    isChromium: boolean;
-    isMobileSafari: boolean;
-    isYandex: boolean;
-    isMIUI: boolean;
-    isSamsungBrowser: boolean;
-    isElectron: boolean;
-    isIOS13: boolean;
-    isIPad13: boolean;
-    isIPhone13: boolean;
-    isIPod13: boolean;
-    deviceType: string;
-    osName: string;
-    osVersion: string;
-    browserName: string;
-    browserVersion: string;
-    fullBrowserVersion: string;
-    mobileVendor: string;
-    mobileModel: string;
-    engineName: string;
-    engineVersion: string;
-    getUA: string;
-    isPortrait: boolean;
-    isLandscape: boolean;
-    orientation: "portrait" | "landscape";
-    selectors: {
-        isMobile: boolean;
-        isTablet: boolean;
-        isDesktop: boolean;
-        isBrowser: boolean;
-        isMobileOnly: boolean;
-        isSmartTV: boolean;
-        isConsole: boolean;
-        isWearable: boolean;
-        isEmbedded: boolean;
-        isAndroid: boolean;
-        isIOS: boolean;
-        isWindows: boolean;
-        isMacOs: boolean;
-        isWinPhone: boolean;
-        isChrome: boolean;
-        isFirefox: boolean;
-        isSafari: boolean;
-        isOpera: boolean;
-        isIE: boolean;
-        isEdge: boolean;
-        isEdgeChromium: boolean;
-        isLegacyEdge: boolean;
-        isChromium: boolean;
-        isMobileSafari: boolean;
-        isYandex: boolean;
-        isMIUI: boolean;
-        isSamsungBrowser: boolean;
-        isElectron: boolean;
-        osVersion: string;
-        osName: string;
-        fullBrowserVersion: string;
-        browserVersion: string;
-        browserName: string;
-        mobileVendor: string;
-        mobileModel: string;
-        engineName: string;
-        engineVersion: string;
-        getUA: string;
-        deviceType: string;
-        isIOS13: boolean;
-        isIPad13: boolean;
-        isIPhone13: boolean;
-        isIPod13: boolean;
-    };
-    deviceData: {
-        deviceType: string;
-        osName: string;
-        osVersion: string;
-        browserName: string;
-        browserVersion: string;
-        fullBrowserVersion: string;
-        mobileVendor: string;
-        mobileModel: string;
-        engineName: string;
-        engineVersion: string;
-        getUA: string;
-    };
-};
-type DeviceDetectResult = ReturnType<typeof useDeviceDetect>;
-
-/**
- * Advanced browser detection hook
- *
- * Detects modern browsers including Chromium-based browsers that may
- * incorrectly report as Safari (Arc, Brave, Vivaldi, Comet, etc.)
- */
-interface BrowserInfo {
-    isChrome: boolean;
-    isChromium: boolean;
-    isSafari: boolean;
-    isFirefox: boolean;
-    isEdge: boolean;
-    isOpera: boolean;
-    isBrave: boolean;
-    isArc: boolean;
-    isVivaldi: boolean;
-    isYandex: boolean;
-    isSamsungBrowser: boolean;
-    isUCBrowser: boolean;
-    isComet: boolean;
-    isOperaMini: boolean;
-    isIE: boolean;
-    isFacebookInApp: boolean;
-    isInstagramInApp: boolean;
-    isTikTokInApp: boolean;
-    isSnapchatInApp: boolean;
-    isWeChatInApp: boolean;
-    isThreadsInApp: boolean;
-    isLinkedInInApp: boolean;
-    isTwitterInApp: boolean;
-    isInAppBrowser: boolean;
-    isWebView: boolean;
-    browserName: string;
-    isWebKit: boolean;
-    isBlink: boolean;
-    isGecko: boolean;
-    /**
-     * Whether the browser supports Web Push Notifications.
-     * Returns false for browsers known to NOT support push:
-     * - Opera Mini (no service worker support)
-     * - Internet Explorer (deprecated, no Push API)
-     * - UC Browser (unreliable push support)
-     * - In-App browsers (Facebook, Instagram, TikTok, Snapchat, etc.)
-     * - Generic WebViews (except Twitter/LinkedIn on Android which use Chrome WebView)
-     *
-     * Note: Comet (Perplexity) is Chromium-based and DOES support push notifications.
-     * Note: This is a browser-level check. For full push support,
-     * also check 'serviceWorker' in navigator && 'PushManager' in window
-     */
-    supportsPushNotifications: boolean;
-    isIOSBrowser: boolean;
-    userAgent: string;
-}
-/**
- * Detect browser with improved accuracy for Chromium-based browsers
- *
- * @example
- * ```tsx
- * const browser = useBrowserDetect();
- *
- * if (browser.isSafari && !browser.isChromium) {
- *   // Real Safari
- * }
- *
- * if (browser.isChromium) {
- *   // Any Chromium-based browser (Chrome, Edge, Brave, Arc, etc.)
- * }
- * ```
- */
-declare function useBrowserDetect(): BrowserInfo;
-
-export { type BrowserInfo, type DeviceDetectResult, type ResolvedTheme, type UseHotkeyOptions, useBrowserDetect, useCfgRouter, useDeviceDetect, useHotkey, useQueryParams, useResolvedTheme };