@donotdev/cli 0.0.6 → 0.0.7

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

@@ -1,1244 +0,0 @@
-# Setup: CRUD Operations
-
-**CRUD = Create, Read, Update, Delete.** Framework handles data ops with built-in security.
-
-Choose between direct Firestore access or Cloud Functions based on your security needs. Functions provide field-level filtering, Firestore relies on security rules.
-
-## Backend Selection
-
-| Backend | Use When | Example |
-|---------|----------|---------|
-| `firestore` | User's own data, public data, no field filtering needed | userProfile, public listings |
-| `functions` | Mixed visibility fields, admin data, field-level security | admin panels, multi-role access |
-
----
-
-## When to Use Each Backend
-
-### `backend: 'firestore'` (Direct)
-
-**Use for:**
-- **User's own data** - Firestore rules enforce `request.auth.uid == userId`
-- **Public data** - No sensitive fields, everyone sees everything
-- **Simple CRUD** - No field-level visibility requirements
-
-```typescript
-// User reading their own profile - Firestore rules are enough
-const { data: profile } = useCrud('userProfiles', { backend: 'firestore' });
-
-// Public product listing - no sensitive fields
-const { data: products } = useCrud('products', { backend: 'firestore' });
-```
-
-**Security:** Firestore Security Rules handle document-level access.
-
----
-
-### `backend: 'functions'` (Via Cloud Functions)
-
-**Use for:**
-- **Mixed visibility** - Some fields guest-visible, some admin-only
-- **Admin panels** - Data with internal/sensitive fields
-- **Multi-role access** - Different users see different fields
-
-```typescript
-// Admin panel - has purchasePrice, vin (admin-only fields)
-const { data: cars } = useCrud('cars', { backend: 'functions' });
-
-// Multi-role - users see guest-visible fields, admins see all
-const { data: orders } = useCrud('orders', { backend: 'functions' });
-```
-
-**Security:** Cloud Functions filter fields based on user role BEFORE sending to client.
-
----
-
-## Decision Tree
-
-```
-Does the data have admin-only fields?
-├─ No  → Does user own this data?
-│        ├─ Yes → backend: 'firestore' (rules enforce ownership)
-│        └─ No  → Is it public data?
-│                 ├─ Yes → backend: 'firestore'
-│                 └─ No  → backend: 'functions'
-└─ Yes → backend: 'functions' (field filtering required)
-```
-
----
-
-## Security Model
-
-**Critical: Separation of concerns**
-
-| Concern | Handled By | Where |
-|---------|------------|-------|
-| **Visibility** (who sees) | Backend | Cloud Functions (`filterVisibleFields`) |
-| **Editability** (who modifies) | Frontend | `EntityFormRenderer` |
-
-**Why?**
-- Visibility = security concern → must be server-side (prevents data leaks)
-- Editability = UI concern → frontend decides input vs read-only display
-
-**Flow:**
-```
-1. Frontend calls backend (useCrud with backend: 'functions')
-2. Backend checks user role, filters fields by visibility
-3. Frontend receives only fields user can see
-4. Frontend renders based on editability (input or read-only)
-```
-
----
-
-## Field Configuration
-
-Controls which fields are included in API responses based on user role. Backend filters fields before sending to client - frontend only renders what it receives.
-
-### Visibility (who SEES the field) - BACKEND enforced
-
-| Value | Who Sees | Filtered By | Shown in Forms |
-|-------|----------|-------------|---------------|
-| `'guest'` | Everyone (even unauthenticated) | Backend | Yes |
-| `'user'` | Authenticated users | Backend | Yes |
-| `'admin'` | Admins only | Backend | Yes |
-| `'technical'` | Admins only (system metadata) | Backend | Edit only (read-only) |
-| `'hidden'` | Never (DB only) | Backend | No |
-
-**Visibility filtering only works with `backend: 'functions'`.**
-Frontend trusts backend - it only renders what it receives.
-
-**Technical fields** (`id`, `createdAt`, etc.) are auto-added by `defineEntity` and shown as read-only in edit forms, never in create forms.
-
-Controls whether a field renders as an input or read-only display. If not specified, defaults to editable (anyone who sees can edit).
-
-### Editable (who MODIFIES the field) - FRONTEND enforced
-
-| Value | Who Can Edit | Rendered As |
-|-------|--------------|-------------|
-| *(not specified)* | Anyone who sees | Input field |
-| `'admin'` | Admins only | Input (admin) / Read-only (others) |
-| `'create-only'` | On create only | Input (new) / Read-only (edit) |
-
-**Default behavior:** If `editable` is not specified, anyone who can see the field can edit it.
-
----
-
-## Entity Definition Example
-
-**Recommended:** Use `defineEntity` to define your entities. It automatically adds technical fields (`id`, `createdAt`, `updatedAt`, `createdById`, `updatedById`) with `visibility: 'technical'`. These fields can be customized (e.g., `editable: 'admin'` to make them editable for admins, custom `label`, additional `validation`) - user-defined properties are merged with defaults.
-
-Use i18n keys for labels (e.g., `'entities.car.make'`) for automatic translation support.
-
-```typescript
-// entities/car.ts
-import { defineEntity } from '@donotdev/core';
-
-export const carEntity = defineEntity({
-  name: 'Car',
-  collection: 'cars',
-  fields: {
-    // Guest-visible - everyone sees, anyone can edit
-    make: { 
-      type: 'text', 
-      label: 'entities.car.make',
-      visibility: 'guest'
-    },
-    model: { 
-      type: 'text', 
-      label: 'entities.car.model',
-      visibility: 'guest'
-    },
-    price: { 
-      type: 'number', 
-      label: 'entities.car.price',
-      visibility: 'guest'
-    },
-
-    // User-visible - authenticated users see (users see both guest and user fields)
-    description: {
-      type: 'textarea',
-      label: 'entities.car.description',
-      visibility: 'user'
-    },
-    ownerNotes: {
-      type: 'textarea',
-      label: 'entities.car.ownerNotes',
-      visibility: 'user'
-    },
-
-    // Select/Combobox fields - options go in validation.options
-    make: {
-      type: 'combobox',
-      label: 'entities.car.make',
-      visibility: 'guest',
-      validation: {
-        required: true,
-        options: [
-          { value: 'Toyota', label: 'Toyota' },
-          { value: 'Honda', label: 'Honda' },
-          { value: 'Ford', label: 'Ford' }
-        ]
-      }
-    },
-    fuelType: {
-      type: 'select',
-      label: 'entities.car.fuelType',
-      visibility: 'guest',
-      validation: {
-        required: true,
-        options: [
-          { value: 'Petrol', label: 'Petrol' },
-          { value: 'Diesel', label: 'Diesel' },
-          { value: 'Electric', label: 'Electric' }
-        ]
-      }
-    },
-    // Status: framework provides draft/available/deleted, we add custom options
-    status: {
-      label: 'entities.car.status',
-      validation: {
-        options: [
-          { value: 'reserved', label: 'reserved' },
-          { value: 'sold', label: 'sold' }
-        ]
-      }
-    },
-    // Result: ['draft', 'available', 'deleted', 'reserved', 'sold']
-
-    // Admin-only - only admins see and edit
-    vin: { 
-      type: 'text', 
-      label: 'entities.car.vin',
-      visibility: 'admin',
-      editable: 'admin'
-    },
-    purchasePrice: { 
-      type: 'number', 
-      label: 'entities.car.purchasePrice',
-      visibility: 'admin',
-      editable: 'admin'
-    },
-    supplier: { 
-      type: 'text', 
-      label: 'entities.car.supplier',
-      visibility: 'admin',
-      editable: 'admin'
-    },
-    
-    // Hidden fields - never shown in UI, only in DB (passwords, tokens, API keys)
-    // apiKey: {
-    //   type: 'text',
-    //   visibility: 'hidden',
-    //   validation: { required: false }
-    // },
-    
-    // Technical fields (id, createdAt, updatedAt, createdById, updatedById) 
-    // are automatically added by defineEntity with visibility: 'technical'
-    // Shown as read-only in edit forms (admins only) by default, never in create forms
-    // Can be customized: createdAt: { editable: 'admin', label: 'Created Date' }
-  }
-});
-```
-
-**Note:** Technical fields are automatically added by `defineEntity`. They're shown as read-only in edit forms (for admins) by default, but can be customized (e.g., `editable: 'admin'` to make editable). They're never shown in create forms. Hidden fields (passwords, tokens) are never shown in any UI.
-
-### Core Types Reference
-
-The framework uses a type-safe system for field definitions. Understanding these types helps when working with entities:
-
-**EntityField<T>** - Field definition with type parameter:
-```typescript
-interface EntityField<T extends FieldType = FieldType> {
-  type: T;                    // Field type ('text', 'number', etc.)
-  visibility: Visibility;     // 'guest' | 'user' | 'admin' | 'technical' | 'hidden'
-  editable?: Editable;        // true | false | 'admin' | 'create-only'
-  validation?: ValidationRules<T>;  // Type-safe validation rules
-  label?: string;             // Display label
-  hint?: string;              // Helper text
-  // ... other optional properties
-}
-```
-
-**FieldType** - Union of all supported field types:
-```typescript
-type FieldType = 
-  | 'text' | 'textarea' | 'email' | 'password' | 'url' | 'tel'
-  | 'number' | 'range' | 'boolean' | 'checkbox'
-  | 'date' | 'datetime-local' | 'time' | 'timestamp'
-  | 'select' | 'multiselect' | 'radio' | 'combobox'
-  | 'file' | 'image' | 'images' | 'reference'
-  | 'geopoint' | 'address' | 'map' | 'array'
-  | ... // See full list in Built-in Field Types Reference below
-```
-
-**FieldTypeToValue** - Maps field types to their TypeScript value types:
-```typescript
-type FieldTypeToValue = {
-  text: string;
-  email: string;
-  number: number;
-  boolean: boolean;
-  date: string;                    // ISO string
-  select: string;
-  multiselect: string[];
-  image: Picture | null;
-  images: Picture[];
-  geopoint: { lat: number; lng: number };
-  // ... complete mapping
-};
-```
-
-**ValueTypeForField<T>** - Helper to get value type for a field type:
-```typescript
-type ValueTypeForField<T extends FieldType> = FieldTypeToValue[T];
-
-// Usage examples:
-type EmailValue = ValueTypeForField<'email'>;  // string
-type GeoValue = ValueTypeForField<'geopoint'>; // { lat: number; lng: number }
-type ImageValue = ValueTypeForField<'image'>;  // Picture | null
-```
-
-**InferEntityData<E>** - Infers data type from entity definition:
-```typescript
-import type { InferEntityData } from '@donotdev/crud';
-
-type CarData = InferEntityData<typeof carEntity>;
-// Infers: { 
-//   make: string; 
-//   model: string; 
-//   price: number;
-//   id: string;
-//   createdAt: string;
-//   ... 
-// }
-```
-
-**Type Safety Benefits:**
-- TypeScript knows the value type for each field
-- Validation rules are type-checked (e.g., `minLength` only on text fields)
-- Form components receive correctly typed props
-- Entity data types are automatically inferred
-
-### Entity Labels (i18n)
-
-**Framework auto-discovers entity label files** - no configuration needed.
-
-**File format:** `entity-<name>_<lang>.json` in `src/locales/` (eager) or `src/pages/locales/` (lazy)
-
-**Example:**
-```json
-// src/locales/entity-car_en.json
-{
-  "make": "Make",
-  "model": "Model",
-  "price": "Price",
-  "fuelType": "Fuel Type",
-  "status": "Status"
-}
-```
-
-**Usage in entity definition:**
-```typescript
-export const carEntity = defineEntity({
-  name: 'Car',  // Framework uses this to find entity-car_*.json files
-  collection: 'cars',
-  fields: {
-    make: {
-      type: 'combobox',
-      visibility: 'guest',
-      // Label is just the field name - framework looks up "car.make" in entity-car_*.json
-      label: 'make',
-      validation: { required: true, options: [...] }
-    }
-  }
-});
-```
-
-**How it works:**
-- Entity name `'Car'` → namespace `'car'` (lowercase)
-- Field label `'make'` → looks up `car.make` in `entity-car_<lang>.json`
-- If file not found, falls back to `dndev` namespace
-- Framework auto-discovers `entity_*_*.json` files
-
-### Field Types with Options
-
-For `select`, `combobox`, `multiselect`, and `radio` fields, **options must be placed in `validation.options`**:
-
-```typescript
-make: {
-  type: 'combobox',  // or 'select', 'multiselect', 'radio'
-  visibility: 'guest',
-  validation: {
-    required: true,
-    // ✅ CORRECT: options go inside validation
-    options: [
-      { value: 'Toyota', label: 'Toyota' },
-      { value: 'Honda', label: 'Honda' }
-    ]
-  }
-}
-```
-
-**Format:** Options must be an array of `{ value: string, label: string }` objects. Labels can use i18n keys for translation.
-
-### Field-Specific Options
-
-Some field types support additional options via the `options` property:
-
-#### Phone Number (`tel`) Options
-
-The `tel` field supports country code customization:
-
-```typescript
-phone: {
-  type: 'tel',
-  label: 'entities.contact.phone',
-  visibility: 'guest',
-  options: {
-    fieldSpecific: {
-      // Default country code (ISO country code, e.g., 'FR' for +33)
-      defaultCountry: 'FR',
-      
-      // Whether to show country flags in the selector
-      showFlags: true,
-      
-      // Preferred countries to show at the top of the dropdown
-      // These appear first, followed by all other common countries
-      preferredCountries: ['FR', 'BE', 'CH'],
-      
-      // OR: Restrict to only specific countries
-      // If provided, only these countries are shown (no others)
-      countries: ['FR', 'US', 'GB'],
-    }
-  }
-}
-```
-
-**Options (inside `options.fieldSpecific`):**
-- `defaultCountry` (string, optional): ISO country code for default selection (default: `'FR'`)
-- `showFlags` (boolean, optional): Show country flags in selector (default: `true`)
-- `preferredCountries` (string[], optional): Country codes to show first in dropdown
-- `countries` (string[], optional): If provided, only these countries are shown (overrides `preferredCountries`)
-
-**Examples:**
-
-```typescript
-// French app - show France, Belgium, Switzerland first
-phone: {
-  type: 'tel',
-  options: {
-    fieldSpecific: {
-      defaultCountry: 'FR',
-      preferredCountries: ['FR', 'BE', 'CH'],
-    }
-  }
-}
-
-// International app - restrict to major markets only
-phone: {
-  type: 'tel',
-  options: {
-    fieldSpecific: {
-      defaultCountry: 'US',
-      countries: ['US', 'GB', 'CA', 'AU'], // Only these 4 countries
-    }
-  }
-}
-
-// Simple usage - just set default country
-phone: {
-  type: 'tel',
-  options: {
-    fieldSpecific: {
-      defaultCountry: 'FR',
-    }
-  }
-}
-```
-
-**Note:** The phone field stores the full number with country code (e.g., `"+33 6 12 34 56 78"`). The component automatically handles country code selection and phone number input.
-
-## Usage Examples
-
-### Guest-Visible App (No Sensitive Fields)
-```typescript
-// Guest-visible car browsing - all fields visible to everyone, direct Firestore is fine
-const { data: cars, query } = useCrud('cars', { backend: 'firestore' });
-
-useEffect(() => {
-  query({ where: [{ field: 'status', operator: '==', value: 'available' }] });
-}, []);
-```
-
-### User Profile (Own Data)
-```typescript
-// User's own profile - Firestore rules enforce ownership
-const { data: profile, update } = useCrud('userProfiles', { backend: 'firestore' });
-```
-
-### Admin Panel (Mixed Visibility)
-```typescript
-// Admin sees all fields including vin, purchasePrice
-// Functions filter these for non-admins
-const { data: cars, query } = useCrud('cars', { backend: 'functions' });
-```
-
-### Using EntityFormRenderer (Quick Start)
-
-```typescript
-import { EntityFormRenderer } from '@donotdev/crud';
-import { carEntity } from '../entities/car';
-
-// Create form - excludes technical and hidden fields automatically
-<EntityFormRenderer
-  entity={carEntity.fields}
-  operation="create"
-  onSubmit={async (data) => {
-    await createCar(data);
-  }}
-/>
-
-// Edit form - shows technical fields as read-only, excludes hidden
-<EntityFormRenderer
-  entity={carEntity.fields}
-  operation="edit"
-  defaultValues={carData} // From useCrud - already filtered by backend
-  onSubmit={async (data) => {
-    await updateCar(carId, data);
-  }}
-/>
-```
-
-**Note:** `operation` defaults to `'create'` if `defaultValues` is missing, or `'edit'` if present. Technical fields are automatically excluded from create forms and shown as read-only in edit forms.
-
-### Custom Forms with useEntityForm (Production)
-
-For custom layouts, branded forms, or complex UX, use the form building blocks:
-
-```typescript
-import { useEntityForm, useCrud } from '@donotdev/crud';
-import { carEntity } from '../entities/car';
-import { Input, Button } from './ui'; // Your components
-
-function CarForm({ carId, onSuccess }) {
-  const crud = useCrud('cars');
-  const [carData, setCarData] = useState(null);
-
-  useEffect(() => {
-    if (carId) crud.get(carId).then(setCarData);
-  }, [carId]);
-
-  const form = useEntityForm(carEntity, {
-    operation: carId ? 'edit' : 'create',
-    defaultValues: carData,
-    viewerRole: 'admin'
-  });
-
-  const onSubmit = async (data) => {
-    if (carId) {
-      await crud.update(carId, data);
-    } else {
-      await crud.add(data);
-    }
-    onSuccess();
-  };
-
-  return (
-    <form onSubmit={form.handleSubmit(onSubmit)}>
-      {/* Custom 2-column layout */}
-      <div className="grid grid-cols-2 gap-4">
-        {form.fields.map(({ name, config, editable }) => (
-          <Input
-            key={name}
-            label={config.label}
-            {...form.register(name)}
-            disabled={!editable}
-            error={form.formState.errors[name]?.message}
-          />
-        ))}
-      </div>
-      <Button type="submit" loading={form.formState.isSubmitting}>
-        {form.operation === 'create' ? 'Create' : 'Update'}
-      </Button>
-    </form>
-  );
-}
-```
-
-### When to Use What
-
-| Use Case | Solution |
-|----------|----------|
-| Admin panels, internal tools | `EntityFormRenderer` |
-| Custom layouts, branded forms | `useEntityForm` + your components |
-| Complex conditional logic | `useEntityField` for granular control |
-
-### Available Building Blocks
-
-```typescript
-import {
-  // High-level
-  EntityFormRenderer,      // Zero-config form rendering
-
-  // Hooks for custom forms
-  useEntityForm,           // Main form hook (wraps React Hook Form)
-  useEntityField,          // Single field control
-
-  // Utilities
-  getFieldsForOperation,   // Filter fields by operation/visibility
-  createEntitySchema,      // Generate Valibot schema
-  validateEntity,          // Standalone validation
-} from '@donotdev/crud';
-```
-
----
-
-## Backend Security Comparison
-
-| Aspect | `firestore` | `functions` |
-|--------|-------------|-------------|
-| Auth check | Firestore rules | Function + rules |
-| Field filtering | No | Yes (by role) |
-| Network exposure | All fields | Only visible fields |
-| Latency | Direct | +50-100ms (cold start) |
-| Cost | Reads only | Reads + invocation |
-
----
-
-## Cloud Functions Setup
-
-For `backend: 'functions'`, deploy CRUD functions. **Recommended:** Generate schemas from your entity definition using the framework's schema generation utilities.
-
-### Firebase Functions
-
-```typescript
-// functions/src/crud/cars.ts
-import { getEntity, listEntities, createEntity, updateEntity, deleteEntity } from '@donotdev/functions/firebase';
-import { carEntity } from '../../../entities/car';
-import { createSchemas } from '@donotdev/core/schemas';
-
-// Generate schemas from entity definition
-const schemas = createSchemas(carEntity);
-const carSchema = schemas.GetCarSchema; // User-visible fields
-const carAdminSchema = schemas.GetCarAdminSchema; // All fields (admin)
-
-export const getCar = getEntity('cars', carSchema);
-export const listCars = listEntities('cars', carSchema);
-export const createCar = createEntity('cars', carSchema);
-export const updateCar = updateEntity('cars', carSchema);
-export const deleteCar = deleteEntity('cars', carSchema);
-```
-
-### Vercel API Routes
-
-For Next.js apps, create API route handlers that wrap the framework functions:
-
-```typescript
-// pages/api/crud/cars/[id].ts (Pages Router)
-import type { NextApiRequest, NextApiResponse } from 'next';
-import { getEntity as frameworkGetEntity } from '@donotdev/functions/vercel';
-
-export default async function handler(
-  req: NextApiRequest,
-  res: NextApiResponse
-) {
-  return frameworkGetEntity(req, res);
-}
-```
-
-**Note:** Vercel functions are Next.js API route handlers, while Firebase uses callable functions. Both support the same schema-based field filtering. The framework handles schema validation and field filtering automatically. See the framework templates (`packages/cli/templates/functions-vercel`) for complete examples.
-
----
-
-## Summary
-
-| Data Type | Backend | Why |
-|-----------|---------|-----|
-| User's own profile | `firestore` | Rules enforce ownership |
-| Public listings | `firestore` | No sensitive fields |
-| Admin panel data | `functions` | Field filtering needed |
-| Multi-role data | `functions` | Different visibility per role |
-
-**Rule of thumb:** If data has `visibility: 'admin'` fields, use `backend: 'functions'`.
-
----
-
-## Analytics & Aggregations
-
-For dashboards and analytics, use `aggregateEntities` instead of fetching all data.
-
-### Why Use Backend Analytics?
-
-| Approach | Data Transfer | Security | Scale |
-|----------|--------------|----------|-------|
-| Frontend (useMemo) | ~500KB (all data) | Raw data in network tab | <500 items |
-| Backend (aggregateEntities) | ~5KB (metrics only) | Only aggregates sent | 10,000+ items |
-
-### aggregateEntities Function
-
-Returns **only computed metrics**, never raw data.
-
-```typescript
-// functions/src/analytics/getCarsAnalytics.ts
-import { aggregateEntities } from '@donotdev/functions/firebase';
-import { carSchema } from '../schemas';
-
-export const getCarsAnalytics = aggregateEntities('cars', carSchema, {
-  // Top-level metrics
-  metrics: [
-    { field: '*', operation: 'count', as: 'total' },
-    { field: 'price', operation: 'sum', as: 'totalValue' },
-    { field: 'price', operation: 'avg', as: 'avgPrice' },
-    // Admin-only field - visibility check enforced
-    { field: 'purchasePrice', operation: 'sum', as: 'totalCost' },
-  ],
-  // Group by field values
-  groupBy: [
-    {
-      field: 'status',
-      metrics: [
-        { field: '*', operation: 'count', as: 'count' },
-        { field: 'price', operation: 'sum', as: 'value' },
-      ],
-    },
-  ],
-});
-```
-
-### Supported Operations
-
-| Operation | Description | Example |
-|-----------|-------------|---------|
-| `count` | Count documents | `{ field: '*', operation: 'count', as: 'total' }` |
-| `sum` | Sum numeric field | `{ field: 'price', operation: 'sum', as: 'revenue' }` |
-| `avg` | Average | `{ field: 'price', operation: 'avg', as: 'avgPrice' }` |
-| `min` | Minimum value | `{ field: 'price', operation: 'min', as: 'cheapest' }` |
-| `max` | Maximum value | `{ field: 'price', operation: 'max', as: 'mostExpensive' }` |
-
-### Filtered Metrics
-
-Apply filters to specific metrics:
-
-```typescript
-metrics: [
-  // Count only sold cars
-  {
-    field: '*',
-    operation: 'count',
-    as: 'soldCount',
-    filter: { field: 'status', operator: '==', value: 'Sold' },
-  },
-  // Revenue from sold cars only
-  {
-    field: 'price',
-    operation: 'sum',
-    as: 'revenue',
-    filter: { field: 'status', operator: '==', value: 'Sold' },
-  },
-]
-```
-
-### Response Format
-
-```typescript
-{
-  metrics: {
-    total: 150,
-    totalValue: 4500000,
-    avgPrice: 30000,
-  },
-  groups: {
-    status: {
-      Available: { count: 80, value: 2400000 },
-      Reserved: { count: 20, value: 600000 },
-      Sold: { count: 50, value: 1500000 },
-    }
-  },
-  meta: {
-    collection: 'cars',
-    totalDocs: 150,
-    computedAt: '2024-01-15T10:30:00Z'
-  }
-}
-```
-
-### Visibility Protection
-
-`aggregateEntities` enforces field visibility:
-- Admin-only fields can only be aggregated by admins
-- Non-admins attempting to aggregate `visibility: 'admin'` fields get `permission-denied`
-
-### When NOT to Use aggregateEntities
-
-Use custom functions for:
-- **Cross-collection relationships** (e.g., "people to call" requires joining customers + inquiries)
-- **Complex computed fields** (e.g., profit = revenue - cost - repairs)
-- **Time-based logic** (e.g., "older than 30 days")
-
-```typescript
-import { onCall } from 'firebase-functions/v2/https';
-import { FUNCTION_CONFIG } from '@donotdev/functions/firebase';
-// ⚠️ CRITICAL: Functions MUST use /server imports
-import { getFirebaseAdminFirestore } from '@donotdev/firebase/server';
-import { handleError } from '@donotdev/core/server';
-
-// Custom function for complex cross-collection logic
-// Use FUNCTION_CONFIG to enable CORS automatically
-export const getDashboardMetrics = onCall(FUNCTION_CONFIG, async (request) => {
-  const firestore = getFirebaseAdminFirestore();
-  
-  // Fetch from multiple collections
-  // Apply custom business logic
-  // Return computed metrics
-});
-```
-
-**⚠️ IMPORTANT:** In functions, always use `@donotdev/firebase/server` (not `@donotdev/firebase`). Client imports will crash your function on deploy.
-
----
-
-**Choose the right backend. Define visibility. Framework handles the rest.**
-
----
-
-## Custom Field Types
-
-The framework provides 30+ built-in field types. For domain-specific needs, you can register custom field types.
-
-### When to Create Custom Fields
-
-| Scenario | Solution |
-|----------|----------|
-| Standard input (text, number, date) | Use built-in types |
-| Special formatting (currency, VIN) | Custom field type |
-| Domain component (rating widget) | Custom field type |
-| Complex data (address picker) | Custom field type |
-
-### Registering a Custom Field Type
-
-**Framework provides `field` and `fieldState`** - No need to import `useController` or `Controller` from react-hook-form.
-
-Custom fields need three things:
-1. **Controlled component** - For react-hook-form integration
-2. **Uncontrolled component** (optional) - For standalone use
-3. **Schema generator** - For Valibot validation
-
-```typescript
-// lib/fields/currencyField.ts
-import { registerFieldType, type ControlledFieldProps } from '@donotdev/crud';
-import * as v from 'valibot';
-import { CurrencyInput } from '../components/CurrencyInput';
-
-// 1. Create the controlled component wrapper
-function ControlledCurrencyField({
-  fieldConfig,
-  field,        // ✅ Provided by framework - no need to use useController
-  fieldState,   // ✅ Provided by framework - no need to use useController
-  errors,
-  t,
-  onChange
-}: ControlledFieldProps) {
-  const { label, validation } = fieldConfig;
-
-  // Use field.value and field.onChange directly - framework handles react-hook-form integration
-  return (
-    <CurrencyInput
-      label={t(label)}
-      value={field?.value || 0}
-      onChange={(value) => {
-        field?.onChange(value);
-        onChange?.(value);
-      }}
-      error={fieldState?.error?.message || errors[fieldConfig.name]?.message}
-      currency={validation?.currency || 'USD'}
-    />
-  );
-}
-
-// 2. Register the field type
-registerFieldType({
-  type: 'currency', // Your custom type name
-  controlledComponent: ControlledCurrencyField,
-  // Optional: uncontrolled component for non-form use
-  // uncontrolledComponent: CurrencyDisplay,
-  schemaGenerator: (field) => {
-    // Generate Valibot schema based on field config
-    const schema = v.pipe(
-      v.number(),
-      v.minValue(field.validation?.min ?? 0)
-    );
-    return field.validation?.required
-      ? schema
-      : v.optional(schema);
-  }
-});
-```
-
-### Complex Custom Fields
-
-For arrays or nested data, use `field` and `fieldState` directly:
-
-```typescript
-import { Text } from '@donotdev/components';
-
-function ControlledRepairOperationsField({
-  fieldConfig,
-  field,        // ✅ Framework provides - use field.value, field.onChange
-  fieldState,   // ✅ Framework provides - use fieldState.error
-  t
-}: ControlledFieldProps) {
-  const value = (field?.value || []) as RepairOperation[];
-  
-  return (
-    <div>
-      {/* Field label - use Text with level="body" and align="start" for non-floating labels */}
-      <Text level="body" align="start">
-        {t(fieldConfig.label)}
-        {fieldConfig.validation?.required && (
-          <span style={{ color: 'var(--destructive-foreground)', marginInlineStart: 'var(--gap-tight)' }}>*</span>
-        )}
-      </Text>
-      
-      {/* Your custom UI */}
-      <Button onClick={() => field?.onChange([...value, { operation: '', cost: 0 }])}>
-        {t('add')}
-      </Button>
-      
-      {/* Helper/error text - use Text with level="small" */}
-      {fieldState?.error && (
-        <Text variant="destructive" level="small">
-          {fieldState.error.message}
-        </Text>
-      )}
-    </div>
-  );
-}
-```
-
-**Text Component Guidelines:**
-
-**Label Typography:**
-- **FloatingLabels** (Input, Textarea, etc.): Framework handles automatically using `--font-size-xs` (12px) internally. You don't need to style these.
-- **Non-floating labels** (ImageField, SwitchField, custom fields): Use `<Text level="body" align="start">` to match framework style (16px, same as input text)
-  - Required asterisk: Add automatically with `<span style={{ color: 'var(--destructive-foreground)', marginInlineStart: 'var(--gap-tight)' }}>*</span>`
-  - **Don't use:** `<Label>` component - it has hover state which is inappropriate for field labels
-
-**Helper/Error Text:**
-- **Helper text:** Use `<Text level="small" variant="muted">` (14px)
-- **Error messages:** Use `<Text level="small" variant="destructive">` (14px)
-
-**Framework Text Levels:**
-- `level="small"` → 14px (`--font-size-sm`)
-- `level="body"` → 16px (`--font-size-base`, default)
-- `level="h1"`-`"h4"` → Larger headings
-
-**Don't use:** `--font-size-xs` in inline styles - use `Text` with `level="small"` instead
-
-### Using Custom Fields in Entities
-
-After registration, use your custom type like built-in types:
-
-```typescript
-// entities/product.ts
-import { defineEntity } from '@donotdev/core';
-import '../lib/fields/currencyField'; // Import to register
-import '../lib/fields/repairOperationsField'; // Import to register
-
-export const productEntity = defineEntity({
-  name: 'Product',
-  collection: 'products',
-  fields: {
-    name: { type: 'text', visibility: 'guest' },
-    // Simple custom type
-    price: {
-      type: 'currency',      // Your custom type
-      visibility: 'guest',
-      validation: {
-        required: true,
-        min: 0,
-        currency: 'USD'      // Custom validation option
-      }
-    },
-    // Complex custom type with arrays
-    repairs: {
-      type: 'repairOperations',
-      visibility: 'admin',
-      validation: { required: false }
-    }
-  }
-});
-```
-
-### Type Safety for Custom Fields
-
-To get full TypeScript support for custom field types:
-
-```typescript
-// types/fields.d.ts
-import '@donotdev/types';
-
-declare module '@donotdev/types' {
-  interface FieldTypeToValue {
-    // Add your custom type's value type
-    currency: number;
-  }
-
-  interface ValidationRulesExtension {
-    // Add custom validation options
-    currency?: string;
-  }
-}
-```
-
-### Registration Timing
-
-Register custom fields **before** using them in forms:
-
-```typescript
-// app/providers.tsx (Next.js App Router)
-'use client';
-import '../lib/fields/currencyField';
-import '../lib/fields/ratingField';
-// ... other custom fields
-
-export function Providers({ children }) {
-  return <>{children}</>;
-}
-
-// app/layout.tsx
-import { Providers } from './providers';
-
-export default function RootLayout({ children }) {
-  return <Providers>{children}</Providers>;
-}
-```
-
-### Built-in Field Types Reference
-
-| Type | Value | Use Case |
-|------|-------|----------|
-| `text` | string | Short text, names |
-| `textarea` | string | Long text, descriptions |
-| `email` | string | Email addresses |
-| `password` | string | Password input |
-| `url` | string | URLs |
-| `tel` | string | Phone numbers (with country code selector) |
-| `number` | number | Numeric input |
-| `range` | number | Slider input |
-| `boolean` | boolean | Yes/no switch |
-| `checkbox` | boolean | Checkbox |
-| `switch` | boolean | Toggle switch |
-| `date` | string | Date picker (ISO) |
-| `datetime-local` | string | DateTime picker |
-| `time` | string | Time picker |
-| `timestamp` | Timestamp | Firestore timestamp |
-| `select` | string | Dropdown single |
-| `multiselect` | string[] | Dropdown multi |
-| `radio` | string | Radio buttons |
-| `combobox` | string | Searchable dropdown |
-| `file` | File \| null | File upload |
-| `image` | Picture \| null | Image upload (single) |
-| `images` | Picture[] | Image upload (multiple) |
-| `reference` | string | Doc reference |
-| `geopoint` | GeoPoint | Map coordinates |
-| `address` | AddressValue | Address picker |
-| `map` | object | Key-value pairs |
-| `color` | string | Color picker |
-| `array` | unknown[] | Array of values |
-
----
-
-**Custom fields follow the same Entity → Schema → UI flow. Register once, use everywhere.**
-
----
-
-## Status Field & Workflows
-
-The `status` field enables draft saves, soft delete, and custom workflows.
-
-### Framework Support
-
-The `status` field is **auto-added** by `defineEntity()` with:
-- `visibility: 'admin'` (visible in admin forms)
-- Default value: `'available'` (new documents are published by default)
-- Options: `['draft', 'available', 'deleted']`
-
-| Behavior | Description |
-|----------|-------------|
-| **Default status** | New documents default to `'available'` (published) |
-| **Draft saves** | Set status to `'draft'` to save incomplete data |
-| **Soft delete** | Set status to `'deleted'` instead of hard delete |
-| **Server filtering** | `draft` and `deleted` hidden from non-admin (never in network tab) |
-| **Publish validation** | Full `required` validation when status !== `'draft'` |
-| **Hide field** | Set `visibility: 'technical'` if you don't want it in forms |
-
-### Basic Usage (No Config Needed)
-
-```typescript
-// entities/car.ts
-export const carEntity = defineEntity({
-  name: 'Car',
-  collection: 'cars',
-  fields: {
-    // Required fields - only enforced when status !== 'draft'
-    make: { type: 'combobox', label: 'make', visibility: 'guest', validation: { required: true } },
-    model: { type: 'text', label: 'model', visibility: 'guest', validation: { required: true } },
-    price: { type: 'number', label: 'price', visibility: 'guest', validation: { required: true } },
-    // Optional fields
-    notes: { type: 'textarea', label: 'notes', visibility: 'user' },
-    // status is auto-added with options: ['draft', 'available', 'deleted']
-  }
-});
-```
-
-**Behavior:**
-- New documents default to `status: 'available'` (published)
-- Set `status: 'draft'` to save incomplete data (`required` validation skipped)
-- Set `status: 'deleted'` for soft delete
-- Public queries → `draft` and `deleted` filtered out automatically
-
-### Extending Status Options
-
-Add custom statuses while keeping framework defaults:
-
-```typescript
-export const carEntity = defineEntity({
-  name: 'Car',
-  collection: 'cars',
-  fields: {
-    make: { type: 'text', visibility: 'guest', validation: { required: true } },
-    // Extend status options
-    status: {
-      validation: {
-        options: [
-          { value: 'reserved', label: 'reserved' },
-          { value: 'sold', label: 'sold' },
-        ]
-      }
-    }
-  }
-});
-// Result: ['draft', 'available', 'deleted', 'reserved', 'sold']
-```
-
-### Hiding the Status Field
-
-If you don't want the status field visible in forms:
-
-```typescript
-export const carEntity = defineEntity({
-  name: 'Car',
-  collection: 'cars',
-  fields: {
-    make: { type: 'text', visibility: 'guest', validation: { required: true } },
-    // Hide status field from forms
-    status: { visibility: 'technical' }
-  }
-});
-// Field still exists in DB, just hidden from UI
-```
-
-### Form Integration
-
-```typescript
-function CarForm({ carId, defaultValues, onSave }) {
-  const form = useEntityForm(carEntity, {
-    operation: carId ? 'edit' : 'create',
-    // Override framework default ('available') to start as draft
-    defaultValues: { status: 'draft', ...defaultValues },
-  });
-
-  const status = form.watch('status');
-  const isDraft = status === 'draft';
-
-  return (
-    <form onSubmit={form.handleSubmit(onSave)}>
-      <EntityFormRenderer entity={carEntity} form={form} />
-
-      <div className="flex gap-2">
-        {/* Save as draft (skip validation) */}
-        <Button
-          type="button"
-          variant="outline"
-          onClick={() => {
-            form.setValue('status', 'draft');
-            form.handleSubmit(onSave)();
-          }}
-        >
-          Save Draft
-        </Button>
-
-        {/* Publish (full validation) */}
-        <Button
-          type="button"
-          onClick={() => {
-            form.setValue('status', 'available');
-            form.handleSubmit(onSave)();
-          }}
-        >
-          {isDraft ? 'Publish' : 'Save'}
-        </Button>
-      </div>
-    </form>
-  );
-}
-```
-
-### Optional: Custom Publish Validation
-
-For additional requirements beyond entity `required` fields (e.g., min images, specific formats):
-
-```typescript
-// lib/schemas/carPublishSchema.ts
-import * as v from 'valibot';
-
-export const carPublishSchema = v.object({
-  images: v.pipe(v.array(v.any()), v.minLength(1, 'At least one image required')),
-  year: v.pipe(v.number(), v.minValue(1900, 'Year must be 1900 or later')),
-});
-
-export function canPublish(data: Record<string, unknown>): boolean {
-  return v.safeParse(carPublishSchema, data).success;
-}
-```
-
-### Admin Panel: Show All Statuses
-
-Admin queries include drafts and deleted documents. Add badges for visibility:
-
-```typescript
-// Admin list shows all including drafts and deleted
-const { data: allCars } = useCrud(carEntity);
-
-// Status badges
-{car.status === 'draft' && <Badge variant="outline">Draft</Badge>}
-{car.status === 'deleted' && <Badge variant="destructive">Deleted</Badge>}
-```
-
-### Soft Delete
-
-Use status instead of hard delete:
-
-```typescript
-const { update } = useCrud(carEntity);
-
-// Soft delete
-await update(carId, { status: 'deleted' });
-
-// Restore
-await update(carId, { status: 'available' });
-```
-
-### Summary
-
-| Concern | Handled By |
-|---------|------------|
-| Default status | Framework (`'available'` - published by default) |
-| Save incomplete data | Consumer sets `status: 'draft'` (validation skipped) |
-| Soft delete | Consumer sets `status: 'deleted'` |
-| Hide draft/deleted | Framework (server-side filtering for non-admin) |
-| Publish validation | Framework (`required` enforced when status !== 'draft') |
-| Custom statuses | Consumer extends options in entity definition |
-| Hide status field | Consumer sets `visibility: 'technical'` |
-
-**Status field is visible by default.** Consumer controls workflow via status values.