@djangocfg/ui-nextjs 2.1.227 → 2.1.229

package/src/pwa/hooks/usePWAPageResume.ts

@@ -0,0 +1,163 @@
+'use client';
+
+/**
+ * Hook to resume last page when opening PWA
+ *
+ * Saves current pathname on navigation and restores it when PWA is launched.
+ * Uses TTL-enabled localStorage to auto-expire saved page after 24 hours.
+ *
+ * @example
+ * ```typescript
+ * // In a component that wraps your app
+ * usePWAPageResume({ enabled: true });
+ * ```
+ */
+
+import { usePathname, useRouter } from 'next/navigation';
+import { useEffect, useRef } from 'react';
+
+import { useIsPWA } from './useIsPWA';
+
+const STORAGE_KEY = 'pwa_last_page';
+const TTL_24_HOURS = 24 * 60 * 60 * 1000;
+
+/**
+ * Default paths to exclude from saving
+ * These paths are typically transient or sensitive
+ */
+const DEFAULT_EXCLUDE_PATTERNS = [
+  '/auth',
+  '/login',
+  '/register',
+  '/error',
+  '/404',
+  '/500',
+  '/oauth',
+  '/callback',
+];
+
+/**
+ * Storage wrapper format with metadata (for TTL support)
+ */
+interface StorageWrapper {
+  _meta: {
+    createdAt: number;
+    ttl: number;
+  };
+  _value: string;
+}
+
+/**
+ * Check if path should be excluded from saving
+ */
+function isExcludedPath(pathname: string): boolean {
+  return DEFAULT_EXCLUDE_PATTERNS.some(pattern =>
+    pathname === pattern || pathname.startsWith(`${pattern}/`)
+  );
+}
+
+/**
+ * Read last page from localStorage with TTL check
+ */
+function readLastPage(): string | null {
+  if (typeof window === 'undefined') return null;
+
+  try {
+    const item = localStorage.getItem(STORAGE_KEY);
+    if (!item) return null;
+
+    const parsed = JSON.parse(item) as StorageWrapper;
+
+    // Check if it's the wrapped format with _meta
+    if (parsed && typeof parsed === 'object' && '_meta' in parsed && '_value' in parsed) {
+      // Check TTL expiration
+      const age = Date.now() - parsed._meta.createdAt;
+      if (age > parsed._meta.ttl) {
+        // Expired! Clean up
+        localStorage.removeItem(STORAGE_KEY);
+        return null;
+      }
+      return parsed._value;
+    }
+
+    // Old format (backwards compatible) - treat as string
+    return item;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Save page to localStorage with TTL
+ */
+function saveLastPage(pathname: string): void {
+  if (typeof window === 'undefined') return;
+
+  try {
+    const wrapped: StorageWrapper = {
+      _meta: {
+        createdAt: Date.now(),
+        ttl: TTL_24_HOURS,
+      },
+      _value: pathname,
+    };
+    localStorage.setItem(STORAGE_KEY, JSON.stringify(wrapped));
+  } catch {
+    // Ignore localStorage errors
+  }
+}
+
+export interface UsePWAPageResumeOptions {
+  /**
+   * Enable page resume feature
+   * @default true
+   */
+  enabled?: boolean;
+}
+
+export interface UsePWAPageResumeReturn {
+  /** Whether app is running as PWA */
+  isPWA: boolean;
+}
+
+/**
+ * Hook to resume last page when opening PWA
+ *
+ * - Saves current pathname on every navigation (always, not just in PWA mode)
+ * - Restores last page on PWA launch (only once per session)
+ * - Auto-excludes auth, error, and callback pages
+ * - Uses TTL (24 hours) to auto-expire saved page
+ *
+ * @param options - Configuration options
+ * @returns Object with isPWA state
+ */
+export function usePWAPageResume(options: UsePWAPageResumeOptions = {}): UsePWAPageResumeReturn {
+  const { enabled = true } = options;
+  const pathname = usePathname();
+  const router = useRouter();
+  const isPWA = useIsPWA();
+  const hasResumed = useRef(false);
+
+  // Resume on PWA launch (only once)
+  useEffect(() => {
+    if (!enabled || !isPWA || hasResumed.current) return;
+
+    hasResumed.current = true;
+
+    const lastPage = readLastPage();
+    if (lastPage && lastPage !== pathname && !isExcludedPath(lastPage)) {
+      router.replace(lastPage);
+    }
+  }, [isPWA, enabled]); // eslint-disable-line react-hooks/exhaustive-deps
+
+  // Save current page on navigation
+  // Save ALWAYS (not just in PWA mode) because user might install PWA after browsing
+  useEffect(() => {
+    if (!enabled) return;
+    if (isExcludedPath(pathname)) return;
+
+    saveLastPage(pathname);
+  }, [pathname, enabled]);
+
+  return { isPWA };
+}

package/src/pwa/index.ts

@@ -0,0 +1,80 @@
+/**
+ * PWA Install Snippet
+ *
+ * Simplified PWA installation for web apps
+ * Handles Add to Home Screen (A2HS) for iOS Safari and Android Chrome
+ *
+ * @example Basic usage
+ * ```tsx
+ * import { PwaProvider, A2HSHint } from '@/snippets/PWAInstall';
+ *
+ * export default function Layout({ children }) {
+ *   return (
+ *     <PwaProvider>
+ *       {children}
+ *       <A2HSHint resetAfterDays={3} />
+ *     </PwaProvider>
+ *   );
+ * }
+ * ```
+ */
+
+// Main API
+export { PwaProvider, useInstall } from './context/InstallContext';
+export { A2HSHint } from './components/A2HSHint';
+export { IOSGuide } from './components/IOSGuide';
+export { DesktopGuide } from './components/DesktopGuide';
+
+// Hooks
+export { useIsPWA, clearIsPWACache, type UseIsPWAOptions } from './hooks/useIsPWA';
+export { usePWAPageResume, type UsePWAPageResumeOptions, type UsePWAPageResumeReturn } from './hooks/usePWAPageResume';
+
+// Page Resume Manager
+export { PWAPageResumeManager } from './components/PWAPageResumeManager';
+
+// Utilities
+export {
+  isStandalone,
+  isStandaloneReliable,
+  isMobileDevice,
+  hasValidManifest,
+  getDisplayMode,
+  onDisplayModeChange,
+} from './utils/platform';
+
+export {
+  pwaLogger,
+  enablePWADebug,
+  disablePWADebug,
+  isPWADebugEnabled,
+} from './utils/logger';
+
+export {
+  STORAGE_KEYS,
+  markA2HSDismissed,
+  isA2HSDismissedRecently,
+  clearAllPWAInstallData,
+} from './utils/localStorage';
+
+// Types - Configuration
+export type { PwaInstallConfig } from './types';
+
+// Types - Platform
+export type { PlatformInfo } from './types';
+
+// Types - Install
+export type {
+  InstallPromptState,
+  BeforeInstallPromptEvent,
+  InstallOutcome,
+  IOSGuideState,
+} from './types';
+
+// Types - Components
+export type {
+  InstallContextType,
+  InstallManagerProps,
+  AndroidInstallButtonProps,
+  IOSGuideModalProps,
+  InstallStep,
+} from './types';

package/src/pwa/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/pwa/types/config.ts

@@ -0,0 +1,29 @@
+/**
+ * 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;
+
+  /**
+   * Resume last page when opening PWA
+   * When enabled, saves current pathname on navigation and restores it on PWA launch
+   * @default false
+   */
+  resumeLastPage?: boolean;
+}

package/src/pwa/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/pwa/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/pwa/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/pwa/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
+  }
+}