@react-md/form/lib/text-field/useNumberField.d.ts

This package is for creating all the different form input types.

import type { Dispatch, SetStateAction } from "react";
import type { ProvidedTextFieldMessageProps, ProvidedTextFieldProps, TextFieldHookOptions } from "./useTextField";
/**
 * @remarks \@since 2.5.0
 */
export interface NumberFieldConstraints {
    /**
     * An optional min value for the number field.
     */
    min?: number;
    /**
     * An optional max value for the number field.
     */
    max?: number;
    /**
     * An optional step amount to use.
     *
     * Note: The `min` and `max` values must be divisible by this value when any
     * are defined.
     */
    step?: number;
}
/**
 * @remarks \@since 2.5.0
 */
export interface ProvidedNumberFieldProps extends NumberFieldConstraints, ProvidedTextFieldProps {
    /**
     * Always set the `TextField` type to `number`.
     */
    type: "number";
}
/**
 * This is how the value within the text field should be "fixed" on blur. By
 * default, the value will not be fixed and continue to display an error if
 * there is an error.
 *
 * If this is set to `true`, the value will be updated to be within the `min`
 * and `max` values. Otherwise, setting this to `min` will only fix the minimum
 * value while `max` will only fix the maximum.
 *
 * @remarks \@since 2.5.0
 */
export declare type FixNumberOnBlur = boolean | "min" | "max";
/**
 * @remarks \@since 2.5.0
 */
export interface ProvidedNumberFieldMessageProps extends ProvidedNumberFieldProps, Pick<ProvidedTextFieldMessageProps, "messageProps"> {
}
/**
 * @remarks \@since 2.5.0
 */
export interface NumberFieldHookOptions extends Omit<TextFieldHookOptions, "defaultValue">, NumberFieldConstraints {
    /**
     * The default **number** value to use which can be a `number` or `undefined`.
     * When this value is set to a `number` (or a function that returns a
     * `number`), the returned value will never be `undefined`.
     */
    defaultValue?: number | (() => number | undefined);
    /**
     * @see {@link FixNumberOnBlur}
     */
    fixOnBlur?: FixNumberOnBlur;
    /**
     * Boolean if the `number` value should be updated as the user types instead
     * of only once the text field has been blurred.
     */
    updateOnChange?: boolean;
}
/**
 * @remarks \@since 2.5.0
 */
export interface NumberFieldHookControls {
    /**
     * Resets the `number` value to the `defaultValue` and clears any error
     * states.
     */
    reset(): void;
    setNumber: Dispatch<SetStateAction<number | undefined>>;
}
/**
 * An ordered list containing:
 * - the current `number` value of the field which will be updated based on the
 *   {@link NumberFieldHookOptions.updateOnChange} option
 *
 * @remarks \@since 2.5.0
 */
export declare type NumberFieldHookReturnType = [
    number | undefined,
    ProvidedNumberFieldProps | ProvidedNumberFieldMessageProps,
    NumberFieldHookControls
];
/**
 * This hook is used to control the value for the `TextField` component acting
 * as an `<input type="number">` and ensuring that a "valid" `number` is
 * available. There is also built-in support for using the validity
 * api/constraint validation so that real-time errors can be presented to the
 * user as they type along with the `FormMessage` component.
 *
 * Simple example:
 *
 * ```tsx
 * const [value, fieldProps] = useNumberField({
 *   id: 'field-id',
 *   min: 0,
 *   max: 10,
 *   defaultValue: 0,
 *   disableMessage: true,
 * });
 *
 * return <TextField {...fieldProps} label="Label" placeholder="0" />;
 * ```
 *
 * Step example and messaging:
 *
 * ```tsx
 * const [value, fieldProps] = useNumberField({
 *   id: 'field-id',
 *   min: 0,
 *   max: 10,
 *   step: 2,
 *   defaultValue: 0,
 * });
 *
 * return <TextFieldWithMessage {...fieldProps} label="Label" placeholder="0" />;
 * ```
 *
 * @see https://developer.mozilla.org/en-US/docs/Web/Guide/HTML/HTML5/Constraint_validation
 * @see {@link useTextField}
 * @param options - All the options used to control the functionality of this
 * hook.
 * @returns @see {@link NumberFieldHookReturnType}
 * @remarks \@since 2.5.0
 */
export declare function useNumberField(options: NumberFieldHookOptions & {
    defaultValue: number | (() => number);
    disableMessage: true;
}): [number, ProvidedNumberFieldProps, NumberFieldHookControls];
export declare function useNumberField(options: NumberFieldHookOptions & {
    defaultValue: number | (() => number);
    disableMessage: false;
}): [number, ProvidedNumberFieldMessageProps, NumberFieldHookControls];
export declare function useNumberField(options: NumberFieldHookOptions & {
    defaultValue: number | (() => number);
    disableMessage?: boolean;
}): [number, ProvidedNumberFieldMessageProps, NumberFieldHookControls];
export declare function useNumberField(options: NumberFieldHookOptions & {
    disableMessage: true;
}): [number | undefined, ProvidedNumberFieldProps, NumberFieldHookControls];
export declare function useNumberField(options: NumberFieldHookOptions & {
    disableMessage: false;
}): [
    number | undefined,
    ProvidedNumberFieldMessageProps,
    NumberFieldHookControls
];
export declare function useNumberField(options: NumberFieldHookOptions & {
    disableMessage?: boolean;
}): [
    number | undefined,
    ProvidedNumberFieldMessageProps,
    NumberFieldHookControls
];