stimulus-plumbers-rails

Version CI

Rails helpers for accessible, WCAG 2.1 AA compliant UI components built on Stimulus. Pairs with the @stimulus-plumbers/controllers npm package.

Requirements

  • Ruby >= 3.0
  • Rails >= 6.1
  • @stimulus-plumbers/controllers registered in your Stimulus app

Installation

# Gemfile
gem "stimulus_plumbers"

bundle install

Include the helpers in your ApplicationHelper:

module ApplicationHelper
  include StimulusPlumbers::Helpers::ComboboxHelper
  include StimulusPlumbers::Helpers::PopoverHelper
  include StimulusPlumbers::Helpers::CalendarHelper
end

Or use the form builder globally:

# config/application.rb
config.action_view.default_form_builder = StimulusPlumbers::Form::Builder

Components

Component Helper(s) Docs
Combobox — date sp_combobox_date docs/component/combobox.md
Combobox — dropdown sp_combobox_dropdown docs/component/combobox.md
Combobox — autocomplete sp_combobox_autocomplete docs/component/combobox.md
Combobox — time sp_combobox_time docs/component/combobox.md
Calendar sp_calendar_month docs/component/calendar.md
Popover sp_popover docs/component/popover.md
Modal — (JS only) docs/component/modal.md

Form Builder

StimulusPlumbers::Form::Builder wraps all components as model-aware form fields with automatic label, name/id, error, and ARIA wiring.

→ docs/component/form_builder.md

Theming

Includes a Tailwind CSS theme out of the box. Supports custom themes by subclassing Themes::Base.

→ docs/component/theme.md

Development

bundle install

bundle exec rake test:unit    # unit tests
bundle exec rake test:system  # accessibility system tests
bundle exec rake rubocop      # lint

Test against a specific Rails version:

BUNDLE_GEMFILE=gemfiles/rails_8.0.gemfile bundle exec rake test:unit

Available appraisals: rails_6.1, rails_7.0, rails_7.1, rails_7.2, rails_8.0, rails_8.1, rails_edge.

License

MIT