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

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, 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
@@ -382,17 +412,18 @@ const setPreset = (days: number) => {
 </script>
 ```
 
-### `type` — day, month, year, or day + time
+### `type` — day, week, month, year, or day + time
 
 `type` decides which segments the field renders and what it emits. It mirrors
 `<input type="…">`:
 
-| `type`             | segments       | emits                 | range emits              |
-| ------------------ | -------------- | --------------------- | ------------------------ |
-| `date` _(default)_ | `DD/MM/YYYY`   | ISO / `YYYY-MM-DD`    | `[start, end]`           |
-| `datetime`         | + `HH:mm(:ss)` | ISO carrying the time | `[start, end]`           |
-| `month`            | `MM/YYYY`      | `2026-08`             | `['2026-01', '2026-03']` |
-| `year`             | `YYYY`         | `2026`                | `['2026', '2028']`       |
+| `type`             | segments       | emits                 | range emits                |
+| ------------------ | -------------- | --------------------- | -------------------------- |
+| `date` _(default)_ | `DD/MM/YYYY`   | ISO / `YYYY-MM-DD`    | `[start, end]`             |
+| `datetime`         | + `HH:mm(:ss)` | ISO carrying the time | `[start, end]`             |
+| `week`             | `W44 2026`     | `2026-W44`            | `['2026-W41', '2026-W43']` |
+| `month`            | `MM/YYYY`      | `2026-08`             | `['2026-01', '2026-03']`   |
+| `year`             | `YYYY`         | `2026`                | `['2026', '2028']`         |
 
 ```vue
 <BbDatePickerInput v-model="period" label="Reporting period" type="month" />
@@ -405,7 +436,7 @@ promising `DD/MM/YYYY` to a two-segment field would be worse than no hint at
 all. The calendar button opens the matching terminal grid, so typing and
 picking always produce the same shape.
 
-`month` and `year` are **calendar labels, not instants**: they force `floating`,
+`week`, `month` and `year` are **calendar labels, not instants**: they force `floating`,
 ignore `utc`, and make the time props inert. This is deliberate rather than
 squeamish — the start of August in Rome is the 31st of July in UTC, so a month
 stored as an instant reads back as the wrong month for half the world.
@@ -416,6 +447,60 @@ a DEV warning, so `min="2026-03-15"` under `type="month"` leaves the whole of
 March selectable instead of quietly deleting it. `selectable` receives the same
 shape it emits.
 
+#### Weeks
+
+`type="week"` types and emits an ISO 8601 week. The field shows a literal `W`,
+a week segment and a year segment (`W44 2026`, in every locale), and the
+calendar picks the whole week of any day you click, with a week-number column
+and Monday-first rows. The year segment is the **ISO week-year**: the week of
+29 December 2025 is `W01 2026`. A typed `W53` in a year with 52 weeks snaps
+to `W52` when the field is read, as 31 February snaps to the 28th.
+
+`min` / `max` take a week (`max="2026-W52"`) or a date, and a week counts only
+when all seven days are inside: `min="2026-10-28"` (a Wednesday) leaves that
+week out, and a typed week below it moves to the first whole week inside, with
+the usual `error` event. The trigger's accessible name reads the week and its
+dates ("week 44, October 26 – November 1, 2026"); the dates are never shown.
+The calendar side — the week rows, the hover outline, ranges of weeks — is
+[BbCalendar § Weeks](./BbCalendar.md#weeks), and `pt:week` /
+`pt:week-number` restyle its rows from this field.
+
+**A delivery week and a sprint of weeks**
+
+```vue
+<template>
+	<div class="grid max-w-xs gap-4">
+		<BbDatePickerInput
+			v-model="delivery"
+			description="Orders ship on the Monday of the week you pick."
+			label="Delivery week"
+			min="2026-10-28"
+			type="week"
+		/>
+		<BbDatePickerInput
+			v-model="sprint"
+			label="Sprint"
+			max="2026-W52"
+			range
+			type="week"
+		/>
+	</div>
+</template>
+
+<script setup lang="ts">
+import { ref } from 'vue';
+import { BbDatePickerInput } from 'bitboss-ui';
+
+/**
+ * `type="week"`: the value is the ISO week, `YYYY-Www`. Any day of a calendar
+ * row picks its week; the field types it as `W44 2026`. `min` on a Wednesday
+ * leaves that week out, because a week counts only when all seven days fit.
+ */
+const delivery = ref<string | null>('2026-W45');
+const sprint = ref<string[]>(['2026-W45', '2026-W46']);
+</script>
+```
+
 ### Time selection
 
 Set `type="datetime"` and the field grows 24-hour `HH:mm` segments after the date
@@ -613,7 +698,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).
 
@@ -733,12 +819,17 @@ table cell (`<BbDatePickerInput compact hide-label variant="ghost" />`) — no
 register through the plugin's `inputVariants` option. The full ladder is in
 the `BbTextInput` guide.
 
+The calendar panel renders inside the field, so it reads the field's
+`--bb-radius`, capped at half a control height: a pill field
+(`style="--bb-radius: 999px"`) gets a rounded panel, never a clipped one, and a
+`0px` app stays square.
+
 ### Restyling with passthrough
 
 `pt` reaches a named part of the control with a class list — or, in the
 object form, a style and attributes — optionally only while a state is on.
-Parts: `root` (the container), `label`, `description`, `message` (the errors / warnings region — one node each, only one ever shows), `hint` (the helper line — shown on focus, or always with `persistent-hint`), `box` (the bordered field box), `input` (the native control), `icon` (`prepend:icon` + `append:icon` — a broadcast; the state glyphs are chrome), `spinner` (the spinner shown while `loading`), `prefix`, `suffix`, `clear` (the ✕ that empties the field). Plus `panel` (the calendar surface you see — the popover's painted bubble on desktop, the sheet itself on a phone; it carries the sizing tokens, so `pt:panel="[--px:2px]"` tightens it), `sheet` (the bottom sheet on a phone only) and the calendar's own parts, forwarded to it: `header`, `arrow`, `month`, `year`, `cellColumnHeader`, `day` (the whole cell), `dayButton` (the mark inside it), `monthItem` and `yearItem` — the `BbDatePicker` guide describes each node. `input` is every segment field; the calendar trigger is `activator`.
-States: `errors`, `warnings` (never beside errors), `loading`, `disabled`, `readonly`, `hasValue` (written `pt:box:has-value`). Plus `open` (the calendar is showing), and the calendar's per-node states: `selected`, `disabled`, `today`, `outside`, `rangeStart` / `rangeEnd` / `inRange` and `highlighted` on the cells, `active` on `month` / `year`. A name outside that list is a type error and an
+Parts: `root` (the container), `label`, `description`, `message` (the errors / warnings region — one node each, only one ever shows), `hint` (the helper line — shown on focus, or always with `persistent-hint`), `box` (the bordered field box), `input` (the native control), `icon` (`prepend:icon` + `append:icon` — a broadcast; the state glyphs are chrome), `spinner` (the spinner shown while `loading`), `prefix`, `suffix`, `clear` (the ✕ that empties the field). Plus `panel` (the calendar surface you see — the popover's painted bubble on desktop, the sheet itself on a phone; it carries the sizing tokens, so `pt:panel="[--px:2px]"` tightens it), `sheet` (the bottom sheet on a phone only) and the calendar's own parts, forwarded to it: `header`, `arrow`, `month`, `year`, `cellColumnHeader`, `day` (the whole cell), `dayButton` (the mark inside it), `week` (one row with `type="week"`), `weekNumber` (its ISO week number), `monthItem` and `yearItem` — the `BbDatePicker` guide describes each node. `input` is every segment field; the calendar trigger is `activator`.
+States: `errors`, `warnings` (never beside errors), `loading`, `disabled`, `readonly`, `hasValue` (written `pt:box:has-value`). Plus `open` (the calendar is showing), and the calendar's per-node states: `selected`, `disabled`, `today`, `outside`, `rangeStart` / `rangeEnd` / `inRange` and `highlighted` on the cells, `selected` / `rangeStart` / `rangeEnd` / `inRange` on the week rows (`pt:week:selected`, `pt:week-number`), `active` on `month` / `year`. A name outside that list is a type error and an
 ESLint error.
 
 The invoice due-date field above, restyled through those parts: a muted
@@ -878,7 +969,7 @@ label>')` matches nothing; query each segment by its own label instead. See
 
 | 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: `activator`, `arrow`, `box`, `cellColumnHeader`, `clear`, `day`, `dayButton`, `description`, `header`, `hint`, `icon`, `input`, `item`, `label`, `message`, `month`, `monthItem`, `panel`, `prefix`, `root`, `sheet`, `spinner`, `suffix`, `year`, `yearItem`. States: `active`, `disabled`, `errors`, `ghost`, `hasValue`, `highlighted`, `inRange`, `loading`, `open`, `outline`, `outside`, `rangeEnd`, `rangeStart`, `readonly`, `secondary`, `selected`, `today`, `warnings`. 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 `BbDatePickerInputProps['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: `activator`, `arrow`, `box`, `cellColumnHeader`, `clear`, `day`, `dayButton`, `description`, `header`, `hint`, `icon`, `input`, `item`, `label`, `message`, `month`, `monthItem`, `panel`, `prefix`, `root`, `sheet`, `spinner`, `suffix`, `week`, `weekNumber`, `year`, `yearItem`. States: `disabled`, `errors`, `ghost`, `hasValue`, `loading`, `open`, `outline`, `readonly`, `secondary`, `warnings`, `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 `BbDatePickerInputProps['pt']` (`PtValue` is not exported): § Typing `pt` in `<script>`. |
 | `adaptive` | `boolean \| undefined` | ``config.adaptive` (`true`)` |  | On mobile the calendar opens inside a bottom off-canvas sheet instead of a floating popover, mirroring the adaptive behaviour of `BbPopover`/`BbSelect`. When unset, falls back to the global `config.adaptive`. |
 | `ampm` | `boolean \| undefined` | `false` |  | 12-hour display with an AM/PM segment (requires `type="datetime"`). Purely a field-composition concern: `modelValue` and the `time` model stay 24-hour regardless. Type `A`/`P` (or ArrowUp/Down) to set the meridiem. |
 | `append:icon` | `string \| undefined` |  |  | Name of the icon to be added at the end of the input. |
@@ -891,12 +982,12 @@ 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` |  |  | Error messages under the field, a string or array, in an `aria-live="polite"` region and first in the control's `aria-describedby`, so they are re-read when it regains focus. |
-| `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). |
+| `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` |  | 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. |
 | `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. |
@@ -906,25 +997,26 @@ label>')` matches nothing; query each segment by its own label instead. See
 | `labelPosition` | `"left" \| "center" \| "right" \| undefined` |  |  | Sets the text alignment of the label. |
 | `layout` | `Responsive<FieldLayout> \| undefined` |  |  | How label and input sit together: `'vertical'`, `'horizontal'` (50/50), `'auto'`, `'label-fill'`, `'input-fill'`, a ratio like `'xx xxxxx'`, or a per-breakpoint map (`{ default: 'vertical', md: 'xx xxxxx' }`). |
 | `loading` | `boolean \| undefined` | `false` |  | Sets the component in a loading state, usually triggering some visual styles. |
-| `max` | `string \| undefined` |  |  | Maximum 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. |
-| `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. |
+| `max` | `string \| undefined` |  |  | Maximum 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. `type="week"`: a week (`YYYY-Www`) or a date, whole weeks only. |
+| `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. `type="week"`: a week (`YYYY-Www`) or a date, whole weeks only. |
 | `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. |
 | `rules` | `RuleExpression<string \| string[] \| null>` |  |  | vee-validate rules for this field. Only inside a `BbForm`. |
 | `seconds` | `boolean \| undefined` | `false` |  | Adds the seconds segment (requires `type="datetime"`). Without it, an incoming value carrying seconds displays truncated and is left untouched until the user commits an edit, at which point seconds zero out. |
-| `selectable` | `((date: string) => boolean) \| undefined` |  |  | Function that accepts a `string` object and returns a boolean. `false` meaning the date cannot be selected. |
+| `selectable` | `((date: string) => boolean) \| undefined` |  |  | Function that accepts a `string` object and returns a boolean. `false` meaning the date cannot be selected. Under `type="week"` it receives the week value (`2026-W44`). |
 | `step` | `number \| undefined` | `1` |  | Minute granularity for the calendar's minute column and arrow stepping (requires `type="datetime"`). Constrains what the component produces, never what it accepts: a typed off-grid value (e.g. `10:07` with `step: 15`) is emitted verbatim, and no column row highlights for it. |
 | `time` | `string \| string[] \| null \| undefined` |  |  | `v-model:time`: the time part, always 24-hour `HH:mm` / `HH:mm:ss`. With `floating` it is the only carrier of the time; otherwise it mirrors `modelValue`'s, and writing it rewrites that. Requires `type="datetime"`. |
 | `transitionDuration` | `number \| undefined` |  |  | Transition duration, in milliseconds, for the popover appearance. |
-| `type` | `'date'` \| `'month'` \| `'year'` \| `'datetime'` | `"date"` |  | What the field edits, and so its segments and emitted shape: `date` (`DD/MM/YYYY`), `datetime` (adds the time segments and rail), `month` (`MM/YYYY`, emits `YYYY-MM`) or `year` (`YYYY`). `month` / `year` force `floating`, ignore `utc`, and leave the time props inert. |
+| `type` | `'date'` \| `'month'` \| `'year'` \| `'week'` \| `'datetime'` | `"date"` |  | What the field edits, so its segments and emitted shape: `date` (`DD/MM/YYYY`), `datetime` (adds the time segments and rail), `week` (`W44 2026`, emits `2026-W44`), `month` (`MM/YYYY`, emits `YYYY-MM`) or `year` (`YYYY`). The last three force `floating` and ignore `utc` and the time props. |
 | `utc` | `boolean \| undefined` | `false` |  | Emits UTC ISO strings (`…Z`) instead of the local offset (`…+01:00`). Emission only: incoming values parse the same either way, and the field always displays local time. Ignored with `floating`. |
 | `validationLabel` | `string \| undefined` |  |  | The field's name in validation messages (`{field}`): "Email is not valid". Defaults to the `label` (or `legend`), then "This field"; never the `name`. Set it when the label is hidden or reads badly in a sentence (icon-only, a question). `BbForm` only. |
 | `validationMode` | `'aggressive'` \| `'balanced'` \| `'lazy'` \| `'submit-only'` \| `'submit-live'` |  |  | When the field validates: `aggressive` (each change), `balanced` (on leave, then live while in error), `lazy` (on leave), `submit-only`, `submit-live`. Unset: the `BbForm`'s `validation-mode`, then `formControls.validationMode` (`'balanced'`). `BbForm` only. |
@@ -952,11 +1044,13 @@ 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. |
 | `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. |
@@ -970,10 +1064,10 @@ States are listed in precedence order: when two are on at once and their entries
 | `hasValue` | Component-wide: the control holds a value, by its own rule (`0` counts on `BbNumberInput`, `''` on `BbColorInput`). |
 | `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. |
 | `readonly` | Component-wide: the control is `readonly` — shown, focusable, not editable. |
 | `disabled` | Component-wide while the input is `disabled`. Also per node, on the calendar's cells: one outside `min` / `max` or refused by `selectable`; on `arrow`, at a bound or while the month / year panel is open. |
 | `warnings` | Component-wide: the control is in its warning state (`warnings` / `has-warnings`) and not in an error state — errors win, so the two are never on together. |
@@ -1032,8 +1126,8 @@ 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`
-    - `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` _(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`, `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`