How josefarias/hotwire_combobox works
Main Components
• Gem/Engine Core: Represented by the files in the lib directory (e.g., lib/hotwire_combobox/engine.rb, helper.rb, etc.), this is the entry point that integrates the combobox functionality into a host Rails application.
• Asset Pipeline & Frontend: This includes the JavaScript assets (controllers, models, helper scripts under app/assets/javascripts/hw_combobox and app/assets/javascripts/controllers/hw_combobox_controller.js) and CSS (app/assets/stylesheets/hotwire_combobox.css). It also covers configurations for handling JS bundlers or importmaps.
• Presenters & Markup: The app/presenters/hotwire_combobox directory holds the logic for constructing the component’s HTML structure. This includes subcomponents for markup (dialog, form, input, label, etc.) and behavior (multiselect, async, etc.) that are later rendered by the views.
• View Templates: The view partials under app/views/hotwire_combobox (and test/dummy’s app/views) are responsible for the server-rendered interface and Turbo Streams for dynamic updates.
• Configuration & Integration: Various configuration files (like the Gemfile, config files, and JavaScript bundling configurations such as rollup.config.mjs and package.json) ensure that external dependencies (Turbo, Stimulus, etc.) are properly hooked up.
• Testing and Examples: The test and test/dummy folders show how the component is integrated and exercised in a dummy Rails app for system, integration, and unit tests.
Relationships and Interactions
• The Rails engine (Gem Core) injects view helpers (from lib/hotwire_combobox/helper.rb) into the host application so that developers can easily call methods like combobox_style_tag.
• When rendered, view templates invoke Presenters to construct the combobox markup using various component files in app/presenters/hotwire_combobox/component and its submodules.
• The resulting HTML is enriched by Hotwire’s Turbo Streams (with corresponding .turbo_stream.erb files) for live updates and interactions.
• On the client side, the Stimulus controller (hw_combobox_controller.js) is registered (as shown by the README instructions) with the Hotwire Stimulus application, which then uses various support functions (from models and helpers in the asset folders) to provide dynamic behavior, such as async fetching of options and handling keyboard navigation.
• CSS resources ensure that the default (but customizable) styling is applied, making the combobox look consistent across host applications.
Architectural Patterns and Design Principles
• MVC Separation: The gem clearly separates presentation (views and presenters), business logic (helpers in lib and parts of the engine), and the client-side behavior (Stimulus controllers).
• Rails Engine Approach: The gem encapsulates its functionality as a Rails engine, allowing it to be mounted or used as a component within a larger Rails app.
• Frontend Integration with Hotwire: Adheres to the Hotwire philosophy with Turbo Streams and Stimulus, ensuring minimal JavaScript overhead while offering responsive UI patterns.
• Accessibility First: The design keeps accessibility in mind following the APG combobox guidelines, with exceptions noted that are integrated into the component’s behavior.
Relevant Technologies, Frameworks, and Libraries
• Ruby on Rails for server-side integration.
• Turbo (from Hotwire) for dynamic page updates and asynchronous interactions.
• Stimulus for establishing the JavaScript controller to manage combobox behaviors on the client side.
• (Optional) JS bundlers such as esbuild or rollup (configured via rollup.config.mjs and package.json) for those using modern JavaScript workflows.
• Sprockets and/or Importmaps for managing CSS and JS assets in different deployment scenarios.