@ariakit/react-core 0.3.12 → 0.3.14

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

package/cjs/group/group.d.cts

@@ -10,7 +10,9 @@ import type { As, Options, Props } from "../utils/types.js";
  */
 export declare const useGroup: import("../utils/types.js").Hook<GroupOptions<"div">>;
 /**
- * Renders a group element.
+ * Renders a group element. Optionally, a
+ * [`GroupLabel`](https://ariakit.org/reference/group-label) can be rendered as
+ * a child to provide a label for the group.
  * @see https://ariakit.org/components/group
  * @example
  * ```jsx

package/cjs/group/group.d.ts

@@ -10,7 +10,9 @@ import type { As, Options, Props } from "../utils/types.js";
  */
 export declare const useGroup: import("../utils/types.js").Hook<GroupOptions<"div">>;
 /**
- * Renders a group element.
+ * Renders a group element. Optionally, a
+ * [`GroupLabel`](https://ariakit.org/reference/group-label) can be rendered as
+ * a child to provide a label for the group.
  * @see https://ariakit.org/components/group
  * @example
  * ```jsx

package/cjs/heading/heading-level.d.cts

@@ -1,8 +1,10 @@
 import type { ReactNode } from "react";
 import type { HeadingLevels } from "./utils.js";
 /**
- * A component that sets the heading level for the children. It doesn't render
- * any HTML element, just sets the `level` prop on the context.
+ * A component that sets the heading level for its children. It doesn't render
+ * any HTML element, just sets the
+ * [`level`](https://ariakit.org/reference/heading-level#level) prop on the
+ * context.
  * @see https://ariakit.org/components/heading
  * @example
  * ```jsx

package/cjs/heading/heading-level.d.ts

@@ -1,8 +1,10 @@
 import type { ReactNode } from "react";
 import type { HeadingLevels } from "./utils.js";
 /**
- * A component that sets the heading level for the children. It doesn't render
- * any HTML element, just sets the `level` prop on the context.
+ * A component that sets the heading level for its children. It doesn't render
+ * any HTML element, just sets the
+ * [`level`](https://ariakit.org/reference/heading-level#level) prop on the
+ * context.
  * @see https://ariakit.org/components/heading
  * @example
  * ```jsx

package/cjs/heading/heading.d.cts

@@ -14,9 +14,10 @@ type HeadingElements = `h${HeadingLevels}`;
  */
 export declare const useHeading: import("../utils/types.js").Hook<HeadingOptions<"h1" | "h2" | "h3" | "h4" | "h5" | "h6">>;
 /**
- * Renders a heading element. The element type (or the `aria-level` prop, if the
- * element type is not a native heading) is determined by the context level
- * provided by the parent `HeadingLevel` component.
+ * Renders a heading element. The element type (or the `aria-level` attribute,
+ * if the element type is not a native heading) is determined by the context
+ * level provided by the closest
+ * [`HeadingLevel`](https://ariakit.org/reference/heading-level) ancestor.
  * @see https://ariakit.org/components/heading
  * @example
  * ```jsx

package/cjs/heading/heading.d.ts

@@ -14,9 +14,10 @@ type HeadingElements = `h${HeadingLevels}`;
  */
 export declare const useHeading: import("../utils/types.js").Hook<HeadingOptions<"h1" | "h2" | "h3" | "h4" | "h5" | "h6">>;
 /**
- * Renders a heading element. The element type (or the `aria-level` prop, if the
- * element type is not a native heading) is determined by the context level
- * provided by the parent `HeadingLevel` component.
+ * Renders a heading element. The element type (or the `aria-level` attribute,
+ * if the element type is not a native heading) is determined by the context
+ * level provided by the closest
+ * [`HeadingLevel`](https://ariakit.org/reference/heading-level) ancestor.
  * @see https://ariakit.org/components/heading
  * @example
  * ```jsx

package/cjs/hovercard/hovercard-anchor.d.cts

@@ -20,7 +20,7 @@ export declare const useHovercardAnchor: import("../utils/types.js").Hook<Hoverc
  * [`Hovercard`](https://ariakit.org/reference/hovercard) popup on hover.
  * @see https://ariakit.org/components/hovercard
  * @example
- * ```jsx
+ * ```jsx {2}
  * <HovercardProvider>
  *   <HovercardAnchor>@username</HovercardAnchor>
  *   <Hovercard>Details</Hovercard>
@@ -38,10 +38,13 @@ export interface HovercardAnchorOptions<T extends As = "a"> extends FocusableOpt
      */
     store?: HovercardStore;
     /**
-     * Whether to show the hovercard on mouse move.
+     * Shows the content element based on the user's _hover intent_ over the
+     * anchor element. This behavior purposely ignores mobile touch and
+     * unintentional mouse enter events, like those that happen during scrolling.
      *
      * Live examples:
      * - [Navigation Menubar](https://ariakit.org/examples/menubar-navigation)
+     * - [Sliding Menu](https://ariakit.org/examples/menu-slide)
      * @default true
      */
     showOnHover?: BooleanOrCallback<ReactMouseEvent<HTMLElement>>;

package/cjs/hovercard/hovercard-anchor.d.ts

@@ -20,7 +20,7 @@ export declare const useHovercardAnchor: import("../utils/types.js").Hook<Hoverc
  * [`Hovercard`](https://ariakit.org/reference/hovercard) popup on hover.
  * @see https://ariakit.org/components/hovercard
  * @example
- * ```jsx
+ * ```jsx {2}
  * <HovercardProvider>
  *   <HovercardAnchor>@username</HovercardAnchor>
  *   <Hovercard>Details</Hovercard>
@@ -38,10 +38,13 @@ export interface HovercardAnchorOptions<T extends As = "a"> extends FocusableOpt
      */
     store?: HovercardStore;
     /**
-     * Whether to show the hovercard on mouse move.
+     * Shows the content element based on the user's _hover intent_ over the
+     * anchor element. This behavior purposely ignores mobile touch and
+     * unintentional mouse enter events, like those that happen during scrolling.
      *
      * Live examples:
      * - [Navigation Menubar](https://ariakit.org/examples/menubar-navigation)
+     * - [Sliding Menu](https://ariakit.org/examples/menu-slide)
      * @default true
      */
     showOnHover?: BooleanOrCallback<ReactMouseEvent<HTMLElement>>;

package/cjs/hovercard/hovercard-arrow.d.cts

@@ -16,10 +16,12 @@ import type { HovercardStore } from "./hovercard-store.js";
  */
 export declare const useHovercardArrow: import("../utils/types.js").Hook<HovercardArrowOptions<"div">>;
 /**
- * Renders an arrow element in a hovercard.
+ * Renders an arrow element inside a
+ * [`Hovercard`](https://ariakit.org/reference/hovercard) component that points
+ * to the anchor element.
  * @see https://ariakit.org/components/hovercard
  * @example
- * ```jsx
+ * ```jsx {4}
  * <HovercardProvider>
  *   <HovercardAnchor>@username</HovercardAnchor>
  *   <Hovercard>

package/cjs/hovercard/hovercard-arrow.d.ts

@@ -16,10 +16,12 @@ import type { HovercardStore } from "./hovercard-store.js";
  */
 export declare const useHovercardArrow: import("../utils/types.js").Hook<HovercardArrowOptions<"div">>;
 /**
- * Renders an arrow element in a hovercard.
+ * Renders an arrow element inside a
+ * [`Hovercard`](https://ariakit.org/reference/hovercard) component that points
+ * to the anchor element.
  * @see https://ariakit.org/components/hovercard
  * @example
- * ```jsx
+ * ```jsx {4}
  * <HovercardProvider>
  *   <HovercardAnchor>@username</HovercardAnchor>
  *   <Hovercard>

package/cjs/hovercard/hovercard-description.d.cts

@@ -17,10 +17,10 @@ export declare const useHovercardDescription: import("../utils/types.js").Hook<H
 /**
  * Renders a description in a hovercard. This component must be wrapped within
  * [`Hovercard`](https://ariakit.org/reference/hovercard) so the
- * `aria-describedby` prop is properly set on the hovercard element.
+ * `aria-describedby` prop is properly set on the content element.
  * @see https://ariakit.org/components/hovercard
  * @example
- * ```jsx
+ * ```jsx {3}
  * <HovercardProvider>
  *   <Hovercard>
  *     <HovercardDescription>Description</HovercardDescription>

package/cjs/hovercard/hovercard-description.d.ts

@@ -17,10 +17,10 @@ export declare const useHovercardDescription: import("../utils/types.js").Hook<H
 /**
  * Renders a description in a hovercard. This component must be wrapped within
  * [`Hovercard`](https://ariakit.org/reference/hovercard) so the
- * `aria-describedby` prop is properly set on the hovercard element.
+ * `aria-describedby` prop is properly set on the content element.
  * @see https://ariakit.org/components/hovercard
  * @example
- * ```jsx
+ * ```jsx {3}
  * <HovercardProvider>
  *   <Hovercard>
  *     <HovercardDescription>Description</HovercardDescription>

package/cjs/hovercard/hovercard-disclosure.d.cts

@@ -21,7 +21,7 @@ export declare const useHovercardDisclosure: import("../utils/types.js").Hook<Ho
  * hovercard when using the keyboard.
  * @see https://ariakit.org/components/hovercard
  * @example
- * ```jsx
+ * ```jsx {3}
  * <HovercardProvider>
  *   <HovercardAnchor>@username</HovercardAnchor>
  *   <HovercardDisclosure />

package/cjs/hovercard/hovercard-disclosure.d.ts

@@ -21,7 +21,7 @@ export declare const useHovercardDisclosure: import("../utils/types.js").Hook<Ho
  * hovercard when using the keyboard.
  * @see https://ariakit.org/components/hovercard
  * @example
- * ```jsx
+ * ```jsx {3}
  * <HovercardProvider>
  *   <HovercardAnchor>@username</HovercardAnchor>
  *   <HovercardDisclosure />