bitboss-ui 3.0.0-beta.3 → 3.0.0-beta.31

package/dist/ai/source/CommonTimeSelector.md

@@ -0,0 +1,642 @@
+# CommonTimeSelector — Implementation Source
+
+> Full implementation for deep dives. For everyday usage read the typed contract: [../CommonTimeSelector.md](../CommonTimeSelector.md).
+>
+> Safety level: **Reference Only - Internal** — do not use in consumer-facing code unless explicitly requested.
+
+## Template & Script
+
+```vue
+<template>
+	<div class="bb-time-selector">
+		<div
+			aria-hidden="true"
+			class="bb-time-selector__readout"
+			:class="{ 'bb-time-selector__readout--empty': readoutEmpty }"
+		>
+			{{ readout }}
+		</div>
+		<div class="bb-time-selector__columns">
+			<div
+				v-for="column in columns"
+				:key="column.unit"
+				:aria-label="column.ariaLabel"
+				class="bb-time-selector__column"
+				:class="`bb-time-selector__column--${column.unit}`"
+				role="group"
+				@keydown="onColumnKeydown(column, $event)"
+			>
+				<div aria-hidden="true" class="bb-time-selector__header">
+					{{ column.header }}
+				</div>
+				<!-- `data-bb-no-drag`: a wheel is a scroller inside a draggable sheet.
+				Without it a downward swipe on a wheel already at its top was handed to
+				the sheet and dismissed it mid-pick (BbOffCanvas only yields to a
+				scroller that can still scroll the gesture's way). -->
+				<div
+					:ref="(el) => (columnRefs[column.unit] = el as HTMLElement)"
+					class="bb-time-selector__scroll"
+					data-bb-no-drag
+				>
+					<!-- eslint-disable vue/attributes-order -- `pt` binds LAST so a consumer listener runs after ours (PASSTHROUGH.md T17) -->
+					<BbBaseButton
+						v-for="option in column.options"
+						:key="option.value"
+						:aria-pressed="option.selected"
+						class="bb-time-selector__btn"
+						:class="{ 'bb-time-selector__btn--selected': option.selected }"
+						:data-value="option.value"
+						:disabled="disabled"
+						@click="select(column, option)"
+						v-bind="passthrough?.part?.('item', { selected: option.selected })"
+					>
+						{{ option.text }}
+					</BbBaseButton>
+					<!-- eslint-enable vue/attributes-order -->
+				</div>
+			</div>
+		</div>
+	</div>
+</template>
+
+<script setup lang="ts">
+import { computed, watch, nextTick, onMounted } from 'vue';
+import type { PtBindings } from '@/types/passthrough';
+import { useLocale } from '@/composables/useLocale';
+import { useTypeahead } from '@/composables/useTypeahead';
+import BbBaseButton from '../BbBaseButton/BbBaseButton.vue';
+import type { TimeUnit } from './types';
+
+const props = defineProps<{
+	/** The owning picker's passthrough resolver: `item` per entry, with `selected`. Internal. */
+	passthrough?: PtBindings<'item', 'selected'>;
+	/** Current hour as a 24-hour field string (may be empty). */
+	hour: string;
+	/** Current minute/second field strings (may be empty). */
+	minute: string;
+	second: string;
+	/** Current meridiem field value (`AM`/`PM`, may be empty). */
+	meridiem?: string;
+	/** Renders the seconds column. */
+	seconds?: boolean;
+	/** 12-hour hour column plus an AM/PM column; emitted hours stay 24-hour. */
+	ampm?: boolean;
+	/** Minute-column granularity; off-grid values highlight nothing. */
+	step?: number;
+	disabled?: boolean;
+}>();
+
+const emit = defineEmits<
+	/**
+	 * A column entry was chosen. `hour` is always the 24-hour value (already
+	 * combined with the meridiem in `ampm` mode); `meridiem` carries `AM`/`PM`.
+	 * Numeric values arrive zero-padded.
+	 */
+	(e: 'select', payload: { unit: TimeUnit; value: string }) => void
+>();
+
+const { t } = useLocale();
+
+const columnRefs: Partial<Record<TimeUnit, HTMLElement | null>> = {};
+
+// ── 12h/24h helpers (display-only; the emitted contract stays 24h) ──────────
+
+const to24Hour = (hour12: number, meridiem: string): number => {
+	if (meridiem === 'PM') return hour12 === 12 ? 12 : hour12 + 12;
+	return hour12 === 12 ? 0 : hour12;
+};
+
+const currentMeridiem = computed<'AM' | 'PM'>(() => {
+	if (props.meridiem === 'PM') return 'PM';
+	if (props.meridiem === 'AM') return 'AM';
+	// Derive from a 24h hour when the field is unset (incoming model values).
+	if (props.hour && parseInt(props.hour, 10) >= 12) return 'PM';
+	return 'AM';
+});
+
+/** The selected number for a column, in that column's own value space. */
+const selectedNumber = (unit: TimeUnit): number | null => {
+	if (unit === 'hour') {
+		if (!props.hour) return null;
+		const hour24 = parseInt(props.hour, 10);
+		if (!props.ampm) return hour24;
+		let hour12 = hour24 % 12;
+		if (hour12 === 0) hour12 = 12;
+		return hour12;
+	}
+	const raw = props[unit as 'minute' | 'second'];
+	if (!raw) return null;
+	return parseInt(raw, 10);
+};
+
+type Option = {
+	value: number | string;
+	text: string;
+	selected: boolean;
+	tokens: string[];
+};
+type Column = {
+	unit: TimeUnit;
+	header: string;
+	ariaLabel: string;
+	options: Option[];
+};
+
+const buildNumericOptions = (unit: TimeUnit, values: number[]): Option[] => {
+	const current = selectedNumber(unit);
+	return values.map((value) => {
+		const text = String(value).padStart(2, '0');
+		return {
+			value,
+			text,
+			// Exact match only: an off-grid value (10:07 under step 15) highlights
+			// nothing rather than lying with the nearest slot.
+			selected: current === value,
+			tokens: [String(value), text],
+		};
+	});
+};
+
+const minuteValues = computed(() => {
+	const step = Math.max(1, Math.floor(props.step ?? 1));
+	const values: number[] = [];
+	for (let m = 0; m < 60; m += step) values.push(m);
+	return values;
+});
+
+/**
+ * Column headers reuse the localized format hint (`HH:MM[:SS]`), so the
+ * letters match the placeholder the user already read in the field.
+ */
+const unitHeaders = computed(() => {
+	const parts = t(
+		props.seconds
+			? 'datePickerInput.timeFormatSeconds'
+			: 'datePickerInput.timeFormat'
+	).value.split(':');
+	return {
+		hour: parts[0] ?? 'HH',
+		minute: parts[1] ?? 'MM',
+		second: parts[2] ?? 'SS',
+	};
+});
+
+const columns = computed<Column[]>(() => {
+	const list: Column[] = [
+		{
+			unit: 'hour',
+			header: unitHeaders.value.hour,
+			ariaLabel: t('datePicker.hoursLabel').value,
+			options: buildNumericOptions(
+				'hour',
+				props.ampm
+					? Array.from({ length: 12 }, (_, i) => i + 1)
+					: Array.from({ length: 24 }, (_, i) => i)
+			),
+		},
+		{
+			unit: 'minute',
+			header: unitHeaders.value.minute,
+			ariaLabel: t('datePicker.minutesLabel').value,
+			options: buildNumericOptions('minute', minuteValues.value),
+		},
+	];
+	if (props.seconds) {
+		list.push({
+			unit: 'second',
+			header: unitHeaders.value.second,
+			ariaLabel: t('datePicker.secondsLabel').value,
+			options: buildNumericOptions(
+				'second',
+				Array.from({ length: 60 }, (_, i) => i)
+			),
+		});
+	}
+	if (props.ampm) {
+		list.push({
+			unit: 'meridiem',
+			header: ' ',
+			ariaLabel: t('datePickerInput.meridiemField').value,
+			options: (['AM', 'PM'] as const).map((value) => ({
+				value,
+				text: value,
+				selected: !!props.hour && currentMeridiem.value === value,
+				tokens: [value.toLowerCase(), value[0].toLowerCase()],
+			})),
+		});
+	}
+	return list;
+});
+
+/**
+ * The rail's counterpart of the calendar heading: the selected time exactly
+ * as the fields display it (12-hour under `ampm`), with dashes while a unit
+ * is still unset.
+ */
+const DASH = '\u2013\u2013';
+
+const readout = computed(() => {
+	const hourNum = selectedNumber('hour');
+	const parts = [
+		hourNum === null ? DASH : String(hourNum).padStart(2, '0'),
+		props.minute ? props.minute.padStart(2, '0') : DASH,
+	];
+	if (props.seconds) {
+		parts.push(props.second ? props.second.padStart(2, '0') : DASH);
+	}
+	let text = parts.join(':');
+	if (props.ampm) text += ` ${props.hour ? currentMeridiem.value : DASH}`;
+	return text;
+});
+
+const readoutEmpty = computed(() => !props.hour && !props.minute);
+
+const select = (column: Column, option: Option) => {
+	if (column.unit === 'hour' && props.ampm) {
+		// Combine the picked 12h row with the active meridiem → 24h contract.
+		const hour24 = to24Hour(option.value as number, currentMeridiem.value);
+		emit('select', { unit: 'hour', value: String(hour24).padStart(2, '0') });
+		return;
+	}
+	if (column.unit === 'meridiem') {
+		emit('select', { unit: 'meridiem', value: String(option.value) });
+		return;
+	}
+	emit('select', {
+		unit: column.unit,
+		value: String(option.value).padStart(2, '0'),
+	});
+};
+
+// ── Scroll management ───────────────────────────────────────────────────────
+// Keep the selected (or nearest, for off-grid values) row centered so the
+// current time is always visible when the panel opens or the value changes.
+
+const prefersReducedMotion = () =>
+	typeof window !== 'undefined' &&
+	!!window.matchMedia?.('(prefers-reduced-motion: reduce)').matches;
+
+/** Recenter a column; animate only on live changes, never against reduced-motion. */
+const scrollColumnTo = (el: HTMLElement, top: number, smooth: boolean) => {
+	el.scrollTo({
+		top,
+		behavior: smooth && !prefersReducedMotion() ? 'smooth' : 'auto',
+	});
+};
+
+const centerColumn = (unit: TimeUnit, smooth = false) => {
+	const container = columnRefs[unit];
+	if (!container) return;
+	const column = columns.value.find((c) => c.unit === unit);
+	if (!column) return;
+	const selected = column.options.find((o) => o.selected);
+	const buttons = Array.from(
+		container.querySelectorAll<HTMLElement>('[data-value]')
+	);
+	if (!buttons.length) return;
+	let target: HTMLElement | undefined;
+	if (selected) {
+		target = buttons.find((el) => el.dataset.value === String(selected.value));
+	} else if (unit === 'minute' && props.minute) {
+		// Off-grid value: scroll to the nearest slot without highlighting it.
+		const current = parseInt(props.minute, 10);
+		target = buttons.reduce((best, el) => {
+			const d = (el2: HTMLElement) =>
+				Math.abs(parseInt(el2.dataset.value ?? '0', 10) - current);
+			return d(el) < d(best) ? el : best;
+		});
+	}
+	if (!target) {
+		scrollColumnTo(container, 0, smooth);
+		return;
+	}
+	// Center the target, then snap to a whole number of rows. Snapping keeps the
+	// scroll offset a multiple of the row height, so the rows always render at the
+	// same phase as the resting (scrollTop 0) list — i.e. level with the calendar
+	// day rows — instead of an exact center landing them on a fractional grid that
+	// shifts with the panel height (a taller/shorter month would drift otherwise).
+	const rowHeight = target.offsetHeight || 1;
+	const centered =
+		target.offsetTop -
+		container.offsetTop -
+		container.clientHeight / 2 +
+		target.offsetHeight / 2;
+	scrollColumnTo(
+		container,
+		Math.round(centered / rowHeight) * rowHeight,
+		smooth
+	);
+};
+
+const centerAll = (smooth = false) => {
+	for (const column of columns.value) centerColumn(column.unit, smooth);
+};
+
+// Instant on first paint (the panel should appear already centered); animate the
+// recenter that follows a live hour/minute/second/meridiem change.
+onMounted(() => nextTick(() => centerAll(false)));
+watch(
+	() => [props.hour, props.minute, props.second, props.meridiem],
+	() => nextTick(() => centerAll(true))
+);
+
+// ── Keyboard ────────────────────────────────────────────────────────────────
+// ArrowUp/Down walk the (stepped) rows; printable keys drive a per-column
+// typeahead, mirroring the month/year selectors.
+
+const typeaheadFor = (index: number) =>
+	useTypeahead({
+		candidates: () => columns.value[index]?.options ?? [],
+		getTokens: (o: Option) => o.tokens,
+		getCurrent: () => columns.value[index]?.options.find((o) => o.selected),
+		onMatch: (o: Option) =>
+			focusValue(columns.value[index].unit, String(o.value)),
+		onCommit: (o: Option) => select(columns.value[index], o),
+		locale: () => 'en',
+	}).onKeydown;
+
+const typeaheads = [0, 1, 2, 3].map(typeaheadFor);
+
+const focusValue = (unit: TimeUnit, value: string) => {
+	const button = columnRefs[unit]?.querySelector<HTMLElement>(
+		`[data-value="${value}"]`
+	);
+	button?.focus();
+	button?.scrollIntoView({ block: 'nearest' });
+};
+
+const onColumnKeydown = (column: Column, event: KeyboardEvent) => {
+	if (event.key === 'ArrowDown' || event.key === 'ArrowUp') {
+		event.preventDefault();
+		const container = columnRefs[column.unit];
+		if (!container) return;
+		const buttons = Array.from(
+			container.querySelectorAll<HTMLElement>('[data-value]')
+		);
+		const active = document.activeElement;
+		const index = buttons.findIndex((el) => el === active);
+		const next =
+			event.key === 'ArrowDown'
+				? buttons[Math.min(index + 1, buttons.length - 1)]
+				: buttons[Math.max(index - 1, 0)];
+		next?.focus();
+		next?.scrollIntoView({ block: 'nearest' });
+		return;
+	}
+	const columnIndex = columns.value.findIndex((c) => c.unit === column.unit);
+	typeaheads[columnIndex]?.(event);
+};
+</script>
+
+<style lang="postcss">
+@import './index.css';
+</style>
+```
+
+## Types
+
+```ts
+/**
+ * One column of the shared time rail (`CommonTimeSelector`): the unit a
+ * `select` / `time-pick` payload carries. Used by BbDatePicker, BbTimePicker
+ * and BbTimePickerInput.
+ */
+export type TimeUnit = 'hour' | 'minute' | 'second' | 'meridiem';
+```
+
+## Styles
+
+```css
+/*
+ * The time rail: hour/minute(/second/AM-PM) columns rendered beside the
+ * calendar grid (below it in the mobile sheet). Shares the month/year
+ * selectors' visual language — same pill rows, same muted header ramp as the
+ * calendar's weekday initials — so it reads as part of the calendar, not an
+ * attachment.
+ */
+.bb-time-selector {
+	--time-row-h: 28px;
+	--time-col-w: 44px;
+	/* Visible mark = the day-cell mark (--cell - 4). Hit area stays the full
+	   row; only the painted knob matches the calendar's. */
+	--time-mark: 24px;
+
+	border-left: var(--bb-border-w) solid var(--bb-border);
+	bottom: 0;
+	display: flex;
+	flex-direction: column;
+	/* Mirror the calendar body's vertical padding (--pad-y, 8px) top AND bottom:
+	   the readout then sits level with the month/year controls, the headers level
+	   with the weekday initials, and — because the middle scroll flexes — the last
+	   row anchors on the calendar's bottom edge. 12px left gutter for the divider. */
+	padding: 8px 8px 8px 12px;
+	position: absolute;
+	right: 0;
+	top: 0;
+	width: calc(var(--rail-w, 252px) - 12px);
+
+	/* The rail's counterpart of "Luglio 2026": the currently selected time,
+	   sized and weighted like the heading buttons. */
+	&__readout {
+		align-items: center;
+		color: var(--bb-text);
+		display: flex;
+		flex: none;
+		font-size: 14px;
+		font-variant-numeric: tabular-nums;
+		font-weight: 500;
+		height: 24px;
+		justify-content: center;
+		margin-bottom: 6px;
+		user-select: none;
+
+		&--empty {
+			color: var(--bb-text-faint);
+		}
+	}
+
+	&__columns {
+		display: flex;
+		flex: 1 1 auto;
+		gap: 6px;
+		min-height: 0;
+	}
+
+	&__column {
+		display: flex;
+		flex-direction: column;
+		min-height: 0;
+		width: var(--time-col-w);
+
+		&--meridiem {
+			--time-col-w: 48px;
+
+			.bb-time-selector__btn::before {
+				width: calc(var(--time-mark) + 10px);
+			}
+		}
+	}
+
+	/* Mirrors the calendar's weekday header cells: 12px/600, 60% text, 26px tall
+	   with the same 2px gap the calendar's header-container leaves below it, so
+	   the first row lands exactly on the calendar's first day row. */
+	&__header {
+		align-items: center;
+		color: var(--bb-text-muted);
+		display: flex;
+		flex: none;
+		font-size: 12px;
+		font-weight: 600;
+		height: 26px;
+		justify-content: center;
+		margin-bottom: 2px;
+		user-select: none;
+		white-space: pre;
+	}
+
+	/* The rows fill the space between the header and the bottom padding, so the
+	   window shows exactly one row per calendar week (--time-row-h == --cell) and
+	   grows a row automatically when a month adds a sixth week. No inset or fade:
+	   the first and last rows sit crisp and level with the calendar's first/last
+	   day rows (scrolling snaps to whole rows — see centerColumn). */
+	&__scroll {
+		display: flex;
+		flex: 1 1 auto;
+		flex-direction: column;
+		gap: 0;
+		min-height: 0;
+		overflow-y: auto;
+		scrollbar-width: none;
+	}
+
+	&__btn {
+		align-items: center;
+		color: var(--bb-text-muted);
+		display: flex;
+		flex: none;
+		font-size: 12px;
+		font-variant-numeric: tabular-nums;
+		font-weight: 500;
+		height: var(--time-row-h);
+		/* Contains the mark's z-index:-1 so it can never slip behind ancestors. */
+		isolation: isolate;
+		justify-content: center;
+		letter-spacing: 0.01em;
+		/* Text line box fills the whole row height, like a calendar day cell. */
+		line-height: var(--time-row-h);
+		position: relative;
+		transition: color var(--bb-transition-fast);
+
+		/* The painted knob: same square as a day cell, centered in the full
+		   hit row so the two zones share one visual measure. */
+		&::before {
+			border-radius: var(--bb-radius-sm);
+			content: '';
+			height: var(--time-mark);
+			left: 50%;
+			position: absolute;
+			top: 50%;
+			transform: translate(-50%, -50%);
+			transition: background-color var(--bb-transition-fast);
+			width: var(--time-mark);
+			z-index: -1;
+		}
+
+		&:hover:not(:disabled) {
+			color: var(--bb-text);
+
+			&::before {
+				background-color: color-mix(in oklab, var(--bb-text) 8%, transparent);
+			}
+		}
+
+		&:focus-visible {
+			outline: none;
+
+			&::before {
+				box-shadow: 0 0 0 var(--bb-ring-size) var(--bb-ring);
+			}
+		}
+
+		/* Waiting for a date: rows recede, headers stay crisp. */
+		&:disabled {
+			cursor: not-allowed;
+			opacity: 0.35;
+		}
+
+		&--selected {
+			color: var(--bb-primary-fg);
+			font-weight: 600;
+
+			&::before {
+				background-color: var(--bb-primary);
+			}
+
+			&:hover:not(:disabled) {
+				color: var(--bb-primary-fg);
+
+				&::before {
+					background-color: var(--bb-primary);
+				}
+			}
+		}
+	}
+}
+
+/* The container reserving the rail width lives in BbCalendar/index.css
+ * (`.bb-calendar--datetime`); the rail's layout in the date picker's mobile
+ * sheet in BbDatePicker/index.css (`.bb-date-picker__panel--sheet`). */
+
+/* Standalone rail (the time-only pickers — BbTimePickerInput's panel and
+ * BbTimePicker's panel): no calendar to size against, so the rail
+ * backs into the flow with a fixed height instead of overlaying a grid. */
+.bb-time-picker-input__panel,
+.bb-time-picker__panel {
+	position: relative;
+
+	.bb-time-selector {
+		border-left: 0;
+		padding-left: 0;
+		padding-top: 8px;
+		position: static;
+		width: auto;
+	}
+
+	/* No calendar to size against: pin the scroll window to exactly 5 rows so the
+	   picker always shows 5 cells (a fixed panel height landed on ~6.5). Works at
+	   any row height — 28px desktop, 40px sheet. */
+	.bb-time-selector__scroll {
+		flex: none;
+		height: calc(var(--time-row-h) * 5);
+	}
+
+	/* No calendar heading to sit beside — the readout just repeats the selected
+	   value (the model), so hide it in the standalone pickers. The HH/MM/SS column
+	   headers stay. (The readout is already aria-hidden, so no a11y impact.) */
+	.bb-time-selector__readout {
+		display: none;
+	}
+}
+
+/* Mobile sheet for those standalone pickers: centre the column cluster in the
+ * full-width sheet and scale the rows to touch, mirroring the datetime rail's
+ * sheet treatment (BbDatePicker/index.css). Column layout so BbTimePicker's range segment toggle
+ * stacks above the centred columns. */
+.bb-time-picker-input__panel--sheet,
+.bb-time-picker__panel--sheet {
+	align-items: center;
+	display: flex;
+	flex-direction: column;
+
+	.bb-time-selector {
+		--time-mark: 36px;
+		--time-row-h: 40px;
+		--time-col-w: 48px;
+
+		.bb-time-selector__columns {
+			gap: 4px;
+			justify-content: center;
+		}
+	}
+}
+```

package/dist/ai/source/ErrorIcon.md

@@ -37,7 +37,7 @@ export type ErrorIconSlots = Record<never, never>;
 
 ```css
 .bb-error-icon {
-	--color: var(--bb-danger);
-	color: var(--color);
+	--accent: var(--bb-danger);
+	color: var(--accent);
 }
 ```