bitboss-ui 2.1.135 → 3.0.0-alpha.4

package/dist/ai/BbDatePickerInput.md

@@ -1,408 +1,740 @@
 # BbDatePickerInput
 
-## Template & Script
+## Agent Contract
+
+- Safety level: **Consumer API**
+- Group: **Inputs**
+- Description: Combines date selection with text input behavior.
+- Usage rule: Prefer this component for consumer-facing implementations.
+- Implementation source (only when the contract below is not enough): [source/BbDatePickerInput.md](./source/BbDatePickerInput.md)
+
+## Usage & Guidelines
+
+### When to use
+
+Use `BbDatePickerInput` for any calendar date the user picks — invoice due dates,
+report / filter ranges, appointments, trip windows. It renders a **segmented**
+day / month / year text field plus a calendar popover, parses and formats with
+[dayjs](https://day.js.org), and keeps the two in sync — typing a date moves the
+calendar and vice versa. It shares the input-family chrome (`label`,
+`description`, `hint`, `errors`, affixes, `clearable`, `loading`) with the rest
+of the form.
+
+Prefer it over a raw `<input type="date">` for consistent styling, range
+selection, per-day gating and mobile behaviour. If you only need a
+month/quarter/year from a short fixed list, a `BbSelect` is simpler.
+
+By default `v-model` holds a full **ISO string with the local offset**
+(`2026-07-02T00:00:00+02:00`); set `floating` to store the shorter `YYYY-MM-DD`
+form instead (see _Output format_). Set `datetime` to pick a time alongside the
+date (see _Time selection_). `label` is required.
+
+### Label & messaging
+
+The shared surface applies:
+
+- **`label`** (required) doubles as the default `name`; **`hideLabel`** hides it
+  visually while keeping the accessible name; **`labelPosition`** aligns it; the
+  **`label` slot** replaces it with `{ text, hasErrors }`.
+- **`labelMode`** — `outside` / `floating` / `inside`. When unset it falls back
+  to the project-wide `config.defaultInputLabelMode` (library default:
+  `outside`), the same resolution as `BbTextInput` and `BbNumberInput`.
+- **`description`** (always visible), **`hint`** (shows while the control is
+  active; `persistentHint` pins it), and **`errors`** + **`hasErrors`**
+  (`aria-live` region, `aria-describedby`, `aria-invalid`) behave as everywhere
+  else. The segment inputs merge the container's ids with their own format
+  description, so nothing is dropped or duplicated.
+- **`warnings`** is the amber counterpart of `errors`: a string or string array
+  rendered below the field in its own `aria-live="polite"` region — and
+  referenced from `aria-describedby` while displayed — for a
+  valid-but-noteworthy value. A non-empty `warnings` implies the warning state
+  (just as `errors` implies the error state), painting the same chrome as
+  `hasErrors` but in amber (`--bb-warn`, a warning icon in the append stack).
+  **`hasWarning`** forces that chrome without a message, the parallel of
+  `hasErrors`. Unlike `hasErrors`, neither sets `aria-invalid` — a soft "needs a
+  second look" state. `hasErrors` wins when both are set, and the warning
+  messages are suppressed, so the field never shows amber while it has an error.
+- **`required`** marks the segment inputs required to the browser.
+
+**Label, description and a persistent hint**
+
+```vue
+<BbDatePickerInput
+	v-model="state.issuedAt"
+	label="Issue date"
+	description="When the invoice is issued."
+	hint="Type it or pick from the calendar."
+	persistentHint
+	prepend:icon="lucide:calendar"
+/>
+```
+
+### Single date vs range
+
+Bind a `string | null` for a single date. Set `range` and bind a `string[]`
+(`[start, end]`) to pick a window — the calendar highlights every day between the
+two clicks, and the field grows a second day/month/year trio joined by an
+en-dash.
+
+> **`range` requires an array modelValue.** In range mode the value must always
+> be an array — use `[]` for "no selection", never `null` or `undefined`.
+> Binding a non-array throws _"Date picker is set to select multiple dates but
+> modelValue is not an array."_ at setup. If you model an empty filter as `null`
+> elsewhere, seed and clear this field to `[]` instead (and test emptiness with
+> `value.length === 0`). Clearing the field emits `[]`, so the array shape round-trips. The classic case is a stay or trip window: bound below by `min` so past
+> check-ins can't be picked, with a nights summary derived from the two dates.
+
+**Stay dates — range with a nights summary**
 
 ```vue
 <template>
-	<BaseInputContainer
-		:id="id"
-		class="bb-date-picker-input"
-		:compact="compact"
-		:direction="direction"
-		:errors="errors"
-		:has-errors="hasErrors"
-		:hide-label="hideLabel"
-		:hint="hint"
-		:label="label"
-		:label-position="labelPosition"
-		:model-value="modelValue"
-		:name="name"
-		:reverse="reverse"
-		:show-hint="showHint"
-	>
-		<template #label="data"><slot name="label" v-bind="data"></slot></template>
-		<template #input="{ id, hasErrors, ariaDescribedby }">
-			<BaseDatePickerInput
-				:id="id"
-				:allow-writing="allowWriting"
-				:append:icon="$props['append:icon']"
-				:aria-describedby="ariaDescribedby"
-				:autocomplete="autocomplete"
-				:autofocus="autofocus"
-				:clearable="clearable"
-				:compact="compact"
-				:disabled="disabled"
-				:first-day-of-week="firstDayOfWeek"
-				:floating="floating"
-				:has-errors="hasErrors"
-				:hide-popover="hidePopover"
-				:loading="loading"
-				:max="max"
-				:min="min"
-				:model-value="modelValue"
-				:name="name"
-				:placeholder="placeholder"
-				:prepend:icon="$props['prepend:icon']"
-				:range="range"
-				:readonly="readonly"
-				:required="required"
-				:selectable="selectable"
-				:width="width"
-				v-bind="eventListeners"
-			>
-				<template #prepend-outer><slot name="prepend-outer"></slot></template>
-				<template #prepend><slot name="prepend"></slot></template>
-				<template #prefix><slot name="prefix"></slot></template>
-				<template #suffix><slot name="suffix"></slot></template>
-				<template #append><slot name="append"></slot></template>
-				<template #append-outer><slot name="append-outer"></slot></template>
-			</BaseDatePickerInput>
-		</template>
-	</BaseInputContainer>
+	<div class="grid max-w-sm gap-3 rounded-[var(--bb-radius)] border p-4">
+		<div>
+			<p class="text-sm font-medium">Book your stay</p>
+			<p class="text-xs text-[color:var(--bb-text-muted)]">
+				Seaside Loft · Lisbon
+			</p>
+		</div>
+		<BbDatePickerInput
+			v-model="stay"
+			compact
+			floating
+			label="Stay dates"
+			:min="today"
+			placeholder="Check-in → check-out"
+			prepend:icon="lucide:calendar"
+			range
+		/>
+		<p class="text-xs text-[color:var(--bb-text-muted)]">
+			<template v-if="stay.length === 2">
+				{{ stay[0] }} → {{ stay[1] }} · {{ nights }} night{{
+					nights === 1 ? '' : 's'
+				}}
+			</template>
+			<template v-else>No dates selected</template>
+		</p>
+	</div>
 </template>
+<script setup lang="ts">
+import { computed, ref } from 'vue';
+import dayjs from 'dayjs';
+import { BbDatePickerInput } from 'bitboss-ui';
+
+const stay = ref<string[]>([]);
+const today = dayjs().format('YYYY-MM-DD');
+
+const nights = computed(() =>
+	stay.value.length === 2
+		? dayjs(stay.value[1]).diff(dayjs(stay.value[0]), 'day')
+		: 0
+);
+</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
+entirely, reach for `disableWriting` (below), not `range`.
+
+### The segmented field & typing
 
+The value is edited as three separate inputs — day, month, year — not one free
+string. Their **order follows `config.locale`**: `en` renders `MM / DD / YYYY`,
+every other locale (e.g. `it`) renders `DD / MM / YYYY`. Typing is forgiving:
+
+- digits **auto-advance** to the next segment when a segment fills (or can't
+  take another digit — e.g. `4` in a day segment becomes `04` and moves on);
+- `/`, `-` or space also advances; **Backspace** at the start of a segment (and
+  **←** / **→** at the edges) moves between segments;
+- focusing a segment selects it for quick replacement;
+- **pasting** `01/02/2024` (or a whole `01/02/2024 - 03/04/2025` range)
+  distributes the digits across the remaining segments regardless of separators;
+- impossible dates self-correct — typing Feb 31 snaps to Feb 28/29 on commit.
+
+An incomplete date is never emitted: the model updates only once a segment
+parses to a real date, and a half-typed segment is restored to the last coherent
+value when focus leaves the control.
+
+### Bounds & per-day gating
+
+`min` and `max` (each a `YYYY-MM-DD` string) constrain the selectable window;
+days outside it render disabled in the calendar, and a typed out-of-range date is
+snapped back on commit. **Malformed `min`/`max` throw during setup** on purpose,
+to catch config mistakes early — always pass the `YYYY-MM-DD` shape.
+
+For non-contiguous rules (no weekends, no holidays, only in-stock slots), pass a
+`selectable` predicate: it receives each date string and returns `false` to
+disable that day. `firstDayOfWeek` shifts the calendar grid (`0` = Sunday …
+`6` = Saturday).
+
+The example below combines a rolling `min`/`max` window, a weekdays-only
+predicate, `floating` output, and the `append:day` slot to dot specific days.
+
+**Bounded, weekdays-only, with event dots**
+
+```vue
+<template>
+	<div class="grid max-w-sm gap-3 rounded-[var(--bb-radius)] border p-4">
+		<div>
+			<p class="text-sm font-medium">Book a demo</p>
+			<p class="text-xs text-[color:var(--bb-text-muted)]">
+				30 minutes. Dotted days still have open slots.
+			</p>
+		</div>
+		<BbDatePickerInput
+			v-model="appointment"
+			compact
+			floating
+			hint="Weekdays only, within the next 30 days."
+			label="Demo date"
+			:max="max"
+			:min="min"
+			persistent-hint
+			placeholder="YYYY-MM-DD"
+			prepend:icon="lucide:calendar-check"
+			:selectable="isWeekday"
+		>
+			<template #append:day="{ item }">
+				<span
+					v-if="hasOpenSlots(item)"
+					class="mx-auto mt-0.5 block h-1 w-1 rounded-full bg-current opacity-70"
+				/>
+			</template>
+		</BbDatePickerInput>
+		<p class="text-xs text-[color:var(--bb-text-muted)]">
+			{{ appointment ? `Booked for ${appointment}` : 'No date chosen yet.' }}
+		</p>
+	</div>
+</template>
 <script setup lang="ts">
-import BaseDatePickerInput from '../BaseDatePickerInput/BaseDatePickerInput.vue';
-import BaseInputContainer from '../BaseInputContainer/BaseInputContainer.vue';
-import type { BaseDatePickerInputEvents } from '../BaseDatePickerInput/types';
-import { ref, computed } from 'vue';
-import type {
-	BbDatePickerInputProps,
-	BbDatePickerInputEvents,
-	BbDatePickerInputSlots,
-	DatePickerInputError,
-} from './types';
-
-const props = withDefaults(defineProps<BbDatePickerInputProps>(), {
-	allowWriting: true,
-});
-
-const emit = defineEmits<BaseDatePickerInputEvents>();
-
-defineSlots<BbDatePickerInputSlots>();
-
-const active = ref(false);
-const showHint = computed(() => props.persistentHint || active.value);
-
-/**
- * These events are just propagated
- */
-const eventListeners = {
-	onError: (error: DatePickerInputError) => emit('error', error),
-	onFocus: (event: FocusEvent) => emit('focus', event),
-	onActive: () => {
-		active.value = true;
-		emit('active');
-	},
-	onInactive: () => {
-		active.value = false;
-		emit('inactive');
-	},
-	'onUpdate:modelValue': (value: BbDatePickerInputProps['modelValue']) =>
-		emit('update:modelValue', value),
+import { ref } from 'vue';
+import dayjs, { type Dayjs } from 'dayjs';
+import { BbDatePickerInput } from 'bitboss-ui';
+
+const appointment = ref<string | null>(null);
+
+const min = dayjs().format('YYYY-MM-DD');
+const max = dayjs().add(30, 'day').format('YYYY-MM-DD');
+
+// Days that still have open demo slots — dotted via the `append:day` slot.
+const openSlots = [3, 5, 8, 12].map((offset) =>
+	dayjs().add(offset, 'day').format('YYYY-MM-DD')
+);
+const hasOpenSlots = (item: Dayjs) =>
+	openSlots.includes(item.format('YYYY-MM-DD'));
+
+const isWeekday = (date: string) => {
+	const day = dayjs(date).day();
+	return day !== 0 && day !== 6;
 };
 </script>
-
-<style lang="postcss">
-@import './index.css';
-</style>
 ```
 
-## Types
-
-```ts
-import type { HTMLAttributes, InputHTMLAttributes } from 'vue';
-import type { IconType } from '@/types/Icon';
-import type {
-	BaseDatePickerInputEvents,
-	DatePickerInputError,
-} from '../BaseDatePickerInput/types';
-
-export type { DatePickerInputError };
-
-export type BbDatePickerInputProps = {
-	/**
-	 * Allows typing into the input.
-	 *
-	 * @defaultValue `true`
-	 */
-	allowWriting?: boolean | 'not-mobile';
-
-	/**
-	 * Name of the icon to be added at the end of the input.
-	 */
-	// eslint-disable-next-line vue/prop-name-casing
-	'append:icon'?: IconType;
-
-	/**
-	 * Guides the browser as to the type of information expected in the field.
-	 */
-	autocomplete?: InputHTMLAttributes['autocomplete'];
-
-	/**
-	 * Sets autofocus on page load.
-	 */
-	autofocus?: InputHTMLAttributes['autofocus'];
-
-	/**
-	 * Displays a clear button when the input has a value and is being interacted with.
-	 */
-	clearable?: boolean;
-
-	/**
-	 * Sets the component in a compact state.
-	 */
-	compact?: boolean;
-
-	/**
-	 * Direction of the layout of the component. Can either be a predefined value or a pattern separated by a space like `xx xxxxx`.
-	 */
-	direction?: 'horizontal' | 'vertical' | 'auto' | string;
-
-	/**
-	 * Disables the component.
-	 */
-	disabled?: boolean;
-
-	/**
-	 * Can be a string or an array of string containing the messages to display.
-	 */
-	errors?: string | string[];
-
-	/**
-	 * Defines the first day of the week with `0` meaning Sunday and `6` meaning Saturday.
-	 */
-	firstDayOfWeek?: 0 | 1 | 6 | 3 | 2 | 4 | 5;
-
-	/**
-	 * If true the date will have a format YYYY-MM-DD instead of the default ISO string.
-	 */
-	floating?: boolean;
-
-	/**
-	 * Define if the component should be in an error state.
-	 * It usually attaches a CSS class for styling purposes.
-	 */
-	hasErrors?: boolean;
-
-	/**
-	 * Hides the calendar trigger button and prevents the popover from opening.
-	 * Use `'not-mobile'` to hide on desktop and keep visible on mobile,
-	 * complementing `allowWriting: 'not-mobile'` for platform-specific interaction modes.
-	 */
-	hidePopover?: boolean | 'not-mobile';
-
-	/**
-	 * Visually hides the label of the input while maintaining accessibility.
-	 */
-	hideLabel?: boolean;
-
-	/**
-	 * Text box to be displayed near the input, usually to indicate instructions.
-	 */
-	hint?: string;
-
-	/**
-	 * The identifier of the component.
-	 */
-	id?: HTMLAttributes['id'];
-
-	/**
-	 * Text content of the label of the element.
-	 */
-	label: string;
-
-	/**
-	 * Sets the text alignment of the label.
-	 */
-	labelPosition?: 'left' | 'center' | 'right';
-
-	/**
-	 * Sets the component in a loading state, usually triggering some visual styles.
-	 */
-	loading?: boolean;
-
-	/**
-	 * Maximum selectable date in `YYYY-MM-DD` format.
-	 * Values outside the pattern throw during setup to surface configuration mistakes.
-	 */
-	max?: string;
-
-	/**
-	 * Minimum selectable date in `YYYY-MM-DD` format.
-	 * Values outside the pattern throw during setup to surface configuration mistakes.
-	 */
-	min?: string;
-
-	/**
-	 * 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.
-	 */
-	modelValue: string | string[] | null;
-
-	/**
-	 * Defines the name of the input.
-	 */
-	name?: InputHTMLAttributes['name'];
-
-	/**
-	 * Keeps the hint displayed.
-	 */
-	persistentHint?: boolean;
-
-	/**
-	 * String displayed when there's no data.
-	 */
-	placeholder?: InputHTMLAttributes['placeholder'];
-
-	/**
-	 * Name of the icon to be added at the start of the input.
-	 */
-	// eslint-disable-next-line vue/prop-name-casing
-	'prepend:icon'?: IconType;
-
-	/**
-	 * Selects a range of dates between two dates. It selects all of the days between start and end.
-	 */
-	range?: boolean;
-
-	/**
-	 * Sets the input in a readonly state.
-	 */
-	readonly?: boolean;
-
-	/**
-	 * Sets the input as required.
-	 */
-	required?: boolean;
-
-	/**
-	 * Reverses the layout. Applicable in every direction the order of the label and the input is swapped.
-	 */
-	reverse?: boolean;
-
-	/**
-	 * Function that accepts a `string` object and returns a boolean. `false` meaning the date cannot be selected.
-	 */
-	selectable?: (date: string) => boolean;
-
-	/**
-	 * Width of the calendar.
-	 */
-	width?: number | string;
-};
+### Output format
+
+By default the model is a full ISO timestamp **carrying the local offset**
+(`2026-07-02T00:00:00+02:00`) — the emitted digits always match what the user
+sees in the fields. If your backend expects UTC `Z` strings, add `utc`: it
+switches emission to `toISOString()` and changes nothing else. Reading accepts
+both forms (and naked local strings) either way, so adding or removing `utc`
+never requires migrating stored values.
 
-/** Re-export for consumers importing events type from BbDatePickerInput. */
-export type { BaseDatePickerInputEvents as BbDatePickerInputEvents };
+When you only care about the calendar day — and want a value that's trivial to
+compare, store or send to an API — set `floating` and the model becomes a plain
+`YYYY-MM-DD` string (as in the appointment example above). `floating` + `utc`
+is incoherent (a plain date has no zone) and `utc` is ignored with a DEV
+warning. Pick one format per field and stick to it; `min` / `max` are
+`YYYY-MM-DD` regardless of `floating` (plus an optional `THH:mm` with
+`datetime` — see below).
 
-/** Props exposed by the `label` slot. */
-export type BbDatePickerInputLabelSlotProps = {
-	/** The `label` prop value. */
-	text: string;
-	/** Whether the input is in an error state. */
-	hasErrors: boolean;
+Floating output shines in filters. The invoice issue-date bar below — the shape
+every records workspace uses — stores plain `YYYY-MM-DD` strings, so the preset
+buttons can write straight into the model and the values go into an API query
+untouched. `max` pins the window to today, and `hideLabel` keeps the accessible
+name while the field reads as toolbar chrome.
+
+**Issue-date range filter with presets**
+
+```vue
+<template>
+	<div class="grid max-w-md gap-3 rounded-[var(--bb-radius)] border p-4">
+		<div class="flex flex-wrap items-center justify-between gap-2">
+			<div>
+				<p class="text-sm font-medium">Issue date</p>
+				<p class="text-xs text-[color:var(--bb-text-muted)]">
+					Filter the invoice list
+				</p>
+			</div>
+			<div class="flex gap-1.5">
+				<BbButton size="xs" variant="outline" @click="setPreset(7)">
+					Last 7 days
+				</BbButton>
+				<BbButton size="xs" variant="outline" @click="setPreset(30)">
+					Last 30 days
+				</BbButton>
+				<BbButton size="xs" variant="outline" @click="setPreset(90)">
+					Last quarter
+				</BbButton>
+			</div>
+		</div>
+		<BbDatePickerInput
+			v-model="period"
+			clearable
+			compact
+			floating
+			hide-label
+			label="Issue date range"
+			:max="today"
+			placeholder="Start → end"
+			prepend:icon="lucide:calendar-range"
+			range
+		/>
+		<p class="text-xs text-[color:var(--bb-text-muted)]">
+			{{
+				period.length === 2
+					? `Showing invoices from ${period[0]} to ${period[1]}`
+					: 'Pick a period or use a preset.'
+			}}
+		</p>
+	</div>
+</template>
+<script setup lang="ts">
+import { ref } from 'vue';
+import dayjs from 'dayjs';
+import { BbButton, BbDatePickerInput } from 'bitboss-ui';
+
+const today = dayjs().format('YYYY-MM-DD');
+const period = ref<string[]>([]);
+
+// `floating` keeps the model as plain YYYY-MM-DD strings, so presets can
+// write straight into it — no ISO conversion on either side.
+const setPreset = (days: number) => {
+	period.value = [
+		dayjs()
+			.subtract(days - 1, 'day')
+			.format('YYYY-MM-DD'),
+		today,
+	];
 };
+</script>
+```
+
+### Time selection
+
+Set `datetime` and the field grows 24-hour `HH:mm` segments after the date
+(auto-advance and paste distribution included), and the calendar gains hour /
+minute columns beside the grid. A picked or typed date with a blank time
+commits at `00:00` — the panel stays open after a day click so the user can
+still pick a time, and the time columns stay disabled until a date exists.
+
+**Date and time**
+
+```vue
+<BbDatePickerInput
+	v-model="state.startsAt"
+	datetime
+	label="Starts at"
+	prepend:icon="lucide:calendar-clock"
+/>
+```
+
+Tuning knobs, all inert without `datetime` (DEV warning):
+
+- **`seconds`** adds the `:ss` segment. Without it, an incoming value carrying
+  seconds displays truncated and zeroes out on the next user commit — precision
+  never rides along invisibly.
+- **`step`** (minutes, default `1`) shapes the minute column — `:step="15"`
+  renders 00/15/30/45 — and constrains what the panel _produces_, never what
+  the field _accepts_: a typed `10:07` is emitted verbatim, and no column row
+  highlights for it.
+- **`ampm`** switches the display to 12-hour with an AM/PM segment (type `A` /
+  `P`, or cycle with ArrowUp/Down). Purely visual: the model stays 24-hour.
+- **`min` / `max`** additionally accept `YYYY-MM-DDTHH:mm` to tighten the
+  boundary day to a minute; date-only bounds keep working day-granular, so any
+  time inside the boundary day is fine.
+
+#### The `time` companion model
 
-export type BbDatePickerInputSlots = {
-	/**
-	 * Content rendered before the entire date picker control, outside the input chrome.
-	 */
-	'prepend-outer'?: (props: object) => any;
-	/**
-	 * Content rendered before the date fields, at the start of the inner container.
-	 */
-	prepend?: (props: object) => any;
-	/**
-	 * Inline content rendered at the start of the input field area, before the date fields.
-	 */
-	prefix?: (props: object) => any;
-	/**
-	 * Content rendered after the date fields, at the end of the inner container (before the calendar toggle button).
-	 */
-	append?: (props: object) => any;
-	/**
-	 * Content rendered after the entire date picker control, outside the input chrome.
-	 */
-	'append-outer'?: (props: object) => any;
-	/**
-	 * Inline content rendered at the end of the input field area, after the date fields.
-	 */
-	suffix?: (props: object) => any;
-	/**
-	 * Replaces the default label text rendered above the date picker.
-	 */
-	label?: (props: BbDatePickerInputLabelSlotProps) => any;
+`v-model:time` carries the time part as a 24-hour `HH:mm` (or `HH:mm:ss`)
+string — an array in range mode. It emits alongside every value change:
+
+- **Non-floating**: the time already lives inside `modelValue`; the mirror has
+  the _same digits_, and writing to it rewrites the model's time part. Bind it
+  only if you want the time as a separate piece of state.
+- **`floating`**: the date string stays plain `YYYY-MM-DD`, so `v-model:time`
+  is the **only** carrier of the time — bind it or the time is lost.
+
+**Floating date + separate time**
+
+```vue
+<BbDatePickerInput
+	v-model="state.reminderDate"
+	v-model:time="state.reminderTime"
+	datetime
+	floating
+	label="Reminder"
+/>
+```
+
+In `range` mode each end has its own time; a same-day range whose end time
+precedes its start swaps on blur (the usual `end_before_start` error fires).
+The panel's time columns edit the segment whose fields you focused last.
+
+### Invalid input & the error event
+
+Typing (not calendar-clicking, which can only pick valid days) can produce a
+date that's disabled or a reversed range. On commit the component **normalises**
+the value and emits an `error` event describing what it did, so you can surface a
+message. It never silently keeps an invalid value.
+
+The payload is a discriminated union on `code`:
+
+| `code`                 | Trigger                       | `normalized`                                                      |
+| ---------------------- | ----------------------------- | ----------------------------------------------------------------- |
+| `disabled_date`        | Typed single date is disabled | Snapped to `min`/`max`, or `null` if only `selectable` blocked it |
+| `disabled_range_start` | Typed range start is disabled | Snapped range, or `null`                                          |
+| `disabled_range_end`   | Typed range end is disabled   | Range with end snapped, or `[start]`                              |
+| `end_before_start`     | Typed end is before start     | `[end, start]` — the swapped pair                                 |
+
+Each payload also carries `original` (what the user typed). Turn it into a
+user-visible message via `errors` + `hasErrors`. The invoice due-date card below
+bounds the field with `:min="issuedAt"` — typing an earlier day snaps to the
+issue date and surfaces the normalisation.
+
+**Invoice due date with bounds error**
+
+```vue
+<template>
+	<div class="grid max-w-sm gap-3 rounded-[var(--bb-radius)] border p-4">
+		<div class="flex items-start justify-between gap-3">
+			<div>
+				<p class="text-sm font-medium">INV-2048</p>
+				<p class="text-xs text-[color:var(--bb-text-muted)]">
+					Acme Studio · $2,400.00
+				</p>
+			</div>
+			<p class="text-xs text-[color:var(--bb-text-muted)]">Draft</p>
+		</div>
+		<BbDatePickerInput
+			v-model="dueDate"
+			compact
+			:errors="dueError"
+			floating
+			:has-errors="!!dueError"
+			hint="Must be on or after the issue date."
+			label="Due date"
+			:min="issuedAt"
+			persistent-hint
+			placeholder="YYYY-MM-DD"
+			prepend:icon="lucide:calendar"
+			@error="onError"
+			@update:model-value="dueError = ''"
+		/>
+		<p class="text-xs text-[color:var(--bb-text-muted)]">
+			Issued {{ issuedAt }} · Net 30 from issue
+		</p>
+	</div>
+</template>
+<script setup lang="ts">
+import { ref } from 'vue';
+import { BbDatePickerInput, type DatePickerInputError } from 'bitboss-ui';
+
+const issuedAt = '2026-03-01';
+const dueDate = ref<string | null>('2026-03-31');
+const dueError = ref('');
+
+// Typing a day before the issue date snaps to `min` and fires `error` —
+// surface that normalisation through `errors` + `hasErrors`.
+const onError = (error: DatePickerInputError) => {
+	dueError.value =
+		error.code === 'disabled_date'
+			? "Due date can't be before the issue date — adjusted."
+			: 'That date was adjusted to stay valid.';
 };
+</script>
 ```
 
-## Styles
-
-```css
-.bb-date-picker-input {
-	&.bb-base-input-outer-container--errors {
-	}
-	&.bb-base-input-outer-container--hint {
-	}
-	.bb-base-input-container {
-		&--vertical {
-		}
-		&--horizontal {
-		}
-
-		&__label {
-			&--left {
-			}
-			&--center {
-			}
-			&--right {
-			}
-			&--hidden {
-			}
-		}
-		&__input {
-			&--left {
-			}
-			&--center {
-			}
-			&--right {
-			}
-
-			.bb-base-date-picker-input {
-				display: inline-flex;
-				&--disabled {
-				}
-				&--errors {
-				}
-				&--loading {
-				}
-				&--readonly {
-				}
-
-				.bb-common-input-inner-container {
-					> input {
-					}
-
-					&__prepend-icon,
-					&__append-icon {
-					}
-					.bb-spinner {
-					}
-					.bb-error-icon {
-					}
-					&__prefix,
-					&__suffix {
-					}
-				}
-			}
-		}
-
-		&__hint-container {
-			.bb-base-input-container__hint {
-			}
-		}
-		&__errors {
-		}
-		&__error {
-		}
-	}
-}
+### Platform-aware interaction
+
+The picker adapts to touch vs pointer, and you can steer that explicitly:
+
+- **`adaptive`** (defaults to the project's `config.adaptive`): on mobile the
+  calendar opens in a bottom `BbOffCanvas` sheet instead of a floating popover.
+  The surface is **latched** when the panel opens, so a mid-session resize never
+  swaps a live popover into a sheet. Forward sheet options via `offCanvasProps`
+  (e.g. `title`, `size`, `persistent`, `draggable`). Set `:adaptive="false"` to
+  force the floating popover on every viewport (deterministic in tests).
+- **`disableWriting`**: block typing so the calendar is the only way in. Use
+  `'mobile'` / `'desktop'` to disable typing on just one platform.
+- **`disableCalendar`**: hide the calendar trigger entirely. Use `'mobile'` /
+  `'desktop'` to disable it on just one platform. Pair
+  `disableWriting: 'mobile'` with `disableCalendar: 'desktop'` to get "type on
+  desktop, tap the calendar on mobile".
+
+Guard rail: a configuration that leaves a platform with **no** way to enter a
+date (e.g. `disableWriting: true` **and** `disableCalendar: true`) **throws
+during setup** — every platform must keep at least one interaction method.
+
+**Typed-only on desktop**
+
+```vue
+<BbDatePickerInput
+	v-model="state.dueDate"
+	label="Due date"
+	disableWriting="mobile"
+	hint="Type it, or pick from the calendar."
+	persistentHint
+	prepend:icon="lucide:calendar"
+	placeholder="YYYY-MM-DD"
+/>
 ```
+
+### Decorating days
+
+The `day` slot **replaces** a day's contents; the `append:day` slot **adds**
+below it (badges, event dots, price tags). Both receive the day's state — `label`
+(the day number), `selected`, `highlighted`, `first` / `middle` / `last` (range
+edges) and `item` (the underlying dayjs object, for formatting or lookups). Keep
+decorations lightweight; they render for every visible cell. The appointment
+example above uses `append:day` for event dots.
+
+### Calendar keyboard navigation
+
+The calendar grid is a `role="grid"` with a roving tabindex (the current day is
+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;
+- **Enter** / **Space** select the focused day and close the surface;
+- the month and year headings open their own pick panels (Enter toggles them).
+
+Today carries `aria-current="date"`, the selection carries `aria-selected`, and
+each day button has a full spoken date label — so don't add your own key
+handlers.
+
+### Icons, affixes, clearable, loading & states
+
+`prepend:icon` / `append:icon`, and the `prefix` / `suffix` / `prepend` /
+`append` / `prepend-outer` / `append-outer` slots work as across the family. The
+append slot sits alongside the calendar trigger button.
+
+`clearable` shows a clear button when a value is present and interactive; it
+emits `null` for a single field and `[]` for a range. `loading` shows a spinner
+(visual only). `disabled` blocks everything including the calendar trigger
+(`aria-disabled`); `readonly` keeps the value readable and copyable but blocks
+typing and the calendar (`aria-readonly`).
+
+**Clearable contract start and a readonly created stamp**
+
+```vue
+<template>
+	<div class="grid max-w-sm gap-3 rounded-[var(--bb-radius)] border p-4">
+		<div>
+			<p class="text-sm font-medium">Contract dates</p>
+			<p class="text-xs text-[color:var(--bb-text-muted)]">
+				Clear the start date, or copy the locked created stamp.
+			</p>
+		</div>
+		<BbDatePickerInput
+			v-model="from"
+			clearable
+			compact
+			floating
+			label="Contract start"
+			placeholder="YYYY-MM-DD"
+			prepend:icon="lucide:calendar"
+		/>
+		<BbDatePickerInput
+			compact
+			floating
+			label="Created"
+			model-value="2026-06-02"
+			prepend:icon="lucide:calendar"
+			readonly
+		/>
+	</div>
+</template>
+<script setup lang="ts">
+import { ref } from 'vue';
+import { BbDatePickerInput } from 'bitboss-ui';
+
+// Clearable emits `null` when the user hits the clear button.
+const from = ref<string | null>('2026-05-01');
+</script>
+```
+
+### Events & v-model
+
+Because the control is a composite (segmented fields + calendar + optional
+sheet), its events differ from a plain input:
+
+- `update:modelValue` — `null` / single string / `[start, end]` per mode and
+  `floating`.
+- `error` — a `DatePickerInputError` on every normalisation (see _Invalid
+  input_).
+- `active` / `inactive` — fire when focus enters / leaves the whole control
+  (not per-field); these gate the `hint`'s show-on-focus behaviour. Use them
+  instead of `blur`, which is not forwarded at this level.
+- `focus` — forwarded when a segment input gains focus.
+
+### Density, layout, config & platforms
+
+- `compact` reduces height; `direction` works whenever the resolved label mode
+  is `'outside'` (the config default) — `direction="horizontal"` lays the label
+  beside the field. With `labelMode="floating"` or `"inside"` (prop or
+  `config.defaultInputLabelMode`) the label is embedded in the field, so the
+  layout is forced vertical and `direction` is ignored — same rule as
+  `BbTextInput`/`BbSelect`/`BbNumberInput`.
+- **`config.locale`** drives both the segment order (`en` → month-first) and the
+  calendar's month/weekday names via dayjs (`it` and `en` locales are bundled).
+- The calendar popover / sheet is **teleported** to the top layer, so its DOM
+  isn't a child of the field — account for that in tests (query `document.body`)
+  and z-index reasoning. The field itself is SSR-safe; the popover mounts client
+  side.
+
+```vue
+<!-- Inertia: bind server validation; store the floating YYYY-MM-DD form -->
+<BbDatePickerInput
+	v-model="form.dueDate"
+	label="Due date"
+	floating
+	:min="today"
+	:errors="form.errors.dueDate"
+	:has-errors="!!form.errors.dueDate"
+/>
+```
+
+### Works well with
+
+- `BbTextInput` / `BbTextarea` / `BbNumberInput` — same chrome; mix in one form.
+  The `BbTextInput` invoice example composes all four, including a `range` date
+  field for a service period and a `min`-bounded due date.
+- `BbSelect` — when a date is really a choice from a short fixed list
+  (month, quarter), a select is simpler.
+- `BbOffCanvas` — the adaptive mobile surface; tune it through `offCanvasProps`.
+- `useToast` — confirm a booking once the date is committed.
+
+### Gotchas & anti-patterns
+
+- `min` / `max` must be `YYYY-MM-DD` — other shapes **throw at setup**.
+- Disabling _both_ typing and the popover on a platform **throws** — always
+  leave one interaction path.
+- Don't gate dates with a custom click handler on top of `selectable`/`min`/`max`
+  — disabled days are already communicated to assistive tech; a parallel handler
+  desyncs them.
+- Don't listen for `blur` here — use `inactive` (the composite tracks focus
+  across its fields and teleported calendar manually).
+- Range mode requires an **array** modelValue (`[start, end]`, or `[]` when
+  empty). Binding `null`/`undefined` or a bare string throws at setup — model the
+  empty state as `[]`, not `null`.
+- Pick one of ISO or `floating` per field and store it consistently; don't mix
+  formats for the same value.
+
+### Accessibility
+
+- Always provide `label`; hide it visually with `hideLabel` rather than dropping
+  it.
+- Keep `min` / `max` and `selectable` authoritative — disabled days are exposed
+  to assistive tech; don't also gate via custom handlers.
+- The `error` event fires when a typed value is invalid or out of bounds; surface
+  that through `errors` + `hasErrors` rather than failing silently.
+- The calendar exposes `role="grid"`, `aria-current="date"` on today,
+  `aria-selected` on the selection and spoken date labels on each day; the
+  trigger button carries `aria-haspopup="dialog"` and `aria-expanded`.
+- **Driving this field from a test:** each segment input carries its own
+  localized `aria-label` ("Month"/"Day"/"Year", …) that overrides the field's
+  own `label` for the accessible-name computation — `getByLabel('<field
+label>')` matches nothing; query each segment by its own label instead. See
+  [Agent Contract](./guides/agent-contract.md) § Testing Against bitboss-ui.
+
+## v-model
+
+- `v-model` — type: `string \| string[] \| null`
+- `v-model:time` — type: `string \| string[] \| null \| undefined`
+
+## Props
+
+| Prop | Type | Default | Required | Description |
+| --- | --- | --- | --- | --- |
+| `adaptive` | `boolean \| undefined` | `undefined` |  | 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` |  |  | 12-hour display with an AM/PM segment (requires `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. |
+| `autocomplete` | `string \| undefined` |  |  | Guides the browser as to the type of information expected in the field. |
+| `autofocus` | `Booleanish \| undefined` |  |  | Sets autofocus on page load. |
+| `clearable` | `boolean \| undefined` |  |  | Displays a clear button when the input has a value and is being interacted with. |
+| `compact` | `boolean \| undefined` |  |  | Sets the component in a compact state. |
+| `datetime` | `boolean \| undefined` |  |  | Adds time selection beside date selection: `HH:mm` segments in the text field (24-hour) and time columns under the calendar. A picked or typed date with a blank time commits at `00:00`. Non-floating values carry the time inside `modelValue`… |
+| `description` | `string \| undefined` |  |  | Descriptive text displayed below the label and above the input. Unlike the hint it is always visible, and it is linked to the input via `aria-describedby` (after any `errors` / `warnings`, before the `hint`). |
+| `direction` | `InputDirection \| undefined` |  |  | Direction of the layout of the component. Can either be a predefined value or a pattern separated by a space like `xx xxxxx`. |
+| `disableCalendar` | `boolean \| "mobile" \| "desktop" \| undefined` |  |  | Disables the calendar: hides the trigger button and prevents the popover from opening. Use `'desktop'` to disable it on desktop only (keeping the calendar for mobile, complementing `disableWriting: 'mobile'`) or `'mobile'` to disable it on … |
+| `disabled` | `boolean \| undefined` |  |  | Disables the component. |
+| `disableWriting` | `boolean \| "mobile" \| "desktop" \| undefined` |  |  | Disables typing into the input. Use `'mobile'` to disable typing only on mobile, `'desktop'` to disable typing only on desktop. |
+| `errors` | `string \| string[] \| undefined` |  |  | Can be a string or an array of string containing the messages to display. They render in an `aria-live="polite"` region (announced when they appear) and, while the list is non-empty, are referenced FIRST from the control's `aria-describedby… |
+| `firstDayOfWeek` | `0 \| 1 \| 2 \| 3 \| 4 \| 5 \| 6 \| undefined` |  |  | Defines the first day of the week with `0` meaning Sunday and `6` meaning Saturday. |
+| `floating` | `boolean \| undefined` |  |  | If true the date will have a format YYYY-MM-DD instead of the default ISO string. |
+| `hasErrors` | `boolean \| undefined` |  |  | Define if the component should be in an error state. It usually attaches a CSS class for styling purposes. |
+| `hasWarning` | `boolean \| undefined` |  |  | Define if the component should be in a warning state. Same chrome as errors with `--bb-warn`; errors take priority. |
+| `hideLabel` | `boolean \| undefined` |  |  | Visually hides the label of the input while maintaining accessibility. |
+| `hint` | `string \| undefined` |  |  | Text box to be displayed near the input, usually to indicate instructions. |
+| `id` | `string \| undefined` |  |  | The identifier of the component. |
+| `label` | `string` |  | yes | Text content of the label of the element. |
+| `labelMode` | `"floating" \| "outside" \| "inside" \| undefined` |  |  | Label rendering mode. |
+| `labelPosition` | `"left" \| "center" \| "right" \| undefined` |  |  | Sets the text alignment of the label. |
+| `loading` | `boolean \| undefined` |  |  | 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 `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 `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` |  | yes | 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. |
+| `offCanvasProps` | `Partial<BbOffCanvasProps> \| undefined` |  |  | Extra props forwarded to the `BbOffCanvas` sheet when `adaptive` is active on mobile (e.g. `title`, `size`, `persistent`). |
+| `persistentHint` | `boolean \| undefined` |  |  | Keeps the hint displayed. |
+| `placeholder` | `string \| undefined` |  |  | String displayed when there's no data. |
+| `prepend:icon` | `string \| undefined` |  |  | Name of the icon to be added at the start of the input. |
+| `range` | `boolean \| undefined` |  |  | Selects a range of dates between two dates. It selects all of the days between start and end. |
+| `readonly` | `boolean \| undefined` |  |  | Sets the input in a readonly state. |
+| `required` | `boolean \| undefined` |  |  | Sets the input as required. |
+| `reverse` | `boolean \| undefined` |  |  | Reverses the layout. Applicable in every direction the order of the label and the input is swapped. |
+| `seconds` | `boolean \| undefined` |  |  | Adds the seconds segment (requires `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. |
+| `step` | `number \| undefined` |  |  | Minute granularity for the calendar's minute column and arrow stepping (requires `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 c… |
+| `time` | `string \| string[] \| null \| undefined` |  |  | Companion model for the time part (`v-model:time`), always 24-hour `HH:mm` / `HH:mm:ss` regardless of display. With `floating` it is the only carrier of the time; otherwise it mirrors the time inside `modelValue` (same digits) and writing i… |
+| `transitionDuration` | `number \| undefined` |  |  | Transition duration, in milliseconds, for the popover appearance. |
+| `utc` | `boolean \| undefined` |  |  | Emits values as UTC ISO strings (`...Z`) instead of ISO strings carrying the local offset (`...+01:00`). Emission-only: incoming values are parsed identically either way, so the prop can be added or removed without touching stored values. F… |
+| `warnings` | `string \| string[] \| undefined` |  |  | Warning messages to display beneath the field, in their own `aria-live` region and amber (`--bb-warn`). A string or array; a non-empty list implies the warning state. Errors suppress warnings when both are set. While displayed they are also… |
+
+## Events
+
+- `active` — `(event: "active"): void`
+- `error` — `(event: "error", error: DatePickerInputError): void`
+- `focus` — `(event: "focus", event: FocusEvent): void`
+- `inactive` — `(event: "inactive"): void`
+- `update:modelValue` — `(event: "update:modelValue", value: string \| string[] \| null): void`
+- `update:time` — `(event: "update:time", value: string \| string[] \| null): void`
+
+## Slots
+
+- `append` — scope: `object` — Content rendered after the date fields, at the end of the inner container (before the calendar toggle button).
+- `append-outer` — scope: `object` — Content rendered after the entire date picker control, outside the input chrome.
+- `append:day` — scope: `{ first: boolean; highlighted: boolean; item: Dayjs; label: string; last: boolean; middle: boolean; selected: boolean; }` — Appends content below each calendar day.
+- `day` — scope: `{ first: boolean; highlighted: boolean; item: Dayjs; label: string; last: boolean; middle: boolean; selected: boolean; }` — Replaces the day button label inside each calendar day.
+- `label` — scope: `BbDatePickerInputLabelSlotProps` — Replaces the default label text rendered above the date picker.
+- `prefix` — scope: `object` — Inline content rendered at the start of the input field area, before the date fields.
+- `prepend` — scope: `object` — Content rendered before the date fields, at the start of the inner container.
+- `prepend-outer` — scope: `object` — Content rendered before the entire date picker control, outside the input chrome.
+- `suffix` — scope: `object` — Inline content rendered at the end of the input field area, after the date fields.
+
+## Validated variant
+
+Importing this component from `bitboss-ui/validated` instead of `bitboss-ui` binds it to a vee-validate field. Same props, same events, same slots — plus the ones below. Requires the `vee-validate` peer dependency and a `<BbForm>` (or `useForm()`) ancestor. Full guide: [validated-forms](./guides/validated-forms.md).
+
+| Prop | Type | Description |
+| --- | --- | --- |
+| `rules` | `RuleExpression<string \| string[] \| null>` | vee-validate rules for this field. |
+| `validateOn` | `ValidateTiming[] \| undefined` | Which interactions trigger validation (see `ValidatedFieldProps.validateOn` for the timing vocabulary). |
+| `vid` | `string \| undefined` | Explicit vee-validate field name. **Usually omit it** — the name is derived automatically from the control's `label`/`legend`. Only set `vid` when that derivation wouldn't be unique (e.g. v-for rows, or array `v-model`s that share a label).… |
+
+## See Also
+
+- [BbDatePicker](./BbDatePicker.md) — Opens an anchored calendar (and optional time rail) popover on a trigger you own — the date analog of BbColorPalette; also the v-bb-date directive.
+- [BbTextInput](./BbTextInput.md) — Captures single-line text values.
+- [BbTimePickerInput](./BbTimePickerInput.md) — Segmented time field with hour/minute columns; 24-hour string model.