@djangocfg/layouts 2.1.101 → 2.1.103

package/dist/snippets.d.mts

@@ -0,0 +1,1192 @@
+import React$1, { ReactNode } from 'react';
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { ButtonProps } from '@djangocfg/ui-nextjs';
+
+interface BreadcrumbItem {
+    path: string;
+    label: string;
+    isActive: boolean;
+}
+declare function generateBreadcrumbsFromPath(pathname: string): BreadcrumbItem[];
+
+declare const DIALOG_EVENTS: {
+    readonly OPEN_AUTH_DIALOG: "OPEN_AUTH_DIALOG";
+    readonly CLOSE_AUTH_DIALOG: "CLOSE_AUTH_DIALOG";
+    readonly AUTH_SUCCESS: "AUTH_SUCCESS";
+    readonly AUTH_FAILURE: "AUTH_FAILURE";
+};
+interface AuthDialogProps {
+    onAuthRequired?: () => void;
+    authPath?: string;
+}
+declare const AuthDialog: React$1.FC<AuthDialogProps>;
+
+declare const AUTH_EVENTS: {
+    readonly OPEN_AUTH_DIALOG: "OPEN_AUTH_DIALOG";
+    readonly CLOSE_AUTH_DIALOG: "CLOSE_AUTH_DIALOG";
+    readonly AUTH_SUCCESS: "AUTH_SUCCESS";
+    readonly AUTH_FAILURE: "AUTH_FAILURE";
+};
+type AuthEventType = typeof AUTH_EVENTS[keyof typeof AUTH_EVENTS];
+interface OpenAuthDialogPayload {
+    message?: string;
+    redirectUrl?: string;
+}
+interface AuthSuccessPayload {
+    user?: any;
+}
+interface AuthFailurePayload {
+    error?: string;
+}
+
+/**
+ * Hook to control auth dialog from anywhere in the app
+ */
+declare function useAuthDialog(): {
+    openAuthDialog: (options?: OpenAuthDialogPayload) => void;
+    closeAuthDialog: () => void;
+};
+
+/**
+ * useAnalytics Hook
+ *
+ * Provides Google Analytics tracking via react-ga4
+ * Automatically tracks page views on route changes
+ * Only works in production mode
+ */
+/**
+ * Analytics utility object for standalone usage (outside React components)
+ *
+ * @example
+ * ```ts
+ * import { Analytics } from '@djangocfg/layouts';
+ *
+ * // In an event handler or utility function
+ * Analytics.event('button_click', { category: 'engagement', label: 'signup' });
+ * ```
+ */
+declare const Analytics: {
+    /**
+     * Initialize Google Analytics (called automatically by useAnalytics hook)
+     */
+    init: (trackingId: string) => void;
+    /**
+     * Check if Analytics is enabled and initialized
+     */
+    isEnabled: () => boolean;
+    /**
+     * Track a page view
+     */
+    pageview: (path: string) => void;
+    /**
+     * Track a custom event
+     * @param name - Event name (action)
+     * @param params - Optional event parameters
+     */
+    event: (name: string, params?: Record<string, any>) => void;
+    /**
+     * Set user ID for tracking
+     */
+    setUser: (userId: string) => void;
+    /**
+     * Set custom dimensions/metrics
+     */
+    set: (fieldsObject: Record<string, any>) => void;
+};
+/**
+ * Hook for Google Analytics tracking via react-ga4
+ *
+ * Automatically initializes GA and tracks page views on route changes
+ * Only works in production mode (NODE_ENV === 'production')
+ *
+ * @example
+ * ```tsx
+ * // Just call the hook - it auto-tracks pageviews
+ * useAnalytics();
+ *
+ * // Or use the returned methods for custom tracking
+ * const { event, isEnabled } = useAnalytics();
+ * event('button_click', { category: 'engagement', label: 'signup' });
+ * ```
+ */
+declare function useAnalytics(trackingIdProp?: string): {
+    isEnabled: boolean;
+    trackingId: string;
+    pageview: (path: string) => void;
+    event: (name: string, params?: Record<string, any>) => void;
+    setUser: (userId: string) => void;
+    set: (fieldsObject: Record<string, any>) => void;
+};
+
+interface AnalyticsProviderProps {
+    children: ReactNode;
+    /** Google Analytics tracking ID (optional if using AppContext) */
+    trackingId?: string;
+}
+/**
+ * Analytics Provider that initializes tracking
+ * Automatically:
+ * - Initializes GA4 with tracking ID from prop or config
+ * - Sets user ID when authenticated
+ * - Tracks page views on route changes
+ */
+declare function AnalyticsProvider({ children, trackingId }: AnalyticsProviderProps): react_jsx_runtime.JSX.Element;
+
+/**
+ * Analytics Events Constants
+ *
+ * Predefined event names and categories for consistent tracking
+ * across the entire application.
+ */
+/**
+ * Event Categories
+ */
+declare const AnalyticsCategory: {
+    readonly AUTH: "auth";
+    readonly ERROR: "error";
+    readonly NAVIGATION: "navigation";
+    readonly ENGAGEMENT: "engagement";
+    readonly USER: "user";
+};
+/**
+ * Predefined Event Names
+ */
+declare const AnalyticsEvent: {
+    readonly AUTH_OTP_REQUEST: "auth_otp_request";
+    readonly AUTH_OTP_VERIFY_SUCCESS: "auth_otp_verify_success";
+    readonly AUTH_OTP_VERIFY_FAIL: "auth_otp_verify_fail";
+    readonly AUTH_LOGIN_SUCCESS: "auth_login_success";
+    readonly AUTH_LOGOUT: "auth_logout";
+    readonly AUTH_SESSION_EXPIRED: "auth_session_expired";
+    readonly AUTH_TOKEN_REFRESH: "auth_token_refresh";
+    readonly AUTH_TOKEN_REFRESH_FAIL: "auth_token_refresh_fail";
+    readonly AUTH_OAUTH_START: "auth_oauth_start";
+    readonly AUTH_OAUTH_SUCCESS: "auth_oauth_success";
+    readonly AUTH_OAUTH_FAIL: "auth_oauth_fail";
+    readonly ERROR_BOUNDARY: "error_boundary";
+    readonly ERROR_API: "error_api";
+    readonly ERROR_VALIDATION: "error_validation";
+    readonly ERROR_NETWORK: "error_network";
+    readonly NAV_ADMIN_ENTER: "nav_admin_enter";
+    readonly NAV_DASHBOARD_ENTER: "nav_dashboard_enter";
+    readonly NAV_PAGE_VIEW: "nav_page_view";
+    readonly THEME_CHANGE: "theme_change";
+    readonly SIDEBAR_TOGGLE: "sidebar_toggle";
+    readonly MOBILE_MENU_OPEN: "mobile_menu_open";
+    readonly USER_PROFILE_VIEW: "user_profile_view";
+    readonly USER_PROFILE_UPDATE: "user_profile_update";
+};
+type AnalyticsCategoryType = typeof AnalyticsCategory[keyof typeof AnalyticsCategory];
+type AnalyticsEventType = typeof AnalyticsEvent[keyof typeof AnalyticsEvent];
+
+/**
+ * Analytics Configuration Types
+ *
+ * Configuration for Google Analytics integration
+ */
+interface AnalyticsConfig {
+    /** Google Analytics tracking ID (e.g., 'G-XXXXXXXXXX') */
+    googleTrackingId?: string;
+}
+
+/**
+ * Types for @djangocfg/mcp-chat
+ */
+
+/**
+ * AI Chat message role
+ */
+type AIMessageRole = 'user' | 'assistant' | 'system';
+/**
+ * AI Chat message
+ */
+interface AIChatMessage {
+    id: string;
+    role: AIMessageRole;
+    content: string;
+    timestamp: Date;
+    /** Related documentation links */
+    sources?: AIChatSource[];
+    /** Is message still being generated */
+    isStreaming?: boolean;
+}
+/**
+ * AI Documentation source reference
+ */
+interface AIChatSource {
+    title: string;
+    path: string;
+    url?: string;
+    section?: string;
+    score?: number;
+}
+/**
+ * Chat display mode
+ * - closed: Only FAB button visible
+ * - floating: Floating panel (default)
+ * - sidebar: Full-height sidebar on the right (desktop only)
+ */
+type ChatDisplayMode = 'closed' | 'floating' | 'sidebar';
+/**
+ * Chat widget configuration
+ */
+interface ChatWidgetConfig {
+    /** API endpoint for chat (default: /api/chat) */
+    apiEndpoint?: string;
+    /** Widget title */
+    title?: string;
+    /** Placeholder text for input */
+    placeholder?: string;
+    /** Initial greeting message */
+    greeting?: string;
+    /** Position on screen */
+    position?: 'bottom-right' | 'bottom-left';
+    /** Theme variant */
+    variant?: 'default' | 'minimal';
+    /** Auto-detect environment (dev/prod) for API endpoint. If false (default), always uses production */
+    autoDetectEnvironment?: boolean;
+}
+/**
+ * AI Chat API response
+ */
+interface AIChatApiResponse {
+    success: boolean;
+    content?: string;
+    sources?: Array<{
+        id?: string;
+        title: string;
+        path: string;
+        url?: string;
+        section?: string;
+        score?: number;
+    }>;
+    threadId?: string;
+    usage?: {
+        promptTokens: number;
+        completionTokens: number;
+        totalTokens: number;
+    };
+    error?: string;
+}
+/**
+ * useAIChat hook options
+ */
+interface UseAIChatOptions {
+    /** API endpoint (default: /api/ai/chat) */
+    apiEndpoint?: string;
+    /** Initial messages */
+    initialMessages?: AIChatMessage[];
+    /** Callback on error */
+    onError?: (error: Error) => void;
+    /** Enable streaming responses (default: true) */
+    enableStreaming?: boolean;
+    /** Thread ID for conversation (generated if not provided) */
+    threadId?: string;
+    /** User ID for conversation (generated if not provided) */
+    userId?: string;
+}
+/**
+ * useAIChat hook return type
+ */
+interface UseAIChatReturn {
+    messages: AIChatMessage[];
+    isLoading: boolean;
+    error: Error | null;
+    threadId: string;
+    userId: string;
+    sendMessage: (content: string) => Promise<void>;
+    clearMessages: () => void;
+    stopStreaming: () => void;
+}
+/**
+ * Context type for chat messages triggered from different parts of the app
+ */
+type McpChatContextType = 'error' | 'question' | 'explain' | 'advice' | 'help' | 'custom';
+/**
+ * Event detail for mcp:chat:send custom event
+ */
+interface McpChatEventDetail {
+    /** Message to send to chat */
+    message: string;
+    /** Optional context about the message */
+    context?: {
+        /** Type of context */
+        type?: McpChatContextType;
+        /** Additional data (error object, selected element, etc.) */
+        data?: Record<string, any>;
+        /** Source component/page that triggered the event */
+        source?: string;
+    };
+    /** Auto-send message after opening chat (default: true) */
+    autoSend?: boolean;
+    /** Open chat in specific mode (default: 'floating') */
+    displayMode?: ChatDisplayMode;
+}
+/**
+ * useMcpChat hook return type
+ */
+interface UseMcpChatReturn {
+    /** Send message to chat from anywhere in the app */
+    sendToChat: (detail: McpChatEventDetail) => void;
+    /** Check if chat is available */
+    isChatAvailable: () => boolean;
+}
+
+interface AIChatWidgetProps extends ChatWidgetConfig {
+    /** Custom class name for the container */
+    className?: string;
+    /** Enable streaming responses (default: true) */
+    enableStreaming?: boolean;
+}
+/**
+ * AI Chat Widget component
+ *
+ * AI-powered documentation assistant with streaming support.
+ * Uses Mastra agent backend for intelligent responses.
+ *
+ * Can be used in two ways:
+ * 1. Standalone (wraps itself in AIChatProvider)
+ * 2. Inside an AIChatProvider (uses context directly)
+ *
+ * @example
+ * ```tsx
+ * // Standalone usage (always uses production API)
+ * <AIChatWidget />
+ *
+ * // Auto-detect environment (dev/prod)
+ * <AIChatWidget autoDetectEnvironment={true} />
+ *
+ * // With provider for custom control
+ * <AIChatProvider apiEndpoint="/api/ai/chat">
+ *   <MyApp />
+ *   <AIChatWidget />
+ * </AIChatProvider>
+ * ```
+ */
+declare const AIChatWidget: React$1.FC<AIChatWidgetProps>;
+
+declare const ChatPanel: React$1.MemoExoticComponent<() => react_jsx_runtime.JSX.Element>;
+
+interface MessageBubbleProps {
+    message: AIChatMessage;
+    isCompact?: boolean;
+}
+declare const MessageBubble: React$1.NamedExoticComponent<MessageBubbleProps>;
+
+interface AIMessageInputProps {
+    onSend: (message: string) => void;
+    disabled?: boolean;
+    isLoading?: boolean;
+    placeholder?: string;
+    maxRows?: number;
+}
+declare const AIMessageInput: React$1.NamedExoticComponent<AIMessageInputProps>;
+
+interface AskAIButtonProps extends Omit<ButtonProps, 'onClick'> {
+    /** Message to send to AI */
+    message: string;
+    /** Additional context data */
+    contextData?: Record<string, any>;
+    /** Source component name */
+    source?: string;
+    /** Auto-send message (default: true) */
+    autoSend?: boolean;
+    /** Show icon (default: true) */
+    showIcon?: boolean;
+    /** Callback after sending */
+    onSent?: () => void;
+}
+/**
+ * Universal AI chat trigger button
+ *
+ * @example Basic usage
+ * ```tsx
+ * <AskAIButton message="Explain this feature">
+ *   Explain this
+ * </AskAIButton>
+ * ```
+ *
+ * @example With context
+ * ```tsx
+ * <AskAIButton
+ *   message="Why is this failing?"
+ *   contextData={{ error: error.stack }}
+ *   source="ErrorBoundary"
+ * >
+ *   Ask AI
+ * </AskAIButton>
+ * ```
+ */
+declare function AskAIButton({ message, contextData, source, autoSend, showIcon, onSent, children, variant, size, className, ...buttonProps }: AskAIButtonProps): react_jsx_runtime.JSX.Element;
+
+/**
+ * AI Chat context state
+ */
+interface AIChatContextState {
+    /** All chat messages */
+    messages: AIChatMessage[];
+    /** Whether a request is in progress */
+    isLoading: boolean;
+    /** Last error if any */
+    error: Error | null;
+    /** Whether chat panel is open */
+    isOpen: boolean;
+    /** Whether chat is minimized */
+    isMinimized: boolean;
+    /** Configuration */
+    config: ChatWidgetConfig;
+    /** Current display mode */
+    displayMode: ChatDisplayMode;
+    /** Is on mobile device */
+    isMobile: boolean;
+    /** Thread ID for conversation */
+    threadId: string;
+    /** User ID for conversation */
+    userId: string;
+}
+/**
+ * AI Chat context actions
+ */
+interface AIChatContextActions {
+    /** Send a message */
+    sendMessage: (content: string) => Promise<void>;
+    /** Clear all messages */
+    clearMessages: () => void;
+    /** Open chat panel */
+    openChat: () => void;
+    /** Close chat panel */
+    closeChat: () => void;
+    /** Toggle chat panel */
+    toggleChat: () => void;
+    /** Minimize/restore chat */
+    toggleMinimize: () => void;
+    /** Set display mode */
+    setDisplayMode: (mode: ChatDisplayMode) => void;
+    /** Stop streaming response */
+    stopStreaming: () => void;
+}
+type AIChatContextValue = AIChatContextState & AIChatContextActions;
+/**
+ * AI Chat provider props
+ */
+interface AIChatProviderProps {
+    children: ReactNode;
+    /** API endpoint for AI chat (default: /api/ai/chat) */
+    apiEndpoint?: string;
+    /** Widget configuration */
+    config?: Partial<ChatWidgetConfig>;
+    /** Callback on error */
+    onError?: (error: Error) => void;
+    /** Enable streaming (default: true) */
+    enableStreaming?: boolean;
+}
+/**
+ * AI Chat provider component
+ * Uses useAIChat hook with server-side persistence
+ */
+declare function AIChatProvider({ children, apiEndpoint, config: userConfig, onError, enableStreaming, }: AIChatProviderProps): react_jsx_runtime.JSX.Element;
+/**
+ * Hook to access AI chat context
+ */
+declare function useAIChatContext(): AIChatContextValue;
+/**
+ * Hook to check if AI chat context is available
+ */
+declare function useAIChatContextOptional(): AIChatContextValue | null;
+
+/**
+ * AI Chat hook with streaming support and server-side history
+ * All persistence is handled through API endpoints - no localStorage
+ */
+declare function useAIChat(options: UseAIChatOptions): UseAIChatReturn;
+
+/**
+ * Configuration for chat layout management
+ */
+interface ChatLayoutConfig {
+    /** Initial width of sidebar in pixels */
+    initialWidth?: number;
+    /** Animation duration in ms */
+    animationDuration?: number;
+    /** Element to push (defaults to body) */
+    pushTarget?: 'body' | 'main' | string;
+}
+/**
+ * Return type for useChatLayout hook
+ */
+interface UseChatLayoutReturn {
+    /** Current sidebar width */
+    sidebarWidth: number;
+    /** Apply layout changes for mode */
+    applyLayout: (mode: ChatDisplayMode) => void;
+    /** Reset layout to default */
+    resetLayout: () => void;
+    /** Update sidebar width (for resize) */
+    updateWidth: (width: number) => void;
+    /** Start resize operation */
+    startResize: (e: React.MouseEvent) => void;
+    /** Whether currently resizing */
+    isResizing: boolean;
+    /** Get CSS for sidebar container */
+    getSidebarStyles: () => React.CSSProperties;
+    /** Get CSS for floating container */
+    getFloatingStyles: (position: 'bottom-right' | 'bottom-left') => React.CSSProperties;
+    /** Get CSS for FAB button */
+    getFabStyles: (position: 'bottom-right' | 'bottom-left') => React.CSSProperties;
+}
+/**
+ * Hook for managing chat layout embedding modes
+ *
+ * Handles:
+ * - Sidebar mode: pushes content left by adding margin to target element
+ *   AND automatically adjusts all position:fixed elements with right:0
+ * - Floating mode: positions chat at bottom-right/left
+ * - Closed mode: just shows FAB button
+ *
+ * @example
+ * ```tsx
+ * const { applyLayout, getSidebarStyles, getFloatingStyles } = useChatLayout({
+ *   sidebarWidth: 400,
+ * });
+ *
+ * useEffect(() => {
+ *   applyLayout(displayMode);
+ * }, [displayMode]);
+ * ```
+ */
+declare function useChatLayout(config?: ChatLayoutConfig): UseChatLayoutReturn;
+
+/**
+ * Hook to send messages to MCP Chat from anywhere in the app
+ *
+ * @example
+ * ```tsx
+ * function ErrorBoundary({ error }) {
+ *   const { sendToChat } = useMcpChat();
+ *
+ *   const explainError = () => {
+ *     sendToChat({
+ *       message: `Explain this error: ${error.message}`,
+ *       context: {
+ *         type: 'error',
+ *         data: { error: error.stack },
+ *         source: 'ErrorBoundary'
+ *       }
+ *     });
+ *   };
+ *
+ *   return <button onClick={explainError}>Explain Error</button>;
+ * }
+ * ```
+ */
+declare function useMcpChat(): UseMcpChatReturn;
+
+/**
+ * Platform Detection Types
+ */
+/**
+ * Platform detection result
+ */
+interface PlatformInfo {
+    isIOS: boolean;
+    isAndroid: boolean;
+    isDesktop: boolean;
+    isSafari: boolean;
+    isChrome: boolean;
+    isEdge: boolean;
+    isFirefox: boolean;
+    isStandalone: boolean;
+    canPrompt: boolean;
+    shouldShowAndroidPrompt: boolean;
+    shouldShowIOSGuide: boolean;
+}
+
+/**
+ * PWA Installation Types
+ */
+/**
+ * Install prompt state
+ */
+interface InstallPromptState {
+    isIOS: boolean;
+    isAndroid: boolean;
+    isSafari: boolean;
+    isChrome: boolean;
+    isInstalled: boolean;
+    canPrompt: boolean;
+    deferredPrompt: BeforeInstallPromptEvent | null;
+}
+/**
+ * BeforeInstallPrompt event (Android Chrome)
+ */
+interface BeforeInstallPromptEvent extends Event {
+    prompt: () => Promise<void>;
+    userChoice: Promise<{
+        outcome: 'accepted' | 'dismissed';
+        platform: string;
+    }>;
+}
+/**
+ * Install outcome
+ */
+type InstallOutcome = 'accepted' | 'dismissed' | null;
+/**
+ * iOS guide dismissal state
+ */
+interface IOSGuideState {
+    dismissed: boolean;
+    dismissedAt: number | null;
+    shouldShow: boolean;
+}
+
+/**
+ * Component Props Types
+ */
+
+/**
+ * Install context type
+ */
+interface InstallContextType {
+    platform: PlatformInfo;
+    isInstalled: boolean;
+    canPrompt: boolean;
+    showIOSGuide: boolean;
+    setShowIOSGuide: (show: boolean) => void;
+    promptInstall: () => Promise<InstallOutcome>;
+    dismissIOSGuide: () => void;
+}
+/**
+ * Install manager props
+ */
+interface InstallManagerProps {
+    /**
+     * Delay before showing iOS guide (ms)
+     * @default 2000
+     */
+    delayMs?: number;
+    /**
+     * Number of days before re-showing dismissed guide
+     * @default 7
+     */
+    resetDays?: number;
+    /**
+     * Custom class name for install button
+     */
+    buttonClassName?: string;
+    /**
+     * Custom button text
+     */
+    buttonText?: string;
+    /**
+     * Force show install UI (ignores platform detection)
+     * Useful for testing on desktop in development
+     * @default false
+     */
+    forceShow?: boolean;
+    /**
+     * Callback when install is successful
+     */
+    onInstallSuccess?: () => void;
+    /**
+     * Callback when install is dismissed
+     */
+    onInstallDismiss?: () => void;
+}
+/**
+ * Android install button props
+ */
+interface AndroidInstallButtonProps {
+    onInstall: () => Promise<InstallOutcome>;
+    className?: string;
+    text?: string;
+}
+/**
+ * iOS guide modal props
+ */
+interface IOSGuideModalProps {
+    onDismiss: () => void;
+    open?: boolean;
+}
+/**
+ * Install step for iOS guide
+ */
+interface InstallStep {
+    number: number;
+    title: string;
+    icon: React.ComponentType<{
+        className?: string;
+    }>;
+    description: string;
+}
+
+interface PwaContextValue {
+    isIOS: boolean;
+    isAndroid: boolean;
+    isDesktop: boolean;
+    isSafari: boolean;
+    isChrome: boolean;
+    isFirefox: boolean;
+    isEdge: boolean;
+    isOpera: boolean;
+    isBrave: boolean;
+    isArc: boolean;
+    isVivaldi: boolean;
+    isYandex: boolean;
+    isSamsungBrowser: boolean;
+    isUCBrowser: boolean;
+    isChromium: boolean;
+    browserName: string;
+    isInstalled: boolean;
+    canPrompt: boolean;
+    install: () => Promise<InstallOutcome>;
+}
+interface PwaConfig {
+    enabled?: boolean;
+}
+declare function PwaProvider({ children, ...config }: PwaConfig & {
+    children: ReactNode;
+}): react_jsx_runtime.JSX.Element;
+/**
+ * Use install context
+ * Must be used within <PwaProvider>
+ */
+declare function useInstall(): PwaContextValue;
+
+interface A2HSHintProps {
+    /**
+     * Additional class names for the container
+     */
+    className?: string;
+    /**
+     * Number of days before re-showing dismissed hint
+     * @default 3
+     * Set to null to never reset (show once forever)
+     */
+    resetAfterDays?: number | null;
+    /**
+     * Delay before showing hint (ms)
+     * @default 3000
+     */
+    delayMs?: number;
+    /**
+     * Demo mode - shows hint on all platforms with appropriate guides
+     * Production: only iOS Safari & Android Chrome
+     * Demo: shows on desktop too with desktop install guide
+     * @default false
+     */
+    demo?: boolean;
+    /**
+     * App logo URL to display in hint
+     * If not provided, uses Share icon
+     */
+    logo?: string;
+}
+declare function A2HSHint({ className, resetAfterDays, delayMs, demo, logo, }?: A2HSHintProps): react_jsx_runtime.JSX.Element;
+
+declare function IOSGuide(props: IOSGuideModalProps): react_jsx_runtime.JSX.Element;
+
+declare function DesktopGuide({ onDismiss, open }: IOSGuideModalProps): react_jsx_runtime.JSX.Element;
+
+/**
+ * Options for useIsPWA hook
+ */
+interface UseIsPWAOptions {
+    /**
+     * Use reliable check with additional validation for desktop browsers
+     * This prevents false positives on Safari macOS "Add to Dock"
+     * @default false
+     */
+    reliable?: boolean;
+}
+/**
+ * Hook to detect if app is running as PWA (standalone mode)
+ *
+ * @param options - Configuration options
+ * @returns true if app is running as PWA
+ */
+declare function useIsPWA(options?: UseIsPWAOptions): boolean;
+/**
+ * Clear isPWA cache
+ *
+ * Useful for testing or when you want to force a re-check
+ *
+ * @example
+ * ```typescript
+ * import { clearIsPWACache } from '@djangocfg/layouts/snippets';
+ * clearIsPWACache();
+ * window.location.reload();
+ * ```
+ */
+declare function clearIsPWACache(): void;
+
+/**
+ * Platform Detection Utilities
+ *
+ * Centralized utilities for detecting PWA state, platform, and capabilities.
+ * Used by hooks to avoid code duplication.
+ */
+/**
+ * Check if running as PWA (standalone mode)
+ *
+ * Checks if the app is running in standalone mode (added to home screen).
+ * This is the primary indicator that a PWA has been installed.
+ *
+ * @returns true if app is running in standalone mode
+ *
+ * @example
+ * ```typescript
+ * if (isStandalone()) {
+ *   console.log('Running as PWA');
+ * }
+ * ```
+ */
+declare function isStandalone(): boolean;
+/**
+ * Check if device is mobile
+ *
+ * @returns true if device is mobile (iOS, Android, etc.)
+ */
+declare function isMobileDevice(): boolean;
+/**
+ * Check if web app manifest exists and is valid
+ *
+ * @returns true if manifest link exists in document head
+ */
+declare function hasValidManifest(): boolean;
+/**
+ * Reliable check for PWA mode with edge case handling
+ *
+ * This function provides additional validation for desktop browsers
+ * to avoid false positives (e.g., Safari macOS "Add to Dock").
+ *
+ * For mobile devices, standard standalone check is sufficient.
+ * For desktop, additionally validates that a manifest exists.
+ *
+ * @returns true if app is running as a genuine PWA
+ *
+ * @example
+ * ```typescript
+ * // Use this for more reliable detection
+ * if (isStandaloneReliable()) {
+ *   console.log('Definitely running as PWA');
+ * }
+ * ```
+ */
+declare function isStandaloneReliable(): boolean;
+/**
+ * Get display mode from media query
+ *
+ * @returns Current display mode: 'standalone', 'fullscreen', 'minimal-ui', or 'browser'
+ */
+declare function getDisplayMode(): 'standalone' | 'fullscreen' | 'minimal-ui' | 'browser';
+/**
+ * Create a media query listener for display-mode changes
+ *
+ * @param callback - Function to call when display mode changes
+ * @returns Cleanup function to remove listener
+ *
+ * @example
+ * ```typescript
+ * const cleanup = onDisplayModeChange((isStandalone) => {
+ *   console.log('Display mode changed:', isStandalone);
+ * });
+ *
+ * // Later: cleanup();
+ * ```
+ */
+declare function onDisplayModeChange(callback: (isStandalone: boolean) => void): () => void;
+
+/**
+ * LocalStorage utilities for PWA install state persistence
+ */
+
+/**
+ * Clear all PWA install data
+ */
+declare function clearAllPWAInstallData(): void;
+
+/**
+ * Push Notification Types
+ */
+/**
+ * Push notification state
+ */
+interface PushNotificationState {
+    isSupported: boolean;
+    permission: NotificationPermission;
+    isSubscribed: boolean;
+    subscription: PushSubscription | null;
+}
+/**
+ * Push notification options
+ */
+interface PushNotificationOptions {
+    vapidPublicKey: string;
+    subscribeEndpoint?: string;
+}
+
+interface PushMessage {
+    id: string;
+    title: string;
+    body: string;
+    icon?: string;
+    badge?: string;
+    tag?: string;
+    timestamp: number;
+    data?: Record<string, unknown>;
+}
+interface DjangoPushContextValue {
+    isSupported: boolean;
+    permission: NotificationPermission;
+    isSubscribed: boolean;
+    subscription: PushSubscription | null;
+    isLoading: boolean;
+    error: Error | null;
+    pushes: PushMessage[];
+    subscribe: () => Promise<boolean>;
+    unsubscribe: () => Promise<boolean>;
+    sendTestPush: (message: {
+        title: string;
+        body: string;
+        url?: string;
+    }) => Promise<boolean>;
+    sendPush: (message: Omit<PushMessage, 'id' | 'timestamp'>) => Promise<void>;
+    clearPushes: () => void;
+    removePush: (id: string) => void;
+}
+interface DjangoPushProviderProps extends PushNotificationOptions {
+    children: React$1.ReactNode;
+    /**
+     * Auto-subscribe on mount if permission granted
+     * @default false
+     */
+    autoSubscribe?: boolean;
+    /**
+     * Callback when subscription created
+     */
+    onSubscribed?: (subscription: PushSubscription) => void;
+    /**
+     * Callback when subscription failed
+     */
+    onSubscribeError?: (error: Error) => void;
+    /**
+     * Callback when unsubscribed
+     */
+    onUnsubscribed?: () => void;
+}
+/**
+ * Provider for Django push notifications
+ */
+declare function DjangoPushProvider({ children, vapidPublicKey, autoSubscribe, onSubscribed, onSubscribeError, onUnsubscribed, }: DjangoPushProviderProps): react_jsx_runtime.JSX.Element;
+/**
+ * Hook to access Django push context
+ */
+declare function useDjangoPushContext(): DjangoPushContextValue;
+
+interface PushPromptProps extends PushNotificationOptions {
+    /**
+     * Only show if PWA is installed
+     * @default true
+     */
+    requirePWA?: boolean;
+    /**
+     * Delay before showing prompt (ms)
+     * @default 5000
+     */
+    delayMs?: number;
+    /**
+     * Number of days before re-showing dismissed prompt
+     * @default 7
+     */
+    resetAfterDays?: number;
+    /**
+     * Callback when push is enabled
+     */
+    onEnabled?: () => void;
+    /**
+     * Callback when push is dismissed
+     */
+    onDismissed?: () => void;
+}
+declare function PushPrompt({ vapidPublicKey, subscribeEndpoint, requirePWA, delayMs, resetAfterDays, onEnabled, onDismissed, }: PushPromptProps): react_jsx_runtime.JSX.Element;
+
+declare function usePushNotifications(options?: PushNotificationOptions): {
+    subscribe: () => Promise<PushSubscription | null>;
+    unsubscribe: () => Promise<boolean>;
+    isSupported: boolean;
+    permission: NotificationPermission;
+    isSubscribed: boolean;
+    subscription: PushSubscription | null;
+};
+
+interface UseDjangoPushOptions extends PushNotificationOptions {
+    /**
+     * Callback when subscription created
+     */
+    onSubscribed?: (subscription: PushSubscription) => void;
+    /**
+     * Callback when subscription failed
+     */
+    onSubscribeError?: (error: Error) => void;
+    /**
+     * Callback when unsubscribed
+     */
+    onUnsubscribed?: () => void;
+}
+interface UseDjangoPushReturn {
+    isSupported: boolean;
+    permission: NotificationPermission;
+    isSubscribed: boolean;
+    subscription: PushSubscription | null;
+    isLoading: boolean;
+    error: Error | null;
+    subscribe: () => Promise<boolean>;
+    unsubscribe: () => Promise<boolean>;
+    sendTestPush: (message: {
+        title: string;
+        body: string;
+        url?: string;
+    }) => Promise<boolean>;
+}
+/**
+ * Hook for Django-CFG push notifications integration
+ */
+declare function useDjangoPush(options: UseDjangoPushOptions): UseDjangoPushReturn;
+
+/**
+ * Push Notifications Configuration
+ *
+ * Centralized constants for push notifications functionality.
+ *
+ * SECURITY NOTE:
+ * - VAPID_PRIVATE_KEY should NEVER be in frontend code
+ * - Private keys must only exist in backend/API routes
+ * - Frontend only needs the public key (NEXT_PUBLIC_* env vars)
+ * - VAPID_MAILTO should also remain on backend only
+ */
+declare const DEFAULT_VAPID_PUBLIC_KEY: string;
+
+/**
+ * VAPID Key Utilities
+ *
+ * Provides validation and conversion utilities for VAPID public keys
+ * used in push notification subscriptions.
+ *
+ * VAPID keys must be:
+ * - Base64url encoded
+ * - 65 bytes after decoding (P-256 uncompressed public key)
+ * - Start with 0x04 (uncompressed point indicator)
+ */
+/**
+ * Custom error class for VAPID key validation failures
+ */
+declare class VapidKeyError extends Error {
+    readonly code: VapidKeyErrorCode;
+    constructor(message: string, code: VapidKeyErrorCode);
+}
+/**
+ * Error codes for VAPID key validation
+ */
+type VapidKeyErrorCode = 'VAPID_EMPTY' | 'VAPID_INVALID_TYPE' | 'VAPID_INVALID_BASE64' | 'VAPID_INVALID_LENGTH' | 'VAPID_INVALID_FORMAT';
+/**
+ * Convert base64url VAPID public key to Uint8Array
+ *
+ * Validates and converts a VAPID public key from base64url format
+ * to Uint8Array for use with PushManager.subscribe().
+ *
+ * @param base64String - VAPID public key in base64url format
+ * @returns Uint8Array ready for pushManager.subscribe()
+ * @throws VapidKeyError if key is invalid
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   const key = urlBase64ToUint8Array(process.env.NEXT_PUBLIC_VAPID_PUBLIC_KEY);
+ *   await registration.pushManager.subscribe({
+ *     userVisibleOnly: true,
+ *     applicationServerKey: key,
+ *   });
+ * } catch (e) {
+ *   if (e instanceof VapidKeyError) {
+ *     console.error('Invalid VAPID key:', e.message, e.code);
+ *   }
+ * }
+ * ```
+ */
+declare function urlBase64ToUint8Array(base64String: string): Uint8Array;
+/**
+ * Validate VAPID key without conversion
+ *
+ * Checks if a VAPID key is valid without converting it.
+ * Useful for validation before attempting subscription.
+ *
+ * @param base64String - VAPID public key to validate
+ * @returns true if key is valid
+ *
+ * @example
+ * ```typescript
+ * if (isValidVapidKey(vapidKey)) {
+ *   // Proceed with subscription
+ * } else {
+ *   console.error('Invalid VAPID key configuration');
+ * }
+ * ```
+ */
+declare function isValidVapidKey(base64String: string): boolean;
+/**
+ * Get VAPID key information for debugging
+ *
+ * Returns detailed information about a VAPID key for troubleshooting.
+ *
+ * @param base64String - VAPID public key to inspect
+ * @returns Key information object
+ *
+ * @example
+ * ```typescript
+ * const info = getVapidKeyInfo(process.env.NEXT_PUBLIC_VAPID_PUBLIC_KEY);
+ * console.log('VAPID Key Info:', info);
+ * // {
+ * //   valid: true,
+ * //   length: 65,
+ * //   firstByte: '0x04',
+ * //   format: 'P-256 uncompressed'
+ * // }
+ * ```
+ */
+declare function getVapidKeyInfo(base64String: string): {
+    valid: boolean;
+    length?: number;
+    firstByte?: string;
+    format?: string;
+    error?: string;
+    errorCode?: VapidKeyErrorCode;
+};
+/**
+ * Safe VAPID key conversion with error handling
+ *
+ * Attempts to convert a VAPID key with detailed error logging.
+ * Returns null on failure instead of throwing.
+ *
+ * @param base64String - VAPID public key
+ * @param onError - Optional error callback
+ * @returns Uint8Array or null if conversion fails
+ *
+ * @example
+ * ```typescript
+ * const key = safeUrlBase64ToUint8Array(vapidKey, (error) => {
+ *   console.error('VAPID conversion failed:', error.message, error.code);
+ * });
+ *
+ * if (key) {
+ *   // Use key for subscription
+ * }
+ * ```
+ */
+declare function safeUrlBase64ToUint8Array(base64String: string, onError?: (error: VapidKeyError) => void): Uint8Array | null;
+
+/**
+ * Clear all push notification data
+ */
+declare function clearAllPushData(): void;
+
+export { A2HSHint, type AIChatApiResponse, type AIChatContextActions, type AIChatContextState, type AIChatContextValue, type AIChatMessage, AIChatProvider, type AIChatProviderProps, type AIChatSource, AIChatWidget, type AIChatWidgetProps, AIMessageInput, type AIMessageInputProps, type AIMessageRole, AUTH_EVENTS, Analytics, AnalyticsCategory, type AnalyticsCategoryType, type AnalyticsConfig, AnalyticsEvent, type AnalyticsEventType, AnalyticsProvider, type AndroidInstallButtonProps, AskAIButton, type AskAIButtonProps, AuthDialog, type AuthEventType, type AuthFailurePayload, type AuthSuccessPayload, type BeforeInstallPromptEvent, type BreadcrumbItem, type ChatLayoutConfig, ChatPanel, type ChatWidgetConfig, DEFAULT_VAPID_PUBLIC_KEY, DIALOG_EVENTS, DesktopGuide, DjangoPushProvider, IOSGuide, type IOSGuideModalProps, type IOSGuideState, type InstallContextType, type InstallManagerProps, type InstallOutcome, type InstallPromptState, type InstallStep, type McpChatContextType, type McpChatEventDetail, MessageBubble, type MessageBubbleProps, type OpenAuthDialogPayload, type PlatformInfo, type PushMessage, type PushNotificationOptions, type PushNotificationState, PushPrompt, DjangoPushProvider as PushProvider, PwaProvider, type UseAIChatOptions, type UseAIChatReturn, type UseChatLayoutReturn, type UseIsPWAOptions, type UseMcpChatReturn, VapidKeyError, type VapidKeyErrorCode, clearAllPWAInstallData, clearAllPushData, clearIsPWACache, generateBreadcrumbsFromPath, getDisplayMode, getVapidKeyInfo, hasValidManifest, isMobileDevice, isStandalone, isStandaloneReliable, isValidVapidKey, onDisplayModeChange, safeUrlBase64ToUint8Array, urlBase64ToUint8Array, useAIChat, useAIChatContext, useAIChatContextOptional, useAnalytics, useAuthDialog, useChatLayout, useDjangoPush, useDjangoPushContext, useInstall, useIsPWA, useMcpChat, useDjangoPushContext as usePush, usePushNotifications };