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

@djangocfg/layouts 2.1.37 → 2.1.39

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/PWA/README.md DELETED Viewed

@@ -1,387 +0,0 @@
-# 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/context/DjangoPushContext.tsx DELETED Viewed

@@ -1,105 +0,0 @@
-'use client';
-/**
- * Django Push Context
- *
- * Provider for Django-CFG push notifications integration.
- * Wraps useDjangoPush hook in React context for easy consumption.
- *
- * @example
- * ```tsx
- * import { DjangoPushProvider, useDjangoPushContext } from '@djangocfg/layouts/PWA';
- *
- * // In layout
- * <DjangoPushProvider vapidPublicKey={process.env.NEXT_PUBLIC_VAPID_KEY}>
- *   {children}
- * </DjangoPushProvider>
- *
- * // In component
- * function NotifyButton() {
- *   const { subscribe, isSubscribed } = useDjangoPushContext();
- *   return <button onClick={subscribe}>Subscribe</button>;
- * }
- * ```
- */
-import React, { createContext, useContext } from 'react';
-import { useDjangoPush } from '../hooks/useDjangoPush';
-import type { PushNotificationOptions } from '../types';
-interface DjangoPushContextValue {
-  // 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>;
-}
-const DjangoPushContext = createContext<DjangoPushContextValue | undefined>(undefined);
-interface DjangoPushProviderProps extends PushNotificationOptions {
-  children: React.ReactNode;
-  /**
-   * 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;
-}
-/**
- * Provider for Django push notifications
- */
-export function DjangoPushProvider({
-  children,
-  vapidPublicKey,
-  autoSubscribe = false,
-  onSubscribed,
-  onSubscribeError,
-  onUnsubscribed,
-}: DjangoPushProviderProps) {
-  const djangoPush = useDjangoPush({
-    vapidPublicKey,
-    autoSubscribe,
-    onSubscribed,
-    onSubscribeError,
-    onUnsubscribed,
-  });
-  return <DjangoPushContext.Provider value={djangoPush}>{children}</DjangoPushContext.Provider>;
-}
-/**
- * Hook to access Django push context
- */
-export function useDjangoPushContext(): DjangoPushContextValue {
-  const context = useContext(DjangoPushContext);
-  if (context === undefined) {
-    throw new Error('useDjangoPushContext must be used within DjangoPushProvider');
-  }
-  return context;
-}

package/src/snippets/PWA/context/InstallContext.tsx DELETED Viewed

@@ -1,118 +0,0 @@
-'use client';
-/**
- * Simplified 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 { A2HSHint } from '../components/A2HSHint';
-import type { InstallOutcome, PushNotificationOptions } from '../types';
-import { useInstallPrompt } from '../hooks/useInstallPrompt';
-import { PushProvider } from './PushContext';
-/**
- * Conditional PushProvider wrapper
- * Only wraps children if push notifications are enabled
- */
-function ConditionalPushProvider({
-  enabled,
-  children,
-  ...config
-}: PushNotificationOptions & { enabled: boolean; children: ReactNode }) {
-  if (!enabled) return <>{children}</>;
-  return <PushProvider {...config}>{children}</PushProvider>;
-}
-export interface PwaContextValue {
-  // Platform
-  isIOS: boolean;
-  isAndroid: boolean;
-  isSafari: boolean;
-  isChrome: boolean;
-  // State
-  isInstalled: boolean;
-  canPrompt: boolean;
-  // Actions
-  install: () => Promise<InstallOutcome>;
-}
-const PwaContext = createContext<PwaContextValue | undefined>(undefined);
-export interface PwaConfig {
-  enabled?: boolean;
-  showInstallHint?: boolean;
-  resetAfterDays?: number | null;
-  delayMs?: number;
-  logo?: string;
-  pushNotifications?: PushNotificationOptions & {
-    delayMs?: number;
-    resetAfterDays?: number;
-  };
-}
-export function PwaProvider({ children, ...config }: PwaConfig & { children: React.ReactNode }) {
-  // If not enabled, acts as a simple pass-through
-  if (config.enabled === false) {
-    return <>{children}</>;
-  }
-  const prompt = useInstallPrompt();
-  const value: PwaContextValue = {
-    isIOS: prompt.isIOS,
-    isAndroid: prompt.isAndroid,
-    isSafari: prompt.isSafari,
-    isChrome: prompt.isChrome,
-    isInstalled: prompt.isInstalled,
-    canPrompt: prompt.canPrompt,
-    install: prompt.promptInstall,
-  };
-  const showHint = config.showInstallHint !== false;
-  // ✅ Explicit composition tree (no magic wrapping)
-  // Structure:
-  // - PwaContext.Provider (PWA install state)
-  //   - ConditionalPushProvider (optional push notifications)
-  //     - children (user content)
-  //     - A2HSHint (PWA install hint UI)
-  return (
-    <PwaContext.Provider value={value}>
-      <ConditionalPushProvider
-        enabled={!!config.pushNotifications}
-        vapidPublicKey={config.pushNotifications?.vapidPublicKey || ''}
-        subscribeEndpoint={config.pushNotifications?.subscribeEndpoint}
-      >
-        {children}
-        {showHint && (
-          <A2HSHint
-            resetAfterDays={config.resetAfterDays}
-            delayMs={config.delayMs}
-            logo={config.logo}
-            pushNotifications={config.pushNotifications}
-          />
-        )}
-      </ConditionalPushProvider>
-    </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;
-}