bitboss-ui 3.0.0-beta.64 → 3.0.0-beta.66

package/dist/ai/BbConfirm.md

@@ -29,7 +29,7 @@
 | `--gap` | `pt:action` | `BbButton` | between icon and label |
 | `--bg` | `pt:action` | `BbButton` | the plate |
 | `--bg-hover` | `pt:action` | `BbButton` | also the focus-visible fill; no change by default |
-| `--bg-pressed` | `pt:action` | `BbButton` | fill while [aria-pressed='true'] |
+| `--bg-pressed` | `pt:action` | `BbButton` | fill while pressed, or open (aria-expanded) |
 | `--fg` | `pt:action` | `BbButton` | label and icons (icons paint currentColor) |
 | `--border-color` | `pt:action` | `BbButton` | the frame; its width is --bw |
 | `--ring-color` | `pt:action` | `BbButton` | focus ring colour, per variant |
@@ -37,8 +37,8 @@
 | `--bw` | `pt:action` | `BbButton` | border width |
 | `--fg-hover` | `pt:action` | `BbButton` | label and icons on hover (and focus-visible) |
 | `--border-hover` | `pt:action` | `BbButton` | the frame on hover (and focus-visible) |
-| `--fg-pressed` | `pt:action` | `BbButton` | label and icons while [aria-pressed='true'] |
-| `--border-pressed` | `pt:action` | `BbButton` | the frame while [aria-pressed='true'] |
+| `--fg-pressed` | `pt:action` | `BbButton` | label and icons while pressed or open |
+| `--border-pressed` | `pt:action` | `BbButton` | the frame while pressed or open |
 | `--bg-disabled` | `pt:action` | `BbButton` | the plate while disabled (not loading) |
 | `--fg-disabled` | `pt:action` | `BbButton` | label and icons while disabled |
 | `--border-disabled` | `pt:action` | `BbButton` | the frame while disabled |
@@ -69,17 +69,22 @@ first — this is that gate.
 
 ### Setup
 
-Mount `<BbHost />` **exactly once, at the app root** (`App.vue` under Vue,
-`app.vue` under Nuxt, the `createInertiaApp` render root under Inertia) — a
-single instance serves the whole app, and `confirm()` can then be called from
-anywhere, components and stores alike. **Every call opens its own dialog**,
-and a new one covers the open one, which stays pending and comes back when
-the newer one closes (see [Several confirms at once](#several-confirms-at-once)).
-A second host renders nothing (a dev-mode console warning says so). With no
-host, `await confirm(...)` resolves `false` after one second, with a dev
-warning. A host that unmounts while its dialog is open (a layout the user
-navigated out of) gets the same second to come back; after that the open
-confirm resolves `false` without running a callback, so it never hangs.
+There is nothing to mount: the plugin (`app.use(bitbossUiPlugin)`, the Nuxt
+module) renders the app's `<BbHost />`, which renders every confirm.
+`confirm()` can be called from anywhere, components and stores alike.
+**Every call opens its own dialog**, and a new one covers the open one, which
+stays pending and comes back when the newer one closes (see
+[Several confirms at once](#several-confirms-at-once)). A host that unmounts
+while its dialog is open (an area layout the user navigated out of) gets one
+second to come back; after that the open confirm resolves `false` without
+running a callback, so it never hangs.
+
+```ts
+const { confirm } = useConfirm();
+if (await confirm({ title: 'Delete this file?', variant: 'destructive' })) {
+	await remove();
+}
+```
 
 **Areas with their own look.** A confirm takes the passthrough scope and the
 tokens of the component that called `useConfirm()`, wherever the host is
@@ -88,21 +93,6 @@ gets confirms in its area's look with nothing to set up. A component portal
 injects from that component's tree too. A `useConfirm()` called outside a
 component (a store, module level) takes the host's.
 
-```vue
-<template>
-	<RouterView />
-	<BbHost />
-</template>
-
-<script setup lang="ts">
-import { BbHost } from 'bitboss-ui';
-</script>
-```
-
-**Every example on this page mounts its own `<BbHost />` only because a
-standalone example has no app root to mount it in.** In a real app the host is
-already mounted at the root; a page that calls `confirm()` mounts nothing.
-
 Everything — content, buttons, behavior — travels in the message you pass to
 `confirm()`; the width every confirm defaults to is the plugin's
 `confirm.defaultSize` (see [Size, fullscreen and focus](#size-fullscreen-and-focus)).
@@ -111,8 +101,10 @@ otherwise).
 
 ### The destructive flow
 
-The canonical pattern: `await confirm(...)`, then act only on a truthy result.
-Set `variant: 'destructive'` so the dialog reads as dangerous and the Yes button
+Pick by where the work runs. A server call or a visit goes in Yes's `onClick`
+(next section): it spins there, and a failure rejects `confirm()`. A local,
+instant step (removing a row you hold, leaving a page) is `await confirm(...)`,
+then act only on a truthy result, as below. Set `variant: 'destructive'` so the dialog reads as dangerous and the Yes button
 inherits the destructive button style automatically. Everything after the
 `await` is your normal code — the dialog has already resolved. A `BbButton`
 whose click awaits `confirm()` spins until it is answered, like any async
@@ -148,18 +140,11 @@ click; `disable-auto-loading` on that button turns it off.
 		<p v-if="keys.length === 0" class="text-xs text-(--bb-text-muted)">
 			No active keys.
 		</p>
-
-		<!--
-			Standalone example: it mounts its own host because it has no app root.
-			A real app mounts exactly one <BbHost /> at the app root, and pages
-			mount none. See ai/guides/agent-contract.md § Global Host Rule.
-		-->
-		<BbHost />
 	</div>
 </template>
 <script setup lang="ts">
 import { ref } from 'vue';
-import { BbButton, BbHost, useConfirm } from 'bitboss-ui';
+import { BbButton, useConfirm } from 'bitboss-ui';
 
 type ApiKey = { id: string; label: string; masked: string; created: string };
 
@@ -210,15 +195,16 @@ plain string still works for one-offs) — you provide the
 
 ### Async actions and busy state
 
-For work that should finish _before_ the dialog closes, put it in the button's
+For server work (anything that can fail or take time), put it in the button's
 `onClick` instead of after the `await`: the button shows a spinner while the
 promise runs, the opposite button is disabled, the X is hidden and dismissal
 is blocked until it settles. Add `returning: true` to resolve with the
 callback's own return value rather than a plain boolean. One sharp edge:
 `confirm()` **rejects** when a button's `onClick` throws — wrap the await in
-`try/catch` when the work can fail. An Inertia visit returns no promise: wrap
-it, as in `ai/composables/useConfirm.md` § async work, rather than calling
-`close()` from its callbacks.
+`try/catch` when the work can fail. An Inertia visit returns no promise: make
+it with the Inertia helpers' `usePromiseRouter`, whose promise rejects with the
+error bag itself on a validation error (not `{ errors }`), rather than calling
+`close()` from its callbacks (`ai/composables/useConfirm.md` § Async work).
 
 **Async publish with a spinner**
 
@@ -236,17 +222,11 @@ it, as in `ai/composables/useConfirm.md` § async work, rather than calling
 				Publish article
 			</BbButton>
 		</div>
-		<!--
-			Standalone example: it mounts its own host because it has no app root.
-			A real app mounts exactly one <BbHost /> at the app root, and pages
-			mount none. See ai/guides/agent-contract.md § Global Host Rule.
-		-->
-		<BbHost />
 	</div>
 </template>
 <script setup lang="ts">
 import { ref } from 'vue';
-import { BbButton, BbHost, useConfirm } from 'bitboss-ui';
+import { BbButton, useConfirm } from 'bitboss-ui';
 
 const status = ref('Draft');
 
@@ -333,17 +313,11 @@ the array (`as const` keeps the literal types; without it each handler infers
 				Close editor
 			</BbButton>
 		</div>
-		<!--
-			Standalone example: it mounts its own host because it has no app root.
-			A real app mounts exactly one <BbHost /> at the app root, and pages
-			mount none. See ai/guides/agent-contract.md § Global Host Rule.
-		-->
-		<BbHost />
 	</div>
 </template>
 <script setup lang="ts">
 import { ref } from 'vue';
-import { BbButton, BbHost, useConfirm } from 'bitboss-ui';
+import { BbButton, useConfirm } from 'bitboss-ui';
 
 const decision = ref('none yet');
 
@@ -457,17 +431,11 @@ edits, so every implicit way out is blocked and the user answers with a button.
 			<BbButton variant="primary" @click="save">Save</BbButton>
 			<BbButton variant="ghost" @click="cancel">Cancel</BbButton>
 		</div>
-		<!--
-			Standalone example: it mounts its own host because it has no app root.
-			A real app mounts exactly one <BbHost /> at the app root, and pages
-			mount none. See ai/guides/agent-contract.md § Global Host Rule.
-		-->
-		<BbHost />
 	</div>
 </template>
 <script setup lang="ts">
 import { ref } from 'vue';
-import { BbButton, BbHost, BbTextInput, useConfirm } from 'bitboss-ui';
+import { BbButton, BbTextInput, useConfirm } from 'bitboss-ui';
 
 const saved = ref('Ada Lovelace');
 const draft = ref<string | null>(saved.value);
@@ -541,17 +509,11 @@ By default the dialog closes as soon as the promise settles. Set
 				<p class="text-center text-sm">{{ progressText }}</p>
 			</template>
 		</BbConfirmPortal>
-		<!--
-			Standalone example: it mounts its own host because it has no app root.
-			A real app mounts exactly one <BbHost /> at the app root, and pages
-			mount none. See ai/guides/agent-contract.md § Global Host Rule.
-		-->
-		<BbHost />
 	</div>
 </template>
 <script setup lang="ts">
 import { ref } from 'vue';
-import { BbButton, BbHost, BbConfirmPortal, useConfirm } from 'bitboss-ui';
+import { BbButton, BbConfirmPortal, useConfirm } from 'bitboss-ui';
 
 const status = ref('No export yet');
 const progressText = ref('Everything in this workspace is bundled into a ZIP.');
@@ -658,17 +620,11 @@ portal never renders.
 				</div>
 			</template>
 		</BbConfirmPortal>
-		<!--
-			Standalone example: it mounts its own host because it has no app root.
-			A real app mounts exactly one <BbHost /> at the app root, and pages
-			mount none. See ai/guides/agent-contract.md § Global Host Rule.
-		-->
-		<BbHost />
 	</div>
 </template>
 <script setup lang="ts">
 import { ref } from 'vue';
-import { BbButton, BbHost, BbConfirmPortal, useConfirm } from 'bitboss-ui';
+import { BbButton, BbConfirmPortal, useConfirm } from 'bitboss-ui';
 
 const result = ref('Member of Acme since 2024');
 
@@ -728,8 +684,8 @@ custom `actions` entry — at the button's root (a listener runs after the
 button's own). State `open`. Backdrop is `::backdrop` — CSS, not pt.
 
 `<BbHost />` takes no `pt`: every confirm is styled from the build plugin's
-global map, under `BbConfirm` (or a named scope's, with `<BbPtScope>` around
-the host). A muted wash on `header`, Yes/No spread on `footer`, a muted ✕ on
+global map, under `BbConfirm` (or a named scope's, for a confirm called
+inside a `<BbPtScope>`). A muted wash on `header`, Yes/No spread on `footer`, a muted ✕ on
 `close`, a primary ring with offset while `root:open`:
 
 ```ts

package/dist/ai/BbConfirmPortal.md

@@ -24,5 +24,5 @@
 
 ## See Also
 
-- [BbHost](./BbHost.md) — Renders confirm() and toast(); one, at the app root.
+- [BbHost](./BbHost.md) — Renders confirm() and toast(); the plugin renders one, place one per scoped area.
 - [useConfirm](./composables/useConfirm.md)

package/dist/ai/BbDatePicker.md

@@ -14,7 +14,6 @@
 
 | pt part | Lands on | In |
 | --- | --- | --- |
-| `pt:panel` | the root of `CommonPopover` | `CommonPopover` _(internal)_ |
 | `pt:panel` | `pt:root` of `BbOffCanvas` | `BbOffCanvas` ([contract](./BbOffCanvas.md)) |
 | `pt:sheet` | `pt:root` of `BbOffCanvas` | `BbOffCanvas` ([contract](./BbOffCanvas.md)) |
 
@@ -220,6 +219,42 @@ const time = ref<string | null>(null);
 </template>
 ```
 
+### Several months
+
+`:number-of-months="2"` puts two months side by side in the popover. It is the
+calendar's prop (`BbCalendar`), passed through: arrows and buttons page all the
+months at once, and the keyboard crosses from one month into the next. A
+popover too narrow for them all wraps the months onto the next row; the phone
+sheet always shows one month.
+
+**A trip across the month line**
+
+```vue
+<template>
+	<BbDatePicker
+		v-model="trip"
+		floating
+		label="Trip dates"
+		:number-of-months="2"
+		range
+	>
+		<template #activator="{ props, text }">
+			<BbButton v-bind="props" append:icon="lucide:calendar" variant="outline">
+				{{ text || 'Pick your trip' }}
+			</BbButton>
+		</template>
+	</BbDatePicker>
+</template>
+
+<script setup lang="ts">
+import { ref } from 'vue';
+import { BbButton, BbDatePicker } from 'bitboss-ui';
+
+/** Two months in the popover; the phone sheet still shows one. */
+const trip = ref<string[]>([]);
+</script>
+```
+
 ### Decorating days
 
 The picker passes its day slots straight to the calendar inside it, so the four
@@ -434,12 +469,13 @@ and digit typeahead; the time rail exposes labelled columns. Always pass a
 | `max` | `string \| undefined` |  |  | Maximum selectable value, in this `type`'s shape. A finer bound is accepted and ceiled to the unit, with a warning. |
 | `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. |
 | `modelValue` | `string \| string[] \| null` |  | yes | v-model: `null` when empty, a string, a `[start, end]` pair with `range`, or a sorted array with `multiple`. The string is `YYYY-MM-DD` when `floating` (`YYYY-MM` / `YYYY` for `month` / `year`), otherwise a zoned ISO instant (carrying the time under `datetime`). |
-| `multiple` | `boolean \| undefined` | `false` |  | Multi-selection: each pick toggles a value in a sorted array (days, months or years), and the panel stays open until dismissed. Needs an array `modelValue` (`[]` when empty, never `null`). Throws with `range` or `type="datetime"`. |
+| `multiple` | `boolean` | `false` |  | Multi-selection: each pick toggles a value in a sorted array (days, months or years), and the panel stays open until dismissed. Needs an array `modelValue` (`[]` when empty, never `null`). Throws with `range` or `type="datetime"`. |
+| `numberOfMonths` | `number \| undefined` | `1` |  | How many months the popover shows side by side (day grids only); the phone sheet always shows one. Too narrow for them all, the months wrap. |
 | `offCanvasProps` | `Partial<BbOffCanvasProps> \| undefined` |  |  | Props for the phone sheet (the `BbOffCanvas` that `adaptive` renders on mobile), spread over its defaults. A `pt` inside it styles only the sheet (passthrough guide § Inside the sheet). The sheet hides its ✕; `{ hideClose: false }` brings it back. |
 | `offset` | `number \| undefined` | `4` |  | Space the popover keeps from the activator. |
 | `padding` | `number \| undefined` |  |  | Minimum empty space to keep from the edge of the page. |
 | `placement` | `'top'` \| `'bottom'` \| `'left'` \| `'right'` \| `'top-start'` \| `'top-end'` \| `'right-start'` \| `'right-end'` \| `'bottom-start'` \| `'bottom-end'` \| `'left-start'` \| `'left-end'` |  |  | Position of the popover relative to the activator/anchor. |
-| `range` | `boolean \| undefined` | `false` |  | Enables range selection (`[start, end]`). |
+| `range` | `boolean` | `false` |  | Enables range selection (`[start, end]`). |
 | `readonly` | `boolean \| undefined` | `false` |  | Prevents opening while keeping the activator visible. |
 | `seconds` | `boolean \| undefined` | `false` |  | Adds the seconds column (requires `type="datetime"`). |
 | `selectable` | `((date: string) => boolean) \| undefined` |  |  | Predicate invoked per candidate; return `false` to disable it. Receives the value in this `type`'s shape — `YYYY-MM` under `month`, `YYYY` under `year`. |
@@ -456,7 +492,7 @@ and digit typeahead; the time rail exposes labelled columns. Always pass a
 | Part | What it is |
 | --- | --- |
 | `root` | The floating element — an invisible positioning wrapper; a `class` on the component lands here. No node on the phone sheet: style what you see with `panel`. |
-| `header` | The navigation bar: the previous / next arrows and the month / year headings. |
+| `header` | The navigation bar: the previous / next arrows and the month / year headings. With `number-of-months`, every month's header row (the later ones caption their month). |
 | `arrow` | The previous / next buttons — a broadcast. |
 | `month` | The month heading button; it opens the month panel. |
 | `year` | The year heading button; it opens the year panel. |
@@ -537,7 +573,7 @@ Set these on the element, or on a class you put on it, to retune this component
 - **CSS custom properties** listed on a node are declared on THAT node's root and read by elements inside it. Set one on that node's root or on the element inside it that reads it — the pt part that lands there is how you reach it (`pt:box="[--border-color:…]"` on a text input) — never on `BbDatePicker`'s root, where the node's own declaration masks it (design-tokens guide, _Overriding one from a consumer app_, rule 0).
 - Listed nodes are the ones `BbDatePicker`'s API reaches or that declare a documented CSS variable; the rest fold into "also mounts". The complete tree, repeats and undocumented locals included, is `manifest/components/BbDatePicker.tree.json`.
 
-- `BbDatePicker` _(this component)_ — its own template binds: `panel` → `div`, `panel` → `CommonPopover`; hands `BbCalendar` the pt map ` passthrough.forward(DATE_PICKER_CALENDAR_PARTS, BB_CALENDAR_PT.states) ` (ours → theirs); hands `BbOffCanvas` the pt map `{ panel: 'root', sheet: 'root' }` (ours → theirs)
+- `BbDatePicker` _(this component)_ — its own template binds: `panel` → `div`; hands `BbCalendar` the pt map ` passthrough.forward(DATE_PICKER_CALENDAR_PARTS, BB_CALENDAR_PT.states) ` (ours → theirs); hands `BbOffCanvas` the pt map `{ panel: 'root', sheet: 'root' }` (ours → theirs)
   - `BbCalendar` _(public — [contract](./BbCalendar.md))_ — its own pt parts (`BbCalendar`): `header` → `div.bb-calendar__header`, `arrow` → `BbBaseButton`, `month` → `BbBaseButton`, `year` → `BbBaseButton`, `day` → `div.bb-calendar__day`, `dayButton` → `button.bb-calendar__day-button`; documented CSS variables: `--cell`, `--unit-row`; also mounts `ScaleFade`, `Slide`, `CalendarMonthPanel`, `CalendarYearPanel`
     - `BbBaseButton` _(public — [contract](./BbBaseButton.md))_ — its own pt parts (`BbBaseButton`): `root` → `RouterComponent`, `root` → `a`, `root` → `component`; also mounts `RouterComponent`
     - `CommonTimeSelector` _(internal — not importable, reach it through `BbCalendar`)_ — its own pt parts (`BbCalendar`): `header` → `div.bb-time-selector__header`, `cellColumnHeader` → `div.bb-time-selector__cell-column-header`, `item` → `BbBaseButton`; documented CSS variables: `--time-mark`; also mounts `BbBaseButton`

package/dist/ai/BbDatePickerInput.md

@@ -40,7 +40,7 @@
 | `--border-focus` | `pt:box` | `CommonFieldInput` | frame while focused, or --active |
 | `--ring-size` | `pt:box` | `CommonFieldInput` | ring width; 0 is a variant declining the ring |
 | `--ring-color` | `pt:box` | `CommonFieldInput` | ring colour; state owns it, not variants |
-| `--elev` | `pt:box` | `CommonFieldInput` | Resting lift, composed UNDER the ring at every box-shadow site below. `0 0 0 0 transparent` and not `none`, so the shadow list keeps a constant length and stays interpolable whatever a variant assigns — the same reason `--bb-elev` itself ships that value. |
+| `--elev` | `pt:box` | `CommonFieldInput` | Resting lift, alone in `box-shadow`: the ring is the box's outline (Q81.6), so a theme's `--elev: none` never takes the ring with it. |
 | `--frost` | `pt:box` | `CommonFieldInput` | Plate frost — a full `backdrop-filter` value (see --bb-surface-filter). Routed through a local rather than read from the token directly, so a chrome-less variant can decline it: frosting a ghost field gives it the plate it is contractually not supposed to have. |
 | `--inside-label-clearance` | `pt:box`, `pt:prefix`, `pt:suffix` | `CommonFieldInput` | Height and top padding added above the text for a label rendered inside the box. Zero here; the `--inside-label` rules at the bottom of this file raise it to one label line, or two with a description. |
 | `--w` | `pt:icon` | `BbIcon` | `--w` is set inline by BbIcon from the size prop. The `initial` default seals it: without it an ancestor's `--w` (e.g. a dropdown's width bridge) would inherit in and size the icon. The `--size` indirection stays so higher-specificity rules (e.g. `.bb-badge .bb-icon`) can re-point it. |
@@ -176,6 +176,36 @@ The value is typed `string | string[] | null` in either mode, so `v-model`
 needs nothing, and an explicit `@update:model-value` handler narrows in one
 line: `if (!Array.isArray(value)) return;` before treating it as the range.
 
+For a window that often crosses the month line, `:number-of-months="2"` shows
+two months side by side in the popover (one in the phone sheet). If the
+popover doesn't have room for both, the second month wraps under the first.
+
+**Booking — two months in the popover**
+
+```vue
+<template>
+	<BbDatePickerInput
+		v-model="booking"
+		class="max-w-sm"
+		floating
+		label="Check-in → check-out"
+		:min="today"
+		:number-of-months="2"
+		range
+	/>
+</template>
+
+<script setup lang="ts">
+import { ref } from 'vue';
+import dayjs from 'dayjs';
+import { BbDatePickerInput } from 'bitboss-ui';
+
+const today = dayjs().format('YYYY-MM-DD');
+/** Typed or picked: the popover shows this month and the next. */
+const booking = ref<string[]>([]);
+</script>
+```
+
 Range mode still lets the user **type** both the start and end dates directly —
 it does not force the field read-only. If a range comes in reversed (end before
 start) it is swapped for you on commit (see _Invalid input_). To prevent typing
@@ -613,7 +643,8 @@ the single tab stop). Once focused:
 
 - **arrow keys** move by day (←/→) and week (↑/↓);
 - **Home** / **End** jump to the week's edges, **PageUp** / **PageDown** change
-  month, and type-ahead jumps within the visible month;
+  month, and type-ahead jumps within the focused month (with
+  `number-of-months`, every key crosses into the next month on show);
 - **Enter** / **Space** select the focused day and close the surface;
 - the month and year headings open their own pick panels (Enter toggles them).
 
@@ -896,7 +927,7 @@ label>')` matches nothing; query each segment by its own label instead. See
 | `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. |
 | `hasWarnings` | `boolean \| undefined` | `false` |  | Define if the component should be in a warning state. Same chrome as errors with `--bb-warn`; errors take priority. |
-| `hideLabel` | `boolean \| undefined` | `false` |  | Visually hides the label of the input while maintaining accessibility. |
+| `hideLabel` | `boolean \| undefined` | `false` |  | Visually hides the label of the input while maintaining accessibility. Pair it with a `placeholder`: an empty field otherwise shows nothing saying what it is for. |
 | `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. |
@@ -910,11 +941,12 @@ label>')` matches nothing; query each segment by its own label instead. See
 | `min` | `string \| undefined` |  |  | Minimum selectable date in `YYYY-MM-DD` format — or, with `type="datetime"`, `YYYY-MM-DDTHH:mm` to tighten the boundary day to a minute. Values outside both patterns throw during setup to surface configuration mistakes. |
 | `modelValue` | `string \| string[] \| null \| undefined` |  |  | Used by v-model. Can be null, a single string, or an array of strings based on whether a range or single date is needed. |
 | `name` | `string \| undefined` |  |  | Defines the name of the input. |
+| `numberOfMonths` | `number \| undefined` | `1` |  | How many months the calendar popover shows side by side (day grids only); the phone sheet always shows one. Too narrow for them all, the months wrap. |
 | `offCanvasProps` | `Partial<BbOffCanvasProps> \| undefined` |  |  | Props for the phone sheet (the `BbOffCanvas` that `adaptive` renders on mobile), spread over its defaults. A `pt` inside it styles only the sheet (passthrough guide § Inside the sheet). The sheet hides its ✕; `{ hideClose: false }` brings it back. |
 | `persistentHint` | `boolean \| undefined` | `false` |  | Keeps the hint displayed. |
 | `placeholder` | `string \| undefined` |  |  | Text shown while the field is empty. |
 | `prepend:icon` | `string \| undefined` |  |  | Name of the icon to be added at the start of the input. |
-| `range` | `boolean \| undefined` | `false` |  | Selects a range of dates between two dates. It selects all of the days between start and end. |
+| `range` | `boolean` | `false` |  | Selects a range of dates between two dates. It selects all of the days between start and end. |
 | `readonly` | `boolean \| undefined` | `false` |  | Sets the input in a readonly state. |
 | `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. |
@@ -952,7 +984,7 @@ label>')` matches nothing; query each segment by its own label instead. See
 | `activator` | The button in the box that opens the calendar. Merged after the picker's own activator props and handlers, so a listener of yours runs after ours. Its glyph is not a part. |
 | `panel` | The calendar surface — the popover's painted bubble on desktop, the sheet itself on a phone. It carries the calendar's sizing tokens (`pt:panel="[--cell:36px]"`). |
 | `sheet` | The bottom sheet around the calendar on a phone only. |
-| `header` | The navigation bar: the previous / next arrows and the month / year headings. |
+| `header` | The navigation bar: the previous / next arrows and the month / year headings. With `number-of-months`, every month's header row (the later ones caption their month). |
 | `arrow` | The previous / next buttons — a broadcast. |
 | `month` | The month heading button; it opens the month panel. |
 | `year` | The year heading button; it opens the year panel. |
@@ -1032,7 +1064,7 @@ Set these on the element, or on a class you put on it, to retune this component
 - Listed nodes are the ones `BbDatePickerInput`'s API reaches or that declare a documented CSS variable; the rest fold into "also mounts". The complete tree, repeats and undocumented locals included, is `manifest/components/BbDatePickerInput.tree.json`.
 
 - `BbDatePickerInput` _(this component)_ — its own template binds: `controlAttrs` → `input.bb-segmented-field__input`, `input` → `input.bb-segmented-field__input`, `activator` → `button.bb-segmented-field__activator`, `suffix` → `span.bb-field-input__suffix`; hands `BbDatePicker` the pt map `passthrough.forward(PICKER_PARTS, BB_DATE_PICKER_PT.states)` (ours → theirs)
-  - `BbDatePicker` _(public — [contract](./BbDatePicker.md))_ — its own pt parts (`BbDatePicker`): `panel` → `div`, `panel` → `CommonPopover`; hands `BbCalendar` the pt map ` passthrough.forward(DATE_PICKER_CALENDAR_PARTS, BB_CALENDAR_PT.states) ` (ours → theirs); hands `BbOffCanvas` the pt map `{ panel: 'root', sheet: 'root' }` (ours → theirs); documented CSS variables: `--cell`, `--unit-row`; also mounts `CommonPopover`
+  - `BbDatePicker` _(public — [contract](./BbDatePicker.md))_ — its own pt parts (`BbDatePicker`): `panel` → `div`; hands `BbCalendar` the pt map ` passthrough.forward(DATE_PICKER_CALENDAR_PARTS, BB_CALENDAR_PT.states) ` (ours → theirs); hands `BbOffCanvas` the pt map `{ panel: 'root', sheet: 'root' }` (ours → theirs); documented CSS variables: `--cell`, `--unit-row`; also mounts `CommonPopover`
     - `BbCalendar` _(public — [contract](./BbCalendar.md))_ — its own pt parts (`BbCalendar`): `header` → `div.bb-calendar__header`, `arrow` → `BbBaseButton`, `month` → `BbBaseButton`, `year` → `BbBaseButton`, `day` → `div.bb-calendar__day`, `dayButton` → `button.bb-calendar__day-button`; documented CSS variables: `--cell`, `--unit-row`; also mounts `ScaleFade`, `Slide`, `CalendarMonthPanel`, `CalendarYearPanel`
       - `BbBaseButton` _(public — [contract](./BbBaseButton.md))_ — its own pt parts (`BbBaseButton`): `root` → `RouterComponent`, `root` → `a`, `root` → `component`; also mounts `RouterComponent`
       - `CommonTimeSelector` _(internal — not importable, reach it through `BbCalendar`)_ — its own pt parts (`BbCalendar`): `header` → `div.bb-time-selector__header`, `cellColumnHeader` → `div.bb-time-selector__cell-column-header`, `item` → `BbBaseButton`; documented CSS variables: `--time-mark`; also mounts `BbBaseButton`