@djangocfg/layouts 2.1.36 → 2.1.38

package/src/snippets/PushNotifications/utils/platform.ts

@@ -0,0 +1,151 @@
+/**
+ * Platform Detection Utilities
+ *
+ * Centralized utilities for detecting PWA state, platform, and capabilities.
+ * Used by hooks to avoid code duplication.
+ */
+
+/**
+ * Check if running as PWA (standalone mode)
+ *
+ * Checks if the app is running in standalone mode (added to home screen).
+ * This is the primary indicator that a PWA has been installed.
+ *
+ * @returns true if app is running in standalone mode
+ *
+ * @example
+ * ```typescript
+ * if (isStandalone()) {
+ *   console.log('Running as PWA');
+ * }
+ * ```
+ */
+export function isStandalone(): boolean {
+  if (typeof window === 'undefined') return false;
+
+  // Fallback for older browsers without matchMedia
+  if (!window.matchMedia) {
+    // Use legacy iOS check only
+    const nav = navigator as Navigator & { standalone?: boolean };
+    return nav.standalone === true;
+  }
+
+  // Check display-mode media query (modern approach)
+  const isStandaloneDisplay = window.matchMedia('(display-mode: standalone)').matches;
+
+  // Legacy iOS check (navigator.standalone)
+  const nav = navigator as Navigator & { standalone?: boolean };
+  const isStandaloneNavigator = nav.standalone === true;
+
+  return isStandaloneDisplay || isStandaloneNavigator;
+}
+
+/**
+ * Check if device is mobile
+ *
+ * @returns true if device is mobile (iOS, Android, etc.)
+ */
+export function isMobileDevice(): boolean {
+  if (typeof window === 'undefined') return false;
+  return /iPhone|iPad|iPod|Android/i.test(navigator.userAgent);
+}
+
+/**
+ * Check if web app manifest exists and is valid
+ *
+ * @returns true if manifest link exists in document head
+ */
+export function hasValidManifest(): boolean {
+  if (typeof document === 'undefined') return false;
+  const manifestLink = document.querySelector('link[rel="manifest"]');
+  return !!manifestLink;
+}
+
+/**
+ * Reliable check for PWA mode with edge case handling
+ *
+ * This function provides additional validation for desktop browsers
+ * to avoid false positives (e.g., Safari macOS "Add to Dock").
+ *
+ * For mobile devices, standard standalone check is sufficient.
+ * For desktop, additionally validates that a manifest exists.
+ *
+ * @returns true if app is running as a genuine PWA
+ *
+ * @example
+ * ```typescript
+ * // Use this for more reliable detection
+ * if (isStandaloneReliable()) {
+ *   console.log('Definitely running as PWA');
+ * }
+ * ```
+ */
+export function isStandaloneReliable(): boolean {
+  const standalone = isStandalone();
+  if (!standalone) return false;
+
+  // For mobile devices, standalone check is sufficient
+  if (isMobileDevice()) return true;
+
+  // For desktop browsers, additionally check for valid manifest
+  // This prevents false positives like Safari macOS "Add to Dock"
+  return hasValidManifest();
+}
+
+/**
+ * Get display mode from media query
+ *
+ * @returns Current display mode: 'standalone', 'fullscreen', 'minimal-ui', or 'browser'
+ */
+export function getDisplayMode(): 'standalone' | 'fullscreen' | 'minimal-ui' | 'browser' {
+  if (typeof window === 'undefined') return 'browser';
+
+  if (!window.matchMedia) return 'browser';
+
+  const modes: Array<'standalone' | 'fullscreen' | 'minimal-ui'> = [
+    'fullscreen',
+    'standalone',
+    'minimal-ui',
+  ];
+
+  for (const mode of modes) {
+    if (window.matchMedia(`(display-mode: ${mode})`).matches) {
+      return mode;
+    }
+  }
+
+  return 'browser';
+}
+
+/**
+ * Create a media query listener for display-mode changes
+ *
+ * @param callback - Function to call when display mode changes
+ * @returns Cleanup function to remove listener
+ *
+ * @example
+ * ```typescript
+ * const cleanup = onDisplayModeChange((isStandalone) => {
+ *   console.log('Display mode changed:', isStandalone);
+ * });
+ *
+ * // Later: cleanup();
+ * ```
+ */
+export function onDisplayModeChange(callback: (isStandalone: boolean) => void): () => void {
+  if (typeof window === 'undefined' || !window.matchMedia) {
+    return () => {}; // No-op cleanup
+  }
+
+  const mediaQuery = window.matchMedia('(display-mode: standalone)');
+
+  const handleChange = (e: MediaQueryListEvent) => {
+    callback(e.matches);
+  };
+
+  mediaQuery.addEventListener('change', handleChange);
+
+  return () => {
+    mediaQuery.removeEventListener('change', handleChange);
+  };
+}

package/src/snippets/PushNotifications/utils/vapid.ts

@@ -0,0 +1,226 @@
+/**
+ * VAPID Key Utilities
+ *
+ * Provides validation and conversion utilities for VAPID public keys
+ * used in push notification subscriptions.
+ *
+ * VAPID keys must be:
+ * - Base64url encoded
+ * - 65 bytes after decoding (P-256 uncompressed public key)
+ * - Start with 0x04 (uncompressed point indicator)
+ */
+
+/**
+ * Custom error class for VAPID key validation failures
+ */
+export class VapidKeyError extends Error {
+  constructor(
+    message: string,
+    public readonly code: VapidKeyErrorCode
+  ) {
+    super(message);
+    this.name = 'VapidKeyError';
+  }
+}
+
+/**
+ * Error codes for VAPID key validation
+ */
+export type VapidKeyErrorCode =
+  | 'VAPID_EMPTY'
+  | 'VAPID_INVALID_TYPE'
+  | 'VAPID_INVALID_BASE64'
+  | 'VAPID_INVALID_LENGTH'
+  | 'VAPID_INVALID_FORMAT';
+
+/**
+ * Convert base64url VAPID public key to Uint8Array
+ *
+ * Validates and converts a VAPID public key from base64url format
+ * to Uint8Array for use with PushManager.subscribe().
+ *
+ * @param base64String - VAPID public key in base64url format
+ * @returns Uint8Array ready for pushManager.subscribe()
+ * @throws VapidKeyError if key is invalid
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   const key = urlBase64ToUint8Array(process.env.NEXT_PUBLIC_VAPID_PUBLIC_KEY);
+ *   await registration.pushManager.subscribe({
+ *     userVisibleOnly: true,
+ *     applicationServerKey: key,
+ *   });
+ * } catch (e) {
+ *   if (e instanceof VapidKeyError) {
+ *     console.error('Invalid VAPID key:', e.message, e.code);
+ *   }
+ * }
+ * ```
+ */
+export function urlBase64ToUint8Array(base64String: string): Uint8Array {
+  // 1. Validate input
+  if (!base64String) {
+    throw new VapidKeyError('VAPID public key is required', 'VAPID_EMPTY');
+  }
+
+  if (typeof base64String !== 'string') {
+    throw new VapidKeyError('VAPID public key must be a string', 'VAPID_INVALID_TYPE');
+  }
+
+  // 2. Convert base64url to base64
+  // base64url uses '-' and '_' instead of '+' and '/'
+  const padding = '='.repeat((4 - (base64String.length % 4)) % 4);
+  const base64 = (base64String + padding).replace(/-/g, '+').replace(/_/g, '/');
+
+  // 3. Decode base64
+  let rawData: string;
+  try {
+    rawData = window.atob(base64);
+  } catch (e) {
+    throw new VapidKeyError(
+      `Invalid base64url format: ${e instanceof Error ? e.message : String(e)}`,
+      'VAPID_INVALID_BASE64'
+    );
+  }
+
+  // 4. Convert to Uint8Array
+  const outputArray = new Uint8Array(rawData.length);
+  for (let i = 0; i < rawData.length; i++) {
+    outputArray[i] = rawData.charCodeAt(i);
+  }
+
+  // 5. Validate length (P-256 uncompressed = 65 bytes)
+  // Format: 0x04 (1 byte) + X coordinate (32 bytes) + Y coordinate (32 bytes)
+  if (outputArray.length !== 65) {
+    throw new VapidKeyError(
+      `Invalid key length: expected 65 bytes (P-256 uncompressed), got ${outputArray.length} bytes`,
+      'VAPID_INVALID_LENGTH'
+    );
+  }
+
+  // 6. Validate format (must start with 0x04 for uncompressed P-256 point)
+  if (outputArray[0] !== 0x04) {
+    throw new VapidKeyError(
+      `Invalid key format: must start with 0x04 (uncompressed P-256 point), got 0x${outputArray[0]
+        .toString(16)
+        .padStart(2, '0')}`,
+      'VAPID_INVALID_FORMAT'
+    );
+  }
+
+  return outputArray;
+}
+
+/**
+ * Validate VAPID key without conversion
+ *
+ * Checks if a VAPID key is valid without converting it.
+ * Useful for validation before attempting subscription.
+ *
+ * @param base64String - VAPID public key to validate
+ * @returns true if key is valid
+ *
+ * @example
+ * ```typescript
+ * if (isValidVapidKey(vapidKey)) {
+ *   // Proceed with subscription
+ * } else {
+ *   console.error('Invalid VAPID key configuration');
+ * }
+ * ```
+ */
+export function isValidVapidKey(base64String: string): boolean {
+  try {
+    urlBase64ToUint8Array(base64String);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Get VAPID key information for debugging
+ *
+ * Returns detailed information about a VAPID key for troubleshooting.
+ *
+ * @param base64String - VAPID public key to inspect
+ * @returns Key information object
+ *
+ * @example
+ * ```typescript
+ * const info = getVapidKeyInfo(process.env.NEXT_PUBLIC_VAPID_PUBLIC_KEY);
+ * console.log('VAPID Key Info:', info);
+ * // {
+ * //   valid: true,
+ * //   length: 65,
+ * //   firstByte: '0x04',
+ * //   format: 'P-256 uncompressed'
+ * // }
+ * ```
+ */
+export function getVapidKeyInfo(base64String: string): {
+  valid: boolean;
+  length?: number;
+  firstByte?: string;
+  format?: string;
+  error?: string;
+  errorCode?: VapidKeyErrorCode;
+} {
+  try {
+    const key = urlBase64ToUint8Array(base64String);
+    return {
+      valid: true,
+      length: key.length,
+      firstByte: `0x${key[0].toString(16).padStart(2, '0')}`,
+      format: key[0] === 0x04 ? 'P-256 uncompressed' : 'Unknown',
+    };
+  } catch (e) {
+    if (e instanceof VapidKeyError) {
+      return {
+        valid: false,
+        error: e.message,
+        errorCode: e.code,
+      };
+    }
+    return {
+      valid: false,
+      error: String(e),
+    };
+  }
+}
+
+/**
+ * Safe VAPID key conversion with error handling
+ *
+ * Attempts to convert a VAPID key with detailed error logging.
+ * Returns null on failure instead of throwing.
+ *
+ * @param base64String - VAPID public key
+ * @param onError - Optional error callback
+ * @returns Uint8Array or null if conversion fails
+ *
+ * @example
+ * ```typescript
+ * const key = safeUrlBase64ToUint8Array(vapidKey, (error) => {
+ *   console.error('VAPID conversion failed:', error.message, error.code);
+ * });
+ *
+ * if (key) {
+ *   // Use key for subscription
+ * }
+ * ```
+ */
+export function safeUrlBase64ToUint8Array(
+  base64String: string,
+  onError?: (error: VapidKeyError) => void
+): Uint8Array | null {
+  try {
+    return urlBase64ToUint8Array(base64String);
+  } catch (e) {
+    if (e instanceof VapidKeyError) {
+      onError?.(e);
+    }
+    return null;
+  }
+}

package/src/snippets/index.ts

@@ -43,3 +43,58 @@ export type {
   UseMcpChatReturn,
   AskAIButtonProps,
 } from './McpChat';
+
+// PWA Install (Progressive Web App Installation)
+export {
+  PwaProvider,
+  useInstall,
+  A2HSHint,
+  IOSGuide,
+  DesktopGuide,
+  useIsPWA,
+  clearIsPWACache,
+  clearAllPWAInstallData,
+  isStandalone,
+  isStandaloneReliable,
+  isMobileDevice,
+  hasValidManifest,
+  getDisplayMode,
+  onDisplayModeChange,
+} from './PWAInstall';
+export type {
+  PlatformInfo,
+  InstallPromptState,
+  BeforeInstallPromptEvent,
+  InstallOutcome,
+  IOSGuideState,
+  InstallContextType,
+  InstallManagerProps,
+  AndroidInstallButtonProps,
+  IOSGuideModalProps,
+  InstallStep,
+  UseIsPWAOptions,
+} from './PWAInstall';
+
+// Push Notifications
+export {
+  PushProvider,
+  usePush,
+  DjangoPushProvider,
+  useDjangoPushContext,
+  PushPrompt,
+  usePushNotifications,
+  useDjangoPush,
+  DEFAULT_VAPID_PUBLIC_KEY,
+  urlBase64ToUint8Array,
+  isValidVapidKey,
+  getVapidKeyInfo,
+  safeUrlBase64ToUint8Array,
+  VapidKeyError,
+  clearAllPushData,
+} from './PushNotifications';
+export type {
+  PushNotificationState,
+  PushNotificationOptions,
+  PushMessage,
+  VapidKeyErrorCode,
+} from './PushNotifications';

package/src/layouts/shared/index.ts

@@ -1,21 +0,0 @@
-/**
- * Shared Layouts Exports
- */
-
-export type {
-  ThemeConfig,
-  LayoutErrorTrackingConfig,
-  ErrorBoundaryConfig,
-  SWRConfigOptions,
-  McpChatConfig,
-  BaseLayoutProps,
-  NavigationItem,
-  NavigationSection,
-  FooterLink,
-  FooterMenuSection,
-  FooterSocialLinks,
-  FooterConfig,
-  UserMenuItem,
-  UserMenuGroup,
-  UserMenuConfig,
-} from './types';

package/src/layouts/shared/types.ts

@@ -1,211 +0,0 @@
-/**
- * Shared Types for All Layouts
- *
- * Universal type system to avoid duplication across layouts
- */
-
-import type { ReactNode } from 'react';
-import type { LucideIcon } from 'lucide-react';
-import type { AuthConfig } from '@djangocfg/api/auth';
-
-// ============================================================================
-// Theme Configuration
-// ============================================================================
-
-export interface ThemeConfig {
-  defaultTheme?: 'light' | 'dark' | 'system';
-  storageKey?: string;
-}
-
-// ============================================================================
-// Error Tracking Configuration
-// ============================================================================
-
-/**
- * Error tracking configuration for layouts
- * Note: Import detailed types from @djangocfg/layouts/components if needed
- */
-export interface LayoutErrorTrackingConfig {
-  validation?: {
-    enabled?: boolean;
-    showToast?: boolean;
-  };
-  cors?: {
-    enabled?: boolean;
-    showToast?: boolean;
-  };
-  network?: {
-    enabled?: boolean;
-    showToast?: boolean;
-  };
-  onError?: (error: any) => boolean | void;
-}
-
-// ============================================================================
-// Error Boundary Configuration
-// ============================================================================
-
-export interface ErrorBoundaryConfig {
-  enabled?: boolean;
-  supportEmail?: string;
-  onError?: (error: Error, errorInfo: React.ErrorInfo) => void;
-}
-
-// ============================================================================
-// SWR Configuration
-// ============================================================================
-
-export interface SWRConfigOptions {
-  revalidateOnFocus?: boolean;
-  revalidateOnReconnect?: boolean;
-  dedupingInterval?: number;
-}
-
-// ============================================================================
-// MCP Chat Configuration
-// ============================================================================
-
-export interface McpChatConfig {
-  /** Enable MCP chat widget */
-  enabled?: boolean;
-  /** API endpoint for chat */
-  apiEndpoint?: string;
-  /** Chat widget title */
-  title?: string;
-  /** Input placeholder */
-  placeholder?: string;
-  /** Greeting message */
-  greeting?: string;
-  /** Widget position */
-  position?: 'bottom-right' | 'bottom-left';
-  /** Widget variant */
-  variant?: 'default' | 'minimal';
-  /** Enable streaming responses */
-  enableStreaming?: boolean;
-  /** Auto-detect environment (dev/prod) */
-  autoDetectEnvironment?: boolean;
-  /** Custom class name */
-  className?: string;
-}
-
-// ============================================================================
-// Base Layout Props
-// ============================================================================
-
-export interface BaseLayoutProps {
-  children: ReactNode;
-
-  /** Theme configuration */
-  theme?: ThemeConfig;
-
-  /** Auth configuration */
-  auth?: AuthConfig;
-
-  /** Error tracking configuration */
-  errorTracking?: LayoutErrorTrackingConfig;
-
-  /** SWR configuration */
-  swr?: SWRConfigOptions;
-
-  /** Error boundary configuration (enabled by default) */
-  errorBoundary?: ErrorBoundaryConfig;
-
-  /** MCP chat configuration */
-  mcpChat?: McpChatConfig;
-}
-
-// ============================================================================
-// Navigation Types
-// ============================================================================
-
-export interface NavigationItem {
-  label: string;
-  href: string;
-  icon?: LucideIcon | string;
-  badge?: string | number;
-  external?: boolean;
-}
-
-export interface NavigationSection {
-  title?: string;
-  items: NavigationItem[];
-}
-
-// ============================================================================
-// Footer Types
-// ============================================================================
-
-export interface FooterLink {
-  label: string;
-  path: string;
-  external?: boolean;
-}
-
-export interface FooterMenuSection {
-  title: string;
-  items: FooterLink[];
-}
-
-export interface FooterSocialLinks {
-  github?: string;
-  linkedin?: string;
-  twitter?: string;
-  telegram?: string;
-  youtube?: string;
-  facebook?: string;
-  instagram?: string;
-  whatsapp?: string;
-  email?: string;
-}
-
-export interface FooterConfig {
-  siteName?: string;
-  description?: string;
-  logo?: string;
-  badge?: {
-    icon: LucideIcon;
-    text: string;
-  };
-  socialLinks?: FooterSocialLinks;
-  links?: FooterLink[];
-  menuSections?: FooterMenuSection[];
-  copyright?: string;
-  credits?: {
-    text: string;
-    url?: string;
-  };
-  variant?: 'full' | 'simple';
-}
-
-// ============================================================================
-// User Menu Types
-// ============================================================================
-
-export interface UserMenuItem {
-  /** Menu item label */
-  label: string;
-  /** Link href (optional if onClick is provided) */
-  href?: string;
-  /** Icon component */
-  icon?: LucideIcon;
-  /** Visual variant */
-  variant?: 'default' | 'destructive';
-  /** Click handler (optional if href is provided) */
-  onClick?: () => void;
-  /** Open link in new tab */
-  external?: boolean;
-}
-
-export interface UserMenuGroup {
-  /** Optional group title (renders DropdownMenuLabel) */
-  title?: string;
-  /** Menu items in this group */
-  items: UserMenuItem[];
-}
-
-export interface UserMenuConfig {
-  /** Menu groups for authenticated users */
-  groups?: UserMenuGroup[];
-  /** Auth page path (for sign in button) */
-  authPath?: string;
-}