hotwire_combobox 0.1.41 → 0.1.42

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1fc70c854bf6cdceda08dd727b854a63b7deb0703d9a8dafcab0bd74ca3e73d0
-  data.tar.gz: ec4ad558a47dcdb94e68d360671a89f3d9147a7a2a172a741f06f59dfbfd096a
+  metadata.gz: 1fc3750ecb7bd58bd28e13d0cc2d543ae4c614535c927c9483e504b643171a8d
+  data.tar.gz: dc6482de8a4344a6d801797d497f6adec8afcc0357e821e1dff8188ecf4c2f68
 SHA512:
-  metadata.gz: 1cb4ab65ec2312a055400870a1c2e91a11e598c389daf96f1f3f079627fac208fbaad73bad1a957db1a5eff33eaaba7c7d2c7eccc7aa389bdcdf9c51e26832b6
-  data.tar.gz: fbb2db40e5b529084c5c65ab644c3af9c0f5721741f2692dcc85e76362f82ebdddf94f979d02b80328b8b39828468e591d6d61faeec3ecff7f262c327bb78a6b
+  metadata.gz: 8884e9e8295b73d37d15762f08c1a69452a7117f99af09dba4369aedea9af2116bc9683127f6f29535813fa5182b21969eb35e4d077edee1f94ce1a6808aadfe
+  data.tar.gz: b58dd5870a0508912c910b387f7970ffc4a08a16e40612b448e7c35ae244d0f8e02f9dd9356e5cdd8ae7f0c45c1bd65513ece94fcbeba38818c39d39c9ecd870

data/README.md

@@ -80,6 +80,9 @@ import HwComboboxController from "@josefarias/hotwire_combobox"
 application.register("hw-combobox", HwComboboxController)
 ```
 
+> [!WARNING]
+> Keep in mind you need to update both the npm package and the gem every time there's a new version of HotwireCombobox. You should always run the same version number on both sides.
+
 ### Configuring CSS
 
 This library comes with optional default styles. Follow the instructions below to include them in your app.
@@ -109,6 +112,19 @@ Require the styles in `app/assets/stylesheets/application.css`:
 Visit [the docs site](https://hotwirecombobox.com/) for a demo and detailed documentation.
 If the site is down, you can run the docs locally by cloning [the docs repo](https://github.com/josefarias/hotwire_combobox_docs).
 
+## Notes about accessibility
+
+This gem follows the [APG combobox pattern guidelines](https://www.w3.org/WAI/ARIA/apg/patterns/combobox/) with some exceptions we feel increase the usefulness of the component without much detriment to the overall accessible experience.
+
+These are the exceptions:
+
+1. Users cannot manipulate the combobox while it's closed. As long as the combobox is focused, the listbox is shown.
+2. The escape key closes the listbox and blurs the combobox. It does not clear the combobox.
+3. The listbox has wrap-around selection. That is, pressing `Up Arrow` when the user is on the first option will select the last option. And pressing `Down Arrow` when on the last option will select the first option. In paginated comboboxes, the first and last options refer to the currently available options. More options may be loaded after navigating to the last currently available option.
+4. It is possible to have an unlabled combobox, as that responsibility is delegated to the implementing user.
+
+It should be noted none of the maintainers use assistive technologies in their daily lives. If you do, and you feel these exceptions are detrimental to your ability to use the component, or if you find an undocumented exception, please [open a GitHub issue](https://github.com/josefarias/hotwire_combobox/issues). We'll get it sorted.
+
 ## Contributing
 
 Please read [CONTRIBUTING.md](./CONTRIBUTING.md).

data/app/assets/javascripts/hotwire_combobox.esm.js

@@ -237,16 +237,21 @@ Combobox.Dialog = Base => class extends Base {
 
 Combobox.Events = Base => class extends Base {
   _dispatchSelectionEvent({ isNew }) {
-    const detail = {
+    dispatch("hw-combobox:selection", { target: this.element, detail: { ...this._eventableDetails, isNew } });
+  }
+
+  _dispatchClosedEvent() {
+    dispatch("hw-combobox:closed", { target: this.element, detail: this._eventableDetails });
+  }
+
+  get _eventableDetails() {
+    return {
       value: this.hiddenFieldTarget.value,
       display: this._fullQuery,
       query: this._typedQuery,
       fieldName: this.hiddenFieldTarget.name,
-      isValid: this._valueIsValid,
-      isNew: isNew
-    };
-
-    dispatch("hw-combobox:selection", { target: this.element, detail });
+      isValid: this._valueIsValid
+    }
   }
 };
 
@@ -1099,6 +1104,7 @@ Combobox.Toggle = Base => class extends Base {
     if (this._isOpen) {
       this._lockInSelection();
       this.expandedValue = false;
+      this._dispatchClosedEvent();
     }
   }
 

data/app/assets/javascripts/hotwire_combobox.umd.js

@@ -241,16 +241,21 @@
 
   Combobox.Events = Base => class extends Base {
     _dispatchSelectionEvent({ isNew }) {
-      const detail = {
+      dispatch("hw-combobox:selection", { target: this.element, detail: { ...this._eventableDetails, isNew } });
+    }
+
+    _dispatchClosedEvent() {
+      dispatch("hw-combobox:closed", { target: this.element, detail: this._eventableDetails });
+    }
+
+    get _eventableDetails() {
+      return {
         value: this.hiddenFieldTarget.value,
         display: this._fullQuery,
         query: this._typedQuery,
         fieldName: this.hiddenFieldTarget.name,
-        isValid: this._valueIsValid,
-        isNew: isNew
-      };
-
-      dispatch("hw-combobox:selection", { target: this.element, detail });
+        isValid: this._valueIsValid
+      }
     }
   };
 
@@ -1103,6 +1108,7 @@
       if (this._isOpen) {
         this._lockInSelection();
         this.expandedValue = false;
+        this._dispatchClosedEvent();
       }
     }
 

data/app/assets/javascripts/hw_combobox/models/combobox/events.js

@@ -3,15 +3,20 @@ import { dispatch } from "hw_combobox/helpers"
 
 Combobox.Events = Base => class extends Base {
   _dispatchSelectionEvent({ isNew }) {
-    const detail = {
+    dispatch("hw-combobox:selection", { target: this.element, detail: { ...this._eventableDetails, isNew } })
+  }
+
+  _dispatchClosedEvent() {
+    dispatch("hw-combobox:closed", { target: this.element, detail: this._eventableDetails })
+  }
+
+  get _eventableDetails() {
+    return {
       value: this.hiddenFieldTarget.value,
       display: this._fullQuery,
       query: this._typedQuery,
       fieldName: this.hiddenFieldTarget.name,
-      isValid: this._valueIsValid,
-      isNew: isNew
+      isValid: this._valueIsValid
     }
-
-    dispatch("hw-combobox:selection", { target: this.element, detail })
   }
 }

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

@@ -10,6 +10,7 @@ Combobox.Toggle = Base => class extends Base {
     if (this._isOpen) {
       this._lockInSelection()
       this.expandedValue = false
+      this._dispatchClosedEvent()
     }
   }
 

data/lib/hotwire_combobox/engine.rb

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

data/lib/hotwire_combobox/helper.rb

@@ -26,11 +26,9 @@ module HotwireCombobox
       if options.first.is_a? HotwireCombobox::Listbox::Option
         options
       else
-        render_in_proc = hw_render_in_proc(render_in) if render_in.present?
-
-        hw_parse_combobox_options(options, render_in: render_in_proc, **methods.merge(display: display)).tap do |options|
-          options.unshift(hw_blank_option(include_blank)) if include_blank.present?
-        end
+        opts = hw_parse_combobox_options options, render_in_proc: hw_render_in_proc(render_in), **methods.merge(display: display)
+        opts.unshift(hw_blank_option(include_blank)) if include_blank.present?
+        opts
       end
     end
     hw_alias :hw_combobox_options
@@ -85,7 +83,7 @@ module HotwireCombobox
         if include_blank.is_a? Hash
           text = include_blank.delete(:text)
 
-          [ text, hw_render_in_proc(include_blank).(text) ]
+          [ text, hw_call_render_in_proc(hw_render_in_proc(include_blank), text, display: text, value: "") ]
         else
           [ include_blank, include_blank ]
         end
@@ -102,7 +100,9 @@ module HotwireCombobox
 
     private
       def hw_render_in_proc(render_in)
-        ->(object) { render(**render_in.reverse_merge(object: object)) }
+        if render_in.present?
+          ->(object, locals) { render(**render_in.reverse_merge(object: object, locals: locals)) }
+        end
       end
 
       def hw_extract_options_and_src(options_or_src, render_in, include_blank)
@@ -113,40 +113,50 @@ module HotwireCombobox
         end
       end
 
-      def hw_parse_combobox_options(options, render_in: nil, **methods)
+      def hw_parse_combobox_options(options, render_in_proc: nil, **methods)
         options.map do |option|
           HotwireCombobox::Listbox::Option.new \
-            **hw_option_attrs_for(option, render_in: render_in, **methods)
+            **hw_option_attrs_for(option, render_in_proc: render_in_proc, **methods)
         end
       end
 
-      def hw_option_attrs_for(option, render_in: nil, **methods)
+      def hw_option_attrs_for(option, render_in_proc: nil, **methods)
         case option
         when Hash
-          option
+          option.tap do |attrs|
+            attrs[:content] = hw_call_render_in_proc(render_in_proc, attrs[:display], attrs) if render_in_proc
+          end
         when String
           {}.tap do |attrs|
             attrs[:display] = option
             attrs[:value] = option
-            attrs[:content] = render_in.(option) if render_in
+            attrs[:content] = hw_call_render_in_proc(render_in_proc, attrs[:display], attrs) if render_in_proc
           end
         when Array
           {}.tap do |attrs|
             attrs[:display] = option.first
             attrs[:value] = option.last
-            attrs[:content] = render_in.(option.first) if render_in
+            attrs[:content] = hw_call_render_in_proc(render_in_proc, attrs[:display], attrs) if render_in_proc
           end
         else
           {}.tap do |attrs|
-            attrs[:value] = hw_call_method_or_proc(option, methods[:value] || :id)
-
             attrs[:id] = hw_call_method_or_proc(option, methods[:id]) if methods[:id]
             attrs[:display] = hw_call_method_or_proc(option, methods[:display]) if methods[:display]
-            attrs[:content] = hw_call_method_or_proc(option, render_in || methods[:content]) if render_in || methods[:content]
+            attrs[:value] = hw_call_method_or_proc(option, methods[:value] || :id)
+
+            if render_in_proc
+              attrs[:content] = hw_call_render_in_proc(render_in_proc, option, attrs)
+            elsif methods[:content]
+              attrs[:content] = hw_call_method_or_proc(option, methods[:content])
+            end
           end
         end
       end
 
+      def hw_call_render_in_proc(render_in_proc, object, attrs)
+        render_in_proc.(object, combobox_display: attrs[:display], combobox_value: attrs[:value])
+      end
+
       def hw_call_method_or_proc(object, method_or_proc)
         if method_or_proc.is_a? Proc
           method_or_proc.call object

data/lib/hotwire_combobox/version.rb

@@ -1,3 +1,3 @@
 module HotwireCombobox
-  VERSION = "0.1.41"
+  VERSION = "0.1.42"
 end

metadata

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