hotwire_combobox 0.1.41 → 0.1.43

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1fc70c854bf6cdceda08dd727b854a63b7deb0703d9a8dafcab0bd74ca3e73d0
-  data.tar.gz: ec4ad558a47dcdb94e68d360671a89f3d9147a7a2a172a741f06f59dfbfd096a
+  metadata.gz: 5d76e27ecc585f8ad3d4d596d2a6f8fe9916909734027d251cb35264604f192e
+  data.tar.gz: eda85b2dd3c21c407c806a5144c4d9b39c40a36c827c7d3b1986a5e27d432cf9
 SHA512:
-  metadata.gz: 1cb4ab65ec2312a055400870a1c2e91a11e598c389daf96f1f3f079627fac208fbaad73bad1a957db1a5eff33eaaba7c7d2c7eccc7aa389bdcdf9c51e26832b6
-  data.tar.gz: fbb2db40e5b529084c5c65ab644c3af9c0f5721741f2692dcc85e76362f82ebdddf94f979d02b80328b8b39828468e591d6d61faeec3ecff7f262c327bb78a6b
+  metadata.gz: 2cab9b83d4bf4caf3e741f5c12f336241e77f6eec0c97041f25162ecb4aade0d0c58b3ce59e5772b1e5edb89a2a6ad92051c8237f0d40bcee30e550e692add1b
+  data.tar.gz: 1d40dfa00ae3884e8c44693abfa542859ed27fb4fb124a90264c03a57ade1dcb31865f7d89078ea4304968f3adcaba51905d940c336a29ed860857fc5b6e5f40

data/README.md

@@ -80,6 +80,9 @@ import HwComboboxController from "@josefarias/hotwire_combobox"
 application.register("hw-combobox", HwComboboxController)
 ```
 
+> [!WARNING]
+> Keep in mind you need to update both the npm package and the gem every time there's a new version of HotwireCombobox. You should always run the same version number on both sides.
+
 ### Configuring CSS
 
 This library comes with optional default styles. Follow the instructions below to include them in your app.
@@ -109,6 +112,19 @@ Require the styles in `app/assets/stylesheets/application.css`:
 Visit [the docs site](https://hotwirecombobox.com/) for a demo and detailed documentation.
 If the site is down, you can run the docs locally by cloning [the docs repo](https://github.com/josefarias/hotwire_combobox_docs).
 
+## Notes about accessibility
+
+This gem follows the [APG combobox pattern guidelines](https://www.w3.org/WAI/ARIA/apg/patterns/combobox/) with some exceptions we feel increase the usefulness of the component without much detriment to the overall accessible experience.
+
+These are the exceptions:
+
+1. Users cannot manipulate the combobox while it's closed. As long as the combobox is focused, the listbox is shown.
+2. The escape key closes the listbox and blurs the combobox. It does not clear the combobox.
+3. The listbox has wrap-around selection. That is, pressing `Up Arrow` when the user is on the first option will select the last option. And pressing `Down Arrow` when on the last option will select the first option. In paginated comboboxes, the first and last options refer to the currently available options. More options may be loaded after navigating to the last currently available option.
+4. It is possible to have an unlabled combobox, as that responsibility is delegated to the implementing user.
+
+It should be noted none of the maintainers use assistive technologies in their daily lives. If you do, and you feel these exceptions are detrimental to your ability to use the component, or if you find an undocumented exception, please [open a GitHub issue](https://github.com/josefarias/hotwire_combobox/issues). We'll get it sorted.
+
 ## Contributing
 
 Please read [CONTRIBUTING.md](./CONTRIBUTING.md).

data/app/assets/javascripts/controllers/hw_combobox_controller.js

@@ -80,7 +80,7 @@ export default class HwComboboxController extends Concerns(...concerns) {
 
     if (inputType && inputType !== "hw:lockInSelection") {
       if (delay) await sleep(delay)
-      this._commitFilter({ inputType })
+      this._selectBasedOnQuery({ inputType })
     } else {
       this._preselectOption()
     }

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

@@ -37,6 +37,10 @@ Combobox.AsyncLoading = Base => class extends Base {
   get _isAsync() {
     return this.hasAsyncSrcValue
   }
+
+  get _isSync() {
+    return !this._isAsync
+  }
 };
 
 function Concerns(Base, ...mixins) {
@@ -128,16 +132,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);
     }
@@ -236,17 +242,27 @@ Combobox.Dialog = Base => class extends Base {
 };
 
 Combobox.Events = Base => class extends Base {
-  _dispatchSelectionEvent({ isNew }) {
-    const detail = {
-      value: this.hiddenFieldTarget.value,
+  _dispatchSelectionEvent({ isNewAndAllowed, previousValue }) {
+    if (previousValue !== this._value) {
+      dispatch("hw-combobox:selection", {
+        target: this.element,
+        detail: { ...this._eventableDetails, isNewAndAllowed, previousValue }
+      });
+    }
+  }
+
+  _dispatchClosedEvent() {
+    dispatch("hw-combobox:closed", { target: this.element, detail: this._eventableDetails });
+  }
+
+  get _eventableDetails() {
+    return {
+      value: this._value,
       display: this._fullQuery,
       query: this._typedQuery,
       fieldName: this.hiddenFieldTarget.name,
-      isValid: this._valueIsValid,
-      isNew: isNew
-    };
-
-    dispatch("hw-combobox:selection", { target: this.element, detail });
+      isValid: this._valueIsValid
+    }
   }
 };
 
@@ -528,20 +544,28 @@ 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) {
+  filterAndSelect(event) {
+    this._filter(event);
+
+    if (this._isSync) {
+      this._selectBasedOnQuery(event);
+    }
+  }
+
+  _initializeFiltering() {
+    this._debouncedFilterAsync = debounce(this._debouncedFilterAsync.bind(this));
+  }
+
+  _filter(event) {
     if (this._isAsync) {
       this._debouncedFilterAsync(event);
     } else {
-      this._filterSync(event);
+      this._filterSync();
     }
 
     this._actingCombobox.toggleAttribute("data-queried", this._isQueried);
   }
 
-  _initializeFiltering() {
-    this._debouncedFilterAsync = debounce(this._debouncedFilterAsync.bind(this));
-  }
-
   _debouncedFilterAsync(event) {
     this._filterAsync(event);
   }
@@ -556,27 +580,14 @@ Combobox.Filtering = Base => class extends Base {
     await get(this.asyncSrcValue, { responseKind: "turbo-stream", query });
   }
 
-  _filterSync(event) {
+  _filterSync() {
     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]);
-    }
   }
 
   _clearQuery() {
     this._fullQuery = "";
-    this.filter({ inputType: "deleteContentBackward" });
+    this.filterAndSelect({ inputType: "deleteContentBackward" });
   }
 
   get _isQueried() {
@@ -670,9 +681,17 @@ 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._setName(this.originalNameValue);
+    deselectionStrategy();
   }
 
   get _allowNew() {
@@ -700,7 +719,7 @@ Combobox.Options = Base => class extends Base {
   }
 
   get _isUnjustifiablyBlank() {
-    const valueIsMissing = !this.hiddenFieldTarget.value;
+    const valueIsMissing = !this._value;
     const noBlankOptionSelected = !this._selectedOptionElement;
 
     return valueIsMissing && noBlankOptionSelected
@@ -709,8 +728,7 @@ Combobox.Options = Base => class extends Base {
 
 Combobox.Selection = Base => class extends Base {
   selectOptionOnClick(event) {
-    this.filter(event);
-    this._select(event.currentTarget, { forceAutocomplete: true });
+    this._forceSelectionAndFilter(event.currentTarget, event);
     this.close();
   }
 
@@ -720,91 +738,136 @@ Combobox.Selection = Base => class extends Base {
     }
   }
 
-  _select(option, { forceAutocomplete = false } = {}) {
-    this._resetOptions();
-
-    if (option) {
-      this._autocompleteWith(option, { force: forceAutocomplete });
-      this._commitSelection(option, { selected: true });
-      this._markValid();
-    } else {
+  _selectBasedOnQuery(event) {
+    if (this._shouldTreatAsNewOptionForFiltering(!isDeleteEvent(event))) {
+      this._selectNew();
+    } else if (isDeleteEvent(event)) {
+      this._deselect();
+    } else if (event.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._value;
 
-    if (selected) {
-      this.hiddenFieldTarget.value = option.dataset.value;
-      option.scrollIntoView({ block: "nearest" });
-    }
+    this._resetOptionsSilently();
+
+    autocompleteStrategy(option);
 
-    this._dispatchSelectionEvent({ isNew: false });
+    this._setValue(option.dataset.value);
+    this._markSelected(option);
+    this._markValid();
+    this._dispatchSelectionEvent({ isNewAndAllowed: false, previousValue: previousValue });
+
+    option.scrollIntoView({ block: "nearest" });
   }
 
-  _markSelected(option, { selected }) {
-    if (this.hasSelectedClass) {
-      option.classList.toggle(this.selectedClass, selected);
-    }
+  _selectNew() {
+    const previousValue = this._value;
 
-    option.setAttribute("aria-selected", selected);
-    this._setActiveDescendant(selected ? option.id : "");
+    this._resetOptionsSilently();
+    this._setValue(this._fullQuery);
+    this._setName(this.nameWhenNewValue);
+    this._markValid();
+    this._dispatchSelectionEvent({ isNewAndAllowed: true, previousValue: previousValue });
   }
 
   _deselect() {
-    const option = this._selectedOptionElement;
+    const previousValue = this._value;
 
-    if (option) this._commitSelection(option, { selected: false });
+    if (this._selectedOptionElement) {
+      this._markNotSelected(this._selectedOptionElement);
+    }
 
-    this.hiddenFieldTarget.value = null;
+    this._setValue(null);
     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();
+  _deselectAndNotify() {
+    const previousValue = this._deselect();
+    this._dispatchSelectionEvent({ isNewAndAllowed: false, previousValue: previousValue });
+  }
 
-    this._dispatchSelectionEvent({ isNew: true });
+  _forceSelectionAndFilter(option, event) {
+    this._forceSelectionWithoutFiltering(option);
+    this._filter(event);
+  }
+
+  _forceSelectionWithoutFiltering(option) {
+    this._selectAndReplaceFullQuery(option);
   }
 
   _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
+        return option.dataset.value === this._value
       });
 
-      if (option) this._markSelected(option, { selected: true });
+      if (option) this._markSelected(option);
     }
   }
 
+  _selectAndReplaceFullQuery(option) {
+    this._select(option, this._replaceFullQueryWithAutocompletedValue.bind(this));
+  }
+
+  _selectAndAutocompleteMissingPortion(option) {
+    this._select(option, this._autocompleteMissingPortion.bind(this));
+  }
+
   _lockInSelection() {
     if (this._shouldLockInSelection) {
-      this._select(this._ensurableOption, { forceAutocomplete: true });
-      this.filter({ inputType: "hw:lockInSelection" });
+      this._forceSelectionAndFilter(this._ensurableOption, { inputType: "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("");
+  }
+
+  _setValue(value) {
+    this.hiddenFieldTarget.value = value;
+  }
+
+  _setName(value) {
+    this.hiddenFieldTarget.name = value;
+  }
+
+  get _value() {
+    return this.hiddenFieldTarget.value
+  }
+
   get _hasValueButNoSelection() {
-    return this.hiddenFieldTarget.value && !this._selectedOptionElement
+    return this._value && !this._selectedOptionElement
   }
 
   get _shouldLockInSelection() {
@@ -1098,7 +1161,11 @@ Combobox.Toggle = Base => class extends Base {
   close() {
     if (this._isOpen) {
       this._lockInSelection();
+      this._clearInvalidQuery();
+
       this.expandedValue = false;
+
+      this._dispatchClosedEvent();
     }
   }
 
@@ -1167,6 +1234,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
 
@@ -1207,6 +1276,13 @@ Combobox.Toggle = Base => class extends Base {
     enableBodyScroll(this.dialogListboxTarget);
   }
 
+  _clearInvalidQuery() {
+    if (this._isUnjustifiablyBlank) {
+      this._deselect();
+      this._clearQuery();
+    }
+  }
+
   get _isOpen() {
     return this.expandedValue
   }
@@ -1250,7 +1326,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._value;
     return isRequiredAndEmpty
   }
 };
@@ -1333,7 +1409,7 @@ class HwComboboxController extends Concerns(...concerns) {
 
     if (inputType && inputType !== "hw:lockInSelection") {
       if (delay) await sleep(delay);
-      this._commitFilter({ inputType });
+      this._selectBasedOnQuery({ inputType });
     } else {
       this._preselectOption();
     }