hotwire_combobox

HotwireCombobox follows the APG combobox pattern guidelines with the following specific implementation exceptions:

1. Wrap-around selection: Pressing Up Arrow on the first option selects the last option. Pressing Down Arrow on the last option selects the first option. In paginated comboboxes, this refers to the currently available options.
2. Unlabeled comboboxes: The library allows for unlabeled comboboxes; the responsibility for providing a label lies with the implementing user.
3. Multiselect support: Since official APG guidelines for multiselect comboboxes are currently unavailable, the library uses custom mechanisms like live regions to announce multi-selections.

If your application uses importmaps, most setups will work automatically if you are using eagerLoadControllersFrom or lazyLoadControllersFrom in app/javascript/controllers/index.js.

If you need to manually register the controller, modify app/javascript/controllers/application.js as follows:

import { Application } from "@hotwired/stimulus"
const application = Application.start()

// Add the following two lines:
import HwComboboxController from "controllers/hw_combobox_controller"
application.register("hw-combobox", HwComboboxController)

export { application }

Ensure Turbo and Stimulus are already configured in your application.

Add the gem to your Gemfile and run bundle install:

gem "hotwire_combobox"

If you are using a JS bundler, you must install the JavaScript portion via npm or yarn and manually register the Stimulus controller.

Note: You must keep the version of the npm package and the Ruby gem in sync.

yarn add @josefarias/hotwire_combobox
# OR
npm install @josefarias/hotwire_combobox

Then, register the controller in app/javascript/controllers/application.js:

import { Application } from "@hotwired/stimulus"
const application = Application.start()

// Add the following two lines:
import HwComboboxController from "@josefarias/hotwire_combobox"
application.register("hw-combobox", HwComboboxController)

export { application }

You can include the default styles using either the Rails helper or Sprockets.

### Default (Layout helper)
<%= combobox_style_tag %>

### Sprockets (app/assets/stylesheets/application.css)
*= require hotwire_combobox

The hotwire_combobox library is built using a mixin pattern for Stimulus controllers. Instead of a single monolithic class, functionality is divided into discrete, reusable modules (mixins) that are applied to a base Stimulus controller using a Concerns helper function.

Key mixins include:

• Actors: Manages the relationship between the combobox input and the listbox.
• Autocomplete: Handles inline or list-based text completion.
• Filtering: Manages sync/async filtering of options based on user input.
• Multiselect: Provides chip-based selection for multiple values.
• Navigation: Handles keyboard interactions (Arrow keys, Home, End, etc.).
• Events: Dispatches custom DOM events like hw-combobox:selection or hw-combobox:removal.
• Dialog: Manages the transition of the combobox to a full-screen dialog on small viewports.

When using Multiselect mode, you can render selection chips using a client-side template. This allows you to customize the look of the chips and inject dynamic data using a placeholder syntax.

1. Define a <template> element inside your combobox container.
2. Add the attribute data-hw-combobox-chip-template to the template.
3. Use the {{key}} syntax to inject data. The keys correspond to attributes on your option elements prefixed with data-chip-.

Example Template:

<template data-hw-combobox-chip-template>
  <div class="chip">
    <span>{{display}}</span>
    <button data-action="click->combobox#removeChip">×</button>
    <small>{{category}}</small>
  </div>
</template>

If an option element has data-chip-category="Work", the {{category}} placeholder will be replaced with "Work".

To ensure the combobox renders with the correct styling, include the library's stylesheet in your application view using hw_combobox_style_tag.

<%= hw_combobox_style_tag %>

To enable asynchronous searching (e.g., fetching results from a server via Turbo Streams), configure the AsyncLoading mixin by providing an async-src value to your controller.

When a user types, the controller will perform a GET request to the URL provided in async-src. The request includes the following query parameters:

• q: The current full query.
• input_type: The type of input event (e.g., insertText).
• for_id: The data-async-id of the combobox.
• callback_id: A unique ID to track the request.

The server should respond with a text/vnd.turbo-stream.html response to update the listbox options.