@ariakit/react-core 0.3.12 → 0.3.14

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

@@ -16,19 +16,16 @@ import type { ComboboxStore } from "./combobox-store.js";
  */
 export declare const useComboboxItem: import("../utils/types.js").Hook<ComboboxItemOptions<"div">>;
 /**
- * Renders a combobox item inside a
+ * Renders a combobox item inside
  * [`ComboboxList`](https://ariakit.org/reference/combobox-list) or
  * [`ComboboxPopover`](https://ariakit.org/reference/combobox-popover)
- * components. The `role` prop will be automatically set based on the list's own
- * `role` prop. For example, if the list `role` is set to `listbox` (default),
- * the `ComboboxItem` `role` will be set to `option`.
+ * components.
  *
- * By default, the
- * [`value`](https://ariakit.org/reference/combobox-item#value) prop will be
- * rendered as the children, but this can be overriden.
+ * By default, the [`value`](https://ariakit.org/reference/combobox-item#value)
+ * prop will be rendered as the children, but this can be overriden.
  * @see https://ariakit.org/components/combobox
  * @example
- * ```jsx
+ * ```jsx {4-6}
  * <ComboboxProvider>
  *   <Combobox />
  *   <ComboboxPopover>
@@ -44,10 +41,13 @@ export interface ComboboxItemOptions<T extends As = "div"> extends CompositeItem
     /**
      * Object returned by the
      * [`useComboboxStore`](https://ariakit.org/reference/use-combobox-store)
-     * hook. If not provided, the parent
+     * hook. If not provided, the closest
      * [`ComboboxList`](https://ariakit.org/reference/combobox-list) or
      * [`ComboboxPopover`](https://ariakit.org/reference/combobox-popover)
      * components' context will be used.
+     *
+     * Live examples:
+     * - [Navigation Menubar](https://ariakit.org/examples/menubar-navigation)
      */
     store?: ComboboxStore;
     /**
@@ -86,6 +86,8 @@ export interface ComboboxItemOptions<T extends As = "div"> extends CompositeItem
      *
      * Live examples:
      * - [Combobox with links](https://ariakit.org/examples/combobox-links)
+     * - [Submenu with
+     *   Combobox](https://ariakit.org/examples/menu-nested-combobox)
      */
     hideOnClick?: BooleanOrCallback<MouseEvent<HTMLElement>>;
     /**

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

@@ -21,12 +21,9 @@ export declare const useComboboxList: import("../utils/types.js").Hook<ComboboxL
  * Renders a combobox list. The `role` prop is set to `listbox` by default, but
  * can be overriden by any other valid combobox popup role (`listbox`, `menu`,
  * `tree`, `grid` or `dialog`).
- *
- * The `aria-labelledby` prop is set to the combobox input element's `id` by
- * default.
  * @see https://ariakit.org/components/combobox
  * @example
- * ```jsx
+ * ```jsx {3-7}
  * <ComboboxProvider>
  *   <Combobox />
  *   <ComboboxList>

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

@@ -19,11 +19,10 @@ export declare const useComboboxPopover: import("../utils/types.js").Hook<Combob
 /**
  * Renders a combobox popover. The `role` prop is set to `listbox` by default,
  * but can be overriden by any other valid combobox popup role (`listbox`,
- * `menu`, `tree`, `grid` or `dialog`). The `aria-labelledby` prop is set to the
- * combobox input element's `id` by default.
+ * `menu`, `tree`, `grid` or `dialog`).
  * @see https://ariakit.org/components/combobox
  * @example
- * ```jsx
+ * ```jsx {3-7}
  * <ComboboxProvider>
  *   <Combobox />
  *   <ComboboxPopover>

package/esm/combobox/combobox-popover.js

@@ -9,12 +9,12 @@ import "../__chunks/IB7YUKH5.js";
 import "../__chunks/4UUKJZ4V.js";
 import {
   usePopover
-} from "../__chunks/A6XC27R5.js";
+} from "../__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";
@@ -22,11 +22,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/combobox/combobox-provider.d.ts

@@ -3,7 +3,8 @@ import type { PickRequired } from "@ariakit/core/utils/types";
 import type { ComboboxStoreProps, ComboboxStoreSelectedValue } from "./combobox-store.js";
 type Value = ComboboxStoreSelectedValue;
 /**
- * Provides a combobox store to Combobox components.
+ * Provides a combobox store that controls the state of
+ * [Combobox](https://ariakit.org/components/combobox) components.
  * @see https://ariakit.org/components/combobox
  * @example
  * ```jsx

package/esm/combobox/combobox-row.d.ts

@@ -19,10 +19,13 @@ import type { ComboboxStore } from "./combobox-store.js";
  */
 export declare const useComboboxRow: import("../utils/types.js").Hook<ComboboxRowOptions<"div">>;
 /**
- * Renders a combobox row.
+ * Renders a combobox row that allows two-dimensional arrow key navigation.
+ * [`ComboboxItem`](https://ariakit.org/reference/combobox-item) elements
+ * wrapped within this component will automatically receive a
+ * [`rowId`](https://ariakit.org/reference/combobox-item#rowid) prop.
  * @see https://ariakit.org/components/combobox
  * @example
- * ```jsx
+ * ```jsx {4-13}
  * <ComboboxProvider>
  *   <Combobox />
  *   <ComboboxPopover>
@@ -45,7 +48,7 @@ export interface ComboboxRowOptions<T extends As = "div"> extends CompositeRowOp
     /**
      * Object returned by the
      * [`useComboboxStore`](https://ariakit.org/reference/use-combobox-store)
-     * hook. If not provided, the parent
+     * hook. If not provided, the closest
      * [`ComboboxList`](https://ariakit.org/reference/combobox-list) or
      * [`ComboboxPopover`](https://ariakit.org/reference/combobox-popover)
      * components' context will be used.

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

@@ -18,10 +18,11 @@ import type { ComboboxStore } from "./combobox-store.js";
  */
 export declare const useComboboxSeparator: import("../utils/types.js").Hook<ComboboxSeparatorOptions<"hr">>;
 /**
- * Renders a separator element for combobox items
+ * Renders a divider between
+ * [`ComboboxItem`](https://ariakit.org/reference/combobox-item) elements.
  * @see https://ariakit.org/components/combobox
  * @example
- * ```jsx
+ * ```jsx {5}
  * <ComboboxProvider>
  *   <Combobox />
  *   <ComboboxPopover>
@@ -38,7 +39,7 @@ export interface ComboboxSeparatorOptions<T extends As = "hr"> extends Composite
     /**
      * Object returned by the
      * [`useComboboxStore`](https://ariakit.org/reference/use-combobox-store)
-     * hook. If not provided, the parent
+     * hook. If not provided, the closest
      * [`ComboboxList`](https://ariakit.org/reference/combobox-list) or
      * [`ComboboxPopover`](https://ariakit.org/reference/combobox-popover)
      * components' context will be used.

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

@@ -5,17 +5,21 @@ import type { PopoverStoreFunctions, PopoverStoreOptions, PopoverStoreState } fr
 import type { Store } from "../utils/store.js";
 export declare function useComboboxStoreProps<T extends Core.ComboboxStore>(store: T, update: () => void, props: ComboboxStoreProps): T;
 /**
- * Creates a combobox store.
+ * Creates a combobox store to control the state of
+ * [Combobox](https://ariakit.org/components/combobox) components.
  * @see https://ariakit.org/components/combobox
  * @example
  * ```jsx
  * const combobox = useComboboxStore();
- * <Combobox store={combobox} />
- * <ComboboxPopover store={combobox}>
- *   <ComboboxItem value="Apple" />
- *   <ComboboxItem value="Banana" />
- *   <ComboboxItem value="Orange" />
- * </ComboboxPopover>
+ *
+ * <ComboboxProvider store={combobox}>
+ *   <Combobox />
+ *   <ComboboxPopover>
+ *     <ComboboxItem value="Apple" />
+ *     <ComboboxItem value="Banana" />
+ *     <ComboboxItem value="Orange" />
+ *   </ComboboxPopover>
+ * </ComboboxProvider>
  * ```
  */
 export declare function useComboboxStore<T extends ComboboxStoreSelectedValue = ComboboxStoreSelectedValue>(props: PickRequired<ComboboxStoreProps<T>, "selectedValue" | "defaultSelectedValue">): ComboboxStore<T>;

package/esm/combobox/combobox.d.ts

@@ -21,10 +21,10 @@ import type { ComboboxStore, ComboboxStoreState } from "./combobox-store.js";
  */
 export declare const useCombobox: import("../utils/types.js").Hook<ComboboxOptions<"input">>;
 /**
- * Renders a combobox input.
+ * Renders a combobox input element that can be used to filter a list of items.
  * @see https://ariakit.org/components/combobox
  * @example
- * ```jsx
+ * ```jsx {2}
  * <ComboboxProvider>
  *   <Combobox />
  *   <ComboboxPopover>
@@ -46,9 +46,9 @@ export interface ComboboxOptions<T extends As = "input"> extends CompositeOption
      */
     store?: ComboboxStore;
     /**
-     * Whether the first item will be automatically selected when the combobox
-     * input value changes. When it's set to `true`, the exact behavior will
-     * depend on the value of
+     * Whether the first enabled item will be automatically selected when the
+     * combobox input value changes. When it's set to `true`, the exact behavior
+     * will depend on the value of the
      * [`autoComplete`](https://ariakit.org/reference/combobox#autocomplete) prop:
      * - If [`autoComplete`](https://ariakit.org/reference/combobox#autocomplete)
      *   is `both` or `inline`, the first item is automatically focused when the
@@ -58,6 +58,10 @@ export interface ComboboxOptions<T extends As = "input"> extends CompositeOption
      *   is `list` or `none`, the first item is automatically focused when the
      *   popup opens, but the input value doesn't change.
      *
+     * To change which item is auto selected, use the
+     * [`getAutoSelectId`](https://ariakit.org/reference/combobox#getautoselectid)
+     * prop.
+     *
      * Live examples:
      * - [Combobox with integrated
      *   filter](https://ariakit.org/examples/combobox-filtering-integrated)
@@ -106,22 +110,22 @@ export interface ComboboxOptions<T extends As = "input"> extends CompositeOption
      * This prop is based on the standard
      * [`aria-autocomplete`](https://w3c.github.io/aria/#aria-autocomplete)
      * attribute, accepting the same values:
-     * - `both`: indicates that the items will be filtered based on
+     * - `list` (default): indicates that the items will be dynamically rendered
+     *   based on [`value`](https://ariakit.org/reference/combobox-provider#value)
+     *   and the input value will _not_ change based on the active item. The
+     *   filtering logic must be implemented by the consumer of this component.
+     * - `inline`: indicates that the items are static, that is, they won't be
+     *   filtered, but the input value will temporarily change based on the active
+     *   item. Ariakit will automatically provide the inline autocompletion
+     *   behavior.
+     * - `both`: indicates that the items will be dynamically rendered based on
      *   [`value`](https://ariakit.org/reference/combobox-provider#value) and the
      *   input value will temporarily change based on the active item. The
      *   filtering logic must be implemented by the consumer of this component,
      *   whereas Ariakit will automatically provide the inline autocompletion
      *   behavior.
-     * - `list` (default): indicates that the items will be filtered based on
-     *   [`value`](https://ariakit.org/reference/combobox-provider#value) and the
-     *   input value will NOT change based on the active item. The filtering logic
-     *   must be implemented by the consumer of this component.
-     * - `inline`: indicates that the items are static, that is, they won't be
-     *   filtered, but the input value will temporarily change based on the active
-     *   item. Ariakit will automatically provide the inline autocompletion
-     *   behavior
-     * - `none`: the items are static and the input value will NOT change based on
-     *   the active item.
+     * - `none`: the items are static and the input value will _not_ change based
+     *   on the active item.
      *
      * Live examples:
      * - [ComboboxGroup](https://ariakit.org/examples/combobox-group)
@@ -129,8 +133,9 @@ export interface ComboboxOptions<T extends As = "input"> extends CompositeOption
      */
     autoComplete?: StringWithValue<Required<AriaAttributes>["aria-autocomplete"]>;
     /**
-     * Whether the combobox list/popover should be shown when the input value is
-     * changed.
+     * Whether the [`ComboboxList`](https://ariakit.org/reference/combobox-list)
+     * or [`ComboboxPopover`](https://ariakit.org/reference/combobox-popover)
+     * components should be shown when the input value changes.
      *
      * Live examples:
      * - [Textarea with inline
@@ -142,17 +147,6 @@ export interface ComboboxOptions<T extends As = "input"> extends CompositeOption
      * ```
      */
     showOnChange?: BooleanOrCallback<ChangeEvent<HTMLElement>>;
-    /**
-     * Whether the combobox store value will be updated when the input value
-     * changes. This is useful if you want to customize how the store value is
-     * updated based on the input value.
-     *
-     * Live examples:
-     * - [Textarea with inline
-     *   Combobox](https://ariakit.org/examples/combobox-textarea)
-     * @default true
-     */
-    setValueOnChange?: BooleanOrCallback<ChangeEvent<HTMLElement>>;
     /**
      * Whether the [`ComboboxList`](https://ariakit.org/reference/combobox-list)
      * or [`ComboboxPopover`](https://ariakit.org/reference/combobox-popover)
@@ -185,11 +179,29 @@ export interface ComboboxOptions<T extends As = "input"> extends CompositeOption
      */
     showOnKeyDown?: BooleanOrCallback<ReactKeyboardEvent<HTMLElement>>;
     /**
-     * Whether the combobox store value will be updated when the combobox input
-     * element gets clicked. This usually only applies when `autoComplete` is
+     * Whether the combobox
+     * [`value`](https://ariakit.org/reference/combobox-provider#value) state
+     * should be updated when the input value changes. This is useful if you want
+     * to customize how the store
+     * [`value`](https://ariakit.org/reference/combobox-provider#value) is updated
+     * based on the input element's value.
+     *
+     * Live examples:
+     * - [Textarea with inline
+     *   Combobox](https://ariakit.org/examples/combobox-textarea)
+     * @default true
+     */
+    setValueOnChange?: BooleanOrCallback<ChangeEvent<HTMLElement>>;
+    /**
+     * Whether the combobox
+     * [`value`](https://ariakit.org/reference/combobox-provider#value) state
+     * should be updated when the combobox input element gets clicked. This
+     * usually only applies when
+     * [`autoComplete`](https://ariakit.org/reference/combobox#autocomplete) is
      * `both` or `inline`, because the input value will temporarily change based
-     * on the active item and the store value will not be updated until the user
-     * confirms the selection.
+     * on the active item and the store
+     * [`value`](https://ariakit.org/reference/combobox-provider#value) will not
+     * be updated until the user confirms the selection.
      * @default true
      */
     setValueOnClick?: BooleanOrCallback<MouseEvent<HTMLElement>>;

package/esm/command/command.d.ts

@@ -26,7 +26,7 @@ export declare const useCommand: import("../utils/types.js").Hook<CommandOptions
  * @see https://ariakit.org/components/command
  * @example
  * ```jsx
- * <Command render={<div />}>Accessible button</Command>
+ * <Command>Button</Command>
  * ```
  */
 export declare const Command: import("../utils/types.js").Component<CommandOptions<"button">>;

package/esm/composite/composite-container.d.ts

@@ -20,24 +20,31 @@ import type { CompositeStore } from "./composite-store.js";
 export declare const useCompositeContainer: import("../utils/types.js").Hook<CompositeContainerOptions<"div">>;
 /**
  * Renders a container for interactive widgets inside composite items. This
- * should be used in conjunction with the `CompositeItem` component or a
- * component that uses `CompositeItem` underneath.
+ * should be used in conjunction with the
+ * [`CompositeItem`](https://ariakit.org/reference/composite-item) component or
+ * a component that uses
+ * [`CompositeItem`](https://ariakit.org/reference/composite-item) underneath.
  * @see https://ariakit.org/components/composite
  * @example
- * ```jsx
- * const composite = useCompositeStore();
- * <Composite store={composite}>
- *   <CompositeItem render={<CompositeContainer />}>
- *     <input type="text" />
- *   </CompositeItem>
- * </Composite>
+ * ```jsx {3-5}
+ * <CompositeProvider>
+ *   <Composite>
+ *     <CompositeItem render={<CompositeContainer />}>
+ *       <input type="text" />
+ *     </CompositeItem>
+ *   </Composite>
+ * </CompositeProvider>
  * ```
  */
 export declare const CompositeContainer: import("../utils/types.js").Component<CompositeContainerOptions<"div">>;
 export interface CompositeContainerOptions<T extends As = "div"> extends Options<T> {
     /**
-     * Object returned by the `useCompositeStore` hook. If not provided, the
-     * parent `Composite` component's context will be used.
+     * Object returned by the
+     * [`useCompositeStore`](https://ariakit.org/reference/use-composite-store)
+     * hook. If not provided, the closest
+     * [`Composite`](https://ariakit.org/reference/composite) or
+     * [`CompositeProvider`](https://ariakit.org/reference/composite-provider)
+     * components' context will be used.
      */
     store?: CompositeStore;
 }

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

@@ -16,26 +16,31 @@ import type { CompositeStore } from "./composite-store.js";
 export declare const useCompositeGroupLabel: import("../utils/types.js").Hook<CompositeGroupLabelOptions<"div">>;
 /**
  * Renders a label in a composite group. This component must be wrapped with
- * `CompositeGroup` so the `aria-labelledby` prop is properly set on the
- * composite group element.
+ * [`CompositeGroup`](https://ariakit.org/reference/composite-group) so the
+ * `aria-labelledby` prop is properly set on the group element.
  * @see https://ariakit.org/components/composite
  * @example
- * ```jsx
- * const composite = useCompositeStore();
- * <Composite store={composite}>
- *   <CompositeGroup>
- *     <CompositeGroupLabel>Label</CompositeGroupLabel>
- *     <CompositeItem>Item 1</CompositeItem>
- *     <CompositeItem>Item 2</CompositeItem>
- *   </CompositeGroup>
- * </Composite>
+ * ```jsx {4}
+ * <CompositeProvider>
+ *   <Composite>
+ *     <CompositeGroup>
+ *       <CompositeGroupLabel>Label</CompositeGroupLabel>
+ *       <CompositeItem>Item 1</CompositeItem>
+ *       <CompositeItem>Item 2</CompositeItem>
+ *     </CompositeGroup>
+ *   </Composite>
+ * </CompositeProvider>
  * ```
  */
 export declare const CompositeGroupLabel: import("../utils/types.js").Component<CompositeGroupLabelOptions<"div">>;
 export interface CompositeGroupLabelOptions<T extends As = "div"> extends GroupLabelOptions<T> {
     /**
-     * Object returned by the `useCompositeStore` hook. If not provided, the
-     * parent `Composite` component's context will be used.
+     * Object returned by the
+     * [`useCompositeStore`](https://ariakit.org/reference/use-composite-store)
+     * hook. If not provided, the closest
+     * [`Composite`](https://ariakit.org/reference/composite) or
+     * [`CompositeProvider`](https://ariakit.org/reference/composite-provider)
+     * components' context will be used.
      */
     store?: CompositeStore;
 }

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

@@ -19,25 +19,33 @@ import type { CompositeStore } from "./composite-store.js";
  */
 export declare const useCompositeGroup: import("../utils/types.js").Hook<CompositeGroupOptions<"div">>;
 /**
- * Renders a group element for composite items.
+ * Renders a group element for composite items. The
+ * [`CompositeGroupLabel`](https://ariakit.org/reference/composite-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/composite
  * @example
- * ```jsx
- * const composite = useCompositeStore();
- * <Composite store={composite}>
- *   <CompositeGroup>
- *     <CompositeGroupLabel>Label</CompositeGroupLabel>
- *     <CompositeItem>Item 1</CompositeItem>
- *     <CompositeItem>Item 2</CompositeItem>
- *   </CompositeGroup>
- * </Composite>
+ * ```jsx {3-7}
+ * <CompositeProvider>
+ *   <Composite>
+ *     <CompositeGroup>
+ *       <CompositeGroupLabel>Label</CompositeGroupLabel>
+ *       <CompositeItem>Item 1</CompositeItem>
+ *       <CompositeItem>Item 2</CompositeItem>
+ *     </CompositeGroup>
+ *   </Composite>
+ * </CompositeProvider>
  * ```
  */
 export declare const CompositeGroup: import("../utils/types.js").Component<CompositeGroupOptions<"div">>;
 export interface CompositeGroupOptions<T extends As = "div"> extends GroupOptions<T> {
     /**
-     * Object returned by the `useCompositeStore` hook. If not provided, the
-     * parent `Composite` component's context will be used.
+     * Object returned by the
+     * [`useCompositeStore`](https://ariakit.org/reference/use-composite-store)
+     * hook. If not provided, the closest
+     * [`Composite`](https://ariakit.org/reference/composite) or
+     * [`CompositeProvider`](https://ariakit.org/reference/composite-provider)
+     * components' context will be used.
      */
     store?: CompositeStore;
 }

package/esm/composite/composite-hover.d.ts

@@ -19,16 +19,25 @@ import type { CompositeStore } from "./composite-store.js";
 export declare const useCompositeHover: import("../utils/types.js").Hook<CompositeHoverOptions<"div">>;
 /**
  * Renders an element in a composite widget that receives focus on mouse move
- * and loses focus to the composite base element on mouse leave. This should be
- * combined with the `CompositeItem` component, the `useCompositeItem` hook or
- * any component/hook that uses them underneath.
+ * and loses focus to the composite base element on mouse leave.
+ *
+ * This should be combined with the
+ * [`CompositeItem`](https://ariakit.org/reference/composite-item) component.
+ * The
+ * [`focusOnHover`](https://ariakit.org/reference/composite-hover#focusonhover)
+ * and
+ * [`blurOnHoverEnd`](https://ariakit.org/reference/composite-hover#bluronhoverend)
+ * props can be used to customize the behavior.
  * @see https://ariakit.org/components/composite
  * @example
- * ```jsx
- * const composite = useCompositeStore();
- * <Composite store={composite}>
- *   <CompositeHover render={<CompositeItem />}>Item</CompositeHover>
- * </Composite>
+ * ```jsx {3-5}
+ * <CompositeProvider>
+ *   <Composite>
+ *     <CompositeHover render={<CompositeItem />}>
+ *       Item
+ *     </CompositeHover>
+ *   </Composite>
+ * </CompositeProvider>
  * ```
  */
 export declare const CompositeHover: import("../utils/types.js").Component<CompositeHoverOptions<"div">>;

package/esm/composite/composite-input.d.ts

@@ -17,22 +17,28 @@ import type { CompositeStore } from "./composite-store.js";
 export declare const useCompositeInput: import("../utils/types.js").Hook<CompositeInputOptions<"input">>;
 /**
  * Renders an input as a composite item. This should be used in conjunction with
- * the `CompositeItem` component or a component that uses `CompositeItem`
- * underneath.
+ * the [`CompositeItem`](https://ariakit.org/reference/composite-item) component
+ * or a component that uses
+ * [`CompositeItem`](https://ariakit.org/reference/composite-item) underneath.
  * @see https://ariakit.org/components/composite
  * @example
- * ```jsx
- * const composite = useCompositeStore();
- * <Composite store={composite}>
- *   <CompositeItem render={<CompositeInput />} />
- * </Composite>
+ * ```jsx {3}
+ * <CompositeProvider>
+ *   <Composite>
+ *     <CompositeItem render={<CompositeInput />} />
+ *   </Composite>
+ * </CompositeProvider>
  * ```
  */
 export declare const CompositeInput: import("../utils/types.js").Component<CompositeInputOptions<"input">>;
 export interface CompositeInputOptions<T extends As = "input"> extends Options<T> {
     /**
-     * Object returned by the `useCompositeStore` hook. If not provided, the
-     * parent `Composite` component's context will be used.
+     * Object returned by the
+     * [`useCompositeStore`](https://ariakit.org/reference/use-composite-store)
+     * hook. If not provided, the closest
+     * [`Composite`](https://ariakit.org/reference/composite) or
+     * [`CompositeProvider`](https://ariakit.org/reference/composite-provider)
+     * components' context will be used.
      */
     store?: CompositeStore;
 }

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

@@ -16,16 +16,27 @@ import type { CompositeStore } from "./composite-store.js";
  */
 export declare const useCompositeItem: import("../utils/types.js").Hook<CompositeItemOptions<"button">>;
 /**
- * Renders a composite item.
+ * Renders a focusable item as part of a composite widget. The `tabindex`
+ * attribute is automatically managed by this component based on the
+ * [`virtualFocus`](https://ariakit.org/reference/composite-provider#virtualfocus)
+ * option.
+ *
+ * When this component receives DOM focus or is virtually focused (when the
+ * [`virtualFocus`](https://ariakit.org/reference/composite-provider#virtualfocus)
+ * option is set to `true`), the element will automatically receive the
+ * [`data-active-item`](https://ariakit.org/guide/styling#data-active-item)
+ * attribute. This can be used to style the focused item, no matter the focus
+ * approach employed.
  * @see https://ariakit.org/components/composite
  * @example
- * ```jsx
- * const composite = useCompositeStore();
- * <Composite store={composite}>
- *   <CompositeItem>Item 1</CompositeItem>
- *   <CompositeItem>Item 2</CompositeItem>
- *   <CompositeItem>Item 3</CompositeItem>
- * </Composite>
+ * ```jsx {3-5}
+ * <CompositeProvider>
+ *   <Composite>
+ *     <CompositeItem>Item 1</CompositeItem>
+ *     <CompositeItem>Item 2</CompositeItem>
+ *     <CompositeItem>Item 3</CompositeItem>
+ *   </Composite>
+ * </CompositeProvider>
  * ```
  */
 export declare const CompositeItem: import("../utils/types.js").Component<CompositeItemOptions<"button">>;
@@ -39,6 +50,14 @@ export interface CompositeItemOptions<T extends As = "button"> extends CommandOp
      * components' context will be used.
      */
     store?: CompositeStore;
+    /**
+     * Determines if the item should be registered as part of the collection. If
+     * this is set to `false`, the item won't be accessible via arrow keys.
+     *
+     * Live examples:
+     * - [Combobox with tabs](https://ariakit.org/examples/combobox-tabs)
+     */
+    shouldRegisterItem?: CollectionItemOptions<T>["shouldRegisterItem"];
     /**
      * The id that will be used to group items in the same row. This is usually
      * retrieved by the
@@ -49,12 +68,33 @@ export interface CompositeItemOptions<T extends As = "button"> extends CommandOp
     /**
      * Whether the scroll behavior should be prevented when pressing arrow keys on
      * the first or the last items.
+     * @deprecated Use CSS
+     * [`scroll-margin`](https://developer.mozilla.org/en-US/docs/Web/CSS/scroll-margin)
+     * instead.
      * @default false
      */
     preventScrollOnKeyDown?: BooleanOrCallback<KeyboardEvent<HTMLElement>>;
     /**
-     * Whether pressing arrow keys should move the focus to a different item.
+     * Determines if pressing arrow keys while this item is in focus should move
+     * focus to a different item.
+     *
+     * **Note**: To entirely disable focus moving within a composite widget, you
+     * can use the
+     * [`focusOnMove`](https://ariakit.org/reference/composite#focusonmove) prop
+     * on the composite component instead. If you want to control the behavior
+     * _only when arrow keys are pressed_, where
+     * [`focusOnMove`](https://ariakit.org/reference/composite#focusonmove) may
+     * not be applicable, this prop must be set on all composite items because
+     * they each manage their own key presses, as well as on the composite
+     * component itself.
      * @default true
+     * @example
+     * ```jsx
+     * <Composite moveOnKeyPress={false}>
+     *   <CompositeItem moveOnKeyPress={false} />
+     *   <CompositeItem moveOnKeyPress={false} />
+     * </Composite>
+     * ```
      */
     moveOnKeyPress?: BooleanOrCallback<KeyboardEvent<HTMLElement>>;
     /**