bitboss-ui 2.1.135 → 3.0.0-alpha.4

package/dist/ai/source/BbDatePickerInput.md

@@ -0,0 +1,525 @@
+# BbDatePickerInput — Implementation Source
+
+> Full implementation for deep dives. For everyday usage read the typed contract: [../BbDatePickerInput.md](../BbDatePickerInput.md).
+
+## Template & Script
+
+```vue
+<template>
+	<BaseInputContainer
+		:id="id"
+		class="bb-date-picker-input"
+		:compact="compact"
+		:description="description"
+		:direction="direction"
+		:errors="errors"
+		:has-errors="hasErrors"
+		:has-value="hasValue"
+		:has-warning="hasWarning"
+		:hide-label="hideLabel"
+		:hint="hint"
+		:label="label"
+		:label-mode="resolvedLabelMode"
+		:label-position="labelPosition"
+		:model-value="modelValue"
+		:name="name"
+		:reverse="reverse"
+		:show-hint="showHint"
+		:warnings="warnings"
+	>
+		<template #label="data"><slot name="label" v-bind="data"></slot></template>
+		<template #input="{ id, hasErrors, hasWarning, ariaDescribedby }">
+			<BaseDatePickerInput
+				:id="id"
+				:adaptive="adaptive"
+				:ampm="ampm"
+				:append:icon="props['append:icon']"
+				:aria-describedby="ariaDescribedby"
+				:autocomplete="autocomplete"
+				:autofocus="autofocus"
+				:clearable="clearable"
+				:compact="compact"
+				:datetime="datetime"
+				:disable-calendar="disableCalendar"
+				:disable-writing="disableWriting"
+				:disabled="disabled"
+				:first-day-of-week="firstDayOfWeek"
+				:floating="floating"
+				:has-errors="hasErrors"
+				:has-warning="hasWarning"
+				:loading="loading"
+				:max="max"
+				:min="min"
+				:model-value="modelValue"
+				:name="name"
+				:off-canvas-props="offCanvasProps"
+				:placeholder="placeholder"
+				:prepend:icon="props['prepend:icon']"
+				:range="range"
+				:readonly="readonly"
+				:required="required"
+				:seconds="seconds"
+				:selectable="selectable"
+				:step="step"
+				:time="time"
+				:transition-duration="transitionDuration"
+				:utc="utc"
+				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>
+				<template #day="slotProps"
+					><slot name="day" v-bind="slotProps"></slot
+				></template>
+				<template #append:day="slotProps">
+					<slot name="append:day" v-bind="slotProps"></slot>
+				</template>
+			</BaseDatePickerInput>
+		</template>
+	</BaseInputContainer>
+</template>
+
+<script setup lang="ts">
+import BaseDatePickerInput from '../BbBaseDatePickerInput/BbBaseDatePickerInput.vue';
+import BaseInputContainer from '../BbBaseInputContainer/BbBaseInputContainer.vue';
+import type { BaseDatePickerInputEvents } from '../BbBaseDatePickerInput/types';
+import { ref, computed, onBeforeUnmount, onDeactivated } from 'vue';
+import { config } from 'virtual:bitboss-ui/config';
+import { removedPropsFor } from '@/deprecation/removedProps';
+import { warnRemovedAttrs } from '@/utilities/functions/warnRemovedAttrs';
+import { isNotEmpty } from '@/utilities/functions/isNotEmpty';
+import type {
+	BbDatePickerInputProps,
+	BbDatePickerInputSlots,
+	DatePickerInputError,
+} from './types';
+
+const props = withDefaults(defineProps<BbDatePickerInputProps>(), {
+	// `undefined` (declared, not omitted) keeps `adaptive` three-state: it disables
+	// Vue's absent→`false` Boolean cast so the base input's
+	// `props.adaptive ?? config.adaptive` can reach the config default, while
+	// keeping the Boolean type so the valueless `adaptive` shorthand still
+	// resolves to `true`.
+	adaptive: undefined,
+});
+const emit = defineEmits<BaseDatePickerInputEvents>();
+defineSlots<BbDatePickerInputSlots>();
+
+if (process.env.NODE_ENV !== 'production')
+	warnRemovedAttrs('BbDatePickerInput', removedPropsFor('BbDatePickerInput'));
+
+const active = ref(false);
+const showHint = computed(() => props.persistentHint || active.value);
+const hasValue = computed(() => isNotEmpty(props.modelValue));
+const resolvedLabelMode = computed(
+	() => props.labelMode ?? config.defaultInputLabelMode
+);
+const resetActiveState = () => {
+	active.value = false;
+};
+
+onDeactivated(resetActiveState);
+onBeforeUnmount(resetActiveState);
+
+/**
+ * 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: () => {
+		resetActiveState();
+		emit('inactive');
+	},
+	'onUpdate:modelValue': (value: BbDatePickerInputProps['modelValue']) =>
+		emit('update:modelValue', value),
+	'onUpdate:time': (value: string | string[] | null) =>
+		emit('update:time', value),
+};
+</script>
+
+<style lang="postcss">
+@import './index.css';
+</style>
+```
+
+## Types
+
+```ts
+import type { HTMLAttributes, InputHTMLAttributes } from 'vue';
+import type { InputDirection } from '@/types/InputDirection';
+import type { Dayjs } from 'dayjs';
+import type { IconType } from '@/types/Icon';
+import type {
+	BaseDatePickerInputEvents,
+	DatePickerInputError,
+} from '../BbBaseDatePickerInput/types';
+import type { BbOffCanvasProps } from '../BbOffCanvas/types';
+
+export type { DatePickerInputError };
+
+export type BbDatePickerInputProps = {
+	/**
+	 * 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`.
+	 * @defaultValue `config.adaptive` (`true`)
+	 */
+	adaptive?: boolean;
+
+	/**
+	 * 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`).
+	 */
+	description?: string;
+
+	/**
+	 * Extra props forwarded to the `BbOffCanvas` sheet when `adaptive` is active on
+	 * mobile (e.g. `title`, `size`, `persistent`).
+	 */
+	offCanvasProps?: Partial<BbOffCanvasProps>;
+
+	/**
+	 * Disables typing into the input.
+	 * Use `'mobile'` to disable typing only on mobile, `'desktop'` to disable typing only on desktop.
+	 *
+	 * @defaultValue `false`
+	 */
+	disableWriting?: boolean | 'mobile' | 'desktop';
+
+	/**
+	 * Name of the icon to be added at the end of the input.
+	 */
+
+	'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?: InputDirection;
+
+	/**
+	 * Disables the component.
+	 */
+	disabled?: boolean;
+
+	/**
+	 * 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`, so the reason the field is invalid is re-read whenever
+	 * the control regains focus.
+	 */
+	errors?: string | string[];
+
+	/**
+	 * Defines the first day of the week with `0` meaning Sunday and `6` meaning Saturday.
+	 */
+	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;
+
+	/**
+	 * Define if the component should be in an error state.
+	 * It usually attaches a CSS class for styling purposes.
+	 */
+	hasErrors?: boolean;
+
+	/**
+	 * 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 referenced from the control's
+	 * `aria-describedby`, after any errors and before the description/hint.
+	 */
+	warnings?: string | string[];
+
+	/**
+	 * Define if the component should be in a warning state.
+	 * Same chrome as errors with `--bb-warn`; errors take priority.
+	 */
+	hasWarning?: boolean;
+
+	/**
+	 * 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 mobile only.
+	 */
+	disableCalendar?: boolean | 'mobile' | 'desktop';
+
+	/**
+	 * 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';
+
+	/**
+	 * Label rendering mode.
+	 */
+	labelMode?: 'outside' | 'floating' | 'inside';
+
+	/**
+	 * Sets the component in a loading state, usually triggering some visual styles.
+	 */
+	loading?: boolean;
+
+	/**
+	 * 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.
+	 */
+	max?: string;
+
+	/**
+	 * 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.
+	 */
+	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.
+	 */
+
+	'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;
+
+	/**
+	 * 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`; with `floating` the date string stays plain and
+	 * the time travels only through `v-model:time`.
+	 */
+	datetime?: boolean;
+
+	/**
+	 * 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.
+	 */
+	ampm?: boolean;
+
+	/**
+	 * 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.
+	 */
+	seconds?: boolean;
+
+	/**
+	 * 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 column row highlights for it.
+	 * @defaultValue `1`
+	 */
+	step?: number;
+
+	/**
+	 * 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 it rewrites the model's time part.
+	 * Requires `datetime`.
+	 */
+	time?: string | string[] | null;
+
+	/**
+	 * Transition duration, in milliseconds, for the popover appearance.
+	 */
+	transitionDuration?: number;
+
+	/**
+	 * 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. Fields always display local time — UTC is a
+	 * backend concern. Ignored when `floating` is set (a plain date has no zone).
+	 */
+	utc?: boolean;
+};
+
+/** Re-export for consumers importing events type from BbDatePickerInput. */
+export type { BaseDatePickerInputEvents as BbDatePickerInputEvents };
+
+/** 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;
+	/** Whether the input is in a warning state (suppressed when errors win). */
+	hasWarning: boolean;
+};
+
+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;
+	/**
+	 * Replaces the day button label inside each calendar day.
+	 */
+	day?: (props: {
+		first: boolean;
+		highlighted: boolean;
+		item: Dayjs;
+		label: string;
+		last: boolean;
+		middle: boolean;
+		selected: boolean;
+	}) => any;
+	/**
+	 * Appends content below each calendar day.
+	 */
+	'append:day'?: (props: {
+		first: boolean;
+		highlighted: boolean;
+		item: Dayjs;
+		label: string;
+		last: boolean;
+		middle: boolean;
+		selected: boolean;
+	}) => any;
+};
+```
+
+## Styles
+
+```css
+.bb-date-picker-input {
+	/* Fill the grid control column (which sizes children to content). */
+	.bb-base-date-picker-input {
+		width: 100%;
+	}
+
+	&.bb-base-input-container--floating-label:not(:focus-within) {
+		.bb-base-date-picker-input__placeholder {
+			opacity: 0;
+		}
+	}
+}
+```