anyicon 1.0.3 → 1.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3f72fd662c558d005d5707b0d42bff57d58bab8642b220a1997486c45f32553c
-  data.tar.gz: f3a4bf9cc2d295817735260d97b716356b4d46c269cd8eaac67f867a70a39a77
+  metadata.gz: cf910787f8f2afc33957a422c85c68bb6453522921dd9d1bbe8af16abea8370a
+  data.tar.gz: 4b3a381baec2cfd44707c1ac7bb37d2ccb5b23fa607d05695c4e827582559320
 SHA512:
-  metadata.gz: e32588d33dd2178c2ebbf91306c1a72ecce49af1c4b9c7f32410fbabfe70aca1f237bda6e1a7e16f92bde8c2112ffb754fe2a6529402d5d2880aea1912cb357d
-  data.tar.gz: ce2ae69a8c52fe073b155f12e85f1fcfb73913ceab1ad977e9f74b4c6b1e7ab22994b2dfff56729c97a71ba53060c93432482768abe02e9eede8e52f346ae0e6
+  metadata.gz: 60e1cb0856388ebf05ddd3cb4bd037445fc0e8191355079a8ee62b79f09f42e55b3be238484248af4a1578551b3fdc1e84e01a46c37e8481b84d325c9883ef72
+  data.tar.gz: '07293138a74f9cea182743a7700cd9cb8f3af4bd3e6dfd8fc2781b522ef1cc42c2f4d8fcb8a2cdd42cd583af9d48f81806271060b8f20b09b1441c97d0bb423e'

data/README.md

@@ -47,6 +47,11 @@ You can just use the anyicon helper in your views:
 ```erb
 <%= anyicon icon: 'fontawesome_regular:address-book' %>
 ```
+or
+
+```erb
+<%= anyicon 'fontawesome_regular:address-book' %>
+```
 
 ## Configuration
 
@@ -61,6 +66,33 @@ Anyicon.configure do |config|
 end
 ```
 
+Or add new collections while keeping the defaults:
+
+```ruby
+Anyicon.configure do |config|
+  config.add_collections(
+    my_custom_collection: { repo: 'user/repo', path: 'path/to/icons', branch: 'main' }
+  )
+end
+```
+
+### GitHub Token
+
+Anyicon fetches icons from GitHub. Without authentication, the GitHub API limits requests to **60 per hour**. If you use `Anyicon::Collection` to download entire collections, or your app fetches many icons on first deploy, you may hit this limit.
+
+Setting a GitHub personal access token raises the limit to **5,000 requests per hour**. The token is also used when downloading individual icons.
+
+```ruby
+# config/initializers/anyicon.rb
+Anyicon.configure do |config|
+  config.github_token = ENV["GITHUB_TOKEN"]
+end
+```
+
+To create a token, go to [GitHub Settings > Developer settings > Personal access tokens > Fine-grained tokens](https://github.com/settings/tokens?type=beta) and generate a token. No special permissions/scopes are needed — public repository read access is sufficient.
+
+> **Note:** This is optional. If you only use a few icons and they are already cached locally in `app/assets/images/icons/`, no API calls are made and no token is needed.
+
 ## Collections Available
 
 | Collection                           | Github List          | Example                          | Quantity | License |
@@ -85,13 +117,28 @@ Please, read the license before using any of these collections. This gem does no
 
 Fell free to add your own collection to this list.
 
+## Demo
+
+To see Anyicon in action with an interactive demo page:
+
+```sh
+git clone https://github.com/arthurmolina/anyicon.git
+cd anyicon
+bundle install
+RAILS_ENV=development bundle exec rackup -p 3000 test/dummy/config.ru
+```
+
+Then open [http://localhost:3000/demo](http://localhost:3000/demo).
+
+The demo showcases basic usage, sizing, colors, HTML/data/aria attributes, inline text components, and CSS animations.
+
 ## Development
 
 To get started with development:
 
-```
+```sh
 git clone https://github.com/arthurmolina/anyicon.git
-cd heroicon
+cd anyicon
 bundle install
 bundle exec rake test
 ```

data/app/helpers/anyicon/rails/icon_helper.rb

@@ -8,8 +8,8 @@ module Anyicon
       # @param icon [String] the name of the icon in the format 'collection:icon_name'
       # @param props [Hash] additional properties to apply to the SVG element
       # @return [String] the rendered SVG icon
-      def anyicon(icon:, **props)
-        Anyicon::Icon.render(icon:, **props)
+      def anyicon(icon = nil, **props)
+        Anyicon::Icon.render(icon, **props)
       end
     end
   end

data/lib/anyicon/collections.rb

@@ -1,8 +1,8 @@
 # frozen_string_literal: true
 
-require 'net/http'
-require 'json'
-require 'fileutils'
+require "net/http"
+require "json"
+require "fileutils"
 
 module Anyicon
   # The Collection class is responsible for managing icon collections
@@ -31,7 +31,8 @@ module Anyicon
     # @return [Array<Hash>] a list of icons with their metadata
     def list
       response = fetch(collection_url)
-      JSON.parse(response&.body || '{}')
+      result = JSON.parse(response&.body || "[]")
+      result.is_a?(Array) ? result : []
     end
 
     # Downloads all icons in the collection and saves them to the local file system.
@@ -39,7 +40,7 @@ module Anyicon
     # @return [void]
     def download_all
       if list.empty?
-        puts 'No icons available.'
+        ::Rails.logger.info "AnyIcon: No icons available for #{@collection}."
         return
       end
 
@@ -48,7 +49,7 @@ module Anyicon
         count += 1
         download(icon)
       end
-      puts "#{@collection}: #{count} downloads."
+      ::Rails.logger.info "AnyIcon: #{@collection}: #{count} downloads."
     end
 
     # Retrieves the configured collections from Anyicon.
@@ -65,12 +66,12 @@ module Anyicon
     # @param icon [Hash] the metadata of the icon to download
     # @return [void]
     def download(icon)
-      return if icon['download_url'].nil?
-      return if File.exist?(icon_path(icon['name']))
+      return if icon["download_url"].nil?
+      return if File.exist?(icon_path(icon["name"]))
 
-      FileUtils.mkdir_p(icon_path(icon['name']).dirname)
-      response = fetch(icon['download_url'])
-      File.write(icon_path(icon['name']), response.body)
+      FileUtils.mkdir_p(icon_path(icon["name"]).dirname)
+      response = fetch(icon["download_url"])
+      File.write(icon_path(icon["name"]), response.body)
     rescue ActionView::Template::Error, Net::HTTPError, Net::HTTPClientException => e
       ::Rails.logger.error "AnyIcon: Failed to download icon: #{e.message}"
     end
@@ -80,21 +81,25 @@ module Anyicon
     # @param icon_name [String] the name of the icon
     # @return [Pathname] the path to the icon file
     def icon_path(icon_name)
-      ::Rails.root.join('app', 'assets', 'images', 'icons', @collection.to_s, icon_name)
+      sanitized_collection = File.basename(@collection.to_s.gsub(/[^a-zA-Z0-9_\-]/, ""))
+      sanitized_name = File.basename(icon_name.to_s)
+      ::Rails.root.join("app", "assets", "images", "icons", sanitized_collection, sanitized_name)
     end
 
     # Constructs the URL to fetch the icon collection directory contents from the repository.
     #
     # @return [String, nil] the URL to fetch the collection contents, or nil if the collection is not configured
     def collection_url
-      return nil unless collections.keys.include?(@collection)
+      return nil unless collections.key?(@collection)
 
       [
-        'https://api.github.com/repos/',
+        "https://api.github.com/repos/",
         collections[@collection][:repo],
-        '/contents/',
-        collections[@collection][:path]
-      ].join('')
+        "/contents/",
+        collections[@collection][:path],
+        "?ref=",
+        collections[@collection][:branch]
+      ].join("")
     end
   end
 end

data/lib/anyicon/common.rb

@@ -12,6 +12,8 @@ module Anyicon
   #   response = common.fetch('https://example.com')
   #   puts response.body if response.is_a?(Net::HTTPSuccess)
   class Common
+    ALLOWED_HOSTS = %w[github.com raw.githubusercontent.com objects.githubusercontent.com api.github.com].freeze
+
     # Fetches the content from the given URL, following redirects if necessary.
     #
     # @param url [String] the URL to fetch
@@ -19,15 +21,25 @@ module Anyicon
     # @return [Net::HTTPResponse] the HTTP response
     # @raise [Net::HTTPError] if the number of redirects exceeds the limit or another HTTP error occurs
     def fetch(url, limit = 10)
-      raise Net::HTTPError, 'Too many HTTP redirects' if limit.zero?
+      raise Net::HTTPError.new("Too many HTTP redirects", nil) if limit.zero?
       return nil if url.nil?
 
-      uri = URI.parse(URI::DEFAULT_PARSER.escape(url))
-      response = Net::HTTP.get_response(uri)
+      uri = URI.parse(URI::RFC2396_PARSER.escape(url))
+      unless uri.is_a?(URI::HTTPS) && ALLOWED_HOSTS.include?(uri.host)
+        raise Net::HTTPError.new("Blocked request to disallowed host: #{uri.host}", nil)
+      end
+
+      request = Net::HTTP::Get.new(uri)
+      token = Anyicon.configuration.github_token
+      request["Authorization"] = "token #{token}" if token
+
+      response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
+        http.request(request)
+      end
 
       case response
       when Net::HTTPSuccess then response
-      when Net::HTTPRedirection then fetch(response['location'], limit - 1)
+      when Net::HTTPRedirection then fetch(response["location"], limit - 1)
       else
         response.error!
       end

data/lib/anyicon/configuration.rb

@@ -22,29 +22,33 @@ module Anyicon
     # A hash containing the default icon collections. Each collection specifies the
     # repository, path, and branch where the icons can be found.
     DEFAULT_COLLECTIONS = {
-      fontawesome_regular: { repo: 'FortAwesome/Font-Awesome', path: 'svgs/regular', branch: '6.x' },
-      fontawesome_solid: { repo: 'FortAwesome/Font-Awesome', path: 'svgs/solid', branch: '6.x' },
-      fontawesome_brands: { repo: 'FortAwesome/Font-Awesome', path: 'svgs/brands', branch: '6.x' },
-      heroicons_outline: { repo: 'tailwindlabs/heroicons', path: 'optimized/24/outline', branch: 'master' },
-      heroicons_solid: { repo: 'tailwindlabs/heroicons', path: 'optimized/24/solid', branch: 'master' },
-      tabler_icons_filled: { repo: 'tabler/tabler-icons', path: 'icons/filled', branch: 'main' },
-      tabler_icons_outline: { repo: 'tabler/tabler-icons', path: 'icons/outline', branch: 'main' },
-      mage_icons_fill: { repo: 'Mage-Icons/mage-icons', path: 'svg/bulk', branch: 'main' },
-      mage_icons_stroke: { repo: 'Mage-Icons/mage-icons', path: 'svg/stroke', branch: 'main' },
-      mage_icons_social_bw: { repo: 'Mage-Icons/mage-icons', path: 'svg/social-bw', branch: 'main' },
-      mage_icons_social_color: { repo: 'Mage-Icons/mage-icons', path: 'svg/social-color', branch: 'main' },
-      line_awesome: { repo: 'icons8/line-awesome', path: 'svg', branch: 'master' },
-      carbon: { repo: 'carbon-design-system/carbon', path: 'packages/icons/src/svg/32', branch: 'main' },
-      ionicons: { repo: 'ionic-team/ionicons', path: 'src/svg', branch: 'main' },
-      feather_icons: { repo: 'feathericons/feather', path: 'icons', branch: 'main' }
+      fontawesome_regular: { repo: "FortAwesome/Font-Awesome", path: "svgs/regular", branch: "6.x" },
+      fontawesome_solid: { repo: "FortAwesome/Font-Awesome", path: "svgs/solid", branch: "6.x" },
+      fontawesome_brands: { repo: "FortAwesome/Font-Awesome", path: "svgs/brands", branch: "6.x" },
+      heroicons_outline: { repo: "tailwindlabs/heroicons", path: "optimized/24/outline", branch: "master" },
+      heroicons_solid: { repo: "tailwindlabs/heroicons", path: "optimized/24/solid", branch: "master" },
+      tabler_icons_filled: { repo: "tabler/tabler-icons", path: "icons/filled", branch: "main" },
+      tabler_icons_outline: { repo: "tabler/tabler-icons", path: "icons/outline", branch: "main" },
+      mage_icons_fill: { repo: "Mage-Icons/mage-icons", path: "svg/bulk", branch: "main" },
+      mage_icons_stroke: { repo: "Mage-Icons/mage-icons", path: "svg/stroke", branch: "main" },
+      mage_icons_social_bw: { repo: "Mage-Icons/mage-icons", path: "svg/social-bw", branch: "main" },
+      mage_icons_social_color: { repo: "Mage-Icons/mage-icons", path: "svg/social-color", branch: "main" },
+      line_awesome: { repo: "icons8/line-awesome", path: "svg", branch: "master" },
+      carbon: { repo: "carbon-design-system/carbon", path: "packages/icons/src/svg/32", branch: "main" },
+      ionicons: { repo: "ionic-team/ionicons", path: "src/svg", branch: "main" },
+      feather_icons: { repo: "feathericons/feather", path: "icons", branch: "main" }
     }.freeze
 
     # @return [Hash] the configured icon collections
     attr_accessor :collections
 
+    # @return [String, nil] optional GitHub personal access token for API requests
+    attr_accessor :github_token
+
     # Initializes a new Configuration instance with default settings.
     def initialize
       @collections = DEFAULT_COLLECTIONS.dup
+      @github_token = nil
     end
 
     def add_collections(new_collections)

data/lib/anyicon/icon.rb

@@ -1,8 +1,8 @@
 # frozen_string_literal: true
 
-require 'net/http'
-require 'nokogiri'
-require 'fileutils'
+require "net/http"
+require "nokogiri"
+require "fileutils"
 
 module Anyicon
   # The Icon class is responsible for managing the rendering of icons from various
@@ -21,22 +21,29 @@ module Anyicon
     #
     # @param icon [String] a comma-separated string of icon names, each in the format 'collection:name'
     # @param props [Hash] additional properties to apply to the SVG element
-    def initialize(icon:, **props)
+    ALLOWED_ATTRIBUTES = %w[
+      class id style width height viewBox fill stroke
+      stroke-width opacity transform title aria-label aria-hidden role
+    ].freeze
+
+    DATA_ATTRIBUTE_PATTERN = /\Adata-[\w-]+\z/
+
+    def initialize(icon = nil, **props)
       super()
-      @icons = icon.to_s.split(',').map { |i| i.split(':') }
-      @props = props
+      @icons = (icon || props[:icon]).to_s.split(",").map { |i| i.split(":") }
+      @icons.reject! { |i| i.length < 2 }
+      @props = props.select { |key, _| allowed_attribute?(key) }
     end
 
     # Renders the SVG content for the specified icons.
     #
     # @return [String] the HTML-safe SVG content
     def render
-      result = ''.html_safe
-      @icons.each do |icon|
+      parts = @icons.map do |icon|
         ensure_icon_exists(icon)
-        result.concat(svg_content(icon).html_safe)
+        svg_content(icon)
       end
-      result
+      ActiveSupport::SafeBuffer.new(parts.join)
     end
 
     private
@@ -48,6 +55,23 @@ module Anyicon
       @collections ||= Anyicon.configuration.collections
     end
 
+    # Checks if an attribute key is allowed on the SVG element.
+    #
+    # @param key [Symbol, String] the attribute key
+    # @return [Boolean]
+    def allowed_attribute?(key)
+      name = key.to_s
+      ALLOWED_ATTRIBUTES.include?(name) || name.match?(DATA_ATTRIBUTE_PATTERN)
+    end
+
+    # Sanitizes an icon name component to prevent path traversal.
+    #
+    # @param name [String] the raw icon name component
+    # @return [String] the sanitized name
+    def sanitize_name(name)
+      File.basename(name.to_s.gsub(/[^a-zA-Z0-9_\-]/, ""))
+    end
+
     # Ensures the specified icon exists by downloading it if necessary.
     #
     # @param icon [Array] the collection and name of the icon
@@ -76,7 +100,7 @@ module Anyicon
     # @param icon [Array] the collection and name of the icon
     # @return [Pathname] the path to the icon file
     def icon_path(icon)
-      ::Rails.root.join('app', 'assets', 'images', 'icons', icon[0], "#{icon[1]}.svg")
+      ::Rails.root.join("app", "assets", "images", "icons", sanitize_name(icon[0]), "#{sanitize_name(icon[1])}.svg")
     end
 
     # Constructs the URL to download the specified icon.
@@ -84,10 +108,22 @@ module Anyicon
     # @param icon [Array] the collection and name of the icon
     # @return [String, nil] the URL to download the icon, or nil if the collection is not configured
     def icon_url(icon)
-      return nil unless collections.keys.include?(icon[0].to_sym)
+      collection_key = sanitize_name(icon[0]).to_sym
+      return nil unless collections.key?(collection_key)
+
+      [ "https://github.com/", collections[collection_key][:repo], "/raw/", collections[collection_key][:branch], "/",
+       collections[collection_key][:path], "/", sanitize_name(icon[1]), ".svg" ].join("")
+    end
 
-      ['https://github.com/', collections[icon[0].to_sym][:repo], '/raw/', collections[icon[0].to_sym][:branch], '/',
-       collections[icon[0].to_sym][:path], '/', icon[1], '.svg'].join('')
+    # Returns the cached raw SVG content for the specified icon.
+    #
+    # @param icon [Array] the collection and name of the icon
+    # @return [String, nil] the raw SVG file content, or nil if file doesn't exist
+    def cached_svg(icon)
+      path = icon_path(icon)
+      return nil unless File.file?(path)
+
+      self.class.svg_cache[path.to_s] ||= File.read(path)
     end
 
     # Reads and customizes the SVG content for the specified icon.
@@ -95,11 +131,11 @@ module Anyicon
     # @param icon [Array] the collection and name of the icon
     # @return [String] the customized SVG content
     def svg_content(icon)
-      return '' unless File.file?(icon_path(icon))
+      raw = cached_svg(icon)
+      return "" unless raw
 
-      svg_content = File.read(icon_path(icon))
-      doc = Nokogiri::HTML::DocumentFragment.parse(svg_content)
-      svg = doc.at_css 'svg'
+      doc = Nokogiri::HTML::DocumentFragment.parse(raw)
+      svg = doc.at_css "svg"
 
       @props.each do |key, value|
         value = "#{value} #{icon[-2..].join(' ')}" if key == :class && icon.count > 2
@@ -115,8 +151,21 @@ module Anyicon
       #
       # @param kwargs [Hash] the parameters for initializing an Icon instance
       # @return [String] the HTML-safe SVG content
-      def render(**kwargs)
-        new(**kwargs).render
+      def render(*args, **kwargs)
+        new(*args, **kwargs).render
+      end
+
+      # In-memory cache for raw SVG file contents, keyed by file path.
+      # Avoids repeated File.read + disk I/O for the same icon.
+      #
+      # @return [Hash] the SVG cache
+      def svg_cache
+        @svg_cache ||= {}
+      end
+
+      # Clears the in-memory SVG cache.
+      def clear_cache!
+        @svg_cache = {}
       end
     end
   end

data/lib/anyicon/version.rb

@@ -1,3 +1,3 @@
 module Anyicon
-  VERSION = "1.0.3"
+  VERSION = "1.1.1"
 end

data/lib/anyicon.rb

@@ -1,8 +1,8 @@
 # frozen_string_literal: true
 
-require 'rails'
-require 'anyicon/engine'
-require 'anyicon/common'
-require 'anyicon/collections'
-require 'anyicon/icon'
-require 'anyicon/configuration'
+require "rails"
+require "anyicon/engine"
+require "anyicon/common"
+require "anyicon/collections"
+require "anyicon/icon"
+require "anyicon/configuration"

data/lib/generators/anyicon/install/install_generator.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-require 'rails/generators'
+require "rails/generators"
 
 module Anyicon
   module Generators
@@ -17,14 +17,14 @@ module Anyicon
     # This will copy the `anyicon.rb` template to `config/initializers/anyicon.rb` in your
     # Rails application.
     class InstallGenerator < ::Rails::Generators::Base
-      source_root File.join(__dir__, 'templates')
-      desc 'This generator installs AnyIcon'
+      source_root File.join(__dir__, "templates")
+      desc "This generator installs AnyIcon"
 
       # Copies the anyicon configuration template to the initializers directory.
       #
       # @return [void]
       def copy_config
-        template 'anyicon.rb', 'config/initializers/anyicon.rb'
+        template "anyicon.rb", "config/initializers/anyicon.rb"
       end
     end
   end

data/lib/generators/anyicon/install/templates/anyicon.rb

@@ -15,4 +15,11 @@ Anyicon.configure do |config|
   #   }
   # )
   #
+
+  ##
+  # Optional: Set a GitHub personal access token to avoid API rate limits
+  # (60 requests/hour unauthenticated vs 5,000/hour authenticated).
+  #
+  # config.github_token = ENV["GITHUB_TOKEN"]
+  #
 end

data/lib/tasks/anyicon.rake

@@ -1,8 +1,8 @@
 # frozen_string_literal: true
 
 namespace :anyicon do
-  desc 'Download a specific icon collection'
-  task :download_collection, [:collection] => :environment do |_t, args|
+  desc "Download a specific icon collection"
+  task :download_collection, [ :collection ] => :environment do |_t, args|
     collection = args[:collection]
     if Anyicon.configuration.collections.keys.include?(collection.to_sym)
       Anyicon::Collection.new(collection.to_sym).download_all
@@ -11,9 +11,9 @@ namespace :anyicon do
     end
   end
 
-  desc 'Download all icon collections'
+  desc "Download all icon collections"
   task download_all_collections: :environment do
-    puts 'Downloading all icon collections'
+    puts "Downloading all icon collections"
     Anyicon.configuration.collections.each_key do |collection|
       puts "Downloading #{collection}..."
       Anyicon::Collection.new(collection).download_all

metadata

@@ -1,14 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: anyicon
 version: !ruby/object:Gem::Version
-  version: 1.0.3
+  version: 1.1.1
 platform: ruby
 authors:
 - Arthur Molina
-autorequire:
 bindir: bin
 cert_chain: []
-date: 2025-07-03 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -24,6 +23,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '5.2'
+- !ruby/object:Gem::Dependency
+  name: nokogiri
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: appraisal
   requirement: !ruby/object:Gem::Requirement
@@ -139,7 +152,6 @@ metadata:
   source_code_uri: https://github.com/arthurmolina/anyicon
   bug_tracker_uri: https://github.com/arthurmolina/anyicon/issues
   wiki_uri: https://github.com/arthurmolina/anyicon/wiki
-post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -154,8 +166,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.16
-signing_key:
+rubygems_version: 3.6.9
 specification_version: 4
 summary: Rails View Helpers for any icon collections.
 test_files: []