Midwest Component Library

Midwest Component Library is an implementation of the Midwest Design System using ViewComponent.

This library is under active development. Breaking changes are likely until stable release.

Usage

Render Midwest ViewComponents:

= midwest_card(title: "Title") do
  %p Card example

Dependencies

• Stimulus

Installation

Add to Gemfile:

gem "midwest", git: "[email protected]:unabridged/midwest.git", branch: "main"

Run installer:

bin/rails midwest:install

Development

To get started:

1. Run: bundle install
2. Run: yarn install
3. Run: git config core.hooksPath .githooks to enable the pre-commit lint hook
4. Run: bin/dev

It will open demo app with component previews on localhost:4000. You can change components and they will be updated on page reload. Component previews located in demo/app/previews.

Running tests

Run the full suite against the current Ruby version:

bin/test

Run the complete matrix — every appraisal × every supported Ruby version:

bin/test --all

Target a specific Rails or Bridgetown version:

bin/test --rails 8
bin/test --bridgetown v2
bin/test --rails 7,8

Run jobs sequentially instead of in parallel:

bin/test --no-parallel

Target specific files, directories, or glob patterns:

bin/test test/integration/navigation_test.rb         # single file
bin/test test/components/                            # all tests in a directory
bin/test "test/components/midwest/popover*"          # glob pattern
bin/test --rails 8 test/integration/                 # scoped appraisal + directory
bin/test --all test/integration/navigation_test.rb   # single file across full Ruby matrix

Compatibility matrix

The gem uses Appraisal to test against multiple Rails and Bridgetown versions. Ruby 3.1 and 3.2 are end-of-life and no longer tested.

| Appraisal | Target | Ruby | |---|---|---| | rails-7 | Rails ~> 7.1 | 3.3, 3.4 | | rails-8 | Rails ~> 8.0 | 3.3, 3.4 | | bridgetown-v1 | Bridgetown ~> 1.0 | 3.4 | | bridgetown-v2 | Bridgetown ~> 2.0 | 3.4 |

Ruby versions are installed and managed via asdf. To install any missing versions from the matrix:

bin/setup-rubies

Generating new components

bin/rails midwest:generate:component YourComponent

The syntax follows ViewComponent's generator.

Deploying your application

In order to deploy your application the deploy server will need access to the private repo. One way to accomplish that is to add the deploy key on this repo to the deploy server. You should be able to create the key from the values in the Shared 1Password vault entry "GitHub - Midwest"

Staging environment

A staging environment is hosted via Dokku. To deploy to it, add the remote once:

git remote add staging [email protected]:midwest

Then deploy by pushing to the remote:

git push staging main

Releases

The library follows semantic versioning. To draft a new release run bin/release with a new version number:

bin/release VERSION

This script will update the version in the gem and push it to GitHub and Rubygems automatically.

To release a new version of the npm package, update package.json with the new version number and run:

npm run release

After that make sure to commit changes in package.json.

License

The gem is available as open source under the terms of the MIT License.