@zag-js/combobox 0.47.0 → 0.49.0

package/dist/index.d.mts

@@ -1,14 +1,15 @@
+import { InteractOutsideHandlers } from '@zag-js/dismissable';
+export { FocusOutsideEvent, InteractOutsideEvent, PointerDownOutsideEvent } from '@zag-js/dismissable';
 import * as _zag_js_anatomy from '@zag-js/anatomy';
 import { CollectionOptions, Collection, CollectionItem } from '@zag-js/collection';
 export { CollectionItem, CollectionOptions } from '@zag-js/collection';
 import { RequiredBy, PropTypes, DirectionProperty, CommonProperties, NormalizeProps } from '@zag-js/types';
 import * as _zag_js_core from '@zag-js/core';
 import { StateMachine } from '@zag-js/core';
-import { InteractOutsideHandlers } from '@zag-js/dismissable';
 import { PositioningOptions } from '@zag-js/popper';
 export { Placement, PositioningOptions } from '@zag-js/popper';
 
-declare const anatomy: _zag_js_anatomy.AnatomyInstance<"root" | "label" | "input" | "positioner" | "control" | "trigger" | "content" | "clearTrigger" | "item" | "itemText" | "itemIndicator" | "itemGroup" | "itemGroupLabel">;
+declare const anatomy: _zag_js_anatomy.AnatomyInstance<"input" | "label" | "content" | "root" | "positioner" | "control" | "trigger" | "clearTrigger" | "item" | "itemText" | "itemIndicator" | "itemGroup" | "itemGroupLabel">;
 
 declare const collection: {
     <T extends unknown>(options: CollectionOptions<T>): Collection<T>;
@@ -24,11 +25,20 @@ interface HighlightChangeDetails<T extends CollectionItem = CollectionItem> {
     highligtedItem: T | null;
 }
 interface InputValueChangeDetails {
-    value: string;
+    inputValue: string;
 }
 interface OpenChangeDetails {
     open: boolean;
 }
+interface SelectionValueDetails<T extends CollectionItem = CollectionItem> {
+    inputValue: string;
+    selectedItems: T[];
+    valueAsString: string;
+}
+interface ScrollToIndexDetails {
+    index: number;
+    immediate?: boolean;
+}
 interface IntlTranslations {
     triggerLabel?: string;
     clearTriggerLabel?: string;
@@ -47,6 +57,14 @@ type ElementIds = Partial<{
     itemGroupLabel(id: string | number): string;
 }>;
 interface PublicContext<T extends CollectionItem = CollectionItem> extends DirectionProperty, CommonProperties, InteractOutsideHandlers {
+    /**
+     * Whether the combobox is open
+     */
+    open?: boolean;
+    /**
+     * Whether the combobox open state is controlled by the user
+     */
+    "open.controlled"?: boolean;
     /**
      * The ids of the elements in the combobox. Useful for composition.
      */
@@ -103,10 +121,6 @@ interface PublicContext<T extends CollectionItem = CollectionItem> extends Direc
      * - `preserve`: The input value is preserved
      */
     selectionBehavior: "clear" | "replace" | "preserve";
-    /**
-     * Whether to select the higlighted item on interaction outside the combobox
-     */
-    selectOnBlur: boolean;
     /**
      * Whether to autofocus the input on mount
      */
@@ -116,13 +130,17 @@ interface PublicContext<T extends CollectionItem = CollectionItem> extends Direc
      */
     openOnClick?: boolean;
     /**
-     * Whether to allow custom values or free values in the input
+     * Whether to show the combobox when the input value changes
+     */
+    openOnChange?: boolean | ((details: InputValueChangeDetails) => boolean);
+    /**
+     * Whether to allow typing custom values in the input
      */
     allowCustomValue?: boolean;
     /**
      * Whether to loop the keyboard navigation through the items
      */
-    loop?: boolean;
+    loopFocus?: boolean;
     /**
      * The positioning options to dynamically position the menu
      */
@@ -160,9 +178,31 @@ interface PublicContext<T extends CollectionItem = CollectionItem> extends Direc
      * Whether to close the combobox when an item is selected.
      */
     closeOnSelect?: boolean;
+    /**
+     * Function to get the display value of the selected item
+     */
+    getSelectionValue?: (details: SelectionValueDetails<T>) => string;
+    /**
+     * Whether to open the combobox on arrow key press
+     */
+    openOnKeyPress: boolean;
+    /**
+     * Function to scroll to a specific index
+     */
+    scrollToIndexFn?: (details: ScrollToIndexDetails) => void;
+    /**
+     * The underling `aria-haspopup` attribute to use for the combobox
+     * - `listbox`: The combobox has a listbox popup (default)
+     * - `dialog`: The combobox has a dialog popup. Useful when in select only mode
+     */
+    popup: "listbox" | "dialog";
+    /**
+     * Whether to register this combobox as a dismissable layer
+     */
+    dismissable: boolean;
 }
 type UserDefinedContext<T extends CollectionItem = CollectionItem> = RequiredBy<PublicContext<T>, "id" | "collection">;
-type ComputedContext<T extends CollectionItem = CollectionItem> = Readonly<{
+type ComputedContext = Readonly<{
     /**
      * @computed
      * Whether the input's value is empty
@@ -181,27 +221,27 @@ type ComputedContext<T extends CollectionItem = CollectionItem> = Readonly<{
      * @computed
      */
     autoHighlight: boolean;
+    /**
+     * @computed
+     * Whether there's a selected option
+     */
+    hasSelectedItems: boolean;
+}>;
+interface PrivateContext<T extends CollectionItem = CollectionItem> {
     /**
      * The highlighted item
      */
     highlightedItem: T | null;
     /**
-     * @computed
+     * @interal
      * The selected items
      */
     selectedItems: T[];
     /**
-     * @computed
-     * Whether there's a selected option
-     */
-    hasSelectedItems: boolean;
-    /**
-     * @computed
+     * @interal
      * The display value of the combobox (based on the selected items)
      */
     valueAsString: string;
-}>;
-interface PrivateContext {
 }
 interface MachineContext extends PublicContext, PrivateContext, ComputedContext {
 }
@@ -212,13 +252,32 @@ interface MachineState {
 type State = StateMachine.State<MachineContext, MachineState>;
 type Send = StateMachine.Send<StateMachine.AnyEventObject>;
 interface ItemProps {
+    /**
+     * Whether hovering outside should clear the highlighted state
+     */
+    persistFocus?: boolean;
+    /**
+     * The item to render
+     */
     item: CollectionItem;
 }
 interface ItemState {
+    /**
+     * The value of the item
+     */
     value: string;
-    isDisabled: boolean;
-    isSelected: boolean;
-    isHighlighted: boolean;
+    /**
+     * Whether the item is disabled
+     */
+    disabled: boolean;
+    /**
+     * Whether the item is selected
+     */
+    selected: boolean;
+    /**
+     * Whether the item is highlighted via pointer or keyboard navigation
+     */
+    highlighted: boolean;
 }
 interface ItemGroupProps {
     id: string;
@@ -230,15 +289,15 @@ interface MachineApi<T extends PropTypes = PropTypes, V extends CollectionItem =
     /**
      * Whether the combobox is focused
      */
-    isFocused: boolean;
+    focused: boolean;
     /**
      * Whether the combobox is open
      */
-    isOpen: boolean;
+    open: boolean;
     /**
      * Whether the combobox input value is empty
      */
-    isInputValueEmpty: boolean;
+    inputEmpty: boolean;
     /**
      * The value of the combobox input
      */
@@ -296,13 +355,9 @@ interface MachineApi<T extends PropTypes = PropTypes, V extends CollectionItem =
      */
     getItemState(props: ItemProps): ItemState;
     /**
-     * Function to open the combobox
-     */
-    open(): void;
-    /**
-     * Function to close the combobox
+     * Function to open or close the combobox
      */
-    close(): void;
+    setOpen(open: boolean): void;
     /**
      * Function to toggle the combobox
      */
@@ -314,7 +369,7 @@ interface MachineApi<T extends PropTypes = PropTypes, V extends CollectionItem =
     /**
      * Function to set the positioning options
      */
-    reposition(options: Partial<PositioningOptions>): void;
+    reposition(options?: Partial<PositioningOptions>): void;
     rootProps: T["element"];
     labelProps: T["label"];
     controlProps: T["element"];
@@ -323,6 +378,7 @@ interface MachineApi<T extends PropTypes = PropTypes, V extends CollectionItem =
     contentProps: T["element"];
     triggerProps: T["button"];
     clearTriggerProps: T["button"];
+    listProps: T["element"];
     getItemProps(props: ItemProps): T["element"];
     getItemTextProps(props: ItemProps): T["element"];
     getItemIndicatorProps(props: ItemProps): T["element"];
@@ -334,4 +390,4 @@ declare function connect<T extends PropTypes, V extends CollectionItem>(state: S
 
 declare function machine<T extends CollectionItem>(userContext: UserDefinedContext<T>): _zag_js_core.Machine<MachineContext, MachineState, _zag_js_core.StateMachine.AnyEventObject>;
 
-export { type MachineApi as Api, type UserDefinedContext as Context, type ElementIds, type HighlightChangeDetails, type InputValueChangeDetails, type ItemGroupLabelProps, type ItemGroupProps, type ItemProps, type ItemState, type OpenChangeDetails, type ValueChangeDetails, anatomy, collection, connect, machine };
+export { type MachineApi as Api, type UserDefinedContext as Context, type ElementIds, type HighlightChangeDetails, type InputValueChangeDetails, type IntlTranslations, type ItemGroupLabelProps, type ItemGroupProps, type ItemProps, type ItemState, type OpenChangeDetails, type ScrollToIndexDetails, type SelectionValueDetails, type ValueChangeDetails, anatomy, collection, connect, machine };

package/dist/index.d.ts

@@ -1,14 +1,15 @@
+import { InteractOutsideHandlers } from '@zag-js/dismissable';
+export { FocusOutsideEvent, InteractOutsideEvent, PointerDownOutsideEvent } from '@zag-js/dismissable';
 import * as _zag_js_anatomy from '@zag-js/anatomy';
 import { CollectionOptions, Collection, CollectionItem } from '@zag-js/collection';
 export { CollectionItem, CollectionOptions } from '@zag-js/collection';
 import { RequiredBy, PropTypes, DirectionProperty, CommonProperties, NormalizeProps } from '@zag-js/types';
 import * as _zag_js_core from '@zag-js/core';
 import { StateMachine } from '@zag-js/core';
-import { InteractOutsideHandlers } from '@zag-js/dismissable';
 import { PositioningOptions } from '@zag-js/popper';
 export { Placement, PositioningOptions } from '@zag-js/popper';
 
-declare const anatomy: _zag_js_anatomy.AnatomyInstance<"root" | "label" | "input" | "positioner" | "control" | "trigger" | "content" | "clearTrigger" | "item" | "itemText" | "itemIndicator" | "itemGroup" | "itemGroupLabel">;
+declare const anatomy: _zag_js_anatomy.AnatomyInstance<"input" | "label" | "content" | "root" | "positioner" | "control" | "trigger" | "clearTrigger" | "item" | "itemText" | "itemIndicator" | "itemGroup" | "itemGroupLabel">;
 
 declare const collection: {
     <T extends unknown>(options: CollectionOptions<T>): Collection<T>;
@@ -24,11 +25,20 @@ interface HighlightChangeDetails<T extends CollectionItem = CollectionItem> {
     highligtedItem: T | null;
 }
 interface InputValueChangeDetails {
-    value: string;
+    inputValue: string;
 }
 interface OpenChangeDetails {
     open: boolean;
 }
+interface SelectionValueDetails<T extends CollectionItem = CollectionItem> {
+    inputValue: string;
+    selectedItems: T[];
+    valueAsString: string;
+}
+interface ScrollToIndexDetails {
+    index: number;
+    immediate?: boolean;
+}
 interface IntlTranslations {
     triggerLabel?: string;
     clearTriggerLabel?: string;
@@ -47,6 +57,14 @@ type ElementIds = Partial<{
     itemGroupLabel(id: string | number): string;
 }>;
 interface PublicContext<T extends CollectionItem = CollectionItem> extends DirectionProperty, CommonProperties, InteractOutsideHandlers {
+    /**
+     * Whether the combobox is open
+     */
+    open?: boolean;
+    /**
+     * Whether the combobox open state is controlled by the user
+     */
+    "open.controlled"?: boolean;
     /**
      * The ids of the elements in the combobox. Useful for composition.
      */
@@ -103,10 +121,6 @@ interface PublicContext<T extends CollectionItem = CollectionItem> extends Direc
      * - `preserve`: The input value is preserved
      */
     selectionBehavior: "clear" | "replace" | "preserve";
-    /**
-     * Whether to select the higlighted item on interaction outside the combobox
-     */
-    selectOnBlur: boolean;
     /**
      * Whether to autofocus the input on mount
      */
@@ -116,13 +130,17 @@ interface PublicContext<T extends CollectionItem = CollectionItem> extends Direc
      */
     openOnClick?: boolean;
     /**
-     * Whether to allow custom values or free values in the input
+     * Whether to show the combobox when the input value changes
+     */
+    openOnChange?: boolean | ((details: InputValueChangeDetails) => boolean);
+    /**
+     * Whether to allow typing custom values in the input
      */
     allowCustomValue?: boolean;
     /**
      * Whether to loop the keyboard navigation through the items
      */
-    loop?: boolean;
+    loopFocus?: boolean;
     /**
      * The positioning options to dynamically position the menu
      */
@@ -160,9 +178,31 @@ interface PublicContext<T extends CollectionItem = CollectionItem> extends Direc
      * Whether to close the combobox when an item is selected.
      */
     closeOnSelect?: boolean;
+    /**
+     * Function to get the display value of the selected item
+     */
+    getSelectionValue?: (details: SelectionValueDetails<T>) => string;
+    /**
+     * Whether to open the combobox on arrow key press
+     */
+    openOnKeyPress: boolean;
+    /**
+     * Function to scroll to a specific index
+     */
+    scrollToIndexFn?: (details: ScrollToIndexDetails) => void;
+    /**
+     * The underling `aria-haspopup` attribute to use for the combobox
+     * - `listbox`: The combobox has a listbox popup (default)
+     * - `dialog`: The combobox has a dialog popup. Useful when in select only mode
+     */
+    popup: "listbox" | "dialog";
+    /**
+     * Whether to register this combobox as a dismissable layer
+     */
+    dismissable: boolean;
 }
 type UserDefinedContext<T extends CollectionItem = CollectionItem> = RequiredBy<PublicContext<T>, "id" | "collection">;
-type ComputedContext<T extends CollectionItem = CollectionItem> = Readonly<{
+type ComputedContext = Readonly<{
     /**
      * @computed
      * Whether the input's value is empty
@@ -181,27 +221,27 @@ type ComputedContext<T extends CollectionItem = CollectionItem> = Readonly<{
      * @computed
      */
     autoHighlight: boolean;
+    /**
+     * @computed
+     * Whether there's a selected option
+     */
+    hasSelectedItems: boolean;
+}>;
+interface PrivateContext<T extends CollectionItem = CollectionItem> {
     /**
      * The highlighted item
      */
     highlightedItem: T | null;
     /**
-     * @computed
+     * @interal
      * The selected items
      */
     selectedItems: T[];
     /**
-     * @computed
-     * Whether there's a selected option
-     */
-    hasSelectedItems: boolean;
-    /**
-     * @computed
+     * @interal
      * The display value of the combobox (based on the selected items)
      */
     valueAsString: string;
-}>;
-interface PrivateContext {
 }
 interface MachineContext extends PublicContext, PrivateContext, ComputedContext {
 }
@@ -212,13 +252,32 @@ interface MachineState {
 type State = StateMachine.State<MachineContext, MachineState>;
 type Send = StateMachine.Send<StateMachine.AnyEventObject>;
 interface ItemProps {
+    /**
+     * Whether hovering outside should clear the highlighted state
+     */
+    persistFocus?: boolean;
+    /**
+     * The item to render
+     */
     item: CollectionItem;
 }
 interface ItemState {
+    /**
+     * The value of the item
+     */
     value: string;
-    isDisabled: boolean;
-    isSelected: boolean;
-    isHighlighted: boolean;
+    /**
+     * Whether the item is disabled
+     */
+    disabled: boolean;
+    /**
+     * Whether the item is selected
+     */
+    selected: boolean;
+    /**
+     * Whether the item is highlighted via pointer or keyboard navigation
+     */
+    highlighted: boolean;
 }
 interface ItemGroupProps {
     id: string;
@@ -230,15 +289,15 @@ interface MachineApi<T extends PropTypes = PropTypes, V extends CollectionItem =
     /**
      * Whether the combobox is focused
      */
-    isFocused: boolean;
+    focused: boolean;
     /**
      * Whether the combobox is open
      */
-    isOpen: boolean;
+    open: boolean;
     /**
      * Whether the combobox input value is empty
      */
-    isInputValueEmpty: boolean;
+    inputEmpty: boolean;
     /**
      * The value of the combobox input
      */
@@ -296,13 +355,9 @@ interface MachineApi<T extends PropTypes = PropTypes, V extends CollectionItem =
      */
     getItemState(props: ItemProps): ItemState;
     /**
-     * Function to open the combobox
-     */
-    open(): void;
-    /**
-     * Function to close the combobox
+     * Function to open or close the combobox
      */
-    close(): void;
+    setOpen(open: boolean): void;
     /**
      * Function to toggle the combobox
      */
@@ -314,7 +369,7 @@ interface MachineApi<T extends PropTypes = PropTypes, V extends CollectionItem =
     /**
      * Function to set the positioning options
      */
-    reposition(options: Partial<PositioningOptions>): void;
+    reposition(options?: Partial<PositioningOptions>): void;
     rootProps: T["element"];
     labelProps: T["label"];
     controlProps: T["element"];
@@ -323,6 +378,7 @@ interface MachineApi<T extends PropTypes = PropTypes, V extends CollectionItem =
     contentProps: T["element"];
     triggerProps: T["button"];
     clearTriggerProps: T["button"];
+    listProps: T["element"];
     getItemProps(props: ItemProps): T["element"];
     getItemTextProps(props: ItemProps): T["element"];
     getItemIndicatorProps(props: ItemProps): T["element"];
@@ -334,4 +390,4 @@ declare function connect<T extends PropTypes, V extends CollectionItem>(state: S
 
 declare function machine<T extends CollectionItem>(userContext: UserDefinedContext<T>): _zag_js_core.Machine<MachineContext, MachineState, _zag_js_core.StateMachine.AnyEventObject>;
 
-export { type MachineApi as Api, type UserDefinedContext as Context, type ElementIds, type HighlightChangeDetails, type InputValueChangeDetails, type ItemGroupLabelProps, type ItemGroupProps, type ItemProps, type ItemState, type OpenChangeDetails, type ValueChangeDetails, anatomy, collection, connect, machine };
+export { type MachineApi as Api, type UserDefinedContext as Context, type ElementIds, type HighlightChangeDetails, type InputValueChangeDetails, type IntlTranslations, type ItemGroupLabelProps, type ItemGroupProps, type ItemProps, type ItemState, type OpenChangeDetails, type ScrollToIndexDetails, type SelectionValueDetails, type ValueChangeDetails, anatomy, collection, connect, machine };