bitboss-ui 2.1.113 → 2.1.115

package/dist/ai/BaseCheckboxGroup.md

@@ -0,0 +1,597 @@
+# BaseCheckboxGroup
+
+## Template & Script
+
+```vue
+<template>
+	<OptionsContainer
+		ref="container"
+		class="bb-base-checkbox-group"
+		:direction="direction"
+		:has-errors="hasErrors"
+		:hide-label="hideLabel"
+		:loading="!!loading"
+		:loading-text="loadingText"
+		:no-data-text="noDataText"
+		:options="options"
+	>
+		<template #prepend><slot name="prepend"></slot></template>
+		<template #loading><slot name="loading"></slot></template>
+		<template #no-data><slot name="no-data"></slot></template>
+		<template #label="data"><slot name="label" v-bind="data"></slot></template>
+		<template #option:prepend="data"
+			><slot name="option:prepend" v-bind="data"></slot
+		></template>
+		<template #input="{ option, index }">
+			<BaseCheckbox
+				:id="getId(option)"
+				:aria-describedby="ariaDescribedby"
+				:autofocus="autofocus && !index"
+				:checked="option.selected"
+				:color="color"
+				:disabled="option.disabled"
+				:has-errors="hasErrors"
+				:name="name"
+				:readonly="readonly"
+				:true-value="option.value"
+				v-bind="eventListeners"
+				@change="(event: Event) => onChange(event, option)"
+				><template #icon="data"
+					><slot
+						:item="option.item"
+						name="icon"
+						:text="option.text"
+						v-bind="data" /></template
+			></BaseCheckbox>
+		</template>
+		<template #option:append="data"
+			><slot name="option:append" v-bind="data"></slot
+		></template>
+		<template #append><slot name="append"></slot></template>
+	</OptionsContainer>
+</template>
+
+<script setup lang="ts" generic="T = any">
+import { computed, ref, toRef } from 'vue';
+import type { Option as BaseOption } from '@/types/Option';
+import BaseCheckbox from '../BaseCheckbox/BaseCheckbox.vue';
+import type { ComponentPublicInstance } from 'vue';
+import type { Option } from '@/types/Option';
+import type {
+	BaseCheckboxGroupEvents,
+	BaseCheckboxGroupProps,
+	BaseCheckboxGroupSlots,
+} from './types';
+import OptionsContainer from '../OptionsContainer/OptionsContainer.vue';
+import { useItemsGetter } from '@/composables/useItemsGetter';
+import { useIndexById } from '@/composables/useIndexById';
+import { useBaseOptions } from '@/composables/useBaseOptions';
+import { useCoherence } from '@/composables/useCoherence';
+import { hash } from '@/utilities/functions/hash';
+import { useHashedWatcher } from '@/composables/useHashedWatcher';
+import { usePrefill } from '@/composables/usePrefill';
+import { useLogger } from '@/composables/useLogger';
+
+const props = withDefaults(defineProps<BaseCheckboxGroupProps<T>>(), {
+	depsDebounceTime: 0,
+	direction: 'horizontal',
+	items: () => [],
+	modelValueDebounceTime: 0,
+	max: Infinity,
+	multiple: true,
+});
+
+const emit = defineEmits<BaseCheckboxGroupEvents>();
+const logger = useLogger();
+
+defineSlots<BaseCheckboxGroupSlots<T>>();
+
+if (props.multiple && !Array.isArray(props.modelValue)) {
+	logger.throw(
+		'BaseCheckboxGroup: multiple is set to "true" but modelValue is not an array.'
+	);
+}
+
+const container = ref<ComponentPublicInstance>();
+const active = ref(false);
+
+const {
+	getter,
+	items: internalItems,
+	loading,
+} = useItemsGetter({
+	items: toRef(props, 'items'),
+	debounce: 0,
+});
+
+const alignToCoherenceSettings = () => {
+	if (props.enforceCoherence && !coherent.value) {
+		emit('update:modelValue', coherentValue.value);
+	}
+};
+
+const { hasPrefilled } = usePrefill({
+	trigger: true,
+	currentValue: props.modelValue,
+	multiple: props.multiple,
+	fn: async (isPrefill) => {
+		await getter(isPrefill, props.modelValue);
+		alignToCoherenceSettings();
+	},
+});
+
+const { data: modelValueIndexedByHash } = useIndexById({
+	items: computed(() => [].concat(props.modelValue)),
+});
+
+const { options } = useBaseOptions({
+	disabled: toRef(props, 'disabled'),
+	items: internalItems,
+	itemText: props.itemText,
+	itemValue: props.itemValue,
+	max: props.max,
+	selectable: true,
+	selectedIndexedByHash: modelValueIndexedByHash,
+});
+
+const onOptionSelected = async (option: BaseOption) => {
+	if (props.multiple) {
+		emit('update:modelValue', [].concat(props.modelValue).concat(option.value));
+		return;
+	}
+	emit('update:modelValue', option.value);
+};
+
+const onOptionUnselected = async (option: BaseOption) => {
+	if (!props.multiple) {
+		emit('update:modelValue', null);
+		return;
+	}
+	const copy = { ...modelValueIndexedByHash.value };
+	delete copy[option.valueHash];
+	emit('update:modelValue', Object.values(copy));
+};
+
+const { data: optionsIndexedByHash } = useIndexById({
+	items: options,
+	key: 'valueHash',
+});
+
+const { coherent, coherentValue } = useCoherence({
+	modelValue: toRef(props, 'modelValue'),
+
+	multiple: props.multiple,
+	iteratee: (item) => !!optionsIndexedByHash.value[hash(item)],
+});
+
+/**
+ * If multiple watchers are running we don't want to run the coherence watcher
+ * multiple times we only run it the last time
+ */
+let runningWatcher = 0;
+useHashedWatcher(
+	() => props.modelValue,
+	async () => {
+		runningWatcher++;
+		if (!coherent.value) {
+			await getter(false, props.modelValue);
+			alignToCoherenceSettings();
+		}
+		runningWatcher--;
+	},
+	{
+		debounce: props.modelValueDebounceTime,
+	}
+);
+useHashedWatcher(
+	() => [props.dependencies, props.items],
+	async () => {
+		if (!hasPrefilled.value) {
+			return;
+		}
+		runningWatcher++;
+		await getter(false, props.modelValue);
+		if (runningWatcher === 1) {
+			alignToCoherenceSettings();
+		}
+		runningWatcher--;
+	},
+	{
+		debounce: props.depsDebounceTime,
+	}
+);
+
+const getId = (option: Option) => {
+	if (!props.id) return undefined;
+	return [props.id, option.valueHash].filter(Boolean).join('-');
+};
+
+const onChange = (event: Event, option: Option) => {
+	emit('change', event);
+	if (!option.selected) {
+		onOptionSelected(option);
+	} else {
+		onOptionUnselected(option);
+	}
+};
+
+const onFocus = (event: FocusEvent) => {
+	emit('focus', event);
+	if (!active.value) {
+		document.addEventListener('focusin', onDocumentFocus, { passive: true });
+		document.addEventListener('click', onDocumentClick, { passive: true });
+		active.value = true;
+	}
+};
+
+const eventListeners = {
+	onBlur: (event: FocusEvent) => emit('blur', event),
+	onClick: (event: MouseEvent) => emit('click', event),
+	onFocus,
+	onInput: (event: Event) => emit('input', event),
+	onKeydown: (event: KeyboardEvent) => emit('keydown', event),
+	onMousedown: (event: MouseEvent) => emit('mousedown', event),
+	onMouseup: (event: MouseEvent) => emit('mouseup', event),
+};
+
+const handleInactive = (): void => {
+	emit('inactive');
+	active.value = false;
+	document.removeEventListener('focusin', onDocumentFocus);
+	document.removeEventListener('click', onDocumentClick);
+};
+
+const onDocumentFocus = (event: FocusEvent) => {
+	if (event.target instanceof HTMLElement) {
+		if (!container.value?.$el.contains(event.target)) {
+			handleInactive();
+		}
+	}
+};
+
+const onDocumentClick = (event: MouseEvent) => {
+	if (event.target instanceof HTMLElement) {
+		if (!container.value?.$el.contains(event.target)) {
+			handleInactive();
+		}
+	}
+};
+</script>
+
+<style lang="postcss">
+@import './index.css';
+</style>
+```
+
+## Types
+
+```ts
+import type {
+	HTMLAttributes,
+	InputHTMLAttributes,
+	MaybeRefOrGetter,
+} from 'vue';
+import type { BaseCheckboxIconSlotProps } from '../BaseCheckbox/types';
+
+export type BaseCheckboxGroupProps<T = any> = {
+	/**
+	 * ID of the element that describes the entire checkbox group for assistive
+	 * technologies. Forwarded to each generated input as `aria-describedby`.
+	 */
+	ariaDescribedby?: InputHTMLAttributes['aria-describedby'];
+	/**
+	 * Automatically focuses the first checkbox on mount when true.
+	 * Applied only to the first option.
+	 * @defaultValue `false`
+	 */
+	autofocus?: InputHTMLAttributes['autofocus'];
+	/**
+	 * Visual color of the checkboxes.
+	 * - If a valid CSS color (HEX/RGB/HSL/etc.), it is applied via the `--color`
+	 *   CSS variable.
+	 * - Otherwise, a BEM modifier class `bb-base-checkbox--{color}` is added for
+	 *   theme-based styling.
+	 */
+	color?: string;
+	/**
+	 * List of reactive values which, when changed, trigger items re-fetching.
+	 * Useful to reload options based on external inputs.
+	 * @defaultValue `[]`
+	 */
+	dependencies?: any[];
+	/**
+	 * Debounce delay (ms) applied when reacting to `dependencies` changes.
+	 * @defaultValue `0`
+	 */
+	depsDebounceTime?: number;
+	/**
+	 * Direction of the group layout.
+	 * - `horizontal`: options flow in rows
+	 * - `vertical`: options stack in a column
+	 * @defaultValue `'horizontal'`
+	 */
+	direction?: 'horizontal' | 'vertical';
+	/**
+	 * Disables interaction for the whole group.
+	 * @defaultValue `false`
+	 */
+	disabled?: boolean;
+	/**
+	 * Enforces that `modelValue` contains only values present in `items`.
+	 * Incoherent values are removed and `update:modelValue` is emitted with a
+	 * coherent array. Please check out {@link https://ui-components-docs.vercel.app/it/guides/coherence | the docs} for more information.
+	 * @defaultValue `false`
+	 */
+	enforceCoherence?: boolean;
+	/**
+	 * Puts the component into an error state adds the error styling class.
+	 * @defaultValue `false`
+	 */
+	hasErrors?: boolean;
+	/**
+	 * Visually hides the label while keeping it accessible to screen readers.
+	 * @defaultValue `false`
+	 */
+	hideLabel?: boolean;
+	/**
+	 * Identifier of the group. Used to derive per-option IDs
+	 * for accessible labeling.
+	 */
+	id?: HTMLAttributes['id'];
+	/**
+	 * Items provider. Can be:
+	 * - An array of items
+	 * - A sync/async function `(prefill, modelValue) => items`
+	 *
+	 * When a function is provided, it is invoked on prefill and when dependencies
+	 * change to load options dynamically.
+	 * @defaultValue `[]`
+	 */
+	items:
+		| T[]
+		| ((prefill: boolean, modelValue?: any) => Promise<T[]>)
+		| ((prefill: boolean, modelValue?: any) => T[]);
+	/**
+	 * Defines how to derive the display text from an item. Accepts a nested key path
+	 * into the item or a function `(item) => string`.
+	 * @example `'address.city.label'`
+	 * @example `(item) => item.address.city.label`
+	 * @defaultValue `JSON.stringify(item)`
+	 */
+	itemText?: T extends object
+		? string | ((item: T) => string)
+		: (item: T) => string;
+	/**
+	 * Defines how to derive the value from an item. Accepts a nested key path into the
+	 * item or a function `(item) => any`.
+	 * @example `'address.city.value'`
+	 * @example `(item) => item.address.city.value`
+	 * @defaultValue `JSON.stringify(item)`
+	 */
+	itemValue?: T extends object
+		? string | ((item: T) => string)
+		: (item: T) => any;
+	/**
+	 * Text displayed while items are loading.
+	 * @defaultValue `'Loading...'`
+	 */
+	loadingText?: string;
+	/**
+	 * Maximum number of selectable items.
+	 * @defaultValue `Infinity`
+	 */
+	max?: number;
+	/**
+	 * Selected values for the group. Used with `v-model`.
+	 * Single value when `multiple` is false, array when `multiple` is true.
+	 */
+	modelValue: any;
+	/**
+	 * Enables multi-selection behavior.
+	 * When `true`, `modelValue` must be an array and emitted updates are arrays.
+	 * When `false`, `modelValue` must be a single value (or `null`) and emitted
+	 * updates are single values.
+	 * @defaultValue `true`
+	 */
+	multiple?: boolean;
+	/**
+	 * Debounce delay (ms) applied when reacting to `modelValue` changes.
+	 * @defaultValue `0`
+	 */
+	modelValueDebounceTime?: number;
+	/**
+	 * Name attribute applied to each input for form submission.
+	 */
+	name?: InputHTMLAttributes['name'];
+	/**
+	 * Text displayed when there are no items to show.
+	 * @defaultValue `'No data to display'`
+	 */
+	noDataText?: MaybeRefOrGetter<string>;
+	/**
+	 * Makes all checkboxes read-only. Since checkboxes do not support native
+	 * `readonly`, inputs are disabled while styled as read-only.
+	 * @defaultValue `false`
+	 */
+	readonly?: boolean;
+};
+
+export type BaseCheckboxGroupEvents = {
+	/**
+	 * Emitted when one of the generated checkbox inputs loses focus.
+	 * Forwards the original DOM `FocusEvent`.
+	 */
+	(e: 'blur', event: FocusEvent): void;
+	/**
+	 * Emitted when a checkbox option is toggled.
+	 * Forwards the original DOM `Event` from the checkbox input.
+	 */
+	(e: 'change', event: Event): void;
+	/**
+	 * Emitted when one of the generated checkbox inputs is clicked.
+	 * Forwards the original DOM `MouseEvent`.
+	 */
+	(e: 'click', event: MouseEvent): void;
+	/**
+	 * Emitted when one of the generated checkbox inputs receives focus.
+	 * Forwards the original DOM `FocusEvent`.
+	 */
+	(e: 'focus', event: FocusEvent): void;
+	/**
+	 * Emitted when focus/click moves outside the group after it was active.
+	 * Useful for validation-on-blur flows at group level.
+	 */
+	(e: 'inactive'): void;
+	/**
+	 * Emitted on native input events from generated checkbox inputs.
+	 * Forwards the original DOM `Event`.
+	 */
+	(e: 'input', event: Event): void;
+	/**
+	 * Emitted for keyboard interaction on generated checkbox inputs.
+	 * Forwards the original DOM `KeyboardEvent`.
+	 */
+	(e: 'keydown', event: KeyboardEvent): void;
+	/**
+	 * Emitted when a pointing device button is pressed over a checkbox input.
+	 * Forwards the original DOM `MouseEvent`.
+	 */
+	(e: 'mousedown', event: MouseEvent): void;
+	/**
+	 * Emitted when a pointing device button is released over a checkbox input.
+	 * Forwards the original DOM `MouseEvent`.
+	 */
+	(e: 'mouseup', event: MouseEvent): void;
+	/**
+	 * Emitted with the coherent next selection array whenever selection changes.
+	 */
+	(e: 'update:modelValue', value: any): void;
+};
+
+/**
+ * Marker type for slots that do not expose scoped props.
+ */
+export type BaseCheckboxGroupEmptySlotProps = Record<string, never>;
+
+/**
+ * Props exposed by the `icon` slot for each option.
+ */
+export type BaseCheckboxGroupIconSlotProps<T> = BaseCheckboxIconSlotProps & {
+	/**
+	 * Original source item for this option.
+	 */
+	item: T;
+	/**
+	 * Resolved display text for this option.
+	 */
+	text: string;
+};
+
+/**
+ * Props exposed by the `label` slot for each option.
+ */
+export type BaseCheckboxGroupLabelSlotProps<T> = {
+	/**
+	 * Original source item for this option.
+	 */
+	item: T;
+	/**
+	 * Resolved display text for this option.
+	 */
+	text: string;
+	/**
+	 * Whether this option is currently selected.
+	 */
+	checked: boolean;
+};
+
+/**
+ * Props exposed by option affix slots (`option:prepend` / `option:append`).
+ */
+export type BaseCheckboxGroupOptionAffixSlotProps<T> = {
+	/**
+	 * Whether this option is currently selected.
+	 */
+	checked: boolean;
+	/**
+	 * Whether this option is currently disabled.
+	 */
+	disabled: boolean;
+	/**
+	 * Generated id for the underlying checkbox input, when available.
+	 */
+	id?: string;
+	/**
+	 * Original source item for this option.
+	 */
+	item: T;
+	/**
+	 * Resolved display text for this option.
+	 */
+	text: string;
+};
+
+export type BaseCheckboxGroupSlots<T> = {
+	/**
+	 * Content rendered after the last option, inside the options container.
+	 */
+	append?: (props: BaseCheckboxGroupEmptySlotProps) => any;
+	/**
+	 * Replaces the default checkmark icon for each checkbox option. Receives all `BaseCheckbox`
+	 * slot attributes plus the source item and its display text.
+	 */
+	icon?: (props: BaseCheckboxGroupIconSlotProps<T>) => any;
+	/**
+	 * Replaces the default label text for each option.
+	 */
+	label?: (props: BaseCheckboxGroupLabelSlotProps<T>) => any;
+	/**
+	 * Content shown while options are loading (replaces the default loading text).
+	 */
+	loading?: (props: BaseCheckboxGroupEmptySlotProps) => any;
+	/**
+	 * Content shown when no options are available (replaces the default "no data" text).
+	 */
+	'no-data'?: (props: BaseCheckboxGroupEmptySlotProps) => any;
+	/**
+	 * Content rendered after each option's checkbox and label.
+	 */
+	'option:append'?: (props: BaseCheckboxGroupOptionAffixSlotProps<T>) => any;
+	/**
+	 * Content rendered before each option's checkbox.
+	 */
+	'option:prepend'?: (props: BaseCheckboxGroupOptionAffixSlotProps<T>) => any;
+	/**
+	 * Content rendered before the first option, inside the options container.
+	 */
+	prepend?: (props: BaseCheckboxGroupEmptySlotProps) => any;
+};
+```
+
+## Styles
+
+```css
+.bb-base-checkbox-group {
+	&.bb-cr-container {
+		&--horizontal {
+			.bb-cr-container-option {
+			}
+		}
+		&--vertical {
+			.bb-cr-container-option {
+			}
+		}
+
+		&__container {
+		}
+		&-option {
+			> .bb-base-checkbox {
+			}
+			&__text {
+				&--hidden {
+				}
+			}
+		}
+	}
+}
+```