bitboss-ui 3.0.0-beta.4 → 3.0.0-beta.41

package/dist/ai/source/BbNumberInput.md

@@ -6,98 +6,192 @@
 
 ```vue
 <template>
-	<BaseInputContainer
+	<CommonField
 		:id="id"
 		class="bb-number-input"
 		:clearable="isClearable"
 		:compact="compact"
 		:description="description"
-		:direction="direction"
 		:disabled="disabled"
-		:errors="errors"
+		:errors="fieldErrors"
 		:has-errors="hasErrors"
 		:has-value="hasValue"
-		:has-warning="hasWarning"
+		:has-warnings="hasWarnings"
 		:hide-label="hideLabel"
 		:hint="hint"
 		:label="label"
 		:label-mode="resolvedLabelMode"
 		:label-position="labelPosition"
+		:layout="layout"
 		:loading="loading"
-		:model-value="modelValue"
 		:name="name"
+		:passthrough="passthrough"
 		:readonly="readonly"
 		:reverse="reverse"
+		:show-asterisk="showAsterisk"
 		:show-hint="showHint"
 		:warnings="warnings"
+		v-bind="passthrough.forwardAttrs"
 	>
 		<template #label="data"><slot name="label" v-bind="data"></slot></template>
-		<template #input="{ id, hasErrors, hasWarning, ariaDescribedby }">
-			<BaseNumberInput
-				:id="id"
+		<template v-if="$slots.description" #description="data"
+			><slot name="description" v-bind="data"></slot
+		></template>
+		<template
+			#input="{
+				id: fieldId,
+				hasErrors: fieldHasErrors,
+				hasWarnings: fieldHasWarnings,
+				ariaDescribedby,
+				ariaLabelledby,
+			}"
+		>
+			<CommonFieldInput
 				:append:icon="props['append:icon']"
-				:aria-describedby="ariaDescribedby"
-				:autocomplete="autocomplete"
-				:autofocus="autofocus"
 				:clearable="clearable"
 				:compact="compact"
 				:disabled="disabled"
-				:has-errors="hasErrors"
-				:has-warning="hasWarning"
+				:has-errors="fieldHasErrors"
+				:has-value="hasValue"
+				:has-warnings="fieldHasWarnings"
 				:loading="loading"
-				:max="max"
-				:max-precision="maxPrecision"
-				:min="min"
-				:model-value="modelValue"
-				:name="name"
-				:placeholder="placeholder"
+				:passthrough="passthrough"
 				:prepend:icon="props['prepend:icon']"
 				:readonly="readonly"
-				:required="required"
-				:step="step"
-				v-bind="eventListeners"
+				:reserve-append-space="clearable"
+				:variant="variant"
+				@click:clear="emit('update:modelValue', null)"
 			>
-				<template #append-outer="data"
-					><slot name="append-outer" v-bind="data"
+				<template #prepend:outer
+					><slot
+						:decrease="decrease"
+						:increase="increase"
+						name="prepend:outer"
+					></slot
+				></template>
+				<template #prepend
+					><slot :decrease="decrease" :increase="increase" name="prepend"
 				/></template>
-				<template #append="data"><slot name="append" v-bind="data" /></template>
-				<template v-if="$slots.prefix" #prefix="data"
-					><slot name="prefix" v-bind="data"
+				<template v-if="$slots.prefix" #prefix
+					><slot :decrease="decrease" :increase="increase" name="prefix"
 				/></template>
-				<template #prepend="data"
-					><slot name="prepend" v-bind="data"
+				<!-- eslint-disable vue/attributes-order -- `pt` binds LAST so a consumer listener runs after ours (PASSTHROUGH.md T17) -->
+				<input
+					:id="fieldId"
+					ref="input"
+					:aria-describedby="ariaDescribedby"
+					:aria-disabled="disabled || undefined"
+					:aria-invalid="fieldHasErrors || undefined"
+					:aria-labelledby="ariaLabelledby"
+					:aria-readonly="readonly || undefined"
+					:aria-valuemax="max !== Number.MAX_SAFE_INTEGER ? max : undefined"
+					:aria-valuemin="min !== Number.MIN_SAFE_INTEGER ? min : undefined"
+					:aria-valuenow="isNotNil(fieldModel) ? fieldModel : undefined"
+					:autocomplete="autocomplete"
+					:autofocus="autofocus"
+					class="bb-number-input__input"
+					:disabled="disabled"
+					inputmode="decimal"
+					:name="name"
+					:placeholder="placeholder"
+					:readonly="readonly"
+					:required="fieldRequired"
+					role="spinbutton"
+					size="1"
+					type="text"
+					@input.stop="onInput"
+					v-bind="mergeProps(passthrough.controlAttrs, inputBindings)"
+				/>
+				<!-- eslint-enable vue/attributes-order -->
+				<template #append
+					><slot :decrease="decrease" :increase="increase" name="append"
 				/></template>
-				<template v-if="$slots.suffix" #suffix="data"
-					><slot name="suffix" v-bind="data"
+				<template v-if="$slots.suffix" #suffix
+					><slot :decrease="decrease" :increase="increase" name="suffix"
 				/></template>
-				<template #prepend-outer="data"
-					><slot name="prepend-outer" v-bind="data"
-				/></template>
-			</BaseNumberInput>
+				<template #append:outer
+					><slot
+						:decrease="decrease"
+						:increase="increase"
+						name="append:outer"
+					></slot
+				></template>
+			</CommonFieldInput>
 		</template>
-	</BaseInputContainer>
+	</CommonField>
 </template>
 
 <script setup lang="ts">
-import BaseInputContainer from '../BbBaseInputContainer/BbBaseInputContainer.vue';
-import BaseNumberInput from '../BbBaseNumberInput/BbBaseNumberInput.vue';
-import { computed, ref } from 'vue';
-import { config } from 'virtual:bitboss-ui/config';
+import { removedPropsFor } from '@/deprecation/removedProps';
+import { warnRemovedAttrs } from '@/utilities/functions/warnRemovedAttrs';
+/**
+ * BbNumberInput
+ *
+ * Numeric text input with resilient sanitization and editing ergonomics.
+ *
+ * Key behaviors:
+ * - Accepts free-form keyboard input and normalizes progressively.
+ * - Preserves intermediate states users type while composing a number
+ *   (for example ".", "-.", "12.").
+ * - Emits `null` for empty/invalid input and `number` for finite values.
+ * - Clamps output to `max` while typing and to `min` on blur; limits
+ *   decimals via `maxPrecision`.
+ * - Supports keyboard stepping with ArrowUp/ArrowDown.
+ * - Hands `increase()` / `decrease()` to every slot for step controls.
+ */
+import { computed, mergeProps, onMounted, ref, useAttrs, watch } from 'vue';
+import CommonField from '../CommonField/CommonField.vue';
+import CommonFieldInput from '../CommonFieldInput/CommonFieldInput.vue';
+import { useConfig } from '@/composables/useConfig';
+import { useFormBinding } from '@/composables/useFormBinding';
+import {
+	formControlPtActive,
+	TEXT_CONTROL_NATIVE_ATTRS,
+	usePassthrough,
+} from '@/composables/usePassthrough';
+import { clamp } from '@/utilities/functions/clamp';
+import { clampPrecision } from '@/utilities/functions/clampPrecision';
+import { isNil } from '@/utilities/functions/isNil';
 import { isNotNil } from '@/utilities/functions/isNotNil';
-import type {
-	BbNumberInputProps,
-	BbNumberInputEvents,
-	BbNumberInputSlots,
+import {
+	BB_NUMBER_INPUT_PT,
+	type BbNumberInputProps,
+	type BbNumberInputEvents,
+	type BbNumberInputSlots,
 } from './types';
-export type { BbNumberInputProps, BbNumberInputEvents, BbNumberInputSlots };
 
-const props = withDefaults(defineProps<BbNumberInputProps>(), {
-	modelValue: null,
+defineOptions({ inheritAttrs: false });
+// `min` / `max` / `step` / `maxPrecision` drive the clamp and step math and
+// `aria-valuemin` / `aria-valuemax` (the SAFE_INTEGER sentinels stay silent),
+// so they are defaulted here, before anything reads them.
+const declaredProps = withDefaults(defineProps<BbNumberInputProps>(), {
+	autocomplete: 'off',
+	max: Number.MAX_SAFE_INTEGER,
+	maxPrecision: 8,
+	min: Number.MIN_SAFE_INTEGER,
+	step: 1,
 });
 
-const emit = defineEmits<BbNumberInputEvents>();
-
+const declaredEmit = defineEmits<BbNumberInputEvents>();
 defineSlots<BbNumberInputSlots>();
+// Inside a BbForm the field joins it (Q54.4): `props` / `emit` are bound.
+const {
+	props,
+	emit,
+	showAsterisk,
+	errors: fieldErrors,
+	required: fieldRequired,
+	model: fieldModel,
+} = useFormBinding(declaredProps, declaredEmit, {
+	componentName: 'BbNumberInput',
+	identifierFallback: () => declaredProps.label,
+	emptyValue: () => null,
+	leaveOn: 'blur',
+});
+if (process.env.NODE_ENV !== 'production')
+	warnRemovedAttrs('BbNumberInput', removedPropsFor('BbNumberInput'));
+const config = useConfig();
+export type { BbNumberInputProps, BbNumberInputEvents, BbNumberInputSlots };
 
 const active = ref(false);
 const showHint = computed(() => props.persistentHint || active.value);
@@ -110,11 +204,246 @@ const resolvedLabelMode = computed(
 );
 
 /**
- * These events are just propagated
+ * Passthrough (plans/passthrough/BbNumberInput.md). The frame binds `root` /
+ * `label` / `description` / `message` / `hint`, the box row binds `box` /
+ * `icon` / `spinner` / `prefix` / `suffix` / `clear`, and `input` lands on the
+ * native control below. `hasValue` follows this control's own notion of a
+ * value.
+ */
+const passthrough = usePassthrough({
+	component: 'BbNumberInput',
+	attrs: useAttrs(),
+	controlAttrs: TEXT_CONTROL_NATIVE_ATTRS,
+	props,
+	parts: BB_NUMBER_INPUT_PT.parts,
+	states: BB_NUMBER_INPUT_PT.states,
+	active: formControlPtActive(props, () => hasValue.value),
+});
+
+const input = ref<HTMLInputElement | null>(null);
+
+/**
+ * Applies precision and range guards to finalized numeric values. While the
+ * user types, only `max` applies (`withMin: false`): the digits of 15 pass
+ * through 1, and snapping that to a `min` of 10 would turn "15" into "105".
+ * `min` applies on blur.
+ */
+const normalizeNumericValue = (value: number, withMin = true): number => {
+	const precisionAligned = Number(
+		clampPrecision(value.toString(), props.maxPrecision)
+	);
+	return clamp(precisionAligned, withMin ? props.min : -Infinity, props.max);
+};
+
+/**
+ * On blur, raises a value typed below `min` to `min`, in the field and in the
+ * model.
+ */
+const applyMinOnBlur = () => {
+	if (!input.value?.value) return;
+	const typed = Number(makeValidNumberString(input.value.value));
+	if (!Number.isFinite(typed) || typed >= props.min) return;
+	input.value.value = props.min.toString();
+	emit('update:modelValue', props.min);
+};
+
+/**
+ * Resolves the next stepped value relative to the current model.
+ */
+const nextStep = (value: number) => {
+	const base = Number(props.modelValue || 0);
+	return normalizeNumericValue(base + value);
+};
+
+/**
+ * Decrements value by `step` and emits both semantic and model events.
+ */
+const decrease = () => {
+	if (props.disabled || props.readonly) return;
+	const valueToEmit = nextStep(props.step * -1);
+	emit('decrease', valueToEmit);
+	emit('update:modelValue', valueToEmit);
+};
+
+/**
+ * Increments value by `step` and emits both semantic and model events.
+ */
+const increase = () => {
+	if (props.disabled || props.readonly) return;
+	const valueToEmit = nextStep(props.step);
+	emit('increase', valueToEmit);
+	emit('update:modelValue', valueToEmit);
+};
+
+/**
+ * Input normalization pipeline.
+ *
+ * Order matters:
+ * 1) Limit total length to guard against very large pasted payloads.
+ * 2) Normalize decimal separator (comma -> period).
+ * 3) Strip unsupported characters and duplicate separators/signs.
+ * 4) Keep transient but valid-in-progress states (like "." -> "0.").
+ * 5) Clamp parsable values to `min`/`max`.
+ * 6) Emit normalized numeric model value.
+ * 7) Sync visible input and preserve caret position when transformed.
+ */
+const onInput = (event: Event) => {
+	if (!input.value) return;
+	if (event.target instanceof HTMLInputElement) {
+		const value = event.target.value;
+		const selectionStart = event.target.selectionStart;
+		const selectionEnd = event.target.selectionEnd;
+		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);
+			const parsedValue = Number(validString);
+			if (Number.isFinite(parsedValue)) {
+				valueToEmit = normalizeNumericValue(parsedValue, false);
+			}
+		}
+		emit('update:modelValue', valueToEmit);
+		const clamped = clampPrecision(nextInputValue, props.maxPrecision);
+		if (input.value.value !== clamped) {
+			input.value.value = clamped;
+			if (selectionStart !== null && selectionEnd !== null) {
+				const delta = clamped.length - value.length;
+				const nextStart = Math.max(0, selectionStart + delta);
+				const nextEnd = Math.max(0, selectionEnd + delta);
+				input.value.setSelectionRange(nextStart, nextEnd);
+			}
+		}
+	}
+};
+
+/**
+ * Handles keyboard step controls while still propagating keydown events.
+ */
+const onKeydown = (event: KeyboardEvent) => {
+	if (event.key === 'ArrowUp') {
+		event.preventDefault();
+		increase();
+	} else if (event.key === 'ArrowDown') {
+		event.preventDefault();
+		decrease();
+	}
+};
+
+/**
+ * Normalises the decimal separator to a period and drops grouping separators,
+ * so a pasted or typed European number is not read a thousand times smaller
+ * (`1.234,56` used to become 1.23456):
+ * - both `.` and `,` present: the LAST one is the decimal, the rest group
+ *   (`1.234,56` → 1234.56, `1,234.56` → 1234.56);
+ * - one kind repeated: it groups (`1.234.567` → 1234567);
+ * - one separator: it is the decimal, comma or period (`1,5` → 1.5).
+ */
+const replaceCommaWithPeriod = (value: string): string => {
+	const lastComma = value.lastIndexOf(',');
+	const lastPeriod = value.lastIndexOf('.');
+	const count = (ch: string) => value.split(ch).length - 1;
+	if (lastComma !== -1 && lastPeriod !== -1) {
+		const decimal = lastComma > lastPeriod ? lastComma : lastPeriod;
+		return [...value]
+			.map((ch, i) =>
+				ch === ',' || ch === '.' ? (i === decimal ? '.' : '') : ch
+			)
+			.join('');
+	}
+	const separator = lastComma !== -1 ? ',' : '.';
+	if (count(separator) > 1) return value.replaceAll(separator, '');
+	return value.replace(',', '.');
+};
+
+/**
+ * Keeps only the first sign/decimal separator and drops other characters.
+ */
+const removeUnwantedSymbols = (value: string): string => {
+	if (!value.length) return '';
+	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;
+};
+
+/**
+ * Converts edge typing states into valid progressive forms.
+ */
+const defaultPad = (value: string): string => {
+	if (value.startsWith('.') && value.length === 1) return `0.`;
+	if (value.startsWith('-.') && value.length === 2) return `-0.`;
+	return value;
+};
+
+/**
+ * Restricts raw input length before deeper parsing/sanitization.
+ */
+const limitLength = (value: string): string => {
+	return value.slice(0, 20);
+};
+
+/**
+ * Applies the `max` boundary to parsable input strings (`min` waits for
+ * blur, see `normalizeNumericValue`).
+ */
+const clampValue = (value: string): string => {
+	const parsed = Number(value);
+	const clamped = clamp(parsed, -Infinity, props.max);
+	const canonical = clamped.toString();
+	// Below 1e-6 `toString()` goes exponential ("1e-7"); an unclamped value
+	// keeps the typed decimal so the next keystroke extends it.
+	if (clamped === parsed && canonical.includes('e')) return value;
+	return canonical;
+};
+
+/**
+ * Distinguishes fully parsable values from in-progress user input.
+ */
+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;
+};
+
+/**
+ * Produces a canonical decimal representation before Number parsing.
+ */
+const makeValidNumberString = (value: string): string => {
+	let [first, second] = value.split('.');
+	first = first || '0';
+	if (!second) return first;
+	second = second?.slice(0, props.maxPrecision) || '0';
+	const unified = `${first}.${second}`;
+	return unified;
+};
+
+/**
+ * Native DOM events re-emitted as component events; `focus` / `blur` also
+ * drive the hint. Keydown is intercepted first for step shortcuts; `input` is
+ * bound separately (`@input.stop`).
  */
 const eventListeners = {
 	onBlur: (event: FocusEvent) => {
 		active.value = false;
+		applyMinOnBlur();
 		emit('blur', event);
 	},
 	onChange: (event: Event) => emit('change', event),
@@ -122,21 +451,77 @@ const eventListeners = {
 	onCompositionend: (event: CompositionEvent) => emit('compositionend', event),
 	onCompositionstart: (event: CompositionEvent) =>
 		emit('compositionstart', event),
-	onDecrease: (event: number) => emit('decrease', event),
 	onFocus: (event: FocusEvent) => {
 		active.value = true;
 		emit('focus', event);
 	},
-	onIncrease: (event: number) => emit('increase', event),
-	onInput: (event: Event) => emit('input', event),
-	onKeydown: (event: KeyboardEvent) => emit('keydown', 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),
 	onPaste: (event: ClipboardEvent) => emit('paste', event),
-	'onUpdate:modelValue': (value: number | null) =>
-		emit('update:modelValue', value),
 };
+
+/**
+ * The native control's whole `v-bind`: the listeners, then `pt:input` LAST —
+ * one object, because two `v-bind`s on one element are a duplicate attribute.
+ * `mergeProps` keeps the contract: a class appends, an attribute wins, a
+ * listener concatenates after ours.
+ */
+const inputBindings = computed(() =>
+	passthrough.input
+		? mergeProps(eventListeners, passthrough.input)
+		: eventListeners
+);
+
+/**
+ * Synchronizes rendered input value with external model updates.
+ *
+ * It intentionally avoids overriding in-progress non-parsable user states,
+ * such as when the field currently contains "-0." while typing.
+ */
+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. Only while
+	// they are: once the field lost focus an in-progress shape like "1.50" is
+	// just a display, and must not lock out the next external write.
+	if (
+		!isNil(value) &&
+		document.activeElement === input.value &&
+		!isParsableString(currentValue) &&
+		currentValue.length > 0
+	) {
+		return;
+	}
+
+	let nextValue = value;
+	if (isNil(nextValue)) {
+		nextValue = '';
+	}
+	input.value.value = nextValue?.toString() || '';
+};
+
+/**
+ * Keeps the raw DOM value in sync with v-model changes.
+ */
+watch(
+	() => props.modelValue,
+	(value) => {
+		alignInputValue(value);
+	}
+);
+
+/**
+ * Ensures initial value is painted once the native input ref exists.
+ */
+onMounted(() => {
+	alignInputValue(props.modelValue);
+});
 </script>
 
 <style lang="postcss">
@@ -147,15 +532,56 @@ const eventListeners = {
 ## Types
 
 ```ts
+import type { InputVariantType } from '@/types/InputVariant';
 import type { HTMLAttributes, InputHTMLAttributes } from 'vue';
-import type { InputDirection } from '@/types/InputDirection';
+import type { FieldLayout } from '@/types/FieldLayout';
 import type { IconType } from '@/types/Icon';
-import type {
-	BaseNumberInputEvents,
-	BaseNumberInputSlots,
-} from '../BbBaseNumberInput/types';
+import {
+	FORM_CONTROL_PT_STATES,
+	TEXT_CONTROL_PT_PARTS,
+	type FormControlPtState,
+	type PtMap,
+	type PtValue,
+	type TextControlPtPart,
+} from '@/types/passthrough';
+import type { FormFieldProps } from '@/composables/useFormBinding';
 
+/**
+ * Passthrough parts of `BbNumberInput` (plans/passthrough/BbNumberInput.md) — the form-control
+ * family vocabulary: `root` (the container), `label`, `description`, `message`, `hint`
+ * (the errors / warnings region), `box` (the bordered box), `input` (the
+ * native control), `icon` (the prepend + append content icons — a broadcast;
+ * the clear button and the error / warning glyphs are chrome), `spinner`
+ * (the spinner shown while `loading`),
+ * `prefix`, `suffix`.
+ */
+export type BbNumberInputPtPart = TextControlPtPart;
+/** Passthrough states of `BbNumberInput`: the family's six, true while the matching `--` modifier is on. */
+export type BbNumberInputPtState = FormControlPtState;
+/** The runtime lists the resolver is wired with — kept next to the types so the two cannot drift. */
+export const BB_NUMBER_INPUT_PT = {
+	parts: TEXT_CONTROL_PT_PARTS,
+	states: FORM_CONTROL_PT_STATES,
+} as const satisfies {
+	parts: readonly BbNumberInputPtPart[];
+	states: readonly BbNumberInputPtState[];
+};
+
+// The passthrough props are a mapped type written INLINE with this
+// component's own unions (Vue's SFC type resolver does not substitute a
+// generic alias's type parameters — plans/PASSTHROUGH.md T20); the test
+// asserts the resolved prop names.
+// eslint-disable-next-line @typescript-eslint/consistent-indexed-object-style
 export type BbNumberInputProps = {
+	[K in
+		| `pt:${BbNumberInputPtPart}`
+		| `pt:${BbNumberInputPtPart}:${BbNumberInputPtState}`]?: PtValue;
+} & {
+	/**
+	 * Passthrough, object form: `{ box: '…', 'box:errors': '…' }` — the same
+	 * keys as the `pt:*` attributes without the prefix. See the `pt:<part>` row.
+	 */
+	pt?: PtMap<BbNumberInputPtPart, BbNumberInputPtState>;
 	/**
 	 * Name of the icon to be added at the end of the input.
 	 */
@@ -163,6 +589,8 @@ export type BbNumberInputProps = {
 	'append:icon'?: IconType;
 	/**
 	 * Guides the browser as to the type of information expected in the field.
+	 *
+	 * @defaultValue `'off'`
 	 */
 	autocomplete?: InputHTMLAttributes['autocomplete'];
 
@@ -177,10 +605,32 @@ export type BbNumberInputProps = {
 	clearable?: boolean;
 
 	/**
-	 * Sets the component in a compact state.
+	 * Compact density. Swaps `--bb-input-h`, `--bb-input-py` and
+	 * `--bb-label-spacing-y` for their `-compact` twins on the field, so a
+	 * `--bb-input-h` you set on the component is ignored while `compact` is on:
+	 * size a compact field with `--bb-input-h-compact` (and
+	 * `--bb-input-py-compact`) instead.
 	 */
 	compact?: boolean;
 
+	/**
+	 * Visual variant of the field box — the same names and tokens as the
+	 * `BbButton` variants. Colours only: height, padding and border width are
+	 * identical across variants, so a form never reflows when one changes.
+	 * `'ghost'` has no border in any state (errors and warnings show through
+	 * the icon and the messages); every variant keeps the focus ring.
+	 * Register extra names with the plugin's `inputVariants` option.
+	 *
+	 * `'none'` is a blank starting point: the field keeps its structure and
+	 * behaviour but takes no look, so your own classes don't fight a built-in
+	 * one. You then own hover, focus, disabled and the error / warning states.
+	 * Fine for a one-off; keep inline styling short, and register a real
+	 * variant (`inputVariants`) when the look recurs.
+	 *
+	 * @defaultValue `'outline'`
+	 */
+	variant?: InputVariantType;
+
 	/**
 	 * Descriptive text displayed below the label and above the input. Unlike the hint it is always
 	 * visible, and it is linked to the input via `aria-describedby` (after any
@@ -189,9 +639,12 @@ export type BbNumberInputProps = {
 	description?: string;
 
 	/**
-	 * Direction of the layout of the component. Can either be a predefined value or a pattern separated by a space like `xx xxxxx`.
+	 * How the label and the input sit together: `'vertical'`, `'horizontal'` (50/50),
+	 * `'auto'`, `'label-fill'` (the label takes the free space, the input keeps
+	 * its size), `'input-fill'` (the other way round), or a two-word ratio
+	 * pattern like `'xx xxxxx'`.
 	 */
-	direction?: InputDirection;
+	layout?: FieldLayout;
 
 	/**
 	 * Disables the component.
@@ -226,7 +679,7 @@ export type BbNumberInputProps = {
 	 * Define if the component should be in a warning state.
 	 * Same chrome as errors with `--bb-warn`; errors take priority.
 	 */
-	hasWarning?: boolean;
+	hasWarnings?: boolean;
 
 	/**
 	 * Visually hides the label of the input while maintaining accessibility.
@@ -239,7 +692,8 @@ export type BbNumberInputProps = {
 	hint?: string;
 
 	/**
-	 * The identifier of the component.
+	 * The `id` of the native control; the label's `for` and the description
+	 * and message ids derive from it. Generated when omitted.
 	 */
 	id?: HTMLAttributes['id'];
 
@@ -265,16 +719,23 @@ export type BbNumberInputProps = {
 
 	/**
 	 * Maximum value cap.
+	 *
+	 * @defaultValue `Number.MAX_SAFE_INTEGER`
 	 */
 	max?: number;
 
 	/**
 	 * Maximum precision of the number.
+	 *
+	 * @defaultValue `8`
 	 */
 	maxPrecision?: number;
 
 	/**
-	 * Minimum value cap.
+	 * Minimum value cap. Applied on blur, not while typing, so a value above a
+	 * `min` greater than 1 can be typed digit by digit.
+	 *
+	 * @defaultValue `Number.MIN_SAFE_INTEGER`
 	 */
 	min?: number;
 
@@ -283,7 +744,7 @@ export type BbNumberInputProps = {
 	 *
 	 * @defaultValue `null`
 	 */
-	modelValue: number | string | null;
+	modelValue?: number | string | null;
 
 	/**
 	 * Defines the name of the input.
@@ -322,18 +783,98 @@ export type BbNumberInputProps = {
 	reverse?: boolean;
 
 	/**
-	 * Incremental unit used in the exposed `increase` and `decrease` functions.
+	 * Incremental unit used by ArrowUp / ArrowDown and by the `increase` and `decrease` functions the slots receive.
 	 * It is NOT applied to manual input as a step of 5 would prevent the user from inserting a value like `115` because of rounding down.
+	 *
+	 * @defaultValue `1`
 	 */
 	step?: number;
+} & FormFieldProps<number | string | null>;
+
+export type BbNumberInputEvents = {
+	/**
+	 * 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 a composition session ends (e.g. CJK IME confirmed).
+	 * Forwards the original DOM `CompositionEvent`.
+	 */
+	(e: 'compositionend', event: CompositionEvent): void;
+	/**
+	 * Emitted when a composition session starts (e.g. CJK IME begins).
+	 * Forwards the original DOM `CompositionEvent`.
+	 */
+	(e: 'compositionstart', event: CompositionEvent): 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 when content is pasted into the input.
+	 * Forwards the original DOM `ClipboardEvent`.
+	 */
+	(e: 'paste', event: ClipboardEvent): void;
+	/**
+	 * Emitted on any value change with the parsed number or `null` when the field is empty.
+	 */
+	(e: 'update:modelValue', value: number | null): void;
 };
 
-/**
- * Event contract of `BbNumberInput` — identical to `BbBaseNumberInput`'s.
- * Declared as a structural interface (rather than a re-export alias) so the
- * `defineEmits` macro can resolve it directly.
- */
-export type BbNumberInputEvents = BaseNumberInputEvents;
+/** Props exposed by the `description` slot. */
+export type BbNumberInputDescriptionSlotProps = {
+	/** The `description` prop value (empty when only the slot is provided). */
+	text: string;
+	/** Whether the field is in an error state. */
+	hasErrors: boolean;
+	/** Whether the field is in a warning state (suppressed when errors win). */
+	hasWarnings: boolean;
+};
 
 /** Props exposed by the `label` slot. */
 export type BbNumberInputLabelSlotProps = {
@@ -342,25 +883,67 @@ export type BbNumberInputLabelSlotProps = {
 	/** Whether the input is in an error state. */
 	hasErrors: boolean;
 	/** Whether the input is in a warning state (suppressed when errors win). */
-	hasWarning: boolean;
+	hasWarnings: boolean;
 };
 
-export type BbNumberInputSlots = BaseNumberInputSlots & {
+/**
+ * Props every slot of `BbNumberInput` receives (`prefix`, `suffix`, `append`,
+ * `append:outer`, `prepend`, `prepend:outer`): the step helpers.
+ */
+export type BbNumberInputStepSlotProps = {
+	/**
+	 * Increments the value by one `step`.
+	 */
+	increase: () => void;
+	/**
+	 * Decrements the value by one `step`.
+	 */
+	decrease: () => void;
+};
+
+export type BbNumberInputSlots = {
+	/**
+	 * Inline content rendered at the start of the input field area, before the typed number.
+	 */
+	prefix?: (props: BbNumberInputStepSlotProps) => 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: BbNumberInputStepSlotProps) => any;
+	/**
+	 * Content rendered after the entire input control, outside the input chrome.
+	 */
+	'append:outer'?: (props: BbNumberInputStepSlotProps) => any;
+	/**
+	 * Content rendered before the number input, at the start of the inner container.
+	 */
+	prepend?: (props: BbNumberInputStepSlotProps) => any;
+	/**
+	 * Content rendered before the entire input control, outside the input chrome.
+	 */
+	'prepend:outer'?: (props: BbNumberInputStepSlotProps) => any;
+	/**
+	 * Inline content rendered at the end of the input field area, after the typed number.
+	 */
+	suffix?: (props: BbNumberInputStepSlotProps) => any;
 	/**
 	 * Replaces the default label text rendered above the number input.
 	 */
 	label?: (props: BbNumberInputLabelSlotProps) => any;
+	/**
+	 * Replaces the description text. Provided alone (no `description` prop) it still
+	 * renders the description region and wires it into `aria-describedby`.
+	 */
+	description?: (props: BbNumberInputDescriptionSlotProps) => any;
 };
 ```
 
 ## Styles
 
 ```css
-.bb-number-input {
-	/* The control column is a grid that sizes children to content; text-like
-	   inputs must fill it. */
-	.bb-base-number-input {
-		width: 100%;
-	}
-}
+/* BbNumberInput has no rules of its own: the frame, the box row and the native
+   input are styled by the shared field chrome (CommonField / CommonFieldInput),
+   and the box row fills the control column through the shared
+   `.bb-field__input-wrapper > .bb-field-input` rule. */
 ```