@djangocfg/layouts 2.1.36 → 2.1.38

package/src/snippets/PushNotifications/@docs/README.md

@@ -0,0 +1,191 @@
+# PushNotifications Documentation
+
+Comprehensive documentation for the PushNotifications snippet.
+
+## Overview
+
+PushNotifications handles **Web Push Notifications** - subscribing, receiving, and managing push notifications.
+
+**Responsibility**: Push notifications only (not PWA installation)
+
+## Documentation Structure
+
+### `/guides/`
+Step-by-step guides:
+- **[vapid-setup.md](./guides/vapid-setup.md)** - VAPID key generation and configuration
+- **[django-integration.md](./guides/django-integration.md)** - Integrating with Django-CFG backend
+- **[service-worker.md](./guides/service-worker.md)** - Service worker configuration
+
+### `/architecture/`
+Architecture and design:
+- Coming soon: Push subscription flow, state management, Django integration
+
+### `/legacy/`
+Historical documentation:
+- Old architecture (before snippet split)
+
+## Quick Navigation
+
+### For Users
+Start here if you want to use PushNotifications:
+- [Main README](../README.md) - Quick start and API reference
+- [VAPID Setup Guide](./guides/vapid-setup.md) - Generate and configure VAPID keys
+- [Django Integration](./guides/django-integration.md) - Backend integration
+
+### For Contributors
+Start here if you want to understand or modify PushNotifications:
+- [Architecture](./architecture/) - How it's built
+- [Service Worker Guide](./guides/service-worker.md) - SW integration
+
+### For Django Developers
+Start here if you're using Django-CFG backend:
+- [Django Integration Guide](./guides/django-integration.md) - Backend setup
+- [DjangoPushProvider API](../README.md#djangopushprovider) - Django-specific provider
+
+## Key Concepts
+
+### Push Subscription Flow
+
+```
+1. Request Permission
+   ↓
+2. Subscribe to Push Service
+   ↓
+3. Send Subscription to Backend
+   ↓
+4. Backend Sends Push → User Receives
+```
+
+### Components
+
+```
+PushPrompt (Permission prompt)
+├── Check permission state
+├── Request notification permission
+└── Subscribe to push service
+```
+
+### State Management
+
+```
+useDjangoPushContext() hook
+├── Permission state (permission, isSupported)
+├── Subscription state (isSubscribed, subscription)
+├── Actions (subscribe, unsubscribe, sendTestPush)
+└── Loading/Error states
+```
+
+### Providers
+
+**Generic (PushProvider)**:
+- For any backend
+- Custom endpoints
+- Manual subscription management
+
+**Django-specific (DjangoPushProvider)**:
+- Django-CFG integration
+- Auto-configured endpoints
+- Built-in error handling
+
+## Browser Support
+
+| Platform | Browser | Support |
+|----------|---------|---------|
+| iOS | Safari 16.4+ | ✅ Push supported |
+| iOS | Chrome/Firefox | ❌ No push support |
+| Android | Chrome | ✅ Full support |
+| Android | Firefox | ✅ Full support |
+| Desktop | Chrome/Edge/Firefox | ✅ Full support |
+
+**Important**: iOS push requires Safari 16.4+ and PWA installation.
+
+## Security: VAPID Keys
+
+### What are VAPID keys?
+
+**VAPID** (Voluntary Application Server Identification) authenticates your push notifications.
+
+- **Public key**: Safe to expose in frontend
+- **Private key**: ⚠️ **NEVER** expose (backend only)
+
+### Generate VAPID Keys
+
+```bash
+npx web-push generate-vapid-keys
+```
+
+### Configuration
+
+```env
+# Frontend (PUBLIC)
+NEXT_PUBLIC_VAPID_PUBLIC_KEY=BM8xT...
+
+# Backend (PRIVATE - never expose!)
+VAPID_PRIVATE_KEY=your_private_key
+VAPID_MAILTO=mailto:you@example.com
+```
+
+**See**: [VAPID Setup Guide](./guides/vapid-setup.md) for details.
+
+## Related Documentation
+
+- **[PWAInstall Docs](../../PWAInstall/@docs/)** - PWA installation (separate concern)
+- **[Refactoring Summary](../../REFACTORING_SUMMARY.md)** - Why snippets were split
+- **[Migration Guide](../../MIGRATION.md)** - How to migrate from old PWA snippet
+
+## Usage Examples
+
+### Basic Usage
+
+```tsx
+import { DjangoPushProvider, PushPrompt } from '@/snippets/PushNotifications';
+
+<DjangoPushProvider vapidPublicKey={VAPID_KEY}>
+  <PushPrompt requirePWA={true} />
+</DjangoPushProvider>
+```
+
+### With PWA Install
+
+```tsx
+import { PwaProvider, A2HSHint } from '@/snippets/PWAInstall';
+import { DjangoPushProvider, PushPrompt } from '@/snippets/PushNotifications';
+
+<PwaProvider>
+  <DjangoPushProvider vapidPublicKey={VAPID_KEY}>
+    <A2HSHint />
+    <PushPrompt requirePWA={true} delayMs={5000} />
+  </DjangoPushProvider>
+</PwaProvider>
+```
+
+### Manual Control
+
+```tsx
+import { useDjangoPushContext } from '@/snippets/PushNotifications';
+
+function NotifyButton() {
+  const { subscribe, isSubscribed, sendTestPush } = useDjangoPushContext();
+
+  return (
+    <button onClick={isSubscribed ? sendTestPush : subscribe}>
+      {isSubscribed ? 'Test' : 'Enable'} Notifications
+    </button>
+  );
+}
+```
+
+## Contributing
+
+When adding documentation:
+1. **Guides** → `/guides/` - Step-by-step tutorials
+2. **Architecture** → `/architecture/` - Design decisions, flows
+3. **Historical** → `/legacy/` - Old docs (keep for reference)
+
+## Questions?
+
+- Implementation questions → See [Main README](../README.md)
+- VAPID setup → See [VAPID Guide](./guides/vapid-setup.md)
+- Django integration → See [Django Guide](./guides/django-integration.md)
+- Service worker → See [SW Guide](./guides/service-worker.md)
+- Migration questions → See [Migration Guide](../../MIGRATION.md)