fa_rails 0.1.2 → 0.1.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 0fd53c5e9810de9d7364425d8928e032741a5df3
-  data.tar.gz: adb052186b5ab4bedd77e27f43cc5e6d973a8915
+  metadata.gz: e0f88269f81e443d27897b42865438b0f2b4dd70
+  data.tar.gz: 1eb05c958c102f6f6c2c8e00009b90f934d596d0
 SHA512:
-  metadata.gz: e11ee40165dd680bc382c66cc2e9d2e62ba81c8e622a336b1a016c4f956712ed873791f6f1e190212058c9c5068ae7fc01bae148a856659ff3e2c375c47f0649
-  data.tar.gz: 02531dc100ff594a87528bf015dccee154d53bf5ba56b0418d2219b8bb6ab487eaa126331082b39a5bf892a189be741f5743f9da17047740934642c154d1cf58
+  metadata.gz: 1ebb0c7826814759264e16f9752b7cc1bcff1b064a2ff4479efbd057e4dfb62504dc4fbf23244bb073170988fa77119811e4d59920b8136eb775153a1d7c723e
+  data.tar.gz: bf6727814a5611ac6bba85fed25fbf142a5ee22dbc8fabc7b39de40eafc5be2be12d3da32aa13b2dc3517ccd80ad08de8a3d2231a1c0449283610670738f638f

data/.travis.yml

@@ -0,0 +1,18 @@
+language: ruby
+rvm:
+  - 2.4.2
+branches:
+  except:
+    - "/^v[0-9]+\\.[0-9]+\\.[0-9]+(?:-.*)?/"
+notifications:
+  email:
+    on_success: change
+    on_failure: always
+before_script:
+  - curl -L https://codeclimate.com/downloads/test-reporter/test-reporter-latest-linux-amd64 > ./cc-test-reporter
+  - chmod +x ./cc-test-reporter
+  - ./cc-test-reporter before-build
+script:
+  - bundle exec rspec
+after_script:
+  - ./cc-test-reporter after-build --exit-code $TRAVIS_TEST_RESULT

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    fa_rails (0.1.2)
+    fa_rails (0.1.3)
       file_utils (~> 1.1, >= 1.1.2)
 
 GEM

data/README.md

@@ -10,9 +10,119 @@ You must still have your own FontAwesome Pro license, or install the
 [Free](https://use.fontawesome.com/releases/v5.2.0/fontawesome-free-5.2.0-web.zip)
 package.
 
-Copy the
-[web download files](https://fontawesome.com/releases/5.2.0/web/download) to the
-appropriate locations in your app:
+Copy the complete `js` and `css` directories from the
+[web download](https://fontawesome.com/releases/5.2.0/web/download) into the
+corresponding locations in your app, and ensure you correctly include all files.
 
-- `js` => `app/asets/javascripts`
-- `css` => `app/assets/stylesheets`
+Add the following to `config/application.rb`:
+
+```ruby
+require 'fa'
+```
+
+## Usage
+
+The `FA` module contains three main subclasses: `Icon`, `Span`, and `Layer`.
+Argument formatting is consistent throughout.
+
+`Icon` and `Span` are the units of this module. Both can be used individually.  
+The first argument of each class's `new` method can be either a String/Symbol of
+the name of the FontAwesome icon, or a Hash containing the complete
+configuration for the object.
+
+`Layer` is used to combine multiple units into a single end object. It takes
+advantage of the Hash input style on `Icon` and `Span` to allow it to accept a
+single configuration Hash for the entire stack.
+
+All three classes respond to two output methods: `raw` and `safe`.
+
+- `raw` outputs the formatted string directly
+- `safe` attempts to call `.html_safe` on the formatted string, if available
+
+### Icon
+
+A single FontAwesome icon.
+
+#### Icon Arguments
+
+```ruby
+fa #=> String / Symbol – OR Hash
+options #=> Hash
+  style: Symbol # One of [:solid, :regular, :light, :brands], default :solid
+  size: Integer # Stepped scaling factor
+
+  css: String # Arbitrary CSS classes, space-delimited
+  fa: String # Arbitrary FA classes, space-delimited – each is automatically prefixed with `fa-`
+  title: String #=> Tooltip text
+  grow: Integer #=> Transform value – amount to grow by
+  shrink: Integer #=> Transform value – amount to shrink by
+  rotate: Integer #=> Transform value – amount to rotate by
+  up: Integer #=> Translation value upward
+  down: Integer #=> Translation value downward
+  left: Integer #=> Translation value leftward
+  right: Integer #=> Translation value rightward
+```
+
+### Span
+
+A single FontAwesome span – counters or text labels – to be used in a Layer.
+
+#### Span Arguments
+
+```ruby
+fa #=> String / Symbol – one of [:counter, :text] – OR Hash
+text #=> String
+options #=> Hash
+  position: Symbol # Indicator of which corner to display on – one of [:tr, :tl, :br, :bl]
+
+  css: String # Arbitrary CSS classes, space-delimited
+  fa: String # Arbitrary FA classes, space-delimited – each is automatically prefixed with `fa-`
+  title: String #=> Tooltip text
+  grow: Integer #=> Transform value – amount to grow by
+  shrink: Integer #=> Transform value – amount to shrink by
+  rotate: Integer #=> Transform value – amount to rotate by
+  up: Integer #=> Translation value upward
+  down: Integer #=> Translation value downward
+  left: Integer #=> Translation value leftward
+  right: Integer #=> Translation value rightward
+```
+
+### Layer
+
+A stack of layered FontAwesome icons and spans.
+
+#### Layer Arguments
+
+```ruby
+icons #=> Hash of icon/span configurations
+title #=> String for tooltip text
+grow #=> Additional global scaling factor added to all objects in the stack
+css # Arbitrary CSS classes, space-delimited, applied to the layer stack
+```
+
+### Examples
+
+```ruby
+# Fixed-width lock icon
+FA::Icon.new('lock', fa: 'fw').safe
+#=> "<i class='fas fa-fw fa-lock' data-fa-transform='' title=''></i>"
+
+# Counter span, with value 5
+FA::Span.new('counter', 5).safe
+#=> "<span class='fa-layers-counter ' data-fa-transform=''>5</span>
+
+# Gray envelope icon with red exclamation mark overlayed, with tooltip 'Invalid email address'
+FA::Layer.new([{ name: 'envelope', options: { css: :gray } }, { name: 'exclamation', options: { css: :red } }], title: 'Invalid email address').safe
+#=> "<span class='icon fa-layers fa-fw ' title='Invalid email address'>" \
+#   "<i class='fas gray fa-envelope' data-fa-transform='grow-0' title=''></i>" \
+#   "<i class='fas red fa-exclamation' data-fa-transform='grow-0' title=''></i>" \
+#   "</span>"
+
+# Blue envelope with red counter on the top left corner, with value 7
+FA::Layer.new([{ name: 'envelope', options: { css: :blue } }, { name: 'counter', text: 7, options: { css: :red, position: :tl } }]).safe
+#=> "<span class='icon fa-layers fa-fw ' title=''>" \
+#   "<i class='fas gray fa-envelope' data-fa-transform='grow-0' title=''></i>" \
+#   "<span class='red fa-layers-counter ' data-fa-transform='grow-0'>7" \
+#   "</span>" \
+#   "</span>"
+```

data/fa_rails.gemspec

@@ -1,6 +1,6 @@
 Gem::Specification.new do |s|
   s.name          = 'fa_rails'
-  s.version       = '0.1.2'
+  s.version       = '0.1.3'
   s.date          = '2018-07-27'
   s.summary       = 'FontAwesome helper for Rails'
   s.description   = 'A helper module for using FontAwesome icons in Rails.'

data/lib/fa/base.rb

@@ -0,0 +1,123 @@
+# frozen_string_literal: true
+
+module FA
+  # FontAwesome 5 (Pro) Helper core class
+  class Base
+    def raw
+      #
+    end
+
+    def safe
+      safe_output(raw)
+    end
+
+    private
+
+    def safe_output(output)
+      # html_safe: No user content
+      output.respond_to?(:html_safe) ? output.html_safe : output
+    end
+
+    def parse_all(icons)
+      icons.map do |icon|
+        name = icon[:name]
+        options = icon[:options] || {}
+
+        if %i[counter text].include?(name.to_sym)
+          parse_span(name, icon[:text], options)
+        else
+          parse_icon(name, options)
+        end
+      end
+    end
+
+    def parse_icon(name, options = {})
+      options = fa_options(options)
+      parse_options(options)
+      title = options[:title]
+
+      @classes << "fa-#{name}"
+      @classes << "fa-#{size_x(options[:size])}" if !!options[:size]
+      css = @classes.flatten.join(' ')
+      transforms = @transforms.join(' ')
+
+      "<i class='#{css}' data-fa-transform='#{transforms}' title='#{title}'></i>"
+    end
+
+    def parse_span(type, text, options = {})
+      options.delete(:style)
+      options = fa_options(options)
+      parse_options(options)
+      pos = options.delete(:position)
+      position = long_position(pos) if !!pos
+
+      @classes << "fa-layers-#{type}"
+      @classes << (!!position ? "fa-layers-#{position}" : '')
+      css = @classes.flatten.reject { |c| c.to_s.match?(/^fa.$/) }.join(' ')
+      transforms = @transforms.join(' ')
+
+      "<span class='#{css}' data-fa-transform='#{transforms}'>#{text}</span>"
+    end
+
+    def fa_options(options)
+      default = { style: :solid, css: '', fa: '' }
+
+      default.merge(options.to_h)
+    end
+
+    def combine_grows(i, grow)
+      if i.key?(:options) && i[:options].key?(:grow)
+        i[:options][:grow] + grow
+      else
+        grow
+      end
+    end
+
+    def combine_options(i, combined_grow)
+      if i.key?(:options)
+        i[:options].merge(grow: combined_grow)
+      else
+        { grow: combined_grow }
+      end
+    end
+
+    def size_x(size)
+      return '' unless !!size || size == 1
+      "#{size}x"
+    end
+
+    def long_position(position)
+      return 'top-right' if position == :tr
+      return 'top-left' if position == :tl
+      return 'bottom-right' if position == :br
+      return 'bottom-left' if position == :bl
+    end
+
+    def parse_options(options)
+      parse_classes(options)
+      parse_transforms(options)
+    end
+
+    def parse_classes(options)
+      @classes = []
+      @classes << parse_style(options[:style])
+      @classes << options[:fa].to_s.split(' ').map { |c| "fa-#{c}" }
+      @classes << options[:css].to_s.split(' ')
+    end
+
+    def parse_transforms(options)
+      @transforms = []
+      %i[grow shrink rotate up down left right].each do |transform|
+        if !!options[transform]
+          @transforms << "#{transform}-#{options[transform]}"
+        end
+      end
+    end
+
+    def parse_style(style)
+      return 'fas' unless %i[solid regular light brands].include?(style)
+
+      'fa' + { solid: 's', regular: 'r', light: 'l', brands: 'b' }[style]
+    end
+  end
+end

data/lib/fa/layer.rb

@@ -8,16 +8,21 @@ module FA
       #
       # Note: scaling counters does not work well with :grow, so should use the
       # older "fa-3x" syntax in :css instead.
-      span_top = "<span class='icon fa-layers fa-fw #{css}' title='#{title}'>"
-      span_bottom = '</span>'
-
-      icons.each { |i| i[:options] = combine_options(i, combine_grows(i, grow)) }
-
-      @output = span_top + parse_all(icons).join + span_bottom
+      @icons = icons
+      @title = title
+      @grow = grow
+      @css = css
     end
 
     def raw
-      @output
+      span_top = "<span class='icon fa-layers fa-fw #{@css}' title='#{@title}'>"
+      span_bottom = '</span>'
+
+      @icons.each do |i|
+        i[:options] = combine_options(i, combine_grows(i, @grow))
+      end
+
+      span_top + parse_all(@icons).join + span_bottom
     end
   end
 end

data/lib/fa.rb

@@ -2,126 +2,8 @@
 
 # FontAwesome 5 (Pro) Helper
 module FA
-  class Base
-    require 'fa/icon'
-    require 'fa/span'
-    require 'fa/layer'
-
-    def raw
-      #
-    end
-
-    def safe
-      safe_output(raw)
-    end
-
-    private
-
-    def safe_output(output)
-      # html_safe: No user content
-      output.respond_to?(:html_safe) ? output.html_safe : output
-    end
-
-    def parse_all(icons)
-      icons.map do |icon|
-        name = icon[:name]
-        options = icon[:options] || {}
-
-        if %i[counter text].include?(name)
-          parse_span(name, icon[:text], options)
-        else
-          parse_icon(name, options)
-        end
-      end
-    end
-
-    def parse_icon(name, options = {})
-      options = fa_options(options)
-      parse_options(options)
-      title = options[:title]
-
-      @classes << "fa-#{name}"
-      @classes << "fa-#{size_x(options[:size])}" if !!options[:size]
-      css = @classes.flatten.join(' ')
-      transforms = @transforms.join(' ')
-
-      "<i class='#{css}' data-fa-transform='#{transforms}' title='#{title}'></i>"
-    end
-
-    def parse_span(type, text, options = {})
-      options.delete(:style)
-      options = fa_options(options)
-      parse_options(options)
-      pos = options.delete(:position)
-      position = long_position(pos) if !!pos
-
-      @classes << "fa-layers-#{type}"
-      @classes << (!!position ? "fa-layers-#{position}" : '')
-      css = @classes.flatten.reject { |c| c.to_s.match?(/^fa.$/) }.join(' ')
-      transforms = @transforms.join(' ')
-
-      "<span class='#{css}' data-fa-transform='#{transforms}'>#{text}</span>"
-    end
-
-    def fa_options(options)
-      default = { style: :solid, css: '', fa: '' }
-
-      default.merge(options.to_h)
-    end
-
-    def combine_grows(i, grow)
-      if i.key?(:options) && i[:options].key?(:grow)
-        i[:options][:grow] + grow
-      else
-        grow
-      end
-    end
-
-    def combine_options(i, combined_grow)
-      if i.key?(:options)
-        i[:options].merge(grow: combined_grow)
-      else
-        { grow: combined_grow }
-      end
-    end
-
-    def size_x(size)
-      return '' unless !!size || size == 1
-      "#{size}x"
-    end
-
-    def long_position(position)
-      return 'top-right' if position == :tr
-      return 'top-left' if position == :tl
-      return 'bottom-right' if position == :br
-      return 'bottom-left' if position == :bl
-    end
-
-    def parse_options(options)
-      parse_classes(options)
-      parse_transforms(options)
-    end
-
-    def parse_classes(options)
-      @classes = []
-      @classes << parse_style(options[:style])
-      @classes << options[:fa].to_s.split(' ').map { |c| "fa-#{c}" }
-      @classes << options[:css].to_s.split(' ')
-    end
-
-    def parse_transforms(options)
-      @transforms = []
-      %i[grow shrink rotate up down left right].each do |transform|
-        if !!options[transform]
-          @transforms << "#{transform}-#{options[transform]}"
-        end
-      end
-    end
-
-    def parse_style(style)
-      return 'fas' unless %i[solid regular light brands].include?(style)
-
-      'fa' + { solid: 's', regular: 'r', light: 'l', brands: 'b' }[style]
-    end
-  end
+  require 'fa/base'
+  require 'fa/icon'
+  require 'fa/span'
+  require 'fa/layer'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: fa_rails
 version: !ruby/object:Gem::Version
-  version: 0.1.2
+  version: 0.1.3
 platform: ruby
 authors:
 - Julian Fiander
@@ -97,12 +97,14 @@ extensions: []
 extra_rdoc_files: []
 files:
 - ".gitignore"
+- ".travis.yml"
 - Gemfile
 - Gemfile.lock
 - README.md
 - Rakefile
 - fa_rails.gemspec
 - lib/fa.rb
+- lib/fa/base.rb
 - lib/fa/icon.rb
 - lib/fa/layer.rb
 - lib/fa/span.rb