@ariakit/core 0.3.8 → 0.3.10

package/cjs/combobox/combobox-store.d.cts

@@ -32,7 +32,9 @@ export interface ComboboxStoreState<T extends ComboboxStoreSelectedValue = Combo
      */
     value: string;
     /**
-     * The value of the current active item.
+     * The value of the currently active item. This state automatically updates as
+     * the user navigates the combobox items either by keyboard or mouse click.
+     * Note that it doesn't update when the user simply hovers over the items.
      */
     activeValue: string | undefined;
     /**
@@ -59,6 +61,8 @@ export interface ComboboxStoreState<T extends ComboboxStoreSelectedValue = Combo
      *   Combobox](https://ariakit.org/examples/combobox-multiple)
      * - [Menu with Combobox](https://ariakit.org/examples/menu-combobox)
      * - [Select with Combobox](https://ariakit.org/examples/select-combobox)
+     * - [Submenu with
+     *   Combobox](https://ariakit.org/examples/menu-nested-combobox)
      */
     resetValueOnHide: boolean;
     /**

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

@@ -32,7 +32,9 @@ export interface ComboboxStoreState<T extends ComboboxStoreSelectedValue = Combo
      */
     value: string;
     /**
-     * The value of the current active item.
+     * The value of the currently active item. This state automatically updates as
+     * the user navigates the combobox items either by keyboard or mouse click.
+     * Note that it doesn't update when the user simply hovers over the items.
      */
     activeValue: string | undefined;
     /**
@@ -59,6 +61,8 @@ export interface ComboboxStoreState<T extends ComboboxStoreSelectedValue = Combo
      *   Combobox](https://ariakit.org/examples/combobox-multiple)
      * - [Menu with Combobox](https://ariakit.org/examples/menu-combobox)
      * - [Select with Combobox](https://ariakit.org/examples/select-combobox)
+     * - [Submenu with
+     *   Combobox](https://ariakit.org/examples/menu-nested-combobox)
      */
     resetValueOnHide: boolean;
     /**

package/cjs/composite/composite-overflow-store.cjs

@@ -1,16 +1,16 @@
 "use strict";Object.defineProperty(exports, "__esModule", {value: true});"use client";
 
 
-var _EFIT5L4Xcjs = require('../__chunks/EFIT5L4X.cjs');
-require('../__chunks/2LS4JJ4S.cjs');
-require('../__chunks/GJFZ5ZPP.cjs');
-require('../__chunks/2UK5WUJX.cjs');
+var _Y6PHIDP6cjs = require('../__chunks/Y6PHIDP6.cjs');
+require('../__chunks/MFSCSSBJ.cjs');
+require('../__chunks/MWNFQD55.cjs');
+require('../__chunks/5CBCKBZ2.cjs');
 require('../__chunks/3UT5FE6K.cjs');
 require('../__chunks/AV6KTKLE.cjs');
 
 // src/composite/composite-overflow-store.ts
 function createCompositeOverflowStore(props = {}) {
-  return _EFIT5L4Xcjs.createPopoverStore.call(void 0, props);
+  return _Y6PHIDP6cjs.createPopoverStore.call(void 0, props);
 }
 
 

package/cjs/composite/composite-store.cjs

@@ -1,13 +1,13 @@
 "use strict";Object.defineProperty(exports, "__esModule", {value: true});"use client";
 
 
-var _QAZ4PF7Scjs = require('../__chunks/QAZ4PF7S.cjs');
-require('../__chunks/ZQTYFYRS.cjs');
-require('../__chunks/2UK5WUJX.cjs');
+var _ZXCB7MXNcjs = require('../__chunks/ZXCB7MXN.cjs');
+require('../__chunks/YLMJBIQM.cjs');
+require('../__chunks/5CBCKBZ2.cjs');
 require('../__chunks/3UT5FE6K.cjs');
 require('../__chunks/5F4DVUNS.cjs');
 require('../__chunks/ULSPM3Y3.cjs');
 require('../__chunks/AV6KTKLE.cjs');
 
 
-exports.createCompositeStore = _QAZ4PF7Scjs.createCompositeStore;
+exports.createCompositeStore = _ZXCB7MXNcjs.createCompositeStore;

package/cjs/composite/composite-store.d.cts

@@ -9,13 +9,14 @@ export declare function createCompositeStore<T extends CompositeStoreItem = Comp
 export type CompositeStoreOrientation = Orientation;
 export interface CompositeStoreItem extends CollectionStoreItem {
     /**
-     * The row id of the item. This is only used on two-dimensional composites
-     * (when using `CompositeRow`).
+     * The row id of the item. This is only used on two-dimensional composite
+     * widgets (when using
+     * [`CompositeRow`](https://ariakit.org/reference/composite-row)).
      */
     rowId?: string;
     /**
-     * If enabled, the item will be disabled and users won't be able to focus it
-     * using arrow keys.
+     * If enabled, the item will be disabled and users won't be able to focus on
+     * it using arrow keys.
      */
     disabled?: boolean;
     /**
@@ -25,7 +26,11 @@ export interface CompositeStoreItem extends CollectionStoreItem {
 }
 export interface CompositeStoreState<T extends CompositeStoreItem = CompositeStoreItem> extends CollectionStoreState<T> {
     /**
-     * The composite element.
+     * The composite element itself. Typically, it's the wrapper element that
+     * contains composite items. However, in a combobox, it's the input element.
+     *
+     * Live examples:
+     * - [Sliding Menu](https://ariakit.org/examples/menu-slide)
      */
     baseElement: HTMLElement | null;
     /**
@@ -35,6 +40,10 @@ export interface CompositeStoreState<T extends CompositeStoreItem = CompositeSto
      * tabindex](https://www.w3.org/WAI/ARIA/apg/practices/keyboard-interface/#kbd_roving_tabindex).
      * DOM focus will remain on the composite element while its items receive
      * virtual focus.
+     *
+     * In both scenarios, the item in focus will carry the
+     * [`data-active-item`](https://ariakit.org/guide/styling#data-active-item)
+     * attribute.
      * @default false
      */
     virtualFocus: boolean;
@@ -51,9 +60,13 @@ export interface CompositeStoreState<T extends CompositeStoreItem = CompositeSto
      */
     orientation: Orientation;
     /**
-     * Determines how the `next` and `previous` functions will behave. If `rtl` is
-     * set to `true`, they will be inverted. This only affects the composite
-     * widget behavior. You still need to set `dir="rtl"` on HTML/CSS.
+     * Determines how the
+     * [`next`](https://ariakit.org/reference/use-composite-store#next) and
+     * [`previous`](https://ariakit.org/reference/use-composite-store#previous)
+     * functions will behave. If `rtl` is set to `true`, they will be inverted.
+     *
+     * This only affects the composite widget behavior. You still need to set
+     * `dir="rtl"` on HTML/CSS.
      * @default false
      */
     rtl: boolean;
@@ -61,15 +74,25 @@ export interface CompositeStoreState<T extends CompositeStoreItem = CompositeSto
      * Determines how the focus behaves when the user reaches the end of the
      * composite widget.
      *
-     * On one-dimensional composites:
+     * On one-dimensional composite widgets:
      * - `true` loops from the last item to the first item and vice-versa.
-     * - `horizontal` loops only if `orientation` is `horizontal` or not set.
-     * - `vertical` loops only if `orientation` is `vertical` or not set.
-     * - If `includesBaseElement` is set to `true` (or `activeId` is initially set
-     *   to `null`), the composite element will be focused in between the last and
-     *   first items.
+     * - `horizontal` loops only if
+     *   [`orientation`](https://ariakit.org/reference/composite-provider#orientation)
+     *   is `horizontal` or not set.
+     * - `vertical` loops only if
+     *   [`orientation`](https://ariakit.org/reference/composite-provider#orientation)
+     *   is `vertical` or not set.
+     * - If
+     *   [`includesBaseElement`](https://ariakit.org/reference/composite-provider#includesbaseelement)
+     *   is set to `true` (or
+     *   [`activeId`](https://ariakit.org/reference/composite-provider#activeid)
+     *   is initially set to `null`), the composite element will be focused in
+     *   between the last and first items.
      *
-     * On two-dimensional composites (when using `CompositeRow`):
+     * On two-dimensional composite widgets (when using
+     * [`CompositeRow`](https://ariakit.org/reference/composite-row) or explicitly
+     * passing a [`rowId`](https://ariakit.org/reference/composite-item#rowid)
+     * prop to composite items):
      * - `true` loops from the last row/column item to the first item in the same
      *   row/column and vice-versa. If it's the last item in the last row, it
      *   moves to the first item in the first row and vice-versa.
@@ -77,64 +100,99 @@ export interface CompositeStoreState<T extends CompositeStoreItem = CompositeSto
      *   same row.
      * - `vertical` loops only from the last column item to the first item in the
      *   column row.
-     * - If `includesBaseElement` is set to `true` (or `activeId` is initially set
-     *   to `null`), vertical loop will have no effect as moving down from the
-     *   last row or up from the first row will focus the composite element.
-     * - If `focusWrap` matches the value of `focusLoop`, it'll wrap between the
-     *   last item in the last row or column and the first item in the first row
-     *   or column and vice-versa.
+     * - If
+     *   [`includesBaseElement`](https://ariakit.org/reference/composite-provider#includesbaseelement)
+     *   is set to `true` (or
+     *   [`activeId`](https://ariakit.org/reference/composite-provider#activeid)
+     *   is initially set to `null`), vertical loop will have no effect as moving
+     *   down from the last row or up from the first row will focus on the
+     *   composite element.
+     * - If
+     *   [`focusWrap`](https://ariakit.org/reference/composite-provider#focuswrap)
+     *   matches the value of `focusLoop`, it'll wrap between the last item in the
+     *   last row or column and the first item in the first row or column and
+     *   vice-versa.
      * @default false
      */
     focusLoop: boolean | Orientation;
     /**
-     * **Works only on two-dimensional composites**. If enabled, moving to the
-     * next item from the last one in a row or column will focus the first item in
-     * the next row or column and vice-versa.
+     * **Works only on two-dimensional composite widgets**.
+     *
+     * If enabled, moving to the next item from the last one in a row or column
+     * will focus on the first item in the next row or column and vice-versa.
      * - `true` wraps between rows and columns.
      * - `horizontal` wraps only between rows.
      * - `vertical` wraps only between columns.
-     * - If `focusLoop` matches the value of `focusWrap`, it'll wrap between the
-     *   last item in the last row or column and the first item in the first row
-     *   or column and vice-versa.
+     * - If
+     *   [`focusLoop`](https://ariakit.org/reference/composite-provider#focusloop)
+     *   matches the value of `focusWrap`, it'll wrap between the last item in the
+     *   last row or column and the first item in the first row or column and
+     *   vice-versa.
      * @default false
      */
     focusWrap: boolean | Orientation;
     /**
-     * **Works only on two-dimensional composites**. If enabled, moving up or down
-     * when there's no next item or when the next item is disabled will shift to
-     * the item right before it.
+     * **Works only on two-dimensional composite widgets**.
+     *
+     * If enabled, moving up or down when there's no next item or when the next
+     * item is disabled will shift to the item right before it.
      * @default false
      */
     focusShift: boolean;
     /**
-     * The number of times the `move` function has been called.
+     * The number of times the
+     * [`move`](https://ariakit.org/reference/use-composite-store#move) function
+     * has been called.
      */
     moves: number;
     /**
-     * Indicates whether the composite element should be included in the focus
-     * order.
+     * Indicates if the composite base element (the one with a [composite
+     * role](https://w3c.github.io/aria/#composite)) should be part of the focus
+     * order when navigating with arrow keys. In other words, moving to the
+     * previous element when the first item is in focus will focus on the
+     * composite element itself. The same applies to the last item when moving to
+     * the next element.
+     *
+     * Live examples:
+     * - [Submenu with
+     *   Combobox](https://ariakit.org/examples/menu-nested-combobox)
+     * - [Combobox with tabs](https://ariakit.org/examples/combobox-tabs)
      * @default false
      */
     includesBaseElement: boolean;
     /**
-     * The current focused item `id`.
-     * - `null` focuses the base composite element and users will be able to
+     * The current active item `id`. The active item is the element within the
+     * composite widget that has either DOM or virtual focus (in case
+     * [`virtualFocus`](https://ariakit.org/reference/composite-provider#virtualfocus)
+     * is enabled).
+     * - `null` represents the base composite element (the one with a [composite
+     *   role](https://w3c.github.io/aria/#composite)). Users will be able to
      *   navigate out of it using arrow keys.
-     * - If `activeId` is initially set to `null`, the `includesBaseElement` prop
-     *   will also default to `true`, which means the base composite element
+     * - If `activeId` is initially set to `null`, the
+     *   [`includesBaseElement`](https://ariakit.org/reference/composite-provider#includesbaseelement)
+     *   prop will also default to `true`, which means the base composite element
      *   itself will have focus and users will be able to navigate to it using
      *   arrow keys.
+     *
+     * Live examples:
+     * - [Combobox with tabs](https://ariakit.org/examples/combobox-tabs)
      */
     activeId: string | null | undefined;
 }
 export interface CompositeStoreFunctions<T extends CompositeStoreItem = CompositeStoreItem> extends CollectionStoreFunctions<T> {
     /**
-     * Sets the `baseElement`.
+     * Sets the `baseElement` state.
      */
     setBaseElement: SetState<CompositeStoreState<T>["baseElement"]>;
     /**
-     * Sets the `activeId` state without moving focus. If you want to move focus,
-     * use the `move` function instead.
+     * Sets the
+     * [`activeId`](https://ariakit.org/reference/composite-provider#activeid)
+     * state _without moving focus_. If you want to move focus, use the
+     * [`move`](https://ariakit.org/reference/use-composite-store#move) function
+     * instead.
+     *
+     * Live examples:
+     * - [Combobox with tabs](https://ariakit.org/examples/combobox-tabs)
      * @example
      * // Sets the composite element as the active item
      * store.setActiveId(null);
@@ -145,9 +203,16 @@ export interface CompositeStoreFunctions<T extends CompositeStoreItem = Composit
      */
     setActiveId: SetState<CompositeStoreState<T>["activeId"]>;
     /**
-     * Moves focus to a given item id and sets it as the active item. Passing
-     * `null` will focus the composite element itself.
-     * @param id The item id to move focus to.
+     * Moves focus to a given item id and sets it as the active item.
+     * - Passing `null` will focus on the composite element itself (the one with a
+     *   [composite role](https://w3c.github.io/aria/#composite)). Users will be
+     *   able to navigate out of it using arrow keys.
+     * - If you want to set the active item id _without moving focus_, use the
+     *   [`setActiveId`](https://ariakit.org/reference/use-composite-store#setactiveid)
+     *   function instead.
+     *
+     * Live examples:
+     * - [Select Grid](https://ariakit.org/examples/select-grid)
      * @example
      * // Moves focus to the composite element
      * store.move(null);
@@ -158,43 +223,59 @@ export interface CompositeStoreFunctions<T extends CompositeStoreItem = Composit
      */
     move: (id?: string | null) => void;
     /**
-     * Returns the id of the next item based on the current `activeId` state.
-     * @param skip The number of items to skip. Defaults to 1.
+     * Returns the id of the next enabled item based on the current
+     * [`activeId`](https://ariakit.org/reference/composite-provider#activeid)
+     * state.
+     *
+     * Live examples:
+     * - [Combobox with tabs](https://ariakit.org/examples/combobox-tabs)
      * @example
      * const nextId = store.next();
      * const nextNextId = store.next(2);
      */
     next: (skip?: number) => string | null | undefined;
     /**
-     * Returns the id of the previous item based on the current `activeId` state.
-     * @param skip The number of items to skip. Defaults to 1.
+     * Returns the id of the previous enabled item based on the current
+     * [`activeId`](https://ariakit.org/reference/composite-provider#activeid)
+     * state.
+     *
+     * Live examples:
+     * - [Combobox with tabs](https://ariakit.org/examples/combobox-tabs)
      * @example
      * const previousId = store.previous();
      * const previousPreviousId = store.previous(2);
      */
     previous: (skip?: number) => string | null | undefined;
     /**
-     * Returns the id of the item above based on the current `activeId` state.
-     * @param skip The number of items to skip. Defaults to 1.
+     * Returns the id of the enabled item above based on the current
+     * [`activeId`](https://ariakit.org/reference/composite-provider#activeid)
+     * state.
      * @example
      * const upId = store.up();
      * const upUpId = store.up(2);
      */
     up: (skip?: number) => string | null | undefined;
     /**
-     * Returns the id of the item below based on the current `activeId` state.
-     * @param skip The number of items to skip. Defaults to 1.
+     * Returns the id of the enabled item below based on the current
+     * [`activeId`](https://ariakit.org/reference/composite-provider#activeid)
+     * state.
      * @example
      * const downId = store.down();
      * const downDownId = store.down(2);
      */
     down: (skip?: number) => string | null | undefined;
     /**
-     * Returns the id of the first item.
+     * Returns the id of the first enabled item.
+     *
+     * Live examples:
+     * - [Combobox with tabs](https://ariakit.org/examples/combobox-tabs)
      */
     first: () => string | null | undefined;
     /**
-     * Returns the id of the last item.
+     * Returns the id of the last enabled item.
+     *
+     * Live examples:
+     * - [Combobox with tabs](https://ariakit.org/examples/combobox-tabs)
      */
     last: () => string | null | undefined;
 }