bitboss-ui 3.0.0-beta.44 → 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/BbDropdownButton.md

@@ -65,6 +65,10 @@ descendants: a group, a nested array or an item with its own `items` (a
 submenu) has no single action for the button, so the component throws (a
 `TypeError`) instead of guessing.
 
+A computed `items` list that comes down to one entry can stay on this
+component: with nothing after the main action and no default slot, there is no
+menu, so the chevron goes and the control renders exactly like a `BbButton`.
+
 **Save / Save as draft**
 
 ```vue

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/BbRadioGroup.md

@@ -888,7 +888,7 @@ for a preset that fits any row type (never `<any>`), not an imported
 | `itemLayout` | `FieldLayout \| undefined` | `'auto'` |  | How each row's input and label sit together — the keywords of `layout`: `'auto'`, `'vertical'` (the input above the label), `'horizontal'` (50/50), `'label-fill'` (the label takes the row's free space — pair it with `list-layout="vertical-stretch"` and `item-reverse` for a settings list), `'input-fill'`, or a two-word ratio pattern like `'xx xxxxx'`, read in on-screen order. |
 | `itemProps` | `BbOptionGroupItemProps<T> \| undefined` |  |  | ADDITIONAL row fields resolved from each item — never its text or value (those stay on `itemText` / `itemValue`). Option groups accept one field: - `description` — a muted line under the option label, beside the control; it may wrap. Either an object with a path or getter per field (`{ description: 'email' }`) or a function returning the fields (`(item) => ({ description: item.email })`). Without it no field renders — an item's own `description` is never read implicitly — and an empty value renders nothing for that item. The description is announced as the option's description, never part of its name. To disable individual options use `selectable`. |
 | `itemReverse` | `boolean \| undefined` | `false` |  | Swaps each row's input and label from their natural order (input first), in every `item-layout`. `reverse` swaps the legend and the options instead. |
-| `items` | `T[] \| ((context: BbCheckboxGroupItemsContext) => T[] \| Promise<T[]>)` |  | yes | The options: an array, or a provider function called with ONE context object and returning the rows, sync or async. The context carries: - `reason` — why this call happened: `'initial'` (the first load, on mount), `'dependencies'` (a `dependencies` entry or the `items` function changed; a retry arrives this way) or `'model'` (the model changed from outside and the options cannot resolve it). The group has no search field, so it never passes `query`; - `modelValue` — the `v-model` as-is; - `signal` — an `AbortSignal`, aborted when a newer call starts or the group is disposed; pass it to every request. A provider signals a failure by THROWING, never by returning `[]`: the rows are cleared, nothing is pruned, and `#empty` receives the `error` (`failed-text` is shown). Zero-argument providers keep working. Annotate the parameter `BbRadioGroupItemsContext`. |
+| `items` | `T[] \| ((context: BbRadioGroupItemsContext) => T[] \| Promise<T[]>)` |  | yes | The options: an array, or a provider function called with ONE context object and returning the rows, sync or async. The context carries: - `reason` — why this call happened: `'initial'` (the first load, on mount), `'dependencies'` (a `dependencies` entry or the `items` function changed; a retry arrives this way) or `'model'` (the model changed from outside and the options cannot resolve it). The group has no search field, so it never passes `query`; - `modelValue` — the `v-model` as-is; - `signal` — an `AbortSignal`, aborted when a newer call starts or the group is disposed; pass it to every request. A provider signals a failure by THROWING, never by returning `[]`: the rows are cleared, nothing is pruned, and `#empty` receives the `error` (`failed-text` is shown). Zero-argument providers keep working. Annotate the parameter `BbRadioGroupItemsContext`. |
 | `itemText` | `ItemAccessor<T, string> \| undefined` | `JSON.stringify(item)` |  | Defines a path that returns a property of the object to use as text or a function that returns a string. |
 | `itemValue` | `ItemAccessor<T> \| undefined` | `the whole item` |  | Defines a path that returns a property of the object to use as value or a function that returns any value. |
 | `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. |

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/BbSelect.md

@@ -765,7 +765,8 @@ a `Promise<T[]>`. Annotate the parameter `BbSelectItemsContext`:
   Branch on `reason !== 'search'`, never on one non-search value, so any call
   the select fires lands on the right side.
 - `modelValue` — your v-model as-is (an array in multiple mode, the raw value —
-  possibly `null` — otherwise), typed `any`; narrow it to your own model type.
+  possibly `null` — otherwise), typed `any` by default. Pass your model type to
+  the context type to check it: `BbSelectItemsContext<string[]>`.
 - `signal` — an `AbortSignal`, aborted when a newer call starts or the select
   is disposed. Pass it to every request.
 

package/dist/ai/BbSelectPopover.md

@@ -1792,7 +1792,7 @@ A `pt` value written in `<script>` (a constant, a preset, a wrapper's
 | `id` | `string \| undefined` |  |  | Seeds the ids the popover sets: its listbox is `<id>_listbox` (the activator's `aria-controls`) and each option's id derives from it. Generated when omitted. |
 | `itemHeight` | `number \| undefined` | `28` |  | Height of the options in the listbox (px). Defaults to 28px (24px compact; 44px / 36px on mobile viewports). An explicit value wins on every viewport. |
 | `itemProps` | `BbSelectItemProps<Item> \| undefined` |  |  | ADDITIONAL row fields resolved from each item — never its text or value (those stay on `itemText` / `itemValue`). Accepted fields: - `description` — a muted line under the option label. Setting it gives every row a fixed two-line height (the list is virtualized); the description stays on one line and ellipsizes. Announced as the option's description, never part of its name; matched by the search with the text when `filterBy` is empty. - `prepend:icon` — an icon before the label. - `append:icon` — an icon after the label; on the selected row the check takes its place. Either an object with a path or getter per field (`{ description: 'email', 'prepend:icon': 'icon' }`) or a function returning the fields (`(item) => ({ description: item.email })`). Without it no field renders — nothing is read off the item implicitly — and an empty value renders nothing for that item. Never shown in the trigger or the chips. To disable individual options use `selectable`. |
-| `items` | `Item[] \| ((context: BbSelectItemsContext) => Item[] \| Promise<Item[]>)` | `[]` | yes | The options: an array, or a provider function called with ONE context object and returning the rows, sync or async. The context carries: - `query` — what the user typed, `''` until they type; - `reason` — why this call happened: `'search'` (the user typed, and nothing else), `'initial'` (the first load, on mount or on the first open), `'dependencies'` (a `dependencies` entry or the `items` function changed; a retry arrives this way), `'model'` (the model changed from outside and the options cannot resolve it), `'reopen'` (the panel reopened over a searched list). To resolve the selection by id, branch on `reason !== 'search'`; - `modelValue` — the raw v-model: an array in `multiple` mode, the raw model value (possibly `null`) in single mode; - `signal` — an `AbortSignal`, aborted when a newer call starts or the component is disposed; pass it to every request. A provider signals a failure by THROWING, never by returning `[]`: the rows are cleared, nothing is pruned, and `#empty` receives the `error` (`failed-text` is shown). A newer call aborts the one in flight, and the aborted call's rejection or resolution is dropped silently. Zero-argument providers keep working. Annotate the parameter `BbSelectPopoverItemsContext`. |
+| `items` | `Item[] \| ((context: BbSelectPopoverItemsContext) => Item[] \| Promise<Item[]>)` | `[]` | yes | The options: an array, or a provider function called with ONE context object and returning the rows, sync or async. The context carries: - `query` — what the user typed, `''` until they type; - `reason` — why this call happened: `'search'` (the user typed, and nothing else), `'initial'` (the first load, on mount or on the first open), `'dependencies'` (a `dependencies` entry or the `items` function changed; a retry arrives this way), `'model'` (the model changed from outside and the options cannot resolve it), `'reopen'` (the panel reopened over a searched list). To resolve the selection by id, branch on `reason !== 'search'`; - `modelValue` — the raw v-model: an array in `multiple` mode, the raw model value (possibly `null`) in single mode; - `signal` — an `AbortSignal`, aborted when a newer call starts or the component is disposed; pass it to every request. A provider signals a failure by THROWING, never by returning `[]`: the rows are cleared, nothing is pruned, and `#empty` receives the `error` (`failed-text` is shown). A newer call aborts the one in flight, and the aborted call's rejection or resolution is dropped silently. Zero-argument providers keep working. Annotate the parameter `BbSelectPopoverItemsContext`. |
 | `itemText` | `ItemAccessor<Item, string> \| undefined` | `JSON.stringify(item)` |  | Path to item property for display text or function to extract it. |
 | `itemValue` | `ItemAccessor<Item> \| undefined` | `the whole item` |  | Path to item property for value or function to extract it. |
 | `loading` | `boolean \| undefined` | `false` |  | Display the loading state styles. |

package/dist/ai/BbTable.md

@@ -323,8 +323,8 @@ reach for it when a single phone cut is all the table needs.
 **When a table does scroll, it says so.** The edge with content hidden past
 it fades what sits against it (the root carries `bb-table--overflow-left` /
 `bb-table--overflow-right` while it does), so a reader sees at rest that the
-table goes on. With pinned columns on that side the fade starts at their
-inner edge, and reads as the pinned column's shadow. Nothing to set up. Keep
+table goes on. With pinned columns on that side the pinned column casts a
+thin shadow over the content scrolled under it instead. Nothing to set up. Keep
 the sticky/pinned identity column for the case where the full grid really
 must stay reachable (a spreadsheet-shaped tool), not as the default for a
 records list.
@@ -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) =>
@@ -3111,13 +3111,25 @@ the one knob and everything pinned follows:
 }
 ```
 
-**The scroll cue is a mask on the root.** While content is hidden past an
-edge the root carries `bb-table--overflow-left` / `bb-table--overflow-right`
-and a `mask-image` fades that edge (to 30% over 20px, never to nothing; it paints no
-element and takes no click). Hook your own treatment on the two classes, or
-turn the fade off with `.my-table.bb-table { mask-image: none; }`. A mask
-clips whatever the root paints outside its own box — give a scrolling table
-a `border`, never an outer `box-shadow`.
+**The scroll cue.** While content is hidden past an edge the root carries
+`bb-table--overflow-left` / `bb-table--overflow-right`. On a side with no
+pinned column a `mask-image` on the root fades that edge (to 30% over 20px,
+never to nothing; it paints no element and takes no click). Turn it off with
+`.my-table.bb-table { mask-image: none; }`. A mask clips whatever the root
+paints outside its own box, so give a scrolling table a `border`, never an
+outer `box-shadow`. A mask also fades row tints in its band, which is why a
+side WITH a pinned column (the root carries `bb-table--pinned-left` /
+`bb-table--pinned-right`) is not masked: its innermost pinned cell casts a
+strip over the scrolled content instead, so a hovered or highlighted row keeps
+its tint up to the pinned cell. Size or tint the strip with two knobs on the
+root (`--cue-w: 0px` turns it off):
+
+```css
+.my-table.bb-table {
+	--cue-w: 12px; /* default 8px */
+	--cue: rgb(0 0 0 / 0.15); /* the strip's dark end; it fades to transparent */
+}
+```
 
 #### The table as a card
 
@@ -3902,6 +3914,10 @@ Set these on the element, or on a class you put on it, to retune this component
 | `--fade-r` | `0px` |  |
 | `--fade-a-l` | `1` |  |
 | `--fade-a-r` | `1` |  |
+| `--cue-l` | `0px` |  |
+| `--cue-r` | `0px` |  |
+| `--cue-w` | `8px` |  |
+| `--cue` | `rgb(0 0 0 / 0.1)` |  |
 
 ## Component tree
 

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.44",
+	"version": "3.0.0-beta.46",
 	"upgrade": "v2-to-v3",
 	"guide": "ai/guides/migration/v2-to-v3.md",
 	"legend": {
@@ -55,7 +55,9 @@
 		"3.0.0-beta.41",
 		"3.0.0-beta.42",
 		"3.0.0-beta.43",
-		"3.0.0-beta.44"
+		"3.0.0-beta.44",
+		"3.0.0-beta.45",
+		"3.0.0-beta.46"
 	],
 	"unpublished": [
 		"3.0.0-alpha.2",
@@ -76,7 +78,7 @@
 	],
 	"summary": {
 		"renames": 213,
-		"behaviourBreaks": 168,
+		"behaviourBreaks": 169,
 		"bySurface": {
 			"prop": 15,
 			"option": 1,
@@ -5540,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"
 		}
 	]
 }