@donotdev/crud 0.0.31 → 0.1.1

package/dist/utils/sanitizeHtml.d.ts

@@ -1,7 +1,2 @@
-/**
- * Sanitize HTML using DOMPurify — handles all known XSS vectors including
- * malformed tags, event handlers, javascript: URIs, data: URIs, SVG payloads,
- * CSS injection, and HTML entity encoding bypasses.
- */
 export declare function sanitizeHtml(html: string): string;
 //# sourceMappingURL=sanitizeHtml.d.ts.map

package/dist/utils/sanitizeHtml.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"sanitizeHtml.d.ts","sourceRoot":"","sources":["../../src/utils/sanitizeHtml.ts"],"names":[],"mappings":"AAaA;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAEjD"}
+{"version":3,"file":"sanitizeHtml.d.ts","sourceRoot":"","sources":["../../src/utils/sanitizeHtml.ts"],"names":[],"mappings":"AA6DA,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAGjD"}

package/dist/utils/sanitizeHtml.js

@@ -1 +1 @@
-import t from"dompurify";function n(i){return t.sanitize(i)}export{n as sanitizeHtml};
+import e from"dompurify";const r=["p","h1","h2","h3","h4","h5","h6","blockquote","pre","hr","ul","ol","li","a","strong","b","em","i","u","s","code","br","span","sub","sup","mark","table","thead","tbody","tr","th","td","img","div","figure","figcaption","details","summary"],i=["href","target","rel","src","alt","width","height","class","colspan","rowspan"],a=/<\/?(?:embed|source|track|area|wbr)[^>]*>/gi;function n(t){return e.sanitize(t,{ALLOWED_TAGS:r,ALLOWED_ATTR:i}).replace(a,"")}export{n as sanitizeHtml};

package/dist/utils/scopeUtils.js

@@ -1 +1 @@
-import{getScopeValue as t,CRUD_OPERATORS as c}from"@donotdev/core";function s(r,e){if(!e)return r;const o=t(e.provider);if(!o)throw new Error(`[CRUD] Scope provider "${e.provider}" returned null. Cannot write scoped entity without a scope value. Ensure a scope is selected before creating scoped entities.`);return{...r,[e.field]:o}}function p(r,e){const o=r??{};if(!e||typeof e.field!="string")return o;const n=t(e.provider);if(!n)throw new Error(`[CRUD] Scope provider "${e.provider}" returned null. Cannot query scoped entity without a scope value. Ensure a scope is selected before querying scoped entities.`);const i={field:e.field,operator:c.EQ,value:n};return{...o,where:o.where?[...o.where,i]:[i]}}function u(r){return r?t(r.provider):null}export{u as getCurrentScopeValue,s as injectScope,p as injectScopeFilter};
+import{getScopeValue as o,CRUD_OPERATORS as p}from"@donotdev/core";function c(t,e){if(!e)return t;const r=o(e.provider);if(!r)throw new Error(`[CRUD] Scope provider "${e.provider}" returned null. Cannot write scoped entity without a scope value. Ensure a scope is selected before creating scoped entities.`);return{...t,[e.field]:r}}function l(t,e){const r=t??{};if(!e||typeof e.field!="string")return r;const i=o(e.provider);if(!i)throw new Error(`[CRUD] Scope provider "${e.provider}" returned null. Cannot query scoped entity without a scope value. Ensure a scope is selected before querying scoped entities.`);const n={field:e.field,operator:p.EQ,value:i};return{...r,where:r.where?[...r.where,n]:[n]}}function s(t){return t?o(t.provider):null}export{s as getCurrentScopeValue,c as injectScope,l as injectScopeFilter};

package/dist/utils/uploadValidation.d.ts

@@ -3,7 +3,7 @@
  * @description Type-safe validation utilities to ensure no blob URLs reach the database.
  * Provides security checks for Picture objects and form data validation.
  *
- * @version 0.0.1
+ * @version 0.1.0
  * @since 0.0.1
  * @author AMBROISE PARK Consulting
  */

package/dist/utils/uploadValidation.js

@@ -1 +1 @@
-"use client";function o(r){return!r||typeof r!="string"?!1:r.startsWith("https://")&&!r.startsWith("blob:")}function h(r){return!(!r||typeof r!="object"||!o(r.fullUrl)||r.thumbUrl&&!o(r.thumbUrl))}function i(r,l=""){const t=[];if(r==null)return t;if(typeof r=="string")return r.startsWith("blob:")&&t.push(l||"root"),t;if(typeof r!="object")return t;if(Array.isArray(r))r.forEach((e,s)=>{const n=l?`${l}[${s}]`:`[${s}]`;t.push(...i(e,n))});else{const e=r;if(e.fullUrl!==void 0&&e.thumbUrl!==void 0){const s=e.fullUrl,n=e.thumbUrl,u=typeof s=="string"&&!o(s),c=n&&typeof n=="string"&&!o(n);if(u||c){const f=l||"root";t.push(`${f}.fullUrl or ${f}.thumbUrl contains blob URL`)}}else Object.entries(e).forEach(([s,n])=>{const u=l?`${l}.${s}`:s;t.push(...i(n,u))})}return t}function b(r){return i(r).length>0}export{i as checkForBlobUrls,b as hasBlobUrls,o as isStorageUrl,h as validatePicture};
+"use client";function s(r){return!r||typeof r!="string"?!1:r.startsWith("https://")&&!r.startsWith("blob:")}function c(r){return!(!r||typeof r!="object"||!s(r.fullUrl)||r.thumbUrl&&!s(r.thumbUrl))}function u(r,o=""){const t=[];if(r==null)return t;if(typeof r=="string")return r.startsWith("blob:")&&t.push(o||"root"),t;if(typeof r!="object")return t;if(Array.isArray(r))r.forEach((e,n)=>{const l=o?`${o}[${n}]`:`[${n}]`;t.push(...u(e,l))});else{const e=r;if(e.fullUrl!==void 0&&e.thumbUrl!==void 0){const n=e.fullUrl,l=e.thumbUrl,f=typeof n=="string"&&!s(n),b=l&&typeof l=="string"&&!s(l);if(f||b){const i=o||"root";t.push(`${i}.fullUrl or ${i}.thumbUrl contains blob URL`)}}else Object.entries(e).forEach(([n,l])=>{const f=o?`${o}.${n}`:n;t.push(...u(l,f))})}return t}function h(r){return u(r).length>0}export{u as checkForBlobUrls,h as hasBlobUrls,s as isStorageUrl,c as validatePicture};

package/dist/workflows/WorkflowPersistence.d.ts

@@ -2,7 +2,7 @@
  * @fileoverview Workflow persistence adapter
  * @description Saves and restores workflow progress to/from localStorage.
  *
- * @version 0.0.1
+ * @version 0.1.0
  * @since 0.0.1
  * @author AMBROISE PARK Consulting
  */

package/dist/workflows/WorkflowPersistence.js

@@ -1 +1 @@
-const a="dndev-workflow-";function r(t,o){try{const e=`${a}${t}`;localStorage.setItem(e,JSON.stringify(o))}catch{}}function c(t){try{const o=`${a}${t}`,e=localStorage.getItem(o);return e?JSON.parse(e):null}catch{return null}}function n(t){try{const o=`${a}${t}`;localStorage.removeItem(o)}catch{}}export{n as clearWorkflowState,c as loadWorkflowState,r as saveWorkflowState};
+const r="dndev-workflow-";function c(t,o){try{const e=`${r}${t}`;localStorage.setItem(e,JSON.stringify(o))}catch{}}function n(t){try{const o=`${r}${t}`,e=localStorage.getItem(o);return e?JSON.parse(e):null}catch{return null}}function a(t){try{const o=`${r}${t}`;localStorage.removeItem(o)}catch{}}export{a as clearWorkflowState,n as loadWorkflowState,c as saveWorkflowState};

package/dist/workflows/defineWorkflow.d.ts

@@ -18,7 +18,7 @@
  * });
  * ```
  *
- * @version 0.0.1
+ * @version 0.1.0
  * @since 0.0.1
  * @author AMBROISE PARK Consulting
  */

package/dist/workflows/index.d.ts

@@ -2,7 +2,7 @@
  * @fileoverview Workflow engine exports
  * @description Multi-step entity workflow: defineWorkflow, useEntityWorkflow, persistence.
  *
- * @version 0.0.1
+ * @version 0.1.0
  * @since 0.0.1
  * @author AMBROISE PARK Consulting
  */

package/dist/workflows/index.js

@@ -1 +1 @@
-import{defineWorkflow as o}from"./defineWorkflow";import{useEntityWorkflow as a}from"./useEntityWorkflow";import{saveWorkflowState as t,loadWorkflowState as r,clearWorkflowState as e}from"./WorkflowPersistence";export{e as clearWorkflowState,o as defineWorkflow,r as loadWorkflowState,t as saveWorkflowState,a as useEntityWorkflow};
+import{defineWorkflow as e}from"./defineWorkflow";import{useEntityWorkflow as f}from"./useEntityWorkflow";import{saveWorkflowState as a,loadWorkflowState as k,clearWorkflowState as w}from"./WorkflowPersistence";export{w as clearWorkflowState,e as defineWorkflow,k as loadWorkflowState,a as saveWorkflowState,f as useEntityWorkflow};

package/dist/workflows/useEntityWorkflow.js

@@ -1 +1 @@
-"use client";import{useState as g,useCallback as p,useMemo as h,useEffect as L,useRef as M}from"react";import{evaluateCondition as R}from"@donotdev/core";import{saveWorkflowState as K,loadWorkflowState as j,clearWorkflowState as C}from"./WorkflowPersistence";function V(e,I={}){const{onComplete:m,onStepChange:f,defaultValues:y}=I,w=M(m);w.current=m;const[a,v]=g(()=>{if(e.persist){const t=j(e.persistKey??e.id);if(t)return t.stepData}if(y){const t={};for(const r of e.steps)if(r.entity&&r.fields){const o={};for(const i of r.fields)i in y&&(o[i]=y[i]);Object.keys(o).length>0&&(t[r.id]=o)}return t}return{}}),[s,S]=g(()=>{if(e.persist){const t=j(e.persistKey??e.id);if(t)return t.currentStepIndex}return 0}),[k,x]=g(!1),l=h(()=>{const t={};for(const[r,o]of Object.entries(a))for(const[i,c]of Object.entries(o))t[i]=c,t[`${r}.${i}`]=c;return t},[a]),n=h(()=>e.steps.filter(t=>t.conditions?.visible?R(t.conditions.visible,l):!0),[e.steps,l]),O=n[s]??n[0],b=s===0,d=s===n.length-1;L(()=>{e.persist&&K(e.persistKey??e.id,{currentStepIndex:s,stepData:a,savedAt:Date.now()})},[e.persist,e.persistKey,e.id,s,a]);const W=p(async t=>{const r=n[s];if(!r)return!1;if(t&&v(i=>({...i,[r.id]:{...i[r.id],...t}})),r.validation?.validate){const i={...l,...t??{}};if(r.validation.validate(i)!==!0)return!1}if(r.after){const i={};await r.after({data:t??a[r.id]??{},allData:{...l,...t??{}},next:{prefill:c=>{const u=n[s+1];u&&(i[u.id]=c)}}}),Object.keys(i).length>0&&v(c=>{const u={...c};for(const[D,G]of Object.entries(i))u[D]={...u[D],...G};return u})}if(d){x(!0);try{const i={...l,...t??{}},c=w.current??e.onComplete;return c&&await c(i),e.persist&&C(e.persistKey??e.id),!0}catch{return!1}finally{x(!1)}}const o=s+1;return S(o),f?.(s,o),!0},[n,s,l,a,d,e,f]),N=p(()=>{if(b)return;const t=s-1;S(t),f?.(s,t)},[s,b,f]),A=p(()=>{if(!n[s]?.allowSkip||d)return;const t=s+1;S(t),f?.(s,t)},[n,s,d,f]),E=p(t=>{t>=0&&t<n.length&&(f?.(s,t),S(t))},[n.length,s,f]),P=p(()=>{e.persist&&K(e.persistKey??e.id,{currentStepIndex:s,stepData:a,savedAt:Date.now()})},[e,s,a]),$=p(()=>{C(e.persistKey??e.id)},[e]),F=p((t,r)=>{v(o=>({...o,[t]:{...o[t],...r}}))},[]);return{currentStep:O,currentStepIndex:s,visibleSteps:n,stepData:a,allData:l,goNext:W,goPrevious:N,skipStep:A,goToStep:E,isFirst:b,isLast:d,isSubmitting:k,canGoNext:!k,persistNow:P,clearPersisted:$,prefillStep:F}}export{V as useEntityWorkflow};
+"use client";import{useState as b,useCallback as p,useMemo as I,useEffect as G,useRef as L}from"react";import{evaluateCondition as M}from"@donotdev/core";import{saveWorkflowState as K,loadWorkflowState as j,clearWorkflowState as O}from"./WorkflowPersistence";function B(e,D={}){const{onComplete:k,onStepChange:u,defaultValues:y}=D,w=L(k);w.current=k;const[l,v]=b(()=>{if(e.persist){const t=j(e.persistKey??e.id);if(t)return t.stepData}if(y){const t={};for(const r of e.steps)if(r.entity&&r.fields){const o={};for(const i of r.fields)i in y&&(o[i]=y[i]);Object.keys(o).length>0&&(t[r.id]=o)}return t}return{}}),[s,m]=b(()=>{if(e.persist){const t=j(e.persistKey??e.id);if(t)return t.currentStepIndex}return 0}),[x,h]=b(!1),d=I(()=>{const t={};for(const[r,o]of Object.entries(l))for(const[i,a]of Object.entries(o))t[i]=a,t[`${r}.${i}`]=a;return t},[l]),n=I(()=>e.steps.filter(t=>t.conditions?.visible?M(t.conditions.visible,d):!0),[e.steps,d]),W=n[s]??n[0],S=s===0,c=s===n.length-1;G(()=>{e.persist&&K(e.persistKey??e.id,{currentStepIndex:s,stepData:l,savedAt:Date.now()})},[e.persist,e.persistKey,e.id,s,l]);const F=p(async t=>{const r=n[s];if(!r)return!1;if(t&&v(i=>({...i,[r.id]:{...i[r.id],...t}})),r.validation?.validate){const i={...d,...t??{}};if(r.validation.validate(i)!==!0)return!1}if(r.after){const i={};await r.after({data:t??l[r.id]??{},allData:{...d,...t??{}},next:{prefill:a=>{const f=n[s+1];f&&(i[f.id]=a)}}}),Object.keys(i).length>0&&v(a=>{const f={...a};for(const[C,$]of Object.entries(i))f[C]={...f[C],...$};return f})}if(c){h(!0);try{const i={...d,...t??{}},a=w.current??e.onComplete;return a&&await a(i),e.persist&&O(e.persistKey??e.id),!0}catch{return!1}finally{h(!1)}}const o=s+1;return m(o),u?.(s,o),!0},[n,s,d,l,c,e,u]),N=p(()=>{if(S)return;const t=s-1;m(t),u?.(s,t)},[s,S,u]),A=p(()=>{if(!n[s]?.allowSkip||c)return;const r=s+1;m(r),u?.(s,r)},[n,s,c,u]),E=p(t=>{t>=0&&t<n.length&&(u?.(s,t),m(t))},[n.length,s,u]),P=p(()=>{e.persist&&K(e.persistKey??e.id,{currentStepIndex:s,stepData:l,savedAt:Date.now()})},[e,s,l]),R=p(()=>{O(e.persistKey??e.id)},[e]),V=p((t,r)=>{v(o=>({...o,[t]:{...o[t],...r}}))},[]);return{currentStep:W,currentStepIndex:s,visibleSteps:n,stepData:l,allData:d,goNext:F,goPrevious:N,skipStep:A,goToStep:E,isFirst:S,isLast:c,isSubmitting:x,canGoNext:!x,persistNow:P,clearPersisted:R,prefillStep:V}}export{B as useEntityWorkflow};

package/guidelines/COMPONENTS.md

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

package/guidelines/CRUD.md

@@ -0,0 +1,340 @@
+# CRUD Operations
+
+> **API details:** `lookup_symbol("symbolName")` via MCP for full props, return types, and examples from JSDoc.
+
+---
+
+## 1. Define Entity (SSOT)
+
+The entity definition drives everything - forms, lists, validation, access, search, sort, backend.
+
+```typescript
+import { defineEntity } from '@donotdev/core';
+
+export const productEntity = defineEntity({
+  name: 'Product',
+  collection: 'products',
+  search: { fields: ['name', 'description'] },
+  defaultSort: { field: 'createdAt', direction: 'desc' },
+  fields: {
+    name: { name: 'name', label: 'name', type: 'text', visibility: 'guest', validation: { required: true } },
+    price: { name: 'price', label: 'price', type: 'price', visibility: 'guest', validation: { required: true } },
+    image: { name: 'image', label: 'image', type: 'image', visibility: 'guest' },
+  }
+});
+```
+
+**Auto-added fields:** `id`, `createdAt`, `updatedAt`, `createdById`, `updatedById`, `status`.
+
+See `lookup_symbol("defineEntity")` for all options (scope, access, ownership, uniqueKeys, validation).
+
+### Status Field (auto-added)
+
+The `status` field is auto-added by `defineEntity()` with sensible defaults:
+
+| Property | Default | Can Override? |
+|----------|---------|---------------|
+| `type` | `'select'` | Yes |
+| `visibility` | `'admin'` | Yes |
+| `editable` | `'admin'` | Yes |
+| `required` | `true` | Yes |
+
+**Default options:** `draft`, `available`, `deleted` - always present, cannot be removed.
+**Default value:** `available`.
+
+If you don't define `status` in your fields at all, the full default is added automatically. If you define it, your properties are merged on top of defaults:
+
+```typescript
+fields: {
+  // Minimal: just add custom options (merged after defaults)
+  status: {
+    validation: {
+      options: [
+        { value: 'shipped', label: 'Shipped' },
+        { value: 'returned', label: 'Returned' },
+      ],
+    },
+  },
+  // Result: [draft, available, deleted, shipped, returned]
+
+  // Full override: all properties respected
+  status: {
+    visibility: 'super',
+    editable: 'super',
+    validation: { options: [...] },
+  },
+}
+```
+
+> `draft` and `deleted` items are hidden from non-admin users (server-side filtering).
+
+---
+
+## 2. Provider Setup (once)
+
+```typescript
+// config/providers.ts
+import { configureProviders } from '@donotdev/core';
+import { FirestoreAdapter } from '@donotdev/firebase'; // or SupabaseCrudAdapter
+
+configureProviders({ crud: new FirestoreAdapter() });
+```
+
+Import in `App.tsx`: `import './config/providers';`
+
+---
+
+## 3. Backend Functions
+
+**Firebase:**
+```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);
+```
+
+**Supabase:**
+```typescript
+// supabase/functions/crud/index.ts
+import * as entities from '../_shared/entities.ts';
+import { createSupabaseCrudFunctions } from '@donotdev/functions/supabase';
+
+const { serve } = createSupabaseCrudFunctions(entities);
+Deno.serve(serve);
+```
+
+See the Firebase or Supabase guideline for full function setup.
+
+---
+
+## 4. Use Components
+
+Drop components on a page. Entity drives the UI - no configuration needed.
+
+```tsx
+<EntityList entity={productEntity} userRole={user?.role} />
+<EntityCardList entity={productEntity} basePath="/shop" cols={[1, 2, 3, 4]} />
+<EntityFormRenderer entity={productEntity} operation="create" onSubmit={handleSubmit} cancelPath="/products" />
+<EntityDisplayRenderer entity={productEntity} id={id} />
+```
+
+Use `lookup_symbol("ComponentName")` for full props.
+
+---
+
+## 5. Visibility & Access
+
+### Field Visibility (who sees what)
+
+| Level | Who |
+|-------|-----|
+| `'guest'` | Everyone |
+| `'user'` | Authenticated |
+| `'admin'` | Admins |
+| `'super'` | Super admins |
+| `'technical'` | Admins only, read-only in forms |
+| `'owner'` | Stakeholders only (see `ownership`) |
+| `'hidden'` | Never |
+
+### Entity Access (who can CRUD)
+
+```typescript
+access: { create: 'admin', read: 'guest', update: 'admin', delete: 'admin' }
+```
+
+### Ownership
+
+For marketplace patterns. See `lookup_symbol("defineEntity")` -> `ownership`.
+
+**Firebase:** Enforced by generated secure Firebase Functions (server-side).
+**Supabase:** Enforced via RLS policies - generated by `dndev setup`.
+
+---
+
+## 6. Multi-Tenancy (Scope)
+
+```typescript
+registerScopeProvider('company', () => companyStore.getState().currentCompanyId);
+
+export const clientEntity = defineEntity({
+  scope: { field: 'companyId', provider: 'company' },
+  // ... (companyId auto-added, all CRUD ops auto-scoped)
+});
+```
+
+See `lookup_symbol("registerScopeProvider")`.
+
+---
+
+## 7. Data Fetching & Pagination
+
+### Default: Auto Mode (zero config)
+
+```tsx
+<EntityList entity={productEntity} />
+```
+
+That's it. The framework handles pagination automatically:
+
+1. **First fetch** - loads up to 1000 items client-side (instant search, sort, filter in the browser)
+2. **If total > 1000** - auto-switches to server pagination (fetches one page at a time via cursor)
+
+You never need to configure pagination mode. It just works.
+
+### Forcing a Mode (rare)
+
+| Mode | Behavior | When to force |
+|------|----------|---------------|
+| `pagination='auto'` (default) | Client-side up to 1000, auto-switches to server if more | Never - this is the default |
+| `pagination='client'` | Always client-side, fetches all | You know the dataset is small and want instant filters |
+| `pagination='server'` | Always server-side, cursor pagination | You know the dataset is huge and want minimal fetch |
+
+```tsx
+// Force server pagination with custom page size
+<EntityList entity={productEntity} pagination="server" pageSize={50} />
+```
+
+### What Changes When Auto-Switches to Server
+
+| Feature | Client mode (< 1000) | Server mode (> 1000) |
+|---------|----------------------|----------------------|
+| Search | Instant (in-memory) | Re-fetches per query |
+| Sort | Instant | Re-fetches |
+| Filters | Instant | Re-fetches |
+| Page navigation | Instant | Fetches next page |
+
+Server mode fetches only `pageSize` items per request - not the whole collection.
+
+---
+
+## What's Available
+
+### Components (`@donotdev/ui`)
+
+| Component | One-liner |
+|-----------|-----------|
+| `EntityList` | Table list with search, filters, pagination, routing |
+| `EntityCardList` | Card grid with search, filters, favorites, routing |
+| `EntityFormRenderer` | Auto-generated form from entity (create/edit) |
+| `EntityDisplayRenderer` | Read-only detail view, auto-fetches by ID |
+| `EntityRecommendations` | "You may also like" related items |
+
+### Templates (`@donotdev/templates`)
+
+| Template | One-liner |
+|----------|-----------|
+| `ProductCardListTemplate` | Shop card grid with price, image, sale badges |
+| `CarCardListTemplate` | Automotive listing with mileage, year |
+| `CarDetailTemplate` | Car detail with gallery, specs, price |
+| `InquiryFormTemplate` | Contact form (Customer + Inquiry, GDPR) |
+| `InquiryAdminTemplate` | Admin dashboard for inquiries |
+| `HomeTemplate` | Landing page |
+| `LoginTemplate` | Auth login page |
+| `DashboardTemplate` | Admin dashboard |
+| `CheckoutTemplate` | Stripe checkout |
+| `BillingSuccessTemplate` | Post-checkout success |
+| `UserSubscriptionTemplate` | Manage subscription |
+
+### Hooks (`@donotdev/crud`)
+
+| Hook | One-liner |
+|------|-----------|
+| `useCrud` | CRUD actions: `add`, `update`, `delete`, `get`, `set`, `query` |
+| `useCrudList` | Real-time list with search, filters, sort applied |
+| `useCrudCardList` | Same as `useCrudList`, optimized for public card views |
+| `useCrudFilters` | Filter state per collection, auto-consumed by list hooks |
+| `useEntityForm` | Form state for custom form layouts |
+| `useEntityField` | Single-field control for custom form layouts |
+| `useEntityFavorites` | Local favorites (localStorage) |
+| `useRelatedItems` | Fetch related items by reference field |
+| `useFileUpload` | File upload with progress tracking |
+| `useUnsavedChangesWarning` | Warn before leaving with unsaved changes |
+
+### Utilities (`@donotdev/crud`)
+
+| Utility | One-liner |
+|---------|-----------|
+| `formatValue` | Format any field value for display |
+| `applyFilters` / `applySearch` / `applySort` | Processing pipeline (what `useCrudList` does internally) |
+| `registerFieldType` | Register custom field type |
+| `validateEntity` | Validate entity data against schemas |
+| `isFieldEditable` / `getFieldsForOperation` | Field visibility helpers |
+
+### Routing (`@donotdev/ui`)
+
+| Symbol | One-liner |
+|--------|-----------|
+| `useNavigate` | Programmatic navigation (Vite/Next.js auto-detected) |
+| `useParams` | Read route params |
+| `Link` | Declarative navigation |
+| `AuthGuard` | Protect routes by auth + role |
+
+**Convention:** `/${collection}` (list) - `/${collection}/new` (create) - `/${collection}/:id` (detail/edit)
+
+---
+
+## Built-in Field Types
+
+| Category | Types |
+|----------|-------|
+| **Text** | `text`, `email`, `tel`, `url`, `color`, `password`, `textarea`, `richtext` |
+| **Number** | `number`, `currency`, `price`, `range`, `year` |
+| **Boolean** | `checkbox`, `boolean`, `switch` |
+| **Date/Time** | `date`, `datetime-local`, `time`, `week`, `month`, `timestamp` |
+| **Selection** | `select`, `combobox`, `multiselect`, `radio` |
+| **Files** | `file`, `files`, `document`, `documents`, `image`, `images` |
+| **Complex** | `geopoint`, `address`, `map`, `array` |
+| **Special** | `avatar`, `badge`, `hidden`, `submit`, `reset` |
+
+---
+
+## Custom Field Types (escape hatch)
+
+When built-in types don't fit, register your own with `registerFieldType`. One call wires form component + display formatter + filter.
+
+```typescript
+import { registerFieldType, useController } from '@donotdev/crud';
+import type { ControlledFieldProps } from '@donotdev/crud';
+
+function StatusTierField({ fieldConfig, control, t }: ControlledFieldProps) {
+  const { field, fieldState } = useController({ name: fieldConfig.name, control });
+  return (
+    <select value={field.value ?? ''} onChange={(e) => field.onChange(e.target.value)}>
+      <option value="basic">Basic</option>
+      <option value="premium">Premium</option>
+    </select>
+  );
+}
+
+registerFieldType({
+  type: 'statusTier',
+  controlledComponent: StatusTierField,
+  displayFormatter: (value) => value ? String(value).charAt(0).toUpperCase() + String(value).slice(1) : '-',
+  filterable: true,
+  filterType: 'select',
+});
+```
+
+Then use in entity: `tier: { name: 'tier', label: 'tier', type: 'statusTier', visibility: 'guest' }`
+
+See `lookup_symbol("registerFieldType")`, `lookup_symbol("ControlledFieldProps")`.
+
+---
+
+## i18n
+
+**Namespace:** `entity-${entity.name.toLowerCase()}` (customizable via `namespace`).
+
+```json
+{ "fields": { "name": "Product Name", "price": "Price" }, "name": "Product" }
+```
+
+Status labels: entity namespace -> `crud` namespace fallback.
+
+---
+
+**Define entity -> register provider -> register functions -> drop components. Entity is the SSOT - everything flows from it.**