@zag-js/combobox 1.18.0 → 1.18.1

package/dist/index.d.mts

@@ -24,11 +24,21 @@ interface HighlightChangeDetails<T extends CollectionItem = CollectionItem> {
     highlightedValue: string | null;
     highlightedItem: T | null;
 }
+/**
+ * The reason for the input value change
+ */
+type InputValueChangeReason = "input-change" | "item-select" | "clear-trigger" | "script" | "interact-outside";
 interface InputValueChangeDetails {
     inputValue: string;
+    reason?: InputValueChangeReason | undefined;
 }
+/**
+ * The reason for the combobox open/close state change
+ */
+type OpenChangeReason = "input-click" | "trigger-click" | "script" | "arrow-key" | "input-change" | "interact-outside" | "escape-key" | "item-select" | "clear-trigger";
 interface OpenChangeDetails {
     open: boolean;
+    reason?: OpenChangeReason | undefined;
 }
 interface ScrollToIndexDetails {
     index: number;
@@ -336,6 +346,10 @@ interface ComboboxApi<T extends PropTypes = PropTypes, V extends CollectionItem
      * The value of the combobox input
      */
     setHighlightValue(value: string): void;
+    /**
+     * Function to clear the highlighted value
+     */
+    clearHighlightValue(): void;
     /**
      * Function to sync the selected items with the value.
      * Useful when `value` is updated from async sources.
@@ -376,7 +390,7 @@ interface ComboboxApi<T extends PropTypes = PropTypes, V extends CollectionItem
     /**
      * Function to set the input value of the combobox
      */
-    setInputValue(value: string): void;
+    setInputValue(value: string, reason?: InputValueChangeReason): void;
     /**
      * Returns the state of a combobox item
      */
@@ -384,7 +398,7 @@ interface ComboboxApi<T extends PropTypes = PropTypes, V extends CollectionItem
     /**
      * Function to open or close the combobox
      */
-    setOpen(open: boolean): void;
+    setOpen(open: boolean, reason?: OpenChangeReason): void;
     /**
      * Function to toggle the combobox
      */
@@ -430,4 +444,4 @@ declare const splitItemGroupProps: <Props extends ItemGroupProps>(props: Props)
 declare const itemProps: (keyof ItemProps)[];
 declare const splitItemProps: <Props extends ItemProps>(props: Props) => [ItemProps, Omit<Props, keyof ItemProps>];
 
-export { type ComboboxApi as Api, type ElementIds, type HighlightChangeDetails, type InputValueChangeDetails, type IntlTranslations, type ItemGroupLabelProps, type ItemGroupProps, type ItemProps, type ItemState, type ComboboxMachine as Machine, type NavigateDetails, type OpenChangeDetails, type ComboboxProps as Props, type ScrollToIndexDetails, type SelectionDetails, type ComboboxService as Service, type TriggerProps, type ValueChangeDetails, anatomy, collection, connect, itemGroupLabelProps, itemGroupProps, itemProps, machine, props, splitItemGroupLabelProps, splitItemGroupProps, splitItemProps, splitProps };
+export { type ComboboxApi as Api, type ElementIds, type HighlightChangeDetails, type InputValueChangeDetails, type InputValueChangeReason, type IntlTranslations, type ItemGroupLabelProps, type ItemGroupProps, type ItemProps, type ItemState, type ComboboxMachine as Machine, type NavigateDetails, type OpenChangeDetails, type OpenChangeReason, type ComboboxProps as Props, type ScrollToIndexDetails, type SelectionDetails, type ComboboxService as Service, type TriggerProps, type ValueChangeDetails, anatomy, collection, connect, itemGroupLabelProps, itemGroupProps, itemProps, machine, props, splitItemGroupLabelProps, splitItemGroupProps, splitItemProps, splitProps };

package/dist/index.d.ts

@@ -24,11 +24,21 @@ interface HighlightChangeDetails<T extends CollectionItem = CollectionItem> {
     highlightedValue: string | null;
     highlightedItem: T | null;
 }
+/**
+ * The reason for the input value change
+ */
+type InputValueChangeReason = "input-change" | "item-select" | "clear-trigger" | "script" | "interact-outside";
 interface InputValueChangeDetails {
     inputValue: string;
+    reason?: InputValueChangeReason | undefined;
 }
+/**
+ * The reason for the combobox open/close state change
+ */
+type OpenChangeReason = "input-click" | "trigger-click" | "script" | "arrow-key" | "input-change" | "interact-outside" | "escape-key" | "item-select" | "clear-trigger";
 interface OpenChangeDetails {
     open: boolean;
+    reason?: OpenChangeReason | undefined;
 }
 interface ScrollToIndexDetails {
     index: number;
@@ -336,6 +346,10 @@ interface ComboboxApi<T extends PropTypes = PropTypes, V extends CollectionItem
      * The value of the combobox input
      */
     setHighlightValue(value: string): void;
+    /**
+     * Function to clear the highlighted value
+     */
+    clearHighlightValue(): void;
     /**
      * Function to sync the selected items with the value.
      * Useful when `value` is updated from async sources.
@@ -376,7 +390,7 @@ interface ComboboxApi<T extends PropTypes = PropTypes, V extends CollectionItem
     /**
      * Function to set the input value of the combobox
      */
-    setInputValue(value: string): void;
+    setInputValue(value: string, reason?: InputValueChangeReason): void;
     /**
      * Returns the state of a combobox item
      */
@@ -384,7 +398,7 @@ interface ComboboxApi<T extends PropTypes = PropTypes, V extends CollectionItem
     /**
      * Function to open or close the combobox
      */
-    setOpen(open: boolean): void;
+    setOpen(open: boolean, reason?: OpenChangeReason): void;
     /**
      * Function to toggle the combobox
      */
@@ -430,4 +444,4 @@ declare const splitItemGroupProps: <Props extends ItemGroupProps>(props: Props)
 declare const itemProps: (keyof ItemProps)[];
 declare const splitItemProps: <Props extends ItemProps>(props: Props) => [ItemProps, Omit<Props, keyof ItemProps>];
 
-export { type ComboboxApi as Api, type ElementIds, type HighlightChangeDetails, type InputValueChangeDetails, type IntlTranslations, type ItemGroupLabelProps, type ItemGroupProps, type ItemProps, type ItemState, type ComboboxMachine as Machine, type NavigateDetails, type OpenChangeDetails, type ComboboxProps as Props, type ScrollToIndexDetails, type SelectionDetails, type ComboboxService as Service, type TriggerProps, type ValueChangeDetails, anatomy, collection, connect, itemGroupLabelProps, itemGroupProps, itemProps, machine, props, splitItemGroupLabelProps, splitItemGroupProps, splitItemProps, splitProps };
+export { type ComboboxApi as Api, type ElementIds, type HighlightChangeDetails, type InputValueChangeDetails, type InputValueChangeReason, type IntlTranslations, type ItemGroupLabelProps, type ItemGroupProps, type ItemProps, type ItemState, type ComboboxMachine as Machine, type NavigateDetails, type OpenChangeDetails, type OpenChangeReason, type ComboboxProps as Props, type ScrollToIndexDetails, type SelectionDetails, type ComboboxService as Service, type TriggerProps, type ValueChangeDetails, anatomy, collection, connect, itemGroupLabelProps, itemGroupProps, itemProps, machine, props, splitItemGroupLabelProps, splitItemGroupProps, splitItemProps, splitProps };

package/dist/index.js

@@ -117,14 +117,17 @@ function connect(service, normalize) {
     setHighlightValue(value) {
       send({ type: "HIGHLIGHTED_VALUE.SET", value });
     },
+    clearHighlightValue() {
+      send({ type: "HIGHLIGHTED_VALUE.CLEAR" });
+    },
     selectValue(value) {
       send({ type: "ITEM.SELECT", value });
     },
     setValue(value) {
       send({ type: "VALUE.SET", value });
     },
-    setInputValue(value) {
-      send({ type: "INPUT_VALUE.SET", value });
+    setInputValue(value, reason = "script") {
+      send({ type: "INPUT_VALUE.SET", value, src: reason });
     },
     clearValue(value) {
       if (value != null) {
@@ -136,10 +139,10 @@ function connect(service, normalize) {
     focus() {
       getInputEl(scope)?.focus();
     },
-    setOpen(nextOpen) {
+    setOpen(nextOpen, reason = "script") {
       const open2 = state.hasTag("open");
       if (open2 === nextOpen) return;
-      send({ type: nextOpen ? "OPEN" : "CLOSE" });
+      send({ type: nextOpen ? "OPEN" : "CLOSE", src: reason });
     },
     getRootProps() {
       return normalize.element({
@@ -216,7 +219,7 @@ function connect(service, normalize) {
           if (event2.defaultPrevented) return;
           if (!prop("openOnClick")) return;
           if (!interactive) return;
-          send({ type: "INPUT.CLICK" });
+          send({ type: "INPUT.CLICK", src: "input-click" });
         },
         onFocus() {
           if (disabled) return;
@@ -227,7 +230,7 @@ function connect(service, normalize) {
           send({ type: "INPUT.BLUR" });
         },
         onChange(event2) {
-          send({ type: "INPUT.CHANGE", value: event2.currentTarget.value });
+          send({ type: "INPUT.CHANGE", value: event2.currentTarget.value, src: "input-change" });
         },
         onKeyDown(event2) {
           if (event2.defaultPrevented) return;
@@ -239,12 +242,12 @@ function connect(service, normalize) {
           const keymap = {
             ArrowDown(event3) {
               if (!openOnKeyPress && !open) return;
-              send({ type: event3.altKey ? "OPEN" : "INPUT.ARROW_DOWN", keypress });
+              send({ type: event3.altKey ? "OPEN" : "INPUT.ARROW_DOWN", keypress, src: "arrow-key" });
               event3.preventDefault();
             },
             ArrowUp() {
               if (!openOnKeyPress && !open) return;
-              send({ type: event2.altKey ? "CLOSE" : "INPUT.ARROW_UP", keypress });
+              send({ type: event2.altKey ? "CLOSE" : "INPUT.ARROW_UP", keypress, src: "arrow-key" });
               event2.preventDefault();
             },
             Home(event3) {
@@ -262,7 +265,7 @@ function connect(service, normalize) {
               }
             },
             Enter(event3) {
-              send({ type: "INPUT.ENTER", keypress });
+              send({ type: "INPUT.ENTER", keypress, src: "item-select" });
               const submittable = computed("isCustomValue") && prop("allowCustomValue");
               if (open && !submittable) {
                 event3.preventDefault();
@@ -274,7 +277,7 @@ function connect(service, normalize) {
               }
             },
             Escape() {
-              send({ type: "INPUT.ESCAPE", keypress });
+              send({ type: "INPUT.ESCAPE", keypress, src: "escape-key" });
               event2.preventDefault();
             }
           };
@@ -309,7 +312,7 @@ function connect(service, normalize) {
           if (event2.defaultPrevented) return;
           if (!interactive) return;
           if (!domQuery.isLeftClick(event2)) return;
-          send({ type: "TRIGGER.CLICK" });
+          send({ type: "TRIGGER.CLICK", src: "trigger-click" });
         },
         onPointerDown(event2) {
           if (!interactive) return;
@@ -325,10 +328,10 @@ function connect(service, normalize) {
           if (composite) return;
           const keyMap = {
             ArrowDown() {
-              send({ type: "INPUT.ARROW_DOWN", src: "trigger" });
+              send({ type: "INPUT.ARROW_DOWN", src: "arrow-key" });
             },
             ArrowUp() {
-              send({ type: "INPUT.ARROW_UP", src: "trigger" });
+              send({ type: "INPUT.ARROW_UP", src: "arrow-key" });
             }
           };
           const key = domQuery.getEventKey(event2, { dir: prop("dir") });
@@ -425,7 +428,7 @@ function connect(service, normalize) {
           if (domQuery.isOpeningInNewTab(event2)) return;
           if (domQuery.isContextMenuEvent(event2)) return;
           if (itemState.disabled) return;
-          send({ type: "ITEM.CLICK", src: "click", value });
+          send({ type: "ITEM.CLICK", src: "item-select", value });
         }
       });
     },
@@ -507,7 +510,7 @@ var machine = createMachine({
     const open = prop("open") || prop("defaultOpen");
     return open ? "suggesting" : "idle";
   },
-  context({ prop, bindable, getContext }) {
+  context({ prop, bindable, getContext, getEvent }) {
     return {
       currentPlacement: bindable(() => ({
         defaultValue: void 0
@@ -554,7 +557,9 @@ var machine = createMachine({
           defaultValue: inputValue,
           value: prop("inputValue"),
           onChange(value2) {
-            prop("onInputValueChange")?.({ inputValue: value2 });
+            const event = getEvent();
+            const reason = (event.previousEvent || event).src;
+            prop("onInputValueChange")?.({ inputValue: value2, reason });
           }
         };
       }),
@@ -579,7 +584,7 @@ var machine = createMachine({
     valueAsString: ({ context, prop }) => prop("collection").stringifyItems(context.get("selectedItems")),
     isCustomValue: ({ context, computed }) => context.get("inputValue") !== computed("valueAsString")
   },
-  watch({ context, prop, track, action }) {
+  watch({ context, prop, track, action, send }) {
     track([() => context.hash("value")], () => {
       action(["syncSelectedItems"]);
     });
@@ -592,13 +597,19 @@ var machine = createMachine({
     track([() => prop("open")], () => {
       action(["toggleVisibility"]);
     });
+    track([() => prop("collection").toString()], () => {
+      send({ type: "CHILDREN_CHANGE" });
+    });
   },
   on: {
     "SELECTED_ITEMS.SYNC": {
       actions: ["syncSelectedItems"]
     },
     "HIGHLIGHTED_VALUE.SET": {
-      actions: ["setHighlightedItem"]
+      actions: ["setHighlightedValue"]
+    },
+    "HIGHLIGHTED_VALUE.CLEAR": {
+      actions: ["clearHighlightedValue"]
     },
     "ITEM.SELECT": {
       actions: ["selectItem"]
@@ -625,7 +636,7 @@ var machine = createMachine({
   states: {
     idle: {
       tags: ["idle", "closed"],
-      entry: ["scrollContentToTop", "clearHighlightedItem"],
+      entry: ["scrollContentToTop", "clearHighlightedValue"],
       on: {
         "CONTROLLED.OPEN": {
           target: "interacting"
@@ -671,7 +682,7 @@ var machine = createMachine({
     },
     focused: {
       tags: ["focused", "closed"],
-      entry: ["scrollContentToTop", "clearHighlightedItem"],
+      entry: ["scrollContentToTop", "clearHighlightedValue"],
       on: {
         "CONTROLLED.OPEN": [
           {
@@ -799,6 +810,15 @@ var machine = createMachine({
             target: "idle"
           }
         ],
+        CHILDREN_CHANGE: [
+          {
+            guard: "isHighlightedItemRemoved",
+            actions: ["clearHighlightedValue"]
+          },
+          {
+            actions: ["scrollToHighlightedItem"]
+          }
+        ],
         "INPUT.HOME": {
           actions: ["highlightFirstItem"]
         },
@@ -808,7 +828,7 @@ var machine = createMachine({
         "INPUT.ARROW_DOWN": [
           {
             guard: and("autoComplete", "isLastItemHighlighted"),
-            actions: ["clearHighlightedItem", "scrollContentToTop"]
+            actions: ["clearHighlightedValue", "scrollContentToTop"]
           },
           {
             actions: ["highlightNextItem"]
@@ -817,7 +837,7 @@ var machine = createMachine({
         "INPUT.ARROW_UP": [
           {
             guard: and("autoComplete", "isFirstItemHighlighted"),
-            actions: ["clearHighlightedItem"]
+            actions: ["clearHighlightedValue"]
           },
           {
             actions: ["highlightPrevItem"]
@@ -856,14 +876,14 @@ var machine = createMachine({
           },
           {
             target: "suggesting",
-            actions: ["clearHighlightedItem", "setInputValue"]
+            actions: ["clearHighlightedValue", "setInputValue"]
           }
         ],
         "ITEM.POINTER_MOVE": {
-          actions: ["setHighlightedItem"]
+          actions: ["setHighlightedValue"]
         },
         "ITEM.POINTER_LEAVE": {
-          actions: ["clearHighlightedItem"]
+          actions: ["clearHighlightedValue"]
         },
         "ITEM.CLICK": [
           {
@@ -953,13 +973,7 @@ var machine = createMachine({
     },
     suggesting: {
       tags: ["open", "focused"],
-      effects: [
-        "trackDismissableLayer",
-        "scrollToHighlightedItem",
-        "trackPlacement",
-        "trackChildNodes",
-        "hideOtherElements"
-      ],
+      effects: ["trackDismissableLayer", "scrollToHighlightedItem", "trackPlacement", "hideOtherElements"],
       entry: ["setInitialFocus"],
       on: {
         "CONTROLLED.CLOSE": [
@@ -972,10 +986,16 @@ var machine = createMachine({
             target: "idle"
           }
         ],
-        CHILDREN_CHANGE: {
-          guard: "autoHighlight",
-          actions: ["highlightFirstItem"]
-        },
+        CHILDREN_CHANGE: [
+          {
+            guard: "autoHighlight",
+            actions: ["highlightFirstItem"]
+          },
+          {
+            guard: "isHighlightedItemRemoved",
+            actions: ["clearHighlightedValue"]
+          }
+        ],
         "INPUT.ARROW_DOWN": {
           target: "interacting",
           actions: ["highlightNextItem"]
@@ -1032,10 +1052,10 @@ var machine = createMachine({
         ],
         "ITEM.POINTER_MOVE": {
           target: "interacting",
-          actions: ["setHighlightedItem"]
+          actions: ["setHighlightedValue"]
         },
         "ITEM.POINTER_LEAVE": {
-          actions: ["clearHighlightedItem"]
+          actions: ["clearHighlightedValue"]
         },
         "LAYER.INTERACT_OUTSIDE": [
           // == group 1 ==
@@ -1124,7 +1144,8 @@ var machine = createMachine({
       },
       restoreFocus: ({ event }) => event.restoreFocus == null ? true : !!event.restoreFocus,
       isChangeEvent: ({ event }) => event.previousEvent?.type === "INPUT.CHANGE",
-      autoFocus: ({ prop }) => !!prop("autoFocus")
+      autoFocus: ({ prop }) => !!prop("autoFocus"),
+      isHighlightedItemRemoved: ({ prop, context }) => !prop("collection").has(context.get("highlightedValue"))
     },
     effects: {
       trackDismissableLayer({ send, prop, scope }) {
@@ -1139,10 +1160,10 @@ var machine = createMachine({
           onEscapeKeyDown(event) {
             event.preventDefault();
             event.stopPropagation();
-            send({ type: "LAYER.ESCAPE" });
+            send({ type: "LAYER.ESCAPE", src: "escape-key" });
           },
           onDismiss() {
-            send({ type: "LAYER.INTERACT_OUTSIDE", restoreFocus: false });
+            send({ type: "LAYER.INTERACT_OUTSIDE", src: "interact-outside", restoreFocus: false });
           }
         });
       },
@@ -1166,16 +1187,6 @@ var machine = createMachine({
           }
         });
       },
-      // in event the options are fetched (async), we still want to auto-highlight the first option
-      trackChildNodes({ scope, computed, send }) {
-        if (!computed("autoHighlight")) return;
-        const exec = () => send({ type: "CHILDREN_CHANGE" });
-        const contentEl = () => getContentEl(scope);
-        return domQuery.observeChildren(contentEl, {
-          callback: exec,
-          defer: true
-        });
-      },
       scrollToHighlightedItem({ context, prop, scope, event }) {
         const inputEl = getInputEl(scope);
         let cleanups = [];
@@ -1222,23 +1233,42 @@ var machine = createMachine({
           }
         });
       },
-      setHighlightedItem(params) {
-        const { context, event } = params;
+      setHighlightedValue({ context, event }) {
         if (event.value == null) return;
         context.set("highlightedValue", event.value);
       },
-      clearHighlightedItem(params) {
-        const { context } = params;
+      clearHighlightedValue({ context }) {
         context.set("highlightedValue", null);
       },
       selectHighlightedItem(params) {
         const { context, prop } = params;
+        const collection2 = prop("collection");
         const highlightedValue = context.get("highlightedValue");
-        if (!highlightedValue) return;
+        if (!highlightedValue || !collection2.has(highlightedValue)) return;
         const nextValue = prop("multiple") ? utils.addOrRemove(context.get("value"), highlightedValue) : [highlightedValue];
         prop("onSelect")?.({ value: nextValue, itemValue: highlightedValue });
         context.set("value", nextValue);
-        context.set("inputValue", getInputValue(params));
+        const inputValue = utils.match(prop("selectionBehavior"), {
+          preserve: context.get("inputValue"),
+          replace: collection2.stringifyMany(nextValue),
+          clear: ""
+        });
+        context.set("inputValue", inputValue);
+      },
+      scrollToHighlightedItem({ context, prop, scope }) {
+        domQuery.nextTick(() => {
+          const highlightedValue = context.get("highlightedValue");
+          if (highlightedValue == null) return;
+          const itemEl = getItemEl(scope, highlightedValue);
+          const contentEl = getContentEl(scope);
+          const scrollToIndexFn = prop("scrollToIndexFn");
+          if (scrollToIndexFn) {
+            const highlightedIndex = prop("collection").indexOf(highlightedValue);
+            scrollToIndexFn({ index: highlightedIndex, immediate: true });
+            return;
+          }
+          domQuery.scrollIntoView(itemEl, { rootEl: contentEl, block: "nearest" });
+        });
       },
       selectItem(params) {
         const { context, event, flush, prop } = params;
@@ -1247,16 +1277,26 @@ var machine = createMachine({
           const nextValue = prop("multiple") ? utils.addOrRemove(context.get("value"), event.value) : [event.value];
           prop("onSelect")?.({ value: nextValue, itemValue: event.value });
           context.set("value", nextValue);
-          context.set("inputValue", getInputValue(params));
+          const inputValue = utils.match(prop("selectionBehavior"), {
+            preserve: context.get("inputValue"),
+            replace: prop("collection").stringifyMany(nextValue),
+            clear: ""
+          });
+          context.set("inputValue", inputValue);
         });
       },
       clearItem(params) {
-        const { context, event, flush } = params;
+        const { context, event, flush, prop } = params;
         if (event.value == null) return;
         flush(() => {
           const nextValue = utils.remove(context.get("value"), event.value);
           context.set("value", nextValue);
-          context.set("inputValue", getInputValue(params));
+          const inputValue = utils.match(prop("selectionBehavior"), {
+            preserve: context.get("inputValue"),
+            replace: prop("collection").stringifyMany(nextValue),
+            clear: ""
+          });
+          context.set("inputValue", inputValue);
         });
       },
       setInitialFocus({ scope }) {
@@ -1299,17 +1339,27 @@ var machine = createMachine({
         context.set("inputValue", inputValue);
       },
       setValue(params) {
-        const { context, flush, event } = params;
+        const { context, flush, event, prop } = params;
         flush(() => {
           context.set("value", event.value);
-          context.set("inputValue", getInputValue(params));
+          const inputValue = utils.match(prop("selectionBehavior"), {
+            preserve: context.get("inputValue"),
+            replace: prop("collection").stringifyMany(event.value),
+            clear: ""
+          });
+          context.set("inputValue", inputValue);
         });
       },
       clearSelectedItems(params) {
-        const { context, flush } = params;
+        const { context, flush, prop } = params;
         flush(() => {
           context.set("value", []);
-          context.set("inputValue", getInputValue(params));
+          const inputValue = utils.match(prop("selectionBehavior"), {
+            preserve: context.get("inputValue"),
+            replace: prop("collection").stringifyMany([]),
+            clear: ""
+          });
+          context.set("inputValue", inputValue);
         });
       },
       scrollContentToTop({ prop, scope }) {
@@ -1322,11 +1372,13 @@ var machine = createMachine({
           contentEl.scrollTop = 0;
         }
       },
-      invokeOnOpen({ prop }) {
-        prop("onOpenChange")?.({ open: true });
+      invokeOnOpen({ prop, event }) {
+        const reason = getOpenChangeReason(event);
+        prop("onOpenChange")?.({ open: true, reason });
       },
-      invokeOnClose({ prop }) {
-        prop("onOpenChange")?.({ open: false });
+      invokeOnClose({ prop, event }) {
+        const reason = getOpenChangeReason(event);
+        prop("onOpenChange")?.({ open: false, reason });
       },
       highlightFirstItem({ context, prop, scope }) {
         const exec = getContentEl(scope) ? queueMicrotask : domQuery.raf;
@@ -1411,12 +1463,18 @@ var machine = createMachine({
       syncSelectedItems(params) {
         queueMicrotask(() => {
           const { context, prop } = params;
+          const collection2 = prop("collection");
+          const value = context.get("value");
+          const selectedItems = value.map((v) => {
+            const item = context.get("selectedItems").find((item2) => collection2.getItemValue(item2) === v);
+            return item || collection2.find(v);
+          });
+          context.set("selectedItems", selectedItems);
           const inputValue = utils.match(prop("selectionBehavior"), {
             preserve: context.get("inputValue"),
-            replace: prop("collection").stringifyMany(context.get("value")),
+            replace: collection2.stringifyMany(value),
             clear: ""
           });
-          context.set("selectedItems", getSelectedItems(params));
           context.set("inputValue", inputValue);
         });
       },
@@ -1430,20 +1488,8 @@ var machine = createMachine({
     }
   }
 });
-function getInputValue({ context, prop, computed }) {
-  return utils.match(prop("selectionBehavior"), {
-    preserve: context.get("inputValue"),
-    replace: computed("valueAsString"),
-    clear: ""
-  });
-}
-function getSelectedItems({ context, prop }) {
-  const collection2 = prop("collection");
-  return context.get("value").map((v) => {
-    const foundItem = context.get("selectedItems").find((item) => collection2.getItemValue(item) === v);
-    if (foundItem) return foundItem;
-    return collection2.find(v);
-  });
+function getOpenChangeReason(event) {
+  return (event.previousEvent || event).src;
 }
 var props = types.createProps()([
   "allowCustomValue",

package/dist/index.mjs

@@ -1,6 +1,6 @@
 import { createAnatomy } from '@zag-js/anatomy';
 import { ListCollection } from '@zag-js/collection';
-import { raf, setCaretToEnd, observeAttributes, observeChildren, clickIfLink, scrollIntoView, query, dataAttr, ariaAttr, isDownloadingEvent, isOpeningInNewTab, isContextMenuEvent, isLeftClick, getEventKey, isComposingEvent, isAnchorElement } from '@zag-js/dom-query';
+import { raf, setCaretToEnd, nextTick, scrollIntoView, observeAttributes, clickIfLink, query, dataAttr, ariaAttr, isDownloadingEvent, isOpeningInNewTab, isContextMenuEvent, isLeftClick, getEventKey, isComposingEvent, isAnchorElement } from '@zag-js/dom-query';
 import { getPlacement, getPlacementStyles } from '@zag-js/popper';
 import { match, remove, addOrRemove, isBoolean, isEqual, createSplitProps, ensure } from '@zag-js/utils';
 import { ariaHidden } from '@zag-js/aria-hidden';
@@ -115,14 +115,17 @@ function connect(service, normalize) {
     setHighlightValue(value) {
       send({ type: "HIGHLIGHTED_VALUE.SET", value });
     },
+    clearHighlightValue() {
+      send({ type: "HIGHLIGHTED_VALUE.CLEAR" });
+    },
     selectValue(value) {
       send({ type: "ITEM.SELECT", value });
     },
     setValue(value) {
       send({ type: "VALUE.SET", value });
     },
-    setInputValue(value) {
-      send({ type: "INPUT_VALUE.SET", value });
+    setInputValue(value, reason = "script") {
+      send({ type: "INPUT_VALUE.SET", value, src: reason });
     },
     clearValue(value) {
       if (value != null) {
@@ -134,10 +137,10 @@ function connect(service, normalize) {
     focus() {
       getInputEl(scope)?.focus();
     },
-    setOpen(nextOpen) {
+    setOpen(nextOpen, reason = "script") {
       const open2 = state.hasTag("open");
       if (open2 === nextOpen) return;
-      send({ type: nextOpen ? "OPEN" : "CLOSE" });
+      send({ type: nextOpen ? "OPEN" : "CLOSE", src: reason });
     },
     getRootProps() {
       return normalize.element({
@@ -214,7 +217,7 @@ function connect(service, normalize) {
           if (event2.defaultPrevented) return;
           if (!prop("openOnClick")) return;
           if (!interactive) return;
-          send({ type: "INPUT.CLICK" });
+          send({ type: "INPUT.CLICK", src: "input-click" });
         },
         onFocus() {
           if (disabled) return;
@@ -225,7 +228,7 @@ function connect(service, normalize) {
           send({ type: "INPUT.BLUR" });
         },
         onChange(event2) {
-          send({ type: "INPUT.CHANGE", value: event2.currentTarget.value });
+          send({ type: "INPUT.CHANGE", value: event2.currentTarget.value, src: "input-change" });
         },
         onKeyDown(event2) {
           if (event2.defaultPrevented) return;
@@ -237,12 +240,12 @@ function connect(service, normalize) {
           const keymap = {
             ArrowDown(event3) {
               if (!openOnKeyPress && !open) return;
-              send({ type: event3.altKey ? "OPEN" : "INPUT.ARROW_DOWN", keypress });
+              send({ type: event3.altKey ? "OPEN" : "INPUT.ARROW_DOWN", keypress, src: "arrow-key" });
               event3.preventDefault();
             },
             ArrowUp() {
               if (!openOnKeyPress && !open) return;
-              send({ type: event2.altKey ? "CLOSE" : "INPUT.ARROW_UP", keypress });
+              send({ type: event2.altKey ? "CLOSE" : "INPUT.ARROW_UP", keypress, src: "arrow-key" });
               event2.preventDefault();
             },
             Home(event3) {
@@ -260,7 +263,7 @@ function connect(service, normalize) {
               }
             },
             Enter(event3) {
-              send({ type: "INPUT.ENTER", keypress });
+              send({ type: "INPUT.ENTER", keypress, src: "item-select" });
               const submittable = computed("isCustomValue") && prop("allowCustomValue");
               if (open && !submittable) {
                 event3.preventDefault();
@@ -272,7 +275,7 @@ function connect(service, normalize) {
               }
             },
             Escape() {
-              send({ type: "INPUT.ESCAPE", keypress });
+              send({ type: "INPUT.ESCAPE", keypress, src: "escape-key" });
               event2.preventDefault();
             }
           };
@@ -307,7 +310,7 @@ function connect(service, normalize) {
           if (event2.defaultPrevented) return;
           if (!interactive) return;
           if (!isLeftClick(event2)) return;
-          send({ type: "TRIGGER.CLICK" });
+          send({ type: "TRIGGER.CLICK", src: "trigger-click" });
         },
         onPointerDown(event2) {
           if (!interactive) return;
@@ -323,10 +326,10 @@ function connect(service, normalize) {
           if (composite) return;
           const keyMap = {
             ArrowDown() {
-              send({ type: "INPUT.ARROW_DOWN", src: "trigger" });
+              send({ type: "INPUT.ARROW_DOWN", src: "arrow-key" });
             },
             ArrowUp() {
-              send({ type: "INPUT.ARROW_UP", src: "trigger" });
+              send({ type: "INPUT.ARROW_UP", src: "arrow-key" });
             }
           };
           const key = getEventKey(event2, { dir: prop("dir") });
@@ -423,7 +426,7 @@ function connect(service, normalize) {
           if (isOpeningInNewTab(event2)) return;
           if (isContextMenuEvent(event2)) return;
           if (itemState.disabled) return;
-          send({ type: "ITEM.CLICK", src: "click", value });
+          send({ type: "ITEM.CLICK", src: "item-select", value });
         }
       });
     },
@@ -505,7 +508,7 @@ var machine = createMachine({
     const open = prop("open") || prop("defaultOpen");
     return open ? "suggesting" : "idle";
   },
-  context({ prop, bindable, getContext }) {
+  context({ prop, bindable, getContext, getEvent }) {
     return {
       currentPlacement: bindable(() => ({
         defaultValue: void 0
@@ -552,7 +555,9 @@ var machine = createMachine({
           defaultValue: inputValue,
           value: prop("inputValue"),
           onChange(value2) {
-            prop("onInputValueChange")?.({ inputValue: value2 });
+            const event = getEvent();
+            const reason = (event.previousEvent || event).src;
+            prop("onInputValueChange")?.({ inputValue: value2, reason });
           }
         };
       }),
@@ -577,7 +582,7 @@ var machine = createMachine({
     valueAsString: ({ context, prop }) => prop("collection").stringifyItems(context.get("selectedItems")),
     isCustomValue: ({ context, computed }) => context.get("inputValue") !== computed("valueAsString")
   },
-  watch({ context, prop, track, action }) {
+  watch({ context, prop, track, action, send }) {
     track([() => context.hash("value")], () => {
       action(["syncSelectedItems"]);
     });
@@ -590,13 +595,19 @@ var machine = createMachine({
     track([() => prop("open")], () => {
       action(["toggleVisibility"]);
     });
+    track([() => prop("collection").toString()], () => {
+      send({ type: "CHILDREN_CHANGE" });
+    });
   },
   on: {
     "SELECTED_ITEMS.SYNC": {
       actions: ["syncSelectedItems"]
     },
     "HIGHLIGHTED_VALUE.SET": {
-      actions: ["setHighlightedItem"]
+      actions: ["setHighlightedValue"]
+    },
+    "HIGHLIGHTED_VALUE.CLEAR": {
+      actions: ["clearHighlightedValue"]
     },
     "ITEM.SELECT": {
       actions: ["selectItem"]
@@ -623,7 +634,7 @@ var machine = createMachine({
   states: {
     idle: {
       tags: ["idle", "closed"],
-      entry: ["scrollContentToTop", "clearHighlightedItem"],
+      entry: ["scrollContentToTop", "clearHighlightedValue"],
       on: {
         "CONTROLLED.OPEN": {
           target: "interacting"
@@ -669,7 +680,7 @@ var machine = createMachine({
     },
     focused: {
       tags: ["focused", "closed"],
-      entry: ["scrollContentToTop", "clearHighlightedItem"],
+      entry: ["scrollContentToTop", "clearHighlightedValue"],
       on: {
         "CONTROLLED.OPEN": [
           {
@@ -797,6 +808,15 @@ var machine = createMachine({
             target: "idle"
           }
         ],
+        CHILDREN_CHANGE: [
+          {
+            guard: "isHighlightedItemRemoved",
+            actions: ["clearHighlightedValue"]
+          },
+          {
+            actions: ["scrollToHighlightedItem"]
+          }
+        ],
         "INPUT.HOME": {
           actions: ["highlightFirstItem"]
         },
@@ -806,7 +826,7 @@ var machine = createMachine({
         "INPUT.ARROW_DOWN": [
           {
             guard: and("autoComplete", "isLastItemHighlighted"),
-            actions: ["clearHighlightedItem", "scrollContentToTop"]
+            actions: ["clearHighlightedValue", "scrollContentToTop"]
           },
           {
             actions: ["highlightNextItem"]
@@ -815,7 +835,7 @@ var machine = createMachine({
         "INPUT.ARROW_UP": [
           {
             guard: and("autoComplete", "isFirstItemHighlighted"),
-            actions: ["clearHighlightedItem"]
+            actions: ["clearHighlightedValue"]
           },
           {
             actions: ["highlightPrevItem"]
@@ -854,14 +874,14 @@ var machine = createMachine({
           },
           {
             target: "suggesting",
-            actions: ["clearHighlightedItem", "setInputValue"]
+            actions: ["clearHighlightedValue", "setInputValue"]
           }
         ],
         "ITEM.POINTER_MOVE": {
-          actions: ["setHighlightedItem"]
+          actions: ["setHighlightedValue"]
         },
         "ITEM.POINTER_LEAVE": {
-          actions: ["clearHighlightedItem"]
+          actions: ["clearHighlightedValue"]
         },
         "ITEM.CLICK": [
           {
@@ -951,13 +971,7 @@ var machine = createMachine({
     },
     suggesting: {
       tags: ["open", "focused"],
-      effects: [
-        "trackDismissableLayer",
-        "scrollToHighlightedItem",
-        "trackPlacement",
-        "trackChildNodes",
-        "hideOtherElements"
-      ],
+      effects: ["trackDismissableLayer", "scrollToHighlightedItem", "trackPlacement", "hideOtherElements"],
       entry: ["setInitialFocus"],
       on: {
         "CONTROLLED.CLOSE": [
@@ -970,10 +984,16 @@ var machine = createMachine({
             target: "idle"
           }
         ],
-        CHILDREN_CHANGE: {
-          guard: "autoHighlight",
-          actions: ["highlightFirstItem"]
-        },
+        CHILDREN_CHANGE: [
+          {
+            guard: "autoHighlight",
+            actions: ["highlightFirstItem"]
+          },
+          {
+            guard: "isHighlightedItemRemoved",
+            actions: ["clearHighlightedValue"]
+          }
+        ],
         "INPUT.ARROW_DOWN": {
           target: "interacting",
           actions: ["highlightNextItem"]
@@ -1030,10 +1050,10 @@ var machine = createMachine({
         ],
         "ITEM.POINTER_MOVE": {
           target: "interacting",
-          actions: ["setHighlightedItem"]
+          actions: ["setHighlightedValue"]
         },
         "ITEM.POINTER_LEAVE": {
-          actions: ["clearHighlightedItem"]
+          actions: ["clearHighlightedValue"]
         },
         "LAYER.INTERACT_OUTSIDE": [
           // == group 1 ==
@@ -1122,7 +1142,8 @@ var machine = createMachine({
       },
       restoreFocus: ({ event }) => event.restoreFocus == null ? true : !!event.restoreFocus,
       isChangeEvent: ({ event }) => event.previousEvent?.type === "INPUT.CHANGE",
-      autoFocus: ({ prop }) => !!prop("autoFocus")
+      autoFocus: ({ prop }) => !!prop("autoFocus"),
+      isHighlightedItemRemoved: ({ prop, context }) => !prop("collection").has(context.get("highlightedValue"))
     },
     effects: {
       trackDismissableLayer({ send, prop, scope }) {
@@ -1137,10 +1158,10 @@ var machine = createMachine({
           onEscapeKeyDown(event) {
             event.preventDefault();
             event.stopPropagation();
-            send({ type: "LAYER.ESCAPE" });
+            send({ type: "LAYER.ESCAPE", src: "escape-key" });
           },
           onDismiss() {
-            send({ type: "LAYER.INTERACT_OUTSIDE", restoreFocus: false });
+            send({ type: "LAYER.INTERACT_OUTSIDE", src: "interact-outside", restoreFocus: false });
           }
         });
       },
@@ -1164,16 +1185,6 @@ var machine = createMachine({
           }
         });
       },
-      // in event the options are fetched (async), we still want to auto-highlight the first option
-      trackChildNodes({ scope, computed, send }) {
-        if (!computed("autoHighlight")) return;
-        const exec = () => send({ type: "CHILDREN_CHANGE" });
-        const contentEl = () => getContentEl(scope);
-        return observeChildren(contentEl, {
-          callback: exec,
-          defer: true
-        });
-      },
       scrollToHighlightedItem({ context, prop, scope, event }) {
         const inputEl = getInputEl(scope);
         let cleanups = [];
@@ -1220,23 +1231,42 @@ var machine = createMachine({
           }
         });
       },
-      setHighlightedItem(params) {
-        const { context, event } = params;
+      setHighlightedValue({ context, event }) {
         if (event.value == null) return;
         context.set("highlightedValue", event.value);
       },
-      clearHighlightedItem(params) {
-        const { context } = params;
+      clearHighlightedValue({ context }) {
         context.set("highlightedValue", null);
       },
       selectHighlightedItem(params) {
         const { context, prop } = params;
+        const collection2 = prop("collection");
         const highlightedValue = context.get("highlightedValue");
-        if (!highlightedValue) return;
+        if (!highlightedValue || !collection2.has(highlightedValue)) return;
         const nextValue = prop("multiple") ? addOrRemove(context.get("value"), highlightedValue) : [highlightedValue];
         prop("onSelect")?.({ value: nextValue, itemValue: highlightedValue });
         context.set("value", nextValue);
-        context.set("inputValue", getInputValue(params));
+        const inputValue = match(prop("selectionBehavior"), {
+          preserve: context.get("inputValue"),
+          replace: collection2.stringifyMany(nextValue),
+          clear: ""
+        });
+        context.set("inputValue", inputValue);
+      },
+      scrollToHighlightedItem({ context, prop, scope }) {
+        nextTick(() => {
+          const highlightedValue = context.get("highlightedValue");
+          if (highlightedValue == null) return;
+          const itemEl = getItemEl(scope, highlightedValue);
+          const contentEl = getContentEl(scope);
+          const scrollToIndexFn = prop("scrollToIndexFn");
+          if (scrollToIndexFn) {
+            const highlightedIndex = prop("collection").indexOf(highlightedValue);
+            scrollToIndexFn({ index: highlightedIndex, immediate: true });
+            return;
+          }
+          scrollIntoView(itemEl, { rootEl: contentEl, block: "nearest" });
+        });
       },
       selectItem(params) {
         const { context, event, flush, prop } = params;
@@ -1245,16 +1275,26 @@ var machine = createMachine({
           const nextValue = prop("multiple") ? addOrRemove(context.get("value"), event.value) : [event.value];
           prop("onSelect")?.({ value: nextValue, itemValue: event.value });
           context.set("value", nextValue);
-          context.set("inputValue", getInputValue(params));
+          const inputValue = match(prop("selectionBehavior"), {
+            preserve: context.get("inputValue"),
+            replace: prop("collection").stringifyMany(nextValue),
+            clear: ""
+          });
+          context.set("inputValue", inputValue);
         });
       },
       clearItem(params) {
-        const { context, event, flush } = params;
+        const { context, event, flush, prop } = params;
         if (event.value == null) return;
         flush(() => {
           const nextValue = remove(context.get("value"), event.value);
           context.set("value", nextValue);
-          context.set("inputValue", getInputValue(params));
+          const inputValue = match(prop("selectionBehavior"), {
+            preserve: context.get("inputValue"),
+            replace: prop("collection").stringifyMany(nextValue),
+            clear: ""
+          });
+          context.set("inputValue", inputValue);
         });
       },
       setInitialFocus({ scope }) {
@@ -1297,17 +1337,27 @@ var machine = createMachine({
         context.set("inputValue", inputValue);
       },
       setValue(params) {
-        const { context, flush, event } = params;
+        const { context, flush, event, prop } = params;
         flush(() => {
           context.set("value", event.value);
-          context.set("inputValue", getInputValue(params));
+          const inputValue = match(prop("selectionBehavior"), {
+            preserve: context.get("inputValue"),
+            replace: prop("collection").stringifyMany(event.value),
+            clear: ""
+          });
+          context.set("inputValue", inputValue);
         });
       },
       clearSelectedItems(params) {
-        const { context, flush } = params;
+        const { context, flush, prop } = params;
         flush(() => {
           context.set("value", []);
-          context.set("inputValue", getInputValue(params));
+          const inputValue = match(prop("selectionBehavior"), {
+            preserve: context.get("inputValue"),
+            replace: prop("collection").stringifyMany([]),
+            clear: ""
+          });
+          context.set("inputValue", inputValue);
         });
       },
       scrollContentToTop({ prop, scope }) {
@@ -1320,11 +1370,13 @@ var machine = createMachine({
           contentEl.scrollTop = 0;
         }
       },
-      invokeOnOpen({ prop }) {
-        prop("onOpenChange")?.({ open: true });
+      invokeOnOpen({ prop, event }) {
+        const reason = getOpenChangeReason(event);
+        prop("onOpenChange")?.({ open: true, reason });
       },
-      invokeOnClose({ prop }) {
-        prop("onOpenChange")?.({ open: false });
+      invokeOnClose({ prop, event }) {
+        const reason = getOpenChangeReason(event);
+        prop("onOpenChange")?.({ open: false, reason });
       },
       highlightFirstItem({ context, prop, scope }) {
         const exec = getContentEl(scope) ? queueMicrotask : raf;
@@ -1409,12 +1461,18 @@ var machine = createMachine({
       syncSelectedItems(params) {
         queueMicrotask(() => {
           const { context, prop } = params;
+          const collection2 = prop("collection");
+          const value = context.get("value");
+          const selectedItems = value.map((v) => {
+            const item = context.get("selectedItems").find((item2) => collection2.getItemValue(item2) === v);
+            return item || collection2.find(v);
+          });
+          context.set("selectedItems", selectedItems);
           const inputValue = match(prop("selectionBehavior"), {
             preserve: context.get("inputValue"),
-            replace: prop("collection").stringifyMany(context.get("value")),
+            replace: collection2.stringifyMany(value),
             clear: ""
           });
-          context.set("selectedItems", getSelectedItems(params));
           context.set("inputValue", inputValue);
         });
       },
@@ -1428,20 +1486,8 @@ var machine = createMachine({
     }
   }
 });
-function getInputValue({ context, prop, computed }) {
-  return match(prop("selectionBehavior"), {
-    preserve: context.get("inputValue"),
-    replace: computed("valueAsString"),
-    clear: ""
-  });
-}
-function getSelectedItems({ context, prop }) {
-  const collection2 = prop("collection");
-  return context.get("value").map((v) => {
-    const foundItem = context.get("selectedItems").find((item) => collection2.getItemValue(item) === v);
-    if (foundItem) return foundItem;
-    return collection2.find(v);
-  });
+function getOpenChangeReason(event) {
+  return (event.previousEvent || event).src;
 }
 var props = createProps()([
   "allowCustomValue",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zag-js/combobox",
-  "version": "1.18.0",
+  "version": "1.18.1",
   "description": "Core logic for the combobox widget implemented as a state machine",
   "keywords": [
     "js",
@@ -26,15 +26,15 @@
     "url": "https://github.com/chakra-ui/zag/issues"
   },
   "dependencies": {
-    "@zag-js/anatomy": "1.18.0",
-    "@zag-js/aria-hidden": "1.18.0",
-    "@zag-js/collection": "1.18.0",
-    "@zag-js/core": "1.18.0",
-    "@zag-js/dismissable": "1.18.0",
-    "@zag-js/dom-query": "1.18.0",
-    "@zag-js/utils": "1.18.0",
-    "@zag-js/popper": "1.18.0",
-    "@zag-js/types": "1.18.0"
+    "@zag-js/anatomy": "1.18.1",
+    "@zag-js/aria-hidden": "1.18.1",
+    "@zag-js/collection": "1.18.1",
+    "@zag-js/core": "1.18.1",
+    "@zag-js/dismissable": "1.18.1",
+    "@zag-js/dom-query": "1.18.1",
+    "@zag-js/utils": "1.18.1",
+    "@zag-js/popper": "1.18.1",
+    "@zag-js/types": "1.18.1"
   },
   "devDependencies": {
     "clean-package": "2.2.0"