@ariakit/react-core 0.3.12 → 0.3.13

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.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>

package/cjs/form/form.d.cts

@@ -12,11 +12,29 @@ import type { FormStore } from "./form-store.js";
  */
 export declare const useForm: import("../utils/types.js").Hook<FormOptions<"form">>;
 /**
- * Renders a form element.
+ * Renders a form element and provides a [form
+ * store](https://ariakit.org/reference/use-form-store) to its controls.
+ *
+ * The form is automatically validated on change and on blur. This behavior can
+ * be disabled with the
+ * [`validateOnChange`](https://ariakit.org/reference/form#validateonchange) and
+ * [`validateOnBlur`](https://ariakit.org/reference/form#validateonblur) props.
+ *
+ * When the form is submitted with errors, the first invalid field is
+ * automatically focused thanks to the
+ * [`autoFocusOnSubmit`](https://ariakit.org/reference/form#autofocusonsubmit)
+ * prop. If it's successful, the
+ * [`resetOnSubmit`](https://ariakit.org/reference/form#resetonsubmit) prop
+ * ensures the form is reset to its initial values as defined by the
+ * [`defaultValues`](https://ariakit.org/reference/use-form-store#defaultvalues)
+ * option on the [store](https://ariakit.org/reference/use-form-store).
  * @see https://ariakit.org/components/form
  * @example
- * ```jsx
- * const form = useFormStore({ defaultValues: { username: "johndoe" } });
+ * ```jsx {5-8}
+ * const form = useFormStore({
+ *   defaultValues: { username: "johndoe" },
+ * });
+ *
  * <Form store={form}>
  *   <FormLabel name={form.names.username}>Username</FormLabel>
  *   <FormInput name={form.names.username} />
@@ -34,32 +52,40 @@ export interface FormOptions<T extends As = "form"> extends Options<T> {
      */
     store?: FormStore;
     /**
-     * Whether the form should trigger the validation callbacks when values
+     * Determines if the form should invoke the validation callbacks registered
+     * with
+     * [`useValidate`](https://ariakit.org/reference/use-form-store#usevalidate)
+     * when the [`values`](https://ariakit.org/reference/use-form-store#values)
      * change.
      * @default true
      */
     validateOnChange?: boolean;
     /**
-     * Whether the form should trigger the validation callbacks when form fields
-     * are blurred.
+     * Determines if the form should invoke the validation callbacks registered
+     * with
+     * [`useValidate`](https://ariakit.org/reference/use-form-store#usevalidate)
+     * when a field loses focus.
      * @default true
      */
     validateOnBlur?: boolean;
     /**
-     * Whether the form store should be reset when the form element gets
+     * Determines if the form state should reset to its
+     * [`defaultValues`](https://ariakit.org/reference/use-form-store#defaultvalues)
+     * when the [`Form`](https://ariakit.org/reference/form) component is
      * unmounted.
      * @default false
      */
     resetOnUnmount?: boolean;
     /**
-     * Whether the form store should be reset when the form gets successfully
-     * submitted.
+     * Determines if the form state should be reset to its
+     * [`defaultValues`](https://ariakit.org/reference/use-form-store#defaultvalues)
+     * upon successful form submission.
      * @default true
      */
     resetOnSubmit?: boolean;
     /**
-     * Whether the form should automatically focus the first invalid field when
-     * the form gets submitted.
+     * Determines if the form should automatically focus on the first invalid
+     * field when the form is submitted.
      * @default true
      */
     autoFocusOnSubmit?: boolean;

package/cjs/form/form.d.ts

@@ -12,11 +12,29 @@ import type { FormStore } from "./form-store.js";
  */
 export declare const useForm: import("../utils/types.js").Hook<FormOptions<"form">>;
 /**
- * Renders a form element.
+ * Renders a form element and provides a [form
+ * store](https://ariakit.org/reference/use-form-store) to its controls.
+ *
+ * The form is automatically validated on change and on blur. This behavior can
+ * be disabled with the
+ * [`validateOnChange`](https://ariakit.org/reference/form#validateonchange) and
+ * [`validateOnBlur`](https://ariakit.org/reference/form#validateonblur) props.
+ *
+ * When the form is submitted with errors, the first invalid field is
+ * automatically focused thanks to the
+ * [`autoFocusOnSubmit`](https://ariakit.org/reference/form#autofocusonsubmit)
+ * prop. If it's successful, the
+ * [`resetOnSubmit`](https://ariakit.org/reference/form#resetonsubmit) prop
+ * ensures the form is reset to its initial values as defined by the
+ * [`defaultValues`](https://ariakit.org/reference/use-form-store#defaultvalues)
+ * option on the [store](https://ariakit.org/reference/use-form-store).
  * @see https://ariakit.org/components/form
  * @example
- * ```jsx
- * const form = useFormStore({ defaultValues: { username: "johndoe" } });
+ * ```jsx {5-8}
+ * const form = useFormStore({
+ *   defaultValues: { username: "johndoe" },
+ * });
+ *
  * <Form store={form}>
  *   <FormLabel name={form.names.username}>Username</FormLabel>
  *   <FormInput name={form.names.username} />
@@ -34,32 +52,40 @@ export interface FormOptions<T extends As = "form"> extends Options<T> {
      */
     store?: FormStore;
     /**
-     * Whether the form should trigger the validation callbacks when values
+     * Determines if the form should invoke the validation callbacks registered
+     * with
+     * [`useValidate`](https://ariakit.org/reference/use-form-store#usevalidate)
+     * when the [`values`](https://ariakit.org/reference/use-form-store#values)
      * change.
      * @default true
      */
     validateOnChange?: boolean;
     /**
-     * Whether the form should trigger the validation callbacks when form fields
-     * are blurred.
+     * Determines if the form should invoke the validation callbacks registered
+     * with
+     * [`useValidate`](https://ariakit.org/reference/use-form-store#usevalidate)
+     * when a field loses focus.
      * @default true
      */
     validateOnBlur?: boolean;
     /**
-     * Whether the form store should be reset when the form element gets
+     * Determines if the form state should reset to its
+     * [`defaultValues`](https://ariakit.org/reference/use-form-store#defaultvalues)
+     * when the [`Form`](https://ariakit.org/reference/form) component is
      * unmounted.
      * @default false
      */
     resetOnUnmount?: boolean;
     /**
-     * Whether the form store should be reset when the form gets successfully
-     * submitted.
+     * Determines if the form state should be reset to its
+     * [`defaultValues`](https://ariakit.org/reference/use-form-store#defaultvalues)
+     * upon successful form submission.
      * @default true
      */
     resetOnSubmit?: boolean;
     /**
-     * Whether the form should automatically focus the first invalid field when
-     * the form gets submitted.
+     * Determines if the form should automatically focus on the first invalid
+     * field when the form is submitted.
      * @default true
      */
     autoFocusOnSubmit?: boolean;

package/cjs/group/group-label.d.cts

@@ -13,8 +13,9 @@ import type { As, Options, Props } from "../utils/types.js";
  */
 export declare const useGroupLabel: import("../utils/types.js").Hook<GroupLabelOptions<"div">>;
 /**
- * Renders a label in a group. This component must be wrapped with `Group` so
- * the `aria-labelledby` prop is properly set on the group element.
+ * Renders a label in a group. This component should be wrapped with a
+ * [`Group`](https://ariakit.org/reference/group) so the `aria-labelledby`
+ * prop is correctly set on the group element.
  * @see https://ariakit.org/components/group
  * @example
  * ```jsx

package/cjs/group/group-label.d.ts

@@ -13,8 +13,9 @@ import type { As, Options, Props } from "../utils/types.js";
  */
 export declare const useGroupLabel: import("../utils/types.js").Hook<GroupLabelOptions<"div">>;
 /**
- * Renders a label in a group. This component must be wrapped with `Group` so
- * the `aria-labelledby` prop is properly set on the group element.
+ * Renders a label in a group. This component should be wrapped with a
+ * [`Group`](https://ariakit.org/reference/group) so the `aria-labelledby`
+ * prop is correctly set on the group element.
  * @see https://ariakit.org/components/group
  * @example
  * ```jsx