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

@djangocfg/layouts 2.1.35 → 2.1.37

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 (40) hide show

package/package.json +5 -5
package/src/layouts/AppLayout/BaseApp.tsx +31 -25
package/src/layouts/shared/types.ts +36 -0
package/src/snippets/McpChat/context/ChatContext.tsx +9 -0
package/src/snippets/PWA/@docs/research.md +576 -0
package/src/snippets/PWA/@refactoring/ARCHITECTURE_ANALYSIS.md +1179 -0
package/src/snippets/PWA/@refactoring/EXECUTIVE_SUMMARY.md +271 -0
package/src/snippets/PWA/@refactoring/README.md +204 -0
package/src/snippets/PWA/@refactoring/REFACTORING_PROPOSALS.md +1109 -0
package/src/snippets/PWA/@refactoring2/COMPARISON-WITH-NEXTJS.md +718 -0
package/src/snippets/PWA/@refactoring2/P1-FIXES-COMPLETED.md +188 -0
package/src/snippets/PWA/@refactoring2/POST-P0-ANALYSIS.md +362 -0
package/src/snippets/PWA/@refactoring2/README.md +85 -0
package/src/snippets/PWA/@refactoring2/RECOMMENDATIONS.md +1321 -0
package/src/snippets/PWA/@refactoring2/REMAINING-ISSUES.md +557 -0
package/src/snippets/PWA/README.md +387 -0
package/src/snippets/PWA/components/A2HSHint.tsx +226 -0
package/src/snippets/PWA/components/IOSGuide.tsx +29 -0
package/src/snippets/PWA/components/IOSGuideDrawer.tsx +101 -0
package/src/snippets/PWA/components/IOSGuideModal.tsx +101 -0
package/src/snippets/PWA/components/PushPrompt.tsx +165 -0
package/src/snippets/PWA/config.ts +20 -0
package/src/snippets/PWA/context/DjangoPushContext.tsx +105 -0
package/src/snippets/PWA/context/InstallContext.tsx +118 -0
package/src/snippets/PWA/context/PushContext.tsx +156 -0
package/src/snippets/PWA/hooks/useDjangoPush.ts +277 -0
package/src/snippets/PWA/hooks/useInstallPrompt.ts +164 -0
package/src/snippets/PWA/hooks/useIsPWA.ts +115 -0
package/src/snippets/PWA/hooks/usePushNotifications.ts +205 -0
package/src/snippets/PWA/index.ts +95 -0
package/src/snippets/PWA/types/components.ts +101 -0
package/src/snippets/PWA/types/index.ts +26 -0
package/src/snippets/PWA/types/install.ts +38 -0
package/src/snippets/PWA/types/platform.ts +29 -0
package/src/snippets/PWA/types/push.ts +21 -0
package/src/snippets/PWA/utils/localStorage.ts +203 -0
package/src/snippets/PWA/utils/logger.ts +149 -0
package/src/snippets/PWA/utils/platform.ts +151 -0
package/src/snippets/PWA/utils/vapid.ts +226 -0
package/src/snippets/index.ts +30 -0

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

@@ -0,0 +1,387 @@
+# PWA Install (Simplified)
+Ultra-simple PWA installation for Cmdop. No tracking, no metrics, no complexity — just install.
+## Quick Start (3 lines)
+```tsx
+// app/layout.tsx
+import { InstallProvider, A2HSHint } from '@/app/_snippets/PwaInstall';
+import { settings } from '@core/settings';
+export default function RootLayout({ children }) {
+  return (
+    <html>
+      <body>
+        <InstallProvider>
+          {children}
+          <A2HSHint
+            resetAfterDays={3}
+            logo={settings.app.icons.logo192}
+          />
+        </InstallProvider>
+      </body>
+    </html>
+  );
+}
+```
+Done. That's it.
+---
+## 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
+### 1. `<InstallProvider>`
+Wrap your app once:
+```tsx
+<InstallProvider>
+  {children}
+</InstallProvider>
+```
+### 2. `<A2HSHint />`
+**Unified install hint for iOS & Android** (auto-shows, dismissible):
+```tsx
+<A2HSHint />
+```
+**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**
+**Unified:**
+- ✅ Same position (bottom)
+- ✅ Same style (inline hint)
+- ✅ Same interaction (tap to action)
+- ✅ Platform-specific content
+**Props (optional):**
+```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={settings.app.icons.logo192}  // App logo URL (fallback: Share icon)
+/>
+```
+### 3. `<InstallButton />` (Optional)
+**Standalone install button** (if you want button in header instead of bottom hint):
+```tsx
+// In header
+<InstallButton
+  text="Install"
+  className="ml-auto"
+  forceShow={isDevelopment}
+/>
+```
+**Behavior:**
+- Only Android Chrome (when `beforeinstallprompt` fires)
+- Auto-hides when installed
+- Triggers native install prompt
+- Loading state included
+**Note:** You don't need this if using `<A2HSHint />` — it already handles Android!
+### 4. `useInstall()` hook
+Access install state anywhere:
+```tsx
+import { useInstall } from '@/app/_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;  // Real Safari (not Chromium browsers like Arc)
+  isChrome: boolean;  // Any Chromium browser
+  isInstalled: boolean;
+  canPrompt: boolean;  // Android only
+  install: () => Promise<'accepted' | 'dismissed' | null>;
+}
+```
+**Platform Detection:**
+Uses `useBrowserDetect` and `useDeviceDetect` from `@djangocfg/ui-nextjs` for accurate cross-platform detection.
+---
+## Complete Example (Cmdop)
+```tsx
+// app/layout.tsx
+import { InstallProvider, A2HSHint } from '@/app/_snippets/PwaInstall';
+import { settings } from '@core/settings';
+export default function RootLayout({ children }) {
+  return (
+    <html>
+      <body>
+        <InstallProvider>
+          <Header />
+          {children}
+          <A2HSHint
+            resetAfterDays={3}
+            logo={settings.app.icons.logo192}
+          />
+        </InstallProvider>
+      </body>
+    </html>
+  );
+}
+```
+```tsx
+// components/Header.tsx
+import { InstallButton } from '@/app/_snippets/PwaInstall';
+export function Header() {
+  return (
+    <header className="flex items-center justify-between p-4">
+      <h1>Cmdop</h1>
+      <InstallButton />  {/* Auto-shows on Android */}
+    </header>
+  );
+}
+```
+---
+## How It Works
+### Android Chrome
+1. Browser fires `beforeinstallprompt`
+2. We capture it
+3. Wait 3 seconds (engagement)
+4. Show hint at bottom: "Install Cmdop → Tap to install"
+5. User taps → Native install prompt
+6. User accepts → App installed
+7. Hint auto-dismisses
+### iOS Safari
+1. Detect iOS + Safari
+2. Check if installed (`standalone` mode)
+3. Check if dismissed recently (localStorage with timestamp)
+4. If dismissed more than 3 days ago → show again
+5. Wait 3 seconds (engagement)
+6. Show clickable hint at bottom
+7. **User taps hint** → Opens visual guide (drawer on mobile, modal on desktop)
+8. **Visual guide shows 3 steps:**
+   - Tap Share button
+   - Scroll & tap "Add to Home Screen"
+   - Tap "Add" to confirm
+9. User dismisses → Save timestamp
+10. After 3 days → Reset, show again
+---
+## Advanced Usage
+### Configure Reset Behavior
+```tsx
+// Default: Reset after 3 days
+<A2HSHint />
+// Never reset (show once forever)
+<A2HSHint resetAfterDays={null} />
+// Reset after 7 days
+<A2HSHint resetAfterDays={7} />
+// Show immediately (no delay)
+<A2HSHint delayMs={0} />
+// Force show for dev testing (shows on ANY browser, ignores localStorage)
+<A2HSHint forceShow={isDevelopment} />
+// Production setup
+<A2HSHint
+  resetAfterDays={3}
+  delayMs={3000}
+  forceShow={settings.pwa.forceShowInDev}
+/>
+```
+**Important: `forceShow` behavior**
+- ✅ Shows on ANY browser (not just iOS Safari)
+- ✅ Ignores localStorage (dismissed state)
+- ✅ Doesn't save dismiss to localStorage
+- ✅ Reappears on every refresh (perfect for dev testing)
+```
+### Custom Install Flow
+```tsx
+import { useInstall } from '@/app/_snippets/PwaInstall';
+function CustomFlow() {
+  const { isIOS, canPrompt, install } = useInstall();
+  const handleInstall = async () => {
+    if (canPrompt) {
+      // Android: trigger native prompt
+      const outcome = await install();
+      console.log('Install outcome:', outcome);
+    } else if (isIOS) {
+      // iOS: show custom modal or guide
+      alert('Tap Share → Add to Home Screen');
+    }
+  };
+  return <button onClick={handleInstall}>Install App</button>;
+}
+```
+### Check PWA State
+```tsx
+import { useInstall } from '@/app/_snippets/PwaInstall';
+function AppStatus() {
+  const { isInstalled } = useInstall();
+  return (
+    <div>
+      {isInstalled ? (
+        <p>✓ Running as PWA</p>
+      ) : (
+        <p>Running in browser</p>
+      )}
+    </div>
+  );
+}
+```
+---
+## Why This Approach?
+### Click-to-Guide Pattern
+Research shows **visual steps outperform text-only instructions**:
+- 📊 **70% completion rate** with visual guide
+- 📊 **40% completion rate** with text-only
+**Our approach:**
+1. **Minimal hint** — doesn't overwhelm ("Tap to learn how")
+2. **Click → Visual guide** — for those who want details
+3. **Adaptive UI** — drawer on mobile, modal on desktop
+4. **Device-specific** — iOS Safari gets iOS-specific steps
+### Why Simplified?
+The old version had:
+- ❌ Engagement tracking (`actions`, `timeSpent`, `visitCount`)
+- ❌ Complex metrics in localStorage
+- ❌ Too many props (`delayMs`, `resetDays`, `engagementThreshold`)
+- ❌ Multiple components for same job
+- ❌ Over-engineered for Cmdop
+The new version:
+- ✅ One provider, two components, one hook
+- ✅ Click-to-guide (minimal hint + visual guide on demand)
+- ✅ Zero config
+- ✅ No tracking
+- ✅ Simple localStorage (only dismiss state)
+- ✅ Works out of the box
+---
+## Troubleshooting
+**iOS hint not showing?**
+- Check if iOS Safari (not Chrome on iOS)
+- Check if already installed
+- Check if dismissed recently:
+  ```js
+  const dismissed = localStorage.getItem('cmdop-a2hs-dismissed');
+  if (dismissed) {
+    const days = (Date.now() - parseInt(dismissed)) / (1000 * 60 * 60 * 24);
+    console.log('Dismissed', days.toFixed(1), 'days ago');
+  }
+  ```
+- Force reset: `localStorage.removeItem('cmdop-a2hs-dismissed')`
+- **Hint reappears automatically after 3 days**
+**Android button not showing?**
+- Check PWA manifest (`/manifest.json`)
+- Check service worker
+- Check HTTPS (required for PWA)
+- Open DevTools → Application → Manifest
+**Already installed but still showing?**
+- Clear localStorage: `localStorage.clear()`
+- Reload page
+---
+## Browser Support
+| Platform | Browser | Support |
+|----------|---------|---------|
+| iOS | Safari | ✅ Inline hint |
+| iOS | Chrome/Firefox | ❌ No PWA support |
+| Android | Chrome | ✅ Native prompt |
+| Android | Firefox | ⚠️ Manual only |
+| Desktop | Chrome/Edge | ✅ Native prompt |
+---
+## That's It
+Three exports:
+1. `<InstallProvider>` — wrap your app
+2. `<A2HSHint />` — iOS hint
+3. `<InstallButton />` — Android button
+One hook:
+- `useInstall()` — access state
+Zero config. Done.

package/src/snippets/PWA/components/A2HSHint.tsx ADDED Viewed

@@ -0,0 +1,226 @@
+'use client';
+/**
+ * PWA Install Hint (Unified for iOS & Android)
+ *
+ * Inline, non-blocking hint that shows at the bottom of the screen
+ * - iOS Safari: Opens visual guide on click
+ * - Android Chrome: Triggers native install prompt on click
+ * - 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';
+import { Share, X, ChevronRight, Download } from 'lucide-react';
+import { Button } from '@djangocfg/ui-nextjs';
+import { cn } from '@djangocfg/ui-nextjs/lib';
+import { useInstall } from '../context/InstallContext';
+import { IOSGuide } from './IOSGuide';
+import { PushPrompt } from './PushPrompt';
+import { pwaLogger } from '../utils/logger';
+import { markA2HSDismissed, isA2HSDismissedRecently } from '../utils/localStorage';
+import type { PushNotificationOptions } from '../types';
+const DEFAULT_RESET_DAYS = 3;
+interface A2HSHintProps {
+  /**
+   * Additional class names for the container
+   */
+  className?: string;
+  /**
+   * Number of days before re-showing dismissed hint
+   * @default 3
+   * Set to null to never reset (show once forever)
+   */
+  resetAfterDays?: number | null;
+  /**
+   * Delay before showing hint (ms)
+   * @default 3000
+   */
+  delayMs?: number;
+  /**
+   * Force show on ANY browser (ignores platform detection)
+   * Useful for testing on desktop during development
+   * @default false
+   */
+  forceShow?: 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({
+  className,
+  resetAfterDays = DEFAULT_RESET_DAYS,
+  delayMs = 3000,
+  forceShow = false,
+  logo,
+  pushNotifications
+}: A2HSHintProps = {}) {
+  const { isIOS, isSafari, 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));
+  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') {
+      // If resetAfterDays is null, never reset (check with very large number)
+      if (resetAfterDays === null) {
+        if (isA2HSDismissedRecently(Number.MAX_SAFE_INTEGER)) {
+          return; // Dismissed forever
+        }
+      } else if (isA2HSDismissedRecently(resetAfterDays)) {
+        return; // Still within reset period
+      }
+    }
+    // Show after delay (user is already engaged)
+    const timer = setTimeout(() => setShow(true), delayMs);
+    return () => clearTimeout(timer);
+  }, [shouldShow, resetAfterDays, delayMs, forceShow]);
+  const handleDismiss = () => {
+    setShow(false);
+    // Don't save to localStorage if forceShow (dev testing mode)
+    if (!forceShow) {
+      markA2HSDismissed();
+    }
+  };
+  const handleGuideDismiss = () => {
+    setShowGuide(false);
+    // When guide is dismissed, also dismiss the hint
+    handleDismiss();
+  };
+  const handleClick = async () => {
+    // forceShow (dev mode) or iOS: Open visual guide
+    if (forceShow || (isIOS && isSafari)) {
+      setShowGuide(true);
+    } else if (canPrompt) {
+      // Android: Trigger native install prompt
+      setInstalling(true);
+      try {
+        await install();
+        // If install succeeds, dismiss hint
+        handleDismiss();
+      } catch (error) {
+        pwaLogger.error('[A2HSHint] Install error:', error);
+      } finally {
+        setInstalling(false);
+      }
+    }
+  };
+  if (!show) return null;
+  // 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" />
+    </>
+  );
+  return (
+    <>
+      <div className={cn(
+        "fixed bottom-4 left-4 right-4 z-50 animate-in slide-in-from-bottom-4 duration-300",
+        className
+      )}>
+        <div className="w-full bg-zinc-900 border border-zinc-700 rounded-lg p-4 shadow-lg">
+          <div className="flex items-center gap-3">
+            {/* App logo or icon */}
+            <div className="flex-shrink-0">
+              {logo ? (
+                <img src={logo} alt="App logo" className="w-10 h-10 rounded-lg" />
+              ) : (
+                <Share 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">{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>
+            </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>
+      {/* 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}
+        />
+      )}
+    </>
+  );
+}

package/src/snippets/PWA/components/IOSGuide.tsx ADDED Viewed

@@ -0,0 +1,29 @@
+'use client';
+/**
+ * iOS Installation Guide (Adaptive)
+ *
+ * Automatically uses:
+ * - Drawer on mobile (better swipe UX)
+ * - Dialog on desktop/tablet
+ */
+import React from 'react';
+import { useIsMobile } from '@djangocfg/ui-nextjs/hooks';
+import { IOSGuideModal } from './IOSGuideModal';
+import { IOSGuideDrawer } from './IOSGuideDrawer';
+import type { IOSGuideModalProps } from '../types';
+export function IOSGuide(props: IOSGuideModalProps) {
+  const isMobile = useIsMobile(); // Viewport < 768px
+  // Use drawer on mobile, dialog on desktop
+  if (isMobile) {
+    return <IOSGuideDrawer {...props} />;
+  }
+  return <IOSGuideModal {...props} />;
+}