bitboss-ui 3.0.0-beta.45 → 3.0.0-beta.46

package/bin/bitboss-ui.mjs

@@ -76,6 +76,7 @@ import {
 	projectLocalBbComponents,
 } from '../scripts/lib/local-components.mjs';
 import { applyBitbossFixes } from '../scripts/lib/check-fix.mjs';
+import { stringControlsFor } from '../scripts/lib/text-null-value.mjs';
 import { cssClassFindings } from '../scripts/lib/css-class-check.mjs';
 import {
 	cssLocalFindings,
@@ -1044,7 +1045,11 @@ async function checkCommand(
 		const content = readText(file);
 		const { findings: fileFindings } = file.endsWith('.md')
 			? validateMarkdown(content, manifest, validateOptions)
-			: validateVueSnippet(content, manifest, validateOptions);
+			: validateVueSnippet(content, manifest, {
+					...validateOptions,
+					// The app's null-value policy, from the project bitboss-ui.d.ts.
+					stringControls: stringControlsFor(file),
+				});
 		// Q46.9: a finding the author silenced for ESLint (`eslint-disable*`,
 		// usually with a reason) is silenced here too, or `check` cannot gate
 		// CI next to a lint step that passes. `.md` lines are fence-relative,

package/dist/ai/BbDialog.md

@@ -99,7 +99,7 @@ back to `false`, which is the same thing.
 		<template #footer>
 			<div class="flex justify-end gap-2">
 				<BbButton variant="ghost" @click="open = false">Cancel</BbButton>
-				<BbButton :disabled="!name.trim()" variant="primary" @click="create">
+				<BbButton :disabled="!name?.trim()" variant="primary" @click="create">
 					Create
 				</BbButton>
 			</div>
@@ -112,7 +112,7 @@ import { ref } from 'vue';
 import { BbButton, BbDialog, BbTextInput } from 'bitboss-ui';
 
 const open = ref(false);
-const name = ref('');
+const name = ref<string | null>('');
 
 // Re-seed on `@show`, not on close — a dismissed dialog may be reopened.
 const reset = () => {
@@ -442,7 +442,7 @@ const roles = [
 ];
 
 const open = ref(false);
-const email = ref('');
+const email = ref<string | null>('');
 const role = ref('member');
 
 // Re-seed on `@show`, not on close — a dismissed dialog may be reopened.
@@ -452,7 +452,9 @@ const reset = () => {
 };
 
 // Primary action stays disabled until the email is plausible.
-const canSend = computed(() => /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email.value));
+const canSend = computed(() =>
+	/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email.value ?? '')
+);
 
 const send = () => {
 	// Send the invite here, then close only on success.
@@ -600,7 +602,7 @@ element.
 			<div class="flex justify-end gap-2">
 				<!-- Keep a visible way out — never trap the user. -->
 				<BbButton variant="ghost" @click="open = false">Skip</BbButton>
-				<BbButton :disabled="!company.trim()" variant="primary" @click="save">
+				<BbButton :disabled="!company?.trim()" variant="primary" @click="save">
 					Save
 				</BbButton>
 			</div>
@@ -613,8 +615,8 @@ import { ref } from 'vue';
 import { BbButton, BbDialog, BbTextInput } from 'bitboss-ui';
 
 const open = ref(false);
-const displayName = ref('');
-const company = ref('');
+const displayName = ref<string | null>('');
+const company = ref<string | null>('');
 
 // Re-seed on `@show` so a dismissed step reopens clean.
 const reset = () => {
@@ -676,7 +678,7 @@ automatically; close only once the work resolves:
 					Cancel
 				</BbButton>
 				<!-- Returning the promise lets BbButton run its own loading state. -->
-				<BbButton :disabled="!draft.trim()" variant="primary" @click="save">
+				<BbButton :disabled="!draft?.trim()" variant="primary" @click="save">
 					Rename
 				</BbButton>
 			</div>
@@ -692,7 +694,7 @@ import { BbButton, BbDialog, BbTextInput } from 'bitboss-ui';
 const projectName = ref('acme-storefront');
 
 const open = ref(false);
-const draft = ref('');
+const draft = ref<string | null>('');
 const saving = ref(false);
 
 // Re-seed on `@show` so a dismissed rename never resurfaces half-typed.
@@ -706,7 +708,7 @@ const save = async () => {
 	try {
 		// Simulated request — replace with your API call.
 		await new Promise((resolve) => setTimeout(resolve, 600));
-		projectName.value = draft.value.trim();
+		projectName.value = (draft.value ?? '').trim();
 		// Work first, then close: the transition runs while your UI refreshes.
 		open.value = false;
 	} finally {

package/dist/ai/BbDropzone.md

@@ -1269,7 +1269,7 @@ import { ref } from 'vue';
 import { BbDropzone, BbButton, BbIcon, BbTextInput } from 'bitboss-ui';
 import type { DropZoneError } from 'bitboss-ui';
 
-const title = ref('');
+const title = ref<string | null>('');
 const documents = ref<File[]>([]);
 const errors = ref<string[]>([]);
 const submitted = ref<{ field: string; fileCount: number } | null>(null);
@@ -1298,7 +1298,7 @@ const remove = (file: File) => {
    model — assemble a FormData and hand it to your request layer. */
 const submit = () => {
 	const body = new FormData();
-	body.append('title', title.value);
+	body.append('title', title.value ?? '');
 	documents.value.forEach((file) => body.append('documents[]', file));
 	submitted.value = { field: 'documents[]', fileCount: documents.value.length };
 };

package/dist/ai/BbForm.md

@@ -310,8 +310,8 @@ Four things to know:
 - **An emptied text field holds `null` by default**, not `''`. So
   `z.string().min(1, 'Required')` alone answers an emptied field with the
   library's own "expected string, received null". Two ways out:
-  - **Set the plugin option `formControls: { textInputNullValue: '',
-textareaNullValue: '' }`.** Emptied fields then emit `''` and the short
+  - **Set the plugin option `formControls: { textInputNullValue: 'string',
+textareaNullValue: 'string' }`.** Emptied fields then emit `''` and the short
     schema shows your message as written. Start text values as `''` too (a
     field nobody touched keeps what your page gave it).
   - **Or keep `null` and put the message on the type as well:**

package/dist/ai/BbOffCanvas.md

@@ -216,7 +216,7 @@ header and footer stay pinned.
 			<div class="flex justify-end gap-2">
 				<BbButton variant="ghost" @click="open = false">Cancel</BbButton>
 				<BbButton
-					:disabled="!email.trim()"
+					:disabled="!email?.trim()"
 					variant="primary"
 					@click="open = false"
 				>
@@ -232,7 +232,7 @@ import { ref } from 'vue';
 import { BbButton, BbOffCanvas, BbTextInput } from 'bitboss-ui';
 
 const open = ref(false);
-const email = ref('');
+const email = ref<string | null>('');
 </script>
 ```
 
@@ -951,7 +951,7 @@ import { ref } from 'vue';
 import { BbButton, BbOffCanvas, BbTextInput } from 'bitboss-ui';
 
 const open = ref(false);
-const reviewer = ref('');
+const reviewer = ref<string | null>('');
 </script>
 ```
 

package/dist/ai/BbPopover.md

@@ -332,7 +332,7 @@ dismissible.
 import { ref } from 'vue';
 import { BbButton, BbPopover, BbTextInput } from 'bitboss-ui';
 
-const days = ref('90');
+const days = ref<string | null>('90');
 </script>
 ```
 

package/dist/ai/BbRating.md

@@ -273,7 +273,7 @@ import { ref } from 'vue';
 import { BbButton, BbRating, BbTextarea } from 'bitboss-ui';
 
 const score = ref<number | null>(null);
-const feedback = ref('');
+const feedback = ref<string | null>('');
 const errors = ref<string | undefined>();
 const sent = ref(false);
 

package/dist/ai/BbTable.md

@@ -849,13 +849,13 @@ const catalogue: Invoice[] = [
 	{ id: '4', number: 'INV-1044', client: 'Umbrella', amount: '€2,750' },
 ];
 
-const search = ref('');
+const search = ref<string | null>('');
 
 // Real apps forward the query to the backend; here we filter a local catalogue
 // after a short simulated round-trip.
 const fetchInvoices = async (): Promise<Invoice[]> => {
 	await new Promise((resolve) => setTimeout(resolve, 250));
-	const term = search.value.trim().toLowerCase();
+	const term = (search.value ?? '').trim().toLowerCase();
 	if (!term) return catalogue;
 	return catalogue.filter(
 		(invoice) =>

package/dist/ai/BbTabs.md

@@ -418,7 +418,7 @@ nothing when you flip back:
 			</template>
 			<template #preview>
 				<div class="grid gap-1.5 pt-3 text-sm whitespace-pre-line">
-					<template v-if="draft.trim()">
+					<template v-if="draft?.trim()">
 						<p class="font-medium">{{ previewTitle }}</p>
 						<p class="text-(--bb-text-muted)">{{ previewBody }}</p>
 					</template>
@@ -442,17 +442,17 @@ const tabs: Array<BbTabsItem<Mode>> = [
 	{ key: 'preview', label: 'Preview' },
 ];
 
-const draft = ref(
+const draft = ref<string | null>(
 	'## Billing retries\n\nVerified on staging — invoice totals now match the ledger.'
 );
 
 const previewTitle = computed(() => {
-	const heading = draft.value.match(/^##\s+(.+)$/m);
+	const heading = (draft.value ?? '').match(/^##\s+(.+)$/m);
 	return heading?.[1] ?? 'Untitled';
 });
 
 const previewBody = computed(() =>
-	draft.value.replace(/^##\s+.+$/m, '').trim()
+	(draft.value ?? '').replace(/^##\s+.+$/m, '').trim()
 );
 </script>
 ```

package/dist/ai/BbTextInput.md

@@ -62,7 +62,7 @@ Pick a sibling when the shape of the data is different:
 - calendar dates → `BbDatePickerInput`;
 - choosing from a known set of options → `BbSelect` / `BbRadioGroup`.
 
-`v-model` binds a `string | null` — an emptied field emits `null` by default, or `''` when the plugin option `formControls` says so (see the installation guide § `formControls`).
+`v-model` binds a `string | null` — an emptied field emits `null` by default, or `''` when the plugin option `formControls` sets the `'string'` policy (see the installation guide § `formControls`). One field can differ from the app with `null-value="string"` or `null-value="null"`; the `update:modelValue` payload types to match (`string` with `'string'`).
 `label` is required (hide it visually with `hideLabel`, never drop it).
 
 ### Label & label modes
@@ -233,7 +233,7 @@ name. The slot alone is enough: no `description` prop needed.
 import { ref } from 'vue';
 import { BbTextInput } from 'bitboss-ui';
 
-const subdomain = ref('');
+const subdomain = ref<string | null>('');
 </script>
 ```
 
@@ -403,8 +403,9 @@ const apiKey = 'sk_live_51Hn3x8Kj2';
 ### Clearable & loading
 
 `clearable` reveals a clear button while the field has a value and is hovered
-or focused; clicking it emits `update:modelValue` with `null` and refocuses the
-input. There is no separate `clear` event — watch the model for `null`. The
+or focused; clicking it emits `update:modelValue` with the empty value (`null`
+by default) and refocuses the input. There is no separate `clear` event — watch
+the model for the empty value. The
 button is suppressed on `disabled`/`readonly` fields.
 
 `loading` shows a spinner in the append position. It is **visual only** — the
@@ -416,7 +417,7 @@ The classic pairing is a signup handle checker: debounce keystrokes, flip
 `loading` while the (simulated) availability call runs, then land the result
 in `errors` or `hint`. Because the field stays editable during the check, the
 handler tags each request and drops stale responses. Watching the model —
-rather than listening to `input` — means the clear button's `null` also resets
+rather than listening to `input` — means the clear button's empty value also resets
 the status.
 
 **Async username check**
@@ -501,7 +502,7 @@ Pass a [maska](https://beholdr.github.io/maska/v3) config to `mask` to format
 as the user types — card numbers, phone numbers, license keys. By default
 `v-model` receives the _unmasked_ value (`'4242424242424242'` for the card
 below); set `emitMasked` to persist the formatted string instead. A fully
-emptied masked field emits the empty value (`null` by default, `''` with `formControls`), like every other state of this component.
+emptied masked field emits the empty value (`null` by default, `''` with the `'string'` policy), like every other state of this component.
 
 The mask is live-reactive: changing the `mask` options at runtime reformats the
 current value, and toggling `emitMasked` re-emits the model in the new format.
@@ -611,7 +612,7 @@ const revealed = ref(false);
 
 ### Events & v-model
 
-- `update:modelValue` — every value change; `string`, or the empty value when emptied (`null` by default, `''` with `formControls`)
+- `update:modelValue` — every value change; `string`, or the empty value when emptied (the `null-value` policy, else `formControls`, else `'null'`; `'string'` emits `''`)
   (with a mask: the unmasked/masked string per `emitMasked`).
 - `focus` / `blur` — forwarded `FocusEvent`s; they also drive the hint's
   show-on-focus behavior.
@@ -1194,7 +1195,7 @@ A `pt` value written in `<script>` (a constant, a preset, a wrapper's
 
 ### Gotchas & anti-patterns
 
-- An emptied field emits `null` by default (`''` with the `formControls` plugin option) — write `value ?? ''` when feeding
+- An emptied field emits `null` by default (`''` with `null-value="string"` or the `formControls` plugin option) — write `value ?? ''` when feeding
   APIs that require strings.
 - `layout` is ignored under `labelMode="floating"`/`"inside"` — those modes
   embed the label in the field and force the vertical layout (see _Density &
@@ -1256,7 +1257,7 @@ A `pt` value written in `<script>` (a constant, a preset, a wrapper's
 | `hint` | `string \| undefined` |  |  | Text box to be displayed near the input, usually to indicate instructions. |
 | `id` | `string \| undefined` |  |  | The `id` of the native control; the label's `for` and the description and message ids derive from it. Generated when omitted. |
 | `inputAlign` | `'top'` \| `'center'` \| `'bottom'` |  |  | Vertical position of the control in a side-by-side row; not `inputPosition`, the horizontal one. Omitted, the control's first line meets the label's. |
-| `inputMode` | `"text" \| "none" \| "search" \| "email" \| "url" \| "tel" \| "numeric" \| "decimal" \| undefined` |  |  | The inputmode of the input. |
+| `inputMode` | `"text" \| "none" \| "search" \| "tel" \| "url" \| "email" \| "numeric" \| "decimal" \| undefined` |  |  | The inputmode of the input. |
 | `label` | `string` |  | yes | Text content of the label of the element. |
 | `labelAlign` | `'top'` \| `'center'` \| `'bottom'` |  |  | Vertical position of the label block in a side-by-side row; not `labelPosition`, the horizontal one. Omitted, the label's first line meets the control's. |
 | `labelMode` | `"outside" \| "floating" \| "inside" \| undefined` |  |  | Label rendering mode. |
@@ -1266,6 +1267,7 @@ A `pt` value written in `<script>` (a constant, a preset, a wrapper's
 | `mask` | `MaskInputOptions \| undefined` |  |  | The mask to be applied to the input. Please visit https://beholdr.github.io/maska/v3 for syntax examples. |
 | `modelValue` | `string \| null \| undefined` |  |  | Used by v-model. |
 | `name` | `string \| undefined` |  |  | Defines the name of the input. |
+| `nullValue` | `E \| undefined` |  |  | What the field emits once the user empties it (typing it empty, the clear button, a mask with nothing in it): `'null'` emits `null`, `'string'` emits `''`. Unset, the app's `formControls.textInputNullValue` applies (`'null'` by default). Also types the `update:modelValue` payload: with `'string'` it is `string`. |
 | `persistentHint` | `boolean \| undefined` | `false` |  | Keeps the hint displayed. |
 | `placeholder` | `string \| undefined` |  |  | String displayed when there's no data. |
 | `prepend:icon` | `string \| undefined` |  |  | Name of the icon to be added at the start of the input. |
@@ -1273,7 +1275,7 @@ A `pt` value written in `<script>` (a constant, a preset, a wrapper's
 | `required` | `boolean \| undefined` | `false` |  | Sets the input as required. |
 | `reverse` | `boolean \| undefined` | `false` |  | Reverses the layout. Applicable in every direction the order of the label and the input is swapped. |
 | `rules` | `RuleExpression<string \| null>` |  |  | vee-validate rules for this field. Only inside a `BbForm`. |
-| `type` | `"text" \| "search" \| "email" \| "url" \| "tel" \| "password" \| undefined` | `"text"` |  | Type of the input. Restricted to the textual input types this component supports — use `BbNumberInput` for numbers and `BbDatePickerInput` for dates. |
+| `type` | `"text" \| "search" \| "tel" \| "url" \| "email" \| "password" \| undefined` | `"text"` |  | Type of the input. Restricted to the textual input types this component supports — use `BbNumberInput` for numbers and `BbDatePickerInput` for dates. |
 | `validationLabel` | `string \| undefined` |  |  | The field's name in validation messages (`{field}`): "Email is not valid". Defaults to the `label` (or `legend`), then "This field"; the field's `name` never shows. Set it when the label is not a good noun for a sentence (an icon-only label, a question) or is hidden. Only inside a `BbForm`. |
 | `validationMode` | `'aggressive'` \| `'balanced'` \| `'lazy'` \| `'submit-only'` \| `'submit-live'` |  |  | When this field checks itself while the user works: `aggressive` (every change), `balanced` (on leave, then every change while it shows an error), `lazy` (on leave only), `submit-only` (on submit only) or `submit-live` (on submit, then every change while it shows an error). "Leave" is blur for a text-like control, and focus leaving the whole control for a picker or a group; a checkbox or switch commits on click. Unset, the enclosing `BbForm`'s `validation-mode` applies, then the app's `formControls.validationMode` (`'balanced'`). Only inside a `BbForm`. |
 | `variant` | `'outline'` \| `'secondary'` \| `'none'` \| `'ghost'` | `'outline'` |  | Visual variant of the field box — the same names and tokens as the `BbButton` variants. Colours only: height, padding and border width are identical across variants, so a form never reflows when one changes. `'ghost'` has no border in any state (errors and warnings show through the icon and the messages); every variant keeps the focus ring. Register extra names with the plugin's `inputVariants` option. `'none'` is a blank starting point: the field keeps its structure and behaviour but takes no look, so your own classes don't fight a built-in one. You then own hover, focus, disabled and the error / warning states. Fine for a one-off; keep inline styling short, and register a real variant (`inputVariants`) when the look recurs. |
@@ -1326,7 +1328,7 @@ States are listed in precedence order: when two are on at once and their entries
 - `mousedown` — `(event: MouseEvent): void` — Emitted when a pointing device button is pressed over the input. Forwards the original DOM `MouseEvent`.
 - `mouseup` — `(event: MouseEvent): void` — Emitted when a pointing device button is released over the input. Forwards the original DOM `MouseEvent`.
 - `paste` — `(event: ClipboardEvent): void` — Emitted when content is pasted into the input. Forwards the original DOM `ClipboardEvent`.
-- `update:modelValue` — `(value: string \| null): void` — Emitted when the value changes. Carries the new string or `null` when cleared. When `mask` is set, emits the masked or unmasked string depending on `emitMasked`.
+- `update:modelValue` — `(value: string \| NullValueOf<E>): void` — Emitted when the value changes. Carries the new string, or the empty value (`null-value`, else the app's, `null` by default) when emptied. When `mask` is set, emits the masked or unmasked string depending on `emitMasked`.
 
 ## Slots
 

package/dist/ai/BbTextarea.md

@@ -63,7 +63,7 @@ Pick a sibling when the shape of the data is different:
 - a calendar date → `BbDatePickerInput`;
 - a value from a known set → `BbSelect` / `BbRadioGroup`.
 
-`v-model` binds a `string | null` — an emptied field emits `null` by default, or `''` when the plugin option `formControls` says so (see the installation guide § `formControls`).
+`v-model` binds a `string | null` — an emptied field emits `null` by default, or `''` when the plugin option `formControls` sets the `'string'` policy (see the installation guide § `formControls`). One field can differ from the app with `null-value="string"` or `null-value="null"`; the `update:modelValue` payload types to match (`string` with `'string'`).
 `label` is required (hide it visually with `hideLabel`, never drop it).
 
 ### Label
@@ -608,9 +608,9 @@ const snippet = 'npx bitboss-ui ai-init';
 ### Clearable & loading
 
 `clearable` reveals a clear button while the field has a value and is hovered or
-focused; clicking it emits `update:modelValue` with `null` and is suppressed on
-`disabled`/`readonly` fields. There is no separate `clear` event — watch the
-model for `null`.
+focused; clicking it emits `update:modelValue` with the empty value (`null` by
+default) and is suppressed on `disabled`/`readonly` fields. There is no separate
+`clear` event — watch the model for the empty value.
 
 `loading` shows a spinner in the append position. It is **visual only** — the
 field stays editable, so pair it with your own guard if the value must not
@@ -803,7 +803,7 @@ const notes = ref<string | null>(null);
 
 ### Events & v-model
 
-- `update:modelValue` — every value change; `string`, or the empty value when emptied (`null` by default, `''` with `formControls`).
+- `update:modelValue` — every value change; `string`, or the empty value when emptied (the `null-value` policy, else `formControls`, else `'null'`; `'string'` emits `''`).
 - `focus` / `blur` — forwarded `FocusEvent`s; they also drive the hint's
   show-on-focus behavior.
 - `input` — every keystroke (raw DOM event); `change` — on commit (blur), the
@@ -979,7 +979,7 @@ A `pt` value written in `<script>` (a constant, a preset, a wrapper's
   floor; the field starts there and never shrinks below it.
 - Avoid `labelMode="floating"` with `placeholder` — the resting label and the
   placeholder occupy the same spot.
-- An emptied field emits `null` by default (`''` with the `formControls` plugin option) — write `value ?? ''` when feeding
+- An emptied field emits `null` by default (`''` with `null-value="string"` or the `formControls` plugin option) — write `value ?? ''` when feeding
   APIs that require strings.
 - `counter` counts what `maxlength` counts: UTF-16 code units, so an emoji
   counts 2, and a line break counts 1 in the browser but 2 once a form
@@ -1044,6 +1044,7 @@ A `pt` value written in `<script>` (a constant, a preset, a wrapper's
 | `loading` | `boolean \| undefined` | `false` |  | Sets the component in a loading state, usually triggering some visual styles. |
 | `modelValue` | `string \| null \| undefined` |  |  | Used by v-model. |
 | `name` | `string \| undefined` |  |  | Defines the name of the input. |
+| `nullValue` | `E \| undefined` |  |  | What the field emits once the user empties it (typing it empty, the clear button): `'null'` emits `null`, `'string'` emits `''`. Unset, the app's `formControls.textareaNullValue` applies (`'null'` by default). Also types the `update:modelValue` payload: with `'string'` it is `string`. |
 | `persistentHint` | `boolean \| undefined` | `false` |  | Keeps the hint displayed. |
 | `placeholder` | `string \| undefined` |  |  | String displayed when there's no data. |
 | `prepend:icon` | `string \| undefined` |  |  | Name of the icon to be added at the start of the input. |
@@ -1104,7 +1105,7 @@ States are listed in precedence order: when two are on at once and their entries
 - `mousedown` — `(event: MouseEvent): void` — Emitted when a pointing device button is pressed over the textarea. Forwards the original DOM `MouseEvent`.
 - `mouseup` — `(event: MouseEvent): void` — Emitted when a pointing device button is released over the textarea. Forwards the original DOM `MouseEvent`.
 - `paste` — `(event: ClipboardEvent): void` — Native clipboard paste. Forwards the original DOM `ClipboardEvent`.
-- `update:modelValue` — `(value: string \| null): void` — Emitted when the value changes. Carries the new text or `null` when cleared.
+- `update:modelValue` — `(value: string \| NullValueOf<E>): void` — Emitted when the value changes. Carries the new text, or the empty value (`null-value`, else the app's, `null` by default) when emptied.
 
 ## Slots
 

package/dist/ai/changelog.json

@@ -1,7 +1,7 @@
 {
 	"schemaVersion": 3,
 	"library": "bitboss-ui",
-	"version": "3.0.0-beta.45",
+	"version": "3.0.0-beta.46",
 	"upgrade": "v2-to-v3",
 	"guide": "ai/guides/migration/v2-to-v3.md",
 	"legend": {
@@ -56,7 +56,8 @@
 		"3.0.0-beta.42",
 		"3.0.0-beta.43",
 		"3.0.0-beta.44",
-		"3.0.0-beta.45"
+		"3.0.0-beta.45",
+		"3.0.0-beta.46"
 	],
 	"unpublished": [
 		"3.0.0-alpha.2",
@@ -77,7 +78,7 @@
 	],
 	"summary": {
 		"renames": 213,
-		"behaviourBreaks": 168,
+		"behaviourBreaks": 169,
 		"bySurface": {
 			"prop": 15,
 			"option": 1,
@@ -5541,6 +5542,19 @@
 			"ruling": "owner 2026-10-01 (popover-in-dialog close)",
 			"guide": "v2-to-v3.md § 6 item 41 + BbDialog.guide.md / BbOffCanvas.guide.md § Lifecycle events",
 			"firstReleasedIn": "3.0.0-beta.44"
+		},
+		{
+			"id": "f302",
+			"kind": "behaviour",
+			"summary": "`formControls.textInputNullValue` / `textareaNullValue` values `null` / `''` → `'null'` / `'string'`; an old `''` falls back to `null`",
+			"components": [
+				"BbTextInput",
+				"BbTextarea"
+			],
+			"description": "formControls.textInputNullValue / textareaNullValue take a policy instead of the value: 'null' (the default) emits null, 'string' emits '' (it was null / ''). An old '' now falls back to null silently; TypeScript flags it in vite.config / app.use. The new per-field null-value prop takes the same values, and the Vite option also types update:modelValue (string with 'string') through the project bitboss-ui.d.ts",
+			"ruling": "owner 2026-10-05 (null-value policy)",
+			"guide": "v2-to-v3.md § 6 item 42 + installation-and-plugin-setup.md § formControls",
+			"firstReleasedIn": "3.0.0-beta.46"
 		}
 	]
 }