bitboss-ui 2.1.134 → 3.0.0-alpha.1

package/dist/ai/BbNumberInput.md

@@ -1,371 +1,729 @@
 # BbNumberInput
 
-## Template & Script
+## Agent Contract
+
+- Safety level: **Consumer API**
+- Group: **Inputs**
+- Description: Captures and validates numeric form values, emits a number value.
+- Usage rule: Prefer this component for consumer-facing implementations.
+- Implementation source (only when the contract below is not enough): [source/BbNumberInput.md](./source/BbNumberInput.md)
+
+## Usage & Guidelines
+
+### When to use
+
+Use `BbNumberInput` whenever the value is a number the user edits directly:
+quantities, prices, ages, thresholds, counts. It sanitises input as people type
+(accepts commas as decimal separators, strips stray characters, keeps
+in-progress states like `12.` or `-0.`), clamps to `min`/`max`, and emits a real
+`number | null` — no manual parsing on your side. It shares the whole
+input-family chrome (`label`, `description`, `hint`, `errors`, affixes,
+`clearable`, `loading`) with `BbTextInput`, so it lines up in the same form.
+
+Reach for a sibling instead when:
+
+- the value is best chosen from a bounded range by dragging → `BbSlider`;
+- it's a rating/score on a fixed scale → `BbRating`;
+- it's really an identifier or code (leading zeros matter, no arithmetic) →
+  `BbTextInput` with a `mask`.
+
+Under the hood the control is a `<input type="text" inputmode="decimal"
+role="spinbutton">`, not a native `type="number"` — which is why leading-zero
+and locale-separator quirks of native number inputs don't apply here.
+
+`v-model` accepts `number | string | null` and the component **emits
+`number | null`** (a cleared field emits `null`, never `''` or `NaN`).
+
+### Label & label modes
+
+`label` is required and doubles as the default `name`. The shared label controls
+apply:
+
+- **`labelMode`** sets where the label sits: `outside` (default, above),
+  `floating` (rests inside like a placeholder, lifts on focus/fill) or `inside`
+  (pinned small at the top of the field). Avoid pairing `floating` with a
+  `placeholder` — the resting label already plays that role.
+- **`hideLabel`** hides it visually but keeps the accessible name;
+  **`labelPosition`** aligns the text; the **`label` slot** replaces it and
+  receives `{ text, hasErrors }`.
+
+When you don't set `labelMode`, the project-wide `config.defaultInputLabelMode`
+applies (library default: `outside`) — the same fallback as `BbTextInput`, so a
+project can go all-floating without touching call sites.
+
+**Inventory counts — three label modes**
 
 ```vue
 <template>
-	<BaseInputContainer
-		:id="id"
-		class="bb-number-input"
-		:compact="compact"
-		:direction="direction"
-		:errors="errors"
-		:has-errors="hasErrors"
-		:hide-label="hideLabel"
-		:hint="hint"
-		:label="label"
-		:label-position="labelPosition"
-		:model-value="modelValue"
-		:name="name"
-		:reverse="reverse"
-		:show-hint="showHint"
-	>
-		<template #label="data"><slot name="label" v-bind="data"></slot></template>
-		<template #input="{ id, hasErrors, ariaDescribedby }">
-			<BaseNumberInput
-				:id="id"
-				ref="bni"
-				:append:icon="props['append:icon']"
-				:aria-describedby="ariaDescribedby"
-				:autocomplete="autocomplete"
-				:autofocus="autofocus"
-				:clearable="clearable"
-				:compact="compact"
-				:disabled="disabled"
-				:has-errors="hasErrors"
-				:loading="loading"
-				:max="max"
-				:max-precision="maxPrecision"
-				:min="min"
-				:model-value="modelValue"
-				:name="name"
-				:placeholder="placeholder"
-				:prepend:icon="props['prepend:icon']"
-				:readonly="readonly"
-				:required="required"
-				:step="step"
-				v-bind="eventListeners"
-			>
-				<template #append-outer="data"
-					><slot name="append-outer" v-bind="data"
-				/></template>
-				<template #append="data"><slot name="append" v-bind="data" /></template>
-				<template #prefix="data"><slot name="prefix" v-bind="data" /></template>
-				<template #prepend="data"
-					><slot name="prepend" v-bind="data"
-				/></template>
-				<template #suffix="data"><slot name="suffix" v-bind="data" /></template>
-				<template #prepend-outer="data"
-					><slot name="prepend-outer" v-bind="data"
-				/></template>
-			</BaseNumberInput>
-		</template>
-	</BaseInputContainer>
+	<div class="grid max-w-sm gap-3 rounded-[var(--bb-radius)] border p-4">
+		<div>
+			<p class="text-sm font-medium">Inventory counts</p>
+			<p class="text-xs text-gray-500">
+				Same field, three label placements — pick one per product.
+			</p>
+		</div>
+		<BbNumberInput
+			v-model="outside"
+			compact
+			label="Outside (default)"
+			:max-precision="0"
+			:min="0"
+		/>
+		<BbNumberInput
+			v-model="floating"
+			compact
+			label="Floating"
+			label-mode="floating"
+			:max-precision="0"
+			:min="0"
+		/>
+		<BbNumberInput
+			v-model="inside"
+			compact
+			label="Inside"
+			label-mode="inside"
+			:max-precision="0"
+			:min="0"
+		/>
+	</div>
 </template>
+<script setup lang="ts">
+import { ref } from 'vue';
+import { BbNumberInput } from 'bitboss-ui';
 
+const outside = ref<number | null>(24);
+// Left empty so the floating label rests inside the field like a placeholder.
+const floating = ref<number | null>(null);
+const inside = ref<number | null>(8);
+</script>
+```
+
+### Description, hint & validation
+
+The same messaging surface as the rest of the family:
+
+- **`description`** — always-visible text between label and field
+  (`aria-describedby`), for instructions the user needs before typing.
+- **`hint`** — shows below the field on focus; `persistentHint` pins it. Great
+  for stating the range or unit.
+- **`errors`** (string or string array) + **`hasErrors`** — render below the
+  field in an `aria-live="polite"` region and set `aria-invalid`. Because `min`
+  and `max` already clamp silently, drive `errors` yourself when a value is
+  business-invalid (e.g. "must be a multiple of 5").
+- **`warnings`** — the amber counterpart of `errors`: a string or string array
+  rendered below the field in its own `aria-live="polite"` region, in amber
+  (`--bb-warn`), for a valid-but-noteworthy number (unusual, near a limit,
+  soft-flagged) where a hard error would overstate the problem. A non-empty
+  `warnings` implies the warning state, so **`hasWarning`** is just the
+  force-the-chrome flag (tinted border, focus ring, warning icon) for when the
+  message lives elsewhere — parallel to how `errors` relates to `hasErrors`.
+  Unlike `errors`, `warnings` do **not** set `aria-invalid`, and `errors` win
+  when both are set — the warning messages are suppressed, so the field never
+  shows amber and red at once.
+- **`required`** forwards to the native input.
+
+**Team seats with hint and plan-cap error**
+
+```vue
+<template>
+	<div class="grid max-w-sm gap-3 rounded-[var(--bb-radius)] border p-4">
+		<div>
+			<p class="text-sm font-medium">Team seats · Pro plan</p>
+			<p class="text-xs text-gray-500">
+				Hint states the range; business caps surface as errors.
+			</p>
+		</div>
+		<BbNumberInput
+			v-model="seats"
+			compact
+			hint="Billed per seat · 1–100 on Pro."
+			label="Seats"
+			:max="100"
+			:max-precision="0"
+			:min="1"
+			name="seats"
+			persistent-hint
+		/>
+		<BbNumberInput
+			v-model="overCap"
+			compact
+			errors="Max 100 seats on this plan. Upgrade to Enterprise."
+			label="Seats (over plan)"
+			:max="100"
+			:max-precision="0"
+			:min="1"
+			name="seats-over"
+		/>
+	</div>
+</template>
 <script setup lang="ts">
-import BaseInputContainer from '../BaseInputContainer/BaseInputContainer.vue';
-import BaseNumberInput from '../BaseNumberInput/BaseNumberInput.vue';
-import type { BaseNumberInputEvents } from '../BaseNumberInput/types';
-import { computed, ref } from 'vue';
-import type {
-	BbNumberInputProps,
-	BbNumberInputEvents,
-	BbNumberInputSlots,
-} from './types';
-
-const props = withDefaults(defineProps<BbNumberInputProps>(), {});
-
-const emit = defineEmits<BaseNumberInputEvents>();
-
-defineSlots<BbNumberInputSlots>();
-
-const bni = ref();
-
-const active = ref(false);
-const showHint = computed(() => props.persistentHint || active.value);
-
-/**
- * These events are just propagated
- */
-const eventListeners = {
-	onBlur: (event: FocusEvent) => {
-		active.value = false;
-		emit('blur', event);
-	},
-	onChange: (event: Event) => emit('change', event),
-	onClick: (event: MouseEvent) => emit('click', 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),
-	onMousedown: (event: MouseEvent) => emit('mousedown', event),
-	onMouseup: (event: MouseEvent) => emit('mouseup', event),
-	'onUpdate:modelValue': (value: number | null) =>
-		emit('update:modelValue', value),
-};
-
-const decrease = () => {
-	bni.value?.decrease();
-};
-
-const increase = () => {
-	bni.value?.increase();
-};
-
-defineExpose({
-	increase,
-	decrease,
+import { ref } from 'vue';
+import { BbNumberInput } from 'bitboss-ui';
+
+const seats = ref<number | null>(12);
+const overCap = ref<number | null>(100);
+</script>
+```
+
+### Bounds & precision
+
+`min` and `max` clamp the **emitted** value — type past the ceiling and it
+settles back to `max` (defaults are the safe-integer bounds, i.e. effectively
+unbounded). `maxPrecision` caps the number of decimal places (default `8`),
+which is how you pin a field to whole numbers (`0`) or currency (`2`). Commas are
+accepted as the decimal separator and normalised to a period, so European
+keyboards work without configuration.
+
+**Clamped office setpoint, 16–28 °C**
+
+```vue
+<template>
+	<div class="grid max-w-sm gap-3 rounded-[var(--bb-radius)] border p-4">
+		<div>
+			<p class="text-sm font-medium">Office climate · Floor 3</p>
+			<p class="text-xs text-gray-500">
+				Clamped 16–28 °C · whole degrees only.
+			</p>
+		</div>
+		<BbNumberInput
+			v-model="temperature"
+			compact
+			hint="Between 16 and 28 °C."
+			label="Setpoint"
+			:max="28"
+			:max-precision="0"
+			:min="16"
+			name="setpoint"
+			persistent-hint
+			prepend:icon="lucide:thermometer"
+		>
+			<template #suffix>°C</template>
+		</BbNumberInput>
+	</div>
+</template>
+<script setup lang="ts">
+import { ref } from 'vue';
+import { BbNumberInput } from 'bitboss-ui';
+
+const temperature = ref<number | null>(21);
+</script>
+```
+
+### Step controls
+
+`step` (default `1`) is the increment applied by:
+
+- **keyboard stepping** — ArrowUp / ArrowDown while the field is focused;
+- the **`increase()` / `decrease()`** scope functions.
+
+Those functions are handed to the `prepend` / `append` / `prefix` / `suffix`
+slots as scope props, so you build a plus/minus stepper without wiring any state
+yourself. For a stepper rendered _outside_ the field, drive `v-model` directly
+(`model += step`) rather than reaching for a template ref. Stepping respects
+`min`/`max`/`maxPrecision` and is a no-op while `disabled` or `readonly`.
+
+Crucially, `step` is **not** applied to typed input — a `step` of `5` would
+otherwise stop someone typing `115` (it would round down) — so manual entry
+stays free while the buttons move in fixed increments.
+
+**Cart quantity with plus/minus steppers**
+
+```vue
+<template>
+	<div class="grid max-w-sm gap-2 rounded-[var(--bb-radius)] border p-3">
+		<div>
+			<p class="text-sm font-medium">USB-C Cable (2 m)</p>
+			<p class="text-xs text-gray-500">$12.50 each · 10 in stock</p>
+		</div>
+		<BbNumberInput
+			v-model="quantity"
+			compact
+			label="Quantity"
+			:max="10"
+			:max-precision="0"
+			:min="1"
+			name="quantity"
+		>
+			<template #prepend="{ decrease }">
+				<BbButton
+					aria-label="Decrease quantity"
+					icon="lucide:minus"
+					size="xs"
+					variant="ghost"
+					@click="decrease"
+				/>
+			</template>
+			<template #append="{ increase }">
+				<BbButton
+					aria-label="Increase quantity"
+					icon="lucide:plus"
+					size="xs"
+					variant="ghost"
+					@click="increase"
+				/>
+			</template>
+		</BbNumberInput>
+		<p class="text-sm font-medium">Subtotal: {{ formattedSubtotal }}</p>
+	</div>
+</template>
+<script setup lang="ts">
+import { ref, computed } from 'vue';
+import { BbNumberInput, BbButton } from 'bitboss-ui';
+
+const unitPrice = 12.5;
+const quantity = ref<number | null>(1);
+
+const formattedSubtotal = computed(() =>
+	new Intl.NumberFormat('en-US', {
+		style: 'currency',
+		currency: 'USD',
+	}).format((quantity.value ?? 0) * unitPrice)
+);
+</script>
+```
+
+### Currency & unit fields
+
+Combine `maxPrecision="2"`, `min="0"` and the `prefix` / `suffix` slots for money
+and measurement inputs. The affixes are inert decoration inside the field; the
+model stays a clean number.
+
+**Invoice unit price with currency affixes**
+
+```vue
+<template>
+	<div class="grid max-w-sm gap-3 rounded-[var(--bb-radius)] border p-4">
+		<div>
+			<p class="text-sm font-medium">Line item · INV-2048</p>
+			<p class="text-xs text-gray-500">
+				Currency stays in the chrome; the model is a clean number.
+			</p>
+		</div>
+		<BbNumberInput
+			v-model="price"
+			compact
+			label="Unit price"
+			:max-precision="2"
+			:min="0"
+			name="unit-price"
+			:step="0.5"
+		>
+			<template #prefix>$</template>
+			<template #suffix>USD</template>
+		</BbNumberInput>
+	</div>
+</template>
+<script setup lang="ts">
+import { ref } from 'vue';
+import { BbNumberInput } from 'bitboss-ui';
+
+const price = ref<number | null>(49.99);
+</script>
+```
+
+### Icons, affixes & slots
+
+`prepend:icon` / `append:icon` add iconography inside the field; the append
+position is shared with the status indicators by priority — **clear button →
+spinner (`loading`) → error icon (`hasErrors`) → your `append:icon`** — so don't
+count on `append:icon` showing on a `clearable` or validated field. The warning
+icon (`hasWarning`) shares the error icon's slot — shown when `hasWarning` is set
+and there is no error.
+
+Every content slot (`prefix`, `suffix`, `prepend`, `append`, `prepend-outer`,
+`append-outer`) receives `{ increase, decrease }` scope, so stepper buttons can
+live anywhere in the ring. Put interactive controls in the _outer_ slots or use
+the scoped callbacks; plain `prefix`/`suffix` text is decoration only.
+
+### Clearable & loading
+
+`clearable` shows a clear button while the field has a value and is
+hovered/focused; clicking it emits `update:modelValue` with `null` and is
+suppressed on `disabled`/`readonly`. `loading` shows a spinner in the append
+position and is visual only — the field stays editable, so guard the value
+yourself if an async check must settle first.
+
+**Clearable budget and async coupon check**
+
+```vue
+<template>
+	<div class="grid max-w-sm gap-3 rounded-[var(--bb-radius)] border p-4">
+		<div>
+			<p class="text-sm font-medium">Invoice credit</p>
+			<p class="text-xs text-gray-500">
+				Clear the budget anytime; coupon check is visual-only loading.
+			</p>
+		</div>
+		<BbNumberInput
+			v-model="budget"
+			clearable
+			compact
+			label="Budget"
+			:max-precision="2"
+			:min="0"
+			name="budget"
+		>
+			<template #prefix>$</template>
+		</BbNumberInput>
+		<BbNumberInput
+			v-model="coupon"
+			compact
+			:errors="couponError"
+			:hint="couponHint"
+			label="Coupon amount"
+			:loading="checking"
+			:max-precision="2"
+			:min="0"
+			name="coupon"
+			persistent-hint
+		>
+			<template #prefix>$</template>
+		</BbNumberInput>
+	</div>
+</template>
+<script setup lang="ts">
+import { ref, computed, watch } from 'vue';
+import { BbNumberInput } from 'bitboss-ui';
+
+const budget = ref<number | null>(2500);
+const coupon = ref<number | null>(50);
+const checking = ref(false);
+const couponError = ref('');
+
+const couponHint = computed(() =>
+	checking.value ? 'Checking availability…' : 'Applied to your next invoice.'
+);
+
+// `loading` is visual only — the field stays editable — so we settle the async
+// check ourselves and only surface an error once the deterministic timeout
+// resolves. A token guards against a stale check overwriting a newer one.
+const maxRedeemable = 200;
+let token = 0;
+watch(coupon, (value) => {
+	const current = ++token;
+	couponError.value = '';
+	checking.value = true;
+	setTimeout(() => {
+		if (current !== token) return;
+		checking.value = false;
+		couponError.value =
+			value !== null && value > maxRedeemable
+				? `Coupons are capped at $${maxRedeemable}.`
+				: '';
+	}, 700);
 });
 </script>
+```
+
+### Disabled & readonly
+
+`disabled` greys the field and blocks all interaction (`aria-disabled`);
+`readonly` keeps the value visible and copyable but not editable
+(`aria-readonly`). Both also disable `increase()` / `decrease()`. Prefer
+`readonly` for detected or derived numbers the user shouldn't change.
+
+**Error, disabled and readonly seats**
+
+```vue
+<template>
+	<div class="grid max-w-sm gap-3 rounded-[var(--bb-radius)] border p-4">
+		<div>
+			<p class="text-sm font-medium">Seat allocation</p>
+			<p class="text-xs text-gray-500">
+				Error, disabled, and readonly — same chrome, different affordances.
+			</p>
+		</div>
+		<BbNumberInput
+			v-model="qtyErr"
+			compact
+			errors="Only 10 in stock."
+			label="Quantity"
+			:max="10"
+			:max-precision="0"
+			:min="1"
+			name="qty-err"
+		/>
+		<BbNumberInput
+			compact
+			disabled
+			label="Allocated seats"
+			:max-precision="0"
+			:model-value="64"
+			name="allocated"
+		/>
+		<BbNumberInput
+			compact
+			label="Detected weight (kg)"
+			:max-precision="1"
+			:model-value="98.2"
+			name="detected-weight"
+			readonly
+		/>
+	</div>
+</template>
+<script setup lang="ts">
+import { ref } from 'vue';
+import { BbNumberInput } from 'bitboss-ui';
+
+const qtyErr = ref<number | null>(12);
+</script>
+```
+
+### Density & layout
 
-<style lang="postcss">
-@import './index.css';
-</style>
+`compact` reduces the control height — set it per view. `direction` works
+whenever the resolved label mode is `'outside'` (the config default), so
+`direction="horizontal"` lays the label beside the field out of the box. With
+`labelMode="floating"` or `"inside"` (prop or `config.defaultInputLabelMode`)
+the label is embedded in the field, so the layout is forced vertical and
+`direction` is ignored — same rule as `BbTextInput`/`BbSelect`/
+`BbDatePickerInput`.
+
+**Compact shipping package fields**
+
+```vue
+<template>
+	<div class="grid max-w-sm gap-3 rounded-[var(--bb-radius)] border p-3">
+		<div>
+			<p class="text-sm font-medium">Package · BOX-4412</p>
+			<p class="text-xs text-gray-500">
+				Shipping dimensions · compact density throughout.
+			</p>
+		</div>
+		<BbNumberInput
+			v-model="weight"
+			compact
+			label="Weight"
+			:max-precision="1"
+			:min="0"
+			name="weight"
+		>
+			<template #suffix>kg</template>
+		</BbNumberInput>
+		<BbNumberInput
+			v-model="units"
+			compact
+			label="Units in box"
+			:max-precision="0"
+			:min="1"
+			name="units"
+		/>
+	</div>
+</template>
+<script setup lang="ts">
+import { ref } from 'vue';
+import { BbNumberInput } from 'bitboss-ui';
+
+const weight = ref<number | null>(2.5);
+const units = ref<number | null>(12);
+</script>
 ```
 
-## Types
-
-```ts
-import type { HTMLAttributes, InputHTMLAttributes } from 'vue';
-import type { IconType } from '@/types/Icon';
-import type {
-	BaseNumberInputEvents,
-	BaseNumberInputSlots,
-} from '../BaseNumberInput/types';
-
-export type BbNumberInputProps = {
-	/**
-	 * Name of the icon to be added at the end of the input.
-	 */
-	// eslint-disable-next-line vue/prop-name-casing
-	'append:icon'?: IconType;
-	/**
-	 * Guides the browser as to the type of information expected in the field.
-	 */
-	autocomplete?: InputHTMLAttributes['autocomplete'];
-
-	/**
-	 * Sets autofocus on page load.
-	 */
-	autofocus?: InputHTMLAttributes['autofocus'];
-
-	/**
-	 * Displays a clear button when the input has a value and is being interacted with.
-	 */
-	clearable?: boolean;
-
-	/**
-	 * Sets the component in a compact state.
-	 */
-	compact?: boolean;
-
-	/**
-	 * Direction of the layout of the component. Can either be a predefined value or a pattern separated by a space like `xx xxxxx`.
-	 */
-	direction?: 'horizontal' | 'vertical' | 'auto' | string;
-
-	/**
-	 * Disables the component.
-	 */
-	disabled?: boolean;
-
-	/**
-	 * Can be a string or an array of string containing the messages to display.
-	 */
-	errors?: string | string[];
-
-	/**
-	 * Define if the component should be in an error state.
-	 * It usually attaches a CSS class for styling purposes.
-	 */
-	hasErrors?: boolean;
-
-	/**
-	 * Visually hides the label of the input while maintaining accessibility.
-	 */
-	hideLabel?: boolean;
-
-	/**
-	 * Text box to be displayed near the input, usually to indicate instructions.
-	 */
-	hint?: string;
-
-	/**
-	 * The identifier of the component.
-	 */
-	id?: HTMLAttributes['id'];
-
-	/**
-	 * Text content of the label of the element.
-	 */
-	label: string;
-
-	/**
-	 * Sets the text alignment of the label.
-	 */
-	labelPosition?: 'left' | 'center' | 'right';
-
-	/**
-	 * Sets the component in a loading state, usually triggering some visual styles.
-	 */
-	loading?: boolean;
-
-	/**
-	 * Maximum value cap.
-	 */
-	max?: number;
-
-	/**
-	 * Maximum precision of the number.
-	 */
-	maxPrecision?: number;
-
-	/**
-	 * Minimum value cap.
-	 */
-	min?: number;
-
-	/**
-	 * Used by v-model.
-	 */
-	modelValue: number | string | null;
-
-	/**
-	 * Defines the name of the input.
-	 */
-	name?: InputHTMLAttributes['name'];
-
-	/**
-	 * Keeps the hint displayed.
-	 */
-	persistentHint?: boolean;
-
-	/**
-	 * String displayed when there's no data.
-	 */
-	placeholder?: InputHTMLAttributes['placeholder'];
-
-	/**
-	 * Name of the icon to be added at the start of the input.
-	 */
-	// eslint-disable-next-line vue/prop-name-casing
-	'prepend:icon'?: IconType;
-
-	/**
-	 * Sets the input in a readonly state.
-	 */
-	readonly?: boolean;
-
-	/**
-	 * Sets the input as required.
-	 */
-	required?: boolean;
-
-	/**
-	 * Reverses the layout. Applicable in every direction the order of the label and the input is swapped.
-	 */
-	reverse?: boolean;
-
-	/**
-	 * Incremental unit used in the exposed `increase` and `decrease` functions.
-	 * 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.
-	 */
-	step?: number;
-};
-
-/** Re-export for consumers importing events type from BbNumberInput. */
-export type { BaseNumberInputEvents as BbNumberInputEvents };
-
-/** Props exposed by the `label` slot. */
-export type BbNumberInputLabelSlotProps = {
-	/** The `label` prop value. */
-	text: string;
-	/** Whether the input is in an error state. */
-	hasErrors: boolean;
-};
-
-export type BbNumberInputSlots = BaseNumberInputSlots & {
-	/**
-	 * Replaces the default label text rendered above the number input.
-	 */
-	label?: (props: BbNumberInputLabelSlotProps) => any;
-};
+Settings panels are where `direction="horizontal"` earns its keep: each numeric
+limit reads as one dense row — label left, value right — the way rate-limit or
+quota screens do it.
+
+**API rate limits settings card**
+
+```vue
+<template>
+	<div class="grid max-w-md gap-3 rounded-[var(--bb-radius)] border p-4">
+		<div>
+			<p class="text-sm font-medium">API rate limits</p>
+			<p class="text-xs text-gray-500">
+				Applied per key. Changes take effect immediately.
+			</p>
+		</div>
+		<BbNumberInput
+			v-model="requestsPerMinute"
+			compact
+			direction="horizontal"
+			label="Requests / min"
+			:max="10000"
+			:max-precision="0"
+			:min="10"
+			name="rpm"
+			:step="10"
+		/>
+		<BbNumberInput
+			v-model="burstLimit"
+			compact
+			direction="horizontal"
+			label="Burst limit"
+			:max="20000"
+			:max-precision="0"
+			:min="10"
+			name="burst"
+			:step="10"
+		/>
+		<BbNumberInput
+			v-model="timeoutSeconds"
+			compact
+			direction="horizontal"
+			label="Timeout"
+			:max="120"
+			:max-precision="0"
+			:min="1"
+			name="timeout"
+		>
+			<template #suffix>s</template>
+		</BbNumberInput>
+	</div>
+</template>
+<script setup lang="ts">
+import { ref } from 'vue';
+import { BbNumberInput } from 'bitboss-ui';
+
+const requestsPerMinute = ref<number | null>(500);
+const burstLimit = ref<number | null>(1000);
+const timeoutSeconds = ref<number | null>(30);
+</script>
 ```
 
-## Styles
-
-```css
-.bb-number-input {
-	&.bb-base-input-outer-container--errors {
-	}
-	&.bb-base-input-outer-container--hint {
-	}
-	.bb-base-input-container {
-		&--vertical {
-		}
-		&--horizontal {
-		}
-
-		&__label {
-			&--left {
-			}
-			&--center {
-			}
-			&--right {
-			}
-			&--hidden {
-			}
-		}
-		&__input {
-			&--left {
-			}
-			&--center {
-			}
-			&--right {
-			}
-
-			.bb-base-number-input {
-				display: inline-flex;
-				&--disabled {
-				}
-				&--errors {
-				}
-				&--loading {
-				}
-				&--readonly {
-				}
-
-				.bb-common-input-inner-container {
-					> input {
-					}
-
-					&__prepend-icon,
-					&__append-icon {
-					}
-					.bb-spinner {
-					}
-					.bb-error-icon {
-					}
-					&__prefix,
-					&__suffix {
-					}
-				}
-			}
-		}
-
-		&__hint-container {
-			.bb-base-input-container__hint {
-			}
-		}
-		&__errors {
-		}
-		&__error {
-		}
-	}
-}
+### Events & v-model
+
+- `update:modelValue` — `number` on any change, `null` when emptied. In-progress
+  non-numeric states (`.`, `-`, `12.`) do **not** emit a number; the field waits
+  until the value parses.
+- `increase` / `decrease` — fire with the **new** clamped number whenever a step
+  control runs (slot button or Arrow key), alongside `update:modelValue`.
+- `focus` / `blur` — forwarded, and drive the hint's show-on-focus behavior.
+- `input`, `change`, `keydown`, `keyup`, `click`, `mousedown`, `mouseup`,
+  `compositionstart`, `compositionend`, `paste` — all forwarded as-is (a fuller
+  set than `BbTextInput`, which doesn't forward keyup/paste/composition).
+
+### Global config & platforms
+
+- No size scale — `compact` is the density knob. `labelMode` falls back to
+  `config.defaultInputLabelMode` when unset, like `BbTextInput`.
+- Plain controlled input: SSR-safe in Nuxt, nothing teleported.
+- Inertia validation binds straight in:
+
+```vue
+<!-- Inertia: useForm drives value and errors -->
+<BbNumberInput
+	v-model="form.quantity"
+	label="Quantity"
+	:min="1"
+	:errors="form.errors.quantity"
+	:has-errors="!!form.errors.quantity"
+/>
 ```
+
+### Works well with
+
+- `BbSlider` — when a bounded number is better dragged than typed, or pair the
+  two on the same model for coarse + precise entry.
+- `BbTextInput` / `BbTextarea` / `BbDatePickerInput` — same chrome; mix in one
+  form (the `BbTextInput` invoice example composes all four).
+- `BbButton` — icon-only stepper buttons in the slot ring (give them an
+  `aria-label`).
+- `useToast` — confirm a save once the number is committed.
+
+### Gotchas & anti-patterns
+
+- `step` never constrains typed input — don't expect a `step` of `5` to force
+  multiples on manual entry; enforce that with `errors` on blur/submit.
+- The model can be `null` (empty) — write `value ?? 0` before arithmetic.
+- Don't rebuild parsing/clamping in a watcher; the component already sanitises,
+  clamps and limits precision.
+- Icon-only stepper buttons **require** an `aria-label`.
+- `direction` is ignored under `labelMode="floating"`/`"inside"` — those modes
+  embed the label in the field and force the vertical layout; it works with the
+  default `'outside'` mode.
+
+### Accessibility
+
+- The field carries `role="spinbutton"` and mirrors `min` / `max` / current
+  value into `aria-valuemin` / `aria-valuemax` / `aria-valuenow`, so keep `min`
+  and `max` set when the range is known.
+- ArrowUp / ArrowDown step the value natively — don't rebuild that with custom
+  key handlers.
+- `hasErrors` / non-empty `errors` set `aria-invalid`; `disabled` / `readonly`
+  set `aria-disabled` / `aria-readonly`.
+- Slot-based stepper buttons are icon-only, so they **require** an `aria-label`
+  (see the stepper example).
+
+## v-model
+
+- `v-model` — type: `string \| number \| null`
+
+## Props
+
+| Prop | Type | Default | Required | Description |
+| --- | --- | --- | --- | --- |
+| `append:icon` | `string \| undefined` |  |  | Name of the icon to be added at the end of the input. |
+| `autocomplete` | `string \| undefined` |  |  | Guides the browser as to the type of information expected in the field. |
+| `autofocus` | `Booleanish \| undefined` |  |  | Sets autofocus on page load. |
+| `clearable` | `boolean \| undefined` |  |  | Displays a clear button when the input has a value and is being interacted with. |
+| `compact` | `boolean \| undefined` |  |  | Sets the component in a compact state. |
+| `description` | `string \| undefined` |  |  | 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`. |
+| `direction` | `InputDirection \| undefined` |  |  | Direction of the layout of the component. Can either be a predefined value or a pattern separated by a space like `xx xxxxx`. |
+| `disabled` | `boolean \| undefined` |  |  | Disables the component. |
+| `errors` | `string \| string[] \| undefined` |  |  | Can be a string or an array of string containing the messages to display. |
+| `hasErrors` | `boolean \| undefined` |  |  | Define if the component should be in an error state. It usually attaches a CSS class for styling purposes. |
+| `hasWarning` | `boolean \| undefined` |  |  | Define if the component should be in a warning state. Same chrome as errors with `--bb-warn`; errors take priority. |
+| `hideLabel` | `boolean \| undefined` |  |  | Visually hides the label of the input while maintaining accessibility. |
+| `hint` | `string \| undefined` |  |  | Text box to be displayed near the input, usually to indicate instructions. |
+| `id` | `string \| undefined` |  |  | The identifier of the component. |
+| `label` | `string` |  | yes | Text content of the label of the element. |
+| `labelMode` | `"floating" \| "outside" \| "inside" \| undefined` |  |  | Label rendering mode. |
+| `labelPosition` | `"left" \| "center" \| "right" \| undefined` |  |  | Sets the text alignment of the label. |
+| `loading` | `boolean \| undefined` |  |  | Sets the component in a loading state, usually triggering some visual styles. |
+| `max` | `number \| undefined` |  |  | Maximum value cap. |
+| `maxPrecision` | `number \| undefined` |  |  | Maximum precision of the number. |
+| `min` | `number \| undefined` |  |  | Minimum value cap. |
+| `modelValue` | `string \| number \| null` | `null` | yes | Used by v-model. |
+| `name` | `string \| undefined` |  |  | Defines the name of the input. |
+| `persistentHint` | `boolean \| undefined` |  |  | Keeps the hint displayed. |
+| `placeholder` | `string \| undefined` |  |  | String displayed when there's no data. |
+| `prepend:icon` | `string \| undefined` |  |  | Name of the icon to be added at the start of the input. |
+| `readonly` | `boolean \| undefined` |  |  | Sets the input in a readonly state. |
+| `required` | `boolean \| undefined` |  |  | Sets the input as required. |
+| `reverse` | `boolean \| undefined` |  |  | Reverses the layout. Applicable in every direction the order of the label and the input is swapped. |
+| `step` | `number \| undefined` |  |  | Incremental unit used in the exposed `increase` and `decrease` functions. 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. |
+| `warnings` | `string \| string[] \| undefined` |  |  | Warning messages to display beneath the field, in their own `aria-live` region and amber (`--bb-warn`). A string or array; a non-empty list implies the warning state. Errors suppress warnings when both are set. |
+
+## Events
+
+- `blur` — `(event: "blur", event: FocusEvent): void`
+- `change` — `(event: "change", event: Event): void`
+- `click` — `(event: "click", event: MouseEvent): void`
+- `compositionend` — `(event: "compositionend", event: CompositionEvent): void`
+- `compositionstart` — `(event: "compositionstart", event: CompositionEvent): void`
+- `decrease` — `(event: "decrease", value: number): void`
+- `focus` — `(event: "focus", event: FocusEvent): void`
+- `increase` — `(event: "increase", value: number): void`
+- `input` — `(event: "input", event: Event): void`
+- `keydown` — `(event: "keydown", event: KeyboardEvent): void`
+- `keyup` — `(event: "keyup", event: KeyboardEvent): void`
+- `mousedown` — `(event: "mousedown", event: MouseEvent): void`
+- `mouseup` — `(event: "mouseup", event: MouseEvent): void`
+- `paste` — `(event: "paste", event: ClipboardEvent): void`
+- `update:modelValue` — `(event: "update:modelValue", value: number \| null): void`
+
+## Slots
+
+- `append` — scope: `BaseNumberInputStepSlotProps` — 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-outer` — scope: `BaseNumberInputStepSlotProps` — Content rendered after the entire input control, outside the input chrome.
+- `label` — scope: `BbNumberInputLabelSlotProps` — Replaces the default label text rendered above the number input.
+- `prefix` — scope: `BaseNumberInputStepSlotProps` — Inline content rendered at the start of the input field area, before the typed number.
+- `prepend` — scope: `BaseNumberInputStepSlotProps` — Content rendered before the number input, at the start of the inner container.
+- `prepend-outer` — scope: `BaseNumberInputStepSlotProps` — Content rendered before the entire input control, outside the input chrome.
+- `suffix` — scope: `BaseNumberInputStepSlotProps` — Inline content rendered at the end of the input field area, after the typed number.
+
+## Validated variant
+
+Importing this component from `bitboss-ui/validated` instead of `bitboss-ui` binds it to a vee-validate field. Same props, same events, same slots — plus the ones below. Requires the `vee-validate` peer dependency and a `<BbForm>` (or `useForm()`) ancestor. Full guide: [validated-forms](./guides/validated-forms.md).
+
+| Prop | Type | Description |
+| --- | --- | --- |
+| `rules` | `RuleExpression<string \| number \| null>` | vee-validate rules for this field. |
+| `validateOn` | `ValidateTiming[] \| undefined` | Which interactions trigger validation. Defaults are per-control (e.g. `['blur']` for text inputs, `['inactive']` for pickers/groups). |
+| `vid` | `string \| undefined` | Explicit vee-validate field name. **Usually omit it** — the name is derived automatically from the control's `label`/`legend`. Only set `vid` when that derivation wouldn't be unique (e.g. v-for rows, or array `v-model`s that share a label).… |
+
+## See Also
+
+- [BbTextInput](./BbTextInput.md) — Captures single-line text values.
+- [BbSlider](./BbSlider.md) — Selects numeric values across a bounded range.
+- [BbDatePickerInput](./BbDatePickerInput.md) — Combines date selection with text input behavior.