@rivetjs/cdk 0.0.0-stage → 0.1.0-alpha.1

package/number/number-field-state.d.ts

@@ -0,0 +1,132 @@
+import { type Signal } from "@rivetjs/reactivity";
+import { type FormValidationOptions, type FormValidationState, type MaybeAccessor } from "@rivetjs/cdk/state/form-validation";
+export interface NumberFieldProps extends FormValidationOptions<number> {
+    /**
+     * The current value (controlled): a two-way signal, a plain number, or an accessor (read live, never written; a
+     * live prop `value={n()}` arrives as one). `null` is treated as NaN (empty).
+     */
+    value?: Signal<number | null> | (() => number | null) | number | null;
+    /** The default value (uncontrolled). Read once at mount. */
+    defaultValue?: number;
+    /** Handler that is called when the value changes (resumed pages: an inline arrow or a local function). */
+    onChange?: (value: number) => void;
+    /** The smallest value allowed for the input. */
+    minValue?: MaybeAccessor<number | undefined>;
+    /** The largest value allowed for the input. */
+    maxValue?: MaybeAccessor<number | undefined>;
+    /** The amount that the input value changes with each increment or decrement "tick". */
+    step?: MaybeAccessor<number | undefined>;
+    /** Whether the input is disabled. */
+    isDisabled?: MaybeAccessor<boolean | undefined>;
+    /** Whether the input can be selected but not changed by the user. */
+    isReadOnly?: MaybeAccessor<boolean | undefined>;
+    /**
+     * Formatting options for the value displayed in the number field.
+     * This also affects what characters are allowed to be typed by the user.
+     */
+    formatOptions?: MaybeAccessor<Intl.NumberFormatOptions | undefined>;
+    /**
+     * Controls the behavior of the number field when the user blurs the field after editing. 'snap'
+     * will clamp the value to the min/max values, and snap to the nearest step value. 'validate' will
+     * not clamp the value, and will validate that the value is within the min/max range and on a
+     * valid step.
+     *
+     * @default 'snap'
+     */
+    commitBehavior?: "snap" | "validate";
+}
+export interface NumberFieldStateOptions extends NumberFieldProps {
+    /**
+     * The locale that should be used for parsing.
+     *
+     * @default 'en-US'
+     */
+    locale: MaybeAccessor<string>;
+}
+/** Previous number value / locale / format options the input text was formatted for (upstream prev* state). */
+export interface NumberFieldSync {
+    value: number;
+    locale: string;
+    formatOptions: Intl.NumberFormatOptions | undefined;
+}
+export interface NumberFieldState {
+    readonly locale: MaybeAccessor<string>;
+    readonly formatOptions: MaybeAccessor<Intl.NumberFormatOptions | undefined> | undefined;
+    readonly minValue: MaybeAccessor<number | undefined> | undefined;
+    readonly maxValue: MaybeAccessor<number | undefined> | undefined;
+    readonly step: MaybeAccessor<number | undefined> | undefined;
+    readonly isDisabled: MaybeAccessor<boolean | undefined> | undefined;
+    readonly isReadOnly: MaybeAccessor<boolean | undefined> | undefined;
+    readonly commitBehavior: "snap" | "validate";
+    /** Whether `value` is controlled (upstream `value !== undefined`). */
+    readonly controlled: boolean;
+    /** A plain or accessor controlled value: `value` is never written (changes only fire `onChange`). */
+    readonly fixed: boolean;
+    /** The committed value (controlled signal / accessor, or the internal one); null = NaN. Never `.set` a fixed one. */
+    readonly value: Signal<number | null>;
+    /** The input text as last written (read it through `inputValue(state)`). */
+    readonly input: Signal<string>;
+    /** What `input` was last formatted for. */
+    readonly prev: Signal<NumberFieldSync>;
+    /** The default value of the input. */
+    readonly defaultNumberValue: number;
+    readonly onChange: ((value: number) => void) | undefined;
+    readonly validation: FormValidationState;
+}
+/**
+ * Provides state management for a number field component. Number fields allow users to enter a
+ * number, and increment or decrement the value using stepper buttons.
+ */
+export declare function createNumberFieldState(props: NumberFieldStateOptions): NumberFieldState;
+/** The committed number value (upstream `numberValue` before it is shadowed by the parsed input). */
+export declare function committedValue(state: NumberFieldState): number;
+/**
+ * The current text value of the input. Updated as the user types,
+ * and formatted according to `formatOptions` on blur.
+ */
+export declare function inputValue(state: NumberFieldState): string;
+/**
+ * Rivet (no upstream member): the committed value formatted for display — the input text once it is in sync; while the
+ * user types, the last committed value (`@rivetjs/ui` NumberStepper's animated display rolls in on commit).
+ */
+export declare function formattedValue(state: NumberFieldState): string;
+/**
+ * The currently parsed number value, or NaN if a valid number could not be parsed.
+ * Updated based on the `inputValue` as the user types.
+ */
+export declare function numberValue(state: NumberFieldState): number;
+/** The minimum value of the number field. */
+export declare const minValue: (state: NumberFieldState) => number | undefined;
+/** The maximum value of the number field. */
+export declare const maxValue: (state: NumberFieldState) => number | undefined;
+/** Whether the current value can be incremented according to the maximum value and step. */
+export declare function canIncrement(state: NumberFieldState): boolean;
+/** Whether the current value can be decremented according to the minimum value and step. */
+export declare function canDecrement(state: NumberFieldState): boolean;
+/**
+ * Validates a user input string according to the current locale and format options. Values can be
+ * partially entered, and may be valid even if they cannot currently be parsed to a number. Can be
+ * used to implement validation as a user types.
+ */
+export declare function validate(state: NumberFieldState, value: string): boolean;
+/** Sets the current text value of the input. */
+export declare function setInputValue(state: NumberFieldState, value: string): void;
+/** Sets the number value. */
+export declare function setNumberValue(state: NumberFieldState, value: number): void;
+/**
+ * Commits the current input value. The value is parsed to a number, clamped according to the
+ * minimum and maximum values of the field, and snapped to the nearest step value. This will fire
+ * the `onChange` prop with the new value, and if uncontrolled, update the `numberValue`.
+ * Typically this is called when the field is blurred.
+ *
+ * @param overrideValue - The value to commit. If not provided, the current input value is used.
+ */
+export declare function commit(state: NumberFieldState, overrideValue?: string): void;
+/** Increments the current input value to the next step boundary, and fires `onChange`. */
+export declare function increment(state: NumberFieldState): void;
+/** Decrements the current input value to the next step boundary, and fires `onChange`. */
+export declare function decrement(state: NumberFieldState): void;
+/** Sets the current value to the `maxValue` if any, and fires `onChange`. */
+export declare function incrementToMax(state: NumberFieldState): void;
+/** Sets the current value to the `minValue` if any, and fires `onChange`. */
+export declare function decrementToMin(state: NumberFieldState): void;

package/number/number-field-state.jsx

@@ -0,0 +1,364 @@
+// Ported from react-stately `useNumberFieldState` (packages/react-stately/src/numberfield/useNumberFieldState.ts), Apache-2.0, © Adobe.
+// Rivet:
+// - Serializable state (cdk `state/*` convention): `createNumberFieldState(options)` returns plain signals + JSON
+//   (region state, resumable); the upstream state members are free functions taking the state (`inputValue(state)`,
+//   `numberValue(state)`, `commit(state)`, `increment(state)`, `canIncrement(state)`, …).
+// - Controlled `value`: a two-way `Signal<number | null>`, a plain number (plain = fixed: changes only fire
+//   `onChange`, like an upstream controlled prop the parent does not update) or an accessor `() => number | null`
+//   (a live prop: read on every use, never written — upstream's controlled prop that the parent re-renders);
+//   `null` = NaN, as upstream.
+// - Props that change between React renders (`locale`, `formatOptions`, `minValue`, `maxValue`, `step`,
+//   `isDisabled`, `isReadOnly`) accept a value or an accessor (`MaybeAccessor`; resumed pages: inline arrows).
+// - Upstream's "set state during render" sync (reformat the input when the number value, locale or format options
+//   change) is pure on read (an out-of-sync input reads as the formatted number value) and written by every
+//   mutation first (`syncInputValue`); the previous value/locale/formatOptions live in a JSON signal.
+// - Validation = `createFormValidationState` (`state.validation`; use the `state/form-validation` free functions).
+//   Its value is upstream's `numberValue`: the uncontrolled signal, or for a controlled value + `validate` an accessor
+//   (null -> NaN, snapped) — a closure, so this module is `.tsx` (resume-compiled; `validationValue` is an R2 symbol).
+/*
+ * Copyright 2020 Adobe. All rights reserved.
+ * This file is licensed to you under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License. You may obtain a copy
+ * of the License at http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under
+ * the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+ * OF ANY KIND, either express or implied. See the License for the specific language
+ * governing permissions and limitations under the License.
+ */
+import { _regionState, signal, untrack } from "@rivetjs/reactivity";
+import { clamp, snapValueToStep } from "@rivetjs/cdk/utils";
+import { commitValidation, createFormValidationState, read, } from "@rivetjs/cdk/state/form-validation";
+import { NumberFormatter } from "./NumberFormatter.js";
+import { NumberParser } from "./NumberParser.js";
+const isSignal = (value) => typeof value === "function" && typeof value.set === "function";
+function snapValue(state, value) {
+    const step = read(state.step);
+    const minValue = read(state.minValue);
+    const maxValue = read(state.maxValue);
+    return step === undefined || isNaN(step) ? clamp(value, minValue, maxValue) : snapValueToStep(value, minValue, maxValue, step);
+}
+/**
+ * Provides state management for a number field component. Number fields allow users to enter a
+ * number, and increment or decrement the value using stepper buttons.
+ */
+export function createNumberFieldState(props) {
+    return _regionState(() => untrack(() => {
+        const commitBehavior = props.commitBehavior ?? "snap";
+        const controlled = props.value !== undefined;
+        const fixed = controlled && !isSignal(props.value);
+        const partial = {
+            locale: props.locale,
+            formatOptions: props.formatOptions,
+            minValue: props.minValue,
+            maxValue: props.maxValue,
+            step: props.step,
+            isDisabled: props.isDisabled,
+            isReadOnly: props.isReadOnly,
+            commitBehavior,
+        };
+        let defaultValue = props.defaultValue ?? NaN;
+        if (!isNaN(defaultValue) && commitBehavior === "snap") {
+            defaultValue = snapValue(partial, defaultValue);
+        }
+        // useControlledState(value, defaultValue, onChange); an accessor (live prop) is kept as is: read, never written.
+        const value = isSignal(props.value) || typeof props.value === "function"
+            ? props.value
+            : signal(controlled ? props.value : isNaN(defaultValue) ? NaN : defaultValue);
+        const state = {
+            ...partial,
+            controlled,
+            fixed,
+            value,
+            input: signal(""),
+            prev: signal({ value: NaN, locale: "", formatOptions: undefined }),
+            defaultNumberValue: NaN,
+            onChange: props.onChange,
+            validation: null,
+        };
+        // Upstream validates `numberValue` (null -> NaN, a controlled value snapped). The uncontrolled signal already
+        // holds exactly that; a controlled one needs the derived accessor (a resumable closure: this module is .tsx).
+        state.validation = createFormValidationState({
+            ...props,
+            value: controlled && props.validate ? validationValue(state) : value,
+        });
+        const initialValue = committedValue(state);
+        const locale = read(state.locale);
+        const formatOptions = read(state.formatOptions);
+        state.input.set(isNaN(initialValue) ? "" : new NumberFormatter(locale, formatOptions).format(initialValue));
+        state.prev.set({ value: initialValue, locale, formatOptions });
+        state.defaultNumberValue = isNaN(defaultValue) ? initialValue : defaultValue;
+        return state;
+    }));
+}
+/** The value custom `validate` receives (upstream `numberValue`): a resumable accessor (R2 return value). */
+function validationValue(state) {
+    return () => committedValue(state);
+}
+// Accessors ------------------------------------------------------------------------------------
+/** The committed number value (upstream `numberValue` before it is shadowed by the parsed input). */
+export function committedValue(state) {
+    let value = state.value();
+    if (value === null)
+        value = NaN;
+    if (state.controlled && !isNaN(value) && state.commitBehavior === "snap")
+        value = snapValue(state, value);
+    return value;
+}
+const numberParser = (state) => new NumberParser(read(state.locale), read(state.formatOptions));
+function formatter(state) {
+    const numberingSystem = numberParser(state).getNumberingSystem(state.input());
+    return new NumberFormatter(read(state.locale), { ...read(state.formatOptions), numberingSystem });
+}
+const format = (state, value) => (isNaN(value) || value === null ? "" : formatter(state).format(value));
+function outOfSync(state, numberValue, locale, formatOptions) {
+    const p = untrack(state.prev);
+    return !Object.is(numberValue, p.value) || locale !== p.locale || !isEqualFormatOptions(formatOptions, p.formatOptions);
+}
+/** Upstream render-time sync: reformat the input when the number value, locale or format options changed. */
+function syncInputValue(state) {
+    const numberValue = committedValue(state);
+    const locale = read(state.locale);
+    const formatOptions = read(state.formatOptions);
+    if (outOfSync(state, numberValue, locale, formatOptions)) {
+        state.input.set(format(state, numberValue));
+        state.prev.set({ value: numberValue, locale, formatOptions });
+    }
+}
+/**
+ * The current text value of the input. Updated as the user types,
+ * and formatted according to `formatOptions` on blur.
+ */
+export function inputValue(state) {
+    const numberValue = committedValue(state);
+    return outOfSync(state, numberValue, read(state.locale), read(state.formatOptions)) ? format(state, numberValue) : state.input();
+}
+/**
+ * Rivet (no upstream member): the committed value formatted for display — the input text once it is in sync; while the
+ * user types, the last committed value (`@rivetjs/ui` NumberStepper's animated display rolls in on commit).
+ */
+export function formattedValue(state) {
+    return format(state, committedValue(state));
+}
+/**
+ * The currently parsed number value, or NaN if a valid number could not be parsed.
+ * Updated based on the `inputValue` as the user types.
+ */
+export function numberValue(state) {
+    return numberParser(state).parse(inputValue(state));
+}
+/** The minimum value of the number field. */
+export const minValue = (state) => read(state.minValue);
+/** The maximum value of the number field. */
+export const maxValue = (state) => read(state.maxValue);
+function clampStep(state) {
+    const step = read(state.step);
+    let clampStep = step !== undefined && !isNaN(step) ? step : 1;
+    if (formatter(state).resolvedOptions().style === "percent" && (step === undefined || isNaN(step))) {
+        clampStep = 0.01;
+    }
+    return clampStep;
+}
+/** Whether the current value can be incremented according to the maximum value and step. */
+export function canIncrement(state) {
+    const parsedValue = numberValue(state);
+    const min = minValue(state), max = maxValue(state), step = clampStep(state);
+    return (!read(state.isDisabled) &&
+        !read(state.isReadOnly) &&
+        (isNaN(parsedValue) ||
+            max === undefined ||
+            isNaN(max) ||
+            snapValueToStep(parsedValue, min, max, step) > parsedValue ||
+            handleDecimalOperation("+", parsedValue, step) <= max));
+}
+/** Whether the current value can be decremented according to the minimum value and step. */
+export function canDecrement(state) {
+    const parsedValue = numberValue(state);
+    const min = minValue(state), max = maxValue(state), step = clampStep(state);
+    return (!read(state.isDisabled) &&
+        !read(state.isReadOnly) &&
+        (isNaN(parsedValue) ||
+            min === undefined ||
+            isNaN(min) ||
+            snapValueToStep(parsedValue, min, max, step) < parsedValue ||
+            handleDecimalOperation("-", parsedValue, step) >= min));
+}
+/**
+ * Validates a user input string according to the current locale and format options. Values can be
+ * partially entered, and may be valid even if they cannot currently be parsed to a number. Can be
+ * used to implement validation as a user types.
+ */
+export function validate(state, value) {
+    return untrack(() => numberParser(state).isValidPartialNumber(value, minValue(state), maxValue(state)));
+}
+// Mutations ------------------------------------------------------------------------------------
+function writeNumberValue(state, value) {
+    const current = committedValue(state);
+    if (!state.fixed && !Object.is(state.value(), value))
+        state.value.set(value);
+    if (!Object.is(current, value))
+        state.onChange?.(value);
+}
+/** Sets the current text value of the input. */
+export function setInputValue(state, value) {
+    untrack(() => {
+        syncInputValue(state);
+        state.input.set(value);
+    });
+}
+/** Sets the number value. */
+export function setNumberValue(state, value) {
+    untrack(() => {
+        syncInputValue(state);
+        writeNumberValue(state, value);
+    });
+}
+/**
+ * Commits the current input value. The value is parsed to a number, clamped according to the
+ * minimum and maximum values of the field, and snapped to the nearest step value. This will fire
+ * the `onChange` prop with the new value, and if uncontrolled, update the `numberValue`.
+ * Typically this is called when the field is blurred.
+ *
+ * @param overrideValue - The value to commit. If not provided, the current input value is used.
+ */
+export function commit(state, overrideValue) {
+    untrack(() => {
+        syncInputValue(state);
+        const numberValue_ = committedValue(state);
+        const newInputValue = overrideValue === undefined ? state.input() : overrideValue;
+        let newParsedValue = numberValue(state);
+        if (overrideValue !== undefined) {
+            newParsedValue = numberParser(state).parse(newInputValue);
+        }
+        // Set to empty state if input value is empty
+        if (!newInputValue.length) {
+            writeNumberValue(state, NaN);
+            state.input.set(!state.controlled ? "" : format(state, numberValue_));
+            return;
+        }
+        // if it failed to parse, then reset input to formatted version of current number
+        if (isNaN(newParsedValue)) {
+            state.input.set(format(state, numberValue_));
+            return;
+        }
+        // Clamp to min and max, round to the nearest step, and round to specified number of digits
+        let clampedValue = state.commitBehavior === "snap" ? snapValue(state, newParsedValue) : newParsedValue;
+        clampedValue = numberParser(state).parse(format(state, clampedValue));
+        const shouldValidate = clampedValue !== numberValue_;
+        writeNumberValue(state, clampedValue);
+        // in a controlled state, the numberValue won't change, so we won't go back to our old input without help
+        state.input.set(format(state, !state.controlled ? clampedValue : numberValue_));
+        if (shouldValidate) {
+            commitValidation(state.validation);
+        }
+    });
+}
+function safeNextStep(state, operation, minMax = 0) {
+    const prev = numberValue(state);
+    const step = clampStep(state);
+    const min = minValue(state), max = maxValue(state);
+    if (isNaN(prev)) {
+        // if the input is empty, start from the min/max value when incrementing/decrementing,
+        // or zero if there is no min/max value defined.
+        const newValue = isNaN(minMax) ? 0 : minMax;
+        return snapValueToStep(newValue, min, max, step);
+    }
+    else {
+        // otherwise, first snap the current value to the nearest step. if it moves in the direction
+        // we're going, use that value, otherwise add the step and snap that value.
+        const newValue = snapValueToStep(prev, min, max, step);
+        if ((operation === "+" && newValue > prev) || (operation === "-" && newValue < prev)) {
+            return newValue;
+        }
+        return snapValueToStep(handleDecimalOperation(operation, prev, step), min, max, step);
+    }
+}
+/** Increments the current input value to the next step boundary, and fires `onChange`. */
+export function increment(state) {
+    untrack(() => {
+        syncInputValue(state);
+        const newValue = safeNextStep(state, "+", minValue(state));
+        // if we've arrived at the same value that was previously in the state, the
+        // input value should be updated to match
+        // ex type 4, press increment, highlight the number in the input, type 4 again, press increment
+        // you'd be at 5, then incrementing to 5 again, so no re-render would happen and 4 would be left in the input
+        if (newValue === committedValue(state)) {
+            state.input.set(format(state, newValue));
+        }
+        writeNumberValue(state, newValue);
+        commitValidation(state.validation);
+    });
+}
+/** Decrements the current input value to the next step boundary, and fires `onChange`. */
+export function decrement(state) {
+    untrack(() => {
+        syncInputValue(state);
+        const newValue = safeNextStep(state, "-", maxValue(state));
+        if (newValue === committedValue(state)) {
+            state.input.set(format(state, newValue));
+        }
+        writeNumberValue(state, newValue);
+        commitValidation(state.validation);
+    });
+}
+/** Sets the current value to the `maxValue` if any, and fires `onChange`. */
+export function incrementToMax(state) {
+    untrack(() => {
+        syncInputValue(state);
+        const max = maxValue(state);
+        if (max != null) {
+            writeNumberValue(state, snapValueToStep(max, minValue(state), max, clampStep(state)));
+            commitValidation(state.validation);
+        }
+    });
+}
+/** Sets the current value to the `minValue` if any, and fires `onChange`. */
+export function decrementToMin(state) {
+    untrack(() => {
+        syncInputValue(state);
+        const min = minValue(state);
+        if (min != null) {
+            writeNumberValue(state, min);
+            commitValidation(state.validation);
+        }
+    });
+}
+// Shallow equality is sufficient here because all values in Intl.NumberFormatOptions are primitives.
+function isEqualFormatOptions(a, b) {
+    if (a === b) {
+        return true;
+    }
+    if (!a || !b) {
+        return false;
+    }
+    const aKeys = Object.keys(a);
+    const bKeys = Object.keys(b);
+    if (aKeys.length !== bKeys.length) {
+        return false;
+    }
+    for (const key of aKeys) {
+        if (b[key] !== a[key]) {
+            return false;
+        }
+    }
+    return true;
+}
+function handleDecimalOperation(operator, value1, value2) {
+    let result = operator === "+" ? value1 + value2 : value1 - value2;
+    // Check if we have decimals
+    if (value1 % 1 !== 0 || value2 % 1 !== 0) {
+        const value1Decimal = value1.toString().split(".");
+        const value2Decimal = value2.toString().split(".");
+        const value1DecimalLength = (value1Decimal[1] && value1Decimal[1].length) || 0;
+        const value2DecimalLength = (value2Decimal[1] && value2Decimal[1].length) || 0;
+        const multiplier = Math.pow(10, Math.max(value1DecimalLength, value2DecimalLength));
+        // Transform the decimals to integers based on the precision
+        value1 = Math.round(value1 * multiplier);
+        value2 = Math.round(value2 * multiplier);
+        // Perform the operation on integers values to make sure we don't get a fancy decimal value
+        result = operator === "+" ? value1 + value2 : value1 - value2;
+        // Transform the integer result back to decimal
+        result /= multiplier;
+    }
+    return result;
+}

package/number-field/behaviour.d.ts

@@ -0,0 +1,165 @@
+import { type MaybeAccessor } from "../interactions/utils.js";
+import type { PressEvent } from "../interactions/press.jsx";
+import { type FieldIds } from "../label/behaviour.js";
+import { type ValidationResult } from "../state/form-validation.js";
+import { type NumberFieldProps, type NumberFieldState } from "../number/number-field-state.jsx";
+import { type SpinButtonProps, type SpinButtonState } from "../spinbutton/behaviour.jsx";
+type Bag = Record<string, unknown>;
+export interface AriaNumberFieldProps extends NumberFieldProps {
+    /** The input id (label / description / error ids derive from it). Read once at mount. */
+    id?: string;
+    /** The content of the visible label (RA `label`; any truthy value = a label renders). */
+    label?: unknown;
+    /** RA `description` (truthy: a description renders). */
+    description?: unknown;
+    /** RA `errorMessage`. */
+    errorMessage?: unknown;
+    placeholder?: string;
+    /** A value, or an accessor that stays live (live props). */
+    isRequired?: MaybeAccessor<boolean | undefined>;
+    /** Whether the input takes focus when it mounts. Read once at mount. */
+    autoFocus?: boolean;
+    /** The name of the hidden input submitted with a form. Read once at mount (form identity). */
+    name?: string;
+    form?: string;
+    /**
+     * A custom aria-label for the decrement button. If not provided, the localized string "Decrement"
+     * is used. Read once at mount (it decides the button's labelling ids).
+     */
+    decrementAriaLabel?: string;
+    /**
+     * A custom aria-label for the increment button. If not provided, the localized string "Increment"
+     * is used. Read once at mount (it decides the button's labelling ids).
+     */
+    incrementAriaLabel?: string;
+    /** Enables or disables changing the value with scroll (a value, or an accessor read at scroll time). */
+    isWheelDisabled?: MaybeAccessor<boolean | undefined>;
+    /** Rivet: the locale (RA `useLocale()`); required (`I18nProvider` in the component). */
+    locale: MaybeAccessor<string>;
+    /** Read once at mount (combined with the label into the input's and the steppers' labels). */
+    "aria-label"?: string;
+    /** Read once at mount (combined with the label into the input's and the steppers' labels). */
+    "aria-labelledby"?: string;
+    "aria-describedby"?: string;
+    "aria-details"?: string;
+    "aria-errormessage"?: string;
+    onFocus?: (e: FocusEvent) => void;
+    onBlur?: (e: FocusEvent) => void;
+    onFocusChange?: (isFocused: boolean) => void;
+    onKeyDown?: (e: KeyboardEvent) => void;
+    onKeyUp?: (e: KeyboardEvent) => void;
+    onCopy?: (e: ClipboardEvent) => void;
+    onCut?: (e: ClipboardEvent) => void;
+    onPaste?: (e: ClipboardEvent) => void;
+    onCompositionStart?: (e: CompositionEvent) => void;
+    onCompositionEnd?: (e: CompositionEvent) => void;
+    onCompositionUpdate?: (e: CompositionEvent) => void;
+    onSelect?: (e: Event) => void;
+    onBeforeInput?: (e: InputEvent) => void;
+    onInput?: (e: Event) => void;
+}
+export interface NumberFieldAria {
+    /** Props for the label element. */
+    labelProps: Bag;
+    /** Props for the group wrapper around the input and stepper buttons. */
+    groupProps: Bag;
+    /** Props for the input element. */
+    inputProps: Bag;
+    /** Props for the increment button (Button / useButton props). */
+    incrementButtonProps: Bag;
+    /** Props for the decrement button (Button / useButton props). */
+    decrementButtonProps: Bag;
+    /** Props for the number field's description element, if any. */
+    descriptionProps: Bag;
+    /** Props for the number field's error message element, if any. */
+    errorMessageProps: Bag;
+    isInvalid: () => boolean;
+    validationErrors: () => string[];
+    validationDetails: () => ValidationResult["validationDetails"];
+    /** Rivet: ids of the parts. */
+    ids: FieldIds & {
+        inputId: string;
+        incrementId: string;
+        decrementId: string;
+    };
+    /** Rivet: the spin button's state (RA refs of useSpinButton; plain JSON). */
+    spin: SpinButtonState;
+    /** Rivet: focus-within state of the group (RA `useFocusWithin` + `focusWithin` state). */
+    within: {
+        isFocusWithin: boolean;
+        globals: (() => void)[];
+    };
+    /** Rivet: a native `change` committed the validation since the input got focus (re-committed after blur's commit). */
+    edit: {
+        changed: boolean;
+    };
+}
+/** RA `textValue`: the number formatted without `currencySign: 'accounting'` (announced with a minus sign). */
+export declare function numberFieldTextValue(props: AriaNumberFieldProps, state: NumberFieldState): string;
+/** RA `inputMode`: numeric / decimal / text by platform and whether negative / fractional numbers are allowed. */
+export declare function numberFieldInputMode(props: AriaNumberFieldProps, state: NumberFieldState): "numeric" | "decimal" | "text";
+/** The spin button props RA passes to useSpinButton (built at event time: browser-only closures). */
+export declare function numberFieldSpinProps(props: AriaNumberFieldProps, state: NumberFieldState): SpinButtonProps;
+/**
+ * Provides the behavior and accessibility implementation for a number field component. Number
+ * fields allow users to enter a number, and increment or decrement the value using stepper
+ * buttons (RA `useNumberField`).
+ */
+export declare function numberFieldProps(props: AriaNumberFieldProps, state: NumberFieldState): NumberFieldAria;
+/**
+ * RA `useNativeValidation` (commitBehavior 'validate'): validity of min / max / step from a native number input,
+ * merged with the text input's validity (browser messages, no own translations).
+ */
+export declare function numberFieldNativeValidation(props: AriaNumberFieldProps, state: NumberFieldState, input: HTMLInputElement | null): void;
+/** RA text field `onChange` (native `input`): accept the text if it is a valid partial number. */
+export declare function numberFieldInput(event: Event, props: AriaNumberFieldProps, state: NumberFieldState, _aria?: NumberFieldAria): void;
+/**
+ * Native `change` (RA useFormValidation change listener): commit the validation. RA defers that commit to after the
+ * next render, so it sees the validity of the blur's number commit (`change` fires before `blur`): the blur handler
+ * commits again when a change was committed during this edit.
+ */
+export declare function numberFieldChange(event: Event, props: AriaNumberFieldProps, state: NumberFieldState, aria?: NumberFieldAria): void;
+/** `invalid` (form submit / checkValidity). */
+export declare function numberFieldInvalid(event: Event, props: AriaNumberFieldProps, state: NumberFieldState): void;
+/** RA `commitAndAnnounce`: commit the input, announce the normalized text when it changed. */
+export declare function numberFieldCommitAndAnnounce(props: AriaNumberFieldProps, state: NumberFieldState, input: HTMLInputElement | null): void;
+/** focus of the input: spin button focus, native custom validity, the platform input mode, user focus events. */
+export declare function numberFieldFocus(event: FocusEvent, props: AriaNumberFieldProps, state: NumberFieldState, aria: NumberFieldAria): void;
+/** blur of the input (RA chain: spin button onBlur, useFocus onBlur → commitAndAnnounce, text field onBlur). */
+export declare function numberFieldBlur(event: FocusEvent, props: AriaNumberFieldProps, state: NumberFieldState, aria: NumberFieldAria): void;
+/** keydown of the input: spin button shortcuts, then Enter commits (RA `useKeyboard` + user `onKeyDown`). */
+export declare function numberFieldKeyDown(event: KeyboardEvent, props: AriaNumberFieldProps, state: NumberFieldState, aria: NumberFieldAria): void;
+/** keyup of the input. */
+export declare function numberFieldKeyUp(event: KeyboardEvent, props: AriaNumberFieldProps, state: NumberFieldState, aria: NumberFieldAria): void;
+/** RA `onPaste`: a paste replacing the whole text commits it at once (the user sees the formatted result). */
+export declare function numberFieldPaste(event: ClipboardEvent, props: AriaNumberFieldProps, state: NumberFieldState): void;
+/** beforeinput (useFormattedTextField): cancel input that would make an invalid partial number. */
+export declare function numberFieldBeforeInput(event: InputEvent, props: AriaNumberFieldProps, state: NumberFieldState): void;
+export declare function numberFieldCompositionStart(event: CompositionEvent, props: AriaNumberFieldProps, _state: NumberFieldState): void;
+export declare function numberFieldCompositionEnd(event: CompositionEvent, props: AriaNumberFieldProps, state: NumberFieldState): void;
+/** RA `onWheel`: vertical wheel increments / decrements (trackpad: mostly-horizontal motion is ignored). */
+export declare function numberFieldScroll(e: {
+    deltaX: number;
+    deltaY: number;
+}, state: NumberFieldState): void;
+/** focusin of the group (RA useFocusWithin): focus within → the input's non-passive wheel listener (useScrollWheel). */
+export declare function numberFieldGroupFocusIn(event: FocusEvent, props: AriaNumberFieldProps, state: NumberFieldState, aria: NumberFieldAria): void;
+/** focusout of the group. */
+export declare function numberFieldGroupFocusOut(event: FocusEvent, props: AriaNumberFieldProps, _state: NumberFieldState, aria: NumberFieldAria): void;
+/**
+ * RA `onButtonPressStart` (both stepper buttons): keep focus on the input if it has it (software keyboard stays);
+ * a mouse moves focus to the input; touch / screen reader focus the button.
+ */
+export declare function numberFieldButtonPressStart(e: PressEvent, _props: AriaNumberFieldProps, _state: NumberFieldState, aria: NumberFieldAria): void;
+export declare function numberFieldIncrementPressStart(e: PressEvent, props: AriaNumberFieldProps, state: NumberFieldState, aria: NumberFieldAria): void;
+export declare function numberFieldIncrementPressUp(e: PressEvent, props: AriaNumberFieldProps, state: NumberFieldState, aria: NumberFieldAria): void;
+export declare function numberFieldIncrementPressEnd(e: PressEvent, props: AriaNumberFieldProps, state: NumberFieldState, aria: NumberFieldAria): void;
+export declare function numberFieldDecrementPressStart(e: PressEvent, props: AriaNumberFieldProps, state: NumberFieldState, aria: NumberFieldAria): void;
+export declare function numberFieldDecrementPressUp(e: PressEvent, props: AriaNumberFieldProps, state: NumberFieldState, aria: NumberFieldAria): void;
+export declare function numberFieldDecrementPressEnd(e: PressEvent, props: AriaNumberFieldProps, state: NumberFieldState, aria: NumberFieldAria): void;
+/** focus / blur of a stepper button (useSpinButton's onFocus / onBlur). */
+export declare function numberFieldButtonFocus(e: FocusEvent, props: AriaNumberFieldProps, state: NumberFieldState, aria: NumberFieldAria): void;
+export declare function numberFieldButtonBlur(e: FocusEvent, props: AriaNumberFieldProps, state: NumberFieldState, aria: NumberFieldAria): void;
+/** RA unmount cleanup (spin timers, global listeners, wheel listener). */
+export declare function numberFieldDispose(aria: NumberFieldAria): void;
+export {};