hotwire_combobox 0.1.6 → 0.1.7

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 06d497472d7966424ceea6dc655bf8baf2bfa7b2232ab587bb1ca6221f1b8e13
-  data.tar.gz: 994345e54975287e4958e917d8ff687851e6628604249c5ec59e2bcf9a858fb2
+  metadata.gz: 01a08bf7fdf486660daebfd29960a62c8435ad87939a8963d805967872ffca4d
+  data.tar.gz: 2ca73e1f2693d9adf838463187bd2c79867b8086d59beea0bb699c12a49e8507
 SHA512:
-  metadata.gz: b3bd3a8d9266f43a542641f762ae059d2f8cc2a5c3d98f14b8a853bc5173fd5b382482fa89c0ff103df7e3e24fbf06a6aad5fccffe4d01bd3194959114610742
-  data.tar.gz: aa29ec37fa9fd51d640622686a91f6e2bf31c6c9df6a1618d88d540dcea3c1f6e5033379bf0397726904a34a19927bb1b5e9b016d797e7e861d993229e79d171
+  metadata.gz: d505fbfb95060cb730a5533dd4d850f4691391a94f4849fd12017f1ebca12df55a12871d29f784e55dccbe2a8512c007c7516f960225e1a13f6ab74d5d8a3431
+  data.tar.gz: 6792bae8acf5f9051f2a5605f95e86d7e3b755d323e47e9dff65dc0a02eb27771fa145d2129b246518711e4b050cc2e3cba8b03e83b581ea519c31c30a2ad5d6

data/README.md

@@ -1,8 +1,9 @@
-# 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:
@@ -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

data/app/helpers/hotwire_combobox/helper.rb

@@ -1,5 +1,13 @@
 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
@@ -20,10 +28,26 @@ module HotwireCombobox
         parent_data: default_hw_combobox_parent_data(attrs, data)
     end
 
-    def value_for_hw_listbox_option(option)
+    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)

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.7"
 end

data/lib/hotwire_combobox.rb

@@ -2,5 +2,5 @@ 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)
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: hotwire_combobox
 version: !ruby/object:Gem::Version
-  version: 0.1.6
+  version: 0.1.7
 platform: ruby
 authors:
 - Jose Farias