hotwire_combobox 0.1.7 → 0.1.8

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 01a08bf7fdf486660daebfd29960a62c8435ad87939a8963d805967872ffca4d
-  data.tar.gz: 2ca73e1f2693d9adf838463187bd2c79867b8086d59beea0bb699c12a49e8507
+  metadata.gz: 9cb2abe7ffd7dc81c39b774fb0028f0f9650182978735f3d21a3d375a32a948e
+  data.tar.gz: a038bd3ce8baff5a47e281be380cc0c4c0b77433cab3161174958a0f135fab08
 SHA512:
-  metadata.gz: d505fbfb95060cb730a5533dd4d850f4691391a94f4849fd12017f1ebca12df55a12871d29f784e55dccbe2a8512c007c7516f960225e1a13f6ab74d5d8a3431
-  data.tar.gz: 6792bae8acf5f9051f2a5605f95e86d7e3b755d323e47e9dff65dc0a02eb27771fa145d2129b246518711e4b050cc2e3cba8b03e83b581ea519c31c30a2ad5d6
+  metadata.gz: 52b14433be746e89f6e0612f42d3a84ed323ebb2931a93d535b90bb9eb1fbde555ea3bf0a3496774b9eb91c30ba0035576e6c3fab7da69e97e7228e927767e69
+  data.tar.gz: '09662cb44deb6854dca5d7a6919ae6170dff3ebcbbae9cab7ea7b1b368ec85e0db82f823a3471886cb55b9e4a44da6bd7e141bdc0e5948266b118ed96b2873bc'

data/README.md

@@ -6,6 +6,7 @@ A combobox implementation for Ruby on Rails apps running on Hotwire.
 > 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
@@ -49,34 +50,25 @@ 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          |
-
+| 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.
 
-
-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:
+You can use the `combobox_options` helper to create an array of option objects which respond to the above methods:
 
 ```ruby
-@states = hwbox_options [
+combobox_options [
   { value: "AL", display: "Alabama" },
+  { value: "AK", display: "Alaska" },
+  { value: "AZ", display: "Arizona" },
   # ...
 ]
 ```
@@ -90,7 +82,7 @@ The combobox is completely unstyled by default. You can use the following CSS se
 * `.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`:
+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.
@@ -108,33 +100,25 @@ The library will mark the element as invalid but this won't be noticeable in the
 > [!CAUTION]
 > Bad actors can still submit invalid values to the server. You should always validate the input on the server side.
 
-## Contributing
+### Naming Conflicts
 
-### Setup
-```bash
-$ bin/setup
-```
+If your application has naming conflicts with this gem, the following config will turn:
 
-### Running the tests
-```bash
-$ bundle exec rake app:test
-```
+* `#combobox_tag` into `#hw_combobox_tag`
+* `#combobox_options` into `#hw_combobox_options`
 
-```bash
-$ bundle exec rake app:test:system
-```
+```ruby
+# config/initializers/hotwire_combobox.rb
 
-### Running the dummy app
-```bash
-$ bin/rails s
+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,11 +1,7 @@
 module HotwireCombobox
   module Helper
-    def hwbox_option(...)
-      HotwireCombobox::Option.new(...)
-    end
-
-    def hwbox_options(options)
-      options.map { |option| hwbox_option(**option) }
+    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)
@@ -28,6 +24,11 @@ module HotwireCombobox
         parent_data: default_hw_combobox_parent_data(attrs, data)
     end
 
+    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
@@ -49,6 +50,10 @@ module HotwireCombobox
     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/lib/hotwire_combobox/version.rb

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

data/lib/hotwire_combobox.rb

@@ -3,4 +3,17 @@ require "hotwire_combobox/engine"
 
 module HotwireCombobox
   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.7
+  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