@djangocfg/layouts 2.1.35 → 2.1.37

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

@@ -0,0 +1,156 @@
+'use client';
+
+import React, { createContext, useContext, useState, useEffect, useCallback } from 'react';
+import { usePushNotifications } from '../hooks/usePushNotifications';
+import { pwaLogger } from '../utils/logger';
+import type { PushNotificationOptions } from '../types';
+
+const ICON_URL = 'https://djangocfg.com/static/logos/192x192.png';
+
+export interface PushMessage {
+  id: string;
+  title: string;
+  body: string;
+  icon?: string;
+  badge?: string;
+  tag?: string;
+  timestamp: number;
+  data?: Record<string, unknown>;
+}
+
+export interface PushContextValue {
+  // Push state
+  isSupported: boolean;
+  permission: NotificationPermission;
+  isSubscribed: boolean;
+  subscription: PushSubscription | null;
+
+  // Accumulated pushes
+  pushes: PushMessage[];
+
+  // Actions
+  subscribe: () => Promise<boolean>;
+  unsubscribe: () => Promise<boolean>;
+  sendPush: (message: Omit<PushMessage, 'id' | 'timestamp'>) => Promise<void>;
+  clearPushes: () => void;
+  removePush: (id: string) => void;
+}
+
+const PushContext = createContext<PushContextValue | undefined>(undefined);
+
+interface PushProviderProps {
+  children: React.ReactNode;
+  vapidPublicKey?: string;
+  subscribeEndpoint?: string;
+  sendEndpoint?: string;
+  onPushReceived?: (push: PushMessage) => void;
+}
+
+export function PushProvider({
+  children,
+  vapidPublicKey = '',
+  subscribeEndpoint = '/api/push/subscribe',
+  sendEndpoint = '/api/push/send',
+  onPushReceived,
+}: PushProviderProps) {
+  const pushNotifications = usePushNotifications({
+    vapidPublicKey,
+    subscribeEndpoint,
+  });
+
+  const [pushes, setPushes] = useState<PushMessage[]>([]);
+
+  // Listen for push messages from service worker
+  useEffect(() => {
+    if (typeof window === 'undefined' || !('serviceWorker' in navigator)) {
+      return;
+    }
+
+    const handleMessage = (event: MessageEvent) => {
+      if (event.data && event.data.type === 'PUSH_RECEIVED') {
+        const push: PushMessage = {
+          id: crypto.randomUUID(),
+          timestamp: Date.now(),
+          ...event.data.notification,
+        };
+
+        setPushes(prev => [push, ...prev]);
+        onPushReceived?.(push);
+      }
+    };
+
+    navigator.serviceWorker.addEventListener('message', handleMessage);
+
+    return () => {
+      navigator.serviceWorker.removeEventListener('message', handleMessage);
+    };
+  }, [onPushReceived]);
+
+  const sendPush = useCallback(async (message: Omit<PushMessage, 'id' | 'timestamp'>) => {
+    if (!pushNotifications.isSubscribed) {
+      throw new Error('Not subscribed to push notifications');
+    }
+
+    // In real app, this calls your backend API to send actual push
+    try {
+      // Send to server
+      await fetch(sendEndpoint, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({
+          subscription: pushNotifications.subscription,
+          notification: message,
+        }),
+      });
+
+      // Optimistic update for UI
+      const push: PushMessage = {
+        ...message,
+        id: crypto.randomUUID(),
+        timestamp: Date.now(),
+      };
+
+      setPushes(prev => [push, ...prev]);
+    } catch (error) {
+      pwaLogger.error('[PushContext] Failed to send push:', error);
+      throw error;
+    }
+  }, [pushNotifications.isSubscribed, pushNotifications.subscription, sendEndpoint]);
+
+  const clearPushes = useCallback(() => {
+    setPushes([]);
+  }, []);
+
+  const removePush = useCallback((id: string) => {
+    setPushes(prev => prev.filter(p => p.id !== id));
+  }, []);
+
+  const value: PushContextValue = {
+    isSupported: pushNotifications.isSupported,
+    permission: pushNotifications.permission,
+    isSubscribed: pushNotifications.isSubscribed,
+    subscription: pushNotifications.subscription,
+    pushes,
+    subscribe: pushNotifications.subscribe,
+    unsubscribe: pushNotifications.unsubscribe,
+    sendPush,
+    clearPushes,
+    removePush,
+  };
+
+  return <PushContext.Provider value={value}>{children}</PushContext.Provider>;
+}
+
+/**
+ * Use push notifications context
+ * Must be used within <PushProvider>
+ */
+export function usePush(): PushContextValue {
+  const context = useContext(PushContext);
+
+  if (context === undefined) {
+    throw new Error('usePush must be used within <PushProvider>');
+  }
+
+  return context;
+}

package/src/snippets/PWA/hooks/useDjangoPush.ts

@@ -0,0 +1,277 @@
+'use client';
+
+/**
+ * Django Push Notifications Hook
+ *
+ * Integrates @djangocfg/layouts/PWA with Django-CFG backend API.
+ * Uses generated TypeScript client from @djangocfg/api for type-safe integration.
+ *
+ * @example
+ * ```tsx
+ * import { useDjangoPush } from '@djangocfg/layouts/PWA';
+ *
+ * function NotificationsButton() {
+ *   const { subscribe, isSubscribed, permission } = useDjangoPush({
+ *     vapidPublicKey: 'YOUR_VAPID_KEY'
+ *   });
+ *
+ *   return (
+ *     <button onClick={subscribe} disabled={isSubscribed}>
+ *       {isSubscribed ? 'Subscribed' : 'Enable Notifications'}
+ *     </button>
+ *   );
+ * }
+ * ```
+ */
+
+import { useState, useCallback } from 'react';
+import { usePushNotifications } from './usePushNotifications';
+import { pwaLogger } from '../utils/logger';
+import type { PushNotificationOptions } from '../types';
+
+// Import Django API client
+// @ts-ignore - optional peer dependency
+import { apiAccounts, apiWebPush } from '@djangocfg/api/clients';
+
+interface UseDjangoPushOptions extends PushNotificationOptions {
+  /**
+   * 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;
+}
+
+interface UseDjangoPushReturn {
+  // 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>;
+}
+
+/**
+ * Hook for Django-CFG push notifications integration
+ */
+export function useDjangoPush(options: UseDjangoPushOptions): UseDjangoPushReturn {
+  const {
+    autoSubscribe = false,
+    onSubscribed,
+    onSubscribeError,
+    onUnsubscribed,
+    ...pushOptions
+  } = options;
+
+  const [isLoading, setIsLoading] = useState(false);
+  const [error, setError] = useState<Error | null>(null);
+
+  // Use base push notifications hook
+  const pushNotifications = usePushNotifications(pushOptions);
+
+  /**
+   * Subscribe to push notifications and save to Django backend
+   */
+  const subscribe = useCallback(async (): Promise<boolean> => {
+    if (!pushNotifications.isSupported) {
+      const err = new Error('Push notifications not supported');
+      setError(err);
+      onSubscribeError?.(err);
+      return false;
+    }
+
+    if (!options.vapidPublicKey) {
+      const err = new Error('VAPID public key required');
+      setError(err);
+      onSubscribeError?.(err);
+      return false;
+    }
+
+    setIsLoading(true);
+    setError(null);
+
+    try {
+      // Step 1: Request permission
+      const permission = await Notification.requestPermission();
+      if (permission !== 'granted') {
+        throw new Error(`Permission ${permission}`);
+      }
+
+      // Step 2: Get service worker registration
+      const registration = await navigator.serviceWorker.ready;
+
+      // Step 3: Subscribe to push manager
+      const subscription = await registration.pushManager.subscribe({
+        userVisibleOnly: true,
+        applicationServerKey: urlBase64ToUint8Array(options.vapidPublicKey) as BufferSource,
+      });
+
+      pwaLogger.info('[useDjangoPush] Browser subscription created:', {
+        endpoint: subscription.endpoint.substring(0, 50) + '...',
+      });
+
+      // Step 4: Save to Django backend using generated API client
+      const result = await apiWebPush.web_push.webpushSubscribeCreate({
+        endpoint: subscription.endpoint,
+        keys: {
+          p256dh: arrayBufferToBase64(subscription.getKey('p256dh')),
+          auth: arrayBufferToBase64(subscription.getKey('auth')),
+        },
+      });
+
+      pwaLogger.info('[useDjangoPush] Subscription saved to Django:', result);
+
+      onSubscribed?.(subscription);
+      return true;
+    } catch (err) {
+      const error = err instanceof Error ? err : new Error(String(err));
+      pwaLogger.error('[useDjangoPush] Subscribe failed:', error);
+      setError(error);
+      onSubscribeError?.(error);
+      return false;
+    } finally {
+      setIsLoading(false);
+    }
+  }, [
+    pushNotifications.isSupported,
+    options.vapidPublicKey,
+    onSubscribed,
+    onSubscribeError,
+  ]);
+
+  /**
+   * Unsubscribe from push notifications
+   */
+  const unsubscribe = useCallback(async (): Promise<boolean> => {
+    if (!pushNotifications.subscription) {
+      return false;
+    }
+
+    setIsLoading(true);
+    setError(null);
+
+    try {
+      // Unsubscribe from push manager
+      await pushNotifications.subscription.unsubscribe();
+      pwaLogger.info('[useDjangoPush] Browser unsubscribed');
+
+      // Note: Django backend will auto-cleanup inactive subscriptions
+      // No need to explicitly remove since subscription.endpoint becomes invalid
+
+      onUnsubscribed?.();
+      return true;
+    } catch (err) {
+      const error = err instanceof Error ? err : new Error(String(err));
+      pwaLogger.error('[useDjangoPush] Unsubscribe failed:', error);
+      setError(error);
+      return false;
+    } finally {
+      setIsLoading(false);
+    }
+  }, [pushNotifications.subscription, onUnsubscribed]);
+
+  /**
+   * Send test push notification
+   */
+  const sendTestPush = useCallback(
+    async (message: { title: string; body: string; url?: string }): Promise<boolean> => {
+      if (!pushNotifications.isSubscribed) {
+        const err = new Error('Not subscribed');
+        setError(err);
+        return false;
+      }
+
+      setIsLoading(true);
+      setError(null);
+
+      try {
+        const result = await apiWebPush.web_push.webpushSendCreate({
+          title: message.title,
+          body: message.body,
+          url: message.url || '/',
+          icon: '/icon.png',
+        });
+
+        pwaLogger.info('[useDjangoPush] Test push sent:', result);
+        return result.success;
+      } catch (err) {
+        const error = err instanceof Error ? err : new Error(String(err));
+        pwaLogger.error('[useDjangoPush] Send test push failed:', error);
+        setError(error);
+        return false;
+      } finally {
+        setIsLoading(false);
+      }
+    },
+    [pushNotifications.isSubscribed]
+  );
+
+  return {
+    // State
+    isSupported: pushNotifications.isSupported,
+    permission: pushNotifications.permission,
+    isSubscribed: pushNotifications.isSubscribed,
+    subscription: pushNotifications.subscription,
+    isLoading,
+    error,
+
+    // Actions
+    subscribe,
+    unsubscribe,
+    sendTestPush,
+  };
+}
+
+// ============================================================================
+// Utilities
+// ============================================================================
+
+/**
+ * Convert base64 VAPID key to Uint8Array
+ */
+function urlBase64ToUint8Array(base64String: string): Uint8Array {
+  const padding = '='.repeat((4 - (base64String.length % 4)) % 4);
+  const base64 = (base64String + padding).replace(/-/g, '+').replace(/_/g, '/');
+
+  const rawData = window.atob(base64);
+  const outputArray = new Uint8Array(rawData.length);
+
+  for (let i = 0; i < rawData.length; ++i) {
+    outputArray[i] = rawData.charCodeAt(i);
+  }
+  return outputArray;
+}
+
+/**
+ * Convert ArrayBuffer to base64 string
+ */
+function arrayBufferToBase64(buffer: ArrayBuffer | null): string {
+  if (!buffer) return '';
+
+  const bytes = new Uint8Array(buffer);
+  let binary = '';
+  for (let i = 0; i < bytes.byteLength; i++) {
+    binary += String.fromCharCode(bytes[i]);
+  }
+  return window.btoa(binary);
+}

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

@@ -0,0 +1,164 @@
+'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,
+  };
+}

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