@donotdev/cli 0.0.7 → 0.0.9

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

@@ -4,6 +4,22 @@
 
 ---
 
+## Quick Import Reference
+
+| What | Package |
+|------|---------|
+| **Hooks** (`useCrud`, `useCrudList`, `useCrudCardList`, `useEntityForm`, `useEntityFavorites`) | `@donotdev/crud` |
+| **Display Utilities** (`formatValue`, `DisplayFieldRenderer`, `EntityFilters`, `translateFieldLabel`) | `@donotdev/crud` |
+| **Form Components** (`FormFieldRenderer`, `Controlled*Field`, `UploadProvider`) | `@donotdev/crud` |
+| **Routing-Aware Components** (`EntityFormRenderer`, `EntityList`, `EntityCardList`, `EntityDisplayRenderer`) | `@donotdev/ui` |
+| **Specialized Templates** (`ProductCardListTemplate`, `CarCardListTemplate`) | `@donotdev/templates` |
+| **Routing** (`useNavigate`, `Link`, `useParams`) | `@donotdev/ui` |
+| **Entity Definition** (`defineEntity`) | `@donotdev/core` |
+
+**Architecture:** Hooks and display utilities live in `@donotdev/crud`. Routing-aware page components that compose CRUD with navigation live in `@donotdev/ui`.
+
+---
+
 ## 1. Define Entity
 
 ```typescript
@@ -13,6 +29,7 @@ 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',
@@ -24,9 +41,16 @@ export const productEntity = defineEntity({
     price: {
       name: 'price',
       label: 'price',
-      type: 'number',
+      type: 'price',  // Structured: { amount, currency?, vatIncluded?, discountPercent? }
       visibility: 'guest',
-      validation: { required: true }
+      validation: { required: true },
+      // Optional: omit options entirely → defaultCurrency 'EUR', list = [EUR, USD, GBP, CHF, JPY, KRW]
+      options: {
+        fieldSpecific: {
+          defaultCurrency: 'EUR',       // Omit → 'EUR'. Used when value.currency is unset
+          currencies: ['EUR', 'USD'],   // Omit → framework default (6 currencies). One item e.g. ['EUR'] → no dropdown, EUR only
+        },
+      },
     },
     image: {
       name: 'image',
@@ -49,7 +73,72 @@ export const productEntity = defineEntity({
 
 ---
 
-## 2. Visibility & Access
+## 2. Multi-Tenancy (Company/Tenant Scoping)
+
+For multi-tenant apps where data belongs to a company/tenant/workspace:
+
+### Step 1: Register Scope Provider (once at app startup)
+
+```typescript
+// src/main.tsx or src/App.tsx
+import { registerScopeProvider } from '@donotdev/core';
+import { useCurrentCompanyStore } from './stores/currentCompanyStore';
+
+// Register before app renders
+registerScopeProvider('company', () =>
+  useCurrentCompanyStore.getState().currentCompanyId
+);
+```
+
+### Step 2: Add `scope` to Entity Definition
+
+```typescript
+// entities/client.ts
+import { defineEntity } from '@donotdev/core';
+
+export const clientEntity = defineEntity({
+  name: 'Client',
+  collection: 'clients',
+  scope: { field: 'companyId', provider: 'company' }, // <-- Add this
+  fields: {
+    // NO need to manually define companyId - framework adds it automatically
+    name: { name: 'name', label: 'name', type: 'text', visibility: 'user', validation: { required: true } },
+    // ...
+  }
+});
+```
+
+### What Happens Automatically
+
+| Operation | Behavior |
+|-----------|----------|
+| `add()` / `set()` | Auto-injects `companyId` from scope provider |
+| `useCrudList()` | Auto-filters by `companyId == currentCompanyId` |
+| `useCrudCardList()` | Auto-filters by `companyId == currentCompanyId` |
+| `query()` | Auto-adds `where companyId == currentCompanyId` |
+
+**Result:** Zero boilerplate. Users only see data from their current company.
+
+### Scope Field Properties
+
+The auto-added scope field has:
+- `type: 'reference'` (references the scoped collection, e.g., `companies`)
+- `visibility: 'technical'` (hidden from regular users)
+- `editable: 'create-only'` (cannot change scope after creation)
+
+### Multiple Scope Types
+
+You can register multiple scope providers for different use cases:
+
+```typescript
+registerScopeProvider('company', () => companyStore.getState().currentCompanyId);
+registerScopeProvider('workspace', () => workspaceStore.getState().currentWorkspaceId);
+registerScopeProvider('tenant', () => tenantStore.getState().currentTenantId);
+```
+
+---
+
+## 3. Visibility & Access
 
 ### Field Visibility (who SEES)
 | Level | Who |
@@ -64,7 +153,7 @@ export const productEntity = defineEntity({
 ```typescript
 access: {
   create: 'admin',  // default
-  read: 'guest',    // default  
+  read: 'guest',    // default
   update: 'admin',  // default
   delete: 'admin',  // default
 }
@@ -96,10 +185,13 @@ export const crud = createCrudFunctions(entities);
 
 ## 4. Frontend Usage
 
-### Create/Edit Page
+Use components directly from `@donotdev/ui`. They handle routing automatically - no navigate handlers needed.
+
+#### Create/Edit Page
 
 ```tsx
-import { EntityFormRenderer, useCrud } from '@donotdev/crud';
+import { useCrud } from '@donotdev/crud';
+import { EntityFormRenderer, useParams } from '@donotdev/ui';
 import { productEntity } from 'entities';
 
 export default function ProductPage() {
@@ -114,10 +206,9 @@ export default function ProductPage() {
 
   const handleSubmit = async (formData: any) => {
     isNew ? await add(formData) : await update(id!, formData);
-    navigate('/products');
+    // Navigation happens automatically via cancelPath (defaults to /products)
   };
 
-  // DON'T mount form until data ready (edit mode)
   if (!isNew && !data) return <Spinner />;
 
   return (
@@ -126,35 +217,191 @@ export default function ProductPage() {
       operation={isNew ? 'create' : 'edit'}
       defaultValues={data}
       onSubmit={handleSubmit}
+      // Cancel automatically navigates to /products (or cancelPath if provided)
+      cancelPath="/products"
     />
   );
 }
 ```
 
-### List Page
+#### List Page
 
 ```tsx
-import { EntityList } from '@donotdev/crud';
+import { EntityList, PageContainer } from '@donotdev/ui';
+import { useAuth } from '@donotdev/auth';
 import { productEntity } from 'entities';
 
 export default function ProductsPage() {
-  return <EntityList entity={productEntity} onRowClick={(p) => navigate(`/products/${p.id}`)} />;
+  const user = useAuth('user');
+
+  return (
+    <PageContainer>
+      <EntityList
+        entity={productEntity}
+        userRole={user?.role}
+        // Routing: basePath defaults to /products. View/Edit = basePath/:id, Create = basePath/new
+        // Optional: basePath="/admin/products" or onClick={(id) => openSheet(id)}
+      />
+    </PageContainer>
+  );
 }
 ```
 
-### Card Grid
+#### Card Grid
 
 ```tsx
-import { EntityCardList } from '@donotdev/crud';
+import { EntityCardList, PageContainer } from '@donotdev/ui';
+import { productEntity } from 'entities';
 
 export default function ShopPage() {
-  return <EntityCardList entity={productEntity} />;
+  return (
+    <PageContainer>
+      <EntityCardList
+        entity={productEntity}
+        // Routing: basePath defaults to /products. View = basePath/:id
+        // Optional: basePath="/shop/products" or onClick={(id) => openSheet(id)}
+      />
+    </PageContainer>
+  );
+}
+```
+
+#### Detail/View Page
+
+```tsx
+import { EntityDisplayRenderer, useParams } from '@donotdev/ui';
+import { productEntity } from 'entities';
+
+export default function ProductDetailPage() {
+  const { id } = useParams<{ id: string }>();
+
+  return (
+    <EntityDisplayRenderer
+      entity={productEntity}
+      id={id}
+      // Auto-fetches data, shows loading state
+      // Read-only display of all visible fields
+    />
+  );
+}
+```
+
+#### Custom Detail Page with Favorites
+
+For custom detail pages, add favorites support using `useEntityFavorites`:
+
+```tsx
+import { useState, useEffect } from 'react';
+import { Heart } from 'lucide-react';
+import { PageContainer, Section, Button, Stack } from '@donotdev/components';
+import { useParams, useNavigate } from '@donotdev/ui';
+import { useCrud, useEntityFavorites } from '@donotdev/crud';
+import { useTranslation } from '@donotdev/core';
+import { productEntity } from 'entities';
+
+export default function ProductDetailPage() {
+  const { id } = useParams<{ id: string }>();
+  const navigate = useNavigate();
+  const { get } = useCrud(productEntity);
+  const { isFavorite, toggleFavorite } = useEntityFavorites({
+    collection: productEntity.collection,
+  });
+  const { t } = useTranslation('crud');
+  const [data, setData] = useState<any>(null);
+  const [loading, setLoading] = useState(true);
+
+  useEffect(() => {
+    if (id) {
+      get(id).then((result) => {
+        setData(result);
+        setLoading(false);
+      });
+    }
+  }, [id, get]);
+
+  if (loading) return <div>Loading...</div>;
+  if (!data) return <div>Not found</div>;
+
+  return (
+    <PageContainer>
+      <Section>
+        <Stack direction="row" gap="medium" align="center">
+          <h1>{data.name}</h1>
+          <Button
+            variant={isFavorite(id) ? 'primary' : 'outline'}
+            icon={<Heart size={18} fill={isFavorite(id) ? 'currentColor' : 'none'} />}
+            onClick={() => toggleFavorite(id)}
+          >
+            {isFavorite(id) ? t('favorites.saved') : t('favorites.save')}
+          </Button>
+        </Stack>
+        {/* Your custom detail page content */}
+      </Section>
+    </PageContainer>
+  );
+}
+```
+
+**Note:** `EntityCardList` automatically includes favorites support - heart icons on cards and a favorites filter toggle. No configuration needed.
+
+#### Product Shop (Specialized Template)
+
+For e-commerce/shop pages with price, image, and category support, use the specialized template:
+
+```tsx
+import { ProductCardListTemplate } from '@donotdev/templates';
+import { productEntity } from 'entities';
+
+export default function ShopPage() {
+  return (
+    <PageContainer>
+      <ProductCardListTemplate
+        entity={productEntity}
+        // Auto-detects price, image, category fields
+        // Routing: basePath defaults to /products. Optional: basePath or onClick
+      />
+    </PageContainer>
+  );
 }
 ```
 
 ---
 
-## 5. Field Types
+## 5. Component Props
+
+### EntityList
+- `basePath` **(optional)** - Base path for view/edit/create. Defaults to `/${collection}`. View/Edit = basePath/:id, Create = basePath/new
+- `onClick` **(optional)** - Called when user clicks a row. If provided, overrides navigation (e.g. open sheet)
+- `userRole` **(optional)** - Current user role for field visibility
+
+### EntityCardList
+- `basePath` **(optional)** - Base path for view. Defaults to `/${collection}`. View = basePath/:id
+- `onClick` **(optional)** - Called when user clicks a card. If provided, overrides navigation (e.g. open sheet)
+- `cols` **(optional)** - `[mobile, tablet, desktop, wide]` (default: `[1, 2, 3, 4]`)
+- `staleTime` **(optional)** - Cache stale time in ms (default: 30 min)
+- `filter` **(optional)** - `(item: any) => boolean` - Client-side filter
+- `hideFilters` **(optional)** - Hide filters section
+
+**Favorites:** Automatically enabled - heart icons on cards, favorites filter toggle in filters section. Uses `useEntityFavorites` hook internally with `entity.collection` as storage key.
+
+### EntityFormRenderer
+- `entity` **(required)** - Entity definition
+- `onSubmit` **(required)** - `(data: any) => Promise<void>` - Submit handler
+- `defaultValues` **(optional)** - Initial form values (for edit mode)
+- `operation` **(optional)** - `'create' | 'edit'` (auto-detected from defaultValues)
+- `viewerRole` **(optional)** - Role for field visibility/editability
+- `cancelPath` **(optional)** - Path to navigate on cancel (defaults to `/${collection}`)
+- `onCancel` **(optional)** - Cancel button handler (takes precedence over cancelPath)
+- `cancelText` **(optional)** - Cancel button text (null to hide)
+
+### EntityDisplayRenderer
+- `entity` **(required)** - Entity definition
+- `id` **(required)** - Entity ID to fetch and display
+- `viewerRole` **(optional)** - Role for field visibility
+
+---
+
+## 6. Field Types
 
 ### Text Inputs
 - `text` - Single-line text input
@@ -168,7 +415,10 @@ export default function ShopPage() {
 
 ### Numbers
 - `number` - Numeric input
+- `currency` - Single amount with currency symbol (value: number; options: `fieldSpecific.currency`)
+- `price` - **Structured price:** amount + currency, VAT label, discount %. Value: `{ amount, currency?, vatIncluded?, discountPercent? }`. Options: `fieldSpecific.defaultCurrency`, `fieldSpecific.currencies` (e.g. `['EUR', 'USD']`; one currency = no dropdown). Form: amount + collapsible options (currency if >1, VAT Incl., discount %). Display: formatted amount; when discounted shows original crossed out + effective price. Filterable by amount (range); "deals" = items with discount.
 - `range` - Slider input
+- `year` - Year input (combobox: type or select from dropdown)
 
 ### Boolean
 - `checkbox` - Checkbox input
@@ -212,6 +462,42 @@ export default function ShopPage() {
 - `submit` - Submit button (uncontrolled)
 - `reset` - Reset button (uncontrolled)
 
+### Price field type (structured)
+
+Use `type: 'price'` when you need amount, currency, VAT label, and optional discount in one field. Replaces separate "price" + "specialPrice" number fields.
+
+**Definition:**
+```typescript
+price: {
+  name: 'price',
+  label: 'price',
+  type: 'price',
+  visibility: 'guest',
+  validation: { required: true },
+  options: {
+    fieldSpecific: {
+      defaultCurrency: 'EUR',           // Omit → 'EUR'. Used when value.currency is unset
+      currencies: ['EUR', 'USD'],      // Omit → list = [EUR, USD, GBP, CHF, JPY, KRW]. One item e.g. ['EUR'] → no dropdown, single currency
+      optionsTitle: 'Price options',   // Omit → 'Price options'. Aria-label for the expand button
+    },
+  },
+},
+```
+
+**Value shape (stored in DB):**
+```ts
+{ amount: number; currency?: string; vatIncluded?: boolean; discountPercent?: number }
+```
+- Only `discountPercent` is stored for discount; effective price is computed as `amount * (1 - discountPercent/100)` for display.
+
+**Form:** Main input = amount (number) with label "Price (symbol)". Collapsible "+" opens: currency select (if more than one in `currencies`), VAT included (checkbox), discount (%). Single currency → no dropdown, value still stored.
+
+**Display:** Formatted amount + "VAT Incl." when `vatIncluded`. When `discountPercent > 0`: original amount crossed out + effective price.
+
+**Templates:** `CarCardListTemplate`, `CarDetailTemplate`, `ProductCardListTemplate` use the price field when present and show a "Sale" (or `price.badge.sale` i18n) badge when discounted.
+
+**Filtering:** Range filter on `amount`; optional "deals" filter (items with `discountPercent > 0`).
+
 ### Select Options
 
 ```typescript
@@ -226,14 +512,18 @@ category: {
 }
 ```
 
-### Year Dropdown
+### Year Field
 
-```typescript
-import { yearOptions } from '@donotdev/crud';
+Use `type: 'year'` for year inputs (combobox with type-or-select UX):
 
+```typescript
 year: {
-  type: 'select',
-  validation: { options: yearOptions(1990) } // 1990 to now, descending
+  type: 'year',
+  validation: {
+    required: true,
+    min: 1900,  // Optional: defaults to 1900
+    max: 2100   // Optional: defaults to current year + 10
+  }
 }
 ```
 
@@ -253,20 +543,17 @@ transmission: {
 
 ---
 
-## 6. Custom Fields & Schemas
+## 7. 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 { registerFieldType, useController } from '@donotdev/crud';
 import type { ControlledFieldProps } from '@donotdev/crud';
+import { defineEntity } from '@donotdev/core';
+import * as v from 'valibot';
 
 function RepairOperationsField({
   fieldConfig,
@@ -282,7 +569,7 @@ function RepairOperationsField({
 
   // Use field.value and field.onChange for form state
   const value = (field.value as any) || [];
-  
+
   return (
     <div>
       <label>{t(fieldConfig.label)}</label>
@@ -323,7 +610,7 @@ export const carEntity = defineEntity({
 });
 ```
 
-**Important:** 
+**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
@@ -333,6 +620,7 @@ export const carEntity = defineEntity({
 For custom validation without custom UI, just define the schema:
 
 ```typescript
+import { defineEntity } from '@donotdev/core';
 import * as v from 'valibot';
 
 export const carEntity = defineEntity({
@@ -383,28 +671,30 @@ export const carEntity = defineEntity({
 
 ---
 
-## 7. Hooks API
+## 8. Hooks API
 
 ```typescript
+import { useCrud, useCrudList, useCrudCardList } from '@donotdev/crud';
+
 // Actions
 const { add, update, delete: remove, get } = useCrud(productEntity);
 
 // List (auto-fetch for tables)
-const { items, loading } = useCrudList(productEntity);
+const { items, loading, refresh } = useCrudList(productEntity);
 
 // Cards (optimized for public)
-const { items, loading, loadMore } = useCrudCardList(productEntity);
+const { items, loading, refresh } = useCrudCardList(productEntity);
 ```
 
 ---
 
-## 8. Custom Form Layouts
+## 9. 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 { useEntityForm, useCrud, UploadProvider, useController } from '@donotdev/crud';
 import { productEntity } from 'entities';
 
 export function CustomProductForm() {
@@ -445,11 +735,24 @@ export function CustomProductForm() {
 
 ---
 
-## 9. i18n
+## 10. i18n
+
+**Namespace:** Automatically set to `entity-${entity.name.toLowerCase()}` (e.g., `entity-product`)
+
+You can customize it by setting `namespace` in your entity definition:
 
-**Namespace:** `entity-${entity.name.toLowerCase()}`
+```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()}`.
 
-**File:** `locales/entity-product_en.json`
+**Translation file:** `locales/entity-product_en.json` (or your custom namespace)
 ```json
 {
   "fields": {
@@ -464,7 +767,42 @@ Field `label` → translation key in `fields.*`
 
 ---
 
-## 10. Routing Convention
+## 11. Display Utilities
+
+For custom displays, use `formatValue` from `@donotdev/crud`:
+
+```tsx
+import { formatValue, translateFieldLabel } from '@donotdev/crud';
+import { useTranslation } from '@donotdev/core';
+import { productEntity } from 'entities';
+
+function ProductCard({ item }) {
+  const { t } = useTranslation(productEntity.namespace);
+
+  // Format any field value using entity config
+  const priceDisplay = formatValue(
+    item.price,
+    productEntity.fields.price,
+    t,
+    { compact: true }  // compact mode for lists/cards
+  );
+
+  // Get translated field label
+  const priceLabel = translateFieldLabel('price', productEntity.fields.price, t);
+
+  return (
+    <div>
+      <span>{priceLabel}: {priceDisplay}</span>
+    </div>
+  );
+}
+```
+
+**`formatValue` handles all field types:** dates, numbers, selects (translates option labels), images, files, etc.
+
+---
+
+## 12. Routing Convention
 
 | Route | Purpose |
 |-------|---------|

package/templates/root-consumer/guides/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.**

package/templates/root-consumer/guides/wai-way/entity_patterns.md.example

@@ -369,7 +369,7 @@ export const reviewEntity = defineEntity({
     rating: {
       name: 'rating',
       label: 'rating',
-      type: 'number',
+      type: 'rating',
       visibility: 'guest',
       validation: { required: true, min: 1, max: 5 },
     },

package/templates/root-consumer/storage.rules.example

@@ -0,0 +1,8 @@
+rules_version = '2';
+service firebase.storage {
+  match /b/{bucket}/o {
+    match /{allPaths=**} {
+      allow read, write: if request.auth != null;
+    }
+  }
+}