@ariakit/core 0.3.9 → 0.3.11

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

@@ -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,71 +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 if the composite element (such as `menu`, `combobox`, `listbox`,
-     * `toolbar`, etc.) should be part of the focus order. In other words, moving
-     * to the previous element when the first item is in focus will focus on the
+     * 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);
@@ -152,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);
@@ -165,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;
 }

package/esm/composite/composite-store.js

@@ -1,10 +1,10 @@
 "use client";
 import {
   createCompositeStore
-} from "../__chunks/DLX2AS6C.js";
-import "../__chunks/TLN4ALYH.js";
-import "../__chunks/A2J4XZ5T.js";
-import "../__chunks/I2VQ3XGR.js";
+} from "../__chunks/IERTEJ3A.js";
+import "../__chunks/22K762VQ.js";
+import "../__chunks/EAHJFCU4.js";
+import "../__chunks/Y3OOHFCN.js";
 import "../__chunks/DLOEKDPY.js";
 import "../__chunks/7PRQYBBV.js";
 import "../__chunks/4R3V3JGP.js";

package/esm/dialog/dialog-store.js

@@ -1,10 +1,10 @@
 "use client";
 import {
   createDialogStore
-} from "../__chunks/LT2OYWRD.js";
-import "../__chunks/NKLTHWCR.js";
-import "../__chunks/A2J4XZ5T.js";
-import "../__chunks/I2VQ3XGR.js";
+} from "../__chunks/SX2XFD6A.js";
+import "../__chunks/Z5IGYIPT.js";
+import "../__chunks/EAHJFCU4.js";
+import "../__chunks/Y3OOHFCN.js";
 import "../__chunks/4R3V3JGP.js";
 export {
   createDialogStore

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

@@ -6,40 +6,38 @@ import type { SetState } from "../utils/types.js";
 export declare function createDisclosureStore(props?: DisclosureStoreProps): DisclosureStore;
 export interface DisclosureStoreState {
     /**
-     * The visibility state of the content.
+     * Whether the content is visible.
      *
      * Live examples:
+     * - [Combobox with links](https://ariakit.org/examples/combobox-links)
      * - [Dialog with React
      *   Router](https://ariakit.org/examples/dialog-react-router)
+     * - [Menu with Framer
+     *   Motion](https://ariakit.org/examples/menu-framer-motion)
+     * - [Lazy Popover](https://ariakit.org/examples/popover-lazy)
      * @default false
      */
     open: boolean;
     /**
-     * The mounted state of the content. If `animated` is `false` or not defined,
-     * this will be the same as `open`. Otherwise, it will wait for the animation
-     * to complete before becoming `false` so the content is not unmounted while
-     * animating.
+     * The mounted state usually matches the
+     * [`open`](https://ariakit.org/reference/disclosure-provider#open) value.
+     * However, if the content element is animated, it waits for the animation to
+     * finish before turning `false`. This ensures the content element doesn't get
+     * unmounted during the animation.
      *
      * Live examples:
-     * - [Combobox with links](https://ariakit.org/examples/combobox-links)
-     * - [Textarea with inline
-     *   Combobox](https://ariakit.org/examples/combobox-textarea)
+     * - [Navigation Menubar](https://ariakit.org/examples/menubar-navigation)
+     * - [Responsive Popover](https://ariakit.org/examples/popover-responsive)
      */
     mounted: boolean;
     /**
      * Determines whether the content should animate when it is shown or hidden.
      * - If `true`, the `animating` state will be `true` when the content is shown
-     *   or hidden and it will wait for `stopAnimation` to be called or a CSS
-     *   animation/transition to end before becoming `false`.
+     *   or hidden and it will wait for a CSS animation/transition to end before
+     *   becoming `false`.
      * - If it's set to a number, the `animating` state will be `true` when the
      *   content is shown or hidden and it will wait for the number of
      *   milliseconds to pass before becoming `false`.
-     *
-     * Live examples:
-     * - [Navigation Menubar](https://ariakit.org/examples/menubar-navigation)
-     * - [Animated Combobox](https://ariakit.org/examples/combobox-animated)
-     * - [Animated Dialog](https://ariakit.org/examples/dialog-animated)
-     * - [Animated Select](https://ariakit.org/examples/select-animated)
      * @default false
      */
     animated: boolean | number;
@@ -58,46 +56,50 @@ export interface DisclosureStoreState {
 }
 export interface DisclosureStoreFunctions {
     /**
-     * Sets the `open` state.
+     * Sets the [`open`](https://ariakit.org/reference/disclosure-provider#open)
+     * state.
      *
      * Live examples:
      * - [Textarea with inline
      *   Combobox](https://ariakit.org/examples/combobox-textarea)
-     * - [Dialog with React
-     *   Router](https://ariakit.org/examples/dialog-react-router)
      * @example
      * store.setOpen(true);
      * store.setOpen((open) => !open);
      */
     setOpen: SetState<DisclosureStoreState["open"]>;
     /**
-     * Sets the `open` state to `true`.
+     * Sets the [`open`](https://ariakit.org/reference/disclosure-provider#open)
+     * state to `true`.
      *
      * Live examples:
-     * - [Navigation Menubar](https://ariakit.org/examples/menubar-navigation)
      * - [Textarea with inline
      *   Combobox](https://ariakit.org/examples/combobox-textarea)
+     * - [Dialog with Framer
+     *   Motion](https://ariakit.org/examples/dialog-framer-motion)
+     * - [Context Menu](https://ariakit.org/examples/menu-context-menu)
+     * - [Navigation Menubar](https://ariakit.org/examples/menubar-navigation)
      */
     show: () => void;
     /**
-     * Sets the `open` state to `false`.
+     * Sets the [`open`](https://ariakit.org/reference/disclosure-provider#open)
+     * state to `false`.
      *
      * Live examples:
      * - [Textarea with inline
      *   Combobox](https://ariakit.org/examples/combobox-textarea)
-     * - [Dialog with React
-     *   Router](https://ariakit.org/examples/dialog-react-router)
      * - [Sliding Menu](https://ariakit.org/examples/menu-slide)
      */
     hide: () => void;
     /**
-     * Toggles the `open` state.
+     * Toggles the
+     * [`open`](https://ariakit.org/reference/disclosure-provider#open) state.
      */
     toggle: () => void;
     /**
      * Sets the `animating` state to `false`, which will automatically set the
      * `mounted` state to `false` if it was `true`. This means that the content
      * element can be safely unmounted.
+     * @deprecated Use `setState("animating", false)` instead.
      */
     stopAnimation: () => void;
     /**
@@ -106,19 +108,23 @@ export interface DisclosureStoreFunctions {
     setContentElement: SetState<DisclosureStoreState["contentElement"]>;
     /**
      * Sets the `disclosureElement` state.
+     *
+     * Live examples:
+     * - [Navigation Menubar](https://ariakit.org/examples/menubar-navigation)
      */
     setDisclosureElement: SetState<DisclosureStoreState["disclosureElement"]>;
 }
 export interface DisclosureStoreOptions extends StoreOptions<DisclosureStoreState, "open" | "animated"> {
     /**
-     * The default visibility state of the content.
+     * Whether the content should be visible by default.
      * @default false
      */
     defaultOpen?: DisclosureStoreState["open"];
     /**
      * A reference to another disclosure store that controls another disclosure
      * component to keep them in sync. Element states like `contentElement` and
-     * `disclosureElement` won't be synced. For that, use the `store` prop
+     * `disclosureElement` won't be synced. For that, use the
+     * [`store`](https://ariakit.org/reference/disclosure-provider#store) prop
      * instead.
      */
     disclosure?: DisclosureStore | null;

package/esm/disclosure/disclosure-store.js

@@ -1,9 +1,9 @@
 "use client";
 import {
   createDisclosureStore
-} from "../__chunks/NKLTHWCR.js";
-import "../__chunks/A2J4XZ5T.js";
-import "../__chunks/I2VQ3XGR.js";
+} from "../__chunks/Z5IGYIPT.js";
+import "../__chunks/EAHJFCU4.js";
+import "../__chunks/Y3OOHFCN.js";
 import "../__chunks/4R3V3JGP.js";
 export {
   createDisclosureStore