@pilotiq/pilotiq 0.23.1 → 0.24.2

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.

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.