@djangocfg/layouts 2.1.36 → 2.1.38

package/src/snippets/PWAInstall/types/components.ts

@@ -0,0 +1,95 @@
+/**
+ * Component Props Types
+ */
+
+import type { PlatformInfo } from './platform';
+import type { InstallOutcome } from './install';
+
+/**
+ * Install context type
+ */
+export interface InstallContextType {
+  // State
+  platform: PlatformInfo;
+  isInstalled: boolean;
+  canPrompt: boolean;
+
+  // iOS Guide
+  showIOSGuide: boolean;
+  setShowIOSGuide: (show: boolean) => void;
+
+  // Actions
+  promptInstall: () => Promise<InstallOutcome>;
+  dismissIOSGuide: () => void;
+}
+
+/**
+ * Install manager props
+ */
+export 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
+ */
+export interface AndroidInstallButtonProps {
+  onInstall: () => Promise<InstallOutcome>;
+  className?: string;
+  text?: string;
+}
+
+/**
+ * iOS guide modal props
+ */
+export interface IOSGuideModalProps {
+  onDismiss: () => void;
+  open?: boolean;
+}
+
+/**
+ * Install step for iOS guide
+ */
+export interface InstallStep {
+  number: number;
+  title: string;
+  icon: React.ComponentType<{ className?: string }>;
+  description: string;
+}

package/src/snippets/PWAInstall/types/config.ts

@@ -0,0 +1,22 @@
+/**
+ * PWA Install Configuration Types
+ *
+ * Configuration for Progressive Web App installation features
+ */
+
+export interface PwaInstallConfig {
+  /** Enable PWA installation features */
+  enabled?: boolean;
+
+  /** Show A2HS (Add to Home Screen) hint (enabled by default when enabled is true) */
+  showInstallHint?: boolean;
+
+  /** Number of days before re-showing dismissed hint (null = never show again) */
+  resetAfterDays?: number | null;
+
+  /** Delay before showing hint (ms) */
+  delayMs?: number;
+
+  /** App logo URL to display in hint */
+  logo?: string;
+}

package/src/snippets/PWAInstall/types/index.ts

@@ -0,0 +1,26 @@
+/**
+ * PWA Install Types - Central Export
+ */
+
+// Configuration
+export type { PwaInstallConfig } from './config';
+
+// Platform
+export type { PlatformInfo } from './platform';
+
+// Install
+export type {
+  InstallPromptState,
+  BeforeInstallPromptEvent,
+  InstallOutcome,
+  IOSGuideState,
+} from './install';
+
+// Components
+export type {
+  InstallContextType,
+  InstallManagerProps,
+  AndroidInstallButtonProps,
+  IOSGuideModalProps,
+  InstallStep,
+} from './components';

package/src/snippets/PWAInstall/types/install.ts

@@ -0,0 +1,38 @@
+/**
+ * PWA Installation Types
+ */
+
+/**
+ * Install prompt state
+ */
+export interface InstallPromptState {
+  isIOS: boolean;
+  isAndroid: boolean;
+  isSafari: boolean;
+  isChrome: boolean;
+  isInstalled: boolean;
+  canPrompt: boolean;
+  deferredPrompt: BeforeInstallPromptEvent | null;
+}
+
+/**
+ * BeforeInstallPrompt event (Android Chrome)
+ */
+export interface BeforeInstallPromptEvent extends Event {
+  prompt: () => Promise<void>;
+  userChoice: Promise<{ outcome: 'accepted' | 'dismissed'; platform: string }>;
+}
+
+/**
+ * Install outcome
+ */
+export type InstallOutcome = 'accepted' | 'dismissed' | null;
+
+/**
+ * iOS guide dismissal state
+ */
+export interface IOSGuideState {
+  dismissed: boolean;
+  dismissedAt: number | null;
+  shouldShow: boolean;
+}

package/src/snippets/PWAInstall/types/platform.ts

@@ -0,0 +1,29 @@
+/**
+ * Platform Detection Types
+ */
+
+/**
+ * Platform detection result
+ */
+export interface PlatformInfo {
+  // Operating System
+  isIOS: boolean;
+  isAndroid: boolean;
+  isDesktop: boolean;
+
+  // Browser
+  isSafari: boolean;
+  isChrome: boolean;
+  isEdge: boolean;
+  isFirefox: boolean;
+
+  // Installation State
+  isStandalone: boolean;
+
+  // Capability
+  canPrompt: boolean;
+
+  // Composite checks
+  shouldShowAndroidPrompt: boolean;
+  shouldShowIOSGuide: boolean;
+}

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

@@ -0,0 +1,181 @@
+/**
+ * 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',
+} 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
+  }
+}
+
+/**
+ * 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 clearAllPWAInstallData(): 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);
+  } catch {
+    // Fail silently
+  }
+}

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