@djangocfg/ui-nextjs 2.1.226 → 2.1.228

package/README.md

@@ -241,6 +241,61 @@ function App({ children }) {
 - Opacity modifiers (`bg-background/80`) broken with HSL — use inline styles
 - Define spacing/z-index in `@theme` block
 
+## PWA Install
+
+Full Progressive Web App installation support — iOS/Android/Desktop, Add to Home Screen prompt, page resume.
+
+```tsx
+import { PwaProvider, A2HSHint, PWAPageResumeManager, useInstall } from '@djangocfg/ui-nextjs/pwa';
+
+// Wrap your app
+<PwaProvider enabled={true}>
+  {children}
+  <A2HSHint resetAfterDays={7} delayMs={3000} logo="/logo192.png" />
+  <PWAPageResumeManager enabled={true} />
+</PwaProvider>
+
+// In any component
+function InstallButton() {
+  const { canPrompt, install, isInstalled, isIOS, isAndroid } = useInstall();
+  if (isInstalled || (!canPrompt && !isIOS)) return null;
+  return <button onClick={install}>Install App</button>;
+}
+```
+
+### Hooks & Utilities
+
+```tsx
+import { useIsPWA, useInstall } from '@djangocfg/ui-nextjs/pwa';
+
+const isPWA = useIsPWA();                    // is running as installed PWA
+const { isIOS, isAndroid, canPrompt } = useInstall();
+```
+
+```tsx
+import {
+  isStandalone,          // window.matchMedia('display-mode: standalone')
+  isStandaloneReliable,  // standalone + navigator.standalone
+  isMobileDevice,        // iOS or Android
+  hasValidManifest,      // checks <link rel="manifest">
+  clearAllPWAInstallData, // reset localStorage flags
+} from '@djangocfg/ui-nextjs/pwa';
+```
+
+### Guide Components
+
+| Component | Description |
+|-----------|-------------|
+| `IOSGuide` | Step-by-step iOS Safari "Add to Home Screen" guide |
+| `DesktopGuide` | Desktop Chrome/Edge install guide |
+| `A2HSHint` | Floating hint bubble (auto-shows on eligible devices) |
+
+### Subpath Import
+
+```tsx
+import { ... } from '@djangocfg/ui-nextjs/pwa';
+```
+
 ## Requirements
 
 - Next.js >= 16

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@djangocfg/ui-nextjs",
-  "version": "2.1.226",
+  "version": "2.1.228",
   "description": "Next.js UI component library with Radix UI primitives, Tailwind CSS styling, charts, and form components",
   "keywords": [
     "ui-components",
@@ -64,6 +64,11 @@
       "import": "./src/theme/index.ts",
       "require": "./src/theme/index.ts"
     },
+    "./pwa": {
+      "types": "./src/pwa/index.ts",
+      "import": "./src/pwa/index.ts",
+      "require": "./src/pwa/index.ts"
+    },
     "./types/*": "./src/types/*",
     "./global": "./src/global.d.ts",
     "./styles": "./src/styles/index.css"
@@ -80,10 +85,11 @@
     "check": "tsc --noEmit"
   },
   "peerDependencies": {
-    "@djangocfg/api": "^2.1.226",
-    "@djangocfg/nextjs": "^2.1.226",
-    "@djangocfg/ui-core": "^2.1.226",
-    "@djangocfg/ui-tools": "^2.1.226",
+    "@djangocfg/api": "^2.1.228",
+    "@djangocfg/i18n": "^2.1.228",
+    "@djangocfg/nextjs": "^2.1.228",
+    "@djangocfg/ui-core": "^2.1.228",
+    "@djangocfg/ui-tools": "^2.1.228",
     "@types/react": "^19.1.0",
     "@types/react-dom": "^19.1.0",
     "consola": "^3.4.2",
@@ -106,7 +112,7 @@
     "react-chartjs-2": "^5.3.0"
   },
   "devDependencies": {
-    "@djangocfg/typescript-config": "^2.1.226",
+    "@djangocfg/typescript-config": "^2.1.228",
     "@radix-ui/react-dropdown-menu": "^2.1.16",
     "@radix-ui/react-slot": "^1.2.4",
     "@types/node": "^24.7.2",

package/src/components/sidebar.tsx

@@ -366,7 +366,9 @@ const SidebarInset = React.forwardRef<
 })
 SidebarInset.displayName = "SidebarInset"
 
-const SidebarInput = React.forwardRef<
+const SidebarInput: React.ForwardRefExoticComponent<
+  React.ComponentProps<typeof Input> & React.RefAttributes<HTMLInputElement>
+> = React.forwardRef<
   React.ElementRef<typeof Input>,
   React.ComponentProps<typeof Input>
 >(({ className, ...props }, ref) => {

package/src/pwa/@docs/README.md

@@ -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)