@donotdev/cli 0.0.4 → 0.0.6

package/templates/root-consumer/guides/SETUP_FUNCTIONS.md.example

@@ -4,6 +4,31 @@
 
 ---
 
+## ⚠️ CRITICAL: Import Rules for Functions
+
+**Functions run on Node.js - you MUST use `/server` imports or your function will crash on deploy.**
+
+```typescript
+// ✅ CORRECT - Functions MUST use /server imports
+import { getFirebaseAdminAuth } from '@donotdev/firebase/server';
+import { getFirebaseAdminFirestore } from '@donotdev/firebase/server';
+import { handleError } from '@donotdev/core/server';
+
+// ❌ WRONG - This will crash on deploy (pulls in React/client code)
+import { getAuth } from '@donotdev/firebase';
+import { getFirestore } from '@donotdev/firebase';
+import { handleError } from '@donotdev/core';
+```
+
+**Why?** Functions run in Node.js, not the browser. Client imports (`@donotdev/firebase`) include React and browser-only code that will crash your function.
+
+**Rule:** Always use `/server` suffix for:
+- `@donotdev/firebase/server` (not `@donotdev/firebase`)
+- `@donotdev/core/server` (not `@donotdev/core`)
+- `@donotdev/utils/server` (not `@donotdev/utils`)
+
+---
+
 ## Standard Use
 
 **Structure:**
@@ -59,4 +84,31 @@ export const createCheckoutSession = generic(stripeBackConfig);
 
 ---
 
+## Advanced: Custom Functions with Firebase
+
+**When writing custom functions that access Firestore/Auth, use `/server` imports:**
+
+```typescript
+import { onCall } from 'firebase-functions/v2/https';
+import { FUNCTION_CONFIG } from '@donotdev/functions/firebase';
+// ✅ MUST use /server imports in functions
+import { getFirebaseAdminFirestore } from '@donotdev/firebase/server';
+import { getFirebaseAdminAuth } from '@donotdev/firebase/server';
+import { handleError } from '@donotdev/core/server';
+
+export const myCustomFunction = onCall(FUNCTION_CONFIG, async (request) => {
+  const firestore = getFirebaseAdminFirestore();
+  const auth = getFirebaseAdminAuth();
+  
+  // Your custom logic here
+  const doc = await firestore.collection('users').doc(request.auth.uid).get();
+  
+  return { data: doc.data() };
+});
+```
+
+**Remember:** All Firebase imports in functions MUST use `@donotdev/firebase/server`, never `@donotdev/firebase`.
+
+---
+
 **Add functions, get backend. Framework handles the rest.**

package/templates/root-consumer/guides/SETUP_I18N.md.example

@@ -4,15 +4,81 @@
 
 ---
 
+## Translation File Locations (CRITICAL)
+
+**Two paths - choose based on when translations are needed:**
+
+1. **Eager (`src/locales/`)**: Always loaded - use for common UI, navigation, app-wide content
+2. **Lazy (`src/pages/locales/`)**: Loaded when page loads - use for page-specific content
+
+**✅ RULE OF THUMB:**
+- **Eager**: Navigation, buttons, common messages (used everywhere)
+- **Lazy**: Page content, feature content, large text blocks (used on specific pages)
+
+**Framework auto-discovers both paths. No configuration needed.**
+
+---
+
 ## Standard Use
 
-**Files:** `src/locales/<namespace>_<2-char-ISO>.json` (eager) | `src/pages/locales/<namespace>_<2-char-ISO>.json` (lazy)
+**CRITICAL: Two Translation Paths - Choose Based on When Translations Are Needed**
+
+### Eager Translations (Always Loaded)
+**Path:** `src/locales/<namespace>_<2-char-ISO>.json`
+
+**Use for:**
+- Common UI elements (buttons, labels, navigation)
+- Critical app-wide translations (app name, common messages)
+- Translations needed on every page
+
+**Example:**
+```
+src/
+  locales/
+    common_en.json      # ✅ Eager - always available
+    common_fr.json
+    navigation_en.json  # ✅ Eager - used in header/sidebar
+    navigation_fr.json
+```
 
+### Lazy Translations (Loaded When Page Loads)
+**Path:** `src/pages/locales/<namespace>_<2-char-ISO>.json`
+
+**Use for:**
+- Page-specific content (page titles, descriptions, page content)
+- Feature-specific translations (dashboard, blog, admin)
+- Translations only needed when that page/feature is accessed
+
+**Example:**
+```
+src/
+  pages/
+    HomePage.tsx
+    locales/
+      home_en.json      # ✅ Lazy - loaded when HomePage loads
+      home_fr.json
+    dashboard/
+      DashboardPage.tsx
+      locales/
+        dashboard_en.json  # ✅ Lazy - loaded when DashboardPage loads
+        dashboard_fr.json
+```
+
+**✅ DECISION GUIDE:**
+- **Eager (`src/locales/`)**: Navigation, common buttons, app-wide messages
+- **Lazy (`src/pages/locales/`)**: Page content, feature-specific content, large text blocks
+
+**Usage:**
 ```tsx
 import { useTranslation } from '@donotdev/core';
 
-const { t } = useTranslation(NAMESPACE);
-t('title');
+// Eager namespace (common, navigation, etc.)
+const { t } = useTranslation('common');
+t('app.title');
+
+// Lazy namespace (page-specific)
+const { t } = useTranslation('home');
+t('hero.title');
 ```
 
 **LanguageSelector:** Included in layout presets. Import from `@donotdev/core` if needed elsewhere.
@@ -21,14 +87,87 @@ t('title');
 
 ## Advanced: Array Translations
 
+### Low-level: translateArray
+
 ```tsx
 import { translateArray, translateObjectArray, maybeTranslate } from '@donotdev/core';
 
-translateArray(t, 'benefits', 10);              // Up to 10 items (benefits.0-9), safe if only 4 exist
-translateObjectArray(t, 'cases', 10, ['useCase', 'bestFit']); // Up to 10 objects
-maybeTranslate(t, 'products.earlyBird.name');  // Auto-detects key vs string
+// Get array of strings (filters missing translations automatically)
+const benefits = translateArray(t, 'benefits', 10); // Up to 10 items (benefits.0-9), safe if only 4 exist
+const features = translateArray(t, 'features.list', 5); // Nested keys work
+
+// Get array of objects
+const cases = translateObjectArray(t, 'cases', 10, ['useCase', 'bestFit']);
+
+// Auto-detect if value is a translation key or literal string
+maybeTranslate(t, 'products.earlyBird.name');
 ```
 
+### High-level: tList (Recommended for Cards)
+
+`tList` wraps `translateArray` and returns a `List` component ready for `Card` content:
+
+```tsx
+import { tList } from '@donotdev/ui';
+
+// With default icon (CheckCircle)
+<Card content={tList(t, 'features.items', 4)} />
+
+// With custom icon
+<Card content={tList(t, 'features.items', 4, Star)} />
+
+// Without icon (for emoji-prefixed labels like "🚀 Kick-off")
+<Card content={tList(t, 'features.items', 4, null)} />
+```
+
+**JSON structure:**
+```json
+{
+  "features": {
+    "items": [
+      "Feature 1",
+      "Feature 2",
+      "Feature 3"
+    ]
+  }
+}
+```
+
+---
+
+## Advanced: Rich Text (Trans)
+
+For inline styling in translations, use `Trans` instead of `t()`. Use when translations contain HTML-like tags for styling.
+
+```tsx
+import { Trans } from '@donotdev/core';
+
+// Translation: "<accent>MVP</accent> in 2 weeks"
+<HeroSection title={<Trans ns={NAMESPACE} i18nKey="hero.title" />} />
+
+// Translation: "I need <accent>Clarity</accent>"
+<Card title={<Trans ns={NAMESPACE} i18nKey="products.transformation.title" />} />
+```
+
+**JSON with tags:**
+```json
+{
+  "hero": {
+    "title": "Idea to <accent>MVP</accent> in 2 weeks"
+  },
+  "products": {
+    "transformation": {
+      "title": "I need <accent>Clarity</accent>",
+      "subtitle": "...for a <accent>critical</accent> application"
+    }
+  }
+}
+```
+
+**Supported tags:** `<accent>` `<primary>` `<muted>` `<success>` `<warning>` `<error>` `<bold>` `<code>`
+
+**Note:** `Trans` accepts `ns` prop (string) for namespace. Use `t()` for plain strings, `Trans` for rich text with styling tags.
+
 ---
 
 ## Advanced: I18N Components

package/templates/root-consumer/guides/SETUP_LAYOUTS.md.example

@@ -18,6 +18,24 @@ export const appConfig: AppConfig = {
 
 ---
 
+## Preset Capabilities
+
+**The `docs` preset AUTOMATICALLY generates sidebar navigation from your `src/pages` files. You do not need to configure a sidebar manually.**
+
+All presets automatically include these components when applicable:
+
+*   **LanguageSelector** - Automatically shown if more than 1 language is configured
+*   **ThemeToggle** - Automatically shown if more than 1 theme is available
+*   **AuthMenu** - Automatically shown if auth is configured in `.env` (Firebase keys present)
+*   **Navigation Menu** - Automatically generated from `src/pages/*Page.tsx` files for sidebars
+*   **GoTo Component** - Command palette (Cmd+K) for quick navigation - always available
+*   **Footer** - Automatic footer with copyright and legal links
+*   **LegalLinks + Copyright** - Automatically included in footer from `config/legal.ts`
+
+**You don't need to add these manually - the framework handles them based on your configuration.**
+
+---
+
 ## Advanced: Slot Overrides
 
 **Customize zones:**

package/templates/root-consumer/guides/SETUP_PAGES.md.example

@@ -4,6 +4,14 @@
 
 ---
 
+## File Routing Rule
+
+**CRITICAL: Only files ending in `Page.tsx` inside `src/pages` become routes.**
+
+Files must be named `*Page.tsx` (e.g., `HomePage.tsx`, `AboutPage.tsx`, `BlogPostPage.tsx`). Files without the `Page.tsx` suffix are ignored by the routing system.
+
+---
+
 ## Standard Use
 
 **Pattern:** `src/pages/**/*Page.tsx` → routes
@@ -103,8 +111,25 @@ import { useNavigate, Link } from '@donotdev/ui';
 const navigate = useNavigate();
 navigate('/about');
 <Link path="/about">About</Link>
+
+// Card with navigation (supports middle-click)
+import { Card } from '@donotdev/components';
+import { Link } from '@donotdev/ui';
+
+<Link
+  path="/about"
+  style={{ display: 'block', textDecoration: 'none', height: '100%' }}
+  aria-label="Learn more about About"
+>
+  <Card title="About" subtitle="Learn more" />
+</Link>
 ```
 
+**Navigation patterns:**
+- **Link component:** Use for text links, buttons, or wrapping other components
+- **Card navigation:** Wrap Card in Link for clickable cards with middle-click support
+- **onClick only:** Use `onClick={() => navigate()}` for actions that don't need middle-click
+
 **Pre-configured:** Navigation menu auto-generated, sitemap auto-built (if `generateSitemap: true`).
 
 ---

package/templates/root-consumer/guides/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.**