bitboss-ui 3.0.0-beta.4 → 3.0.0-beta.41

package/dist/ai/guides/validated-forms.md

@@ -1,20 +1,105 @@
 ---
 title: Validated Forms (vee-validate)
-summary: The `bitboss-ui/validated` entrypoint — form controls pre-wired to vee-validate. Global rules give an effort-free `rules="required|email"` string syntax; BbForm hosts the form; requiredAsterisk marks required fields.
+summary: Forms with validation — the form controls join a BbForm (vee-validate underneath). Validate with one schema for the whole form (any Standard Schema — Zod, Valibot, ArkType, Yup — on BbForm's `schema`, no adapter) or with per-field `rules="required|email"` strings; BbForm hosts the form, focuses the first invalid field on a failed submit and emits `invalid`; requiredAsterisk marks required fields.
 ---
 
 # Validated Forms
 
-`bitboss-ui/validated` ships the standard form controls wrapped with
-[vee-validate](https://vee-validate.logaretm.com/v4/) field binding. Import from
-`bitboss-ui/validated` **only** where you want validation — the core `bitboss-ui`
-entrypoint never pulls vee-validate into apps that don't use it.
+The form controls (`BbTextInput`, `BbSelect`, the groups, the pickers…) join the
+`BbForm` they are inside and get [vee-validate](https://vee-validate.logaretm.com/v4/)
+field binding; outside a form they are plain. Everything comes from
+`bitboss-ui`. An app without forms ships no vee-validate at all, and a build
+that uses `BbForm` without the peer installed fails with the install hint.
+(`bitboss-ui/validated` was retired in 3.0.0-beta.41; `npx bitboss-ui check
+--fix` rewrites its imports.)
 
 ```bash
-npm i vee-validate                        # required peer for /validated
-npm i @vee-validate/rules @vee-validate/i18n   # recommended: standard rules + messages
+npm i vee-validate                        # required peer for BbForm
+npm i @vee-validate/rules @vee-validate/i18n   # only for string `rules` (§ 1)
 ```
 
+**No adapter to install:** `@vee-validate/zod` and friends are NOT needed with
+`schema` (§ 3). Install `@vee-validate/rules` (and optionally
+`@vee-validate/i18n`) only if you use string `rules`.
+
+## The shape of a form (start here)
+
+```vue
+<script setup lang="ts">
+import { z } from 'zod';
+import { BbButton, BbCheckbox, BbForm, BbTextInput } from 'bitboss-ui';
+
+const signup = z.object({
+	email: z.email('Enter a valid email'),
+	terms: z.literal(true, 'Accept the terms to continue'),
+});
+
+async function createAccount(values: z.output<typeof signup>) {
+	await fetch('/api/signup', { method: 'POST', body: JSON.stringify(values) });
+}
+</script>
+
+<template>
+	<BbForm v-slot="{ isSubmitting }" :schema="signup" @submit="createAccount">
+		<BbTextInput label="Email" name="email" type="email" />
+		<BbCheckbox label="I accept the terms" name="terms" />
+		<BbButton :loading="isSubmitting" type="submit" variant="primary">
+			Create account
+		</BbButton>
+	</BbForm>
+</template>
+```
+
+That is the whole pattern. The rules that keep a form this small:
+
+- **A field is a `label` and a `name`.** `name` is its key: in the schema, in
+  the `@submit` values, in the server's errors. **No `v-model` on a field**
+  and no ref per field: the form holds the values.
+- **The page needs the values before submit** (an edit form filled from the
+  server, a live preview, Inertia's `useForm`)? Bind the whole object once,
+  `<BbForm v-model="profile">`: it seeds the fields and receives every change.
+  Still no `v-model` on the fields.
+- **Validate with one `schema`** (Zod, Valibot, ArkType, Yup) **or with
+  `rules` strings** on the fields (§ 1–2), never both.
+- **With a schema, give each field's message to its TYPE too**:
+  `z.string('Enter your name').trim().min(1, 'Enter your name')`. An emptied
+  text field holds `null` and one never touched holds `undefined`, so
+  `z.string().min(1, '…')` alone shows the library's "expected string,
+  received null" instead of your message. Same for Valibot
+  (`v.string('…')`); Yup's `.required('…')` covers it
+  ([validation-libraries § What needs a tweak](./validation-libraries.md#what-needs-a-tweak)).
+  The app is on **Zod 4**: the message is the argument (`z.literal(true,
+'Accept the terms')`, `z.email('…')`); Zod 3's `errorMap` /
+  `required_error` do not type-check.
+- **Every value you submit is a key of the schema.** Zod and Valibot drop
+  undeclared keys from `@submit`'s values, so a switch or a hidden field the
+  schema does not name vanishes (declare it: `separateShipping: z.boolean()`).
+- **`@submit` fires only when the form is valid**, with the values (the
+  schema's output, typed). The slot's `isSubmitting` drives the button. No
+  `saving` ref, no `@submit.prevent`, no `<form>` of your own.
+- **A server's 422** goes to the form in one call:
+  `useBbFormContext(id).setErrors(body.errors)` (§ 4). No `:errors` ref per
+  field. Call `useBbFormContext(id)` once, at the top of `<script setup>`
+  (not inside a handler); its state is refs: `form.errors.value`,
+  `form.dirty.value`.
+- **A page never imports `vee-validate`**: `defineRule` lives in one
+  validators module (§ 1), and nothing else is needed.
+- **Seed only what you have.** The bound object holds loaded data and real
+  defaults (a quantity of 1); leave out what the user must choose (a terms
+  checkbox, an empty email), so its field starts empty and its message
+  shows. Typing the object as the schema's output fails for those
+  (`terms: false` is not `true`): type it by what you seed.
+- **A form in steps** (a wizard) gets **one schema per step**,
+  `:schema="steps[step]"` with `steps = [account, account.extend(…)] as const`
+  and `keep-values-on-unmount`. One whole-form schema blocks "Next" on the
+  fields of the steps not shown yet
+  ([BbForm § Multi-step forms](../BbForm.md#multi-step-forms)).
+- **A control inside the form that is not form data** (a filter, a "show
+  advanced" switch) gets `formless`.
+- **Rows** are a `v-for` over an array of the bound object:
+  `:name="`lines[${i}][qty]`"`, `:key="line.id"`; add is `push`, delete is
+  `splice` ([BbForm § Rows](../BbForm.md#rows-v-for)).
+
 ## 1. Define rules once (global)
 
 The recommended, effort-free setup: `defineRule` your rules once as a
@@ -68,36 +153,33 @@ import './app/validators';
 ## 2. Build the form
 
 Wrap fields in `<BbForm>` (a thin `useForm` host). Give each field a `label`
-(or `legend`) and `rules`. The field name is auto-derived from the label, so
-you don't write `vid`:
+(or `legend`), a `name` and its `rules`:
 
 ```vue
 <script setup lang="ts">
-import { reactive, ref } from 'vue';
-import { BbButton } from 'bitboss-ui';
 import {
+	BbButton,
+	BbCheckbox,
 	BbForm,
-	BbTextInput,
 	BbNumberInput,
-	BbCheckbox,
-} from 'bitboss-ui/validated';
+	BbTextInput,
+} from 'bitboss-ui';
 
-const form = reactive({ email: null, quantity: null, terms: false });
-// `@submit` hands you the collected values, so the ref must be able to hold
-// them — a bare `ref(null)` infers `Ref<null>` and the assignment won't compile.
-const submitted = ref<Record<string, unknown> | null>(null);
+async function order(values: Record<string, unknown>) {
+	await fetch('/api/orders', { method: 'POST', body: JSON.stringify(values) });
+}
 </script>
 
 <template>
-	<BbForm v-slot="{ isSubmitting }" @submit="(v) => (submitted = v)">
-		<BbTextInput v-model="form.email" label="Email" rules="required|email" />
+	<BbForm v-slot="{ isSubmitting }" @submit="order">
+		<BbTextInput label="Email" name="email" rules="required|email" />
 		<BbNumberInput
-			v-model="form.quantity"
 			label="Quantity"
+			name="quantity"
 			rules="required|min_value:1"
 		/>
-		<BbCheckbox v-model="form.terms" label="Accept terms" rules="required" />
-		<BbButton type="submit" :loading="isSubmitting">Submit</BbButton>
+		<BbCheckbox label="Accept terms" name="terms" rules="required" />
+		<BbButton :loading="isSubmitting" type="submit">Order</BbButton>
 	</BbForm>
 </template>
 ```
@@ -115,43 +197,355 @@ handle: `useBbFormContext` is the only outside surface, by design.
 Prefer strings, but a one-off inline function still works:
 `:rules="(v) => !!v || 'Required'"`.
 
-**`vid` is an escape hatch.** The field name is derived from the label
-(`"Preferred time"` → `preferredtime`), so set `vid` only when that wouldn't be
-unique — v-for'd rows, or array `v-model`s sharing a label:
+**A field's path is its `name`.** Without one, the path is derived from the
+label (`"Preferred time"` → `preferredtime`), which is enough for a throwaway
+form; set `name` on real ones, and always when:
+
+- **Rows in a `v-for`**, where the label repeats: `:name="`attendees[${i}]`"`.
+- **Nested or array values**: `name` is read as a path, in either spelling.
+  `address[city]` and `address.city` are the same field, `users[0][name]` is
+  `users.0.name`, and a trailing `[]` goes (`tags[]` → `tags`). The `@submit`
+  payload nests to match.
+- **A translated or changing label.** A label-derived path moves when the
+  label does (`"Email"` → `email`, `"E-mail"` → `e-mail`), and everything
+  keyed by it misses: server errors keyed by field, saved drafts, analytics.
+  A fixed `name` stays put.
+- **`BbDropzone`**, which has no label, always needs one.
+
+`name` also goes on the native input unchanged, so the same field posts under
+it in a plain HTML form. **For a native post, use brackets** (`address[city]`):
+PHP (so Laravel) turns dots in a posted field name into `_`, and
+`address.city` arrives as `address_city`. The validation path is the same
+either way.
 
 ```vue
+<!-- <BbForm v-model="form">: the rows follow `form.attendees` -->
 <BbTextInput
 	v-for="(_, i) in form.attendees"
 	:key="i"
-	v-model="form.attendees[i]"
 	label="Attendee"
-	:vid="`attendee_${i}`"
+	:name="`attendees[${i}]`"
 />
 ```
 
-`BbDropzone` has no label, so it always needs `vid`.
+**Messages name the field by its label, never its path.** `{field}` in a rule
+message is the `label` (or `legend`). Set **`validation-label`** when the label
+is not the noun a sentence needs (a question, an icon-only label, a hidden
+one): `<BbTextInput label="Where do you live?" validation-label="City" />`
+reads "City is required". A field with neither says "This field".
 
-## The three added props
+### Upgrading from a 3.0 beta: `vid` is gone
 
-| Prop         | Type                         | Notes                                                                     |
-| ------------ | ---------------------------- | ------------------------------------------------------------------------- |
-| `rules`      | `RuleExpression<modelValue>` | A rule string (`"required\|email"`), function, or object.                 |
-| `validateOn` | timing array                 | When to re-validate; per-control default below.                           |
-| `vid`        | `string`                     | Escape hatch — explicit field name; normally auto-derived from the label. |
+In the 3.0 betas `vid` was the field's path; it is `name` now, with the same
+value (`vid="address.city"` → `name="address.city"`, or `address[city]`).
+From v2, where `vid` was the name shown in messages, it is `validation-label`.
+`npx bitboss-ui check --fix` rewrites each `vid` by its value, and the
+[migration guide](./migration/v2-to-v3.md) has the details.
 
-External errors compose: whatever you pass to the base `errors` prop is
-**merged** with the vee-validate messages, so server-side errors and rule
-messages show together.
+## 3. Or: one schema for the whole form
+
+If your app already describes its data with Zod, Valibot, ArkType or Yup, hand
+that schema to `BbForm`'s **`schema`** instead of writing `rules` per
+field. Any [Standard Schema](https://standardschema.dev) works as it is: no
+`@vee-validate/zod`, no adapter import, nothing extra to install.
+
+```vue
+<script setup lang="ts">
+import { reactive } from 'vue';
+import { z } from 'zod';
+import { BbButton, BbForm, BbNumberInput, BbTextInput } from 'bitboss-ui';
+
+const schema = z.object({
+	// An emptied text field holds `null`: give the type the message too.
+	email: z.email('Enter a valid email').toLowerCase(),
+	address: z.object({
+		city: z.string('Enter a city').trim().min(1, 'Enter a city'),
+	}),
+	quantity: z.number('How many?').int().min(1, 'At least 1'),
+});
+
+// Only to start the quantity at 1: the fields read their start value here.
+const order = reactive({ quantity: 1 });
+
+// Typed from the schema, and it is the schema's OUTPUT: trimmed, lower-cased.
+const save = async (values: z.output<typeof schema>) => {
+	console.log(values.address.city);
+};
+</script>
+
+<template>
+	<BbForm
+		v-slot="{ isSubmitting }"
+		v-model="order"
+		:schema="schema"
+		@submit="save"
+	>
+		<BbTextInput label="Email" name="email" type="email" />
+		<BbTextInput label="City" name="address[city]" />
+		<BbNumberInput label="Quantity" name="quantity" />
+		<BbButton :loading="isSubmitting" type="submit">Save</BbButton>
+	</BbForm>
+</template>
+```
+
+- **`name` is the field's path in the schema** (`email`, `address[city]` or
+  `address.city`, `lines[0][qty]`); each issue lands on the field with that
+  path. With a schema, set `name` on every field rather than relying on the
+  label-derived path.
+- **`@submit` gets the schema's output** (transforms and coercions applied),
+  typed from the schema. Async refinements gate the submit like any rule.
+- **Per-field `rules` are ignored while a schema is set** (vee-validate's
+  design). Pick one per form. `npx bitboss-ui check` flags `rules` inside a
+  form that has a `schema` (`rules-ignored-by-schema`), and a string rule the
+  project never registers with `defineRule` (`unregistered-rule`).
+- **Server errors (a 422): call `setErrors(errors)`** on the form, see
+  [§ 4](#4-server-errors-seterrors-fields-unmatchederrors). Each message lands on the field with that
+  path, beside the schema's. A field's own `errors` prop still merges in, for
+  one field's external message.
+- **Set the schema when the form mounts.** It may change afterwards: a
+  `computed` per wizard step, together with `keep-values-on-unmount` so the
+  steps you leave keep their values. Pattern and traps:
+  [BbForm § Multi-step forms](../BbForm.md#multi-step-forms).
+
+Verified against Zod 3.24 and 4, Valibot 1, ArkType 2 and Yup 1.7. vee-validate's
+own `toTypedSchema(...)` schemas and rule objects keep working.
+
+On a failed submit (schema or rules), `BbForm` focuses the first invalid field
+that is on screen and emits `invalid` with `{ errors, values }`: every failing
+path, including those whose field is not on screen, so a wizard can jump to the
+step that holds one.
+
+Which library does what (asterisk, messages per path, async, emptied fields) and what changes when you switch: [validation-libraries](./validation-libraries.md).
+
+**Conditional validation has no on/off switch.** A field that does not apply
+is `v-if`'d away; in a form with `keep-values-on-unmount` also call
+`removeField(path)` (it applies after the re-render, so any watcher works), or its value is
+still submitted (and still checked by a schema). A form checked differently by
+state switches a computed `schema`, or binds computed `rules` (`''` = none).
+A draft posts `useBbFormContext(id).values` and calls `snapshot()`; it never
+goes through `@submit`. Patterns:
+[BbForm § Conditional validation](../BbForm.md#conditional-validation) and
+[§ Saving a draft](../BbForm.md#saving-a-draft). Rows (`v-for`): your array is
+the truth, name fields by index, key by id or index, and in a keep-values form
+call `removeField` on a deleted row: [BbForm § Rows](../BbForm.md#rows-v-for).
+
+### A check across fields (confirm a password)
+
+A rule that compares two fields is a refinement of the whole object, with
+`path` naming the field that shows the message:
+
+```ts
+import { z } from 'zod';
+
+const signup = z
+	.object({
+		password: z.string('At least 8 characters').min(8, 'At least 8 characters'),
+		password_confirmation: z.string('Repeat the password'),
+	})
+	.refine((form) => form.password === form.password_confirmation, {
+		message: 'The passwords do not match',
+		path: ['password_confirmation'],
+	});
+```
+
+The message lands on the field whose `name` is `password_confirmation`, and a
+failed submit focuses it. Valibot: `v.forward(v.partialCheck(...), [...])`;
+Yup: `yup.string().oneOf([yup.ref('password')], '…')`.
 
-## `validateOn` defaults
+### An edit form: filled from the server, Save only when something changed
 
-| Default                                 | Controls                                                                                                                |
-| --------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
-| `['blur']`                              | BbTextInput, BbNumberInput, BbTextarea, BbColorInput, BbDropzone                                                        |
-| `['inactive']`                          | BbSelect, BbTag, BbSlider, BbRating, BbDatePickerInput, BbTimePickerInput, BbCheckboxGroup, BbSwitchGroup, BbRadioGroup |
-| `['update:modelValue','change','blur']` | BbCheckbox, BbSwitch                                                                                                    |
+Bind the loaded object; the slot's `dirty` gates Save and Discard, `reset()`
+puts the loaded values back, and `snapshot()` after a successful save makes
+the saved values the new baseline (so `dirty` clears and Save disables
+again):
 
-`BbDropzone` has no label, so it **requires** `vid`.
+```vue
+<script setup lang="ts">
+import { reactive } from 'vue';
+import { z } from 'zod';
+import {
+	BbButton,
+	BbForm,
+	BbTextarea,
+	BbTextInput,
+	useBbFormContext,
+} from 'bitboss-ui';
+
+// As loaded from the server; a preview elsewhere on the page reads it too.
+const profile = reactive({ name: 'Ada Lovelace', bio: 'Analyst.' });
+
+const schema = z.object({
+	name: z.string('Enter a name').trim().min(1, 'Enter a name'),
+	bio: z.string().max(160, 'Keep it under 160 characters').nullish(),
+});
+
+const form = useBbFormContext('profile');
+
+async function save(values: z.output<typeof schema>) {
+	const response = await fetch('/api/profile', {
+		method: 'PUT',
+		body: JSON.stringify(values),
+	});
+	if (response.ok) form.snapshot();
+}
+</script>
+
+<template>
+	<p>{{ profile.name }}: {{ profile.bio }}</p>
+	<BbForm
+		id="profile"
+		v-slot="{ dirty, isSubmitting }"
+		v-model="profile"
+		:schema="schema"
+		@submit="save"
+	>
+		<BbTextInput label="Name" name="name" />
+		<BbTextarea label="Bio" name="bio" />
+		<BbButton :disabled="!dirty" variant="ghost" @click="form.reset()">
+			Discard
+		</BbButton>
+		<BbButton
+			:disabled="!dirty"
+			:loading="isSubmitting"
+			type="submit"
+			variant="primary"
+		>
+			Save
+		</BbButton>
+	</BbForm>
+</template>
+```
+
+## 4. Server errors: `setErrors`, `fields`, `unmatchedErrors`
+
+Hand a server's validation errors to the form in one call, through
+[`useBbFormContext(id)`](../composables/useBbFormContext.md) or the `BbForm`
+slot: `setErrors(map)` takes Laravel's 422 `errors` (`{ key: string[] }`) and
+Inertia's `errors` (`{ key: string }`), keyed by field path (dots or
+brackets). It returns nothing; the form state is the answer:
+
+- `errors` is every error of a field in `fields`, `{ [path]: string[] }`.
+- `unmatchedErrors` is every other error (no field has that path), same
+  shape, never gating submit; it clears when a submit starts, on reset and
+  on the next `setErrors`.
+- They never share a path: `{ ...errors, ...unmatchedErrors }` is every
+  error. `fields[path].errors` is one field's full list.
+- Focus moves to the first failing field on screen, like a failed submit,
+  while focus is still the form's (`setErrors(map, { focus: false })` to
+  skip).
+
+A save that keeps the user on the page ends with `snapshot()` (or
+`snapshot(savedValues)`): the saved values become the baseline, so `dirty`
+clears. See [BbForm § Saving in place](../BbForm.md#saving-in-place-snapshot).
+
+```ts
+// Inertia: router.post('/signup', values, { onError: (errors) => form.setErrors(errors) })
+// fetch / axios: if (response.status === 422) form.setErrors((await response.json()).errors)
+```
+
+**One summary of every error**, messages only (never print the arrays):
+
+```vue
+<BbAlert v-if="Object.keys(allErrors).length" variant="destructive">
+	<p v-for="(messages, path) in allErrors" :key="path">{{ messages[0] }}</p>
+</BbAlert>
+<!-- script: const allErrors = computed(() => ({ ...form.errors.value, ...form.unmatchedErrors.value })) -->
+```
+
+**A wizard that posts on the last step** keeps every step's values
+(`keep-values-on-unmount`), so a 422 for a field on a step that is not on
+screen still lands on that field (`fields[path].mounted` is `false`) and in
+the summary above. To jump to it, find the first failing path's step:
+
+```ts
+const STEPS = [['email'], ['profile.name', 'profile.city']];
+async function submit(values: Record<string, unknown>) {
+	if (step.value < STEPS.length - 1) return void step.value++;
+	const response = await fetch('/api/signup', {
+		method: 'POST',
+		headers: { 'Content-Type': 'application/json', Accept: 'application/json' },
+		body: JSON.stringify(values),
+	});
+	if (response.status !== 422) return;
+	form.setErrors((await response.json()).errors);
+	const failing = Object.keys(form.errors.value)[0];
+	const owner = STEPS.findIndex((paths) => paths.includes(failing ?? ''));
+	if (owner !== -1) step.value = owner;
+}
+```
+
+Full pattern with a schema per step and a badge per step:
+[BbForm § Multi-step forms](../BbForm.md#multi-step-forms) and
+[§ Fields on a step you left](../BbForm.md#fields-on-a-step-you-left-and-the-step-badge).
+
+With `keep-values-on-unmount`, fields on a step you left stay in `fields`
+(`mounted: false`) and still receive their server errors. Full pattern, the
+step badge and deleting rows (`removeField`):
+[BbForm § Server errors (setErrors) and fields](../BbForm.md#server-errors-seterrors-and-fields).
+Every provider's shape and bridge (Inertia, error bags, Laravel 422,
+Precognition, vee-validate, Nuxt UI, API Platform):
+[validation-providers](./validation-providers.md).
+
+**`<BbForm v-model="values">`** keeps the values in an object your page owns
+(any reactive object, Inertia's `useForm()` included), both ways, in place:
+seeded from it, written by path (nested created), foreign keys untouched,
+your writes drive the fields, rows follow its arrays with nothing to call.
+With Inertia, declare every field in `useForm({ … })` (Inertia posts only the
+keys it was created with). See
+[BbForm § Binding the form to your object](../BbForm.md#binding-the-form-to-your-object-v-model).
+
+**`v-model` is optional inside `BbForm`**: the form holds each field's value
+by its `name`. Read it in `@submit`, the slot's `values` or
+`useBbFormContext(id).values`
+([BbForm § Fields without v-model](../BbForm.md#fields-without-v-model)); bind
+`v-model` when the page owns the value.
+
+## The three added props
+
+| Prop              | Type                         | Notes                                                                |
+| ----------------- | ---------------------------- | -------------------------------------------------------------------- |
+| `rules`           | `RuleExpression<modelValue>` | A rule string (`"required\|email"`), function, or object.            |
+| `validationMode`  | `ValidationMode`             | When the field checks itself while the user works; see below.        |
+| `validationLabel` | `string`                     | The field's name in messages; defaults to the `label` (or `legend`). |
+
+The field's path is the base control's own `name` (see above); there is no
+separate id prop (`vid` is gone in 3.0.0-beta.41).
+
+Types keep their home: a control's props and events come from `bitboss-ui`
+(`import type { BbTextInputProps } from 'bitboss-ui'`), and the three added
+props too (`FormFieldProps`, `ValidationMode`).
+
+External errors compose: whatever you pass to the base `errors` prop is
+**merged** with the vee-validate messages. For a server's 422, use
+[`setErrors`](#4-server-errors-seterrors-fields-unmatchederrors) instead: one
+call for the whole form.
+
+## `validationMode`: when a field checks itself
+
+One mode, the same for every control. "Leave" is blur for a text-like control
+(BbTextInput, BbNumberInput, BbTextarea, BbColorInput, BbDropzone) and focus
+leaving the whole control (`inactive`) for a picker or a group (BbSelect,
+BbTag, BbSlider, BbRating, the date and time inputs, the groups). A checkbox or
+switch click commits its value, so the click counts as the change and the leave.
+
+| Mode                     | First check  | While it shows an error | Once fixed                  |
+| ------------------------ | ------------ | ----------------------- | --------------------------- |
+| `aggressive`             | every change | every change            | every change                |
+| `balanced` (the default) | leave        | every change            | back to waiting for leave   |
+| `lazy`                   | leave        | leave only              | leave                       |
+| `submit-only`            | submit       | the next submit         | the next submit             |
+| `submit-live`            | submit       | every change            | quiet until the next submit |
+
+Set it on a field, on the `BbForm` (`validation-mode="submit-live"`, its fields
+inherit it) or app-wide (`formControls: { validationMode: 'lazy' }`); the
+field's own wins, then the form's. A failed submit validates every field
+whatever its mode. Pick `balanced` for most forms, `submit-only` /
+`submit-live` for long forms that should not nag, `lazy` for expensive async
+checks; `aggressive` errors on half-typed values, so opt into it deliberately.
+A page that writes the model itself re-checks a field that shows an error
+(except `lazy` and `submit-only`).
+
+`BbDropzone` has no label, so it **requires** `name`.
 
 ## Required asterisk
 
@@ -162,9 +556,9 @@ Turn on the plugin option to mark required fields with a red `*`:
 bitbossUi({ requiredAsterisk: true });
 ```
 
-It shows on any `/validated` control that is `required`, or whose `rules`
-contain a **`required` rule** — rendered in the control's `#label`/`#legend`
-slot. Rules alone are not enough, and deliberately so: every other rule is
+Inside a `BbForm` it shows on a control that is `required`, or whose `rules`
+contain a **`required` rule** (outside a form: `required` only), after the
+label text. Rules alone are not enough, and deliberately so: every other rule is
 conditional on a value being present (`max:5` passes on an empty field, which is
 what makes "optional, but at most 5 if filled" expressible), so raising the
 asterisk for any rule would mark optional fields as mandatory and contradict the
@@ -173,20 +567,37 @@ engine.
 Both rule shapes are read — the string form (`'required|email'`, arguments
 allowed: `'required:true'`) and the object form (`{ required: true }`, where
 `{ required: false }` correctly shows nothing). `required_if` and friends do
-**not** count: conditionally required is not required. A validator function or a
-typed schema (yup/zod) is opaque to this check, so set `required` explicitly on
-schema-driven fields that should carry the marker.
+**not** count: conditionally required is not required. A validator function is
+opaque to this check; set `required` on the field for those.
+
+With a `schema`, the schema decides, with every Standard Schema
+library above: a field gets the asterisk when its key is required in the
+schema (not optional, no default, not nullable, and its parent object required
+too). Zod 4, ArkType and Joi are read through their JSON Schema; Zod 3, Yup,
+Valibot and Effect through their own schema shape — nothing to wrap, no
+`required` to add. The marker follows a reactive (per-step) schema.
 
-Core (non-validated) components ignore the option. The marker is the exported
-`BbAsterisk` component — drop it into your own label content when you build a
+The marker is the exported `BbAsterisk` component — drop it into your own label content when you build a
 bespoke field.
 
 ## Controls
 
 BbTextInput · BbNumberInput · BbTextarea · BbSelect · BbTag · BbCheckbox ·
 BbCheckboxGroup · BbSwitch · BbSwitchGroup · BbRadioGroup · BbRating · BbSlider ·
-BbDatePickerInput · BbTimePickerInput · BbColorInput — plus `BbForm` and the
-`useValidatedField` composable for wrapping your own controls.
+BbDatePickerInput · BbTimePickerInput · BbColorInput · BbDropzone — each one
+joins the `BbForm` it sits in by itself (no wrapper, no second import) — plus
+`BbForm` and the `useBbFormField` composable for a control of your own.
+
+`BbCalendar` (the always-visible calendar) does **not** join a form: it is
+bare, with no `errors` chrome to show a message in. When a form needs one, a
+date field is `BbDatePickerInput`; if the calendar in place must be validated,
+bind it with `useBbFormField` and render the message next to it yourself.
+
+`BbRadio` (a single radio) does not join a form either — the one control of
+the checkbox / switch / radio family that does not. A radio answers only as
+part of a group: validate the choice with `BbRadioGroup`; for radios you lay
+out by hand (one per pricing card, one per table row), bind the choice with
+`useBbFormField`, or pass `errors` to them yourself.
 
 A live, end-to-end demo lives in `fixtures/vue/pages/ValidatedForm` (with global
 rules in `fixtures/vue/app/validators.ts`), asserted by