bitboss-ui 2.1.113 → 2.1.115

package/dist/ai/BbSelect.md

@@ -0,0 +1,562 @@
+# BbSelect
+
+## Template & Script
+
+```vue
+<template>
+	<BaseInputContainer
+		:id="id"
+		class="bb-select"
+		:compact="compact"
+		:direction="direction"
+		:errors="errors"
+		:has-errors="hasErrors"
+		:hide-label="hideLabel"
+		:hint="hint"
+		:label="label"
+		:label-position="labelPosition"
+		:model-value="modelValue"
+		:name="name"
+		:reverse="reverse"
+		:show-hint="showHint"
+	>
+		<template #label="data"><slot name="label" v-bind="data"></slot></template>
+		<template #input="{ id, hasErrors, ariaDescribedby }">
+			<BaseSelect
+				:id="id"
+				:allow-writing="allowWriting"
+				:append:icon="props['append:icon']"
+				:aria-describedby="ariaDescribedby"
+				:autocomplete="autocomplete"
+				:autofocus="autofocus"
+				:clearable="clearable"
+				:comma="comma"
+				:compact="compact"
+				:dependencies="dependencies"
+				:deps-debounce-time="depsDebounceTime"
+				:disabled="disabled"
+				:enforce-coherence="enforceCoherence"
+				:filter-by="filterBy"
+				:group-by="groupBy"
+				:has-errors="hasErrors"
+				:header-height="headerHeight"
+				:item-height="itemHeight"
+				:item-text="<any>itemText"
+				:item-value="<any>itemValue"
+				:items="items"
+				:loading="loading"
+				:loading-text="loadingText"
+				:max="max"
+				:max-selected-labels="maxSelectedLabels"
+				:model-value="modelValue"
+				:model-value-debounce-time="modelValueDebounceTime"
+				:multiple="multiple"
+				:name="name"
+				:no-data-text="noDataText"
+				:placeholder="placeholder"
+				:prefill="prefill"
+				:prepend:icon="props['prepend:icon']"
+				:query-debounce-time="queryDebounceTime"
+				:readonly="readonly"
+				:required="required"
+				:selected-labels-fn="selectedLabelsFn"
+				:show-chevron="showChevron"
+				:stash="stash"
+				:transition-duration="transitionDuration"
+				:update-on-animation-frame="updateOnAnimationFrame"
+				v-bind="eventListeners"
+			>
+				<template #append-outer="data"
+					><slot name="append-outer" v-bind="data"
+				/></template>
+				<template #append="data"><slot name="append" v-bind="data" /></template>
+				<template #prefix="data"><slot name="prefix" v-bind="data" /></template>
+				<template #chevron="data"
+					><slot name="chevron" v-bind="data"
+				/></template>
+				<template #loading="data"
+					><slot name="loading" v-bind="data"
+				/></template>
+				<template #no-data="data"
+					><slot name="no-data" v-bind="data"
+				/></template>
+				<template #option="data"><slot name="option" v-bind="data" /></template>
+				<template #group="data"><slot name="group" v-bind="data" /></template>
+				<template #options:append="data"
+					><slot name="options:append" v-bind="data"
+				/></template>
+				<template #options:append:outer="data"
+					><slot name="options:append:outer" v-bind="data"
+				/></template>
+				<template #options:prepend="data"
+					><slot name="options:prepend" v-bind="data"
+				/></template>
+				<template #options:prepend:outer="data"
+					><slot name="options:prepend:outer" v-bind="data"
+				/></template>
+				<template #prepend-outer="data"
+					><slot name="prepend-outer" v-bind="data"
+				/></template>
+				<template #prepend="data"
+					><slot name="prepend" v-bind="data"
+				/></template>
+				<template #suffix="data"><slot name="suffix" v-bind="data" /></template>
+			</BaseSelect>
+		</template>
+	</BaseInputContainer>
+</template>
+
+<script setup lang="ts" generic="T = any">
+import BaseInputContainer from '../BaseInputContainer/BaseInputContainer.vue';
+import BaseSelect from '../BaseSelect/BaseSelect.vue';
+import { ref, computed } from 'vue';
+import type { BbSelectProps, BbSelectEvents, BbSelectSlots } from './types';
+export type { BbSelectProps, BbSelectEvents, BbSelectSlots };
+
+const props = withDefaults(defineProps<BbSelectProps<T>>(), {
+	allowWriting: true,
+	filterBy: () => [],
+	prefill: 'focus',
+	showChevron: true,
+});
+
+const emit = defineEmits<BbSelectEvents>();
+defineSlots<BbSelectSlots<T>>();
+
+const active = ref(false);
+const showHint = computed(() => props.persistentHint || active.value);
+
+const eventListeners = {
+	onBlur: (event: FocusEvent) => emit('blur', event),
+	onChange: (event: Event) => emit('change', event),
+	onClick: (event: MouseEvent) => emit('click', event),
+	'onOption:add': (text: string) => emit('option:add', text),
+	onFocus: (event: FocusEvent) => {
+		active.value = true;
+		emit('focus', event);
+	},
+	onInactive: () => {
+		active.value = false;
+		emit('inactive');
+	},
+	onInput: (event: Event) => emit('input', event),
+	'onUpdate:modelValue': (value: any) => emit('update:modelValue', value),
+};
+</script>
+
+<style lang="postcss">
+@import './index.css';
+</style>
+```
+
+## Types
+
+```ts
+import type { HTMLAttributes, InputHTMLAttributes } from 'vue';
+import type { NestedKeyOf } from '@/types/NestedKeyOf';
+import type { IconType } from '@/types/Icon';
+import type { BaseSelectEvents } from '../BaseSelect/types';
+
+export type BbSelectProps<T> = {
+	/**
+	 * Allows typing into the input.
+	 */
+	allowWriting?: boolean | 'not-mobile';
+
+	/**
+	 * Name of the icon to be added at the end of the input.
+	 */
+	// eslint-disable-next-line vue/prop-name-casing
+	'append:icon'?: IconType;
+
+	/**
+	 * Guides to 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 display model for selected values to a list of comma separated string.
+	 * In this mode the user cannot deselect an option by pressing the close button.
+	 */
+	comma?: boolean;
+
+	/**
+	 * Sets the component in a compact mode.
+	 */
+	compact?: boolean;
+
+	/**
+	 * Defines an array of dependencies that will trigger actions in the component upon change.
+	 */
+	dependencies?: any[];
+
+	/**
+	 * Timeout used to debounce response to changes to dependencies.
+	 */
+	depsDebounceTime?: number;
+
+	/**
+	 * Direction of the layout of the component. Can either be a predefined value or a
+	 * pattern separated by a space like `xx xxxxx`.
+	 */
+	direction?: 'horizontal' | 'vertical' | 'auto' | string;
+
+	/**
+	 * Disables the component.
+	 */
+	disabled?: boolean;
+
+	/**
+	 * If coherence is enforced the input cannot have a modelValue that is incoherent
+	 * with its current items. modelValue will be reset upon incoherence.
+	 */
+	enforceCoherence?: boolean;
+
+	/**
+	 * Can be a string or an array of string containing the messages to display.
+	 */
+	errors?: string | string[];
+
+	/**
+	 * Defines how the filtering should work.
+	 */
+	filterBy?:
+		| string
+		| string[]
+		| false
+		| 'not_stashed'
+		| ((value: any, item: T, query: string | null) => boolean)
+		| null;
+
+	/**
+	 * Path to item property for grouping options.
+	 */
+	groupBy?: string | ((item: T) => string | number | symbol);
+
+	/**
+	 * Define if the component should be in an error state.
+	 * It usually attaches a CSS class for styling purposes.
+	 */
+	hasErrors?: boolean;
+
+	/**
+	 * 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'];
+
+	/**
+	 * Used to retrieve items; can be an array or a function.
+	 */
+	items:
+		| T[]
+		| ((query: string, prefill: boolean, modelValue: any) => Promise<T[]>)
+		| ((query: string, prefill: boolean, modelValue: any) => T[]);
+
+	/**
+	 * Height of group headers in the listbox (px). Defaults to 24px (compact) or 32px.
+	 * Only applies when `groupBy` is set.
+	 */
+	headerHeight?: number;
+
+	/**
+	 * Height of the options in the listbox. By default it will be 32px for the compact
+	 * variant and 40px for the regular variant.
+	 *
+	 * @defaultValue `40`
+	 */
+	itemHeight?: number;
+
+	/**
+	 * Defines a path that returns a property of the object to use as text or a function
+	 * that returns a string.
+	 */
+	itemText?: T extends object
+		? NestedKeyOf<T> | ((item: T) => string)
+		: ((item: T) => string) | undefined;
+
+	/**
+	 * Defines a path that returns a property of the object to use as value or a function
+	 * that returns any value.
+	 */
+	itemValue?: T extends object
+		? NestedKeyOf<T> | ((item: T) => any)
+		: ((item: T) => any) | undefined;
+
+	/**
+	 * Text content of the label of the element.
+	 */
+	label: string;
+
+	/**
+	 * Sets the text alignment of the label.
+	 */
+	labelPosition?: 'left' | 'center' | 'right';
+
+	/**
+	 * Sets the component in a loading state, usually triggering some visual styles.
+	 */
+	loading?: boolean;
+
+	/**
+	 * String displayed while items are being loaded.
+	 */
+	loadingText?: string;
+
+	/**
+	 * Maximum number of selectable items when the multiple flag is set.
+	 */
+	max?: number;
+
+	/**
+	 * Maximum number of labels shown before collapsing to a count summary.
+	 */
+	maxSelectedLabels?: number;
+
+	/**
+	 * Used by v-model. Can be any serializable type.
+	 */
+	modelValue: any;
+
+	/**
+	 * Timeout used to debounce response to changes to modelValue.
+	 */
+	modelValueDebounceTime?: number;
+
+	/**
+	 * Allows the selection of multiple items.
+	 */
+	multiple?: boolean;
+
+	/**
+	 * Defines the name of the input.
+	 */
+	name?: InputHTMLAttributes['name'];
+
+	/**
+	 * String displayed when there are no items to display.
+	 */
+	noDataText?: string;
+
+	/**
+	 * Keeps the hint displayed.
+	 */
+	persistentHint?: boolean;
+
+	/**
+	 * String displayed when there's no data.
+	 */
+	placeholder?: InputHTMLAttributes['placeholder'];
+
+	/**
+	 * Defines the prefill strategy for the input. By default the input will prefill
+	 * on focus. It can also always prefill with `true` and only prefill on search with `false`.
+	 *
+	 * @defaultValue `'focus'`
+	 */
+	prefill?: boolean | 'focus';
+
+	/**
+	 * Name of the icon to be added at the start of the input.
+	 */
+	// eslint-disable-next-line vue/prop-name-casing
+	'prepend:icon'?: IconType;
+
+	/**
+	 * Sets the input as required.
+	 */
+	required?: boolean;
+
+	/**
+	 * Time to wait when the user stops writing in the input before querying data.
+	 */
+	queryDebounceTime?: number;
+
+	/**
+	 * Sets the input in a readonly state.
+	 */
+	readonly?: boolean;
+
+	/**
+	 * Reverses the layout. Applicable in every direction the order of the label and
+	 * the input is swapped.
+	 */
+	reverse?: boolean;
+
+	/**
+	 * Function that returns a string to be displayed when the number of selected labels
+	 * is greater than `maxSelectedLabels`.
+	 */
+	selectedLabelsFn?: (count: number) => string;
+
+	/**
+	 * If true, the chevron will be shown.
+	 *
+	 * @defaultValue `true`
+	 */
+	showChevron?: boolean;
+
+	/**
+	 * Adds a stash to accumulate selected values across searches.
+	 */
+	stash?: boolean;
+
+	/**
+	 * How long the transition has to last in milliseconds.
+	 */
+	transitionDuration?: number;
+
+	/**
+	 * Pass `true` if the dropdown is not updating following movement in the UI, like in modals.
+	 * Very expensive so use with care.
+	 */
+	updateOnAnimationFrame?: boolean;
+};
+
+/** Re-export for consumers importing events type from BbSelect. */
+export type BbSelectEvents = BaseSelectEvents;
+
+/** Props exposed by the `label` slot. */
+export type BbSelectLabelSlotProps = {
+	/** The `label` prop value. */
+	text: string;
+	/** Whether the input is in an error state. */
+	hasErrors: boolean;
+};
+
+/** Props exposed by the `option` slot. */
+export type BbSelectOptionSlotProps<T> = {
+	/** Whether this option is disabled. */
+	disabled: boolean;
+	/** Whether this option currently has keyboard focus. */
+	focused: boolean;
+	/** Zero-based index of this option in the list. */
+	index: number;
+	/** Whether the select is in an error state. */
+	hasErrors?: boolean;
+	/** The raw item from the `items` prop. */
+	item: T;
+	/** Whether items are still being fetched. */
+	loading: boolean;
+	/** Whether this option is currently selected. */
+	selected: boolean;
+	/** The resolved display text for this option. */
+	text: string;
+	/** The resolved value for this option. */
+	value: any;
+};
+
+/** Props exposed by the `group` slot. */
+export type BbSelectGroupSlotProps<T> = {
+	/** The display text for this group. */
+	text: string;
+	/** The raw group item. */
+	item: T;
+	/** Zero-based index of the first option in this group. */
+	index: number;
+	/** Number of options in this group. */
+	length: number;
+	/** Whether all options in this group are disabled. */
+	disabled: boolean;
+};
+
+export type BbSelectSlots<T> = {
+	/**
+	 * Content appended inside the input field, after the value area.
+	 */
+	append?: (props: { query: string; focus: () => void }) => any;
+	/**
+	 * Content appended outside the input field wrapper.
+	 */
+	'append-outer'?: (props: { query: string }) => any;
+	/**
+	 * Replaces the default dropdown chevron icon.
+	 */
+	chevron?: (props: { loading: boolean; shown: boolean }) => any;
+	/**
+	 * Replaces the default label text rendered above the input.
+	 */
+	label?: (props: BbSelectLabelSlotProps) => any;
+	/**
+	 * Content shown inside the options dropdown while items are loading.
+	 */
+	loading?: (props: { query: string }) => any;
+	/**
+	 * Content shown when no options match the query or the list is empty.
+	 */
+	'no-data'?: (props: { query: string; focus: () => void }) => any;
+	/**
+	 * Replaces the default rendering of each option row in the dropdown.
+	 */
+	option?: (props: BbSelectOptionSlotProps<T>) => any;
+	/**
+	 * Replaces the default group header rendered above grouped options.
+	 */
+	group?: (props: BbSelectGroupSlotProps<T>) => any;
+	/**
+	 * Content appended inside the options list, after the last option.
+	 */
+	'options:append'?: (props: { focus: () => void }) => any;
+	/**
+	 * Content appended outside the options list container.
+	 */
+	'options:append:outer'?: (props: { focus: () => void }) => any;
+	/**
+	 * Content prepended inside the options list, before the first option.
+	 */
+	'options:prepend'?: (props: { focus: () => void }) => any;
+	/**
+	 * Content prepended outside the options list container.
+	 */
+	'options:prepend:outer'?: (props: { focus: () => void }) => any;
+	/**
+	 * Content rendered as an inline prefix inside the input field.
+	 */
+	prefix?: (props: object) => any;
+	/**
+	 * Content prepended inside the input field, before the value area.
+	 */
+	prepend?: (props: { query: string; focus: () => void }) => any;
+	/**
+	 * Content prepended outside the input field wrapper.
+	 */
+	'prepend-outer'?: (props: { query: string }) => any;
+	/**
+	 * Content rendered as an inline suffix inside the input field.
+	 */
+	suffix?: (props: object) => any;
+};
+```
+
+## Styles
+
+```css
+.bb-select {
+	.bb-base-input-container {
+		.bb-base-input-container__input {
+			.bb-base-select {
+				display: flex;
+			}
+		}
+	}
+}
+```