@djangocfg/ui-nextjs 2.1.102 → 2.1.103

package/dist/animations.d.mts

@@ -0,0 +1,36 @@
+import React from 'react';
+
+type BackgroundVariant = 'aurora-borealis' | 'mesh-gradient' | 'floating-orbs' | 'geometric-flow' | 'liquid-gradient' | 'spotlight' | 'none' | 'gradient-mesh' | 'dot-matrix' | 'grid-lines' | 'aurora' | 'particles' | 'waves';
+interface AnimatedBackgroundProps {
+    variant?: BackgroundVariant;
+    className?: string;
+    intensity?: 'subtle' | 'medium' | 'strong';
+    /** Color scheme - 'vibrant' uses multiple colors, 'monochrome' uses primary only */
+    colorScheme?: 'vibrant' | 'monochrome' | 'cool' | 'warm';
+}
+declare const AnimatedBackground: React.FC<AnimatedBackgroundProps>;
+
+type MouseFollowerVariant = 'glow' | 'spotlight' | 'gradient-blob' | 'ring' | 'trail';
+interface MouseFollowerProps {
+    /** Visual style of the follower */
+    variant?: MouseFollowerVariant;
+    /** Size of the effect in pixels */
+    size?: number;
+    /** Color - can be CSS color or 'primary' to use theme */
+    color?: string;
+    /** Smoothness of following (0.05 = very smooth, 0.3 = snappy) */
+    smoothness?: number;
+    /** Opacity of the effect (0-1) */
+    opacity?: number;
+    /** Blur amount for glow effects */
+    blur?: 'sm' | 'md' | 'lg' | 'xl' | '2xl' | '3xl';
+    /** Additional className for the container */
+    className?: string;
+    /** Whether to show on mobile (touch devices) */
+    showOnMobile?: boolean;
+    /** Disable the effect */
+    disabled?: boolean;
+}
+declare const MouseFollower: React.FC<MouseFollowerProps>;
+
+export { AnimatedBackground, type BackgroundVariant, MouseFollower, type MouseFollowerVariant };

package/dist/animations.d.ts

@@ -0,0 +1,36 @@
+import React from 'react';
+
+type BackgroundVariant = 'aurora-borealis' | 'mesh-gradient' | 'floating-orbs' | 'geometric-flow' | 'liquid-gradient' | 'spotlight' | 'none' | 'gradient-mesh' | 'dot-matrix' | 'grid-lines' | 'aurora' | 'particles' | 'waves';
+interface AnimatedBackgroundProps {
+    variant?: BackgroundVariant;
+    className?: string;
+    intensity?: 'subtle' | 'medium' | 'strong';
+    /** Color scheme - 'vibrant' uses multiple colors, 'monochrome' uses primary only */
+    colorScheme?: 'vibrant' | 'monochrome' | 'cool' | 'warm';
+}
+declare const AnimatedBackground: React.FC<AnimatedBackgroundProps>;
+
+type MouseFollowerVariant = 'glow' | 'spotlight' | 'gradient-blob' | 'ring' | 'trail';
+interface MouseFollowerProps {
+    /** Visual style of the follower */
+    variant?: MouseFollowerVariant;
+    /** Size of the effect in pixels */
+    size?: number;
+    /** Color - can be CSS color or 'primary' to use theme */
+    color?: string;
+    /** Smoothness of following (0.05 = very smooth, 0.3 = snappy) */
+    smoothness?: number;
+    /** Opacity of the effect (0-1) */
+    opacity?: number;
+    /** Blur amount for glow effects */
+    blur?: 'sm' | 'md' | 'lg' | 'xl' | '2xl' | '3xl';
+    /** Additional className for the container */
+    className?: string;
+    /** Whether to show on mobile (touch devices) */
+    showOnMobile?: boolean;
+    /** Disable the effect */
+    disabled?: boolean;
+}
+declare const MouseFollower: React.FC<MouseFollowerProps>;
+
+export { AnimatedBackground, type BackgroundVariant, MouseFollower, type MouseFollowerVariant };

package/dist/hooks.d.mts

@@ -0,0 +1,364 @@
+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 };

package/dist/hooks.d.ts

@@ -0,0 +1,364 @@
+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 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@djangocfg/ui-nextjs",
-  "version": "2.1.102",
+  "version": "2.1.103",
   "description": "Next.js UI component library with Radix UI primitives, Tailwind CSS styling, charts, and form components",
   "keywords": [
     "ui-components",
@@ -83,9 +83,9 @@
     "check": "tsc --noEmit"
   },
   "peerDependencies": {
-    "@djangocfg/api": "^2.1.102",
-    "@djangocfg/ui-core": "^2.1.102",
-    "@djangocfg/ui-tools": "^2.1.102",
+    "@djangocfg/api": "^2.1.103",
+    "@djangocfg/ui-core": "^2.1.103",
+    "@djangocfg/ui-tools": "^2.1.103",
     "@types/react": "^19.1.0",
     "@types/react-dom": "^19.1.0",
     "consola": "^3.4.2",
@@ -109,7 +109,7 @@
     "react-hotkeys-hook": "^5.2.1"
   },
   "devDependencies": {
-    "@djangocfg/typescript-config": "^2.1.102",
+    "@djangocfg/typescript-config": "^2.1.103",
     "@radix-ui/react-dropdown-menu": "^2.1.16",
     "@radix-ui/react-slot": "^1.2.4",
     "@types/node": "^24.7.2",