iconmap-rails 0.0.1 → 0.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ffee894f6afcd5daa549857261eeeb4c663a25992edcc02bd59d442868153d80
-  data.tar.gz: a28499b09beb0cf46259bbd7f16a78afadc5a0965c8529f6cc282cb74d94481f
+  metadata.gz: 5c61ce9e8224c055c3ab34e9be6ded6426502f32239eca9f0f791d97d4c4a9d2
+  data.tar.gz: 0f9799bc47f36f340b97dcd77820d28fc90bde120957fff908d169b9863e5554
 SHA512:
-  metadata.gz: 1b5c60f56f2413639d944e46a6df23174842348399155c42ec64c2817174ee32cdd06b02dd818d1c5043c2886ca8782be22ea04f7dd4de09ebd1376fe9e76424
-  data.tar.gz: a7d1717b47946064e9dd44fe7c2d9c2af513967a17dbe00109aa0add0a6b7b8917d19dab7b23a90c9b1547e7017a650f2050bb48f55fcc8be6f0a5ddd48a81fb
+  metadata.gz: 50de00b8417cafea43086a17b47d038b1e044c96360e755fb634aa7003d7a38aef73e2da9b87779699bcc348245a92e4d113ea3505107f66d9471428c497d027
+  data.tar.gz: 5f6c2a6aaf8868f6d2d5bcece89943d36a33160a97ba71afe90a05db78099f7d5f72888e7a3e2a71b5991c7df9774572004a446f42b37feb8117c732334fd105

data/README.md

@@ -1,266 +1,292 @@
 # Iconmap for Rails
 
-Like [Importmap Rails](https://github.com/rails/importmap-rails), but for Icons.
+Manage SVG icons from npm packages by vendoring them locally and serving them through the Rails asset pipeline.
 
-## Installation
+Iconmap for Rails downloads individual SVG files from npm packages via the [jsdelivr CDN](https://www.jsdelivr.com) and stores them in your Rails application. Icons are referenced by their npm package path and served as static files through Sprockets or Propshaft.
 
-Iconmap for Rails is automatically included in Rails 7+ for new applications, but you can also install it manually in existing applications:
+## Installation
 
 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:
+This creates:
 
-```ruby
-pin "@rails/actioncable", to: "actioncable.esm.js"
-pin "@rails/activestorage", to: "activestorage.esm.js"
-pin "@rails/actiontext", to: "actiontext.esm.js"
-pin "trix"
-```
+- `config/iconmap.rb` — your icon map configuration
+- `vendor/icons/` — where vendored SVG files are stored
+- `bin/iconmap` — CLI for managing icons
 
-## How do iconmaps work?
+Tip: the `bin/iconmap` binstub is safe to commit to your app. Run it from the project root (for example `./bin/iconmap pin ...`).
 
-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:
+## How it works
 
-- Absolute path:
-```js
-import React from "/Users/DHH/projects/basecamp/node_modules/react"
-```
+Iconmap uses a simple pin-based system to vendor single SVG files from npm packages.
 
-- Relative path:
-```js
-import React from "./node_modules/react"
-```
+1. Pin an icon (examples below). The CLI parses the package name, optional version, and icon path, then:
+   - Resolves the package version via the jsdelivr data API when no explicit version is given
+   - Downloads the SVG from `https://cdn.jsdelivr.net/npm/<package>@<version>/<path>`
+   - Writes the file to `vendor/icons/` using a flat filename derived from the package/path (slashes replaced with `--`)
+   - Appends or updates a `pin` line in `config/iconmap.rb` with the resolved version comment
 
-- 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.
+2. Serve icons: `vendor/icons/` is added to the Rails asset paths so vendored SVGs are available via the normal Rails asset helpers.
 
-For example:
+Pin syntax examples (CLI usage shown below):
 
-```rb
-# config/iconmap.rb
-pin "react", to: "https://ga.jspm.io/npm:react@17.0.2/index.js"
+```bash
+./bin/iconmap pin @fortawesome/fontawesome-free/svgs/brands/github.svg
+./bin/iconmap pin @fortawesome/fontawesome-free@6.7.0/svgs/brands/github.svg
+./bin/iconmap pin some-package/icons/logo.svg
 ```
 
-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"`"
+In `config/iconmap.rb` a pin looks like:
 
-```js
-import React from "react"
-// => import React from "https://ga.jspm.io/npm:react@17.0.2/index.js"
+```ruby
+pin '@fortawesome/fontawesome-free/svgs/brands/github.svg' # @6.7.2
 ```
 
-## Usage
+The downloaded filename mirrors the pin but with path separators replaced by `--`, for example:
+`@fortawesome--fontawesome-free--svgs--brands--github.svg` in `vendor/icons/`.
 
-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.
+Notes:
+- Scoped package names (those starting with `@`) are preserved in the filename and mapping.
+- If jsdelivr fails to resolve a package version the CLI will leave the pin without a version comment and print a helpful error.
 
-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.
+## Usage
 
-### Local modules
+All commands are run via the `bin/iconmap` binstub that `iconmap:install` creates.
 
-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.
+### Pinning icons
 
-```rb
-# config/iconmap.rb
-pin_all_from 'app/javascript/src', under: 'src', to: 'src'
-```
+Pin a single icon from an npm package:
 
-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.
+```bash
+./bin/iconmap pin @fortawesome/fontawesome-free/svgs/brands/github.svg
+```
 
-Allows you to:
+Pin a specific version:
 
-```js
-// app/javascript/application.js
-import { ExampleFunction } from 'src/example_function'
+```bash
+./bin/iconmap pin @fortawesome/fontawesome-free@6.7.0/svgs/brands/github.svg
 ```
-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
+Pin multiple icons at once:
 
-Iconmap for Rails downloads and vendors your npm package dependencies via JavaScript CDNs that provide pre-compiled distribution versions.
+```bash
+./bin/iconmap pin \
+  @fortawesome/fontawesome-free/svgs/brands/github.svg \
+  @fortawesome/fontawesome-free/svgs/solid/heart.svg
+```
 
-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).
+After pinning, you will see lines like this in `config/iconmap.rb`:
 
-```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
+```ruby
+pin '@fortawesome/fontawesome-free/svgs/brands/github.svg' # @6.7.2
+pin '@fortawesome/fontawesome-free/svgs/solid/heart.svg'   # @6.7.2
 ```
 
-This will produce pins in your `config/iconmap.rb` like so:
+Referencing vendored icons in Rails views:
 
 ```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
+# use asset_path or image_tag with the vendored filename
+image_tag asset_path('@fortawesome--fontawesome-free--svgs--brands--github.svg')
 ```
 
-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.
+Because `vendor/icons` is added to the app's asset paths the vendored SVGs are available to `asset_path`, `image_tag`, `stylesheet_link_tag`, etc.
+
+Real example — Font Awesome GitHub brand icon
 
-If you later wish to remove a downloaded pin:
+1. Pin the latest Font Awesome GitHub brand SVG:
 
 ```bash
-./bin/iconmap unpin react
-Unpinning and removing "react"
-Unpinning and removing "object-assign"
+./bin/iconmap pin @fortawesome/fontawesome-free/svgs/brands/github.svg
 ```
 
-## Preloading pinned modules
+2. Or pin a specific version (example uses 6.7.0):
 
-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.
+```bash
+./bin/iconmap pin @fortawesome/fontawesome-free@6.7.0/svgs/brands/github.svg
+```
 
-Example:
+The vendored file will be written to `vendor/icons/` with a flattened name, for 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
+```
+@fortawesome--fontawesome-free--svgs--brands--github.svg
+```
 
-# app/views/layouts/application.html.erb
-<%= javascript_iconmap_tags %>
+Because `vendor/icons` is added to the Rails asset paths you can reference the file from views. For inline SVG rendering, we recommend using the `inline_svg` gem (https://github.com/jamesmartin/inline_svg). Example ERB:
 
-# will include the following link before the iconmap is setup:
-<link rel="modulepreload" href="/assets/javascript/@github--hotkey.js">
-...
+```erb
+<%= inline_svg_tag '@fortawesome--fontawesome-free--svgs--brands--github.svg', class: 'icon' %>
 ```
 
-You can also specify which entry points to preload a particular dependency in by providing `preload:` a string or array of strings.
-
-Example:
+Or using asset helpers directly:
 
 ```ruby
-# config/iconmap.rb
-pin "@github/hotkey", to: "@github--hotkey.js", preload: 'application'
-pin "md5", preload: ['application', 'alternate']
+image_tag asset_path('@fortawesome--fontawesome-free--svgs--brands--github.svg'), alt: 'GitHub'
+```
 
-# app/views/layouts/application.html.erb
-<%= javascript_iconmap_tags 'alternate' %>
+### Unpinning icons
 
-# will include the following link before the iconmap is setup:
-<link rel="modulepreload" href="/assets/javascript/md5.js">
-...
+Remove an icon and its vendored file:
+
+```bash
+./bin/iconmap unpin @fortawesome/fontawesome-free/svgs/brands/github.svg
 ```
 
+This removes the matching `pin` line from `config/iconmap.rb` and deletes the vendored SVG file from `vendor/icons/`.
 
+### Checking for outdated icons
 
-## Composing import maps
+Check jsdelivr for newer versions of the npm packages behind your pinned icons:
 
-By default, Rails loads import map definition from the application's `config/iconmap.rb` to the `Iconmap::Map` object available at `Rails.application.iconmap`.
+```bash
+./bin/iconmap outdated
+```
 
-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:
+Example output:
 
-```ruby
-# my_engine/lib/my_engine/engine.rb
+```
+| Icon                                                 | Current | Latest |
+|------------------------------------------------------|---------|--------|
+| @fortawesome/fontawesome-free/svgs/brands/github.svg | 6.7.0   | 6.7.2  |
+  1 outdated icon found
+```
 
-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
+If jsdelivr fails to resolve a version for a package, the table will show an error message in the `Latest` column.
+
+### Updating outdated icons
+
+Re-download icons from packages that have newer versions available and update your pins:
+
+```bash
+./bin/iconmap update
 ```
 
-And pinning JavaScript modules from the engine:
+For each outdated icon, this command:
 
-```ruby
-# my_engine/config/iconmap.rb
+- Downloads the SVG for the latest version
+- Replaces the vendored file in `vendor/icons/`
+- Updates the `# @<version>` comment in `config/iconmap.rb`
+
+### Re-downloading all icons
+
+Re-download every pinned icon from jsdelivr, regardless of version:
 
-pin_all_from File.expand_path("../app/assets/javascripts", __dir__)
+```bash
+./bin/iconmap pristine
 ```
 
+This is useful after checking out a new branch, restoring from backup, or when vendored files may be corrupted.
 
-## Selectively importing modules
+If you commit the vendored files to your repository you will not need to run `pristine` after a fresh checkout; run it only when files are missing or you suspect corruption.
 
-You can selectively import your javascript modules on specific pages.
+### Security audit
 
-Create your javascript in `app/javascript`:
+Check the npm registry for known security vulnerabilities in your pinned packages:
 
-```js
-// /app/javascript/checkout.js
-// some checkout specific js
+```bash
+./bin/iconmap audit
 ```
 
-Pin your js file:
+Example output:
 
-```rb
-# config/iconmap.rb
-# ... other pins...
-pin "checkout", preload: false
+```
+| Package        | Severity | Vulnerable versions | Vulnerability        |
+|----------------|----------|---------------------|----------------------|
+| some-package   | high     | < 2.0.0             | Remote code execution|
+  1 vulnerability found: 1 high
 ```
 
-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.
+The command exits with status 1 when vulnerabilities are found.
 
-```erb
-<% content_for :head do %>
-  <%= javascript_import_module_tag "checkout" %>
-<% end %>
+### Listing pinned packages
+
+Display all pinned icons with their resolved versions:
+
+```bash
+./bin/iconmap packages
 ```
 
-**Important**: The `javascript_import_module_tag` should come after your `javascript_iconmap_tags`
+Example output:
 
-```erb
-<%= javascript_iconmap_tags %>
-<%= yield(:head) %>
+```
+@fortawesome/fontawesome-free 6.7.2 @fortawesome/fontawesome-free/svgs/brands/github.svg
+@fortawesome/fontawesome-free 6.7.2 @fortawesome/fontawesome-free/svgs/solid/heart.svg
 ```
 
+## Configuration
 
-## Include a digest of the import map in your ETag
+### config/iconmap.rb
 
-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:
+The icon map file uses `pin` directives to define vendored icons:
 
 ```ruby
-class ApplicationController < ActionController::Base
-  stale_when_iconmap_changes
-end
+# config/iconmap.rb
+
+# Pin icons by running ./bin/iconmap
+
+# Pin with version comment (automatically added by iconmap)
+
+# Pin without version comment (version will be resolved dynamically)
 ```
 
-This will add the digest of the iconmap to the etag calculation when the request format is HTML.
+Iconmap does not currently support additional pin options (like `preload:` or `to:`) – every pin represents a single SVG at a specific version.
+
+If you need to combine multiple maps (for engines or shared gems) see the "Composing icon maps" section below.
+
+### Cache sweeping
 
+In development and test environments Iconmap can automatically clear its internal caches when files change.
 
-## Sweeping the cache in development and test
+The engine configures:
 
-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`.
+- `config.iconmap.paths` — list of iconmap config files (by default just `config/iconmap.rb`)
+- `config.iconmap.sweep_cache` — whether to set up file watching (defaults to `Rails.env.local?`)
+- `config.iconmap.cache_sweepers` — extra directories to watch in addition to `vendor/icons`
 
-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:
+Behavior:
+
+- An asset watcher clears the map cache when vendored SVGs in `vendor/icons` change (the watcher observes `*.svg`).
+- A dedicated `Iconmap::Reloader` watches the `config.iconmap.paths` (for example `config/iconmap.rb`) and automatically re-draws the map when pin files change — this avoids needing to restart the Rails server after editing pins in development.
+
+To opt out of automatic reloading set `config.iconmap.sweep_cache = false` in your environment config.
+
+## Composing icon maps
+
+By default, Rails loads the icon map from `config/iconmap.rb` into `Rails.application.iconmap`.
+
+You can combine multiple icon maps by adding paths to `Rails.application.config.iconmap.paths`, for example from a 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")
+    initializer 'my-engine.iconmap', before: 'iconmap' do |app|
+      app.config.iconmap.paths << Engine.root.join('config/iconmap.rb')
     end
   end
 end
 ```
 
-## Checking for outdated or vulnerable packages
+The engine's `config/iconmap.rb` can then declare its own pins that will be merged into the main application's icon map.
 
-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
+## Rails integration
 
-## Supporting legacy browsers such as Safari on iOS 15
+Iconmap for Rails integrates via a Rails engine (`Iconmap::Engine`) that:
 
-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.
+1. **Defines `Rails.application.iconmap`** as an `Iconmap::Map` instance.
+2. **Loads pin definitions** from all paths in `config.iconmap.paths` (by default `config/iconmap.rb`).
+3. **Adds `vendor/icons` to the asset pipeline** so your SVGs are served like any other asset.
+4. **Optionally sets up a cache sweeper** in development and test that watches icon files and clears the map cache when they change.
 
-```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 %>
+### Accessing the icon map
+
+```ruby
+iconmap = Rails.application.iconmap
+iconmap.packages #=> hash of pin name -> MappedFile
 ```
 
+The `Iconmap::Map` API is intentionally small and internal – most applications should interact with icons via the CLI and asset helpers, not by manipulating the map directly.
+
 ## License
 
 Iconmap for Rails is released under the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -1,13 +1,15 @@
-require "bundler/setup"
+# frozen_string_literal: true
 
-APP_RAKEFILE = File.expand_path("test/dummy/Rakefile", __dir__)
-load "rails/tasks/engine.rake"
+require 'bundler/setup'
 
-load "rails/tasks/statistics.rake"
+APP_RAKEFILE = File.expand_path('test/dummy/Rakefile', __dir__)
+load 'rails/tasks/engine.rake'
 
-require "bundler/gem_tasks"
+load 'rails/tasks/statistics.rake'
 
-require "rake/testtask"
+require 'bundler/gem_tasks'
+
+require 'rake/testtask'
 
 Rake::TestTask.new(:test) do |t|
   t.libs << 'test'