npm - @voltro/cli - Versions diffs - 0.52.0 → 0.53.0 - Mend

@voltro/cli 0.52.0 → 0.53.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (195) hide show

package/templates/agent-docs/schema-driven-ui.md CHANGED Viewed

@@ -173,8 +173,10 @@ A combined create-or-edit screen is a three-line wrapper:
 ### The customization ladder
 - **Rung 0 — zero config.** Fields render from the schema: a `Schema.Literal`
-  union → `select`; string → text; boolean → checkbox; `Date` → date; nested
-  object → a `custom` placeholder asking for a render-prop.
+  union → `select`; string → text; boolean → checkbox; `Schema.Date` → date;
+  a nested struct → a real `<fieldset>` SECTION with its legend and dotted
+  fields; widgets receive `onBlur`, so errors reveal on leave-field exactly
+  like the headless binding.
 - **Rung 1 — one custom widget** via a `<Field>` render-prop:
   ```tsx
   import { AutoForm, Field, AsyncSelect } from '@voltro/ui'
@@ -214,6 +216,189 @@ Schema.Struct({
 })
 ```
+### Validation — one schema, translated messages, server field errors
+Client and server validate the SAME input schema, and the messages a user
+sees are structured, not developer text. Every failed check maps to a stable
+message id with params — `validation.required`, `validation.minLength {min}`,
+`validation.minValue {min}` — rendered through a built-in en/de catalog. The
+locale follows `<html lang>` (the framework's locale contract); override it
+per form with `locale:`, or wire your own catalog in one line:
+```tsx
+// ONCE, at the app root — every form under it resolves ids through your catalog
+<ValidationMessagesProvider messages={(id, params) => t(id, params)}>
+  <App />
+</ValidationMessagesProvider>
+```
+A per-form `messages:` option still exists and wins over the provider; a
+resolver returning `undefined` falls through to the built-ins per id, so a
+partial catalog costs nothing.
+A widget kit that resolves ids itself reads the same resolver with
+`useValidationMessages()`. It returns the provider's function, or
+`undefined` when no provider is mounted — so a kit can fall through to the
+built-in catalog instead of shipping its own.
+Errors key the FULL field path (`address.city`, `entries.0.startsAt`), and a
+`message` annotation on a schema may BE an id with params — as may the issues
+a struct-level `filter` returns, which land at THEIR field:
+```ts
+const Input = Schema.Struct({
+  name: Schema.String.pipe(Schema.minLength(2)),
+  startsAt: Schema.Number,
+  endsAt: Schema.Number,
+}).pipe(
+  Schema.filter((v) =>
+    v.startsAt < v.endsAt ? undefined : [{ path: ['endsAt'], message: 'validation.beforeStart' }],
+  ),
+)
+```
+**Server-side rules route to their field too.** An executor raises a typed
+field error through the always-present `ctx.validation` — no declaration
+needed, `ValidationError` is auto-merged into every mutation's and action's
+wire error union exactly like `ScopeError`:
+```ts
+// executor
+if (await emailTaken(input.email)) {
+  return yield* ctx.validation.fail('email', 'validation.emailTaken')
+}
+yield* ctx.validation.require(input.startsAt < input.endsAt, 'endsAt', 'validation.beforeStart')
+// several at once: ctx.validation.failAll([{ field, message }, …])
+```
+The binding routes it: the message lands in `errors.email` (translated
+through the same catalog), the form stays editable, and `submitError` only
+carries what NO field can — a `BusinessRuleViolation` whose rule pinpointed
+a `field` routes the same way. Custom widget kits get the same judgement via
+`fieldIssuesOf(error)` from `@voltro/protocol`.
+**Async checks gate the submit.** Bind a uniqueness probe to its field and
+`submit` waits for it — an `invalid` verdict blocks with the message on that
+field, an unsettled check fails closed after 5s:
+```tsx
+const email = useAsyncValidation('app', 'users.emailAvailable', values.email ?? '', {
+  interpret: (r) => ({ valid: (r as { available: boolean }).available, message: 'Email taken' }),
+})
+const form = useFormBinding('app', 'users.create', { asyncFields: { email } })
+```
+**The binding is typed — `toInput` included.** `createHooks<AppProcedures>('app')`
+returns `useFormBinding` beside the other hooks — tag as a literal type,
+`values`/`defaults` and the submit output inferred from the descriptor. With
+`toInput`, the form gets its OWN `Values` shape and the mapper's return is
+checked against the mutation's input by the compiler — a mapping that stops
+producing the wire shape is a type error, not a runtime refusal.
+### The full binding — nested values, arrays, timing, one state
+`useFormBinding` carries a complete form, not just flat fields. Nested structs
+flatten into SECTIONS (`address.city`, grouped under `section('address')`),
+arrays of structs become field arrays, and every field is reachable as a
+bound handle a widget kit spreads onto its input:
+```tsx
+const form = useFormBinding('app', 'employees.update', {
+  defaults: fromRow(employee),
+  toInput: (values) => ({ id: employee.id, ...employeePatch(values) }),
+  errorPath: { fullName: 'name' },
+})
+const city = form.field('address.city')   // { value, setValue, onBlur, error, required, label, a11y, … }
+form.array('entries').push({ startsAt: '' })
+form.section('address')                    // the section's descriptors
+form.state                                 // { isDirty, canSubmit, isSubmitting, isSubmitSuccessful, submissionAttempts, errorCount, pending, … }
+form.reset(nextDefaults)                   // switch the edited record without a remount
+form.focusFirstInvalid()
+```
+**Error timing has defaults a form can trust:** a form NEVER opens with
+errors — a field reveals its error after ITS blur or after the first submit
+attempt, then live (`validate: { onChange: 'afterTouched' }`; `'always'` and
+`'never'` exist). `isValid`/`canSubmit` always tell the truth underneath, so
+the save button disables correctly while the user is not yet being scolded.
+**Values ≠ mutation input:** `toInput` maps form values to the wire input
+BEFORE validation; input-schema issues route back to form fields via
+`errorPath` (same-name fields map automatically). For composed saves,
+`onSubmit: async ({ input, values, mutate }) => …` owns the write and keeps
+optimistic + error routing.
+**Per-field rendering:** with `subscribe: 'fields'` the binding only
+re-renders on submission-level changes, and each field component subscribes
+narrowly:
+```tsx
+const BoundField = ({ form, path }: { form: FormBinding<Record<string, unknown>, unknown>; path: string }) => {
+  const f = useFormField(form, path)
+  return <input id={f.a11y.id} value={String(f.value ?? '')} onChange={(e) => f.setValue(e.target.value)} onBlur={f.onBlur} aria-invalid={f.a11y['aria-invalid']} />
+}
+```
+Annotate structure on the schema itself: `formField({ section, order, label,
+widget })` rides an annotation, `description` becomes help text, and
+`Schema.Date` / `Schema.DateTimeUtc` map to date/datetime widgets. The engine
+underneath is an implementation detail — no engine type appears in the public
+API, and production builds stub its devtools channel automatically.
+### Reference fields, uploads, and testing the form
+**Reference fields.** Mark a schema field as a table reference and it renders
+as a picker-shaped field whose VALUE stays the id (or id list — which is
+exactly what a target's declared `relations:` consumes):
+```ts
+const EmployeesUpdateInput = Schema.Struct({
+  id: Schema.String,
+  storeId: Schema.String.annotations(formField({ reference: 'stores' })),
+  assignedStores: Schema.Array(Schema.String).annotations(formField({ reference: 'stores' })),
+})
+```
+The descriptor carries `widget: 'reference'` + `reference: 'stores'`; bind
+the shipped `<AsyncSelect>` (or your own picker) to it via a render-prop —
+the default registry deliberately renders the render-prop note, because a
+live picker needs a query binding only the app can name.
+**Uploads as field values.** `useUpload` returns a `fileId`; hold it in a
+field and LINK it in the submit — the composed save is what `onSubmit` is
+for, so the upload that never got attached cannot happen silently:
+```tsx
+const form = useFormBinding('app', 'tasks.create', {
+  onSubmit: async ({ input, values, mutate }) => {
+    const row = await mutate(input)
+    // attachments: [...existing, ...uploaded fileIds] — linked HERE, not forgotten
+    return row
+  },
+})
+```
+**Leaving a dirty form** is guarded by the router: `useBlocker(form.state.isDirty)`
+holds SPA navigations (Back button included) and arms the native
+`beforeunload` prompt — see the routing docs.
+**Testing.** `renderFormBinding` (from `@voltro/testing/client`) drives the
+REAL binding against a fake api — fill, blur, submit, read the visible
+errors; a mutation handler that throws `ValidationError({ field })`
+exercises the same routing path a server refusal takes:
+```ts
+const form = await renderFormBinding('users.create', {
+  binding: { schema: UsersCreateInput },
+  mutation: () => { throw new ValidationError({ field: 'email', message: 'validation.emailTaken' }) },
+})
+await form.submit()
+expect(form.errors()['email']).toBe('validation.emailTaken')
+```
+Runs under jsdom (`// @vitest-environment jsdom`).
 ### Forms without JavaScript
 On a server-rendered page, `<AutoForm>` works with JavaScript disabled — or not
@@ -720,7 +905,33 @@ multi-device CRDT (single-user/device, honest about its limits).
 ```tsx
 const outbox = useOutbox({ send })
-// → { queue, enqueue, replay, online, pending, conflicts }
+// → { queue, enqueue, replay, online, pending, conflicts, resolveConflict }
+```
+**Durable across reloads.** Pass `persistence` and the queue survives:
+entries rehydrate on mount, every transition persists (delivered entries are
+compacted away), and a failing backing degrades to the in-memory behaviour
+instead of breaking the outbox. The one real implementation is
+`outboxPersistence()` from `@voltro/local-first`, backed by the same
+`PersistenceAdapter` the sync engine drains — one durable queue per device:
+```tsx
+import { createIndexedDbPersistence, outboxPersistence } from '@voltro/local-first'
+const adapter = await createIndexedDbPersistence()
+const outbox = useOutbox({ send, persistence: outboxPersistence(adapter) })
+```
+**Resolving a conflict.** A conflicted entry blocks everything behind it
+(causality). `resolveConflict(id, input)` replaces its input with the RESOLVED
+value, returns it to pending and replays — typically computed with
+`resolveWithPolicy()` from `@voltro/local-first`, where `crdtText()` columns
+merge and scalars follow the declared `conflictPolicy()`:
+```tsx
+outbox.resolveConflict(entry.id, resolveWithPolicy(policy, local, remote, {
+  crdtColumns: ['body'],
+}))
 ```

package/templates/agent-docs/security.md CHANGED Viewed

@@ -195,7 +195,7 @@ would break every link into your api.
 ### Raw WebSocket gateways are guarded before the upgrade
-A [`defineWebSocket` gateway](/docs/data/subscriptions#raw-websocket-gateways--definewebsocket)
+A [`defineWebSocket` gateway](/docs/data/subscriptions#raw-websocket-gateways-definewebsocket)
 mounts its own upgrade path beside the rpc socket, and the listener treats it
 exactly like the rpc upgrade:
@@ -479,7 +479,7 @@ deferred registry, the shell's bundle tags, and React's own bootstrap/settle
 scripts — while the policy header itself stays the middleware's to set via
 `responseHeaders`, carrying the same nonce. An `isr` page combined with
 `cspNonce` refuses the render: a cached nonce is a lie the browser enforces.
-Mechanics + examples: [Middleware → cspNonce](/docs/routing/middleware#a-per-request-csp-nonce--cspnonce).
+Mechanics + examples: [Middleware → cspNonce](/docs/routing/middleware#a-per-request-csp-nonce-cspnonce).
 ## Incoming webhooks must verify their caller
@@ -582,7 +582,7 @@ dependency, like a rate-limit counter in Redis — catches internally and
 degrades **loudly**. `@voltro/plugin-ratelimit`'s `httpShield` does exactly
 that: a Redis outage means unlimited-with-a-warning, never a self-inflicted API
 outage. The full authoring guidance is in the
-[plugin contract](/docs/plugins/contract#onhttprequest-httprequestinterceptor--pre-auth-http-pipeline-hook).
+[plugin contract](/docs/plugins/contract#onhttprequest-httprequestinterceptor-pre-auth-http-pipeline-hook).
 ## Response compression — and where BREACH sits