@react-md/core 1.0.0-next.0

package/dist/form/useNumberField.d.ts

@@ -0,0 +1,292 @@
+import { type UseStateInitializer, type UseStateSetter } from "../types.js";
+import { type ProvidedTextFieldMessageProps, type ProvidedTextFieldProps, type TextFieldHookOptions, type TextFieldHookState, type TextFieldImplementation, type ValidatedTextFieldImplementation } from "./useTextField.js";
+/** @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
+ * \@since 6.0.0
+ * - Removed `updateOnChange` in favor of `updateValue`
+ * - Renamed `fixOnBlur` to `updateValueOnBlur`
+ */
+export interface NumberFieldHookOptions extends Omit<TextFieldHookOptions<HTMLInputElement>, "defaultValue" | "isNumber">, NumberFieldConstraints {
+    /**
+     * @defaultValue `undefined`
+     */
+    defaultValue?: UseStateInitializer<number>;
+    /**
+     * This controls the behavior for the `value` returned by this hook. If you
+     * need access to the current value immediately as the user types to update
+     * other components, keep this as the default of `"change"`. Otherwise, set
+     * this to `"blur"`.
+     *
+     * @example
+     * Deferring Updates on Blur
+     * ```tsx
+     * import { TextField, useNumberField } from "@react-md/core";
+     * import type { ReactElement } from "react";
+     *
+     * function Example(): ReactElement {
+     *   const { fieldProps, value } = useNumberField({
+     *     min: 0,
+     *     max: 100,
+     *     name: "someName",
+     *     defaultValue: 0,
+     *     updateValue: "blur",
+     *   });
+     *
+     *   const result = useMemo(() => someExpensiveComputation(value), [value]);
+     *
+     *   return <TextField {...fieldProps} label="Label" />;
+     * }
+     * ```
+     *
+     * @defaultValue `"change"`
+     */
+    updateValue?: "blur" | "change";
+    /**
+     * This option is used to update the `number` value and text field value to be
+     * within the `min` and `max` range or just format the text field value when
+     * the input is blurred. This update will only be applied if the text field
+     * contains a valid number. Using `min = 0` and `max = 10`:
+     *
+     * | text value | updated value |
+     * | ---------- | ------------- |
+     * | 000001     | 1             |
+     * | -1         | 0             |
+     * | 20         | 10            |
+     * | -12        | 0             |
+     * | --1        | --1           |
+     * | fjdka      | fjdka         |
+     *
+     *
+     * Set this to `false` if no changed should be applied and force the user to
+     * fix any min/max errors manually and maintain weird formatting.
+     *
+     * @defaultValue `true`
+     * @remarks \@since 6.0.0 This was renamed from `fixOnBlur` and removed the
+     * `"min"` and `"max"` behavior.
+     */
+    updateValueOnBlur?: boolean;
+}
+/** @remarks \@since 6.0.0 */
+export interface NumberFieldHookState extends Omit<TextFieldHookState, "value"> {
+    value: number | undefined;
+}
+/** @remarks \@since 2.5.6 */
+export interface ProvidedNumberFieldProps extends ProvidedTextFieldProps<HTMLInputElement>, NumberFieldConstraints {
+    type: "number";
+}
+/** @remarks \@since 2.5.6 */
+export interface ProvidedNumberFieldMessageProps extends ProvidedTextFieldMessageProps<HTMLInputElement>, NumberFieldConstraints {
+    type: "number";
+}
+/** @remarks \@since 6.0.0 */
+export interface NumberFieldImplementation extends Omit<TextFieldImplementation<HTMLInputElement>, "value" | "setState"> {
+    value: number | undefined;
+    setState: UseStateSetter<NumberFieldHookState>;
+    fieldProps: ProvidedNumberFieldProps;
+}
+/** @remarks \@since 6.0.0 */
+export interface NumberFieldWithMessageImplementation extends NumberFieldImplementation {
+    fieldProps: ProvidedNumberFieldMessageProps;
+}
+/** @remarks \@since 6.0.0 */
+export interface ValidatedNumberFieldImplementation extends Omit<ValidatedTextFieldImplementation<HTMLInputElement>, "value" | "setState"> {
+    value: number | undefined;
+    setState: UseStateSetter<NumberFieldHookState>;
+    fieldProps: ProvidedNumberFieldProps | ProvidedNumberFieldMessageProps;
+}
+/**
+ * @example
+ * Enforce Number Value and No Error Messages
+ * ```tsx
+ * import { TextField, useNumberField } from "@react-md/core";
+ * import type { ReactElement } from "react";
+ *
+ * function Example(): ReactElement {
+ *   const { fieldProps, value } = useNumberField({
+ *     min: 0,
+ *     max: 100,
+ *     name: "someName",
+ *     defaultValue: 0,
+ *     disableMessage: true,
+ *   });
+ *
+ *   // this is safe since `value` will always be a number even if there is a
+ *   // validation error. since the min and max options were provided as well,
+ *   // number will be between that range as well.
+ *   const computed = value * 10;
+ *
+ *   return <TextField {...fieldProps} label="Label" />;
+ * }
+ *
+ * @see {@link useTextField}
+ * @see {@link useNumberField} overrides for other examples.
+ * ```
+ */
+export declare function useNumberField(options: NumberFieldHookOptions & {
+    disableMessage: true;
+    defaultValue: UseStateInitializer<number>;
+}): NumberFieldImplementation & {
+    value: number;
+    setState: UseStateSetter<NumberFieldHookState & {
+        value: number;
+    }>;
+};
+/**
+ * @example
+ * No Error Messages
+ * ```tsx
+ * import { TextField, useNumberField } from "@react-md/core";
+ * import type { ReactElement } from "react";
+ *
+ * function Example(): ReactElement {
+ *   const { fieldProps, value } = useNumberField({
+ *     min: 0,
+ *     max: 100,
+ *     name: "someName",
+ *     disableMessage: true,
+ *   });
+ *
+ *   // `value` will be `undefined` until the user enters a valid value once
+ *   // there is a valid value, `value` will be a `number`. So this might cause
+ *   // `computed` to be `NaN | number`
+ *   //
+ *   // const computed = value * 10;
+ *
+ *   return <TextField {...fieldProps} label="Label" />;
+ * }
+ * ```
+ *
+ * @see {@link useTextField}
+ * @see {@link useNumberField} overrides for other examples.
+ */
+export declare function useNumberField(options: NumberFieldHookOptions & {
+    disableMessage: true;
+}): NumberFieldImplementation;
+/**
+ * @example
+ * Enforce Number Value
+ * ```tsx
+ * import { TextField, useNumberField } from "@react-md/core";
+ * import type { ReactElement } from "react";
+ *
+ * function Example(): ReactElement {
+ *   const { fieldProps, value } = useNumberField({
+ *     min: 0,
+ *     max: 100,
+ *     name: "someName",
+ *     defaultValue: 0,
+ *   });
+ *
+ *   // this is safe since `value` will always be a number even if there is a
+ *   // validation error. since the min and max options were provided as well,
+ *   // number will be between that range as well.
+ *   const computed = value * 10;
+ *
+ *   return <TextField {...fieldProps} label="Label" />;
+ * }
+ * ```
+ *
+ * @example
+ * Enforce Number Value and Deferring Updates
+ * ```tsx
+ * import { TextField, useNumberField } from "@react-md/core";
+ * import type { ReactElement } from "react";
+ *
+ * function Example(): ReactElement {
+ *   const { fieldProps, value } = useNumberField({
+ *     min: 0,
+ *     max: 100,
+ *     name: "someName",
+ *     defaultValue: 0,
+ *     updateValue: "blur",
+ *   });
+ *
+ *   // the `value` will only be updated whenever the `TextField` is blurred.
+ *   // This is helpful if the `value` is used in expensive computations or
+ *   // updates that do not need to be updated as the user types
+ *   const computed = value * 10;
+ *
+ *   return <TextField {...fieldProps} label="Label" />;
+ * }
+ * ```
+ *
+ * @see {@link useTextField}
+ * @see {@link useNumberField} overrides for other examples.
+ */
+export declare function useNumberField(options: NumberFieldHookOptions & {
+    defaultValue: UseStateInitializer<number>;
+}): NumberFieldWithMessageImplementation & {
+    value: number;
+    setState: UseStateSetter<NumberFieldHookState & {
+        value: number;
+    }>;
+};
+/**
+ * The `useNumberField` hook is used to control the state of a `TextField` or
+ * `<input type="number">`
+ *
+ * @example
+ * Default Implementation
+ * ```tsx
+ * import { TextField, useNumberField } from "@react-md/core";
+ * import type { ReactElement } from "react";
+ *
+ * function Example(): ReactElement {
+ *   const { fieldProps, value } = useNumberField({
+ *     name: "someName",
+ *   });
+ *
+ *   // `value` will be `undefined` until the user enters a valid value once
+ *   // there is a valid value, `value` will be a `number`. So this might cause
+ *   // `computed` to be `NaN | number`
+ *   //
+ *   // const computed = value * 10;
+ *
+ *   // whenever there is an error, an error message will be displayed below the
+ *   // `TextField`
+ *   return <TextField {...fieldProps} label="Label" />;
+ * }
+ * ```
+ *
+ * @example
+ * Adding Constraints
+ * ```tsx
+ * import { TextField, useNumberField } from "@react-md/core";
+ * import type { ReactElement } from "react";
+ *
+ * function Example(): ReactElement {
+ *   const { fieldProps, value } = useNumberField({
+ *     name: "someName",
+ *     min: 0,
+ *     max: 100,
+ *     step: 2,
+ *     required: true,
+ *   });
+ *
+ *   return <TextField {...fieldProps} label="Label" />;
+ * }
+ * ```
+ *
+ * @see https://developer.mozilla.org/en-US/docs/Web/Guide/HTML/HTML5/Constraint_validation
+ * @see {@link useTextField}
+ */
+export declare function useNumberField(options: NumberFieldHookOptions): NumberFieldWithMessageImplementation;

package/dist/form/useNumberField.js

@@ -0,0 +1,123 @@
+"use client";
+import { useCallback, useRef, useState } from "react";
+import { withinRange } from "../utils/withinRange.js";
+import { useTextField } from "./useTextField.js";
+const noop = ()=>{
+// do nothing
+};
+/**
+ * @internal
+ * @see {@link useTextField}
+ * @see {@link useNumberField} overrides for other examples.
+ */ export function useNumberField(options) {
+    const { min, max, step, onBlur = noop, onChange = noop, updateValue = "change", updateValueOnBlur = true, defaultValue, ...textOptions } = options;
+    const [number, setNumber] = useState(defaultValue);
+    const initial = useRef(number);
+    const { value: _value, reset: resetTextField, fieldProps, setState: setTextFieldState, ...remaining } = useTextField({
+        ...textOptions,
+        isNumber: true,
+        defaultValue: `${number ?? ""}`,
+        onBlur (event) {
+            onBlur(event);
+            if (event.isPropagationStopped()) {
+                return;
+            }
+            const input = event.currentTarget;
+            input.setCustomValidity("");
+            input.checkValidity();
+            if (!updateValueOnBlur || // do nothing else since it's a weird value like: `"--0"` which causes
+            // the value to be `""` and `numberAsValue` to be `NaN`
+            input.validity.badInput) {
+                return;
+            }
+            let value = input.valueAsNumber;
+            if (input.value === "" && typeof initial.current === "number") {
+                value = min ?? initial.current;
+            }
+            // can't have both rangeUnderflow and rangeOverflow at the same time, so
+            // it's "safe" to always provide both
+            value = withinRange({
+                min,
+                max,
+                value
+            });
+            if (!Number.isNaN(value)) {
+                setNumber(value);
+                input.value = `${value}`;
+            } else if (typeof initial.current === "undefined") {
+                setNumber(undefined);
+            }
+        },
+        onChange (event) {
+            onChange(event);
+            if (event.isPropagationStopped() || updateValue === "blur") {
+                return;
+            }
+            const input = event.currentTarget;
+            input.checkValidity();
+            const value = withinRange({
+                min,
+                max,
+                value: event.currentTarget.valueAsNumber
+            });
+            if (!input.validity.valid && !input.validity.rangeUnderflow && !input.validity.rangeOverflow) {
+                return;
+            }
+            if (!Number.isNaN(value)) {
+                setNumber(value);
+            } else if (initial.current === undefined) {
+                setNumber(undefined);
+            }
+        }
+    });
+    const reset = useCallback(()=>{
+        resetTextField();
+        setNumber(initial.current);
+    }, [
+        resetTextField
+    ]);
+    const setState = useCallback((nextState)=>{
+        if (typeof nextState === "function") {
+            setNumber((prevNumber)=>{
+                let nextNumber = prevNumber;
+                setTextFieldState((prevState)=>{
+                    const updated = nextState({
+                        ...prevState,
+                        value: prevNumber
+                    });
+                    nextNumber = updated.value;
+                    return {
+                        ...updated,
+                        value: `${nextNumber ?? ""}`
+                    };
+                });
+                return nextNumber;
+            });
+            return;
+        }
+        const { value, error, errorMessage } = nextState;
+        setNumber(value);
+        setTextFieldState({
+            value: `${value ?? ""}`,
+            error,
+            errorMessage
+        });
+    }, [
+        setTextFieldState
+    ]);
+    return {
+        ...remaining,
+        reset,
+        value: number,
+        setState,
+        fieldProps: {
+            ...fieldProps,
+            min,
+            max,
+            step,
+            type: "number"
+        }
+    };
+}
+
+//# sourceMappingURL=useNumberField.js.map

package/dist/form/useNumberField.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/form/useNumberField.ts"],"sourcesContent":["\"use client\";\nimport { useCallback, useRef, useState } from \"react\";\nimport { type UseStateInitializer, type UseStateSetter } from \"../types.js\";\nimport { withinRange } from \"../utils/withinRange.js\";\nimport {\n  useTextField,\n  type ProvidedTextFieldMessageProps,\n  type ProvidedTextFieldProps,\n  type TextFieldHookOptions,\n  type TextFieldHookState,\n  type TextFieldImplementation,\n  type ValidatedTextFieldImplementation,\n} from \"./useTextField.js\";\n\nconst noop = (): void => {\n  // do nothing\n};\n\n/** @remarks \\@since 2.5.0 */\nexport interface NumberFieldConstraints {\n  /**\n   * An optional min value for the number field.\n   */\n  min?: number;\n\n  /**\n   * An optional max value for the number field.\n   */\n  max?: number;\n\n  /**\n   * An optional step amount to use.\n   *\n   * Note: The `min` and `max` values must be divisible by this value when any\n   * are defined.\n   */\n  step?: number;\n}\n\n/**\n * @remarks\n * \\@since 2.5.0\n * \\@since 6.0.0\n * - Removed `updateOnChange` in favor of `updateValue`\n * - Renamed `fixOnBlur` to `updateValueOnBlur`\n */\nexport interface NumberFieldHookOptions\n  extends Omit<\n      TextFieldHookOptions<HTMLInputElement>,\n      \"defaultValue\" | \"isNumber\"\n    >,\n    NumberFieldConstraints {\n  /**\n   * @defaultValue `undefined`\n   */\n  defaultValue?: UseStateInitializer<number>;\n\n  /**\n   * This controls the behavior for the `value` returned by this hook. If you\n   * need access to the current value immediately as the user types to update\n   * other components, keep this as the default of `\"change\"`. Otherwise, set\n   * this to `\"blur\"`.\n   *\n   * @example\n   * Deferring Updates on Blur\n   * ```tsx\n   * import { TextField, useNumberField } from \"@react-md/core\";\n   * import type { ReactElement } from \"react\";\n   *\n   * function Example(): ReactElement {\n   *   const { fieldProps, value } = useNumberField({\n   *     min: 0,\n   *     max: 100,\n   *     name: \"someName\",\n   *     defaultValue: 0,\n   *     updateValue: \"blur\",\n   *   });\n   *\n   *   const result = useMemo(() => someExpensiveComputation(value), [value]);\n   *\n   *   return <TextField {...fieldProps} label=\"Label\" />;\n   * }\n   * ```\n   *\n   * @defaultValue `\"change\"`\n   */\n  updateValue?: \"blur\" | \"change\";\n\n  /**\n   * This option is used to update the `number` value and text field value to be\n   * within the `min` and `max` range or just format the text field value when\n   * the input is blurred. This update will only be applied if the text field\n   * contains a valid number. Using `min = 0` and `max = 10`:\n   *\n   * | text value | updated value |\n   * | ---------- | ------------- |\n   * | 000001     | 1             |\n   * | -1         | 0             |\n   * | 20         | 10            |\n   * | -12        | 0             |\n   * | --1        | --1           |\n   * | fjdka      | fjdka         |\n   *\n   *\n   * Set this to `false` if no changed should be applied and force the user to\n   * fix any min/max errors manually and maintain weird formatting.\n   *\n   * @defaultValue `true`\n   * @remarks \\@since 6.0.0 This was renamed from `fixOnBlur` and removed the\n   * `\"min\"` and `\"max\"` behavior.\n   */\n  updateValueOnBlur?: boolean;\n}\n\n/** @remarks \\@since 6.0.0 */\nexport interface NumberFieldHookState\n  extends Omit<TextFieldHookState, \"value\"> {\n  value: number | undefined;\n}\n\n/** @remarks \\@since 2.5.6 */\nexport interface ProvidedNumberFieldProps\n  extends ProvidedTextFieldProps<HTMLInputElement>,\n    NumberFieldConstraints {\n  type: \"number\";\n}\n\n/** @remarks \\@since 2.5.6 */\nexport interface ProvidedNumberFieldMessageProps\n  extends ProvidedTextFieldMessageProps<HTMLInputElement>,\n    NumberFieldConstraints {\n  type: \"number\";\n}\n\n/** @remarks \\@since 6.0.0 */\nexport interface NumberFieldImplementation\n  extends Omit<\n    TextFieldImplementation<HTMLInputElement>,\n    \"value\" | \"setState\"\n  > {\n  value: number | undefined;\n  setState: UseStateSetter<NumberFieldHookState>;\n  fieldProps: ProvidedNumberFieldProps;\n}\n\n/** @remarks \\@since 6.0.0 */\nexport interface NumberFieldWithMessageImplementation\n  extends NumberFieldImplementation {\n  fieldProps: ProvidedNumberFieldMessageProps;\n}\n\n/** @remarks \\@since 6.0.0 */\nexport interface ValidatedNumberFieldImplementation\n  extends Omit<\n    ValidatedTextFieldImplementation<HTMLInputElement>,\n    \"value\" | \"setState\"\n  > {\n  value: number | undefined;\n  setState: UseStateSetter<NumberFieldHookState>;\n  fieldProps: ProvidedNumberFieldProps | ProvidedNumberFieldMessageProps;\n}\n\n/**\n * @example\n * Enforce Number Value and No Error Messages\n * ```tsx\n * import { TextField, useNumberField } from \"@react-md/core\";\n * import type { ReactElement } from \"react\";\n *\n * function Example(): ReactElement {\n *   const { fieldProps, value } = useNumberField({\n *     min: 0,\n *     max: 100,\n *     name: \"someName\",\n *     defaultValue: 0,\n *     disableMessage: true,\n *   });\n *\n *   // this is safe since `value` will always be a number even if there is a\n *   // validation error. since the min and max options were provided as well,\n *   // number will be between that range as well.\n *   const computed = value * 10;\n *\n *   return <TextField {...fieldProps} label=\"Label\" />;\n * }\n *\n * @see {@link useTextField}\n * @see {@link useNumberField} overrides for other examples.\n * ```\n */\nexport function useNumberField(\n  options: NumberFieldHookOptions & {\n    disableMessage: true;\n    defaultValue: UseStateInitializer<number>;\n  }\n): NumberFieldImplementation & {\n  value: number;\n  setState: UseStateSetter<NumberFieldHookState & { value: number }>;\n};\n\n/**\n * @example\n * No Error Messages\n * ```tsx\n * import { TextField, useNumberField } from \"@react-md/core\";\n * import type { ReactElement } from \"react\";\n *\n * function Example(): ReactElement {\n *   const { fieldProps, value } = useNumberField({\n *     min: 0,\n *     max: 100,\n *     name: \"someName\",\n *     disableMessage: true,\n *   });\n *\n *   // `value` will be `undefined` until the user enters a valid value once\n *   // there is a valid value, `value` will be a `number`. So this might cause\n *   // `computed` to be `NaN | number`\n *   //\n *   // const computed = value * 10;\n *\n *   return <TextField {...fieldProps} label=\"Label\" />;\n * }\n * ```\n *\n * @see {@link useTextField}\n * @see {@link useNumberField} overrides for other examples.\n */\nexport function useNumberField(\n  options: NumberFieldHookOptions & { disableMessage: true }\n): NumberFieldImplementation;\n\n/**\n * @example\n * Enforce Number Value\n * ```tsx\n * import { TextField, useNumberField } from \"@react-md/core\";\n * import type { ReactElement } from \"react\";\n *\n * function Example(): ReactElement {\n *   const { fieldProps, value } = useNumberField({\n *     min: 0,\n *     max: 100,\n *     name: \"someName\",\n *     defaultValue: 0,\n *   });\n *\n *   // this is safe since `value` will always be a number even if there is a\n *   // validation error. since the min and max options were provided as well,\n *   // number will be between that range as well.\n *   const computed = value * 10;\n *\n *   return <TextField {...fieldProps} label=\"Label\" />;\n * }\n * ```\n *\n * @example\n * Enforce Number Value and Deferring Updates\n * ```tsx\n * import { TextField, useNumberField } from \"@react-md/core\";\n * import type { ReactElement } from \"react\";\n *\n * function Example(): ReactElement {\n *   const { fieldProps, value } = useNumberField({\n *     min: 0,\n *     max: 100,\n *     name: \"someName\",\n *     defaultValue: 0,\n *     updateValue: \"blur\",\n *   });\n *\n *   // the `value` will only be updated whenever the `TextField` is blurred.\n *   // This is helpful if the `value` is used in expensive computations or\n *   // updates that do not need to be updated as the user types\n *   const computed = value * 10;\n *\n *   return <TextField {...fieldProps} label=\"Label\" />;\n * }\n * ```\n *\n * @see {@link useTextField}\n * @see {@link useNumberField} overrides for other examples.\n */\nexport function useNumberField(\n  options: NumberFieldHookOptions & {\n    defaultValue: UseStateInitializer<number>;\n  }\n): NumberFieldWithMessageImplementation & {\n  value: number;\n  setState: UseStateSetter<NumberFieldHookState & { value: number }>;\n};\n\n/**\n * The `useNumberField` hook is used to control the state of a `TextField` or\n * `<input type=\"number\">`\n *\n * @example\n * Default Implementation\n * ```tsx\n * import { TextField, useNumberField } from \"@react-md/core\";\n * import type { ReactElement } from \"react\";\n *\n * function Example(): ReactElement {\n *   const { fieldProps, value } = useNumberField({\n *     name: \"someName\",\n *   });\n *\n *   // `value` will be `undefined` until the user enters a valid value once\n *   // there is a valid value, `value` will be a `number`. So this might cause\n *   // `computed` to be `NaN | number`\n *   //\n *   // const computed = value * 10;\n *\n *   // whenever there is an error, an error message will be displayed below the\n *   // `TextField`\n *   return <TextField {...fieldProps} label=\"Label\" />;\n * }\n * ```\n *\n * @example\n * Adding Constraints\n * ```tsx\n * import { TextField, useNumberField } from \"@react-md/core\";\n * import type { ReactElement } from \"react\";\n *\n * function Example(): ReactElement {\n *   const { fieldProps, value } = useNumberField({\n *     name: \"someName\",\n *     min: 0,\n *     max: 100,\n *     step: 2,\n *     required: true,\n *   });\n *\n *   return <TextField {...fieldProps} label=\"Label\" />;\n * }\n * ```\n *\n * @see https://developer.mozilla.org/en-US/docs/Web/Guide/HTML/HTML5/Constraint_validation\n * @see {@link useTextField}\n */\nexport function useNumberField(\n  options: NumberFieldHookOptions\n): NumberFieldWithMessageImplementation;\n\n/**\n * @internal\n * @see {@link useTextField}\n * @see {@link useNumberField} overrides for other examples.\n */\nexport function useNumberField(\n  options: NumberFieldHookOptions\n): ValidatedNumberFieldImplementation {\n  const {\n    min,\n    max,\n    step,\n    onBlur = noop,\n    onChange = noop,\n    updateValue = \"change\",\n    updateValueOnBlur = true,\n    defaultValue,\n    ...textOptions\n  } = options;\n\n  const [number, setNumber] = useState(defaultValue);\n  const initial = useRef(number);\n  const {\n    value: _value,\n    reset: resetTextField,\n    fieldProps,\n    setState: setTextFieldState,\n    ...remaining\n  } = useTextField({\n    ...textOptions,\n    isNumber: true,\n    defaultValue: `${number ?? \"\"}`,\n    onBlur(event) {\n      onBlur(event);\n      if (event.isPropagationStopped()) {\n        return;\n      }\n\n      const input = event.currentTarget;\n      input.setCustomValidity(\"\");\n      input.checkValidity();\n      if (\n        !updateValueOnBlur ||\n        // do nothing else since it's a weird value like: `\"--0\"` which causes\n        // the value to be `\"\"` and `numberAsValue` to be `NaN`\n        input.validity.badInput\n      ) {\n        return;\n      }\n\n      let value = input.valueAsNumber;\n      if (input.value === \"\" && typeof initial.current === \"number\") {\n        value = min ?? initial.current;\n      }\n\n      // can't have both rangeUnderflow and rangeOverflow at the same time, so\n      // it's \"safe\" to always provide both\n      value = withinRange({ min, max, value });\n      if (!Number.isNaN(value)) {\n        setNumber(value);\n        input.value = `${value}`;\n      } else if (typeof initial.current === \"undefined\") {\n        setNumber(undefined);\n      }\n    },\n    onChange(event) {\n      onChange(event);\n      if (event.isPropagationStopped() || updateValue === \"blur\") {\n        return;\n      }\n\n      const input = event.currentTarget;\n      input.checkValidity();\n      const value = withinRange({\n        min,\n        max,\n        value: event.currentTarget.valueAsNumber,\n      });\n      if (\n        !input.validity.valid &&\n        !input.validity.rangeUnderflow &&\n        !input.validity.rangeOverflow\n      ) {\n        return;\n      }\n\n      if (!Number.isNaN(value)) {\n        setNumber(value);\n      } else if (initial.current === undefined) {\n        setNumber(undefined);\n      }\n    },\n  });\n\n  const reset = useCallback(() => {\n    resetTextField();\n    setNumber(initial.current);\n  }, [resetTextField]);\n  const setState = useCallback<UseStateSetter<NumberFieldHookState>>(\n    (nextState) => {\n      if (typeof nextState === \"function\") {\n        setNumber((prevNumber) => {\n          let nextNumber: number | undefined = prevNumber;\n          setTextFieldState((prevState) => {\n            const updated = nextState({\n              ...prevState,\n              value: prevNumber,\n            });\n\n            nextNumber = updated.value;\n\n            return {\n              ...updated,\n              value: `${nextNumber ?? \"\"}`,\n            };\n          });\n\n          return nextNumber;\n        });\n        return;\n      }\n\n      const { value, error, errorMessage } = nextState;\n      setNumber(value);\n      setTextFieldState({\n        value: `${value ?? \"\"}`,\n        error,\n        errorMessage,\n      });\n    },\n    [setTextFieldState]\n  );\n\n  return {\n    ...remaining,\n    reset,\n    value: number,\n    setState,\n    fieldProps: {\n      ...fieldProps,\n      min,\n      max,\n      step,\n      type: \"number\",\n    },\n  };\n}\n"],"names":["useCallback","useRef","useState","withinRange","useTextField","noop","useNumberField","options","min","max","step","onBlur","onChange","updateValue","updateValueOnBlur","defaultValue","textOptions","number","setNumber","initial","value","_value","reset","resetTextField","fieldProps","setState","setTextFieldState","remaining","isNumber","event","isPropagationStopped","input","currentTarget","setCustomValidity","checkValidity","validity","badInput","valueAsNumber","current","Number","isNaN","undefined","valid","rangeUnderflow","rangeOverflow","nextState","prevNumber","nextNumber","prevState","updated","error","errorMessage","type"],"mappings":"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"}

package/dist/form/useRadioGroup.d.ts

@@ -0,0 +1,192 @@
+import { type ChangeEventHandler, type FormEventHandler } from "react";
+import { type UseStateInitializer, type UseStateSetter } from "../types.js";
+/** @remarks \@since 6.0.0 */
+export interface RadioGroupOptions<T extends string | number> {
+    /**
+     * A `name` to apply to all the radios within the group. This is required if
+     * unless {@link menu} is set to `true`.
+     */
+    name?: string;
+    /**
+     * Set this to `true` if using the `MenuItemRadio` component instead of the
+     * `Radio` so the correct props can be provided.
+     *
+     * @defaultValue `false`
+     */
+    menu?: boolean;
+    /**
+     * The value of a radio that should be checked by default. If you want to
+     * force the user to select one of the radios, keep this as the empty string
+     * or set it to a string or number that does not represent a valid radio
+     * value.
+     *
+     * @defaultValue `""`
+     */
+    defaultValue?: UseStateInitializer<T>;
+    /**
+     * Set this to `true` if one of the radios within the group must be checked before
+     * a form can be submitted.
+     *
+     * This option is invalid and will be ignored if {@link menu} is `true`.
+     *
+     * @defaultValue `false`
+     */
+    required?: boolean;
+    /**
+     * If you need to prevent the default behavior in a radio group for some
+     * reason, you can provide a custom `onCHange` event handler and call
+     * `event.stopPropagation()`. This will be called whenever a new radio button
+     * is checked.
+     *
+     * This option is invalid and will be ignored if {@link menu} is `true`.
+     *
+     * @defaultValue `() => {}`
+     */
+    onChange?: ChangeEventHandler<HTMLInputElement>;
+    /**
+     * If the radio group has {@link required} set to `true`, the radios will gain
+     * the `error` state if a form is submitted without a checked radio. If you
+     * want to prevent that behavior for some reason, you can provide this
+     * function and call `event.stopPropagation()`.
+     *
+     * This option is invalid and will be ignored if {@link menu} is `true`.
+     *
+     * @defaultValue `() => {}`
+     */
+    onInvalid?: FormEventHandler<HTMLInputElement>;
+}
+/** @remarks \@since 6.0.0 */
+export interface ProvidedRadioGroupProps<V extends string | number> {
+    name: string;
+    value: V;
+    checked: boolean;
+    onChange: ChangeEventHandler<HTMLInputElement>;
+    error: boolean;
+    required: boolean;
+    onInvalid: FormEventHandler<HTMLInputElement>;
+}
+/** @remarks \@since 6.0.0 */
+export type GetRadioGroupProps<V extends string | number> = (value: V) => Readonly<ProvidedRadioGroupProps<V>>;
+/** @remarks \@since 6.0.0 */
+export interface RadioGroupImplementation<V extends string | number> {
+    reset(): void;
+    value: V;
+    setValue: UseStateSetter<V>;
+    getRadioProps: GetRadioGroupProps<V>;
+}
+export type GetMenuItemRadioGroupProps<V extends string | number> = (value: V) => Readonly<{
+    checked: boolean;
+    onCheckedChange(): void;
+}>;
+/** @remarks \@since 6.0.0 */
+export interface MenuItemRadioGroupImplementation<V extends string | number> {
+    reset(): void;
+    value: V;
+    setValue: UseStateSetter<V>;
+    getRadioProps: GetMenuItemRadioGroupProps<V>;
+}
+/** @remarks \@since 6.0.0 */
+export interface CombinedRadioGroupReturnValue<V extends string | number> {
+    reset(): void;
+    value: V;
+    setValue: UseStateSetter<V>;
+    getRadioProps?(value: V): {
+        name?: string;
+        value?: V;
+        checked: boolean;
+        error?: boolean;
+        required?: boolean;
+        onChange?: ChangeEventHandler<HTMLInputElement>;
+        onCheckedChange?(): void;
+        onInvalid?: FormEventHandler<HTMLInputElement>;
+    };
+}
+/**
+ * @example
+ * Generic Number Example
+ * ```tsx
+ * const { value, getRadioProps } = useRadioGroup<number>({
+ *   name: "group",
+ *   defaultValue: -1
+ * });
+ *
+ *
+ * return (
+ *   <>
+ *     <Radio {...getRadioProps(0)} label="First" />
+ *     <Radio {...getRadioProps(1)} label="Second" />
+ *     <Radio {...getRadioProps(2)} label="Third" />
+ *   </>
+ * );
+ * ```
+ * @remarks \@since 6.0.0
+ */
+export declare function useRadioGroup<V extends number>(options: RadioGroupOptions<V> & {
+    menu?: false;
+    name: string;
+    defaultValue: UseStateInitializer<V>;
+}): RadioGroupImplementation<V>;
+export declare function useRadioGroup<V extends number>(options: RadioGroupOptions<V> & {
+    menu: true;
+    name?: never;
+    required?: never;
+    onChange?: never;
+    onInvalid?: never;
+    defaultValue: UseStateInitializer<V>;
+}): MenuItemRadioGroupImplementation<V>;
+/**
+ * @example
+ * Generic String Example
+ * ```tsx
+ * const { value, getRadioProps } = useRadioGroup({ name: "group" });
+ *
+ * return (
+ *   <>
+ *     <Radio {...getRadioProps("a")} label="First" />
+ *     <Radio {...getRadioProps("b")} label="Second" />
+ *     <Radio {...getRadioProps("c")} label="Third" />
+ *   </>
+ * );
+ * ```
+ *
+ * @example
+ * String Union Example
+ * ```tsx
+ * const values = [
+ *   { label: "First", value: "a" },
+ *   { label: "Second", value: "b" },
+ *   { label: "Third", value: "c" },
+ * ] as const;
+ *
+ * type Values = typeof values[number]["value"];
+ * //   ^ "a" | "b" | "c"
+ *
+ * const { value, getRadioProps } = useRadioGroup<Values | "">({
+ *   name: "group",
+ *   defaultValue: "",
+ * });
+ *
+ *
+ * return (
+ *   <>
+ *     {values.map(({ label, value }) => (
+ *       <Radio {...getRadioProps(value)} key={value} label={label} />
+ *     ))}
+ *   </>
+ * );
+ * ```
+ * @remarks \@since 6.0.0
+ */
+export declare function useRadioGroup<V extends string>(options: RadioGroupOptions<V> & {
+    menu?: false;
+    name: string;
+    defaultValue?: UseStateInitializer<V>;
+}): RadioGroupImplementation<V>;
+export declare function useRadioGroup<V extends string>(options: RadioGroupOptions<V> & {
+    menu: true;
+    name?: never;
+    required?: never;
+    onChange?: never;
+    onInvalid?: never;
+    defaultValue?: UseStateInitializer<V>;
+}): MenuItemRadioGroupImplementation<V>;