bitboss-ui 2.1.135 → 3.0.0-alpha.4

package/dist/ai/BbForm.md

@@ -0,0 +1,239 @@
+# BbForm
+
+## Agent Contract
+
+- Safety level: **Consumer API**
+- Group: **Inputs**
+- Description: Form host for `bitboss-ui/validated`: owns the vee-validate form (useForm), validates every field on submit, and emits `submit` with the collected values only when the form is valid.
+- Usage rule: Prefer this component for consumer-facing implementations.
+- Implementation source (only when the contract below is not enough): [source/BbForm.md](./source/BbForm.md)
+
+## Usage & Guidelines
+
+### When to use
+
+`BbForm` is the host every `bitboss-ui/validated` control expects. It calls
+vee-validate's `useForm()` once and provides the field context those controls
+bind to, so a validated `BbTextInput` inside it needs nothing but a `label` and
+its `rules`.
+
+Reach for it whenever a screen collects input that must be valid before it is
+sent. Do **not** reach for it to lay out a form — it renders a bare `<form>` and
+nothing else; spacing, columns and section headings stay yours.
+
+Two things it is not:
+
+- **Not needed for unvalidated forms.** Controls imported from `bitboss-ui`
+  carry no field binding, so a plain `<form>` is enough. Mixing is fine: only
+  the controls you import from `bitboss-ui/validated` participate.
+- **Not a submit button.** It has no built-in actions; put your own
+  `<BbButton type="submit">` in the slot.
+
+Setup (the peer dependency, defining rules once, the whole control list) lives
+in [Validated Forms](./guides/validated-forms.md). This page is only about the
+host.
+
+### Submit is the gate
+
+The one event is `submit`, and it fires **only when every field passes**. The
+native submission is always prevented, so there is no navigation to suppress and
+no `@submit.prevent` to remember — an invalid form simply surfaces its messages
+and stays put.
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue';
+import { BbButton } from 'bitboss-ui';
+import { BbForm, BbTextInput } from 'bitboss-ui/validated';
+
+const saving = ref(false);
+
+const save = async (values: Record<string, unknown>) => {
+	saving.value = true;
+	try {
+		await api.contacts.create(values);
+	} finally {
+		saving.value = false;
+	}
+};
+</script>
+
+<template>
+	<BbForm @submit="save">
+		<BbTextInput label="Full name" rules="required" />
+		<BbTextInput label="Email" rules="required|email" type="email" />
+		<BbButton :loading="saving" type="submit" variant="primary">Save</BbButton>
+	</BbForm>
+</template>
+```
+
+The payload is the collected form values, keyed by each field's name — derived
+from the control's `label` unless you set `vid`. `Full name` above arrives as
+`fullname`; when two fields in one form would collide (rows in a `v-for`), give
+those a `vid`.
+
+### Reading form state in the slot
+
+The default slot is scoped, so the chrome around the fields can react without
+lifting state into the page. It carries `values`, `isSubmitting`, `submitCount`,
+`validate`, `resetForm`, plus vee-validate's own `meta` flags (`valid`, `dirty`,
+`touched`, `pending`).
+
+```vue
+<template>
+	<BbForm v-slot="{ dirty, valid, isSubmitting, resetForm }" @submit="save">
+		<BbTextInput label="Display name" rules="required" />
+		<BbTextarea label="Bio" rules="max:280" />
+
+		<footer>
+			<BbButton :disabled="!dirty" variant="ghost" @click="resetForm()">
+				Discard
+			</BbButton>
+			<BbButton
+				:disabled="!valid"
+				:loading="isSubmitting"
+				type="submit"
+				variant="primary"
+			>
+				Save changes
+			</BbButton>
+		</footer>
+	</BbForm>
+</template>
+```
+
+Disabling submit on `!valid` is a choice, not a default: vee-validate marks a
+pristine form invalid until its fields have been validated once, so a
+disabled-until-valid button can read as broken on first paint. Leaving the
+button enabled and letting the failed submit surface the messages is usually the
+kinder flow — `valid` is there for wizards and dialogs where a dead-end step is
+worse.
+
+### Driving it from outside
+
+When the submit action lives outside the form — a dialog footer, a page toolbar,
+a leave guard — give the form an **explicit `id`** and read it with
+`useBbFormContext(id)`. Same pattern as `useBbTableContext` /
+`useBbDropdownContext`: no template ref, no shared subtree, no props threaded
+through the layout.
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue';
+import { BbButton, BbDialog } from 'bitboss-ui';
+import { BbForm, BbTextInput, useBbFormContext } from 'bitboss-ui/validated';
+
+const open = ref(false);
+const invite = useBbFormContext('invite-teammate');
+</script>
+
+<template>
+	<BbDialog v-model="open" title="Invite teammate">
+		<BbForm id="invite-teammate" @submit="sendInvite">
+			<BbTextInput label="Email" rules="required|email" type="email" />
+		</BbForm>
+
+		<template #footer>
+			<BbButton variant="ghost" @click="open = false">Cancel</BbButton>
+			<BbButton
+				:loading="invite.submitting.value"
+				variant="primary"
+				@click="invite.submit()"
+			>
+				Invite
+			</BbButton>
+		</template>
+	</BbDialog>
+</template>
+```
+
+The handle carries `valid`, `dirty`, `touched`, `pending`, `submitting`,
+`submitCount`, `values` and `errors` as computeds, plus `submit()`, `reset()`
+and `validate()`. It is callable **before** the form mounts — every field reads a
+stable baseline and every action is a no-op until `isReady` flips — so a footer
+that renders ahead of its dialog's content is fine.
+
+Keep `@submit` as the place the work happens even then: `submit()` routes
+through the same handler the button inside would, so validation gates the
+request once and there is one code path, not two.
+
+The id must be one you set. An auto-generated id cannot be targeted, and a form
+with no `id` simply has no outside handle — which is the right default for a
+self-contained form, where the slot scope already carries the same state.
+
+### One validator, one set of messages
+
+The rendered `<form>` carries **`novalidate`**. That is not a licence to skip
+validation — it hands validation to vee-validate exclusively.
+
+Without it the browser's own constraint validation runs first: a field with
+`required`, `type="email"`, `pattern`, `maxlength` or `min`/`max` blocks the
+submit event before `BbForm` ever sees it, shows a native bubble in the
+browser's wording, and the form's real messages never render. The attributes
+themselves are worth setting — `type="email"` gets the right mobile keyboard and
+autofill, `required` is announced by screen readers — so the fix is not to drop
+them; it is to stop the browser from gating submission. `novalidate` leaves
+every attribute in the DOM and changes only who decides.
+
+The consequence to know: a field inside `<BbForm>` that is **not** a
+`bitboss-ui/validated` control is not validated at all — vee-validate only
+knows about registered fields, and the browser has stepped aside. Import the
+controls from `bitboss-ui/validated`, or give a bespoke field its own rule
+through `useValidatedField`.
+
+#### There is no template-ref handle
+
+`BbForm` calls no `defineExpose`, so a template ref yields the plain component
+instance and `form.value.submitForm()` / `.isValid` / `.validate()` / `.reset()`
+do not exist. Use `useBbFormContext(id)` for all four.
+
+The native form element is still right there, though — `$el` is public-instance
+API and unaffected:
+
+```vue
+<script setup lang="ts">
+import { useTemplateRef } from 'vue';
+
+const form = useTemplateRef('form');
+// The ref is the COMPONENT; requestSubmit is a DOM method, so it lives on $el.
+const submitNatively = () =>
+	(form.value?.$el as HTMLFormElement).requestSubmit();
+</script>
+```
+
+`requestSubmit()` dispatches a real submit event, which the component handles
+through the same `handleSubmit` — so validation still gates it and `@submit`
+still fires only when every field passes. (`form.submit()`, the other native
+method, bypasses event handlers entirely and would skip validation _and_ reload
+the page. Never use it here.)
+
+Prefer `useBbFormContext(id).submit()` anyway: it says what you mean, needs no
+cast, and does not depend on the root element staying a `<form>`.
+
+### Required markers
+
+A field whose rules include `required` renders a red asterisk beside its label
+automatically ([`BbAsterisk`](./BbAsterisk.md) does the drawing). You only place
+that component yourself when you have replaced a control's `label` slot with
+custom content — the wrapper hands you `showAsterisk` in the slot scope so the
+marker stays consistent with the rules.
+
+## Props
+
+| Prop | Type | Default | Required | Description |
+| --- | --- | --- | --- | --- |
+| `id` | `string \| undefined` |  |  | Explicit id, so anything outside the form can read and drive it through `useBbFormContext(id)` — a dialog footer's submit button, a page toolbar, a leave guard. Omit it when the form is self-contained: the slot scope already carries the sam… |
+
+## Events
+
+- `submit` — `(event: "submit", values: Record<string, unknown>): void`
+
+## Slots
+
+- `default` — scope: `{ touched: boolean; dirty: boolean; valid: boolean; pending: boolean; initialValues?: Partial<GenericObject> \| undefined; isSubmitting: boolean; resetForm: (st…`
+
+## See Also
+
+- [BbTextInput](./BbTextInput.md) — Captures single-line text values.
+- [BbSelect](./BbSelect.md) — Selects one or many options from structured data.
+- [BbCheckbox](./BbCheckbox.md) — Toggles a single boolean option.