fontico 0.1.1 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e650a7b2e4dd27bd57a0318811c9e5557b229c7b21151fd40b670f6d513532b1
-  data.tar.gz: 0a59aa8f304d339c3d5a151c3359473c585ef1c9fe438252d24147a19462c937
+  metadata.gz: 3ad5f56ad9c1523dbd17d2cdb07da3a2d6aac315008ebd08ba84551d125083c0
+  data.tar.gz: 207804df603f81d1da9117d5b081a73dbcf649bf882dbeb43fdec33678fcacb4
 SHA512:
-  metadata.gz: 07f21c106e47d7dbc23e73a0c8d091d7b9284bc6a32b0d2fde04a7fef5fc9d11e3b650a9e223dfd204214511d35ae454ffa67602e2e0e48426295456cd72d682
-  data.tar.gz: fccdc71296e585a335f9a7539234ced2cf6fe1e8f51721aa288825cb840e9a3866db1e31cd1c947e2293383828068dcd112263d31cfeffbfa2548c04e1be913a
+  metadata.gz: 4a4bf9595c5257803d26ff2c79607d0a44b48b0c4bc7b1584ce9a71e6e61f18fd71447884eba9d9e48d296a5aec6c42ad6973b7c82e197443be02c6b1032756e
+  data.tar.gz: 3132cfd1d3a9fa3997a23ed450fa749416aac364414b883e5c65e6995b7708cbbb4155ed672de376c0089543ea3b36167cc1d93deb055e402529ca705685f030

data/README.md

@@ -1,6 +1,20 @@
-# fontico
+<div align="center">
 
-Name icons by intent. Source them from anywhere. Ship one artifact.
+```
+╔═╗╔═╗╔╗╔╔╦╗╦╔═╗╔═╗
+╠╣ ║ ║║║║ ║ ║║  ║ ║
+╚  ╚═╝╝╚╝ ╩ ╩╚═╝╚═╝
+```
+
+**Name icons by intent. Source them from anywhere. Ship one artifact.**
+
+[![Gem](https://img.shields.io/gem/v/fontico)](https://rubygems.org/gems/fontico)
+[![CI](https://github.com/fireho/fontico/actions/workflows/ci.yml/badge.svg)](https://github.com/fireho/fontico/actions/workflows/ci.yml)
+[![License](https://img.shields.io/badge/license-MIT-blue)](LICENSE.txt)
+
+</div>
+
+---
 
 ```erb
 <%= icon "save" %>      <%# Lucide            %>
@@ -11,6 +25,30 @@ Name icons by intent. Source them from anywhere. Ship one artifact.
 Three providers, one call. Templates never name a vendor, so re-skinning the
 app — or surviving an upstream rename — is a diff in one file.
 
+| | |
+| --- | --- |
+| **353,000 icons** | any of [Iconify's 238 sets](https://icon-sets.iconify.design/), plus your own folder |
+| **One request** | a single sprite, 2.3KB brotli, not render-blocking |
+| **361ms cold, 2ms warm** | measured on 35 icons across two remote providers and five local files |
+| **No Node, no npm** | the sprite target is pure Ruby; deploys rebuild offline from the lockfile |
+| **Also PDFs** | a real TTF for Prawn, with pinned codepoints |
+
+## Install
+
+```ruby
+# Gemfile
+gem "fontico"
+```
+
+```bash
+bundle install
+$EDITOR icons.yml     # the manifest, below
+rake fontico:build
+```
+
+No JS bundle, no `package.json`, no importmap pin. Artifacts land in
+`app/assets/builds/`, which Propshaft already serves.
+
 ## The manifest
 
 `icons.yml`, one line per icon:
@@ -35,26 +73,25 @@ icons:
 ```
 
 Like pokemon, you gotta catch 'em all.
-Any of [Iconify's 200k+ icons](https://icon-sets.iconify.design/) work as a
-provider prefix. Your own SVGs go in `app/assets/icons/`, filename as slug.
+Any of [Iconify's sets](https://icon-sets.iconify.design/) work as a provider
+prefix. Your own SVGs go in `app/assets/icons/`, filename as slug.
+
+A Rails engine that ships `config/icons.yml` (or `icons.yml` at its root) is
+merged under the app's file, the same way `config/locales/` layers. Later
+wins a name — the app always has the last word. Nested groups merge, so an
+engine can ship `auth.google` and the app can add `auth.apple` without
+copying the rest. `rake fontico:build` reads the same list.
 
 ## Build
 
 ```bash
 rake fontico:build     # resolve, normalise, emit
-rake fontico:update    # re-fetch, ignoring icons.lock
+rake fontico:update    # re-fetch bodies; codepoints stay pinned
 ```
 
-Artifacts land in `app/assets/builds/`, which Propshaft serves automatically —
-no manifest, no precompile list. `rake assets:precompile` is hooked, so deploys
-need no extra step.
-
-That directory is gitignored in a stock Rails app, so nothing is committed from
-it. **`icons.lock` is the thing you commit**: it holds every normalised body,
-so a deploy rebuilds the sprite from it in milliseconds with no network access
-and no Node.
+`rake assets:precompile` is hooked, so deploys need no extra step.
 
-In development you rarely type either one. Saving `icons.yml` — or a local
+**In development you rarely type either one.** Saving `icons.yml` — or a local
 SVG — rebuilds the artifacts and drops the cached manifest, so the icon is live
 on the next request: no rake, no restart. A save that only reshuffles known
 icons costs a couple of milliseconds; a brand-new one pays its provider fetch
@@ -73,13 +110,14 @@ there — is named in red and left out; the rest of the manifest still builds.
 It keeps its codepoint reserved, so fixing the entry and rebuilding brings it
 back with the same glyph. A provider that is unreachable is still fatal.
 
-Measured on 35 icons across two remote providers and five local files:
-**361ms cold, 2ms warm.** Vendor icons are fetched in one batched request per
-provider — not one per icon.
+Vendor icons are fetched in one batched request per provider — not one per
+icon.
 
 ## Why there is a lockfile
 
-`icons.lock` pins two things that must not drift:
+`app/assets/builds/` is gitignored in a stock Rails app, so nothing is
+committed from it. **`icons.lock` is the thing you commit.** It pins two things
+that must not drift:
 
 - **Codepoints**, append-only. Adding an icon must not renumber the others, or
   every glyph in a built font moves and the committed artifact churns
@@ -88,7 +126,8 @@ provider — not one per icon.
   Iconify API serves *latest*; without this an icon can silently change shape
   between two builds of the same manifest.
 
-Commit it.
+A deploy rebuilds the sprite from it in milliseconds, with no network access
+and no Node. Commit it.
 
 ## What happens to your SVGs
 
@@ -204,12 +243,27 @@ build names each one it dropped.
 Font targets need Node, installed on demand into `~/.cache/fontico`. A manifest
 with `targets: [sprite]` never touches it and stays pure Ruby.
 
+## How it compares
+
+| | vendor gems (`lucide-rails`, `heroicon`) | `iconify-icon` web component | fontico |
+| --- | --- | --- | --- |
+| Icon sets | one, per gem | 238 | 238, plus your own folder |
+| Where the SVG comes from | inlined per render | fetched at runtime, per client | one build-time sprite |
+| Requests | 0, but repeated in every response body | 1+ per icon, per visitor | 1, cached |
+| JS required | no | yes | no |
+| Rename-proof templates | no — `lucide_icon "pencil"` | no — `icon="lucide:pencil"` | yes — `icon "edit"` |
+| Offline / reproducible build | yes | no | yes, via `icons.lock` |
+| PDF | no | no | yes, TTF for Prawn |
+
 ## Status
 
 - ✅ Manifest, resolver, preprocessor, lockfile, sprite emitter, Rails helper
 - ✅ TTF emitter with glyph extraction, codepoint API, Prawn helpers
 - ⏳ `woff2` — declared targets are skipped with a notice
+- ⏳ `variant:` — accepted and ignored by the helper; see [TODO.md](TODO.md)
 
 ## License
 
-MIT
+MIT.
+Icons keep their upstream licenses:
+`icons.lock` records what you declared and shipped.

data/lib/fontico/builder.rb

@@ -12,11 +12,13 @@ module Fontico
     Report = Struct.new(:written, :warnings, :skipped, :cached, :fetched, :pending,
                         :missing, keyword_init: true)
 
-    def initialize(manifest, root: Dir.pwd, output: "app/assets/builds", offline: false)
+    def initialize(manifest, root: Dir.pwd, output: "app/assets/builds",
+                   offline: false, force: false)
       @manifest = manifest
       @root = root
       @output = File.join(root, output)
       @offline = offline
+      @force = force
       @lock = Lockfile.new(File.join(root, "icons.lock"))
     end
 
@@ -25,11 +27,23 @@ module Fontico
       cached, fetched = [], []
       missing = {}
 
-      stale = @manifest.icons.reject { @lock.fresh?(_1.name, _1.source) }
+      # The lock caches Iconify bodies so deploys run offline. Local files
+      # are already on disk: treating them as fresh meant editing logo.svg
+      # rebuilt nothing. Force is `rake fontico:update` — re-fetch remotes,
+      # keep the append-only codepoints.
+      stale = @manifest.icons.select { _1.local? || @force || !@lock.fresh?(_1.name, _1.source) }
       cached = @manifest.icons.map(&:name) - stale.map(&:name)
 
       unless stale.empty?
-        raise Error, "icons.lock is missing #{stale.size} icon(s) and --offline was given" if @offline
+        remote_stale = stale.reject(&:local?)
+        # Local files do not need the network. Offline is a hard fail only
+        # when a remote body has to come off the wire — which under force is
+        # every remote, lock or no lock. Saying "missing" there would be a
+        # lie: the bodies are present, force is what made them stale.
+        if @offline && remote_stale.any?
+          reason = @force ? "re-fetch #{remote_stale.size} icon(s)" : "resolve #{remote_stale.size} icon(s) missing from icons.lock"
+          raise Error, "cannot #{reason} and --offline was given"
+        end
 
         resolver = Resolver.new(@manifest, root: @root)
         sources = resolver.call(only: stale.map(&:name))
@@ -43,9 +57,16 @@ module Fontico
 
           pre = Preprocessor.new(icon, size: @manifest.size)
                             .call(src.markup, width: src.width, height: src.height)
+          # Locals are re-read every build, so "stale" does not mean changed.
+          # Compare the stored digest to keep an untouched logo.svg counted as
+          # cached rather than reported as a fetch that never happened. A
+          # remote is judged by the wire, not the digest: under force it was
+          # genuinely re-fetched even when it came back byte-identical.
+          before = @lock.entry(icon.name)&.fetch("digest", nil)
           @lock.store(icon.name, source: icon.source, body: pre.body,
                       multicolor: pre.multicolor, warnings: pre.warnings)
-          fetched << icon.name
+          unchanged = icon.local? && @lock.entry(icon.name)["digest"] == before
+          (unchanged ? cached : fetched) << icon.name
         end
       end
 

data/lib/fontico/emitters/font.rb

@@ -26,9 +26,16 @@ module Fontico
         outlines = @outliner.outlines(@build, size: @manifest.size)
 
         glyphs = @build.map do |icon, body|
-          { name: icon.key,
-            codepoint: @lock.codepoint_for(icon.name),
-            svg: document(outlines[icon.name], body) }
+          # Never fall back to allocating here. The builder has already
+          # save!d the lock by the time it emits, so a codepoint minted now
+          # would never reach disk: the font would ship a glyph that
+          # Fontico.glyph cannot name. A nil is worse still — it reaches
+          # String.fromCodePoint as null and maps the glyph to U+0000
+          # without complaint.
+          cp = @lock.codepoint_for(icon.name)
+          raise Fontico::Error, "#{icon.name} has no codepoint in icons.lock" if cp.nil?
+
+          { name: icon.key, codepoint: cp, svg: document(outlines[icon.name], body) }
         end
 
         result = @outliner.instance_variable_get(:@runner)

data/lib/fontico/lockfile.rb

@@ -29,7 +29,13 @@ module Fontico
       @entries    = data["icons"]      || {}
     end
 
-    def codepoint_for(name)
+    # Lookup only. A missing name is nil — callers that draw a glyph must
+    # not invent a codepoint, or a typo silently becomes a .notdef.
+    def codepoint_for(name) = @codepoints[name]
+
+    # Append-only reservation. store is the production caller; tests use it
+    # to pin order without going through a full build.
+    def allocate(name)
       @codepoints[name] ||= next_free
     end
 
@@ -43,7 +49,7 @@ module Fontico
         "warnings"   => warnings,
         "body"       => body
       }
-      codepoint_for(name)
+      allocate(name)
     end
 
     # Names present in the lock but absent from the manifest keep their

data/lib/fontico/manifest.rb

@@ -13,7 +13,28 @@ module Fontico
 
     attr_reader :path, :defaults, :providers, :targets, :icons
 
-    def self.load(path) = new(YAML.safe_load_file(path), path: path)
+    def self.load(*paths)
+      paths = paths.flatten.compact.select { File.file?(_1) }
+      raise Errno::ENOENT, "icons.yml" if paths.empty?
+
+      data = paths.map { YAML.safe_load_file(_1) || {} }.reduce { |a, b| merge_data(a, b) }
+      new(data, path: paths.last)
+    end
+
+    # Later overlay wins a leaf; nested groups merge so an engine can ship
+    # `auth.google` and the app can add `auth.apple` without copying.
+    def self.merge_data(base, overlay)
+      {
+        "defaults" => (base["defaults"] || {}).merge(overlay["defaults"] || {}),
+        "targets" => overlay["targets"] || base["targets"] || ["sprite"],
+        "providers" => (base["providers"] || {}).merge(overlay["providers"] || {}),
+        "icons" => deep_merge(base["icons"] || {}, overlay["icons"] || {})
+      }
+    end
+
+    def self.deep_merge(left, right)
+      left.merge(right) { |_, a, b| a.is_a?(Hash) && b.is_a?(Hash) ? deep_merge(a, b) : b }
+    end
 
     def initialize(data, path: nil)
       @path      = path

data/lib/fontico/railtie.rb

@@ -12,6 +12,12 @@ module Fontico
       Fontico.root = Rails.root.to_s
     end
 
+    # Engines' config/icons.yml under the app's icons.yml. After root: the
+    # app file is Rails.root/icons.yml, not whatever Dir.pwd was at require.
+    initializer "fontico.load_path", after: "fontico.root" do |app|
+      Fontico.load_path = Fontico.discover(app)
+    end
+
     # Saving icons.yml — or a local SVG — rebuilds the artifacts and drops the
     # memoized manifest, so a new icon is live on the next request with no
     # restart and no rake. That memo is the only thing that ever needed one:
@@ -20,7 +26,7 @@ module Fontico
     initializer "fontico.reloader" do |app|
       next unless app.config.enable_reloading
 
-      watcher = app.config.file_watcher.new([Fontico.manifest_path], Railtie.local_dirs) do
+      watcher = app.config.file_watcher.new(Fontico.load_path, Railtie.local_dirs) do
         Fontico.reset!
         Fontico.rebuild!
         # Recorded rather than raised: a save that half-breaks the manifest

data/lib/fontico/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Fontico
-  VERSION = "0.1.1"
+  VERSION = "0.2.0"
 end

data/lib/fontico.rb

@@ -34,9 +34,35 @@ module Fontico
     def root          = @root ||= Dir.pwd
     def output_dir    = @output_dir ||= "app/assets/builds"
     def manifest_path = @manifest_path ||= File.join(root, "icons.yml")
-    def manifest      = @manifest ||= Manifest.load(manifest_path)
+    # Same shape as I18n.load_path: engines first, the app last, later wins
+    # a name. Unset, it is just the app's icons.yml (non-Rails, tests).
+    def load_path     = @load_path || [manifest_path].select { File.file?(_1) }
+
+    def load_path=(paths)
+      @load_path = paths.nil? ? nil : Array(paths)
+      reset!
+    end
+
+    def manifest      = @manifest ||= Manifest.load(*load_path)
     def sprite_file   = File.join(root, output_dir, "icons.svg")
 
+    # Rails engines that ship config/icons.yml (or icons.yml at the gem
+    # root), then the app's file. The app is last on purpose.
+    def discover(app)
+      files = []
+      app.railties.each do |rt|
+        next unless rt.is_a?(Rails::Engine)
+        next if rt.is_a?(Rails::Application)
+
+        root = rt.root
+        found = %w[config/icons.yml icons.yml].map { root.join(_1) }.find { File.file?(_1.to_s) }
+        files << found.to_s if found
+      end
+      # manifest_path goes in even when absent: the dev watcher has to notice
+      # an icons.yml created after boot. Manifest.load skips what isn't there.
+      (files.select { File.file?(_1) } << manifest_path).uniq
+    end
+
     # Inline mode embeds <symbol> definitions in the layout instead of
     # referencing an external file — required when assets are served from a
     # CDN, where cross-origin <use href> silently renders nothing.
@@ -85,7 +111,7 @@ module Fontico
     # a reference in Ruby source never goes stale.
     def codepoint(name)
       cp = lockfile.codepoint_for(name.to_s)
-      raise Error, "no icon named #{name.inspect}; run rake fontico:build" if cp.nil?
+      raise Error, "no icon named #{name.inspect} in icons.lock" if cp.nil?
 
       cp
     end

data/lib/tasks/fontico.rake

@@ -4,43 +4,52 @@
 # is noise, and the message reads fine without it.
 def fontico_red(text) = $stdout.tty? ? "\e[31m#{text}\e[0m" : text
 
-namespace :fontico do
-  desc "Build icon artifacts from icons.yml"
-  task :build do
-    require "fontico"
-    report = Fontico.build
+def fontico_print_report(report)
+  puts "fontico: #{report.written.size} artifact(s)"
+  report.written.each { puts "  #{_1}" }
+  puts "  fetched #{report.fetched.size}, cached #{report.cached.size}"
 
-    puts "fontico: #{report.written.size} artifact(s)"
-    report.written.each { puts "  #{_1}" }
-    puts "  fetched #{report.fetched.size}, cached #{report.cached.size}"
+  # Loud, but not fatal: one bad name should not stop the other 199 icons
+  # from building. The artifacts simply come out without it.
+  if report.missing&.any?
+    puts
+    puts fontico_red("fontico: #{report.missing.size} icon(s) could not be resolved and were left out:")
+    report.missing.each { |name, reason| puts fontico_red("  #{name}: #{reason}") }
+    puts fontico_red("  fix the entry in icons.yml, then run rake fontico:build again")
+    puts
+  end
 
-    # Loud, but not fatal: one bad name should not stop the other 199 icons
-    # from building. The artifacts simply come out without it.
-    if report.missing&.any?
-      puts
-      puts fontico_red("fontico: #{report.missing.size} icon(s) could not be resolved and were left out:")
-      report.missing.each { |name, reason| puts fontico_red("  #{name}: #{reason}") }
-      puts fontico_red("  fix the entry in icons.yml, then run rake fontico:build again")
-      puts
-    end
+  report.skipped.each do |target, names|
+    puts "  #{target}: skipped #{names.size} multicolor icon(s): #{names.join(", ")}" if names.any?
+  end
+  puts "  pending target(s): #{report.pending.join(", ")}" if report.pending.any?
 
-    report.skipped.each do |target, names|
-      puts "  #{target}: skipped #{names.size} multicolor icon(s): #{names.join(", ")}" if names.any?
-    end
-    puts "  pending target(s): #{report.pending.join(", ")}" if report.pending.any?
+  if report.warnings.any?
+    puts "\nfontico: #{report.warnings.size} icon(s) need fixing at the source:"
+    report.warnings.each { |name, list| puts "  #{name}: #{list.join("; ")}" }
+    puts "  see docs/icon-authoring.html"
+  end
+end
 
-    if report.warnings.any?
-      puts "\nfontico: #{report.warnings.size} icon(s) need fixing at the source:"
-      report.warnings.each { |name, list| puts "  #{name}: #{list.join("; ")}" }
-      puts "  see docs/icon-authoring.html"
-    end
+def fontico_rails_load_path!
+  return unless defined?(Rails) && Rails.respond_to?(:application) && Rails.application
+
+  Fontico.load_path = Fontico.discover(Rails.application)
+end
+
+namespace :fontico do
+  desc "Build icon artifacts from icons.yml"
+  task :build do
+    require "fontico"
+    fontico_rails_load_path!
+    fontico_print_report(Fontico.build)
   end
 
-  desc "Re-fetch every icon, ignoring icons.lock"
+  desc "Re-fetch every icon from its provider. Codepoints stay pinned."
   task :update do
     require "fontico"
-    File.delete(File.join(Fontico.root, "icons.lock")) if File.exist?(File.join(Fontico.root, "icons.lock"))
-    Rake::Task["fontico:build"].invoke
+    fontico_rails_load_path!
+    fontico_print_report(Fontico.build(force: true))
   end
 end
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: fontico
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.2.0
 platform: ruby
 authors:
 - nofxx
@@ -126,7 +126,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.7
+rubygems_version: 3.6.9
 specification_version: 4
 summary: Name icons by intent. Source them from anywhere. Ship one artifact.
 test_files: []