@donotdev/crud 0.0.31 → 0.1.1

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.0.31",
+  "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.0.33",
-    "@donotdev/core": "^0.0.46",
+    "@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"