# josefarias/hotwire_combobox architecture

> Architecture diagram of the GitHub repository josefarias/hotwire_combobox, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/josefarias/hotwire_combobox
- Repository: https://github.com/josefarias/hotwire_combobox

## Overview

##### 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.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Server-Side Components
    subgraph "Server-Side"
        subgraph "Gem/Engine Core"
            engine["Engine (lib/hotwire_combobox/engine.rb)"]:::ruby
            helper["Helper (lib/hotwire_combobox/helper.rb)"]:::ruby
        end
        subgraph "Presenters & Markup"
            compPresenter["Component Presenter (component.rb)"]:::ruby
            presentersDir["Presenters Directory (app/presenters/hotwire_combobox)"]:::ruby
        end
        subgraph "View Templates"
            views["View Templates (app/views/hotwire_combobox)"]:::view
        end
        %% Server-Side Connections
        engine -->|"injects"| views
        helper -->|"provides_helper"| views
        views -->|"invokes"| compPresenter
        views -->|"invokes"| presentersDir
    end

    %% Client-Side Components
    subgraph "Client-Side"
        subgraph "Asset Pipeline & Frontend"
            jsController["JS Controller (hw_combobox_controller.js)"]:::js
            jsAssets["JS Assets (app/assets/javascripts/hw_combobox)"]:::js
            cssAssets["CSS (hotwire_combobox.css)"]:::js
            jsManifest["JS Manifest (hw_combobox_manifest.js)"]:::js
        end
        subgraph "External Dependencies"
            turboStimulus["Turbo & Stimulus"]:::external
        end
        %% Client-Side Connections
        views -->|"triggers"| jsController
        jsController -->|"utilizes"| jsAssets
        jsController -->|"applies_styles_from"| cssAssets
        jsManifest -->|"configs"| jsController
        turboStimulus -->|"integrates_with"| jsController
    end

    %% Configuration & Integration
    subgraph "Configuration & Integration"
        gemfile["Gemfile (Gemfile)"]:::config
        pkgJSON["JS Bundling (package.json)"]:::config
        rollup["Bundling Config (rollup.config.mjs)"]:::config
    end

    %% Testing and Examples
    subgraph "Testing & Examples"
        tests["Test Folder (test)"]:::test
        dummy["Dummy App (test/dummy)"]:::test
    end

    %% Cross-Cutting Connections
    engine --- gemfile
    helper --- gemfile
    jsManifest --- pkgJSON
    jsManifest --- rollup
    views --- tests
    tests --- dummy

    %% User Interaction
    user["User Interaction"]:::external
    user -->|"types_input"| jsController

    %% Styling Definitions
    classDef ruby fill:#f9e79f,stroke:#d35400,stroke-width:2px;
    classDef js fill:#aed6f1,stroke:#2471a3,stroke-width:2px;
    classDef config fill:#abebc6,stroke:#17a589,stroke-width:2px;
    classDef view fill:#f5cba7,stroke:#ca6f1e,stroke-width:2px;
    classDef test fill:#d2b4de,stroke:#8e44ad,stroke-width:2px;
    classDef external fill:#d5f5e3,stroke:#27ae60,stroke-width:2px;

    %% Click Events for Gem/Engine Core
    click engine "https://github.com/josefarias/hotwire_combobox/blob/main/lib/hotwire_combobox/engine.rb"
    click helper "https://github.com/josefarias/hotwire_combobox/blob/main/lib/hotwire_combobox/helper.rb"

    %% Click Events for Asset Pipeline & Frontend
    click jsController "https://github.com/josefarias/hotwire_combobox/blob/main/app/assets/javascripts/controllers/hw_combobox_controller.js"
    click jsAssets "https://github.com/josefarias/hotwire_combobox/tree/main/app/assets/javascripts/hw_combobox"
    click cssAssets "https://github.com/josefarias/hotwire_combobox/blob/main/app/assets/stylesheets/hotwire_combobox.css"
    click jsManifest "https://github.com/josefarias/hotwire_combobox/blob/main/app/assets/config/hw_combobox_manifest.js"

    %% Click Events for Presenters & Markup
    click compPresenter "https://github.com/josefarias/hotwire_combobox/blob/main/app/presenters/hotwire_combobox/component.rb"
    click presentersDir "https://github.com/josefarias/hotwire_combobox/tree/main/app/presenters/hotwire_combobox"

    %% Click Event for View Templates
    click views "https://github.com/josefarias/hotwire_combobox/tree/main/app/views/hotwire_combobox"

    %% Click Events for Configuration & Integration
    click gemfile "https://github.com/josefarias/hotwire_combobox/tree/main/Gemfile"
    click pkgJSON "https://github.com/josefarias/hotwire_combobox/blob/main/package.json"
    click rollup "https://github.com/josefarias/hotwire_combobox/blob/main/rollup.config.mjs"

    %% Click Events for Testing and Examples
    click tests "https://github.com/josefarias/hotwire_combobox/tree/main/test/"
    click dummy "https://github.com/josefarias/hotwire_combobox/tree/main/test/dummy/"
```
