entasis 0.11.0 → 0.13.0

package/dist/components/Form/NumberInput/NumberInput.svelte

@@ -1,13 +1,27 @@
 <script lang="ts">
 	import { untrack } from 'svelte';
+	import type { Attachment } from 'svelte/attachments';
+	import { on } from 'svelte/events';
+	import Button from '../../Button/Button.svelte';
 	import { minusIcon } from '../../Icons/minus.js';
 	import { plusIcon } from '../../Icons/plus.js';
 	import Field from '../Field/Field.svelte';
-	import FieldActionButton from '../Field/FieldActionButton.svelte';
-	import { createFieldState } from '../Field/field.state.svelte.js';
-	import type { NumberInputProps } from './numberInput.props.js';
+	import FieldHiddenInputs from '../Field/FieldHiddenInputs.svelte';
+	import { useFieldTheme } from '../Field/field.theme.js';
+	import { createFieldState, type FieldValidatorResult } from '../Field/field.state.svelte.js';
+	import type { NumberInputCommitReason, NumberInputProps } from './numberInput.props.js';
 	import { useNumberInputTheme } from './numberInput.theme.js';
 	import { useI18n } from '../../../i18n/context.svelte.js';
+	import { composeHandlers } from '../../../utils/handlers.js';
+	import {
+		cleanFloatingPoint,
+		formatNumber,
+		hasRoundingOptions,
+		isNumberText,
+		parseNumber,
+		roundToFormat
+	} from '../../../utils/number.js';
+	import { usePressAndHold } from '../../../utils/usePressAndHold.svelte.js';
 
 	let {
 		defaultValue = null,
@@ -18,21 +32,46 @@
 		placeholder = '',
 		theme,
 		disabled,
+		readOnly,
+		messages,
 		name,
 		onValidate,
 		onValueChange,
+		onValueCommit,
 		visible,
 		min,
 		max,
 		step,
 		increment,
+		largeStep,
+		smallStep,
+		snapOnStep = false,
+		wheelStep = false,
 		showControls = true,
+		format,
+		locale,
+		inputAttrs,
 		...rest
 	}: NumberInputProps = $props();
 	const t = $derived(useI18n());
 	if (value === undefined) value = untrack(() => defaultValue);
 
 	const id = $props.id();
+	const activeLocale = $derived(locale ?? t.locale);
+	// Compact suffixes ("1.2K") cannot be read back, so entry always uses the standard notation.
+	const entryFormat = $derived<Intl.NumberFormatOptions | undefined>(
+		format?.notation === 'compact' ? { ...format, notation: 'standard' } : format
+	);
+	// Without a rounding option Intl shows at most three fraction digits; the value keeps its full
+	// precision, so the text must too.
+	const displayFormat = $derived<Intl.NumberFormatOptions>(
+		hasRoundingOptions(entryFormat)
+			? { ...entryFormat }
+			: { ...entryFormat, maximumFractionDigits: 20 }
+	);
+	const allowNegative = $derived(min === undefined || min < 0);
+
+	const formatValue = (number: number | null) => formatNumber(number, activeLocale, displayFormat);
 
 	const field = createFieldState({
 		id,
@@ -61,6 +100,12 @@
 		set disabled(v: boolean | undefined) {
 			disabled = v;
 		},
+		get readOnly() {
+			return readOnly;
+		},
+		get messages() {
+			return messages;
+		},
 		get required() {
 			return required;
 		},
@@ -70,13 +115,13 @@
 		set name(v: string | undefined) {
 			name = v;
 		},
-		onValidate: (val) => {
+		onValidate: (val): FieldValidatorResult => {
 			if (typeof val === 'number') {
 				if (min !== undefined && val < min) {
-					return true;
+					return field.messages.rangeUnderflow(formatValue(min));
 				}
 				if (max !== undefined && val > max) {
-					return true;
+					return field.messages.rangeOverflow(formatValue(max));
 				}
 			}
 			return onValidate?.(val) || false;
@@ -88,59 +133,299 @@
 	});
 
 	const classes = $derived(useNumberInputTheme(theme));
+	const fieldClasses = $derived(useFieldTheme());
 
-	const configuredIncrement = $derived(increment ?? step ?? 1);
-	const buttonIncrement = $derived(
-		Number.isFinite(configuredIncrement) && configuredIncrement !== 0
-			? Math.abs(configuredIncrement)
-			: 1
-	);
 	const numericValue = $derived(
 		typeof field.value === 'number' && Number.isFinite(field.value) ? field.value : null
 	);
+
+	// The text the input shows. It follows the user's typing as typed, and the value otherwise.
+	let inputText = $state(untrack(() => formatValue(numericValue)));
+	let inputFocused = $state(false);
+	// Typed text that has not been committed (formatted, rounded and reported) yet.
+	let textEdited = false;
+
+	const parseText = (text: string): number | null =>
+		text.trim() === '' ? null : parseNumber(text, activeLocale, entryFormat);
+
+	// A value that changes from outside replaces the text; typing publishes the parsed value, which
+	// then matches the text and leaves it alone.
+	$effect.pre(() => {
+		const next = numericValue;
+		untrack(() => {
+			if (!Object.is(parseText(inputText), next)) {
+				inputText = formatValue(next);
+				textEdited = false;
+			}
+		});
+	});
+	// The text follows a locale or format change, except while it is being typed.
+	$effect.pre(() => {
+		void activeLocale;
+		void displayFormat;
+		untrack(() => {
+			if (!inputFocused) inputText = formatValue(numericValue);
+		});
+	});
+
+	const sanitizeStep = (candidate: number | undefined, fallback: number) =>
+		typeof candidate === 'number' && Number.isFinite(candidate) && candidate !== 0
+			? Math.abs(candidate)
+			: fallback;
+	const baseStep = $derived(sanitizeStep(increment ?? step, 1));
+	const largeAmount = $derived(sanitizeStep(largeStep, baseStep * 10));
+	const smallAmount = $derived(sanitizeStep(smallStep, cleanFloatingPoint(baseStep / 10)));
+
+	const locked = $derived(field.disabled || field.readOnly);
 	const canDecrement = $derived(
-		!field.disabled && (numericValue === null || min === undefined || numericValue > min)
+		!locked && (numericValue === null || min === undefined || numericValue > min)
 	);
 	const canIncrement = $derived(
-		!field.disabled && (numericValue === null || max === undefined || numericValue < max)
+		!locked && (numericValue === null || max === undefined || numericValue < max)
 	);
 
-	const countDecimalPlaces = (value: number) => {
-		const valueText = String(value);
-		if (valueText.includes('e-')) {
-			return Number(valueText.split('e-')[1]) || 0;
-		}
-		return valueText.split('.')[1]?.length ?? 0;
+	// Whole, non-negative numbers get the digit pad; anything else needs the decimal point or sign.
+	const inputMode = $derived<'decimal' | 'numeric'>(
+		min !== undefined && min >= 0 && entryFormat?.maximumFractionDigits === 0
+			? 'numeric'
+			: 'decimal'
+	);
+
+	const countDecimalPlaces = (number: number) => {
+		const text = String(number);
+		if (text.includes('e-')) return Number(text.split('e-')[1]) || 0;
+		return text.split('.')[1]?.length ?? 0;
 	};
 
-	const clampValue = (nextValue: number) => {
-		if (min !== undefined && nextValue < min) return min;
-		if (max !== undefined && nextValue > max) return max;
-		return nextValue;
+	const clampValue = (number: number) => {
+		if (min !== undefined && number < min) return min;
+		if (max !== undefined && number > max) return max;
+		return number;
 	};
 
-	const roundToIncrementPrecision = (baseValue: number, nextValue: number) => {
+	const computeStep = (base: number, direction: 1 | -1, amount: number) => {
+		let next: number;
+		const origin = min ?? 0;
+		if (snapOnStep) {
+			const position = (base - origin) / amount;
+			const tolerance = 1e-9;
+			const index =
+				direction > 0 ? Math.floor(position + tolerance) + 1 : Math.ceil(position - tolerance) - 1;
+			next = origin + index * amount;
+		} else {
+			next = base + direction * amount;
+		}
 		const precision = Math.min(
-			Math.max(countDecimalPlaces(buttonIncrement), countDecimalPlaces(baseValue)),
+			Math.max(
+				countDecimalPlaces(amount),
+				countDecimalPlaces(base),
+				snapOnStep ? countDecimalPlaces(origin) : 0
+			),
 			12
 		);
-		return Number(nextValue.toFixed(precision));
+		return clampValue(Number(next.toFixed(precision)));
 	};
 
-	const getEmptyBaseValue = (direction: 1 | -1) => {
-		if (direction > 0 && min !== undefined) return min - buttonIncrement;
-		if (direction < 0 && max !== undefined) return max + buttonIncrement;
+	const emptyBase = (direction: 1 | -1, amount: number) => {
+		if (direction > 0 && min !== undefined) return min - amount;
+		if (direction < 0 && max !== undefined) return max + amount;
 		return 0;
 	};
 
-	const changeValue = (direction: 1 | -1) => {
-		if (field.disabled) return;
+	/** Moves the value one step; returns whether it moved and whether it cannot move further. */
+	const stepValue = (direction: 1 | -1, amount: number) => {
+		if (locked) return { changed: false, atBound: true };
+		const next = computeStep(numericValue ?? emptyBase(direction, amount), direction, amount);
+		const changed = !Object.is(next, numericValue);
+		setNumber(next);
+		const atBound =
+			direction > 0 ? max !== undefined && next >= max : min !== undefined && next <= min;
+		return { changed, atBound };
+	};
+
+	/** Publishes `next` and shows it formatted. */
+	const setNumber = (next: number | null) => {
+		field.setValue(next);
+		inputText = formatValue(numericValue);
+		textEdited = false;
+	};
+
+	const emitCommit = (reason: NumberInputCommitReason) =>
+		onValueCommit?.({ value: numericValue, reason });
+
+	/** Formats, rounds and reports the typed text. */
+	const commitText = (reason: NumberInputCommitReason) => {
+		if (!textEdited) return;
+		textEdited = false;
+		const parsed = parseText(inputText);
+		if (parsed === null) {
+			// Empty clears the value; leftovers such as "-" go back to the value they never changed.
+			if (inputText.trim() === '') field.setValue(null);
+			inputText = formatValue(numericValue);
+		} else {
+			const rounded = roundToFormat(parsed, entryFormat);
+			if (!Object.is(rounded, numericValue)) field.setValue(rounded);
+			inputText = formatValue(numericValue);
+		}
+		emitCommit(reason);
+	};
+
+	const applyInputText = (input: HTMLInputElement) => {
+		const text = input.value;
+		if (text === inputText) return;
+		if (locked || !isNumberText(text, activeLocale, entryFormat, { allowNegative })) {
+			// Refused characters leave the text, and the caret, where they were.
+			const caret = Math.max(
+				0,
+				(input.selectionStart ?? text.length) - (text.length - inputText.length)
+			);
+			input.value = inputText;
+			input.setSelectionRange(caret, caret);
+			return;
+		}
+		inputText = text;
+		textEdited = true;
+		const parsed = parseText(text);
+		// Only text that is a complete number is published; "-" or "1e" wait for more typing.
+		if (parsed !== null || text.trim() === '') field.setValue(parsed);
+	};
 
-		const baseValue = numericValue ?? getEmptyBaseValue(direction);
-		field.value = clampValue(
-			roundToIncrementPrecision(baseValue, baseValue + direction * buttonIncrement)
+	const handleInput = (event: Event & { currentTarget: HTMLInputElement }) => {
+		// An input method owns the text until compositionend.
+		if ((event as unknown as InputEvent).isComposing) return;
+		applyInputText(event.currentTarget);
+	};
+
+	const handleCompositionEnd = (event: Event & { currentTarget: HTMLInputElement }) =>
+		applyInputText(event.currentTarget);
+
+	const handlePaste = (event: ClipboardEvent & { currentTarget: HTMLInputElement }) => {
+		const input = event.currentTarget;
+		const pasted = (event.clipboardData?.getData('text/plain') ?? '').trim();
+		event.preventDefault();
+		if (
+			locked ||
+			pasted === '' ||
+			!isNumberText(pasted, activeLocale, entryFormat, { allowNegative })
+		) {
+			return;
+		}
+		const start = input.selectionStart ?? input.value.length;
+		const end = input.selectionEnd ?? start;
+		input.setRangeText(pasted, start, end, 'end');
+		applyInputText(input);
+	};
+
+	const handleKeydown = (event: KeyboardEvent & { currentTarget: HTMLInputElement }) => {
+		if (event.isComposing || event.ctrlKey || event.metaKey) return;
+		switch (event.key) {
+			case 'ArrowUp':
+			case 'ArrowDown':
+			case 'PageUp':
+			case 'PageDown': {
+				if (locked) return;
+				event.preventDefault();
+				const direction = event.key === 'ArrowUp' || event.key === 'PageUp' ? 1 : -1;
+				const amount =
+					event.key.startsWith('Page') || event.shiftKey
+						? largeAmount
+						: event.altKey
+							? smallAmount
+							: baseStep;
+				// Typed text is committed by the step: it steps from the number it holds.
+				stepValue(direction, amount);
+				emitCommit('keyboard');
+				return;
+			}
+			case 'Home':
+			case 'End': {
+				const bound = event.key === 'Home' ? min : max;
+				if (locked || bound === undefined) return;
+				event.preventDefault();
+				setNumber(bound);
+				emitCommit('keyboard');
+				return;
+			}
+			case 'Enter':
+				// Formats what was typed; the Form still sees the key and moves on or submits.
+				commitText('keyboard');
+		}
+	};
+
+	const handleFocus = () => {
+		inputFocused = true;
+		field.focused = true;
+	};
+
+	const handleBlur = () => {
+		inputFocused = false;
+		field.focused = false;
+		commitText('blur');
+	};
+
+	const inputElement = () => (field.node instanceof HTMLInputElement ? field.node : null);
+
+	// Wheel steps are opt in: otherwise the wheel scrolls the page, even over a focused input.
+	const wheel: Attachment<HTMLInputElement> = (node) => {
+		if (!wheelStep) return;
+		return on(
+			node,
+			'wheel',
+			(event) => {
+				const root = node.getRootNode() as Document | ShadowRoot;
+				if (root.activeElement !== node || locked) return;
+				const vertical = Math.abs(event.deltaY) > Math.abs(event.deltaX);
+				// A horizontal gesture steps only with Shift; a trackpad's sideways drift never does.
+				if (!vertical && !event.shiftKey) return;
+				const delta = vertical ? event.deltaY : event.deltaX;
+				if (delta === 0) return;
+				event.preventDefault();
+				stepValue(delta < 0 ? 1 : -1, baseStep);
+				emitCommit('wheel');
+			},
+			{ passive: false }
 		);
 	};
+
+	// Pressing a stepper keeps the caret where it is: focus stays in (or moves to) the input, so
+	// the arrow keys keep working after a click.
+	const keepInputFocus: Attachment<HTMLElement> = (node) => {
+		const offs = [
+			on(node, 'mousedown', (event) => event.preventDefault()),
+			on(node, 'pointerdown', (event) => {
+				// A touch press would raise the on-screen keyboard.
+				if (event.button !== 0 || event.pointerType === 'touch' || locked) return;
+				inputElement()?.focus({ preventScroll: true });
+			})
+		];
+		return () => offs.forEach((off) => off());
+	};
+
+	const createStepper = (direction: 1 | -1) => {
+		let stepped = false;
+		const hold = usePressAndHold({
+			onStep: () => {
+				const result = stepValue(direction, baseStep);
+				if (result.changed) stepped = true;
+				return !result.atBound;
+			},
+			disabled: () => locked,
+			// One commit for the whole press, when it ends.
+			onStop: () => {
+				if (!stepped) return;
+				stepped = false;
+				emitCommit('step');
+			}
+		});
+		const onclick = (event: MouseEvent) => {
+			if (hold.shouldSkipClick(event)) return;
+			// Keyboard and assistive-technology activation, and a quick touch tap.
+			if (stepValue(direction, baseStep).changed) emitCommit('step');
+		};
+		return { hold, onclick };
+	};
+	const decrementer = createStepper(-1);
+	const incrementer = createStepper(1);
 </script>
 
 <Field
@@ -161,34 +446,68 @@
 >
 	<input
 		data-1p-ignore
-		type="number"
+		autocomplete="off"
+		autocorrect="off"
+		spellcheck="false"
+		{...inputAttrs}
+		type="text"
+		role="spinbutton"
+		inputmode={inputAttrs?.inputmode ?? inputMode}
 		{id}
-		name={field.name}
-		bind:value={field.value}
 		bind:this={field.node}
+		{@attach wheel}
+		value={inputText}
 		{placeholder}
-		{min}
-		{max}
-		{step}
 		disabled={field.disabled}
+		aria-required={field.required || undefined}
+		aria-readonly={field.readOnly || undefined}
+		aria-valuenow={numericValue ?? undefined}
+		aria-valuemin={min}
+		aria-valuemax={max}
+		aria-valuetext={numericValue === null ? undefined : inputText}
 		class={classes.input({ disabled: field.disabled, size: rest.size })}
+		oninput={composeHandlers(inputAttrs?.oninput, handleInput)}
+		oncompositionend={composeHandlers(inputAttrs?.oncompositionend, handleCompositionEnd)}
+		onpaste={composeHandlers(inputAttrs?.onpaste, handlePaste)}
+		onkeydown={composeHandlers(inputAttrs?.onkeydown, handleKeydown)}
+		onfocus={composeHandlers(inputAttrs?.onfocus, handleFocus)}
+		onblur={composeHandlers(inputAttrs?.onblur, handleBlur)}
 	/>
+	<!-- The visible text is formatted for the locale; a native form posts the plain number. -->
+	<FieldHiddenInputs {field} value={numericValue} />
 	{#if showControls}
 		<div class="flex shrink-0 items-stretch gap-0.5 self-stretch">
-			<FieldActionButton
+			<Button
+				variant="ghost"
+				color="neutral"
 				size={rest.size}
-				edge="none"
+				type="button"
+				squared
+				tabindex={-1}
+				controls={id}
 				label={`${t.decrease} ${t.value}`}
 				disabled={!canDecrement}
 				prefix={minusIcon}
-				onclick={() => changeValue(-1)}
+				class={fieldClasses.actionButton({ size: rest.size, edge: 'none' })}
+				onclick={decrementer.onclick}
+				{@attach decrementer.hold.attachment}
+				{@attach keepInputFocus}
 			/>
-			<FieldActionButton
+			<Button
+				variant="ghost"
+				color="neutral"
 				size={rest.size}
+				type="button"
+				squared
+				tabindex={-1}
+				controls={id}
 				label={`${t.increase} ${t.value}`}
 				disabled={!canIncrement}
 				prefix={plusIcon}
-				onclick={() => changeValue(1)}
+				class={fieldClasses.actionButton({ size: rest.size, edge: 'end' })}
+				onclick={incrementer.onclick}
+				{@attach incrementer.hold.attachment}
+				{@attach keepInputFocus}
 			/>
 		</div>
 	{/if}

package/dist/components/Form/NumberInput/index.d.ts

@@ -1,3 +1,3 @@
 export { default as NumberInput } from './NumberInput.svelte';
-export type { NumberInputProps } from './numberInput.props.js';
+export type { NumberInputCommitDetail, NumberInputCommitReason, NumberInputInputAttributes, NumberInputProps } from './numberInput.props.js';
 export { numberInputTheme, setNumberInputTheme, useNumberInputTheme, type NumberInputTheme, type NumberInputThemeProps } from './numberInput.theme.js';

package/dist/components/Form/NumberInput/numberInput.mcp.d.ts

@@ -1 +1 @@
-export declare const numberInputDescription = "\n# NumberInput Component\n\nThe NumberInput component is a numeric input field with +/- controls, min/max validation, and formatting options.\n\n## Basic Usage\n\n```svelte\n<script>\n\tlet quantity = $state(1);\n</script>\n\n<NumberInput label=\"Quantity\" bind:value={quantity} />\n```\n\n## Props\n\nExtends all Field component props plus:\n\n### Core Props\n- **value**: number (bindable) - Input value\n- **min**: number - Minimum allowed value\n- **max**: number - Maximum allowed value\n- **step**: number - Native number input step for keyboard and browser interactions\n- **increment**: number (default: step ?? 1) - Amount changed by the +/- buttons\n- **showControls**: boolean (default: true) - Whether to render the +/- buttons\n\n### Display Props\n- **placeholder**: string - Placeholder text\n\n### Field Props (inherited)\n- **label**: string | Snippet - Field label\n- **description**: string | Snippet - Helper text\n- **error**: string - Error message\n- **required**: boolean - Mark as required\n- **disabled**: boolean - Disable input\n- **size**: 'small' | 'normal' | 'large' - Input size\n\n### Content Slots\n- **prefix**: Snippet - Content before input (e.g., currency symbol)\n- **suffix**: Snippet - Content after input (e.g., unit)\n\n### Styling Props\n- **class**: string - Additional CSS classes\n- **theme**: ComponentTheme - Custom theme overrides\n\n## Structure\n\n```\n<Field>\n\t<Label />\n\t<Description />\n\t<InputContainer>\n\t\t<Prefix />\n\t\t<Input type=\"number\" />\n\t\t<Controls>\n\t\t\t<Button label=\"Decrease value\" />\n\t\t\t<Button label=\"Increase value\" />\n\t\t</Controls>\n\t\t<Suffix />\n\t</InputContainer>\n\t<Error />\n</Field>\n```\n\n## Examples\n\n### Basic Number Input\n```svelte\n<script>\n\tlet age = $state(25);\n</script>\n\n<NumberInput label=\"Age\" bind:value={age} />\n```\n\n### With Min and Max\n```svelte\n<NumberInput \n\tlabel=\"Quantity\"\n\tbind:value={quantity}\n\tmin={1}\n\tmax={100}\n/>\n```\n\n### With Step and Button Increment\n```svelte\n<NumberInput \n\tlabel=\"Price\"\n\tbind:value={price}\n\tstep={0.01}\n\tincrement={1}\n\tmin={0}\n/>\n```\n\n### Custom Button Increment\n```svelte\n<NumberInput \n\tlabel=\"Quantity\"\n\tbind:value={quantity}\n\tincrement={5}\n/>\n```\n\n### With Prefix (Currency)\n```svelte\n<NumberInput \n\tlabel=\"Amount\"\n\tbind:value={amount}\n\tmin={0}\n\tstep={0.01}\n>\n\t{#snippet prefix()}\n\t\t<span>$</span>\n\t{/snippet}\n</NumberInput>\n```\n\n### With Suffix (Unit)\n```svelte\n<NumberInput \n\tlabel=\"Weight\"\n\tbind:value={weight}\n\tmin={0}\n>\n\t{#snippet suffix()}\n\t\t<span>kg</span>\n\t{/snippet}\n</NumberInput>\n```\n\n### Required Field\n```svelte\n<NumberInput \n\tlabel=\"Number of Guests\"\n\tbind:value={guests}\n\tmin={1}\n\trequired\n/>\n```\n\n### Disabled State\n```svelte\n<NumberInput \n\tlabel=\"Score\"\n\tvalue={100}\n\tdisabled\n/>\n```\n\n### Product Quantity Selector\n```svelte\n<script>\n\tlet quantity = $state(1);\n\tlet price = 29.99;\n\t\n\tconst total = $derived(quantity * price);\n</script>\n\n<div>\n\t<NumberInput \n\t\tlabel=\"Quantity\"\n\t\tbind:value={quantity}\n\t\tmin={1}\n\t\tmax={10}\n\t\tdescription={`Total: $${total.toFixed(2)}`}\n\t/>\n</div>\n```\n\n### Age Input\n```svelte\n<NumberInput \n\tlabel=\"Age\"\n\tbind:value={age}\n\tmin={18}\n\tmax={120}\n\tdescription=\"You must be 18 or older\"\n\trequired\n/>\n```\n\n### Temperature Control\n```svelte\n<NumberInput \n\tlabel=\"Temperature\"\n\tbind:value={temperature}\n\tmin={-10}\n\tmax={40}\n\tstep={0.5}\n>\n\t{#snippet suffix()}\n\t\t<span>\u00B0C</span>\n\t{/snippet}\n</NumberInput>\n```\n\n### Percentage Input\n```svelte\n<NumberInput \n\tlabel=\"Discount\"\n\tbind:value={discount}\n\tmin={0}\n\tmax={100}\n\tstep={5}\n>\n\t{#snippet suffix()}\n\t\t<span>%</span>\n\t{/snippet}\n</NumberInput>\n```\n\n### Rating Input\n```svelte\n<NumberInput \n\tlabel=\"Rating\"\n\tbind:value={rating}\n\tmin={1}\n\tmax={5}\n\tstep={0.5}\n\tdescription=\"Rate from 1 to 5 stars\"\n/>\n```\n\n## Validation\n\nNumberInput automatically validates:\n- **min**: Value must be >= min\n- **max**: Value must be <= max\n- **step**: Value must align with step increments\n- **required**: Non-null value\n\n## Keyboard Controls\n\n- **Arrow Up**: Increment by step\n- **Arrow Down**: Decrement by step\n- **Page Up**: Increment by step * 10\n- **Page Down**: Decrement by step * 10\n\n## Accessibility\n\n- Proper label association\n- ARIA attributes for min, max, and current value\n- Keyboard navigation support\n- Screen reader announcements for value changes\n- Control buttons are focusable and keyboard accessible\n\n## Notes\n\n- Native HTML number input for best compatibility\n- +/- controls provide visual increment/decrement\n- Automatically respects min/max bounds\n- Supports decimal values with step\n- Can be styled with prefix/suffix for units\n\n## Theme Customization\n\nThe NumberInput component uses a theme object that can be customized using the `theme` prop or by setting a global theme.\n\n### Theme Structure\n\nThe theme object contains the following parts:\n- **input**: Input element styles\n- **inputContainer**: Input container wrapper styles\n\n### Available Variants\n\n**input**:\n- base: Base classes applied to the input element\n- Variants:\n  - size: 'small' | 'normal' | 'large' - Text size\n  - disabled: boolean - Disabled state styling\n\n**inputContainer**:\n- base: Base classes for the input container (handles focus states, borders, padding)\n- Variants:\n  - size: 'small' | 'normal' | 'large' - Container height and size-based styling\n  - disabled: boolean - Disabled state styling\n\n### Usage Examples\n\n**Basic Theme Override**:\n```svelte\n<NumberInput \n  label=\"Quantity\"\n  bind:value={quantity}\n  theme={{\n    inputContainer: {\n      base: 'border-2 rounded-lg',\n      size: {\n        normal: 'h-8 px-4'\n      }\n    },\n    input: {\n      size: {\n        normal: 'text-base'\n      }\n    }\n  }}\n/>\n```\n\n**Focus State Customization**:\n\nTo recolor every focus ring in the app at once, set `designTokens.focusColor` on `Theme`\ninstead of overriding per component. `ring-focus` is the focus state role and falls back to the\ncurrent role, so it never hard-pins a color.\n\n```svelte\n<NumberInput \n  label=\"Custom Number\"\n  bind:value={value}\n  theme={{\n    inputContainer: {\n      base: 'focus-within:ring-2 focus-within:ring-focus/50 focus-within:border-focus'\n    }\n  }}\n/>\n```\n\n**Global Theme Setting**:\n```svelte\n<script>\n  import { setNumberInputTheme } from './index.ts';\n  \n  setNumberInputTheme({\n    inputContainer: {\n      base: 'rounded-lg border-2 transition-all',\n      size: {\n        normal: 'h-8 px-4'\n      }\n    },\n    input: {\n      base: 'text-right'\n    }\n  });\n</script>\n```\n\n## State contract\n\n- **value**: current bindable editable value.\n- **defaultValue**: initial value used only when `value` is omitted.\n- **onValueChange**: called with the new value when the component changes it.\n\n";
+export declare const numberInputDescription = "\n# NumberInput Component\n\nThe NumberInput component is a locale-aware numeric input: a text input that reads and shows numbers the way the user writes them (`1 234,5`, `\u0661\u0662\u0663\u066B\u0664`, `R$ 12,50`), with +/- steppers, keyboard stepping, min/max validation, and a hidden input that posts the plain number to a native form.\n\n## Basic Usage\n\n```svelte\n<script>\n\tlet quantity = $state(1);\n</script>\n\n<NumberInput label=\"Quantity\" bind:value={quantity} />\n```\n\n## Props\n\nExtends all Field component props plus:\n\n### Core Props\n- **value**: number | null (bindable) - Input value. Only text that is a complete number is published: `-` or `.` while typing leave the value as it was, an emptied input is `null`.\n- **min**: number - Minimum allowed value. Stepping stops there; a typed lower value is kept and reports a range error. A non-negative minimum refuses the minus sign.\n- **max**: number - Maximum allowed value. Stepping stops there; a typed higher value is kept and reports a range error.\n- **step**: number (default: 1) - Size of one step by the arrow keys, the +/- buttons and the wheel\n- **increment**: number - Alias of step that wins when both are set\n- **largeStep**: number (default: 10 x step) - Step of Shift+Arrow, PageUp and PageDown\n- **smallStep**: number (default: step / 10) - Step of Alt+Arrow\n- **snapOnStep**: boolean (default: false) - Snap the value to the step grid (counted from min, else 0) when stepping, before clamping: 7 with a step of 5 moves to 10. Without it a step adds or subtracts the step.\n- **wheelStep**: boolean (default: false) - Step with the mouse wheel while the input is focused and hovered (vertical scroll, or horizontal with Shift). The wheel never changes the value otherwise.\n- **showControls**: boolean (default: true) - Whether to render the +/- buttons\n- **format**: Intl.NumberFormatOptions - Currency, percent and unit styles, fraction digits, grouping. The value is shown formatted on blur. Without a rounding option the value keeps its full precision; with one (maximumFractionDigits, maximumSignificantDigits...) the committed value is rounded the way the text is. Compact notation is not supported for entry.\n- **locale**: string (default: the i18n catalog locale) - BCP 47 locale of the shown and parsed text. Digits of other numeral systems (Arabic-Indic, Persian, Devanagari, Bengali, Thai, full-width, Han) are read in any locale.\n- **onValueCommit**: ({ value, reason }) => void - Called when an edit ends. reason is 'blur' (typed text committed on blur), 'keyboard' (Enter on typed text, and each arrow, Page or Home/End step), 'wheel' (each wheel step) or 'step' (release of a stepper button: one call for a whole press-and-hold). A blur without typing reports nothing.\n- **inputAttrs**: native attributes of the text input (autocomplete, aria-label, aria-roledescription, inputmode, data-*, event handlers). Consumer handlers run before the built-in ones, and preventDefault cancels the built-in behaviour. The component keeps the role, value, type and form attributes.\n\n### Display Props\n- **placeholder**: string - Placeholder text\n\n### Field Props (inherited)\n- **label**: string | Snippet - Field label\n- **description**: string | Snippet - Helper text\n- **error**: string - Error message\n- **required**: boolean - Mark as required\n- **disabled**: boolean - Disable input\n- **readOnly**: boolean - Focusable and announced as read-only; typing, pasting, stepping and the wheel are refused, and the value still validates and submits\n- **name**: string - Posted by a hidden input as the plain number (`1234.5`), not the formatted text; an empty or disabled input posts nothing\n- **size**: 'small' | 'normal' | 'large' - Input size\n\n### Content Slots\n- **prefix**: Snippet - Content before input (e.g., currency symbol)\n- **suffix**: Snippet - Content after input (e.g., unit)\n\n### Styling Props\n- **class**: string - Additional CSS classes\n- **theme**: ComponentTheme - Custom theme overrides\n\n## Structure\n\n```\n<Field>\n\t<Label />\n\t<Description />\n\t<InputContainer>\n\t\t<Prefix />\n\t\t<Input type=\"text\" role=\"spinbutton\" inputmode=\"decimal\" />\n\t\t<HiddenInput type=\"hidden\" name />\n\t\t<Controls>\n\t\t\t<Button label=\"Decrease value\" tabindex=\"-1\" />\n\t\t\t<Button label=\"Increase value\" tabindex=\"-1\" />\n\t\t</Controls>\n\t\t<Suffix />\n\t</InputContainer>\n\t<Error />\n</Field>\n```\n\n## Examples\n\n### Basic Number Input\n```svelte\n<script>\n\tlet age = $state(25);\n</script>\n\n<NumberInput label=\"Age\" bind:value={age} />\n```\n\n### With Min and Max\n```svelte\n<NumberInput \n\tlabel=\"Quantity\"\n\tbind:value={quantity}\n\tmin={1}\n\tmax={100}\n/>\n```\n\n### Locale, currency and percent\n```svelte\n<NumberInput label=\"Prix\" locale=\"fr\" format={{ style: 'currency', currency: 'EUR' }} bind:value={price} />\n<NumberInput label=\"Discount\" format={{ style: 'percent', maximumFractionDigits: 0 }} step={0.01} bind:value={discount} />\n```\n\n`1 234,5` typed in a French input publishes 1234.5; a percent of `12.7` rounds to 13% (the value 0.13) on blur.\n\n### Large steps and snapping\n```svelte\n<NumberInput label=\"Seats\" bind:value={seats} step={5} largeStep={50} snapOnStep min={0} />\n```\n\n### Native form\n```svelte\n<form method=\"POST\">\n\t<NumberInput name=\"amount\" locale=\"de\" value={1234.5} />\n</form>\n<!-- posts amount=1234.5 -->\n```\n\n### Custom Button Increment\n```svelte\n<NumberInput \n\tlabel=\"Quantity\"\n\tbind:value={quantity}\n\tincrement={5}\n/>\n```\n\n### With Prefix (Currency)\n```svelte\n<NumberInput \n\tlabel=\"Amount\"\n\tbind:value={amount}\n\tmin={0}\n\tstep={0.01}\n>\n\t{#snippet prefix()}\n\t\t<span>$</span>\n\t{/snippet}\n</NumberInput>\n```\n\n### With Suffix (Unit)\n```svelte\n<NumberInput \n\tlabel=\"Weight\"\n\tbind:value={weight}\n\tmin={0}\n>\n\t{#snippet suffix()}\n\t\t<span>kg</span>\n\t{/snippet}\n</NumberInput>\n```\n\n### Required Field\n```svelte\n<NumberInput \n\tlabel=\"Number of Guests\"\n\tbind:value={guests}\n\tmin={1}\n\trequired\n/>\n```\n\n### Disabled State\n```svelte\n<NumberInput \n\tlabel=\"Score\"\n\tvalue={100}\n\tdisabled\n/>\n```\n\n### Product Quantity Selector\n```svelte\n<script>\n\tlet quantity = $state(1);\n\tlet price = 29.99;\n\t\n\tconst total = $derived(quantity * price);\n</script>\n\n<div>\n\t<NumberInput \n\t\tlabel=\"Quantity\"\n\t\tbind:value={quantity}\n\t\tmin={1}\n\t\tmax={10}\n\t\tdescription={`Total: $${total.toFixed(2)}`}\n\t/>\n</div>\n```\n\n### Age Input\n```svelte\n<NumberInput \n\tlabel=\"Age\"\n\tbind:value={age}\n\tmin={18}\n\tmax={120}\n\tdescription=\"You must be 18 or older\"\n\trequired\n/>\n```\n\n### Temperature Control\n```svelte\n<NumberInput \n\tlabel=\"Temperature\"\n\tbind:value={temperature}\n\tmin={-10}\n\tmax={40}\n\tstep={0.5}\n>\n\t{#snippet suffix()}\n\t\t<span>\u00B0C</span>\n\t{/snippet}\n</NumberInput>\n```\n\n### Percentage Input\n```svelte\n<NumberInput \n\tlabel=\"Discount\"\n\tbind:value={discount}\n\tmin={0}\n\tmax={100}\n\tstep={5}\n>\n\t{#snippet suffix()}\n\t\t<span>%</span>\n\t{/snippet}\n</NumberInput>\n```\n\n### Rating Input\n```svelte\n<NumberInput \n\tlabel=\"Rating\"\n\tbind:value={rating}\n\tmin={1}\n\tmax={5}\n\tstep={0.5}\n\tdescription=\"Rate from 1 to 5 stars\"\n/>\n```\n\n## Validation\n\nNumberInput automatically validates:\n- **min**: Value must be >= min\n- **max**: Value must be <= max\n- **required**: Non-null value\n\nThe range messages come from the i18n catalog with the bound formatted in the input's locale and format (`Enter a value of 1.000 or less`); override them with `messages={{ rangeOverflow: (max) => ... }}`.\n\n## Keyboard Controls\n\n- **Arrow Up / Arrow Down**: step by step\n- **Shift + Arrow, Page Up / Page Down**: step by largeStep (default 10 x step)\n- **Alt + Arrow**: step by smallStep (default step / 10)\n- **Home / End**: jump to min / max when set (otherwise they move the caret)\n- **Enter**: formats and commits the typed text; a surrounding Form still moves on or submits\n\nThe +/- buttons step by the same step, repeat while pressed (after 400 ms, every 60 ms), stop at the bounds and when the input becomes disabled or read-only, and keep focus in the input. They are out of the tab order (tabindex -1) and point at the input with `aria-controls`.\n\n## Accessibility\n\n- Proper label association\n- The input has role spinbutton with aria-valuenow, aria-valuemin, aria-valuemax and aria-valuetext (the shown text)\n- Read-only is announced with the readonly attribute and aria-readonly\n- Keyboard stepping with large, small and bound keys\n- The +/- buttons are labelled and activate with a keyboard click, but add no tab stops\n\n## Notes\n\n- The input is type text with inputmode decimal (numeric for non-negative integers), so the browser's locale never decides the separators. Characters that cannot belong to a number in the locale and format are refused, a paste is inserted at the caret, and text that is not a number yet (`-`) is not published.\n- Intermediate text is kept as typed while focused; on blur or Enter it is rounded to the format, formatted for the locale and reported.\n- Out-of-range typed values are kept and flagged, not clamped; stepping and Home/End clamp.\n- The mouse wheel does nothing unless wheelStep is set.\n- Can be styled with prefix/suffix for units\n\n## Theme Customization\n\nThe NumberInput component uses a theme object that can be customized using the `theme` prop or by setting a global theme.\n\n### Theme Structure\n\nThe theme object contains the following parts:\n- **input**: Input element styles\n- **inputContainer**: Input container wrapper styles\n\n### Available Variants\n\n**input**:\n- base: Base classes applied to the input element\n- Variants:\n  - size: 'small' | 'normal' | 'large' - Text size\n  - disabled: boolean - Disabled state styling\n\n**inputContainer**:\n- base: Base classes for the input container (handles focus states, borders, padding)\n- Variants:\n  - size: 'small' | 'normal' | 'large' - Container height and size-based styling\n  - disabled: boolean - Disabled state styling\n\n### Usage Examples\n\n**Basic Theme Override**:\n```svelte\n<NumberInput \n  label=\"Quantity\"\n  bind:value={quantity}\n  theme={{\n    inputContainer: {\n      base: 'border-2 rounded-lg',\n      size: {\n        normal: 'h-8 px-4'\n      }\n    },\n    input: {\n      size: {\n        normal: 'text-base'\n      }\n    }\n  }}\n/>\n```\n\n**Focus State Customization**:\n\nTo recolor every focus ring in the app at once, set `designTokens.focusColor` on `Theme`\ninstead of overriding per component. `ring-focus` is the focus state role and falls back to the\ncurrent role, so it never hard-pins a color.\n\n```svelte\n<NumberInput \n  label=\"Custom Number\"\n  bind:value={value}\n  theme={{\n    inputContainer: {\n      base: 'focus-within:ring-2 focus-within:ring-focus/50 focus-within:border-focus'\n    }\n  }}\n/>\n```\n\n**Global Theme Setting**:\n```svelte\n<script>\n  import { setNumberInputTheme } from './index.ts';\n  \n  setNumberInputTheme({\n    inputContainer: {\n      base: 'rounded-lg border-2 transition-all',\n      size: {\n        normal: 'h-8 px-4'\n      }\n    },\n    input: {\n      base: 'text-right'\n    }\n  });\n</script>\n```\n\n## State contract\n\n- **value**: current bindable editable value.\n- **defaultValue**: initial value used only when `value` is omitted.\n- **onValueChange**: called with the new value when the component changes it.\n\n";