icons 0.8.1 → 0.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 258de5224f1792f19bc6024149d3b83796c215fb2dafcdb4ad832817396fa497
-  data.tar.gz: 735659b38f49f975bfd758c7260e7ea5ac56971a9cd3942293b8f0ae2c240f3d
+  metadata.gz: eddb62f576eb4a0f7914cd2fba762e6306bed0fefd719671c9f631a3d4b84644
+  data.tar.gz: a108e7b8f54aada59206d3c2a125d4b75c6e05386ac84ca760f13a801d2dbb8d
 SHA512:
-  metadata.gz: 62fa8a1399597b1e99e524f16db444af2680a42e23b5b86d938ed9855fa0859e134f2810aed56d51e398e79f366c71a9106bd12de70e0f62a26ccdbe449e1e32
-  data.tar.gz: 233185f2705e719ec0230091aec8b2390a70e7ea74bdbe09376942388fa6db1dbf5ab6f5757afbf5fab89f5f83b0c7ce90c2a72ea732a9dfc52ac5e96db1f6cc
+  metadata.gz: 2f6d4f4a1e29efc77f46622ab78b4aa041d7a5116d3c4ec945a610d66f60f8f8cd66266f0cbfcb0b9ccff6d7f4c515c726d69ece0af5bc41c729da31054d4f66
+  data.tar.gz: 22dcc6888aa46bf59476e9d511df57d04ff4ff7e5c32230372164f06c8ccd6654e3875a28d2a986874eae162330d1dd581e24e051d861511b7fb4126c3a9e038

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    icons (0.8.1)
+    icons (0.9.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.9.0)
   io-console (0.8.2) sha256=d6e3ae7a7cc7574f4b8893b4fca2162e57a825b223a177b7afa236c5ef9814cc
   irb (1.16.0) sha256=2abe56c9ac947cdcb2f150572904ba798c1e93c890c256f8429981a7675b0806
   json (2.18.0) sha256=b10506aee4183f5cf49e0efc48073d7b75843ce3782c68dbeb763351c08fd505

data/README.md

@@ -34,6 +34,22 @@ 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.

data/lib/icons/configuration/boxicons.rb

@@ -50,7 +50,11 @@ module Icons
         {
           filenames: {
             delete_prefix: ["bxl-", "bx-", "bxs-"]
-          }
+          },
+
+          svg: [
+            {element: "path", action: :set_attribute, attribute: "fill", value: "currentColor"}
+          ]
         }
       end
 

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,22 +18,31 @@ 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
@@ -41,6 +53,9 @@ module Icons
       @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/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,6 +15,8 @@ require "icons/configuration/weather"
 module Icons
   extend self
 
+  # @return [Hash{Symbol => Class}] A map of library names to their configuration classes
+  #
   def libraries
     {
       boxicons: Icons::Configuration::Boxicons,

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

@@ -47,10 +47,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 +78,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

@@ -6,7 +6,7 @@ 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)
+      raise "[Icons] Not a valid library" unless Icons.libraries.key?(name.to_sym)
 
       @name = name
       @library = Icons.libraries.fetch(name.to_sym).source
@@ -36,11 +36,25 @@ 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
+      @library[:variants].values.map { |path| "'#{path}'" }.join(" ")
+    end
+
     def process_variants
       Sync::ProcessVariants.new(@temp_directory, @name, @library).process
     end

data/lib/icons/version.rb

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

data/lib/icons.rb

@@ -5,17 +5,25 @@ require "icons/errors"
 require "icons/libraries"
 require "icons/configuration"
 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.9.0
 platform: ruby
 authors:
 - Rails Designer
@@ -67,8 +67,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
@@ -93,7 +97,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.8
+rubygems_version: 4.0.14
 specification_version: 4
 summary: Add any icon library to a Ruby app
 test_files: []