bitboss-ui 2.1.113 → 2.1.115

package/dist/ai/BaseTag.md

@@ -0,0 +1,624 @@
+# BaseTag
+
+## Template & Script
+
+```vue
+<template>
+	<CommonInputOuterContainer
+		ref="outerContainer"
+		:class="{
+			'bb-base-tag': true,
+			'bb-base-tag--active': active,
+			'bb-base-tag--disabled': disabled,
+			'bb-base-tag--loading': loading,
+			'bb-base-tag--errors': hasErrors,
+			'bb-base-tag--readonly': readonly,
+			'bb-base-tag--compact': compact,
+		}"
+		@click="onOuterContainerClick"
+	>
+		<template #prepend-outer><slot name="prepend-outer"></slot></template>
+		<CommonInputInnerContainer
+			ref="innerContainer"
+			:append:icon="props['append:icon']"
+			:clearable="clearable && !isEmpty(modelValue)"
+			:prepend:icon="props['prepend:icon']"
+			:prevent-focus="true"
+			@click:clear="onClear"
+		>
+			<template #prepend><slot name="prepend" /></template>
+			<template #prefix><slot name="prefix" /></template>
+			<BbSmoothHeight tag="span">
+				<span class="bb-base-tag__input-container">
+					<template v-if="multiple">
+						<template v-if="comma">
+							<CommaBox ref="commaBox" :options="selectedOptions" />
+						</template>
+						<template v-else>
+							<ChipsBox
+								ref="chipsBox"
+								:options="selectedOptions"
+								@option:unselected="onOptionUnselected"
+							/>
+						</template>
+					</template>
+
+					<input
+						:id="id"
+						ref="input"
+						v-bind="eventListeners"
+						v-model="query"
+						:aria-describedby="ariaDescribedby"
+						:autocomplete="autocomplete"
+						:autofocus="autofocus"
+						:class="'bb-base-tag__text-input'"
+						:disabled="disabled"
+						enterkeyhint="done"
+						:placeholder="placeholder"
+						:readonly="readonly"
+						:required="required && (!multiple || !modelValue.length)"
+						size="1"
+						:style="{ '--characters': query.length }"
+						type="text"
+						@focus.stop="onInputFocus"
+						@keydown.stop="onInputKeydown"
+						@keydown.stop.delete="onBackspace"
+						@keydown.stop.left="onArrowLeft"
+						@keydown.stop.prevent.esc="onEscape"
+						@keydown.stop.right="onArrowRight"
+					/>
+				</span>
+			</BbSmoothHeight>
+			<template #append><slot name="append" /></template>
+			<template #suffix><slot name="suffix" /></template>
+		</CommonInputInnerContainer>
+
+		<template #append-outer><slot name="append-outer"></slot></template>
+	</CommonInputOuterContainer>
+</template>
+
+<script setup lang="ts">
+import BbSmoothHeight from '../BbSmoothHeight/BbSmoothHeight.vue';
+import { computed, ref, watch } from 'vue';
+import { last } from '@/utilities/functions/last';
+import { nextTick } from 'vue';
+import { toRef } from 'vue';
+import { useBaseOptions } from '@/composables/useBaseOptions';
+import { useIndexById } from '@/composables/useIndexById';
+import ChipsBox from '../ChipsBox/ChipsBox.vue';
+import CommaBox from '../CommaBox/CommaBox.vue';
+import CommonInputInnerContainer from '../CommonInputInnerContainer/CommonInputInnerContainer.vue';
+import CommonInputOuterContainer from '../CommonInputOuterContainer/CommonInputOuterContainer.vue';
+import type { Option as BaseOption } from '@/types/Option';
+import { isEmpty } from '@/utilities/functions/empty';
+import type { BaseTagProps, BaseTagEvents, BaseTagSlots } from './types';
+export type { BaseTagProps, BaseTagEvents, BaseTagSlots };
+
+const props = withDefaults(defineProps<BaseTagProps>(), {
+	autocomplete: 'off',
+	divider: 'Enter',
+	multiple: true,
+});
+
+const emit = defineEmits<BaseTagEvents>();
+
+defineSlots<BaseTagSlots>();
+
+if (props.multiple && !Array.isArray(props.modelValue)) {
+	throw new Error('Multiple is set to "true" but modelValue is not an array.');
+}
+
+const outerContainer = ref<InstanceType<
+	typeof CommonInputOuterContainer
+> | null>(null);
+const innerContainer = ref<InstanceType<
+	typeof CommonInputInnerContainer
+> | null>(null);
+const commaBox = ref<InstanceType<typeof CommaBox> | null>(null);
+const chipsBox = ref<InstanceType<typeof ChipsBox> | null>(null);
+const selectedBox = computed(() =>
+	props.comma ? commaBox.value : chipsBox.value
+);
+
+const input = ref<HTMLElement | null>(null);
+const focusInput = () => {
+	if (input.value instanceof HTMLInputElement) {
+		input.value.focus();
+	}
+};
+
+const query = ref<string>('');
+const selectedOptions = computed(() => {
+	return options.value.filter((o) => o.selected);
+});
+
+const { data: modelValueIndexedByHash, get: isItemSelected } = useIndexById({
+	items: toRef(props, 'modelValue'),
+});
+
+const { options } = useBaseOptions({
+	disabled: toRef(props, 'disabled'),
+	items: computed(() => [].concat(props.modelValue)),
+	itemText: undefined,
+	itemValue: undefined,
+	max: props.max,
+	selectable: true,
+	selectedIndexedByHash: modelValueIndexedByHash,
+});
+
+const alignQueryToState = () => {
+	if (props.multiple) {
+		query.value = '';
+		return;
+	}
+	let option: BaseOption | undefined;
+	if (selectedOptions.value) {
+		option = last(selectedOptions.value);
+	}
+	query.value = option?.text || '';
+};
+
+const onOptionUnselected = async (option: BaseOption) => {
+	if (props.multiple) {
+		const copy = { ...modelValueIndexedByHash.value };
+		delete copy[option.valueHash];
+		emit('update:modelValue', Object.values(copy));
+	} else {
+		emit('update:modelValue', null);
+	}
+	focusInput();
+};
+
+watch(
+	() => props.modelValue,
+	async () => {
+		alignQueryToState();
+	}
+);
+
+/**
+ * Applies a class when the user is inside this whole component.
+ * Also we cannot use the <input/> if we physically move focus to the options so
+ * we track it manually.
+ */
+const active = ref(false);
+
+const setActive = () => {
+	active.value = true;
+};
+const setInactive = () => {
+	active.value = false;
+	emit('inactive');
+};
+
+const canProcessKeyboardBindings = computed(() => {
+	if (props.readonly) return false;
+	if (props.disabled) return false;
+	if (!selectedBox.value && props.multiple) return false;
+	return true;
+});
+
+const onArrowLeft = (event: KeyboardEvent) => {
+	if (!canProcessKeyboardBindings.value) {
+		return;
+	}
+	if (!props.multiple || query.value) {
+		return;
+	}
+	event.preventDefault();
+	if (!selectedOptions.value.length) return;
+	selectedBox.value?.focusPrevious();
+};
+const onArrowRight = (event: KeyboardEvent) => {
+	if (!canProcessKeyboardBindings.value) {
+		return;
+	}
+	if (!props.multiple || query.value) {
+		return;
+	}
+	event.preventDefault();
+	if (!selectedOptions.value.length) return;
+	selectedBox.value?.focusNext();
+};
+
+const onBackspace = async () => {
+	if (
+		!canProcessKeyboardBindings.value ||
+		query.value ||
+		!selectedOptions.value.length
+	) {
+		return;
+	}
+	if (selectedBox.value?.getHighlighted()) {
+		selectedBox.value.confirmOption();
+	}
+	await nextTick();
+	selectedBox.value?.focusPrevious();
+};
+
+const onEscape = () => {
+	selectedBox.value?.blur();
+};
+
+const onInputKeydown = async (event: KeyboardEvent) => {
+	emit('keydown', event);
+	if (props.readonly || props.disabled) {
+		event.preventDefault();
+		return;
+	}
+	// Reset focused chips on key input
+	if (/^[A-Za-z0-9]$/.test(event.key)) {
+		selectedBox.value?.blur();
+	}
+	if (
+		event.key === props.divider ||
+		(event.key === 'Unidentified' && query.value.includes(props.divider))
+	) {
+		if (props.divider.length === 1 && query.value.includes(props.divider)) {
+			const found = query.value.split(props.divider)[0];
+			if (found) {
+				query.value = found;
+			} else {
+				query.value = '';
+				return;
+			}
+		}
+		if (!query.value) {
+			emit('keydown', event);
+			return;
+		}
+		event.preventDefault();
+		if (isItemSelected(query.value)) {
+			emit('duplicate', query.value);
+			query.value = '';
+		} else if (props.max && selectedOptions.value.length >= props.max) {
+			return;
+		} else {
+			if (props.multiple) {
+				emit('update:modelValue', props.modelValue.concat(query.value));
+			} else {
+				emit('update:modelValue', query.value);
+			}
+		}
+	}
+};
+
+const onInputFocus = (event: FocusEvent) => {
+	emit('focus', event);
+	setActive();
+	document.addEventListener('click', onOutsideInteraction);
+	document.addEventListener('focusin', onOutsideInteraction);
+};
+
+/**
+ * When clicking on the outside container seamlessly move focus to the input and open the panel
+ */
+const onOuterContainerClick = (event: MouseEvent) => {
+	emit('click', event);
+	if (props.disabled || props.readonly) return;
+	if (input.value instanceof HTMLElement) {
+		input.value.focus();
+	}
+};
+
+/**
+ * On click outside of the container close the panel, remove active state.
+ * In multiple selection clear query after a timeout
+ */
+const onOutsideInteraction = async (event: Event) => {
+	if (event.target instanceof Node) {
+		if (outerContainer.value) {
+			if (!outerContainer.value.$el.contains(event.target)) {
+				setInactive();
+				document.removeEventListener('click', onOutsideInteraction);
+				document.removeEventListener('focusin', onOutsideInteraction);
+				alignQueryToState();
+				return;
+			}
+		}
+	}
+};
+const eventListeners = {
+	onBlur: (event: FocusEvent) => emit('blur', event),
+	onChange: (event: Event) => emit('change', event),
+	onKeyup: (event: KeyboardEvent) => emit('keyup', event),
+	onInput: (event: Event) => emit('input', event),
+};
+
+const onClear = () => {
+	let value = null;
+	if (props.multiple) {
+		value = [];
+	}
+	emit('update:modelValue', value);
+};
+</script>
+<style lang="postcss">
+@import './index.css';
+</style>
+```
+
+## Types
+
+```ts
+import type { HTMLAttributes, InputHTMLAttributes } from 'vue';
+import type { IconType } from '@/types/Icon';
+
+export type BaseTagProps = {
+	/**
+	 * Name of the icon to render at the right hand side of the input.
+	 */
+	// eslint-disable-next-line vue/prop-name-casing
+	'append:icon'?: IconType;
+
+	/**
+	 * Id(s) of elements describing this tag input for assistive technologies.
+	 */
+	ariaDescribedby?: InputHTMLAttributes['aria-describedby'];
+
+	/**
+	 * Browser autocomplete hint for the input field.
+	 * @defaultValue `'off'`
+	 */
+	autocomplete?: InputHTMLAttributes['autocomplete'];
+
+	/**
+	 * Focus the input automatically on mount.
+	 */
+	autofocus?: InputHTMLAttributes['autofocus'];
+
+	/**
+	 * Display selected tags as a comma-separated string instead of individual chips.
+	 * When enabled, tags cannot be deselected by clicking individual chips.
+	 */
+	comma?: boolean;
+
+	/**
+	 * Show a clear button whenever tags are present and the control is interactive.
+	 */
+	clearable?: boolean;
+
+	/**
+	 * Apply the compact density variant.
+	 */
+	compact?: boolean;
+
+	/**
+	 * Disable all interactions with the tag input.
+	 */
+	disabled?: boolean;
+
+	/**
+	 * Keyboard key that triggers tag creation from current input value.
+	 * @defaultValue `'Enter'`
+	 */
+	divider?: KeyboardEvent['key'];
+
+	/**
+	 * Apply error styling to the tag input.
+	 */
+	hasErrors?: boolean;
+
+	/**
+	 * Explicit id for the input element.
+	 */
+	id?: HTMLAttributes['id'];
+
+	/**
+	 * Display the loading state styles.
+	 */
+	loading?: boolean;
+
+	/**
+	 * Maximum number of tags that can be created.
+	 */
+	max?: number;
+
+	/**
+	 * v-model value. Single value for single tag, array for multiple tags.
+	 */
+	modelValue: any;
+
+	/**
+	 * Enable multiple tag selection. When true, modelValue must be an array.
+	 * @defaultValue `true`
+	 */
+	multiple?: boolean;
+
+	/**
+	 * Name attribute forwarded to the input element.
+	 */
+	name?: InputHTMLAttributes['name'];
+
+	/**
+	 * Placeholder text when no tags are present.
+	 */
+	placeholder?: InputHTMLAttributes['placeholder'];
+
+	/**
+	 * Name of the icon to render at the left hand side of the input.
+	 */
+	// eslint-disable-next-line vue/prop-name-casing
+	'prepend:icon'?: IconType;
+
+	/**
+	 * Make the input read-only while keeping tags visible.
+	 */
+	readonly?: boolean;
+
+	/**
+	 * Mark the input as required for form validation.
+	 */
+	required?: boolean;
+};
+
+export type BaseTagEvents = {
+	/** Emitted when the native input loses focus. Forwards the original DOM `FocusEvent`. */
+	(e: 'blur', event: FocusEvent): void;
+	/** Emitted when the native input fires a change event. Forwards the original DOM `Event`. */
+	(e: 'change', event: Event): void;
+	/** Emitted when the input receives a click interaction. Forwards the original DOM `MouseEvent`. */
+	(e: 'click', event: MouseEvent): void;
+	/** Emitted when an attempt is made to add a tag that already exists. */
+	(e: 'duplicate', string: string): void;
+	/** Emitted when the native input gains focus. Forwards the original DOM `FocusEvent`. */
+	(e: 'focus', event: FocusEvent): void;
+	/** Emitted when focus/click moves outside the tag input after it was active. */
+	(e: 'inactive'): void;
+	/** Emitted on native input events. Forwards the original DOM `Event`. */
+	(e: 'input', event: Event): void;
+	/** Emitted for keyboard interaction. Forwards the original DOM `KeyboardEvent`. */
+	(e: 'keydown', event: KeyboardEvent): void;
+	/** Emitted when a key is released. Forwards the original DOM `KeyboardEvent`. */
+	(e: 'keyup', event: KeyboardEvent): void;
+	/** Emitted when the tag array changes. */
+	(e: 'update:modelValue', value: any): void;
+};
+
+export type BaseTagSlots = {
+	/**
+	 * Content rendered after the tag input, at the end of the inner container.
+	 */
+	append?: (props: object) => any;
+	/**
+	 * Content rendered after the entire tag input control, outside the input chrome.
+	 */
+	'append-outer'?: (props: object) => any;
+	/**
+	 * Content rendered before the tag input, at the start of the inner container.
+	 */
+	prepend?: (props: object) => any;
+	/**
+	 * Content rendered before the entire tag input control, outside the input chrome.
+	 */
+	'prepend-outer'?: (props: object) => any;
+	/**
+	 * Inline content rendered at the start of the input field area, before the typed text.
+	 */
+	prefix?: (props: object) => any;
+	/**
+	 * Inline content rendered at the end of the input field area, after the typed text.
+	 */
+	suffix?: (props: object) => any;
+};
+```
+
+## Styles
+
+```css
+.bb-base-tag {
+	--bb-input-inner-h: max(
+		calc(var(--bb-leading) + var(--bb-input-py) * 2),
+		calc(var(--bb-input-h) - 2px),
+		var(--bb-input-icon)
+	);
+	--floating-py: calc((var(--bb-input-inner-h) - var(--bb-input-icon)) / 2);
+
+	&.bb-base-tag--active {
+		.bb-common-input-inner-container {
+			.bb-base-tag__text-input {
+				/* Approximate the length of the text as min width so the character doesn't go into a newline as often*/
+				min-width: min(100%, calc(var(--characters) * 12px));
+			}
+		}
+	}
+	&--loading {
+		/* Add styles for loading state if needed */
+	}
+	&--disabled {
+		/* Add styles for disabled state if needed */
+	}
+	&--errors {
+		/* Add styles for error state if needed */
+	}
+	&--readonly {
+		/* Add styles for readonly state if needed */
+	}
+	&--compact {
+		--floating-py: var(--bb-input-compact-floating-py);
+
+		.bb-chipsbox-item {
+			min-height: 20px;
+		}
+	}
+
+	&__inner-container {
+		/* Add styles for inner container if needed */
+	}
+
+	.bb-smooth-height {
+		align-self: center;
+		text-align: left;
+		width: 100%;
+	}
+
+	.bb-common-input-inner-container {
+		align-items: flex-start;
+
+		> :last-child {
+			order: 2;
+		}
+		> .bb-clearable-button {
+			margin-top: var(--floating-py);
+		}
+
+		.bb-spinner {
+			margin-top: var(--floating-py);
+		}
+
+		.bb-error-icon {
+			margin-top: var(--floating-py);
+		}
+
+		.bb-common-input-inner-container__prepend-icon,
+		.bb-common-input-inner-container__append-icon {
+			margin-top: var(--floating-py);
+		}
+
+		.bb-common-input-inner-container__prefix,
+		.bb-common-input-inner-container__suffix {
+			align-items: flex-start;
+			padding-top: var(--floating-py);
+		}
+	}
+
+	&__input-container {
+		display: inline-flex;
+		flex: 1;
+		flex-wrap: wrap;
+		gap: 0.25rem;
+		overflow: hidden;
+		padding-bottom: var(--bb-input-py);
+		padding-top: var(--bb-input-py);
+		width: 100%;
+
+		.bb-chipsbox-item {
+			position: relative;
+			z-index: 1;
+		}
+
+		.bb-base-tag__text-input {
+			flex-basis: 0px !important;
+			flex-grow: 1 !important;
+			flex-shrink: 10000 !important;
+			margin-bottom: 0px;
+			margin-top: 0px;
+			min-width: 0;
+		}
+	}
+
+	&__selected {
+		max-width: 100%;
+
+		&--comma {
+			&.bb-base-tag__selected--focused {
+			}
+		}
+
+		&--chip {
+			&.bb-base-tag__selected--focused {
+			}
+		}
+	}
+}
+```