@djangocfg/ui-nextjs 2.1.227 → 2.1.229

package/src/pwa/components/IOSGuide.tsx

@@ -0,0 +1,29 @@
+'use client';
+
+/**
+ * iOS Installation Guide (Adaptive)
+ *
+ * Automatically uses:
+ * - Drawer on mobile (better swipe UX)
+ * - Dialog on desktop/tablet
+ */
+
+import React from 'react';
+
+import { useIsMobile } from '@djangocfg/ui-core/hooks';
+
+import { IOSGuideDrawer } from './IOSGuideDrawer';
+import { IOSGuideModal } from './IOSGuideModal';
+
+import type { IOSGuideModalProps } from '../types';
+
+export function IOSGuide(props: IOSGuideModalProps) {
+  const isMobile = useIsMobile(); // Viewport < 768px
+
+  // Use drawer on mobile, dialog on desktop
+  if (isMobile) {
+    return <IOSGuideDrawer {...props} />;
+  }
+
+  return <IOSGuideModal {...props} />;
+}

package/src/pwa/components/IOSGuideDrawer.tsx

@@ -0,0 +1,103 @@
+'use client';
+
+/**
+ * iOS Installation Guide Drawer (Mobile-Optimized)
+ *
+ * Bottom drawer with swipe gestures for iOS installation guide
+ * Better UX for mobile devices
+ */
+
+import { ArrowDown, ArrowUpRight, Check, CheckCircle, Share } from 'lucide-react';
+import React, { useMemo } from 'react';
+
+import { useAppT } from '@djangocfg/i18n';
+import {
+    Button, Card, CardContent, Drawer, DrawerContent, DrawerDescription, DrawerHeader, DrawerTitle
+} from '@djangocfg/ui-core/components';
+
+import type { IOSGuideModalProps, InstallStep } from '../types';
+
+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) {
+  const t = useAppT();
+
+  const labels = useMemo(() => ({
+    title: t('layouts.pwa.iosTitle'),
+    description: t('layouts.pwa.iosDescription'),
+    gotIt: t('layouts.pwa.gotIt'),
+  }), [t]);
+
+  const steps: InstallStep[] = useMemo(() => [
+    {
+      number: 1,
+      title: t('layouts.pwa.iosStep1Title'),
+      icon: ArrowUpRight,
+      description: t('layouts.pwa.iosStep1Desc'),
+    },
+    {
+      number: 2,
+      title: t('layouts.pwa.iosStep2Title'),
+      icon: ArrowDown,
+      description: t('layouts.pwa.iosStep2Desc'),
+    },
+    {
+      number: 3,
+      title: t('layouts.pwa.iosStep3Title'),
+      icon: CheckCircle,
+      description: t('layouts.pwa.iosStep3Desc'),
+    },
+  ], [t]);
+
+  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" />
+            {labels.title}
+          </DrawerTitle>
+          <DrawerDescription className="text-left">
+            {labels.description}
+          </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" />
+            {labels.gotIt}
+          </Button>
+        </div>
+      </DrawerContent>
+    </Drawer>
+  );
+}

package/src/pwa/components/IOSGuideModal.tsx

@@ -0,0 +1,103 @@
+'use client';
+
+/**
+ * iOS Installation Guide Modal
+ *
+ * Visual step-by-step guide for adding PWA to home screen on iOS Safari
+ */
+
+import { ArrowDown, ArrowUpRight, Check, CheckCircle, Share } from 'lucide-react';
+import React, { useMemo } from 'react';
+
+import { useAppT } from '@djangocfg/i18n';
+import {
+    Button, Card, CardContent, Dialog, DialogContent, DialogDescription, DialogFooter, DialogHeader,
+    DialogTitle
+} from '@djangocfg/ui-core/components';
+
+import type { IOSGuideModalProps, InstallStep } from '../types';
+
+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) {
+  const t = useAppT();
+
+  const labels = useMemo(() => ({
+    title: t('layouts.pwa.iosTitle'),
+    description: t('layouts.pwa.iosDescription'),
+    gotIt: t('layouts.pwa.gotIt'),
+  }), [t]);
+
+  const steps: InstallStep[] = useMemo(() => [
+    {
+      number: 1,
+      title: t('layouts.pwa.iosStep1Title'),
+      icon: ArrowUpRight,
+      description: t('layouts.pwa.iosStep1Desc'),
+    },
+    {
+      number: 2,
+      title: t('layouts.pwa.iosStep2Title'),
+      icon: ArrowDown,
+      description: t('layouts.pwa.iosStep2Desc'),
+    },
+    {
+      number: 3,
+      title: t('layouts.pwa.iosStep3Title'),
+      icon: CheckCircle,
+      description: t('layouts.pwa.iosStep3Desc'),
+    },
+  ], [t]);
+
+  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" />
+            {labels.title}
+          </DialogTitle>
+          <DialogDescription className="text-left">
+            {labels.description}
+          </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" />
+            {labels.gotIt}
+          </Button>
+        </DialogFooter>
+      </DialogContent>
+    </Dialog>
+  );
+}

package/src/pwa/components/PWAPageResumeManager.tsx

@@ -0,0 +1,33 @@
+'use client';
+
+/**
+ * PWA Page Resume Manager
+ *
+ * Invisible component that manages page resume functionality for PWA.
+ * Add this component to your app layout to enable page resume on PWA launch.
+ *
+ * @example
+ * ```tsx
+ * // In your layout
+ * <PWAPageResumeManager enabled={true} />
+ * ```
+ */
+
+import { usePWAPageResume } from '../hooks/usePWAPageResume';
+
+interface PWAPageResumeManagerProps {
+  /**
+   * Enable page resume feature
+   * @default true
+   */
+  enabled?: boolean;
+}
+
+/**
+ * Component that manages PWA page resume functionality
+ * Renders nothing, just manages state and navigation
+ */
+export function PWAPageResumeManager({ enabled = true }: PWAPageResumeManagerProps) {
+  usePWAPageResume({ enabled });
+  return null; // Renders nothing, just manages state
+}

package/src/pwa/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, ReactNode, useContext } from 'react';
+
+import { useInstallPrompt } from '../hooks/useInstallPrompt';
+
+import type { InstallOutcome } from '../types';
+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/pwa/hooks/useInstallPrompt.ts

@@ -0,0 +1,168 @@
+'use client';
+
+/**
+ * PWA Install Prompt Hook
+ *
+ * Manages beforeinstallprompt event and installation state
+ * Uses existing hooks from @djangocfg/ui-core for platform detection
+ */
+
+import { useEffect, useState } from 'react';
+
+import { useBrowserDetect, useDeviceDetect } from '../../hooks';
+
+import { markAppInstalled } from '../utils/localStorage';
+import { pwaLogger } from '../utils/logger';
+import { isStandalone, onDisplayModeChange } from '../utils/platform';
+
+import type { BeforeInstallPromptEvent, InstallPromptState, InstallOutcome } from '../types';
+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/pwa/hooks/useIsPWA.ts

@@ -0,0 +1,116 @@
+'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 { useEffect, useState } 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
+  }
+}