hotwire_combobox 0.1.42 → 0.2.0

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

@@ -1,3 +1,6 @@
+/*!
+HotwireCombobox 0.2.0
+*/
 import { Controller } from '@hotwired/stimulus';
 
 const Combobox = {};
@@ -33,10 +36,20 @@ Combobox.Actors = Base => class extends Base {
   }
 };
 
+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) {
@@ -121,6 +134,22 @@ function dispatch(eventName, { target, cancelable, detail } = {}) {
   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) {
@@ -128,16 +157,18 @@ Combobox.Autocomplete = Base => class extends Base {
     }
   }
 
-  _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);
     }
@@ -226,7 +257,7 @@ Combobox.Dialog = Base => class extends Base {
     this.dialogFocusTrapTarget.focus();
   }
 
-  get _smallViewport() {
+  get _isSmallViewport() {
     return window.matchMedia(`(max-width: ${this.smallViewportMaxWidthValue})`).matches
   }
 
@@ -236,20 +267,35 @@ Combobox.Dialog = Base => class extends Base {
 };
 
 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
     }
   }
@@ -533,55 +579,58 @@ async function get(url, options) {
 // 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() {
@@ -601,20 +650,255 @@ Combobox.Filtering = Base => class extends Base {
   }
 };
 
+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) => {
@@ -626,14 +910,18 @@ Combobox.Navigation = Base => class extends Base {
       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);
+      }
     }
   }
 };
@@ -675,9 +963,25 @@ Combobox.NewOptions = Base => class extends Base {
 };
 
 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() {
@@ -685,19 +989,23 @@ Combobox.Options = Base => class extends Base {
   }
 
   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() {
@@ -705,7 +1013,7 @@ Combobox.Options = Base => class extends Base {
   }
 
   get _isUnjustifiablyBlank() {
-    const valueIsMissing = !this.hiddenFieldTarget.value;
+    const valueIsMissing = this._hasEmptyFieldValue;
     const noBlankOptionSelected = !this._selectedOptionElement;
 
     return valueIsMissing && noBlankOptionSelected
@@ -713,103 +1021,148 @@ Combobox.Options = Base => class extends Base {
 };
 
 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() {
@@ -1100,19 +1453,40 @@ Combobox.Toggle = Base => class extends Base {
     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();
     }
   }
 
@@ -1123,14 +1497,14 @@ Combobox.Toggle = Base => class extends Base {
     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() {
@@ -1142,6 +1516,11 @@ Combobox.Toggle = Base => class extends Base {
     }
   }
 
+  _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`
@@ -1153,18 +1532,16 @@ Combobox.Toggle = Base => class extends Base {
     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();
@@ -1173,6 +1550,8 @@ Combobox.Toggle = Base => class extends Base {
     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
 
@@ -1213,12 +1592,15 @@ Combobox.Toggle = Base => class extends Base {
     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
   }
 };
 
@@ -1256,7 +1638,7 @@ Combobox.Validity = Base => class extends Base {
   // +_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
   }
 };
@@ -1266,11 +1648,14 @@ window.HOTWIRE_COMBOBOX_STREAM_DELAY = 0; // ms, for testing purposes
 const concerns = [
   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,
@@ -1286,7 +1671,10 @@ class HwComboboxController extends Concerns(...concerns) {
   ]
 
   static targets = [
+    "announcer",
     "combobox",
+    "chipDismisser",
+    "closer",
     "dialog",
     "dialogCombobox",
     "dialogFocusTrap",
@@ -1307,12 +1695,14 @@ class HwComboboxController extends Concerns(...concerns) {
     nameWhenNew: String,
     originalName: String,
     prefilledDisplay: String,
+    selectionChipSrc: String,
     smallViewportMaxWidth: String
   }
 
   initialize() {
     this._initializeActors();
     this._initializeFiltering();
+    this._initializeMultiselect();
   }
 
   connect() {
@@ -1337,13 +1727,27 @@ class HwComboboxController extends Concerns(...concerns) {
     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);
+  }
 }
 
 export { HwComboboxController as default };