bitboss-ui 2.1.113 → 2.1.115

package/dist/ai/BaseDatePicker.md

@@ -0,0 +1,739 @@
+# BaseDatePicker
+
+## Template & Script
+
+```vue
+<template>
+	<div class="bb-base-date-picker">
+		<Header :cursor="cursor" :disabled="disabled" :hidden="!header" />
+		<div class="bb-base-date-picker__body">
+			<div class="bb-base-date-picker__controls">
+				<BaseButton
+					:aria-expanded="mode === 'month'"
+					aria-label="Select month"
+					class="bb-base-date-picker__control bb-base-date-picker__month-control"
+					:disabled="disabled"
+					@click="toggleMode('month')"
+				>
+					{{ formattedMonthYear }}
+					<span class="sr-only">{{ t('datePicker.monthLabel') }}</span>
+				</BaseButton>
+				<BaseButton
+					:aria-expanded="mode === 'year'"
+					aria-label="Select year"
+					class="bb-base-date-picker__control bb-base-date-picker__year-control"
+					:disabled="disabled"
+					@click="toggleMode('year')"
+				>
+					<svg
+						fill="none"
+						height="6"
+						viewBox="0 0 10 6"
+						width="10"
+						xmlns="http://www.w3.org/2000/svg"
+					>
+						<path
+							d="M5.24124 5.81871L9.52771 1.39839C9.79517 1.12257 9.63305 0.595276 9.28077 0.595276H0.707839C0.355562 0.595276 0.193433 1.12257 0.460901 1.39839L4.74736 5.81871C4.88946 5.96524 5.09914 5.96524 5.24124 5.81871Z"
+							fill="currentColor"
+						/>
+					</svg>
+					<span class="sr-only">{{ t('datePicker.yearLabel') }}</span>
+				</BaseButton>
+				<BaseButton
+					:aria-label="t('datePicker.previousMonthLabel')"
+					class="bb-base-date-picker__control"
+					:disabled="disabled || mode !== 'day'"
+					@click="decreaseMonth"
+				>
+					<svg
+						viewBox="0 0 24 24"
+						width="24px"
+						xmlns="http://www.w3.org/2000/svg"
+					>
+						<path
+							d="M13.939 4.939 6.879 12l7.06 7.061 2.122-2.122L11.121 12l4.94-4.939z"
+							fill="currentColor"
+						/>
+					</svg>
+					<span class="sr-only">{{ t('datePicker.previousMonthLabel') }}</span>
+				</BaseButton>
+				<BaseButton
+					:aria-label="t('datePicker.nextMonthLabel')"
+					class="bb-base-date-picker__control"
+					:disabled="disabled || mode !== 'day'"
+					@click="increaseMonth"
+				>
+					<svg
+						style="transform: rotate(180deg)"
+						viewBox="0 0 24 24"
+						width="24px"
+						xmlns="http://www.w3.org/2000/svg"
+					>
+						<path
+							d="M13.939 4.939 6.879 12l7.06 7.061 2.122-2.122L11.121 12l4.94-4.939z"
+							fill="currentColor"
+						/>
+					</svg>
+					<span class="sr-only">{{ t('datePicker.nextMonthLabel') }}</span>
+				</BaseButton>
+			</div>
+			<div class="bb-base-date-picker__content">
+				<DaySelector
+					:id="globalId"
+					:current="mode === 'day'"
+					:cursor="cursor"
+					:disabled="disabled"
+					:first-day-of-week="firstDayOfWeek"
+					:floating="floating"
+					:inert="mode !== 'day'"
+					:max="max"
+					:min="min"
+					:model-value="modelValue"
+					:multiple="multiple"
+					:range="range"
+					:readonly="readonly"
+					:selectable="selectable"
+					@update:cursor="handleCursorUpdate"
+					@update:model-value="updateModelValue"
+				>
+					<!-- @vue-ignore -->
+					<template v-for="(_, name) in $slots" #[name]="data">
+						<slot :name="name" v-bind="data" />
+					</template>
+				</DaySelector>
+				<ScaleFadeTransition :duration="200">
+					<MonthSelector
+						v-if="mode === 'month'"
+						:cursor="cursor"
+						:disabled="disabled"
+						@update:month="handleMonthSelected"
+					/>
+				</ScaleFadeTransition>
+				<ScaleFadeTransition :duration="200">
+					<YearSelector
+						v-if="mode === 'year'"
+						:cursor="cursor"
+						:disabled="disabled"
+						@update:year="handleYearSelected"
+					/>
+				</ScaleFadeTransition>
+			</div>
+		</div>
+		<div
+			:id="`${globalId}-status`"
+			aria-atomic="true"
+			aria-live="polite"
+			class="sr-only"
+			role="status"
+		>
+			{{ modeAnnouncement }}
+		</div>
+	</div>
+</template>
+
+<script setup lang="ts">
+import { BaseButton, useId } from '@/index';
+import { Dayjs, default as dayjs } from 'dayjs';
+import { default as isSameOrAfter } from 'dayjs/plugin/isSameOrAfter';
+import { default as isSameOrBefore } from 'dayjs/plugin/isSameOrBefore';
+import { default as weekOfYear } from 'dayjs/plugin/weekOfYear';
+import { hash } from '@/utilities/functions/hash';
+import { last } from '@/utilities/functions/last';
+import { validateDateFormat } from '@/utilities/functions/validateDateFormat';
+import { ref, watch, computed } from 'vue';
+import { useLogger } from '@/composables/useLogger';
+import DaySelector from './BaseDatePickerInputDaySelector.vue';
+import Header from './BaseDatePickerHeader.vue';
+import MonthSelector from './BaseDatePickerMonthSelector.vue';
+import ScaleFadeTransition from '@/components/Transitions/ScaleFade.vue';
+import YearSelector from './BaseDatePickerYearSelector.vue';
+import { useLocale } from '@/composables/useLocale';
+import { _config } from '@/composables/useBbConfig';
+
+dayjs.extend(weekOfYear);
+dayjs.extend(isSameOrAfter);
+dayjs.extend(isSameOrBefore);
+
+import type {
+	BaseDatePickerProps,
+	BaseDatePickerEvents,
+	BaseDatePickerSlots,
+} from './types';
+
+const emit = defineEmits<BaseDatePickerEvents>();
+
+const props = withDefaults(defineProps<BaseDatePickerProps>(), {
+	firstDayOfWeek: 1,
+});
+
+defineSlots<BaseDatePickerSlots>();
+
+const { t } = useLocale();
+
+const globalId = props.id || useId().id;
+
+const logger = useLogger();
+if (props.multiple && props.range) {
+	logger.throw('Date picker cannot be both multiple and range.');
+}
+if (props.multiple || props.range) {
+	if (!Array.isArray(props.modelValue)) {
+		logger.throw(
+			'Date picker is set to select multiple dates but modelValue is not an array.'
+		);
+	}
+}
+
+if (props.min) {
+	validateDateFormat(props.min, 'Min');
+}
+if (props.max) {
+	validateDateFormat(props.max, 'Max');
+}
+
+const cursor = ref<Dayjs>(dayjs());
+const setCursor = (value: typeof props.modelValue) => {
+	// Default to today if no value
+	if (!value) {
+		cursor.value = dayjs().startOf('day');
+		return;
+	}
+
+	// Handle array values (multiple/range mode)
+	if (Array.isArray(value)) {
+		if (value.length === 0) {
+			cursor.value = dayjs().startOf('day');
+			return;
+		}
+
+		const datesAsNumber = value.map((el) => dayjs(el).valueOf());
+		const cursorTimestamp = cursor.value.valueOf();
+
+		// Keep current cursor if it's in the selected dates
+		if (datesAsNumber.includes(cursorTimestamp)) {
+			return;
+		}
+
+		// Otherwise, move to last selected date
+		cursor.value = dayjs(last(value)).startOf('day');
+		return;
+	}
+
+	// Handle single value
+	cursor.value = dayjs(value).startOf('day');
+};
+setCursor(props.modelValue);
+type Mode = 'day' | 'month' | 'year';
+const mode = ref<Mode>('day');
+const toggleMode = (target: Mode) => {
+	if (mode.value === target) mode.value = 'day';
+	else mode.value = target;
+};
+
+const formattedMonthYear = computed(() =>
+	cursor.value.locale(_config.locale).format('MMMM YYYY')
+);
+
+const modeAnnouncement = computed(() => {
+	if (mode.value === 'month') return 'Selecting month';
+	if (mode.value === 'year') return 'Selecting year';
+	return '';
+});
+
+const updateMonth = (monthNumber: number) => {
+	cursor.value = cursor.value.set('month', monthNumber);
+};
+
+const increaseMonth = () => {
+	cursor.value = cursor.value.add(1, 'month');
+};
+const decreaseMonth = () => {
+	cursor.value = cursor.value.subtract(1, 'month');
+};
+
+const updateYear = (yearNumber: number) => {
+	cursor.value = cursor.value.set('year', yearNumber);
+};
+
+const handleMonthSelected = (month: number) => {
+	updateMonth(month);
+	mode.value = 'day';
+};
+
+const handleYearSelected = (year: number) => {
+	updateYear(year);
+	mode.value = 'day';
+};
+
+const handleCursorUpdate = (value: Dayjs) => {
+	cursor.value = value;
+};
+
+const lastValue = ref(props.modelValue);
+const updateModelValue = (value: BaseDatePickerProps['modelValue']) => {
+	lastValue.value = value;
+	emit('update:modelValue', value);
+};
+
+watch(
+	() => props.modelValue,
+	() => {
+		if (hash(props.modelValue) !== hash(lastValue.value)) {
+			lastValue.value = props.modelValue;
+			setCursor(props.modelValue);
+		}
+	}
+);
+
+const resetStatus = () => {
+	mode.value = 'day';
+};
+
+defineExpose({
+	resetStatus,
+});
+</script>
+
+<style lang="postcss">
+@import './index.css';
+</style>
+```
+
+## Types
+
+```ts
+import type { HTMLAttributes } from 'vue';
+
+export type BaseDatePickerProps = {
+	/**
+	 * Disables the component.
+	 */
+	disabled?: boolean;
+
+	/**
+	 * Defines the first day of the week with `0` meaning Sunday and `6` meaning Saturday.
+	 * @defaultValue `1`
+	 */
+	firstDayOfWeek?: 0 | 1 | 2 | 3 | 4 | 5 | 6;
+
+	/**
+	 * If true the date will have a format YYYY-MM-DD instead of the default ISO string.
+	 */
+	floating?: boolean;
+
+	/**
+	 * The identifier of the component.
+	 */
+	id?: HTMLAttributes['id'];
+
+	/**
+	 * Shows or hides the header of the component.
+	 */
+	header?: boolean;
+
+	/**
+	 * Maximum selectable date.
+	 */
+	max?: string;
+
+	/**
+	 * Minimum selectable date.
+	 */
+	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;
+
+	/**
+	 * Allows the selection of multiple items.
+	 */
+	multiple?: boolean;
+
+	/**
+	 * 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;
+
+	/**
+	 * Function that accepts a date string and returns a boolean. Returning `false` means the date cannot be selected.
+	 */
+	selectable?: (date: string) => boolean;
+};
+
+export type BaseDatePickerEvents = {
+	/**
+	 * Emitted whenever the selected date(s) change via calendar interaction.
+	 * Payload is `null` for cleared values, a single ISO string for single-date mode,
+	 * or an array of ISO strings for multiple/range mode.
+	 */
+	(event: 'update:modelValue', value: string | string[] | null): void;
+};
+
+/**
+ * Props exposed by day slots (keyed by date string, e.g. `"2024-03-15"`, or `"day"` as a fallback for all days).
+ */
+export type BaseDatePickerDaySlotProps = {
+	/**
+	 * Whether this day is the first in a selected range.
+	 */
+	first: boolean;
+	/**
+	 * Whether this day falls within the highlighted range.
+	 */
+	highlighted: boolean;
+	/**
+	 * The underlying date value for this day.
+	 */
+	item: any;
+	/**
+	 * The display label for this day (day number as string).
+	 */
+	label: string;
+	/**
+	 * Whether this day is the last in a selected range.
+	 */
+	last: boolean;
+	/**
+	 * Whether this day falls between the first and last of a selected range.
+	 */
+	middle: boolean;
+	/**
+	 * Whether this day is currently selected.
+	 */
+	selected: boolean;
+};
+
+export type BaseDatePickerSlots = {
+	/**
+	 * Named slot for a specific calendar day, identified by the formatted date string (e.g. `"2024-03-15"`),
+	 * or `"day"` as a fallback for all days. Rendered alongside the default day button.
+	 */
+	[key: string]: (props: BaseDatePickerDaySlotProps) => any;
+};
+```
+
+## Styles
+
+```css
+.bb-base-date-picker {
+	--cell-height: 32px;
+	--padding-y: 12px;
+	--padding-x: 16px;
+	background-color: var(--bb-panel);
+	border-radius: var(--bb-radius);
+
+	overflow: clip;
+	transition: background-color 0.2s;
+	width: 260px;
+
+	.bb-base-date-picker__header {
+		background-color: var(--bb-primary);
+		color: var(--bb-contrasting);
+		margin-left: -1px;
+		margin-right: -1px;
+		margin-top: -1px;
+		padding-bottom: var(--padding-y);
+		padding-left: var(--padding-x);
+		padding-top: var(--padding-y);
+		transition: background-color 0.2s;
+
+		&--hidden {
+			border-width: 0;
+			clip: rect(0, 0, 0, 0);
+			height: 1px;
+			margin: -1px;
+			overflow: hidden;
+			padding: 0;
+			position: absolute;
+			white-space: nowrap;
+			width: 1px;
+		}
+
+		.bb-base-date-picker__year-container {
+			height: 28px;
+			overflow: clip;
+			position: relative;
+
+			.bb-base-date-picker__year-button {
+				font-size: 18px;
+				left: 0px;
+				line-height: 28px;
+				opacity: 0.75;
+				position: absolute;
+				top: 0px;
+			}
+		}
+
+		.bb-base-date-picker__selected-day-label {
+			font-size: 20px;
+			line-height: 24px;
+			text-transform: capitalize;
+
+			.bb-base-date-picker__weekday {
+				display: inline-block;
+				margin-right: 4px;
+			}
+			.bb-base-date-picker__monthday {
+				display: inline-block;
+				margin-right: 4px;
+			}
+			.bb-base-date-picker__month-button {
+				display: inline-block;
+			}
+		}
+	}
+	&__body {
+		background-color: inherit;
+		padding-bottom: var(--padding-y);
+		padding-left: var(--padding-x);
+		padding-right: var(--padding-x);
+		padding-top: var(--padding-y);
+	}
+	&__controls {
+		align-items: center;
+		column-gap: 4px;
+		display: flex;
+		margin-bottom: 14px;
+		margin-top: 4px;
+	}
+	&__control {
+		align-items: center;
+		background-color: color-mix(
+			in srgb,
+			var(--bb-primary),
+			transparent var(--transparency)
+		);
+		border-radius: 4px;
+		color: var(--bb-text);
+		display: flex;
+		font-size: 14px;
+		height: 24px;
+		justify-content: center;
+		line-height: 20px;
+		min-width: 24px;
+		padding-bottom: 2px;
+		padding-top: 2px;
+		text-transform: capitalize;
+
+		--transparency: 100%;
+		&:hover:not(:disabled) {
+			--transparency: 85%;
+			color: var(--bb-primary);
+		}
+
+		&:active:not(:disabled) {
+			--transparency: 85%;
+		}
+		span {
+		}
+	}
+	.bb-base-date-picker__year-control {
+		margin-right: auto;
+	}
+	.bb-base-date-picker__content {
+		background-color: inherit;
+		overflow-y: clip;
+		position: relative;
+	}
+	.bb-base-date-picker__button-menu {
+		background-color: inherit;
+		height: 100%;
+		padding-bottom: var(--bb-ring-size);
+		padding-top: var(--bb-ring-size);
+		position: absolute;
+		top: 0px;
+		width: 100%;
+
+		.content {
+			column-gap: 16px;
+			display: grid;
+			height: 100%;
+			width: 100%;
+
+			.content__btn {
+				align-items: center;
+				border-radius: var(--bb-radius);
+				display: inline-flex;
+				font-size: 14px;
+				height: 32px;
+				justify-content: center;
+				line-height: 20px;
+				text-transform: capitalize;
+				transition:
+					background-color 150ms,
+					color 150ms;
+
+				&:hover {
+					background-color: color-mix(
+						in srgb,
+						var(--bb-primary) 15%,
+						transparent
+					);
+				}
+
+				&.content__btn--selected {
+					background-color: var(--bb-primary);
+					color: var(--bb-contrasting);
+				}
+			}
+		}
+	}
+
+	.bb-base-date-picker__month-selector {
+		.content {
+			grid-template-columns: 1fr 1fr;
+		}
+	}
+
+	.bb-base-date-picker__year-selector {
+		width: calc(100% + var(--padding-x));
+		.content {
+			grid-template-columns: 1fr 1fr 1fr;
+			overflow: auto;
+		}
+	}
+
+	&__days-selector {
+		min-height: calc(var(--cell-height) * 7);
+		opacity: 1;
+		position: relative;
+		transition: opacity 500ms 150ms;
+
+		&--hidden {
+			opacity: 0;
+			transition: opacity 500ms 0ms;
+		}
+	}
+	&__month {
+		display: inline-block;
+		position: absolute;
+		top: 0;
+		left: 0;
+		width: 100%;
+	}
+	&__header-container {
+		display: flex;
+	}
+	&__header-cell {
+		align-items: center;
+		color: var(--bb-text);
+		display: flex;
+		flex: 1 1 auto;
+		font-size: 0.75rem;
+		font-weight: 600;
+		height: var(--cell-height);
+		justify-content: center;
+		line-height: 1rem;
+	}
+	&__week {
+		display: flex;
+	}
+	&__date {
+		color: color-mix(in srgb, var(--bb-text) 40%, transparent);
+		flex: 1 1 0%;
+		font-size: 0.75rem;
+		height: var(--cell-height);
+		line-height: 1rem;
+		text-align: center;
+		transition-duration: 300ms;
+		transition-property: color, background-color;
+		transition-timing-function: cubic-bezier(0.4, 0, 0.2, 1);
+
+		&.bb-base-date-picker__date--first:not([class*='--last']) {
+			.bb-base-date-picker__date-button {
+			}
+		}
+		&.bb-base-date-picker__date--middle {
+			background-color: color-mix(in srgb, var(--bb-primary) 15%, transparent);
+			.bb-base-date-picker__date-button {
+			}
+		}
+		&.bb-base-date-picker__date--last:not([class*='--first']) {
+			.bb-base-date-picker__date-button {
+			}
+		}
+		&.bb-base-date-picker__date--highlighted {
+			color: var(--bb-text);
+
+			.bb-base-date-picker__date-button {
+				&:hover:not(:disabled) {
+					background-color: color-mix(
+						in srgb,
+						var(--bb-primary) 15%,
+						transparent
+					);
+				}
+			}
+		}
+		&.bb-base-date-picker__date--disabled {
+			.bb-base-date-picker__date-button {
+				cursor: not-allowed;
+				opacity: 0.5;
+			}
+		}
+		&.bb-base-date-picker__date--today {
+			.bb-base-date-picker__date-button {
+				border: 1px solid color-mix(in srgb, var(--bb-primary) 40%, transparent);
+				color: var(--bb-primary);
+			}
+			&.bb-base-date-picker__date--middle {
+				.bb-base-date-picker__date-button {
+					background-color: color-mix(
+						in srgb,
+						var(--bb-primary) 40%,
+						transparent
+					);
+				}
+			}
+		}
+		&.bb-base-date-picker__date--current {
+			.bb-base-date-picker__date-button:not(:disabled) {
+				background-color: color-mix(
+					in srgb,
+					var(--bb-primary) 55%,
+					transparent
+				);
+				color: var(--bb-contrasting);
+			}
+		}
+		&.bb-base-date-picker__date--selected {
+			.bb-base-date-picker__date-button {
+				background-color: var(--bb-primary) !important;
+				color: var(--bb-contrasting);
+				&:hover:not(:disabled) {
+					background-color: var(--bb-primary);
+				}
+			}
+		}
+
+		&-button {
+			border-radius: var(--bb-radius);
+			box-shadow: 0px 0px 0px 0px var(--bb-ring);
+			display: inline-block;
+			height: 100%;
+			outline: 2px solid transparent;
+			outline-offset: 2px;
+			transition:
+				box-shadow 200ms,
+				background-color 200ms,
+				color 200ms;
+			width: var(--cell-height);
+
+			&:focus-visible {
+				box-shadow: 0px 0px 0px var(--bb-ring-size) var(--bb-ring);
+			}
+
+			&:hover:not(:disabled) {
+				background-color: color-mix(in srgb, var(--bb-primary) 5%, transparent);
+			}
+		}
+	}
+}
+```