phlex-icons-remix 2.19.0 → 2.20.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f3b1e33cbe36620964299ea71a4244b05288899d4ed7e9d77d34f43b24604ef1
-  data.tar.gz: 55c06f67e36af0ce521af86f445fcb91c992fd1d86303dd14d031c4e0d18dd6d
+  metadata.gz: 7f2e4d014e149c487878e9617e87b46fa8f9d337cd5c0fa61ca9fe59052565c2
+  data.tar.gz: 0e869885590e034cc9bd2bce235e1e672ee11a959ba29f2d67b5912b85c9504a
 SHA512:
-  metadata.gz: 785af670c354dd9ec95472ac597d0352f87e096a1c8352e01a46070a837e5a0a164bb444dcbb0d849c73998a478b13e6c521526d8c993b17340994ecbb8014a8
-  data.tar.gz: a77047190bcf8e7feb589ef120f95c7dfad58990cca2e019cee76d89513925998dce2d9c29213af2606eec201a9eb5f6734260430da93163c1d8383a56ebeb07
+  metadata.gz: d2af13a8f755ef205bcabe3aeccf70276ee750ed5f3ff156b672def3e4d17f5a667175616166c50ce7d3731699408b6b87f9baf4a474dc977642f7d19a2fa6d4
+  data.tar.gz: 97a42d75ce8de5c702dc33f0649b856cf0350b0488252deb67a9b887fbbfff6789fab8b6022ba871d29c9c19bf2348f9ed9fb821ef15ec27d6b619387f1631b4

data/.rubocop.yml

@@ -25,4 +25,8 @@ Metrics/MethodLength:
   CountAsOne: ['array', 'method_call']
 
 Metrics/ClassLength:
-  CountAsOne: ['array', 'method_call']
+  CountAsOne: ['array', 'method_call']
+
+Metrics/BlockLength:
+  Exclude:
+    - 'spec/**/*'

data/README.md

@@ -62,11 +62,15 @@ The gem provides global configuration options, and per icons pack configuration
 ```ruby
 PhlexIcons.configure do |config|
   config.default_classes = 'size-6'
+  config.helper_method_name = :phlex_icon # Default: :phlex_icon
+  config.default_pack = :hero # Default: nil. Accepts :symbol, "string", or Class (e.g., PhlexIcons::Hero)
 end
 
 # OR
 
 PhlexIcons.configuration.default_classes = 'size-6'
+PhlexIcons.configuration.helper_method_name = :phlex_icon
+PhlexIcons.configuration.default_pack = :hero
 ```
 
 ### Bootstrap Icons configuration
@@ -153,6 +157,9 @@ class PhlexIcons < Phlex::HTML
       Radix::Home(class: 'size-4')
       Remix::HomeLine(class: 'size-4')
       Tabler::Home(variant: :filled, class: 'size-4')
+
+      # or with a string
+      Icon('bootstrap/house', class: 'size-4')
     end
   end
 end
@@ -174,11 +181,48 @@ class PhlexIcons < Phlex::HTML
       render PhlexIcons::Radix::Home.new(class: 'size-4')
       render PhlexIcons::Remix::HomeLine.new(class: 'size-4')
       render PhlexIcons::Tabler::Home.new(variant: :filled, class: 'size-4')
+
+      # or with a string
+      render PhlexIcons::Icon('bootstrap/house', class: 'size-4')
     end
   end
 end
 ```
 
+### Rails View Helper
+
+`phlex-icons` provides a convenient helper method to render icons directly in your ERB or Phlex views.
+
+By default, the helper method is named `phlex_icon`, but is configurable.
+
+```erb
+<%# Render a Bootstrap house icon with default size %>
+<%= phlex_icon 'bootstrap/house' %>
+
+<%# Render a Heroicons solid home icon with a specific class %>
+<%= phlex_icon 'hero/home', variant: :solid, class: 'w-5 h-5 text-blue-500' %>
+
+<%# Render a Tabler home icon, filled variant %>
+<%= phlex_icon 'tabler/home:filled' %>
+
+<%# If default_pack = :hero, render a Heroicons home icon %>
+<%= phlex_icon 'home', class: 'w-6 h-6' %>
+
+<%# Render a Flag icon (rectangle variant is default for flags if not configured otherwise) %>
+<%= phlex_icon 'flag/sa' %>
+
+<%# Render a custom icon %>
+<%= phlex_icon 'custom/my_awesome_icon:variant_name' %>
+```
+
+The first argument is the icon identifier. Such as: `'pack/icon_name:variant'`.
+
+*   If `default_pack` is configured, you can omit the pack name (e.g., `'icon_name:variant'` instead of `'pack/icon_name:variant'`).
+*   The `:variant` part is optional.
+*   Examples: `'hero/house:solid'`, `'house:solid'`, `'house'`
+
+Subsequent arguments are passed as options to the icon component, such as `variant`, `class`, etc.
+
 ### Specific icon pack(s)
 
 Let's say you want to use only Heroicons and Flag Icons, you can use the following gems:

data/lib/phlex-icons/configuration.rb

@@ -2,10 +2,33 @@
 
 module PhlexIcons
   class Configuration
-    attr_accessor :default_variant, :default_classes
+    attr_accessor :default_variant, :default_classes, :helper_method_name
+    attr_reader :default_pack
 
     def initialize(default_classes: 'size-6')
       @default_classes = default_classes
+      @helper_method_name = :phlex_icon
+      @default_pack = nil
+    end
+
+    # Custom setter for default_pack
+    # Accepts Class (PhlexIcons::Hero), String ('hero'), or Symbol (:hero)
+    #
+    # @param value [Class, String, Symbol, nil] The value to set the default pack to.
+    # @raise [ArgumentError] If the value is not a Class, String, Symbol, or nil.
+    def default_pack=(value)
+      @default_pack = case value
+                      when Class
+                        # Extract 'Hero' from PhlexIcons::Hero, lowercase, symbolize
+                        value.name.split('::').last&.downcase&.to_sym
+                      when String, Symbol
+                        value.to_sym
+                      when nil
+                        nil
+                      else
+                        raise ArgumentError,
+                              "Invalid type for default_pack: #{value.class}. Expected Class, String, Symbol, or nil."
+                      end
     end
   end
 end

data/lib/phlex-icons/icon.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+require_relative 'name_parser'
+
+module PhlexIcons
+  extend Phlex::Kit
+
+  class Icon < Phlex::SVG
+    # Factory method to create an icon component instance.
+    # Parses the name string, finds the corresponding class, and initializes it with options.
+    # @param name [String] Icon identifier (e.g., "hero/house:solid", "lucide/arrow-right").
+    # @param options [Hash] HTML attributes and options for the icon component.
+    # @return [Phlex::SVG] An instance of the resolved icon component.
+    # @raise [ArgumentError] If the name format is invalid or default pack is missing.
+    # @raise [NameError] If the corresponding icon class cannot be found.
+    def initialize(name, **options)
+      @name = name
+      @options = options&.transform_keys(&:to_sym) || {}
+      super()
+    end
+
+    def view_template
+      parser = PhlexIcons::NameParser.new(@name)
+
+      # Prioritize variant from the name string over options hash
+      @options[:variant] = parser.variant_name if parser.variant_name
+
+      render parser.klass.new(**@options)
+    end
+  end
+end

data/lib/phlex-icons/name_parser.rb

@@ -0,0 +1,117 @@
+# frozen_string_literal: true
+
+module PhlexIcons
+  class NameParser
+    attr_reader :pack_name, :icon_name, :variant_name, :identifier, :klass
+
+    # Initializes the parser with the full icon identifier string (e.g., "hero/arrow-right:solid").
+    # Parses the string into pack, icon, and variant components.
+    # Determines and validates the corresponding icon component class.
+    # @param identifier [String] The full icon identifier.
+    # @raise [ArgumentError] If the name format is invalid or default pack is missing.
+    # @raise [NameError] If the corresponding icon class cannot be found.
+    def initialize(identifier)
+      @identifier = identifier.to_s
+      @pack_name, @icon_name, @variant_name = parse(@identifier)
+      @klass = find_icon_class(@pack_name, @icon_name)
+    end
+
+    private
+
+    # Performs the core parsing logic.
+    # @param identifier [String] The full icon identifier.
+    # @return [Array<String, String, Symbol, nil>] An array containing [pack_name, icon_name, variant_name].
+    def parse(identifier)
+      name_part, variant = identifier.split(':', 2)
+
+      # Check if the part before ':' (or the whole string if no ':') is empty
+      if name_part.nil? || name_part.strip.empty?
+        raise ArgumentError,
+              "Invalid icon name format. Could not determine pack or icon name from '#{identifier}'."
+      end
+
+      parsed_variant = variant&.empty? ? nil : variant&.to_sym
+      pack, icon = parse_pack_and_icon(name_part)
+
+      validate_identifier_parts(pack, icon, identifier)
+
+      [pack, icon, parsed_variant]
+    end
+
+    # Extracts the pack and icon names from the part before the variant separator (':').
+    # @param name_part [String] The part of the name string before ':'.
+    # @return [Array<String, String>] An array containing [pack_name, icon_name].
+    def parse_pack_and_icon(name_part)
+      if name_part.include?('/')
+        # If split results in empty parts, they will be caught by validate_identifier_parts later
+        name_part.split('/', 2)
+      else
+        # If name_part is just the icon, it cannot be empty (checked in `parse`)
+        [get_default_pack_name_or_raise(name_part), name_part]
+      end
+    end
+
+    # Retrieves the configured default pack name or raises an error if not set.
+    # @param icon_name_part [String] The icon name used when the pack prefix is missing (for error message).
+    # @return [String] The default pack name.
+    # @raise [ArgumentError] If PhlexIcons.configuration.default_pack is not configured.
+    def get_default_pack_name_or_raise(icon_name_part)
+      # Assumes PhlexIcons.configuration is available.
+      # Consider requiring 'phlex_icons/configuration' explicitly if needed outside Rails context.
+      default_pack_name = defined?(PhlexIcons.configuration) ? PhlexIcons.configuration&.default_pack&.to_s : nil
+      unless default_pack_name && !default_pack_name.empty?
+        raise ArgumentError,
+              "Icon name '#{icon_name_part}' is missing the pack name prefix (e.g., 'hero/'), " \
+              'and no `default_pack` is configured in PhlexIcons.'
+      end
+      default_pack_name
+    end
+
+    # Validates that both pack and icon name parts were successfully extracted.
+    # @param pack [String, nil] The extracted pack name.
+    # @param icon [String, nil] The extracted icon name.
+    # @param identifier [String] The original full identifier (for error message).
+    # @raise [ArgumentError] If either pack or icon is missing or empty.
+    def validate_identifier_parts(pack, icon, identifier)
+      return if pack && !pack.empty? && icon && !icon.empty?
+
+      raise ArgumentError,
+            "Invalid icon name format. Could not determine pack or icon name from '#{identifier}'."
+    end
+
+    # Finds the PhlexIcon component class based on pack and icon names.
+    # @param pack_name [String] The kebab-case pack name (e.g., "hero").
+    # @param icon_name [String] The kebab-case icon name (e.g., "arrow-right").
+    # @return [Class] The icon component class.
+    # @raise [NameError] If the corresponding icon class cannot be found.
+    def find_icon_class(pack_name, icon_name)
+      class_name = build_icon_class_name(pack_name, icon_name)
+      find_and_validate_icon_class(class_name, pack_name, icon_name)
+    end
+
+    # Constructs the full Ruby class name for an icon component.
+    # @param pack_name [String] The kebab-case pack name (e.g., "hero").
+    # @param icon_name [String] The kebab-case icon name (e.g., "arrow-right").
+    # @return [String] The CamelCase class name (e.g., "PhlexIcons::Hero::ArrowRight").
+    def build_icon_class_name(pack_name, icon_name)
+      pack_module_name = pack_name.split('-').map(&:capitalize).join
+      icon_class_name = icon_name.split('-').map(&:capitalize).join
+      "PhlexIcons::#{pack_module_name}::#{icon_class_name}"
+    end
+
+    # Attempts to find the icon class by its name and validates its existence.
+    # @param class_name [String] The full class name to find.
+    # @param pack_name [String] Original pack name (for error message).
+    # @param icon_name [String] Original icon name (for error message).
+    # @return [Class] The found icon component class.
+    # @raise [NameError] If the class cannot be found.
+    def find_and_validate_icon_class(class_name, pack_name, icon_name)
+      Object.const_get(class_name)
+    rescue NameError
+      raise NameError,
+            "Could not find icon component class '#{class_name}'. " \
+            "Make sure the pack ('#{pack_name}') and name ('#{icon_name}') " \
+            'are correct and the corresponding file is loaded.'
+    end
+  end
+end

data/lib/phlex-icons/railtie.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+require_relative 'configuration'
+
+module PhlexIcons
+  class Railtie < ::Rails::Railtie
+    initializer 'phlex_icons.view_helpers' do
+      ActiveSupport.on_load(:action_view) do
+        helper_method_name = PhlexIcons.configuration.helper_method_name
+
+        define_method helper_method_name do |name, **options|
+          PhlexIcons::Icon.call(name, **options)&.html_safe
+        end
+      end
+    end
+  end
+end

data/lib/phlex-icons/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module PhlexIcons
-  VERSION = '2.19.0'
+  VERSION = '2.20.0'
 end

data/lib/phlex-icons-remix.rb

@@ -12,6 +12,9 @@ require_relative 'phlex-icons/version'
 require_relative 'phlex-icons/material'
 require_relative 'phlex-icons/remix'
 
+require_relative 'phlex-icons/icon'
+require_relative 'phlex-icons/railtie' if defined?(Rails)
+
 module PhlexIcons
   class << self
     def configuration

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: phlex-icons-remix
 version: !ruby/object:Gem::Version
-  version: 2.19.0
+  version: 2.20.0
 platform: ruby
 authors:
 - Ali Hamdi Ali Fadel
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2025-04-25 00:00:00.000000000 Z
+date: 2025-05-11 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: phlex
@@ -53,6 +53,7 @@ files:
 - lib/phlex-icons-remix.rb
 - lib/phlex-icons/base.rb
 - lib/phlex-icons/configuration.rb
+- lib/phlex-icons/icon.rb
 - lib/phlex-icons/material.rb
 - lib/phlex-icons/material/abc.rb
 - lib/phlex-icons/material/abc_filled.rb
@@ -12777,6 +12778,8 @@ files:
 - lib/phlex-icons/material/zoom_out_round.rb
 - lib/phlex-icons/material/zoom_out_sharp.rb
 - lib/phlex-icons/material/zoom_out_two_tone.rb
+- lib/phlex-icons/name_parser.rb
+- lib/phlex-icons/railtie.rb
 - lib/phlex-icons/remix.rb
 - lib/phlex-icons/remix/a_b.rb
 - lib/phlex-icons/remix/accessibility_fill.rb