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

package/README.md

@@ -57,7 +57,7 @@ Full detail: `dist/ai/guides/installation-and-plugin-setup.md`.
 
 ### Directives
 
-`vBbTooltip`, `vBbDropdown`, `vBbColor`, `vBbDate`, `vBbTime` — plus a
+`vBbTooltip`, `vBbDropdown`, `vBbColor`, `vBbDate`, `vBbTime`, `vBbHoverCard`, `vBbPopover` — plus a
 `Bb*DirectivePlugin` for each, for app-level registration. Prefer the directive
 over the component for simple no-slot cases.
 
@@ -79,7 +79,7 @@ Product-ready components with labels, hints, errors, and consistent styling:
 - **Forms & actions:** `BbTextInput`, `BbTextarea`, `BbNumberInput`, `BbSelect`, `BbSelectPopover`, `BbCheckbox`, `BbCheckboxGroup`, `BbRadio`, `BbRadioGroup`, `BbSwitch`, `BbSwitchGroup`, `BbSlider`, `BbRating`, `BbColorInput`, `BbColorPalette`, `BbCalendar`, `BbDatePicker`, `BbDatePickerInput`, `BbTimePicker`, `BbTimePickerInput`, `BbButton`, `BbBadge`, `BbBadgeButton`, `BbIndicator`, `BbTag`, `BbDropdown`, `BbDropdownGroup`, `BbDropdownButton`, `BbAsterisk`
 - **Feedback:** `BbAlert`, `BbProgress`, `BbSpinner`, `BbToast`, `BbToastPortal`, `BbTooltip`
 - **Layout & navigation:** `BbAccordion`, `BbCollapsible`, `BbTabs` (+ `BbTabsRoot`, `BbTabsList`, `BbTabsPanels`), `BbBreadcrumbs`, `BbPagination`, `BbSmoothHeight`
-- **Overlays & panels:** `BbDialog`, `BbConfirm`, `BbConfirmPortal`, `BbOffCanvas`, `BbPopover`
+- **Overlays & panels:** `BbDialog`, `BbConfirm`, `BbConfirmPortal`, `BbOffCanvas`, `BbPopover`, `BbHoverCard`
 - **Data:** `BbTable`, `BbTree`
 - **Media & files:** `BbAvatar`, `BbDropzone`, `BbIcon`
 - **Forms** (`BbForm` needs the `vee-validate` peer; an app without forms needs nothing): `BbForm`, `useBbFormContext`, and the 16 form controls join the form they are inside (plus `rules` / `validation-label` / `validation-mode` / `formless`; the field's path is its `name`, else its label).

package/bin/bitboss-ui-mcp.mjs

@@ -1188,7 +1188,11 @@ function getComponent({
 		// A directive (`v-bb-tooltip`, `vBbTooltip`) — review D3-13.
 		const directiveName = String(name ?? '')
 			.trim()
-			.replace(/^vBb([A-Z]\w*)$/, (_, word) => `v-bb-${word.toLowerCase()}`)
+			.replace(
+				/^vBb([A-Z]\w*)$/,
+				// `vBbHoverCard` → `v-bb-hover-card`, the registered name.
+				(_, word) => `v-bb-${word.replace(/(?<!^)([A-Z])/g, '-$1')}`
+			)
 			.toLowerCase();
 		const directive = (manifest.directives ?? []).find(
 			(d) => d.name === directiveName

package/bin/bitboss-ui.mjs

@@ -76,6 +76,8 @@ 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 { projectResolution } from '../scripts/lib/unimported-components.mjs';
 import { cssClassFindings } from '../scripts/lib/css-class-check.mjs';
 import {
 	cssLocalFindings,
@@ -1044,7 +1046,13 @@ 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),
+					// Q61.19: what the project registers globally.
+					unimported: { project: projectResolution(projectRoot) },
+				});
 		// 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,
@@ -1076,8 +1084,9 @@ async function checkCommand(
 	}
 
 	for (const [name, file] of projectLocal) warnLocal(name, file);
-	// Q60.6: a `vue-tsc` below 3 and a missing `checkUnknownComponents`, read
-	// from package.json and the tsconfig. One line each, never fatal.
+	// Q60.6: a `vue-tsc` below 3, read from package.json. One line, never
+	// fatal. (A missing `checkUnknownComponents` is no longer warned about:
+	// `unimported-component` covers it, Q61.19.)
 	warnings.push(...toolchainWarnings(projectRoot));
 
 	// Q25: a hand import of `bitboss-ui/styles.css` while the runtime plugin
@@ -1388,12 +1397,19 @@ Commands:
                       \`duplicate-field-identity\` (two validated fields in
                       one \`BbForm\` on the same path: the same \`name\`,
                       or the same label with no \`name\`),
+                      \`unimported-component\` (a \`.vue\` file uses a
+                      bitboss-ui tag it never imports and the project never
+                      registers globally: it renders as an empty element),
                       \`reactive-v-model\` (a \`v-model\` on a \`<script
                       setup>\` \`const x = reactive(…)\`: a production build
                       rejects the write-back; hold it in a \`ref()\`),
                       \`form-v-model\` (\`v-model\`, \`:model-value\` or an
                       \`@update:model-value\` listener on a \`BbForm\`: it
                       takes its object one way, \`:model="draft"\`),
+                      \`bare-portal-name\` (\`v-bb-popover="user-card"\` /
+                      \`v-bb-hover-card="user-card"\` without the inner
+                      quotes: an expression, not a portal name; write
+                      \`"'user-card'"\`),
                       \`positional-provider\` (an \`items\` provider with
                       positional arguments: it receives one object,
                       \`({ query, reason, modelValue, signal })\`),
@@ -1456,10 +1472,7 @@ Commands:
                       \`reason\` against one cause other than \`'search'\`;
                       check \`reason !== 'search'\`), \`vue-tsc-major\`
                       (\`vue-tsc\` below 3 in package.json: the generic
-                      components' props go unchecked),
-                      \`check-unknown-components\` (no
-                      \`vueCompilerOptions.checkUnknownComponents: true\` in
-                      the tsconfig; \`ai-init\` writes it).
+                      components' props go unchecked).
   changelog [--since <version>] [--until <version>] [--json]
                       Breaking changes between two releases — "what breaks if I
                       bump". \`--since\` is the version you are ON, and is

package/dist/ai/BbAccordion.md

@@ -39,7 +39,8 @@ Step down the ladder when the composed header doesn't fit:
   **`BbSmoothHeight`** (`./BbSmoothHeight.md`).
 
 The public surface is small on purpose: `v-model` (boolean), `eager`,
-`transition-duration`, `id`, two slots, and the `update:modelValue` event.
+`transition-duration`, `id`, `heading-level`, two slots, and the
+`update:modelValue` event.
 Everything else is composition.
 
 ### Composing an FAQ
@@ -489,6 +490,25 @@ references): the body region gets your id and the header gets `<id>_header`,
 already cross-wired via `aria-controls`/`aria-labelledby`. Omitted, a unique id
 is generated for you.
 
+### Headers in the page outline
+
+Set `heading-level` when the accordion's headers are section titles a screen
+reader user should find by jumping between headings: an FAQ, a settings page's
+sections. The header button then sits inside `<h1>`–`<h6>` (the APG accordion
+shape), named after your header text. Match the page outline: under an `<h2>`
+the panels take `3`, never a level picked for its size, because the heading
+looks the same at every level (its margins and font are reset). Leave it out
+for accordions inside a form, a card or a side panel, where the headers are
+controls, not titles.
+
+```vue
+<h2>Billing questions</h2>
+<BbAccordion v-model="open" :heading-level="3">
+	<template #header>Can I change plans?</template>
+	Yes, at any time.
+</BbAccordion>
+```
+
 ### Restyling with passthrough
 
 `pt` reaches a named part with a class list — or, in the object form, a
@@ -606,7 +626,8 @@ A `pt` value written in `<script>` (a constant, a preset, a wrapper's
 - The header is a real `button` with `aria-expanded`/`aria-controls`; the body
   is a `role="region"` labelled by the header via `aria-labelledby`. You add
   nothing — and you must not wrap the header slot in another interactive
-  element.
+  element. `heading-level` puts the button inside a heading (above); never wrap
+  the accordion in your own `<hN>` instead.
 - Keyboard comes free with the native button: Tab to the header, Enter/Space
   toggles. Closed content is `inert`, so it can never be tabbed into.
 - Provide a visible, meaningful header label; the chevron is decorative (mark
@@ -623,6 +644,7 @@ A `pt` value written in `<script>` (a constant, a preset, a wrapper's
 | --- | --- | --- | --- | --- |
 | `pt:<part>`, `pt:<part>:<state>`, `pt` | `PtValue` | | | Passthrough — a class list, or `{ class, style, attrs }`, bound to one named part of the component; the state form applies only while that state is on. Parts: `header`, `panel`, `root`. States: `open`. What each one is: _Passthrough parts and states_ below. `pt` is the object form with the same keys minus the prefix (`{ icon: '…', 'icon:loading': '…' }`). See `guides/passthrough.md`. In `<script>` a `pt` value is typed `BbAccordionProps['pt']` (`PtValue` is not exported): § Typing `pt` in `<script>`. |
 | `eager` | `boolean \| undefined` | `false` |  | Prevents rendering content before it's made visible. |
+| `headingLevel` | `1 \| 2 \| 3 \| 4 \| 5 \| 6 \| undefined` |  |  | Wraps the header button in a heading of this level (`<h1>`–`<h6>`), the APG accordion shape, so the header joins the page's outline. Match the level to where the accordion sits (a section under an `<h2>` takes `3`). No visual change: the heading's margins and font are reset. Omitted, there is no heading. |
 | `id` | `string \| undefined` |  |  | The root's `id`; the header button's id (`<id>_header`) derives from it. Generated when omitted. |
 | `modelValue` | `boolean \| undefined` | `false` |  | Used by v-model to trigger opening / closing the collapsible. An accordion with no `v-model` starts closed. |
 | `transitionDuration` | `number \| undefined` | `250` |  | How long the transition has to last in milliseconds |

package/dist/ai/BbCalendar.md

@@ -493,11 +493,22 @@ const isOpen = (date: string) => !closed.has(date);
 </style>
 ```
 
+### The first day of the week
+
+The grid's week starts on the active locale's day, from the dayjs pack the
+plugin bundled: Monday for `it`, `de`, `fr`, `es` or `en-gb`, Sunday for bare
+`en` (US English) and `pt` (Brazil), and Sunday for a locale with no pack. The
+weekday headers follow, and so does a locale switch at runtime. Pass
+`first-day-of-week` (`0` = Sunday … `6` = Saturday) when the app's week is not
+its language's — an `en` app for a European audience takes
+`:first-day-of-week="1"`. `BbDatePicker` and `BbDatePickerInput` take the same
+prop and the same default.
+
 ### Keyboard and accessibility
 
 The calendar is an ordinary control in the tab order: **one tab stop** lands
 on the day under the cursor (the value, or today), arrows move by day and
-week, Home / End jump to the week's ends, PageUp / PageDown page by month
+week, Home / End jump to the ends of the grid's row, PageUp / PageDown page by month
 (with Shift, by year), typing a day number jumps to it, Enter or Space picks.
 The grid is a `role="grid"` of `role="row"` / `gridcell` nodes; a picked day
 carries `aria-selected` and says "selected" in its name, a pending range
@@ -580,7 +591,7 @@ the page is `BbDatePicker`.
 | `activeSegment` | `'start'` \| `'end'` |  |  | Which end the time rail edits in range + `type="datetime"` (`v-model:active-segment`). Standalone use manages this internally; an embedding host (the date input) drives it from its focused field. Ignored outside range + datetime. |
 | `ampm` | `boolean \| undefined` | `false` |  | 12-hour display with an AM/PM column (requires `type="datetime"`); emits stay 24h. |
 | `disabled` | `boolean \| undefined` | `false` |  | Disables every cell, the navigation and the time rail. |
-| `firstDayOfWeek` | `0 \| 1 \| 2 \| 3 \| 4 \| 5 \| 6 \| undefined` | `1` |  | First day of the week (0 = Sunday … 6 = Saturday). |
+| `firstDayOfWeek` | `0 \| 1 \| 2 \| 3 \| 4 \| 5 \| 6 \| undefined` | `the locale's week start` |  | First day of the week (0 = Sunday … 6 = Saturday). Omitted, the active locale's week start: Monday for `it`, `de`, `fr`, `en-gb`…, Sunday for bare `en` (US) and `pt` (Brazil). |
 | `floating` | `boolean \| undefined` | `false` |  | Emit plain calendar strings instead of zoned ISO instants. Implied (and forced) by `type="month"` and `type="year"`. |
 | `max` | `string \| undefined` |  |  | Maximum selectable value, in this `type`'s shape. A finer bound is accepted and ceiled to the unit, with a warning. With `datetime`, on its own day the time rail disables the times after it. |
 | `min` | `string \| undefined` |  |  | Minimum selectable value, in this `type`'s shape — `YYYY-MM-DD` (`YYYY-MM-DDTHH:mm` with `datetime`, `YYYY-MM` with `month`, `YYYY` with `year`). A finer bound is accepted and floored to the unit, with a warning. With `datetime`, the grid disables the days before it and, on its own day, the time rail disables the times before it. |

package/dist/ai/BbColorPalette.md

@@ -827,4 +827,4 @@ Set these on the element, or on a class you put on it, to retune this component
 ## See Also
 
 - [BbColorInput](./BbColorInput.md) — Captures color values through input controls.
-- [BbPopover](./BbPopover.md) — Anchors floating content to reference elements.
+- [BbPopover](./BbPopover.md) — Anchors floating content to reference elements; also the v-bb-popover directive (its body is a BbPopoverPortal or a component).

package/dist/ai/BbDatePicker.md

@@ -420,7 +420,7 @@ and digit typeahead; the time rail exposes labelled columns. Always pass a
 | `disabled` | `boolean \| undefined` | `false` |  | Disables the activator and the calendar. |
 | `disableFlip` | `boolean \| undefined` | `false` |  | Disable the automatic flip to the opposite side on overflow. |
 | `eager` | `boolean \| undefined` | `false` |  | Render popover content before it is first shown. |
-| `firstDayOfWeek` | `0 \| 1 \| 2 \| 3 \| 4 \| 5 \| 6 \| undefined` | `1` |  | First day of the week (0 = Sunday … 6 = Saturday). |
+| `firstDayOfWeek` | `0 \| 1 \| 2 \| 3 \| 4 \| 5 \| 6 \| undefined` | `the locale's week start` |  | First day of the week (0 = Sunday … 6 = Saturday). Omitted, the active locale's week start: Monday for `it`, `de`, `fr`, `en-gb`…, Sunday for bare `en` (US) and `pt` (Brazil). |
 | `floating` | `boolean \| undefined` | `false` |  | Emit plain calendar strings instead of zoned ISO instants. Implied (and forced) by `type="month"` and `type="year"`. |
 | `label` | `string \| undefined` |  |  | Accessible label. The activator is named by it followed by the activator's own text ("Due date 12 Sep"), through `aria-labelledby`. |
 | `max` | `string \| undefined` |  |  | Maximum selectable value, in this `type`'s shape. A finer bound is accepted and ceiled to the unit, with a warning. |
@@ -542,4 +542,4 @@ Set these on the element, or on a class you put on it, to retune this component
 - [BbCalendar](./BbCalendar.md) — A calendar in place — the month grid (or month / year grid, or day grid plus time rail) with no popover and no field chrome; v-model of a day, range, set, month, year or datetime.
 - [BbDatePickerInput](./BbDatePickerInput.md) — Combines date selection with text input behavior.
 - [BbColorPalette](./BbColorPalette.md) — Opens an anchored popover color palette for color picking interactions.
-- [BbPopover](./BbPopover.md) — Anchors floating content to reference elements.
+- [BbPopover](./BbPopover.md) — Anchors floating content to reference elements; also the v-bb-popover directive (its body is a BbPopoverPortal or a component).

package/dist/ai/BbDatePickerInput.md

@@ -213,8 +213,10 @@ to catch config mistakes early — always pass the `YYYY-MM-DD` shape.
 
 For non-contiguous rules (no weekends, no holidays, only in-stock slots), pass a
 `selectable` predicate: it receives each date string and returns `false` to
-disable that day. `firstDayOfWeek` shifts the calendar grid (`0` = Sunday …
-`6` = Saturday).
+disable that day. The grid's week starts on the locale's day (Monday for
+`it` or `de`, Sunday for bare `en` and `pt`); `firstDayOfWeek` pins it
+(`0` = Sunday … `6` = Saturday) when the app's week differs from its
+language's.
 
 The example below combines a rolling `min`/`max` window, a weekdays-only
 predicate, `floating` output, and the `day:append` slot to dot specific days.
@@ -872,7 +874,7 @@ label>')` matches nothing; query each segment by its own label instead. See
 | `disabled` | `boolean \| undefined` | `false` |  | Disables the component. |
 | `disableWriting` | `boolean \| "mobile" \| "desktop" \| undefined` | `false` |  | Disables typing into the input. Use `'mobile'` to disable typing only on mobile, `'desktop'` to disable typing only on desktop. |
 | `errors` | `string \| string[] \| undefined` |  |  | Can be a string or an array of string containing the messages to display. They render in an `aria-live="polite"` region (announced when they appear) and, while the list is non-empty, are referenced FIRST from the control's `aria-describedby`, so the reason the field is invalid is re-read whenever the control regains focus. |
-| `firstDayOfWeek` | `0 \| 1 \| 2 \| 3 \| 4 \| 5 \| 6 \| undefined` |  |  | Defines the first day of the week with `0` meaning Sunday and `6` meaning Saturday. |
+| `firstDayOfWeek` | `0 \| 1 \| 2 \| 3 \| 4 \| 5 \| 6 \| undefined` | `the locale's week start` |  | First day of the week (0 = Sunday … 6 = Saturday). Omitted, the active locale's week start: Monday for `it`, `de`, `fr`, `en-gb`…, Sunday for bare `en` (US) and `pt` (Brazil). |
 | `floating` | `boolean \| undefined` | `false` |  | If true the date will have a format YYYY-MM-DD instead of the default ISO string. |
 | `formless` | `boolean \| undefined` | `false` |  | Keep this control out of the enclosing `BbForm` entirely: not submitted, not dirty, not reset, not validated. For a control that is not form data (a filter, a "show advanced" switch). |
 | `hasErrors` | `boolean \| undefined` | `false` |  | Define if the component should be in an error state. It usually attaches a CSS class for styling purposes. |

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 {
@@ -1212,4 +1214,4 @@ Set these on the element, or on a class you put on it, to retune this component
 
 - [BbOffCanvas](./BbOffCanvas.md) — Shows side-panel overlay content outside normal layout flow.
 - [BbConfirm](./BbConfirm.md) — Prompts users to confirm or cancel critical actions (includes co-located BbConfirmPortal export).
-- [BbPopover](./BbPopover.md) — Anchors floating content to reference elements.
+- [BbPopover](./BbPopover.md) — Anchors floating content to reference elements; also the v-bb-popover directive (its body is a BbPopoverPortal or a component).

package/dist/ai/BbDropdown.md

@@ -1661,6 +1661,18 @@ listeners attach to the referenced element. ARIA — `aria-haspopup`,
 too, the same as it would to the slot's `props`; don't hand-write your own
 `aria-*` attributes on it, or you get a double-set conflict.)
 
+**One per row is fine, even thousands.** Until someone presses, focuses or
+right-clicks the element, the directive builds no component: the element
+carries `aria-haspopup` / `aria-expanded` itself, and a handful of listeners on
+`document` serve every sleeping menu. A menu of plain action rows (no
+selectable group, no fetched `items`) goes back to sleep once it has closed, or
+when focus leaves an element whose menu never opened, so only the open menu
+is ever a component. Measured on 3,000 elements: mount and re-render cost
+about the same as the bare elements. Two things opt a binding out: `eager`, and
+an explicit `id` (it must stay resolvable by `useBbDropdownContext(id)`). Each
+then mounts a full `BbDropdown` (about 1 ms per element), so leave both off on
+long lists.
+
 **Menu on any element, no wrapper**
 
 ```vue
@@ -2249,5 +2261,5 @@ Set these on the element, or on a class you put on it, to retune this component
 
 - [BbDropdownButton](./BbDropdownButton.md) — A button with primary action and all other actions collected in a dropdown.
 - [BbButton](./BbButton.md) — Button with loading state, tooltip, and icon support.
-- [BbPopover](./BbPopover.md) — Anchors floating content to reference elements.
+- [BbPopover](./BbPopover.md) — Anchors floating content to reference elements; also the v-bb-popover directive (its body is a BbPopoverPortal or a component).
 - [BbBaseButton](./BbBaseButton.md) — Unstyled button/link primitive: element resolution (button/anchor/router link) and the full navigation engine, with no visual chrome. Use for any clickable or navigable surface that is not a variant-first BbButton — cards, list rows, custom links.

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:**