unmagic-icon 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 78dfe537a660edce4ede922cf790a6b2a317c24f54143e356674925113f94bb8
+  data.tar.gz: 513b08d32b96b7f4da9177c814e44b8a1f85a9cb8be54d75b6e4bffb166b6a63
+SHA512:
+  metadata.gz: 3f57f44dd2680988425b6c2e8fc195f2eca2d4647305ba9250ca5220e7b6cc6a807b641927e820ba7bb0a651ab016bf15c8e2e5165350a9e68230822a52fd417
+  data.tar.gz: 557cb9b7886ef6d7d0bd7ce28c40815c6b0442dd7a8ae6c79d0033b697044a8e6c930b4bd23a3d2338e18cf64ef447a8a06633b91403d70fe75dbeb25c35fef8

data/CHANGELOG.md

@@ -0,0 +1,37 @@
+# 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.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-06-21
+
+### Added
+- Initial release
+- `Unmagic::Icon` for loading an SVG asset and rendering it inline as
+  html-safe markup, with a `unmagic-icon` class, a `data-unmagic-icon` marker,
+  and caller-supplied attributes (`class`, `aria-*`, `data-*`, etc.) merged onto
+  the `<svg>` element; rendered markup is cached when no options are passed
+- `Unmagic::Icon.find` to resolve a `library/name` reference (tolerating the
+  emoji-style `:library/name:` decoration) to an icon
+- `Unmagic::Icon::Library` with on-disk icon discovery and an optional
+  `manifest.json` declaring a `default` icon and `aliases` (exact strings plus
+  glob patterns, matched longest-first)
+- `Unmagic::Icon::Library::Registry` that builds libraries from configured
+  paths, supporting nested library names and a `prefix:path` syntax
+- `Unmagic::Icon::Configuration` with `paths`, `libraries`, and a `download_path`
+  defaulting to `vendor/icons` under Rails
+- Rails integration via `Unmagic::Icon::Engine`: registers the `unmagic_icon`
+  view helper and configures default icon paths (including engine-provided icons)
+- `Unmagic::Icon::Library::Source`, a DSL-driven downloader for popular icon
+  sets — Heroicons, Devicons, Feather, Tabler, Lucide, Simple Icons, Material
+  File Icons, and Silk
+- Rake tasks `unmagic:icons:install` (downloads the configured libraries, and
+  hooks into `assets:precompile`) and `unmagic:icons:download[library]`
+- `Unmagic::Icon::Web`, a Rack app for browsing the configured icon libraries
+
+[Unreleased]: https://github.com/unreasonable-magic/unmagic-icon/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/unreasonable-magic/unmagic-icon/releases/tag/v0.1.0

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Keith Pitt
+
+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,156 @@
+# Unmagic::Icon
+
+Inline SVG icons for Rails, with downloadable icon libraries.
+
+## Features
+
+- Render SVG icons inline as html-safe markup, straight into your views
+- Resolve icons through `library/name` references, with aliases and glob patterns
+- Per-library `manifest.json` for a default icon and alias mappings
+- Caller-controlled attributes (`class`, `aria-*`, `data-*`, …) merged onto the `<svg>`
+- Rails engine that registers a `unmagic_icon` view helper and sensible icon paths
+- One-command downloads for popular icon sets (Heroicons, Lucide, Tabler, Feather, and more)
+- A Rack app for browsing your configured libraries
+
+## Installation
+
+Add to your Gemfile:
+
+```ruby
+gem 'unmagic-icon'
+```
+
+## Usage
+
+### In Rails views
+
+The Rails engine registers a `unmagic_icon` helper and looks for icons in
+`vendor/icons` and `app/assets/icons` (plus any engine-provided
+`app/assets/icons`).
+
+```erb
+<%= unmagic_icon "heroicons/24-outline/star" %>
+<%= unmagic_icon "lucide/check", class: "size-5 text-green-600" %>
+<%= unmagic_icon "feather/menu", "aria-hidden": "true" %>
+```
+
+An icon reference is `library/name`. The library is the directory the icon
+lives in (relative to a configured path), and the name is the SVG file without
+its extension. Nested libraries work too — `heroicons/24-outline/star` is the
+`star` icon in the `heroicons/24-outline` library.
+
+The rendered `<svg>` always gets a `unmagic-icon` class and a
+`data-unmagic-icon="library/name"` marker. Any caller class is appended, and
+every other option is merged verbatim as an attribute — so accessibility
+(`aria-hidden`, `aria-label`, `role`), `id`, and `data-*` are entirely up to you.
+
+### Outside Rails
+
+Configure the paths to look in, then resolve and render icons:
+
+```ruby
+require "unmagic_icon"
+
+Unmagic::Icon.init do |config|
+  config.paths = ["path/to/icons"]
+end
+
+icon = Unmagic::Icon.find("lucide/check")
+icon.to_svg                       # => html-safe "<svg …>…</svg>"
+icon.to_svg(class: "size-5")      # => with an extra class
+icon.as_json                      # => { name: "lucide/check", svg: "<svg …>" }
+```
+
+References tolerate the emoji-style colon decoration, so `":lucide/check:"`
+resolves the same as `"lucide/check"`.
+
+### Aliases and defaults
+
+Drop a `manifest.json` into a library directory to declare a default icon and
+aliases. Aliases can be exact names or glob patterns (patterns are matched
+longest-first, so the most specific wins):
+
+```json
+{
+  "default": "file",
+  "aliases": {
+    "*.rb": "ruby",
+    "*.test.tsx": "test",
+    "*.tsx": "react"
+  }
+}
+```
+
+```ruby
+Unmagic::Icon.find("material/app.rb").name   # => "material/ruby"
+Unmagic::Icon.find("material/unknown").name  # => "material/file" (the default)
+```
+
+### Downloading icon libraries
+
+The gem can fetch popular icon sets for you. List the ones you want in an
+initializer:
+
+```ruby
+# config/initializers/unmagic_icon.rb
+Unmagic::Icon.configure do |config|
+  config.libraries = [:heroicons, :lucide, :feather]
+end
+```
+
+Then download them (this also runs automatically during `assets:precompile`):
+
+```bash
+bin/rails unmagic:icons:install
+```
+
+Or grab a single library on demand:
+
+```bash
+bin/rails unmagic:icons:download[heroicons]
+bin/rails unmagic:icons:download[silk,force]   # re-download even if present
+```
+
+Libraries are written to `config.download_path` (defaults to `vendor/icons`
+under Rails), which keeps downloaded sets out of the asset pipeline — icons are
+inlined via `File.read`, never served as assets.
+
+Available libraries:
+
+| Key                   | Title               | Description                                                                  |
+| --------------------- | ------------------- | ---------------------------------------------------------------------------- |
+| `heroicons`           | Heroicons           | Beautiful hand-crafted SVG icons by the makers of Tailwind CSS               |
+| `devicons`            | Devicons            | Icons representing programming languages, designing & development tools      |
+| `feather`             | Feather Icons       | Simply beautiful open source icons                                           |
+| `tabler`              | Tabler Icons        | Over 5400 free SVG icons                                                     |
+| `lucide`              | Lucide Icons        | Beautiful & consistent icons                                                 |
+| `simple-icons`        | Simple Icons        | SVG icons for popular brands                                                 |
+| `material-file-icons` | Material File Icons | Material Design file icons with filename/extension aliases                   |
+| `silk`                | Silk Icons Scalable | The classic silk icon set recreated as SVG                                   |
+
+### Browsing icons
+
+`Unmagic::Icon::Web` is a small Rack app for browsing your configured
+libraries. Mount it in your routes:
+
+```ruby
+mount Unmagic::Icon::Web => "/unmagic/icons"
+```
+
+## Development
+
+After checking out the repo, install dependencies and run the tests:
+
+```bash
+bundle install
+bundle exec rake spec
+```
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at
+https://github.com/unreasonable-magic/unmagic-icon.
+
+## License
+
+Released under the [MIT License](LICENSE).

data/lib/tasks/unmagic/icon/download.rake

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+namespace :unmagic do
+  namespace :icons do
+    desc "Download popular icon libraries"
+    task :download, %i[library force] => :environment do |_task, args|
+      require_relative "../../../unmagic/icon/library/source"
+
+      library = args[:library]&.strip
+      force = args[:force] == "force"
+
+      if library.nil? || library.empty?
+        puts "Error: Please specify a library to download"
+        puts "Available libraries:"
+        Unmagic::Icon::Library::Source.all.each do |source|
+          puts "  #{source.key.to_s.ljust(20)} - #{source.description}"
+        end
+        puts "\nUsage: rails unmagic:icons:download[heroicons]"
+        puts "       rails unmagic:icons:download[silk,force]"
+        exit 1
+      end
+
+      Unmagic::Icon::Library::Source.find(library).new.download(force: force)
+    end
+  end
+end

data/lib/tasks/unmagic/icon/install.rake

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+namespace :unmagic do
+  namespace :icons do
+    desc "Download every icon library listed in Unmagic::Icon.configuration.libraries"
+    task install: :environment do
+      require_relative "../../../unmagic/icon/library/source"
+
+      libraries = Array(Unmagic::Icon.configuration.libraries)
+
+      if libraries.empty?
+        puts "No icon libraries configured. Set Unmagic::Icon.configuration.libraries in an initializer."
+      else
+        libraries.each { |name| Unmagic::Icon::Library::Source.find(name).new.download }
+      end
+    end
+  end
+end
+
+# Fetch the configured icon libraries as part of asset precompilation, so they
+# arrive through normal Rails operations (e.g. the production image build) rather
+# than a separate manual step. The download skips libraries already present, and
+# it's a no-op when none are configured. The prerequisite resolves at invocation
+# time, so this works regardless of when assets:precompile is defined.
+task "assets:precompile" => "unmagic:icons:install"

data/lib/unmagic/icon/action_view_helpers.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module Unmagic
+  class Icon
+    # View helper, registered into ActionView by the engine. Mirrors the shape a
+    # future emoji pack would use (`unmagic_emoji`), so both share one rendering
+    # surface.
+    module ActionViewHelpers
+      def unmagic_icon(reference, **options)
+        Unmagic::Icon.find(reference).render(**options)
+      end
+    end
+  end
+end

data/lib/unmagic/icon/configuration.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+require "pathname"
+
+module Unmagic
+  class Icon
+    class Configuration
+      attr_accessor :paths, :libraries
+      attr_writer :download_path
+
+      def initialize
+        @paths = []
+        @libraries = []
+      end
+
+      # Where `Unmagic::Icon::Library::Source` writes libraries by default.
+      # vendor/icons keeps downloaded sets out of the asset pipeline (Propshaft
+      # fingerprints app/assets/*, but the icons are inlined via File.read, never
+      # served), and reads as vendored third-party. Must be set explicitly when
+      # not running under Rails.
+      def download_path
+        @download_path ||= default_download_path
+      end
+
+      private
+
+      def default_download_path
+        return unless defined?(Rails) && Rails.respond_to?(:root) && Rails.root
+
+        Rails.root.join("vendor", "icons")
+      end
+    end
+  end
+end

data/lib/unmagic/icon/engine.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+require_relative "action_view_helpers"
+
+module Unmagic
+  class Icon
+    class Engine < ::Rails::Engine
+      isolate_namespace Unmagic::Icon
+
+      initializer "unmagic_icon.helpers" do
+        ActiveSupport.on_load(:action_view) do
+          include Unmagic::Icon::ActionViewHelpers
+        end
+      end
+
+      initializer "unmagic_icon.init" do
+        unless Unmagic::Icon.initialized?
+          Unmagic::Icon.init do |config|
+            # vendor/icons is the default home for downloaded sets (out of the
+            # asset pipeline); app/assets/icons stays supported for committed,
+            # hand-authored icons.
+            paths = [
+              Rails.root.join("vendor", "icons").to_s,
+              Rails.root.join("app", "assets", "icons").to_s
+            ]
+
+            # Also look for icons in engines
+            Rails.application.railties.select do |r|
+              r.is_a?(Rails::Engine) && r.class != Rails::Application
+            end.each do |engine|
+              engine_path = engine.root.join("app", "assets", "icons")
+              next unless engine_path.exist?
+
+              prefix = engine.class.name.underscore.gsub(%r{/engine$}, "").tr("/", "_")
+              paths << "#{prefix}:#{engine_path}"
+            end
+
+            config.paths = paths
+          end
+        end
+      end
+    end
+  end
+end

data/lib/unmagic/icon/library/registry.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+module Unmagic
+  class Icon
+    class Library
+      class Registry
+        class << self
+          def all
+            _all.values
+          end
+
+          def exists?(name)
+            !_all[name].nil?
+          end
+
+          def find(name)
+            return name if name.is_a?(Unmagic::Icon::Library)
+
+            _all[name] or
+              raise Unmagic::Icon::LibraryNotFoundError.new("Can't find library #{name.inspect}")
+          end
+
+          def reset!
+            @_all = nil
+          end
+
+          private
+
+          def _all
+            @_all ||= find_libraries
+          end
+
+          def find_libraries
+            libs = {}
+            Unmagic::Icon.configuration.paths.each do |path|
+              build_libraries(path: path).each do |lib|
+                libs[lib.name] = lib
+              end
+            end
+            libs
+          end
+
+          def build_libraries(path:)
+            discovered = []
+
+            # If the path has a `blah:` at the start, extract it and use it as a
+            # prefix for the library name
+            prefix, path = path.to_s.split(":", 2)
+            if path.blank?
+              path = prefix
+              prefix = nil
+            end
+
+            Dir.glob(File.join(path, "**/")).each do |dir_path|
+              next unless File.directory?(dir_path)
+
+              # Check if this directory has any SVG files
+              svg_files = Dir.glob(File.join(dir_path, "*.svg"))
+              next if svg_files.empty?
+
+              # Build library name from path relative to icons root
+              library_path = Pathname.new(dir_path)
+              relative = library_path.relative_path_from(path).to_s.chomp("/")
+
+              # Skip empty library names (root directory)
+              next if relative.empty? || relative == "."
+
+              # Add name prefix if we had one
+              name = prefix ? "#{prefix}:#{relative}" : relative
+
+              # Add it to our list
+              discovered << Unmagic::Icon::Library.new(name: name, path: library_path)
+            end
+
+            discovered
+          end
+        end
+      end
+    end
+  end
+end

data/lib/unmagic/icon/library/source/devicons.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module Unmagic
+  class Icon
+    class Library
+      class Source
+        class Devicons < Source
+          key :devicons
+          title "Devicons"
+          description "Icons representing programming languages, designing & development tools"
+          url "https://github.com/devicons/devicon/archive/refs/tags/v2.17.0.zip"
+          archive :zip
+          extract "devicon-2.17.0/icons/**/*.svg"
+        end
+      end
+    end
+  end
+end

data/lib/unmagic/icon/library/source/feather.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module Unmagic
+  class Icon
+    class Library
+      class Source
+        class Feather < Source
+          key :feather
+          title "Feather Icons"
+          description "Simply beautiful open source icons"
+          url "https://github.com/feathericons/feather/archive/refs/tags/v4.29.1.zip"
+          archive :zip
+          extract "feather-4.29.1/icons/*.svg"
+        end
+      end
+    end
+  end
+end

data/lib/unmagic/icon/library/source/heroicons.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Unmagic
+  class Icon
+    class Library
+      class Source
+        class Heroicons < Source
+          key :heroicons
+          title "Heroicons"
+          description "Beautiful hand-crafted SVG icons by the makers of Tailwind CSS"
+          url "https://github.com/tailwindlabs/heroicons/archive/refs/tags/v2.2.0.zip"
+          archive :zip
+          extract_into(
+            "heroicons-2.2.0/optimized/16/solid" => "16-solid",
+            "heroicons-2.2.0/optimized/20/solid" => "20-solid",
+            "heroicons-2.2.0/optimized/24/solid" => "24-solid",
+            "heroicons-2.2.0/optimized/24/outline" => "24-outline"
+          )
+        end
+      end
+    end
+  end
+end

data/lib/unmagic/icon/library/source/lucide.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module Unmagic
+  class Icon
+    class Library
+      class Source
+        class Lucide < Source
+          key :lucide
+          title "Lucide Icons"
+          description "Beautiful & consistent icons"
+          url "https://github.com/lucide-icons/lucide/releases/download/1.21.0/lucide-icons-1.21.0.zip"
+          archive :zip
+          extract "icons/*.svg"
+        end
+      end
+    end
+  end
+end

data/lib/unmagic/icon/library/source/material_file_icons.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module Unmagic
+  class Icon
+    class Library
+      class Source
+        # PKief's material-icon-theme, sourced from the npm tarball so we also get
+        # dist/material-icons.json — the file→icon mapping — which we turn into a
+        # manifest.json of aliases.
+        class MaterialFileIcons < Source
+          key :"material-file-icons"
+          title "Material File Icons"
+          description "Material Design file icons with filename/extension aliases (PKief material-icon-theme)"
+          url "https://registry.npmjs.org/material-icon-theme/-/material-icon-theme-5.35.0.tgz"
+          archive :tgz
+          dir "material"
+          extract "package/icons/*.svg"
+
+          private
+
+          def write_manifest(tmpdir, target_dir)
+            json_path = File.join(tmpdir, "package", "dist", "material-icons.json")
+            return unless File.exist?(json_path)
+
+            data = JSON.parse(File.read(json_path))
+            definitions = data["iconDefinitions"] || {}
+
+            rename_clones(definitions, target_dir)
+
+            aliases = {}
+            (data["fileExtensions"] || {}).each { |extension, name| aliases["*.#{extension.downcase}"] = name }
+            (data["fileNames"] || {}).each { |filename, name| aliases[filename.downcase] = name }
+
+            manifest = {
+              "name" => "material",
+              "description" => "Material Design file icons (PKief material-icon-theme)",
+              "provider" => "material-icon-theme",
+              "default" => data["file"] || "file",
+              "aliases" => aliases
+            }
+
+            File.write(Pathname(target_dir).join("manifest.json"), JSON.pretty_generate(manifest))
+            puts "  ✓ Wrote manifest.json (#{aliases.size} aliases)"
+          end
+
+          # Material ships ~72 "*.clone.svg" files; rename them to the clean icon
+          # name the aliases point at, so on-disk names match the manifest targets.
+          def rename_clones(definitions, target_dir)
+            target_dir = Pathname(target_dir)
+
+            definitions.each do |name, info|
+              basename = File.basename(info["iconPath"].to_s, ".svg")
+              next if basename == name
+
+              source = target_dir.join("#{basename}.svg")
+              destination = target_dir.join("#{name}.svg")
+              FileUtils.mv(source, destination) if source.exist? && !destination.exist?
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/unmagic/icon/library/source/silk.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module Unmagic
+  class Icon
+    class Library
+      class Source
+        # No release archive: fetch the svgs directly from the repo via the
+        # GitHub contents API, so #acquire is overridden entirely.
+        class Silk < Source
+          key :silk
+          title "Silk Icons Scalable"
+          description "The classic silk icon set recreated as SVG"
+
+          REPO = "frhun/silk-icon-scalable"
+          BRANCH = "main"
+          PATHS = [ "baseicons", "extra" ].freeze
+
+          private
+
+          def acquire(target_dir)
+            FileUtils.mkdir_p(target_dir)
+
+            headers = {
+              "Accept" => "application/vnd.github.v3+json",
+              "User-Agent" => "unmagic-icon-downloader"
+            }
+
+            PATHS.each do |dir_path|
+              uri = URI("https://api.github.com/repos/#{REPO}/contents/#{dir_path}?ref=#{BRANCH}")
+              response = fetch_with_redirect(uri, headers)
+              raise DownloadError, "Failed to list #{dir_path}: HTTP #{response.code}" if response.code != "200"
+
+              files = JSON.parse(response.body).select { |file| file["name"].end_with?(".svg") }
+              puts "  Downloading #{files.size} icons from #{dir_path}..."
+              each_with_progress(files, show_time: true) do |file|
+                download_file(file["download_url"], File.join(target_dir, file["name"]))
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/unmagic/icon/library/source/simple_icons.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module Unmagic
+  class Icon
+    class Library
+      class Source
+        class SimpleIcons < Source
+          key :"simple-icons"
+          title "Simple Icons"
+          description "SVG icons for popular brands"
+          url "https://registry.npmjs.org/simple-icons/-/simple-icons-14.2.0.tgz"
+          archive :tgz
+          extract "package/icons/*.svg"
+        end
+      end
+    end
+  end
+end