ropav 0.2.0 → 0.3.0

package/dist/composables/use-modal-transition.d.ts

@@ -0,0 +1,50 @@
+import type { ComputedRef, MaybeRefOrGetter } from "vue";
+export interface UseModalTransitionOptions {
+    /** The backdrop, which fades. */
+    backdropRef: MaybeRefOrGetter<HTMLElement | null | undefined>;
+    /** The container the dialog sits in, which moves and scales. */
+    contentRef: MaybeRefOrGetter<HTMLElement | null | undefined>;
+    isOpen: MaybeRefOrGetter<boolean>;
+    /** Forces the exit state, for a caller driving the animation itself. */
+    isExiting?: MaybeRefOrGetter<boolean | undefined>;
+    /** Forces the entry state on both elements. */
+    isEntering?: MaybeRefOrGetter<boolean | undefined>;
+}
+export interface UseModalTransitionReturn {
+    /** Whether either element should be in the DOM: open, or still animating out. */
+    isPresent: ComputedRef<boolean>;
+    isBackdropEntering: ComputedRef<boolean>;
+    isContentEntering: ComputedRef<boolean>;
+    /**
+     * Whether **either** element is animating out, reported to both.
+     *
+     * See the note on the composable: this being a union rather than two separate answers is what
+     * keeps a drawer on screen long enough to slide away.
+     */
+    isExiting: ComputedRef<boolean>;
+}
+/**
+ * The presence and animation state of a modal overlay's two elements, ported from React Aria's
+ * `ModalOverlay`.
+ *
+ * The entry states are separate — the backdrop fades while the container scales in, and each waits
+ * for its own animation. The **exit** state is deliberately not: it is the union, reported to both
+ * elements, and both stay mounted until every animation has finished.
+ *
+ * That union is load-bearing rather than tidy. An element is judged to be animating by asking it
+ * for its animations, and `getAnimations()` does not look into a subtree — so a container whose
+ * transition is declared on the dialog *inside* it reports nothing and would be unmounted on the
+ * spot, taking the dialog's slide-away with it. What keeps it on screen is the backdrop's own fade,
+ * the other half of the union. Giving each element only its own answer removes a drawer's exit
+ * animation entirely, and no jsdom test can see it happen.
+ *
+ * @example
+ * ```ts
+ * const transition = useModalTransition({
+ *   backdropRef: backdropElement,
+ *   contentRef: containerElement,
+ *   isOpen: () => state.isOpen.value,
+ * });
+ * ```
+ */
+export declare const useModalTransition: (options: UseModalTransitionOptions) => UseModalTransitionReturn;

package/dist/composables/use-modal-transition.js

@@ -0,0 +1,49 @@
+import { useEnterExit } from "./use-enter-exit.js";
+import { computed, toValue } from "vue";
+//#region src/composables/use-modal-transition.ts
+/**
+* The presence and animation state of a modal overlay's two elements, ported from React Aria's
+* `ModalOverlay`.
+*
+* The entry states are separate — the backdrop fades while the container scales in, and each waits
+* for its own animation. The **exit** state is deliberately not: it is the union, reported to both
+* elements, and both stay mounted until every animation has finished.
+*
+* That union is load-bearing rather than tidy. An element is judged to be animating by asking it
+* for its animations, and `getAnimations()` does not look into a subtree — so a container whose
+* transition is declared on the dialog *inside* it reports nothing and would be unmounted on the
+* spot, taking the dialog's slide-away with it. What keeps it on screen is the backdrop's own fade,
+* the other half of the union. Giving each element only its own answer removes a drawer's exit
+* animation entirely, and no jsdom test can see it happen.
+*
+* @example
+* ```ts
+* const transition = useModalTransition({
+*   backdropRef: backdropElement,
+*   contentRef: containerElement,
+*   isOpen: () => state.isOpen.value,
+* });
+* ```
+*/
+var useModalTransition = (options) => {
+	const isOpen = () => toValue(options.isOpen);
+	const backdrop = useEnterExit({
+		elementRef: options.backdropRef,
+		isOpen,
+		isReady: () => toValue(options.backdropRef) != null
+	});
+	const content = useEnterExit({
+		elementRef: options.contentRef,
+		isOpen,
+		isReady: () => toValue(options.contentRef) != null
+	});
+	const isExiting = computed(() => toValue(options.isExiting) ?? (backdrop.isExiting.value || content.isExiting.value));
+	return {
+		isBackdropEntering: computed(() => toValue(options.isEntering) ?? backdrop.isEntering.value),
+		isContentEntering: computed(() => toValue(options.isEntering) ?? content.isEntering.value),
+		isExiting,
+		isPresent: computed(() => isOpen() || backdrop.isExiting.value || content.isExiting.value || toValue(options.isExiting) === true)
+	};
+};
+//#endregion
+export { useModalTransition };

package/dist/composables/use-move.d.ts

@@ -0,0 +1,65 @@
+import type { PointerType } from "./use-press";
+/** The modifier state every move event carries over from the event that produced it. */
+interface ModifierKeys {
+    shiftKey: boolean;
+    ctrlKey: boolean;
+    metaKey: boolean;
+    altKey: boolean;
+}
+export interface MoveStartEvent extends ModifierKeys {
+    type: "movestart";
+    pointerType: PointerType;
+}
+export interface MoveMoveEvent extends ModifierKeys {
+    type: "move";
+    pointerType: PointerType;
+    /** Movement along the x axis since the last event, in pixels. */
+    deltaX: number;
+    /** Movement along the y axis since the last event, in pixels. */
+    deltaY: number;
+}
+export interface MoveEndEvent extends ModifierKeys {
+    type: "moveend";
+    pointerType: PointerType;
+}
+export interface UseMoveOptions {
+    onMoveStart?: (event: MoveStartEvent) => void;
+    onMove?: (event: MoveMoveEvent) => void;
+    onMoveEnd?: (event: MoveEndEvent) => void;
+}
+export interface UseMoveHandlers {
+    onKeydown: (event: KeyboardEvent) => void;
+    onPointerdown: (event: PointerEvent) => void;
+}
+export interface UseMoveReturn {
+    /**
+     * The pointer and the keyboard entry points. Attach each one statically with `@event`, never
+     * through `v-bind`: a vapor render re-attaches every `on*` key that arrived that way, which
+     * drops the listener when the interaction itself is what re-rendered the element.
+     */
+    handlers: UseMoveHandlers;
+}
+/**
+ * Drag and arrow-key movement, reported as a stream of deltas.
+ *
+ * Ported from React Aria's `useMove`. The consumer never sees coordinates, only how far the
+ * pointer moved since the last event, which is what lets one handler serve a pointer drag and
+ * an arrow press alike — an arrow press is reported as a single move of one unit, with
+ * `pointerType: "keyboard"` so the consumer can scale it by whatever a step means to it.
+ *
+ * Deltas come from `pageX`/`pageY` rather than `movementX`/`movementY`: the latter is always
+ * `0` in Safari on macOS, and Chrome on Android scales it by the device pixel ratio.
+ *
+ * Only the `PointerEvent` path is ported. React Aria carries a mouse/touch fallback for
+ * environments without pointer events, which every browser this targets — and jsdom — has.
+ *
+ * @example
+ * ```ts
+ * const {handlers} = useMove({
+ *   onMove: ({deltaX}) => { offset.value += deltaX; },
+ * });
+ * // <div @keydown="handlers.onKeydown" @pointerdown="handlers.onPointerdown" />
+ * ```
+ */
+export declare const useMove: (options: UseMoveOptions) => UseMoveReturn;
+export {};

package/dist/composables/use-move.js

@@ -0,0 +1,133 @@
+import { onScopeDispose } from "vue";
+//#region src/composables/use-move.ts
+/** How far one arrow press moves, before the consumer scales it by step or page size. */
+var KEYBOARD_DELTA = {
+	ArrowDown: [0, 1],
+	ArrowLeft: [-1, 0],
+	ArrowRight: [1, 0],
+	ArrowUp: [0, -1],
+	Down: [0, 1],
+	Left: [-1, 0],
+	Right: [1, 0],
+	Up: [0, -1]
+};
+/**
+* Drag and arrow-key movement, reported as a stream of deltas.
+*
+* Ported from React Aria's `useMove`. The consumer never sees coordinates, only how far the
+* pointer moved since the last event, which is what lets one handler serve a pointer drag and
+* an arrow press alike — an arrow press is reported as a single move of one unit, with
+* `pointerType: "keyboard"` so the consumer can scale it by whatever a step means to it.
+*
+* Deltas come from `pageX`/`pageY` rather than `movementX`/`movementY`: the latter is always
+* `0` in Safari on macOS, and Chrome on Android scales it by the device pixel ratio.
+*
+* Only the `PointerEvent` path is ported. React Aria carries a mouse/touch fallback for
+* environments without pointer events, which every browser this targets — and jsdom — has.
+*
+* @example
+* ```ts
+* const {handlers} = useMove({
+*   onMove: ({deltaX}) => { offset.value += deltaX; },
+* });
+* // <div @keydown="handlers.onKeydown" @pointerdown="handlers.onPointerdown" />
+* ```
+*/
+var useMove = (options) => {
+	const { onMove, onMoveEnd, onMoveStart } = options;
+	let didMove = false;
+	let lastPosition = null;
+	let pointerId = null;
+	let detachGlobalListeners;
+	const start = () => {
+		didMove = false;
+	};
+	const move = (event, pointerType, deltaX, deltaY) => {
+		if (deltaX === 0 && deltaY === 0) return;
+		const modifiers = {
+			altKey: event.altKey,
+			ctrlKey: event.ctrlKey,
+			metaKey: event.metaKey,
+			shiftKey: event.shiftKey
+		};
+		if (!didMove) {
+			didMove = true;
+			onMoveStart?.({
+				...modifiers,
+				pointerType,
+				type: "movestart"
+			});
+		}
+		onMove?.({
+			...modifiers,
+			deltaX,
+			deltaY,
+			pointerType,
+			type: "move"
+		});
+	};
+	const end = (event, pointerType) => {
+		if (!didMove) return;
+		onMoveEnd?.({
+			altKey: event.altKey,
+			ctrlKey: event.ctrlKey,
+			metaKey: event.metaKey,
+			pointerType,
+			shiftKey: event.shiftKey,
+			type: "moveend"
+		});
+	};
+	const onPointermove = (event) => {
+		if (event.pointerId !== pointerId) return;
+		move(event, event.pointerType || "mouse", event.pageX - (lastPosition?.pageX ?? 0), event.pageY - (lastPosition?.pageY ?? 0));
+		lastPosition = {
+			pageX: event.pageX,
+			pageY: event.pageY
+		};
+	};
+	const onPointerup = (event) => {
+		if (event.pointerId !== pointerId) return;
+		end(event, event.pointerType || "mouse");
+		pointerId = null;
+		detachGlobalListeners?.();
+	};
+	const onPointerdown = (event) => {
+		if (event.button !== 0 || pointerId !== null) return;
+		start();
+		event.stopPropagation();
+		event.preventDefault();
+		lastPosition = {
+			pageX: event.pageX,
+			pageY: event.pageY
+		};
+		pointerId = event.pointerId;
+		window.addEventListener("pointermove", onPointermove, false);
+		window.addEventListener("pointerup", onPointerup, false);
+		window.addEventListener("pointercancel", onPointerup, false);
+		detachGlobalListeners = () => {
+			window.removeEventListener("pointermove", onPointermove, false);
+			window.removeEventListener("pointerup", onPointerup, false);
+			window.removeEventListener("pointercancel", onPointerup, false);
+			detachGlobalListeners = void 0;
+		};
+	};
+	const onKeydown = (event) => {
+		const delta = KEYBOARD_DELTA[event.key];
+		if (!delta) return;
+		event.preventDefault();
+		event.stopPropagation();
+		start();
+		move(event, "keyboard", delta[0], delta[1]);
+		end(event, "keyboard");
+	};
+	onScopeDispose(() => {
+		detachGlobalListeners?.();
+		pointerId = null;
+	}, true);
+	return { handlers: {
+		onKeydown,
+		onPointerdown
+	} };
+};
+//#endregion
+export { useMove };

package/dist/composables/use-number-field-state.d.ts

@@ -0,0 +1,72 @@
+import type { FormValidationState, ValidationBehavior, ValidationFunction } from "./use-form-validation-state";
+import type { ComputedRef, MaybeRefOrGetter } from "vue";
+import { NumberParser } from "@internationalized/number";
+/**
+ * What happens to the value once the user is done editing.
+ *
+ * `"snap"` pulls it inside the range and onto the nearest step. `"validate"` leaves it where the
+ * user put it and lets validation object.
+ */
+export type NumberFieldCommitBehavior = "snap" | "validate";
+export interface UseNumberFieldStateOptions {
+    value?: MaybeRefOrGetter<number | null | undefined>;
+    defaultValue?: MaybeRefOrGetter<number | undefined>;
+    onChange?: (value: number) => void;
+    minValue?: MaybeRefOrGetter<number | undefined>;
+    maxValue?: MaybeRefOrGetter<number | undefined>;
+    step?: MaybeRefOrGetter<number | undefined>;
+    /** How the value is written, and by extension which characters may be typed. */
+    formatOptions?: MaybeRefOrGetter<Intl.NumberFormatOptions | undefined>;
+    /** @default "snap" */
+    commitBehavior?: MaybeRefOrGetter<NumberFieldCommitBehavior | undefined>;
+    isDisabled?: MaybeRefOrGetter<boolean | undefined>;
+    isReadOnly?: MaybeRefOrGetter<boolean | undefined>;
+    isRequired?: MaybeRefOrGetter<boolean | undefined>;
+    isInvalid?: MaybeRefOrGetter<boolean | undefined>;
+    validate?: MaybeRefOrGetter<ValidationFunction<number> | undefined>;
+    validationBehavior?: MaybeRefOrGetter<ValidationBehavior | undefined>;
+    name?: MaybeRefOrGetter<string | undefined>;
+    /** Locale used for both writing and reading the number. @default the runtime's own */
+    locale?: MaybeRefOrGetter<string | undefined>;
+}
+export interface NumberFieldState extends FormValidationState {
+    /** Text in the input. Follows the typing, and is rewritten in full on commit. */
+    inputValue: ComputedRef<string>;
+    /** The number the text currently parses to, or `NaN` when it does not parse. */
+    numberValue: ComputedRef<number>;
+    /** What a form reset goes back to. */
+    defaultNumberValue: ComputedRef<number>;
+    minValue: ComputedRef<number | undefined>;
+    maxValue: ComputedRef<number | undefined>;
+    canIncrement: ComputedRef<boolean>;
+    canDecrement: ComputedRef<boolean>;
+    /** Whether a half-typed string could still become a number in this locale and format. */
+    validate: (value: string) => boolean;
+    setInputValue: (value: string) => void;
+    setNumberValue: (value: number) => void;
+    /** Parse, pull into range, snap to a step and rewrite the text. What blurring does. */
+    commit: (value?: string) => void;
+    increment: () => void;
+    decrement: () => void;
+    incrementToMax: () => void;
+    decrementToMin: () => void;
+    /** The parser the input needs to tell an acceptable keystroke from an unacceptable one. */
+    parser: ComputedRef<NumberParser>;
+    /** How the number is written, with the numbering system the user is actually typing in. */
+    format: (value: number) => string;
+}
+/**
+ * State for a number field, ported from React Stately's
+ * `packages/react-stately/src/numberfield/useNumberFieldState.ts` (react-stately 3.49.0).
+ *
+ * The field keeps two values at once and that is the whole design: the text the user is typing,
+ * which may not be a number yet, and the number it parses to. They only come back together on
+ * commit, which is what lets someone type `-`, or `1.`, or a half-finished currency amount
+ * without the field fighting them.
+ *
+ * @example
+ * ```ts
+ * const state = useNumberFieldState({value: () => props.value, step: () => props.step});
+ * ```
+ */
+export declare const useNumberFieldState: (options?: UseNumberFieldStateOptions) => NumberFieldState;

package/dist/composables/use-number-field-state.js

@@ -0,0 +1,207 @@
+import { useControllableState } from "./use-controllable-state.js";
+import { useFormValidationState } from "./use-form-validation-state.js";
+import { useLocale } from "./use-locale.js";
+import { clamp, snapValueToStep } from "../utils/number.js";
+import { computed, shallowRef, toValue, watch } from "vue";
+import { NumberFormatter, NumberParser } from "@internationalized/number";
+//#region src/composables/use-number-field-state.ts
+/**
+* Addition and subtraction that do not leak binary floating point.
+*
+* `0.1 + 0.2` is the famous one, but the case that matters here is stepping a decimal field:
+* without this, incrementing `1.1` by `0.1` puts `1.2000000000000002` in the input. Both
+* operands are scaled to integers by the larger of their decimal lengths, and the result scaled
+* back. Ported from react-stately's `handleDecimalOperation`.
+*/
+var decimalOperation = (operator, a, b) => {
+	let result = operator === "+" ? a + b : a - b;
+	if (a % 1 === 0 && b % 1 === 0) return result;
+	const aDecimals = a.toString().split(".")[1]?.length ?? 0;
+	const bDecimals = b.toString().split(".")[1]?.length ?? 0;
+	const multiplier = 10 ** Math.max(aDecimals, bDecimals);
+	const scaledA = Math.round(a * multiplier);
+	const scaledB = Math.round(b * multiplier);
+	result = operator === "+" ? scaledA + scaledB : scaledA - scaledB;
+	return result / multiplier;
+};
+/**
+* A key that changes only when the format options really differ.
+*
+* Every value in `Intl.NumberFormatOptions` is a primitive, so a shallow comparison is enough —
+* and it has to be shallow rather than by reference, because a caller writing the options inline
+* hands over a fresh object every render and would otherwise rewrite the input on each one.
+*/
+var formatOptionsKey = (options) => {
+	if (!options) return "";
+	return Object.keys(options).sort().map((key) => key + ":" + String(options[key])).join("|");
+};
+/**
+* State for a number field, ported from React Stately's
+* `packages/react-stately/src/numberfield/useNumberFieldState.ts` (react-stately 3.49.0).
+*
+* The field keeps two values at once and that is the whole design: the text the user is typing,
+* which may not be a number yet, and the number it parses to. They only come back together on
+* commit, which is what lets someone type `-`, or `1.`, or a half-finished currency amount
+* without the field fighting them.
+*
+* @example
+* ```ts
+* const state = useNumberFieldState({value: () => props.value, step: () => props.step});
+* ```
+*/
+var useNumberFieldState = (options = {}) => {
+	const resolvedLocale = useLocale();
+	const locale = computed(() => toValue(options.locale) ?? resolvedLocale.value.locale);
+	const minValue = computed(() => toValue(options.minValue));
+	const maxValue = computed(() => toValue(options.maxValue));
+	const step = computed(() => toValue(options.step));
+	const formatOptions = computed(() => toValue(options.formatOptions));
+	const commitBehavior = computed(() => toValue(options.commitBehavior) ?? "snap");
+	const snap = (candidate) => step.value === void 0 || Number.isNaN(step.value) ? clamp(candidate, minValue.value, maxValue.value) : snapValueToStep(candidate, minValue.value, maxValue.value, step.value);
+	const controlledValue = computed(() => {
+		const raw = toValue(options.value);
+		if (raw === void 0) return void 0;
+		if (raw === null || Number.isNaN(raw)) return NaN;
+		return commitBehavior.value === "snap" ? snap(raw) : raw;
+	});
+	const defaultValue = computed(() => {
+		const raw = toValue(options.defaultValue);
+		if (raw === void 0 || Number.isNaN(raw)) return NaN;
+		return commitBehavior.value === "snap" ? snap(raw) : raw;
+	});
+	const { setState: setNumberValue, state: numberValueState } = useControllableState({
+		defaultValue: defaultValue.value,
+		onValueChange: options.onChange,
+		value: () => controlledValue.value
+	});
+	const isControlled = computed(() => controlledValue.value !== void 0);
+	const initialValue = numberValueState.value;
+	const parser = computed(() => new NumberParser(locale.value, formatOptions.value));
+	const inputValue = shallowRef("");
+	const numberingSystem = computed(() => parser.value.getNumberingSystem(inputValue.value));
+	const formatter = computed(() => new NumberFormatter(locale.value, {
+		...formatOptions.value,
+		numberingSystem: numberingSystem.value
+	}));
+	const format = (candidate) => Number.isNaN(candidate) ? "" : formatter.value.format(candidate);
+	inputValue.value = format(numberValueState.value);
+	const validation = useFormValidationState({
+		isInvalid: () => toValue(options.isInvalid),
+		name: () => toValue(options.name),
+		validate: () => toValue(options.validate),
+		validationBehavior: () => toValue(options.validationBehavior),
+		value: () => numberValueState.value
+	});
+	const clampStep = computed(() => {
+		if (step.value !== void 0 && !Number.isNaN(step.value)) return step.value;
+		if (formatter.value.resolvedOptions().style === "percent") return .01;
+		return 1;
+	});
+	const setInputValue = (next) => {
+		inputValue.value = next;
+	};
+	/**
+	* Rewrite the text whenever the number, the locale or the format changes underneath it.
+	*
+	* Synchronous on purpose. Stepping the value and then reading the input back has to see the
+	* new text — a post-flush watcher would leave the old text there for a tick, which the caret
+	* handling downstream reads and would then restore to the wrong place.
+	*/
+	watch([
+		numberValueState,
+		locale,
+		() => formatOptionsKey(formatOptions.value)
+	], () => {
+		inputValue.value = format(numberValueState.value);
+	}, { flush: "sync" });
+	const parsedValue = computed(() => parser.value.parse(inputValue.value));
+	const commit = (override) => {
+		const nextInput = override ?? inputValue.value;
+		const nextParsed = override === void 0 ? parsedValue.value : parser.value.parse(override);
+		if (!nextInput.length) {
+			setNumberValue(NaN);
+			inputValue.value = isControlled.value ? format(numberValueState.value) : "";
+			return;
+		}
+		if (Number.isNaN(nextParsed)) {
+			inputValue.value = format(numberValueState.value);
+			return;
+		}
+		let committed = commitBehavior.value === "snap" ? snap(nextParsed) : nextParsed;
+		committed = parser.value.parse(format(committed));
+		const changed = committed !== numberValueState.value;
+		setNumberValue(committed);
+		inputValue.value = format(isControlled.value ? numberValueState.value : committed);
+		if (changed) validation.commitValidation();
+	};
+	/**
+	* The next value one step along, without ever landing off a step boundary.
+	*
+	* Snapping first is what handles a value that is already between steps: if the snap alone
+	* moves in the direction being asked for, that is the answer, and only otherwise does a whole
+	* step get added.
+	*/
+	const nextStep = (operation, fromEmpty) => {
+		const previous = parsedValue.value;
+		if (Number.isNaN(previous)) return snapValueToStep(fromEmpty === void 0 || Number.isNaN(fromEmpty) ? 0 : fromEmpty, minValue.value, maxValue.value, clampStep.value);
+		const snapped = snapValueToStep(previous, minValue.value, maxValue.value, clampStep.value);
+		if (operation === "+" && snapped > previous) return snapped;
+		if (operation === "-" && snapped < previous) return snapped;
+		return snapValueToStep(decimalOperation(operation, previous, clampStep.value), minValue.value, maxValue.value, clampStep.value);
+	};
+	const step1 = (operation, fromEmpty) => {
+		const next = nextStep(operation, fromEmpty);
+		if (next === numberValueState.value) inputValue.value = format(next);
+		setNumberValue(next);
+		validation.commitValidation();
+	};
+	const increment = () => step1("+", minValue.value);
+	const decrement = () => step1("-", maxValue.value);
+	const incrementToMax = () => {
+		if (maxValue.value === void 0 || maxValue.value === null) return;
+		setNumberValue(snapValueToStep(maxValue.value, minValue.value, maxValue.value, clampStep.value));
+		validation.commitValidation();
+	};
+	const decrementToMin = () => {
+		if (minValue.value === void 0 || minValue.value === null) return;
+		setNumberValue(minValue.value);
+		validation.commitValidation();
+	};
+	const isSteppable = computed(() => !toValue(options.isDisabled) && !toValue(options.isReadOnly));
+	const canIncrement = computed(() => {
+		if (!isSteppable.value) return false;
+		const current = parsedValue.value;
+		const max = maxValue.value;
+		if (Number.isNaN(current) || max === void 0 || Number.isNaN(max)) return true;
+		return snapValueToStep(current, minValue.value, max, clampStep.value) > current || decimalOperation("+", current, clampStep.value) <= max;
+	});
+	const canDecrement = computed(() => {
+		if (!isSteppable.value) return false;
+		const current = parsedValue.value;
+		const min = minValue.value;
+		if (Number.isNaN(current) || min === void 0 || Number.isNaN(min)) return true;
+		return snapValueToStep(current, min, maxValue.value, clampStep.value) < current || decimalOperation("-", current, clampStep.value) >= min;
+	});
+	return {
+		...validation,
+		canDecrement,
+		canIncrement,
+		commit,
+		decrement,
+		decrementToMin,
+		defaultNumberValue: computed(() => Number.isNaN(defaultValue.value) ? initialValue : defaultValue.value),
+		format,
+		increment,
+		incrementToMax,
+		inputValue: computed(() => inputValue.value),
+		maxValue,
+		minValue,
+		numberValue: parsedValue,
+		parser,
+		setInputValue,
+		setNumberValue,
+		validate: (candidate) => parser.value.isValidPartialNumber(candidate, minValue.value, maxValue.value)
+	};
+};
+//#endregion
+export { useNumberFieldState };

package/dist/composables/use-number-field.d.ts

@@ -0,0 +1,88 @@
+import type { FieldIdsContext } from "./use-field-ids";
+import type { NumberFieldCommitBehavior, NumberFieldState, UseNumberFieldStateOptions } from "./use-number-field-state";
+import type { SpinStepperHandlers } from "./use-spin-button";
+import type { ComputedRef, MaybeRefOrGetter } from "vue";
+/** What a stepper button gets from the field, kept apart from its listeners. */
+export interface NumberFieldStepper {
+    /** Spread with `v-bind`. Never carries an `on*` key. */
+    attrs: ComputedRef<Record<string, unknown>>;
+    /** Wire with `@event`, never with `v-bind`. */
+    handlers: SpinStepperHandlers;
+    /** Whether the value can move any further in this direction. */
+    isDisabled: ComputedRef<boolean>;
+}
+export interface UseNumberFieldOptions extends UseNumberFieldStateOptions {
+    id?: MaybeRefOrGetter<string | undefined>;
+    /** Lands on a hidden input rather than the visible one, which carries formatted text. */
+    name?: MaybeRefOrGetter<string | undefined>;
+    form?: MaybeRefOrGetter<string | undefined>;
+    autoFocus?: MaybeRefOrGetter<boolean | undefined>;
+    ariaLabel?: MaybeRefOrGetter<string | undefined>;
+    ariaLabelledby?: MaybeRefOrGetter<string | undefined>;
+    ariaDescribedby?: MaybeRefOrGetter<string | undefined>;
+    /** Overrides the name the increment button announces. */
+    incrementAriaLabel?: MaybeRefOrGetter<string | undefined>;
+    /** Overrides the name the decrement button announces. */
+    decrementAriaLabel?: MaybeRefOrGetter<string | undefined>;
+    /** Whether the wheel over a focused field is ignored. */
+    isWheelDisabled?: MaybeRefOrGetter<boolean | undefined>;
+    /**
+     * State built elsewhere, for a field whose number is a view of something else.
+     *
+     * A colour channel field is the case this exists for: the number it edits is one channel of a
+     * colour, so the state has to be built on top of the colour and then handed down — letting
+     * this composable start a second state over the same number would give the field two values
+     * that disagree. Same escape hatch as `validationState` on {@link useTextField}.
+     */
+    state?: NumberFieldState;
+    onFocusChange?: (isFocused: boolean) => void;
+    onKeydown?: (event: KeyboardEvent) => void;
+    onKeyup?: (event: KeyboardEvent) => void;
+}
+export interface UseNumberFieldReturn {
+    state: NumberFieldState;
+    /** Pass to `provideFieldIdsContext`. */
+    fieldIds: FieldIdsContext;
+    /** Attributes for the input. Spread with `v-bind`. */
+    attrs: ComputedRef<Record<string, unknown>>;
+    /** Attributes for the group around the input and the buttons. */
+    groupAttrs: ComputedRef<Record<string, unknown>>;
+    /** The input reports its element, which the wheel, reset and validation wiring hang off. */
+    registerElement: (element: HTMLInputElement | null) => void;
+    element: ComputedRef<HTMLInputElement | null>;
+    increment: NumberFieldStepper;
+    decrement: NumberFieldStepper;
+    onInput: (event: Event) => void;
+    onKeydown: (event: KeyboardEvent) => void;
+    onKeyup: (event: KeyboardEvent) => void;
+    onFocus: (event: FocusEvent) => void;
+    onBlur: (event: FocusEvent) => void;
+    onPaste: (event: ClipboardEvent) => void;
+    onFocusin: () => void;
+    onFocusout: (event: FocusEvent) => void;
+    isDisabled: ComputedRef<boolean>;
+    isReadOnly: ComputedRef<boolean>;
+    isRequired: ComputedRef<boolean>;
+    isInvalid: ComputedRef<boolean>;
+    /** Whether focus is anywhere inside the group. Gates the wheel, and the hover fill. */
+    isFocusWithin: ComputedRef<boolean>;
+    /** Put the input's text back to what the state holds. */
+    reassert: () => void;
+}
+/**
+ * Behaviour and accessibility for a number field, ported from React Aria's
+ * `packages/react-aria/src/numberfield/useNumberField.ts` (react-aria 3.51.0).
+ *
+ * The visible control is a plain text input, not `type="number"`: a number input cannot hold a
+ * currency symbol, a percent sign or grouping separators, and the field's whole point is that it
+ * can. Everything a number input would have given for free is put back by hand — the spin button
+ * semantics, the software keyboard choice, and range validation, which is borrowed from a real
+ * number input kept off-document so the browser's own message is what the user reads.
+ *
+ * @example
+ * ```ts
+ * const field = useNumberField({value: () => props.value, step: () => props.step});
+ * ```
+ */
+export declare const useNumberField: (options?: UseNumberFieldOptions) => UseNumberFieldReturn;
+export type { NumberFieldCommitBehavior, NumberFieldState };