npm - @djangocfg/layouts - Versions diffs - 2.1.37 → 2.1.38 - Mend

@djangocfg/layouts 2.1.37 → 2.1.38

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (77) hide show

package/src/snippets/PWAInstall/@docs/README.md ADDED Viewed

@@ -0,0 +1,92 @@
+# PWAInstall Documentation
+Comprehensive documentation for the PWAInstall snippet.
+## Overview
+PWAInstall handles **Progressive Web App installation** on user devices (Add to Home Screen functionality).
+**Responsibility**: Device installation only (not push notifications)
+## Documentation Structure
+### `/research/`
+Research and best practices:
+- **[ios-android-install-flows.md](./research/ios-android-install-flows.md)** - iOS vs Android PWA installation patterns, limitations, and best practices (2024-2025)
+### `/architecture/`
+Architecture and design:
+- Coming soon: Architecture decisions, component design, state management
+### `/legacy/`
+Historical documentation:
+- Old architecture analysis (before snippet split)
+- Refactoring history
+## Quick Navigation
+### For Users
+Start here if you want to use PWAInstall:
+- [Main README](../README.md) - Quick start and API reference
+- [Migration Guide](../../MIGRATION.md) - Migrating from old PWA snippet
+### For Contributors
+Start here if you want to understand or modify PWAInstall:
+- [iOS/Android Install Flows](./research/ios-android-install-flows.md) - Platform-specific behavior
+- [Architecture](./architecture/) - How it's built
+### For Researchers
+Start here if you want to understand PWA installation patterns:
+- [Research](./research/) - Industry research and best practices
+## Key Concepts
+### Platform Asymmetry
+| Aspect | Android Chrome | iOS Safari |
+|--------|----------------|------------|
+| Install API | `beforeinstallprompt` | ❌ No API |
+| User effort | 1 tap | 3-4 taps |
+| Detection | Event-based | Heuristic |
+| Guidance | Optional | **Required** |
+**PWAInstall handles this asymmetry transparently.**
+### Components
+```
+A2HSHint (Unified hint)
+├── Android → Native install prompt
+└── iOS → Visual guide (IOSGuide)
+    ├── Mobile → IOSGuideDrawer
+    └── Desktop → IOSGuideModal
+```
+### State Management
+```
+useInstall() hook
+├── Platform detection (isIOS, isAndroid, isSafari)
+├── Installation state (isInstalled, canPrompt)
+└── Install action (install())
+```
+## Related Documentation
+- **[PushNotifications Docs](../../PushNotifications/@docs/)** - Web push notifications (separate concern)
+- **[Refactoring Summary](../../REFACTORING_SUMMARY.md)** - Why snippets were split
+- **[Migration Guide](../../MIGRATION.md)** - How to migrate from old PWA snippet
+## Contributing
+When adding documentation:
+1. **Research** → `/research/` - Industry patterns, browser behavior
+2. **Architecture** → `/architecture/` - Design decisions, component structure
+3. **Historical** → `/legacy/` - Old docs (keep for reference)
+## Questions?
+- Implementation questions → See [Main README](../README.md)
+- Architecture questions → See [/architecture/](./architecture/)
+- Platform behavior → See [/research/](./research/)
+- Migration questions → See [Migration Guide](../../MIGRATION.md)

package/src/snippets/PWAInstall/README.md ADDED Viewed

@@ -0,0 +1,185 @@
+# PWA Install
+Progressive Web App installation snippet for web applications.
+## Responsibility
+**Installation of PWA on user's device** (Add to Home Screen)
+- iOS Safari: Visual guide for manual installation
+- Android Chrome: Native install prompt
+- Unified UX across platforms
+- Smart dismissal with auto-reset
+## Quick Start
+```tsx
+// app/layout.tsx
+import { PwaProvider, A2HSHint } from '@/snippets/PWAInstall';
+export default function RootLayout({ children }) {
+  return (
+    <html>
+      <body>
+        <PwaProvider>
+          {children}
+          <A2HSHint resetAfterDays={3} />
+        </PwaProvider>
+      </body>
+    </html>
+  );
+}
+```
+## What You Get
+- **Unified UX** → Same hint position (bottom) for both iOS & Android
+- **iOS Safari** → Click hint → Opens visual step-by-step guide
+- **Android Chrome** → Click hint → Native install prompt
+- **Visual guide** → Adaptive (drawer on mobile, modal on desktop)
+- **Zero config** → Works out of the box
+- **Smart reset** → Re-appears after 3 days (user gets second chance)
+- **No spam** → Dismissible, respects user choice
+## API
+### `<PwaProvider>`
+Wrap your app once:
+```tsx
+<PwaProvider>
+  {children}
+</PwaProvider>
+```
+### `<A2HSHint />`
+Unified install hint for iOS & Android (auto-shows, dismissible):
+```tsx
+<A2HSHint
+  resetAfterDays={3}             // Default: 3 days (set to null for never)
+  delayMs={3000}                 // Default: 3 seconds
+  forceShow={isDevelopment}      // Show on ANY browser (for dev testing)
+  logo="/logo192.png"            // App logo URL (fallback: Share icon)
+/>
+```
+**Behavior (iOS Safari):**
+- Shows after 3 seconds
+- Text: "Keep terminal with you → Tap to learn how"
+- Click → Opens visual guide (adaptive: drawer on mobile, modal on desktop)
+- Dismissible (saved to localStorage)
+- Auto-resets after 3 days
+**Behavior (Android Chrome):**
+- Shows after 3 seconds
+- Text: "Install Cmdop → Tap to install"
+- Click → Triggers native install prompt
+- Dismissible (saved to localStorage)
+- Auto-resets after 3 days
+### `useInstall()` hook
+Access install state anywhere:
+```tsx
+import { useInstall } from '@/snippets/PWAInstall';
+function Header() {
+  const { isIOS, isInstalled, canPrompt, install } = useInstall();
+  return (
+    <header>
+      {canPrompt && <button onClick={install}>Install</button>}
+      {isInstalled && <span>✓ Installed</span>}
+    </header>
+  );
+}
+```
+**Returns:**
+```ts
+{
+  isIOS: boolean;
+  isAndroid: boolean;
+  isSafari: boolean;
+  isChrome: boolean;
+  isInstalled: boolean;
+  canPrompt: boolean;
+  install: () => Promise<'accepted' | 'dismissed' | null>;
+}
+```
+## Usage with Push Notifications
+Use together with the PushNotifications snippet:
+```tsx
+import { PwaProvider, A2HSHint } from '@/snippets/PWAInstall';
+import { DjangoPushProvider, PushPrompt } from '@/snippets/PushNotifications';
+export default function Layout({ children }) {
+  return (
+    <PwaProvider>
+      <DjangoPushProvider vapidPublicKey={VAPID_KEY}>
+        {children}
+        {/* PWA Install hint */}
+        <A2HSHint resetAfterDays={3} />
+        {/* Push notification prompt (after PWA install) */}
+        <PushPrompt
+          requirePWA={true}
+          delayMs={5000}
+          resetAfterDays={7}
+        />
+      </DjangoPushProvider>
+    </PwaProvider>
+  );
+}
+```
+## Browser Support
+| Platform | Browser | Support |
+|----------|---------|---------|
+| iOS | Safari | ✅ Visual guide |
+| iOS | Chrome/Firefox | ❌ No PWA support |
+| Android | Chrome | ✅ Native prompt |
+| Android | Firefox | ⚠️ Manual only |
+| Desktop | Chrome/Edge | ✅ Native prompt |
+## Architecture
+```
+PWAInstall/
+├── context/
+│   └── InstallContext.tsx      # Install state management
+├── components/
+│   ├── A2HSHint.tsx           # Unified install hint
+│   ├── IOSGuide.tsx           # Visual guide wrapper
+│   ├── IOSGuideDrawer.tsx     # Mobile guide
+│   └── IOSGuideModal.tsx      # Desktop guide
+├── hooks/
+│   ├── useInstallPrompt.ts    # Install prompt logic
+│   └── useIsPWA.ts            # PWA detection
+├── utils/
+│   ├── platform.ts            # Platform detection
+│   ├── localStorage.ts        # Persistence
+│   └── logger.ts              # Logging
+└── types/
+    ├── platform.ts
+    ├── install.ts
+    └── components.ts
+```
+## Separation from Push Notifications
+This snippet is **completely independent** from push notifications:
+- **PWAInstall** → Handles device installation
+- **PushNotifications** → Handles web push subscriptions
+Both can be used together or separately.

package/src/snippets/{PWA → PWAInstall}/components/A2HSHint.tsx RENAMED Viewed

@@ -9,9 +9,6 @@
  * - Unified UX: Same position, same style, same behavior
  *
  * Auto-resets after 3 days (configurable)
- *
- * Optionally shows push notification prompt after PWA installation
- * by providing pushNotifications.vapidPublicKey
  */
 import React, { useState, useEffect } from 'react';
@@ -21,10 +18,9 @@ import { cn } from '@djangocfg/ui-nextjs/lib';
 import { useInstall } from '../context/InstallContext';
 import { IOSGuide } from './IOSGuide';
-import { PushPrompt } from './PushPrompt';
+import { DesktopGuide } from './DesktopGuide';
 import { pwaLogger } from '../utils/logger';
 import { markA2HSDismissed, isA2HSDismissedRecently } from '../utils/localStorage';
-import type { PushNotificationOptions } from '../types';
 const DEFAULT_RESET_DAYS = 3;
@@ -48,58 +44,44 @@ interface A2HSHintProps {
   delayMs?: number;
   /**
-   * Force show on ANY browser (ignores platform detection)
-   * Useful for testing on desktop during development
+   * Demo mode - shows hint on all platforms with appropriate guides
+   * Production: only iOS Safari & Android Chrome
+   * Demo: shows on desktop too with desktop install guide
    * @default false
    */
-  forceShow?: boolean;
+  demo?: boolean;
   /**
    * App logo URL to display in hint
    * If not provided, uses Share icon
    */
   logo?: string;
-  /**
-   * Enable push notifications prompt after PWA install
-   * Provide VAPID public key to enable
-   */
-  pushNotifications?: PushNotificationOptions & {
-    /**
-     * Delay before showing push prompt after PWA install (ms)
-     * @default 5000
-     */
-    delayMs?: number;
-    /**
-     * Number of days before re-showing dismissed push prompt
-     * @default 7
-     */
-    resetAfterDays?: number;
-  };
 }
-export function A2HSHint({
+export function A2HSHint({
   className,
-  resetAfterDays = DEFAULT_RESET_DAYS,
-  delayMs = 3000,
-  forceShow = false,
-  logo,
-  pushNotifications
+  resetAfterDays = DEFAULT_RESET_DAYS,
+  delayMs = 3000,
+  demo = false,
+  logo,
 }: A2HSHintProps = {}) {
-  const { isIOS, isSafari, isInstalled, canPrompt, install } = useInstall();
+  const { isIOS, isSafari, isAndroid, isDesktop, isInstalled, canPrompt, install } = useInstall();
   const [show, setShow] = useState(false);
   const [showGuide, setShowGuide] = useState(false);
   const [installing, setInstalling] = useState(false);
   // Determine if should show hint
-  const shouldShow = forceShow || (!isInstalled && ((isIOS && isSafari) || canPrompt));
+  // Production: only iOS Safari & Android Chrome with native prompt
+  // Demo: show on all platforms (desktop, iOS, Android)
+  const shouldShow = demo
+    ? !isInstalled  // Demo: show on all platforms if not installed
+    : !isInstalled && ((isIOS && isSafari) || canPrompt);  // Production: only supported platforms
   useEffect(() => {
-    // Only show on iOS Safari or Android Chrome (unless forceShow for dev testing)
     if (!shouldShow) return;
-    // Check if previously dismissed (skip localStorage check if forceShow)
-    if (!forceShow && typeof window !== 'undefined') {
+    // Check if previously dismissed (skip localStorage check in demo mode)
+    if (!demo && typeof window !== 'undefined') {
       // If resetAfterDays is null, never reset (check with very large number)
       if (resetAfterDays === null) {
         if (isA2HSDismissedRecently(Number.MAX_SAFE_INTEGER)) {
@@ -113,25 +95,30 @@ export function A2HSHint({
     // Show after delay (user is already engaged)
     const timer = setTimeout(() => setShow(true), delayMs);
     return () => clearTimeout(timer);
-  }, [shouldShow, resetAfterDays, delayMs, forceShow]);
+  }, [shouldShow, resetAfterDays, delayMs, demo]);
   const handleDismiss = () => {
     setShow(false);
-    // Don't save to localStorage if forceShow (dev testing mode)
-    if (!forceShow) {
+    // Don't save to localStorage if demo mode (dev testing)
+    if (!demo) {
       markA2HSDismissed();
     }
   };
   const handleGuideDismiss = () => {
     setShowGuide(false);
-    // When guide is dismissed, also dismiss the hint
-    handleDismiss();
+    // In demo mode, keep hint visible after guide is dismissed
+    // In production mode, dismiss both guide and hint
+    if (!demo) {
+      handleDismiss();
+    }
   };
   const handleClick = async () => {
-    // forceShow (dev mode) or iOS: Open visual guide
-    if (forceShow || (isIOS && isSafari)) {
+    const isIOSPlatform = isIOS && isSafari;
+    // iOS or Desktop: Open visual guide
+    if (isIOSPlatform || isDesktop) {
       setShowGuide(true);
     } else if (canPrompt) {
       // Android: Trigger native install prompt
@@ -152,24 +139,47 @@ export function A2HSHint({
   // Platform-specific content
   const isIOSPlatform = isIOS && isSafari;
-  const title = isIOSPlatform ? 'Keep terminal with you' : 'Install Cmdop';
-  const subtitle = isIOSPlatform ? (
-    <>
-      Tap to learn how <ChevronRight className="w-3 h-3" />
-    </>
-  ) : (
-    <>
-      Tap to install <Download className="w-3 h-3" />
-    </>
-  );
+  // Determine which guide/action to show
+  let title: string;
+  let subtitle: React.ReactNode;
+  if (isIOSPlatform) {
+    title = 'Add to Home Screen';
+    subtitle = <>Tap to learn how <ChevronRight className="w-3 h-3" /></>;
+  } else if (isDesktop) {
+    title = 'Install App';
+    subtitle = <>Click to see desktop guide <ChevronRight className="w-3 h-3" /></>;
+  } else {
+    // Android or other mobile with native prompt
+    title = 'Install App';
+    subtitle = <>Tap to install <Download className="w-3 h-3" /></>;
+  }
   return (
     <>
       <div className={cn(
         "fixed bottom-4 left-4 right-4 z-50 animate-in slide-in-from-bottom-4 duration-300",
+        demo && "relative inset-auto z-auto",  // Demo mode: remove fixed positioning
         className
       )}>
-        <div className="w-full bg-zinc-900 border border-zinc-700 rounded-lg p-4 shadow-lg">
+        {/* Make entire card clickable */}
+        <div
+          role="button"
+          tabIndex={0}
+          onClick={handleClick}
+          onKeyDown={(e) => {
+            if (e.key === 'Enter' || e.key === ' ') {
+              e.preventDefault();
+              handleClick();
+            }
+          }}
+          className={cn(
+            "w-full bg-zinc-900 border border-zinc-700 rounded-lg p-4 shadow-lg cursor-pointer hover:bg-zinc-800 transition-colors",
+            installing && "opacity-70 cursor-not-allowed"
+          )}
+          aria-disabled={installing}
+        >
           <div className="flex items-center gap-3">
             {/* App logo or icon */}
             <div className="flex-shrink-0">
@@ -180,46 +190,37 @@ export function A2HSHint({
               )}
             </div>
-            {/* Content */}
+            {/* Content - now just displays, clicking anywhere triggers action */}
             <div className="flex-1 min-w-0">
               <p className="text-sm font-medium text-white mb-1">{title}</p>
-              <Button
-                onClick={handleClick}
-                loading={installing}
-                size="sm"
-                variant="ghost"
-                className="text-xs text-zinc-400 hover:text-zinc-300 p-0 h-auto font-normal flex items-center gap-1"
-              >
-                {subtitle}
-              </Button>
+              <p className="text-xs text-zinc-400 flex items-center gap-1">
+                {installing ? 'Installing...' : subtitle}
+              </p>
             </div>
-            {/* Close button */}
-            <Button
-              onClick={handleDismiss}
-              size="sm"
-              variant="ghost"
-              className="flex-shrink-0 p-1"
+            {/* Close button - prevent event bubbling */}
+            <button
+              onClick={(e) => {
+                e.stopPropagation();
+                handleDismiss();
+              }}
+              className="flex-shrink-0 p-1 hover:bg-zinc-700 rounded transition-colors"
               aria-label="Dismiss"
             >
-              <X className="w-4 h-4" />
-            </Button>
+              <X className="w-4 h-4 text-zinc-400" />
+            </button>
           </div>
         </div>
       </div>
-      {/* iOS or forceShow: Detailed guide modal - dismissing guide also dismisses hint */}
-      {(isIOSPlatform || forceShow) && <IOSGuide open={showGuide} onDismiss={handleGuideDismiss} />}
-      {/* Push Notifications Prompt - shown after PWA install if enabled */}
-      {pushNotifications?.vapidPublicKey && (
-        <PushPrompt
-          vapidPublicKey={pushNotifications.vapidPublicKey}
-          subscribeEndpoint={pushNotifications.subscribeEndpoint}
-          requirePWA={true}
-          delayMs={pushNotifications.delayMs || 5000}
-          resetAfterDays={pushNotifications.resetAfterDays || 7}
-        />
+      {/* Show appropriate guide based on platform */}
+      {(isIOSPlatform || (demo && isIOS)) && (
+        <IOSGuide open={showGuide} onDismiss={handleGuideDismiss} />
+      )}
+      {/* Desktop guide */}
+      {isDesktop && (
+        <DesktopGuide open={showGuide} onDismiss={handleGuideDismiss} />
       )}
     </>
   );