iconmap-rails 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: ffee894f6afcd5daa549857261eeeb4c663a25992edcc02bd59d442868153d80
+  data.tar.gz: a28499b09beb0cf46259bbd7f16a78afadc5a0965c8529f6cc282cb74d94481f
+SHA512:
+  metadata.gz: 1b5c60f56f2413639d944e46a6df23174842348399155c42ec64c2817174ee32cdd06b02dd818d1c5043c2886ca8782be22ea04f7dd4de09ebd1376fe9e76424
+  data.tar.gz: a7d1717b47946064e9dd44fe7c2d9c2af513967a17dbe00109aa0add0a6b7b8917d19dab7b23a90c9b1547e7017a650f2050bb48f55fcc8be6f0a5ddd48a81fb

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2022 Basecamp, 2025 Geremia Taglialatela
+
+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,266 @@
+# Iconmap for Rails
+
+Like [Importmap Rails](https://github.com/rails/importmap-rails), but for Icons.
+
+## Installation
+
+Iconmap for Rails is automatically included in Rails 7+ for new applications, but you can also install it manually in existing applications:
+
+1. Run `./bin/bundle add iconmap-rails`
+2. Run `./bin/rails iconmap:install`
+
+You can pin those libraries manually by relying on the compiled versions included in Rails like this:
+
+```ruby
+pin "@rails/actioncable", to: "actioncable.esm.js"
+pin "@rails/activestorage", to: "activestorage.esm.js"
+pin "@rails/actiontext", to: "actiontext.esm.js"
+pin "trix"
+```
+
+## How do iconmaps work?
+
+At their core, iconmaps are essentially a string substitution for what are referred to as "bare module specifiers". A "bare module specifier" looks like this: `import React from "react"`. This is not compatible with the ES Module loader spec. Instead, to be ESM compatible, you must provide 1 of the 3 following types of specifiers:
+
+- Absolute path:
+```js
+import React from "/Users/DHH/projects/basecamp/node_modules/react"
+```
+
+- Relative path:
+```js
+import React from "./node_modules/react"
+```
+
+- HTTP path:
+```js
+import React from "https://ga.jspm.io/npm:react@17.0.1/index.js"
+```
+
+Iconmap-rails provides a clean API for mapping "bare module specifiers" like `"react"`
+to 1 of the 3 viable ways of loading ES Module javascript packages.
+
+For example:
+
+```rb
+# config/iconmap.rb
+pin "react", to: "https://ga.jspm.io/npm:react@17.0.2/index.js"
+```
+
+means "everytime you see `import React from "react"`
+change it to `import React from "https://ga.jspm.io/npm:react@17.0.2/index.js"`"
+
+```js
+import React from "react"
+// => import React from "https://ga.jspm.io/npm:react@17.0.2/index.js"
+```
+
+## Usage
+
+The icon map is setup through `Rails.application.iconmap` via the configuration in `config/iconmap.rb`. This file is automatically reloaded in development upon changes, but note that you must restart the server if you remove pins and need them gone from the rendered iconmap or list of preloads.
+
+It makes sense to use logical names that match the package names used by npm, such that if you later want to start transpiling or bundling your code, you won't have to change any module imports.
+
+### Local modules
+
+If you want to import local js module files from `app/javascript/src` or other sub-folders of `app/javascript` (such as `channels`), you must pin these to be able to import them. You can use `pin_all_from` to pick all files in a specific folder, so you don't have to `pin` each module individually.
+
+```rb
+# config/iconmap.rb
+pin_all_from 'app/javascript/src', under: 'src', to: 'src'
+```
+
+The `:to` parameter is only required if you want to change the destination logical import name. If you drop the :to option, you must place the :under option directly after the first parameter.
+
+Allows you to:
+
+```js
+// app/javascript/application.js
+import { ExampleFunction } from 'src/example_function'
+```
+Which imports the function from `app/javascript/src/example_function.js`.
+
+Note: Sprockets used to serve assets (albeit without filename digests) it couldn't find from the `app/javascripts` folder with logical relative paths, meaning pinning local files wasn't needed. Propshaft doesn't have this fallback, so when you use Propshaft you have to pin your local modules.
+
+## Using npm packages via JavaScript CDNs
+
+Iconmap for Rails downloads and vendors your npm package dependencies via JavaScript CDNs that provide pre-compiled distribution versions.
+
+You can use the `./bin/iconmap` command that's added as part of the install to pin, unpin, or update npm packages in your import map. This command uses an API from [JSPM.org](https://jspm.org) to resolve your package dependencies efficiently, and then add the pins to your `config/iconmap.rb` file. It can resolve these dependencies from JSPM itself, but also from other CDNs, like [unpkg.com](https://unpkg.com) and [jsdelivr.com](https://www.jsdelivr.com).
+
+```bash
+./bin/iconmap pin react
+Pinning "react" to vendor/react.js via download from https://ga.jspm.io/npm:react@17.0.2/index.js
+Pinning "object-assign" to vendor/object-assign.js via download from https://ga.jspm.io/npm:object-assign@4.1.1/index.js
+```
+
+This will produce pins in your `config/iconmap.rb` like so:
+
+```ruby
+pin "react" # https://ga.jspm.io/npm:react@17.0.2/index.js
+pin "object-assign" # https://ga.jspm.io/npm:object-assign@4.1.1/index.js
+```
+
+The packages are downloaded to `vendor/icons`, which you can check into your source control, and they'll be available through your application's own asset pipeline serving.
+
+If you later wish to remove a downloaded pin:
+
+```bash
+./bin/iconmap unpin react
+Unpinning and removing "react"
+Unpinning and removing "object-assign"
+```
+
+## Preloading pinned modules
+
+To avoid the waterfall effect where the browser has to load one file after another before it can get to the deepest nested import, iconmap-rails uses [modulepreload links](https://developers.google.com/web/updates/2017/12/modulepreload) by default. If you don't want to preload a dependency, because you want to load it on-demand for efficiency, append `preload: false` to the pin.
+
+Example:
+
+```ruby
+# config/iconmap.rb
+pin "@github/hotkey", to: "@github--hotkey.js" # file lives in vendor/icons/@github--hotkey.js
+pin "md5", preload: false # file lives in vendor/javascript/md5.js
+
+# app/views/layouts/application.html.erb
+<%= javascript_iconmap_tags %>
+
+# will include the following link before the iconmap is setup:
+<link rel="modulepreload" href="/assets/javascript/@github--hotkey.js">
+...
+```
+
+You can also specify which entry points to preload a particular dependency in by providing `preload:` a string or array of strings.
+
+Example:
+
+```ruby
+# config/iconmap.rb
+pin "@github/hotkey", to: "@github--hotkey.js", preload: 'application'
+pin "md5", preload: ['application', 'alternate']
+
+# app/views/layouts/application.html.erb
+<%= javascript_iconmap_tags 'alternate' %>
+
+# will include the following link before the iconmap is setup:
+<link rel="modulepreload" href="/assets/javascript/md5.js">
+...
+```
+
+
+
+## Composing import maps
+
+By default, Rails loads import map definition from the application's `config/iconmap.rb` to the `Iconmap::Map` object available at `Rails.application.iconmap`.
+
+You can combine multiple import maps by adding paths to additional import map configs to `Rails.application.config.iconmap.paths`. For example, appending import maps defined in Rails engines:
+
+```ruby
+# my_engine/lib/my_engine/engine.rb
+
+module MyEngine
+  class Engine < ::Rails::Engine
+    # ...
+    initializer "my-engine.iconmap", before: "iconmap" do |app|
+      app.config.iconmap.paths << Engine.root.join("config/iconmap.rb")
+      # ...
+    end
+  end
+end
+```
+
+And pinning JavaScript modules from the engine:
+
+```ruby
+# my_engine/config/iconmap.rb
+
+pin_all_from File.expand_path("../app/assets/javascripts", __dir__)
+```
+
+
+## Selectively importing modules
+
+You can selectively import your javascript modules on specific pages.
+
+Create your javascript in `app/javascript`:
+
+```js
+// /app/javascript/checkout.js
+// some checkout specific js
+```
+
+Pin your js file:
+
+```rb
+# config/iconmap.rb
+# ... other pins...
+pin "checkout", preload: false
+```
+
+Import your module on the specific page. Note: you'll likely want to use a `content_for` block on the specifc page/partial, then yield it in your layout.
+
+```erb
+<% content_for :head do %>
+  <%= javascript_import_module_tag "checkout" %>
+<% end %>
+```
+
+**Important**: The `javascript_import_module_tag` should come after your `javascript_iconmap_tags`
+
+```erb
+<%= javascript_iconmap_tags %>
+<%= yield(:head) %>
+```
+
+
+## Include a digest of the import map in your ETag
+
+If you're using [ETags](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/ETag) generated by Rails helpers like `stale?` or `fresh_when`, you need to include the digest of the import map into this calculation. Otherwise your application will return [304](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/304) cache responses even when your JavaScript assets have changed. You can avoid this using the `stale_when_iconmap_changes` method:
+
+```ruby
+class ApplicationController < ActionController::Base
+  stale_when_iconmap_changes
+end
+```
+
+This will add the digest of the iconmap to the etag calculation when the request format is HTML.
+
+
+## Sweeping the cache in development and test
+
+Generating the import map json and modulepreloads may require resolving hundreds of assets. This can take a while, so these operations are cached, but in development and test, we watch for changes to both `config/iconmap.rb` and files in `app/javascript` to clear this cache. This feature can be controlled in an environment configuration file via the boolean `config.iconmap.sweep_cache`.
+
+If you're pinning local files from outside of `app/javascript`, you'll need to add them to the cache sweeper configuration or restart your development server upon changes to those external files. For example, here's how you can do it for Rails engine:
+
+```ruby
+# my_engine/lib/my_engine/engine.rb
+
+module MyEngine
+  class Engine < ::Rails::Engine
+    # ...
+    initializer "my-engine.iconmap", before: "iconmap" do |app|
+      # ...
+      app.config.iconmap.cache_sweepers << Engine.root.join("app/assets/icons")
+    end
+  end
+end
+```
+
+## Checking for outdated or vulnerable packages
+
+Iconmap for Rails provides two commands to check your pinned packages:
+- `./bin/iconmap outdated` checks the NPM registry for new versions
+- `./bin/iconmap audit` checks the NPM registry for known security issues
+
+## Supporting legacy browsers such as Safari on iOS 15
+
+If you want to support [legacy browsers that do not support import maps](https://caniuse.com/import-maps) such as [iOS 15.8.1 released on 22 Jan 2024](https://support.apple.com/en-us/HT201222), insert [`es-module-shims`](https://github.com/guybedford/es-module-shims) before `javascript_iconmap_tags` as below.
+
+```erb
+<script async src="https://ga.jspm.io/npm:es-module-shims@1.8.2/dist/es-module-shims.js" data-turbo-track="reload"></script>
+<%= javascript_iconmap_tags %>
+```
+
+## License
+
+Iconmap for Rails is released under the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,19 @@
+require "bundler/setup"
+
+APP_RAKEFILE = File.expand_path("test/dummy/Rakefile", __dir__)
+load "rails/tasks/engine.rake"
+
+load "rails/tasks/statistics.rake"
+
+require "bundler/gem_tasks"
+
+require "rake/testtask"
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << 'test'
+  t.pattern = 'test/**/*_test.rb'
+  t.verbose = false
+  t.warning = false
+end
+
+task default: :test

data/app/controllers/iconmap/freshness.rb

@@ -0,0 +1,5 @@
+module Iconmap::Freshness
+  def stale_when_iconmap_changes
+    etag { Rails.application.iconmap.digest(resolver: helpers) if request.format&.html? }
+  end
+end

data/app/helpers/iconmap/iconmap_tags_helper.rb

@@ -0,0 +1,37 @@
+module Iconmap::IconmapTagsHelper
+  # Setup all script tags needed to use an iconmap-powered entrypoint (which defaults to application.js)
+  def javascript_iconmap_tags(entry_point = "application", iconmap: Rails.application.iconmap)
+    safe_join [
+      javascript_inline_iconmap_tag(iconmap.to_json(resolver: self)),
+      javascript_iconmap_module_preload_tags(iconmap, entry_point:),
+      javascript_import_module_tag(entry_point)
+    ], "\n"
+  end
+
+  # Generate an inline iconmap tag using the passed `iconmap_json` JSON string.
+  # By default, `Rails.application.iconmap.to_json(resolver: self)` is used.
+  def javascript_inline_iconmap_tag(iconmap_json = Rails.application.iconmap.to_json(resolver: self))
+    tag.script iconmap_json.html_safe,
+      type: "iconmap", "data-turbo-track": "reload", nonce: request&.content_security_policy_nonce
+  end
+
+  # Import a named JavaScript module(s) using a script-module tag.
+  def javascript_import_module_tag(*module_names)
+    imports = Array(module_names).collect { |m| %(import "#{m}") }.join("\n")
+    tag.script imports.html_safe, type: "module", nonce: request&.content_security_policy_nonce
+  end
+
+  # Link tags for preloading all modules marked as preload: true in the `iconmap`
+  # (defaults to Rails.application.iconmap), such that they'll be fetched
+  # in advance by browsers supporting this link type (https://caniuse.com/?search=modulepreload).
+  def javascript_iconmap_module_preload_tags(iconmap = Rails.application.iconmap, entry_point: "application")
+    javascript_module_preload_tag(*iconmap.preloaded_module_paths(resolver: self, entry_point:, cache_key: entry_point))
+  end
+
+  # Link tag(s) for preloading the JavaScript module residing in `*paths`. Will return one link tag per path element.
+  def javascript_module_preload_tag(*paths)
+    safe_join(Array(paths).collect { |path|
+      tag.link rel: "modulepreload", href: path, nonce: request&.content_security_policy_nonce
+    }, "\n")
+  end
+end

data/lib/iconmap/commands.rb

@@ -0,0 +1,159 @@
+require "thor"
+require_relative "packager"
+require_relative "npm"
+
+class Iconmap::Commands < Thor
+  include Thor::Actions
+
+  def self.exit_on_failure?
+    false
+  end
+
+  desc "pin [*PACKAGES]", "Pin new icons"
+  option :env, type: :string, aliases: :e, default: "production"
+  option :from, type: :string, aliases: :f, default: "jspm"
+  def pin(*packages)
+    if imports = packager.import(*packages, env: options[:env], from: options[:from])
+      imports.each do |package, url|
+        puts %(Pinning "#{package}" to #{packager.vendor_path}/#{package} via download from #{url})
+        packager.download(package, url)
+        pin = packager.vendored_pin_for(package, url)
+
+        if packager.packaged?(package)
+          gsub_file("config/iconmap.rb", /^pin "#{package}".*$/, pin, verbose: false)
+        else
+          append_to_file("config/iconmap.rb", "#{pin}\n", verbose: false)
+        end
+      end
+    else
+      puts "Couldn't find any icons in #{packages.inspect} on #{options[:from]}"
+    end
+  end
+
+  desc "unpin [*PACKAGES]", "Unpin existing packages"
+  option :env, type: :string, aliases: :e, default: "production"
+  option :from, type: :string, aliases: :f, default: "jspm"
+  def unpin(*packages)
+    if imports = packager.import(*packages, env: options[:env], from: options[:from])
+      imports.each do |package, url|
+        if packager.packaged?(package)
+          puts %(Unpinning and removing "#{package}")
+          packager.remove(package)
+        end
+      end
+    else
+      puts "Couldn't find any packages in #{packages.inspect} on #{options[:from]}"
+    end
+  end
+
+  desc "pristine", "Redownload all pinned packages"
+  option :env, type: :string, aliases: :e, default: "production"
+  option :from, type: :string, aliases: :f, default: "jspm"
+  def pristine
+    packages = npm.packages_with_versions.map do |p, v|
+      v.blank? ? p : [p, v].join("@")
+    end
+
+    if imports = packager.import(*packages, env: options[:env], from: options[:from])
+      imports.each do |package, url|
+        puts %(Downloading "#{package}" to #{packager.vendor_path}/#{package} from #{url})
+        packager.download(package, url)
+      end
+    else
+      puts "Couldn't find any packages in #{packages.inspect} on #{options[:from]}"
+    end
+  end
+
+  desc "json", "Show the full iconmap in json"
+  def json
+    require Rails.root.join("config/environment")
+    puts Rails.application.iconmap.to_json(resolver: ActionController::Base.helpers)
+  end
+
+  desc "audit", "Run a security audit"
+  def audit
+    vulnerable_packages = npm.vulnerable_packages
+
+    if vulnerable_packages.any?
+      table = [["Package", "Severity", "Vulnerable versions", "Vulnerability"]]
+      vulnerable_packages.each { |p| table << [p.name, p.severity, p.vulnerable_versions, p.vulnerability] }
+
+      puts_table(table)
+      vulnerabilities = 'vulnerability'.pluralize(vulnerable_packages.size)
+      severities = vulnerable_packages.map(&:severity).tally.sort_by(&:last).reverse
+                                      .map { |severity, count| "#{count} #{severity}" }
+                                      .join(", ")
+      puts "  #{vulnerable_packages.size} #{vulnerabilities} found: #{severities}"
+
+      exit 1
+    else
+      puts "No vulnerable packages found"
+    end
+  end
+
+  desc "outdated", "Check for outdated packages"
+  def outdated
+    if (outdated_packages = npm.outdated_packages).any?
+      table = [["Icon", "Current", "Latest"]]
+      outdated_packages.each { |p| table << [p.name, p.current_version, p.latest_version || p.error] }
+
+      puts_table(table)
+      packages = 'icon'.pluralize(outdated_packages.size)
+      puts "  #{outdated_packages.size} outdated #{packages} found"
+
+      exit 1
+    else
+      puts "No outdated icons found"
+    end
+  end
+
+  desc "update", "Update outdated icon pins"
+  def update
+    if (outdated_packages = npm.outdated_packages).any?
+      pin(*outdated_packages.map(&:name))
+    else
+      puts "No outdated icons found"
+    end
+  end
+
+  desc "packages", "Print out icons with version numbers"
+  def packages
+    puts npm.packages_with_versions.map { |x| x.join(' ') }
+  end
+
+  private
+    def packager
+      @packager ||= Iconmap::Packager.new
+    end
+
+    def npm
+      @npm ||= Iconmap::Npm.new
+    end
+
+    def remove_line_from_file(path, pattern)
+      path = File.expand_path(path, destination_root)
+
+      all_lines = File.readlines(path)
+      with_lines_removed = all_lines.select { |line| line !~ pattern }
+
+      File.open(path, "w") do |file|
+        with_lines_removed.each { |line| file.write(line) }
+      end
+    end
+
+    def puts_table(array)
+      column_sizes = array.reduce([]) do |lengths, row|
+        row.each_with_index.map{ |iterand, index| [lengths[index] || 0, iterand.to_s.length].max }
+      end
+
+      divider = "|" + (column_sizes.map { |s| "-" * (s + 2) }.join('|')) + '|'
+      array.each_with_index do |row, row_number|
+        row = row.fill(nil, row.size..(column_sizes.size - 1))
+        row = row.each_with_index.map { |v, i| v.to_s + " " * (column_sizes[i] - v.to_s.length) }
+        puts "| " + row.join(" | ") + " |"
+        puts divider if row_number == 0
+      end
+    end
+end
+
+Iconmap::Commands.start(ARGV)

data/lib/iconmap/engine.rb

@@ -0,0 +1,71 @@
+require_relative "map"
+
+# Use Rails.application.iconmap to access the map
+Rails::Application.send(:attr_accessor, :iconmap)
+
+module Iconmap
+  class Engine < ::Rails::Engine
+    config.iconmap = ActiveSupport::OrderedOptions.new
+    config.iconmap.paths = []
+    config.iconmap.sweep_cache = Rails.env.development? || Rails.env.test?
+    config.iconmap.cache_sweepers = []
+    config.iconmap.rescuable_asset_errors = []
+
+    config.autoload_once_paths = %W( #{root}/app/helpers #{root}/app/controllers )
+
+    initializer "iconmap" do |app|
+      app.iconmap = Iconmap::Map.new
+      app.config.iconmap.paths << app.root.join("config/iconmap.rb")
+      app.config.iconmap.paths.each { |path| app.iconmap.draw(path) }
+    end
+
+    initializer "iconmap.reloader" do |app|
+      unless app.config.cache_classes
+        Iconmap::Reloader.new.tap do |reloader|
+          reloader.execute
+          app.reloaders << reloader
+          app.reloader.to_run { reloader.execute }
+        end
+      end
+    end
+
+    initializer "iconmap.cache_sweeper" do |app|
+      if app.config.iconmap.sweep_cache && !app.config.cache_classes
+        app.config.iconmap.cache_sweepers << app.root.join("vendor/icons")
+        app.iconmap.cache_sweeper(watches: app.config.iconmap.cache_sweepers)
+
+        ActiveSupport.on_load(:action_controller_base) do
+          before_action { Rails.application.iconmap.cache_sweeper.execute_if_updated }
+        end
+      end
+    end
+
+    initializer "iconmap.assets" do |app|
+      if app.config.respond_to?(:assets)
+        app.config.assets.paths << Rails.root.join("vendor/icons")
+      end
+    end
+
+    initializer "iconmap.concerns" do
+      ActiveSupport.on_load(:action_controller_base) do
+        extend Iconmap::Freshness
+      end
+    end
+
+    initializer "iconmap.helpers" do
+      ActiveSupport.on_load(:action_controller_base) do
+        helper Iconmap::IconmapTagsHelper
+      end
+    end
+
+    initializer "iconmap.rescuable_asset_errors" do |app|
+      if defined?(Propshaft)
+        app.config.iconmap.rescuable_asset_errors << Propshaft::MissingAssetError
+      end
+
+      if defined?(Sprockets::Rails)
+        app.config.iconmap.rescuable_asset_errors << Sprockets::Rails::Helper::AssetNotFound
+      end
+    end
+  end
+end

data/lib/iconmap/map.rb

@@ -0,0 +1,168 @@
+require "pathname"
+
+class Iconmap::Map
+  attr_reader :packages, :directories
+
+  class InvalidFile < StandardError; end
+
+  def initialize
+    @packages, @directories = {}, {}
+    @cache = {}
+  end
+
+  def draw(path = nil, &block)
+    if path && File.exist?(path)
+      begin
+        instance_eval(File.read(path), path.to_s)
+      rescue StandardError => e
+        Rails.logger.error "Unable to parse import map from #{path}: #{e.message}"
+        raise InvalidFile, "Unable to parse import map from #{path}: #{e.message}"
+      end
+    elsif block_given?
+      instance_eval(&block)
+    end
+
+    self
+  end
+
+  def pin(name, to: nil, preload: true)
+    clear_cache
+    @packages[name] = MappedFile.new(name: name, path: to || "#{name}.js", preload: preload)
+  end
+
+  def pin_all_from(dir, under: nil, to: nil, preload: true)
+    clear_cache
+    @directories[dir] = MappedDir.new(dir: dir, under: under, path: to, preload: preload)
+  end
+
+  # Returns an array of all the resolved module paths of the pinned packages. The `resolver` must respond to
+  # `path_to_asset`, such as `ActionController::Base.helpers` or `ApplicationController.helpers`. You'll want to use the
+  # resolver that has been configured for the `asset_host` you want these resolved paths to use. In case you need to
+  # resolve for different asset hosts, you can pass in a custom `cache_key` to vary the cache used by this method for
+  # the different cases.
+  def preloaded_module_paths(resolver:, entry_point: "application", cache_key: :preloaded_module_paths)
+    cache_as(cache_key) do
+      resolve_asset_paths(expanded_preloading_packages_and_directories(entry_point:), resolver:).values
+    end
+  end
+
+  # Returns a JSON hash (as a string) of all the resolved module paths of the pinned packages in the import map format.
+  # The `resolver` must respond to `path_to_asset`, such as `ActionController::Base.helpers` or
+  # `ApplicationController.helpers`. You'll want to use the resolver that has been configured for the `asset_host` you
+  # want these resolved paths to use. In case you need to resolve for different asset hosts, you can pass in a custom
+  # `cache_key` to vary the cache used by this method for the different cases.
+  def to_json(resolver:, cache_key: :json)
+    cache_as(cache_key) do
+      JSON.pretty_generate({ "imports" => resolve_asset_paths(expanded_packages_and_directories, resolver: resolver) })
+    end
+  end
+
+  # Returns a SHA1 digest of the import map json that can be used as a part of a page etag to
+  # ensure that a html cache is invalidated when the import map is changed.
+  #
+  # Example:
+  #
+  #   class ApplicationController < ActionController::Base
+  #     etag { Rails.application.iconmap.digest(resolver: helpers) if request.format&.html? }
+  #   end
+  def digest(resolver:)
+    Digest::SHA1.hexdigest(to_json(resolver: resolver).to_s)
+  end
+
+  # Returns an instance of ActiveSupport::EventedFileUpdateChecker configured to clear the cache of the map
+  # when the directories passed on initialization via `watches:` have changes. This is used in development
+  # and test to ensure the map caches are reset when javascript files are changed.
+  def cache_sweeper(watches: nil)
+    if watches
+      @cache_sweeper =
+        Rails.application.config.file_watcher.new([], Array(watches).collect { |dir| [ dir.to_s, "js"] }.to_h) do
+          clear_cache
+        end
+    else
+      @cache_sweeper
+    end
+  end
+
+  private
+    MappedDir  = Struct.new(:dir, :path, :under, :preload, keyword_init: true)
+    MappedFile = Struct.new(:name, :path, :preload, keyword_init: true)
+
+    def cache_as(name)
+      if result = @cache[name.to_s]
+        result
+      else
+        @cache[name.to_s] = yield
+      end
+    end
+
+    def clear_cache
+      @cache.clear
+    end
+
+    def rescuable_asset_error?(error)
+      Rails.application.config.iconmap.rescuable_asset_errors.any? { |e| error.is_a?(e) }
+    end
+
+    def resolve_asset_paths(paths, resolver:)
+      paths.transform_values do |mapping|
+        begin
+          resolver.path_to_asset(mapping.path)
+        rescue => e
+          if rescuable_asset_error?(e)
+            Rails.logger.warn "Iconmap skipped missing path: #{mapping.path}"
+            nil
+          else
+            raise e
+          end
+        end
+      end.compact
+    end
+
+    def expanded_preloading_packages_and_directories(entry_point:)
+      expanded_packages_and_directories.select { |name, mapping| mapping.preload.in?([true, false]) ? mapping.preload : (Array(mapping.preload) & Array(entry_point)).any? }
+    end
+
+    def expanded_packages_and_directories
+      @packages.dup.tap { |expanded| expand_directories_into expanded }
+    end
+
+    def expand_directories_into(paths)
+      @directories.values.each do |mapping|
+        if (absolute_path = absolute_root_of(mapping.dir)).exist?
+          find_javascript_files_in_tree(absolute_path).each do |filename|
+            module_filename = filename.relative_path_from(absolute_path)
+            module_name     = module_name_from(module_filename, mapping)
+            module_path     = module_path_from(module_filename, mapping)
+
+            paths[module_name] = MappedFile.new(name: module_name, path: module_path, preload: mapping.preload)
+          end
+        end
+      end
+    end
+
+    def module_name_from(filename, mapping)
+      # Regex explanation:
+      # (?:\/|^) # Matches either / OR the start of the string
+      # index   # Matches the word index
+      # $       # Matches the end of the string
+      #
+      # Sample matches
+      # index
+      # folder/index
+      index_regex = /(?:\/|^)index$/
+
+      [ mapping.under, filename.to_s.remove(filename.extname).remove(index_regex).presence ].compact.join("/")
+    end
+
+    def module_path_from(filename, mapping)
+      [ mapping.path || mapping.under, filename.to_s ].compact.reject(&:empty?).join("/")
+    end
+
+    def find_javascript_files_in_tree(path)
+      Dir[path.join("**/*.js{,m}")].sort.collect { |file| Pathname.new(file) }.select(&:file?)
+    end
+
+    def absolute_root_of(path)
+      (pathname = Pathname.new(path)).absolute? ? pathname : Rails.root.join(path)
+    end
+end

data/lib/iconmap/npm.rb

@@ -0,0 +1,129 @@
+require "net/http"
+require "uri"
+require "json"
+
+class Iconmap::Npm
+  Error     = Class.new(StandardError)
+  HTTPError = Class.new(Error)
+
+  singleton_class.attr_accessor :base_uri
+  self.base_uri = URI("https://registry.npmjs.org")
+
+  def initialize(iconmap_path = "config/iconmap.rb")
+    @iconmap_path = Pathname.new(iconmap_path)
+  end
+
+  def outdated_packages
+    packages_with_versions.each.with_object([]) do |(package, current_version), outdated_packages|
+      outdated_package = OutdatedPackage.new(name: package,
+                                             current_version: current_version)
+
+      if !(response = get_package(normalize_package_name(package)))
+        outdated_package.error = 'Response error'
+      elsif (error = response['error'])
+        outdated_package.error = error
+      else
+        latest_version = find_latest_version(response)
+        next unless outdated?(current_version, latest_version)
+
+        outdated_package.latest_version = latest_version
+      end
+
+      outdated_packages << outdated_package
+    end.sort_by(&:name)
+  end
+
+  def vulnerable_packages
+    get_audit.flat_map do |package, vulnerabilities|
+      vulnerabilities.map do |vulnerability|
+        VulnerablePackage.new(name: package,
+                              severity: vulnerability['severity'],
+                              vulnerable_versions: vulnerability['vulnerable_versions'],
+                              vulnerability: vulnerability['title'])
+      end
+    end.sort_by { |p| [p.name, p.severity] }
+  end
+
+  def packages_with_versions
+    # We cannot use the name after "pin" because some dependencies are loaded from inside packages
+    # Eg. pin "buffer", to: "https://ga.jspm.io/npm:@jspm/core@2.0.0-beta.19/nodelibs/browser/buffer.js"
+
+    iconmap.scan(/^pin .*(?<=npm:|npm\/|skypack\.dev\/|unpkg\.com\/)(.*)(?=@\d+\.\d+\.\d+)@(\d+\.\d+\.\d+(?:[^\/\s["']]*)).*$/) |
+      iconmap.scan(/^pin ["']([^["']]*)["'].* #.*@(\d+\.\d+\.\d+(?:[^\s]*)).*$/)
+  end
+
+  private
+    OutdatedPackage   = Struct.new(:name, :current_version, :latest_version, :error, keyword_init: true)
+    VulnerablePackage = Struct.new(:name, :severity, :vulnerable_versions, :vulnerability, keyword_init: true)
+
+    # Normalize the package name (remove any trailing paths)
+    def normalize_package_name(name)
+      if name.start_with?('@')
+        name.split('/', 3)[0..1].join('/')
+      else
+        name.split('/', 2).first
+      end
+    end
+
+    def iconmap
+      @iconmap ||= File.read(@iconmap_path)
+    end
+
+    def get_package(package)
+      uri = self.class.base_uri.dup
+      uri.path = "/" + package
+      response = get_json(uri)
+
+      JSON.parse(response)
+    rescue JSON::ParserError
+      nil
+    end
+
+    def get_json(uri)
+      request = Net::HTTP::Get.new(uri)
+      request["Content-Type"] = "application/json"
+
+      response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http|
+        http.request(request)
+      }
+
+      response.body
+    rescue => error
+      raise HTTPError, "Unexpected transport error (#{error.class}: #{error.message})"
+    end
+
+    def find_latest_version(response)
+      latest_version = response.is_a?(String) ? response : response.dig('dist-tags', 'latest')
+      return latest_version if latest_version
+
+      return unless response['versions']
+
+      response['versions'].keys.map { |v| Gem::Version.new(v) rescue nil }.compact.sort.last
+    end
+
+    def outdated?(current_version, latest_version)
+      Gem::Version.new(current_version) < Gem::Version.new(latest_version)
+    rescue ArgumentError
+      current_version.to_s < latest_version.to_s
+    end
+
+    def get_audit
+      uri = self.class.base_uri.dup
+      uri.path = "/-/npm/v1/security/advisories/bulk"
+
+      body = packages_with_versions.each.with_object({}) { |(package, version), data|
+        data[package] ||= []
+        data[package] << version
+      }
+      return {} if body.empty?
+
+      response = post_json(uri, body)
+      JSON.parse(response.body)
+    end
+
+    def post_json(uri, body)
+      Net::HTTP.post(uri, body.to_json, "Content-Type" => "application/json")
+    rescue => error
+      raise HTTPError, "Unexpected transport error (#{error.class}: #{error.message})"
+    end
+end

data/lib/iconmap/packager.rb

@@ -0,0 +1,149 @@
+require "net/http"
+require "uri"
+require "json"
+
+class Iconmap::Packager
+  Error        = Class.new(StandardError)
+  HTTPError    = Class.new(Error)
+  ServiceError = Error.new(Error)
+
+  singleton_class.attr_accessor :endpoint
+  self.endpoint = URI("https://api.jspm.io/generate")
+
+  attr_reader :vendor_path
+
+  def initialize(iconmap_path = "config/iconmap.rb", vendor_path: "vendor/icons")
+    @iconmap_path = Pathname.new(iconmap_path)
+    @vendor_path    = Pathname.new(vendor_path)
+  end
+
+  def import(*packages, env: "production", from: "jspm")
+    response = post_json({
+      "install"      => Array(packages),
+      "flattenScope" => true,
+      "env"          => [ "browser", "module", env ],
+      "provider"     => normalize_provider(from)
+    })
+
+    case response.code
+    when "200"        then extract_parsed_imports(response)
+    when "404", "401" then nil
+    else                   handle_failure_response(response)
+    end
+  end
+
+  def pin_for(package, url)
+    %(pin "#{package}", to: "#{url}")
+  end
+
+  def vendored_pin_for(package, url)
+    filename = package_filename(package)
+    version  = extract_package_version_from(url)
+
+    if "#{package}" == filename
+      %(pin "#{package}" # #{version})
+    else
+      %(pin "#{package}", to: "#{filename}" # #{version})
+    end
+  end
+
+  def packaged?(package)
+    iconmap.match(/^pin ["']#{package}["'].*$/)
+  end
+
+  def download(package, url)
+    ensure_vendor_directory_exists
+    remove_existing_package_file(package)
+    download_package_file(package, url)
+  end
+
+  def remove(package)
+    remove_existing_package_file(package)
+    remove_package_from_iconmap(package)
+  end
+
+  private
+    def post_json(body)
+      Net::HTTP.post(self.class.endpoint, body.to_json, "Content-Type" => "application/json")
+    rescue => error
+      raise HTTPError, "Unexpected transport error (#{error.class}: #{error.message})"
+    end
+
+    def normalize_provider(name)
+      name.to_s == "jspm" ? "jspm.io" : name.to_s
+    end
+
+    def extract_parsed_imports(response)
+      JSON.parse(response.body).dig("map", "imports")
+    end
+
+    def handle_failure_response(response)
+      if error_message = parse_service_error(response)
+        raise ServiceError, error_message
+      else
+        raise HTTPError, "Unexpected response code (#{response.code})"
+      end
+    end
+
+    def parse_service_error(response)
+      JSON.parse(response.body.to_s)["error"]
+    rescue JSON::ParserError
+      nil
+    end
+
+    def iconmap
+      @iconmap ||= File.read(@iconmap_path)
+    end
+
+
+    def ensure_vendor_directory_exists
+      FileUtils.mkdir_p @vendor_path
+    end
+
+    def remove_existing_package_file(package)
+      FileUtils.rm_rf vendored_package_path(package)
+    end
+
+    def remove_package_from_iconmap(package)
+      all_lines = File.readlines(@iconmap_path)
+      with_lines_removed = all_lines.grep_v(/pin ["']#{package}["']/)
+
+      File.open(@iconmap_path, "w") do |file|
+        with_lines_removed.each { |line| file.write(line) }
+      end
+    end
+
+    def download_package_file(package, url)
+      response = Net::HTTP.get_response(URI(url))
+
+      if response.code == "200"
+        save_vendored_package(package, url, response.body)
+      else
+        handle_failure_response(response)
+      end
+    end
+
+    def save_vendored_package(package, url, source)
+      File.open(vendored_package_path(package), "w+") do |vendored_package|
+        vendored_package.write "<!-- #{package}#{extract_package_version_from(url)} downloaded from #{url} -->\n\n"
+
+        vendored_package.write remove_sourcemap_comment_from(source).force_encoding("UTF-8")
+      end
+    end
+
+    def remove_sourcemap_comment_from(source)
+      source.gsub(/^\/\/# sourceMappingURL=.*/, "")
+    end
+
+    def vendored_package_path(package)
+      @vendor_path.join(package_filename(package))
+    end
+
+    def package_filename(package)
+      package.gsub("/", "--")
+    end
+
+    def extract_package_version_from(url)
+      url.match(/@\d+\.\d+\.\d+/)&.to_a&.first
+    end
+end

data/lib/iconmap/reloader.rb

@@ -0,0 +1,23 @@
+require "active_support"
+require "active_support/core_ext/module/delegation"
+
+class Iconmap::Reloader
+  delegate :execute_if_updated, :execute, :updated?, to: :updater
+
+  def reload!
+    icon_map_paths.each { |path| Rails.application.iconmap.draw(path) }
+  end
+
+  private
+    def updater
+      @updater ||= config.file_watcher.new(icon_map_paths) { reload! }
+    end
+
+    def icon_map_paths
+      config.iconmap.paths
+    end
+
+    def config
+      Rails.application.config
+    end
+end

data/lib/iconmap/version.rb

@@ -0,0 +1,3 @@
+module Iconmap
+  VERSION = "0.0.1"
+end

data/lib/iconmap-rails.rb

@@ -0,0 +1,6 @@
+module Iconmap
+end
+
+require_relative "iconmap/version"
+require_relative "iconmap/reloader"
+require_relative "iconmap/engine" if defined?(Rails::Railtie)

data/lib/install/bin/iconmap

@@ -0,0 +1,4 @@
+#!/usr/bin/env ruby
+
+require_relative "../config/application"
+require "iconmap/commands"

data/lib/install/config/iconmap.rb

@@ -0,0 +1,2 @@
+# Pin icons by running ./bin/iconmap
+

data/lib/install/install.rb

@@ -0,0 +1,16 @@
+say "Use vendor/icons for downloaded pins"
+empty_directory "vendor/icons"
+keep_file "vendor/icons"
+
+if (sprockets_manifest_path = Rails.root.join("app/assets/config/manifest.js")).exist?
+  say "Ensure icons are in the Sprocket manifest"
+  append_to_file sprockets_manifest_path,
+    %(//= link_tree ../../../vendor/icons .svg\n)
+end
+
+say "Configure iconmap paths in config/iconmap.rb"
+copy_file "#{__dir__}/config/iconmap.rb", "config/iconmap.rb"
+
+say "Copying binstub"
+copy_file "#{__dir__}/bin/iconmap", "bin/iconmap"
+chmod "bin", 0755 & ~File.umask, verbose: false

data/lib/tasks/iconmap_tasks.rake

@@ -0,0 +1,9 @@
+namespace :iconmap do
+  desc "Setup Iconmap 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,101 @@
+--- !ruby/object:Gem::Specification
+name: iconmap-rails
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+platform: ruby
+authors:
+- Geremia Taglialatela
+bindir: bin
+cert_chain: []
+date: 2025-02-04 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: railties
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 7.1.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 7.1.0
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 7.1.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 7.1.0
+- !ruby/object:Gem::Dependency
+  name: actionpack
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 7.1.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 7.1.0
+email: tagliala.dev@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- MIT-LICENSE
+- README.md
+- Rakefile
+- app/controllers/iconmap/freshness.rb
+- app/helpers/iconmap/iconmap_tags_helper.rb
+- lib/iconmap-rails.rb
+- lib/iconmap/commands.rb
+- lib/iconmap/engine.rb
+- lib/iconmap/map.rb
+- lib/iconmap/npm.rb
+- lib/iconmap/packager.rb
+- lib/iconmap/reloader.rb
+- lib/iconmap/version.rb
+- lib/install/bin/iconmap
+- lib/install/config/iconmap.rb
+- lib/install/install.rb
+- lib/tasks/iconmap_tasks.rake
+homepage: https://github.com/tagliala/iconmap-rails
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/tagliala/iconmap-rails
+  source_code_uri: https://github.com/tagliala/iconmap-rails
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.1.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.3
+specification_version: 4
+summary: Use ESM with importmap to manage modern JavaScript in Rails without transpiling
+  or bundling.
+test_files: []