@djangocfg/layouts 2.1.36 → 2.1.38

package/src/snippets/PWAInstall/components/IOSGuideDrawer.tsx

@@ -0,0 +1,101 @@
+'use client';
+
+/**
+ * iOS Installation Guide Drawer (Mobile-Optimized)
+ *
+ * Bottom drawer with swipe gestures for iOS installation guide
+ * Better UX for mobile devices
+ */
+
+import React from 'react';
+import { Share, Check, ArrowUpRight, ArrowDown, CheckCircle } from 'lucide-react';
+
+import {
+  Drawer,
+  DrawerContent,
+  DrawerDescription,
+  DrawerHeader,
+  DrawerTitle,
+  Button,
+  Card,
+  CardContent,
+} from '@djangocfg/ui-nextjs';
+
+import type { IOSGuideModalProps, InstallStep } from '../types';
+
+const steps: InstallStep[] = [
+  {
+    number: 1,
+    title: 'Tap Share',
+    icon: ArrowUpRight,
+    description: 'At the bottom of Safari',
+  },
+  {
+    number: 2,
+    title: 'Scroll & Tap',
+    icon: ArrowDown,
+    description: '"Add to Home Screen"',
+  },
+  {
+    number: 3,
+    title: 'Confirm',
+    icon: CheckCircle,
+    description: 'Tap "Add" in top-right',
+  },
+];
+
+function StepCard({ step }: { step: InstallStep }) {
+  return (
+    <Card className="border border-border">
+      <CardContent className="p-4">
+        <div className="flex items-start gap-3">
+          <div
+            className="flex items-center justify-center rounded-full bg-primary text-primary-foreground flex-shrink-0"
+            style={{ width: '32px', height: '32px' }}
+          >
+            <span className="text-sm font-semibold">{step.number}</span>
+          </div>
+
+          <div className="flex-1 min-w-0">
+            <div className="flex items-center gap-2 mb-1">
+              <step.icon className="w-5 h-5 text-primary" />
+              <h3 className="font-semibold text-foreground">{step.title}</h3>
+            </div>
+            <p className="text-sm text-muted-foreground">{step.description}</p>
+          </div>
+        </div>
+      </CardContent>
+    </Card>
+  );
+}
+
+export function IOSGuideDrawer({ onDismiss, open = true }: IOSGuideModalProps) {
+  return (
+    <Drawer open={open} onOpenChange={(isOpen) => !isOpen && onDismiss()}>
+      <DrawerContent>
+        <DrawerHeader className="text-left">
+          <DrawerTitle className="flex items-center gap-2">
+            <Share className="w-5 h-5 text-primary" />
+            Add to Home Screen
+          </DrawerTitle>
+          <DrawerDescription className="text-left">
+            Install this app on your iPhone for quick access and a better experience
+          </DrawerDescription>
+        </DrawerHeader>
+
+        <div className="space-y-3 p-4">
+          {steps.map((step) => (
+            <StepCard key={step.number} step={step} />
+          ))}
+        </div>
+
+        <div className="p-4 pt-0">
+          <Button onClick={onDismiss} variant="default" className="w-full">
+            <Check className="w-4 h-4 mr-2" />
+            Got It
+          </Button>
+        </div>
+      </DrawerContent>
+    </Drawer>
+  );
+}

package/src/snippets/PWAInstall/components/IOSGuideModal.tsx

@@ -0,0 +1,101 @@
+'use client';
+
+/**
+ * iOS Installation Guide Modal
+ *
+ * Visual step-by-step guide for adding PWA to home screen on iOS Safari
+ */
+
+import React from 'react';
+import { Share, Check, ArrowUpRight, ArrowDown, CheckCircle } from 'lucide-react';
+
+import {
+  Dialog,
+  DialogContent,
+  DialogDescription,
+  DialogFooter,
+  DialogHeader,
+  DialogTitle,
+  Button,
+  Card,
+  CardContent,
+} from '@djangocfg/ui-nextjs';
+
+import type { IOSGuideModalProps, InstallStep } from '../types';
+
+const steps: InstallStep[] = [
+  {
+    number: 1,
+    title: 'Tap Share',
+    icon: ArrowUpRight,
+    description: 'At the bottom of Safari',
+  },
+  {
+    number: 2,
+    title: 'Scroll & Tap',
+    icon: ArrowDown,
+    description: '"Add to Home Screen"',
+  },
+  {
+    number: 3,
+    title: 'Confirm',
+    icon: CheckCircle,
+    description: 'Tap "Add" in top-right',
+  },
+];
+
+function StepCard({ step }: { step: InstallStep }) {
+  return (
+    <Card className="border border-border">
+      <CardContent className="p-4">
+        <div className="flex items-start gap-3">
+          <div
+            className="flex items-center justify-center rounded-full bg-primary text-primary-foreground flex-shrink-0"
+            style={{ width: '32px', height: '32px' }}
+          >
+            <span className="text-sm font-semibold">{step.number}</span>
+          </div>
+
+          <div className="flex-1 min-w-0">
+            <div className="flex items-center gap-2 mb-1">
+              <step.icon className="w-5 h-5 text-primary" />
+              <h3 className="font-semibold text-foreground">{step.title}</h3>
+            </div>
+            <p className="text-sm text-muted-foreground">{step.description}</p>
+          </div>
+        </div>
+      </CardContent>
+    </Card>
+  );
+}
+
+export function IOSGuideModal({ onDismiss, open = true }: IOSGuideModalProps) {
+  return (
+    <Dialog open={open} onOpenChange={(isOpen) => !isOpen && onDismiss()}>
+      <DialogContent className="sm:max-w-md">
+        <DialogHeader className="text-left">
+          <DialogTitle className="flex items-center gap-2">
+            <Share className="w-5 h-5 text-primary" />
+            Add to Home Screen
+          </DialogTitle>
+          <DialogDescription className="text-left">
+            Install this app on your iPhone for quick access and a better experience
+          </DialogDescription>
+        </DialogHeader>
+
+        <div className="space-y-3 py-4">
+          {steps.map((step) => (
+            <StepCard key={step.number} step={step} />
+          ))}
+        </div>
+
+        <DialogFooter>
+          <Button onClick={onDismiss} variant="default" className="w-full">
+            <Check className="w-4 h-4 mr-2" />
+            Got It
+          </Button>
+        </DialogFooter>
+      </DialogContent>
+    </Dialog>
+  );
+}

package/src/snippets/PWAInstall/context/InstallContext.tsx

@@ -0,0 +1,102 @@
+'use client';
+
+/**
+ * PWA Install Context
+ *
+ * Minimal global state for PWA installation
+ * No tracking, no metrics, no engagement — just install state
+ */
+
+import React, { createContext, useContext, ReactNode } from 'react';
+
+import type { InstallOutcome } from '../types';
+import { useInstallPrompt } from '../hooks/useInstallPrompt';
+
+export interface PwaContextValue {
+  // Platform
+  isIOS: boolean;
+  isAndroid: boolean;
+  isDesktop: boolean;
+
+  // Browsers
+  isSafari: boolean;
+  isChrome: boolean;
+  isFirefox: boolean;
+  isEdge: boolean;
+  isOpera: boolean;
+  isBrave: boolean;
+  isArc: boolean;
+  isVivaldi: boolean;
+  isYandex: boolean;
+  isSamsungBrowser: boolean;
+  isUCBrowser: boolean;
+  isChromium: boolean; // Any Chromium-based browser
+  browserName: string;
+
+  // State
+  isInstalled: boolean;
+  canPrompt: boolean;
+
+  // Actions
+  install: () => Promise<InstallOutcome>;
+}
+
+const PwaContext = createContext<PwaContextValue | undefined>(undefined);
+
+export interface PwaConfig {
+  enabled?: boolean;
+}
+
+export function PwaProvider({ children, ...config }: PwaConfig & { children: ReactNode }) {
+  // If not enabled, acts as a simple pass-through
+  if (config.enabled === false) {
+    return <>{children}</>;
+  }
+
+  const prompt = useInstallPrompt();
+
+  const value: PwaContextValue = {
+    // Platform
+    isIOS: prompt.isIOS,
+    isAndroid: prompt.isAndroid,
+    isDesktop: !prompt.isIOS && !prompt.isAndroid,
+
+    // Browsers (from useBrowserDetect)
+    isSafari: prompt.browser.isSafari && !prompt.browser.isChromium, // Real Safari only
+    isChrome: prompt.browser.isChrome,
+    isFirefox: prompt.browser.isFirefox,
+    isEdge: prompt.browser.isEdge,
+    isOpera: prompt.browser.isOpera,
+    isBrave: prompt.browser.isBrave,
+    isArc: prompt.browser.isArc,
+    isVivaldi: prompt.browser.isVivaldi,
+    isYandex: prompt.browser.isYandex,
+    isSamsungBrowser: prompt.browser.isSamsungBrowser,
+    isUCBrowser: prompt.browser.isUCBrowser,
+    isChromium: prompt.browser.isChromium,
+    browserName: prompt.browser.browserName,
+
+    // State
+    isInstalled: prompt.isInstalled,
+    canPrompt: prompt.canPrompt,
+
+    // Actions
+    install: prompt.promptInstall,
+  };
+
+  return <PwaContext.Provider value={value}>{children}</PwaContext.Provider>;
+}
+
+/**
+ * Use install context
+ * Must be used within <PwaProvider>
+ */
+export function useInstall(): PwaContextValue {
+  const context = useContext(PwaContext);
+
+  if (context === undefined) {
+    throw new Error('useInstall must be used within <PwaProvider>');
+  }
+
+  return context;
+}

package/src/snippets/PWAInstall/hooks/useInstallPrompt.ts

@@ -0,0 +1,167 @@
+'use client';
+
+/**
+ * PWA Install Prompt Hook
+ *
+ * Manages beforeinstallprompt event and installation state
+ * Uses existing hooks from @djangocfg/ui-nextjs for platform detection
+ */
+
+import { useEffect, useState } from 'react';
+import { useBrowserDetect, useDeviceDetect } from '@djangocfg/ui-nextjs';
+
+import type { BeforeInstallPromptEvent, InstallPromptState, InstallOutcome } from '../types';
+import { markAppInstalled } from '../utils/localStorage';
+import { isStandalone, onDisplayModeChange } from '../utils/platform';
+import { pwaLogger } from '../utils/logger';
+
+export function useInstallPrompt() {
+  const browser = useBrowserDetect();
+  const device = useDeviceDetect();
+
+  const [state, setState] = useState<InstallPromptState>(() => {
+    if (typeof window === 'undefined') {
+      return {
+        isIOS: false,
+        isAndroid: false,
+        isSafari: false,
+        isChrome: false,
+        isInstalled: false,
+        canPrompt: false,
+        deferredPrompt: null,
+      };
+    }
+
+    // Real Safari = Safari && NOT Chromium (avoid Arc, Brave on iOS)
+    const isSafari = browser.isSafari && !browser.isChromium;
+
+    return {
+      isIOS: device.isIOS,
+      isAndroid: device.isAndroid,
+      isSafari,
+      isChrome: browser.isChrome || browser.isChromium,
+      isInstalled: isStandalone(),
+      canPrompt: false,
+      deferredPrompt: null,
+    };
+  });
+
+  // Update state when platform info changes
+  useEffect(() => {
+    const isSafari = browser.isSafari && !browser.isChromium;
+
+    setState((prev) => ({
+      ...prev,
+      isIOS: device.isIOS,
+      isAndroid: device.isAndroid,
+      isSafari,
+      isChrome: browser.isChrome || browser.isChromium,
+      isInstalled: isStandalone(),
+    }));
+  }, [browser, device]);
+
+  // Listen for beforeinstallprompt event (Android Chrome only)
+  useEffect(() => {
+    if (typeof window === 'undefined') return;
+
+    const handleBeforeInstallPrompt = (e: Event) => {
+      // Prevent the default browser install prompt
+      e.preventDefault();
+
+      const event = e as BeforeInstallPromptEvent;
+
+      setState((prev) => ({
+        ...prev,
+        canPrompt: true,
+        deferredPrompt: event,
+      }));
+    };
+
+    window.addEventListener('beforeinstallprompt', handleBeforeInstallPrompt);
+
+    return () => {
+      window.removeEventListener('beforeinstallprompt', handleBeforeInstallPrompt);
+    };
+  }, []);
+
+  // Listen for appinstalled event (Android Chrome)
+  useEffect(() => {
+    if (typeof window === 'undefined') return;
+
+    const handleAppInstalled = () => {
+      setState((prev) => ({
+        ...prev,
+        canPrompt: false,
+        deferredPrompt: null,
+        isInstalled: true,
+      }));
+
+      // Mark as installed in localStorage
+      markAppInstalled();
+    };
+
+    window.addEventListener('appinstalled', handleAppInstalled);
+
+    return () => {
+      window.removeEventListener('appinstalled', handleAppInstalled);
+    };
+  }, []);
+
+  // Check for display-mode changes (user adds to home screen)
+  useEffect(() => {
+    const cleanup = onDisplayModeChange((isStandaloneMode) => {
+      if (isStandaloneMode) {
+        setState((prev) => ({
+          ...prev,
+          isInstalled: true,
+          canPrompt: false,
+          deferredPrompt: null,
+        }));
+
+        markAppInstalled();
+      }
+    });
+
+    return cleanup;
+  }, []);
+
+  /**
+   * Trigger Android native install prompt
+   */
+  const promptInstall = async (): Promise<InstallOutcome> => {
+    if (!state.deferredPrompt) {
+      pwaLogger.warn('[PWA Install] No deferred prompt available');
+      return null;
+    }
+
+    try {
+      // Show the native prompt
+      await state.deferredPrompt.prompt();
+
+      // Wait for user response
+      const { outcome } = await state.deferredPrompt.userChoice;
+
+      pwaLogger.info('[PWA Install] User choice:', outcome);
+
+      // Clear the deferred prompt
+      setState((prev) => ({
+        ...prev,
+        deferredPrompt: null,
+        canPrompt: false,
+      }));
+
+      return outcome;
+    } catch (error) {
+      pwaLogger.error('[PWA Install] Error showing install prompt:', error);
+      return null;
+    }
+  };
+
+  return {
+    ...state,
+    promptInstall,
+    // Expose full browser info
+    browser,
+    device,
+  };
+}

package/src/snippets/PWAInstall/hooks/useIsPWA.ts

@@ -0,0 +1,115 @@
+'use client';
+
+/**
+ * Hook to detect if app is running as PWA
+ *
+ * Checks if the app is running in standalone mode (added to home screen).
+ * Results are cached in sessionStorage for fast initialization across page loads.
+ *
+ * @example
+ * ```typescript
+ * // Basic usage (standard check)
+ * const isPWA = useIsPWA();
+ *
+ * // Reliable check (with manifest validation for desktop)
+ * const isPWA = useIsPWA({ reliable: true });
+ * ```
+ */
+
+import { useState, useEffect } from 'react';
+import { isStandalone, isStandaloneReliable, onDisplayModeChange } from '../utils/platform';
+
+const CACHE_KEY = 'pwa_is_standalone';
+
+/**
+ * Options for useIsPWA hook
+ */
+export 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
+ */
+export function useIsPWA(options?: UseIsPWAOptions): boolean {
+  const checkFunction = options?.reliable ? isStandaloneReliable : isStandalone;
+
+  const [isPWA, setIsPWA] = useState<boolean>(() => {
+    // Try to restore from cache for fast initialization
+    if (typeof window !== 'undefined') {
+      try {
+        const cached = sessionStorage.getItem(CACHE_KEY);
+        if (cached !== null) {
+          return cached === 'true';
+        }
+      } catch {
+        // Ignore sessionStorage errors (e.g., in incognito mode)
+      }
+    }
+
+    // Initial check
+    return checkFunction();
+  });
+
+  useEffect(() => {
+    // Check after mount (may differ from SSR)
+    const isStandaloneMode = checkFunction();
+    setIsPWA(isStandaloneMode);
+
+    // Update cache
+    if (typeof window !== 'undefined') {
+      try {
+        sessionStorage.setItem(CACHE_KEY, String(isStandaloneMode));
+      } catch {
+        // Ignore sessionStorage errors
+      }
+    }
+
+    // Listen for display-mode changes
+    const cleanup = onDisplayModeChange((newValue) => {
+      setIsPWA(newValue);
+
+      // Update cache
+      if (typeof window !== 'undefined') {
+        try {
+          sessionStorage.setItem(CACHE_KEY, String(newValue));
+        } catch {
+          // Ignore sessionStorage errors
+        }
+      }
+    });
+
+    return cleanup;
+  }, [checkFunction]);
+
+  return isPWA;
+}
+
+/**
+ * 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();
+ * ```
+ */
+export function clearIsPWACache(): void {
+  if (typeof window === 'undefined') return;
+  try {
+    sessionStorage.removeItem(CACHE_KEY);
+  } catch {
+    // Ignore sessionStorage errors
+  }
+}

package/src/snippets/PWAInstall/index.ts

@@ -0,0 +1,76 @@
+/**
+ * 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';
+
+// 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';