bitboss-ui 2.1.113 → 2.1.115

package/dist/ai/BaseTextInput.md

@@ -0,0 +1,392 @@
+# BaseTextInput
+
+## Template & Script
+
+```vue
+<template>
+	<CommonInputOuterContainer :class="classes">
+		<template #prepend-outer><slot name="prepend-outer"></slot></template>
+		<CommonInputInnerContainer
+			:append:icon="props['append:icon']"
+			:clearable="props.clearable && isNotEmpty(props.modelValue)"
+			:prepend:icon="props['prepend:icon']"
+			@click:clear="$emit('update:modelValue', null)"
+		>
+			<template #prepend><slot name="prepend" /></template>
+			<template #prefix><slot name="prefix" /></template>
+			<input
+				v-if="mask"
+				:id="id"
+				ref="input"
+				:aria-describedby="ariaDescribedby"
+				:aria-invalid="hasErrors ? true : undefined"
+				:autocomplete="autocomplete"
+				:autofocus="autofocus"
+				:class="'bb-base-text-input__input'"
+				:disabled="disabled"
+				:inputmode="inputMode"
+				:name="name"
+				:placeholder="placeholder"
+				:readonly="readonly"
+				:required="required"
+				size="1"
+				:type="type"
+				v-bind="eventListeners"
+				@maska="onMaska"
+			/>
+			<input
+				v-else
+				:id="id"
+				ref="input"
+				:aria-describedby="ariaDescribedby"
+				:aria-invalid="hasErrors ? true : undefined"
+				:autocomplete="autocomplete"
+				:autofocus="autofocus"
+				:class="'bb-base-text-input__input'"
+				:disabled="disabled"
+				:inputmode="inputMode"
+				:name="name"
+				:placeholder="placeholder"
+				:readonly="readonly"
+				:required="required"
+				size="1"
+				:type="type"
+				:value="modelValue"
+				v-bind="eventListeners"
+			/>
+			<template #append><slot name="append" /></template>
+			<template #suffix><slot name="suffix" /></template>
+		</CommonInputInnerContainer>
+		<template #append-outer><slot name="append-outer"></slot></template>
+	</CommonInputOuterContainer>
+	<span> </span>
+</template>
+
+<script setup lang="ts">
+import { computed, onBeforeUnmount, onMounted, ref, watch } from 'vue';
+import CommonInputInnerContainer from '../CommonInputInnerContainer/CommonInputInnerContainer.vue';
+import CommonInputOuterContainer from '../CommonInputOuterContainer/CommonInputOuterContainer.vue';
+import { isNotNil } from '@/utilities/functions/isNotNil';
+import { MaskInput, type MaskInputOptions } from 'maska';
+import { isNotEmpty } from '@/utilities/functions/isNotEmpty';
+import type {
+	BaseTextInputProps,
+	BaseTextInputEvents,
+	BaseTextInputSlots,
+} from './types';
+
+const props = withDefaults(defineProps<BaseTextInputProps>(), {
+	type: 'text',
+});
+
+const emit = defineEmits<BaseTextInputEvents>();
+
+defineSlots<BaseTextInputSlots>();
+const input = ref<HTMLInputElement>();
+
+const classes = computed(() => ({
+	'bb-base-text-input': true,
+	'bb-base-text-input--disabled': props.disabled,
+	'bb-base-text-input--errors': props.hasErrors,
+	'bb-base-text-input--has-value': isNotNil(props.modelValue),
+	'bb-base-text-input--loading': props.loading,
+	'bb-base-text-input--readonly': props.readonly,
+	'bb-base-text-input--compact': props.compact,
+}));
+
+let _mask: MaskInput;
+const onMaska = (
+	event: CustomEvent<{
+		masked: string;
+		unmasked: string;
+		completed: boolean;
+	}>
+) => {
+	if (props.mask) {
+		if (!event.detail.unmasked) {
+			emit('update:modelValue', null);
+		} else {
+			if (props.emitMasked) {
+				emit('update:modelValue', event.detail.masked);
+			} else {
+				emit('update:modelValue', event.detail.unmasked);
+			}
+		}
+	}
+};
+
+const setValue = (val: typeof props.modelValue) => {
+	input.value!.value = val ?? '';
+	_mask!.updateValue(input.value!);
+};
+
+onMounted(() => {
+	if (props.mask) {
+		_mask = new MaskInput(input.value!, props.mask);
+		setValue(props.modelValue);
+	}
+});
+onBeforeUnmount(() => {
+	if (props.mask) {
+		_mask?.destroy();
+	}
+});
+
+watch(
+	() => props.modelValue,
+	(val) => {
+		if (props.mask) setValue(val);
+	}
+);
+
+/**
+ * These events are just propagated
+ */
+const eventListeners = {
+	onBlur: (event: FocusEvent) => emit('blur', event),
+	onChange: (event: Event) => emit('change', event),
+	onClick: (event: MouseEvent) => emit('click', event),
+	onFocus: (event: FocusEvent) => emit('focus', event),
+	onKeydown: (event: KeyboardEvent) => emit('keydown', event),
+	onInput: (event: Event) => {
+		if (!props.mask && event.target instanceof HTMLInputElement) {
+			const value = event.target.value;
+			emit('update:modelValue', value || null);
+		}
+		emit('input', event);
+	},
+	onMousedown: (event: MouseEvent) => emit('mousedown', event),
+	onMouseup: (event: MouseEvent) => emit('mouseup', event),
+};
+</script>
+
+<style lang="postcss">
+@import './index.css';
+</style>
+```
+
+## Types
+
+```ts
+import type { HTMLAttributes, InputHTMLAttributes } from 'vue';
+import type { IconType } from '@/types/Icon';
+import type { MaskInputOptions } from 'maska';
+
+/**
+ * Props for the base text input component with optional masking support.
+ */
+export type BaseTextInputProps = {
+	/**
+	 * 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 input for assistive technologies.
+	 */
+	ariaDescribedby?: InputHTMLAttributes['aria-describedby'];
+
+	/**
+	 * Browser autocomplete hint for the input field.
+	 */
+	autocomplete?: InputHTMLAttributes['autocomplete'];
+
+	/**
+	 * Focus the input automatically on mount.
+	 */
+	autofocus?: InputHTMLAttributes['autofocus'];
+
+	/**
+	 * Show a clear button whenever a value is present and the control is interactive.
+	 */
+	clearable?: boolean;
+
+	/**
+	 * Apply the compact density variant.
+	 */
+	compact?: boolean;
+
+	/**
+	 * Disable all interactions with the input.
+	 */
+	disabled?: boolean;
+
+	/**
+	 * When using a mask, emit the formatted (masked) value instead of the raw input.
+	 */
+	emitMasked?: boolean;
+
+	/**
+	 * Apply error styling to the input and set `aria-invalid`.
+	 */
+	hasErrors?: boolean;
+
+	/**
+	 * Explicit id for the input element.
+	 */
+	id?: HTMLAttributes['id'];
+
+	/**
+	 * Input mode hint for mobile keyboards.
+	 */
+	inputMode?: InputHTMLAttributes['inputmode'];
+
+	/**
+	 * Label rendering mode, forwarded by wrapper components.
+	 */
+	labelMode?: 'outside' | 'floating' | 'inside';
+
+	/**
+	 * Display the loading state styles.
+	 */
+	loading?: boolean;
+
+	/**
+	 * Input mask configuration. When provided, enables formatted input with validation.
+	 */
+	mask?: MaskInputOptions;
+
+	/**
+	 * v-model value: the input text, or `null` when empty.
+	 */
+	modelValue: string | null;
+
+	/**
+	 * Name attribute forwarded to the input element.
+	 */
+	name?: InputHTMLAttributes['name'];
+
+	/**
+	 * Placeholder text when no value is 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 it visible.
+	 */
+	readonly?: boolean;
+
+	/**
+	 * Mark the input as required for form validation.
+	 */
+	required?: boolean;
+
+	/**
+	 * HTML input type attribute.
+	 * @defaultValue `'text'`
+	 */
+	type?: HTMLInputElement['type'];
+};
+
+export type BaseTextInputEvents = {
+	/**
+	 * 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 the native input gains focus.
+	 * Forwards the original DOM `FocusEvent`.
+	 */
+	(e: 'focus', event: FocusEvent): void;
+	/**
+	 * Emitted on native input events from the text field.
+	 * Forwards the original DOM `Event`.
+	 */
+	(e: 'input', event: Event): void;
+	/**
+	 * Emitted for keyboard interaction on the input.
+	 * Forwards the original DOM `KeyboardEvent`.
+	 */
+	(e: 'keydown', event: KeyboardEvent): void;
+	/**
+	 * Emitted when a pointing device button is pressed over the input.
+	 * Forwards the original DOM `MouseEvent`.
+	 */
+	(e: 'mousedown', event: MouseEvent): void;
+	/**
+	 * Emitted when a pointing device button is released over the input.
+	 * Forwards the original DOM `MouseEvent`.
+	 */
+	(e: 'mouseup', event: MouseEvent): void;
+	/**
+	 * Emitted when the value changes. Carries the new string or `null` when cleared.
+	 * When `mask` is set, emits the masked or unmasked string depending on `emitMasked`.
+	 */
+	(e: 'update:modelValue', value: string | null): void;
+};
+
+export type BaseTextInputSlots = {
+	/**
+	 * Content rendered after the entire text input control, outside the input chrome.
+	 */
+	'append-outer'?: (props: object) => any;
+	/**
+	 * Content rendered after the text input, at the end of the inner container.
+	 */
+	append?: (props: object) => any;
+	/**
+	 * Inline content rendered at the start of the input field area, before the typed text.
+	 */
+	prefix?: (props: object) => any;
+	/**
+	 * Content rendered before the text input, at the start of the inner container.
+	 */
+	prepend?: (props: object) => any;
+	/**
+	 * Content rendered before the entire text input control, outside the input chrome.
+	 */
+	'prepend-outer'?: (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-text-input {
+	&--disabled {
+	}
+	&--errors {
+	}
+	&--loading {
+	}
+	&--readonly {
+	}
+
+	.bb-common-input-inner-container {
+		> input {
+		}
+
+		&__prepend-icon,
+		&__append-icon {
+		}
+		.bb-spinner {
+		}
+		.bb-error-icon {
+		}
+		&__prefix,
+		&__suffix {
+		}
+	}
+}
+```