@ariakit/react-core 0.3.11 → 0.3.13

package/cjs/form/form-radio-group.d.ts

@@ -19,15 +19,20 @@ import type { FormGroupOptions } from "./form-group.js";
  */
 export declare const useFormRadioGroup: import("../utils/types.js").Hook<FormRadioGroupOptions<"div">>;
 /**
- * Renders a radio group in a form.
+ * Renders a group element for
+ * [`FormRadio`](https://ariakit.org/reference/form-radio) elements. The
+ * [`FormGroupLabel`](https://ariakit.org/reference/form-group-label) component
+ * can be used inside this component so the `aria-labelledby` prop is properly
+ * set on the group element.
  * @see https://ariakit.org/components/form
  * @example
- * ```jsx
+ * ```jsx {8-13}
  * const form = useFormStore({
  *   defaultValues: {
  *     color: "red",
  *   },
  * });
+ *
  * <Form store={form}>
  *   <FormRadioGroup>
  *     <FormGroupLabel>Favorite color</FormGroupLabel>

package/cjs/form/form-radio.cjs

@@ -1,28 +1,28 @@
 "use strict";Object.defineProperty(exports, "__esModule", {value: true});"use client";
 
 
-var _VCDQISP7cjs = require('../__chunks/VCDQISP7.cjs');
+var _N3XK7EAHcjs = require('../__chunks/N3XK7EAH.cjs');
 
 
 var _FROYTN4Bcjs = require('../__chunks/FROYTN4B.cjs');
 
 
-var _IAYTETYNcjs = require('../__chunks/IAYTETYN.cjs');
+var _MMRX6FNScjs = require('../__chunks/MMRX6FNS.cjs');
 require('../__chunks/HEEQY4DZ.cjs');
-require('../__chunks/3RUODFRU.cjs');
-require('../__chunks/DAJUUBUI.cjs');
+require('../__chunks/GSETTLOU.cjs');
+require('../__chunks/OSTQZD2E.cjs');
 require('../__chunks/R5A2WTWB.cjs');
-require('../__chunks/RV3PHHWM.cjs');
+require('../__chunks/6ZZYUFPW.cjs');
 require('../__chunks/UZNYSPKP.cjs');
 require('../__chunks/BZTDJIVT.cjs');
-require('../__chunks/Z3GCTNW4.cjs');
+require('../__chunks/VUEWHLYH.cjs');
 require('../__chunks/75KXQZJX.cjs');
 
 
 
 
 var _RNZNGEL4cjs = require('../__chunks/RNZNGEL4.cjs');
-require('../__chunks/B233QVZE.cjs');
+require('../__chunks/OLOZ5JT2.cjs');
 
 
 var _EO6LS72Hcjs = require('../__chunks/EO6LS72H.cjs');
@@ -60,8 +60,8 @@ var useFormRadio = _RNZNGEL4cjs.createHook.call(void 0,
       checked,
       onChange
     });
-    props = _IAYTETYNcjs.useRadio.call(void 0, _AV6KTKLEcjs.__spreadValues.call(void 0, { value }, props));
-    props = _VCDQISP7cjs.useFormField.call(void 0, _AV6KTKLEcjs.__spreadValues.call(void 0, {
+    props = _MMRX6FNScjs.useRadio.call(void 0, _AV6KTKLEcjs.__spreadValues.call(void 0, { value }, props));
+    props = _N3XK7EAHcjs.useFormControl.call(void 0, _AV6KTKLEcjs.__spreadValues.call(void 0, {
       store,
       name,
       "aria-labelledby": void 0

package/cjs/form/form-radio.d.cts

@@ -1,6 +1,6 @@
 import type { RadioOptions } from "../radio/radio.js";
 import type { As, Props } from "../utils/types.js";
-import type { FormFieldOptions } from "./form-field.js";
+import type { FormControlOptions } from "./form-control.js";
 /**
  * Returns props to create a `FormRadio` component.
  * @see https://ariakit.org/components/form
@@ -22,15 +22,19 @@ import type { FormFieldOptions } from "./form-field.js";
  */
 export declare const useFormRadio: import("../utils/types.js").Hook<FormRadioOptions<"input">>;
 /**
- * Renders a radio button in a form.
+ * Renders a radio button as a form control. This component must be wrapped in a
+ * [`FormRadioGroup`](https://ariakit.org/reference/form-radio-group) along with
+ * other radio buttons sharing the same
+ * [`name`](https://ariakit.org/reference/form-radio#name).
  * @see https://ariakit.org/components/form
  * @example
- * ```jsx
+ * ```jsx {10-12}
  * const form = useFormStore({
  *   defaultValues: {
  *     char: "a",
  *   },
  * });
+ *
  * <Form store={form}>
  *   <FormRadioGroup>
  *     <FormGroupLabel>Favorite character</FormGroupLabel>
@@ -42,6 +46,6 @@ export declare const useFormRadio: import("../utils/types.js").Hook<FormRadioOpt
  * ```
  */
 export declare const FormRadio: import("../utils/types.js").Component<FormRadioOptions<"input">>;
-export interface FormRadioOptions<T extends As = "input"> extends FormFieldOptions<T>, Omit<RadioOptions<T>, "store" | "name"> {
+export interface FormRadioOptions<T extends As = "input"> extends FormControlOptions<T>, Omit<RadioOptions<T>, "store" | "name"> {
 }
 export type FormRadioProps<T extends As = "input"> = Props<FormRadioOptions<T>>;

package/cjs/form/form-radio.d.ts

@@ -1,6 +1,6 @@
 import type { RadioOptions } from "../radio/radio.js";
 import type { As, Props } from "../utils/types.js";
-import type { FormFieldOptions } from "./form-field.js";
+import type { FormControlOptions } from "./form-control.js";
 /**
  * Returns props to create a `FormRadio` component.
  * @see https://ariakit.org/components/form
@@ -22,15 +22,19 @@ import type { FormFieldOptions } from "./form-field.js";
  */
 export declare const useFormRadio: import("../utils/types.js").Hook<FormRadioOptions<"input">>;
 /**
- * Renders a radio button in a form.
+ * Renders a radio button as a form control. This component must be wrapped in a
+ * [`FormRadioGroup`](https://ariakit.org/reference/form-radio-group) along with
+ * other radio buttons sharing the same
+ * [`name`](https://ariakit.org/reference/form-radio#name).
  * @see https://ariakit.org/components/form
  * @example
- * ```jsx
+ * ```jsx {10-12}
  * const form = useFormStore({
  *   defaultValues: {
  *     char: "a",
  *   },
  * });
+ *
  * <Form store={form}>
  *   <FormRadioGroup>
  *     <FormGroupLabel>Favorite character</FormGroupLabel>
@@ -42,6 +46,6 @@ export declare const useFormRadio: import("../utils/types.js").Hook<FormRadioOpt
  * ```
  */
 export declare const FormRadio: import("../utils/types.js").Component<FormRadioOptions<"input">>;
-export interface FormRadioOptions<T extends As = "input"> extends FormFieldOptions<T>, Omit<RadioOptions<T>, "store" | "name"> {
+export interface FormRadioOptions<T extends As = "input"> extends FormControlOptions<T>, Omit<RadioOptions<T>, "store" | "name"> {
 }
 export type FormRadioProps<T extends As = "input"> = Props<FormRadioOptions<T>>;

package/cjs/form/form-remove.cjs

@@ -4,10 +4,10 @@
 var _FROYTN4Bcjs = require('../__chunks/FROYTN4B.cjs');
 
 
-var _5UTRYT6Ecjs = require('../__chunks/5UTRYT6E.cjs');
-require('../__chunks/DAJUUBUI.cjs');
+var _REJALU3Pcjs = require('../__chunks/REJALU3P.cjs');
+require('../__chunks/OSTQZD2E.cjs');
 require('../__chunks/BZTDJIVT.cjs');
-require('../__chunks/Z3GCTNW4.cjs');
+require('../__chunks/VUEWHLYH.cjs');
 require('../__chunks/75KXQZJX.cjs');
 
 
@@ -83,7 +83,7 @@ var useFormRemove = _RNZNGEL4cjs.createHook.call(void 0,
     props = _AV6KTKLEcjs.__spreadProps.call(void 0, _AV6KTKLEcjs.__spreadValues.call(void 0, {}, props), {
       onClick
     });
-    props = _5UTRYT6Ecjs.useButton.call(void 0, props);
+    props = _REJALU3Pcjs.useButton.call(void 0, props);
     return props;
   }
 );

package/cjs/form/form-remove.d.cts

@@ -31,14 +31,26 @@ export declare const useFormRemove: import("../utils/types.js").Hook<FormRemoveO
 /**
  * Renders a button that will remove an item from an array field in the form
  * when clicked.
+ *
+ * The [`name`](https://ariakit.org/reference/form-remove#name) prop must be
+ * provided to identify the array field. Similarly, the
+ * [`index`](https://ariakit.org/reference/form-remove#index) prop is required
+ * to pinpoint the item to remove.
+ *
+ * By default, the button will automatically move focus to the next field in the
+ * form when clicked, or to the previous field if there isn't a next field. This
+ * behavior can be disabled by setting the
+ * [`autoFocusOnClick`](https://ariakit.org/reference/form-remove#autofocusonclick)
+ * prop to `false`.
  * @see https://ariakit.org/components/form
  * @example
- * ```jsx
+ * ```jsx {13}
  * const form = useFormStore({
  *   defaultValues: {
  *     languages: ["JavaScript", "PHP"],
  *   },
  * });
+ *
  * const values = form.useState("values");
  *
  * <Form store={form}>
@@ -62,7 +74,10 @@ export interface FormRemoveOptions<T extends As = "button"> extends ButtonOption
      */
     store?: FormStore;
     /**
-     * Name of the array field.
+     * Name of the array field. This can either be a string or a reference to a
+     * field name from the
+     * [`names`](https://ariakit.org/reference/use-form-store#names) object in the
+     * store, for type safety.
      */
     name: StringLike;
     /**

package/cjs/form/form-remove.d.ts

@@ -31,14 +31,26 @@ export declare const useFormRemove: import("../utils/types.js").Hook<FormRemoveO
 /**
  * Renders a button that will remove an item from an array field in the form
  * when clicked.
+ *
+ * The [`name`](https://ariakit.org/reference/form-remove#name) prop must be
+ * provided to identify the array field. Similarly, the
+ * [`index`](https://ariakit.org/reference/form-remove#index) prop is required
+ * to pinpoint the item to remove.
+ *
+ * By default, the button will automatically move focus to the next field in the
+ * form when clicked, or to the previous field if there isn't a next field. This
+ * behavior can be disabled by setting the
+ * [`autoFocusOnClick`](https://ariakit.org/reference/form-remove#autofocusonclick)
+ * prop to `false`.
  * @see https://ariakit.org/components/form
  * @example
- * ```jsx
+ * ```jsx {13}
  * const form = useFormStore({
  *   defaultValues: {
  *     languages: ["JavaScript", "PHP"],
  *   },
  * });
+ *
  * const values = form.useState("values");
  *
  * <Form store={form}>
@@ -62,7 +74,10 @@ export interface FormRemoveOptions<T extends As = "button"> extends ButtonOption
      */
     store?: FormStore;
     /**
-     * Name of the array field.
+     * Name of the array field. This can either be a string or a reference to a
+     * field name from the
+     * [`names`](https://ariakit.org/reference/use-form-store#names) object in the
+     * store, for type safety.
      */
     name: StringLike;
     /**

package/cjs/form/form-reset.cjs

@@ -4,10 +4,10 @@
 var _FROYTN4Bcjs = require('../__chunks/FROYTN4B.cjs');
 
 
-var _5UTRYT6Ecjs = require('../__chunks/5UTRYT6E.cjs');
-require('../__chunks/DAJUUBUI.cjs');
+var _REJALU3Pcjs = require('../__chunks/REJALU3P.cjs');
+require('../__chunks/OSTQZD2E.cjs');
 require('../__chunks/BZTDJIVT.cjs');
-require('../__chunks/Z3GCTNW4.cjs');
+require('../__chunks/VUEWHLYH.cjs');
 require('../__chunks/75KXQZJX.cjs');
 
 
@@ -36,7 +36,7 @@ var useFormReset = _RNZNGEL4cjs.createHook.call(void 0,
       type: "reset",
       disabled: store.useState("submitting")
     }, props);
-    props = _5UTRYT6Ecjs.useButton.call(void 0, props);
+    props = _REJALU3Pcjs.useButton.call(void 0, props);
     return props;
   }
 );

package/cjs/form/form-reset.d.cts

@@ -15,10 +15,13 @@ import type { FormStore } from "./form-store.js";
  */
 export declare const useFormReset: import("../utils/types.js").Hook<FormResetOptions<"button">>;
 /**
- * Renders a reset buttom in a form.
+ * Renders a button that resets the form to its initial values, as defined by
+ * the
+ * [`defaultValues`](https://ariakit.org/reference/use-form-store#defaultvalues)
+ * prop given to the form store.
  * @see https://ariakit.org/components/form
  * @example
- * ```jsx
+ * ```jsx {4}
  * const form = useFormStore();
  *
  * <Form store={form}>

package/cjs/form/form-reset.d.ts

@@ -15,10 +15,13 @@ import type { FormStore } from "./form-store.js";
  */
 export declare const useFormReset: import("../utils/types.js").Hook<FormResetOptions<"button">>;
 /**
- * Renders a reset buttom in a form.
+ * Renders a button that resets the form to its initial values, as defined by
+ * the
+ * [`defaultValues`](https://ariakit.org/reference/use-form-store#defaultvalues)
+ * prop given to the form store.
  * @see https://ariakit.org/components/form
  * @example
- * ```jsx
+ * ```jsx {4}
  * const form = useFormStore();
  *
  * <Form store={form}>

package/cjs/form/form-store.cjs

@@ -2,13 +2,13 @@
 
 
 
-var _QLRXXIBYcjs = require('../__chunks/QLRXXIBY.cjs');
-require('../__chunks/DKOWT2IJ.cjs');
-require('../__chunks/B233QVZE.cjs');
+var _ODJ76C5Wcjs = require('../__chunks/ODJ76C5W.cjs');
+require('../__chunks/CDNJPIEG.cjs');
+require('../__chunks/OLOZ5JT2.cjs');
 require('../__chunks/EO6LS72H.cjs');
 require('../__chunks/CJDHQUBR.cjs');
 require('../__chunks/AV6KTKLE.cjs');
 
 
 
-exports.useFormStore = _QLRXXIBYcjs.useFormStore; exports.useFormStoreProps = _QLRXXIBYcjs.useFormStoreProps;
+exports.useFormStore = _ODJ76C5Wcjs.useFormStore; exports.useFormStoreProps = _ODJ76C5Wcjs.useFormStoreProps;

package/cjs/form/form-store.d.cts

@@ -9,7 +9,8 @@ export declare function useFormStoreProps<T extends Omit<FormStore, "useValue" |
     useSubmit: (callback: Core.FormStoreCallback<FormStoreState<FormStoreValues>>) => void;
 };
 /**
- * Creates a form store.
+ * Creates a form store to control the state of
+ * [Form](https://ariakit.org/components/form) components.
  * @example
  * ```jsx
  * const form = useFormStore({
@@ -17,6 +18,7 @@ export declare function useFormStoreProps<T extends Omit<FormStore, "useValue" |
  *     email: "",
  *   },
  * });
+ *
  * <Form store={form}>
  *   <FormLabel name={form.names.email}>Email</FormLabel>
  *   <FormInput name={form.names.email} />
@@ -36,18 +38,26 @@ export interface FormStoreState<T extends FormStoreValues = FormStoreValues> ext
 export interface FormStoreFunctions<T extends FormStoreValues = FormStoreValues> extends Core.FormStoreFunctions<T>, CollectionStoreFunctions<FormStoreItem> {
     /**
      * A custom hook that rerenders the component when the value of the given
-     * field changes. It returns the value of the field.
-     * @param name The name of the field.
+     * field changes. It accepts a string or a reference to a field name from the
+     * [`names`](https://ariakit.org/reference/use-form-store#names) object in the
+     * store, for type safety. It returns the value of the field.
+     *
+     * Live examples:
+     * - [Form with Select](https://ariakit.org/examples/form-select)
      * @example
      * const nameValue = store.useValue("name");
-     * // Can also use store.names for type-safety.
+     * // Can also use store.names for type safety.
      * const emailValue = store.useValue(store.names.email);
      */
     useValue: <T = any>(name: StringLike) => T;
     /**
      * Custom hook that accepts a callback that will be used to validate the form
-     * when `form.validate` is called.
-     * @param callback The callback that receives the form state as argument.
+     * when [`validate`](https://ariakit.org/reference/use-form-store#validate) is
+     * called, typically when a form field is touched or when the form is
+     * submitted.
+     *
+     * Live examples:
+     * - [FormRadio](https://ariakit.org/examples/form-radio)
      * @example
      * store.useValidate(async (state) => {
      *   const errors = await api.validate(state.values);
@@ -59,8 +69,12 @@ export interface FormStoreFunctions<T extends FormStoreValues = FormStoreValues>
     useValidate: (callback: Core.FormStoreCallback<FormStoreState<T>>) => void;
     /**
      * Custom hook that accepts a callback that will be used to submit the form
-     * when `form.submit` is called.
-     * @param callback The callback that receives the form state as argument.
+     * when [`submit`](https://ariakit.org/reference/use-form-store#submit) is
+     * called.
+     *
+     * Live examples:
+     * - [FormRadio](https://ariakit.org/examples/form-radio)
+     * - [Form with Select](https://ariakit.org/examples/form-select)
      * @example
      * store.useSubmit(async (state) => {
      *   try {
@@ -74,8 +88,9 @@ export interface FormStoreFunctions<T extends FormStoreValues = FormStoreValues>
 }
 export interface FormStoreOptions<T extends FormStoreValues = FormStoreValues> extends Core.FormStoreOptions<T>, CollectionStoreOptions<FormStoreItem> {
     /**
-     * Function that will be called when `values` state changes.
-     * @param values The new values.
+     * Function that will be called when
+     * [`values`](https://ariakit.org/reference/use-form-store#values) state
+     * changes.
      * @example
      * function MyForm({ values, onChange }) {
      *   const form = useFormStore({ values, setValues: onChange });
@@ -83,15 +98,17 @@ export interface FormStoreOptions<T extends FormStoreValues = FormStoreValues> e
      */
     setValues?: (values: FormStoreState<T>["values"]) => void;
     /**
-     * Function that will be called when the `errors` state changes.
-     * @param errors The new errors.
+     * Function that will be called when the
+     * [`errors`](https://ariakit.org/reference/use-form-store#errors) state
+     * changes.
      * @example
      * useFormStore({ setErrors: (errors) => console.log(errors) });
      */
     setErrors?: (errors: FormStoreState<T>["errors"]) => void;
     /**
-     * Function that will be called when the `touched` state changes.
-     * @param touched The new touched state.
+     * Function that will be called when the
+     * [`touched`](https://ariakit.org/reference/use-form-store#touched) state
+     * changes.
      * @example
      * useFormStore({ setTouched: (touched) => console.log(touched) });
      */

package/cjs/form/form-store.d.ts

@@ -9,7 +9,8 @@ export declare function useFormStoreProps<T extends Omit<FormStore, "useValue" |
     useSubmit: (callback: Core.FormStoreCallback<FormStoreState<FormStoreValues>>) => void;
 };
 /**
- * Creates a form store.
+ * Creates a form store to control the state of
+ * [Form](https://ariakit.org/components/form) components.
  * @example
  * ```jsx
  * const form = useFormStore({
@@ -17,6 +18,7 @@ export declare function useFormStoreProps<T extends Omit<FormStore, "useValue" |
  *     email: "",
  *   },
  * });
+ *
  * <Form store={form}>
  *   <FormLabel name={form.names.email}>Email</FormLabel>
  *   <FormInput name={form.names.email} />
@@ -36,18 +38,26 @@ export interface FormStoreState<T extends FormStoreValues = FormStoreValues> ext
 export interface FormStoreFunctions<T extends FormStoreValues = FormStoreValues> extends Core.FormStoreFunctions<T>, CollectionStoreFunctions<FormStoreItem> {
     /**
      * A custom hook that rerenders the component when the value of the given
-     * field changes. It returns the value of the field.
-     * @param name The name of the field.
+     * field changes. It accepts a string or a reference to a field name from the
+     * [`names`](https://ariakit.org/reference/use-form-store#names) object in the
+     * store, for type safety. It returns the value of the field.
+     *
+     * Live examples:
+     * - [Form with Select](https://ariakit.org/examples/form-select)
      * @example
      * const nameValue = store.useValue("name");
-     * // Can also use store.names for type-safety.
+     * // Can also use store.names for type safety.
      * const emailValue = store.useValue(store.names.email);
      */
     useValue: <T = any>(name: StringLike) => T;
     /**
      * Custom hook that accepts a callback that will be used to validate the form
-     * when `form.validate` is called.
-     * @param callback The callback that receives the form state as argument.
+     * when [`validate`](https://ariakit.org/reference/use-form-store#validate) is
+     * called, typically when a form field is touched or when the form is
+     * submitted.
+     *
+     * Live examples:
+     * - [FormRadio](https://ariakit.org/examples/form-radio)
      * @example
      * store.useValidate(async (state) => {
      *   const errors = await api.validate(state.values);
@@ -59,8 +69,12 @@ export interface FormStoreFunctions<T extends FormStoreValues = FormStoreValues>
     useValidate: (callback: Core.FormStoreCallback<FormStoreState<T>>) => void;
     /**
      * Custom hook that accepts a callback that will be used to submit the form
-     * when `form.submit` is called.
-     * @param callback The callback that receives the form state as argument.
+     * when [`submit`](https://ariakit.org/reference/use-form-store#submit) is
+     * called.
+     *
+     * Live examples:
+     * - [FormRadio](https://ariakit.org/examples/form-radio)
+     * - [Form with Select](https://ariakit.org/examples/form-select)
      * @example
      * store.useSubmit(async (state) => {
      *   try {
@@ -74,8 +88,9 @@ export interface FormStoreFunctions<T extends FormStoreValues = FormStoreValues>
 }
 export interface FormStoreOptions<T extends FormStoreValues = FormStoreValues> extends Core.FormStoreOptions<T>, CollectionStoreOptions<FormStoreItem> {
     /**
-     * Function that will be called when `values` state changes.
-     * @param values The new values.
+     * Function that will be called when
+     * [`values`](https://ariakit.org/reference/use-form-store#values) state
+     * changes.
      * @example
      * function MyForm({ values, onChange }) {
      *   const form = useFormStore({ values, setValues: onChange });
@@ -83,15 +98,17 @@ export interface FormStoreOptions<T extends FormStoreValues = FormStoreValues> e
      */
     setValues?: (values: FormStoreState<T>["values"]) => void;
     /**
-     * Function that will be called when the `errors` state changes.
-     * @param errors The new errors.
+     * Function that will be called when the
+     * [`errors`](https://ariakit.org/reference/use-form-store#errors) state
+     * changes.
      * @example
      * useFormStore({ setErrors: (errors) => console.log(errors) });
      */
     setErrors?: (errors: FormStoreState<T>["errors"]) => void;
     /**
-     * Function that will be called when the `touched` state changes.
-     * @param touched The new touched state.
+     * Function that will be called when the
+     * [`touched`](https://ariakit.org/reference/use-form-store#touched) state
+     * changes.
      * @example
      * useFormStore({ setTouched: (touched) => console.log(touched) });
      */

package/cjs/form/form-submit.cjs

@@ -4,10 +4,10 @@
 var _FROYTN4Bcjs = require('../__chunks/FROYTN4B.cjs');
 
 
-var _5UTRYT6Ecjs = require('../__chunks/5UTRYT6E.cjs');
-require('../__chunks/DAJUUBUI.cjs');
+var _REJALU3Pcjs = require('../__chunks/REJALU3P.cjs');
+require('../__chunks/OSTQZD2E.cjs');
 require('../__chunks/BZTDJIVT.cjs');
-require('../__chunks/Z3GCTNW4.cjs');
+require('../__chunks/VUEWHLYH.cjs');
 require('../__chunks/75KXQZJX.cjs');
 
 
@@ -37,7 +37,7 @@ var useFormSubmit = _RNZNGEL4cjs.createHook.call(void 0,
       type: "submit",
       disabled: store.useState("submitting")
     }, props);
-    props = _5UTRYT6Ecjs.useButton.call(void 0, _AV6KTKLEcjs.__spreadProps.call(void 0, _AV6KTKLEcjs.__spreadValues.call(void 0, {}, props), { accessibleWhenDisabled }));
+    props = _REJALU3Pcjs.useButton.call(void 0, _AV6KTKLEcjs.__spreadProps.call(void 0, _AV6KTKLEcjs.__spreadValues.call(void 0, {}, props), { accessibleWhenDisabled }));
     return props;
   }
 );

package/cjs/form/form-submit.d.cts

@@ -15,11 +15,17 @@ import type { FormStore } from "./form-store.js";
  */
 export declare const useFormSubmit: import("../utils/types.js").Hook<FormSubmitOptions<"button">>;
 /**
- * Renders a submit buttom in a form.
+ * Renders a native submit button inside a form. The button will be
+ * [`disabled`](https://ariakit.org/reference/form-submit#disabled) while the
+ * form is submitting, but it will remain accessible to keyboard and screen
+ * reader users thanks to the
+ * [`accessibleWhenDisabled`](https://ariakit.org/reference/form-submit#accessiblewhendisabled)
+ * prop that's enabled by default.
  * @see https://ariakit.org/components/form
  * @example
- * ```jsx
+ * ```jsx {4}
  * const form = useFormStore();
+ *
  * <Form store={form}>
  *   <FormSubmit>Submit</FormSubmit>
  * </Form>

package/cjs/form/form-submit.d.ts

@@ -15,11 +15,17 @@ import type { FormStore } from "./form-store.js";
  */
 export declare const useFormSubmit: import("../utils/types.js").Hook<FormSubmitOptions<"button">>;
 /**
- * Renders a submit buttom in a form.
+ * Renders a native submit button inside a form. The button will be
+ * [`disabled`](https://ariakit.org/reference/form-submit#disabled) while the
+ * form is submitting, but it will remain accessible to keyboard and screen
+ * reader users thanks to the
+ * [`accessibleWhenDisabled`](https://ariakit.org/reference/form-submit#accessiblewhendisabled)
+ * prop that's enabled by default.
  * @see https://ariakit.org/components/form
  * @example
- * ```jsx
+ * ```jsx {4}
  * const form = useFormStore();
+ *
  * <Form store={form}>
  *   <FormSubmit>Submit</FormSubmit>
  * </Form>