@djangocfg/layouts 2.1.37 → 2.1.38

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

@@ -0,0 +1,229 @@
+'use client';
+
+/**
+ * Desktop Installation Guide Modal
+ *
+ * Visual step-by-step guide for installing PWA on desktop browsers
+ * Uses platform detection from InstallContext
+ * Supports: Chrome, Edge, Brave, Arc, Vivaldi, Opera, Yandex, Firefox, Safari
+ */
+
+import React, { useMemo } from 'react';
+import { Monitor, Check, ArrowDownToLine, Menu, Search, Plus } from 'lucide-react';
+
+import {
+  Dialog,
+  DialogContent,
+  DialogDescription,
+  DialogFooter,
+  DialogHeader,
+  DialogTitle,
+  Button,
+  Card,
+  CardContent,
+} from '@djangocfg/ui-nextjs';
+
+import type { IOSGuideModalProps, InstallStep } from '../types';
+import { useInstall } from '../context/InstallContext';
+
+type BrowserCategory = 'chromium' | 'firefox' | 'safari' | 'unknown';
+
+function getBrowserCategory(browser: {
+  isChromium: boolean;
+  isFirefox: boolean;
+  isSafari: boolean;
+}): BrowserCategory {
+  if (browser.isChromium) return 'chromium';
+  if (browser.isFirefox) return 'firefox';
+  if (browser.isSafari) return 'safari';
+  return 'unknown';
+}
+
+function getBrowserSteps(category: BrowserCategory, browserName: string): InstallStep[] {
+  switch (category) {
+    case 'chromium':
+      // Chrome, Edge, Brave, Arc, Vivaldi, Opera, Yandex, etc.
+      return [
+        {
+          number: 1,
+          title: 'Find Install Icon',
+          icon: ArrowDownToLine,
+          description: 'Look for install icon in address bar (right side)',
+        },
+        {
+          number: 2,
+          title: 'Click Install',
+          icon: Plus,
+          description: 'Click the icon and select "Install"',
+        },
+        {
+          number: 3,
+          title: 'Confirm',
+          icon: Check,
+          description: 'Click "Install" in the popup dialog',
+        },
+      ];
+
+    case 'firefox':
+      return [
+        {
+          number: 1,
+          title: 'Open Menu',
+          icon: Menu,
+          description: 'Click the menu button (three lines)',
+        },
+        {
+          number: 2,
+          title: 'Find Install Option',
+          icon: Search,
+          description: 'Look for "Install" or "Add to Home Screen"',
+        },
+        {
+          number: 3,
+          title: 'Confirm',
+          icon: Check,
+          description: 'Follow the installation prompts',
+        },
+      ];
+
+    case 'safari':
+      return [
+        {
+          number: 1,
+          title: 'Limited Support',
+          icon: Monitor,
+          description: 'Safari on macOS has limited PWA support',
+        },
+        {
+          number: 2,
+          title: 'Use Chromium Browser',
+          icon: ArrowDownToLine,
+          description: 'Consider using Chrome, Edge, or Brave for full PWA experience',
+        },
+      ];
+
+    default:
+      return [
+        {
+          number: 1,
+          title: 'Check Address Bar',
+          icon: ArrowDownToLine,
+          description: 'Look for an install or download icon',
+        },
+        {
+          number: 2,
+          title: 'Or Use Menu',
+          icon: Menu,
+          description: 'Check browser menu for install option',
+        },
+        {
+          number: 3,
+          title: 'Confirm',
+          icon: Check,
+          description: 'Follow the installation prompts',
+        },
+      ];
+  }
+}
+
+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 DesktopGuide({ onDismiss, open = true }: IOSGuideModalProps) {
+  const {
+    browserName,
+    isChromium,
+    isFirefox,
+    isSafari,
+    isEdge,
+    isBrave,
+    isArc,
+    isVivaldi,
+    isOpera,
+    isYandex,
+  } = useInstall();
+
+  const category = useMemo(
+    () => getBrowserCategory({ isChromium, isFirefox, isSafari }),
+    [isChromium, isFirefox, isSafari]
+  );
+
+  const steps = useMemo(() => getBrowserSteps(category, browserName), [category, browserName]);
+
+  // Get specific browser display name with emoji
+  const displayName = useMemo(() => {
+    if (isEdge) return 'Edge';
+    if (isBrave) return 'Brave';
+    if (isArc) return 'Arc';
+    if (isVivaldi) return 'Vivaldi';
+    if (isOpera) return 'Opera';
+    if (isYandex) return 'Yandex Browser';
+    return browserName;
+  }, [browserName, isEdge, isBrave, isArc, isVivaldi, isOpera, isYandex]);
+
+  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">
+            <Monitor className="w-5 h-5 text-primary" />
+            Install App on Desktop
+          </DialogTitle>
+          <DialogDescription className="text-left">
+            {isSafari
+              ? 'Safari on macOS has limited PWA support. For the best experience, use Chrome, Edge, or Brave.'
+              : `Install this app on ${displayName} for quick access from your desktop`
+            }
+          </DialogDescription>
+        </DialogHeader>
+
+        <div className="space-y-3 py-4">
+          {steps.map((step) => (
+            <StepCard key={step.number} step={step} />
+          ))}
+        </div>
+
+        {category === 'chromium' && (
+          <div className="p-3 bg-muted/30 rounded-lg text-xs text-muted-foreground">
+            💡 Tip: You can also right-click the page and look for "Install" option in {displayName}
+          </div>
+        )}
+
+        {category === 'firefox' && (
+          <div className="p-3 bg-amber-500/10 rounded-lg text-xs text-amber-700 dark:text-amber-400">
+            ℹ️ Note: Firefox has limited PWA support. Some features may not work as expected.
+          </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/{PWA → PWAInstall}/hooks/useInstallPrompt.ts

@@ -160,5 +160,8 @@ export function useInstallPrompt() {
   return {
     ...state,
     promptInstall,
+    // Expose full browser info
+    browser,
+    device,
   };
 }

package/src/snippets/{PWA → PWAInstall}/index.ts

@@ -1,20 +1,19 @@
 /**
- * PWA Install Flow (Simplified)
+ * PWA Install Snippet
  *
- * Ultra-simple PWA installation for Cmdop
- * No tracking, no metrics, no complexity — just install
+ * Simplified PWA installation for web apps
+ * Handles Add to Home Screen (A2HS) for iOS Safari and Android Chrome
  *
  * @example Basic usage
  * ```tsx
- * import { InstallProvider, A2HSHint } from './PwaInstall';
- * import { DEFAULT_VAPID_PUBLIC_KEY } from './config';
+ * import { PwaProvider, A2HSHint } from '@/snippets/PWAInstall';
  *
  * export default function Layout({ children }) {
  *   return (
- *     <InstallProvider>
+ *     <PwaProvider>
  *       {children}
  *       <A2HSHint resetAfterDays={3} />
- *     </InstallProvider>
+ *     </PwaProvider>
  *   );
  * }
  * ```
@@ -22,19 +21,12 @@
 
 // Main API
 export { PwaProvider, useInstall } from './context/InstallContext';
-export { PushProvider, usePush } from './context/PushContext';
-export type { PushMessage, PushContextValue } from './context/PushContext';
-
-// Django Integration
-export { DjangoPushProvider, useDjangoPushContext } from './context/DjangoPushContext';
 export { A2HSHint } from './components/A2HSHint';
-export { PushPrompt } from './components/PushPrompt';
-export { DEFAULT_VAPID_PUBLIC_KEY } from './config';
+export { IOSGuide } from './components/IOSGuide';
+export { DesktopGuide } from './components/DesktopGuide';
 
 // Hooks
 export { useIsPWA, clearIsPWACache, type UseIsPWAOptions } from './hooks/useIsPWA';
-export { usePushNotifications } from './hooks/usePushNotifications';
-export { useDjangoPush } from './hooks/useDjangoPush';
 
 // Utilities
 export {
@@ -53,24 +45,16 @@ export {
   isPWADebugEnabled,
 } from './utils/logger';
 
-export {
-  urlBase64ToUint8Array,
-  isValidVapidKey,
-  getVapidKeyInfo,
-  safeUrlBase64ToUint8Array,
-  VapidKeyError,
-  type VapidKeyErrorCode,
-} from './utils/vapid';
-
 export {
   STORAGE_KEYS,
   markA2HSDismissed,
-  markPushDismissed,
   isA2HSDismissedRecently,
-  isPushDismissedRecently,
-  clearAllPWAData,
+  clearAllPWAInstallData,
 } from './utils/localStorage';
 
+// Types - Configuration
+export type { PwaInstallConfig } from './types';
+
 // Types - Platform
 export type { PlatformInfo } from './types';
 
@@ -82,9 +66,6 @@ export type {
   IOSGuideState,
 } from './types';
 
-// Types - Push Notifications
-export type { PushNotificationState, PushNotificationOptions } from './types';
-
 // Types - Components
 export type {
   InstallContextType,

package/src/snippets/{PWA → PWAInstall}/types/components.ts

@@ -4,7 +4,6 @@
 
 import type { PlatformInfo } from './platform';
 import type { InstallOutcome } from './install';
-import type { PushNotificationState } from './push';
 
 /**
  * Install context type
@@ -22,11 +21,6 @@ export interface InstallContextType {
   // Actions
   promptInstall: () => Promise<InstallOutcome>;
   dismissIOSGuide: () => void;
-
-  // Push Notifications
-  pushState: PushNotificationState;
-  subscribeToPush: () => Promise<boolean>;
-  unsubscribeFromPush: () => Promise<boolean>;
 }
 
 /**

package/src/snippets/PWAInstall/types/config.ts

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

package/src/snippets/{PWA → PWAInstall}/types/index.ts

@@ -1,7 +1,10 @@
 /**
- * PWA Types - Central Export
+ * PWA Install Types - Central Export
  */
 
+// Configuration
+export type { PwaInstallConfig } from './config';
+
 // Platform
 export type { PlatformInfo } from './platform';
 
@@ -13,9 +16,6 @@ export type {
   IOSGuideState,
 } from './install';
 
-// Push Notifications
-export type { PushNotificationState, PushNotificationOptions } from './push';
-
 // Components
 export type {
   InstallContextType,

package/src/snippets/{PWA → PWAInstall}/utils/localStorage.ts

@@ -11,7 +11,6 @@ export const STORAGE_KEYS = {
   IOS_GUIDE_DISMISSED: 'pwa_ios_guide_dismissed_at',
   APP_INSTALLED: 'pwa_app_installed',
   A2HS_DISMISSED: 'pwa_a2hs_dismissed_at',
-  PUSH_DISMISSED: 'pwa_push_dismissed_at',
 } as const;
 
 /**
@@ -149,26 +148,6 @@ export function markA2HSDismissed(): void {
   }
 }
 
-/**
- * Check if push prompt was dismissed recently
- * @param resetDays Number of days before re-showing (default: 7)
- */
-export function isPushDismissedRecently(resetDays: number = 7): boolean {
-  return isDismissedRecentlyHelper(resetDays, STORAGE_KEYS.PUSH_DISMISSED);
-}
-
-/**
- * Mark push prompt as dismissed
- */
-export function markPushDismissed(): void {
-  if (typeof window === 'undefined') return;
-  try {
-    localStorage.setItem(STORAGE_KEYS.PUSH_DISMISSED, Date.now().toString());
-  } catch {
-    // Fail silently
-  }
-}
-
 /**
  * Helper: Check if a key was dismissed recently
  * @internal
@@ -189,14 +168,13 @@ function isDismissedRecentlyHelper(resetDays: number, key: string): boolean {
 /**
  * Clear all PWA install data
  */
-export function clearAllPWAData(): void {
+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);
-    localStorage.removeItem(STORAGE_KEYS.PUSH_DISMISSED);
   } catch {
     // Fail silently
   }