hotwire_combobox 0.1.5 → 0.1.7

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 99cf62ece0c5bf6182ab759cbab18c4f561c22215babfdf00eed7329f5797eb9
-  data.tar.gz: dcca7ddceca4e3b7f840716bf789b641d62ffaea589b9bf86da39e4445c6a9cf
+  metadata.gz: 01a08bf7fdf486660daebfd29960a62c8435ad87939a8963d805967872ffca4d
+  data.tar.gz: 2ca73e1f2693d9adf838463187bd2c79867b8086d59beea0bb699c12a49e8507
 SHA512:
-  metadata.gz: fb5f896deae2dde8b36d91d7eaee8ec27abfd00b07a94d64c094d8da865e4cd2723c6349a9fe49296f8e20cde933ed698f2f64b1e65909ed1fca889517213773
-  data.tar.gz: 31ce6c44d91feb634fd16349ed0f89ab58975a3a6744f36c6f05f6ea207d6caa1317267b1892ae602b48daf5f4182a3908681c7746e05bd19ae9b489bcf9696b
+  metadata.gz: d505fbfb95060cb730a5533dd4d850f4691391a94f4849fd12017f1ebca12df55a12871d29f784e55dccbe2a8512c007c7516f960225e1a13f6ab74d5d8a3431
+  data.tar.gz: 6792bae8acf5f9051f2a5605f95e86d7e3b755d323e47e9dff65dc0a02eb27771fa145d2129b246518711e4b050cc2e3cba8b03e83b581ea519c31c30a2ad5d6

data/README.md

@@ -1,14 +1,15 @@
-# Hotwire Combobox
-Short description and motivation.
+# HotwireCombobox
 
-## Usage
-How to use my plugin.
+A combobox implementation for Ruby on Rails apps running on Hotwire.
+
+> [!WARNING]
+> This gem is pre-release software. It's not ready for production use yet and the API is subject to change.
 
 ## Installation
 Add this line to your application's Gemfile:
 
 ```ruby
-gem "hotwire_combobox", require: "combobox"
+gem "hotwire_combobox"
 ```
 
 And then execute:
@@ -16,11 +17,97 @@ And then execute:
 $ bundle
 ```
 
-Or install it yourself as:
-```bash
-$ gem install hotwire_combobox
+## 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:
+
+| Attribute                        | Description                                                                                                                                | Required? |
+|----------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------|-------------------|
+| `id`                             | Used as the option element's `id` attribute. Only required if `value` is not provided.                                                     | Required*         |
+| `value`                          | Used to populate the input element's `value` attribute. Falls back to calling `id` on the object if not provided.                          | Optional          |
+| `content` <br> **Supports HTML** | Used as the option element's content. Falls back to calling `display` on the object if not provided.                                       | Optional          |
+| `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. | Optional          |
+| `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.         | Optional          |
+| `display`                        | Used as a short-hand for other attributes. See the rest of the list for details.                                                           | Optional          |
+
+
+> [!NOTE]
+> The `id` attribute is required only if `value` is not provided.
+
+
+The gem provides a `HotwireCombobox::Option` class which you can use to create options:
+
+```ruby
+@states = [
+  HotwireCombobox::Option.new(value: "AL", display: "Alabama"),
+  # ...
+]
+```
+
+If you feel `HotwireCombobox::Option` is too verbose, you can also use the `hwbox_options` helper. It will destructure the hashes you pass to it and create `HotwireCombobox::Option` instances for you:
+
+```ruby
+@states = hwbox_options [
+  { value: "AL", display: "Alabama" },
+  # ...
+]
 ```
 
+### 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 `hw_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
+
+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.
+
 ## Contributing
 
 ### Setup
@@ -44,8 +131,10 @@ $ bin/rails s
 
 ### Releasing
 
-1. Bump the version in `lib/hotwire_combobox/version.rb`
-2. Run `bundle exec rake release`
+1. Bump the version in `lib/hotwire_combobox/version.rb` (e.g. `VERSION = "0.1.0"`)
+2. Bump the version in `Gemfile.lock` (e.g. `hotwire_combobox (0.1.0)`)
+3. Commit the change (e.g. `git commit -am "Bump to 0.1.0"`)
+4. Run `bundle exec rake release`
 
 ## License
 The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/app/helpers/hotwire_combobox/helper.rb

@@ -0,0 +1,99 @@
+module HotwireCombobox
+  module Helper
+    def hwbox_option(...)
+      HotwireCombobox::Option.new(...)
+    end
+
+    def hwbox_options(options)
+      options.map { |option| hwbox_option(**option) }
+    end
+
+    def hw_combobox_tag(name, value = nil, form: nil, options: [], data: {}, input: {}, **attrs)
+      value_field_attrs = {}.tap do |h|
+        h[:id] = default_hw_combobox_value_field_id attrs, form, name
+        h[:name] = default_hw_combobox_value_field_name form, name
+        h[:data] = default_hw_combobox_value_field_data
+        h[:value] = form&.object&.public_send(name) || value
+      end
+
+      attrs[:type] ||= :text
+      attrs[:role] = :combobox
+      attrs[:id] = hw_combobox_id value_field_attrs[:id]
+      attrs[:data] = default_hw_combobox_data input.fetch(:data, {})
+      attrs[:aria] = default_hw_combobox_aria value_field_attrs, input.fetch(:aria, {})
+
+      render "hotwire_combobox/combobox", options: options,
+        attrs: attrs, value_field_attrs: value_field_attrs,
+        listbox_id: hw_combobox_listbox_id(value_field_attrs[:id]),
+        parent_data: default_hw_combobox_parent_data(attrs, data)
+    end
+
+    def hw_listbox_option_id(option)
+      option.try(:id)
+    end
+
+    def hw_listbox_option_value(option)
+      option.try(:value) || option.id
+    end
+
+    def hw_listbox_option_content(option)
+      option.try(:content) || option.try(:display)
+    end
+
+    def hw_listbox_option_filterable_as(option)
+      option.try(:filterable_as) || option.try(:display)
+    end
+
+    def hw_listbox_option_autocompletable_as(option)
+      option.try(:autocompletable_as) || option.try(:display)
+    end
+
+    private
+      def default_hw_combobox_value_field_id(attrs, form, name)
+        attrs.delete(:id) || form&.field_id(name)
+      end
+
+      def default_hw_combobox_value_field_name(form, name)
+        form&.field_name(name) || name
+      end
+
+      def default_hw_combobox_value_field_data
+        { "hw-combobox-target": "valueField" }
+      end
+
+      def default_hw_combobox_data(data)
+        data.reverse_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,
+          "hw-combobox-target": "combobox"
+      end
+
+      def default_hw_combobox_aria(attrs, aria)
+        aria.reverse_merge! \
+          "controls": hw_combobox_listbox_id(attrs[:id]),
+          "owns": hw_combobox_listbox_id(attrs[:id]),
+          "haspopup": "listbox",
+          "autocomplete": "both"
+      end
+
+      def default_hw_combobox_parent_data(attrs, data)
+        data.reverse_merge! \
+          "controller": token_list("hw-combobox", data.delete(:controller)),
+          "hw-combobox-expanded-value": attrs.delete(:open),
+          "hw-combobox-filterable-attribute-value": "data-filterable-as",
+          "hw-combobox-autocompletable-attribute-value": "data-autocompletable-as"
+      end
+
+      def hw_combobox_id(id)
+        "#{id}-hw-combobox"
+      end
+
+      def hw_combobox_listbox_id(id)
+        "#{id}-hw-listbox"
+      end
+  end
+end

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

@@ -0,0 +1,21 @@
+<%= tag.fieldset class: "hw-combobox", data: parent_data do %>
+  <%= hidden_field_tag value_field_attrs.delete(:name),
+        value_field_attrs.delete(:value), **value_field_attrs %>
+
+  <%= tag.input **attrs %>
+
+  <%= tag.ul id: listbox_id, hidden: "", role: :listbox,
+        data: { "hw-combobox-target": "listbox" } do |ul| %>
+    <% options.each do |option| %>
+      <%= tag.li hw_listbox_option_content(option),
+            id: hw_listbox_option_id(option),
+            role: :option,
+            style: "cursor: pointer;",
+            data: {
+              "action": "click->hw-combobox#selectOption",
+              "filterable-as": hw_listbox_option_filterable_as(option),
+              "autocompletable-as": hw_listbox_option_autocompletable_as(option),
+              "value": hw_listbox_option_value(option) } %>
+    <% end %>
+  <% end %>
+<% end %>

data/lib/hotwire_combobox/engine.rb

@@ -0,0 +1,15 @@
+module HotwireCombobox
+  class Engine < ::Rails::Engine
+    isolate_namespace HotwireCombobox
+
+    initializer "hotwire_combobox.view_helpers" do
+      ActiveSupport.on_load :action_controller do
+        helper HotwireCombobox::Helper
+      end
+    end
+
+    initializer "hotwire_combobox.importmap", before: "importmap" do |app|
+      app.config.importmap.paths << Engine.root.join("config/importmap.rb")
+    end
+  end
+end

data/lib/hotwire_combobox/version.rb

@@ -0,0 +1,3 @@
+module HotwireCombobox
+  VERSION = "0.1.7"
+end

data/lib/hotwire_combobox.rb

@@ -0,0 +1,6 @@
+require "hotwire_combobox/version"
+require "hotwire_combobox/engine"
+
+module HotwireCombobox
+  Option = Struct.new(:id, :value, :display, :content, :filterable_as, :autocompletable_as)
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: hotwire_combobox
 version: !ruby/object:Gem::Version
-  version: 0.1.5
+  version: 0.1.7
 platform: ruby
 authors:
 - Jose Farias
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2023-10-05 00:00:00.000000000 Z
+date: 2023-12-10 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -62,16 +62,16 @@ files:
 - MIT-LICENSE
 - README.md
 - Rakefile
-- app/assets/javascripts/combobox_application.js
 - app/assets/javascripts/controllers/application.js
-- app/assets/javascripts/controllers/combobox_controller.js
+- app/assets/javascripts/controllers/hw_combobox_controller.js
 - app/assets/javascripts/controllers/index.js
-- app/helpers/combobox/helper.rb
-- app/views/combobox/_combobox.html.erb
+- app/assets/javascripts/hotwire_combobox_application.js
+- app/helpers/hotwire_combobox/helper.rb
+- app/views/hotwire_combobox/_combobox.html.erb
 - config/importmap.rb
-- lib/combobox.rb
-- lib/combobox/engine.rb
-- lib/combobox/version.rb
+- lib/hotwire_combobox.rb
+- lib/hotwire_combobox/engine.rb
+- lib/hotwire_combobox/version.rb
 homepage: https://github.com/josefarias/hotwire_combobox
 licenses:
 - MIT

data/app/helpers/combobox/helper.rb

@@ -1,75 +0,0 @@
-module Combobox
-  module Helper
-    def combobox_tag(name, value = nil, form: nil, options: [], data: {}, input: {}, **attrs)
-      value_field_attrs = {}.tap do |h|
-        h[:id] = default_combobox_value_field_id attrs, form, name
-        h[:name] = default_combobox_value_field_name form, name
-        h[:data] = default_combobox_value_field_data
-        h[:value] = form&.object&.public_send(name) || value
-      end
-
-      attrs[:type] ||= :text
-      attrs[:role] = :combobox
-      attrs[:id] = combobox_id(value_field_attrs[:id])
-      attrs[:data] = default_combobox_data input.fetch(:data, {})
-      attrs[:aria] = default_combobox_aria value_field_attrs, input.fetch(:aria, {})
-
-      render "combobox/combobox", options: options,
-        attrs: attrs, value_field_attrs: value_field_attrs,
-        listbox_id: combobox_listbox_id(value_field_attrs[:id]),
-        parent_data: default_combobox_parent_data(attrs, data)
-    end
-
-    def value_for_listbox_option(option)
-      option.try(:value) || option.id
-    end
-
-    private
-      def default_combobox_value_field_id(attrs, form, name)
-        attrs.delete(:id) || form&.field_id(name)
-      end
-
-      def default_combobox_value_field_name(form, name)
-        form&.field_name(name) || name
-      end
-
-      def default_combobox_value_field_data
-        { "combobox-target": "valueField" }
-      end
-
-      def default_combobox_data(data)
-        data.reverse_merge! \
-          "action": "
-            focus->combobox#open
-            input->combobox#filter
-            keydown->combobox#navigate
-            click@window->combobox#closeOnClickOutside
-            focusin@window->combobox#closeOnFocusOutside".squish,
-          "combobox-target": "combobox"
-      end
-
-      def default_combobox_aria(attrs, aria)
-        aria.reverse_merge! \
-          "controls": combobox_listbox_id(attrs[:id]),
-          "owns": combobox_listbox_id(attrs[:id]),
-          "haspopup": "listbox",
-          "autocomplete": "both"
-      end
-
-      def default_combobox_parent_data(attrs, data)
-        data.reverse_merge! \
-          "controller": token_list(:combobox, data.delete(:controller)),
-          "combobox-expanded-value": attrs.delete(:open),
-          "combobox-filterable-attribute-value": "data-filterable-as",
-          "combobox-autocompletable-attribute-value": "data-autocompletable-as"
-      end
-
-      def combobox_id(id)
-        "#{id}-combobox"
-      end
-
-      def combobox_listbox_id(id)
-        "#{id}-listbox"
-      end
-  end
-end

data/app/views/combobox/_combobox.html.erb

@@ -1,19 +0,0 @@
-<%= tag.fieldset class: "hotwire-combobox", data: parent_data do %>
-  <%= hidden_field_tag value_field_attrs.delete(:name),
-        value_field_attrs.delete(:value), **value_field_attrs %>
-
-  <%= tag.input **attrs %>
-
-  <%= tag.ul id: listbox_id, hidden: "", role: :listbox,
-        data: { "combobox-target": "listbox" } do |ul| %>
-    <% options.each do |option| %>
-      <%= tag.li option.content, id: option.try(:id),
-            role: :option, style: "cursor: pointer;",
-            data: {
-              "action": "click->combobox#selectOption",
-              "filterable-as": option.try(:filterable_as),
-              "autocompletable-as": option.try(:autocompletable_as),
-              "value": value_for_listbox_option(option) } %>
-    <% end %>
-  <% end %>
-<% end %>

data/lib/combobox/engine.rb

@@ -1,15 +0,0 @@
-module Combobox
-  class Engine < ::Rails::Engine
-    isolate_namespace Combobox
-
-    initializer "combobox.view_helpers" do
-      ActiveSupport.on_load :action_controller do
-        helper Combobox::Helper
-      end
-    end
-
-    initializer "combobox.importmap", before: "importmap" do |app|
-      app.config.importmap.paths << Engine.root.join("config/importmap.rb")
-    end
-  end
-end

data/lib/combobox/version.rb

@@ -1,3 +0,0 @@
-module Combobox
-  VERSION = "0.1.5"
-end

data/lib/combobox.rb

@@ -1,6 +0,0 @@
-require "combobox/version"
-require "combobox/engine"
-
-module Combobox
-  Option = Struct.new(:id, :value, :content, :filterable_as, :autocompletable_as)
-end