@donotdev/cli 0.0.5 → 0.0.6

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

@@ -0,0 +1,1244 @@
+# 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.