hotwire_combobox 0.1.42 → 0.2.0

data/app/assets/javascripts/hotwire_combobox.umd.js

@@ -1,3 +1,6 @@
+/*!
+HotwireCombobox 0.2.0
+*/
 (function (global, factory) {
   typeof exports === 'object' && typeof module !== 'undefined' ? module.exports = factory(require('@hotwired/stimulus')) :
   typeof define === 'function' && define.amd ? define(['@hotwired/stimulus'], factory) :
@@ -37,10 +40,20 @@
     }
   };
 
+  Combobox.Announcements = Base => class extends Base {
+    _announceToScreenReader(display, action) {
+      this.announcerTarget.innerText = `${display} ${action}`;
+    }
+  };
+
   Combobox.AsyncLoading = Base => class extends Base {
     get _isAsync() {
       return this.hasAsyncSrcValue
     }
+
+    get _isSync() {
+      return !this._isAsync
+    }
   };
 
   function Concerns(Base, ...mixins) {
@@ -125,6 +138,22 @@
     return event
   }
 
+  function nextRepaint() {
+    if (document.visibilityState === "hidden") {
+      return nextEventLoopTick()
+    } else {
+      return nextAnimationFrame()
+    }
+  }
+
+  function nextAnimationFrame() {
+    return new Promise((resolve) => requestAnimationFrame(() => resolve()))
+  }
+
+  function nextEventLoopTick() {
+    return new Promise((resolve) => setTimeout(() => resolve(), 0))
+  }
+
   Combobox.Autocomplete = Base => class extends Base {
     _connectListAutocomplete() {
       if (!this._autocompletesList) {
@@ -132,16 +161,18 @@
       }
     }
 
-    _autocompleteWith(option, { force }) {
-      if (!this._autocompletesInline && !force) return
+    _replaceFullQueryWithAutocompletedValue(option) {
+      const autocompletedValue = option.getAttribute(this.autocompletableAttributeValue);
+
+      this._fullQuery = autocompletedValue;
+      this._actingCombobox.setSelectionRange(autocompletedValue.length, autocompletedValue.length);
+    }
 
+    _autocompleteMissingPortion(option) {
       const typedValue = this._typedQuery;
       const autocompletedValue = option.getAttribute(this.autocompletableAttributeValue);
 
-      if (force) {
-        this._fullQuery = autocompletedValue;
-        this._actingCombobox.setSelectionRange(autocompletedValue.length, autocompletedValue.length);
-      } else if (startsWith(autocompletedValue, typedValue)) {
+      if (this._autocompletesInline && startsWith(autocompletedValue, typedValue)) {
         this._fullQuery = autocompletedValue;
         this._actingCombobox.setSelectionRange(typedValue.length, autocompletedValue.length);
       }
@@ -230,7 +261,7 @@
       this.dialogFocusTrapTarget.focus();
     }
 
-    get _smallViewport() {
+    get _isSmallViewport() {
       return window.matchMedia(`(max-width: ${this.smallViewportMaxWidthValue})`).matches
     }
 
@@ -240,20 +271,35 @@
   };
 
   Combobox.Events = Base => class extends Base {
-    _dispatchSelectionEvent({ isNew }) {
-      dispatch("hw-combobox:selection", { target: this.element, detail: { ...this._eventableDetails, isNew } });
+    _dispatchPreselectionEvent({ isNewAndAllowed, previousValue }) {
+      if (previousValue === this._incomingFieldValueString) return
+
+      dispatch("hw-combobox:preselection", {
+        target: this.element,
+        detail: { ...this._eventableDetails, isNewAndAllowed, previousValue }
+      });
     }
 
-    _dispatchClosedEvent() {
-      dispatch("hw-combobox:closed", { target: this.element, detail: this._eventableDetails });
+    _dispatchSelectionEvent() {
+      dispatch("hw-combobox:selection", {
+        target: this.element,
+        detail: this._eventableDetails
+      });
+    }
+
+    _dispatchRemovalEvent({ removedDisplay, removedValue }) {
+      dispatch("hw-combobox:removal", {
+        target: this.element,
+        detail: { ...this._eventableDetails, removedDisplay, removedValue }
+      });
     }
 
     get _eventableDetails() {
       return {
-        value: this.hiddenFieldTarget.value,
+        value: this._incomingFieldValueString,
         display: this._fullQuery,
         query: this._typedQuery,
-        fieldName: this.hiddenFieldTarget.name,
+        fieldName: this._fieldName,
         isValid: this._valueIsValid
       }
     }
@@ -537,55 +583,58 @@
   // WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 
   Combobox.Filtering = Base => class extends Base {
-    filter(event) {
-      if (this._isAsync) {
-        this._debouncedFilterAsync(event);
-      } else {
-        this._filterSync(event);
-      }
+    filterAndSelect({ inputType }) {
+      this._filter(inputType);
 
-      this._actingCombobox.toggleAttribute("data-queried", this._isQueried);
+      if (this._isSync) {
+        this._selectOnQuery(inputType);
+      }
     }
 
     _initializeFiltering() {
       this._debouncedFilterAsync = debounce(this._debouncedFilterAsync.bind(this));
     }
 
-    _debouncedFilterAsync(event) {
-      this._filterAsync(event);
+    _filter(inputType) {
+      if (this._isAsync) {
+        this._debouncedFilterAsync(inputType);
+      } else {
+        this._filterSync();
+      }
+
+      this._markQueried();
+    }
+
+    _debouncedFilterAsync(inputType) {
+      this._filterAsync(inputType);
     }
 
-    async _filterAsync(event) {
+    async _filterAsync(inputType) {
       const query = {
         q: this._fullQuery,
-        input_type: event.inputType,
+        input_type: inputType,
         for_id: this.element.dataset.asyncId
       };
 
       await get(this.asyncSrcValue, { responseKind: "turbo-stream", query });
     }
 
-    _filterSync(event) {
-      this.open();
-      this._allOptionElements.forEach(applyFilter(this._fullQuery, { matching: this.filterableAttributeValue }));
-      this._commitFilter(event);
-    }
-
-    _commitFilter(event) {
-      if (this._shouldTreatAsNewOptionForFiltering(!isDeleteEvent(event))) {
-        this._selectNew();
-      } else if (isDeleteEvent(event)) {
-        this._deselect();
-      } else if (event.inputType === "hw:lockInSelection") {
-        this._select(this._ensurableOption);
-      } else if (this._isOpen) {
-        this._select(this._visibleOptionElements[0]);
-      }
+    _filterSync() {
+      this._allFilterableOptionElements.forEach(
+        applyFilter(
+          this._fullQuery,
+          { matching: this.filterableAttributeValue }
+        )
+      );
     }
 
     _clearQuery() {
       this._fullQuery = "";
-      this.filter({ inputType: "deleteContentBackward" });
+      this.filterAndSelect({ inputType: "deleteContentBackward" });
+    }
+
+    _markQueried() {
+      this._actingCombobox.toggleAttribute("data-queried", this._isQueried);
     }
 
     get _isQueried() {
@@ -605,20 +654,255 @@
     }
   };
 
+  Combobox.FormField = Base => class extends Base {
+    get _fieldValue() {
+      if (this._isMultiselect) {
+        const currentValue = this.hiddenFieldTarget.value;
+        const arrayFromValue = currentValue ? currentValue.split(",") : [];
+
+        return new Set(arrayFromValue)
+      } else {
+        return this.hiddenFieldTarget.value
+      }
+    }
+
+    get _fieldValueString() {
+      if (this._isMultiselect) {
+        return this._fieldValueArray.join(",")
+      } else {
+        return this.hiddenFieldTarget.value
+      }
+    }
+
+    get _incomingFieldValueString() {
+      if (this._isMultiselect) {
+        const array = this._fieldValueArray;
+
+        if (this.hiddenFieldTarget.dataset.valueForMultiselect) {
+          array.push(this.hiddenFieldTarget.dataset.valueForMultiselect);
+        }
+
+        return array.join(",")
+      } else {
+        return this.hiddenFieldTarget.value
+      }
+    }
+
+    get _fieldValueArray() {
+      if (this._isMultiselect) {
+        return Array.from(this._fieldValue)
+      } else {
+        return [ this.hiddenFieldTarget.value ]
+      }
+    }
+
+    set _fieldValue(value) {
+      if (this._isMultiselect) {
+        this.hiddenFieldTarget.dataset.valueForMultiselect = value?.replace(/,/g, "");
+        this.hiddenFieldTarget.dataset.displayForMultiselect = this._fullQuery;
+      } else {
+        this.hiddenFieldTarget.value = value;
+      }
+    }
+
+    get _hasEmptyFieldValue() {
+      if (this._isMultiselect) {
+        return this.hiddenFieldTarget.dataset.valueForMultiselect == "" ||
+          this.hiddenFieldTarget.dataset.valueForMultiselect == "undefined"
+      } else {
+        return this.hiddenFieldTarget.value === ""
+      }
+    }
+
+    get _hasFieldValue() {
+      return !this._hasEmptyFieldValue
+    }
+
+    get _fieldName() {
+      return this.hiddenFieldTarget.name
+    }
+
+    set _fieldName(value) {
+      this.hiddenFieldTarget.name = value;
+    }
+  };
+
+  Combobox.Multiselect = Base => class extends Base {
+    navigateChip(event) {
+      this._chipKeyHandlers[event.key]?.call(this, event);
+    }
+
+    removeChip({ currentTarget, params }) {
+      let display;
+      const option = this._optionElementWithValue(params.value);
+
+      if (option) {
+        display = option.getAttribute(this.autocompletableAttributeValue);
+        this._markNotSelected(option);
+        this._markNotMultiselected(option);
+      } else {
+        display = params.value; // for new options
+      }
+
+      this._removeFromFieldValue(params.value);
+      this._filter("hw:multiselectSync");
+
+      currentTarget.closest("[data-hw-combobox-chip]").remove();
+
+      if (!this._isSmallViewport) {
+        this.openByFocusing();
+      }
+
+      this._announceToScreenReader(display, "removed");
+      this._dispatchRemovalEvent({ removedDisplay: display, removedValue: params.value });
+    }
+
+    hideChipsForCache() {
+      this.element.querySelectorAll("[data-hw-combobox-chip]").forEach(chip => chip.hidden = true);
+    }
+
+    _chipKeyHandlers = {
+      Backspace: (event) => {
+        this.removeChip(event);
+        cancel(event);
+      },
+      Enter: (event) => {
+        this.removeChip(event);
+        cancel(event);
+      },
+      Space: (event) => {
+        this.removeChip(event);
+        cancel(event);
+      },
+      Escape: (event) => {
+        this.openByFocusing();
+        cancel(event);
+      }
+    }
+
+    _initializeMultiselect() {
+      if (!this._isMultiPreselected) {
+        this._preselectMultiple();
+        this._markMultiPreselected();
+      }
+    }
+
+    async _createChip(shouldReopen) {
+      if (!this._isMultiselect) return
+
+      this._beforeClearingMultiselectQuery(async (display, value) => {
+        this._fullQuery = "";
+        this._filter("hw:multiselectSync");
+        this._requestChips(value);
+        this._addToFieldValue(value);
+        if (shouldReopen) {
+          await nextRepaint();
+          this.openByFocusing();
+        }
+        this._announceToScreenReader(display, "multi-selected. Press Shift + Tab, then Enter to remove.");
+      });
+    }
+
+    async _requestChips(values) {
+      await get(this.selectionChipSrcValue, {
+        responseKind: "turbo-stream",
+        query: {
+          for_id: this.element.dataset.asyncId,
+          combobox_values: values
+        }
+      });
+    }
+
+    _beforeClearingMultiselectQuery(callback) {
+      const display = this.hiddenFieldTarget.dataset.displayForMultiselect;
+      const value = this.hiddenFieldTarget.dataset.valueForMultiselect;
+
+      if (value && !this._fieldValue.has(value)) {
+        callback(display, value);
+      }
+
+      this.hiddenFieldTarget.dataset.displayForMultiselect = "";
+      this.hiddenFieldTarget.dataset.valueForMultiselect = "";
+    }
+
+    _resetMultiselectionMarks() {
+      if (!this._isMultiselect) return
+
+      this._fieldValueArray.forEach(value => {
+        const option = this._optionElementWithValue(value);
+
+        if (option) {
+          option.setAttribute("data-multiselected", "");
+          option.hidden = true;
+        }
+      });
+    }
+
+    _markNotMultiselected(option) {
+      if (!this._isMultiselect) return
+
+      option.removeAttribute("data-multiselected");
+      option.hidden = false;
+    }
+
+    _addToFieldValue(value) {
+      const newValue = this._fieldValue;
+
+      newValue.add(String(value));
+      this.hiddenFieldTarget.value = Array.from(newValue).join(",");
+
+      if (this._isSync) this._resetMultiselectionMarks();
+    }
+
+    _removeFromFieldValue(value) {
+      const newValue = this._fieldValue;
+
+      newValue.delete(String(value));
+      this.hiddenFieldTarget.value = Array.from(newValue).join(",");
+
+      if (this._isSync) this._resetMultiselectionMarks();
+    }
+
+    _focusLastChipDismisser() {
+      this.chipDismisserTargets[this.chipDismisserTargets.length - 1]?.focus();
+    }
+
+    _markMultiPreselected() {
+      this.element.dataset.multiPreselected = "";
+    }
+
+    get _isMultiselect() {
+      return this.hasSelectionChipSrcValue
+    }
+
+    get _isSingleSelect() {
+      return !this._isMultiselect
+    }
+
+    get _isMultiPreselected() {
+      return this.element.hasAttribute("data-multi-preselected")
+    }
+  };
+
   Combobox.Navigation = Base => class extends Base {
     navigate(event) {
       if (this._autocompletesList) {
-        this._keyHandlers[event.key]?.call(this, event);
+        this._navigationKeyHandlers[event.key]?.call(this, event);
       }
     }
 
-    _keyHandlers = {
+    _navigationKeyHandlers = {
       ArrowUp: (event) => {
         this._selectIndex(this._selectedOptionIndex - 1);
         cancel(event);
       },
       ArrowDown: (event) => {
         this._selectIndex(this._selectedOptionIndex + 1);
+
+        if (this._selectedOptionIndex === 0) {
+          this._actingListbox.scrollTop = 0;
+        }
+
         cancel(event);
       },
       Home: (event) => {
@@ -630,14 +914,18 @@
         cancel(event);
       },
       Enter: (event) => {
-        this.close();
-        this._actingCombobox.blur();
+        this._closeAndBlur("hw:keyHandler:enter");
         cancel(event);
       },
       Escape: (event) => {
-        this.close();
-        this._actingCombobox.blur();
+        this._closeAndBlur("hw:keyHandler:escape");
         cancel(event);
+      },
+      Backspace: (event) => {
+        if (this._isMultiselect && !this._fullQuery) {
+          this._focusLastChipDismisser();
+          cancel(event);
+        }
       }
     }
   };
@@ -679,9 +967,25 @@
   };
 
   Combobox.Options = Base => class extends Base {
-    _resetOptions() {
-      this._deselect();
-      this.hiddenFieldTarget.name = this.originalNameValue;
+    _resetOptionsSilently() {
+      this._resetOptions(this._deselect.bind(this));
+    }
+
+    _resetOptionsAndNotify() {
+      this._resetOptions(this._deselectAndNotify.bind(this));
+    }
+
+    _resetOptions(deselectionStrategy) {
+      this._fieldName = this.originalNameValue;
+      deselectionStrategy();
+    }
+
+    _optionElementWithValue(value) {
+      return this._actingListbox.querySelector(`[${this.filterableAttributeValue}][data-value='${value}']`)
+    }
+
+    _displayForOptionElement(element) {
+      return element.getAttribute(this.autocompletableAttributeValue)
     }
 
     get _allowNew() {
@@ -689,19 +993,23 @@
     }
 
     get _allOptions() {
-      return Array.from(this._allOptionElements)
+      return Array.from(this._allFilterableOptionElements)
     }
 
-    get _allOptionElements() {
-      return this._actingListbox.querySelectorAll(`[${this.filterableAttributeValue}]`)
+    get _allFilterableOptionElements() {
+      return this._actingListbox.querySelectorAll(`[${this.filterableAttributeValue}]:not([data-multiselected])`)
     }
 
     get _visibleOptionElements() {
-      return [ ...this._allOptionElements ].filter(visible)
+      return [ ...this._allFilterableOptionElements ].filter(visible)
     }
 
     get _selectedOptionElement() {
-      return this._actingListbox.querySelector("[role=option][aria-selected=true]")
+      return this._actingListbox.querySelector("[role=option][aria-selected=true]:not([data-multiselected])")
+    }
+
+    get _multiselectedOptionElements() {
+      return this._actingListbox.querySelectorAll("[role=option][data-multiselected]")
     }
 
     get _selectedOptionIndex() {
@@ -709,7 +1017,7 @@
     }
 
     get _isUnjustifiablyBlank() {
-      const valueIsMissing = !this.hiddenFieldTarget.value;
+      const valueIsMissing = this._hasEmptyFieldValue;
       const noBlankOptionSelected = !this._selectedOptionElement;
 
       return valueIsMissing && noBlankOptionSelected
@@ -717,103 +1025,148 @@
   };
 
   Combobox.Selection = Base => class extends Base {
-    selectOptionOnClick(event) {
-      this.filter(event);
-      this._select(event.currentTarget, { forceAutocomplete: true });
-      this.close();
+    selectOnClick({ currentTarget, inputType }) {
+      this._forceSelectionAndFilter(currentTarget, inputType);
+      this._closeAndBlur("hw:optionRoleClick");
     }
 
     _connectSelection() {
       if (this.hasPrefilledDisplayValue) {
         this._fullQuery = this.prefilledDisplayValue;
+        this._markQueried();
       }
     }
 
-    _select(option, { forceAutocomplete = false } = {}) {
-      this._resetOptions();
-
-      if (option) {
-        this._autocompleteWith(option, { force: forceAutocomplete });
-        this._commitSelection(option, { selected: true });
-        this._markValid();
-      } else {
+    _selectOnQuery(inputType) {
+      if (this._shouldTreatAsNewOptionForFiltering(!isDeleteEvent({ inputType: inputType }))) {
+        this._selectNew();
+      } else if (isDeleteEvent({ inputType: inputType })) {
+        this._deselect();
+      } else if (inputType === "hw:lockInSelection" && this._ensurableOption) {
+        this._selectAndAutocompleteMissingPortion(this._ensurableOption);
+      } else if (this._isOpen && this._visibleOptionElements[0]) {
+        this._selectAndAutocompleteMissingPortion(this._visibleOptionElements[0]);
+      } else if (this._isOpen) {
+        this._resetOptionsAndNotify();
         this._markInvalid();
-      }
+      } else ;
     }
 
-    _commitSelection(option, { selected }) {
-      this._markSelected(option, { selected });
+    _select(option, autocompleteStrategy) {
+      const previousValue = this._fieldValueString;
 
-      if (selected) {
-        this.hiddenFieldTarget.value = option.dataset.value;
-        option.scrollIntoView({ block: "nearest" });
-      }
+      this._resetOptionsSilently();
+
+      autocompleteStrategy(option);
 
-      this._dispatchSelectionEvent({ isNew: false });
+      this._fieldValue = option.dataset.value;
+      this._markSelected(option);
+      this._markValid();
+      this._dispatchPreselectionEvent({ isNewAndAllowed: false, previousValue: previousValue });
+
+      option.scrollIntoView({ block: "nearest" });
     }
 
-    _markSelected(option, { selected }) {
-      if (this.hasSelectedClass) {
-        option.classList.toggle(this.selectedClass, selected);
-      }
+    _selectNew() {
+      const previousValue = this._fieldValueString;
 
-      option.setAttribute("aria-selected", selected);
-      this._setActiveDescendant(selected ? option.id : "");
+      this._resetOptionsSilently();
+      this._fieldValue = this._fullQuery;
+      this._fieldName = this.nameWhenNewValue;
+      this._markValid();
+      this._dispatchPreselectionEvent({ isNewAndAllowed: true, previousValue: previousValue });
     }
 
     _deselect() {
-      const option = this._selectedOptionElement;
+      const previousValue = this._fieldValueString;
 
-      if (option) this._commitSelection(option, { selected: false });
+      if (this._selectedOptionElement) {
+        this._markNotSelected(this._selectedOptionElement);
+      }
 
-      this.hiddenFieldTarget.value = null;
+      this._fieldValue = "";
       this._setActiveDescendant("");
 
-      if (!option) this._dispatchSelectionEvent({ isNew: false });
+      return previousValue
     }
 
-    _selectNew() {
-      this._resetOptions();
-      this.hiddenFieldTarget.value = this._fullQuery;
-      this.hiddenFieldTarget.name = this.nameWhenNewValue;
-      this._markValid();
-
-      this._dispatchSelectionEvent({ isNew: true });
+    _deselectAndNotify() {
+      const previousValue = this._deselect();
+      this._dispatchPreselectionEvent({ isNewAndAllowed: false, previousValue: previousValue });
     }
 
     _selectIndex(index) {
       const option = wrapAroundAccess(this._visibleOptionElements, index);
-      this._select(option, { forceAutocomplete: true });
+      this._forceSelectionWithoutFiltering(option);
     }
 
-    _preselectOption() {
-      if (this._hasValueButNoSelection && this._allOptions.length < 100) {
-        const option = this._allOptions.find(option => {
-          return option.dataset.value === this.hiddenFieldTarget.value
-        });
+    _preselectSingle() {
+      if (this._isSingleSelect && this._hasValueButNoSelection && this._allOptions.length < 100) {
+        const option = this._optionElementWithValue(this._fieldValue);
+        if (option) this._markSelected(option);
+      }
+    }
 
-        if (option) this._markSelected(option, { selected: true });
+    _preselectMultiple() {
+      if (this._isMultiselect && this._hasValueButNoSelection) {
+        this._requestChips(this._fieldValueString);
+        this._resetMultiselectionMarks();
       }
     }
 
+    _selectAndAutocompleteMissingPortion(option) {
+      this._select(option, this._autocompleteMissingPortion.bind(this));
+    }
+
+    _selectAndAutocompleteFullQuery(option) {
+      this._select(option, this._replaceFullQueryWithAutocompletedValue.bind(this));
+    }
+
+    _forceSelectionAndFilter(option, inputType) {
+      this._forceSelectionWithoutFiltering(option);
+      this._filter(inputType);
+    }
+
+    _forceSelectionWithoutFiltering(option) {
+      this._selectAndAutocompleteFullQuery(option);
+    }
+
     _lockInSelection() {
       if (this._shouldLockInSelection) {
-        this._select(this._ensurableOption, { forceAutocomplete: true });
-        this.filter({ inputType: "hw:lockInSelection" });
+        this._forceSelectionAndFilter(this._ensurableOption, "hw:lockInSelection");
       }
+    }
 
-      if (this._isUnjustifiablyBlank) {
-        this._deselect();
-        this._clearQuery();
-      }
+    _markSelected(option) {
+      if (this.hasSelectedClass) option.classList.add(this.selectedClass);
+      option.setAttribute("aria-selected", true);
+      this._setActiveDescendant(option.id);
+    }
+
+    _markNotSelected(option) {
+      if (this.hasSelectedClass) option.classList.remove(this.selectedClass);
+      option.removeAttribute("aria-selected");
+      this._removeActiveDescendant();
     }
 
     _setActiveDescendant(id) {
       this._forAllComboboxes(el => el.setAttribute("aria-activedescendant", id));
     }
 
+    _removeActiveDescendant() {
+      this._setActiveDescendant("");
+    }
+
     get _hasValueButNoSelection() {
-      return this.hiddenFieldTarget.value && !this._selectedOptionElement
+      return this._hasFieldValue && !this._hasSelection
+    }
+
+    get _hasSelection() {
+      if (this._isSingleSelect) {
+        this._selectedOptionElement;
+      } else {
+        this._multiselectedOptionElements.length > 0;
+      }
     }
 
     get _shouldLockInSelection() {
@@ -1104,19 +1457,40 @@
       this.expandedValue = true;
     }
 
-    close() {
+    openByFocusing() {
+      this._actingCombobox.focus();
+    }
+
+    close(inputType) {
       if (this._isOpen) {
+        const shouldReopen = this._isMultiselect &&
+          this._isSync &&
+          !this._isSmallViewport &&
+          inputType != "hw:clickOutside" &&
+          inputType != "hw:focusOutside";
+
         this._lockInSelection();
+        this._clearInvalidQuery();
+
         this.expandedValue = false;
-        this._dispatchClosedEvent();
+
+        this._dispatchSelectionEvent();
+
+        if (inputType != "hw:keyHandler:escape") {
+          this._createChip(shouldReopen);
+        }
+
+        if (this._isSingleSelect && this._selectedOptionElement) {
+          this._announceToScreenReader(this._displayForOptionElement(this._selectedOptionElement), "selected");
+        }
       }
     }
 
     toggle() {
       if (this.expandedValue) {
-        this.close();
+        this._closeAndBlur("hw:toggle");
       } else {
-        this._openByFocusing();
+        this.openByFocusing();
       }
     }
 
@@ -1127,14 +1501,14 @@
       if (this.mainWrapperTarget.contains(target) && !this._isDialogDismisser(target)) return
       if (this._withinElementBounds(event)) return
 
-      this.close();
+      this._closeAndBlur("hw:clickOutside");
     }
 
     closeOnFocusOutside({ target }) {
       if (!this._isOpen) return
       if (this.element.contains(target)) return
 
-      this.close();
+      this._closeAndBlur("hw:focusOutside");
     }
 
     clearOrToggleOnHandleClick() {
@@ -1146,6 +1520,11 @@
       }
     }
 
+    _closeAndBlur(inputType) {
+      this.close(inputType);
+      this._actingCombobox.blur();
+    }
+
     // Some browser extensions like 1Password overlay elements on top of the combobox.
     // Hovering over these elements emits a click event for some reason.
     // These events don't contain any telling information, so we use `_withinElementBounds`
@@ -1157,18 +1536,16 @@
       return clientX >= left && clientX <= right && clientY >= top && clientY <= bottom
     }
 
-    _openByFocusing() {
-      this._actingCombobox.focus();
-    }
-
     _isDialogDismisser(target) {
       return target.closest("dialog") && target.role != "combobox"
     }
 
     _expand() {
-      if (this._preselectOnExpansion) this._preselectOption();
+      if (this._isSync) {
+        this._preselectSingle();
+      }
 
-      if (this._autocompletesList && this._smallViewport) {
+      if (this._autocompletesList && this._isSmallViewport) {
         this._openInDialog();
       } else {
         this._openInline();
@@ -1177,6 +1554,8 @@
       this._actingCombobox.setAttribute("aria-expanded", true); // needs to happen after setting acting combobox
     }
 
+    // +._collapse()+ differs from `.close()` in that it might be called by stimulus on connect because
+    // it interprets a change in `expandedValue` — whereas `.close()` is only called internally by us.
     _collapse() {
       this._actingCombobox.setAttribute("aria-expanded", false); // needs to happen before resetting acting combobox
 
@@ -1217,12 +1596,15 @@
       enableBodyScroll(this.dialogListboxTarget);
     }
 
-    get _isOpen() {
-      return this.expandedValue
+    _clearInvalidQuery() {
+      if (this._isUnjustifiablyBlank) {
+        this._deselect();
+        this._clearQuery();
+      }
     }
 
-    get _preselectOnExpansion() {
-      return !this._isAsync // async comboboxes preselect based on callbacks
+    get _isOpen() {
+      return this.expandedValue
     }
   };
 
@@ -1260,7 +1642,7 @@
     // +_valueIsInvalid+ only checks if `comboboxTarget` (and not `_actingCombobox`) is required
     // because the `required` attribute is only forwarded to the `comboboxTarget` element
     get _valueIsInvalid() {
-      const isRequiredAndEmpty = this.comboboxTarget.required && !this.hiddenFieldTarget.value;
+      const isRequiredAndEmpty = this.comboboxTarget.required && this._hasEmptyFieldValue;
       return isRequiredAndEmpty
     }
   };
@@ -1270,11 +1652,14 @@
   const concerns = [
     stimulus.Controller,
     Combobox.Actors,
+    Combobox.Announcements,
     Combobox.AsyncLoading,
     Combobox.Autocomplete,
     Combobox.Dialog,
     Combobox.Events,
     Combobox.Filtering,
+    Combobox.FormField,
+    Combobox.Multiselect,
     Combobox.Navigation,
     Combobox.NewOptions,
     Combobox.Options,
@@ -1290,7 +1675,10 @@
     ]
 
     static targets = [
+      "announcer",
       "combobox",
+      "chipDismisser",
+      "closer",
       "dialog",
       "dialogCombobox",
       "dialogFocusTrap",
@@ -1311,12 +1699,14 @@
       nameWhenNew: String,
       originalName: String,
       prefilledDisplay: String,
+      selectionChipSrc: String,
       smallViewportMaxWidth: String
     }
 
     initialize() {
       this._initializeActors();
       this._initializeFiltering();
+      this._initializeMultiselect();
     }
 
     connect() {
@@ -1341,13 +1731,27 @@
       const inputType = element.dataset.inputType;
       const delay = window.HOTWIRE_COMBOBOX_STREAM_DELAY;
 
-      if (inputType && inputType !== "hw:lockInSelection") {
+      this._resetMultiselectionMarks();
+
+      if (inputType === "hw:multiselectSync") {
+        this.openByFocusing();
+      } else if (inputType && inputType !== "hw:lockInSelection") {
         if (delay) await sleep(delay);
-        this._commitFilter({ inputType });
+        this._selectOnQuery(inputType);
       } else {
-        this._preselectOption();
+        this._preselectSingle();
       }
     }
+
+    closerTargetConnected() {
+      this._closeAndBlur("hw:asyncCloser");
+    }
+
+    // Use +_printStack+ for debugging purposes
+    _printStack() {
+      const err = new Error();
+      console.log(err.stack || err.stacktrace);
+    }
   }
 
   return HwComboboxController;