hanami_icons 0.5.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: f3afa33bc73c5af3cbd69a0e5fc7a9417c608b6173ea4e1ab0ceb101220af122
+  data.tar.gz: 3409501c85d83eee1d8871251d58012f89552b56bd00450918ef62ec0c3bd080
+SHA512:
+  metadata.gz: 653d92e5ca0206d4a8ddd09d6b8ea393078e66f4850c8c8b1be4d390daf2cbac44f514c64556b3a54a0ca774b6140554963d7428911e82554aa6d950d2bfd080
+  data.tar.gz: f7f93a4158c3817630bb28563267807a66a58cf2c3bf7fd5d2381724f41a0127349f897c8431ee951bdc4b356f9d1b9cd60cde4cd7c5406bafdddde04af9211e

data/Gemfile

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+source "https://rubygems.org"
+
+gemspec
+
+gem "minitest"
+gem "rake"
+gem "standard"

data/README.md

@@ -0,0 +1,228 @@
+# Hanami Icons
+
+Add any icon library to a Hanami app. Hanami Icons has first-party support for a [handful of libraries](#first-party-libraries). It is library agnostic so it can be used with any icon library using the same interface. Hanami Icons is a Hanami gem for the [Icons Ruby gem](https://github.com/Rails-Designer/icons).
+
+```erb
+# Using the default icon library
+<%== icon "check", class: "text-gray-500" %>
+
+# Using any custom library
+<%== icon "apple", library: "simple_icons", class: "text-black" %>
+```
+
+The icons are sourced directly from their respective GitHub repositories via the [Icons](https://github.com/Rails-Designer/icons) gem, ensuring Hanami Icons remain lightweight.
+
+**Sponsored By [Rails Designer](https://railsdesigner.com/)**
+
+## Install
+
+Add the gem:
+
+```bash
+bundle add hanami_icons
+```
+
+Install, choosing one of the supported libraries:
+
+```bash
+hanami generate icons --library=heroicons
+```
+
+**Example**
+
+```bash
+hanami generate icons --library=heroicons
+
+# Or multiple at once
+hanami generate icons --libraries=heroicons lucide
+
+# Or only specific variants
+hanami generate icons --library=heroicons --variants solid outline
+```
+
+This creates `config/providers/icons.rb`, registers the provider with the app container and adds the view helpers into `app/views/helpers.rb`.
+
+## Usage
+
+```ruby
+# Uses the default library and variant defined in config/providers/icons.rb
+icon "check"
+
+# Use another variant
+icon "check", variant: "solid"
+
+# Set library explicitly
+icon "check", library: "heroicons"
+
+# Add CSS
+icon "check", class: "text-green-500"
+
+# Add data attributes
+icon "check", data: { controller: "swap" }
+
+# Set the stroke-width
+icon "check", stroke_width: 2
+
+# Base64-encoded data URI
+encoded_icon "check"
+```
+
+The helpers return `Hanami::View::HTML::SafeString`, so they are safe to output in templates (`<%== … %>` or `&= …`).
+
+## Sprites
+
+Hanami Icons supports SVG sprites for improved performance. Instead of inlining each icon's full SVG, sprite icons reference a shared set of `<symbol>` definitions via `<use href="…">`.
+
+### Configuration
+
+```ruby
+# config/providers/icons.rb
+HanamiIcons.configure do |config|
+  config.default_library = "heroicons"
+  config.default_variant = "outline"
+
+  # Where `sprite_icon` references symbols. Set to nil to use inline mode (`<%== icons_sprite %>` in layout).
+  config.default_sprite_location = "/sprite.svg"
+
+  # Set to true to validate that referenced icons exist on disk
+  config.validate_sprite_icons = false
+
+  # Define which icons to include in the sprite
+  config.sprite = {
+    heroicons: {
+      outline: %w[check chevron-down menu search x],
+      mini: %w[check chevron-down]
+    }
+  }
+end
+```
+
+### External sprite
+
+Generate a static sprite file and reference it with `sprite_icon`:
+
+```bash
+hanami generate icons:sprite
+```
+
+```erb
+<%== sprite_icon "check" %>
+<%# renders: <svg><use href="/sprite.svg#heroicons_outline_check"></use></svg> %>
+```
+
+Point at a precompiled file or a CDN by changing the location:
+
+```ruby
+config.default_sprite_location = "https://cdn.example.com/sprite_icons.svg"
+```
+
+Override per icon:
+
+```erb
+<%== sprite_icon "check", sprite_location: "/assets/sprites.svg" %>
+```
+
+### Inline sprite
+
+Set the location to `nil` and embed the sprite directly in your layout:
+
+```ruby
+config.default_sprite_location = nil
+```
+
+```erb
+<body>
+  <%== icons_sprite %>
+
+  <%== sprite_icon "check" %>
+  <%== sprite_icon "search", class: "text-blue-500" %>
+  <%== sprite_icon "menu", data: { controller: "nav" } %>
+</body>
+```
+
+You can also generate a sprite for a specific set of icons:
+
+```erb
+<%== icons_sprite ["check", "search"], library: "heroicons", variant: "outline" %>
+```
+
+## Sync icons
+
+To sync all libraries, run:
+
+```bash
+hanami generate icons:sync
+```
+
+To sync only a specific library, run:
+
+```bash
+hanami generate icons:sync --library=heroicons
+
+# Or multiple at once:
+hanami generate icons:sync --libraries=heroicons lucide
+```
+
+To sync only specific variants for a library:
+
+```bash
+hanami generate icons:sync --library=heroicons --variants solid outline
+```
+
+## Custom icon libraries
+
+Hanami Icons pulls SVGs straight from the path `<icons_path>/<library_name>/<name>.svg`. No generator is required for custom icons. Configuration is optional and only used to define defaults.
+
+To add a custom library, create its directory and drop in your SVGs:
+
+```
+app/assets/svg/icons/simple_icons/apple.svg
+```
+
+(alternatively, scaffold it with `hanami generate icons --library=simple_icons`, which creates the directory and adds `config.custom_library :simple_icons` in the provider.)
+
+Use them like any other library:
+
+```ruby
+icon "apple", library: "simple_icons"
+```
+
+To add a git source for syncing, edit the provider:
+
+```ruby
+HanamiIcons.configure do |config|
+  config.custom_library :my_icons, source: {
+    url: "https://github.com/user/icons.git",
+    variants: { default: "." }
+  }
+end
+```
+
+Then sync:
+
+```bash
+hanami generate icons:sync --library=my_icons
+```
+
+## First-party libraries
+
+- [Boxicons](https://railsdesigner.com/open-source/rails-icons/boxicons/) (1600+ icons)
+- [Feather](https://railsdesigner.com/open-source/rails-icons/feather/) (280+ icons)
+- [Flags](https://railsdesigner.com/open-source/rails-icons/flags/) (540+ icons)
+- [Heroicons](https://railsdesigner.com/open-source/rails-icons/heroicons/) (300+ icons)
+- [Hugeicons](https://railsdesigner.com/open-source/rails-icons/hugeicons/) (4600+ icons)
+- [Linear](https://railsdesigner.com/open-source/rails-icons/linear/) (170+ icons)
+- [Lucide](https://railsdesigner.com/open-source/rails-icons/lucide/) (1500+ icons)
+- [Phosphor](https://railsdesigner.com/open-source/rails-icons/phosphor/) (9000+ icons)
+- [Radix](https://railsdesigner.com/open-source/rails-icons/radix/) (300+ icons)
+- [SidekickIcons](https://railsdesigner.com/open-source/rails-icons/sidekickicons/) (49 icons, complementing [Heroicons](https://railsdesigner.com/open-source/rails-icons/heroicons/))
+- [Tabler](https://railsdesigner.com/open-source/rails-icons/tabler/) (5700+ icons)
+- [Weather](https://railsdesigner.com/open-source/rails-icons/weather/) (215+ icons)
+
+## Contributing
+
+This project uses [Standard](https://github.com/testdouble/standard) for formatting Ruby code. Please make sure to run `bundle exec standardrb` before submitting pull requests. Run tests via `bundle exec rake`.
+
+## License
+
+Hanami Icons is released under the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rake/testtask"
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << "test"
+  t.libs << "lib"
+
+  t.test_files = FileList["test/**/*_test.rb"]
+end
+
+task :standard do
+  sh "bundle exec standardrb"
+end
+
+task default: %i[test standard]

data/hanami_icons.gemspec

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+require_relative "lib/hanami_icons/version"
+
+Gem::Specification.new do |spec|
+  spec.name = "hanami_icons"
+  spec.version = HanamiIcons::VERSION
+  spec.authors = ["Rails Designer"]
+  spec.email = ["devs@railsdesigner.com"]
+
+  spec.summary = "Add any icon library to a Hanami app"
+  spec.description = "Add any icon library to a Hanami app, from Heroicons, to Lucide to Tabler (and others). Hanami Icons is library-agnostic, so you can add any library while using the same interface."
+  spec.homepage = "https://railsdesigner.com/open-source/hanami-icons/"
+  spec.license = "MIT"
+
+  spec.metadata["homepage_uri"] = spec.homepage
+  spec.metadata["source_code_uri"] = "https://github.com/Rails-Designer/hanami_icons"
+  spec.metadata["changelog_uri"] = "https://github.com/Rails-Designer/hanami_icons/releases"
+  spec.metadata["bug_tracker_uri"] = "https://github.com/Rails-Designer/hanami_icons/issues"
+  spec.metadata["documentation_uri"] = spec.homepage
+  spec.metadata["rubygems_mfa_required"] = "true"
+
+  spec.files = Dir["lib/**/*", "Rakefile", "README.md", "LICENSE.txt", "hanami_icons.gemspec", "Gemfile"]
+
+  spec.require_paths = ["lib"]
+
+  spec.required_ruby_version = ">= 3.3"
+
+  spec.add_dependency "base64"
+  spec.add_dependency "hanami-view", "~> 3.0"
+  spec.add_dependency "hanami-cli", "~> 3.0"
+  spec.add_dependency "icons", "~> 0.11.0"
+end

data/lib/hanami_icons/cli/commands/generate/icons.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+require "hanami/cli"
+
+module HanamiIcons
+  module CLI
+    module Commands
+      module Generate
+        # Installs Hanami Icons by creating the provider file, wiring the view
+        # helpers and syncing the chosen libraries.
+        #
+        # @api public
+        # @since 0.1.0
+        class Icons < Hanami::CLI::Command
+          desc "Install Hanami Icons with the chosen libraries"
+
+          option :library, desc: "Choose a library"
+          option :libraries, type: :array, default: [], desc: "Choose libraries"
+          option :variants, type: :array, desc: "Only sync specific variants (e.g. solid outline)"
+          option :destination, type: :string, default: HanamiIcons.configuration.icons_path, desc: "Specify destination folder for icons"
+          option :skip_sync, type: :boolean, default: false
+
+          # @param library [String, nil]
+          # @param libraries [Array<String>]
+          # @param variants [Array<String>, nil]
+          # @param destination [String]
+          # @param skip_sync [Boolean]
+          #
+          # @api public
+          # @since 0.1.0
+          def call(library: nil, libraries: [], variants: nil, destination: HanamiIcons.configuration.icons_path, skip_sync: false, **)
+            run_initializer(library: library, libraries: libraries, variants: variants, destination: destination)
+
+            if !skip_sync && selected_libraries(library, libraries).any?
+              run_sync(library: library, libraries: libraries, variants: variants)
+            end
+          end
+
+          private
+
+          # @api private
+          # @since 0.1.0
+          def run_initializer(library:, libraries:, variants:, destination:)
+            Generate::Initializer.new(out: out, err: err, fs: fs).call(
+              library: library,
+              libraries: libraries,
+              variants: variants,
+              destination: destination
+            )
+          end
+
+          # @api private
+          # @since 0.1.0
+          def run_sync(library:, libraries:, variants:)
+            Generate::Sync.new(out: out, err: err, fs: fs).call(
+              library: library,
+              libraries: libraries,
+              variants: variants
+            )
+          end
+
+          # @api private
+          # @since 0.1.0
+          def selected_libraries(library, libraries)
+            [library, *libraries].compact.reject(&:empty?).map(&:downcase).uniq
+          end
+        end
+      end
+    end
+  end
+end

data/lib/hanami_icons/cli/commands/generate/initializer.rb

@@ -0,0 +1,171 @@
+# frozen_string_literal: true
+
+require "hanami/cli"
+
+module HanamiIcons
+  module CLI
+    module Commands
+      module Generate
+        # Creates the Hanami Icons provider file (`config/providers/icons.rb`),
+        # which Hanami auto-loads, and registers the view helpers in the app's
+        # helpers module (`app/views/helpers.rb`).
+        #
+        # @api public
+        # @since 0.1.0
+        class Initializer < Hanami::CLI::Command
+          desc "Create the Hanami Icons provider file"
+
+          option :library, desc: "Choose a library"
+          option :libraries, type: :array, default: [], desc: "Choose libraries"
+          option :variants, type: :array, desc: "Only sync specific variants (e.g. solid outline)"
+          option :destination, type: :string, default: HanamiIcons.configuration.icons_path, desc: "Specify destination folder for icons"
+
+          PROVIDER = "config/providers/icons.rb"
+          HELPERS = "app/views/helpers.rb"
+          TEMPLATE = File.expand_path("../../templates/provider.rb", __dir__)
+
+          # @param library [String, nil]
+          # @param libraries [Array<String>]
+          # @param variants [Array<String>, nil]
+          # @param destination [String]
+          #
+          # @api public
+          # @since 0.1.0
+          def call(library: nil, libraries: [], variants: nil, destination: HanamiIcons.configuration.icons_path, **)
+            copy_provider
+
+            insert_default_configuration(selected_libraries(library, libraries).first)
+            insert_icons_path(destination)
+            setup_custom_libraries(selected_libraries(library, libraries), destination)
+
+            register_helpers
+          end
+
+          private
+
+          # @api private
+          # @since 0.1.0
+          def copy_provider
+            return if fs.exist?(PROVIDER)
+
+            fs.mkdir(File.dirname(PROVIDER))
+            fs.write(PROVIDER, File.read(TEMPLATE))
+          end
+
+          # @api private
+          # @since 0.1.0
+          def insert_default_configuration(library)
+            return if library.nil? || default_configuration_exists?
+
+            insert_into_provider(
+              indent("config.default_library = \"#{library}\"\n", 2),
+              after: "HanamiIcons.configure do |config|\n"
+            )
+          end
+
+          # @api private
+          # @since 0.1.0
+          def insert_icons_path(destination)
+            return if destination == HanamiIcons.configuration.icons_path
+            return if icons_path_exists?
+
+            insert_into_provider(
+              indent("# Default icons path\nconfig.icons_path = \"#{destination}\"\n", 2),
+              after: "HanamiIcons.configure do |config|\n"
+            )
+          end
+
+          # @api private
+          # @since 0.1.0
+          def setup_custom_libraries(libraries, destination)
+            custom_libraries(libraries).each do |name|
+              fs.mkdir(File.join(destination, name))
+
+              insert_into_provider(
+                "\n#{indent("config.custom_library :#{name}", 2)}",
+                before: "end"
+              )
+            end
+          end
+
+          # @api private
+          # @since 0.1.0
+          def register_helpers
+            unless fs.exist?(HELPERS)
+              warn "[HanamiIcons] Could not find #{HELPERS}. Add `include HanamiIcons::Helpers::IconHelper` and `include HanamiIcons::Helpers::SpriteHelper` to your app's Views::Helpers module manually."
+
+              return
+            end
+
+            content = fs.read(HELPERS)
+
+            return if content.include?("include HanamiIcons::Helpers::IconHelper")
+
+            line = content.lines.find { it.match?(/^\s*module\s+Helpers\b/) }
+
+            unless line
+              warn "[HanamiIcons] Could not find a `module Helpers` in #{HELPERS}. Add the helper includes manually."
+
+              return
+            end
+
+            indentation = line[/^\s*/]
+            includes = "\n#{indentation}  include HanamiIcons::Helpers::IconHelper\n#{indentation}  include HanamiIcons::Helpers::SpriteHelper"
+
+            fs.write(HELPERS, content.sub(/^(\s*module\s+Helpers\b.*)$/, "\\1#{includes}"))
+          end
+
+          # @api private
+          # @since 0.1.0
+          def insert_into_provider(content, after: nil, before: nil)
+            text = fs.read(PROVIDER)
+
+            if after
+              text = text.sub(after, "#{after}#{content}")
+            elsif before
+              text = text.sub(before, "#{content}\n#{before}")
+            end
+
+            fs.write(PROVIDER, text)
+          end
+
+          # @api private
+          # @since 0.1.0
+          def default_configuration_exists?
+            line = /^\s*config\.default_library\s*=/
+
+            fs.read(PROVIDER).lines.any? { it.match?(line) }
+          end
+
+          # @api private
+          # @since 0.1.0
+          def icons_path_exists?
+            line = /^\s*config\.icons_path\s*=/
+
+            fs.read(PROVIDER).lines.any? { it.match?(line) }
+          end
+
+          # @api private
+          # @since 0.1.0
+          def custom_libraries(libraries)
+            libraries.reject { HanamiIcons.libraries.key?(it.to_sym) }
+          end
+
+          # @api private
+          # @since 0.1.0
+          def selected_libraries(library, libraries)
+            [library, *libraries].compact.reject(&:empty?).map(&:downcase).uniq
+          end
+
+          # @api private
+          # @since 0.1.0
+          def indent(text, spaces)
+            prefix = " " * spaces
+
+            text.lines.map { "#{prefix}#{it}" }.join
+          end
+        end
+      end
+    end
+  end
+end

data/lib/hanami_icons/cli/commands/generate/sprite.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+require "hanami/cli"
+
+module HanamiIcons
+  module CLI
+    module Commands
+      module Generate
+        # Writes a static SVG sprite file for use with `sprite_icon`.
+        #
+        # @api public
+        # @since 0.1.0
+        class Sprite < Hanami::CLI::Command
+          desc "Generate a static SVG sprite file"
+
+          option :output, type: :string, default: "public/sprite.svg", desc: "Where to write the sprite file"
+
+          # @param output [String]
+          #
+          # @api public
+          # @since 0.1.0
+          def call(output: "public/sprite.svg", **)
+            fs.mkdir(File.dirname(output))
+            fs.write(output, ::Icons::Sprite.new.svg)
+
+            location = "/#{File.basename(output)}"
+
+            out.puts "Sprite written to #{output}"
+            out.puts "Set config.default_sprite_location = \"#{location}\" in config/providers/icons.rb to use it."
+          end
+        end
+      end
+    end
+  end
+end

data/lib/hanami_icons/cli/commands/generate/sync.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+require "hanami/cli"
+
+module HanamiIcons
+  module CLI
+    module Commands
+      module Generate
+        # Syncs the chosen icon libraries from their respective git repositories.
+        #
+        # @api public
+        # @since 0.1.0
+        class Sync < Hanami::CLI::Command
+          desc "Sync the chosen icon libraries from their respective git repos"
+
+          option :library, desc: "Choose a library"
+          option :libraries, type: :array, default: [], desc: "Choose libraries"
+          option :variants, type: :array, desc: "Only sync specific variants (e.g. solid outline)"
+
+          # @param library [String, nil]
+          # @param libraries [Array<String>]
+          # @param variants [Array<String>, nil]
+          #
+          # @api public
+          # @since 0.1.0
+          def call(library: nil, libraries: [], variants: nil, **)
+            selected_libraries(library, libraries).each do |name|
+              ::Icons::Sync.new(name, variants: variants&.map(&:to_sym)).now
+            end
+          end
+
+          private
+
+          # @api private
+          # @since 0.1.0
+          def selected_libraries(library, libraries)
+            [library, *libraries].compact.reject(&:empty?).map(&:downcase).uniq
+          end
+        end
+      end
+    end
+  end
+end

data/lib/hanami_icons/cli/templates/provider.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require "hanami_icons"
+
+HanamiIcons.configure do |config|
+end
+
+Hanami.app.register_provider(:icons) do
+  start do
+    register "icons", HanamiIcons
+  end
+end

data/lib/hanami_icons/helpers/icon_helper.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+require "base64"
+
+module HanamiIcons
+  module Helpers
+    # View helpers for rendering inline SVG icons.
+    #
+    # @api public
+    # @since 0.1.0
+    module IconHelper
+      extend self
+
+      # Renders an SVG icon.
+      #
+      # @param name [String] The icon name
+      # @param library [String] The icon library (defaults to HanamiIcons configuration)
+      # @param from [String] Syntactic sugar for a cleanly readable view layer API
+      # @param variant [String] The icon variant (optional)
+      # @param arguments [Hash] Additional attributes including class, data, stroke_width, etc.
+      # @return [Hanami::View::HTML::SafeString] An HTML-safe SVG string
+      #
+      # @example
+      #   <%= icon "chevron-down" %>
+      #   <%= icon "search", class: "text-blue-500" %>
+      #
+      # @api public
+      # @since 0.1.0
+      def icon(name, library: HanamiIcons.configuration.default_library, from: library, variant: nil, **arguments)
+        Icons::Icon.new(
+          name: name,
+          library: from || library,
+          variant: variant,
+          arguments: arguments
+        ).svg.html_safe
+      end
+
+      # Returns a base64-encoded data URI for an icon.
+      #
+      # @param name [String] The icon name
+      # @param library [String] The icon library (defaults to HanamiIcons configuration)
+      # @param from [String] Syntactic sugar for a cleanly readable view layer API
+      # @param variant [String] The icon variant (optional)
+      # @param arguments [Hash] Additional attributes including class, data, stroke_width, etc.
+      # @return [String] A base64-encoded data URI (e.g. "data:image/svg+xml;base64,...")
+      #
+      # @example
+      #   <%= encoded_icon "chevron-down" %>
+      #
+      # @api public
+      # @since 0.1.0
+      def encoded_icon(name, library: HanamiIcons.configuration.default_library, from: library, variant: nil, **arguments)
+        svg = Icons::Icon.new(
+          name: name,
+          library: from || library,
+          variant: variant,
+          arguments: arguments
+        ).svg
+
+        "data:image/svg+xml;base64,#{Base64.strict_encode64(svg)}"
+      end
+    end
+  end
+end

data/lib/hanami_icons/helpers/sprite_helper.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+require "icons/sprite_icon"
+
+module HanamiIcons
+  module Helpers
+    # View helpers for rendering SVG icons from a sprite.
+    #
+    # @api public
+    # @since 0.1.0
+    module SpriteHelper
+      extend self
+
+      # Renders an SVG icon referencing a sprite symbol.
+      #
+      # @param name [String] The icon name
+      # @param library [String] The icon library (defaults to HanamiIcons configuration)
+      # @param from [String] Syntactic sugar for a cleanly readable view layer API
+      # @param variant [String] The icon variant (optional)
+      # @param sprite_location [String] Override URL for the sprite file (optional)
+      # @param arguments [Hash] Additional attributes including class, data, stroke_width, etc.
+      # @return [Hanami::View::HTML::SafeString] An HTML-safe SVG string
+      #
+      # @example
+      #   <%= sprite_icon "chevron-down" %>
+      #   <%= sprite_icon "check", sprite_location: "/sprite.svg" %>
+      #
+      # @api public
+      # @since 0.1.0
+      def sprite_icon(name, library: nil, from: library, variant: nil, sprite_location: nil, **arguments)
+        Icons::SpriteIcon.new(
+          name: name,
+          library: from || library || HanamiIcons.configuration.default_library,
+          variant: variant,
+          sprite_location: sprite_location,
+          arguments: arguments
+        ).svg.html_safe
+      end
+
+      # Returns the inline SVG sprite containing all symbols.
+      #
+      # @param icons [Array<String>, nil] Optional list of icon names (defaults to all configured icons)
+      # @param library [String, nil] Optional library to use for icons
+      # @param variant [String, nil] Optional variant to use for icons
+      # @return [Hanami::View::HTML::SafeString] An HTML-safe SVG string
+      #
+      # @example
+      #   <%= icons_sprite %>
+      #   <%= icons_sprite ["check", "search"], library: "lucide" %>
+      #
+      # @api public
+      # @since 0.1.0
+      def icons_sprite(icons = nil, library: nil, variant: nil)
+        Icons::Sprite.new(icons: icons, library: library, variant: variant).svg.html_safe
+      end
+    end
+  end
+end

data/lib/hanami_icons/version.rb

@@ -0,0 +1,3 @@
+module HanamiIcons
+  VERSION = "0.5.0"
+end

data/lib/hanami_icons.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+require "zeitwerk"
+require "icons"
+require "hanami/cli"
+
+module HanamiIcons
+  # @api private
+  # @since 0.1.0
+  def self.gem_loader
+    @gem_loader ||= Zeitwerk::Loader.new.tap do |loader|
+      root = __dir__
+
+      loader.tag = "hanami-icons"
+      loader.inflector = Zeitwerk::GemInflector.new("#{root}/hanami_icons.rb")
+      loader.inflector.inflect("cli" => "CLI")
+      loader.push_dir(root)
+
+      loader.ignore("#{root}/hanami_icons.rb", "#{root}/hanami_icons/version.rb")
+    end
+  end
+
+  gem_loader.setup
+
+  require_relative "hanami_icons/version"
+
+  class << self
+    # @yield [config] Yields the Icons configuration
+    # @yieldparam config [Icons::Configuration]
+    #
+    # @api public
+    # @since 0.1.0
+    def configure(&block) = Icons.configure(&block)
+
+    # @return [Icons::Configuration]
+    #
+    # @api public
+    # @since 0.1.0
+    def configuration = Icons.config
+
+    alias_method :config, :configuration
+
+    # @return [Hash{Symbol => Icons::Library}] The registered icon libraries
+    #
+    # @api public
+    # @since 0.1.0
+    def libraries = Icons.libraries
+  end
+
+  if Hanami::CLI.within_hanami_app?
+    Hanami::CLI.register "generate icons", CLI::Commands::Generate::Icons
+    Hanami::CLI.register "generate icons:initializer", CLI::Commands::Generate::Initializer
+    Hanami::CLI.register "generate icons:sync", CLI::Commands::Generate::Sync
+    Hanami::CLI.register "generate icons:sprite", CLI::Commands::Generate::Sprite
+  end
+end

metadata

@@ -0,0 +1,117 @@
+--- !ruby/object:Gem::Specification
+name: hanami_icons
+version: !ruby/object:Gem::Version
+  version: 0.5.0
+platform: ruby
+authors:
+- Rails Designer
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: base64
+  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: hanami-view
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: hanami-cli
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: icons
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.11.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.11.0
+description: Add any icon library to a Hanami app, from Heroicons, to Lucide to Tabler
+  (and others). Hanami Icons is library-agnostic, so you can add any library while
+  using the same interface.
+email:
+- devs@railsdesigner.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- Gemfile
+- README.md
+- Rakefile
+- hanami_icons.gemspec
+- lib/hanami_icons.rb
+- lib/hanami_icons/cli/commands/generate/icons.rb
+- lib/hanami_icons/cli/commands/generate/initializer.rb
+- lib/hanami_icons/cli/commands/generate/sprite.rb
+- lib/hanami_icons/cli/commands/generate/sync.rb
+- lib/hanami_icons/cli/templates/provider.rb
+- lib/hanami_icons/helpers/icon_helper.rb
+- lib/hanami_icons/helpers/sprite_helper.rb
+- lib/hanami_icons/version.rb
+homepage: https://railsdesigner.com/open-source/hanami-icons/
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://railsdesigner.com/open-source/hanami-icons/
+  source_code_uri: https://github.com/Rails-Designer/hanami_icons
+  changelog_uri: https://github.com/Rails-Designer/hanami_icons/releases
+  bug_tracker_uri: https://github.com/Rails-Designer/hanami_icons/issues
+  documentation_uri: https://railsdesigner.com/open-source/hanami-icons/
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.3'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.22
+specification_version: 4
+summary: Add any icon library to a Hanami app
+test_files: []