@donotdev/cli 0.0.3 → 0.0.5

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

@@ -0,0 +1,14 @@
+# Environment Setup
+
+If you see this guide, you've already installed `@donotdev/cli` and ran `dndev init`.
+
+## Next Steps
+
+1. **AI Agent?** Have them read [AGENT_START_HERE.md](./AGENT_START_HERE.md)
+2. **Create app:** `dndev create-app` - choose Vite (SPA) or Next.js (SSR), with optional backend
+3. **Build:** Use auto-routing, auth, and translations
+
+## Resources
+
+- https://donotdev.com
+- Discord: https://discord.gg/fbeYWDak

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

@@ -4,46 +4,38 @@
 
 ---
 
-## Quick Setup
-
-1. [INSTALLATION.md](./INSTALLATION.md) - Install framework packages
-2. [GETTING_STARTED.md](./GETTING_STARTED.md) - Scaffold first app
-3. [FRAMEWORK_OVERVIEW.md](./FRAMEWORK_OVERVIEW.md) - Package structure
-
----
-
 ## Core Setup
 
-- [PAGES_SETUP.md](./PAGES_SETUP.md) - File-based routing
-- [CONFIG_SETUP.md](./CONFIG_SETUP.md) - App + Vite configuration
-- [I18N_SETUP.md](./I18N_SETUP.md) - Translations
-- [THEMING_SETUP.md](./THEMING_SETUP.md) - Themes + CSS variables
+- [SETUP_PAGES.md](./SETUP_PAGES.md) - Pages & routing (pre-configured)
+- [SETUP_APP_CONFIG.md](./SETUP_APP_CONFIG.md) - App + Vite configuration
+- [SETUP_I18N.md](./SETUP_I18N.md) - Translations (pre-configured)
+- [SETUP_THEMES.md](./SETUP_THEMES.md) - Themes & CSS variables (pre-configured)
+- [SETUP_LAYOUTS.md](./SETUP_LAYOUTS.md) - Layout presets (pre-configured)
 
 ---
 
 ## Feature Setup
 
-- [AUTH_SETUP.md](./AUTH_SETUP.md) - Authentication
-- [BILLING_SETUP.md](./BILLING_SETUP.md) - Stripe subscriptions
-- [APP_CHECK_SETUP.md](./APP_CHECK_SETUP.md) - Abuse protection (reCAPTCHA)
-- [FUNCTIONS.md](./FUNCTIONS.md) - Firebase Cloud Functions
+- [SETUP_AUTH.md](./SETUP_AUTH.md) - Authentication (pre-configured)
+- [SETUP_OAUTH.md](./SETUP_OAUTH.md) - OAuth connections (pre-configured)
+- [SETUP_BILLING.md](./SETUP_BILLING.md) - Stripe subscriptions (pre-configured)
+- [SETUP_FUNCTIONS.md](./SETUP_FUNCTIONS.md) - Firebase Functions (pre-configured)
 
 ---
 
-## Usage & Reference
+## Component Reference
 
-- [HOW_TO_USE.md](./HOW_TO_USE.md) - Component composition philosophy
-- [COMPONENTS.md](./COMPONENTS.md) - Component catalog
-- [FEATURES.md](./FEATURES.md) - Feature packages usage
-- [LAYOUTS.md](./LAYOUTS.md) - Layout presets
-- [STYLING.md](./STYLING.md) - Styling system
-- [IMPORT_PATTERNS.md](./IMPORT_PATTERNS.md) - Import conventions
+- [COMPONENTS_ATOMIC.md](./COMPONENTS_ATOMIC.md) - Atomic components (@donotdev/components)
+- [COMPONENTS_UI.md](./COMPONENTS_UI.md) - Layout/composition components (@donotdev/ui)
+- [COMPONENTS_CRUD.md](./COMPONENTS_CRUD.md) - CRUD components (@donotdev/crud)
 
 ---
 
-## Tools
+## Advanced
 
-- [CLI.md](./CLI.md) - `dndev` commands
+- [advanced/APP_CHECK.md](./advanced/APP_CHECK.md) - Abuse protection
+- [advanced/EMULATORS.md](./advanced/EMULATORS.md) - Local emulator setup
+- [advanced/VERSION_CONTROL.md](./advanced/VERSION_CONTROL.md) - Package upgrades
 
 ---
 

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

@@ -0,0 +1,77 @@
+# Setup: Authentication (Firebase Auth)
+
+**Most is pre-configured.** Firebase Auth for user sign-in/sign-up. Add env vars and config. Framework handles providers, callbacks, sessions.
+
+---
+
+## Standard Use
+
+**Environment:**
+```bash
+# .env
+VITE_AUTH_PARTNERS=password,emailLink,google,github,facebook
+```
+
+**Config:**
+```typescript
+// src/config/app.ts
+export const appConfig: AppConfig = {
+  auth: {
+    authRoute: '/login',
+    loginPath: '/login',     // Optional: undefined = header providers
+    profilePath: '/profile',
+  },
+};
+```
+
+**Firebase Console:** Enable providers in Authentication > Sign-in method
+
+---
+
+## Advanced: Protected Routes
+
+```tsx
+// Basic protection
+export const meta: PageMeta = {
+  namespace: NAMESPACE,
+  auth: { required: true },
+};
+
+// Role-based access
+export const meta: PageMeta = {
+  namespace: NAMESPACE,
+  auth: { required: true, role: 'admin' },
+};
+
+// Tier-based access
+export const meta: PageMeta = {
+  namespace: NAMESPACE,
+  auth: { required: true, tier: 'pro' },
+};
+```
+
+---
+
+## Advanced: Components & Hooks
+
+```tsx
+import { useAuth } from '@donotdev/auth';
+import { MultipleAuthProviders, AuthPartnerButton } from '@donotdev/auth';
+import { AuthHeader, AuthMenu } from '@donotdev/ui';
+import { LoginTemplate } from '@donotdev/templates';
+
+// Hook
+const user = useAuth('user');
+const signIn = useAuth('signInWithEmail');
+const signOut = useAuth('signOut');
+
+// Components
+<MultipleAuthProviders layout="vertical" emailMode="signin" />
+<AuthPartnerButton partnerId="google" method="popup" />
+```
+
+**Pre-configured:** `AuthHeader` in layout (null if auth disabled), OAuth callbacks, session management, account linking.
+
+---
+
+**Add env vars, get auth. Framework handles the rest.**

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

@@ -0,0 +1,78 @@
+# Setup: Billing
+
+**Most is pre-configured.** Create Stripe config files. Framework handles checkout, webhooks, subscriptions.
+
+---
+
+## Standard Use
+
+**Environment:**
+```bash
+# .env (frontend)
+VITE_STRIPE_PUBLISHABLE_KEY=pk_test_xxx
+
+# functions/.env.local (local)
+STRIPE_SECRET_KEY=sk_test_xxx
+STRIPE_WEBHOOK_SECRET=whsec_xxx  # From 'stripe listen'
+
+# functions/.env (production)
+STRIPE_SECRET_KEY=sk_live_xxx
+STRIPE_WEBHOOK_SECRET=whsec_xxx
+```
+
+**Stripe Dashboard:** Create products, copy Price IDs (`price_...`)
+
+---
+
+## Advanced: Frontend Config
+
+```typescript
+// src/config/stripeFrontConfig.ts
+export const stripeFrontConfig: StripeFrontConfig = {
+  pro_plan: {
+    name: 'Pro Plan',
+    price: 29,
+    currency: 'USD',
+    priceId: 'price_1234567890',
+    allowPromotionCodes: true,
+  },
+};
+```
+
+---
+
+## Advanced: Backend Config
+
+```typescript
+// functions/src/config/stripeBackConfig.ts
+export const stripeBackConfig: StripeBackConfig = {
+  pro_plan: {
+    type: 'StripeSubscription', // or 'StripePayment'
+    price: 2900, // In cents
+    priceId: process.env.STRIPE_PRICE_PRO_PLAN!,
+    tier: 'pro',
+    onPurchaseSuccess: async (userId, metadata) => { /* Grant features */ },
+  },
+};
+
+// functions/src/index.ts
+import { createCheckoutSession } from '@donotdev/functions/firebase';
+export const createCheckout = createCheckoutSession(stripeBackConfig);
+```
+
+---
+
+## Advanced: Components & Hooks
+
+```tsx
+import { useStripeBilling } from '@donotdev/billing';
+import { SubscriptionTemplate, PaymentTemplate } from '@donotdev/templates';
+import { ProductCard, SubscriptionManager } from '@donotdev/billing';
+
+const checkout = useStripeBilling('checkout');
+await checkout({ priceId: 'price_123', mode: 'subscription' });
+```
+
+---
+
+**Create config files, get billing. Framework handles the rest.**

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

@@ -0,0 +1,62 @@
+# Setup: Firebase Functions
+
+**Most is pre-configured.** Functions scaffolded. Just add config and deploy.
+
+---
+
+## Standard Use
+
+**Structure:**
+```
+functions/
+├── src/
+│   ├── billing/
+│   └── index.ts
+├── functions.yaml    # Manually maintained
+└── .env.local        # Local secrets
+```
+
+**Environment:**
+```bash
+# .env.local (local)
+STRIPE_SECRET_KEY=sk_test_...
+
+# .env (production, synced via dndev sync-secrets)
+STRIPE_SECRET_KEY=sk_live_...
+```
+
+---
+
+## Advanced: Adding Functions
+
+1. **Create:** `src/billing/myFunction.ts`
+2. **Export:** `export * from './billing/myFunction.js';` in `src/index.ts`
+3. **Add to functions.yaml:**
+```yaml
+endpoints:
+  myFunction:
+    region: [europe-west1]
+    platform: gcfv2
+    httpsTrigger: {}
+    entryPoint: myFunction
+    labels: {}
+```
+4. **Deploy:** `dndev deploy`
+
+**Critical:** Every exported function must be in `functions.yaml` or it won't deploy.
+
+---
+
+## Advanced: Framework Integration
+
+```typescript
+// Your function = framework + your config
+import { createCheckoutSession as generic } from '@donotdev/functions/firebase';
+import { stripeBackConfig } from '../config/stripeBackConfig';
+
+export const createCheckoutSession = generic(stripeBackConfig);
+```
+
+---
+
+**Add functions, get backend. Framework handles the rest.**

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

@@ -0,0 +1,187 @@
+# Setup: Internationalization
+
+**Most is pre-configured.** Drop translation files. Framework auto-discovers languages.
+
+---
+
+## 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
+
+**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';
+
+// 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.
+
+---
+
+## Advanced: Array Translations
+
+### Low-level: translateArray
+
+```tsx
+import { translateArray, translateObjectArray, maybeTranslate } from '@donotdev/core';
+
+// 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
+
+```tsx
+import { LanguageSelector, LanguageFAB, FAQSection, TranslatedText, useLanguageSelector } from '@donotdev/core';
+
+<LanguageSelector display="auto" />           // Already in presets
+<LanguageFAB />                               // Floating action button
+<FAQSection items={faqItems} namespace="faq" />
+<TranslatedText keyPath="welcome.message" namespace="home" />
+const { languages, currentLanguage } = useLanguageSelector();
+```
+
+---
+
+**Drop files, get languages. Framework handles the rest.**

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

@@ -0,0 +1,126 @@
+# Setup: Layouts
+
+**Most is pre-configured.** Choose preset in `config/app.ts`. Framework handles header, sidebar, footer, auth, themes, languages.
+
+---
+
+## Standard Use
+
+**Choose preset:**
+```typescript
+// config/app.ts
+export const appConfig: AppConfig = {
+  preset: 'landing', // landing | admin | moolti | docs | blog | game | plain
+};
+```
+
+**7 presets:** `landing` (marketing), `admin` (dashboards), `moolti` (SaaS), `docs` (documentation), `blog` (content), `game` (mobile), `plain` (minimal).
+
+---
+
+## 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:**
+```tsx
+<ViteAppProviders
+  config={appConfig}
+  layout={{
+    header: {
+      start: () => <CustomLogo />,    // Override start zone
+      center: () => <SearchBar />,     // Override center zone
+      end: () => <UserMenu />,         // Override end zone
+    },
+    sidebar: {
+      top: () => <Branding />,         // Override top zone
+      content: () => <CustomNav />,    // Override content zone
+      bottom: () => <UserProfile />,    // Override bottom zone
+    },
+    footer: () => <CustomFooter />,    // Replace entire footer
+  }}
+/>
+```
+
+**Hide zones:**
+```tsx
+layout={{
+  header: {
+    center: () => null,  // Hide center zone
+  },
+  footer: () => null,    // Hide footer
+}}
+```
+
+**Available slots:** `header.start/center/end`, `sidebar.top/content/bottom`, `footer`, `mergedbar` (mobile nav).
+
+---
+
+## Advanced: CSS Variable Overrides
+
+**Override dimensions in `src/themes.css`:**
+```css
+:root {
+  --header-height: 96px;
+  --sidebar-width: 320px;
+  --main-max-width: 1480px;
+  --footer-height: 64px;
+  --section-gap: 2rem;
+}
+```
+
+**Framework auto-computes:** Spacing, typography, responsive breakpoints.
+
+---
+
+## Advanced: Density System
+
+**Global density:**
+```tsx
+layout={{
+  density: 'compact', // compact | standard | expressive
+}}
+```
+
+**Per-page density:**
+```tsx
+<PageContainer density="expressive">
+  <HeroSection title="Hero" />
+</PageContainer>
+```
+
+**Three densities:** `compact` (1.2×), `standard` (1.25×), `expressive` (1.333×).
+
+---
+
+## Advanced: Runtime Preset Changes
+
+**Change preset programmatically:**
+```tsx
+import { useLayout } from '@donotdev/core';
+
+const setLayoutPreset = useLayout('setLayoutPreset');
+setLayoutPreset('plain');  // Switch to plain layout
+```
+
+**Pre-configured:** All presets handle auth, themes, languages automatically.
+
+---
+
+**Choose preset, get layout. Framework handles the rest.**

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

@@ -0,0 +1,53 @@
+# Setup: OAuth (Third-Party Connections)
+
+**Most is pre-configured.** Connect to Spotify, LinkedIn, GitHub, etc. for API access. Add env vars. Framework handles OAuth flows, token exchange, refresh.
+
+---
+
+## Standard Use
+
+**Environment:**
+```bash
+# .env
+VITE_OAUTH_PARTNERS=github,google,spotify,discord
+VITE_OAUTH_GITHUB_CLIENT_ID=your_github_client_id
+VITE_OAUTH_GOOGLE_CLIENT_ID=your_google_client_id
+VITE_OAUTH_SPOTIFY_CLIENT_ID=your_spotify_client_id
+VITE_OAUTH_DISCORD_CLIENT_ID=your_discord_client_id
+```
+
+**Available:** `github`, `google`, `spotify`, `discord`, `twitch`, `reddit`, `linkedin`, `slack`, `notion`, `medium`, `twitter`, `mastodon`, `youtube`
+
+**OAuth Provider Dashboard:** Create OAuth apps, copy Client IDs, configure redirect URIs.
+
+---
+
+## Advanced: Components & Hooks
+
+```tsx
+import { useOAuth } from '@donotdev/oauth';
+import { MultipleOAuthProviders, OAuthPartnerButton } from '@donotdev/oauth';
+import { OAuthConnectionModal } from '@donotdev/oauth';
+
+// Hook
+const connect = useOAuth('connect');
+const disconnect = useOAuth('disconnect');
+const isConnected = useOAuth('isConnected');
+const loading = useOAuth('loading');
+const error = useOAuth('error');
+
+await connect('github', 'api-access');  // Purpose: 'authentication' | 'api-access'
+await disconnect('github');
+const connected = isConnected('github');
+
+// Components
+<MultipleOAuthProviders purpose="api-access" layout="vertical" />
+<OAuthPartnerButton partnerId="github" purpose="api-access" />
+<OAuthConnectionModal />
+```
+
+**Pre-configured:** Auto-discovers enabled providers, handles PKCE flow, token refresh, callbacks.
+
+---
+
+**Add env vars, get OAuth. Framework handles the rest.**