hotwire_combobox 0.1.13 → 0.1.15

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4f868770ad8adc907437ea9d7c0f2a9550b848a1ab0ca3dddb3592aacd4ce75a
-  data.tar.gz: 6d1932f507fd650da412d2bacc1d6dc01faed6b8d3f2230fe9df1251b66baaf9
+  metadata.gz: aa358f06557f2f70b072650e12b11a270fc3afa36addc8e73820105ea7383da5
+  data.tar.gz: e35a86d210a02af308614ebdb983a3af69026824ea327fc0f1e353a9612bf807
 SHA512:
-  metadata.gz: 31127e0fa02f231b604b10b25f5ff514b33065814a3283ae4d6c338ab59835ef8696e19496f867bec8ddc564066a1b5af2c6c7fa1a88e88507c1943bb741f6ce
-  data.tar.gz: 77070143486b82fa1b0d3179e1fb74fe43300988a6a6c2c3654dc883a06d1b4b3a9e069e10d8e71f543ee72ee6a242cba42ef7e595e6ba377a530e73954a1aca
+  metadata.gz: 011a0b91f679374998444836f121bdede29a86fc8d4c905dd5f0988e41b834be84044fd9cd9a1cc91e88d3bd7812f16b727d9144764968fe07bb44b6d8e06a66
+  data.tar.gz: 7ff6b81587de0d53496fcb008cffa0c9ff4df8d19d1f9e8583b7becba82234252b60a57cf4cc258fb5b633a9e5d90821991a14bcb341732a59454a8b50b996d2

data/README.md

@@ -1,115 +1,21 @@
-# HotwireCombobox
+<p align="center">
+  <img src="docs/assets/images/logo.png" height=150>
+</p>
 
-A combobox implementation for Ruby on Rails apps running on Hotwire.
+# Autocomplete for Rails apps using Hotwire
 
-> [!WARNING]
-> This gem is pre-release software. It's not ready for production use yet and the API is subject to change.
+[![CI Tests](https://github.com/josefarias/hotwire_combobox/actions/workflows/ci_tests.yml/badge.svg)](https://github.com/josefarias/hotwire_combobox/actions/workflows/ci_tests.yml) [![Gem Version](https://badge.fury.io/rb/hotwire_combobox.svg)](https://badge.fury.io/rb/hotwire_combobox)
 
-## Installation
-
-Add this line to your application's Gemfile:
-
-```ruby
-gem "hotwire_combobox"
-```
-
-And then execute:
-```bash
-$ bundle
-```
-
-## Output
-
-This is the stripped-down output of a combobox generated with HotwireCombobox. Understanding it will be helpful in getting the most out of this library.
-
-```html
-<fieldset class="hw-combobox">
-  <input type="hidden" name="provided_name">
-
-  <input type="text" role="combobox">
-
-  <ul role="listbox">
-    <li role="option">Provided Option 1 Content</li>
-    <li role="option">Provided Option 2 Content</li>
-    <!-- ... -->
-  </ul>
-</fieldset>
-```
-
-The `<ul role="listbox">` element is what gets shown when the combobox is open.
-
-The library uses stimulus to add interactivity to the combobox and sync the input element's value with the hidden input element.
-
-The hidden input's value is what ultimately gets sent to the server when submitting a form containing the combobox.
-
-## Usage
-
-### Options
-
-Options are what you see when you open the combobox.
 
-The `options` argument takes an array of any objects which respond to:
+> [!IMPORTANT]
+> We need your help to finalize this gem's first major release. Please use it in your apps and report any issues.
 
-| Method             | Description                                                                                                                                |
-|--------------------|--------------------------------------------------------------------------------------------------------------------------------------------|
-| id                 | Used as the option element's `id` attribute. Only required if `value` is not provided.                                                     |
-| value              | Used to populate the input element's `value` attribute. Falls back to calling `id` on the object if not provided.                          |
-| content            | **Supports HTML** <br> Used as the option element's content. Falls back to calling `display` on the object if not provided.                |
-| filterable_as      | Used to filter down the options when the user types into the input element. Falls back to calling `display` on the object if not provided. |
-| autocompletable_as | Used to autocomplete the input element when the user types into it. Falls back to calling `display` on the object if not provided.         |
-| display            | Used as a short-hand for other attributes. See the rest of the list for details.                                                           |
-
-You can use the `combobox_options` helper to create an array of option objects which respond to the above methods:
-
-```ruby
-combobox_options [
-  { value: "AL", display: "Alabama" },
-  { value: "AK", display: "Alaska" },
-  { value: "AZ", display: "Arizona" },
-  # ...
-]
-```
-
-### Styling
-
-The combobox is completely unstyled by default. You can use the following CSS selectors to style the combobox:
-
-* `.hw-combobox` targets the `<fieldset>` element used to wrap the whole component.
-* `.hw-combobox [role="combobox"]` targets the input element.
-* `.hw-combobox [role="listbox"]` targets the listbox which encloses all option elements.
-* `.hw-combobox [role="option"]` targets each option element inside the listbox.
-
-Additionally, you can pass the following [Stimulus class values](https://stimulus.hotwired.dev/reference/css-classes) to `combobox_tag`:
-
-* `data-hw-combobox-selected-class`: The class to apply to the selected option while shown inside an open listbox.
-* `data-hw-combobox-invalid-class`: The class to apply to the input element when the current value is invalid.
-
-### Validity
-
-Unless `name_when_new` is passed, the hidden input can't have a value that's not in the list of options.
-
-If a nonexistent value is typed into the combobox, the value of the hidden input will be set empty.
-
-The only way a value can be marked as invalid is if the field is required and empty after having interacted with the combobox.
-
-The library will mark the element as invalid but this won't be noticeable in the UI unless you specify styles for the invalid state. See the [Styling](#styling) section for details.
-
-> [!CAUTION]
-> Bad actors can still submit invalid values to the server. You should always validate the input on the server side.
-
-### Naming Conflicts
-
-If your application has naming conflicts with this gem, the following config will turn:
+## Installation
 
-* `#combobox_tag` into `#hw_combobox_tag`
-* `#combobox_options` into `#hw_combobox_options`
+Add this line to your application's Gemfile and run `bundle install`:
 
 ```ruby
-# config/initializers/hotwire_combobox.rb
-
-HotwireCombobox.setup do |config|
-  config.bypass_convenience_methods = true
-end
+gem "hotwire_combobox"
 ```
 
 ## Contributing

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

@@ -30,7 +30,8 @@ export default class HwComboboxController extends Concerns(...concerns) {
     "dialogListbox",
     "handle",
     "hiddenField",
-    "listbox"
+    "listbox",
+    "paginationFrame"
   ]
 
   static values = {
@@ -41,6 +42,7 @@ export default class HwComboboxController extends Concerns(...concerns) {
     filterableAttribute: String,
     nameWhenNew: String,
     originalName: String,
+    prefilledDisplay: String,
     smallViewportMaxWidth: String
   }
 
@@ -66,4 +68,8 @@ export default class HwComboboxController extends Concerns(...concerns) {
       this._collapse()
     }
   }
+
+  paginationFrameTargetConnected() {
+    this._preselectOption()
+  }
 }

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

@@ -14,7 +14,7 @@ Combobox.Dialog = Base => class extends Base {
   }
 
   _moveArtifactsToDialog() {
-    this.dialogComboboxTarget.value = this.actingCombobox.value
+    this.dialogComboboxTarget.value = this._actingCombobox.value
 
     this._actingCombobox = this.dialogComboboxTarget
     this._actingListbox = this.dialogListboxTarget
@@ -23,7 +23,7 @@ Combobox.Dialog = Base => class extends Base {
   }
 
   _moveArtifactsInline() {
-    this.comboboxTarget.value = this.actingCombobox.value
+    this.comboboxTarget.value = this._actingCombobox.value
 
     this._actingCombobox = this.comboboxTarget
     this._actingListbox = this.listboxTarget
@@ -32,9 +32,11 @@ Combobox.Dialog = Base => class extends Base {
   }
 
   _resizeDialog = () => {
-    const fullHeight = window.innerHeight
-    const viewportHeight = window.visualViewport.height
-    this.dialogTarget.style.setProperty("--hw-dialog-bottom-padding", `${fullHeight - viewportHeight}px`)
+    if (window.visualViewport) {
+      const fullHeight = window.innerHeight
+      const viewportHeight = window.visualViewport.height
+      this.dialogTarget.style.setProperty("--hw-dialog-bottom-padding", `${fullHeight - viewportHeight}px`)
+    }
   }
 
   // After closing a dialog, focus returns to the last focused element.

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

@@ -10,9 +10,9 @@ Combobox.Options = Base => class extends Base {
   _isValidNewOption(query, { ignoreAutocomplete = false } = {}) {
     const typedValue = this._actingCombobox.value
     const autocompletedValue = this._visibleOptionElements[0]?.getAttribute(this.autocompletableAttributeValue)
-    const insufficentAutocomplete = !autocompletedValue || !startsWith(autocompletedValue, typedValue)
+    const insufficientAutocomplete = !autocompletedValue || !startsWith(autocompletedValue, typedValue)
 
-    return query.length > 0 && this._allowNew && (ignoreAutocomplete || insufficentAutocomplete)
+    return query.length > 0 && this._allowNew && (ignoreAutocomplete || insufficientAutocomplete)
   }
 
   get _allowNew() {

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

@@ -8,8 +8,8 @@ Combobox.Selection = Base => class extends Base {
   }
 
   _connectSelection() {
-    if (this.hiddenFieldTarget.value) {
-      this._selectOptionByValue(this.hiddenFieldTarget.value)
+    if (this.hasPrefilledDisplayValue) {
+      this._actingCombobox.value = this.prefilledDisplayValue
     }
   }
 
@@ -17,8 +17,6 @@ Combobox.Selection = Base => class extends Base {
     this._resetOptions()
 
     if (option) {
-      if (this.hasSelectedClass) option.classList.add(this.selectedClass)
-
       this._markValid()
       this._maybeAutocompleteWith(option, { force })
       this._commitSelection(option, { selected: true })
@@ -28,21 +26,27 @@ Combobox.Selection = Base => class extends Base {
   }
 
   _commitSelection(option, { selected }) {
-    option?.setAttribute("aria-selected", selected)
-    option?.scrollIntoView({ block: "nearest" })
+    this._markSelected(option, { selected })
 
     if (selected) {
-      this.hiddenFieldTarget.value = option?.dataset.value
+      this.hiddenFieldTarget.value = option.dataset.value
+      option.scrollIntoView({ block: "nearest" })
     } else {
       this.hiddenFieldTarget.value = null
     }
   }
 
+  _markSelected(option, { selected }) {
+    if (this.hasSelectedClass) {
+      option.classList.toggle(this.selectedClass, selected)
+    }
+
+    option.setAttribute("aria-selected", selected)
+  }
+
   _deselect() {
     const option = this._selectedOptionElement
-
-    if (this.hasSelectedClass) option?.classList.remove(this.selectedClass)
-    this._commitSelection(option, { selected: false })
+    if (option) this._commitSelection(option, { selected: false })
   }
 
   _selectNew(query) {
@@ -56,7 +60,17 @@ Combobox.Selection = Base => class extends Base {
     this._select(option, { force: true })
   }
 
-  _selectOptionByValue(value) {
-    this._allOptions.find(option => option.dataset.value === value)?.click()
+  _preselectOption() {
+    if (this._hasValueButNoSelection && this._allOptions.length < 100) {
+      const option = this._allOptions.find(option => {
+        return option.dataset.value === this.hiddenFieldTarget.value
+      })
+
+      if (option) this._markSelected(option, { selected: true })
+    }
+  }
+
+  get _hasValueButNoSelection() {
+    return this.hiddenFieldTarget.value && !this._selectedOptionElement
   }
 }

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

@@ -21,8 +21,11 @@ Combobox.Toggle = Base => class extends Base {
     }
   }
 
-  closeOnClickOutside({ target }) {
+  closeOnClickOutside(event) {
+    const target = event.target
+
     if (this.element.contains(target) && !this._isDialogDismisser(target)) return
+    if (this._withinElementBounds(event)) return
 
     this.close()
   }
@@ -35,6 +38,17 @@ Combobox.Toggle = Base => class extends Base {
     this.close()
   }
 
+  // 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`
+  // as an alternative to check whether the click is legitimate.
+  _withinElementBounds(event) {
+    const { left, right, top, bottom } = this.element.getBoundingClientRect()
+    const { clientX, clientY } = event
+
+    return clientX >= left && clientX <= right && clientY >= top && clientY <= bottom
+  }
+
   _ensureSelection() {
     if (!this._isValidNewOption(this._actingCombobox.value, { ignoreAutocomplete: true })) {
       this._select(this._selectedOptionElement, { force: true })
@@ -49,7 +63,9 @@ Combobox.Toggle = Base => class extends Base {
     return target.closest("dialog") && target.role != "combobox"
   }
 
-  async _expand() {
+  _expand() {
+    if (this._preselectOnExpansion) this._preselectOption()
+
     if (this._autocompletesList && this._smallViewport) {
       this._openInDialog()
     } else {
@@ -101,4 +117,8 @@ Combobox.Toggle = Base => class extends Base {
   get _isOpen() {
     return this.expandedValue
   }
+
+  get _preselectOnExpansion() {
+    return !this._isAsync // async comboboxes preselect based on callbacks
+  }
 }

data/app/helpers/hotwire_combobox/helper.rb

@@ -15,10 +15,9 @@ module HotwireCombobox
     end
     hw_alias :hw_combobox_style_tag
 
-    def hw_combobox_tag(*args, async_src: nil, options: [], render_in: {}, **kwargs)
-      options = hw_combobox_options options, render_in: render_in
-      src = hw_uri_with_params async_src, format: :turbo_stream
-      component = HotwireCombobox::Component.new self, *args, options: options, async_src: src, **kwargs
+    def hw_combobox_tag(name, options_or_src = [], render_in: {}, **kwargs)
+      options, src = hw_extract_options_and_src(options_or_src, render_in)
+      component = HotwireCombobox::Component.new self, name, options: options, async_src: src, **kwargs
 
       render "hotwire_combobox/combobox", component: component
     end
@@ -39,20 +38,32 @@ module HotwireCombobox
     end
     hw_alias :hw_combobox_options
 
-    def hw_paginated_combobox_options(options, for_id:, src:, next_page:, render_in: {}, **methods)
-      this_page = render("hotwire_combobox/paginated_options", for_id: for_id, options: hw_combobox_options(options, render_in: render_in, **methods), format: :turbo_stream)
-      next_page = render("hotwire_combobox/next_page", src: src, next_page: next_page, format: :turbo_stream)
+    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)
 
       safe_join [ this_page, next_page ]
     end
     hw_alias :hw_paginated_combobox_options
 
-    def hw_listbox_options_id(id)
-      "#{id}-hw-listbox__options"
-    end
-    hw_alias :hw_listbox_options_id
+    protected # library use only
+      def hw_listbox_options_id(id)
+        "#{id}-hw-listbox__options"
+      end
+
+      def hw_pagination_frame_id(id)
+        "#{id}__hw_combobox_pagination"
+      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) ]
+        else
+          [ hw_combobox_options(options_or_src, render_in: render_in), nil ]
+        end
+      end
+
       def hw_uri_with_params(url_or_path, **params)
         URI.parse(url_or_path).tap do |url_or_path|
           query = URI.decode_www_form(url_or_path.query || "").to_h.merge(params)

data/app/presenters/hotwire_combobox/component.rb

@@ -1,23 +1,29 @@
 class HotwireCombobox::Component
   attr_reader :async_src, :options, :dialog_label
 
-  def initialize(
-      view, name, value = nil,
-      autocomplete: :both,
-      id: nil,
-      form: nil,
-      name_when_new: nil,
-      open: false,
-      small_width: "640px",
-      async_src: nil,
-      dialog_label: nil,
-      options: [], data: {}, input: {}, **rest)
-    @combobox_attrs = input.reverse_merge(rest).with_indifferent_access
-
+  def initialize \
+      view, name,
+      association_name: nil,
+      async_src:        nil,
+      autocomplete:     :both,
+      data:             {},
+      dialog_label:     nil,
+      form:             nil,
+      id:               nil,
+      input:            {},
+      name_when_new:    nil,
+      open:             false,
+      options:          [],
+      small_width:      "640px",
+      value:            nil,
+      **rest
     @view, @autocomplete, @id, @name, @value, @form, @async_src,
     @name_when_new, @open, @data, @small_width, @options, @dialog_label =
       view, autocomplete, id, name, value, form, async_src,
       name_when_new, open, data, small_width, options, dialog_label
+
+    @combobox_attrs = input.reverse_merge(rest).with_indifferent_access
+    @association_name = association_name || infer_association_name
   end
 
   def fieldset_attrs
@@ -125,15 +131,23 @@ class HotwireCombobox::Component
   end
 
   def pagination_attrs
-    { src: async_src }
+    { for_id: hidden_field_id, src: async_src }
   end
 
   private
     attr_reader :view, :autocomplete, :id, :name, :value, :form,
-      :name_when_new, :open, :data, :combobox_attrs, :small_width
+      :name_when_new, :open, :data, :combobox_attrs, :small_width,
+      :association_name
+
+    def infer_association_name
+      if name.to_s.include?("_id")
+        name.to_s.sub(/_id\z/, "")
+      end
+    end
 
     def fieldset_data
       data.reverse_merge \
+        pagination_id: hidden_field_id,
         controller: view.token_list("hw-combobox", data[:controller]),
         hw_combobox_expanded_value: open,
         hw_combobox_name_when_new_value: name_when_new,
@@ -141,11 +155,30 @@ class HotwireCombobox::Component
         hw_combobox_autocomplete_value: autocomplete,
         hw_combobox_small_viewport_max_width_value: small_width,
         hw_combobox_async_src_value: async_src,
+        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"
     end
 
+    def prefilled_display
+      if async_src && associated_object
+        associated_object.to_combobox_display
+      elsif value
+        options.find { |option| option.value == value }&.content
+      end
+    end
+
+    def associated_object
+      @associated_object ||= if association_exists?
+        form.object.public_send association_name
+      end
+    end
+
+    def association_exists?
+      form&.object&.class&.reflect_on_association(association_name).present?
+    end
+
 
     def hidden_field_id
       id || form&.field_id(name)
@@ -180,7 +213,8 @@ class HotwireCombobox::Component
           keydown->hw-combobox#navigate
           click@window->hw-combobox#closeOnClickOutside
           focusin@window->hw-combobox#closeOnFocusOutside".squish,
-        hw_combobox_target: "combobox"
+        hw_combobox_target: "combobox",
+        pagination_id: hidden_field_id
     end
 
     def input_aria

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

@@ -3,8 +3,16 @@ class HotwireCombobox::Listbox::Option
     @option = option.is_a?(Hash) ? Data.new(**option) : option
   end
 
-  def render_in(view_context)
-    view_context.tag.li content, **options
+  def render_in(view)
+    view.tag.li content, **options
+  end
+
+  def value
+    option.try(:value) || option.id
+  end
+
+  def content
+    option.try(:content) || option.try(:display)
   end
 
   private
@@ -12,10 +20,6 @@ class HotwireCombobox::Listbox::Option
 
     attr_reader :option
 
-    def content
-      option.try(:content) || option.try(:display)
-    end
-
     def options
       {
         id: id,
@@ -45,8 +49,4 @@ class HotwireCombobox::Listbox::Option
     def autocompletable_as
       option.try(:autocompletable_as) || option.try(:display)
     end
-
-    def value
-      option.try(:value) || option.id
-    end
 end

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

@@ -1,5 +1,5 @@
-<%# locals: (next_page:, src:) -%>
+<%# locals: (for_id:, next_page:, src:) -%>
 
-<%= turbo_stream.replace :hotwire_combobox_pagination do %>
-  <%= render "hotwire_combobox/pagination", src: hw_combobox_next_page_uri(src, next_page) %>
+<%= turbo_stream.replace hw_pagination_frame_id(for_id) do %>
+  <%= render "hotwire_combobox/pagination", for_id: for_id, src: hw_combobox_next_page_uri(src, next_page) %>
 <% end %>

data/app/views/hotwire_combobox/_pagination.html.erb

@@ -1,3 +1,4 @@
-<%# locals: (src:) -%>
+<%# locals: (for_id:, src:) -%>
 
-<%= turbo_frame_tag :hotwire_combobox_pagination, src: src, loading: :lazy %>
+<%= turbo_frame_tag hw_pagination_frame_id(for_id), src: src, loading: :lazy,
+      data: { hw_combobox_target: "paginationFrame" } %>

data/lib/hotwire_combobox/engine.rb

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

data/lib/hotwire_combobox/version.rb

@@ -1,3 +1,3 @@
 module HotwireCombobox
-  VERSION = "0.1.13"
+  VERSION = "0.1.15"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: hotwire_combobox
 version: !ruby/object:Gem::Version
-  version: 0.1.13
+  version: 0.1.15
 platform: ruby
 authors:
 - Jose Farias
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2024-01-31 00:00:00.000000000 Z
+date: 2024-02-03 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -80,7 +80,7 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: 0.0.11
-description: A combobox implementation for Ruby on Rails apps running on Hotwire.
+description: A combobox implementation for Ruby on Rails apps using Hotwire.
 email:
 - jose@farias.mx
 executables: []
@@ -149,5 +149,5 @@ requirements: []
 rubygems_version: 3.4.18
 signing_key:
 specification_version: 4
-summary: A combobox implementation for Ruby on Rails apps running on Hotwire
+summary: Autocomplete for Rails apps using Hotwire
 test_files: []