avo-icons 0.1.0 → 0.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 723efbbd2aa4adf88b418aa9af5de57601362e0c82a322fe8ceae38f3802193a
-  data.tar.gz: 44a1a68a09a166334db49677274941541f05b98b8b07bfbb19f84e13040010da
+  metadata.gz: afdb0b75a063a1d209c93ab86b8c399267abed0c700ccf8450c83ab7da19e879
+  data.tar.gz: 1009146281411a8c10d051621ab0f1d2370af19b99de63f2d5e25992b18acf35
 SHA512:
-  metadata.gz: e00481d3e9b8bc33204226925f874c229e3ca954e2254c46e5ac0306c973a45518fc8db0eb2ce1630a0a9b6d21e689163445a35f4b355fe7649b107dc989c32b
-  data.tar.gz: 310456a106e4b6d506538826bcf1d71c5c458f3b090f6dd089331db2c315ca76e90cc45d4d39716dd20aa1a8245c3cee1afa5713bd812e13162a7e31f1770ab3
+  metadata.gz: 2228b5b5656800c17028c90b7cf92170dd73d3433478491abb62ec2c783271790d6c9d31e8e0156e9d23555549c9412b07c377442a08437c6066edaf5f670697
+  data.tar.gz: 5419d618e7b911b18e5c4a56bef051b1d7bc55852ccbc0c1dd31f899c4e8056ddf3fd1ac5e638fe125126f33ce12c9968c7bbb9cfe386d7b2c588ff997345b55

data/README.md

@@ -1,45 +1,205 @@
-# Avo::Icons
+# Avo Icons
 
-`avo-icons` was built as a dependency for [Avo](https://avohq.io/), is a Ruby gem designed to seamlessly integrate [Heroicons](https://heroicons.com/) and [Tabler Icons](https://tabler.io/icons) SVGs into [Avo](https://avohq.io/).
+A lightweight, standalone gem for serving icon SVGs effortlessly in Rails applications. This gem provides access to Heroicons and Tabler Icons with smart caching and configurable search paths.
+
+## Features
+
+- **Multiple Icon Sets**: Includes Heroicons (outline, solid, mini, micro) and Tabler Icons (outline, filled)
+- **Smart Caching**: Intelligent caching strategy for optimal performance
+- **Configurable Paths**: Pluggable system to add custom SVG search paths
+- **Rails-Ready**: Seamlessly integrates with any Rails application
+- **Asset Pipeline Support**: Works with Sprockets and Propshaft
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'avo-icons'
+```
+
+And then execute:
+
+```bash
+bundle install
+```
 
 ## Usage
 
-### Heroicons
+### Basic Usage
+
+The `svg` helper is automatically available in all your views:
+
+```erb
+<%= svg "heroicons/outline/user" %>
+<%= svg "heroicons/solid/heart", class: "w-6 h-6" %>
+<%= svg "tabler/outline/home", class: "w-5 h-5 text-gray-500" %>
+```
 
-Prepend the `heroicons` namespace and then the variant `outline`, `solid`, `mini`, or `micro` and then the icon name.
+You can omit the `.svg` extension - it will be added automatically:
 
 ```erb
-<%= svg "heroicons/outline/academic-cap.svg" %>
+<%= svg "heroicons/outline/user" %>
+<!-- Same as: -->
+<%= svg "heroicons/outline/user.svg" %>
 ```
 
+### Available Icon Sets
+
+- **Heroicons**:
+  - `heroicons/outline/` - Outline style icons
+  - `heroicons/solid/` - Solid style icons
+  - `heroicons/mini/` - Mini size icons
+  - `heroicons/micro/` - Micro size icons
+
+- **Tabler Icons**:
+  - `tabler/outline/` - Outline style icons
+  - `tabler/filled/` - Filled style icons
+
+### Adding Custom SVG Paths
+
+You can configure additional paths to search for SVG files. Create an initializer:
+
 ```ruby
-# in the menu builder
-# config/initializers/avo.rb
-Avo.configure do |config|
-  config.main_menu = -> {
-    section "Store", icon: "heroicons/outline/academic-cap" do
-      resource Avo::Resources::Store
-    end
-  end
+# config/initializers/avo_icons.rb
+
+Avo::Icons.configure do |config|
+  # Add a static path
+  config.add_path(Rails.root.join("app", "assets", "images", "icons"))
+  
+  # Add a path from another gem or engine
+  config.add_path(MyEngine::Engine.root.join("app", "assets", "svgs"))
+  
+  # Add a dynamic path using a proc
+  config.add_path(->(filename) { 
+    Rails.root.join("vendor", "assets", "custom-icons", filename) 
+  })
 end
 ```
 
-### Tabler Icons
+### Search Order
+
+The gem searches for SVG files in the following order:
 
-Prepend the `tabler` namespace and then the variant `outline` or `filled` and then the icon name.
+1. Asset pipeline (Sprockets/Propshaft)
+2. `app/assets/svgs/` in your Rails app
+3. Rails root directory
+4. Heroicons in avo-icons gem
+5. Tabler Icons in avo-icons gem
+6. Custom paths (in order of configuration)
+7. All Rails asset paths (including engines)
+
+### Passing Options
+
+The `svg` helper accepts all options supported by the [inline_svg](https://github.com/jamesmartin/inline_svg) gem:
 
 ```erb
-<%= svg "tabler/outline/settings.svg" %>
+<%= svg "heroicons/outline/user", 
+        class: "w-6 h-6", 
+        aria: { hidden: true },
+        title: "User Profile" %>
 ```
 
+### Using in Controllers or Models
+
+If you need to use the svg helper outside of views, include the helper module:
+
 ```ruby
-# in the menu builder
-# config/initializers/avo.rb
-Avo.configure do |config|
-  config.main_menu = -> {
-    section "Settings", icon: "tabler/outline/settings" do
-      resource Avo::Resources::Setting
-    end
+class MyService
+  include Avo::Icons::Helpers
+  
+  def user_icon
+    svg("heroicons/outline/user", class: "w-6 h-6")
   end
 end
 ```
+
+## Configuration
+
+### Custom Configuration
+
+```ruby
+Avo::Icons.configure do |config|
+  # Add as many custom paths as needed
+  config.add_path("/path/to/your/svgs")
+  config.add_path(MyEngine::Engine.root.join("assets", "icons"))
+  
+  # Use procs for dynamic paths
+  config.add_path(->(filename) { 
+    # Custom logic to find SVGs
+    File.join("/custom/path", filename)
+  })
+end
+```
+
+### Resetting Configuration
+
+You can reset the configuration (useful in tests):
+
+```ruby
+Avo::Icons.reset_configuration!
+```
+
+### Managing the Cache
+
+The SVG cache is stored in `Avo::Icons.cached_svgs` and persists for the application lifecycle. You can manually clear or inspect it if needed:
+
+```ruby
+# Clear the cache manually (e.g., after adding new SVG files)
+Avo::Icons.cached_svgs = {}
+
+# Check if a file is cached
+Avo::Icons.cached_svgs["heroicons/outline/user.svg"]
+
+# In development, you can clear the cache in an initializer to_prepare block
+# if you want fresh lookups on each request:
+Rails.application.config.to_prepare do
+  Avo::Icons.cached_svgs = {}
+end
+```
+
+## Integration with Other Apps
+
+This gem is designed to work with any Rails application, not just Avo. Simply add it to your Gemfile and start using the `svg` helper in your views.
+
+### Example: Adding to a Rails App
+
+1. Add to Gemfile:
+```ruby
+gem 'avo-icons'
+```
+
+2. Bundle install:
+```bash
+bundle install
+```
+
+3. Use in views:
+```erb
+<%= svg "heroicons/outline/home", class: "w-5 h-5" %>
+```
+
+4. (Optional) Configure custom paths:
+```ruby
+# config/initializers/avo_icons.rb
+Avo::Icons.configure do |config|
+  config.add_path(Rails.root.join("app", "assets", "images", "custom-icons"))
+end
+```
+
+## Performance
+
+The gem uses smart caching to ensure SVG files are only located once per application lifecycle. This means:
+
+- **First Request**: File is located and cached
+- **Subsequent Requests**: Cached path is used (no file system lookup)
+- **Production**: Cache persists for optimal performance
+- **Development**: Cache persists by default. If you need fresh lookups (e.g., when adding new SVG files), manually clear the cache or configure a `to_prepare` hook
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub.
+
+## License
+
+See LICENSE.md

data/lib/avo/icons/configuration.rb

@@ -0,0 +1,24 @@
+module Avo
+  module Icons
+    class Configuration
+      attr_accessor :custom_paths
+
+      def initialize
+        @custom_paths = []
+      end
+
+      # Add a custom path to search for SVG files
+      # @param path [String, Pathname, Proc] A path or proc that returns a path
+      # @example
+      #   Avo::Icons.configure do |config|
+      #     config.add_path("/my/custom/svg/path")
+      #     config.add_path(Rails.root.join("vendor", "assets", "svgs"))
+      #     config.add_path(->(filename) { File.join("/dynamic/path", filename) })
+      #   end
+      def add_path(path)
+        @custom_paths << path
+      end
+    end
+  end
+end
+

data/lib/avo/icons/helpers.rb

@@ -0,0 +1,35 @@
+module Avo
+  module Icons
+    module Helpers
+      # Use inline_svg gem but with our own finder implementation.
+      # @param file_name [String] The name of the SVG file (with or without .svg extension)
+      # @param args [Hash] Additional arguments to pass to inline_svg
+      # @return [String] The inline SVG HTML
+      # @example
+      #   svg("heroicons/outline/user", class: "w-6 h-6")
+      #   svg("my-icon", class: "w-4 h-4", aria: { hidden: true })
+      def svg(file_name, **args)
+        return if file_name.blank?
+
+        file_name = "#{file_name}.svg" unless file_name.end_with? ".svg"
+
+        with_asset_finder(Avo::Icons::SvgFinder) do
+          inline_svg file_name, **args
+        end
+      end
+
+      private
+
+      # Taken from the original library
+      # https://github.com/jamesmartin/inline_svg/blob/main/lib/inline_svg/action_view/helpers.rb#L76
+      def with_asset_finder(asset_finder)
+        Thread.current[:inline_svg_asset_finder] = asset_finder
+        output = yield
+        Thread.current[:inline_svg_asset_finder] = nil
+
+        output
+      end
+    end
+  end
+end
+

data/lib/avo/icons/railtie.rb

@@ -1,6 +1,11 @@
 module Avo
   module Icons
     class Railtie < ::Rails::Railtie
+      initializer "avo-icons.helpers" do
+        ActiveSupport.on_load(:action_view) do
+          include Avo::Icons::Helpers
+        end
+      end
     end
   end
 end

data/lib/avo/icons/svg_finder.rb

@@ -0,0 +1,76 @@
+module Avo
+  module Icons
+    class SvgFinder
+      def self.find_asset(filename)
+        new(filename)
+      end
+
+      def initialize(filename)
+        @filename = filename
+      end
+
+      # Use the default static finder logic. If that doesn't find anything, search according to our pattern:
+      def pathname
+        Avo::Icons.cached_svgs[@filename] ||= begin
+          found_asset = default_strategy
+
+          # Use the found asset
+          if found_asset.present?
+            found_asset
+          else
+            paths.find do |path|
+              File.exist? path
+            end
+          end
+        end
+      end
+
+      def paths
+        base_paths = [
+          Rails.root.join("app", "assets", "svgs", @filename),
+          Rails.root.join(@filename),
+          Avo::Icons.root.join("assets", "svgs", @filename),
+          Avo::Icons.root.join("assets", "svgs", "heroicons", "outline", @filename),
+          Avo::Icons.root.join("assets", "svgs", "heroicons", "solid", @filename),
+          Avo::Icons.root.join("assets", "svgs", "heroicons", "mini", @filename),
+          Avo::Icons.root.join("assets", "svgs", "heroicons", "micro", @filename),
+          Avo::Icons.root.join("assets", "svgs", "tabler", "outline", @filename),
+          Avo::Icons.root.join("assets", "svgs", "tabler", "filled", @filename),
+          # Add all paths from Rails including engines
+          *Rails.application.config.assets&.paths&.map { |path| File.join(path, @filename) }
+        ]
+
+        # Add custom paths from configuration
+        custom_paths = Avo::Icons.configuration.custom_paths.map do |custom_path|
+          if custom_path.is_a?(Proc)
+            custom_path.call(@filename)
+          else
+            File.join(custom_path.to_s, @filename)
+          end
+        end
+
+        (base_paths + custom_paths).map(&:to_s).uniq
+      end
+
+      def default_strategy
+        # If the app uses Propshaft, grab it from there
+        if defined?(Propshaft)
+          asset_path = ::Rails.application.assets.load_path.find(@filename)
+          asset_path&.path
+        elsif ::Rails.application.config.assets.compile
+          # Grab the asset from the compiled asset manifest
+          asset = ::Rails.application.assets[@filename]
+          Pathname.new(asset.filename) if asset.present?
+        else
+          # Grab the asset from the manifest
+          manifest = ::Rails.application.assets_manifest
+          asset_path = manifest.assets[@filename]
+          unless asset_path.nil?
+            ::Rails.root.join(manifest.directory, asset_path)
+          end
+        end
+      end
+    end
+  end
+end
+

data/lib/avo/icons/version.rb

@@ -1,5 +1,5 @@
 module Avo
   module Icons
-    VERSION = "0.1.0"
+    VERSION = "0.1.1"
   end
 end

data/lib/avo/icons.rb

@@ -1,10 +1,34 @@
+require "inline_svg"
 require "avo/icons/version"
+require "avo/icons/configuration"
+require "avo/icons/svg_finder"
+require "avo/icons/helpers"
 require "avo/icons/railtie"
 
 module Avo
   module Icons
-    def self.root
-      Pathname.new File.expand_path('..', __dir__)
+    class << self
+      attr_writer :configuration
+      attr_accessor :cached_svgs
+
+      def root
+        Pathname.new File.expand_path('..', __dir__)
+      end
+
+      def configuration
+        @configuration ||= Configuration.new
+      end
+
+      def configure
+        yield(configuration)
+      end
+
+      def reset_configuration!
+        @configuration = Configuration.new
+      end
     end
+
+    # Initialize cache
+    self.cached_svgs = {}
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: avo-icons
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.1
 platform: ruby
 authors:
 - Paul Bob
@@ -9,8 +9,23 @@ authors:
 bindir: bin
 cert_chain: []
 date: 1980-01-02 00:00:00.000000000 Z
-dependencies: []
-description: A lightweight Avo dependency for serving icon SVGs effortlessly.
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: inline_svg
+  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'
+description: A standalone Rails gem that provides Heroicons and Tabler Icons with
+  smart caching and configurable search paths. Works with any Rails application.
 email:
 - avo@avohq.io
 executables: []
@@ -7518,7 +7533,10 @@ files:
 - lib/assets/svgs/tabler/outline/zzz-off.svg
 - lib/assets/svgs/tabler/outline/zzz.svg
 - lib/avo/icons.rb
+- lib/avo/icons/configuration.rb
+- lib/avo/icons/helpers.rb
 - lib/avo/icons/railtie.rb
+- lib/avo/icons/svg_finder.rb
 - lib/avo/icons/version.rb
 - lib/tasks/avo/icons_tasks.rake
 homepage: https://avohq.io
@@ -7541,5 +7559,5 @@ required_rubygems_version: !ruby/object:Gem::Requirement
 requirements: []
 rubygems_version: 3.7.1
 specification_version: 4
-summary: A lightweight Avo dependency for serving icon SVGs effortlessly.
+summary: A lightweight gem for serving icon SVGs effortlessly in Rails applications.
 test_files: []