hotwire_combobox 0.1.6 → 0.1.8

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 06d497472d7966424ceea6dc655bf8baf2bfa7b2232ab587bb1ca6221f1b8e13
-  data.tar.gz: 994345e54975287e4958e917d8ff687851e6628604249c5ec59e2bcf9a858fb2
+  metadata.gz: 9cb2abe7ffd7dc81c39b774fb0028f0f9650182978735f3d21a3d375a32a948e
+  data.tar.gz: a038bd3ce8baff5a47e281be380cc0c4c0b77433cab3161174958a0f135fab08
 SHA512:
-  metadata.gz: b3bd3a8d9266f43a542641f762ae059d2f8cc2a5c3d98f14b8a853bc5173fd5b382482fa89c0ff103df7e3e24fbf06a6aad5fccffe4d01bd3194959114610742
-  data.tar.gz: aa29ec37fa9fd51d640622686a91f6e2bf31c6c9df6a1618d88d540dcea3c1f6e5033379bf0397726904a34a19927bb1b5e9b016d797e7e861d993229e79d171
+  metadata.gz: 52b14433be746e89f6e0612f42d3a84ed323ebb2931a93d535b90bb9eb1fbde555ea3bf0a3496774b9eb91c30ba0035576e6c3fab7da69e97e7228e927767e69
+  data.tar.gz: '09662cb44deb6854dca5d7a6919ae6170dff3ebcbbae9cab7ea7b1b368ec85e0db82f823a3471886cb55b9e4a44da6bd7e141bdc0e5948266b118ed96b2873bc'

data/README.md

@@ -1,10 +1,12 @@
-# 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
@@ -16,38 +18,107 @@ And then execute:
 $ bundle
 ```
 
-Or install it yourself as:
-```bash
-$ gem install hotwire_combobox
-```
+## Output
 
-## Contributing
+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.
 
-### Setup
-```bash
-$ bin/setup
-```
+```html
+<fieldset class="hw-combobox">
+  <input type="hidden" name="provided_name">
 
-### Running the tests
-```bash
-$ bundle exec rake app:test
+  <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>
 ```
 
-```bash
-$ bundle exec rake app:test:system
+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:
+
+| 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.                                                           |
+
+> [!NOTE]
+> The `id` attribute is required only if `value` is not provided.
+
+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" },
+  # ...
+]
 ```
 
-### Running the dummy app
-```bash
-$ bin/rails s
+### 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
+
+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:
+
+* `#combobox_tag` into `#hw_combobox_tag`
+* `#combobox_options` into `#hw_combobox_options`
+
+```ruby
+# config/initializers/hotwire_combobox.rb
+
+HotwireCombobox.setup do |config|
+  config.bypass_convenience_methods = true
+end
 ```
 
-### Releasing
+## Contributing
 
-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`
+Please read [CONTRIBUTING.md](./CONTRIBUTING.md).
 
 ## 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

@@ -1,5 +1,9 @@
 module HotwireCombobox
   module Helper
+    def hw_combobox_options(options)
+      options.map { |option| hw_combobox_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
@@ -20,11 +24,36 @@ module HotwireCombobox
         parent_data: default_hw_combobox_parent_data(attrs, data)
     end
 
-    def value_for_hw_listbox_option(option)
+    unless HotwireCombobox.bypass_convenience_methods?
+      alias_method :combobox_options, :hw_combobox_options
+      alias_method :combobox_tag, :hw_combobox_tag
+    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 hw_combobox_option(...)
+        HotwireCombobox::Option.new(...)
+      end
+
       def default_hw_combobox_value_field_id(attrs, form, name)
         attrs.delete(:id) || form&.field_id(name)
       end

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

@@ -7,13 +7,15 @@
   <%= tag.ul id: listbox_id, hidden: "", role: :listbox,
         data: { "hw-combobox-target": "listbox" } do |ul| %>
     <% options.each do |option| %>
-      <%= tag.li option.content, id: option.try(:id),
-            role: :option, style: "cursor: pointer;",
+      <%= 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": option.try(:filterable_as),
-              "autocompletable-as": option.try(:autocompletable_as),
-              "value": value_for_hw_listbox_option(option) } %>
+              "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/version.rb

@@ -1,3 +1,3 @@
 module HotwireCombobox
-  VERSION = "0.1.6"
+  VERSION = "0.1.8"
 end

data/lib/hotwire_combobox.rb

@@ -2,5 +2,18 @@ require "hotwire_combobox/version"
 require "hotwire_combobox/engine"
 
 module HotwireCombobox
-  Option = Struct.new(:id, :value, :content, :filterable_as, :autocompletable_as)
+  Option = Struct.new(:id, :value, :display, :content, :filterable_as, :autocompletable_as)
+
+  mattr_accessor :bypass_convenience_methods
+  @@bypass_convenience_methods = false
+
+  class << self
+    def setup
+      yield self
+    end
+
+    def bypass_convenience_methods?
+      bypass_convenience_methods
+    end
+  end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: hotwire_combobox
 version: !ruby/object:Gem::Version
-  version: 0.1.6
+  version: 0.1.8
 platform: ruby
 authors:
 - Jose Farias
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2023-12-10 00:00:00.000000000 Z
+date: 2023-12-12 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails