icons 0.8.1 → 0.10.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 258de5224f1792f19bc6024149d3b83796c215fb2dafcdb4ad832817396fa497
-  data.tar.gz: 735659b38f49f975bfd758c7260e7ea5ac56971a9cd3942293b8f0ae2c240f3d
+  metadata.gz: 6a560ee22eaef4722cc54a4810c2471fa9ee24aa015e609e80ba0c876a207b23
+  data.tar.gz: f03071f72a369fc8eff35b9fca520ba6108576d361537b97406204b2bec58b42
 SHA512:
-  metadata.gz: 62fa8a1399597b1e99e524f16db444af2680a42e23b5b86d938ed9855fa0859e134f2810aed56d51e398e79f366c71a9106bd12de70e0f62a26ccdbe449e1e32
-  data.tar.gz: 233185f2705e719ec0230091aec8b2390a70e7ea74bdbe09376942388fa6db1dbf5ab6f5757afbf5fab89f5f83b0c7ce90c2a72ea732a9dfc52ac5e96db1f6cc
+  metadata.gz: 1d71a79a568b7a19e1eadb13f846fb571357aa3542026c80683ad623bbeeb6af1c779c8f0634bcdebe445e26d10b8639b5ea8571a15fb1c682b3089f4c3362d3
+  data.tar.gz: 1ffb7d8ef4233e67b9011028efe012459d3bd2562a1e08a753152523ce850a684165aedf48699433c85cdca2a0481d379d4b9215900dcc5ae85d3fe24b6d69c0

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    icons (0.8.1)
+    icons (0.10.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.8.1)
+  icons (0.10.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"
 ```
@@ -34,11 +34,81 @@ Icons::Sync.new("lucide").now
 # Render an icon
 icon = Icons::Icon.new(name: "check", library: "lucide", variant: "outline", arguments: { class: "text-gray-500" })
 svg = icon.svg
+
+# Generate SVG sprite for performance
+sprite = Icons::Sprite.new(icons: ["check", "search"], library: "lucide", variant: "outline")
+svg = sprite.svg
+# => <svg xmlns="http://www.w3.org/2000/svg" style="display: none;">
+#      <symbol id="lucide_outline_check" viewBox="0 0 24 24">...</symbol>
+#      <symbol id="lucide_outline_search" viewBox="0 0 24 24">...</symbol>
+#    </svg>
+
+# Or configure globally
+Icons.configure do |config|
+  config.sprite = { lucide: { outline: ["check", "search"] } }
+end
+
+sprite = Icons::Sprite.new
+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 = {}
@@ -50,7 +51,11 @@ module Icons
         {
           filenames: {
             delete_prefix: ["bxl-", "bx-", "bxs-"]
-          }
+          },
+
+          svg: [
+            {element: "path", action: :set_attribute, attribute: "fill", value: "currentColor"}
+          ]
         }
       end
 

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

@@ -5,7 +5,10 @@ require "icons/configuration/options"
 
 module Icons
   class Configuration
-    attr_accessor :default_library, :icons_path, :default_variant
+    # @return [String, nil]
+    attr_accessor :default_library, :icons_path, :default_variant, :sprite, :default_sprite_location, :validate_sprite_icons
+
+    # @return [Options]
     attr_reader :libraries
 
     def initialize
@@ -15,32 +18,70 @@ module Icons
       set_libraries_config
     end
 
+    # @deprecated Use {#icons_path} instead
+    # @return [String]
+    #
     def destination_path
       warn "[DEPRECATION] `destination_path` is deprecated. Use `icons_path` instead."
 
       @icons_path
     end
 
+    # @deprecated Use {#icons_path=} instead
+    #
     def destination_path=(value)
       warn "[DEPRECATION] `destination_path=` is deprecated. Use `icons_path=` instead."
 
       @icons_path = value
     end
 
+    # @return [Pathname]
+    #
     def base_path
       @base_path ||= Pathname.new(Dir.pwd)
     end
 
+    # @param value [Pathname, String]
+    #
     def base_path=(value)
       @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
       @default_library = nil
       @default_variant = nil
       @icons_path = "app/assets/svg/icons"
+      @sprite = {}
+      @default_sprite_location = nil
+      @validate_sprite_icons = false
     end
 
     def set_libraries_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/configurable.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module Icons
+  class Icon
+    module Configurable
+      private
+
+      def set_variant
+        value = @config.libraries.dig(@library, :default_variant) || @config.default_variant
+
+        value.to_s.empty? ? nil : value
+      end
+
+      def error_message
+        attributes = [
+          @library,
+          @variant,
+          @name
+        ].compact
+
+        "Icon not found: `#{attributes.join(" / ")}`"
+      end
+
+      def attach_attributes(to:)
+        Icons::Icon::Attributes
+          .new(default_attributes: default_attributes, arguments: @arguments)
+          .attach(to: to)
+      end
+
+      def default_attributes
+        {
+          "stroke-width": default(:stroke_width),
+          data: default(:data),
+          class: default(:css)
+        }.compact
+      end
+
+      def default(key)
+        library_attributes.dig(:default, key)
+      end
+
+      def library_attributes
+        keys = [@library, @variant].compact
+
+        @config.libraries.dig(*keys) || {}
+      end
+    end
+  end
+end

data/lib/icons/icon.rb

@@ -4,8 +4,16 @@ require "nokogiri"
 
 require "icons/icon/file_path"
 require "icons/icon/attributes"
+require "icons/icon/configurable"
 
 class Icons::Icon
+  include Icons::Icon::Configurable
+
+  # @param name [String] The icon name
+  # @param library [String, Symbol] The icon library
+  # @param variant [String, Symbol, nil] The icon variant (optional)
+  # @param arguments [Hash] Additional attributes including class, data, stroke_width, etc.
+  #
   def initialize(name:, library:, arguments:, variant: nil)
     @config = Icons.configuration
 
@@ -15,6 +23,12 @@ class Icons::Icon
     @arguments = arguments
   end
 
+  # Returns the rendered SVG markup for the icon
+  #
+  # @return [String] The SVG markup as an HTML string
+  #
+  # @raise [Icons::IconNotFound] If the icon file does not exist
+  #
   def svg
     Nokogiri::HTML::DocumentFragment.parse(File.read(file_path))
       .at_css("svg")
@@ -26,48 +40,7 @@ class Icons::Icon
 
   private
 
-  def set_variant
-    value = @config.libraries.dig(@library, :default_variant) ||
-      @config.default_variant
-
-    value.to_s.empty? ? nil : value
-  end
-
-  def error_message
-    attributes = [
-      @library,
-      @variant,
-      @name
-    ].compact
-
-    "Icon not found: `#{attributes.join(" / ")}`"
-  end
-
   def file_path
     Icons::Icon::FilePath.new(name: @name, library: @library, variant: @variant).call
   end
-
-  def attach_attributes(to:)
-    Icons::Icon::Attributes
-      .new(default_attributes: default_attributes, arguments: @arguments)
-      .attach(to: to)
-  end
-
-  def default_attributes
-    {
-      "stroke-width": default(:stroke_width),
-      data: default(:data),
-      class: default(:css)
-    }
-  end
-
-  def default(key)
-    library_attributes.dig(:default, key)
-  end
-
-  def library_attributes
-    keys = [@library, @variant].compact
-
-    @config.libraries.dig(*keys) || {}
-  end
 end

data/lib/icons/libraries.rb

@@ -15,20 +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/sprite/reference.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Icons
+  class Sprite
+    Reference = Data.define(:name, :library, :variant) do
+      def id = [library, variant, name].join("_")
+
+      def file_path
+        Icons::Icon::FilePath.new(
+          name: name.to_s,
+          library: library.to_s,
+          variant: variant.to_s
+        ).call
+      end
+
+      def exists?
+        File.exist?(file_path)
+      rescue Icons::IconNotFound
+        false
+      end
+    end
+  end
+end

data/lib/icons/sprite.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+module Icons
+  class Sprite
+    # @param config [Configuration] The configuration object (defaults to Icons.configuration)
+    # @param icons [Array<String>, nil] Optional list of icon names to include (defaults to configured icons)
+    # @param library [String, Symbol, nil] The icon library to use when icons are provided
+    # @param variant [String, Symbol, nil] The icon variant to use when icons are provided
+    #
+    def initialize(config: Icons.configuration, icons: nil, library: nil, variant: nil)
+      @config = config
+      @icons = icons
+      @library = library
+      @variant = variant
+    end
+
+    # Returns the combined SVG sprite markup containing all icon symbols
+    #
+    # @return [String] The SVG markup with `<symbol>` elements wrapped in a hidden `<svg>`
+    #
+    def svg
+      symbols = references.filter_map { |reference| symbol_from(reference) }
+
+      <<~SVG
+        <svg xmlns="http://www.w3.org/2000/svg" style="display: none;">
+          #{symbols.join("\n  ")}
+        </svg>
+      SVG
+    end
+
+    private
+
+    def references
+      @icons ? override_references : configured_references
+    end
+
+    def override_references
+      library = @library || @config.default_library
+      variant = @variant || @config.default_variant
+
+      @icons.map { |name| Sprite::Reference.new(name: name, library: library, variant: variant) }
+    end
+
+    def configured_references
+      sprite_config = @config.sprite || {}
+
+      sprite_config.flat_map do |library, variants|
+        variants.flat_map do |variant, names|
+          names.map { |name| Sprite::Reference.new(name: name, library: library, variant: variant) }
+        end
+      end
+    end
+
+    def symbol_from(reference)
+      return unless reference.exists?
+
+      svg_element = Nokogiri::XML(File.read(reference.file_path)).at_css("svg")
+      view_box = svg_element["viewBox"] || "0 0 24 24"
+      content = svg_element.children.map(&:to_s).join
+
+      %(<symbol id="#{reference.id}" viewBox="#{view_box}">#{content}</symbol>)
+    rescue Icons::IconNotFound
+      warn "Icon not found: #{reference.name} from #{reference.library}/#{reference.variant}"
+
+      nil
+    end
+  end
+end

data/lib/icons/sprite_icon.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+require "nokogiri"
+
+require "icons/icon/attributes"
+require "icons/icon/configurable"
+
+class Icons::SpriteIcon
+  include Icons::Icon::Configurable
+
+  # @param name [String] The icon name
+  # @param library [String, Symbol] The icon library
+  # @param variant [String, Symbol, nil] The icon variant (optional)
+  # @param arguments [Hash] Additional attributes including class, data, stroke_width, etc.
+  # @param sprite_location [String, nil] Override URL for the sprite file (optional)
+  # @param config [Configuration] The configuration object (defaults to Icons.configuration)
+  #
+  def initialize(name:, library:, arguments:, variant: nil, sprite_location: nil, config: Icons.configuration)
+    @config = config
+
+    @name = name
+    @library = library.to_sym
+    @variant = (variant || set_variant)&.to_sym
+    @arguments = arguments
+    @sprite_location = sprite_location || @config.default_sprite_location
+  end
+
+  # Returns the SVG markup referencing the icon from a sprite sheet
+  #
+  # @return [String] The SVG markup using a `<use>` tag referencing the sprite symbol
+  #
+  # @raise [Icons::IconNotFound] If validate_sprite_icons is enabled and the icon does not exist
+  #
+  def svg
+    if @config.validate_sprite_icons
+      raise Icons::IconNotFound, error_message unless reference.exists?
+    end
+
+    sprite_svg
+  end
+
+  private
+
+  def reference
+    @reference ||= Icons::Sprite::Reference.new(name: @name, library: @library, variant: @variant)
+  end
+
+  def sprite_svg
+    sprite_href = @sprite_location.nil? ? "##{reference.id}" : "#{@sprite_location}##{reference.id}"
+
+    svg_content = <<~SVG
+      <svg><use href="#{sprite_href}"></use></svg>
+    SVG
+
+    Nokogiri::HTML::DocumentFragment.parse(svg_content)
+      .at_css("svg")
+      .tap { |svg| attach_attributes(to: svg) }
+      .to_html
+  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
@@ -47,10 +48,13 @@ module Icons
 
       def apply_transformations_to(destination)
         Dir.each_child(destination) do |filename|
-          File.rename(
-            File.join(destination, filename),
-            File.join(destination, Sync::Transformations.transform(filename, transformations.fetch(:filenames, {})))
-          )
+          original_file_path = File.join(destination, filename)
+          transformed_filename = Sync::Transformations.transform(filename, transformations)
+          transformed_file_path = File.join(destination, transformed_filename)
+
+          File.rename(original_file_path, transformed_file_path)
+
+          transform_svg(transformed_file_path)
         end
       end
 
@@ -75,6 +79,14 @@ module Icons
           {}
         end
       end
+
+      def transform_svg(file_path)
+        return if File.extname(file_path) != ".svg"
+
+        svg_transformations = transformations.fetch(:svg, [])
+
+        Sync::Transformations.transform_svg(file_path, svg_transformations)
+      end
     end
   end
 end

data/lib/icons/sync/transformations.rb

@@ -1,21 +1,40 @@
 # frozen_string_literal: true
 
+require "nokogiri"
+
 module Icons
   class Sync
     class Transformations
       def self.transform(filename, rules = {})
         basename = File.basename(filename, File.extname(filename))
 
-        transformed = rules.reduce(basename) do |fn, (type, value)|
-          TRANSFORMERS.fetch(type).call(fn, value)
+        transformed = rules.fetch(:filenames, {}).reduce(basename) do |fn, (type, value)|
+          FILENAME_TRANSFORMERS.fetch(type).call(fn, value)
         end
 
         [transformed, File.extname(filename)].join
       end
 
+      def self.transform_svg(file_path, rules = [])
+        return unless rules.any?
+
+        svg_document = Nokogiri::HTML::DocumentFragment.parse(File.read(file_path))
+
+        rules.each do |rule|
+          SVG_TRANSFORMERS.fetch(rule[:action]).call(
+            svg_document,
+            rule[:element],
+            rule[:attribute],
+            rule[:value]
+          )
+        end
+
+        File.write(file_path, svg_document.to_html)
+      end
+
       private
 
-      TRANSFORMERS = {
+      FILENAME_TRANSFORMERS = {
         delete_prefix: ->(filename, prefixes) {
           Array(prefixes).reduce(filename) { |fn, prefix| fn.delete_prefix(prefix) }
         },
@@ -24,6 +43,14 @@ module Icons
           Array(suffixes).reduce(filename) { |fn, suffix| fn.delete_suffix(suffix) }
         }
       }
+
+      SVG_TRANSFORMERS = {
+        set_attribute: ->(document, element_selector, attribute_name, attribute_value) {
+          document.css(element_selector).each do |element|
+            element[attribute_name] = attribute_value
+          end
+        }
+      }
     end
   end
 end

data/lib/icons/sync.rb

@@ -5,12 +5,13 @@ require "icons/sync/process_variants"
 
 module Icons
   class Sync
-    def initialize(name)
-      raise "[Icons] Not a valid library" if Icons.libraries.keys.exclude?(name.to_sym)
+    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
@@ -36,13 +37,30 @@ module Icons
     end
 
     def clone_repository
-      raise "[Icons] Failed to clone repository" unless system("git clone '#{@library[:url]}' '#{@temp_directory}'")
+      unless clone_repository_sparse
+        puts "[Icons] Sparse clone failed, falling back to full clone"
+        FileUtils.rm_rf(@temp_directory)
+
+        raise "[Icons] Failed to clone repository" unless system("git clone '#{@library[:url]}' '#{@temp_directory}'")
+      end
 
       puts "[Icons] '#{@name}' repository cloned"
     end
 
+    def clone_repository_sparse
+      system("git clone --depth 1 --filter=blob:none --sparse '#{@library[:url]}' '#{@temp_directory}'") &&
+        system("git -C '#{@temp_directory}' sparse-checkout set #{sparse_checkout_paths}")
+    end
+
+    def sparse_checkout_paths
+      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.8.1"
+  VERSION = "0.10.0"
 end

data/lib/icons.rb

@@ -4,18 +4,27 @@ 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"
 require "icons/sync"
 
 module Icons
   class << self
+    # @return [Configuration]
     attr_accessor :configuration
 
+    # @yield [config] Yields the configuration object for customization
+    # @yieldparam config [Configuration]
+    #
     def configure
       self.configuration ||= Configuration.new
       yield(configuration) if block_given?
     end
 
+    # @return [Configuration]
+    #
     def config
       configuration || configure {}
     end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: icons
 version: !ruby/object:Gem::Version
-  version: 0.8.1
+  version: 0.10.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
@@ -67,8 +68,12 @@ files:
 - lib/icons/errors.rb
 - lib/icons/icon.rb
 - lib/icons/icon/attributes.rb
+- lib/icons/icon/configurable.rb
 - lib/icons/icon/file_path.rb
 - lib/icons/libraries.rb
+- lib/icons/sprite.rb
+- lib/icons/sprite/reference.rb
+- lib/icons/sprite_icon.rb
 - lib/icons/sync.rb
 - lib/icons/sync/process_variants.rb
 - lib/icons/sync/transformations.rb
@@ -86,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.8
+rubygems_version: 4.0.22
 specification_version: 4
 summary: Add any icon library to a Ruby app
 test_files: []