kiso-icons 0.1.0.pre

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 6f91c4c7b067ad325b199468604b89aead98ba16f3c99469aff5e2ef836d4878
+  data.tar.gz: d9f4b770b5081f8bbd463591710dadb8b9e198b4526bb226d60563f065b92c1e
+SHA512:
+  metadata.gz: 2db2872c247bc11a982224eff8feb89ddc63b2ba51b96aba1783e5c9fab9dadf73b336554fb0caa13b26014028e64d0be5ad5db0656382c472650a179ba1fdd2
+  data.tar.gz: 9633012b948ac6fb942ef2b51408dc4c1cd64f82daf61d4c3cadb4d1957bd43d377afab5cdc9f376ba38f8a307bf39608ef3d97d13bb7c4dba7e9cd0642b4194

data/CHANGELOG.md

@@ -0,0 +1,26 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0.pre] - 2026-02-25
+
+### Added
+
+- Inline SVG rendering via `kiso_icon_tag` helper
+- CLI (`bin/kiso-icons`) for pinning, unpinning, and listing icon sets
+- Support for all 224 Iconify icon sets (299k+ icons)
+- Vendored Lucide icon set as zero-config default (81KB gzipped)
+- Resolution cascade: vendored JSON → bundled Lucide → Iconify API fallback
+- Thread-safe in-memory icon cache
+- Alias resolution with rotation/flip transforms (up to 5 levels)
+- Iconify API fallback in development with prompt to pin
+- Rails generator (`kiso_icons:install`) for project setup
+- `pristine` command to re-download all pinned sets
+
+[Unreleased]: https://github.com/steveclarke/kiso-icons/compare/v0.1.0.pre...HEAD
+[0.1.0.pre]: https://github.com/steveclarke/kiso-icons/releases/tag/v0.1.0.pre

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) Stephen Clarke
+
+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,134 @@
+# Kiso Icons 基礎
+
+Iconify icons for Rails. Use any of [224 icon sets](https://icon-sets.iconify.design/) (299k+ icons) as inline SVG. No JavaScript needed.
+
+Icons live in `vendor/icons/` as JSON files. Commit them to git, just like vendored JavaScript with importmap-rails.
+
+Part of the [Kiso 基礎](https://github.com/steveclarke/kiso) family. Works on its own in any Rails 8+ app.
+
+## Installation
+
+```bash
+./bin/bundle add kiso-icons
+./bin/rails kiso_icons:install
+```
+
+This creates `vendor/icons/` and a `bin/kiso-icons` binstub.
+
+## Quick start
+
+[Lucide](https://lucide.dev) ships with the gem. Use it right away:
+
+```erb
+<%= kiso_icon_tag("check") %>
+<%= kiso_icon_tag("arrow-right") %>
+```
+
+Want a different icon set? Pin it:
+
+```bash
+./bin/kiso-icons pin heroicons
+```
+
+Then use it with the set name as a prefix:
+
+```erb
+<%= kiso_icon_tag("heroicons:home") %>
+```
+
+Browse all sets at [icon-sets.iconify.design](https://icon-sets.iconify.design/).
+
+## Usage
+
+```erb
+<%= kiso_icon_tag("lucide:check") %>
+<%= kiso_icon_tag("check") %>                          <%# uses the default set (lucide) %>
+<%= kiso_icon_tag("check", class: "w-5 h-5") %>       <%# add CSS classes %>
+<%= kiso_icon_tag("check", aria: { label: "Done" }) %> <%# screen reader label %>
+```
+
+You can pass any HTML attribute. If you add `aria: { label: "..." }`, screen readers will see the icon and `aria-hidden` is removed.
+
+### Pin icon sets
+
+The `pin` command downloads an Iconify JSON file to `vendor/icons/`. Commit it to git. In production, icons load from these files with no API calls.
+
+```bash
+./bin/kiso-icons pin lucide             # pin Lucide (replaces the bundled copy)
+./bin/kiso-icons pin heroicons mdi      # pin more than one set at once
+./bin/kiso-icons unpin heroicons        # remove a set
+./bin/kiso-icons pristine               # re-download all pinned sets
+./bin/kiso-icons list                   # show what's pinned
+```
+
+## Configuration
+
+Add an initializer to change the defaults:
+
+```ruby
+# config/initializers/kiso_icons.rb
+Kiso::Icons.configure do |config|
+  config.default_set = "lucide"        # icon set used when no prefix is given
+  config.vendor_path = "vendor/icons"  # where pinned JSON files are stored
+  config.fallback_to_api = false       # fetch missing icons from the Iconify API
+end
+```
+
+| Option | Default | What it does |
+|--------|---------|-------------|
+| `default_set` | `"lucide"` | Icon set used when you write `kiso_icon_tag("check")` with no prefix. |
+| `vendor_path` | `"vendor/icons"` | Where pinned JSON files are stored. |
+| `fallback_to_api` | `true` in dev, `false` in prod | If `true`, missing icons are fetched from the Iconify API. A log message tells you to pin the set. |
+
+> [!TIP]
+> In production, `fallback_to_api` is off. Pin all the sets you need so icons load from local files.
+
+## How it works
+
+Icons are found in this order:
+
+1. **Pinned JSON** — your sets in `vendor/icons/`
+2. **Bundled Lucide** — ships with the gem (81 KB gzipped), works with no setup
+3. **Iconify API** — only in dev mode, with a prompt to pin
+
+Each SVG uses `width="1em"`, `height="1em"`, and `currentColor`. It inherits its size from `font-size` and its color from the parent element. No CSS framework needed.
+
+## Development
+
+```bash
+git clone https://github.com/steveclarke/kiso-icons.git
+cd kiso-icons
+bin/setup    # install deps + pin demo icon sets
+bin/dev      # start demo app at http://localhost:3100
+```
+
+`bin/dev` starts a Rails app that shows icons from 10 sets. You can change the port: `bin/dev 4200`.
+
+Run tests:
+
+```bash
+bundle exec rake test            # unit tests (no Rails)
+bundle exec rake test_integration # integration tests (boots Rails)
+bundle exec rake                  # both
+```
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) to help out.
+
+## Project layout
+
+```
+bin/           dev scripts and CLI binstub
+data/          bundled Lucide icon set (gzipped JSON)
+lib/           gem source code
+test/          unit and integration tests
+test/dummy/    Rails app used for integration tests and the demo
+```
+
+## Requirements
+
+- Ruby >= 3.2
+- Rails >= 8.0
+
+## License
+
+MIT License. See [MIT-LICENSE](MIT-LICENSE).

data/Rakefile

@@ -0,0 +1,19 @@
+# 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
+
+Rake::TestTask.new(:test_integration) do |t|
+  t.libs << "test"
+  t.libs << "lib"
+  t.test_files = FileList["test/integration/**/*_test.rb"]
+end
+
+task test_all: [:test, :test_integration]
+task default: :test_all

data/lib/install/bin/kiso-icons

@@ -0,0 +1,6 @@
+#!/usr/bin/env ruby
+
+require_relative "../config/application"
+require "kiso/icons/commands"
+
+Kiso::Icons::Commands.start(ARGV)

data/lib/install/install.rb

@@ -0,0 +1,7 @@
+say "Use vendor/icons for pinned icon sets"
+empty_directory "vendor/icons"
+keep_file "vendor/icons"
+
+say "Copying binstub"
+copy_file "#{__dir__}/bin/kiso-icons", "bin/kiso-icons"
+chmod "bin", 0o755 & ~File.umask, verbose: false

data/lib/kiso/icons/api_client.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "uri"
+require "json"
+
+module Kiso
+  module Icons
+    class ApiClient
+      API_BASE = "https://api.iconify.design"
+      TIMEOUT = 5
+
+      class << self
+        def fetch_icon(set_prefix, icon_name)
+          start_time = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+
+          uri = URI("#{API_BASE}/#{set_prefix}/#{icon_name}.json")
+          response = make_request(uri)
+          return nil unless response
+
+          data = JSON.parse(response.body)
+          return nil unless data["body"]
+
+          elapsed_ms = ((Process.clock_gettime(Process::CLOCK_MONOTONIC) - start_time) * 1000).round
+
+          warn_to_pin(set_prefix, icon_name, elapsed_ms)
+
+          {
+            body: data["body"],
+            width: data["width"] || 24,
+            height: data["height"] || 24
+          }
+        rescue JSON::ParserError => e
+          warn "[Kiso::Icons] Failed to parse API response for #{set_prefix}:#{icon_name}: #{e.message}"
+          nil
+        end
+
+        private
+
+        def make_request(uri)
+          http = Net::HTTP.new(uri.host, uri.port)
+          http.use_ssl = true
+          http.open_timeout = TIMEOUT
+          http.read_timeout = TIMEOUT
+
+          request = Net::HTTP::Get.new(uri)
+          request["Accept"] = "application/json"
+
+          response = http.request(request)
+
+          case response
+          when Net::HTTPSuccess then response
+          when Net::HTTPNotFound then nil
+          else
+            warn "[Kiso::Icons] API returned #{response.code} for #{uri}"
+            nil
+          end
+        rescue Net::OpenTimeout, Net::ReadTimeout
+          warn "[Kiso::Icons] API timeout for #{uri} (#{TIMEOUT}s)"
+          nil
+        rescue SocketError, Errno::ECONNREFUSED => e
+          warn "[Kiso::Icons] Network error: #{e.message}"
+          nil
+        end
+
+        def warn_to_pin(set_prefix, icon_name, elapsed_ms)
+          message = "[Kiso::Icons] Fetched #{set_prefix}:#{icon_name} from Iconify API (#{elapsed_ms}ms).\n" \
+            "  Pin this set for offline use: bin/kiso-icons pin #{set_prefix}"
+
+          if defined?(Rails) && defined?(Rails.logger)
+            Rails.logger.debug { message }
+          else
+            warn message
+          end
+        end
+      end
+    end
+  end
+end

data/lib/kiso/icons/cache.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Kiso
+  module Icons
+    class Cache
+      def initialize
+        @store = {}
+        @mutex = Mutex.new
+      end
+
+      def get(set_prefix, name)
+        @mutex.synchronize { @store["#{set_prefix}:#{name}"] }
+      end
+
+      def set(set_prefix, name, data)
+        @mutex.synchronize { @store["#{set_prefix}:#{name}"] = data.freeze }
+      end
+
+      def clear!
+        @mutex.synchronize { @store.clear }
+      end
+
+      def size
+        @mutex.synchronize { @store.size }
+      end
+    end
+  end
+end

data/lib/kiso/icons/commands.rb

@@ -0,0 +1,149 @@
+# frozen_string_literal: true
+
+require "thor"
+require "kiso/icons"
+
+class Kiso::Icons::Commands < Thor
+  include Thor::Actions
+
+  SETS_URL = "https://raw.githubusercontent.com/iconify/icon-sets/master/json"
+
+  def self.exit_on_failure? = false
+
+  desc "pin SETS...", "Download icon sets to vendor/icons/"
+  long_desc <<~DESC
+    Downloads Iconify JSON files for the specified icon sets to vendor/icons/.
+    Commit these files to git for production use (like importmap-rails vendor pattern).
+
+    Example:
+      $ bin/kiso-icons pin lucide
+      $ bin/kiso-icons pin heroicons mdi tabler
+  DESC
+  def pin(*sets)
+    if sets.empty?
+      say "Usage: bin/kiso-icons pin SET [SET...]", :red
+      say ""
+      say "Example: bin/kiso-icons pin lucide heroicons"
+      say "Browse sets: https://icon-sets.iconify.design/"
+      exit 1
+    end
+
+    vendor_dir = vendor_path
+    FileUtils.mkdir_p(vendor_dir)
+
+    sets.each { |set_name| pin_set(set_name, vendor_dir) }
+  end
+
+  desc "unpin SET", "Remove a vendored icon set"
+  def unpin(set_name)
+    path = File.join(vendor_path, "#{set_name}.json")
+
+    unless File.exist?(path)
+      say "  not found  #{set_name} is not pinned", :red
+      return
+    end
+
+    File.delete(path)
+    say "  remove  vendor/icons/#{set_name}.json", :green
+  end
+
+  desc "pristine", "Re-download all pinned icon sets"
+  def pristine
+    sets = vendored_sets
+    if sets.empty?
+      say "No icon sets pinned. Pin one with: bin/kiso-icons pin lucide", :yellow
+      return
+    end
+
+    vendor_dir = vendor_path
+    say "Re-downloading #{sets.size} pinned set(s)..."
+    sets.each { |set_name| pin_set(set_name, vendor_dir, overwrite: true) }
+  end
+
+  desc "list", "Show pinned icon sets"
+  def list
+    sets = vendored_sets
+    if sets.empty?
+      say "No icon sets pinned.", :yellow
+      say ""
+      say "Pin a set:  bin/kiso-icons pin lucide"
+      return
+    end
+
+    say "Pinned icon sets (vendor/icons/):", :cyan
+    say ""
+
+    sets.each do |set_name|
+      path = File.join(vendor_path, "#{set_name}.json")
+      size_kb = (File.size(path) / 1024.0).round(1)
+      data = JSON.parse(File.read(path))
+      icon_count = (data["icons"] || {}).size
+      display_name = data.dig("info", "name") || set_name
+
+      say "  #{set_name.ljust(20)} #{icon_count.to_s.rjust(6)} icons  #{size_kb.to_s.rjust(8)} KB  (#{display_name})"
+    end
+  end
+
+  private
+
+  def pin_set(set_name, vendor_dir, overwrite: false)
+    dest = File.join(vendor_dir, "#{set_name}.json")
+
+    if File.exist?(dest) && !overwrite
+      say "  exists  vendor/icons/#{set_name}.json (use `pristine` to re-download)", :yellow
+      return
+    end
+
+    url = "#{SETS_URL}/#{set_name}.json"
+    say "  fetch   #{url}"
+
+    body = download(url)
+    if body.nil?
+      say "  error   Could not download #{set_name}. Check the set name.", :red
+      say "          Browse sets: https://icon-sets.iconify.design/"
+      return
+    end
+
+    body = body.force_encoding("UTF-8")
+
+    data = JSON.parse(body)
+    unless data["icons"]
+      say "  error   #{set_name}.json has no 'icons' key -- invalid Iconify format", :red
+      return
+    end
+
+    File.write(dest, body)
+    icon_count = data["icons"].size
+    size_kb = (body.bytesize / 1024.0).round(1)
+    say "  pin     vendor/icons/#{set_name}.json (#{icon_count} icons, #{size_kb} KB)", :green
+  end
+
+  def download(url, redirect_limit = 5)
+    raise "Too many redirects" if redirect_limit == 0
+
+    uri = URI(url)
+    response = Net::HTTP.get_response(uri)
+    case response
+    when Net::HTTPSuccess then response.body
+    when Net::HTTPRedirection then download(response["location"], redirect_limit - 1)
+    end
+  rescue SocketError, Net::OpenTimeout, Net::ReadTimeout, Errno::ECONNREFUSED => e
+    say "  error   Network error: #{e.message}", :red
+    nil
+  end
+
+  def vendor_path
+    base = if defined?(Rails) && Rails.root
+      Rails.root.to_s
+    else
+      Dir.pwd
+    end
+    File.join(base, Kiso::Icons.configuration.vendor_path)
+  end
+
+  def vendored_sets
+    Dir.glob(File.join(vendor_path, "*.json"))
+      .map { |f| File.basename(f, ".json") }
+      .sort
+  end
+end

data/lib/kiso/icons/configuration.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Kiso
+  module Icons
+    class Configuration
+      attr_accessor :default_set, :vendor_path, :fallback_to_api
+
+      def initialize
+        @default_set = "lucide"
+        @vendor_path = "vendor/icons"
+        @fallback_to_api = defined?(Rails) ? Rails.env.development? : false
+      end
+    end
+  end
+end

data/lib/kiso/icons/helper.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+require "erb"
+
+module Kiso
+  module Icons
+    module Helper
+      # Renders an inline SVG icon from Iconify icon sets.
+      #
+      #   kiso_icon_tag("lucide:check")
+      #   kiso_icon_tag("check")                          # uses default set (lucide)
+      #   kiso_icon_tag("check", class: "w-5 h-5")       # pass any CSS classes
+      #   kiso_icon_tag("check", aria: { label: "Done" }) # accessible icon
+      #
+      def kiso_icon_tag(name, **options)
+        icon_data = Kiso::Icons.resolve(name.to_s)
+
+        unless icon_data
+          if defined?(Rails) && Rails.env.development?
+            return safe_string("<!-- kiso-icons: '#{ERB::Util.html_escape(name)}' not found -->")
+          end
+          return safe_string("")
+        end
+
+        Kiso::Icons::Renderer.render(icon_data, css_class: options.delete(:class), **options)
+      end
+
+      private
+
+      def safe_string(str)
+        if defined?(ActiveSupport::SafeBuffer)
+          ActiveSupport::SafeBuffer.new(str)
+        else
+          str
+        end
+      end
+    end
+  end
+end

data/lib/kiso/icons/railtie.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+require "kiso/icons/helper"
+
+module Kiso
+  module Icons
+    class Railtie < ::Rails::Railtie
+      initializer "kiso_icons.configure" do |_app|
+        Kiso::Icons.configure do |config|
+          config.fallback_to_api = Rails.env.development? || Rails.env.test?
+        end
+      end
+
+      initializer "kiso_icons.helpers" do
+        ActiveSupport.on_load(:action_view) do
+          include Kiso::Icons::Helper
+        end
+      end
+
+      rake_tasks do
+        load "tasks/kiso_icons_tasks.rake"
+      end
+    end
+  end
+end

data/lib/kiso/icons/renderer.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module Kiso
+  module Icons
+    class Renderer
+      class << self
+        def render(icon_data, css_class: nil, **options)
+          body = icon_data[:body]
+          width = icon_data[:width]
+          height = icon_data[:height]
+
+          attrs = {
+            "xmlns" => "http://www.w3.org/2000/svg",
+            "viewBox" => "0 0 #{width} #{height}",
+            "width" => "1em",
+            "height" => "1em",
+            "aria-hidden" => "true",
+            "fill" => "none"
+          }
+
+          attrs["class"] = css_class if css_class && !css_class.empty?
+
+          options.each do |key, value|
+            if key == :data && value.is_a?(Hash)
+              value.each { |k, v| attrs["data-#{k.to_s.tr("_", "-")}"] = v.to_s }
+            elsif key == :aria && value.is_a?(Hash)
+              value.each { |k, v| attrs["aria-#{k.to_s.tr("_", "-")}"] = v.to_s }
+            else
+              attrs[key.to_s.tr("_", "-")] = value.to_s
+            end
+          end
+
+          if attrs.key?("aria-label")
+            attrs.delete("aria-hidden")
+            attrs["role"] = "img"
+          end
+
+          attr_str = attrs.map { |k, v| %(#{k}="#{escape_attr(v)}") }.join(" ")
+          svg = %(<svg #{attr_str}>#{body}</svg>)
+
+          if defined?(ActiveSupport::SafeBuffer)
+            ActiveSupport::SafeBuffer.new(svg)
+          else
+            svg
+          end
+        end
+
+        private
+
+        def escape_attr(value)
+          value.to_s
+            .gsub("&", "&amp;")
+            .gsub('"', "&quot;")
+            .gsub("<", "&lt;")
+            .gsub(">", "&gt;")
+        end
+      end
+    end
+  end
+end

data/lib/kiso/icons/resolver.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+module Kiso
+  module Icons
+    class Resolver
+      def initialize
+        @loaded_sets = {}
+        @mutex = Mutex.new
+      end
+
+      def resolve(name)
+        set_prefix, icon_name = parse_name(name)
+
+        # 1. In-memory cache
+        cached = Kiso::Icons.cache.get(set_prefix, icon_name)
+        return cached if cached
+
+        # 2. Already-loaded set
+        icon_data = resolve_from_loaded_set(set_prefix, icon_name)
+
+        # 3. Vendored JSON
+        icon_data ||= resolve_from_vendor(set_prefix, icon_name)
+
+        # 4. Bundled (lucide ships in gem)
+        icon_data ||= resolve_from_bundled(set_prefix, icon_name)
+
+        # 5. API fallback (dev only)
+        icon_data ||= resolve_from_api(set_prefix, icon_name)
+
+        Kiso::Icons.cache.set(set_prefix, icon_name, icon_data) if icon_data
+
+        icon_data
+      end
+
+      def clear!
+        @mutex.synchronize { @loaded_sets.clear }
+      end
+
+      private
+
+      def parse_name(name)
+        name = name.to_s.strip
+        if name.include?(":")
+          name.split(":", 2)
+        else
+          [Kiso::Icons.configuration.default_set, name]
+        end
+      end
+
+      def resolve_from_loaded_set(set_prefix, icon_name)
+        set = @mutex.synchronize { @loaded_sets[set_prefix] }
+        set&.icon(icon_name)
+      end
+
+      def resolve_from_vendor(set_prefix, icon_name)
+        set = Set.from_vendor(set_prefix)
+        return nil unless set
+
+        @mutex.synchronize { @loaded_sets[set_prefix] = set }
+        set.icon(icon_name)
+      end
+
+      def resolve_from_bundled(set_prefix, icon_name)
+        set = Set.from_bundled(set_prefix)
+        return nil unless set
+
+        @mutex.synchronize { @loaded_sets[set_prefix] = set }
+        set.icon(icon_name)
+      end
+
+      def resolve_from_api(set_prefix, icon_name)
+        return nil unless Kiso::Icons.configuration.fallback_to_api
+
+        ApiClient.fetch_icon(set_prefix, icon_name)
+      end
+    end
+  end
+end

data/lib/kiso/icons/set.rb

@@ -0,0 +1,148 @@
+# frozen_string_literal: true
+
+require "json"
+require "zlib"
+require "stringio"
+require "pathname"
+
+module Kiso
+  module Icons
+    class Set
+      attr_reader :prefix, :default_width, :default_height
+
+      def initialize(prefix:, data:)
+        @prefix = prefix
+        @icons = data["icons"] || {}
+        @aliases = data["aliases"] || {}
+        @default_width = data["width"] || 24
+        @default_height = data["height"] || 24
+        @info = data["info"] || {}
+      end
+
+      def icon(name)
+        if (icon_data = @icons[name])
+          return build_icon_data(icon_data)
+        end
+
+        resolved_name = resolve_alias(name)
+        if resolved_name && (icon_data = @icons[resolved_name])
+          alias_data = @aliases[name]
+          return build_icon_data(icon_data, alias_transforms: alias_data)
+        end
+
+        nil
+      end
+
+      def icon_names
+        @icons.keys + @aliases.keys
+      end
+
+      def icon_count
+        @icons.size
+      end
+
+      def display_name
+        @info["name"] || @prefix
+      end
+
+      class << self
+        def from_vendor(prefix)
+          path = vendor_path_for(prefix)
+          return nil unless File.exist?(path)
+
+          data = JSON.parse(File.read(path))
+          new(prefix: prefix, data: data)
+        end
+
+        def from_bundled(prefix)
+          path = bundled_path_for(prefix)
+          return nil unless File.exist?(path)
+
+          gz_data = File.binread(path)
+          json_str = Zlib::GzipReader.new(StringIO.new(gz_data)).read
+          data = JSON.parse(json_str)
+          new(prefix: prefix, data: data)
+        end
+
+        def vendor_path_for(prefix)
+          base = if defined?(Rails) && Rails.root
+            Rails.root
+          else
+            Pathname.new(Dir.pwd)
+          end
+          base.join(Kiso::Icons.configuration.vendor_path, "#{prefix}.json").to_s
+        end
+
+        def bundled_path_for(prefix)
+          File.join(gem_data_path, "#{prefix}.json.gz")
+        end
+
+        def gem_data_path
+          File.expand_path("../../../../data", __FILE__)
+        end
+
+        def vendored_sets
+          pattern = if defined?(Rails) && Rails.root
+            Rails.root.join(Kiso::Icons.configuration.vendor_path, "*.json").to_s
+          else
+            File.join(Dir.pwd, Kiso::Icons.configuration.vendor_path, "*.json")
+          end
+
+          Dir.glob(pattern).map { |f| File.basename(f, ".json") }.sort
+        end
+      end
+
+      private
+
+      def resolve_alias(name, depth: 0)
+        return nil if depth > 5
+        alias_entry = @aliases[name]
+        return nil unless alias_entry
+
+        parent = alias_entry["parent"]
+        return parent if @icons.key?(parent)
+
+        resolve_alias(parent, depth: depth + 1)
+      end
+
+      def build_icon_data(icon_data, alias_transforms: nil)
+        body = icon_data["body"]
+        width = icon_data["width"] || @default_width
+        height = icon_data["height"] || @default_height
+
+        if alias_transforms
+          body = apply_transforms(body, alias_transforms, width, height)
+          width = alias_transforms["width"] || width
+          height = alias_transforms["height"] || height
+        end
+
+        {body: body, width: width, height: height}
+      end
+
+      def apply_transforms(body, transforms, width, height)
+        parts = []
+
+        if transforms["rotate"]
+          degrees = transforms["rotate"] * 90
+          parts << "rotate(#{degrees} #{width / 2.0} #{height / 2.0})"
+        end
+
+        scale_x = transforms["hFlip"] ? -1 : 1
+        scale_y = transforms["vFlip"] ? -1 : 1
+
+        if scale_x != 1 || scale_y != 1
+          tx = transforms["hFlip"] ? width : 0
+          ty = transforms["vFlip"] ? height : 0
+          parts << "translate(#{tx} #{ty})" if tx != 0 || ty != 0
+          parts << "scale(#{scale_x} #{scale_y})"
+        end
+
+        if parts.any?
+          %(<g transform="#{parts.join(" ")}">#{body}</g>)
+        else
+          body
+        end
+      end
+    end
+  end
+end

data/lib/kiso/icons/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Kiso
+  module Icons
+    VERSION = "0.1.0.pre"
+  end
+end

data/lib/kiso/icons.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module Kiso
+  module Icons
+    class Error < StandardError; end
+    class IconNotFound < Error; end
+    class SetNotFound < Error; end
+
+    class << self
+      def configuration
+        @configuration ||= Configuration.new
+      end
+
+      def configure
+        yield(configuration)
+      end
+
+      def resolver
+        @resolver ||= Resolver.new
+      end
+
+      def cache
+        @cache ||= Cache.new
+      end
+
+      def resolve(name)
+        resolver.resolve(name)
+      end
+
+      def reset!
+        @resolver = nil
+        @cache = nil
+        @configuration = nil
+      end
+    end
+  end
+end
+
+require "kiso/icons/version"
+require "kiso/icons/configuration"
+require "kiso/icons/cache"
+require "kiso/icons/set"
+require "kiso/icons/resolver"
+require "kiso/icons/renderer"
+require "kiso/icons/api_client"
+require "kiso/icons/railtie" if defined?(Rails::Railtie)

data/lib/kiso-icons.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+require "kiso/icons"

data/lib/tasks/kiso_icons_tasks.rake

@@ -0,0 +1,9 @@
+namespace :kiso_icons do
+  desc "Setup kiso-icons for the app"
+  task :install do
+    previous_location = ENV["LOCATION"]
+    ENV["LOCATION"] = File.expand_path("../install/install.rb", __dir__)
+    Rake::Task["app:template"].invoke
+    ENV["LOCATION"] = previous_location
+  end
+end

metadata

@@ -0,0 +1,109 @@
+--- !ruby/object:Gem::Specification
+name: kiso-icons
+version: !ruby/object:Gem::Version
+  version: 0.1.0.pre
+platform: ruby
+authors:
+- Steve Clarke
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: railties
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '8.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '8.0'
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '8.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '8.0'
+- !ruby/object:Gem::Dependency
+  name: actionpack
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '8.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '8.0'
+description: Pin any of Iconify's 224 icon sets (299k icons) to vendor/icons/. Inline
+  SVG rendering, zero JavaScript, vendored for production.
+email:
+- steve@sevenview.ca
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- MIT-LICENSE
+- README.md
+- Rakefile
+- data/lucide.json.gz
+- lib/install/bin/kiso-icons
+- lib/install/install.rb
+- lib/kiso-icons.rb
+- lib/kiso/icons.rb
+- lib/kiso/icons/api_client.rb
+- lib/kiso/icons/cache.rb
+- lib/kiso/icons/commands.rb
+- lib/kiso/icons/configuration.rb
+- lib/kiso/icons/helper.rb
+- lib/kiso/icons/railtie.rb
+- lib/kiso/icons/renderer.rb
+- lib/kiso/icons/resolver.rb
+- lib/kiso/icons/set.rb
+- lib/kiso/icons/version.rb
+- lib/tasks/kiso_icons_tasks.rake
+homepage: https://github.com/steveclarke/kiso-icons
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/steveclarke/kiso-icons
+  source_code_uri: https://github.com/steveclarke/kiso-icons
+  changelog_uri: https://github.com/steveclarke/kiso-icons/blob/master/CHANGELOG.md
+  bug_tracker_uri: https://github.com/steveclarke/kiso-icons/issues
+  rubygems_mfa_required: 'true'
+  allowed_push_host: https://rubygems.org
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.2'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: Iconify icons for Rails
+test_files: []