hotwire_combobox 0.1.37 → 0.1.39

data/app/assets/javascripts/hw_combobox/helpers.js

@@ -62,3 +62,20 @@ export function unselectedPortion(element) {
     return element.value.substring(0, element.selectionStart)
   }
 }
+
+export function dispatch(eventName, { target, cancelable, detail } = {}) {
+  const event = new CustomEvent(eventName, {
+    cancelable,
+    bubbles: true,
+    composed: true,
+    detail
+  })
+
+  if (target && target.isConnected) {
+    target.dispatchEvent(event)
+  } else {
+    document.documentElement.dispatchEvent(event)
+  }
+
+  return event
+}

data/app/assets/javascripts/hw_combobox/models/combobox/dialog.js

@@ -1,6 +1,12 @@
 import Combobox from "hw_combobox/models/combobox/base"
 
 Combobox.Dialog = Base => class extends Base {
+  rerouteListboxStreamToDialog({ detail: { newStream } }) {
+    if (newStream.target == this.listboxTarget.id && this._dialogIsOpen) {
+      newStream.setAttribute("target", this.dialogListboxTarget.id)
+    }
+  }
+
   _connectDialog() {
     if (window.visualViewport) {
       window.visualViewport.addEventListener("resize", this._resizeDialog)
@@ -50,4 +56,8 @@ Combobox.Dialog = Base => class extends Base {
   get _smallViewport() {
     return window.matchMedia(`(max-width: ${this.smallViewportMaxWidthValue})`).matches
   }
+
+  get _dialogIsOpen() {
+    return this.dialogTarget.open
+  }
 }

data/app/assets/javascripts/hw_combobox/models/combobox/events.js

@@ -0,0 +1,17 @@
+import Combobox from "hw_combobox/models/combobox/base"
+import { dispatch } from "hw_combobox/helpers"
+
+Combobox.Events = Base => class extends Base {
+  _dispatchSelectionEvent({ isNew }) {
+    const detail = {
+      value: this.hiddenFieldTarget.value,
+      display: this._fullQuery,
+      query: this._typedQuery,
+      fieldName: this.hiddenFieldTarget.name,
+      isValid: this._valueIsValid,
+      isNew: isNew
+    }
+
+    dispatch("hw-combobox:selection", { target: this.element, detail })
+  }
+}

data/app/assets/javascripts/hw_combobox/models/combobox/filtering.js

@@ -21,7 +21,12 @@ Combobox.Filtering = Base => class extends Base {
   }
 
   async _filterAsync(event) {
-    const query = { q: this._fullQuery, input_type: event.inputType }
+    const query = {
+      q: this._fullQuery,
+      input_type: event.inputType,
+      for_id: this.element.dataset.asyncId
+    }
+
     await get(this.asyncSrcValue, { responseKind: "turbo-stream", query })
   }
 
@@ -36,11 +41,16 @@ Combobox.Filtering = Base => class extends Base {
       this._selectNew()
     } else if (isDeleteEvent(event)) {
       this._deselect()
-    } else {
+    } else if (this._isOpen) {
       this._select(this._visibleOptionElements[0])
     }
   }
 
+  _clearQuery() {
+    this._fullQuery = ""
+    this.filter({ inputType: "deleteContentBackward" })
+  }
+
   get _isQueried() {
     return this._fullQuery.length > 0
   }

data/app/assets/javascripts/hw_combobox/models/combobox/options.js

@@ -30,4 +30,11 @@ Combobox.Options = Base => class extends Base {
   get _selectedOptionIndex() {
     return [ ...this._visibleOptionElements ].indexOf(this._selectedOptionElement)
   }
+
+  get _isUnjustifiablyBlank() {
+    const valueIsMissing = !this.hiddenFieldTarget.value
+    const noBlankOptionSelected = !this._selectedOptionElement
+
+    return valueIsMissing && noBlankOptionSelected
+  }
 }

data/app/assets/javascripts/hw_combobox/models/combobox/selection.js

@@ -18,9 +18,9 @@ Combobox.Selection = Base => class extends Base {
     this._resetOptions()
 
     if (option) {
-      this._markValid()
       this._autocompleteWith(option, { force: forceAutocomplete })
       this._commitSelection(option, { selected: true })
+      this._markValid()
     } else {
       this._markInvalid()
     }
@@ -33,6 +33,8 @@ Combobox.Selection = Base => class extends Base {
       this.hiddenFieldTarget.value = option.dataset.value
       option.scrollIntoView({ block: "nearest" })
     }
+
+    this._dispatchSelectionEvent({ isNew: false })
   }
 
   _markSelected(option, { selected }) {
@@ -46,15 +48,22 @@ Combobox.Selection = Base => class extends Base {
 
   _deselect() {
     const option = this._selectedOptionElement
+
     if (option) this._commitSelection(option, { selected: false })
+
     this.hiddenFieldTarget.value = null
     this._setActiveDescendant("")
+
+    if (!option) this._dispatchSelectionEvent({ isNew: false })
   }
 
   _selectNew() {
     this._resetOptions()
     this.hiddenFieldTarget.value = this._fullQuery
     this.hiddenFieldTarget.name = this.nameWhenNewValue
+    this._markValid()
+
+    this._dispatchSelectionEvent({ isNew: true })
   }
 
   _selectIndex(index) {
@@ -77,6 +86,11 @@ Combobox.Selection = Base => class extends Base {
       this._select(this._ensurableOption, { forceAutocomplete: true })
       this.filter({ inputType: "hw:lockInSelection" })
     }
+
+    if (this._isUnjustifiablyBlank) {
+      this._deselect()
+      this._clearQuery()
+    }
   }
 
   _setActiveDescendant(id) {

data/app/assets/javascripts/hw_combobox/models/combobox/toggle.js

@@ -72,7 +72,7 @@ Combobox.Toggle = Base => class extends Base {
   _collapse() {
     this._actingCombobox.setAttribute("aria-expanded", false) // needs to happen before resetting acting combobox
 
-    if (this.dialogTarget.open) {
+    if (this._dialogIsOpen) {
       this._closeInDialog()
     } else {
       this._closeInline()

data/app/assets/javascripts/hw_combobox/models/combobox/validity.js

@@ -4,29 +4,35 @@ Combobox.Validity = Base => class extends Base {
   _markValid() {
     if (this._valueIsInvalid) return
 
-    if (this.hasInvalidClass) {
-      this.comboboxTarget.classList.remove(this.invalidClass)
-    }
-
-    this.comboboxTarget.removeAttribute("aria-invalid")
-    this.comboboxTarget.removeAttribute("aria-errormessage")
+    this._forAllComboboxes(combobox => {
+      if (this.hasInvalidClass) {
+        combobox.classList.remove(this.invalidClass)
+      }
+
+      combobox.removeAttribute("aria-invalid")
+      combobox.removeAttribute("aria-errormessage")
+    })
   }
 
   _markInvalid() {
     if (this._valueIsValid) return
 
-    if (this.hasInvalidClass) {
-      this.comboboxTarget.classList.add(this.invalidClass)
-    }
+    this._forAllComboboxes(combobox => {
+      if (this.hasInvalidClass) {
+        combobox.classList.add(this.invalidClass)
+      }
 
-    this.comboboxTarget.setAttribute("aria-invalid", true)
-    this.comboboxTarget.setAttribute("aria-errormessage", `Please select a valid option for ${this.comboboxTarget.name}`)
+      combobox.setAttribute("aria-invalid", true)
+      combobox.setAttribute("aria-errormessage", `Please select a valid option for ${combobox.name}`)
+    })
   }
 
   get _valueIsValid() {
     return !this._valueIsInvalid
   }
 
+  // +_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
     return isRequiredAndEmpty

data/app/assets/javascripts/hw_combobox/models/combobox.js

@@ -4,6 +4,7 @@ import "hw_combobox/models/combobox/actors"
 import "hw_combobox/models/combobox/async_loading"
 import "hw_combobox/models/combobox/autocomplete"
 import "hw_combobox/models/combobox/dialog"
+import "hw_combobox/models/combobox/events"
 import "hw_combobox/models/combobox/filtering"
 import "hw_combobox/models/combobox/navigation"
 import "hw_combobox/models/combobox/new_options"

data/app/assets/stylesheets/hotwire_combobox.css

@@ -121,6 +121,10 @@
   text-overflow: ellipsis;
 }
 
+.hw-combobox__option--blank {
+  border-bottom: var(--hw-border-width--slim) solid var(--hw-border-color);
+}
+
 .hw-combobox__option:hover,
 .hw-combobox__option--selected {
   background-color: var(--hw-active-bg-color);

data/app/presenters/hotwire_combobox/component.rb

@@ -1,5 +1,7 @@
+require "securerandom"
+
 class HotwireCombobox::Component
-  attr_reader :async_src, :options, :dialog_label
+  attr_reader :options, :dialog_label
 
   def initialize \
       view, name,
@@ -148,7 +150,7 @@ class HotwireCombobox::Component
     end
 
     def fieldset_data
-      data.reverse_merge \
+      data.merge \
         async_id: canonical_id,
         controller: view.token_list("hw-combobox", data[:controller]),
         hw_combobox_expanded_value: open,
@@ -160,7 +162,8 @@ class HotwireCombobox::Component
         hw_combobox_prefilled_display_value: prefilled_display,
         hw_combobox_filterable_attribute_value: "data-filterable-as",
         hw_combobox_autocompletable_attribute_value: "data-autocompletable-as",
-        hw_combobox_selected_class: "hw-combobox__option--selected"
+        hw_combobox_selected_class: "hw-combobox__option--selected",
+        hw_combobox_invalid_class: "hw-combobox__input--invalid"
     end
 
     def prefilled_display
@@ -181,9 +184,13 @@ class HotwireCombobox::Component
       form&.object&.class&.reflect_on_association(association_name).present?
     end
 
+    def async_src
+      view.hw_uri_with_params @async_src, for_id: canonical_id, format: :turbo_stream
+    end
+
 
     def canonical_id
-      id || form&.field_id(name)
+      @canonical_id ||= id || form&.field_id(name) || SecureRandom.uuid
     end
 
 
@@ -219,19 +226,20 @@ class HotwireCombobox::Component
     end
 
     def input_data
-      combobox_attrs.fetch(:data, {}).reverse_merge! \
+      combobox_attrs.fetch(:data, {}).merge \
         action: "
           focus->hw-combobox#open
           input->hw-combobox#filter
           keydown->hw-combobox#navigate
           click@window->hw-combobox#closeOnClickOutside
-          focusin@window->hw-combobox#closeOnFocusOutside".squish,
+          focusin@window->hw-combobox#closeOnFocusOutside
+          turbo:before-stream-render@document->hw-combobox#rerouteListboxStreamToDialog".squish,
         hw_combobox_target: "combobox",
         async_id: canonical_id
     end
 
     def input_aria
-      combobox_attrs.fetch(:aria, {}).reverse_merge! \
+      combobox_attrs.fetch(:aria, {}).merge \
         controls: listbox_id,
         owns: listbox_id,
         haspopup: "listbox",

data/app/presenters/hotwire_combobox/listbox/option.rb

@@ -18,7 +18,7 @@ class HotwireCombobox::Listbox::Option
   end
 
   private
-    Data = Struct.new :id, :value, :display, :content, :filterable_as, :autocompletable_as, keyword_init: true
+    Data = Struct.new :id, :value, :display, :content, :blank, :filterable_as, :autocompletable_as, keyword_init: true
 
     attr_reader :option
 
@@ -26,13 +26,13 @@ class HotwireCombobox::Listbox::Option
       {
         id: id,
         role: :option,
-        class: "hw-combobox__option",
+        class: [ "hw-combobox__option", { "hw-combobox__option--blank": blank? } ],
         data: data
       }
     end
 
     def id
-      option.try(:id) || SecureRandom.uuid
+      @id ||= option.try(:id) || SecureRandom.uuid
     end
 
     def data
@@ -51,4 +51,8 @@ class HotwireCombobox::Listbox::Option
     def filterable_as
       option.try(:filterable_as) || option.try(:display)
     end
+
+    def blank?
+      option.try(:blank).present?
+    end
 end

data/app/views/hotwire_combobox/_next_page.turbo_stream.erb

@@ -2,5 +2,5 @@
 
 <%= turbo_stream.remove hw_pagination_frame_wrapper_id(for_id) %>
 <%= turbo_stream.append hw_listbox_id(for_id) do %>
-  <%= render "hotwire_combobox/pagination", for_id: for_id, src: hw_combobox_next_page_uri(src, next_page) %>
+  <%= render "hotwire_combobox/pagination", for_id: for_id, src: hw_combobox_next_page_uri(src, next_page, for_id) %>
 <% end %>

data/lib/hotwire_combobox/engine.rb

@@ -10,7 +10,7 @@ module HotwireCombobox
         unless HotwireCombobox.bypass_convenience_methods?
           module FormBuilderExtensions
             def combobox(*args, **kwargs)
-              @template.hw_combobox_tag *args, **kwargs.merge(form: self)
+              @template.hw_combobox_tag(*args, **kwargs.merge(form: self))
             end
           end
 

data/lib/hotwire_combobox/helper.rb

@@ -15,27 +15,32 @@ module HotwireCombobox
     end
     hw_alias :hw_combobox_style_tag
 
-    def hw_combobox_tag(name, options_or_src = [], render_in: {}, **kwargs)
-      options, src = hw_extract_options_and_src(options_or_src, render_in)
+    def hw_combobox_tag(name, options_or_src = [], render_in: {}, include_blank: nil, **kwargs)
+      options, src = hw_extract_options_and_src(options_or_src, render_in, include_blank)
       component = HotwireCombobox::Component.new self, name, options: options, async_src: src, **kwargs
 
       render "hotwire_combobox/combobox", component: component
     end
     hw_alias :hw_combobox_tag
 
-    def hw_combobox_options(options, render_in: {}, display: :to_combobox_display, **methods)
+    def hw_combobox_options(options, render_in: {}, include_blank: nil, display: :to_combobox_display, **methods)
       if options.first.is_a? HotwireCombobox::Listbox::Option
         options
       else
-        render_in_proc = ->(object) { render(**render_in.merge(object: object)) } if render_in.present?
-        hw_parse_combobox_options options, render_in: render_in_proc, **methods.merge(display: display)
+        render_in_proc = hw_render_in_proc(render_in) if render_in.present?
+
+        hw_parse_combobox_options(options, render_in: render_in_proc, **methods.merge(display: display)).tap do |options|
+          options.unshift(hw_blank_option(include_blank)) if include_blank.present?
+        end
       end
     end
     hw_alias :hw_combobox_options
 
-    def hw_paginated_combobox_options(options, for_id:, src: request.path, next_page: nil, render_in: {}, **methods)
-      this_page = render("hotwire_combobox/paginated_options", for_id: for_id, options: hw_combobox_options(options, render_in: render_in, **methods))
-      next_page = render("hotwire_combobox/next_page", for_id: for_id, src: src, next_page: next_page)
+    def hw_paginated_combobox_options(options, for_id: params[:for_id], src: request.path, next_page: nil, render_in: {}, include_blank: {}, **methods)
+      include_blank = params[:page] ? nil : include_blank
+      options = hw_combobox_options options, render_in: render_in, include_blank: include_blank, **methods
+      this_page = render "hotwire_combobox/paginated_options", for_id: for_id, options: options
+      next_page = render "hotwire_combobox/next_page", for_id: for_id, src: src, next_page: next_page
 
       safe_join [ this_page, next_page ]
     end
@@ -44,7 +49,7 @@ module HotwireCombobox
     alias_method :hw_async_combobox_options, :hw_paginated_combobox_options
     hw_alias :hw_async_combobox_options
 
-    protected # library use only
+    # private library use only
       def hw_listbox_id(id)
         "#{id}-hw-listbox"
       end
@@ -57,9 +62,13 @@ module HotwireCombobox
         "#{id}__hw_combobox_pagination"
       end
 
-      def hw_combobox_next_page_uri(uri, next_page)
+      def hw_combobox_next_page_uri(uri, next_page, for_id)
         if next_page
-          hw_uri_with_params uri, page: next_page, q: params[:q], format: :turbo_stream
+          hw_uri_with_params uri,
+            page: next_page,
+            q: params[:q],
+            for_id: for_id,
+            format: :turbo_stream
         end
       end
 
@@ -67,12 +76,19 @@ module HotwireCombobox
         params[:page] ? :append : :update
       end
 
-    private
-      def hw_extract_options_and_src(options_or_src, render_in)
-        if options_or_src.is_a? String
-          [ [], hw_uri_with_params(options_or_src, format: :turbo_stream) ]
+      def hw_blank_option(include_blank)
+        display, content = hw_extract_blank_display_and_content include_blank
+
+        HotwireCombobox::Listbox::Option.new display: display, content: content, value: "", blank: true
+      end
+
+      def hw_extract_blank_display_and_content(include_blank)
+        if include_blank.is_a? Hash
+          text = include_blank.delete(:text)
+
+          [ text, hw_render_in_proc(include_blank).(text) ]
         else
-          [ hw_combobox_options(options_or_src, render_in: render_in), nil ]
+          [ include_blank, include_blank ]
         end
       end
 
@@ -85,9 +101,23 @@ module HotwireCombobox
         url_or_path
       end
 
+    private
+      def hw_render_in_proc(render_in)
+        ->(object) { render(**render_in.reverse_merge(object: object)) }
+      end
+
+      def hw_extract_options_and_src(options_or_src, render_in, include_blank)
+        if options_or_src.is_a? String
+          [ [], options_or_src ]
+        else
+          [ hw_combobox_options(options_or_src, render_in: render_in, include_blank: include_blank), nil ]
+        end
+      end
+
       def hw_parse_combobox_options(options, render_in: nil, **methods)
         options.map do |option|
-          HotwireCombobox::Listbox::Option.new **hw_option_attrs_for(option, render_in: render_in, **methods)
+          HotwireCombobox::Listbox::Option.new \
+            **hw_option_attrs_for(option, render_in: render_in, **methods)
         end
       end
 
@@ -122,8 +152,43 @@ module HotwireCombobox
         if method_or_proc.is_a? Proc
           method_or_proc.call object
         else
-          object.public_send method_or_proc
+          hw_call_method object, method_or_proc
+        end
+      end
+
+      def hw_call_method(object, method)
+        if object.respond_to? method
+          object.public_send method
+        else
+          hw_raise_no_public_method_error object, method
         end
       end
+
+      def hw_raise_no_public_method_error(object, method)
+        if object.respond_to? method, true
+          header = "`#{object.class}` responds to `##{method}` but the method is not public."
+        else
+          header = "`#{object.class}` does not respond to `##{method}`."
+        end
+
+        if method.to_s == "to_combobox_display"
+          header << "\n\nThis method is used to determine how this option should appear in the combobox options list."
+        end
+
+        raise NoMethodError, <<~MSG
+          [ACTION NEEDED] – Message from HotwireCombobox:
+
+          #{header}
+
+          Please add this as a public method and return a string.
+
+          Example:
+            class #{object.class} < ApplicationRecord
+              def #{method}
+                name # or `title`, `to_s`, etc.
+              end
+            end
+        MSG
+      end
   end
 end

data/lib/hotwire_combobox/version.rb

@@ -1,3 +1,3 @@
 module HotwireCombobox
-  VERSION = "0.1.37"
+  VERSION = "0.1.39"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: hotwire_combobox
 version: !ruby/object:Gem::Version
-  version: 0.1.37
+  version: 0.1.39
 platform: ruby
 authors:
 - Jose Farias
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2024-03-03 00:00:00.000000000 Z
+date: 2024-03-07 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -52,8 +52,7 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '1.2'
-description: An autocomplete combobox implementation for Ruby on Rails apps using
-  Hotwire.
+description: An accessible autocomplete for Ruby on Rails apps using Hotwire.
 email:
 - jose@farias.mx
 executables: []
@@ -65,6 +64,8 @@ files:
 - Rakefile
 - app/assets/config/hw_combobox_manifest.js
 - app/assets/javascripts/controllers/hw_combobox_controller.js
+- app/assets/javascripts/hotwire_combobox.esm.js
+- app/assets/javascripts/hotwire_combobox.umd.js
 - app/assets/javascripts/hw_combobox/helpers.js
 - app/assets/javascripts/hw_combobox/models/combobox.js
 - app/assets/javascripts/hw_combobox/models/combobox/actors.js
@@ -72,6 +73,7 @@ files:
 - app/assets/javascripts/hw_combobox/models/combobox/autocomplete.js
 - app/assets/javascripts/hw_combobox/models/combobox/base.js
 - app/assets/javascripts/hw_combobox/models/combobox/dialog.js
+- app/assets/javascripts/hw_combobox/models/combobox/events.js
 - app/assets/javascripts/hw_combobox/models/combobox/filtering.js
 - app/assets/javascripts/hw_combobox/models/combobox/navigation.js
 - app/assets/javascripts/hw_combobox/models/combobox/new_options.js
@@ -97,13 +99,13 @@ files:
 - lib/hotwire_combobox/engine.rb
 - lib/hotwire_combobox/helper.rb
 - lib/hotwire_combobox/version.rb
-homepage: https://github.com/josefarias/hotwire_combobox
+homepage: https://hotwirecombobox.com/
 licenses:
 - MIT
 metadata:
-  homepage_uri: https://github.com/josefarias/hotwire_combobox
+  homepage_uri: https://hotwirecombobox.com/
   source_code_uri: https://github.com/josefarias/hotwire_combobox
-  changelog_uri: https://github.com/josefarias/hotwire_combobox
+  changelog_uri: https://github.com/josefarias/hotwire_combobox/releases
 post_install_message:
 rdoc_options: []
 require_paths:
@@ -112,7 +114,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '0'
+      version: 2.7.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
@@ -122,5 +124,5 @@ requirements: []
 rubygems_version: 3.5.6
 signing_key:
 specification_version: 4
-summary: Autocomplete for Rails apps using Hotwire
+summary: Accessible Autocomplete for Rails apps
 test_files: []