@pilotiq/pilotiq 0.24.1 → 0.24.2

package/boost/skills/pilotiq-fields/rules/field-catalog.md

@@ -0,0 +1,288 @@
+# Field Catalog
+
+24 built-in field types. Every field is a static `make(name)` builder; all share the `Field` base setters (see "Common setters" at the bottom).
+
+## Text-like
+
+```ts
+TextField.make('title')
+  .placeholder('e.g. My first article')
+  .prefix('https://')
+  .suffix('.com')
+  .copyable()                            // value-side copy icon
+  .password()                            // <input type="password">
+  .revealable()                          // password reveal toggle
+  .mask('+1 (999) 999-9999')             // input mask
+  .datalist(['draft', 'review', 'final'])// browser-native datalist
+  .stripCharacters(/[^\w-]/g)            // sanitize on input
+  .trim()                                // trim whitespace
+  .inputMode('email')                    // mobile keyboard hint
+  .autocapitalize('words')
+
+EmailField.make('email')                 // auto-attaches email() validator
+
+NumberField.make('price')
+  .min(0).max(10_000).step(0.01)
+
+Slider.make('volume')
+  .range(0, 100).step(5)
+```
+
+## Long text
+
+```ts
+Textarea.make('bio')
+  .rows(5)
+  .cols(80)
+  .autosize()                            // grow with content
+  .disableGrammarly()
+
+MarkdownField.make('body')
+  .toolbarButtons(['bold', 'italic', 'link', 'codeBlock'])
+  .minHeight('20rem')
+
+RichTextField.make('description')        // requires @pilotiq/tiptap
+  .toolbarButtons([...])
+
+CodeEditorField.make('snippet')          // requires @pilotiq/codemirror
+  .language('javascript')
+  .lineNumbers()
+```
+
+`RichTextField` and `CodeEditorField` ship in separate adapter packages — install `@pilotiq/tiptap` / `@pilotiq/codemirror` and register via `.plugins([tiptap(), codeEditor()])` on the panel.
+
+## Choice
+
+```ts
+SelectField.make('status')
+  .options({ draft: 'Draft', review: 'In review', published: 'Published' })
+  .searchable()
+  .nullable()                            // adds a clear option
+  .preload()                             // fetch all options on mount (default)
+
+// Dynamic options
+SelectField.make('region')
+  .options(async ({ $get }) => {
+    const country = $get('country')
+    return country ? regionsFor(country) : {}
+  })
+  .live()
+
+// Inline create
+SelectField.make('tagId')
+  .options(async () => Object.fromEntries((await Tag.all()).map(t => [t.id, t.name])))
+  .createOptionForm([TextField.make('name').required()])
+  .createOptionUsing(async ({ name }) => {
+    const tag = await Tag.create({ name })
+    return tag.id                        // return the new value
+  })
+
+RadioField.make('priority')              // single-select radio stack
+  .options({ low: 'Low', med: 'Medium', high: 'High' })
+
+ToggleButtons.make('size')               // chip-style segmented (sugar over Radio)
+  .options({ s: 'S', m: 'M', l: 'L', xl: 'XL' })
+```
+
+## Boolean
+
+```ts
+CheckboxField.make('agreeToTerms')       // single bool, renders as checkbox
+  .required('You must agree to continue')
+
+ToggleField.make('isPublic')             // single bool, renders as switch
+
+CheckboxList.make('topics')              // string[] value, checkbox stack
+  .options({ js: 'JavaScript', ts: 'TypeScript', rust: 'Rust' })
+```
+
+## Tags / collections
+
+```ts
+TagsInput.make('keywords')               // string[] value, JSON-encoded
+  .suggestions(['design', 'code', 'process'])
+  .reorderable()                         // HTML5 drag-and-drop
+  .maxTags(8)
+  .separator(',')
+
+KeyValueField.make('metadata')           // Record<string, string>
+  .keyLabel('Field')
+  .valueLabel('Value')
+```
+
+## Date / time / color / file
+
+```ts
+DateField.make('publishedAt')
+  .minDate(new Date())                   // future-only
+
+DateTimePicker.make('eventAt')
+  .seconds(false)
+
+ColorPicker.make('brandColor')
+  .palette(['#ef4444', '#10b981', '#3b82f6'])
+
+FileUpload.make('cover')
+  .accept('image/*')
+  .maxSize(5 * 1024 * 1024)              // 5 MB
+  .multiple()                            // string[] when on
+  .imageEditor()                         // crop / rotate before upload
+```
+
+`FileUpload` requires an upload adapter wired at the panel level:
+
+```ts
+import { localUpload } from '@pilotiq/pilotiq/uploads'
+
+adminPanel.uploads({
+  adapter: localUpload({ root: 'public/uploads', urlPrefix: '/uploads' }),
+})
+```
+
+S3 / R2 / custom adapters implement the same `UploadAdapter` interface.
+
+## Array-of-rows (Repeater / Builder)
+
+```ts
+Repeater.make('items')                   // uniform rows
+  .schema([
+    TextField.make('label').required(),
+    NumberField.make('qty').required(),
+  ])
+  .min(1)
+  .maxItems(10)
+  .reorderable()
+  .cloneable()
+  .collapsible()
+  .itemLabel(row => row.label || 'New item')
+
+Builder.make('content')                  // heterogeneous rows
+  .blocks([
+    Block.make('heading').icon('heading').schema([
+      TextField.make('text').required(),
+      SelectField.make('level').options({ h1: 'H1', h2: 'H2', h3: 'H3' }),
+    ]),
+    Block.make('paragraph').icon('text').schema([
+      MarkdownField.make('body'),
+    ]),
+    Block.make('image').icon('image').schema([
+      FileUpload.make('src').accept('image/*').required(),
+      TextField.make('alt'),
+    ]),
+  ])
+  .reorderable()
+  .blockPickerColumns(2)
+```
+
+For relation-backed rows (real `hasMany` / `morph*` / M2M children instead of JSON-blob storage), see the `pilotiq-relations` skill.
+
+## Hidden
+
+```ts
+HiddenField.make('authorId')             // always submitted, never rendered
+  .default(({ user }) => user.id)
+```
+
+## Common setters
+
+Every field inherits these from `Field`:
+
+```ts
+Field.make('name')
+  .label('Display label')                // sr-only if empty
+  .helperText('Shown below the input')
+  .placeholder('e.g. Hello world')
+  .default('initial value')              // or () => value, or (ctx) => value
+  .prefix('$')                           // or .prefix({ icon: 'dollar' })
+  .suffix('USD')
+  .required()                            // implicit required validator
+  .validate([Field.email(), Field.unique({ model: User })])
+  .visible(({ user }) => user.role === 'admin')
+  .hidden(rule)
+  .disabled(rule)
+  .columnSpan(2)                         // inside a Grid / Section.columns(n)
+  .live()                                // re-resolve schema on change
+  .afterStateUpdated((value, ctx) => ctx.$set('slug', slugify(value)))
+  .dehydrated(false)                     // exclude from POST body
+  .formatStateUsing(v => `${v} px`)      // display transform (read paths)
+  .autofocus()
+  .hiddenLabel()                         // visually hidden, sr-only kept
+  .validationAttribute('email address')  // tunes the implicit-required text
+  .extraAttributes({ 'data-cy': 'name' }) // outer wrapper attrs
+  .extraInputAttributes({ autocomplete: 'off' }) // <input> attrs
+  .disabledOn(['edit'])                  // page-mode sugar
+  .hiddenOn(['view'])
+  .visibleOn(['create', 'edit'])
+  .readonly()                            // disabled + non-submittable
+```
+
+## Operation-aware shortcuts
+
+`disabledOn` / `hiddenOn` / `visibleOn` are sugar over `disabled(ctx => ctx.mode === 'edit')` / `hidden(ctx => ctx.mode === 'view')` / `visible(ctx => ['create', 'edit'].includes(ctx.mode))`.
+
+They resolve against page mode (`'table' | 'create' | 'edit' | 'view'`) and no-op on custom Pages (mode is unset). `readonly()` wins over `disabledOn`.
+
+```ts
+TextField.make('email')
+  .disabledOn(['edit'])                  // can set on create, locked on edit
+  .visibleOn(['create', 'edit'])         // never on view
+```
+
+## Conditional visibility
+
+`.visible(rule)` / `.hidden(rule)` / `.disabled(rule)` accept `boolean | (ctx: ConditionContext) => bool | Promise<bool>`:
+
+```ts
+ConditionContext = {
+  record?: unknown                       // current record on edit/view
+  values?: Record<string, unknown>       // form values (only when reactive)
+  user?: unknown                         // from Pilotiq.user()
+  mode?: 'create' | 'edit' | 'view'
+}
+```
+
+```ts
+TextField.make('publishUrl')
+  .visible(({ values }) => values?.status === 'published')
+
+TextField.make('adminNotes')
+  .visible(({ user }) => user.role === 'admin')
+
+TextField.make('signature')
+  .disabled(({ record }) => record?.locked === true)
+```
+
+For visibility that depends on form values to change in real-time, ALSO add `.live()` to the source field — otherwise the dependent field only re-evaluates on submit.
+
+## Display-only transforms
+
+`formatStateUsing(v => …)` runs on the read path (loadRecord → fill) to transform the value for display. It does NOT affect the submitted value:
+
+```ts
+NumberField.make('priceInCents')
+  .formatStateUsing(v => (v / 100).toFixed(2))
+  // user sees "9.99"; column stores 999
+```
+
+For two-way conversion, pair with an accessor / mutator on the underlying model (e.g. `Attribute.make({ get: c => c / 100, set: d => d * 100 })`).
+
+## Mass-assignment + `dehydrated`
+
+Fields submit by default. `dehydrated(false)` excludes the field from the POST body:
+
+```ts
+TextField.make('computedSlug')
+  .dehydrated(false)
+  .formatStateUsing(({ values }) => slugify(values?.title ?? ''))
+```
+
+Useful for derived display, server-computed values, or admin-only debug toggles. The model never receives the field; coerce + validate skip it.
+
+## Common pitfalls
+
+- **`SelectField.options(fn)` without `.live()` upstream** — when options depend on another field via `$get`, the source field must be `.live()` for the dependent options to re-fetch. Otherwise the options resolve once at form load.
+- **`TagsInput` stores `string[]` via JSON-encoded hidden input** — if you read it directly with `parseFormBody`, decode the JSON. The framework's `coerceFormValues` already handles it.
+- **`FileUpload` without an upload adapter** silently hides the drop zone via `RenderContext.hasUploadAdapter`. Wire `panel.uploads({ adapter })` to expose it.
+- **`Repeater.simple(field)` is a different storage shape.** `Repeater.make().schema([TextField.make('value')])` stores `[{ value: 'a' }, { value: 'b' }]`. `Repeater.simple(TextField.make('value'))` stores `['a', 'b']` — flat array. The framework wraps/unwraps internally; the inner schema must be a single field.
+- **`HiddenField` is still in the submitted body** — `dehydrated(false)` exists for the case where you want a value rendered but not submitted (typically for `formatStateUsing` display).
+- **`columnSpan(n)` only works inside a layout that defines a column grid** (`Section.columns(n)` / `Grid.columns(n)`). Bare schema arrays don't grid.

package/boost/skills/pilotiq-fields/rules/reactive-fields.md

@@ -0,0 +1,199 @@
+# Reactive Fields
+
+Forms are static by default — the schema resolves once on page load, the form renders, the user fills + submits. Reactive fields make schema resolution dynamic: fields can re-resolve on every keystroke (`live()`), and a field's value can imperatively update sibling fields via `afterStateUpdated`.
+
+## `Field.live()`
+
+`live()` marks a field as a re-resolve trigger:
+
+```ts
+TextField.make('title')
+  .live()                                          // re-resolve on every change
+  .afterStateUpdated((title, ctx) => ctx.$set('slug', slugify(title)))
+
+SelectField.make('country')
+  .options(countries)
+  .live()
+
+SelectField.make('region')                         // dependent on country
+  .options(({ $get }) => {
+    const country = $get('country')
+    return country ? regionsFor(country) : {}
+  })
+```
+
+When a `live()` field changes:
+
+1. Client POSTs `{ changed: 'title', values: {...} }` to `Form.stateUrl`.
+2. Server runs `applyStateUpdate()` — finds the changed field, runs its `afterStateUpdated` hook (which may `$set` siblings), then re-resolves the form with the updated values.
+3. Server returns the new `FormMeta` (with refreshed conditional visibility, options, helper text).
+4. Client diffs and re-renders.
+
+Tune the trigger:
+
+```ts
+TextField.make('search')
+  .live({ debounce: 300 })                         // wait 300ms after last keystroke
+  .afterStateUpdated((q, ctx) => ctx.$set('results', searchFor(q)))
+
+TextField.make('rawJson')
+  .live({ onBlur: true })                          // only fire on blur, not per keystroke
+```
+
+Bare `.live()` fires immediately on every change.
+
+## `afterStateUpdated`
+
+The server-side hook that fires when a `live()` field changes:
+
+```ts
+TextField.make('title')
+  .live()
+  .afterStateUpdated(async (value, ctx) => {
+    // value: the new value of THIS field
+    // ctx: { $get, $set, values, user, record?, basePath?, row? }
+
+    if (!ctx.$get('slug')) {                       // only auto-fill if blank
+      ctx.$set('slug', slugify(value))
+    }
+  })
+```
+
+The `ctx` API:
+
+- **`$get(name)`** — read another field's current value. Works for nested paths (`$get('contacts.0.email')`).
+- **`$set(name, value)`** — write another field's value. The new value lands in the next `FormMeta` response.
+- **`values`** — snapshot of all form values at this moment.
+- **`row`** — when the hook fires inside a `Repeater` / `Builder` row, this is the row context `{ index, id, values, fieldName, blockType? }`. The plain `$get` / `$set` are scoped to the row — `$set('label', 'X')` writes `items.<row>.label`.
+
+Resolve-time `$set` is a no-op closure during schema re-resolution; only the `afterStateUpdated` write survives. This prevents infinite re-resolve loops.
+
+Throws fail-loudly — the server returns 500 and the client falls back to the previous form state.
+
+## Client-only reactivity: `afterStateUpdatedJs`
+
+For trivial transformations (title → slug, sum of two fields), the server round-trip is overkill. `afterStateUpdatedJs` compiles a string body via `new Function` and runs it in the browser:
+
+```ts
+TextField.make('title')
+  .afterStateUpdatedJs(`$set('slug', $state.title.toLowerCase().replace(/\\s+/g, '-'))`)
+
+NumberField.make('subtotal')
+  .afterStateUpdatedJs(`$set('total', $state.subtotal * 1.0875)`)
+```
+
+The body has these bindings:
+
+- `$state` — the form's current values
+- `$get(name)` / `$set(name, value)` — same shape as the server hook
+- `$value` — the changed field's new value (sugar over `$state[$name]`)
+- `$name` — the changed field's name
+
+Compiled once per source-string (cached via identity in `react/fieldJsHandler.ts`). Runs synchronously on every change. No `live()` required — the JS fires regardless.
+
+Compose with the server hook:
+
+```ts
+TextField.make('title')
+  .live()
+  .afterStateUpdatedJs(`$set('slug', $value.toLowerCase().replace(/\\s+/g, '-'))`)
+  .afterStateUpdated(async (value, ctx) => {
+    // Server-side: validate the auto-slug is unique
+    const existing = await Article.where('slug', ctx.$get('slug')).count()
+    if (existing > 0) ctx.$set('slug', `${ctx.$get('slug')}-${Date.now()}`)
+  })
+```
+
+JS runs first, server response overlays sibling values when it comes back.
+
+Note: `afterStateUpdatedJs` requires CSP `unsafe-eval`. If your CSP is locked down, stick with the server hook.
+
+## Multi-form pages: pin `formId`
+
+The auto-fall-back covers single-form pages. For pages with multiple forms (a record-page with both a "Settings" form and a "Notifications" form), you MUST pin `formId` explicitly:
+
+```ts
+Form.make()
+  .formId('settings')                              // stable across re-renders
+  .schema([...])
+
+Form.make()
+  .formId('notifications')
+  .schema([...])
+```
+
+Without `formId`, the framework can't tell which form's state-update endpoint to POST to — live() silently fails. The auto-fallback uses the page slug; multi-form pages need distinct names.
+
+The same applies to Repeaters / Builders that live inside live() forms — the form's `formId` is what disambiguates them.
+
+## `$get` inside `SelectField.options(fn)`
+
+Dependent options are the most common reactive pattern:
+
+```ts
+SelectField.make('country').options(countries).live()
+
+SelectField.make('region')
+  .options(async ({ $get, user }) => {
+    const country = $get('country')
+    if (!country) return {}
+    return await regionsFor(country)
+  })
+```
+
+The options resolver receives the same `ctx` as `afterStateUpdated`. It runs every re-resolve cycle (so always sees fresh `$get`). Without `live()` on the source, the dependent options resolve ONCE on form load and never update.
+
+## Conditional visibility based on live values
+
+```ts
+SelectField.make('billingType')
+  .options({ none: 'No billing', card: 'Credit card', invoice: 'Net 30' })
+  .live()
+
+TextField.make('cardNumber')
+  .visible(({ values }) => values?.billingType === 'card')
+
+TextField.make('purchaseOrder')
+  .visible(({ values }) => values?.billingType === 'invoice')
+```
+
+Both `visible(({ values }) => …)` rules see fresh `values` on every re-resolve. Without `.live()` on `billingType`, the dependent fields re-evaluate only on submit.
+
+## Reactive fields inside Repeater / Builder
+
+Inside an array-row container, `$get` / `$set` accept dotted paths AND scope to the row by default:
+
+```ts
+Repeater.make('items')
+  .schema([
+    SelectField.make('product').options(products).live(),
+    NumberField.make('quantity').default(1).live(),
+    NumberField.make('lineTotal')
+      .disabled()
+      .afterStateUpdatedJs(`
+        const product = $get('product')
+        const qty = Number($get('quantity'))
+        const price = product ? PRICES[product] : 0
+        $set('lineTotal', price * qty)
+      `),
+  ])
+
+// Or cross-row read with dotted path:
+NumberField.make('discount')
+  .afterStateUpdated((v, ctx) => {
+    const subtotal = (ctx.values.items ?? []).reduce((s, r) => s + (r.lineTotal ?? 0), 0)
+    ctx.$set('total', subtotal - v)
+  })
+```
+
+Inside the row, `$get('product')` reads the row's `product`. Outside the Repeater, `$get('items.0.product')` reads the same value via dotted path.
+
+## Common pitfalls
+
+- **`afterStateUpdated` without `.live()`** only fires on submit. The hook still exists but the partial-resolve endpoint never gets called.
+- **Multi-form pages without `.formId('id')`** — live() silently no-ops because the framework can't route the partial-resolve POST. See `feedback_pilotiq_live_forms_pin_formid.md`.
+- **Infinite loops via cross-`$set`** — if A's `afterStateUpdated` sets B, and B's `afterStateUpdated` sets A, the resolve-time `$set` no-op prevents the loop. But synchronous JS loops in `afterStateUpdatedJs` will hang the browser — write idempotent JS.
+- **`$get` returning `undefined`** — fields not yet rendered or `dehydrated(false)` aren't in `values`. Guard with `?? defaultValue`.
+- **`debounce` on dependent SelectFields** — the source's debounce delays the partial-resolve POST, which delays the dependent's options refresh. For "type to search" patterns, debounce the source 200-400ms.
+- **`afterStateUpdatedJs` CSP** — if your app has a strict CSP without `unsafe-eval`, JS handlers throw at registration. Use the server hook instead.
+- **Reading `values.items` outside a row context** — when reading the full Repeater array from a sibling field (e.g. computing `total` from all rows), use `ctx.values` (the form-wide snapshot), not `$get`. `$get('items')` returns the array; `$get('items.0.qty')` returns one row's field; both work.

package/boost/skills/pilotiq-fields/rules/validation.md

@@ -0,0 +1,198 @@
+# Validation
+
+Validators are functions: `(value, ctx?) => string | null | Promise<string | null>`. Return a message string to fail; return `null` to pass. The framework runs them in declaration order, awaits async ones, and aggregates per-field errors before calling the form's `save` handler.
+
+## Built-in validators
+
+```ts
+import { Field } from '@pilotiq/pilotiq'
+
+TextField.make('email')
+  .validate([
+    Field.required(),                              // or just .required()
+    Field.email(),
+    Field.maxLength(255),
+  ])
+
+TextField.make('password')
+  .password()
+  .validate([
+    Field.required(),
+    Field.minLength(8, 'At least 8 characters'),
+    Field.pattern(/[A-Z]/, 'Must contain an uppercase letter'),
+    Field.pattern(/[0-9]/, 'Must contain a digit'),
+  ])
+
+NumberField.make('age')
+  .validate([
+    Field.min(18, 'Must be 18 or older'),
+    Field.max(120),
+  ])
+
+TextField.make('slug')
+  .validate([
+    Field.required(),
+    Field.pattern(/^[a-z0-9-]+$/, 'Lowercase letters, numbers, hyphens only'),
+  ])
+```
+
+The full set: `required(message?) / email(message?) / minLength(n, message?) / maxLength(n, message?) / min(n, message?) / max(n, message?) / pattern(regex, message)`.
+
+`Field.required()` is auto-contributed when you call `.required()` directly — no need to add it twice.
+
+## Custom validators
+
+A validator is just a function. Inline:
+
+```ts
+TextField.make('username')
+  .validate(async (value, ctx) => {
+    if (typeof value !== 'string') return null
+    if (value.length < 3) return 'At least 3 characters'
+    if (value.startsWith('admin')) return 'Reserved prefix'
+    return null                                    // pass
+  })
+```
+
+The `ctx` shape:
+
+```ts
+{
+  record?: unknown                                 // current record on edit/view
+  values?: Record<string, unknown>                 // all form values
+  user?: unknown
+  mode?: 'create' | 'edit' | 'view'
+  basePath?: string
+}
+```
+
+Async is fine — the framework awaits each one.
+
+## `Field.unique()` async DB probe
+
+The standard "this field must be unique across all records" check:
+
+```ts
+import { Field } from '@pilotiq/pilotiq'
+
+TextField.make('slug')
+  .validate(Field.unique({
+    model: Article,
+    column: 'slug',                              // optional, defaults to field name
+    ignoreRecord: true,                           // skip the row matching ctx.record[pk]
+    where: { status: 'published' },               // optional scope
+    caseInsensitive: true,
+    message: 'Slug is already in use',            // optional custom message
+  }))
+```
+
+How it works:
+
+- Issues `M.query().where(column, value).paginate(1, 2)` — limit 2 to detect uniqueness without scanning the table.
+- `ignoreRecord: true` (default `true`) skips the row matching `ctx.record[primaryKey]` so edit-no-change saves don't conflict.
+- `caseInsensitive: true` switches to SQL `LIKE` with `%` / `_` / `\` escaped (SQLite + MySQL friendly; Postgres collation-dependent).
+- `where: { status: 'published' }` adds AND-clauses to the lookup query (useful for soft scopes — "unique among published rows").
+- Inside a `Repeater`, `unique()` probes the database but does NOT see unsaved sibling rows. Pair with `distinct()` for cross-row uniqueness within the form.
+
+`Field.unique` accepts a `Model`-like object (anything with `.query()`). The Resource doesn't need to be using the same Model.
+
+## `Field.distinct()` cross-row uniqueness inside Repeater / Builder
+
+Inside a `Repeater` or `Builder`, `unique()` only checks the database. To enforce that values are unique ACROSS rows in the form itself (before submit), use `distinct()`:
+
+```ts
+Repeater.make('contacts')
+  .schema([
+    TextField.make('email')
+      .validate(Field.email())
+      .distinct(),                                 // unique within this Repeater
+    TextField.make('label'),
+  ])
+```
+
+Options:
+
+```ts
+TextField.make('email')
+  .distinct({
+    caseInsensitive: true,                         // default false
+    ignoreNulls: true,                             // default true — skip empty rows
+    message: 'Email already used in another row',
+  })
+```
+
+For `Builder`, distinctness is per-block-type — `heading.text="X"` never conflicts with `paragraph.text="X"`.
+
+Pair with `unique({ model })` for in-form + cross-record uniqueness:
+
+```ts
+TextField.make('slug')
+  .validate(Field.unique({ model: Article }))     // unique in DB
+  .distinct()                                      // unique in this form too
+```
+
+## Form-level validators
+
+`Form.validate(fn)` runs after every field's validators have passed:
+
+```ts
+form
+  .schema([
+    DateField.make('startsAt').required(),
+    DateField.make('endsAt').required(),
+  ])
+  .validate(({ values }) => {
+    if (values.endsAt < values.startsAt) {
+      return { endsAt: 'Must be after start date' }
+    }
+    return null
+  })
+```
+
+Return shape:
+- `null` (or `{}`) — pass
+- `{ [fieldName]: 'message' }` — per-field errors (replaces any field-level errors)
+- `{ _form: 'Top-level message' }` — form-wide error, rendered at the top of the form
+
+Form-level validators run AFTER coercion (so values are typed) but BEFORE save.
+
+## Validation order
+
+For each form submit, the framework runs:
+
+1. **Coerce raw FormData values** to typed values (string → number for NumberField, JSON-string → object for KeyValueField, etc.). Coerce errors aren't reported per-field; raw values fall through.
+2. **Field-level validators** — for every Field with `validate([...])` or `.required()`. Aggregated by field name.
+3. **Form-level `validate(fn)`** — if present, runs only when no field errors fired (early exit).
+4. **`save(ctx)` / model.create / model.update** — only reached when validation passes.
+
+Important: **validate runs BEFORE coerce in `dispatchFormSubmit`**, then field-types do their own coerce-fold during their `runValidators`. The order is "validate the raw value, then coerce the validated value" — useful to remember when writing custom validators.
+
+## Errors on the wire
+
+Field errors land on `FormMeta.errors` as `Record<fieldName, string[]>`. The renderer auto-stamps them under each field's input. Repeater/Builder errors key as `items.<i>.<name>` / `name.<i>.data.<child>` respectively; `min/maxItems` lands under the bare field name.
+
+For form-level errors, the `_form` key is special — the renderer surfaces it as an Alert at the top of the form.
+
+## Throwing validators
+
+A validator that throws is treated as a failure. The message comes from `err.message`:
+
+```ts
+TextField.make('email')
+  .validate(async (value) => {
+    if (typeof value !== 'string') throw new Error('Email is required')
+    if (!value.includes('@')) return 'Invalid email'
+    return null
+  })
+```
+
+For unique-across-DB or other async lookups, prefer returning `null` for "skip the check" rather than throwing — throws log + fail with the error message verbatim.
+
+## Common pitfalls
+
+- **`required()` doesn't see `null` as empty** — by default `required()` checks for `value !== null && value !== undefined && value !== ''`. For domain-specific empty (`[]`, `{}`), write a custom validator.
+- **`Field.unique()` without `ignoreRecord: true`** trips on edit-no-change saves — the row's own value conflicts with itself. Default is `true`; only set to `false` for "even my own row counts."
+- **`distinct()` outside a Repeater/Builder** is a no-op. The framework only evaluates it inside an array-row container.
+- **Async validators in parallel** — validators within ONE field run serially in declaration order; validators across DIFFERENT fields run in parallel. Don't rely on cross-field ordering.
+- **`pattern(/regex/)` without anchors** matches anywhere in the string. Add `^…$` if you mean "the whole value."
+- **Validation result `{}`** (empty object) means "pass" — the framework treats no-keys as no-errors. Return `null` for clarity.