@pilotiq/pilotiq 0.24.1 → 0.24.3

package/boost/skills/pilotiq-actions/rules/dispatch-modes.md

@@ -0,0 +1,177 @@
+# Dispatch Modes
+
+Every `Action` has exactly one of four dispatch modes. They're mutually exclusive — calling a setter from a different mode replaces the prior choice. Pick the mode by what the action does, not where it appears.
+
+## 1. `href(url)` — link
+
+```ts
+Action.make('docs')
+  .label('Documentation')
+  .icon('book')
+  .href('https://docs.example.com')
+```
+
+Renders as `<a href>`. No server round-trip. Cmd+click / right-click "open in new tab" works because it's a real anchor.
+
+`.openInNewTab()` adds `target="_blank" rel="noopener"`. `.tooltip(text)` adds a hover hint.
+
+Use for: external doc links, marketing CTAs, sibling-app deep links.
+
+## 2. `method(verb).action(url)` — form-post
+
+```ts
+Action.make('archive')
+  .label('Archive')
+  .color('warning')
+  .method('POST')
+  .action(`${base}/articles/${row.id}/archive`)
+  .confirm('Archive this article? You can restore it later.')
+```
+
+Renders as a hidden `<form>` with a submit button. The form body is empty (or carries `Action.formField(name, value)` pairs — see below). Server responds 303 → browser follows → page re-renders.
+
+This is the **only mode that survives no-JavaScript clients** — useful for back-compat with progressively-enhanced flows or for actions that must remain accessible from raw HTML email links. The framework's `Action.delete` factory ships in this mode for that reason.
+
+`.confirm(message)` wraps the submit in a confirmation Dialog. The submit doesn't fire until the user OKs.
+
+## 3. `handler(ctx => …)` — JSON dispatch
+
+```ts
+Action.make('publish')
+  .label('Publish')
+  .color('primary')
+  .icon('send')
+  .handler(async (ctx) => {
+    const article = await ArticleModel.find(ctx.record.id)
+    article.publishedAt = new Date()
+    await article.save()
+    return {
+      notify: { title: 'Published', body: article.title, kind: 'success' },
+      redirect: `${ctx.basePath}/articles/${article.id}/edit`,
+    }
+  })
+```
+
+Clicking POSTs `Accept: application/json` to `{basePath}/{slug}/_action/{name}`. The framework routes through `dispatchAction(action, body, ctx)`, calls the handler, normalizes the return shape, ships it back.
+
+**Return shape** (all keys optional):
+
+```ts
+{
+  notify?:        NotificationLike | NotificationLike[],
+  redirect?:      string,                    // URL to navigate to after success
+  download?:      { filename, contentType, body },  // triggers <a download> on the client
+  ok?:            boolean,                   // false short-circuits to error toast
+  error?:         string,                    // surfaced as toast when ok:false
+  // ...any extras get round-tripped via additional ActionResult slots
+}
+```
+
+Client-side: drains notifications via `useToast()`, then `useNavigate(redirect)`. **No page reload** — SPA-only flow. If the response carries a `download` payload, the framework synthesizes a temporary `<a download>` blob and clicks it.
+
+**`ctx` shape:**
+
+```ts
+{
+  user:       OpaqueUser | null,         // from Pilotiq.user() resolver
+  record?:    Record,                    // row placement — current row
+  records?:   Record[],                  // bulk placement — selected rows
+  basePath:   string,                    // panel base ("/admin")
+  resource?:  ResourceLike,              // when in a resource scope
+  relation?:  { parent, parentId, relationship },  // when inside a relation manager
+  body?:      unknown,                   // raw POST body (FormData-parsed) — modal-form values land here
+}
+```
+
+Use for: anything that needs server work but is conceptually a one-shot operation, not a page navigation.
+
+## 4. `submit()` — trigger an enclosing form
+
+```ts
+// inside CreatePage.getFormActions(R)
+Action.make('createAnother')
+  .label('Create & create another')
+  .outlined()
+  .submit()
+  .formField('_continueCreate', '1')      // rides the form body so the handler can branch
+```
+
+Renders as `<button type="submit">`. No dispatch URL — it submits the enclosing `<form>`. Used in page headers / form footers where the form already wires its own POST.
+
+`.form(formId)` targets a form outside the natural enclosing `<form>` (HTML `form=` attribute). Useful when the submit button lives in the page header but the form lives further down the tree.
+
+`.formField(name, value='1')` attaches a hidden `name`/`value` pair to the form body — the click sets `event.submitter` so `new FormData(form, submitter)` picks it up. Confirm-gated submits intentionally **don't** honor `formField` (programmatic `requestSubmit()` has no submitter).
+
+## Modal-form actions (flavor of handler)
+
+Add `.schema([Field, …])` to a handler action and it switches to modal-form mode:
+
+```ts
+Action.make('addNote')
+  .label('Add note')
+  .icon('plus')
+  .schema([
+    TextField.make('subject').required(),
+    TextareaField.make('body').required(),
+    SelectField.make('priority').options({ low: 'Low', med: 'Med', high: 'High' }).default('med'),
+  ])
+  .handler(async (ctx) => {
+    // ctx.body has the parsed + validated form values
+    await Note.create({ ...ctx.body, articleId: ctx.record.id })
+    return { notify: { title: 'Note added', kind: 'success' } }
+  })
+```
+
+Clicking the trigger opens a Dialog with the schema mounted as a real pilotiq form. Submit fetches `Accept: application/json`. Server responses:
+
+- **200 `{ ok: true, redirect, notifications }`** — drain notifications, SPA-navigate.
+- **422 `{ ok: false, errors: { field: [msg, …] } }`** — stamp inline field errors.
+- **5xx `{ ok: false, error }`** — error toast.
+
+The form runs every `pilotiq-fields`-style validator (required / email / unique / distinct) before reaching the handler. Field-level `live()` works inside the modal.
+
+### Modal chrome
+
+12 setters customize the modal:
+
+```ts
+Action.make('addNote')
+  .modalHeading('Add a note')
+  .modalDescription('Notes are visible to all editors.')
+  .modalIcon('sticky-note')
+  .modalIconColor('warning')
+  .modalWidth('lg')                       // 'sm' | 'md' | 'lg' | 'xl' | '2xl' | '3xl' | '4xl' | 'screen'
+  .modalSubmitActionLabel('Save note')
+  .modalCancelActionLabel('Discard')
+  .modalCloseable(false)                  // user can't close via Esc / outside-click
+  .modalContentFooter([                    // Element[] rendered below the form body
+    Text.make('Notes auto-archive after 90 days.').size('xs').color('muted'),
+  ])
+  // …
+```
+
+Setters with no special chrome you want, just omit — sensible defaults ship.
+
+## Confirm
+
+Both handler and method modes accept `.confirm(message)`:
+
+```ts
+Action.make('publish')
+  .handler(/* … */)
+  .confirm('Publish this article? It will be visible to everyone.')
+```
+
+`.modalConfirmIcon` / `.modalConfirmIconColor` customize the chrome. Confirm dialogs share the same `<ActionModalDialog>` primitive as modal-form — the difference is content: confirm shows a message + Cancel/OK; modal-form mounts a `<FormFields>`.
+
+## Pitfalls
+
+- **`.handler()` on a method action.** Calling `.method('POST').action(...)` then `.handler(...)` will override the method, NOT compose — handler wins. Pick one mode.
+- **`.submit().formField(...)` with `.confirm(...)`.** Confirm-gated submits use `form.requestSubmit()` programmatically, which doesn't carry a `submitter`. The `formField` pair will silently drop. If you need both, use `.handler()` + `.confirm()` instead.
+- **Modal-form fields inside the modal can't access the outer page's form state.** The modal is a fresh form scope; `$get('outerFieldName')` won't see the page's form. If you need cross-form data, pass it via `ctx.record` instead.
+- **Handler returns are async-aware but not stream-aware.** Don't expect to ship progressive output from a long-running handler. For batch operations that take >5s, return immediately with `{ notify: 'Queued', redirect }` and process out-of-band.
+
+## See also
+
+- `visibility-and-authorization.md` — gating which dispatch modes fire for which user / record.
+- `factories.md` — pre-built factories you usually want instead of writing dispatch from scratch.

package/boost/skills/pilotiq-actions/rules/factories.md

@@ -0,0 +1,130 @@
+# Built-in Action Factories
+
+Pilotiq ships ~25 pre-built `Action.*` factories for the operations every admin panel needs. They handle dispatch wiring, visibility gating, chrome, and notification copy — most of the time you reach for one of these instead of `Action.make(...)`.
+
+## CRUD basics (single row)
+
+```ts
+import { Action } from '@pilotiq/pilotiq'
+
+Action.create(R, base)              // header — "Create <Label>"; href = `${base}/${slug}/create`
+Action.edit(R, base, recordId)      // row — pencil icon; href = `${base}/${slug}/:id/edit`
+Action.view(R, base, recordId)      // row — eye icon; href = `${base}/${slug}/:id`
+Action.delete(R, base, recordId)    // row — trash icon; method POST → `${base}/${slug}/:id/delete` with .confirm()
+```
+
+Each delegates visibility to the matching Resource policy (`canCreate` / `canEdit` / `canView` / `canDelete`) automatically — see `visibility-and-authorization.md` § Composing with Resource policies.
+
+## Replicate
+
+```ts
+Action.replicate(R, base, recordId, {
+  excludeAttributes:    ['name', 'slug'],     // strip these in addition to PK + soft-delete column
+  beforeReplicaSaved:   async (replica, source) => {
+    replica.name = `Copy of ${source.name}`
+    replica.slug = await generateSlug(replica.name)
+  },
+  getCreatedNotificationTitle: ({ replica, source }) => `Cloned "${source.title}"`,
+  getRedirectUrl:       ({ replica }) => `${base}/articles/${replica.id}/edit`,
+})
+```
+
+Clones the source row via `R.model.create(...)`. Strips PK + soft-delete column + `opts.excludeAttributes`, runs `beforeReplicaSaved` to mutate, persists, redirects to the new record's edit page. Visibility delegates to `R.canCreate`.
+
+`Action.bulkReplicate(R, base, opts?)` is the bulk variant — iterates `ctx.records`, applies the same strip-mutate-create pipeline per row, skips rows that throw or fail per-row `canCreate`, notifies with the count.
+
+`opts.getCreatedNotificationTitle` and `opts.getRedirectUrl` are both sync-or-async; receive `{ replica, source }` (single) or `{ count, records }` (bulk). Returning `undefined` falls back to the default copy. Empty string is honored — won't be swallowed by `??`.
+
+## Soft delete (when `Resource.softDeletes = true`)
+
+```ts
+Action.restore(R, base, recordId)            // row — only visible on trashed rows
+Action.forceDelete(R, base, recordId)        // row — only visible on trashed rows; method POST with .confirm()
+
+Action.bulkRestore(R, base)                  // bulk — restores selected trashed rows
+Action.bulkForceDelete(R, base)              // bulk
+```
+
+`Action.delete` auto-hides on already-trashed rows (per Plan #13 soft-delete wiring); restore / forceDelete auto-hide on non-trashed rows. The toggling is structural, not optional — opt out by overriding `.visible()` after the factory.
+
+## Import / Export
+
+```ts
+Action.export(R, base, {
+  format:    'csv',                                  // 'csv' | 'json'
+  columns:   ['id', 'title', 'publishedAt'],         // omit → all columns from R.table()
+  filename:  () => `articles-${new Date().toISOString().slice(0, 10)}.csv`,
+})
+
+Action.bulkExport(R, base, opts?)                    // bulk — exports only selected rows
+
+Action.import(R, base, {
+  format:     'csv',                                 // omit → auto-detect from filename
+  upsertBy:   ['email'],                             // turns it into an upsert action; mode-select appears in the modal
+  maxRows:    10_000,                                // default cap
+})
+```
+
+`Action.export` reads from the resource's `Table.records(ctx)` (so filters / search / sort flow through); writes the body to a `download` envelope that the client synthesizes as `<a download>`. CSV via the in-tree `src/io/csv.ts` (RFC 4180, in-memory only).
+
+`Action.import` auto-builds a modal-form schema with a `FileUpload` field (and a `Mode` select when `upsertBy` is set). Handler reads `ctx.values.file`, fetches the URL the upload stamped, parses CSV/JSON, walks rows through `R.model.create` (or `R.model.update` for matched upserts). Per-row `validate / beforeCreate / beforeUpdate` lifecycle hooks fire from the resource's form config. Partial-failure-soft: rows that throw / fail validate accumulate in `summary.errors` and the import keeps going. v1 has **no transaction wrapper** — partial imports leave the DB in a partially-applied state.
+
+## Relation factories (inside RelationManagers)
+
+```ts
+// inside a RelationManager static table(table, ctx)
+Action.relationCreate(M, ctx)                        // header — "Create <Label>"; opens create form in tab
+Action.relationEdit(M, ctx, recordId)                // row — pencil
+Action.relationDelete(M, ctx, recordId)              // row — trash
+Action.relationRestore(M, ctx, recordId)             // row — soft-delete trash only
+Action.relationForceDelete(M, ctx, recordId)         // row — soft-delete trash only
+
+Action.relationReplicate(M, ctx, recordId, opts?)
+Action.relationBulkReplicate(M, ctx, opts?)
+
+// M2M only (auto-hide outside `belongsToMany / morphToMany / morphedByMany`)
+Action.relationAttach(M, ctx)                        // header — modal-form picker
+Action.relationDetach(M, ctx, recordId)              // row
+Action.relationBulkDetach(M, ctx)                    // bulk
+```
+
+`ctx` is the `RelationManagerContext` injected into `M.table(table, ctx)` — it carries `basePath / parentSlug / parentId / relationship / parentRecord / related? / mode`. The factories thread URLs + parent attachment automatically.
+
+`relationReplicate` force-pins the parent FK back onto the replica AFTER strip + BEFORE `beforeReplicaSaved`, so a tampered source row can't slip a different parent in by riding its own FK column. Auto-hides on M2M (replicate doesn't fit pivot semantics) and on `morphTo` (no single owner to pin to).
+
+For the broader RelationManager surface (when to override `canDelete` vs `canDetach`, how `ctx.mode` derives), see [[pilotiq-relations]].
+
+## Common chrome customizations
+
+The factory result is just an `Action` instance — every chain method composes after the factory call:
+
+```ts
+Action.delete(R, base, row.id)
+  .label('Move to trash')                   // override default copy
+  .color('warning')                          // override 'destructive'
+  .tooltip('Trashed items auto-purge after 30 days')
+  .confirm('Move this article to trash?')   // override default confirm copy
+  .visible(({ user }) => user?.role === 'admin')
+```
+
+The `.visible()` you set wins over the factory's auto-attached policy gate.
+
+## When NOT to use a factory
+
+- **Custom modal-form** — the import factory's modal schema is fixed (FileUpload + maybe Mode). For richer modals (multi-field policy decisions, conditional reactivity), use `Action.make('foo').schema([…]).handler(…)` directly.
+- **Cross-record orchestration** — bulk factories iterate row-by-row. For "select 50 rows, run one SQL UPDATE" semantics, write a handler that consumes `ctx.records` and dispatches a single ORM call.
+- **Compound flows** — anything that needs multi-step UX (confirm → modal-form → second confirm) doesn't compose from factories. Build it from `Action.make()` primitives.
+
+## Pitfalls
+
+- **`opts.beforeReplicaSaved` mutates a plain object, not a model instance.** It's `Record<string, unknown>`, pre-create. Don't expect `replica.save()` / lifecycle hooks — those are framework-internal post-mutation.
+- **Bulk factories don't wrap in a transaction.** Partial failures leave the DB partially updated. The notification shows the count succeeded; the rest accumulate in `summary.errors`. If you need atomicity, write a handler that opens a transaction explicitly via your ORM.
+- **`Action.import`'s `upsertBy` requires `R.model.update` to exist.** Without it, the import will throw on the first matching row. Boot-time guard catches the missing method.
+- **Relation factories' `ctx.mode` lies about `morphOne` / `hasOne`.** Both collapse into `'hasMany'` for action dispatch — `morphOne / hasOne` semantically still allow one child, but the factory shape is the same.
+
+## See also
+
+- `dispatch-modes.md` — what each factory does under the hood.
+- `visibility-and-authorization.md` — how factory auto-visibility composes with manual `.visible()`.
+- [[pilotiq-relations]] — broader RelationManager + `Repeater.relationship` patterns.
+- [[pilotiq-resource]] — the `Resource.softDeletes` + `can*` static surface that factories key off.

package/boost/skills/pilotiq-actions/rules/visibility-and-authorization.md

@@ -0,0 +1,125 @@
+# Visibility & Authorization
+
+Every action exposes four conditional setters. They differ in *intent*; all use the same predicate shape.
+
+```ts
+type VisibilityRule =
+  | boolean
+  | ((ctx: ActionVisibilityContext) => boolean | Promise<boolean>)
+
+type ActionVisibilityContext = {
+  record?:  Record               // present on row-placement
+  records?: Record[]             // present on bulk-placement
+  user?:    OpaqueUser | null    // from Pilotiq.user()
+}
+```
+
+## The four setters
+
+```ts
+Action.make('publish')
+  .visible(({ record, user }) => !record.publishedAt && user?.role === 'editor')
+  .hidden(({ record }) => record.archived)
+  .disabled(({ record }) => record.locked)
+  .authorize(async ({ user, record }) => await canPublish(user, record))
+```
+
+- **`.visible(rule)`** — mounts the button only when rule resolves truthy. Default: visible.
+- **`.hidden(rule)`** — sugar inverse of `visible`. Last write wins; if you set both, the more recent setter is the active one.
+- **`.disabled(rule)`** — renders the button but as a non-interactive (greyed) chip. The user sees it exists but can't fire it.
+- **`.authorize(rule)`** — semantically equivalent to `.visible()` but reads as a permission gate at call sites. Use when the predicate is policy-shaped (`canEdit`, `canDelete`).
+
+`visible` + `authorize` both gate *presence*. Composing them is fine; both must resolve truthy. Default is `true` for both, so omitting them leaves the action always-visible.
+
+## Fail-closed semantics
+
+Predicates that throw or reject → button hides (or for `.disabled`, treats as disabled-true). This is the **opposite** of the layout `visible()` posture in `pilotiq-fields`, which fails *open* for in-progress data safety. Actions are operations, not data — silently hiding a bad button is safer than rendering one with broken logic.
+
+```ts
+Action.make('publish')
+  .visible(async ({ record }) => {
+    if (!record) throw new Error('record missing')   // silently hides; no toast, no log
+    return record.status === 'draft'
+  })
+```
+
+If you want errors loud, log inside the predicate yourself. Don't expect a framework-level toast.
+
+## Per-row gating on tables
+
+Row-placement actions evaluate predicates **per row** during `loadTableRecords`. The framework:
+
+1. Walks the registered row actions (from `Resource.table().recordActions([…])` or page-override `getRowActions()`).
+2. Filters to actions with at least one conditional rule (`visible` / `hidden` / `disabled` / `authorize`).
+3. Calls each rule in parallel via `Promise.all` for each row.
+4. Stamps the row with `_visibleActions: name[]` (names that resolved truthy on visible/authorize) and `_disabledActions: name[]` (names that resolved truthy on disabled).
+5. The renderer's `renderRowActions` filters its strip against `_visibleActions` and applies disabled styling per `_disabledActions`.
+
+**Performance** — every conditional rule × every row × every page load. Heavy predicates (DB queries, network calls) inside `visible()` will dominate list-page latency. Prefer reading from the row record itself when possible:
+
+```ts
+// Cheap — reads from the record server-side stamped fields
+.visible(({ record }) => record.status === 'draft')
+
+// Expensive — DB query per row
+.visible(async ({ record }) => await UserPolicy.canEdit(user, record))
+```
+
+If you need expensive checks, stamp the result on the row via `Column.formatStateUsing` upstream and read from `record._formatted[col]` instead.
+
+## Bulk-placement gating
+
+Bulk-action predicates receive `records: Record[]` instead of `record`. They evaluate ONCE per page render (against the rendered row set), not per row:
+
+```ts
+Action.make('bulkDelete')
+  .label('Delete selected')
+  .color('destructive')
+  .handler(async ({ records, user }) => {
+    for (const r of records) {
+      if (!await canDelete(user, r)) continue
+      await Article.delete(r.id)
+    }
+    return { notify: { title: `Deleted ${records.length}`, kind: 'success' } }
+  })
+  .visible(({ user }) => user?.role === 'editor')      // gates the bulk button
+```
+
+For *per-row* exclusion inside a bulk handler, the convention is: iterate `records` in the handler, run the per-row predicate yourself, skip / accumulate errors. The framework doesn't pre-filter `records` against row-side predicates — the bulk button either shows or doesn't, and the handler owns row-level safety.
+
+## Composing with Resource policies
+
+Resource statics (`canView` / `canEdit` / `canDelete` / `canCreate` etc.) return `boolean | Promise<boolean>` against `(user, record?)`. Built-in factories (`Action.delete`, `Action.edit`, `Action.replicate`) auto-attach a `.visible()` rule that consults the matching policy:
+
+```ts
+// Resource
+class ArticleResource extends Resource {
+  static async canDelete(user, record) {
+    return user?.role === 'editor' && !record.locked
+  }
+}
+
+// page-override row actions
+Action.delete(ArticleResource, base, row.id)
+// equivalent to: Action.make('delete').method('POST').action(...).visible(({ record, user }) => ArticleResource.canDelete(user, record))
+```
+
+Override the auto-attach by setting `.visible(...)` explicitly — your setter wins.
+
+## Async + parallel
+
+All four predicates may be `async`. Per-row eval runs every row's predicates in parallel via `Promise.all`. Don't fan-out further inside a predicate — each row already pays one round-trip if you go async. Batch reads upstream if you need them.
+
+## Pitfalls
+
+- **`hidden(true)` does NOT permanently hide.** It's just the inverse of `visible(true)`. To permanently disable an action conditionally on config rather than data, hide it at the schema-builder level (don't include it in `recordActions([…])` at all).
+- **`disabled(true)` still POSTS if you mount it elsewhere.** The disabled flag is purely chrome. The action's dispatch URL is still live server-side — if a user crafts the POST manually, the handler still fires. Always gate inside the handler too for security.
+- **Predicates can see `record` as `undefined`** when an action is placed in a context that doesn't have a record (e.g. inline placement on a non-row page). Guard with `if (!record) return false` or use `?.` chaining.
+- **`user` may be `null`** when no user resolver runs or the resolver returns null. Predicates that need a user must guard.
+- **Don't read mutable state in predicates** (counter increments, request-scoped caches). They run multiple times per render in parallel — the same predicate may fire 5× concurrently for 5 rows.
+
+## See also
+
+- `dispatch-modes.md` — what the button does when allowed to fire.
+- `factories.md` — built-in factories auto-attach visibility rules; this rule covers the manual setter form.
+- `pilotiq-resource/rules/authorization.md` — Resource-level `can*` policies that feed factory auto-visibility.

package/boost/skills/pilotiq-fields/SKILL.md

@@ -0,0 +1,47 @@
+---
+name: pilotiq-fields
+description: Form fields in pilotiq — the 24 built-in field types, common setters, validators, and reactive ($get/$set + live + afterStateUpdated) patterns
+license: MIT
+appliesTo:
+  - '@pilotiq/pilotiq'
+trigger: defining or editing a form field inside a `Resource.form()` schema — `TextField` / `SelectField` / `Repeater` / etc., setting `validate()` / `unique()` / `distinct()`, or wiring reactive `live()` / `afterStateUpdated`
+skip: working with read-only display primitives (`TextEntry` / `BadgeEntry` / etc.) — those are infolist entries, not form fields
+metadata:
+  author: pilotiq
+---
+
+# Pilotiq Fields
+
+## When to use this skill
+
+Load when you're:
+
+- Picking a field type for a form (text vs textarea vs markdown vs richtext, single-select vs multi-select)
+- Setting common chrome — labels, placeholders, helper text, prefixes, suffixes
+- Adding validators (`required`, `email`, `min/maxLength`, `pattern`, `unique`, `distinct`)
+- Wiring reactive behavior — `live()` to re-resolve schema on change, `afterStateUpdated()` to imperatively update sibling fields
+
+For Resource-level concerns (when to override `form()` itself), use `pilotiq-resource`. For relation-backed array fields (`Repeater.relationship()`), see `pilotiq-relations`.
+
+## Quick Reference
+
+| Task | Open |
+|---|---|
+| Field types — full catalog of 24 built-ins, when to use each | `rules/field-catalog.md` |
+| Validation — built-in validators, `unique()` async DB probe, `distinct()` cross-row uniqueness | `rules/validation.md` |
+| Reactive fields — `live()`, `afterStateUpdated`, `afterStateUpdatedJs`, `$get` / `$set`, multi-form `formId` | `rules/reactive-fields.md` |
+
+## Key concepts (load once)
+
+- **Every field is a static `make(name)` builder.** `TextField.make('title').required().label('Title')` — the `name` is the form field name AND the model column name.
+- **Common setters cascade from `Field` base.** `.label() / .helperText() / .placeholder() / .default() / .prefix() / .suffix() / .required() / .validate() / .visible() / .hidden() / .disabled() / .columnSpan() / .live() / .afterStateUpdated() / .dehydrated() / .formatStateUsing() / .autofocus() / .hiddenLabel() / .disabledOn() / .hiddenOn() / .visibleOn()` work on every subclass.
+- **Operation-aware shortcuts.** `disabledOn(['edit'])` / `hiddenOn(['view'])` / `visibleOn(['create', 'edit'])` resolve against page mode (`'create' | 'edit' | 'view'`). They no-op on custom Pages (mode unset). `readonly()` still wins over `disabledOn`.
+- **Validators are async.** `Validator = (value, ctx?) => string | null | Promise<string | null>` — return a message string to fail, `null` to pass. `validateSchema()` awaits each field's validators in declaration order.
+- **Reactive fields require `live()`.** Without it, `afterStateUpdated` only fires on submit. With it, every change POSTs to a partial-resolve endpoint that re-runs the schema with fresh `$get/$set` state.
+- **Live forms must pin `formId`.** `Form.make().formId('details')` is required when more than one form lives on a single page. The auto-fallback covers single-form pages.
+
+## Examples
+
+- `playground/app/Pilotiq/Articles/Schemas/form.ts` — typical form with TextField / Textarea / SelectField / DateField.
+- `playground/app/Pilotiq/Posts/Schemas/form.ts` — reactive fields (`live()` + `afterStateUpdated`) for title→slug.
+- `playground/app/Pilotiq/BlocksDemo/Schemas/form.ts` — Builder field with heterogeneous block types.