@donotdev/cli 0.0.6 → 0.0.8

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

@@ -0,0 +1,539 @@
+# Setup: CRUD Operations
+
+**CRUD = Create, Read, Update, Delete.** Framework handles data ops with built-in security.
+
+---
+
+## 1. Define Entity
+
+```typescript
+// entities/product.ts
+import { defineEntity } from '@donotdev/core';
+
+export const productEntity = defineEntity({
+  name: 'Product',
+  collection: 'products',
+  // namespace: 'entity-product', // Optional: defaults to entity-${name.toLowerCase()}
+  fields: {
+    name: {
+      name: 'name',
+      label: 'name',
+      type: 'text',
+      visibility: 'guest',
+      validation: { required: true }
+    },
+    price: {
+      name: 'price',
+      label: 'price',
+      type: 'number',
+      visibility: 'guest',
+      validation: { required: true }
+    },
+    image: {
+      name: 'image',
+      label: 'image',
+      type: 'image',
+      visibility: 'guest'
+    },
+    customerContact: {
+      name: 'customerContact',
+      label: 'customerContact',
+      type: 'email',
+      visibility: 'admin',
+      editable: 'admin'
+    }
+  }
+});
+```
+
+**Auto-added fields:** `id`, `createdAt`, `updatedAt`, `createdById`, `updatedById`, `status`
+
+---
+
+## 2. Visibility & Access
+
+### Field Visibility (who SEES)
+| Level | Who |
+|-------|-----|
+| `'guest'` | Everyone |
+| `'user'` | Authenticated |
+| `'admin'` | Admins |
+| `'super'` | Super admins |
+| `'hidden'` | Never |
+
+### Entity Access (who CAN DO)
+```typescript
+access: {
+  create: 'admin',  // default
+  read: 'guest',    // default  
+  update: 'admin',  // default
+  delete: 'admin',  // default
+}
+```
+
+**Override:**
+```typescript
+// Contact form - guests submit, admins read
+access: { create: 'guest', read: 'admin' }
+```
+
+---
+
+## 3. Register Functions (Backend)
+
+```typescript
+// functions/src/index.ts
+import { initializeApp } from 'firebase-admin/app';
+import { createCrudFunctions } from '@donotdev/functions/firebase';
+import * as entities from 'entities';
+
+initializeApp();
+export const crud = createCrudFunctions(entities);
+```
+
+**Deploy:** `dndev deploy`
+
+---
+
+## 4. Frontend Usage
+
+### Create/Edit Page
+
+```tsx
+import { EntityFormRenderer, useCrud } from '@donotdev/crud';
+import { productEntity } from 'entities';
+
+export default function ProductPage() {
+  const { id } = useParams<{ id: string }>();
+  const { add, update, get } = useCrud(productEntity);
+  const isNew = id === 'new';
+  const [data, setData] = useState<any>(null);
+
+  useEffect(() => {
+    if (!isNew && id) get(id).then(setData);
+  }, [id]);
+
+  const handleSubmit = async (formData: any) => {
+    isNew ? await add(formData) : await update(id!, formData);
+    navigate('/products');
+  };
+
+  // DON'T mount form until data ready (edit mode)
+  if (!isNew && !data) return <Spinner />;
+
+  return (
+    <EntityFormRenderer
+      entity={productEntity}
+      operation={isNew ? 'create' : 'edit'}
+      defaultValues={data}
+      onSubmit={handleSubmit}
+    />
+  );
+}
+```
+
+### List Page
+
+```tsx
+import { EntityList } from '@donotdev/crud';
+import { useAuth } from '@donotdev/auth';
+import { PageContainer, useNavigate } from '@donotdev/ui';
+import { productEntity } from 'entities';
+
+export default function ProductsPage() {
+  const user = useAuth('user');
+  const navigate = useNavigate();
+
+  return (
+    <PageContainer>
+      <EntityList
+        entity={productEntity}
+        userRole={user?.role}
+        // Required: Edit handler - navigates to edit page when edit button clicked
+        onEdit={(id) => navigate(`/products/${id}`)}
+        // Optional: Create handler - navigates to create page when "Add New" clicked
+        onCreate={() => navigate('/products/new')}
+        // Optional: View handler - called when row is clicked
+        onView={(id) => navigate(`/products/${id}`)}
+      />
+    </PageContainer>
+  );
+}
+```
+
+**Props:**
+- `onEdit` **(required)** - Function `(id: string) => void` called when edit button is clicked. Typically navigates to `/${collection}/${id}` (e.g., `/products/${id}`).
+- `onCreate` **(optional)** - Function `() => void` called when "Add New" button is clicked. Typically navigates to `/${collection}/new`.
+- `onView` **(optional)** - Function `(id: string) => void` called when a table row is clicked. Useful for view-only pages or detail navigation.
+- `userRole` **(optional)** - Current user role for field visibility filtering (backend still enforces security).
+
+**Routing Convention:**
+- Default edit route: `/${entity.collection}/${id}` (e.g., `/products/abc123`)
+- You must create a page at `/${collection}/:id` route to handle the edit page
+
+### Card Grid
+
+```tsx
+import { EntityCardList } from '@donotdev/crud';
+import { PageContainer, useNavigate } from '@donotdev/ui';
+import { productEntity } from 'entities';
+
+export default function ShopPage() {
+  const navigate = useNavigate();
+
+  return (
+    <PageContainer>
+      <EntityCardList
+        entity={productEntity}
+        // Required: View handler - called when card is clicked
+        onView={(id) => navigate(`/products/${id}`)}
+      />
+    </PageContainer>
+  );
+}
+```
+
+**Props:**
+- `onView` **(required)** - Function `(id: string) => void` called when a card is clicked. Typically navigates to `/${collection}/${id}` (e.g., `/products/${id}`).
+- `cols` **(optional)** - Responsive column breakpoints `[mobile, tablet, desktop, wide]` (default: `[1, 2, 3, 4]`).
+- `staleTime` **(optional)** - Cache stale time in milliseconds (default: 30 minutes).
+- `filter` **(optional)** - Filter function `(item: any) => boolean` to filter items client-side.
+- `hideFilters` **(optional)** - Hide filters section (default: `false`).
+
+---
+
+## 5. Field Types
+
+### 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
+- `year` - Year input (combobox: type or select from dropdown)
+
+### 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 (deferred: uploads on form submit)
+- `files` - Multiple file uploads (deferred: uploads on form submit)
+- `document` - Document upload (PDF, etc.) (deferred: uploads on form submit)
+- `documents` - Multiple document uploads (deferred: uploads on form submit)
+- `image` - Single image upload (deferred: uploads on form submit, optimistic UI updates)
+- `images` - Multiple image uploads (deferred: uploads on form submit, optimistic UI updates)
+
+**Note:** File uploads use deferred uploads when inside `EntityFormRenderer` - files upload to storage when you submit the form. Images show immediately with optimistic updates (blob URLs) and automatically replace with storage URLs after upload completes.
+
+### 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)
+
+### Select Options
+
+```typescript
+category: {
+  type: 'select',
+  validation: {
+    options: [
+      { value: 'electronics', label: 'Electronics' },
+      { value: 'clothing', label: 'Clothing' }
+    ]
+  }
+}
+```
+
+### Year Field
+
+Use `type: 'year'` for year inputs (combobox with type-or-select UX):
+
+```typescript
+year: {
+  type: 'year',
+  validation: { 
+    required: true,
+    min: 1900,  // Optional: defaults to 1900
+    max: 2100   // Optional: defaults to current year + 10
+  }
+}
+```
+
+### Switch with Custom Values
+
+```typescript
+transmission: {
+  type: 'switch',
+  options: {
+    fieldSpecific: {
+      uncheckedValue: 'Manual',
+      checkedValue: 'Automatic',
+    }
+  }
+}
+```
+
+---
+
+## 6. Custom Fields & Schemas
+
+### Custom Field Types with UI Components
+
+For custom field types that need custom UI components:
+
+```typescript
+import { registerFieldType, type ControlledFieldProps } from '@donotdev/crud';
+import { useController } from 'react-hook-form';
+import * as v from 'valibot';
+
+// Custom controlled component MUST use framework's useController
+import { useController, registerFieldType } from '@donotdev/crud';
+import type { ControlledFieldProps } from '@donotdev/crud';
+
+function RepairOperationsField({
+  fieldConfig,
+  control,
+  errors,
+  t,
+}: ControlledFieldProps) {
+  // REQUIRED: Use framework's useController (not react-hook-form's) - ensures type compatibility
+  const { field, fieldState } = useController({
+    name: fieldConfig.name,
+    control: control,
+  });
+
+  // Use field.value and field.onChange for form state
+  const value = (field.value as any) || [];
+  
+  return (
+    <div>
+      <label>{t(fieldConfig.label)}</label>
+      {/* Your custom UI here */}
+      {fieldState?.error && (
+        <span className="error">{fieldState.error.message}</span>
+      )}
+    </div>
+  );
+}
+
+// Register UI component
+registerFieldType({
+  type: 'repairOperations',
+  controlledComponent: RepairOperationsField,
+});
+
+// Then define schema in entity
+export const carEntity = defineEntity({
+  name: 'Car',
+  collection: 'cars',
+  fields: {
+    repairs: {
+      name: 'repairs',
+      label: 'repairs',
+      type: 'repairOperations' as any,
+      visibility: 'admin',
+      validation: {
+        required: false,
+        // Custom Valibot schema - single source of truth
+        schema: v.nullish(v.array(v.object({
+          operation: v.string(),
+          cost: v.number(),
+        })))
+      }
+    }
+  }
+});
+```
+
+**Important:** 
+- Custom controlled components receive `control` prop, NOT `field` prop
+- You MUST use `useController` hook to get `field` and `fieldState`
+- Define schema in `validation.schema` - it's the single source of truth
+
+### Custom Schemas (No Custom UI)
+
+For custom validation without custom UI, just define the schema:
+
+```typescript
+import * as v from 'valibot';
+
+export const carEntity = defineEntity({
+  name: 'Car',
+  collection: 'cars',
+  fields: {
+    // Custom array field with inline schema
+    repairs: {
+      name: 'repairs',
+      label: 'repairs',
+      type: 'text',  // Can be any type, schema takes precedence
+      visibility: 'admin',
+      validation: {
+        required: false,
+        // Custom Valibot schema - takes priority over type-based schema
+        schema: v.array(
+          v.object({
+            operation: v.string(),
+            cost: v.number(),
+            date: v.string(),  // ISO date string
+          })
+        )
+      }
+    },
+
+    // Custom object field
+    metadata: {
+      name: 'metadata',
+      label: 'metadata',
+      type: 'map',
+      visibility: 'admin',
+      validation: {
+        schema: v.object({
+          source: v.string(),
+          importedAt: v.string(),
+          tags: v.array(v.string()),
+        })
+      }
+    }
+  }
+});
+```
+
+**How It Works:**
+- `validation.schema` is the **single source of truth** - works everywhere (client + server)
+- Takes priority over built-in type schemas
+- Entity is self-contained - no separate registrations needed
+
+---
+
+## 7. Hooks API
+
+```typescript
+// Actions
+const { add, update, delete: remove, get } = useCrud(productEntity);
+
+// List (auto-fetch for tables)
+const { items, loading } = useCrudList(productEntity);
+
+// Cards (optimized for public)
+const { items, loading, loadMore } = useCrudCardList(productEntity);
+```
+
+---
+
+## 8. Custom Form Layouts
+
+Need a custom layout instead of `EntityFormRenderer`? Use `useEntityForm` directly.
+
+```tsx
+import { useId, useEffect } from 'react';
+import { useEntityForm, useCrud, UploadProvider } from '@donotdev/crud';
+import { productEntity } from 'entities';
+
+export function CustomProductForm() {
+  const formId = useId();
+  const { add } = useCrud(productEntity);
+  const {
+    control,
+    handleSubmit,
+    fields,
+    formStatus,      // 'idle' | 'uploading' | 'submitting' | ...
+    uploadProgress,  // 0-100 during uploads
+    cleanup
+  } = useEntityForm(productEntity, { formId });
+
+  useEffect(() => cleanup, [cleanup]);
+
+  return (
+    <UploadProvider formId={formId}>
+      <form onSubmit={handleSubmit(add)}>
+        {/* Your custom layout here */}
+        <Controller control={control} name="name" render={({ field }) => (
+          <input {...field} placeholder="Product name" />
+        )} />
+
+        <button type="submit" disabled={formStatus !== 'idle'}>
+          {formStatus === 'uploading' ? `Uploading ${uploadProgress}%...` : 'Save'}
+        </button>
+      </form>
+    </UploadProvider>
+  );
+}
+```
+
+**Key points:**
+- Pass `formId` to get automatic upload handling and loading states
+- Wrap with `UploadProvider` if using file/image fields
+- `handleSubmit` automatically uploads files before validation
+
+---
+
+## 9. i18n
+
+**Namespace:** Automatically set to `entity-${entity.name.toLowerCase()}` (e.g., `entity-product`)
+
+You can customize it by setting `namespace` in your entity definition:
+
+```typescript
+export const productEntity = defineEntity({
+  name: 'Product',
+  collection: 'products',
+  namespace: 'custom-namespace', // Optional: override default
+  fields: { ... }
+});
+```
+
+**Default behavior:** If not specified, the namespace is automatically set to `entity-${entity.name.toLowerCase()}`.
+
+**Translation file:** `locales/entity-product_en.json` (or your custom namespace)
+```json
+{
+  "fields": {
+    "name": "Product Name",
+    "price": "Price"
+  },
+  "name": "Product"
+}
+```
+
+Field `label` → translation key in `fields.*`
+
+---
+
+## 10. Routing Convention
+
+| Route | Purpose |
+|-------|---------|
+| `/${collection}` | List |
+| `/${collection}/new` | Create |
+| `/${collection}/:id` | Detail/Edit |

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

@@ -0,0 +1,116 @@
+# Setup: Firebase Functions
+
+**Most is pre-configured.** Functions scaffolded. Just add config and deploy.
+
+---
+
+## ⚠️ CRITICAL: Import Rules
+
+**Functions run on Node.js - you MUST use `/server` imports or your function will crash.**
+
+```typescript
+// ✅ CORRECT
+import { getFirebaseAdminFirestore } from '@donotdev/firebase/server';
+import { handleError } from '@donotdev/core/server';
+
+// ❌ WRONG - crashes on deploy
+import { getFirestore } from '@donotdev/firebase';
+import { handleError } from '@donotdev/core';
+```
+
+**Rule:** Always use `/server` suffix for:
+- `@donotdev/firebase/server`
+- `@donotdev/core/server`
+- `@donotdev/utils/server`
+
+---
+
+## CRUD Functions Setup
+
+**One line to register all entity functions:**
+
+```typescript
+// functions/src/index.ts
+import { initializeApp } from 'firebase-admin/app';
+import { createCrudFunctions } from '@donotdev/functions/firebase';
+import * as entities from 'entities';
+
+initializeApp();
+export const crud = createCrudFunctions(entities);
+```
+
+**Result:** Auto-generates `create_products`, `get_products`, `list_products`, `update_products`, `delete_products` for each entity.
+
+**Access control:** Configured via `entity.access` (see SETUP_CRUD.md). All functions use `invoker: 'public'` - security enforced via role-based access in code.
+
+---
+
+## Custom Functions
+
+**When writing custom functions, use `/server` imports:**
+
+```typescript
+import { onCall } from 'firebase-functions/v2/https';
+import { FUNCTION_CONFIG } from '@donotdev/functions/firebase';
+import { getFirebaseAdminFirestore } from '@donotdev/firebase/server';
+import { handleError } from '@donotdev/core/server';
+
+export const myFunction = onCall(FUNCTION_CONFIG, async (request) => {
+  const db = getFirebaseAdminFirestore();
+  // Your logic here
+  return { data: 'result' };
+});
+```
+
+---
+
+## Post-Deployment: Cloud Run IAM
+
+**After deploying, you may see `403 Forbidden` on CORS preflight. Fix:**
+
+```bash
+# PowerShell
+gcloud run services update create-products --region=europe-west1 --no-invoker-iam-check --project=myproject
+```
+
+**For all CRUD functions:**
+```powershell
+$services = @('create-products', 'get-products', 'list-products', 'update-products', 'delete-products');
+foreach ($service in $services) {
+  gcloud run services update $service --region=europe-west1 --no-invoker-iam-check --project=myproject
+}
+```
+
+**Why?** Cloud Run blocks unauthenticated OPTIONS (CORS preflight) by default. Your function still validates Firebase Auth - this only allows the preflight to pass.
+
+---
+
+## Function Naming
+
+**Export name (camelCase):**
+```typescript
+export const getDashboardMetrics = onCall(...);
+// Client: httpsCallable(functions, 'getDashboardMetrics')
+```
+
+**Operation ID (snake_case):**
+```typescript
+createBaseFunction(config, handler, 'get_dashboard_metrics')
+// Used for logging, rate limiting
+```
+
+---
+
+## Environment
+
+```bash
+# .env.local (local)
+STRIPE_SECRET_KEY=sk_test_...
+
+# .env (production, synced via dndev sync-secrets)
+STRIPE_SECRET_KEY=sk_live_...
+```
+
+---
+
+**Add functions, get backend. Framework handles the rest.**

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

@@ -184,4 +184,50 @@ const { languages, currentLanguage } = useLanguageSelector();
 
 ---
 
+## Advanced: Shared Entity Translations (Monorepos)
+
+**Auto-detected:** The framework automatically scans `../../entities/locales/*_*.json` for shared entity translations. If the path exists, translations are loaded; if not, nothing happens.
+
+**File naming:** `entity-car_en.json`, `entity-car_fr.json`
+
+**Merge behavior:** Base translations from shared package, app can override any key. Deep merge, app wins.
+
+**Example structure:**
+```
+monorepo/
+  entities/
+    locales/
+      entity-car_en.json    # ✅ Auto-detected - no config needed
+      entity-car_fr.json
+  apps/
+    admin/                  # ✅ Just works - framework auto-detects
+    public/                 # ✅ Just works - framework auto-detects
+```
+
+**Custom paths:** If your shared translations are in a different location, use `additionalPaths`:
+
+**Vite:**
+```ts
+// vite.config.ts
+export default defineViteConfig({
+  appConfig,
+  i18n: {
+    additionalPaths: ['../../packages/shared/locales']  // Custom path
+  }
+})
+```
+
+**Next.js:**
+```ts
+// next.config.ts
+export default defineNextConfig({
+  appConfig,
+  i18n: {
+    additionalPaths: ['../../packages/shared/locales']  // Custom path
+  }
+})
+```
+
+---
+
 **Drop files, get languages. Framework handles the rest.**