Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/yuki24/shoelace-rails

Rails helpers for https://shoelace.style, the design system.
https://github.com/yuki24/shoelace-rails

custom-elements design-system rails ruby ruby-on-rails shoelace ui ux web-components webcomponents

Last synced: about 2 months ago
JSON representation

Rails helpers for https://shoelace.style, the design system.

Awesome Lists containing this project

README 

        
# 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



  

  

  



  

    Option 1

    Option 2

    Option 3

  



  

    Option 1

    Option 2

    Option 3

  



  Create User



```



#### 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_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



  Next Page



```



With a block:



```erb

<%= sl_button_to "/components?page=2" do %>

  Next Page 

<% end %>

```



```html



 Next Page



```



#### `#sl_icon_tag`



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



```erb

<%= sl_icon_tag "apple" %>

```



```html



```



## 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).