bitboss-ui 3.0.0-beta.65 → 3.0.0-beta.67

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
@@ -803,7 +759,7 @@ The map is typed where you write it by `definePt`, never with an imported
 
 | Prop | Type | Default | Required | Description |
 | --- | --- | --- | --- | --- |
-| `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: `action`, `close`, `content`, `footer`, `header`, `root`, `sheet`, `text`, `title`. States: `default`, `destructive`, `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 `BbConfirmProps['pt']` (`PtValue` is not exported): § Typing `pt` in `<script>`. |
+| `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: `action`, `close`, `content`, `footer`, `header`, `root`, `sheet`, `text`, `title`. States: `default`, `destructive`, `fullscreen`, `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 `BbConfirmProps['pt']` (`PtValue` is not exported): § Typing `pt` in `<script>`. |
 
 ## Passthrough parts and states
 
@@ -826,6 +782,7 @@ States are listed in precedence order: when two are on at once and their entries
 | State | When it is on |
 | --- | --- |
 | `open` | Component-wide: a confirm is showing. |
+| `fullscreen` | Component-wide: the showing confirm is fullscreen (its `fullscreen` option, or `'mobile'` on a phone). |
 | `default` | Component-wide, from the message: `variant: 'default'`. Merged after the part's base entry and before its states, so the real states still win. |
 | `destructive` | Component-wide, from the message: `variant: 'destructive'`. Below the real states, like every variant. |
 

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)) |
 
@@ -137,10 +136,11 @@ It mirrors `<input type="…">`, so the names should already be familiar:
 | ------------------ | -------------------- | --------------------- | ------------- |
 | `date` _(default)_ | the day grid         | `2026-08-14`          | ISO instant   |
 | `datetime`         | day grid + time rail | `2026-08-14` + `time` | ISO instant   |
+| `week`             | day grid, week rows  | `2026-W44`            | —             |
 | `month`            | the 12-month grid    | `2026-08`             | —             |
 | `year`             | the year list        | `2026`                | —             |
 
-`month` and `year` are **calendar labels, not instants**. A month has no
+`week`, `month` and `year` are **calendar labels, not instants**. A month has no
 timezone, and pinning one to an instant is how you lose it: the start of August
 in Rome is the 31st of July in UTC, so a value stored that way reads back as the
 wrong month. They force `floating`, ignore `utc`, and warn if you pass it.
@@ -164,6 +164,12 @@ selectable — it cannot silently delete the month you named.
 The month grid pages by year and the year list by decade; arrows, Home/End and
 PageUp/PageDown all keep working, one unit up.
 
+`type="week"` keeps the day grid and its keyboard, adds a week-number column
+(Monday first, always), and makes any day pick its ISO week: the value is
+`2026-W44`, the activator slot's `text` reads "Week 44, 2026", and `min` /
+`max` (a week or a date) enable a week only when all seven days are inside.
+See [BbCalendar § Weeks](./BbCalendar.md#weeks).
+
 ### Multi-selection
 
 `multiple` turns every pick into a toggle: the value is a **sorted array** and
@@ -220,6 +226,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
@@ -322,7 +364,8 @@ desktop, the sheet itself on a phone — it also carries the sizing tokens, so
 bottom sheet on a phone only, applied after `panel`), `header` (the
 navigation bar), `arrow` (the previous / next buttons), `month` and `year`
 (the heading buttons), `cellColumnHeader` (each weekday letter), `day` (one whole
-day cell) and `dayButton` (the button inside it), `monthItem` and
+day cell) and `dayButton` (the button inside it), `week` (one row with
+`type="week"`) and `weekNumber` (its ISO week number), `monthItem` and
 `yearItem` (one button of the month / year panel).
 
 States: `open` follows the surface; `arrow` is `disabled` at a `min` / `max`
@@ -330,7 +373,9 @@ bound; `month` and `year` are `active` while their panel is open. The cells
 resolve per node — on `day` and `dayButton`: `selected`, `disabled`, `today`,
 `outside` (a day of the previous or next month), `rangeStart` / `rangeEnd` /
 `inRange` (a committed range) and `highlighted` (the keyboard cursor). The
-panel items carry the same set without `today` and `outside`.
+panel items carry the same set without `today` and `outside`; the week rows
+(`week`, `weekNumber`) carry `selected`, `rangeStart`, `rangeEnd` and
+`inRange`, per row.
 
 `day` is the whole cell and `dayButton` the rounded mark inside it: a
 background on `pt:day` paints the full cell square, so restyle the mark on
@@ -418,7 +463,7 @@ and digit typeahead; the time rail exposes labelled columns. Always pass a
 
 | Prop | Type | Default | Required | Description |
 | --- | --- | --- | --- | --- |
-| `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: `arrow`, `cellColumnHeader`, `day`, `dayButton`, `header`, `item`, `month`, `monthItem`, `panel`, `root`, `sheet`, `year`, `yearItem`. States: `active`, `disabled`, `highlighted`, `inRange`, `open`, `outside`, `rangeEnd`, `rangeStart`, `selected`, `today`. 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 `BbDatePickerProps['pt']` (`PtValue` is not exported): § Typing `pt` in `<script>`. |
+| `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: `arrow`, `cellColumnHeader`, `day`, `dayButton`, `header`, `item`, `month`, `monthItem`, `panel`, `root`, `sheet`, `week`, `weekNumber`, `year`, `yearItem`. States: `disabled`, `open`, `highlighted`, `inRange`, `outside`, `rangeEnd`, `rangeStart`, `selected`, `today`, `active`. 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 `BbDatePickerProps['pt']` (`PtValue` is not exported): § Typing `pt` in `<script>`. |
 | `activator` | `ElementOrComponentRef \| undefined` |  |  | External activator element or component ref. When provided, the `activator` slot is not rendered and click + ARIA are attached programmatically to the referenced element — mirroring the `BbColorPalette` activator API. |
 | `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. |
 | `adaptive` | `boolean \| undefined` | ``config.adaptive` (`true`)` |  | On mobile, open in a bottom off-canvas sheet instead of a floating popover. When unset, falls back to the global `config.adaptive`. |
@@ -428,26 +473,27 @@ 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` | `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"`. |
+| `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). Ignored under `type="week"`: ISO weeks run Monday to Sunday, so a week grid always starts on Monday. |
+| `floating` | `boolean \| undefined` | `false` |  | Emit plain calendar strings instead of zoned ISO instants. Implied (and forced) by `type="week"`, `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. |
-| `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"`. |
+| `max` | `string \| undefined` |  |  | Maximum selectable value, in this `type`'s shape. A finer bound is accepted and ceiled to the unit, with a warning (`week`: as `min`). |
+| `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 week or a date with `week`, whole weeks only). 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-Www` / `YYYY-MM` / `YYYY` for `week` / `month` / `year`), otherwise a zoned ISO instant (carrying the time under `datetime`). |
+| `multiple` | `boolean` | `false` |  | Multi-selection: each pick toggles a value in a sorted array (days, weeks, 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`. |
+| `selectable` | `((date: string) => boolean) \| undefined` |  |  | Predicate invoked per candidate; return `false` to disable it. Receives the value in this `type`'s shape — `YYYY-Www` under `week` (so a week is enabled or disabled whole), `YYYY-MM` under `month`, `YYYY` under `year`. |
 | `step` | `number \| undefined` | `1` |  | Minute-column granularity and arrow stepping (requires `type="datetime"`). |
 | `time` | `string \| string[] \| null \| undefined` |  |  | Companion time model (`v-model:time`), 24-hour `HH:mm` / `HH:mm:ss`. With `floating` it is the only carrier of the time; otherwise it mirrors the time inside `modelValue`. Requires `type="datetime"`. |
 | `transitionDuration` | `number \| undefined` | `250` |  | Popover/sheet transition duration in milliseconds. |
-| `type` | `'date'` \| `'month'` \| `'year'` \| `'datetime'` | `"date"` |  | What the picker selects and emits: `date` (a day), `datetime` (a day plus a time rail), `month` (`YYYY-MM`) or `year` (`YYYY`). `month` / `year` force `floating`, ignore `utc`, and leave the time props inert. |
-| `utc` | `boolean \| undefined` | `false` |  | Emit UTC (`...Z`) instead of the local offset. Ignored with `floating`, and therefore with `type="month"`/`type="year"`. |
+| `type` | `'date'` \| `'month'` \| `'year'` \| `'week'` \| `'datetime'` | `"date"` |  | What the picker selects and emits: `date` (a day), `datetime` (a day plus a time rail), `week` (an ISO week, `YYYY-Www`: any day of a row picks its week), `month` (`YYYY-MM`) or `year` (`YYYY`). `week` / `month` / `year` force `floating`, ignore `utc`, and leave the time props inert. |
+| `utc` | `boolean \| undefined` | `false` |  | Emit UTC (`...Z`) instead of the local offset. Ignored with `floating`, and therefore with `type="week"`/`type="month"`/`type="year"`. |
 
 ## Passthrough parts and states
 
@@ -456,11 +502,13 @@ 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. |
 | `cellColumnHeader` | Each weekday letter above the grid — a broadcast. |
+| `week` | One row of seven days with `type="week"` — the band a picked week paints and the hover outline. A broadcast resolved per row. |
+| `weekNumber` | The ISO week number heading each row with `type="week"` — a broadcast resolved per row. |
 | `day` | One whole day cell — a broadcast resolved per day. A background here paints the full cell square; restyle the round mark on `dayButton`. |
 | `dayButton` | The button inside a day cell — the mark that shows selection. A broadcast resolved per day. |
 | `monthItem` | One month button of the month panel (the home grid of `type="month"`) — a broadcast resolved per month. |
@@ -475,10 +523,10 @@ States are listed in precedence order: when two are on at once and their entries
 | --- | --- |
 | `outside` | Per node, on `day` / `dayButton`: a day of the previous or next month, shown to fill the grid. |
 | `today` | Per node, on `day` / `dayButton`: today. |
-| `inRange` | Per node, on the cells (`day`, `dayButton`, `monthItem`, `yearItem`): inside a committed range, between its ends. |
-| `selected` | Per node, on the cells: a chosen day, month or year; on `item`, the picked time's entry in each column. |
-| `rangeStart` | Per node, on the cells: a committed range's first day, month or year. |
-| `rangeEnd` | Per node, on the cells: a committed range's last day, month or year. |
+| `inRange` | Per node, on the cells (`day`, `dayButton`, `monthItem`, `yearItem`) and the week rows (`week`, `weekNumber`): inside a committed range, between its ends. |
+| `selected` | Per node, on the cells: a chosen day, month or year; on `week` / `weekNumber`, a chosen week (a range's ends too, as on its days); on `item`, the picked time's entry in each column. |
+| `rangeStart` | Per node, on the cells and the week rows: a committed range's first day, week, month or year. |
+| `rangeEnd` | Per node, on the cells and the week rows: a committed range's last day, week, month or year. |
 | `disabled` | Component-wide while the picker is `disabled`. Also per node: on the cells, one outside `min` / `max` or refused by `selectable`; on `arrow`, at a bound or while the month / year panel is open. |
 | `active` | Per node, on `month` / `year`: its panel is open. |
 | `open` | Component-wide: the calendar is showing. |
@@ -537,8 +585,8 @@ 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)
-  - `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`
+- `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`, `week` → `div.bb-calendar__week`, `weekNumber` → `div.bb-calendar__week-number`, `day` → `div.bb-calendar__day`, `dayButton` → `button.bb-calendar__day-button`; documented CSS variables: `--cell`, `--unit-row`, `--wk`; 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`
   - `BbOffCanvas` _(public — [contract](./BbOffCanvas.md))_ — its own pt parts (`BbOffCanvas`): `header` → `div.bb-offcanvas__header`, `title` → `span.bb-offcanvas__title`, `description` → `p.bb-offcanvas__description`, `close` → `CloseButton`, `content` → `div.bb-offcanvas__content`, `footer` → `div.bb-offcanvas__footer`; documented CSS variables: `--stack-x`, `--snap-y`, `--stack-fill`, `--stack-transition-duration`, `--px`, `--handle-w`, `--handle-h`, `--handle-bg`, `--safe-top`, `--close-size`