heroicons-view-components 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 400e623f516a8099347f114c375b372e1bc37d32403014077e35882f036f3f91
+  data.tar.gz: 5ddcbf3ece3ad78e4efe7bf53150ae52612c789ea70f1b8c2ee5ed374fdcf609
+SHA512:
+  metadata.gz: d8086807c9324eb27555f41167e68997288a7d5a702e60907e2a42560d7e7104058fcb29f36ce64a497709f24494baf036c7e5839c63e0613291b6c11bbd6e2a
+  data.tar.gz: ed030dfbace1cbc6f21ba2ea188b809007d68b28fe79d5909603087e2f99d5ac3e22cffe90d91845dde069b4cd04fd9f018d56a74f4330cccb8d97b6deb22edd

data/.github/dependabot.yml

@@ -0,0 +1,12 @@
+# To get started with Dependabot version updates, you'll need to specify which
+# package ecosystems to update and where the package manifests are located.
+# Please see the documentation for all configuration options:
+# https://docs.github.com/github/administering-a-repository/configuration-options-for-dependency-updates
+
+version: 2
+updates:
+  - package-ecosystem: "bundler"
+    directory: "/"
+    versioning-strategy: increase
+    schedule:
+      interval: "weekly"

data/.github/workflows/gem-push.yml

@@ -0,0 +1,37 @@
+name: Ruby Gem
+
+on:
+  push:
+    branches: [ "main" ]
+    paths:
+      - lib/heroicons/view_component/version.rb # Only run when version changes
+  pull_request:
+    branches: [ "main" ]
+    paths:
+      - lib/heroicons/view_component/version.rb # Only run when version changes
+
+jobs:
+  build:
+    name: Build + Publish
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      packages: write
+
+    steps:
+    - uses: actions/checkout@v6
+    - name: Set up Ruby
+      uses: ruby/setup-ruby@v1
+      with:
+        ruby-version: 4.0.1
+
+    - name: Publish to RubyGems
+      run: |
+        mkdir -p $HOME/.gem
+        touch $HOME/.gem/credentials
+        chmod 0600 $HOME/.gem/credentials
+        printf -- "---\n:rubygems_api_key: ${GEM_HOST_API_KEY}\n" > $HOME/.gem/credentials
+        gem build *.gemspec
+        gem push *.gem
+      env:
+        GEM_HOST_API_KEY: "${{secrets.RUBYGEMS_AUTH_TOKEN}}"

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Kobus Post
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,264 @@
+# Heroicons::ViewComponent
+
+A Rails gem that provides ViewComponent components for [Heroicons](https://heroicons.com/), making it easy to use Heroicons SVG icons in your Rails applications.
+
+## Features
+
+- 🎨 **Two Variants**: Support for both outline and solid icon styles
+- 📏 **Multiple Sizes**: 16px, 20px, and 24px icon sizes
+- ⚡ **Performance**: Lazy-loading with intelligent caching for optimal performance
+- 🎯 **Type Safety**: Validates icon names, variants, and sizes
+- 🎨 **Customizable**: Merge custom CSS classes and HTML attributes
+- 🔒 **Thread-Safe**: Thread-safe caching implementation
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem "heroicons-view-components"
+```
+
+And then execute:
+
+```bash
+$ bundle install
+```
+
+Or install it yourself as:
+
+```bash
+$ gem install heroicons-view-components
+```
+
+## Prerequisites
+
+- Ruby >= 3.2.0
+- Rails (for ViewComponent)
+- ViewComponent >= 4.0
+
+## Usage
+
+### Basic Usage
+
+Render a Heroicon in your views or components:
+
+```erb
+<%= render Heroicons::ViewComponent::Icon.new(name: "academic-cap", variant: "outline") %>
+```
+
+### Variants
+
+Heroicons come in two variants:
+
+- `outline` - 24x24 icons with strokes (default)
+- `solid` - 20x20 icons with fills
+
+```erb
+<!-- Outline icon (default) -->
+<%= render Heroicons::ViewComponent::Icon.new(name: "home") %>
+
+<!-- Solid icon -->
+<%= render Heroicons::ViewComponent::Icon.new(name: "home", variant: "solid") %>
+```
+
+### Sizes
+
+You can specify a size for icons (16, 20, or 24):
+
+```erb
+<!-- Outline icon for 24px -->
+<%= render Heroicons::ViewComponent::Icon.new(name: "home", variant: "outline", size: "24") %>
+
+<!-- Solid icon for 20px -->
+<%= render Heroicons::ViewComponent::Icon.new(name: "home", variant: "solid", size: "20") %>
+```
+
+### Custom HTML Attributes
+
+Pass additional HTML attributes including CSS classes:
+
+```erb
+<!-- Single class -->
+<%= render Heroicons::ViewComponent::Icon.new(
+  name: "user",
+  variant: "outline",
+  class: "w-6 h-6 text-gray-500"
+) %>
+
+<!-- Multiple classes (array) -->
+<%= render Heroicons::ViewComponent::Icon.new(
+  name: "user",
+  variant: "solid",
+  class: ["w-8", "h-8", "text-gray-700"]
+) %>
+
+<!-- With data attributes -->
+<%= render Heroicons::ViewComponent::Icon.new(
+  name: "heart",
+  class: "w-5 h-5",
+  data: { controller: "icon", action: "click->favorite#toggle" }
+) %>
+
+<!-- With aria attributes -->
+<%= render Heroicons::ViewComponent::Icon.new(
+  name: "search",
+  class: "w-6 h-6",
+  id: "search-icon",
+  aria: { label: "Search" }
+) %>
+```
+
+### In ViewComponents
+
+You can use Heroicons in your own ViewComponents:
+
+```ruby
+class UserProfileComponent < ViewComponent::Base
+  def initialize(user:)
+    @user = user
+  end
+
+  private
+
+  attr_reader :user
+end
+```
+
+```erb
+<!-- user_profile_component.html.erb -->
+<div class="profile">
+  <%= render Heroicons::ViewComponent::Icon.new(
+    name: "user-circle",
+    variant: "solid",
+    class: "w-10 h-10 text-blue-500"
+  ) %>
+  <span><%= user.name %></span>
+</div>
+```
+
+### In Rails Helpers
+
+You can also use it in helpers:
+
+```ruby
+module ApplicationHelper
+  def icon(name, variant: "outline", **options)
+    render Heroicons::ViewComponent::Icon.new(
+      name: name,
+      variant: variant,
+      **options
+    )
+  end
+end
+```
+
+Then use it in your views:
+
+```erb
+<%= icon("home", variant: "solid", class: "w-6 h-6") %>
+```
+
+## Icon Names
+
+Icon names should match the Heroicons naming convention (kebab-case). For example:
+
+- `academic-cap`
+- `adjustments-horizontal`
+- `arrow-down`
+- `user-circle`
+- `arrow-down-circle`
+
+Browse all available icons at [heroicons.com](https://heroicons.com/).
+
+## API Reference
+
+### `Heroicons::ViewComponent::Icon.new(name:, variant: "outline", size: "24", **html_options)`
+
+Creates a new Icon component instance.
+
+#### Parameters
+
+- `name` (required): The icon name in kebab-case (e.g., `"arrow-down-circle"`)
+- `variant` (optional): Icon variant, either `"outline"` or `"solid"` (default: `"outline"`)
+- `size` (optional): Icon size, either `"16"`, `"20"`, or `"24"` (default: `"24"`)
+- `**html_options` (optional): Additional HTML attributes to merge into the SVG element
+
+#### Examples
+
+```ruby
+# Basic usage
+icon = Heroicons::ViewComponent::Icon.new(name: "home")
+
+# With custom classes
+icon = Heroicons::ViewComponent::Icon.new(
+  name: "user",
+  variant: "solid",
+  class: "w-6 h-6 text-blue-500"
+)
+
+# With multiple attributes
+icon = Heroicons::ViewComponent::Icon.new(
+  name: "search",
+  id: "search-icon",
+  class: "w-5 h-5",
+  data: { controller: "search" },
+  aria: { label: "Search" }
+)
+```
+
+## Performance
+
+The gem uses lazy-loading with intelligent caching:
+
+- Icons are loaded from disk only when first requested
+- Subsequent requests use cached SVG content
+- Thread-safe caching ensures safe concurrent access
+- Only icons that are actually used are cached in memory
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+### Running Tests
+
+```bash
+# Run all tests
+bundle exec rake test
+
+# Run tests directly
+ruby -Itest test/heroicons/view_component/icon_test.rb
+```
+
+### Code Quality
+
+```bash
+# Run RuboCop
+bundle exec rubocop
+```
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at [https://github.com/kpost/heroicons-view-components](https://github.com/kpost/heroicons-view-components).
+
+1. Fork the repository
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Make your changes
+4. Add tests for your changes
+5. Ensure all tests pass (`bundle exec rake test`)
+6. Ensure RuboCop passes (`bundle exec rubocop`)
+7. Commit your changes (`git commit -am 'Add some feature'`)
+8. Push to the branch (`git push origin my-new-feature`)
+9. Create a new Pull Request
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+
+## Credits
+
+- [Heroicons](https://heroicons.com/) - Beautiful hand-crafted SVG icons by the makers of Tailwind CSS
+- [ViewComponent](https://viewcomponent.org/) - A framework for building view components in Rails
+

data/Rakefile

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rubocop/rake_task"
+
+RuboCop::RakeTask.new
+
+require "rake/testtask"
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << "test"
+  t.libs << "lib"
+  t.test_files = FileList["test/**/*_test.rb"]
+end
+
+task default: :test

data/lib/heroicons/view/components.rb

@@ -0,0 +1 @@
+require_relative "../view_component"

data/lib/heroicons/view_component/icon.rb

@@ -0,0 +1,118 @@
+# frozen_string_literal: true
+
+require "view_component"
+require_relative "icon_cache"
+
+module Heroicons
+  module ViewComponent
+    class Icon < ::ViewComponent::Base
+      VARIANTS = ["outline", "solid"].freeze
+      SIZES = ["16", "20", "24"].freeze
+
+      def initialize(name:, variant: "outline", size: "24", **html_options)
+        super()
+        @name = name.to_s
+        @variant = variant.to_s
+        @size = size&.to_s
+        @html_options = html_options
+
+        validate_variant!
+        validate_size!
+      end
+
+      def call
+        svg_content.html_safe
+      end
+
+      private
+
+      attr_reader :name, :variant, :size, :html_options
+
+      def svg_content
+        @svg_content ||= begin
+          raw_svg = IconCache.get(size: size, variant: variant, name: name) || ""
+
+          if raw_svg.empty?
+            ""
+          else
+            merge_html_attributes(raw_svg)
+          end
+        end
+      end
+
+      def merge_html_attributes(svg_string)
+        # Fast path: no HTML options to merge
+        return svg_string if html_options.empty?
+
+        # Find the opening <svg> tag
+        svg_tag_match = svg_string.match(/<svg([^>]*)>/)
+        return svg_string unless svg_tag_match
+
+        existing_attrs = svg_tag_match[1]
+        new_attrs = []
+
+        # Handle class attribute - merge with existing classes
+        if html_options[:class]
+          class_match = existing_attrs.match(/class=["']([^"']*)["']/)
+          existing_classes = class_match ? class_match[1].strip : ""
+          new_classes = normalize_class(html_options[:class])
+
+          # Remove existing class attribute from string
+          existing_attrs = existing_attrs.gsub(/class=["'][^"']*["']/, "").strip
+
+          # Combine classes
+          combined_classes = [existing_classes, new_classes].reject(&:empty?).join(" ")
+          new_attrs << %(class="#{combined_classes}") unless combined_classes.empty?
+        end
+
+        # Add other HTML attributes
+        html_options.except(:class).each do |key, value|
+          attr_name = key.to_s.tr("_", "-")
+
+          if value.is_a?(Hash)
+            # Handle nested attributes like data: { controller: "icon" }
+            value.each do |nested_key, nested_value|
+              nested_attr = nested_key.to_s.tr("_", "-")
+              new_attrs << %(#{attr_name}-#{nested_attr}="#{escape_html(nested_value)}")
+            end
+          else
+            new_attrs << %(#{attr_name}="#{escape_html(value)}")
+          end
+        end
+
+        # Reconstruct SVG tag
+        all_attrs = [existing_attrs, *new_attrs].reject(&:empty?).join(" ")
+        new_svg_tag = "<svg #{all_attrs}>"
+
+        svg_string.sub(/<svg[^>]*>/, new_svg_tag)
+      end
+
+      def normalize_class(class_value)
+        case class_value
+        when Array
+          class_value.join(" ")
+        when String
+          class_value
+        else
+          class_value.to_s
+        end
+      end
+
+      def escape_html(value)
+        value.to_s.gsub('"', "&quot;").gsub("'", "&#39;")
+      end
+
+      def validate_variant!
+        return if VARIANTS.include?(@variant)
+
+        raise ArgumentError, "Invalid variant: #{@variant}. Must be one of: #{VARIANTS.join(", ")}"
+      end
+
+      def validate_size!
+        return if @size.nil? || SIZES.include?(@size)
+
+        raise ArgumentError, "Invalid size: #{@size}. Must be one of: #{SIZES.join(", ")}"
+      end
+    end
+  end
+end

data/lib/heroicons/view_component/icon_cache.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module Heroicons
+  module ViewComponent
+    class IconCache
+      @cache = {}
+      @mutex = Mutex.new
+
+      class << self
+        def get(size:, variant:, name:)
+          key = cache_key(size: size, variant: variant, name: name)
+
+          # Check cache first (fast path)
+          cached = @mutex.synchronize { @cache[key] }
+          return cached if cached
+
+          # Load from file and cache (slow path)
+          @mutex.synchronize do
+            # Double-check after acquiring lock (in case another thread loaded it)
+            return @cache[key] if @cache[key]
+
+            svg_content = load_from_file(size: size, variant: variant, name: name)
+            @cache[key] = svg_content.freeze if svg_content
+            svg_content
+          end
+        end
+
+        def clear
+          @mutex.synchronize { @cache.clear }
+        end
+
+        def cache_size
+          @mutex.synchronize { @cache.size }
+        end
+
+        private
+
+        def cache_key(size:, variant:, name:)
+          "#{size}/#{variant}/#{name}"
+        end
+
+        def load_from_file(size:, variant:, name:)
+          path = svg_path(size: size, variant: variant, name: name)
+          return unless File.exist?(path)
+
+          content = File.read(path)
+          # Remove XML declaration and clean up whitespace
+          content.gsub(/<\?xml[^>]*\?>/, "").strip
+        end
+
+        def svg_path(size:, variant:, name:)
+          File.join(__dir__, "..", "..", "..", "vendor", "heroicons", size.to_s, variant, "#{name}.svg")
+        end
+      end
+    end
+  end
+end

data/lib/heroicons/view_component/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Heroicons
+  module ViewComponent
+    VERSION = "0.1.0"
+  end
+end

data/lib/heroicons/view_component.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+require_relative "view_component/version"
+require_relative "view_component/icon_cache"
+require_relative "view_component/icon"
+
+module Heroicons
+  module ViewComponent
+    class Error < StandardError; end
+  end
+end