@donotdev/cli 0.0.5 → 0.0.7

package/templates/root-consumer/guides/{COMPONENTS_ATOMIC.md.example → dndev/COMPONENTS_ATOMIC.md.example}

@@ -22,6 +22,7 @@ These are the only ways one should handle layout to get to quick results functio
 ## Content Components
 
 - **Card** - Premium card component with title, content, footer, and elevation variants.
+  - **Navigation with middle-click support:** Wrap Card in Link component for navigation that supports middle-click (opens in new tab). See navigation section below.
 - **DualCard** - Side-by-side card layout for comparison or feature showcases.
 - **Text** - Typography component with semantic text variants.
 - **Blockquote** - Styled blockquote for citations and testimonials.
@@ -130,5 +131,46 @@ These are the only ways one should handle layout to get to quick results functio
 
 **See also:** [COMPONENTS_UI.md](./COMPONENTS_UI.md) for layout/composition components | [COMPONENTS_CRUD.md](./COMPONENTS_CRUD.md) for CRUD operations and entity forms
 
+---
+
+## Navigation with Card Component
+
+**For clickable cards with navigation support (including middle-click):**
+
+Wrap Card in Link component from `@donotdev/ui`:
+
+```tsx
+import { Card } from '@donotdev/components';
+import { Link } from '@donotdev/ui';
+
+// Card with navigation (supports middle-click)
+<Link
+  path="/about"
+  style={{ display: 'block', textDecoration: 'none', height: '100%' }}
+  aria-label="Learn more about About"
+>
+  <Card
+    title="About"
+    subtitle="Learn more about us"
+    content="Click to navigate"
+  />
+</Link>
+
+// Card with onClick only (no middle-click support)
+<Card
+  title="Action Card"
+  onClick={() => handleAction()}
+/>
+```
+
+**Why wrap in Link?**
+- Card component is standalone and not routing-aware
+- Link wrapper provides framework navigation (SPA routing, keeps outlet context)
+- Native browser middle-click support (opens in new tab)
+- CSR/SSR safe
+
+**Alternative:** Use FeatureCard from `@donotdev/ui` which handles this automatically when `href` prop is provided.
+
+---
 
 **All props documented in JSDoc** - Hover in IDE for complete reference.

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

@@ -0,0 +1,231 @@
+# CRUD Package Reference
+
+**Import:** `@donotdev/crud`
+
+---
+
+## Hooks
+
+### useCrud
+Single document CRUD actions (add, update, delete, get, subscribe).
+
+```tsx
+const { add, update, delete: remove, get, data, loading, error } = useCrud(carEntity);
+await add({ name: 'Tesla', year: 2024 });
+await remove('doc-id');
+```
+
+### useCrudList
+Paginated list with automatic loading. For data tables.
+
+```tsx
+const { items, loading, hasMore, loadMore } = useCrudList(productEntity);
+```
+
+### useCrudCardList  
+Card-based list with infinite scroll.
+
+```tsx
+const { items, loading, hasMore, loadMore, refresh } = useCrudCardList(articleEntity);
+```
+
+---
+
+## Form Components
+
+### EntityFormRenderer
+Auto-render full entity form from definition.
+
+```tsx
+<EntityFormRenderer
+  entity={productEntity}
+  operation="create"
+  onSubmit={handleSubmit}
+/>
+```
+
+### FormFieldRenderer
+Render single field. Used inside custom forms.
+
+```tsx
+<FormFieldRenderer field={field} control={form.control} />
+```
+
+### EntityList
+Data table for entity collection.
+
+```tsx
+<EntityList entity={userEntity} onRowClick={(user) => edit(user.id)} />
+```
+
+### EntityCardList
+Card grid for entity collection.
+
+```tsx
+<EntityCardList entity={productEntity} renderCard={(item) => <ProductCard {...item} />} />
+```
+
+---
+
+## Form Building Blocks
+
+For custom forms, use these low-level utilities:
+
+```tsx
+import { useEntityForm, getFieldsForOperation, validateEntity } from '@donotdev/crud';
+
+const { register, handleSubmit, fields, formState } = useEntityForm(productEntity, { 
+  operation: 'create' 
+});
+```
+
+| Export | Purpose |
+|--------|---------|
+| `useEntityForm` | React Hook Form wrapper for entities |
+| `useEntityField` | Single field hook |
+| `getFieldsForOperation` | Get editable fields for create/edit |
+| `validateEntity` | Validate data against entity schema |
+| `isFieldEditable` | Check if field is editable |
+
+---
+
+## Field Types (Built-in)
+
+Field components are auto-rendered by `FormFieldRenderer`. You don't import them directly.
+
+### Text Inputs
+- `text` - Single-line text input
+- `email` - Email input with validation
+- `tel` - Phone number input
+- `url` - URL input
+- `color` - Color picker
+- `password` - Password input (masked)
+- `textarea` - Multi-line text input
+- `richtext` - Rich text editor
+
+### Numbers
+- `number` - Numeric input
+- `range` - Slider input
+
+### Boolean
+- `checkbox` - Checkbox input
+- `boolean` - Alias for checkbox
+- `switch` - Toggle switch
+
+### Dates & Time
+- `date` - Date picker
+- `datetime-local` - Date and time picker
+- `time` - Time picker
+- `week` - Week picker
+- `month` - Month picker
+- `timestamp` - Timestamp (Firestore Timestamp)
+
+### Selection
+- `select` - Dropdown select
+- `combobox` - Searchable dropdown
+- `multiselect` - Multiple selection dropdown
+- `radio` - Radio button group
+
+### Files & Media
+- `file` - Single file upload
+- `files` - Multiple file uploads
+- `document` - Document upload (PDF, etc.)
+- `documents` - Multiple document uploads
+- `image` - Single image upload
+- `images` - Multiple image uploads
+
+### Complex Types
+- `geopoint` - Geographic coordinates (lat/lng)
+- `address` - Address input with autocomplete
+- `map` - Map picker
+- `array` - Array of text inputs
+
+### Special
+- `avatar` - Avatar image upload
+- `badge` - Badge display
+- `hidden` - Hidden field (not displayed)
+- `submit` - Submit button (uncontrolled)
+- `reset` - Reset button (uncontrolled)
+
+To add custom field types:
+```tsx
+import { useController, registerFieldType } from '@donotdev/crud';
+import type { ControlledFieldProps } from '@donotdev/crud';
+
+// Custom controlled component MUST use framework's useController (not react-hook-form's)
+function RatingField({
+  fieldConfig,
+  control,
+  errors,
+  t,
+  onChange
+}: ControlledFieldProps) {
+  // REQUIRED: Use framework's useController - ensures type compatibility
+  const { field, fieldState } = useController({
+    name: fieldConfig.name,
+    control: control,
+  });
+
+  return (
+    <div>
+      <label>{t(fieldConfig.label)}</label>
+      {/* Use field.value and field.onChange */}
+      <input
+        type="number"
+        value={field.value ?? 0}
+        onChange={(e) => {
+          const value = Number(e.target.value);
+          field.onChange(value);
+          onChange?.(value);
+        }}
+        min={0}
+        max={5}
+      />
+      {fieldState?.error && (
+        <span className="error">{fieldState.error.message}</span>
+      )}
+    </div>
+  );
+}
+
+registerFieldType({
+  type: 'rating',
+  controlledComponent: RatingField,
+});
+```
+
+**Important:** 
+- Custom controlled components receive `control` prop, NOT `field` prop
+- You must use **framework's `useController`** (from `@donotdev/crud`), NOT `react-hook-form`'s useController
+- This ensures type compatibility - no type assertions needed
+
+---
+
+## Service & Store
+
+Direct access (rarely needed):
+
+```tsx
+import { getCrudService, useCrudStore } from '@donotdev/crud';
+
+const service = getCrudService();
+await service.query('products', { where: [['active', '==', true]] });
+```
+
+---
+
+## Collection Utilities
+
+```tsx
+import { loadDeterministicRange, upsertDeterministic, appendToCollection } from '@donotdev/crud';
+```
+
+| Utility | Purpose |
+|---------|---------|
+| `loadDeterministicRange` | Paginated loading with deterministic IDs |
+| `upsertDeterministic` | Insert or update with deterministic ID |
+| `appendToCollection` | Add to collection end |
+
+---
+
+**JSDoc in IDE** - Hover over any import for full props and examples.

package/templates/root-consumer/guides/{INDEX.md.example → dndev/INDEX.md.example}

@@ -7,6 +7,7 @@
 ## Core Setup
 
 - [SETUP_PAGES.md](./SETUP_PAGES.md) - Pages & routing (pre-configured)
+- [USE_ROUTING.md](./USE_ROUTING.md) - **Routing components & hooks (CRITICAL)**
 - [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)
@@ -16,9 +17,11 @@
 
 ## Feature Setup
 
+- [SETUP_CRUD.md](./SETUP_CRUD.md) - CRUD operations & data access (critical)
 - [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_PWA.md](./SETUP_PWA.md) - Progressive Web App setup
 - [SETUP_FUNCTIONS.md](./SETUP_FUNCTIONS.md) - Firebase Functions (pre-configured)
 
 ---

package/templates/root-consumer/guides/{SETUP_APP_CONFIG.md.example → dndev/SETUP_APP_CONFIG.md.example}

@@ -13,6 +13,8 @@ import type { AppConfig } from '@donotdev/core';
 export const appConfig: AppConfig = {
   app: {
     name: 'My App',
+    shortName: 'App',              // Required for PWA
+    description: 'My app description', // Required for PWA
     url: 'https://myapp.com',
   },
 
@@ -93,9 +95,10 @@ export default defineViteConfig({
     generateSitemap: true,
   },
 
-  // PWA
+  // PWA (see SETUP_PWA.md for full guide)
   pwa: {
-    enabled: false,
+    enabled: false,      // Enable PWA in production
+    devEnabled: false,  // Enable PWA in development (optional)
   },
 });
 ```

package/templates/root-consumer/guides/{SETUP_AUTH.md.example → dndev/SETUP_AUTH.md.example}

@@ -74,4 +74,34 @@ const signOut = useAuth('signOut');
 
 ---
 
+## User Roles
+
+**Role hierarchy:** `guest (0) < user (1) < admin (2) < super (3)`
+
+**Default:** All authenticated users are `'user'` role.
+
+**Setting admin/super roles:** Set Firebase Auth customClaims:
+
+```typescript
+// Using Firebase Admin SDK
+import { getFirebaseAdminAuth } from '@donotdev/firebase/server';
+
+const auth = getFirebaseAdminAuth();
+await auth.setCustomUserClaims(userId, {
+  role: 'admin',  // or 'super'
+  isAdmin: true   // legacy support
+});
+```
+
+**Using CLI:**
+```bash
+dndev make-admin <userId>
+```
+
+**Note:** User must sign out and sign in again for role changes to take effect (customClaims are in the ID token).
+
+**Used by:** CRUD access control, protected routes, field visibility filtering.
+
+---
+
 **Add env vars, get auth. Framework handles the rest.**

package/templates/root-consumer/guides/{SETUP_BILLING.md.example → dndev/SETUP_BILLING.md.example}

@@ -1,6 +1,6 @@
 # Setup: Billing
 
-**Most is pre-configured.** Create Stripe config files. Framework handles checkout, webhooks, subscriptions.
+**Most is pre-configured.** Create Stripe config files. Framework handles checkout, webhooks, subscriptions, and loading UX.
 
 ---
 
@@ -24,6 +24,36 @@ STRIPE_WEBHOOK_SECRET=whsec_xxx
 
 ---
 
+## Automatic UX (Zero Config)
+
+**The hook handles loading overlays automatically for redirect operations:**
+
+```tsx
+// Just call the method - framework handles the rest
+const checkout = useStripeBilling('checkout', authState);
+const openCustomerPortal = useStripeBilling('openCustomerPortal', authState);
+
+// Checkout → Shows "Redirecting to Stripe" / "Initializing secure payment..."
+await checkout({ priceId: 'price_123', mode: 'payment' });
+
+// Portal → Shows "Redirecting to Stripe" / "Opening billing portal..."
+await openCustomerPortal();
+```
+
+**What happens automatically:**
+- Blocking fullscreen overlay during Firebase Functions cold start
+- Operation-specific messaging (checkout vs portal)
+- Translated in all 8 supported languages
+- Clean removal on redirect or error
+
+**Optional:** Use `loading` state if you want to disable your own buttons:
+```tsx
+const loading = useStripeBilling('loading', authState);
+<Button disabled={loading}>Purchase</Button>
+```
+
+---
+
 ## Advanced: Frontend Config
 
 ```typescript
@@ -69,10 +99,20 @@ 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' });
+// Auth state required
+const user = useAuth('user');
+const status = useAuth('status');
+const authState = { user, status };
+
+// Methods - framework handles overlay automatically
+const checkout = useStripeBilling('checkout', authState);
+const openCustomerPortal = useStripeBilling('openCustomerPortal', authState);
+
+// Optional state access
+const loading = useStripeBilling('loading', authState);
+const error = useStripeBilling('error', authState);
 ```
 
 ---
 
-**Create config files, get billing. Framework handles the rest.**
+**Create config files, get billing with best-in-class UX. Framework handles the rest.**