@zag-js/combobox 0.47.0 → 0.48.0

package/src/combobox.props.ts

@@ -6,18 +6,20 @@ export const props = createProps<UserDefinedContext>()([
   "allowCustomValue",
   "autoFocus",
   "closeOnSelect",
+  "collection",
   "dir",
   "disabled",
+  "dismissable",
   "form",
   "getRootNode",
+  "getSelectionValue",
   "highlightedValue",
   "id",
   "ids",
   "inputBehavior",
-  "collection",
   "inputValue",
   "invalid",
-  "loop",
+  "loopFocus",
   "multiple",
   "name",
   "onFocusOutside",
@@ -28,13 +30,18 @@ export const props = createProps<UserDefinedContext>()([
   "onOpenChange",
   "onPointerDownOutside",
   "onValueChange",
+  "open.controlled",
+  "open",
   "openOnClick",
+  "openOnChange",
+  "openOnKeyPress",
   "placeholder",
   "positioning",
   "readOnly",
+  "scrollToIndexFn",
   "selectionBehavior",
-  "selectOnBlur",
   "translations",
+  "popup",
   "value",
 ])
 export const splitProps = createSplitProps<Partial<UserDefinedContext>>(props)
@@ -45,5 +52,5 @@ export const splitItemGroupLabelProps = createSplitProps<ItemGroupLabelProps>(it
 export const itemGroupProps = createProps<ItemGroupProps>()(["id"])
 export const splitItemGroupProps = createSplitProps<ItemGroupProps>(itemGroupProps)
 
-export const itemProps = createProps<ItemProps>()(["item"])
+export const itemProps = createProps<ItemProps>()(["item", "persistFocus"])
 export const splitItemProps = createSplitProps<ItemProps>(itemProps)

package/src/combobox.types.ts

@@ -19,13 +19,24 @@ export interface HighlightChangeDetails<T extends CollectionItem = CollectionIte
 }
 
 export interface InputValueChangeDetails {
-  value: string
+  inputValue: string
 }
 
 export interface OpenChangeDetails {
   open: boolean
 }
 
+export interface SelectionValueDetails<T extends CollectionItem = CollectionItem> {
+  inputValue: string
+  selectedItems: T[]
+  valueAsString: string
+}
+
+export interface ScrollToIndexDetails {
+  index: number
+  immediate?: boolean
+}
+
 /* -----------------------------------------------------------------------------
  * Machine context
  * -----------------------------------------------------------------------------*/
@@ -53,6 +64,14 @@ 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.
    */
@@ -109,10 +128,6 @@ interface PublicContext<T extends CollectionItem = CollectionItem>
    * - `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
    */
@@ -122,13 +137,17 @@ interface PublicContext<T extends CollectionItem = CollectionItem>
    */
   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
    */
@@ -166,6 +185,28 @@ interface PublicContext<T extends CollectionItem = CollectionItem>
    * 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
 }
 
 export type UserDefinedContext<T extends CollectionItem = CollectionItem> = RequiredBy<
@@ -173,7 +214,7 @@ export type UserDefinedContext<T extends CollectionItem = CollectionItem> = Requ
   "id" | "collection"
 >
 
-type ComputedContext<T extends CollectionItem = CollectionItem> = Readonly<{
+type ComputedContext = Readonly<{
   /**
    * @computed
    * Whether the input's value is empty
@@ -192,38 +233,33 @@ type ComputedContext<T extends CollectionItem = CollectionItem> = Readonly<{
    * @computed
    */
   autoHighlight: boolean
-  /**
-   * The highlighted item
-   */
-  highlightedItem: T | null
-  /**
-   * @computed
-   * The selected items
-   */
-  selectedItems: T[]
   /**
    * @computed
    * Whether there's a selected option
    */
   hasSelectedItems: boolean
-  /**
-   * @computed
-   * The display value of the combobox (based on the selected items)
-   */
-  valueAsString: string
 }>
 
-interface PrivateContext {
+interface PrivateContext<T extends CollectionItem = CollectionItem> {
   /**
    * @internal
    * The placement of the combobox popover.
    */
   currentPlacement?: Placement
   /**
-   * @internal
-   * Whether the user is composing text in the input
+   * The highlighted item
+   */
+  highlightedItem: T | null
+  /**
+   * @interal
+   * The selected items
+   */
+  selectedItems: T[]
+  /**
+   * @interal
+   * The display value of the combobox (based on the selected items)
    */
-  composing: boolean
+  valueAsString: string
 }
 
 export interface MachineContext extends PublicContext, PrivateContext, ComputedContext {}
@@ -242,14 +278,33 @@ export type Send = S.Send<S.AnyEventObject>
  * -----------------------------------------------------------------------------*/
 
 export interface ItemProps {
+  /**
+   * Whether hovering outside should clear the highlighted state
+   */
+  persistFocus?: boolean
+  /**
+   * The item to render
+   */
   item: CollectionItem
 }
 
 export 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
 }
 
 export interface ItemGroupProps {
@@ -264,15 +319,15 @@ export interface MachineApi<T extends PropTypes = PropTypes, V extends Collectio
   /**
    * 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
    */
@@ -330,13 +385,9 @@ export interface MachineApi<T extends PropTypes = PropTypes, V extends Collectio
    */
   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
    */
@@ -348,7 +399,7 @@ export interface MachineApi<T extends PropTypes = PropTypes, V extends Collectio
   /**
    * Function to set the positioning options
    */
-  reposition(options: Partial<PositioningOptions>): void
+  reposition(options?: Partial<PositioningOptions>): void
 
   rootProps: T["element"]
   labelProps: T["label"]
@@ -358,6 +409,7 @@ export interface MachineApi<T extends PropTypes = PropTypes, V extends Collectio
   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"]

package/src/index.ts

@@ -17,5 +17,7 @@ export type {
   OpenChangeDetails,
   Placement,
   PositioningOptions,
+  ScrollToIndexDetails,
+  SelectionValueDetails,
   ValueChangeDetails,
 } from "./combobox.types"