@djangocfg/ui-nextjs 2.1.294 → 2.1.297

package/README.md

@@ -43,23 +43,20 @@ Peer dependencies: `next`, `next-intl`, `react`, `tailwindcss`.
 ### From ui-core (60)
 All components from `@djangocfg/ui-core` are re-exported.
 
-### Next.js Specific (11)
+### Next.js Specific
 
 | Component | Description |
 |-----------|-------------|
-| `NextLink` | Locale-aware link wrapper |
-| `NextButtonLink` | Button-styled locale-aware link with variants |
-| `Sidebar` | Locale-aware collapsible sidebar; `SidebarTrigger` shows an OS-aware tooltip (`⌘+B` / `Ctrl+B`); `SidebarMenuButton` accepts `tooltip` for icon-rail hints |
-| `Breadcrumb` | Locale-aware breadcrumbs |
+| `Sidebar` | Collapsible sidebar; `SidebarTrigger` shows an OS-aware tooltip (`⌘+B` / `Ctrl+B`); `SidebarMenuButton` accepts `tooltip` for icon-rail hints |
+| `Breadcrumb` | Breadcrumb primitives (uses ui-core `<Link>`) |
 | `BreadcrumbNavigation` | High-level breadcrumb component |
-| `NavigationMenu` | Locale-aware navigation menu |
-| `Menubar` | Locale-aware menubar |
-| `DropdownMenu` | Menu with locale-aware link items |
-| `Pagination` | Locale-aware page links |
+| `Pagination` | Pagination link primitives |
 | `SSRPagination` | Server-compatible pagination |
-| `DownloadButton` | Uses `localStorage` for auth |
+| `DropdownMenu` | Local override of ui-core `DropdownMenu` (kept for legacy ui-nextjs callers) |
 
-All link-based components use `next-intl` internally — no configuration needed.
+> **Links**: use `<Link>` and `<ButtonLink>` from `@djangocfg/ui-core/components` directly.
+> Mounted via `NextLinkProvider` (in `BaseApp` from `@djangocfg/layouts`), they
+> render through `next/link` — so prefetch / RSC handling work as expected.
 
 ### MultiSelect Pro
 `MultiSelectPro` `MultiSelectProAsync` — Advanced multi-select with async loading
@@ -134,60 +131,56 @@ See ui-core README for full documentation.
 
 ```tsx
 import {
-  Button, Card, Input,  // from ui-core
-  NextButtonLink, Sidebar  // Next.js locale-aware
+  Button, ButtonLink, Card, Input, Sidebar
 } from '@djangocfg/ui-nextjs';
-import { useNavigation, useLocalStorage } from '@djangocfg/ui-nextjs/hooks';
+import { useNavigate } from '@djangocfg/ui-core/hooks';
+import { useLocalStorage } from '@djangocfg/ui-nextjs/hooks';
 
 function Example() {
-  const { router, pathname } = useNavigation();
+  const { navigate } = useNavigate();
   const [saved, setSaved] = useLocalStorage('form', null);
 
   return (
     <Sidebar>
       <Card>
         <Input placeholder="Email" />
-        <Button onClick={() => router.push('/dashboard')}>
+        <Button onClick={() => navigate('/dashboard')}>
           Submit
         </Button>
-        <NextButtonLink href="/docs" variant="outline">
+        <ButtonLink href="/docs" variant="outline">
           Documentation
-        </NextButtonLink>
+        </ButtonLink>
       </Card>
     </Sidebar>
   );
 }
 ```
 
-### NextButtonLink Examples
+### `<ButtonLink>` examples
+
+`<ButtonLink>` lives in `@djangocfg/ui-core/components`. In Next.js apps it renders
+through `next/link` automatically (via `NextLinkProvider` mounted in `BaseApp`).
+In Wails / Electron / Vite consumers it falls back to a plain `<a>` driven by
+`useNavigate`.
 
 ```tsx
-import { NextButtonLink } from '@djangocfg/ui-nextjs';
+import { ButtonLink } from '@djangocfg/ui-core/components';
 import { ArrowLeft, Settings } from 'lucide-react';
 
-// Basic — automatically gets locale prefix
-<NextButtonLink href="/dashboard">Dashboard</NextButtonLink>
+<ButtonLink href="/dashboard">Dashboard</ButtonLink>
 
-// With variants
-<NextButtonLink href="/settings" variant="outline" size="sm">
+<ButtonLink href="/settings" variant="outline" size="sm">
   <Settings className="h-4 w-4 mr-2" />
   Settings
-</NextButtonLink>
+</ButtonLink>
 
-// Icon button (back navigation)
-<NextButtonLink href="/list" variant="ghost" size="icon">
+<ButtonLink href="/list" variant="ghost" size="icon">
   <ArrowLeft className="h-4 w-4" />
-</NextButtonLink>
-
-// With Next.js Link props
-<NextButtonLink href="/page" prefetch={false} replace scroll={false}>
-  Navigate
-</NextButtonLink>
+</ButtonLink>
 
-// With locale override
-<NextButtonLink href="/docs" locale="en">
-  English Docs
-</NextButtonLink>
+<ButtonLink href="/page" prefetch={false} replace>
+  Navigate (replaceState)
+</ButtonLink>
 ```
 
 ## Styling

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@djangocfg/ui-nextjs",
-  "version": "2.1.294",
+  "version": "2.1.297",
   "description": "Next.js UI component library with Radix UI primitives, Tailwind CSS styling, charts, and form components",
   "keywords": [
     "ui-components",
@@ -85,11 +85,11 @@
     "check": "tsc --noEmit"
   },
   "peerDependencies": {
-    "@djangocfg/api": "^2.1.294",
-    "@djangocfg/i18n": "^2.1.294",
-    "@djangocfg/nextjs": "^2.1.294",
-    "@djangocfg/ui-core": "^2.1.294",
-    "@djangocfg/ui-tools": "^2.1.294",
+    "@djangocfg/api": "^2.1.297",
+    "@djangocfg/i18n": "^2.1.297",
+    "@djangocfg/nextjs": "^2.1.297",
+    "@djangocfg/ui-core": "^2.1.297",
+    "@djangocfg/ui-tools": "^2.1.297",
     "@types/react": "^19.1.0",
     "@types/react-dom": "^19.1.0",
     "consola": "^3.4.2",
@@ -112,7 +112,7 @@
     "react-chartjs-2": "^5.3.0"
   },
   "devDependencies": {
-    "@djangocfg/typescript-config": "^2.1.294",
+    "@djangocfg/typescript-config": "^2.1.297",
     "@radix-ui/react-dropdown-menu": "^2.1.16",
     "@radix-ui/react-slot": "^1.2.4",
     "@types/node": "^24.7.2",

package/src/blocks/ArticleCard.tsx

@@ -2,10 +2,9 @@ import React from 'react';
 import moment from 'moment';
 
 import {
-    Badge, Card, CardContent, CardDescription, CardHeader, CardTitle
+    Badge, ButtonLink, Card, CardContent, CardDescription, CardHeader, CardTitle
 } from '@djangocfg/ui-core/components';
 
-import { NextButtonLink as ButtonLink } from '../components/next-link';
 import { cn } from '@djangocfg/ui-core/lib';
 
 export type ArticleType = 'security' | 'release' | 'announcement' | 'feature';

package/src/blocks/Hero.tsx

@@ -1,9 +1,8 @@
 import React from 'react';
 
+import { ButtonLink } from '@djangocfg/ui-core/components';
 import { cn } from '@djangocfg/ui-core/lib';
 
-import { NextButtonLink as ButtonLink } from '../components/next-link';
-
 interface HeroProps {
   title: string;
   subtitle?: string;

package/src/blocks/SplitHero/SplitHeroContent.tsx

@@ -2,9 +2,8 @@
 
 import React from 'react';
 import { ArrowRight, Sparkles } from 'lucide-react';
+import { ButtonLink } from '@djangocfg/ui-core/components';
 import { cn } from '@djangocfg/ui-core/lib';
-
-import { NextButtonLink as ButtonLink } from '../../components/next-link';
 import type { SplitHeroBadge, SplitHeroAction, SplitHeroFeature } from './types';
 
 interface SplitHeroContentProps {

package/src/blocks/SuperHero.tsx

@@ -5,10 +5,9 @@ import { ArrowRight, Sparkles, Wand2 } from 'lucide-react';
 import React from 'react';
 
 import {
-    Button, CopyButton, Sticky, Tooltip, TooltipContent, TooltipTrigger
+    Button, ButtonLink, CopyButton, Sticky, Tooltip, TooltipContent, TooltipTrigger
 } from '@djangocfg/ui-core/components';
 
-import { NextButtonLink as ButtonLink } from '../components/next-link';
 import { cn } from '@djangocfg/ui-core/lib';
 
 import { AnimatedBackground, BackgroundVariant} from '../animations';

package/src/components/breadcrumb-navigation.tsx

@@ -1,4 +1,4 @@
-import { Link } from '../lib/navigation';
+import { Link } from '@djangocfg/ui-core/components';
 import React from 'react';
 
 import {

package/src/components/breadcrumb.tsx

@@ -1,9 +1,9 @@
 "use client"
 
 import { ChevronRight, MoreHorizontal } from 'lucide-react';
-import { Link } from '../lib/navigation';
 import * as React from 'react';
 
+import { Link } from '@djangocfg/ui-core/components';
 import { cn } from '@djangocfg/ui-core/lib';
 import { Slot } from '@radix-ui/react-slot';
 

package/src/components/dropdown-menu.tsx

@@ -1,9 +1,9 @@
 "use client"
 
 import { Check, ChevronRight, Circle } from 'lucide-react';
-import { Link } from '../lib/navigation';
 import * as React from 'react';
 
+import { Link } from '@djangocfg/ui-core/components';
 import { cn } from '@djangocfg/ui-core/lib';
 import * as DropdownMenuPrimitive from '@radix-ui/react-dropdown-menu';
 

package/src/components/index.ts

@@ -6,15 +6,9 @@
 'use client';
 
 // Re-export all base components from ui-core
+// (includes Link / ButtonLink — wired to next/link via NextLinkProvider in BaseApp)
 export * from '@djangocfg/ui-core/components';
 
-// Locale-aware Link (re-export from next-intl navigation)
-export { Link } from '../lib/navigation';
-
-// Link Components (Next.js)
-export { NextLink, NextButtonLink } from './next-link';
-export type { NextLinkProps, NextButtonLinkProps } from './next-link';
-
 // Navigation Components (Next.js)
 export { Breadcrumb, BreadcrumbItem, BreadcrumbLink, BreadcrumbList, BreadcrumbPage, BreadcrumbSeparator, BreadcrumbEllipsis } from './breadcrumb';
 export { BreadcrumbNavigation } from './breadcrumb-navigation';

package/src/components/pagination.tsx

@@ -1,8 +1,7 @@
 import { ChevronLeft, ChevronRight, MoreHorizontal } from 'lucide-react';
-import { Link } from '../lib/navigation';
 import * as React from 'react';
 
-import { ButtonProps, buttonVariants} from '@djangocfg/ui-core/components';
+import { ButtonProps, Link, buttonVariants } from '@djangocfg/ui-core/components';
 import { cn } from '@djangocfg/ui-core/lib';
 
 const Pagination = ({ className, ...props }: React.ComponentProps<"nav">) => (

package/src/components/sidebar.tsx

@@ -2,9 +2,10 @@
 
 import { cva, VariantProps } from 'class-variance-authority';
 import { Menu, PanelLeft } from 'lucide-react';
-import { Link } from '../lib/navigation';
 import * as React from 'react';
 
+import { Link } from '@djangocfg/ui-core/components';
+
 import {
   Button,
   Drawer,

package/src/components/ssr-pagination.tsx

@@ -1,6 +1,6 @@
 'use client';
 
-import { usePathname } from '../lib/navigation';
+import { usePathname } from 'next/navigation';
 import React from 'react';
 
 import { useIsMobile } from '@djangocfg/ui-core/hooks';

package/src/hooks/index.ts

@@ -6,7 +6,7 @@
 'use client';
 
 // Locale-aware navigation hooks (next-intl)
-export { useRouter, usePathname } from '../lib/navigation';
+export { useRouter, usePathname } from 'next/navigation';
 export { useNavigation } from './useNavigation';
 
 // Theme hook (standalone, no provider required)

package/src/hooks/useNavigation.ts

@@ -1,6 +1,6 @@
 'use client';
 
-import { useRouter, usePathname, redirect } from '../lib/navigation';
+import { useRouter, usePathname, redirect } from 'next/navigation';
 
 /**
  * Locale-aware navigation hook.

package/src/components/next-link.tsx

@@ -1,91 +0,0 @@
-'use client';
-
-import * as React from 'react';
-import type { LinkProps as NextLinkBaseProps } from 'next/link';
-import { Link } from '../lib/navigation';
-import { buttonVariants } from '@djangocfg/ui-core/components';
-import type { VariantProps } from 'class-variance-authority';
-import { cn } from '@djangocfg/ui-core/lib';
-
-type BaseLinkProps = React.ComponentProps<typeof Link>;
-
-// ============================================================================
-// NextLink - Styled Next.js Link (text link style)
-// ============================================================================
-
-export interface NextLinkProps
-  extends Omit<React.AnchorHTMLAttributes<HTMLAnchorElement>, keyof NextLinkBaseProps>,
-    NextLinkBaseProps {
-  locale?: string;
-  children?: React.ReactNode;
-}
-
-/**
- * NextLink - Next.js Link with no additional styling
- *
- * Use this for regular navigation links. For button-styled links, use NextButtonLink.
- *
- * @example
- * <NextLink href="/about">About</NextLink>
- * <NextLink href="/docs" className="text-primary hover:underline">Docs</NextLink>
- */
-const NextLink = React.forwardRef<HTMLAnchorElement, NextLinkProps>(
-  ({ children, locale: _locale, ...props }, ref) => {
-    return (
-      <Link ref={ref} {...props as BaseLinkProps}>
-        {children}
-      </Link>
-    );
-  }
-);
-NextLink.displayName = 'NextLink';
-
-// ============================================================================
-// NextButtonLink - Button styled Next.js Link
-// ============================================================================
-
-export interface NextButtonLinkProps
-  extends Omit<React.AnchorHTMLAttributes<HTMLAnchorElement>, keyof NextLinkBaseProps>,
-    NextLinkBaseProps,
-    VariantProps<typeof buttonVariants> {
-  locale?: string;
-  children?: React.ReactNode;
-}
-
-/**
- * NextButtonLink - A button styled link using Next.js Link component
- *
- * Supports all Next.js Link props (prefetch, replace, scroll, etc.)
- * and all Button variant props (variant, size).
- *
- * @example
- * // Basic usage
- * <NextButtonLink href="/dashboard">Dashboard</NextButtonLink>
- *
- * // With variants
- * <NextButtonLink href="/settings" variant="outline" size="sm">Settings</NextButtonLink>
- *
- * // Icon button
- * <NextButtonLink href="/back" variant="ghost" size="icon">
- *   <ArrowLeft className="h-4 w-4" />
- * </NextButtonLink>
- *
- * // With Next.js Link props
- * <NextButtonLink href="/page" prefetch={false} replace>Go</NextButtonLink>
- */
-const NextButtonLink = React.forwardRef<HTMLAnchorElement, NextButtonLinkProps>(
-  ({ className, variant, size, children, locale: _locale, ...props }, ref) => {
-    return (
-      <Link
-        className={cn(buttonVariants({ variant, size, className }))}
-        ref={ref}
-        {...props as BaseLinkProps}
-      >
-        {children}
-      </Link>
-    );
-  }
-);
-NextButtonLink.displayName = 'NextButtonLink';
-
-export { NextLink, NextButtonLink };

package/src/lib/navigation.ts

@@ -1,12 +0,0 @@
-/**
- * Internal navigation utilities for ui-nextjs
- *
- * Uses standard next/link and next/navigation to avoid requiring
- * NextIntlClientProvider in the component tree. This makes ui-nextjs
- * work both with and without next-intl i18n setup.
- *
- * Apps that need locale-aware links should use their own navigation
- * module (e.g. @i18n/navigation) created via next-intl's createNavigation().
- */
-export { default as Link } from 'next/link';
-export { usePathname, useRouter, redirect } from 'next/navigation';

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

@@ -1,92 +0,0 @@
-# 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/pwa/@docs/research/ios-android-install-flows.md

@@ -1,576 +0,0 @@
-
-
-
-## PWA Install Flows: Modern Best Practices for React (2024-2025)
-
-Given your experience with Django and Next.js infrastructure, you'll appreciate that PWA install flows are fundamentally about **adaptive UX patterns**, not magic APIs. Let me break down the reality vs. the aspirations.
-
-***
-
-### **The Core Problem: iOS vs. Android Asymmetry**
-
-| Aspect | Android (Chrome) | iOS (Safari) |
-|--------|------------------|--------------|
-| **Install API** | `beforeinstallprompt` event + native prompt | ❌ No API, no native banner |
-| **User effort** | 1 tap (native prompt) | 3-4 taps (Share → Add to Home Screen) |
-| **App awareness** | Chrome auto-prompts if installable | **You must educate users manually** |
-| **Detection** | Straightforward event-based | Must use heuristics (Safari + mobile) |
-| **Persistence** | Browser remembers install state | No native tracking |
-| **After install** | `appinstalled` event fires | Must detect via `standalone` flag |
-
-**The brutal truth:** iOS Safari treats PWAs as "websites you happened to bookmark"—there's no concept of "installation" from Apple's perspective. You're responsible for education and guidance.
-
-***
-
-### **What's Actually Possible vs. Impossible on iOS**
-
-#### ✅ **Possible (2024-2025)**
-
-1. **Detect if running as standalone (already installed)**
-   ```javascript
-   const isInstalled = window.matchMedia("(display-mode: standalone)").matches 
-     || navigator.standalone === true;
-   ```
-
-2. **Detect iOS + Safari combination**
-   - User agent parsing (for initial load)
-   - Browser capability detection
-
-3. **Show custom guidance UI with visual/text instructions**
-   - No technical restrictions on UI—you can display modal, banner, tooltip, etc.
-
-4. **Persist user guidance state (show once)**
-   - localStorage, IndexedDB, or cookies
-
-5. **Use web standards:**
-   - Web App Manifest (icon, splash screen, display mode)
-   - Service Workers (offline, performance)
-   - Media queries for standalone detection
-
-#### ❌ **Impossible (Hard Limits)**
-
-1. **Programmatically trigger install prompt** ← iOS blocks this intentionally
-2. **Native install banner** ← Apple doesn't expose one
-3. **beforeinstallprompt event** ← iOS doesn't fire it
-4. **Push notifications on PWA** ← Disabled by Apple for PWAs (only for native apps)
-5. **Detect `appinstalled` event** ← iOS doesn't fire this
-6. **Background sync / periodic background sync** ← Not available for PWAs on iOS
-7. **File system access** ← Blocked by iOS sandbox
-8. **Native app store integration** ← You're not in the App Store
-
-***
-
-### **Browser & Environment Detection (React Hook)**
-
-Here's a production-ready detection hook that handles all the cases:
-
-```javascript
-// useInstallPrompt.js
-import { useEffect, useState } from 'react';
-
-export function useInstallPrompt() {
-  const [state, setState] = useState({
-    isIOS: false,
-    isAndroid: false,
-    isSafari: false,
-    isChrome: false,
-    isInstalled: false, // Already added to home screen
-    canPrompt: false, // beforeinstallprompt available (Android)
-    deferredPrompt: null,
-  });
-
-  useEffect(() => {
-    // Detect OS
-    const ua = navigator.userAgent.toLowerCase();
-    const isIOS = /iphone|ipad|ipod/.test(ua);
-    const isAndroid = /android/.test(ua);
-
-    // Detect browser
-    const isSafari = /safari/.test(ua) && !/chrome/.test(ua) && !/edge/.test(ua);
-    const isChrome = /chrome|chromium/.test(ua);
-
-    // Detect if already installed (running as PWA on home screen)
-    const isInstalled = 
-      window.matchMedia("(display-mode: standalone)").matches ||
-      navigator.standalone === true; // Legacy iOS check
-
-    setState(prev => ({
-      ...prev,
-      isIOS,
-      isAndroid,
-      isSafari,
-      isChrome,
-      isInstalled,
-    }));
-  }, []);
-
-  // Listen for beforeinstallprompt (Android Chrome only)
-  useEffect(() => {
-    const handleBeforeInstallPrompt = (e) => {
-      e.preventDefault(); // Don't show native prompt yet
-      setState(prev => ({
-        ...prev,
-        canPrompt: true,
-        deferredPrompt: e,
-      }));
-    };
-
-    window.addEventListener('beforeinstallprompt', handleBeforeInstallPrompt);
-
-    // Clean up: if app gets installed, can't prompt again
-    const handleAppInstalled = () => {
-      setState(prev => ({
-        ...prev,
-        canPrompt: false,
-        deferredPrompt: null,
-        isInstalled: true,
-      }));
-    };
-
-    window.addEventListener('appinstalled', handleAppInstalled);
-
-    return () => {
-      window.removeEventListener('beforeinstallprompt', handleBeforeInstallPrompt);
-      window.removeEventListener('appinstalled', handleAppInstalled);
-    };
-  }, []);
-
-  // Trigger Android native prompt
-  const promptInstall = async () => {
-    if (!state.deferredPrompt) return null;
-
-    state.deferredPrompt.prompt();
-    const { outcome } = await state.deferredPrompt.userChoice;
-    setState(prev => ({
-      ...prev,
-      deferredPrompt: null,
-      canPrompt: false,
-    }));
-    return outcome; // 'accepted' or 'dismissed'
-  };
-
-  return {
-    ...state,
-    promptInstall,
-  };
-}
-```
-
-***
-
-### **Real-World UX Patterns That Actually Work**
-
-#### **Pattern 1: The Adaptive Install Banner (Recommended)**
-
-**For first-time visitors:**
-
-1. **Android Chrome**: Show custom "Install" button in navbar/footer
-   - Click → triggers native prompt via `beforeinstallprompt`
-   - Non-intrusive, native look
-
-2. **iOS Safari**: Show subtle banner/tooltip on first visit
-   - Text: "Add to Home Screen for quick access"
-   - Visual: Share icon + "Add to Home Screen" steps
-   - Dismiss-able, one-time only
-
-3. **Already installed**: Hide all prompts
-
-**Implementation strategy:**
-- Show Android button immediately (it's native, trusted)
-- Delay iOS banner 2-3 seconds (let them explore first)
-- Use localStorage to track "dismissed once" per user
-- Reset for new visitors (check last visit date)
-
-***
-
-#### **Pattern 2: Context-Aware Prompts (Based on Engagement)**
-
-**Show iOS guidance when:**
-- User has spent 30+ seconds on the app
-- Completed first action (e.g., created note, searched)
-- Returning visitor (showed visit count in localStorage)
-
-**Logic:**
-```javascript
-// Pseudocode
-useEffect(() => {
-  if (isIOS && !isInstalled && !isDismissedRecently) {
-    const timer = setTimeout(() => {
-      if (engagementMetrics.timeSpent > 30000 || engagementMetrics.actions > 1) {
-        showIOSGuideModal();
-      }
-    }, 2000); // Check after 2 seconds
-
-    return () => clearTimeout(timer);
-  }
-}, [isIOS, isInstalled]);
-```
-
-**Why it works:**
-- Users are already bought-in (they've engaged)
-- Feels less spammy
-- Higher conversion rates
-
-***
-
-#### **Pattern 3: Visual Inline Instructions (The iOS Workaround)**
-
-Since iOS has no API, show a **visual + text guide**:
-
-```jsx
-<IOSInstallGuide />
-```
-
-Show:
-1. Screenshot of Safari toolbar
-2. "Tap Share button (↗️)"
-3. "Swipe down, tap 'Add to Home Screen'"
-4. "Tap 'Add' in top-right"
-5. "App appears on home screen"
-
-**Best practices:**
-- Use actual iOS system fonts and colors
-- Show real screenshots, not cartoons
-- Make dismissible with "I'll do it later" option
-- Track if dismissed (localStorage key)
-
-***
-
-### **Example React Component: Complete Install Manager**
-
-```javascript
-// InstallManager.jsx
-import { useEffect, useState } from 'react';
-import { useInstallPrompt } from './useInstallPrompt';
-import IOSGuideModal from './modals/IOSGuideModal';
-import AndroidInstallButton from './buttons/AndroidInstallButton';
-
-export default function InstallManager() {
-  const install = useInstallPrompt();
-  const [showIOSGuide, setShowIOSGuide] = useState(false);
-  const [dismissalTime, setDismissalTime] = useState(null);
-
-  // Initialize state from localStorage
-  useEffect(() => {
-    const stored = localStorage.getItem('ios_guide_dismissed_at');
-    if (stored) setDismissalTime(parseInt(stored, 10));
-  }, []);
-
-  // Determine if should show iOS guide
-  useEffect(() => {
-    if (!install.isIOS || install.isInstalled || install.isSafari === false) {
-      setShowIOSGuide(false);
-      return;
-    }
-
-    // Check if dismissed recently (within 7 days)
-    const now = Date.now();
-    const WEEK = 7 * 24 * 60 * 60 * 1000;
-    if (dismissalTime && now - dismissalTime < WEEK) {
-      setShowIOSGuide(false);
-      return;
-    }
-
-    // Show after 2 seconds if not dismissed
-    const timer = setTimeout(() => setShowIOSGuide(true), 2000);
-    return () => clearTimeout(timer);
-  }, [install.isIOS, install.isInstalled, install.isSafari, dismissalTime]);
-
-  const handleIOSDismiss = () => {
-    setShowIOSGuide(false);
-    localStorage.setItem('ios_guide_dismissed_at', Date.now().toString());
-    setDismissalTime(Date.now());
-  };
-
-  // Don't render anything if already installed
-  if (install.isInstalled) return null;
-
-  return (
-    <>
-      {/* Android: Show button in navbar/header */}
-      {install.isAndroid && install.canPrompt && (
-        <AndroidInstallButton onInstall={install.promptInstall} />
-      )}
-
-      {/* iOS: Show modal with visual guide */}
-      {showIOSGuide && (
-        <IOSGuideModal onDismiss={handleIOSDismiss} />
-      )}
-    </>
-  );
-}
-```
-
-```javascript
-// AndroidInstallButton.jsx
-export default function AndroidInstallButton({ onInstall }) {
-  const [loading, setLoading] = useState(false);
-
-  const handleClick = async () => {
-    setLoading(true);
-    const outcome = await onInstall();
-    setLoading(false);
-    // outcome will be 'accepted' or 'dismissed'
-  };
-
-  return (
-    <button
-      onClick={handleClick}
-      disabled={loading}
-      className="install-btn"
-    >
-      {loading ? 'Installing...' : '⬇️ Install App'}
-    </button>
-  );
-}
-```
-
-```javascript
-// IOSGuideModal.jsx
-export default function IOSGuideModal({ onDismiss }) {
-  return (
-    <div className="modal-overlay">
-      <div className="modal-content">
-        <h2>Quick Access on Your Home Screen</h2>
-        
-        <div className="guide-steps">
-          <Step number={1} title="Tap Share" icon="↗️">
-            <p>At the bottom of Safari</p>
-          </Step>
-          
-          <Step number={2} title="Scroll & Tap" icon="👇">
-            <p>"Add to Home Screen"</p>
-          </Step>
-          
-          <Step number={3} title="Confirm" icon="✓">
-            <p>Tap "Add" in the top-right</p>
-          </Step>
-        </div>
-
-        <button onClick={onDismiss} className="btn-secondary">
-          I'll Do It Later
-        </button>
-        <button onClick={onDismiss} className="btn-primary">
-          Got It!
-        </button>
-      </div>
-    </div>
-  );
-}
-```
-
-***
-
-### **State Persistence Strategy**
-
-**Key considerations:**
-
-1. **localStorage best choice for PWAs:**
-   ```javascript
-   // Don't re-show guide if dismissed in last 7 days
-   const isDismissedRecently = () => {
-     const dismissed = localStorage.getItem('ios_guide_last_dismissed');
-     if (!dismissed) return false;
-     const days = (Date.now() - parseInt(dismissed)) / (1000 * 60 * 60 * 24);
-     return days < 7;
-   };
-   ```
-
-2. **Track engagement** (optional, for smart prompts):
-   ```javascript
-   // Log engagement metrics
-   const logEngagement = (action) => {
-     const current = JSON.parse(localStorage.getItem('engagement') || '{"actions":0,"time":0}');
-     current.actions += 1;
-     localStorage.setItem('engagement', JSON.stringify(current));
-   };
-   ```
-
-3. **Clear state on install** (Android):
-   ```javascript
-   // On appinstalled event, clear prompts
-   window.addEventListener('appinstalled', () => {
-     localStorage.setItem('app_installed', 'true');
-     localStorage.removeItem('ios_guide_dismissed_at');
-   });
-   ```
-
-***
-
-### **Real-World Examples: How Major PWAs Handle This**
-
-#### **Twitter/X PWA**
-- **Android**: Native install button in sidebar (when eligible)
-- **iOS**: No visible prompt (assumes power users know how to add to home screen)
-- **Strategy**: Relies on word-of-mouth, not aggressive prompting
-
-#### **GitHub PWA**
-- Minimal install flow
-- **Android**: Shows prompt when visiting multiple times
-- **iOS**: Silent (no prompts)
-- **Philosophy**: Let power users discover, don't interrupt
-
-#### **Linear PWA**
-- **Android**: Clean install button in top-nav
-- **iOS**: No modal—relies on quality app experience to drive manual adds
-- **Pattern**: "If your app is good, users will find the add button"
-
-#### **Successful PWAs (based on community feedback)**
-- **Don't show iOS guides on first visit** (feels pushy)
-- **Do show after engagement** (user is bought-in)
-- **Do provide dismissal option** (avoid dark patterns)
-- **Do use localStorage to respect prior dismissals**
-- **Don't show if already installed** (detection is critical)
-
-***
-
-### **What "Actually Works" on iOS (Data-Driven Patterns)**
-
-Based on successful PWA deployments:
-
-1. **Engagement-triggered guidance beats first-visit prompts**
-   - First visit → explore, don't interrupt
-   - Third+ visit or 2+ actions → show guide
-   - **Conversion rate: 8-15% vs. 2-3% on first-visit prompts**
-
-2. **Visual steps outperform text instructions**
-   - Showing actual iOS UI is clearer than describing it
-   - Consider GIFs/animated sequences
-   - **Completion rate: 70% with visuals vs. 40% with text**
-
-3. **One-step dismissal matters**
-   - Single "Got it" button works better than "Remind me later"
-   - Users respect apps that respect their choice
-   - **Reduces annoyance by ~40%**
-
-4. **Returning visitors convert better**
-   - Reset the "dismissed" flag weekly, not permanently
-   - Show guide again to users after 7 days
-   - **Why: They may have forgotten how, or different device**
-
-5. **Context-aware timing wins**
-   - Show during natural pause in interaction
-   - Not during form entry or upload
-   - Not immediately on page load
-   - **Soft rule: Show after 2-3 seconds of inactivity**
-
-***
-
-### **Minimal, Clean UX Checklist**
-
-**✅ Do:**
-- [ ] Detect installation state correctly (standalone + navigator.standalone)
-- [ ] Hide prompts if already installed
-- [ ] Make guides dismissible with one tap
-- [ ] Show Android button only when `beforeinstallprompt` available
-- [ ] Use localStorage to avoid re-showing dismissed guides
-- [ ] Use visual/emoji-based steps (more accessible)
-- [ ] Test on real devices (iOS 15+, Android Chrome)
-- [ ] Respect user choice (don't show again for 7 days)
-- [ ] Show only on Safari (not in WebView or other browsers)
-
-**❌ Don't:**
-- [ ] Show guide on every page view (respect dismissals)
-- [ ] Use deceptive wording ("Add App" implies App Store)
-- [ ] Show fullscreen overlays (modals are fine, but not blocking)
-- [ ] Re-show immediately after dismiss
-- [ ] Prompt on first load (let them explore first)
-- [ ] Show if no web app manifest (install would fail)
-- [ ] Use dark patterns (hide dismiss button, auto-show after X seconds)
-- [ ] Assume users know what PWA means (use "app" language)
-
-***
-
-### **Key Detection Code Snippet**
-
-```javascript
-// Browser & Platform Detection (Production-Ready)
-export function getPlatformInfo() {
-  const ua = navigator.userAgent.toLowerCase();
-  
-  const platform = {
-    // Operating System
-    isiOS: /iphone|ipad|ipod/.test(ua),
-    isAndroid: /android/.test(ua),
-    isDesktop: !/mobile|android|iphone|ipad/.test(ua),
-    
-    // Browser
-    isSafari: /safari/.test(ua) && !/chrome|edge|firefox/.test(ua),
-    isChrome: /chrome|chromium/.test(ua) && !/edge/.test(ua),
-    isEdge: /edge|edg/.test(ua),
-    isFirefox: /firefox/.test(ua),
-    
-    // Installation State
-    isStandalone: window.matchMedia("(display-mode: standalone)").matches 
-      || navigator.standalone === true,
-    
-    // Capability
-    canPrompt: 'onbeforeinstallprompt' in window, // Will be true on Android Chrome
-  };
-  
-  // Composite checks
-  platform.shouldShowAndroidPrompt = platform.isAndroid && !platform.isStandalone;
-  platform.shouldShowIOSGuide = platform.isiOS && platform.isSafari && !platform.isStandalone;
-  
-  return platform;
-}
-```
-
-***
-
-### **Final Recommendation: Production Flow**
-
-**For your React PWA, this is the minimal viable approach:**
-
-```javascript
-// App.jsx
-import { useEffect, useState } from 'react';
-import { useInstallPrompt } from './hooks/useInstallPrompt';
-
-function App() {
-  const install = useInstallPrompt();
-  const [showIOSGuide, setShowIOSGuide] = useState(false);
-
-  // Track first interaction
-  useEffect(() => {
-    const handleFirstInteraction = () => {
-      // Optionally show iOS guide after user does something
-      if (install.isIOS && !install.isInstalled && !hasUserDismissedBefore()) {
-        setShowIOSGuide(true);
-      }
-      document.removeEventListener('click', handleFirstInteraction);
-    };
-
-    document.addEventListener('click', handleFirstInteraction);
-    return () => document.removeEventListener('click', handleFirstInteraction);
-  }, [install.isIOS, install.isInstalled]);
-
-  // Don't show anything if already installed
-  if (install.isInstalled) return <YourApp />;
-
-  return (
-    <>
-      <YourApp />
-      
-      {/* Android: Simple nav button (appears when eligible) */}
-      {install.canPrompt && (
-        <NavButton onClick={install.promptInstall}>
-          ⬇️ Install
-        </NavButton>
-      )}
-
-      {/* iOS: One-time guide modal */}
-      {showIOSGuide && (
-        <SimpleIOSGuideModal
-          onClose={() => {
-            setShowIOSGuide(false);
-            markIOSGuideDismissed();
-          }}
-        />
-      )}
-    </>
-  );
-}
-```
-
-**That's it.** You don't need complex analytics, dark patterns, or aggressive nudging. The best PWAs win through quality, not manipulation.