icons 0.9.0 → 0.11.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: eddb62f576eb4a0f7914cd2fba762e6306bed0fefd719671c9f631a3d4b84644
-  data.tar.gz: a108e7b8f54aada59206d3c2a125d4b75c6e05386ac84ca760f13a801d2dbb8d
+  metadata.gz: b3020899914efdd03ecf2a92102d477b2f8852aa3688ea09039aaf6d220c0e67
+  data.tar.gz: ab8d18495924688b6797bf9c8cc17fb11b0ed2789915dc93cf39fdaf15ae76fd
 SHA512:
-  metadata.gz: 2f6d4f4a1e29efc77f46622ab78b4aa041d7a5116d3c4ec945a610d66f60f8f8cd66266f0cbfcb0b9ccff6d7f4c515c726d69ece0af5bc41c729da31054d4f66
-  data.tar.gz: 22dcc6888aa46bf59476e9d511df57d04ff4ff7e5c32230372164f06c8ccd6654e3875a28d2a986874eae162330d1dd581e24e051d861511b7fb4126c3a9e038
+  metadata.gz: 1bac607ff06f7a74a61ad368de35962f29b159d57be17d1181f2a38471fc5c0a6563955015f25690267e41d88acec1344192409d41df0d984617a07c9ac57297
+  data.tar.gz: 956af529c206586d7d30d9558e5c36545f2805c5d9a6187eef508e9efa6282ebcd10bca1f1b856186a2a55fd293bd7f6edb5b4ae48c68977dd5951a2693c95c0

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    icons (0.9.0)
+    icons (0.11.0)
       nokogiri (~> 1.16, >= 1.16.4)
 
 GEM
@@ -119,7 +119,7 @@ CHECKSUMS
   date (3.5.1) sha256=750d06384d7b9c15d562c76291407d89e368dda4d4fff957eb94962d325a0dc0
   debug (1.11.1) sha256=2e0b0ac6119f2207a6f8ac7d4a73ca8eb4e440f64da0a3136c30343146e952b6
   erb (6.0.1) sha256=28ecdd99c5472aebd5674d6061e3c6b0a45c049578b071e5a52c2a7f13c197e5
-  icons (0.9.0)
+  icons (0.11.0)
   io-console (0.8.2) sha256=d6e3ae7a7cc7574f4b8893b4fca2162e57a825b223a177b7afa236c5ef9814cc
   irb (1.16.0) sha256=2abe56c9ac947cdcb2f150572904ba798c1e93c890c256f8429981a7675b0806
   json (2.18.0) sha256=b10506aee4183f5cf49e0efc48073d7b75843ce3782c68dbeb763351c08fd505

data/README.md

@@ -5,7 +5,7 @@ Add any icon library to a Ruby app. Icons has first-party support for a [dozen o
 
 ## Installation
 
-Add the core gem to your Gemfile:
+Add the core gem to the Gemfile:
 ```ruby
 gem "icons"
 ```
@@ -55,6 +55,60 @@ sprite.svg
 The resulting SVG will include the proper attributes and the SVG content from the library’s asset path.
 
 
+## Custom libraries
+
+Add non first-party icon libraries. The Icons gem looks for SVGs at `<icons_path>/<library_name>/<name>.svg`, so any name works without configuration.
+
+
+### Zero config
+
+Place SVGs at the expected path:
+```bash
+app/assets/svg/icons/my_icons/check.svg
+```
+
+Usage:
+```ruby
+Icons::Icon.new(name: "check", library: "my_icons", arguments: {}).svg
+```
+
+
+### Registered custom libraries
+
+Use `config.custom_library` to declare a custom library with defaults:
+```ruby
+Icons.configure do |config|
+  config.custom_library :my_icons
+end
+```
+
+Then set library specific defaults:
+```ruby
+Icons.configure do |config|
+  config.custom_library :my_icons
+
+  config.libraries.my_icons.default.css = "size-6"
+  config.libraries.my_icons.default.stroke_width = 1.5
+end
+```
+
+### Custom libraries with a git source
+
+Pass a `source:` option to make a custom library syncable from a Git repository:
+```ruby
+Icons.configure do |config|
+  config.custom_library :my_icons, source: {
+    url: "https://github.com/user/icons.git",
+    variants: { default: "." }
+  }
+end
+
+Icons::Sync.new(:my_icons).now
+```
+
+After syncing, `Icons::Icon.new(name: "check", library: "my_icons", arguments: {}).svg` , works just like any first party library.
+
+
 ## First-party libraries
 
 - [Boxicons](https://railsdesigner.com/open-source/rails-icons/boxicons/) (1600+ icons)

data/icons.gemspec

@@ -18,5 +18,7 @@ Gem::Specification.new do |spec|
 
   spec.files = Dir["{bin,config,lib}/**/*", "Rakefile", "README.md", "icons.gemspec", "Gemfile", "Gemfile.lock"]
 
+  spec.required_ruby_version = ">= 3.1.0"
+
   spec.add_runtime_dependency "nokogiri", "~> 1.16", ">= 1.16.4"
 end

data/lib/icons/configuration/boxicons.rb

@@ -23,6 +23,7 @@ module Icons
           # Override Boxicons defaults
           # config.libraries.boxicons.default_variant = "" # Set a default variant for Boxicons
           # config.libraries.boxicons.exclude_variants = [] # Exclude specific variants
+          # config.libraries.boxicons.variants = [] # Only sync these variants
 
           # config.libraries.boxicons.solid.css = "size-6"
           # config.libraries.boxicons.solid.data = {}

data/lib/icons/configuration/custom_library.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module Icons
+  class Configuration
+    class CustomLibrary
+      attr_reader :source
+
+      def initialize(source: nil)
+        @source = source
+      end
+
+      def config
+        Options.new.tap do |options|
+          options.default_variant = nil
+          options.exclude_variants = []
+        end
+      end
+
+      def initializer_config
+        ""
+      end
+    end
+  end
+end

data/lib/icons/configuration/feather.rb

@@ -21,6 +21,7 @@ module Icons
           # Override Feather defaults
           # config.libraries.feather.default_variant = "" # Feather has no variants, this is provided for backwards compatibility
           # config.libraries.feather.exclude_variants = [] # Feather has no variants, this is provided for backwards compatibility
+          # config.libraries.feather.variants = [] # Feather has no variants, provided for consistency
 
           # config.libraries.feather.default.css = "size-6"
           # config.libraries.feather.default.stroke_width = "2"

data/lib/icons/configuration/flags.rb

@@ -22,6 +22,7 @@ module Icons
           # Override Flags defaults
           # config.libraries.flags.default_variant = "" # Set a default variant for Flags
           # config.libraries.flags.exclude_variants = [:square, :landscape]
+          # config.libraries.flags.variants = [] # Only sync these variants
 
           # config.libraries.flags.square.default.css = "size-6"
           # config.libraries.flags.square.default.data = {}

data/lib/icons/configuration/heroicons.rb

@@ -24,6 +24,7 @@ module Icons
           # Override Heroicon defaults
           # config.libraries.heroicons.default_variant = "" # Set a default variant for Heroicons
           # config.libraries.heroicons.exclude_variants = [:mini, :micro] # Exclude specific variants
+          # config.libraries.heroicons.variants = [] # Only sync these variants
 
           # config.libraries.heroicons.outline.default.css = "size-6"
           # config.libraries.heroicons.outline.default.stroke_width = "1.5"

data/lib/icons/configuration/hugeicons.rb

@@ -21,6 +21,7 @@ module Icons
           # Override Hugeicons defaults
           # config.libraries.hugeicons.default_variant = "" # Hugeicons has no variants, this is provided for backwards compatibility
           # config.libraries.hugeicons.exclude_variants = [] # Hugeicons has no variants, this is provided for backwards compatibility
+          # config.libraries.hugeicons.variants = [] # Hugeicons has no variants, provided for consistency
 
           # config.libraries.hugeicons.default.css = "size-6"
           # config.libraries.hugeicons.default.stroke_width = "1.5"

data/lib/icons/configuration/linear.rb

@@ -21,6 +21,7 @@ module Icons
           # Override Linear defaults
           # config.libraries.linear.default_variant = "" # Set a default variant for Linear
           # config.libraries.linear.exclude_variants = []
+          # config.libraries.linear.variants = [] # Linear has no variants, provided for consistency
 
           # config.libraries.linear.default.css = "size-6"
           # config.libraries.linear.default.stroke_width = "2"

data/lib/icons/configuration/lucide.rb

@@ -21,6 +21,7 @@ module Icons
           # Override Lucide defaults
           # config.libraries.lucide.default_variant = "" # Set a default variant for Lucide
           # config.libraries.lucide.exclude_variants = [] # Exclude specific variants
+          # config.libraries.lucide.variants = [] # Only sync these variants
 
           # config.libraries.lucide.outline.default.css = "size-6"
           # config.libraries.lucide.outline.default.stroke_width = "1.5"

data/lib/icons/configuration/phosphor.rb

@@ -26,6 +26,7 @@ module Icons
           # Override Phosphor defaults
           # config.libraries.phosphor.default_variant = "" # Set a default variant for Phosphor
           # config.libraries.phosphor.exclude_variants = [:duotone, :thin] # Exclude specific variants
+          # config.libraries.phosphor.variants = [] # Only sync these variants
 
           # config.libraries.phosphor.bold.default.css = "size-6"
           # config.libraries.phosphor.bold.default.data = {}

data/lib/icons/configuration/radix.rb

@@ -21,6 +21,8 @@ module Icons
           # Override Radix defaults
           # config.libraries.radix.default_variant = "" # Radix has no variants, this is provided for backwards compatibility
           # config.libraries.radix.exclude_variants = [] # Radix has no variants, this is provided for backwards compatibility
+          # config.libraries.radix.variants = [] # Radix has no variants, provided for consistency
+
           # config.libraries.radix.default.css = "size-6"
           # config.libraries.radix.default.stroke_width = "2"
           # config.libraries.radix.default.data = {}

data/lib/icons/configuration/sidekickicons.rb

@@ -24,6 +24,7 @@ module Icons
           # Override Sidekickicons defaults
           # config.libraries.sidekickicons.default_variant = "" # Set a default variant for Sidekickicons
           # config.libraries.sidekickicons.exclude_variants = [:mini, :micro] # Exclude specific variants
+          # config.libraries.sidekickicons.variants = [] # Only sync these variants
 
           # config.libraries.sidekickicons.outline.default.css = "size-6"
           # config.libraries.sidekickicons.outline.default.stroke_width = "1.5"

data/lib/icons/configuration/tabler.rb

@@ -22,6 +22,7 @@ module Icons
           # Override Tabler defaults
           # config.libraries.tabler.default_variant = "" # Set a default variant for Tabler
           # config.libraries.tabler.exclude_variants = [] # Exclude specific variants
+          # config.libraries.tabler.variants = [] # Only sync these variants
 
           # config.libraries.tabler.regular.default.css = "size-6"
           # config.libraries.tabler.solid.default.css = "size-6"

data/lib/icons/configuration/weather.rb

@@ -21,6 +21,7 @@ module Icons
           # Override Weather defaults
           # config.libraries.weather.default_variant = "" # Set a default variant for Wweather
           # config.libraries.weather.exclude_variants = []
+          # config.libraries.weather.variants = [] # Only sync these variants
 
           # config.libraries.weather.default.css = "size-6"
           # config.libraries.weather.default.data = {}

data/lib/icons/configuration.rb

@@ -47,6 +47,32 @@ module Icons
       @base_path = value.is_a?(Pathname) ? value : Pathname.new(value)
     end
 
+    # Register a custom library at configuration time.
+    #
+    # @param name [Symbol] The library name used in `icon "name", library: :your_name`
+    # @param source [Hash, nil] Optional git source hash with `:url` and `:variants`.
+    #        When provided, the library becomes syncable via `Icons::Sync.new(:your_name).now`.
+    #
+    # @example Add a local custom library
+    #   Icons.configure do |config|
+    #     config.custom_library :my_icons
+    #   end
+    #
+    # @example Add a custom library with a git source
+    #   Icons.configure do |config|
+    #     config.custom_library :my_icons, source: { url: "https://github.com/user/icons.git", variants: { default: "." } }
+    #   end
+    #
+    def custom_library(name, source: nil)
+      name = name.to_sym
+
+      library_config = CustomLibrary.new(source: source)
+
+      Icons.register_library(name, library_config)
+
+      @libraries[name] = library_config.config
+    end
+
     private
 
     def set_default_config

data/lib/icons/errors.rb

@@ -4,7 +4,7 @@ module Icons
   class IconNotFound < StandardError
     def initialize(icon_name = nil)
       if icon_name
-        super("The icon `#{icon_name}` is not available. Please check the icon name and try again.")
+        super("The icon `#{icon_name}` is not available. Check the icon name and try again.")
       else
         super("Icon not found")
       end
@@ -12,12 +12,12 @@ module Icons
   end
 
   class LibraryNotFound < StandardError
-    def initialize(library_name)
-      if library_name.empty?
-        libraries = Icons.libraries.keys.join(", ")
-        super("No libraries were specified. Please choose from: #{libraries}")
+    def initialize(library_name = nil)
+      if library_name
+        super("The library `#{library_name}` is not available. Check the library name and try again.")
       else
-        super("The library `#{library_name}` is not available. Please check the library name and try again.")
+        libraries = Icons.libraries.keys.join(", ")
+        super("No libraries were specified. Choose from: #{libraries}")
       end
     end
   end

data/lib/icons/icon/file_path.rb

@@ -12,6 +12,8 @@ module Icons
       end
 
       def call
+        validate_components!
+
         if animated_library?
           path = animated_icons_path
           raise Icons::IconNotFound if path.nil?
@@ -25,6 +27,18 @@ module Icons
 
       private
 
+      ALLOWED_CHARACTERS = /\A[a-zA-Z0-9_-]+\z/
+
+      def validate_components!
+        raise Icons::IconNotFound, @name unless safe?(@name.to_s)
+        raise Icons::IconNotFound, @name unless safe?(@library.to_s)
+        raise Icons::IconNotFound, @name unless @variant.nil? || @variant == :"." || safe?(@variant.to_s)
+      end
+
+      def safe?(component)
+        component.match?(ALLOWED_CHARACTERS)
+      end
+
       def animated_library?
         @library == :animated
       end

data/lib/icons/icon.rb

@@ -30,11 +30,13 @@ class Icons::Icon
   # @raise [Icons::IconNotFound] If the icon file does not exist
   #
   def svg
-    Nokogiri::HTML::DocumentFragment.parse(File.read(file_path))
-      .at_css("svg")
-      .tap { |svg| attach_attributes(to: svg) }
-      .to_html
-  rescue Errno::ENOENT
+    svg = Nokogiri::HTML::DocumentFragment.parse(File.read(file_path)).at_css("svg")
+    raise Icons::IconNotFound, error_message unless svg
+
+    attach_attributes(to: svg)
+
+    svg.to_html
+  rescue Errno::ENOENT, Errno::EACCES, Errno::EISDIR
     raise Icons::IconNotFound, error_message
   end
 

data/lib/icons/libraries.rb

@@ -15,22 +15,40 @@ require "icons/configuration/weather"
 module Icons
   extend self
 
+  BUILT_IN_LIBRARIES = {
+    boxicons: Icons::Configuration::Boxicons,
+    feather: Icons::Configuration::Feather,
+    flags: Icons::Configuration::Flags,
+    heroicons: Icons::Configuration::Heroicons,
+    hugeicons: Icons::Configuration::Hugeicons,
+    linear: Icons::Configuration::Linear,
+    lucide: Icons::Configuration::Lucide,
+    phosphor: Icons::Configuration::Phosphor,
+    radix: Icons::Configuration::Radix,
+    sidekickicons: Icons::Configuration::Sidekickicons,
+    tabler: Icons::Configuration::Tabler,
+    weather: Icons::Configuration::Weather
+  }.freeze
+
   # @return [Hash{Symbol => Class}] A map of library names to their configuration classes
   #
   def libraries
-    {
-      boxicons: Icons::Configuration::Boxicons,
-      feather: Icons::Configuration::Feather,
-      flags: Icons::Configuration::Flags,
-      heroicons: Icons::Configuration::Heroicons,
-      hugeicons: Icons::Configuration::Hugeicons,
-      linear: Icons::Configuration::Linear,
-      lucide: Icons::Configuration::Lucide,
-      phosphor: Icons::Configuration::Phosphor,
-      radix: Icons::Configuration::Radix,
-      sidekickicons: Icons::Configuration::Sidekickicons,
-      tabler: Icons::Configuration::Tabler,
-      weather: Icons::Configuration::Weather
-    }
+    BUILT_IN_LIBRARIES.merge(@registered_libraries || {})
+  end
+
+  # Register a custom library for use with the icons gem.
+  #
+  # @param name [Symbol] The library name
+  # @param library_module [Module, Object] A configuration module or object
+  #        that responds to `.config` and optionally `.source` and `.custom_path`
+  #
+  def register_library(name, library_module)
+    @registered_libraries ||= {}
+
+    @registered_libraries[name.to_sym] = library_module
+  end
+
+  def reset_registered_libraries
+    @registered_libraries = {}
   end
 end

data/lib/icons/sync/process_variants.rb

@@ -6,17 +6,19 @@ require "icons/sync/transformations"
 module Icons
   class Sync
     class ProcessVariants
-      def initialize(temp_directory, name, library)
-        @temp_directory, @name, @library = temp_directory, name, library
+      def initialize(temp_directory, name, library, variants: nil)
+        @temp_directory = temp_directory
+        @name = name
+        @library = library
+        @variants = variants
       end
 
       def process
         original_variants = Dir.children(@temp_directory)
         excluded_variants = Icons.configuration.libraries.dig(@name.to_sym)&.exclude_variants || []
+        effective_variants = (@variants || @library[:variants].keys) - excluded_variants
 
-        @library[:variants].each do |variant_name, variant_source_path|
-          next if excluded_variants.include?(variant_name)
-
+        @library[:variants].slice(*effective_variants).each do |variant_name, variant_source_path|
           source = File.join(@temp_directory, variant_source_path)
           destination = File.join(@temp_directory, variant_name.to_s)
 
@@ -25,12 +27,11 @@ module Icons
           raise "[Icons] Failed to find the icons directory: '#{source}'" unless Dir.exist?(source)
 
           move_icons(source, destination)
-
           apply_transformations_to(destination)
         end
 
         remove_files_and_folders_for(original_variants)
-        remove_previously_downloaded(excluded_variants)
+        remove_previously_downloaded(@library[:variants].keys - effective_variants)
 
         puts "[Icons] Icon variants processed successfully"
       end

data/lib/icons/sync.rb

@@ -5,12 +5,13 @@ require "icons/sync/process_variants"
 
 module Icons
   class Sync
-    def initialize(name)
+    def initialize(name, variants: nil)
       raise "[Icons] Not a valid library" unless Icons.libraries.key?(name.to_sym)
 
       @name = name
       @library = Icons.libraries.fetch(name.to_sym).source
-      @temp_directory = File.join(temp_directory_root, name)
+      @variants = variants
+      @temp_directory = File.join(temp_directory_root, name.to_s)
     end
 
     def now
@@ -52,11 +53,14 @@ module Icons
     end
 
     def sparse_checkout_paths
-      @library[:variants].values.map { |path| "'#{path}'" }.join(" ")
+      paths = @library[:variants]
+      paths = paths.slice(*@variants) if @variants
+
+      paths.values.map { |path| "'#{path}'" }.join(" ")
     end
 
     def process_variants
-      Sync::ProcessVariants.new(@temp_directory, @name, @library).process
+      Sync::ProcessVariants.new(@temp_directory, @name, @library, variants: @variants).process
     end
 
     def remove_non_svg_files

data/lib/icons/version.rb

@@ -1,3 +1,3 @@
 module Icons
-  VERSION = "0.9.0"
+  VERSION = "0.11.0"
 end

data/lib/icons.rb

@@ -4,6 +4,7 @@ require "icons/version"
 require "icons/errors"
 require "icons/libraries"
 require "icons/configuration"
+require "icons/configuration/custom_library"
 require "icons/icon"
 require "icons/sprite/reference"
 require "icons/sprite"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: icons
 version: !ruby/object:Gem::Version
-  version: 0.9.0
+  version: 0.11.0
 platform: ruby
 authors:
 - Rails Designer
@@ -52,6 +52,7 @@ files:
 - lib/icons/configuration.rb
 - lib/icons/configuration/animated.rb
 - lib/icons/configuration/boxicons.rb
+- lib/icons/configuration/custom_library.rb
 - lib/icons/configuration/feather.rb
 - lib/icons/configuration/flags.rb
 - lib/icons/configuration/heroicons.rb
@@ -90,14 +91,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '0'
+      version: 3.1.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.14
+rubygems_version: 4.0.22
 specification_version: 4
 summary: Add any icon library to a Ruby app
 test_files: []