bitboss-ui 2.1.113 → 2.1.115

package/dist/ai/BaseRadioGroup.md

@@ -0,0 +1,535 @@
+# BaseRadioGroup
+
+## Template & Script
+
+```vue
+<template>
+	<OptionsContainer
+		ref="container"
+		class="bb-base-radio-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 }">
+			<BaseRadio
+				:id="getId(option)"
+				:aria-describedby="ariaDescribedby"
+				:autofocus="autofocus && !index"
+				:checked="option.selected"
+				:color="color"
+				:disabled="option.disabled"
+				:has-errors="hasErrors"
+				:model-value="props.modelValue"
+				:name="name"
+				:readonly="readonly"
+				:required="required"
+				:value="option.value"
+				v-bind="eventListeners"
+			>
+				<template v-if="$slots.icon" #icon="data">
+					<slot
+						:item="option.item"
+						name="icon"
+						:text="option.text"
+						v-bind="data"
+					/>
+				</template>
+			</BaseRadio>
+		</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 BaseRadio from '../BaseRadio/BaseRadio.vue';
+import OptionsContainer from '../OptionsContainer/OptionsContainer.vue';
+import type { Option } from '@/types/Option';
+import type {
+	BaseRadioGroupProps,
+	BaseRadioGroupEvents,
+	BaseRadioGroupSlots,
+} from './types';
+import { useItemsGetter } from '@/composables/useItemsGetter';
+import { usePrefill } from '@/composables/usePrefill';
+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';
+
+const props = withDefaults(defineProps<BaseRadioGroupProps<T>>(), {
+	depsDebounceTime: 0,
+	direction: 'horizontal',
+	items: () => [],
+	modelValueDebounceTime: 0,
+});
+
+const emit = defineEmits<BaseRadioGroupEvents>();
+
+defineSlots<BaseRadioGroupSlots<T>>();
+
+const container = ref<any>();
+const active = ref(false);
+
+const {
+	getter,
+	items: internalItems,
+	loading,
+} = useItemsGetter({
+	items: toRef(props, 'items'),
+});
+
+const alignToCoherenceSettings = () => {
+	if (props.enforceCoherence && !coherent.value) {
+		emit('update:modelValue', null);
+	}
+};
+
+const { hasPrefilled } = usePrefill({
+	trigger: true,
+	currentValue: props.modelValue,
+	multiple: false,
+	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: Infinity,
+	selectable: true,
+	selectedIndexedByHash: modelValueIndexedByHash,
+});
+
+const { data: optionsIndexedByHash } = useIndexById({
+	items: options,
+	key: 'valueHash',
+});
+
+const { coherent } = useCoherence({
+	modelValue: toRef(props, 'modelValue'),
+
+	multiple: false,
+	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 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),
+	onChange: (event: Event) => emit('change', 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),
+	'onUpdate:modelValue': (value: any) => emit('update:modelValue', value),
+};
+
+const onDocumentFocus = (event: FocusEvent) => {
+	if (event.target instanceof HTMLElement) {
+		if (!container.value?.$el.contains(event.target)) {
+			emit('inactive');
+			active.value = false;
+			document.removeEventListener('focusin', onDocumentFocus);
+			document.removeEventListener('click', onDocumentClick);
+		}
+	}
+};
+
+const onDocumentClick = (event: MouseEvent) => {
+	if (event.target instanceof HTMLElement) {
+		if (!container.value?.$el.contains(event.target)) {
+			emit('inactive');
+			active.value = false;
+			document.removeEventListener('focusin', onDocumentFocus);
+			document.removeEventListener('click', onDocumentClick);
+		}
+	}
+};
+</script>
+
+<style lang="postcss">
+@import './index.css';
+</style>
+```
+
+## Types
+
+```ts
+import type { InputHTMLAttributes, HTMLAttributes } from 'vue';
+import type { NestedKeyOf } from '@/types/NestedKeyOf';
+import type { BaseRadioIconSlotProps } from '../BaseRadio/types';
+
+/**
+ * Props for the radio group component that renders a list of radio options from items.
+ */
+export type BaseRadioGroupProps<T = any> = {
+	/**
+	 * Id(s) of elements describing this group for assistive technologies.
+	 */
+	ariaDescribedby?: InputHTMLAttributes['aria-describedby'];
+
+	/**
+	 * Focus the first radio on mount.
+	 */
+	autofocus?: InputHTMLAttributes['autofocus'];
+
+	/**
+	 * Define a color for the component.
+	 *
+	 * Either a custom color or a coded color in common HEX, RGB, etc... format.
+	 */
+	color?: string;
+
+	/**
+	 * Additional dependencies that trigger item reloading when changed.
+	 */
+	dependencies?: any[];
+
+	/**
+	 * Debounce delay (ms) for dependency-triggered reloads.
+	 * @defaultValue `0`
+	 */
+	depsDebounceTime?: number;
+
+	/**
+	 * Direction of the layout of the inputs inside the fieldset.
+	 * @defaultValue `'horizontal'`
+	 */
+	direction?: 'horizontal' | 'vertical';
+
+	/**
+	 * Disable all radios in the group.
+	 */
+	disabled?: boolean;
+
+	/**
+	 * Reset modelValue to `null` if it no longer matches available items (enforces coherence).
+	 */
+	enforceCoherence?: boolean;
+
+	/**
+	 * Apply error styling to the group.
+	 */
+	hasErrors?: boolean;
+
+	/**
+	 * Hide the visual label while keeping it accessible.
+	 */
+	hideLabel?: boolean;
+
+	/**
+	 * Explicit id for the fieldset. Used to generate ids for individual radios.
+	 */
+	id?: HTMLAttributes['id'];
+
+	/**
+	 * Array of items or function to load them asynchronously.
+	 * @defaultValue `[]`
+	 */
+	items:
+		| T[]
+		| ((prefill: boolean, modelValue?: any[]) => Promise<T[]>)
+		| ((prefill: boolean, modelValue?: any[]) => T[]);
+
+	/**
+	 * Path to item property for display text or function to extract it.
+	 */
+	itemText?: T extends object
+		? NestedKeyOf<T> | ((item: T) => string)
+		: ((item: T) => string) | undefined;
+
+	/**
+	 * Path to item property for value or function to extract it.
+	 */
+	itemValue?: T extends object
+		? NestedKeyOf<T> | ((item: T) => string)
+		: ((item: T) => any) | undefined;
+
+	/**
+	 * Message shown while items are loading.
+	 */
+	loadingText?: string;
+
+	/**
+	 * Used by v-model. Can be any serializable type.
+	 */
+	modelValue: any;
+
+	/**
+	 * Debounce delay (ms) for modelValue change handling.
+	 * @defaultValue `0`
+	 */
+	modelValueDebounceTime?: number;
+
+	/**
+	 * Shared name for all radios in the group (required for grouping).
+	 */
+	name: InputHTMLAttributes['name'];
+
+	/**
+	 * Message displayed when no items are available.
+	 */
+	noDataText?: string;
+
+	/**
+	 * Make all radios read-only.
+	 */
+	readonly?: boolean;
+
+	/**
+	 * Mark at least one radio as required.
+	 */
+	required?: boolean;
+};
+
+export type BaseRadioGroupEvents = {
+	/**
+	 * Emitted when one of the generated radio inputs loses focus.
+	 * Forwards the original DOM `FocusEvent`.
+	 */
+	(e: 'blur', event: FocusEvent): void;
+	/**
+	 * Emitted when a radio option is selected.
+	 * Forwards the original DOM `Event` from the radio input.
+	 */
+	(e: 'change', event: Event): void;
+	/**
+	 * Emitted when one of the generated radio inputs is clicked.
+	 * Forwards the original DOM `MouseEvent`.
+	 */
+	(e: 'click', event: MouseEvent): void;
+	/**
+	 * Emitted when one of the generated radio 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 radio inputs.
+	 * Forwards the original DOM `Event`.
+	 */
+	(e: 'input', event: Event): void;
+	/**
+	 * Emitted for keyboard interaction on generated radio inputs.
+	 * Forwards the original DOM `KeyboardEvent`.
+	 */
+	(e: 'keydown', event: KeyboardEvent): void;
+	/**
+	 * Emitted when a pointing device button is pressed over a radio input.
+	 * Forwards the original DOM `MouseEvent`.
+	 */
+	(e: 'mousedown', event: MouseEvent): void;
+	/**
+	 * Emitted when a pointing device button is released over a radio input.
+	 * Forwards the original DOM `MouseEvent`.
+	 */
+	(e: 'mouseup', event: MouseEvent): void;
+	/**
+	 * Emitted with the newly selected value when the selection changes.
+	 */
+	(e: 'update:modelValue', value: any): void;
+};
+
+/**
+ * Props exposed by option affix slots (`option:prepend` / `option:append`).
+ */
+export type BaseRadioGroupOptionAffixSlotProps<T = any> = {
+	/**
+	 * Whether this option is currently selected.
+	 */
+	checked: boolean;
+	/**
+	 * Whether this option is disabled.
+	 */
+	disabled: boolean;
+	/**
+	 * The `id` of this option's input, if set.
+	 */
+	id?: string;
+	/**
+	 * The raw item from the `items` prop.
+	 */
+	item: T;
+	/**
+	 * The display text for this option.
+	 */
+	text: string;
+};
+
+/**
+ * Props exposed by the `label` slot for each option.
+ */
+export type BaseRadioGroupLabelSlotProps<T = any> = {
+	/**
+	 * The raw item from the `items` prop.
+	 */
+	item: T;
+	/**
+	 * The resolved display text for this option.
+	 */
+	text: string;
+	/**
+	 * Whether this option is currently selected.
+	 */
+	checked: boolean;
+};
+
+/**
+ * Props exposed by the `icon` slot for each option. Extends `BaseRadioIconSlotProps`
+ * with the source item and its display text.
+ */
+export type BaseRadioGroupIconSlotProps<T = any> = BaseRadioIconSlotProps & {
+	/**
+	 * The raw item from the `items` prop.
+	 */
+	item: T;
+	/**
+	 * The display text resolved for this option.
+	 */
+	text: string;
+};
+
+export type BaseRadioGroupSlots<T = any> = {
+	/**
+	 * Content rendered before the first option, inside the options container.
+	 */
+	prepend?: (props: object) => any;
+	/**
+	 * Content shown while options are loading (replaces the default loading text).
+	 */
+	loading?: (props: object) => any;
+	/**
+	 * Content shown when no options are available (replaces the default "no data" text).
+	 */
+	'no-data'?: (props: object) => any;
+	/**
+	 * Content rendered before each option's radio button.
+	 */
+	'option:prepend'?: (props: BaseRadioGroupOptionAffixSlotProps<T>) => any;
+	/**
+	 * Replaces the default radio dot icon for each option. Receives all `BaseRadio`
+	 * slot attributes plus the source item and its display text.
+	 */
+	icon?: (props: BaseRadioGroupIconSlotProps<T>) => any;
+	/**
+	 * Replaces the default label text for each option.
+	 */
+	label?: (props: BaseRadioGroupLabelSlotProps<T>) => any;
+	/**
+	 * Content rendered after each option's radio button and label.
+	 */
+	'option:append'?: (props: BaseRadioGroupOptionAffixSlotProps<T>) => any;
+	/**
+	 * Content rendered after the last option, inside the options container.
+	 */
+	append?: (props: object) => any;
+};
+```
+
+## Styles
+
+```css
+.bb-base-radio-group {
+	&.bb-cr-container {
+		&--horizontal {
+			.bb-cr-container-option {
+			}
+		}
+		&--vertical {
+			.bb-cr-container-option {
+			}
+		}
+
+		&__container {
+		}
+		&-option {
+			> .bb-base-radio {
+			}
+			&__text {
+				&--hidden {
+				}
+			}
+		}
+	}
+}
+```