@ariakit/react-core 0.3.12 → 0.3.14

package/esm/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/esm/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/esm/form/form-radio.js

@@ -1,7 +1,7 @@
 "use client";
 import {
-  useFormField
-} from "../__chunks/FS2EVEJO.js";
+  useFormControl
+} from "../__chunks/4GO43MST.js";
 import {
   useFormContext
 } from "../__chunks/V4ZFXDFK.js";
@@ -61,7 +61,7 @@ var useFormRadio = createHook(
       onChange
     });
     props = useRadio(__spreadValues({ value }, props));
-    props = useFormField(__spreadValues({
+    props = useFormControl(__spreadValues({
       store,
       name,
       "aria-labelledby": void 0

package/esm/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/esm/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/esm/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/esm/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/esm/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/esm/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/esm/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/esm/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/esm/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/esm/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/esm/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/esm/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/esm/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 />

package/esm/hovercard/hovercard-dismiss.d.ts

@@ -15,10 +15,11 @@ import type { HovercardStore } from "./hovercard-store.js";
  */
 export declare const useHovercardDismiss: import("../utils/types.js").Hook<HovercardDismissOptions<"button">>;
 /**
- * Renders a button that hides a hovercard.
+ * Renders a button that hides a
+ * [`Hovercard`](https://ariakit.org/reference/hovercard) when clicked.
  * @see https://ariakit.org/components/hovercard
  * @example
- * ```jsx
+ * ```jsx {3}
  * <HovercardProvider>
  *   <Hovercard>
  *     <HovercardDismiss />

package/esm/hovercard/hovercard-heading.d.ts

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

package/esm/hovercard/hovercard-provider.d.ts

@@ -1,7 +1,8 @@
 import type { ReactNode } from "react";
 import type { HovercardStoreProps } from "./hovercard-store.js";
 /**
- * Provides a hovercard store to Hovercard components.
+ * Provides a hovercard store to
+ * [Hovercard](https://ariakit.org/components/hovercard) components.
  * @see https://ariakit.org/components/hovercard
  * @example
  * ```jsx

package/esm/hovercard/hovercard-store.d.ts

@@ -3,7 +3,8 @@ import type { PopoverStoreFunctions, PopoverStoreOptions, PopoverStoreState } fr
 import type { Store } from "../utils/store.js";
 export declare function useHovercardStoreProps<T extends Core.HovercardStore>(store: T, update: () => void, props: HovercardStoreProps): T;
 /**
- * Creates a hovercard store.
+ * Creates a hovercard store to control the state of
+ * [Hovercard](https://ariakit.org/reference/hovercard) components.
  * @see https://ariakit.org/components/hovercard
  * @example
  * ```jsx

package/esm/hovercard/hovercard.d.ts

@@ -20,7 +20,7 @@ export declare const useHovercard: import("../utils/types.js").Hook<HovercardOpt
  * [`HovercardAnchor`](https://ariakit.org/reference/hovercard-anchor).
  * @see https://ariakit.org/components/hovercard
  * @example
- * ```jsx
+ * ```jsx {3}
  * <HovercardProvider>
  *   <HovercardAnchor>@username</HovercardAnchor>
  *   <Hovercard>Details</Hovercard>
@@ -38,17 +38,29 @@ export interface HovercardOptions<T extends As = "div"> extends PopoverOptions<T
      */
     store?: HovercardStore;
     /**
-     * Whether to hide the popover when the mouse cursor leaves any hovercard
-     * element, including the hovercard popover itself, but also the anchor
-     * element.
+     * Determines whether the popover should hide when the mouse leaves the
+     * popover or the anchor element and there's no _hover intent_, meaning, the
+     * mouse isn't moving toward the popover.
+     *
+     * This can be either a boolean or a callback receiving the mouse move event
+     * that initiated the behavior. The callback should return a boolean.
+     *
+     * **Note**: This behavior won't be triggered when the popover or any of its
+     * descendants are in focus.
      * @default true
      */
     hideOnHoverOutside?: BooleanOrCallback<MouseEvent>;
     /**
-     * Whether to disable the pointer events outside of the hovercard while the
-     * mouse is moving toward the hovercard. This is necessary because these
-     * events may trigger focus on other elements and close the hovercard while
-     * the user is moving the mouse toward it.
+     * Determines if the pointer events outside of the popover and its anchor
+     * element should be disabled during _hover intent_, that is, when the mouse
+     * is moving toward the popover.
+     *
+     * This is required as these external events may trigger focus on other
+     * elements and close the popover while the user is attempting to hover over
+     * it.
+     *
+     * This can be either a boolean or a callback receiving the mouse event
+     * happening during hover intent. The callback should return a boolean.
      * @default true
      */
     disablePointerEventsOnApproach?: BooleanOrCallback<MouseEvent>;

package/esm/hovercard/hovercard.js

@@ -2,12 +2,12 @@
 import {
   Hovercard,
   useHovercard
-} from "../__chunks/EPBRINPG.js";
+} from "../__chunks/QWSZGSIG.js";
 import "../__chunks/YMV43K4F.js";
-import "../__chunks/A6XC27R5.js";
-import "../__chunks/PGAEII2Q.js";
+import "../__chunks/IRX7SFUJ.js";
+import "../__chunks/NERBASET.js";
 import "../__chunks/LWHPHW7Q.js";
-import "../__chunks/CLF4PQ7T.js";
+import "../__chunks/TQYOGOE2.js";
 import "../__chunks/BULCTPRV.js";
 import "../__chunks/6BJGLK2C.js";
 import "../__chunks/CS347UVZ.js";
@@ -15,11 +15,11 @@ import "../__chunks/IUB2BTEK.js";
 import "../__chunks/XHJGS6Z5.js";
 import "../__chunks/TL67WVI6.js";
 import "../__chunks/MKDDWKFK.js";
+import "../__chunks/72E5EPFF.js";
 import "../__chunks/OOBDFMJL.js";
+import "../__chunks/X6WIMZJE.js";
 import "../__chunks/677M2CI3.js";
 import "../__chunks/6GXEOXGT.js";
-import "../__chunks/72E5EPFF.js";
-import "../__chunks/X6WIMZJE.js";
 import "../__chunks/HPP6CWMY.js";
 import "../__chunks/UYRJLDVS.js";
 import "../__chunks/JPXNJYSO.js";

package/esm/menu/menu-arrow.d.ts

@@ -16,10 +16,12 @@ import type { MenuStore } from "./menu-store.js";
  */
 export declare const useMenuArrow: import("../utils/types.js").Hook<MenuArrowOptions<"div">>;
 /**
- * Renders an arrow inside the menu element.
+ * Renders an arrow element inside a
+ * [`Menu`](https://ariakit.org/reference/menu) component that points to its
+ * [`MenuButton`](https://ariakit.org/reference/menu-button).
  * @see https://ariakit.org/components/menu
  * @example
- * ```jsx
+ * ```jsx {4}
  * <MenuProvider>
  *   <MenuButton>Menu</MenuButton>
  *   <Menu>

package/esm/menu/menu-bar.d.ts

@@ -2,8 +2,7 @@ import type { MenubarOptions } from "../menubar/menubar.js";
 import type { As, Props } from "../utils/types.js";
 /**
  * Returns props to create a `MenuBar` component.
- * @deprecated
- * Use [`useMenubar`](https://ariakit.org/reference/use-menubar) instead.
+ * @deprecated Use `useMenubar` instead.
  * @example
  * ```jsx
  * const store = useMenuBarStore();

package/esm/menu/menu-button-arrow.d.ts

@@ -20,12 +20,17 @@ import type { MenuStore } from "./menu-store.js";
  */
 export declare const useMenuButtonArrow: import("../utils/types.js").Hook<MenuButtonArrowOptions<"span">>;
 /**
- * Renders an arrow pointing to the menu position, usually inside a
- * `MenuButton`.
+ * Displays an arrow within a
+ * [`MenuButton`](https://ariakit.org/reference/menu-button), pointing to the
+ * [`Menu`](https://ariakit.org/reference/menu) position. It's typically based
+ * on the [`placement`](https://ariakit.org/reference/menu-provider#placement)
+ * state from the menu store, but this can be overridden with the
+ * [`placement`](https://ariakit.org/reference/menu-button-arrow#placement)
+ * prop.
  * @see https://ariakit.org/components/menu
  * @example
- * ```jsx
- * <MenuProvider>
+ * ```jsx {4}
+ * <MenuProvider placement="bottom-start">
  *   <MenuButton>
  *     Edit
  *     <MenuButtonArrow />