fontawesome_icons_rails 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: d871e9135cdfc4bc928f9db6834026b830acfea6ed2b95681039280700a62437
+  data.tar.gz: 659dd8955884d0c9edb98c48ab1330509220227c2aabb74b198e7ea037940d4e
+SHA512:
+  metadata.gz: c8d4dd8d09c85c7013deddce4a03b5ba68647bc43b8d317fc95ca9311137274c1883f39f5b87872722bfb81125f96bcce5205fb23866e0433d7488394cb31cb6
+  data.tar.gz: 310e061d66e4ef448c1222e5eef167ca5f5dead3fadca1c86988cc2723902804a114290fdff48546cccf51e8d214d37eadda14472c25b3dcbd23b71c8cd95179

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright 2018 tomas.kral@railsformers.com
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,418 @@
+# fontawesome_rails
+**fontawesome_rails** provides **Font Awesome 5/6/7** assets and helpers as a Rails engine for use with the asset pipeline.
+
+This gem provides only **Free** icons from Font Awesome by default, but supports importing **Pro** assets into your app.
+
+Keep track of changes in `CHANGELOG.md`.
+
+## Requirements
+
+- **Rails**: 7.2+ (including Rails 8.x)
+- **Ruby**:
+  - Rails 7.2: 3.1+
+  - Rails 8.x: 3.2+
+
+## Credits
+
+This project is based on and inspired by [`tomkr4l/font_awesome5_rails`](https://github.com/tomkr4l/font_awesome5_rails).
+
+## Vendored Font Awesome versions
+
+<!-- BEGIN VENDORED_VERSIONS -->
+- **FA5**: `5.15.4`
+- **FA6**: `6.7.2`
+- **FA7**: `7.1.0`
+<!-- END VENDORED_VERSIONS -->
+
+## Table of Contents
+
+**[Installation](#installation)** <br />
+
+- **[Install as webfont with CSS](#install-as-webfont-with-css)** <br />
+- **[Install as SVG with JS](#install-as-SVG-with-JS)** <br />
+- **[Install with webpack](#install-with-webpack)** <br />
+
+**[Usage](#usage)** <br />
+
+- **[Basic usage](#basic-usage)** <br />
+- **[Solid, Regular, Light, Brand icon types](#solid-regular-light-brand-icon-types)** <br />
+- **[Animations and data attributes](#animations-and-data-attributes)** <br />
+- **[Layered and Stacked icons](#layered-and-stacked-icons)** <br />
+
+**[Use as images](#use-as-images)** <br />
+**[Use inline SVGs](#use-inline-svgs)** <br />
+**[Font Awesome Pro assets](#font-awesome-pro-assets)** <br />
+
+## Installation
+
+You have two options for including Font Awesome icons. The first option is to use `SVG` + `JS`, which is recommended by the Font Awesome team. However, you can also use icons as `webfont with CSS`, but you will not be able to use some features (such as animations or layered icons). Choose one installation option from above:
+
+See the differences [here](https://fontawesome.com/how-to-use/on-the-web/setup/getting-started?using=svg-with-js&explain=using).
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'fontawesome_icons_rails'
+```
+
+Generate (or create) `config/initializers/fontawesome_rails.rb` (default is 7):
+
+```bash
+bin/rails g fontawesome_rails:install
+```
+
+```ruby
+FontawesomeRails.configure do |config|
+  config.major_version = 7 # 5, 6, or 7
+end
+```
+
+### Asset delivery (Sprockets / Propshaft / Importmap)
+
+How you *serve* the gem’s assets depends on your Rails setup. Pick the section that matches your app.
+
+#### Sprockets (asset pipeline)
+
+- Use the `require` / `@import` instructions below (“Install as webfont…” / “Install as SVG…”).
+- **No `manifest.js` changes required**: when `sprockets-rails` is present, this gem automatically registers its Font Awesome assets for precompile.
+  - If you prefer managing precompile manually, disable it:
+
+```ruby
+FontawesomeRails.configure do |config|
+  config.sprockets_precompile = false
+end
+```
+
+Note: `fontawesome` / `fontawesome_webfont` are provided as SCSS (erb). If your app does **not** have the `sassc` gem, prefer requiring the prebuilt versioned CSS directly (e.g. `fontawesome/v7/svg-with-js.css` or `fontawesome/v7/webfont.css`).
+
+#### Propshaft (no SCSS compilation)
+
+If you use **Propshaft** (no SCSS compilation), include the prebuilt CSS/JS assets directly (pick the version you want):
+
+- **Webfonts**:
+  - CSS: `fontawesome/v7/webfont.css` (or `v6` / `v5`)
+  - JS (optional): `fontawesome/v7/all.min.js` (only needed for SVG+JS)
+- **SVG + JS**:
+  - CSS: `fontawesome/v7/svg-with-js.css` (or `v6` / `v5`)
+  - JS: `fontawesome/v7/all.min.js`
+
+#### Importmap (importmap-rails)
+
+If you use **importmap-rails** and want **SVG + JS**, opt-in to a gem-provided importmap pin for `fontawesome` (based on `config.major_version`):
+
+```ruby
+FontawesomeRails.configure do |config|
+  config.importmap_pin = true
+end
+```
+
+Then add this to your JavaScript entrypoint:
+
+```js
+import "fontawesome";
+```
+
+Importmap only covers the JS side. You still need to include CSS via **Sprockets** (sections below) or **Propshaft** (prebuilt `*.css` files above).
+
+### 1. Install as webfont with CSS
+
+In your `application.css`, include the CSS file:
+
+```css
+ *= require fontawesome_webfont
+```
+
+Or, if you prefer SCSS, add this to your `application.css.scss` file:
+
+```scss
+@import "fontawesome_webfont";
+```
+
+### 2. Install as SVG with JS
+
+In your `application.css`, include the CSS file:
+
+```css
+ *= require fontawesome
+```
+
+Or, if you prefer SCSS, add this to your `application.scss` file:
+
+```scss
+@import "fontawesome";
+```
+
+In your `application.js`, include the JavaScript file:
+
+```javascript
+#= require fontawesome
+```
+
+### 3. Install with webpack
+
+If you want to install Font Awesome with `yarn` or `npm` and still use helpers from this gem, it's possible.
+
+First add Font Awesome to your `package.json`.
+
+```shell
+$ yarn add @fortawesome/fontawesome-free
+```
+
+Next, import Font Awesome in your `app/javascript/packs/application.js`. You can find more about importing in the [Font Awesome docs](https://fontawesome.com/how-to-use/with-the-api/setup/importing-icons).
+
+Now you have icons installed through webpack, and you can still use the `fa_icon` helpers.
+
+### 4. Install webfont with CSS Bundling + Propshaft (npm-managed)
+
+To install the webfont on Rails 7+ with [Propshaft][] and [CSS Bundling][] (using Dart Sass), follow these instructions.
+
+First, add Font Awesome 5 to your ```package.json```:
+
+```shell
+$ npm install "@fortawesome/fontawesome-free@^5.0.0"
+```
+
+Then, copy the fonts to `app/assets`:
+
+```shell
+$ mkdir -p app/assets/fonts
+$ cp -a node_modules/@fortawesome/fontawesome-free/webfonts app/assets/fonts/
+```
+
+Finally, add this to your `app/assets/stylesheets/application.sass.scss`:
+
+```scss
+$fa-font-path: "/webfonts";
+@import "@fortawesome/fontawesome-free/scss/fontawesome";
+@import "@fortawesome/fontawesome-free/scss/regular";
+@import "@fortawesome/fontawesome-free/scss/solid";
+@import "@fortawesome/fontawesome-free/scss/brands";
+@import "@fortawesome/fontawesome-free/scss/v4-shims";
+```
+
+[CSS Bundling]: https://github.com/rails/cssbundling-rails
+[Propshaft]: https://github.com/rails/propshaft
+
+## Usage
+
+This gem provides Font Awesome icons through a helper. In your views, call `fa_icon`.
+
+### Basic usage
+
+```ruby
+fa_icon('camera-retro')
+# => (FA7) <i class="fa-solid fa-camera-retro"></i>
+
+fa_icon('camera-retro', style: 'color: Tomato')
+# => (FA7) <i class="fa-solid fa-camera-retro" style="color:Tomato"></i>
+
+fa_icon('camera-retro', class: 'my-class', text: 'Camera', size: '3x')
+# => (FA7) <i class="fa-solid fa-camera-retro my-class fa-3x"></i>
+# =>  <span>Camera</span>
+
+fa_icon(:camera_retro, class: 'my-class')
+# => (FA7) <i class="fa-solid fa-camera-retro my-class"></i>
+
+fa_icon(:camera_retro, text: 'Camera', right: true)
+# =>  <span class="fa-text-r">Camera</span>
+# => (FA7) <i class="fa-solid fa-camera-retro"></i>
+```
+
+### Solid, Regular, Light, Brand, Duotone icon types
+
+Font Awesome has several different icon styles. In `fontawesome_rails`, the default icon type is `solid`.
+If you want to use a different style, you can do so through the `type` attribute.
+
+| Style   | type: | type:    |
+| ------- | ----- | -------- |
+| Solid   | :fas  | :solid   |
+| Regular | :far  | :regular |
+| Light   | :fal  | :light   |
+| Brand   | :fab  | :brand   |
+| Duotone | :fad  | :duotone |
+
+```ruby
+fa_icon('camera-retro', type: :solid) #Default
+# => (FA7) <i class="fa-solid fa-camera-retro"></i>
+
+fa_icon('camera-retro', type: :regular)
+# => (FA7) <i class="fa-regular fa-camera-retro"></i>
+
+fa_icon('camera-retro', type: :light)
+# => (FA7) <i class="fa-light fa-camera-retro"></i>
+
+fa_icon('camera-retro', type: :brand)
+# => (FA7) <i class="fa-brands fa-camera-retro"></i>
+
+fa_icon('camera-retro', type: :duotone)
+# => (FA7) <i class="fa-duotone fa-camera-retro"></i>
+
+fa_icon('camera-retro', type: :fab)
+# => (FA7) <i class="fa-brands fa-camera-retro"></i>
+
+fa_icon('custom-uploaded', type: :fak)
+# => <i class="fak fa-custom-uploaded"></i>
+
+fa_icon('custom-uploaded', type: :uploaded)
+# => <i class="fak fa-custom-uploaded"></i>
+
+```
+
+Each icon type has its own helper method, so you don't need to provide the `type` attribute in every call.
+This can be overridden if `type` is explicitly provided.
+
+```ruby
+far_icon('camera-retro')
+# => <i class="far fa-camera-retro"></i>
+
+far_icon('camera-retro', type: :fab)
+# => <i class="fab fa-camera-retro"></i>
+
+far_stacked_icon('camera', base: 'circle')
+# => <span class="fa-stack">
+# =>   <i class="far fa-circle fa-stack-2x"></i>
+# =>   <i class="far fa-camera fa-stack-1x"></i>
+# => </span>
+
+far_stacked_icon('camera', base: 'circle', type: :fal)
+# => <span class="fa-stack">
+# =>   <i class="fal fa-circle fa-stack-2x"></i>
+# =>   <i class="fal fa-camera fa-stack-1x"></i>
+# => </span>
+
+```
+
+### Animations and data attributes
+
+Font Awesome provides animations and data attributes. Here are some examples of how to use them:
+
+```ruby
+fa_icon('camera-retro', animation: 'spin')
+# => <i class="fas fa-camera-retro fa-spin"></i>
+
+fa_icon('camera-retro', data: {'fa-transform': 'rotate-90'})
+# => <i class="fas fa-camera-retro" data-fa-transform="rotate-90"></i>
+
+```
+
+By default, helper text is rendered right next to the icon. For better readability, the text has a default `padding-left: 5px;`. If you want to override this setting, you can do so via the `.fa-text` class in your CSS.
+
+### Layered and Stacked icons
+
+Font Awesome provides layered icons. For backward compatibility, the `fa_stacked_icon` helper is preserved, but you can accomplish the same result with `fa_layered_icon`.
+
+#### Layered icon examples
+
+`fa_layered_icon` takes options and block of code that will be rendered inside.
+
+Following `fa_layered_icon` examples are written in `haml`.
+
+```ruby
+= fa_layered_icon do
+  = fa_icon 'circle'
+# => <span class="fa-layers fa-fw">
+# =>   <i class="fas fa-circle"></i>
+# => </span>
+
+= fa_layered_icon style: 'background: MistyRose', size: '4x' do
+  = fa_icon 'circle', style: 'color: Tomato'
+  = fa_icon 'times', class: 'fa-inverse', data: { fa_transform: 'shrink-6' }
+# => <div class="fa-4x">
+# =>   <span class="fa-layers fa-fw" style="background: MistyRose">
+# =>     <i class="fas fa-circle" style="color: Tomato"></i>
+# =>     <i class="fas fa-times fa-inverse" data-fa-transform="shrink-6"></i>
+# =>   </span>
+# => </div>
+
+= fa_layered_icon aligned: :false do
+  = fa_icon 'circle'
+  %span.fa-layers-text= "Text"
+  %span.fa-layers-counter= "1,419"
+# => <span class="fa-layers">
+# =>   <i class="fas fa-circle"></i>
+# =>   <span class="fa-layers-counter">1,419</span>
+# => </span>
+```
+
+#### Stacked icon examples
+
+For different base icon type you can use `base_type` option.
+
+```ruby
+fa_stacked_icon('camera', base: 'circle')
+# => <span class="fa-stack">
+# =>   <i class="fas fa-circle fa-stack-2x"></i>
+# =>   <i class="fas fa-camera fa-stack-1x"></i>
+# => </span>
+
+fa_stacked_icon('camera inverse', base: 'circle', type: :fas, class: 'my-class') #Default :fas is default type
+# => <span class="fa-stack my-class">
+# =>   <i class="fas fa-circle fa-stack-2x"></i>
+# =>   <i class="fas fa-camera fa-inverse fa-stack-1x"></i>
+# => </span>
+
+fa_stacked_icon('camera', base: 'circle', reverse: true, text: 'Text!') #Default: reverse: false
+# => <span class="fa-stack">
+# =>   <i class="fas fa-circle fa-stack-1x"></i>
+# =>   <i class="fas fa-camera fa-stack-2x"></i>
+# => </span>Text!
+
+fa_stacked_icon('camera', base: 'circle', type: :fas, base_type: :fab)
+# => <span class="fa-stack">
+# =>   <i class="fab fa-circle fa-stack-2x"></i>
+# =>   <i class="fas fa-camera fa-stack-1x"></i>
+# => </span>
+
+fa_stacked_icon('camera', base: 'circle', type: :fas, base_type: :fab, base_options: { class: 'base' }, icon_options: { style: 'color: red' })
+# => <span class="fa-stack">
+# =>   <i class="fab fa-circle fa-stack-2x base"></i>
+# =>   <i class="fas fa-camera fa-stack-1x" style="color: red"></i>
+# => </span>
+
+```
+
+## Use as images
+
+```ruby
+image_tag('fa5/solid/camera.svg')
+image_tag('fa5/brand/facebook.svg')
+image_tag('fa5/regular/bell.svg', width: '100px', class: 'my-img')
+```
+
+More examples can be found in specs.
+
+More animation and data attributes can be found on [FontAwesome documentation](https://fontawesome.com/how-to-use/svg-with-js).
+
+## Use inline SVGs
+
+You can also include icons as inline SVGs in your views directly, avoiding any JS entirely.
+
+```ruby
+fa_inline_icon('camera') # defaults to solid
+fa_inline_icon('camera', style: :solid)
+fa_inline_icon('camera', class: 'my-svg')
+```
+
+There are also helpers for the various styles available:
+
+```ruby
+fas_inline_icon('camera')
+fab_inline_icon('facebook')
+far_inline_icon('bell')
+```
+
+## Font Awesome Pro assets
+
+If you have a downloaded Font Awesome Pro zip, you can import it into your app (so the gem’s helpers can render Pro icons and styles):
+
+```bash
+bin/rails g fontawesome_rails:install_pro --zip /path/to/fontawesome-pro-*.zip --major 7
+```
+
+If you have any questions, feel free to create a new issue.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT).
+
+[Font Awesome License](https://fontawesome.com/license).

data/Rakefile

@@ -0,0 +1,21 @@
+begin
+  require 'bundler/setup'
+rescue LoadError
+  puts 'You must `gem install bundler` and `bundle install` to run rake tasks'
+end
+
+require 'rdoc/task'
+
+RDoc::Task.new(:rdoc) do |rdoc|
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title    = 'FontawesomeRails'
+  rdoc.options << '--line-numbers'
+  rdoc.rdoc_files.include('README.md')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end
+
+require 'bundler/gem_tasks'
+
+require 'rspec/core/rake_task'
+RSpec::Core::RakeTask.new(:spec)
+task default: :spec