fontico 0.1.0

data/lib/fontico/resolver.rb

@@ -0,0 +1,148 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "uri"
+require "json"
+
+module Fontico
+  # Turns manifest entries into raw SVG. Vendor icons come from the Iconify
+  # API in one batched request per provider; first-party icons come off disk.
+  class Resolver
+    class Error < Fontico::Error; end
+
+    API = "https://api.iconify.design"
+
+    # Guards a malformed set; real chains are one or two hops.
+    MAX_ALIAS_DEPTH = 8
+
+    Source = Struct.new(:markup, :width, :height, keyword_init: true)
+
+    # { "save" => "lucide/save: not found in provider lucide" } — icons this
+    # run could not resolve. Filled by #call; see the comment there.
+    attr_reader :missing
+
+    def initialize(manifest, root: Dir.pwd, api: API)
+      @manifest = manifest
+      @root = root
+      @api = api
+      @missing = {}
+    end
+
+    # => { "save" => Source, ... } keyed by icon name.
+    #
+    # One bad name in a manifest of two hundred used to take the whole build
+    # down, which meant a typo in an icon nobody had shipped yet blocked
+    # everyone. A single icon failing is now recorded in #missing and left
+    # out of the result; the caller reports it and builds the rest. Failures
+    # that are not per-icon — an unreachable API, a provider that 404s — are
+    # still raised, because then nothing would be correct.
+    def call(only: nil)
+      icons = @manifest.icons
+      icons = icons.select { only.include?(_1.name) } if only
+
+      resolved = {}
+      icons.select(&:local?).each do |icon|
+        try(icon) { resolved[icon.name] = local(icon) }
+      end
+
+      icons.reject(&:local?).group_by(&:provider).each do |provider, group|
+        payload = fetch(provider, group.map(&:slug).uniq.sort)
+        group.each { |icon| try(icon) { resolved[icon.name] = remote(icon, payload) } }
+      end
+
+      resolved
+    end
+
+    private
+
+    def try(icon)
+      yield
+    rescue Error => e
+      @missing[icon.name] = e.message
+      nil
+    end
+
+    def local(icon)
+      path = File.join(@root, @manifest.local_path, "#{icon.slug}.svg")
+      raise Error, "#{icon.source}: no such file #{path}" unless File.exist?(path)
+
+      Source.new(markup: File.read(path))
+    end
+
+    # One request per provider, not per icon. 30 icons across two providers
+    # measured at ~0.9s and 7KB total.
+    def fetch(provider, slugs)
+      uri = URI("#{@api}/#{provider}.json?icons=#{slugs.join(",")}")
+      body = Net::HTTP.get_response(uri).then do |res|
+        raise Error, "#{provider}: API returned #{res.code}" unless res.is_a?(Net::HTTPSuccess)
+
+        res.body
+      end
+      JSON.parse(body)
+    rescue JSON::ParserError, SocketError, Errno::ECONNREFUSED => e
+      raise Error, "#{provider}: could not reach #{@api} (#{e.class}). " \
+                   "Run with a populated icons.lock to build offline."
+    end
+
+    def remote(icon, payload)
+      data, transform = lookup(icon, payload)
+      raise Error, "#{icon.source}: not found in provider #{icon.provider}" if data.nil?
+
+      # Per-icon dimensions override the set default; fa6-solid ships 512
+      # sets with 576 icons inside them.
+      width  = data["width"]  || payload["width"]
+      height = data["height"] || payload["height"]
+
+      Source.new(
+        markup: apply(transform, data.fetch("body"), width, height),
+        width: width,
+        height: height
+      )
+    end
+
+    # Iconify keeps renames and mirrored variants out of "icons" and in
+    # "aliases", pointing at a parent that may itself be an alias. Without
+    # this, `lucide/fingerprint` — an alias since the icon was renamed to
+    # fingerprint-pattern — resolves to nothing and the build dies.
+    def lookup(icon, payload)
+      slug = icon.slug
+      transform = {}
+      seen = []
+
+      MAX_ALIAS_DEPTH.times do
+        return [payload.dig("icons", slug), transform] if payload.dig("icons", slug)
+
+        entry = payload.dig("aliases", slug)
+        return [nil, transform] if entry.nil?
+
+        # A transform is expressed relative to the parent, so an alias chain
+        # composes outwards: rotation adds, each flip toggles.
+        transform[:rotate] = (transform[:rotate].to_i + entry["rotate"].to_i) % 4
+        transform[:h_flip] = transform[:h_flip] ^ true if entry["hFlip"]
+        transform[:v_flip] = transform[:v_flip] ^ true if entry["vFlip"]
+
+        seen << slug
+        slug = entry["parent"]
+        raise Error, "#{icon.source}: alias cycle #{(seen << slug).join(" -> ")}" if seen.include?(slug)
+      end
+
+      raise Error, "#{icon.source}: alias chain deeper than #{MAX_ALIAS_DEPTH} in #{icon.provider}"
+    end
+
+    # Flip about the box centre, then rotate about it in quarter turns —
+    # the order Iconify defines. Emitted as one wrapping <g> so the body
+    # itself is untouched and still normalises like any other.
+    def apply(transform, body, width, height)
+      return body if transform.empty? || transform.values.none? { _1 == true || _1.to_i.positive? }
+
+      w = (width || 24).to_f
+      h = (height || 24).to_f
+      ops = []
+      ops << "rotate(#{transform[:rotate] * 90} #{w / 2} #{h / 2})" if transform[:rotate].to_i.positive?
+      ops << "translate(#{w} 0) scale(-1 1)" if transform[:h_flip]
+      ops << "translate(0 #{h}) scale(1 -1)" if transform[:v_flip]
+
+      %(<g transform="#{ops.join(" ")}">#{body}</g>)
+    end
+  end
+end

data/lib/fontico/version.rb

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

data/lib/fontico.rb

@@ -0,0 +1,100 @@
+# frozen_string_literal: true
+
+require "erb"
+require_relative "fontico/version"
+
+module Fontico
+  class Error < StandardError; end
+
+  autoload :Icon,         "fontico/icon"
+  autoload :Manifest,     "fontico/manifest"
+  autoload :Preprocessor, "fontico/preprocessor"
+  autoload :Resolver,     "fontico/resolver"
+  autoload :Lockfile,     "fontico/lockfile"
+  autoload :Builder,      "fontico/builder"
+  autoload :Helper,       "fontico/helper"
+  autoload :NodeRunner,   "fontico/node_runner"
+  autoload :ProviderFonts, "fontico/provider_fonts"
+  autoload :Outliner,     "fontico/outliner"
+  # fontico/prawn is opt-in: `require "fontico/prawn"`, so the gem never
+  # loads Prawn for apps that only build a sprite.
+
+  module Emitters
+    autoload :Sprite,     "fontico/emitters/sprite"
+    autoload :Font,       "fontico/emitters/font"
+    autoload :Stylesheet, "fontico/emitters/stylesheet"
+  end
+
+  class << self
+    attr_writer :manifest_path, :root, :output_dir, :inline_sprite, :css_class
+
+    # Base class on every emitted <svg>; also the stylesheet's selector.
+    def css_class = @css_class ||= "ico"
+
+    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)
+    def sprite_file   = File.join(root, output_dir, "icons.svg")
+
+    # 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.
+    def inline_sprite? = !!@inline_sprite
+
+    def build(**opts) = Builder.new(manifest, root: root, output: output_dir, **opts).call
+
+    # The dev reloader's build, and the only caller that records what went
+    # wrong. Building stays forgiving on purpose — one typo must not stop the
+    # other 199 icons — so nothing raises here; the complaint is held until
+    # someone actually draws an icon. See #check!.
+    def rebuild!
+      @build_error = nil
+      @missing_icons = build.missing || {}
+    rescue StandardError => e
+      @build_error = e
+      @missing_icons = {}
+    end
+
+    # Why the last rebuild could not deliver: the exception it died on, and
+    # the icons it left out of the sprite.
+    attr_reader :build_error
+
+    def missing_icons = @missing_icons ||= {}
+
+    # Raised at the call site, because that is the only place with anything
+    # useful to say. An icon left out of the sprite still resolves through the
+    # manifest and renders a perfectly valid <use> at a symbol that isn't
+    # there — an invisible empty box, on a page that 200s. Silence is the one
+    # outcome worse than a stack trace.
+    #
+    # Free in production: only the dev reloader ever fills these in.
+    def check!(name = nil)
+      raise Error, "icons.yml did not build: #{@build_error.message}" if @build_error
+
+      reason = missing_icons[name]
+      raise Error, "icon #{name.inspect} was left out of the sprite: #{reason}" if reason
+    end
+
+    def lockfile = Lockfile.new(File.join(root, "icons.lock"))
+
+    def font_file = File.join(root, output_dir, "icons.ttf")
+
+    # The character to print when drawing this icon from the font — for Prawn,
+    # where you write the glyph literally. Pinned append-only in icons.lock so
+    # 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?
+
+      cp
+    end
+
+    def glyph(name) = [codepoint(name)].pack("U")
+    def reset!        = (@manifest = @build_error = @missing_icons = nil)
+
+    def configure = yield(self)
+  end
+end
+
+require "fontico/railtie" if defined?(::Rails::Railtie)

data/lib/tasks/fontico.rake

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+# Only when someone is watching: a colour escape in a CI log or a piped file
+# 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
+
+    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
+
+    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
+
+  desc "Re-fetch every icon, ignoring icons.lock"
+  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
+  end
+end
+
+# Deploys just work: Propshaft serves whatever is in app/assets/builds, and
+# that directory is gitignored in a stock Rails app, so the artifacts have to
+# be regenerated during precompile rather than committed.
+#
+# Same hook jsbundling-rails uses for javascript:build.
+if Rake::Task.task_defined?("assets:precompile")
+  Rake::Task["assets:precompile"].enhance(["fontico:build"])
+end
+
+if Rake::Task.task_defined?("assets:clobber")
+  Rake::Task["assets:clobber"].enhance(["fontico:clobber"])
+end
+
+namespace :fontico do
+  desc "Remove generated icon artifacts (icons.lock is kept: it is source)"
+  task :clobber do
+    require "fontico"
+    %w[icons.svg icons.css icons.ttf].each do |name|
+      path = File.join(Fontico.root, Fontico.output_dir, name)
+      File.delete(path) if File.exist?(path)
+    end
+  end
+end

metadata

@@ -0,0 +1,132 @@
+--- !ruby/object:Gem::Specification
+name: fontico
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- nofxx
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rexml
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.2'
+- !ruby/object:Gem::Dependency
+  name: prawn
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.5'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.5'
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.79'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.79'
+- !ruby/object:Gem::Dependency
+  name: rubocop-performance
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.25'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.25'
+description: Declare every icon in your app in one manifest — from Lucide, Material
+  Symbols, any Iconify set, or your own SVG folder — under names you choose. fontico
+  resolves, normalises and merges them into a single build artifact, so templates
+  never name a vendor.
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE.txt
+- README.md
+- docs/expand-check.png
+- docs/icon-authoring.html
+- docs/lucide-glyphs-extracted.png
+- docs/lucide-ttf-glyph.png
+- docs/rails-preview.png
+- docs/sprite-sheet.png
+- docs/stroke-vs-fill.png
+- docs/ttf-glyphs.png
+- lib/fontico.rb
+- lib/fontico/builder.rb
+- lib/fontico/emitters/font.rb
+- lib/fontico/emitters/sprite.rb
+- lib/fontico/emitters/stylesheet.rb
+- lib/fontico/helper.rb
+- lib/fontico/icon.rb
+- lib/fontico/lockfile.rb
+- lib/fontico/manifest.rb
+- lib/fontico/node/build_font.mjs
+- lib/fontico/node/extract_glyphs.mjs
+- lib/fontico/node/package.json
+- lib/fontico/node_runner.rb
+- lib/fontico/outliner.rb
+- lib/fontico/prawn.rb
+- lib/fontico/preprocessor.rb
+- lib/fontico/provider_fonts.rb
+- lib/fontico/railtie.rb
+- lib/fontico/resolver.rb
+- lib/fontico/version.rb
+- lib/tasks/fontico.rake
+homepage: https://github.com/fireho/fontico
+licenses:
+- MIT
+metadata:
+  source_code_uri: https://github.com/fireho/fontico
+  bug_tracker_uri: https://github.com/fireho/fontico/issues
+  changelog_uri: https://github.com/fireho/fontico/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.1'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.7
+specification_version: 4
+summary: Name icons by intent. Source them from anywhere. Ship one artifact.
+test_files: []