@djangocfg/layouts 2.1.37 → 2.1.39

package/src/snippets/PushNotifications/utils/localStorage.ts

@@ -0,0 +1,60 @@
+/**
+ * LocalStorage utilities for Push Notifications state persistence
+ */
+
+/**
+ * Storage keys
+ */
+export const STORAGE_KEYS = {
+  PUSH_DISMISSED: 'pwa_push_dismissed_at',
+} as const;
+
+/**
+ * Check if push prompt was dismissed recently
+ * @param resetDays Number of days before re-showing (default: 7)
+ */
+export function isPushDismissedRecently(resetDays: number = 7): boolean {
+  return isDismissedRecentlyHelper(resetDays, STORAGE_KEYS.PUSH_DISMISSED);
+}
+
+/**
+ * Mark push prompt as dismissed
+ */
+export function markPushDismissed(): void {
+  if (typeof window === 'undefined') return;
+  try {
+    localStorage.setItem(STORAGE_KEYS.PUSH_DISMISSED, Date.now().toString());
+  } catch {
+    // Fail silently
+  }
+}
+
+/**
+ * Helper: Check if a key was dismissed recently
+ * @internal
+ */
+function isDismissedRecentlyHelper(resetDays: number, key: string): boolean {
+  if (typeof window === 'undefined') return false;
+  try {
+    const dismissed = localStorage.getItem(key);
+    if (!dismissed) return false;
+    const dismissedAt = parseInt(dismissed, 10);
+    const daysSince = (Date.now() - dismissedAt) / (1000 * 60 * 60 * 24);
+    return daysSince < resetDays;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Clear all push notification data
+ */
+export function clearAllPushData(): void {
+  if (typeof window === 'undefined') return;
+
+  try {
+    localStorage.removeItem(STORAGE_KEYS.PUSH_DISMISSED);
+  } catch {
+    // Fail silently
+  }
+}

package/src/snippets/PushNotifications/utils/logger.ts

@@ -0,0 +1,149 @@
+/**
+ * PWA Logger with Conditional Logging
+ *
+ * Provides logging utilities that respect environment and debug settings:
+ * - In production: Only errors are logged
+ * - In development: All levels are logged
+ * - Debug mode: Can be enabled in production via localStorage
+ *
+ * @example
+ * ```typescript
+ * import { pwaLogger } from '../utils/logger';
+ *
+ * pwaLogger.info('Info message'); // Only in dev
+ * pwaLogger.warn('Warning message'); // Only in dev
+ * pwaLogger.error('Error message'); // Always logged
+ * pwaLogger.debug('Debug message'); // Only when debug enabled
+ * ```
+ *
+ * Enable debug mode in production:
+ * ```typescript
+ * import { enablePWADebug } from '../utils/logger';
+ * enablePWADebug();
+ * // or in console:
+ * localStorage.setItem('pwa_debug', 'true');
+ * ```
+ */
+
+import { consola } from 'consola';
+
+const isDevelopment = process.env.NODE_ENV === 'development';
+
+/**
+ * Check if debug mode is enabled via localStorage
+ */
+function isDebugEnabled(): boolean {
+  if (typeof window === 'undefined') return false;
+  try {
+    return localStorage.getItem('pwa_debug') === 'true';
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * PWA Logger instance with conditional logging
+ */
+export const pwaLogger = {
+  /**
+   * Info level logging
+   * Only logs in development or when debug is enabled
+   */
+  info: (...args: Parameters<typeof consola.info>): void => {
+    if (isDevelopment || isDebugEnabled()) {
+      consola.info(...args);
+    }
+  },
+
+  /**
+   * Warning level logging
+   * Only logs in development or when debug is enabled
+   */
+  warn: (...args: Parameters<typeof consola.warn>): void => {
+    if (isDevelopment || isDebugEnabled()) {
+      consola.warn(...args);
+    }
+  },
+
+  /**
+   * Error level logging
+   * Always logs (production + development)
+   */
+  error: (...args: Parameters<typeof consola.error>): void => {
+    consola.error(...args);
+  },
+
+  /**
+   * Debug level logging
+   * Only logs when debug is explicitly enabled
+   */
+  debug: (...args: Parameters<typeof consola.debug>): void => {
+    if (isDebugEnabled()) {
+      consola.debug(...args);
+    }
+  },
+
+  /**
+   * Success level logging
+   * Only logs in development or when debug is enabled
+   */
+  success: (...args: Parameters<typeof consola.success>): void => {
+    if (isDevelopment || isDebugEnabled()) {
+      consola.success(...args);
+    }
+  },
+};
+
+/**
+ * Enable debug mode
+ *
+ * This allows seeing debug logs in production.
+ * Call this function or set localStorage manually:
+ * `localStorage.setItem('pwa_debug', 'true')`
+ *
+ * @example
+ * ```typescript
+ * import { enablePWADebug } from '@djangocfg/layouts/snippets';
+ * enablePWADebug();
+ * // Reload page to see debug logs
+ * ```
+ */
+export function enablePWADebug(): void {
+  if (typeof window !== 'undefined') {
+    try {
+      localStorage.setItem('pwa_debug', 'true');
+      consola.info('[PWA] Debug mode enabled. Reload page to see debug logs.');
+    } catch (e) {
+      consola.error('[PWA] Failed to enable debug mode:', e);
+    }
+  }
+}
+
+/**
+ * Disable debug mode
+ *
+ * @example
+ * ```typescript
+ * import { disablePWADebug } from '@djangocfg/layouts/snippets';
+ * disablePWADebug();
+ * ```
+ */
+export function disablePWADebug(): void {
+  if (typeof window !== 'undefined') {
+    try {
+      localStorage.removeItem('pwa_debug');
+      consola.info('[PWA] Debug mode disabled.');
+    } catch (e) {
+      consola.error('[PWA] Failed to disable debug mode:', e);
+    }
+  }
+}
+
+/**
+ * Check if debug mode is currently active
+ *
+ * @returns true if debug mode is enabled
+ */
+export function isPWADebugEnabled(): boolean {
+  return isDebugEnabled();
+}

package/src/snippets/PushNotifications/utils/platform.ts

@@ -0,0 +1,151 @@
+/**
+ * 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');
+ * }
+ * ```
+ */
+export function isStandalone(): boolean {
+  if (typeof window === 'undefined') return false;
+
+  // Fallback for older browsers without matchMedia
+  if (!window.matchMedia) {
+    // Use legacy iOS check only
+    const nav = navigator as Navigator & { standalone?: boolean };
+    return nav.standalone === true;
+  }
+
+  // Check display-mode media query (modern approach)
+  const isStandaloneDisplay = window.matchMedia('(display-mode: standalone)').matches;
+
+  // Legacy iOS check (navigator.standalone)
+  const nav = navigator as Navigator & { standalone?: boolean };
+  const isStandaloneNavigator = nav.standalone === true;
+
+  return isStandaloneDisplay || isStandaloneNavigator;
+}
+
+/**
+ * Check if device is mobile
+ *
+ * @returns true if device is mobile (iOS, Android, etc.)
+ */
+export function isMobileDevice(): boolean {
+  if (typeof window === 'undefined') return false;
+  return /iPhone|iPad|iPod|Android/i.test(navigator.userAgent);
+}
+
+/**
+ * Check if web app manifest exists and is valid
+ *
+ * @returns true if manifest link exists in document head
+ */
+export function hasValidManifest(): boolean {
+  if (typeof document === 'undefined') return false;
+  const manifestLink = document.querySelector('link[rel="manifest"]');
+  return !!manifestLink;
+}
+
+/**
+ * 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');
+ * }
+ * ```
+ */
+export function isStandaloneReliable(): boolean {
+  const standalone = isStandalone();
+  if (!standalone) return false;
+
+  // For mobile devices, standalone check is sufficient
+  if (isMobileDevice()) return true;
+
+  // For desktop browsers, additionally check for valid manifest
+  // This prevents false positives like Safari macOS "Add to Dock"
+  return hasValidManifest();
+}
+
+/**
+ * Get display mode from media query
+ *
+ * @returns Current display mode: 'standalone', 'fullscreen', 'minimal-ui', or 'browser'
+ */
+export function getDisplayMode(): 'standalone' | 'fullscreen' | 'minimal-ui' | 'browser' {
+  if (typeof window === 'undefined') return 'browser';
+
+  if (!window.matchMedia) return 'browser';
+
+  const modes: Array<'standalone' | 'fullscreen' | 'minimal-ui'> = [
+    'fullscreen',
+    'standalone',
+    'minimal-ui',
+  ];
+
+  for (const mode of modes) {
+    if (window.matchMedia(`(display-mode: ${mode})`).matches) {
+      return mode;
+    }
+  }
+
+  return '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();
+ * ```
+ */
+export function onDisplayModeChange(callback: (isStandalone: boolean) => void): () => void {
+  if (typeof window === 'undefined' || !window.matchMedia) {
+    return () => {}; // No-op cleanup
+  }
+
+  const mediaQuery = window.matchMedia('(display-mode: standalone)');
+
+  const handleChange = (e: MediaQueryListEvent) => {
+    callback(e.matches);
+  };
+
+  mediaQuery.addEventListener('change', handleChange);
+
+  return () => {
+    mediaQuery.removeEventListener('change', handleChange);
+  };
+}

package/src/snippets/index.ts

@@ -44,32 +44,57 @@ export type {
   AskAIButtonProps,
 } from './McpChat';
 
-// PWA (Progressive Web App)
+// PWA Install (Progressive Web App Installation)
 export {
   PwaProvider,
   useInstall,
-  PushProvider,
-  usePush,
   A2HSHint,
-  PushPrompt,
+  IOSGuide,
+  DesktopGuide,
   useIsPWA,
-  usePushNotifications,
-  DEFAULT_VAPID_PUBLIC_KEY,
-  clearAllPWAData,
-} from './PWA';
+  clearIsPWACache,
+  clearAllPWAInstallData,
+  isStandalone,
+  isStandaloneReliable,
+  isMobileDevice,
+  hasValidManifest,
+  getDisplayMode,
+  onDisplayModeChange,
+} from './PWAInstall';
 export type {
   PlatformInfo,
   InstallPromptState,
   BeforeInstallPromptEvent,
   InstallOutcome,
   IOSGuideState,
-  PushNotificationState,
-  PushNotificationOptions,
   InstallContextType,
   InstallManagerProps,
   AndroidInstallButtonProps,
   IOSGuideModalProps,
   InstallStep,
+  UseIsPWAOptions,
+} from './PWAInstall';
+
+// Push Notifications
+export {
+  PushProvider,
+  usePush,
+  DjangoPushProvider,
+  useDjangoPushContext,
+  PushPrompt,
+  usePushNotifications,
+  useDjangoPush,
+  DEFAULT_VAPID_PUBLIC_KEY,
+  urlBase64ToUint8Array,
+  isValidVapidKey,
+  getVapidKeyInfo,
+  safeUrlBase64ToUint8Array,
+  VapidKeyError,
+  clearAllPushData,
+} from './PushNotifications';
+export type {
+  PushNotificationState,
+  PushNotificationOptions,
   PushMessage,
-  PushContextValue,
-} from './PWA';
+  VapidKeyErrorCode,
+} from './PushNotifications';

package/src/layouts/shared/index.ts

@@ -1,21 +0,0 @@
-/**
- * Shared Layouts Exports
- */
-
-export type {
-  ThemeConfig,
-  LayoutErrorTrackingConfig,
-  ErrorBoundaryConfig,
-  SWRConfigOptions,
-  McpChatConfig,
-  BaseLayoutProps,
-  NavigationItem,
-  NavigationSection,
-  FooterLink,
-  FooterMenuSection,
-  FooterSocialLinks,
-  FooterConfig,
-  UserMenuItem,
-  UserMenuGroup,
-  UserMenuConfig,
-} from './types';

package/src/layouts/shared/types.ts

@@ -1,247 +0,0 @@
-/**
- * Shared Types for All Layouts
- *
- * Universal type system to avoid duplication across layouts
- */
-
-import type { ReactNode } from 'react';
-import type { LucideIcon } from 'lucide-react';
-import type { AuthConfig } from '@djangocfg/api/auth';
-
-// ============================================================================
-// Theme Configuration
-// ============================================================================
-
-export interface ThemeConfig {
-  defaultTheme?: 'light' | 'dark' | 'system';
-  storageKey?: string;
-}
-
-// ============================================================================
-// Error Tracking Configuration
-// ============================================================================
-
-/**
- * Error tracking configuration for layouts
- * Note: Import detailed types from @djangocfg/layouts/components if needed
- */
-export interface LayoutErrorTrackingConfig {
-  validation?: {
-    enabled?: boolean;
-    showToast?: boolean;
-  };
-  cors?: {
-    enabled?: boolean;
-    showToast?: boolean;
-  };
-  network?: {
-    enabled?: boolean;
-    showToast?: boolean;
-  };
-  onError?: (error: any) => boolean | void;
-}
-
-// ============================================================================
-// Error Boundary Configuration
-// ============================================================================
-
-export interface ErrorBoundaryConfig {
-  enabled?: boolean;
-  supportEmail?: string;
-  onError?: (error: Error, errorInfo: React.ErrorInfo) => void;
-}
-
-// ============================================================================
-// SWR Configuration
-// ============================================================================
-
-export interface SWRConfigOptions {
-  revalidateOnFocus?: boolean;
-  revalidateOnReconnect?: boolean;
-  dedupingInterval?: number;
-}
-
-// ============================================================================
-// MCP Chat Configuration
-// ============================================================================
-
-export interface McpChatConfig {
-  /** Enable MCP chat widget */
-  enabled?: boolean;
-  /** API endpoint for chat */
-  apiEndpoint?: string;
-  /** Chat widget title */
-  title?: string;
-  /** Input placeholder */
-  placeholder?: string;
-  /** Greeting message */
-  greeting?: string;
-  /** Widget position */
-  position?: 'bottom-right' | 'bottom-left';
-  /** Widget variant */
-  variant?: 'default' | 'minimal';
-  /** Enable streaming responses */
-  enableStreaming?: boolean;
-  /** Auto-detect environment (dev/prod) */
-  autoDetectEnvironment?: boolean;
-  /** Custom class name */
-  className?: string;
-}
-
-// ============================================================================
-// PWA Configuration
-// ============================================================================
-
-export interface PwaConfig {
-  /** Enable PWA provider and features */
-  enabled?: boolean;
-
-  /** Show A2HS hint (enabled by default when pwa.enabled is true) */
-  showInstallHint?: boolean;
-
-  /** Number of days before re-showing dismissed hint */
-  resetAfterDays?: number | null;
-
-  /** Delay before showing hint (ms) */
-  delayMs?: number;
-
-  /** App logo URL to display in hint */
-  logo?: string;
-
-  /** Push notifications configuration */
-  pushNotifications?: {
-    /** VAPID public key for push notifications */
-    vapidPublicKey: string;
-    /** API endpoint for subscription */
-    subscribeEndpoint?: string;
-    /** Delay before showing push prompt after PWA install (ms) */
-    delayMs?: number;
-    /** Number of days before re-showing dismissed push prompt */
-    resetAfterDays?: number;
-  };
-}
-
-// ============================================================================
-// Base Layout Props
-// ============================================================================
-
-export interface BaseLayoutProps {
-  children: ReactNode;
-
-  /** Theme configuration */
-  theme?: ThemeConfig;
-
-  /** Auth configuration */
-  auth?: AuthConfig;
-
-  /** Error tracking configuration */
-  errorTracking?: LayoutErrorTrackingConfig;
-
-  /** SWR configuration */
-  swr?: SWRConfigOptions;
-
-  /** Error boundary configuration (enabled by default) */
-  errorBoundary?: ErrorBoundaryConfig;
-
-  /** MCP chat configuration */
-  mcpChat?: McpChatConfig;
-
-  /** PWA configuration */
-  pwa?: PwaConfig;
-}
-
-// ============================================================================
-// Navigation Types
-// ============================================================================
-
-export interface NavigationItem {
-  label: string;
-  href: string;
-  icon?: LucideIcon | string;
-  badge?: string | number;
-  external?: boolean;
-}
-
-export interface NavigationSection {
-  title?: string;
-  items: NavigationItem[];
-}
-
-// ============================================================================
-// Footer Types
-// ============================================================================
-
-export interface FooterLink {
-  label: string;
-  path: string;
-  external?: boolean;
-}
-
-export interface FooterMenuSection {
-  title: string;
-  items: FooterLink[];
-}
-
-export interface FooterSocialLinks {
-  github?: string;
-  linkedin?: string;
-  twitter?: string;
-  telegram?: string;
-  youtube?: string;
-  facebook?: string;
-  instagram?: string;
-  whatsapp?: string;
-  email?: string;
-}
-
-export interface FooterConfig {
-  siteName?: string;
-  description?: string;
-  logo?: string;
-  badge?: {
-    icon: LucideIcon;
-    text: string;
-  };
-  socialLinks?: FooterSocialLinks;
-  links?: FooterLink[];
-  menuSections?: FooterMenuSection[];
-  copyright?: string;
-  credits?: {
-    text: string;
-    url?: string;
-  };
-  variant?: 'full' | 'simple';
-}
-
-// ============================================================================
-// User Menu Types
-// ============================================================================
-
-export interface UserMenuItem {
-  /** Menu item label */
-  label: string;
-  /** Link href (optional if onClick is provided) */
-  href?: string;
-  /** Icon component */
-  icon?: LucideIcon;
-  /** Visual variant */
-  variant?: 'default' | 'destructive';
-  /** Click handler (optional if href is provided) */
-  onClick?: () => void;
-  /** Open link in new tab */
-  external?: boolean;
-}
-
-export interface UserMenuGroup {
-  /** Optional group title (renders DropdownMenuLabel) */
-  title?: string;
-  /** Menu items in this group */
-  items: UserMenuItem[];
-}
-
-export interface UserMenuConfig {
-  /** Menu groups for authenticated users */
-  groups?: UserMenuGroup[];
-  /** Auth page path (for sign in button) */
-  authPath?: string;
-}