Primer ViewComponents
ViewComponents for the Primer Design System
_Note: This library is in pre-release development and should not be considered stable._
## Design philosophy
Primer ViewComponents aims to mimic the API of [Primer Components](https://github.com/primer/components), while using [Primer CSS](https://github.com/primer/css) under the hood.
## Installation
In `Gemfile`, add:
```ruby
gem "primer_view_components"
```
In `config/application.rb`, add **after the application definition**
```ruby
require "primer/view_components/engine"
```
## Usage
### Built-in styling arguments
Primer components should be styled using the built-in arguments when possible. Most Primer utility classes for spacing, alignment, display, and colors have equivalent component arguments.
Example label built with Primer CSS:
```html
Suggested
```
The same label using `Primer::LabelComponent`:
```erb
<%= render Primer::LabelComponent.new(ml: 2, vertical_align: :middle, scheme: :green, title: "Label: Suggested") do %>
Suggested
<% end %>
```
Some components have their own specific arguments, but they can all be styled with the following arguments.
| Component argument | Primer class | Example |
| --------------- | --------------- | -------- |
| `m` | `m-` | `m: 4` → `.m-4` |
| `my` | `my-` | `my: 4` → `.my-4` |
| `mx` | `my-` | `mx: 4` → `.mx-4` |
| `mt` | `mt-` | `mt: 4` → `.mt-4` |
| `mb` | `mb-` | `mb: 4` → `.mb-4` |
| `ml` | `ml-` | `ml: 4` → `.ml-4` |
| `mr` | `mr-` | `mr: 4` → `.mr-4` |
| `p` | `p-` | `p: 4` → `.p-4` |
| `py` | `py-` | `py: 4` → `.py-4` |
| `px` | `py-` | `px: 4` → `.px-4` |
| `pt` | `pt-` | `pt: 4` → `.pt-4` |
| `pb` | `pb-` | `pb: 4` → `.pb-4` |
| `pl` | `pl-` | `pl: 4` → `.pl-4` |
| `pr` | `pr-` | `pr: 4` → `.pr-4` |
| `pr` | `pr-` | `pr: 4` → `.pr-4` |
| `f` | `f-` | `f: 4` → `.f-4` |
| `color` | `color-` | `color: :red_500` → `.color-red-500` |
| `text` | `text-` | `text: :green` → `.text-green` |
| `bg` | `bg-` | `bg: :blue_light` → `.bg-blue-light` |
| `display` | `d-` | `display: :none` → `.d-none` |
| `float` | `float-` | `float: :right` → `.float-right` |
| `vertical_align` | `v-align-` | `vertical_align: :baseline` → `.v-align-baseline` |
| `text_align` | `text-` | `text_align: :right` → `.text-right` |
| `font_size` | `f` | `font_size: 4` → `.f4` |
| `font_weight` | `text-` | `font_weight: :bold` → `.text-bold` |
| `border` | `border-` | `border: :bottom` → `.border-bottom` |
| `border_color` | `border-` | `border: :green` → `.border-green` |
| `word_break` | `wb-` | `word_break: :break_all` → `.wb-break-all` |
| `direction` | `flex-` | `direction: :row` → `.flex-row` |
| `justify_content` | `flex-justify-` | `justify_content: :center` → `.flex-justify-center` |
| `align_items` | `flex-items-` | `align_items: :baseline` → `.flex-items-baseline` |
| `box_shadow` | `box-shadow-` | `box_shadow: :medium` → `.box-shadow-medium` |
#### Boolean arguments
| Component arguments | True | False |
| -------------- | ------- | ------ |
| `underline` | `underline: true` → `.text-underline` | `underline: false` → `.no-underline` |
| `top` | n/a | `top: false` → `.top-0` |
| `bottom` | n/a | `bottom: false` → `.bottom-0` |
| `left` | n/a | `left: false` → `.left-0` |
| `right` | n/a | `right: false` → `.right-0` |
#### Responsive arguments
Different classes can be used for different breakpoints just like in Primer CSS. Simply use an array with the four values required for `[none, small, medium, large]`. If no breakpoint is needed for a breakpoint, pass `nil`.
Example heading built with Primer CSS:
```html
Hello world
```
The same label using `Primer::HeadingComponent`:
```erb
<%= render Primer::HeadingComponent.new(mt: [0, nil, nil, 4]) do %>
Hello world
<% end %>
```
## Contributing
Bug reports and pull requests are welcome on GitHub at https://github.com/primer/view_components. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [Contributor Covenant](http://contributor-covenant.org) code of conduct.
### Setting up
Run
```bash
script/setup
```
to install all necessary dependencies
### Storybook
*We recommend having [overmind](https://github.com/DarthSim/overmind) installed to run both rails and storybook, but it is not required.*
To run storybook:
```bash
script/storybook
```
### Developing with another app
In your `Gemfile`, change:
```ruby
gem "primer_view_components"
```
to
```ruby
gem "primer_view_components", path: "path_to_the_gem" # e.g. path: "~/primer/view_components"
```
Then, `bundle install` to update references. You'll now be able to see changes from the gem without having to build it.
Remember that restarting the Rails server is necessary to see changes, as the gem is loaded at boot time.
To minimize the number of restarts, we recommend checking the component in Storybook first, and then when it's in a good state,
you can check it in your app.
## License
The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).