bitboss-ui 2.1.113 → 2.1.115

package/dist/ai/BaseNumberInput.md

@@ -0,0 +1,509 @@
+# BaseNumberInput
+
+## Template & Script
+
+```vue
+<template>
+	<CommonInputOuterContainer :class="classes">
+		<template #prepend-outer
+			><slot
+				:decrease="decrease"
+				:increase="increase"
+				name="prepend-outer"
+			></slot
+		></template>
+		<CommonInputInnerContainer
+			:append:icon="props['append:icon']"
+			:clearable="props.clearable && isNotNil(modelValue)"
+			:prepend:icon="props['prepend:icon']"
+			@click:clear="$emit('update:modelValue', null)"
+		>
+			<template #prepend
+				><slot :decrease="decrease" :increase="increase" name="prepend"
+			/></template>
+			<template #prefix
+				><slot :decrease="decrease" :increase="increase" name="prefix"
+			/></template>
+			<input
+				:id="id"
+				ref="input"
+				:aria-describedby="ariaDescribedby"
+				:aria-valuemax="max"
+				:aria-valuemin="min"
+				:aria-valuenow="isNotNil(modelValue) ? modelValue : undefined"
+				:autocomplete="autocomplete"
+				:autofocus="autofocus"
+				:class="'bb-base-number-input__input'"
+				:disabled="disabled"
+				:inputmode="'decimal'"
+				:name="name"
+				:placeholder="placeholder"
+				:readonly="readonly"
+				:required="required"
+				role="spinbutton"
+				size="1"
+				:type="`text`"
+				v-bind="eventListeners"
+				@input.stop="onInput"
+			/>
+			<template #append
+				><slot :decrease="decrease" :increase="increase" name="append"
+			/></template>
+			<template #suffix
+				><slot :decrease="decrease" :increase="increase" name="suffix"
+			/></template>
+		</CommonInputInnerContainer>
+		<template #append-outer
+			><slot
+				:decrease="decrease"
+				:increase="increase"
+				name="append-outer"
+			></slot
+		></template>
+	</CommonInputOuterContainer>
+</template>
+
+<script setup lang="ts">
+import { clamp } from '@/utilities/functions/clamp';
+import { clampPrecision } from '@/utilities/functions/clampPrecision';
+import { computed, ref, watchPostEffect } from 'vue';
+import { isNil } from '@/utilities/functions/isNil';
+import { isNotNil } from '@/utilities/functions/isNotNil';
+import CommonInputInnerContainer from '../CommonInputInnerContainer/CommonInputInnerContainer.vue';
+import CommonInputOuterContainer from '../CommonInputOuterContainer/CommonInputOuterContainer.vue';
+import type {
+	BaseNumberInputProps,
+	BaseNumberInputEvents,
+	BaseNumberInputSlots,
+} from './types';
+
+const props = withDefaults(defineProps<BaseNumberInputProps>(), {
+	autocomplete: 'off',
+	maxPrecision: 8,
+	step: 1,
+	min: Number.MIN_SAFE_INTEGER,
+	max: Number.MAX_SAFE_INTEGER,
+});
+
+const emit = defineEmits<BaseNumberInputEvents>();
+
+defineSlots<BaseNumberInputSlots>();
+
+const classes = computed(() => {
+	return {
+		'bb-base-number-input': true,
+		'bb-base-number-input--disabled': props.disabled,
+		'bb-base-number-input--errors': props.hasErrors,
+		'bb-base-number-input--loading': props.loading,
+		'bb-base-number-input--readonly': props.readonly,
+		'bb-base-number-input--compact': props.compact,
+	};
+});
+
+const input = ref<HTMLInputElement | null>(null);
+
+const nextStep = (value: number) => {
+	const base = Number(props.modelValue || 0);
+	return clamp(base + value, props.min, props.max);
+};
+
+const decrease = () => {
+	if (props.disabled || props.readonly) return;
+	const valueToEmit = nextStep(props.step * -1);
+	emit('decrease', valueToEmit);
+	emit('update:modelValue', valueToEmit);
+};
+
+const increase = () => {
+	if (props.disabled || props.readonly) return;
+	const valueToEmit = nextStep(props.step);
+	emit('increase', valueToEmit);
+	emit('update:modelValue', valueToEmit);
+};
+
+const onInput = (event: Event) => {
+	if (!input.value) return;
+	if (event.target instanceof HTMLInputElement) {
+		const value = event.target.value;
+		emit('input', event);
+
+		let nextInputValue = value;
+		nextInputValue = limitLength(nextInputValue);
+		nextInputValue = replaceCommaWithPeriod(nextInputValue);
+		nextInputValue = removeUnwantedSymbols(nextInputValue);
+		nextInputValue = defaultPad(nextInputValue);
+		if (isParsableString(nextInputValue)) {
+			nextInputValue = clampValue(nextInputValue);
+		}
+		let valueToEmit: null | number = null;
+		if (nextInputValue) {
+			const validString = makeValidNumberString(nextInputValue);
+			valueToEmit = clamp(Number(validString), props.min, props.max);
+		}
+		emit('update:modelValue', valueToEmit);
+		const clamped = clampPrecision(nextInputValue, props.maxPrecision);
+		input.value.value = clamped;
+	}
+};
+
+const onKeydown = (event: KeyboardEvent) => {
+	if (event.key === 'ArrowUp') {
+		event.preventDefault();
+		increase();
+	} else if (event.key === 'ArrowDown') {
+		event.preventDefault();
+		decrease();
+	}
+};
+
+const replaceCommaWithPeriod = (value: string): string => {
+	return value.replaceAll(',', '.');
+};
+
+const removeUnwantedSymbols = (value: string): string => {
+	const noDashes = value[0] + value.slice(1).replaceAll('-', '');
+	const onlyOnePeriod = [...noDashes]
+		.reduce((acc: string[], curr: string) => {
+			if (curr === '.' && acc.includes('.')) return acc;
+			acc.push(curr);
+			return acc;
+		}, [])
+		.join('');
+	const onlyNumbers = onlyOnePeriod.replaceAll(/[^\d.-]/g, '');
+	return onlyNumbers;
+};
+
+const defaultPad = (value: string): string => {
+	if (value.startsWith('.') && value.length === 1) return `0.`;
+	if (value.startsWith('-.') && value.length === 2) return `-0.`;
+	return value;
+};
+
+const limitLength = (value: string): string => {
+	return value.slice(0, 20);
+};
+
+const clampValue = (value: string): string => {
+	return clamp(Number(value), props.min, props.max).toString();
+};
+
+const isParsableString = (value: string): boolean => {
+	if (value.length === 0) return false;
+	if (value.endsWith('.')) return false;
+	if (value.endsWith('-')) return false;
+	if (value.endsWith('-0')) return false;
+	if (/\.\d*0+$/.test(value)) return false;
+	return true;
+};
+
+const makeValidNumberString = (value: string): string => {
+	let [first, second] = value.split('.');
+	first = first || '0';
+	if (!second) return first;
+	second = second?.slice(0, props.maxPrecision) || '0';
+	let unified = `${first}.${second}`;
+	return unified;
+};
+
+/**
+ * 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) => {
+		onKeydown(event);
+		emit('keydown', event);
+	},
+	onKeyup: (event: KeyboardEvent) => emit('keyup', event),
+	onMousedown: (event: MouseEvent) => emit('mousedown', event),
+	onMouseup: (event: MouseEvent) => emit('mouseup', event),
+};
+
+const alignInputValue = (value: string | number | null) => {
+	if (isNil(input.value)) return;
+
+	const currentValue = input.value.value;
+	// This is triggered while the user is writing numbers like -0.75
+	if (
+		!isNil(value) &&
+		!isParsableString(currentValue) &&
+		currentValue.length > 0
+	) {
+		return;
+	}
+
+	let nextValue = value;
+	if (isNil(nextValue)) {
+		nextValue = '';
+	}
+	input.value.value = nextValue?.toString() || '';
+};
+
+watchPostEffect(() => {
+	alignInputValue(props.modelValue);
+});
+
+defineExpose({
+	increase,
+	decrease,
+});
+</script>
+
+<style lang="postcss">
+@import './index.css';
+</style>
+```
+
+## Types
+
+```ts
+import type { HTMLAttributes, InputHTMLAttributes } from 'vue';
+import type { IconType } from '@/types/Icon';
+
+/**
+ * Props for the low-level number input with manual parsing, clamping, and increment/decrement helpers.
+ */
+export type BaseNumberInputProps = {
+	/**
+	 * 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 descriptive elements announced by screen readers.
+	 */
+	ariaDescribedby?: InputHTMLAttributes['aria-describedby'];
+
+	/**
+	 * Browser autocomplete hint for the field.
+	 * @defaultValue `'off'`
+	 */
+	autocomplete?: InputHTMLAttributes['autocomplete'];
+
+	/**
+	 * Focus the input automatically after 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 manual input and the exposed increase/decrease helpers.
+	 */
+	disabled?: boolean;
+
+	/**
+	 * Force the error state; also toggles `aria-invalid`.
+	 */
+	hasErrors?: boolean;
+
+	/**
+	 * Explicit id forwarded to the native input.
+	 */
+	id?: HTMLAttributes['id'];
+
+	/**
+	 * Display the loading state styles.
+	 */
+	loading?: boolean;
+
+	/**
+	 * Upper bound for clamping user input and helper increments.
+	 * @defaultValue `Number.MAX_SAFE_INTEGER`
+	 */
+	max?: number;
+
+	/**
+	 * Maximum number of decimal digits retained after processing.
+	 * @defaultValue `8`
+	 */
+	maxPrecision?: number;
+
+	/**
+	 * Lower bound for clamping user input and helper decrements.
+	 * @defaultValue `Number.MIN_SAFE_INTEGER`
+	 */
+	min?: number;
+
+	/**
+	 * v-model value. Accepts numbers, numeric strings, or null when empty.
+	 */
+	modelValue: number | string | null;
+
+	/**
+	 * Name attribute forwarded to the native input.
+	 */
+	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 its value visible.
+	 */
+	readonly?: boolean;
+
+	/**
+	 * Mark the input as required for form validation.
+	 */
+	required?: boolean;
+
+	/**
+	 * Increment used by the `increase`/`decrease` helpers. Manual typing is never forced to this step.
+	 * @defaultValue `1`
+	 */
+	step?: number;
+};
+
+export type BaseNumberInputEvents = {
+	/**
+	 * 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 by the `decrease` helper with the clamped value after decrementing by one `step`.
+	 */
+	(e: 'decrease', value: number): void;
+	/**
+	 * Emitted when the native input gains focus.
+	 * Forwards the original DOM `FocusEvent`.
+	 */
+	(e: 'focus', event: FocusEvent): void;
+	/**
+	 * Emitted by the `increase` helper with the clamped value after incrementing by one `step`.
+	 */
+	(e: 'increase', value: number): void;
+	/**
+	 * Emitted on native input events from the number input.
+	 * 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 key is released over the input.
+	 * Forwards the original DOM `KeyboardEvent`.
+	 */
+	(e: 'keyup', 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 on any value change with the parsed number or `null` when the field is empty.
+	 */
+	(e: 'update:modelValue', value: number | null): void;
+};
+
+/**
+ * Props exposed by the step control slots (`append`, `append-outer`, `prepend`, `prepend-outer`).
+ */
+export type BaseNumberInputStepSlotProps = {
+	/**
+	 * Increments the value by one `step`.
+	 */
+	increase: () => void;
+	/**
+	 * Decrements the value by one `step`.
+	 */
+	decrease: () => void;
+};
+
+export type BaseNumberInputSlots = {
+	/**
+	 * Inline content rendered at the start of the input field area, before the typed number.
+	 */
+	prefix?: (props: object) => any;
+	/**
+	 * Content rendered after the number input, at the end of the inner container.
+	 * Typically used to place increment/decrement buttons next to the input.
+	 */
+	append?: (props: BaseNumberInputStepSlotProps) => any;
+	/**
+	 * Content rendered after the entire input control, outside the input chrome.
+	 */
+	'append-outer'?: (props: BaseNumberInputStepSlotProps) => any;
+	/**
+	 * Content rendered before the number input, at the start of the inner container.
+	 */
+	prepend?: (props: BaseNumberInputStepSlotProps) => any;
+	/**
+	 * Content rendered before the entire input control, outside the input chrome.
+	 */
+	'prepend-outer'?: (props: BaseNumberInputStepSlotProps) => any;
+	/**
+	 * Inline content rendered at the end of the input field area, after the typed number.
+	 */
+	suffix?: (props: object) => any;
+};
+```
+
+## Styles
+
+```css
+.bb-base-number-input {
+	&--disabled {
+	}
+	&--errors {
+	}
+	&--loading {
+	}
+	&--readonly {
+	}
+
+	.bb-common-input-inner-container {
+		.bb-base-number-input__input {
+		}
+
+		&__prepend-icon,
+		&__append-icon {
+		}
+		.bb-spinner {
+		}
+		.bb-error-icon {
+		}
+		&__prefix,
+		&__suffix {
+		}
+	}
+}
+```