# Shoelace Rails

The `shoelace-rails` gem adds useful helper methods for [Shoelace.style](https://shoelace.style), the design system.

## Compatibility with Shoelace

* **For Shoelace version >= 2.0.0-beta.88, use the gem version `0.4.0` or above**.
* For Shoelace version <= 2.0.0-beta.87, use the gem version `0.3.0`.

## Installation

Add this line to your application's Gemfile:

```ruby
gem 'shoelace-rails'
```

And then execute:

```
$ bundle install
```

Additionally, you need to add the following npm packages:

```sh
$ yarn add @shoelace-style/shoelace
```

## Set up CSS

### Asset Pipeline

Add the following lines to the `app/assets/stylesheets/application.css` if you need the sprockets gem:

```scss
/*
 *= require @shoelace-style/shoelace/dist/themes/light.css
 *= require @shoelace-style/shoelace/dist/themes/dark.css
 */
```

### Webpack & CSS Loader

Add the following lines to the `app/packs/entrypoints/application.js` if you prefer the webpack and CSS loader:

```js
import "@shoelace-style/shoelace/dist/themes/light.css"
import "@shoelace-style/shoelace/dist/themes/dark.css" // Optional dark mode
```

## Set up Javascript

In this README, it is assumed that you are using a JS bundler such as `webpack` or `esbuild`. In order to define all
the custome elements,  import the shoelace dependency in the entrypoint file:

```js
import "@shoelace-style/shoelace"
```

That's it!

### Shoelace Icons

Shoelace icons are automatically set up to load properly, so you don't need to add any extra code. More specifically,

 * In development, the icons are served by the `ActionDispatch::Static` middleware, directly from the
   `node_modules/@shoelace-style/shoelace/dist/assets/icons` directory.
 * In production, the icon files are automatically copied into the `public/assets` directory as part of the
   `assets:precompile` rake task.

## View Helpers

As explained above, this gem provides drop-in replacements to Rails view helpers.

### Form Helpers

The `sl_form_with` or `sl_form_for` method could be used to generate a form with the Shoelace components:

```erb
<%= sl_form_for @user do |form| %>
  <%  # Text input: https://shoelace.style/components/input %>
  <%= form.text_field :name %>
  <%= form.password_field :password, placeholder: "Password Toggle", 'toggle-password': true %>

  <%  # Radio buttons: https://shoelace.style/components/color-picker %>
  <%= form.color_field :color %>

  <%  # Radio buttons: https://shoelace.style/components/radio %>
  <%= form.collection_radio_buttons :status, { id_1: "Option 1", id_2: "Option 2", id_3: "Option 3" }, :first, :last %>

  <%  # Select: https://shoelace.style/components/select %>
  <%= form.collection_select :tag, { id_1: "Option 1", id_2: "Option 2", id_3: "Option 3" }, :first, :last, {}, { placeholder: "Select one" } %>

  <%= form.submit %>
<% end %>
```

And this code will produce:

```html
<form class="new_user" id="new_user" data-remote="true" action="/" accept-charset="UTF-8" method="post">
  <sl-input label="Name" type="text" name="user[name]" id="user_name"></sl-input>
  <sl-input label="Password" type="password" name="user[password]" id="user_password"></sl-input>
  <sl-color-picker value="#ffffff" name="user[color]" id="user_color"></sl-color-picker>

  <sl-radio-group no-fieldset="true">
    <sl-radio value="id_1" name="user[status]" id="user_status_id_1">Option 1</sl-radio>
    <sl-radio value="id_2" name="user[status]" id="user_status_id_2">Option 2</sl-radio>
    <sl-radio value="id_3" name="user[status]" id="user_status_id_3">Option 3</sl-radio>
  </sl-radio-group>

  <sl-select placeholder="Select one" name="user[tag]" id="user_tag">
    <sl-menu-item value="id_1">Option 1</sl-menu-item>
    <sl-menu-item value="id_2">Option 2</sl-menu-item>
    <sl-menu-item value="id_3">Option 3</sl-menu-item>
  </sl-select>

  <sl-button submit="true" type="primary" data-disable-with="Create User">Create User</sl-button>
</form>
```

#### Using The `sl-select` component with `multiple`

TDB

#### Using the Shoelace FormBuilder with other gems

Sometimes you want to use the Shoelace FormBuilder with other gems, such as [ransack](https://github.com/activerecord-hackery/ransack).
In this case, you can not use the `sl_form_for` or `sl_form_with` methods in tandem with `ransack`, but you can use
the `Shoelace::FormBuilder` with e.g. [the `search_form_for` method](https://activerecord-hackery.github.io/ransack/getting-started/simple-mode/#form-helper):

```erb
<%= search_form_for @q, builder: Shoelace::FormBuilder do |form| %>
  ...
<% end %>
```

### Tag Helpers

#### `#sl_avatar_tag`

The `@sl_avatar_tag` method behaves just like the `image_tag` method.

```erb
<%= sl_avatar_tag "/path/to/image.jpg" %>
```

Will produce:

```html
<sl-avatar image="/path/to/image.jpg"></sl-avatar>
```

#### `#sl_button_to`

The `sl_button_to` method behaves just like the `link_to` method. Note that this is slightly different from the
built-in `button_to` method.

Without a block:

```erb
<%= sl_button_to "Next Page", "/components?page=2" %>
```

```html
<sl-button href="/components?page=2">
  Next Page
</sl-button>
```

With a block:

```erb
<%= sl_button_to "/components?page=2" do %>
  Next Page 
<% end %>
```

```html
<sl-button href="/components?page=2">
 Next Page
</sl-button>
```

#### `#sl_icon_tag`

The `sl_icon_tag` method takes the `name` attribute value as the first argument:

```erb
<%= sl_icon_tag "apple" %>
```

```html
<sl-icon name="apple"></sl-icon>
```

## Development

 1. Run `bundle install`
 2. Make a change and add test coverage
 3. Run `bundle rails test`
 4. Make a commit and push it to GitHub
 5. Send us a pull request

## Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/yuki24/shoelace-rails. This project is
intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the
[code of conduct](https://github.com/yuki24/shoelace-rails/blob/master/CODE_OF_CONDUCT.md).

## License

The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

## Code of Conduct

Everyone interacting in the Shoelace::Rails project's codebases, issue trackers, chat rooms and mailing lists is
expected to follow the [code of conduct](https://github.com/yuki24/shoelace-rails/blob/master/CODE_OF_CONDUCT.md).