@donotdev/crud 0.1.0 → 0.1.1

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.**

package/guidelines/GOTCHAS.md

@@ -0,0 +1,46 @@
+# Gotchas: @donotdev/crud
+
+Common mistakes related to entity definition, forms, fields, and CRUD operations.
+
+---
+
+## CRUD [Phase 2, 3]
+
+**Hidden fields are auto-added by `defineEntity()` - don't define them manually:**
+- `id`, `createdAt`, `updatedAt`, `createdById`, `updatedById`
+
+**Status field - auto-added, fully overridable.**
+The `status` field is auto-added with defaults: `visibility: 'admin'`, `editable: 'admin'`, `type: 'select'`, `required: true`. All properties can be overridden. `validation.options` are **merged** (consumer options added after base: `draft`, `available`, `deleted`).
+
+```typescript
+// Minimal: just extend options
+status: { validation: { options: [{ value: 'shipped', label: 'Shipped' }] } }
+
+// Override visibility, editable, label - all respected
+status: { name: 'status', label: 'fields.status', visibility: 'admin', editable: 'super', validation: { options: [...] } }
+
+// Hide from forms entirely
+status: { visibility: 'technical' }
+```
+
+**Scope field is auto-added** when `scope` is configured. Don't manually define the scope field (e.g., `companyId`).
+
+**Custom form fields MUST use framework's `useController`:**
+
+```typescript
+// WRONG
+import { useController } from 'react-hook-form';
+
+// CORRECT
+import { useController } from '@donotdev/crud';
+```
+
+**Form components receive `control` prop, not `field` prop.**
+
+**Price field is structured:** `{ amount, currency, vatIncluded, discountPercent }`. Don't store computed discount amounts.
+
+**File uploads are deferred** - files upload on form submit, not on selection. Images show optimistic blob URLs.
+
+**Generated/computed fields are auto-excluded from forms.** Fields with `editable: 'generated'` (DB-generated columns) or `editable: 'computed'` (UI-derived values) are silently filtered out by `getFieldsForOperation`. They won't appear in create or edit forms. Use `'generated'` for PostgreSQL `GENERATED ALWAYS` columns. Use `'computed'` for fields derived from other form values (still included in write payloads).
+
+**Entity namespace defaults to `entity-{name}`** (lowercase). Translation files must match: `locales/entity-product_en.json`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@donotdev/crud",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "private": false,
   "type": "module",
   "license": "SEE LICENSE IN LICENSE.md",
@@ -20,6 +20,7 @@
   ],
   "files": [
     "dist",
+    "guidelines",
     "package.json",
     "README.md",
     "LICENSE.md"
@@ -47,14 +48,16 @@
     "dev": "tsc --noEmit --watch --listFiles false --listEmittedFiles false",
     "clean": "rimraf dist tsconfig.tsbuildinfo",
     "lint": "eslint src/",
-    "type-check": "bunx tsc --noEmit"
+    "type-check": "bunx tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest"
   },
   "dependencies": {
     "@dnd-kit/core": "^6.3.1",
     "@dnd-kit/sortable": "^10.0.0",
     "@dnd-kit/utilities": "^3.2.2",
-    "@donotdev/components": "^0.1.0",
-    "@donotdev/core": "^0.1.0",
+    "@donotdev/components": "^0.1.1",
+    "@donotdev/core": "^0.1.1",
     "@hookform/resolvers": "^5.2.2",
     "dompurify": "^3.3.2",
     "react-easy-crop": "^5.5.6"