bitboss-ui 2.1.134 → 3.0.0-alpha.1

package/dist/ai/source/BbDatePicker.md

@@ -0,0 +1,725 @@
+# BbDatePicker — Implementation Source
+
+> Full implementation for deep dives. For everyday usage read the typed contract: [../BbDatePicker.md](../BbDatePicker.md).
+
+## Template & Script
+
+```vue
+<template>
+	<!-- Activator slot — skipped when an external activator ref is passed -->
+	<slot
+		v-if="!hasExternalActivator"
+		name="activator"
+		v-bind="{
+			props: { ref: setActivatorRef },
+			anchorProps: { ref: setAnchorRef },
+			open: isOpen,
+			value: modelValue,
+			disabled: !!disabled,
+		}"
+	/>
+
+	<!-- The calendar panel is authored once and replayed in whichever surface is
+	mounted, so the desktop popover and the mobile sheet share identical markup,
+	refs and wiring — only one live instance exists at a time. -->
+	<DefinePanel>
+		<div
+			ref="calendarRef"
+			class="bb-date-picker__calendar"
+			:class="{
+				'bb-date-picker__calendar--datetime': datetime,
+				'bb-date-picker__calendar--sheet': useOffcanvas,
+			}"
+			:style="railStyle"
+		>
+			<BbBaseDatePicker
+				:id="gridId"
+				ref="gridRef"
+				:disabled="disabled"
+				:first-day-of-week="firstDayOfWeek"
+				:floating="floating"
+				header
+				:max="calendarMax"
+				:min="calendarMin"
+				:model-value="gridModelValue"
+				:range="range"
+				:readonly="readonly"
+				:selectable="selectable"
+				:utc="utc"
+				@update:model-value="onGridPick"
+			>
+				<template #day="slotProps">
+					<slot name="day" v-bind="slotProps" />
+				</template>
+				<template #append:day="slotProps">
+					<slot name="append:day" v-bind="slotProps" />
+				</template>
+			</BbBaseDatePicker>
+			<TimeSelector
+				v-if="datetime"
+				:ampm="ampm"
+				:disabled="disabled || readonly || !canPickTime"
+				:hour="panelHour"
+				:meridiem="panelMeridiem"
+				:minute="panelMinute"
+				:second="panelSecond"
+				:seconds="seconds"
+				:step="step"
+				@select="onTimePick"
+			/>
+		</div>
+	</DefinePanel>
+
+	<!-- Mobile adaptive surface: a bottom sheet hosting the same panel. -->
+	<BbOffCanvas
+		v-if="useOffcanvas"
+		v-model="isOpen"
+		class="bb-date-picker-offcanvas"
+		v-bind="offcanvasBindings"
+		@hidden="onSurfaceHidden"
+	>
+		<ReusePanel />
+	</BbOffCanvas>
+
+	<CommonPopover
+		v-else
+		v-model="isOpen"
+		:anchor="effectiveAnchor"
+		:aria-label="effectiveLabel"
+		:boundary="boundary"
+		class="bb-date-picker__popover"
+		dialog
+		:disable-flip="disableFlip"
+		:eager="eager"
+		hide-arrow
+		:offset="offset"
+		:padding="padding"
+		:placement="placement"
+		:transition-duration="transitionDuration"
+	>
+		<ReusePanel />
+	</CommonPopover>
+</template>
+
+<script setup lang="ts">
+import { config } from 'virtual:bitboss-ui/config';
+import { computed, nextTick, onBeforeUnmount, ref, watch } from 'vue';
+import { createReusableTemplate } from '@vueuse/core';
+import { extractDomContainer } from '@/utilities/functions/extractDomContainer';
+import {
+	toInnerValue,
+	toOuterValue,
+} from '@/utilities/functions/convertDateValue';
+import { useId } from '@/composables/useId';
+import { useLocale } from '@/composables/useLocale';
+import { useMobile } from '@/composables/useMobile';
+import { transitions } from '@/utilities/misc/transitions';
+import BbBaseDatePicker from '../BbBaseDatePicker/BbBaseDatePicker.vue';
+import TimeSelector, {
+	type TimeUnit,
+} from '../BbBaseDatePickerInput/BbBaseDatePickerTimeSelector.vue';
+import BbOffCanvas from '../BbOffCanvas/BbOffCanvas.vue';
+import CommonPopover from '../CommonPopover/CommonPopover.vue';
+import type {
+	BbDatePickerProps,
+	BbDatePickerEvents,
+	BbDatePickerSegment,
+	BbDatePickerSlots,
+} from './types';
+export type {
+	BbDatePickerProps,
+	BbDatePickerEvents,
+	BbDatePickerSlots,
+} from './types';
+
+const props = withDefaults(defineProps<BbDatePickerProps>(), {
+	offset: 4,
+	adaptive: undefined,
+	transitionDuration: transitions.medium,
+});
+
+const emit = defineEmits<BbDatePickerEvents>();
+defineSlots<BbDatePickerSlots>();
+
+const { t } = useLocale();
+const { isMobile } = useMobile();
+
+const gridId = `bdp-${useId().id.value}`;
+
+const [DefinePanel, ReusePanel] = createReusableTemplate();
+
+// ---- Refs ----------------------------------------------------------------------
+
+const calendarRef = ref<HTMLElement | null>(null);
+const gridRef = ref<InstanceType<typeof BbBaseDatePicker> | null>(null);
+
+// ---- Active range end (which end the time rail edits) --------------------------
+
+const activeSegment = computed<BbDatePickerSegment>(
+	() => props.activeSegment ?? internalSegment.value
+);
+const internalSegment = ref<BbDatePickerSegment>('start');
+const setActiveSegment = (segment: BbDatePickerSegment) => {
+	internalSegment.value = segment;
+	emit('update:activeSegment', segment);
+};
+
+// ---- Activator / anchor plumbing (mirrors BbColorPalette) -----------------------
+
+const activatorEl = ref<HTMLElement | undefined>();
+const anchorEl = ref<HTMLElement | undefined>();
+const hasExternalActivator = computed(() => props.activator != null);
+
+const setActivatorRef = (reference: unknown) => {
+	activatorEl.value = extractDomContainer(reference) ?? undefined;
+};
+const setAnchorRef = (reference: unknown) => {
+	anchorEl.value = extractDomContainer(reference) ?? undefined;
+};
+
+watch(
+	() => props.activator,
+	(val) => {
+		activatorEl.value = extractDomContainer(val) ?? undefined;
+	},
+	{ immediate: true }
+);
+watch(
+	() => props.anchor,
+	(val) => {
+		anchorEl.value =
+			val != null ? (extractDomContainer(val) ?? undefined) : undefined;
+	},
+	{ immediate: true }
+);
+
+const effectiveAnchor = computed(() => anchorEl.value ?? activatorEl.value);
+
+// ---- Open state ----------------------------------------------------------------
+
+const isOpen = ref(false);
+let previousFocus: HTMLElement | null = null;
+
+const onActivatorClick = (event: MouseEvent) => {
+	if (props.disabled || props.readonly) return;
+	event.stopPropagation();
+	isOpen.value = !isOpen.value;
+};
+
+/** Close when the backdrop (the dialog element itself) is clicked. */
+const onClickDocument = (event: Event) => {
+	if (event.target instanceof HTMLDialogElement) {
+		isOpen.value = false;
+	}
+};
+
+watch(isOpen, async (val) => {
+	if (val) {
+		previousFocus =
+			document.activeElement instanceof HTMLElement
+				? document.activeElement
+				: null;
+		// The floating <dialog> is modal; the sheet manages its own backdrop.
+		if (!useOffcanvas.value) {
+			document.addEventListener('click', onClickDocument, { passive: true });
+		}
+		await nextTick();
+		calendarRef.value?.querySelector<HTMLElement>('[tabindex="0"]')?.focus();
+	} else {
+		document.removeEventListener('click', onClickDocument);
+		gridRef.value?.resetStatus();
+		previousFocus?.focus();
+		previousFocus = null;
+	}
+});
+
+// ---- Programmatic listener + ARIA on the activator element ----------------------
+
+let cleanupActivator: (() => void) | null = null;
+
+watch(
+	activatorEl,
+	(el) => {
+		cleanupActivator?.();
+		cleanupActivator = null;
+		if (!el) return;
+		el.addEventListener('click', onActivatorClick);
+		cleanupActivator = () => {
+			el.removeEventListener('click', onActivatorClick);
+			el.removeAttribute('aria-haspopup');
+			el.removeAttribute('aria-expanded');
+			el.removeAttribute('aria-label');
+		};
+	},
+	{ immediate: true }
+);
+
+const effectiveLabel = computed(
+	() => props.label ?? t('datePicker.openPicker').value
+);
+
+watch(
+	[activatorEl, isOpen, effectiveLabel] as const,
+	([el, open, label]) => {
+		if (!el) return;
+		el.setAttribute('aria-haspopup', 'dialog');
+		el.setAttribute('aria-expanded', open ? 'true' : 'false');
+		el.setAttribute('aria-label', label);
+	},
+	{ immediate: true }
+);
+
+onBeforeUnmount(() => {
+	cleanupActivator?.();
+	document.removeEventListener('click', onClickDocument);
+});
+
+// ---- Adaptive surface (popover on desktop, bottom sheet on mobile) --------------
+// Latched when the panel opens and frozen until it closes, so a mid-session
+// resize never swaps a live popover into a sheet — mirroring the date input.
+
+const resolveSurface = (): 'popover' | 'canvas' =>
+	(props.adaptive ?? config.adaptive) && isMobile.value ? 'canvas' : 'popover';
+const surface = ref<'popover' | 'canvas'>(resolveSurface());
+const useOffcanvas = computed(() => surface.value === 'canvas');
+
+watch([() => props.adaptive, isMobile, isOpen], () => {
+	if (!isOpen.value) surface.value = resolveSurface();
+});
+
+const offcanvasBindings = computed(() => ({
+	side: 'bottom' as const,
+	size: 'auto' as const,
+	draggable: true,
+	disabled: props.disabled,
+	transitionDuration: props.transitionDuration,
+	...props.offCanvasProps,
+}));
+
+/** Return focus to the activator once the sheet's close transition finishes. */
+const onSurfaceHidden = () => {
+	activatorEl.value?.focus();
+};
+
+// The calendar is day-granular: hand it only the day part of the bounds.
+const calendarMin = computed(() => props.min?.slice(0, 10));
+const calendarMax = computed(() => props.max?.slice(0, 10));
+
+// The grid throws in range mode unless it receives an array — normalize an
+// empty/`null` range to `[]` so a cleared range never trips it.
+const gridModelValue = computed(() =>
+	props.range && !Array.isArray(props.modelValue) ? [] : props.modelValue
+);
+
+// ---- Value helpers -------------------------------------------------------------
+
+const satisfiesSelection = (value: BbDatePickerProps['modelValue']) =>
+	props.range ? Array.isArray(value) && value.length === 2 : !!value;
+
+const segIndex = (segment: BbDatePickerSegment) => (segment === 'end' ? 1 : 0);
+
+/** The raw date string carried in `modelValue` for a segment (or `null`). */
+const dateStringFor = (segment: BbDatePickerSegment): string | null => {
+	const mv = props.modelValue;
+	if (mv == null) return null;
+	if (Array.isArray(mv)) return mv[segIndex(segment)] ?? null;
+	return segment === 'start' ? mv : null;
+};
+
+type TimeParts = { hour: string; minute: string; second: string };
+
+/** The `HH:mm[:ss]` string for a segment: `time` model first, else the model's time. */
+const timeStringFor = (segment: BbDatePickerSegment): string | null => {
+	const time = props.time;
+	if (time != null) {
+		if (Array.isArray(time)) return time[segIndex(segment)] ?? null;
+		if (segment === 'start' && typeof time === 'string') return time;
+	}
+	if (props.floating) return null;
+	const raw = dateStringFor(segment);
+	if (!raw) return null;
+	const parsed = toInnerValue(raw);
+	return parsed.isValid()
+		? parsed.format(props.seconds ? 'HH:mm:ss' : 'HH:mm')
+		: null;
+};
+
+const timePartsFor = (segment: BbDatePickerSegment): TimeParts | null => {
+	const str = timeStringFor(segment);
+	if (!str) return null;
+	const [hour = '', minute = '', second = ''] = str.split(':');
+	return { hour, minute, second };
+};
+
+/** Combine one segment's date string with its time parts into an outer value. */
+const combineOne = (dateStr: string, time: TimeParts | null) => {
+	const date = toInnerValue(dateStr, { floating: props.floating });
+	if (!date.isValid()) return null;
+	const hour = time?.hour ? parseInt(time.hour, 10) : 0;
+	const minute = time?.minute ? parseInt(time.minute, 10) : 0;
+	const second = props.seconds && time?.second ? parseInt(time.second, 10) : 0;
+	const dt = date.hour(hour).minute(minute).second(second).millisecond(0);
+	return {
+		value: toOuterValue(dt, { floating: props.floating, utc: props.utc }),
+		time: props.seconds ? dt.format('HH:mm:ss') : dt.format('HH:mm'),
+	};
+};
+
+type SegmentState = { date: string | null; time: TimeParts | null };
+
+const readStates = (): Record<BbDatePickerSegment, SegmentState> => ({
+	start: { date: dateStringFor('start'), time: timePartsFor('start') },
+	end: { date: dateStringFor('end'), time: timePartsFor('end') },
+});
+
+/** Re-emit `modelValue` + `time` from the given per-segment date/time state. */
+const commit = (states: Record<BbDatePickerSegment, SegmentState>) => {
+	if (props.range) {
+		const values: string[] = [];
+		const times: string[] = [];
+		for (const segment of ['start', 'end'] as const) {
+			const st = states[segment];
+			if (!st.date) continue;
+			const combined = combineOne(st.date, st.time);
+			if (!combined) continue;
+			values.push(combined.value);
+			times.push(combined.time);
+		}
+		emit('update:modelValue', values.length ? values : null);
+		emit('update:time', times.length ? times : null);
+		return;
+	}
+	const st = states.start;
+	if (!st.date) {
+		emit('update:modelValue', null);
+		emit('update:time', null);
+		return;
+	}
+	const combined = combineOne(st.date, st.time);
+	emit('update:modelValue', combined ? combined.value : null);
+	emit('update:time', combined ? combined.time : null);
+};
+
+// ---- Grid pick -----------------------------------------------------------------
+
+const onGridPick = (value: BbDatePickerProps['modelValue']) => {
+	emit('grid-pick', value);
+
+	if (!props.datetime) {
+		emit('update:modelValue', value);
+		if (satisfiesSelection(value)) isOpen.value = false;
+		return;
+	}
+
+	if (value === null) {
+		emit('update:modelValue', null);
+		emit('update:time', null);
+		return;
+	}
+
+	const states = readStates();
+	if (Array.isArray(value)) {
+		states.start.date = value[0] ?? null;
+		states.end.date = value[1] ?? null;
+		// A new range keeps only the ends the grid still reports.
+		if (!value[1]) states.end.time = null;
+	} else {
+		states.start.date = value;
+	}
+	commit(states);
+};
+
+// ---- Time rail -----------------------------------------------------------------
+
+const canPickTime = computed(() => !!dateStringFor(activeSegment.value));
+const activeTime = computed(() => timePartsFor(activeSegment.value));
+const panelHour = computed(() => activeTime.value?.hour ?? '');
+const panelMinute = computed(() => activeTime.value?.minute ?? '');
+const panelSecond = computed(() => activeTime.value?.second ?? '');
+// The rail derives the meridiem from the 24h hour; no separate field to track.
+const panelMeridiem = computed(() => '');
+
+const onTimePick = (payload: { unit: TimeUnit; value: string }) => {
+	emit('time-pick', payload);
+	if (!props.datetime) return;
+
+	const segment = activeSegment.value;
+	const states = readStates();
+	if (!states[segment].date) return;
+
+	const next: TimeParts = states[segment].time
+		? { ...(states[segment].time as TimeParts) }
+		: { hour: '', minute: '', second: '' };
+
+	if (payload.unit === 'meridiem') {
+		let hour = next.hour ? parseInt(next.hour, 10) : 0;
+		const isPM = payload.value === 'PM';
+		if (isPM && hour < 12) hour += 12;
+		if (!isPM && hour >= 12) hour -= 12;
+		next.hour = String(hour).padStart(2, '0');
+	} else {
+		// `hour` arrives already converted to 24h; minute/second are zero-padded.
+		next[payload.unit] = payload.value;
+	}
+
+	// Fill the remaining blanks so a single tap commits a full time.
+	if (!next.hour) next.hour = '00';
+	if (!next.minute) next.minute = '00';
+	if (props.seconds && !next.second) next.second = '00';
+
+	states[segment].time = next;
+	commit(states);
+};
+
+// ---- Rail width (matches time-selector.css: columns + gaps + insets) -----------
+
+const railStyle = computed(() => {
+	if (!props.datetime) return undefined;
+	const widths = [44, 44];
+	if (props.seconds) widths.push(44);
+	if (props.ampm) widths.push(48);
+	const width =
+		33 + widths.reduce((a, b) => a + b, 0) + (widths.length - 1) * 6;
+	return { '--rail-w': `${width}px` };
+});
+
+// Keep the internal active segment in a sane place for range + datetime: default
+// to the end the grid last filled (host-driven `activeSegment` overrides this).
+watch(
+	() => props.modelValue,
+	(value) => {
+		if (!props.range || !props.datetime || props.activeSegment != null) return;
+		if (Array.isArray(value) && value.length === 2) setActiveSegment('end');
+	}
+);
+
+// Expose the live calendar element so a host (e.g. BbBaseDatePickerInput) can
+// scope an outside-click check to THIS picker's calendar instead of a page-wide
+// `.bb-date-picker__calendar` query that could match another open picker.
+defineExpose({ calendarEl: calendarRef });
+</script>
+
+<style lang="postcss">
+@import './index.css';
+</style>
+```
+
+## Types
+
+```ts
+import type {
+	ElementOrComponentRef,
+	ElementOrComponentRefOrSelector,
+} from '@/types/CommonProps';
+import type { Placement } from '@/types/Placement';
+import type { BbOffCanvasProps } from '../BbOffCanvas/types';
+import type { TimeUnit } from '../BbBaseDatePickerInput/BbBaseDatePickerTimeSelector.vue';
+
+/** Which end of a range the time rail edits. */
+export type BbDatePickerSegment = 'start' | 'end';
+
+export type BbDatePickerProps = {
+	/**
+	 * 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.
+	 */
+	activator?: ElementOrComponentRef;
+	/**
+	 * Element or component ref the popover positions itself relative to.
+	 * Defaults to the activator when omitted (anchor to a larger row while a
+	 * smaller element stays the click target).
+	 */
+	anchor?: ElementOrComponentRef;
+	/**
+	 * v-model value. `null` for empty, a single ISO string for single selection,
+	 * or a two-element `[start, end]` array when `range` is true. Plain
+	 * `YYYY-MM-DD` when `floating`; carries the time inline when
+	 * `datetime && !floating`.
+	 */
+	modelValue: string | string[] | null;
+	/**
+	 * 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 `datetime`.
+	 */
+	time?: string | string[] | null;
+	/**
+	 * Which end the time rail edits in range + 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.
+	 */
+	activeSegment?: BbDatePickerSegment;
+	/**
+	 * Adds a time rail beside the calendar. Non-floating values carry the time
+	 * inside `modelValue`; with `floating` the time travels only through `time`.
+	 */
+	datetime?: boolean;
+	/** Enables range selection (`[start, end]`). */
+	range?: boolean;
+	/** Adds the seconds column (requires `datetime`). */
+	seconds?: boolean;
+	/** 12-hour display with an AM/PM column (requires `datetime`); emits stay 24h. */
+	ampm?: boolean;
+	/**
+	 * Minute-column granularity and arrow stepping (requires `datetime`).
+	 * @defaultValue `1`
+	 */
+	step?: number;
+	/** Minimum selectable date, `YYYY-MM-DD` (or `YYYY-MM-DDTHH:mm` with `datetime`). */
+	min?: string;
+	/** Maximum selectable date, `YYYY-MM-DD` (or `YYYY-MM-DDTHH:mm` with `datetime`). */
+	max?: string;
+	/** Predicate invoked per candidate date; return `false` to disable it. */
+	selectable?: (date: string) => boolean;
+	/** Emit dates as plain `YYYY-MM-DD` instead of zoned ISO strings. */
+	floating?: boolean;
+	/** First day of the week (0 = Sunday … 6 = Saturday). */
+	firstDayOfWeek?: 0 | 1 | 2 | 3 | 4 | 5 | 6;
+	/** Emit UTC (`...Z`) instead of the local offset. Ignored with `floating`. */
+	utc?: boolean;
+	/** Disables the activator and the calendar. */
+	disabled?: boolean;
+	/** Prevents opening while keeping the activator visible. */
+	readonly?: boolean;
+	/**
+	 * On mobile, open in a bottom off-canvas sheet instead of a floating popover.
+	 * When unset, falls back to the global `config.adaptive`.
+	 * @defaultValue `config.adaptive` (`true`)
+	 */
+	adaptive?: boolean;
+	/** Extra props forwarded to the `BbOffCanvas` sheet when adaptive on mobile. */
+	offCanvasProps?: Partial<BbOffCanvasProps>;
+	/** Popover/sheet transition duration in milliseconds. */
+	transitionDuration?: number;
+	/** Position of the popover relative to the activator/anchor. */
+	placement?: Placement;
+	/**
+	 * Space the popover keeps from the activator.
+	 * @defaultValue `4`
+	 */
+	offset?: number;
+	/** Minimum empty space to keep from the edge of the page. */
+	padding?: number;
+	/** Constrains the popover within a bounding element or CSS selector. */
+	boundary?: ElementOrComponentRefOrSelector;
+	/** Disable the automatic flip to the opposite side on overflow. */
+	disableFlip?: boolean;
+	/** Render popover content before it is first shown. */
+	eager?: boolean;
+	/** Accessible label applied to the activator via `aria-label`. */
+	label?: string;
+};
+
+export type BbDatePickerEvents = {
+	/** Emitted when the selected date value changes (single/range/null). */
+	(e: 'update:modelValue', value: string | string[] | null): void;
+	/** Companion time model, alongside every change while `datetime` is on. */
+	(e: 'update:time', value: string | string[] | null): void;
+	/** The active range end changed (range + datetime only). */
+	(e: 'update:activeSegment', value: BbDatePickerSegment): void;
+	/**
+	 * Relay of the raw calendar-grid pick, before this component combines it with
+	 * the time. An embedding host binds this to run its own value engine; clean
+	 * consumers ignore it and use `update:modelValue`.
+	 */
+	(e: 'grid-pick', value: string | string[] | null): void;
+	/**
+	 * Relay of the raw time-rail pick. An embedding host binds this to run its own
+	 * value engine; clean consumers ignore it and use `update:time`.
+	 */
+	(e: 'time-pick', payload: { unit: TimeUnit; value: string }): void;
+};
+
+/** Props exposed by the `activator` slot (mirrors `BbColorPalette`). */
+export type BbDatePickerActivatorSlotProps = {
+	/** Spread onto your activator element to register its ref. */
+	props: { ref: (el: unknown) => void };
+	/** Spread onto a wrapping element to anchor the popover to something larger. */
+	anchorProps: { ref: (el: unknown) => void };
+	/** Whether the calendar popover is currently open. */
+	open: boolean;
+	/** The current value (mirrors `modelValue`). */
+	value: string | string[] | null;
+	/** Whether the picker is disabled. */
+	disabled: boolean;
+};
+
+/** Scope handed to the `day` / `append:day` slots (forwarded to the grid). */
+export type BbDatePickerDaySlotProps = {
+	first: boolean;
+	highlighted: boolean;
+	item: any;
+	label: string;
+	last: boolean;
+	middle: boolean;
+	selected: boolean;
+};
+
+export type BbDatePickerSlots = {
+	/** Custom activator element. Apply `v-bind="props"` to your trigger. */
+	activator?: (props: BbDatePickerActivatorSlotProps) => any;
+	/** Replaces the day button label inside each calendar day. */
+	day?: (props: BbDatePickerDaySlotProps) => any;
+	/** Appends content below each calendar day. */
+	'append:day'?: (props: BbDatePickerDaySlotProps) => any;
+};
+```
+
+## Styles
+
+```css
+/*
+ * BbDatePicker — the calendar (and optional time rail) hosted in a popover or,
+ * on mobile with `adaptive`, a bottom sheet. The calendar grid and the time
+ * rail carry their own styles (BbBaseDatePicker / BbBaseDatePickerTimeSelector);
+ * only the container-level layout lives here.
+ */
+
+/* Match the calendar popover drop shadow. The `<dialog>` UA style clips
+   overflow, so reset it to visible to let the bubble shadow show. */
+.bb-date-picker__popover.bb-common-popover {
+	overflow: visible;
+
+	.bb-common-popover__bubble {
+		box-shadow: var(--bb-shadow);
+	}
+}
+
+/* Desktop popover: the calendar grid defines the panel height; the time rail is
+   an absolutely-positioned overlay in the width the container reserves for it,
+   so it is always exactly as tall as the calendar. */
+.bb-date-picker__calendar--datetime {
+	padding-right: var(--rail-w, 252px);
+	position: relative;
+}
+
+/* Mobile sheet: the calendar has a fixed width (7 cells), so just center it. */
+.bb-date-picker__calendar--sheet {
+	/* Declared on the container so the time rail (the calendar's sibling) can
+	   align its wheels to the same column grid. */
+	--sheet-cell: 40px;
+
+	display: flex;
+	justify-content: center;
+
+	/* One touch scale for the whole sheet: 40px day cells (36px marks), and a
+	   nav row to match. */
+	.bb-base-date-picker {
+		--cell: var(--sheet-cell);
+		--nav-button-h: 40px;
+
+		.bb-base-date-picker__heading-btn {
+			padding: 10px 12px;
+		}
+	}
+
+	/* Sheet + datetime: stack the rail under the calendar instead of beside it. */
+	&.bb-date-picker__calendar--datetime {
+		flex-direction: column;
+		margin-inline: auto;
+		padding-right: 0;
+		width: fit-content;
+	}
+}
+```