@djangocfg/layouts 2.1.35 → 2.1.37

package/src/snippets/PWA/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/PWA/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/PWA/components/PushPrompt.tsx

@@ -0,0 +1,165 @@
+'use client';
+
+/**
+ * Push Notification Prompt
+ *
+ * Shows after PWA is installed to request push notification permission
+ * Auto-dismisses after user action or timeout
+ */
+
+import React, { useState, useEffect } from 'react';
+import { Bell, X } from 'lucide-react';
+import { Button } from '@djangocfg/ui-nextjs';
+
+import { usePushNotifications } from '../hooks/usePushNotifications';
+import { isStandalone } from '../utils/platform';
+import { pwaLogger } from '../utils/logger';
+import { markPushDismissed, isPushDismissedRecently } from '../utils/localStorage';
+import type { PushNotificationOptions } from '../types';
+
+const DEFAULT_RESET_DAYS = 7;
+
+interface PushPromptProps extends PushNotificationOptions {
+  /**
+   * Only show if PWA is installed
+   * @default true
+   */
+  requirePWA?: boolean;
+
+  /**
+   * Delay before showing prompt (ms)
+   * @default 5000
+   */
+  delayMs?: number;
+
+  /**
+   * Number of days before re-showing dismissed prompt
+   * @default 7
+   */
+  resetAfterDays?: number;
+
+  /**
+   * Callback when push is enabled
+   */
+  onEnabled?: () => void;
+
+  /**
+   * Callback when push is dismissed
+   */
+  onDismissed?: () => void;
+}
+
+export function PushPrompt({
+  vapidPublicKey,
+  subscribeEndpoint = '/api/push/subscribe',
+  requirePWA = true,
+  delayMs = 5000,
+  resetAfterDays = DEFAULT_RESET_DAYS,
+  onEnabled,
+  onDismissed,
+}: PushPromptProps) {
+  const { isSupported, permission, isSubscribed, subscribe } = usePushNotifications({
+    vapidPublicKey,
+    subscribeEndpoint,
+  });
+
+  const [show, setShow] = useState(false);
+  const [enabling, setEnabling] = useState(false);
+
+  // Check if should show
+  useEffect(() => {
+    if (!isSupported || isSubscribed || permission === 'denied') {
+      return;
+    }
+
+    // Check if PWA is installed (standalone mode)
+    if (requirePWA && !isStandalone()) {
+      return;
+    }
+
+    // Check if previously dismissed
+    if (typeof window !== 'undefined') {
+      if (isPushDismissedRecently(resetAfterDays)) {
+        return; // Still within reset period
+      }
+    }
+
+    // Show after delay
+    const timer = setTimeout(() => setShow(true), delayMs);
+    return () => clearTimeout(timer);
+  }, [isSupported, isSubscribed, permission, requirePWA, resetAfterDays, delayMs]);
+
+  const handleEnable = async () => {
+    setEnabling(true);
+    try {
+      const success = await subscribe();
+      if (success) {
+        setShow(false);
+        onEnabled?.();
+      }
+    } catch (error) {
+      pwaLogger.error('[PushPrompt] Enable failed:', error);
+    } finally {
+      setEnabling(false);
+    }
+  };
+
+  const handleDismiss = () => {
+    setShow(false);
+    markPushDismissed();
+    onDismissed?.();
+  };
+
+  if (!show) return null;
+
+  return (
+    <div className="fixed bottom-4 left-4 right-4 z-50 animate-in slide-in-from-bottom-4 duration-300">
+      <div className="bg-zinc-900 border border-zinc-700 rounded-lg p-4 shadow-lg">
+        <div className="flex items-start gap-3">
+          {/* Icon */}
+          <div className="flex-shrink-0">
+            <Bell className="w-5 h-5 text-blue-400" />
+          </div>
+
+          {/* Content */}
+          <div className="flex-1 min-w-0">
+            <p className="text-sm font-medium text-white mb-1">Enable notifications</p>
+            <p className="text-xs text-zinc-400 mb-3">
+              Stay updated with important updates and alerts
+            </p>
+
+            {/* Actions */}
+            <div className="flex gap-2">
+              <Button
+                onClick={handleEnable}
+                loading={enabling}
+                size="sm"
+                variant="default"
+              >
+                Enable
+              </Button>
+              <Button
+                onClick={handleDismiss}
+                size="sm"
+                variant="ghost"
+              >
+                Not now
+              </Button>
+            </div>
+          </div>
+
+          {/* Close button */}
+          <Button
+            onClick={handleDismiss}
+            size="sm"
+            variant="ghost"
+            className="flex-shrink-0 p-1"
+            aria-label="Dismiss"
+          >
+            <X className="w-4 h-4" />
+          </Button>
+        </div>
+      </div>
+    </div>
+  );
+}

package/src/snippets/PWA/config.ts

@@ -0,0 +1,20 @@
+/**
+ * PWA Configuration
+ *
+ * Centralized constants for PWA functionality.
+ *
+ * SECURITY NOTE:
+ * - VAPID_PRIVATE_KEY should NEVER be in frontend code
+ * - Private keys must only exist in backend/API routes
+ * - Frontend only needs the public key (NEXT_PUBLIC_* env vars)
+ * - VAPID_MAILTO should also remain on backend only
+ */
+
+// Default VAPID public key (safe to expose in frontend)
+export const DEFAULT_VAPID_PUBLIC_KEY = process.env.NEXT_PUBLIC_VAPID_PUBLIC_KEY || '';
+
+// NOTE: VAPID private key and mailto should only exist in:
+// - Backend environment variables (not NEXT_PUBLIC_*)
+// - API route handlers (app/api/push/*)
+// - Service worker generation scripts
+// NEVER import or use private keys in frontend code

package/src/snippets/PWA/context/DjangoPushContext.tsx

@@ -0,0 +1,105 @@
+'use client';
+
+/**
+ * Django Push Context
+ *
+ * Provider for Django-CFG push notifications integration.
+ * Wraps useDjangoPush hook in React context for easy consumption.
+ *
+ * @example
+ * ```tsx
+ * import { DjangoPushProvider, useDjangoPushContext } from '@djangocfg/layouts/PWA';
+ *
+ * // In layout
+ * <DjangoPushProvider vapidPublicKey={process.env.NEXT_PUBLIC_VAPID_KEY}>
+ *   {children}
+ * </DjangoPushProvider>
+ *
+ * // In component
+ * function NotifyButton() {
+ *   const { subscribe, isSubscribed } = useDjangoPushContext();
+ *   return <button onClick={subscribe}>Subscribe</button>;
+ * }
+ * ```
+ */
+
+import React, { createContext, useContext } from 'react';
+import { useDjangoPush } from '../hooks/useDjangoPush';
+import type { PushNotificationOptions } from '../types';
+
+interface DjangoPushContextValue {
+  // State
+  isSupported: boolean;
+  permission: NotificationPermission;
+  isSubscribed: boolean;
+  subscription: PushSubscription | null;
+  isLoading: boolean;
+  error: Error | null;
+
+  // Actions
+  subscribe: () => Promise<boolean>;
+  unsubscribe: () => Promise<boolean>;
+  sendTestPush: (message: { title: string; body: string; url?: string }) => Promise<boolean>;
+}
+
+const DjangoPushContext = createContext<DjangoPushContextValue | undefined>(undefined);
+
+interface DjangoPushProviderProps extends PushNotificationOptions {
+  children: React.ReactNode;
+
+  /**
+   * Auto-subscribe on mount if permission granted
+   * @default false
+   */
+  autoSubscribe?: boolean;
+
+  /**
+   * Callback when subscription created
+   */
+  onSubscribed?: (subscription: PushSubscription) => void;
+
+  /**
+   * Callback when subscription failed
+   */
+  onSubscribeError?: (error: Error) => void;
+
+  /**
+   * Callback when unsubscribed
+   */
+  onUnsubscribed?: () => void;
+}
+
+/**
+ * Provider for Django push notifications
+ */
+export function DjangoPushProvider({
+  children,
+  vapidPublicKey,
+  autoSubscribe = false,
+  onSubscribed,
+  onSubscribeError,
+  onUnsubscribed,
+}: DjangoPushProviderProps) {
+  const djangoPush = useDjangoPush({
+    vapidPublicKey,
+    autoSubscribe,
+    onSubscribed,
+    onSubscribeError,
+    onUnsubscribed,
+  });
+
+  return <DjangoPushContext.Provider value={djangoPush}>{children}</DjangoPushContext.Provider>;
+}
+
+/**
+ * Hook to access Django push context
+ */
+export function useDjangoPushContext(): DjangoPushContextValue {
+  const context = useContext(DjangoPushContext);
+
+  if (context === undefined) {
+    throw new Error('useDjangoPushContext must be used within DjangoPushProvider');
+  }
+
+  return context;
+}

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

@@ -0,0 +1,118 @@
+'use client';
+
+/**
+ * Simplified 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 { A2HSHint } from '../components/A2HSHint';
+import type { InstallOutcome, PushNotificationOptions } from '../types';
+import { useInstallPrompt } from '../hooks/useInstallPrompt';
+import { PushProvider } from './PushContext';
+
+/**
+ * Conditional PushProvider wrapper
+ * Only wraps children if push notifications are enabled
+ */
+function ConditionalPushProvider({
+  enabled,
+  children,
+  ...config
+}: PushNotificationOptions & { enabled: boolean; children: ReactNode }) {
+  if (!enabled) return <>{children}</>;
+  return <PushProvider {...config}>{children}</PushProvider>;
+}
+
+export interface PwaContextValue {
+  // Platform
+  isIOS: boolean;
+  isAndroid: boolean;
+  isSafari: boolean;
+  isChrome: boolean;
+
+  // State
+  isInstalled: boolean;
+  canPrompt: boolean;
+
+  // Actions
+  install: () => Promise<InstallOutcome>;
+}
+
+const PwaContext = createContext<PwaContextValue | undefined>(undefined);
+
+export interface PwaConfig {
+  enabled?: boolean;
+  showInstallHint?: boolean;
+  resetAfterDays?: number | null;
+  delayMs?: number;
+  logo?: string;
+  pushNotifications?: PushNotificationOptions & {
+    delayMs?: number;
+    resetAfterDays?: number;
+  };
+}
+
+export function PwaProvider({ children, ...config }: PwaConfig & { children: React.ReactNode }) {
+  // If not enabled, acts as a simple pass-through
+  if (config.enabled === false) {
+    return <>{children}</>;
+  }
+
+  const prompt = useInstallPrompt();
+
+  const value: PwaContextValue = {
+    isIOS: prompt.isIOS,
+    isAndroid: prompt.isAndroid,
+    isSafari: prompt.isSafari,
+    isChrome: prompt.isChrome,
+    isInstalled: prompt.isInstalled,
+    canPrompt: prompt.canPrompt,
+    install: prompt.promptInstall,
+  };
+
+  const showHint = config.showInstallHint !== false;
+
+  // ✅ Explicit composition tree (no magic wrapping)
+  // Structure:
+  // - PwaContext.Provider (PWA install state)
+  //   - ConditionalPushProvider (optional push notifications)
+  //     - children (user content)
+  //     - A2HSHint (PWA install hint UI)
+  return (
+    <PwaContext.Provider value={value}>
+      <ConditionalPushProvider
+        enabled={!!config.pushNotifications}
+        vapidPublicKey={config.pushNotifications?.vapidPublicKey || ''}
+        subscribeEndpoint={config.pushNotifications?.subscribeEndpoint}
+      >
+        {children}
+        {showHint && (
+          <A2HSHint
+            resetAfterDays={config.resetAfterDays}
+            delayMs={config.delayMs}
+            logo={config.logo}
+            pushNotifications={config.pushNotifications}
+          />
+        )}
+      </ConditionalPushProvider>
+    </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;
+}