@donotdev/cli 0.0.3 → 0.0.4

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

@@ -0,0 +1,135 @@
+# UI Package Reference
+
+**Check JSDoc in your IDE** - Hover over any component import to see props, types, and examples.
+
+**Import from:** `@donotdev/ui` (layout/composition components)
+
+---
+
+## Layout Components
+
+- **PageContainer** - Page wrapper with width constraints, spacing, and density system.
+- **GameContainer** - Game preset container with fixed header/footer layout.
+- **GameFlow** - Game flow component for step-by-step game interfaces.
+
+---
+
+## Layout Sub-Components
+
+- **AppBranding** - App branding display with logo and name.
+- **AppIcon** - App icon component.
+- **AppTitle** - App title display component.
+- **GameTitle** - Game title component for game preset.
+- **Breadcrumbs** - Breadcrumb navigation component.
+- **HeaderNavigation** - Header navigation menu component.
+- **DropdownNavigation** - Dropdown navigation menu.
+- **HeaderMenu** - Header menu component.
+- **SettingsMenu** - Settings menu component.
+- **ThemeToggle** - Theme toggle button component.
+- **CacheSettings** - Cache settings component.
+- **Notifications** - Notifications component.
+- **FloatingLanguageSwitcher** - Floating language selector component.
+
+---
+
+## Auth Components
+
+- **AuthHeader** - Header component with authentication UI (sign in/out, user menu).
+- **AuthMenu** - Authentication menu component.
+
+---
+
+## Common Components
+
+- **AppLoading** - App-level loading component.
+- **FeatureDisabled** - Component shown when features are disabled.
+- **Icon** - Icon component wrapper.
+- **Loader** - Loading spinner component.
+- **LoadingMessage** - Loading message with variants (processing, saving, uploading, etc.).
+- **LoadingOverlay** - Overlay component for loading states.
+- **LoadingScreen** - Full-screen loading component.
+- **ProgressBar** - Progress bar component.
+- **Skeleton** - Skeleton loading component.
+- **FeatureCard** - Feature showcase card component.
+- **TechBento** - Tech stack showcase component.
+
+---
+
+## Routing Components
+
+- **Link** - Platform-agnostic link component (works in Vite + Next.js).
+- **AuthGuard** - Route guard component for protected routes.
+- **AuthGuardFallback** - Fallback component for auth-guarded routes.
+- **GoTo** - Programmatic navigation component.
+- **GoToWrapper** - Wrapper for GoTo navigation.
+- **GoToInput** - Input component for GoTo navigation.
+- **GoToDialog** - Dialog for GoTo navigation.
+- **DnDevNavigationMenu** - Framework navigation menu component.
+- **NotFoundPage** - 404 page component.
+
+---
+
+## Routing Hooks
+
+- **useNavigate** - Navigate to routes programmatically.
+- **useBack** - Navigate back in history.
+- **useRefresh** - Refresh current route.
+- **usePrefetch** - Prefetch route data.
+- **useLocation** - Get current location.
+- **useParams** - Get route parameters.
+- **useSearchParams** - Get URL search parameters.
+- **useMatch** - Match current route pattern.
+- **useQueryParams** - Get and set query parameters.
+- **useRedirectGuard** - Guard against redirects.
+- **useNavigation** - Navigation state and methods.
+- **useGoTo** - GoTo navigation hook.
+- **useRouteDiscovery** - Route discovery hook.
+
+---
+
+## Cookie Consent
+
+- **CookieConsent** - Cookie consent management component.
+- **ConsentBanner** - Cookie consent banner component.
+
+---
+
+## Platform-Specific Providers
+
+- **ViteAppProviders** - App providers for Vite (import from `@donotdev/ui/vite`).
+- **NextJsAppProviders** - App providers for Next.js (import from `@donotdev/ui/next`).
+
+---
+
+## CRUD Display Components (from @donotdev/ui)
+
+- **DisplayFieldRenderer** - Renders read-only field displays.
+- **EntityDisplayRenderer** - Renders complete entity displays.
+- **TextFieldDisplay** - Text field display component.
+- **BadgeFieldDisplay** - Badge field display component.
+- **AvatarFieldDisplay** - Avatar field display component.
+- **LinkFieldDisplay** - Link field display component.
+- **DateFieldDisplay** - Date field display component.
+- **NumberFieldDisplay** - Number field display component.
+- **PhoneNumberDisplay** - Phone number display component.
+- **TextAreaDisplay** - Textarea display component.
+- **CheckboxFieldDisplay** - Checkbox display component.
+- **DropdownDisplay** - Dropdown display component.
+- **MultiDropdownDisplay** - Multi-select dropdown display component.
+- **MultiInputTextFieldDisplay** - Multi-input text field display component.
+- **RadioFieldDisplay** - Radio field display component.
+- **RangeFieldDisplay** - Range field display component.
+- **FileFieldDisplay** - File field display component.
+- **ImageFieldDisplay** - Image field display component.
+- **GeoPointFieldDisplay** - GeoPoint field display component.
+- **MapFieldDisplay** - Map field display component.
+- **ReferenceFieldDisplay** - Reference field display component.
+- **TimestampFieldDisplay** - Timestamp field display component.
+- **HiddenFieldDisplay** - Hidden field display component.
+- **ButtonFieldDisplay** - Button field display component.
+
+---
+
+**For MVP:** Only `PageContainer` is needed. All other components are optional.
+
+**All props documented in JSDoc** - Hover in IDE for complete reference.

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,48 @@
+# Setup: Internationalization
+
+**Most is pre-configured.** Drop translation files. Framework auto-discovers languages.
+
+---
+
+## Standard Use
+
+**Files:** `src/locales/<namespace>_<2-char-ISO>.json` (eager) | `src/pages/locales/<namespace>_<2-char-ISO>.json` (lazy)
+
+```tsx
+import { useTranslation } from '@donotdev/core';
+
+const { t } = useTranslation(NAMESPACE);
+t('title');
+```
+
+**LanguageSelector:** Included in layout presets. Import from `@donotdev/core` if needed elsewhere.
+
+---
+
+## Advanced: Array Translations
+
+```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
+```
+
+---
+
+## 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,108 @@
+# 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).
+
+---
+
+## 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.**