@donotdev/cli 0.0.5 → 0.0.7

package/templates/root-consumer/guides/dndev/SETUP_PWA.md.example

@@ -0,0 +1,213 @@
+# PWA Setup
+
+**For AI Agents:** Enable PWA in config, add required app metadata. Framework handles service worker, manifest, and caching.
+
+---
+
+## Quick Start
+
+### 1. Add Required App Metadata
+
+PWA requires `name`, `shortName`, and `description` in your app config:
+
+```typescript
+// src/config/app.ts
+import type { AppConfig } from '@donotdev/core';
+
+export const appConfig: AppConfig = {
+  app: {
+    name: 'My App',              // Full app name (required for PWA)
+    shortName: 'App',            // Short name for home screen (required for PWA)
+    description: 'My app description', // App description (required for PWA)
+    url: 'https://myapp.com',
+  },
+  // ... rest of config
+};
+```
+
+### 2. Enable PWA in Build Config
+
+**For Vite apps:**
+
+```typescript
+// vite.config.ts
+import { defineViteConfig } from '@donotdev/core/vite';
+import { appConfig } from './src/config/app';
+
+export default defineViteConfig({
+  appConfig,
+  pwa: {
+    enabled: true,        // Enable PWA in production builds
+    devEnabled: false,   // Enable PWA in development (optional)
+  },
+});
+```
+
+**For Next.js apps:**
+
+```typescript
+// next.config.ts
+import { defineNextConfig } from '@donotdev/core/next';
+import { appConfig } from './src/config/app';
+
+export default defineNextConfig({
+  appConfig,
+  pwa: {
+    enabled: true,        // Enable PWA in production builds
+    devEnabled: false,   // Enable PWA in development (optional)
+  },
+});
+```
+
+**Done.** Framework automatically:
+- Generates `manifest.json` from app metadata
+- Creates service worker with Workbox
+- Discovers and precaches app icons
+- Sets up offline caching strategies
+
+---
+
+## What Gets Auto-Generated
+
+### Manifest (`manifest.json`)
+- **Name & description:** From `appConfig.app.name`, `shortName`, `description`
+- **Icons:** Auto-discovered from `public/` folder (favicon, apple-touch-icon, etc.)
+- **Theme colors:** Defaults to white background, black theme (customizable)
+- **Display mode:** `standalone` (app-like experience)
+
+### Service Worker (`sw.js`)
+- **Precaching:** All JS, CSS, HTML, icons, and fonts
+- **Runtime caching:** Smart defaults for API calls and images
+- **Offline support:** Navigation fallback to `/`
+- **Update strategy:** Prompts user to update when new version available
+
+### Icons
+Framework discovers icons from:
+- `public/favicon.svg` or `public/favicon.ico`
+- `public/apple-touch-icon.png`
+- Any icons generated by AssetPlugin
+
+---
+
+## Optional Configuration
+
+### Custom Manifest Values
+
+```typescript
+// vite.config.ts or next.config.ts
+export default defineViteConfig({
+  appConfig,
+  pwa: {
+    enabled: true,
+    manifest: {
+      // Override any manifest values
+      theme_color: '#667eea',
+      background_color: '#ffffff',
+      display: 'standalone',
+      orientation: 'portrait',
+    },
+  },
+});
+```
+
+### Custom Workbox Configuration
+
+```typescript
+pwa: {
+  enabled: true,
+  workbox: {
+    // Maximum file size to cache (default: 5MB)
+    maximumFileSizeToCacheInBytes: 5 * 1024 * 1024,
+    
+    // Custom precache patterns
+    globPatterns: ['**/*.{js,css,html,ico,png,svg,woff2}'],
+    globIgnores: ['**/node_modules/**'],
+    
+    // Runtime caching strategies
+    runtimeCaching: [
+      {
+        urlPattern: /^https:\/\/api\.example\.com\/.*/i,
+        handler: 'NetworkFirst',
+        options: {
+          cacheName: 'api-cache',
+          expiration: {
+            maxEntries: 50,
+            maxAgeSeconds: 60 * 60, // 1 hour
+          },
+        },
+      },
+    ],
+  },
+},
+```
+
+### Development Mode
+
+Enable PWA in development for testing:
+
+```typescript
+pwa: {
+  enabled: true,
+  devEnabled: true,  // Enable service worker in dev mode
+  debug: true,       // Enable debug logging
+},
+```
+
+**Note:** Service workers require HTTPS (or localhost). Use `server: { https: true }` in Vite config for local HTTPS.
+
+---
+
+## Testing PWA
+
+1. **Build for production:**
+   ```bash
+   bun run build
+   ```
+
+2. **Serve production build:**
+   ```bash
+   bun run preview  # Vite
+   # or
+   bun run start    # Next.js
+   ```
+
+3. **Test in browser:**
+   - Open DevTools → Application → Service Workers
+   - Check "Offline" checkbox to test offline mode
+   - Verify manifest in Application → Manifest
+   - Test "Add to Home Screen" prompt
+
+---
+
+## Requirements Checklist
+
+- [ ] `appConfig.app.name` defined
+- [ ] `appConfig.app.shortName` defined
+- [ ] `appConfig.app.description` defined
+- [ ] `pwa.enabled: true` in build config
+- [ ] Icons in `public/` folder (auto-discovered)
+- [ ] HTTPS in production (required for service workers)
+
+---
+
+## Troubleshooting
+
+**PWA not working:**
+- Check browser console for service worker errors
+- Verify HTTPS (required except localhost)
+- Check manifest.json exists in build output
+- Verify app metadata is complete
+
+**Icons not showing:**
+- Ensure icons exist in `public/` folder
+- Check icon formats (SVG, PNG, ICO supported)
+- Verify AssetPlugin discovered icons (check build logs)
+
+**Service worker not registering:**
+- Check browser console for registration errors
+- Verify HTTPS (service workers require secure context)
+- Clear browser cache and hard refresh
+
+---
+
+**Zero config. Override when needed.**

package/templates/root-consumer/guides/dndev/USE_ROUTING.md.example

@@ -0,0 +1,503 @@
+# Routing Guide
+
+**For AI Agents:** Use framework routing components/hooks. NEVER import from `react-router-dom` directly. Framework handles SPA navigation, Outlet, and overlay closing automatically.
+
+---
+
+## 🚨 Critical Rule: Never Use react-router-dom Directly
+
+**❌ WRONG:**
+```tsx
+import { Link, useNavigate, useParams } from 'react-router-dom'; // ❌ BREAKS FRAMEWORK
+```
+
+**✅ CORRECT:**
+```tsx
+import { Link, useNavigate, useParams } from '@donotdev/ui/routing'; // ✅ Framework routing
+```
+
+**Why?** The framework's routing components:
+- Automatically close overlays on navigation
+- Handle SPA navigation correctly with Outlet
+- Work with both Vite and Next.js
+- Integrate with auth and route discovery
+- Provide proper TypeScript types
+
+---
+
+## Framework Routing API
+
+### Components
+
+```tsx
+import { Link, DnDevNavigationMenu } from '@donotdev/ui/routing';
+```
+
+**Link Component:**
+```tsx
+<Link path="/products" label="Products" icon="Package" />
+<Link path="/users/:id" replace prefetch={false}>User Details</Link>
+```
+
+**DnDevNavigationMenu (Sidebar/Header):**
+```tsx
+// Auto-fetches routes, handles auth filtering
+<DnDevNavigationMenu vertical display={DISPLAY.AUTO} />
+```
+
+### Hooks
+
+```tsx
+import {
+  useNavigate,
+  useLocation,
+  useParams,
+  useRouteParam,
+  useSearchParams,
+  useNavigationItems,
+} from '@donotdev/ui/routing';
+```
+
+---
+
+## Navigation Patterns
+
+### 1. Basic Navigation
+
+**✅ Use framework Link:**
+```tsx
+import { Link } from '@donotdev/ui/routing';
+
+function ProductCard({ product }) {
+  return (
+    <Link path={`/products/${product.id}`} label={product.name} />
+  );
+}
+```
+
+**✅ Use framework useNavigate:**
+```tsx
+import { useNavigate } from '@donotdev/ui/routing';
+
+function ProductForm() {
+  const navigate = useNavigate();
+  
+  const handleSubmit = async () => {
+    await saveProduct();
+    navigate('/products'); // ✅ Closes overlays automatically
+  };
+  
+  return <form onSubmit={handleSubmit}>...</form>;
+}
+```
+
+**❌ DON'T use react-router-dom:**
+```tsx
+import { useNavigate } from 'react-router-dom'; // ❌ BREAKS FRAMEWORK
+
+function ProductForm() {
+  const navigate = useNavigate(); // ❌ Doesn't close overlays, breaks SPA
+  // ...
+}
+```
+
+---
+
+### 2. Route Parameters
+
+**✅ Use framework useRouteParam:**
+```tsx
+import { useRouteParam } from '@donotdev/ui/routing';
+
+function ProductPage() {
+  const id = useRouteParam('id'); // ✅ Returns string | undefined
+  // Safe: handles string | string[] | undefined automatically
+}
+```
+
+**✅ Or use framework useParams:**
+```tsx
+import { useParams } from '@donotdev/ui/routing';
+
+function ProductPage() {
+  const params = useParams();
+  const id = typeof params.id === 'string' ? params.id : undefined;
+}
+```
+
+**❌ DON'T use react-router-dom:**
+```tsx
+import { useParams } from 'react-router-dom'; // ❌ Type issues, breaks framework
+```
+
+---
+
+### 3. Sidebar Navigation
+
+**✅ Use DnDevNavigationMenu (auto-fetches routes):**
+```tsx
+import { DnDevNavigationMenu, DISPLAY } from '@donotdev/ui/routing';
+
+function Sidebar() {
+  return (
+    <DnDevNavigationMenu
+      vertical
+      display={DISPLAY.AUTO} // CSS-driven collapse
+      showIcons={true}
+    />
+  );
+}
+```
+
+**✅ Or use useNavigationItems for custom sidebar:**
+```tsx
+import { Link, useNavigationItems } from '@donotdev/ui/routing';
+
+function CustomSidebar() {
+  const menuItems = useNavigationItems(); // ✅ Auth-filtered routes
+  
+  return (
+    <nav>
+      {menuItems.map((item) => (
+        <Link
+          key={item.path}
+          path={item.path}
+          label={item.label}
+          icon={item.icon}
+          className={item.isActive ? 'active' : ''}
+        />
+      ))}
+    </nav>
+  );
+}
+```
+
+**❌ DON'T manually build navigation:**
+```tsx
+import { Link } from 'react-router-dom'; // ❌ BREAKS FRAMEWORK
+
+function Sidebar() {
+  // ❌ Doesn't integrate with route discovery
+  // ❌ Doesn't handle auth filtering
+  // ❌ Doesn't work with Outlet
+  return (
+    <nav>
+      <Link to="/products">Products</Link>
+    </nav>
+  );
+}
+```
+
+---
+
+### 4. Programmatic Navigation
+
+**✅ Use framework useNavigate:**
+```tsx
+import { useNavigate } from '@donotdev/ui/routing';
+
+function LoginForm() {
+  const navigate = useNavigate();
+  
+  const handleLogin = async () => {
+    await signIn();
+    navigate('/dashboard', { replace: true }); // ✅ Closes overlays
+  };
+  
+  return <form onSubmit={handleLogin}>...</form>;
+}
+```
+
+**✅ Navigate back:**
+```tsx
+const navigate = useNavigate();
+navigate('back'); // ✅ Framework handles browser history
+```
+
+**✅ With options:**
+```tsx
+navigate('/products', {
+  replace: true,        // Replace history entry
+  preserveScroll: true, // Preserve scroll position
+});
+```
+
+---
+
+### 5. Query Parameters
+
+**✅ Use framework useSearchParams:**
+```tsx
+import { useSearchParams } from '@donotdev/ui/routing';
+
+function ProductList() {
+  const [searchParams, setSearchParams] = useSearchParams();
+  const page = searchParams.get('page') || '1';
+  
+  const handlePageChange = (newPage: string) => {
+    setSearchParams({ page: newPage });
+  };
+  
+  return <div>Page: {page}</div>;
+}
+```
+
+**✅ Or use useQueryParams helper:**
+```tsx
+import { useQueryParams } from '@donotdev/ui/routing';
+
+function ProductList() {
+  const { page, sort } = useQueryParams({ page: '1', sort: 'name' });
+  // Returns { page: string, sort: string } with defaults
+}
+```
+
+---
+
+### 6. Route Matching
+
+**✅ Use framework useMatch:**
+```tsx
+import { useMatch } from '@donotdev/ui/routing';
+
+function NavigationItem({ path }) {
+  const isActive = useMatch(path);
+  return <Link path={path} className={isActive ? 'active' : ''} />;
+}
+```
+
+---
+
+## Outlet and Nested Routes
+
+**Framework handles Outlet automatically.** You don't need to manually use `<Outlet />` in most cases.
+
+### How It Works
+
+1. **RootLayout** wraps all routes and includes `<Outlet />`
+2. **DnDevLayout** receives `<Outlet />` and renders it in the main content area
+3. **Routes are discovered** from `src/pages/*Page.tsx` files automatically
+
+**✅ Your pages just render content:**
+```tsx
+// src/pages/ProductsPage.tsx
+export function ProductsPage() {
+  return <div>Products List</div>; // ✅ Rendered via Outlet automatically
+}
+```
+
+**❌ DON'T manually use Outlet:**
+```tsx
+import { Outlet } from 'react-router-dom'; // ❌ BREAKS FRAMEWORK
+
+export function ProductsPage() {
+  return (
+    <div>
+      <h1>Products</h1>
+      <Outlet /> {/* ❌ Framework already handles this */}
+    </div>
+  );
+}
+```
+
+### Nested Routes (Advanced)
+
+If you need nested routes, use the framework's route discovery:
+
+```tsx
+// src/pages/products/ProductsPage.tsx
+export const pageMeta = {
+  route: '/products',
+  // ...
+};
+
+// src/pages/products/ProductDetailPage.tsx
+export const pageMeta = {
+  route: '/products/:id',
+  // ...
+};
+```
+
+Framework automatically creates nested route structure.
+
+---
+
+## Route Discovery
+
+**Routes are auto-discovered from `src/pages/*Page.tsx` files.**
+
+**✅ Define routes with PageMeta:**
+```tsx
+// src/pages/ProductsPage.tsx
+import type { PageMeta } from '@donotdev/core';
+
+export const pageMeta: PageMeta = {
+  title: 'Products',
+  route: '/products',
+  icon: 'Package',
+  auth: { required: true, roles: ['user', 'admin'] },
+};
+
+export function ProductsPage() {
+  return <div>Products</div>;
+}
+```
+
+**Framework automatically:**
+- Discovers routes from filesystem
+- Generates navigation menus
+- Filters by auth permissions
+- Handles lazy loading
+- Creates route structure
+
+---
+
+## Common Mistakes
+
+### ❌ Mistake 1: Importing from react-router-dom
+
+```tsx
+// ❌ WRONG
+import { Link, useNavigate } from 'react-router-dom';
+```
+
+**Fix:**
+```tsx
+// ✅ CORRECT
+import { Link, useNavigate } from '@donotdev/ui/routing';
+```
+
+---
+
+### ❌ Mistake 2: Manual Outlet Usage
+
+```tsx
+// ❌ WRONG
+import { Outlet } from 'react-router-dom';
+
+export function Layout() {
+  return <Outlet />; // Framework already handles this
+}
+```
+
+**Fix:** Don't use Outlet manually. Framework handles it.
+
+---
+
+### ❌ Mistake 3: Manual Route Configuration
+
+```tsx
+// ❌ WRONG
+import { Routes, Route } from 'react-router-dom';
+
+function App() {
+  return (
+    <Routes>
+      <Route path="/products" element={<ProductsPage />} />
+    </Routes>
+  );
+}
+```
+
+**Fix:** Use route discovery. Create `src/pages/ProductsPage.tsx` with `pageMeta`.
+
+---
+
+### ❌ Mistake 4: Manual Navigation Menu
+
+```tsx
+// ❌ WRONG
+function Sidebar() {
+  return (
+    <nav>
+      <Link to="/products">Products</Link>
+      <Link to="/users">Users</Link>
+    </nav>
+  );
+}
+```
+
+**Fix:**
+```tsx
+// ✅ CORRECT
+import { DnDevNavigationMenu } from '@donotdev/ui/routing';
+
+function Sidebar() {
+  return <DnDevNavigationMenu vertical />; // Auto-fetches routes
+}
+```
+
+---
+
+### ❌ Mistake 5: Not Using Framework Link
+
+```tsx
+// ❌ WRONG
+import { Link } from 'react-router-dom';
+
+<Link to="/products">Products</Link>
+```
+
+**Fix:**
+```tsx
+// ✅ CORRECT
+import { Link } from '@donotdev/ui/routing';
+
+<Link path="/products" label="Products" />
+```
+
+---
+
+## Quick Reference
+
+### Import Paths
+
+```tsx
+// ✅ Framework routing (platform-agnostic)
+import {
+  Link,
+  useNavigate,
+  useLocation,
+  useParams,
+  useRouteParam,
+  useSearchParams,
+  useNavigationItems,
+  DnDevNavigationMenu,
+} from '@donotdev/ui/routing';
+```
+
+### Common Patterns
+
+```tsx
+// Navigation
+const navigate = useNavigate();
+navigate('/products');
+navigate('back');
+navigate('/products', { replace: true });
+
+// Route params
+const id = useRouteParam('id');
+
+// Query params
+const [searchParams, setSearchParams] = useSearchParams();
+const page = searchParams.get('page');
+
+// Navigation menu
+const menuItems = useNavigationItems(); // Auth-filtered routes
+
+// Link component
+<Link path="/products" label="Products" icon="Package" />
+```
+
+---
+
+## Summary
+
+1. **Always use `@donotdev/ui/routing`** - never `react-router-dom`
+2. **Use `DnDevNavigationMenu`** for sidebars/headers
+3. **Use `useNavigationItems()`** for custom navigation
+4. **Don't use `<Outlet />` manually** - framework handles it
+5. **Routes are auto-discovered** from `src/pages/*Page.tsx`
+6. **Framework closes overlays** on navigation automatically
+
+**Framework handles SPA navigation, Outlet, and route discovery. Use framework components/hooks only.**