@ariakit/react-core 0.3.12 → 0.3.14

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

@@ -19,13 +19,12 @@ import type { MenuStore } from "./menu-store.js";
  */
 export declare const useMenuButton: import("../utils/types.js").Hook<MenuButtonOptions<"button" | "div">>;
 /**
- * Renders a menu button that triggers a
- * [`Menu`](https://ariakit.org/reference/menu) component. Usually, this is
- * rendered as a native `button` element, but if it's a submenu button rendered
- * as a menu item inside another menu, it'll be rendered as a `div`.
+ * Renders a menu button that toggles the visibility of a
+ * [`Menu`](https://ariakit.org/reference/menu) component when clicked or when
+ * using arrow keys.
  * @see https://ariakit.org/components/menu
  * @example
- * ```jsx
+ * ```jsx {2}
  * <MenuProvider>
  *   <MenuButton>Edit</MenuButton>
  *   <Menu>
@@ -49,8 +48,10 @@ export interface MenuButtonOptions<T extends As = "button" | "div"> extends Hove
      * Determines whether pressing a character key while focusing on the
      * [`MenuButton`](https://ariakit.org/reference/menu-button) should move focus
      * to the [`MenuItem`](https://ariakit.org/reference/menu-item) starting with
-     * that character. By default, it's `true` for menu buttons in a
-     * [Menubar](https://ariakit.org/components/menubar), but `false` for other
+     * that character.
+     *
+     * By default, it's `true` for menu buttons in a
+     * [`Menubar`](https://ariakit.org/reference/menubar), but `false` for other
      * menu buttons.
      */
     typeahead?: boolean;

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

@@ -15,12 +15,12 @@ import type { MenuStore } from "./menu-store.js";
  */
 export declare const useMenuDescription: import("../utils/types.js").Hook<MenuDescriptionOptions<"p">>;
 /**
- * Renders a description in a menu. This component must be wrapped with
+ * Renders a description in a menu. This component must be wrapped with a
  * [`Menu`](https://ariakit.org/reference/menu) component so the
  * `aria-describedby` prop is properly set on the menu element.
  * @see https://ariakit.org/components/menu
  * @example
- * ```jsx
+ * ```jsx {3}
  * <MenuProvider>
  *   <Menu>
  *     <MenuDescription>Description</MenuDescription>

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

@@ -15,10 +15,11 @@ import type { MenuStore } from "./menu-store.js";
  */
 export declare const useMenuDismiss: import("../utils/types.js").Hook<MenuDismissOptions<"button">>;
 /**
- * Renders a button that hides a menu.
+ * Renders a button that hides a [`Menu`](https://ariakit.org/reference/menu)
+ * when clicked.
  * @see https://ariakit.org/components/menu
  * @example
- * ```jsx
+ * ```jsx {3}
  * <MenuProvider>
  *   <Menu>
  *     <MenuDismiss />

package/esm/menu/menu-group-label.d.ts

@@ -15,12 +15,12 @@ import type { MenuStore } from "./menu-store.js";
  */
 export declare const useMenuGroupLabel: import("../utils/types.js").Hook<MenuGroupLabelOptions<"div">>;
 /**
- * Renders a label in a menu group. This component must be wrapped with
- * `MenuGroup` so the `aria-labelledby` prop is properly set on the menu group
- * element.
+ * Renders a label in a menu group. This component should be wrapped with
+ * [`MenuGroup`](https://ariakit.org/reference/menu-group) so the
+ * `aria-labelledby` is correctly set on the group element.
  * @see https://ariakit.org/components/menu
  * @example
- * ```jsx
+ * ```jsx {5}
  * <MenuProvider>
  *   <MenuButton>Recent Items</MenuButton>
  *   <Menu>

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

@@ -20,10 +20,13 @@ import type { MenuStore } from "./menu-store.js";
  */
 export declare const useMenuGroup: import("../utils/types.js").Hook<MenuGroupOptions<"div">>;
 /**
- * Renders a menu group inside a menu.
+ * Renders a group for [`MenuItem`](https://ariakit.org/reference/menu-item)
+ * elements. Optionally, a
+ * [`MenuGroupLabel`](https://ariakit.org/reference/menu-group-label) can be
+ * rendered as a child to provide a label for the group.
  * @see https://ariakit.org/components/menu
  * @example
- * ```jsx
+ * ```jsx {4-8}
  * <MenuProvider>
  *   <MenuButton>Recent Items</MenuButton>
  *   <Menu>

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

@@ -15,8 +15,9 @@ import type { MenuStore } from "./menu-store.js";
  */
 export declare const useMenuHeading: import("../utils/types.js").Hook<MenuHeadingOptions<"h1">>;
 /**
- * Renders a heading in a menu. This component must be wrapped with `Menu` so
- * the `aria-labelledby` prop is properly set on the menu element.
+ * Renders a heading in a menu. This component must be wrapped within
+ * [`Menu`](https://ariakit.org/reference/menu) so the `aria-labelledby` prop is
+ * properly set on the content element.
  * @see https://ariakit.org/components/menu
  * @example
  * ```jsx

package/esm/menu/menu-item-check.d.ts

@@ -12,12 +12,18 @@ import type { MenuStore } from "./menu-store.js";
  */
 export declare const useMenuItemCheck: import("../utils/types.js").Hook<MenuItemCheckOptions<"span">>;
 /**
- * Renders a checkmark inside a `MenuItemCheckbox` or `MenuItemRadio`
- * components. This component must be wrapped with one of those components or
- * the `checked` prop must be explicitly passed to the component.
+ * Renders a checkmark icon when the
+ * [`checked`](https://ariakit.org/reference/menu-item-check#checked) prop is
+ * `true`. The icon can be overridden by providing a different one as children.
+ *
+ * When rendered inside
+ * [`MenuItemCheckbox`](https://ariakit.org/reference/menu-item-checkbox) or
+ * [`MenuItemRadio`](https://ariakit.org/reference/menu-item-radio) components,
+ * the [`checked`](https://ariakit.org/reference/menu-item-check#checked) prop
+ * is automatically derived from the context.
  * @see https://ariakit.org/components/menu
  * @example
- * ```jsx
+ * ```jsx {5,9}
  * <MenuProvider defaultValues={{ apple: true, orange: false }}>
  *   <MenuButton>Fruits</MenuButton>
  *   <Menu>
@@ -40,19 +46,5 @@ export interface MenuItemCheckOptions<T extends As = "span"> extends Omit<Checkb
      * [`useMenuStore`](https://ariakit.org/reference/use-menu-store) hook.
      */
     store?: MenuStore;
-    /**
-     * Determines if the check mark should be displayed. This value is automatically
-     * derived from the parent
-     * [`MenuItemRadio`](https://ariakit.org/reference/menu-item-radio) or
-     * [`MenuItemCheckbox`](https://ariakit.org/reference/menu-item-checkbox)
-     * component.
-     *
-     * Manually setting this prop will supersede the derived value.
-     *
-     * Live examples:
-     * - [Submenu with
-     *   Combobox](https://ariakit.org/examples/menu-nested-combobox)
-     */
-    checked?: CheckboxCheckOptions<T>["checked"];
 }
 export type MenuItemCheckProps<T extends As = "span"> = Props<MenuItemCheckOptions<T>>;

package/esm/menu/menu-item-checkbox.d.ts

@@ -17,14 +17,43 @@ import type { MenuStore } from "./menu-store.js";
  */
 export declare const useMenuItemCheckbox: import("../utils/types.js").Hook<MenuItemCheckboxOptions<"div">>;
 /**
- * Renders a menu item checkbox inside a menu.
+ * Renders a [`menuitemcheckbox`](https://w3c.github.io/aria/#menuitemcheckbox)
+ * element within a [`Menu`](https://ariakit.org/reference/menu) component. The
+ * [`name`](https://ariakit.org/reference/menu-item-checkbox#name) prop must be
+ * provided to identify the field in the
+ * [`values`](https://ariakit.org/reference/menu-provider#values) state.
+ *
+ * A [`MenuItemCheck`](https://ariakit.org/reference/menu-item-check) can be
+ * used to render a checkmark inside this component.
  * @see https://ariakit.org/components/menu
  * @example
- * ```jsx
- * <MenuProvider defaultValues={{ apple: false }}>
- *   <MenuButton>Fruits</MenuButton>
+ * The [`name`](https://ariakit.org/reference/menu-item-checkbox#name) prop can
+ * refer to a single value in the state:
+ * ```jsx {4-7}
+ * <MenuProvider defaultValues={{ warnBeforeQuitting: true }}>
+ *   <MenuButton>Chrome</MenuButton>
+ *   <Menu>
+ *     <MenuItemCheckbox name="warnBeforeQuitting">
+ *       <MenuItemCheck />
+ *       Warn Before Quitting
+ *     </MenuItemCheckbox>
+ *   </Menu>
+ * </MenuProvider>
+ * ```
+ * @example
+ * Or it can refer to an array of values, in which case the
+ * [`value`](https://ariakit.org/reference/menu-item-checkbox#value) prop must
+ * be provided:
+ * ```jsx {4-9}
+ * <MenuProvider defaultValues={{ watching: ["issues"] }}>
+ *   <MenuButton>Watch</MenuButton>
  *   <Menu>
- *     <MenuItemCheckbox name="apple">Apple</MenuItemCheckbox>
+ *     <MenuItemCheckbox name="watching" value="issues">
+ *       Issues
+ *     </MenuItemCheckbox>
+ *     <MenuItemCheckbox name="watching" value="pull-requests">
+ *       Pull Requests
+ *     </MenuItemCheckbox>
  *   </Menu>
  * </MenuProvider>
  * ```
@@ -40,8 +69,11 @@ export interface MenuItemCheckboxOptions<T extends As = "div"> extends MenuItemO
      */
     store?: MenuStore;
     /**
-     * MenuItemCheckbox's name as specified in the
+     * The name of the field in the
      * [`values`](https://ariakit.org/reference/menu-provider#values) state.
+     *
+     * Live examples:
+     * - [MenuItemCheckbox](https://ariakit.org/examples/menu-item-checkbox)
      */
     name: string;
     /**

package/esm/menu/menu-item-checkbox.js

@@ -1,11 +1,11 @@
 "use client";
+import {
+  useCheckboxStore
+} from "../__chunks/JIZ5C2JK.js";
 import {
   useCheckbox
 } from "../__chunks/3AHQ6JCP.js";
 import "../__chunks/VPR2WHQV.js";
-import {
-  useCheckboxStore
-} from "../__chunks/JIZ5C2JK.js";
 import {
   useMenuItem
 } from "../__chunks/Y6467XPW.js";

package/esm/menu/menu-item-radio.d.ts

@@ -19,18 +19,27 @@ import type { MenuStore } from "./menu-store.js";
  */
 export declare const useMenuItemRadio: import("../utils/types.js").Hook<MenuItemRadioOptions<"div">>;
 /**
- * Renders a menu item radio inside a menu.
+ * Renders a [`menuitemradio`](https://w3c.github.io/aria/#menuitemradio)
+ * element within a [`Menu`](https://ariakit.org/reference/menu) component. The
+ * [`name`](https://ariakit.org/reference/menu-item-radio#name) prop must be
+ * provided to identify the field in the
+ * [`values`](https://ariakit.org/reference/menu-provider#values) state.
+ *
+ * A [`MenuItemCheck`](https://ariakit.org/reference/menu-item-check) can be
+ * used to render a checkmark inside this component.
  * @see https://ariakit.org/components/menu
  * @example
- * ```jsx
- * <MenuProvider defaultValues={{ fruit: "apple" }}>
- *   <MenuButton>Fruit</MenuButton>
+ * ```jsx {4-11}
+ * <MenuProvider defaultValues={{ profile: "john" }}>
+ *   <MenuButton>Profiles</MenuButton>
  *   <Menu>
- *     <MenuItemRadio name="fruit" value="apple">
- *       Apple
+ *     <MenuItemRadio name="profile" value="john">
+ *       <MenuItemCheck />
+ *       John Doe
  *     </MenuItemRadio>
- *     <MenuItemRadio name="fruit" value="orange">
- *       Orange
+ *     <MenuItemRadio name="profile" value="jane">
+ *       <MenuItemCheck />
+ *       Jane Doe
  *     </MenuItemRadio>
  *   </Menu>
  * </MenuProvider>
@@ -47,8 +56,11 @@ export interface MenuItemRadioOptions<T extends As = "div"> extends MenuItemOpti
      */
     store?: MenuStore;
     /**
-     * MenuItemRadio's name as specified in the
+     * The name of the field in the
      * [`values`](https://ariakit.org/reference/menu-provider#values) state.
+     *
+     * Live examples:
+     * - [MenuItemRadio](https://ariakit.org/examples/menu-item-radio)
      */
     name: string;
     /**

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

@@ -22,10 +22,13 @@ import type { MenuStore } from "./menu-store.js";
  */
 export declare const useMenuItem: import("../utils/types.js").Hook<MenuItemOptions<"div">>;
 /**
- * Renders a menu item.
+ * Renders a menu item inside
+ * [`MenuList`](https://ariakit.org/reference/menu-list) or
+ * [`Menu`](https://ariakit.org/reference/menu)
+ * components.
  * @see https://ariakit.org/components/menu
  * @example
- * ```jsx
+ * ```jsx {4-5}
  * <MenuProvider>
  *   <MenuButton>Edit</MenuButton>
  *   <Menu>
@@ -50,20 +53,16 @@ export interface MenuItemOptions<T extends As = "div"> extends CompositeItemOpti
      */
     store?: MenubarStore | MenuStore;
     /**
-     * Whether to hide the menu when a menu item is clicked. This prop won't be
-     * invoked if the click is on a link and modifier keys are used to open the
-     * link in a new tab or download it.
+     * Determines if the menu should hide when this item is clicked.
+     *
+     * **Note**: This behavior isn't triggered if this menu item is rendered as a
+     * link and modifier keys are used to either open the link in a new tab or
+     * download it.
      *
      * Live examples:
-     * - [Submenu with
-     *   Combobox](https://ariakit.org/examples/menu-nested-combobox)
      * - [Sliding Menu](https://ariakit.org/examples/menu-slide)
      * @default true
      */
     hideOnClick?: BooleanOrCallback<MouseEvent<HTMLElement>>;
-    /**
-     * @default true
-     */
-    preventScrollOnKeyDown?: CompositeItemOptions<T>["preventScrollOnKeyDown"];
 }
 export type MenuItemProps<T extends As = "div"> = Props<MenuItemOptions<T>>;

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

@@ -19,10 +19,15 @@ import type { MenuStore } from "./menu-store.js";
  */
 export declare const useMenuList: import("../utils/types.js").Hook<MenuListOptions<"div">>;
 /**
- * Renders a menu list element.
+ * Renders a menu list element. This is the primitive component used by the
+ * [`Menu`](https://ariakit.org/reference/menu) component.
+ *
+ * Unlike [`Menu`](https://ariakit.org/reference/menu), this component doesn't
+ * render a popover and therefore doesn't automatically focus on items when
+ * opened.
  * @see https://ariakit.org/components/menu
  * @example
- * ```jsx
+ * ```jsx {3-6}
  * <MenuProvider>
  *   <MenuButton>Edit</MenuButton>
  *   <MenuList>

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

@@ -3,7 +3,8 @@ import type { PickRequired } from "@ariakit/core/utils/types";
 import type { MenuStoreProps, MenuStoreValues } from "./menu-store.js";
 type Values = MenuStoreValues;
 /**
- * Provides a menu store to Menu components.
+ * Provides a menu store to [Menu](https://ariakit.org/components/menu)
+ * components.
  * @see https://ariakit.org/components/menu
  * @example
  * ```jsx

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

@@ -19,10 +19,13 @@ import type { MenuStore } from "./menu-store.js";
  */
 export declare const useMenuSeparator: import("../utils/types.js").Hook<MenuSeparatorOptions<"hr">>;
 /**
- * Renders a separator for menu items.
+ * Renders a divider between
+ * [`MenuItem`](https://ariakit.org/reference/menu-item),
+ * [`MenuItemCheckbox`](https://ariakit.org/reference/menu-item-checkbox), and
+ * [`MenuItemRadio`](https://ariakit.org/reference/menu-item-radio) elements.
  * @see https://ariakit.org/components/menu
  * @example
- * ```jsx
+ * ```jsx {6}
  * <MenuProvider>
  *   <MenuButton>Edit</MenuButton>
  *   <Menu>

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

@@ -11,11 +11,13 @@ export declare function useMenuStoreProps<T extends Core.MenuStore>(store: T, up
     menubar: MenubarStore | null | undefined;
 };
 /**
- * Creates a menu store.
+ * Creates a menu store to control the state of
+ * [Menu](https://ariakit.org/components/menu) components.
  * @see https://ariakit.org/components/menu
  * @example
  * ```jsx
  * const menu = useMenuStore({ placement: "top" });
+ *
  * <MenuButton store={menu}>Edit</MenuButton>
  * <Menu store={menu}>
  *   <MenuItem>Undo</MenuItem>
@@ -32,7 +34,9 @@ export interface MenuStoreFunctions<T extends MenuStoreValues = MenuStoreValues>
 }
 export interface MenuStoreOptions<T extends MenuStoreValues = MenuStoreValues> extends Core.MenuStoreOptions<T>, CompositeStoreOptions, HovercardStoreOptions {
     /**
-     * A callback that gets called when the `values` state changes.
+     * A callback that gets called when the
+     * [`values`](https://ariakit.org/reference/menu-provider#values) state
+     * changes.
      *
      * Live examples:
      * - [MenuItemCheckbox](https://ariakit.org/examples/menu-item-checkbox)
@@ -41,9 +45,10 @@ export interface MenuStoreOptions<T extends MenuStoreValues = MenuStoreValues> e
      */
     setValues?: BivariantCallback<(values: MenuStoreState<T>["values"]) => void>;
     /**
-     * A reference to a combobox store. This is used when combining the combobox
-     * with a menu (e.g., dropdown menu with a search input). The stores will
-     * share the same state.
+     * A reference to a [combobox
+     * store](https://ariakit.org/reference/use-combobox-store). It's
+     * automatically set when composing [Menu with
+     * Combobox](https://ariakit.org/examples/menu-combobox).
      */
     combobox?: ComboboxStore | null;
     /**
@@ -54,11 +59,17 @@ export interface MenuStoreOptions<T extends MenuStoreValues = MenuStoreValues> e
      * Live examples:
      * - [Menubar](https://ariakit.org/components/menubar)
      * - [Submenu](https://ariakit.org/examples/menu-nested)
+     * - [Navigation Menubar](https://ariakit.org/examples/menubar-navigation)
      */
     parent?: MenuStore | null;
     /**
-     * A reference to a menu bar store. It's automatically set when rendering
-     * menus inside a menu bar in the React tree.
+     * A reference to a [menubar
+     * store](https://ariakit.org/reference/use-menubar-store). It's automatically
+     * set when rendering menus inside a
+     * [`Menubar`](https://ariakit.org/reference/menubar) in the React tree.
+     *
+     * Live examples:
+     * - [Navigation Menubar](https://ariakit.org/examples/menubar-navigation)
      */
     menubar?: MenubarStore | null;
 }

package/esm/menu/menu.d.ts

@@ -17,10 +17,16 @@ import type { MenuListOptions } from "./menu-list.jsx";
  */
 export declare const useMenu: import("../utils/types.js").Hook<MenuOptions<"div">>;
 /**
- * Renders a dropdown menu element.
+ * Renders a dropdown menu element that's controlled by a
+ * [`MenuButton`](https://ariakit.org/reference/menu-button) component.
+ *
+ * This component uses the primitive
+ * [`MenuList`](https://ariakit.org/reference/menu-list) component under the
+ * hood. It renders a popover and automatically focuses on items when the menu
+ * is shown.
  * @see https://ariakit.org/components/menu
  * @example
- * ```jsx
+ * ```jsx {3-6}
  * <MenuProvider>
  *   <MenuButton>Edit</MenuButton>
  *   <Menu>

package/esm/menu/menu.js

@@ -13,14 +13,14 @@ import "../__chunks/IB7YUKH5.js";
 import "../__chunks/4UUKJZ4V.js";
 import {
   useHovercard
-} from "../__chunks/EPBRINPG.js";
+} from "../__chunks/QWSZGSIG.js";
 import "../__chunks/YMV43K4F.js";
-import "../__chunks/A6XC27R5.js";
+import "../__chunks/IRX7SFUJ.js";
 import {
   createDialogComponent
-} from "../__chunks/PGAEII2Q.js";
+} from "../__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";
@@ -28,11 +28,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/menubar/menubar-provider.d.ts

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

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

@@ -3,11 +3,13 @@ import type { CompositeStoreFunctions, CompositeStoreOptions, CompositeStoreStat
 import type { Store } from "../utils/store.js";
 export declare function useMenubarStoreProps<T extends Core.MenubarStore>(store: T, update: () => void, props: MenubarStoreProps): T;
 /**
- * Creates a menubar store.
+ * Creates a menubar store to control the state of
+ * [Menubar](https://ariakit.org/components/menubar) components.
  * @see https://ariakit.org/components/menubar
  * @example
  * ```jsx
  * const menu = useMenubarStore();
+ *
  * <Menubar store={menu} />
  * ```
  */

package/esm/menubar/menubar.d.ts

@@ -23,8 +23,9 @@ import type { MenubarStore, MenubarStoreProps } from "./menubar-store.js";
  */
 export declare const useMenubar: import("../utils/types.js").Hook<MenubarOptions<"div">>;
 /**
- * Renders a menu bar that may contain a group of menu items that control other
- * submenus.
+ * Renders a menubar that may contain a group of
+ * [`MenuItem`](https://ariakit.org/reference/menu-item) elements that control
+ * other submenus.
  * @see https://ariakit.org/components/menubar
  * @example
  * ```jsx

package/esm/popover/popover-anchor.d.ts

@@ -13,11 +13,12 @@ import type { PopoverStore } from "./popover-store.js";
  */
 export declare const usePopoverAnchor: import("../utils/types.js").Hook<PopoverAnchorOptions<"div">>;
 /**
- * Renders an element that will serve as the popover's anchor. The popover will
- * be positioned relative to this element.
+ * Renders an element that acts as the anchor for the popover. The
+ * [`Popover`](https://ariakit.org/reference/popover) component will be
+ * positioned in relation to this element.
  * @see https://ariakit.org/components/popover
  * @example
- * ```jsx
+ * ```jsx {2}
  * <PopoverProvider>
  *   <PopoverAnchor>Anchor</PopoverAnchor>
  *   <Popover>Popover</Popover>

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

@@ -16,11 +16,12 @@ import type { PopoverStore } from "./popover-store.js";
 export declare const usePopoverArrow: import("../utils/types.js").Hook<PopoverArrowOptions<"div">>;
 /**
  * Renders an arrow inside a [`Popover`](https://ariakit.org/reference/popover)
- * component.
+ * component pointing to the anchor element.
  * @see https://ariakit.org/components/popover
  * @example
- * ```jsx
+ * ```jsx {4}
  * <PopoverProvider>
+ *   <PopoverAnchor />
  *   <Popover>
  *     <PopoverArrow />
  *     Popover
@@ -41,6 +42,9 @@ export interface PopoverArrowOptions<T extends As = "div"> extends Options<T> {
     store?: PopoverStore;
     /**
      * The size of the arrow.
+     *
+     * Live examples:
+     * - [Selection Popover](https://ariakit.org/examples/popover-selection)
      * @default 30
      */
     size?: number;

package/esm/popover/popover-description.d.ts

@@ -20,7 +20,7 @@ export declare const usePopoverDescription: import("../utils/types.js").Hook<Pop
  * prop is properly set on the popover element.
  * @see https://ariakit.org/components/popover
  * @example
- * ```jsx
+ * ```jsx {3}
  * <PopoverProvider>
  *   <Popover>
  *     <PopoverDescription>Description</PopoverDescription>

package/esm/popover/popover-disclosure-arrow.d.ts

@@ -21,7 +21,7 @@ export declare const usePopoverDisclosureArrow: import("../utils/types.js").Hook
  * component.
  * @see https://ariakit.org/components/popover
  * @example
- * ```jsx
+ * ```jsx {4}
  * <PopoverProvider>
  *   <PopoverDisclosure>
  *     Disclosure
@@ -43,9 +43,11 @@ export interface PopoverDisclosureArrowOptions<T extends As = "span"> extends Op
      */
     store?: PopoverStore;
     /**
-     * Placement to which the arrow should point. If not provided, the parent
-     * [`PopoverDisclosure`](https://ariakit.org/reference/popover-disclosure)
-     * component's context will be used.
+     * Arrow's placement direction. If not provided, it will be inferred from the
+     * context.
+     *
+     * Live examples:
+     * - [Sliding Menu](https://ariakit.org/examples/menu-slide)
      */
     placement?: PopoverStoreState["placement"];
 }

package/esm/popover/popover-disclosure.d.ts

@@ -14,10 +14,11 @@ import type { PopoverAnchorOptions } from "./popover-anchor.js";
  */
 export declare const usePopoverDisclosure: import("../utils/types.js").Hook<PopoverDisclosureOptions<"button">>;
 /**
- * Renders a button that controls the visibility of the popover when clicked.
+ * Renders a button that controls the visibility of the
+ * [`Popover`](https://ariakit.org/reference/popover) component when clicked.
  * @see https://ariakit.org/components/popover
  * @example
- * ```jsx
+ * ```jsx {2}
  * <PopoverProvider>
  *   <PopoverDisclosure>Disclosure</PopoverDisclosure>
  *   <Popover>Popover</Popover>

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

@@ -19,7 +19,7 @@ export declare const usePopoverDismiss: import("../utils/types.js").Hook<Popover
  * [`Popover`](https://ariakit.org/reference/popover) component when clicked.
  * @see https://ariakit.org/components/popover
  * @example
- * ```jsx
+ * ```jsx {3}
  * <PopoverProvider>
  *   <Popover>
  *     <PopoverDismiss />

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

@@ -20,7 +20,7 @@ export declare const usePopoverHeading: import("../utils/types.js").Hook<Popover
  * prop is properly set on the popover element.
  * @see https://ariakit.org/components/popover
  * @example
- * ```jsx
+ * ```jsx {3}
  * <PopoverProvider>
  *   <Popover>
  *     <PopoverHeading>Heading</PopoverHeading>