@djangocfg/layouts 2.1.36 → 2.1.37

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

@@ -0,0 +1,203 @@
+/**
+ * LocalStorage utilities for PWA install state persistence
+ */
+
+import type { IOSGuideState } from '../types';
+
+/**
+ * Storage keys
+ */
+export const STORAGE_KEYS = {
+  IOS_GUIDE_DISMISSED: 'pwa_ios_guide_dismissed_at',
+  APP_INSTALLED: 'pwa_app_installed',
+  A2HS_DISMISSED: 'pwa_a2hs_dismissed_at',
+  PUSH_DISMISSED: 'pwa_push_dismissed_at',
+} as const;
+
+/**
+ * Check if iOS guide was dismissed recently
+ * @param resetDays Number of days before re-showing (default: 7)
+ */
+export function isDismissedRecently(resetDays: number = 7): boolean {
+  if (typeof window === 'undefined') return false;
+
+  try {
+    const dismissed = localStorage.getItem(STORAGE_KEYS.IOS_GUIDE_DISMISSED);
+    if (!dismissed) return false;
+
+    const dismissedAt = parseInt(dismissed, 10);
+    const now = Date.now();
+    const daysSinceDismissed = (now - dismissedAt) / (1000 * 60 * 60 * 24);
+
+    return daysSinceDismissed < resetDays;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Mark iOS guide as dismissed
+ */
+export function markIOSGuideDismissed(): void {
+  if (typeof window === 'undefined') return;
+
+  try {
+    localStorage.setItem(STORAGE_KEYS.IOS_GUIDE_DISMISSED, Date.now().toString());
+  } catch {
+    // Fail silently if localStorage is not available
+  }
+}
+
+/**
+ * Clear iOS guide dismissal
+ */
+export function clearIOSGuideDismissal(): void {
+  if (typeof window === 'undefined') return;
+
+  try {
+    localStorage.removeItem(STORAGE_KEYS.IOS_GUIDE_DISMISSED);
+  } catch {
+    // Fail silently
+  }
+}
+
+/**
+ * Get iOS guide state
+ */
+export function getIOSGuideState(resetDays: number = 7): IOSGuideState {
+  if (typeof window === 'undefined') {
+    return {
+      dismissed: false,
+      dismissedAt: null,
+      shouldShow: false,
+    };
+  }
+
+  try {
+    const dismissed = localStorage.getItem(STORAGE_KEYS.IOS_GUIDE_DISMISSED);
+    if (!dismissed) {
+      return {
+        dismissed: false,
+        dismissedAt: null,
+        shouldShow: true,
+      };
+    }
+
+    const dismissedAt = parseInt(dismissed, 10);
+    const now = Date.now();
+    const daysSinceDismissed = (now - dismissedAt) / (1000 * 60 * 60 * 24);
+
+    return {
+      dismissed: true,
+      dismissedAt,
+      shouldShow: daysSinceDismissed >= resetDays,
+    };
+  } catch {
+    return {
+      dismissed: false,
+      dismissedAt: null,
+      shouldShow: false,
+    };
+  }
+}
+
+/**
+ * Mark app as installed
+ */
+export function markAppInstalled(): void {
+  if (typeof window === 'undefined') return;
+
+  try {
+    localStorage.setItem(STORAGE_KEYS.APP_INSTALLED, 'true');
+    // Clear dismissal state when app is installed
+    clearIOSGuideDismissal();
+  } catch {
+    // Fail silently
+  }
+}
+
+/**
+ * Check if app is marked as installed
+ */
+export function isAppInstalled(): boolean {
+  if (typeof window === 'undefined') return false;
+
+  try {
+    return localStorage.getItem(STORAGE_KEYS.APP_INSTALLED) === 'true';
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Check if A2HS hint was dismissed recently
+ * @param resetDays Number of days before re-showing (default: 3)
+ */
+export function isA2HSDismissedRecently(resetDays: number = 3): boolean {
+  return isDismissedRecentlyHelper(resetDays, STORAGE_KEYS.A2HS_DISMISSED);
+}
+
+/**
+ * Mark A2HS hint as dismissed
+ */
+export function markA2HSDismissed(): void {
+  if (typeof window === 'undefined') return;
+  try {
+    localStorage.setItem(STORAGE_KEYS.A2HS_DISMISSED, Date.now().toString());
+  } catch {
+    // Fail silently
+  }
+}
+
+/**
+ * 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 PWA install data
+ */
+export function clearAllPWAData(): void {
+  if (typeof window === 'undefined') return;
+
+  try {
+    localStorage.removeItem(STORAGE_KEYS.IOS_GUIDE_DISMISSED);
+    localStorage.removeItem(STORAGE_KEYS.APP_INSTALLED);
+    localStorage.removeItem(STORAGE_KEYS.A2HS_DISMISSED);
+    localStorage.removeItem(STORAGE_KEYS.PUSH_DISMISSED);
+  } catch {
+    // Fail silently
+  }
+}

package/src/snippets/PWA/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/PWA/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);
+  };
+}