bitboss-ui 2.1.135 → 3.0.0-alpha.4

package/dist/ai/BaseNumberInput.md

@@ -1,509 +0,0 @@
-# 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 {
-		}
-	}
-}
-```