fontico 0.1.0

data/lib/fontico/builder.rb

@@ -0,0 +1,115 @@
+# frozen_string_literal: true
+
+require "fileutils"
+
+module Fontico
+  # Resolve -> preprocess -> lock -> emit. Everything the rake task does.
+  class Builder
+    # Declared in manifests, emitter not landed yet. Skipped with a notice so
+    # the manifest can state intent without breaking the build.
+    PENDING = %w[woff2].freeze
+
+    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)
+      @manifest = manifest
+      @root = root
+      @output = File.join(root, output)
+      @offline = offline
+      @lock = Lockfile.new(File.join(root, "icons.lock"))
+    end
+
+    def call
+      warnings = Hash.new { |h, k| h[k] = [] }
+      cached, fetched = [], []
+      missing = {}
+
+      stale = @manifest.icons.reject { @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
+
+        resolver = Resolver.new(@manifest, root: @root)
+        sources = resolver.call(only: stale.map(&:name))
+        missing = resolver.missing
+        stale.each do |icon|
+          src = sources[icon.name]
+          # Named in #missing already, and reported by the caller. It keeps
+          # its codepoint and whatever the lock still holds, so fixing the
+          # manifest entry is all it takes to bring it back.
+          next if src.nil?
+
+          pre = Preprocessor.new(icon, size: @manifest.size)
+                            .call(src.markup, width: src.width, height: src.height)
+          @lock.store(icon.name, source: icon.source, body: pre.body,
+                      multicolor: pre.multicolor, warnings: pre.warnings)
+          fetched << icon.name
+        end
+      end
+
+      # Missing icons stay in the list: their codepoints must not be reissued
+      # while the manifest still claims them.
+      @lock.retire_missing!(@manifest.icons.map(&:name))
+      @lock.save!
+
+      buildable = @manifest.icons.reject { missing.key?(_1.name) }
+      buildable.each do |icon|
+        found = @lock.warnings(icon.name)
+        warnings[icon.name] = found if found.any?
+      end
+
+      written, skipped = emit(buildable)
+      Report.new(written: written, warnings: warnings, skipped: skipped,
+                 cached: cached, fetched: fetched, missing: missing,
+                 pending: @manifest.targets & PENDING)
+    end
+
+    private
+
+    def emit(icons)
+      FileUtils.mkdir_p(@output)
+      written = []
+      skipped = Hash.new { |h, k| h[k] = [] }
+
+      targets = @manifest.targets - PENDING
+      targets += ["css"] if targets.include?("sprite") && !targets.include?("css")
+
+      targets.each do |target|
+        path = File.join(@output, filename_for(target))
+        emitter = emitter_for(target, [], path: path)
+
+        accepted = icons.select { emitter.accepts?(_1) }
+        # A rules-only emitter refuses every icon by design; that is not a skip
+        # anyone needs to hear about.
+        (icons - accepted).each { skipped[target] << _1.name } unless emitter.rules_only?
+
+        pairs = accepted.map { [_1, @lock.body(_1.name)] }
+        result = emitter_for(target, pairs, path: path).call
+        File.write(path, result) if result.is_a?(String)
+        written << path
+      end
+
+      [written, skipped]
+    end
+
+    def emitter_for(target, build = [], path: nil)
+      case target
+      when "sprite" then Emitters::Sprite.new(@manifest, build)
+      when "css"    then Emitters::Stylesheet.new(@manifest, build)
+      when "ttf"    then Emitters::Font.new(@manifest, build, lock: @lock, output: path)
+      else raise Error, "unknown target #{target.inspect} (have: sprite, ttf)"
+      end
+    end
+
+    def filename_for(target)
+      case target
+      when "sprite" then "icons.svg"
+      when "css"    then "icons.css"
+      when "ttf"    then "icons.ttf"
+      else raise Error, "unknown target #{target.inspect}"
+      end
+    end
+  end
+end

data/lib/fontico/emitters/font.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module Fontico
+  module Emitters
+    # A TTF for Prawn. Not for the web: at this icon count the sprite is both
+    # smaller over the wire and not render-blocking. Prawn reads TTF/OTF via
+    # ttfunk and cannot read woff2, so TTF is the right container here.
+    class Font
+      def initialize(manifest, build, lock: nil, outliner: nil, output: nil)
+        @manifest = manifest
+        @build = build
+        @lock = lock
+        @outliner = outliner || Outliner.new
+        @output = output
+      end
+
+      # Glyphs store no colour, so multicolour icons cannot be represented at
+      # all. They stay in the sprite and the build names each one it dropped.
+      def accepts?(icon) = !(@lock&.multicolor?(icon.name) || icon.multicolor?)
+      def rules_only? = false
+
+      def call
+        unsupported = @build.select { |icon, body| @outliner.strategy_for(icon, body) == :none }
+        @outliner.refuse(unsupported.map(&:first)) if unsupported.any?
+
+        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) }
+        end
+
+        result = @outliner.instance_variable_get(:@runner)
+                          .run("build_font.mjs", {
+                                 fontName: "fontico", size: @manifest.size,
+                                 output: @output, glyphs: glyphs
+                               })
+        if result["empty"]&.any?
+          raise Fontico::Error, <<~MSG
+            #{result["empty"].size} icon(s) produced an empty glyph and would ship invisible:
+
+              #{result["empty"].join("\n  ")}
+
+            The usual cause is live <text> in the source SVG, which has no outline
+            to convert. Convert text to paths (Path > Object to Path), or remove
+            the icon from the font target.
+          MSG
+        end
+
+        result
+      end
+
+      private
+
+      def document(outline, body)
+        inner = outline ? %(<path d="#{outline}"/>) : body.gsub("currentColor", "#000")
+        %(<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 #{@manifest.size} #{@manifest.size}">#{inner}</svg>)
+      end
+    end
+  end
+end

data/lib/fontico/emitters/sprite.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Fontico
+  module Emitters
+    # One <svg> of <symbol> definitions, referenced with <use href="…#name">.
+    # Pure Ruby string assembly: no external toolchain, builds anywhere.
+    class Sprite
+      def initialize(manifest, build)
+        @manifest = manifest
+        @build = build
+      end
+
+      def accepts?(_icon) = true
+      def rules_only? = false
+
+      def call
+        symbols = @build.map do |icon, body|
+          %(<symbol id="#{icon.key}" viewBox="0 0 #{@manifest.size} #{@manifest.size}" ) +
+            %(fill="none">#{body}</symbol>)
+        end
+
+        <<~SVG
+          <svg xmlns="http://www.w3.org/2000/svg" aria-hidden="true" style="display:none">
+          #{symbols.join("\n")}
+          </svg>
+        SVG
+      end
+    end
+  end
+end

data/lib/fontico/emitters/stylesheet.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module Fontico
+  module Emitters
+    # The small amount of CSS that makes an <svg> behave like a glyph.
+    #
+    # Colour is already handled: bodies are folded to `currentColor`, which is
+    # what makes an *external* sprite themeable at all — host CSS does not
+    # cascade into a cross-document <use>, but inherited properties like
+    # `color` do reach it.
+    class Stylesheet
+      def initialize(manifest, _build)
+        @manifest = manifest
+      end
+
+      # Contributes no icons, only rules — so the builder must not count all
+      # 91 of them as "skipped" on its behalf.
+      def accepts?(_icon) = false
+      def rules_only?     = true
+
+      def call
+        <<~CSS
+          /* generated by fontico — do not edit */
+          .#{Fontico.css_class} {
+            display: inline-block;
+            width: 1em;
+            height: 1em;
+
+            /* An <svg> sits on the text baseline's bottom edge, a glyph sits
+               slightly below it. This is the conventional nudge; tune it if
+               your body face has unusual metrics. */
+            vertical-align: -0.125em;
+
+            /* Never let a flex or grid parent squash an icon. */
+            flex: none;
+          }
+
+          /* Optical sizing for icons set beside larger text. */
+          .#{Fontico.css_class}-lg { width: 1.25em; height: 1.25em; }
+          .#{Fontico.css_class}-xl { width: 1.5em;  height: 1.5em;  }
+        CSS
+      end
+    end
+  end
+end

data/lib/fontico/helper.rb

@@ -0,0 +1,105 @@
+# frozen_string_literal: true
+
+module Fontico
+  # The whole point of the manifest: templates say what they mean, and never
+  # name a vendor. icon("save") and icon("logo") are the same call.
+  module Helper
+    # A glyph inherits font-size and colour from the text around it; an <svg>
+    # does not. width/height of 1em restores the first, `currentColor` baked
+    # into every body restores the second, and the generated stylesheet puts
+    # it on the baseline. Pass size: to override, or a CSS class — classes win
+    # over the attributes, so `class: "size-6"` works untouched.
+    def icon(name, size: nil, variant: nil, **options)
+      Fontico.check!(name.to_s)
+      entry = Fontico.manifest[name.to_s]
+      return missing(name) if entry.nil?
+
+      symbol = entry.key
+      attrs = {
+        class: [Fontico.css_class, options.delete(:class)].compact.join(" "),
+        width: size || "1em",
+        height: size || "1em",
+        style: inline_size(size, options.delete(:style)),
+        "aria-hidden": options.key?(:title) ? nil : "true",
+        role: options.key?(:title) ? "img" : nil
+      }.merge(options).compact
+
+      title = attrs.delete(:title)
+      body = +""
+      body << "<title>#{ERB::Util.html_escape(title)}</title>" if title
+      body << %(<use href="#{sprite_path(variant)}##{symbol}"></use>)
+
+      tag = %(<svg #{attrs.map { |k, v| %(#{k}="#{ERB::Util.html_escape(v)}") }.join(" ")}>#{body}</svg>)
+      tag.respond_to?(:html_safe) ? tag.html_safe : tag
+    end
+
+    # The `<use href>` for one icon, for markup this helper doesn't build —
+    # a Vue or Stimulus template, a JSON blob on its way to the client.
+    # Both halves are things a template shouldn't have to know: the sprite
+    # carries an asset digest, and a dotted manifest name is a dashed symbol
+    # id inside the file.
+    #
+    #   icon_href("game.aim")  # => "/assets/icons-ac89a32b.svg#game-aim"
+    #
+    # Hand it to the client rather than reconstructing it there; see
+    # icons_sprite for the inline case, where the path half is empty and the
+    # fragment resolves against the current document.
+    def icon_href(name)
+      Fontico.check!(name.to_s)
+      entry = Fontico.manifest[name.to_s]
+      raise Fontico::Error, "no icon named #{name.inspect} in #{Fontico.manifest_path}" if entry.nil?
+
+      "#{sprite_path}##{entry.key}"
+    end
+
+    # Embeds the symbol definitions directly, for pages served from a CDN
+    # where a cross-origin <use href> would silently render nothing.
+    def icons_sprite
+      Fontico.check!
+      svg = File.read(Fontico.sprite_file)
+      svg.respond_to?(:html_safe) ? svg.html_safe : svg
+    end
+
+    private
+
+    # width/height on an <svg> are presentation attributes, and *any* CSS
+    # declaration outranks those — including icons.css's own `.ico { width:
+    # 1em }`. So an explicitly requested size has to be inline or the
+    # stylesheet silently swallows it and every icon comes out 1em.
+    #
+    # With no size given the attributes stay the only word on the matter,
+    # which is what lets `class: "size-6"` or `class: "h-7 w-7"` still win.
+    def inline_size(size, style = nil)
+      return style if size.nil?
+
+      dim = size.is_a?(Numeric) ? "#{size}px" : size.to_s
+      ["width:#{dim}", "height:#{dim}", style].compact.join(";")
+    end
+
+    # Propshaft always digests, so there is no undigested path to guess at:
+    # "/assets/icons.svg" is a 404 in every environment, and a <use> pointing
+    # at one renders an empty box rather than raising. That matters most for
+    # icon_href, which gets called from serializers, jobs and broadcasts —
+    # payload-building code that has no view context to borrow asset_path
+    # from. Rails hands one out off ActionController::Base either way.
+    def sprite_path(_variant = nil)
+      return "" if Fontico.inline_sprite?
+      return asset_path("icons.svg") if respond_to?(:asset_path)
+      return ActionController::Base.helpers.asset_path("icons.svg") if defined?(::ActionController::Base)
+
+      "/assets/icons.svg"
+    end
+
+    # An icon missing from the manifest is a typo, and typos should not reach
+    # production as an invisible empty box.
+    def missing(name)
+      raise Fontico::Error, "no icon named #{name.inspect} in #{Fontico.manifest_path}" unless production?
+
+      "".respond_to?(:html_safe) ? "".html_safe : ""
+    end
+
+    def production?
+      defined?(Rails) && Rails.env.production?
+    end
+  end
+end

data/lib/fontico/icon.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Fontico
+  # One resolved entry from the manifest: the name templates use, plus where
+  # it came from and the flags that decide which emitters accept it.
+  Icon = Struct.new(:name, :provider, :slug, :multicolor, keyword_init: true) do
+    def source     = "#{provider}/#{slug}"
+    def local?     = provider == "local"
+    def multicolor? = !!multicolor
+
+    # Sprite symbol ids and the id-namespacing prefix both derive from here,
+    # so a rename in the manifest moves them together.
+    def key = name.tr(".", "-")
+  end
+end

data/lib/fontico/lockfile.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+require "yaml"
+require "digest"
+
+module Fontico
+  # icons.lock pins two things that must never drift:
+  #
+  #   codepoints — append-only. Adding an icon must not renumber the others,
+  #                or every glyph in the built font moves and the committed
+  #                artifact churns whole-file on each addition. Codepoints of
+  #                removed icons are retired, never reissued.
+  #
+  #   bodies     — the normalised SVG for each icon, so builds are
+  #                reproducible and run offline. The Iconify API serves
+  #                *latest*; without this an icon can change shape between
+  #                two builds of the same manifest.
+  class Lockfile
+    PUA_START = 0xE001
+    FORMAT = 1
+
+    attr_reader :path
+
+    def initialize(path)
+      @path = path
+      data = File.exist?(path) ? (YAML.safe_load_file(path) || {}) : {}
+      @codepoints = data["codepoints"] || {}
+      @retired    = data["retired"]    || {}
+      @entries    = data["icons"]      || {}
+    end
+
+    def codepoint_for(name)
+      @codepoints[name] ||= next_free
+    end
+
+    def entry(name) = @entries[name]
+
+    def store(name, source:, body:, multicolor: false, warnings: [])
+      @entries[name] = {
+        "source"     => source,
+        "digest"     => Digest::SHA256.hexdigest(body)[0, 16],
+        "multicolor" => multicolor,
+        "warnings"   => warnings,
+        "body"       => body
+      }
+      codepoint_for(name)
+    end
+
+    # Names present in the lock but absent from the manifest keep their
+    # codepoint reserved so it is never handed to a different icon.
+    def retire_missing!(names)
+      (@codepoints.keys - names).each do |gone|
+        @retired[gone] = @codepoints.delete(gone)
+        @entries.delete(gone)
+      end
+    end
+
+    def fresh?(name, source)
+      entry(name)&.fetch("source", nil) == source && entry(name)["body"]
+    end
+
+    def body(name) = entry(name)&.fetch("body", nil)
+    def multicolor?(name) = !!entry(name)&.fetch("multicolor", false)
+
+    # Replayed on cached builds so a hard failure keeps being reported until
+    # the source file is actually fixed.
+    def warnings(name) = entry(name)&.fetch("warnings", nil) || []
+
+    def save!
+      File.write(@path, {
+        "format"     => FORMAT,
+        "codepoints" => @codepoints.sort.to_h,
+        "retired"    => @retired.sort.to_h,
+        "icons"      => @entries.sort.to_h
+      }.to_yaml)
+    end
+
+    private
+
+    def next_free
+      used = (@codepoints.values + @retired.values).map(&:to_i)
+      cp = PUA_START
+      cp += 1 while used.include?(cp)
+      cp
+    end
+  end
+end

data/lib/fontico/manifest.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+require "yaml"
+
+module Fontico
+  # Parses icons.yml. Nested groups flatten to dotted names, so
+  # `nav: { menu: lucide/menu }` is addressable as icon("nav.menu").
+  class Manifest
+    class Error < Fontico::Error; end
+
+    # Where local/ SVGs live when the manifest doesn't say otherwise.
+    LOCAL_PATH = "app/assets/icons"
+
+    attr_reader :path, :defaults, :providers, :targets, :icons
+
+    def self.load(path) = new(YAML.safe_load_file(path), path: path)
+
+    def initialize(data, path: nil)
+      @path      = path
+      @defaults  = data["defaults"]  || {}
+      @providers = data["providers"] || {}
+      @targets   = data["targets"]   || ["sprite"]
+      @icons     = flatten(data["icons"] || {}).freeze
+      validate!
+    end
+
+    def default_provider = defaults.fetch("provider", "lucide")
+    def local_path       = providers.dig("local", "path") || LOCAL_PATH
+    def size             = defaults.fetch("size", 24).to_i
+
+    def [](name) = icons.find { _1.name == name }
+
+    # Vendor icons grouped by provider so the resolver can batch one HTTP
+    # request per provider instead of one per icon.
+    def remote_by_provider
+      icons.reject(&:local?).group_by(&:provider).transform_values { _1.map(&:slug).uniq.sort }
+    end
+
+    def local_icons = icons.select(&:local?)
+
+    private
+
+    def flatten(tree, prefix = nil)
+      tree.flat_map do |key, value|
+        name = [prefix, key].compact.join(".")
+        case value
+        when String then [build(name, value)]
+        when Hash
+          if value.key?("icon") || value.key?("file")
+            [build(name, value["icon"] || "local/#{File.basename(value["file"], ".svg")}", value)]
+          else
+            flatten(value, name)
+          end
+        else
+          raise Error, "icon #{name.inspect} must be a string or a mapping, got #{value.class}"
+        end
+      end
+    end
+
+    def build(name, spec, opts = {})
+      provider, slug = spec.include?("/") ? spec.split("/", 2) : [default_provider, spec]
+      Icon.new(name: name, provider: provider, slug: slug, multicolor: opts["multicolor"])
+    end
+
+    def validate!
+      raise Error, "manifest declares no icons" if icons.empty?
+
+      dupes = icons.map(&:name).tally.select { |_, n| n > 1 }.keys
+      raise Error, "duplicate icon names: #{dupes.join(", ")}" if dupes.any?
+
+      unknown = icons.map(&:provider).uniq - providers.keys
+      raise Error, "icons reference undeclared providers: #{unknown.join(", ")}" if unknown.any?
+    end
+  end
+end

data/lib/fontico/node/build_font.mjs

@@ -0,0 +1,52 @@
+// Assemble normalised SVG bodies into a TTF.
+//
+// stdin: { fontName, size, output, glyphs: [{ name, codepoint, svg }] }
+import fs from 'fs';
+import { Readable } from 'stream';
+import { SVGIcons2SVGFontStream } from 'svgicons2svgfont';
+import svg2ttf from 'svg2ttf';
+
+const job = JSON.parse(fs.readFileSync(0, 'utf8'));
+
+// 1000 upm with the full em above the baseline keeps icons aligned with text
+// instead of drifting against it.
+const UPM = 1000;
+
+const stream = new SVGIcons2SVGFontStream({
+  fontName: job.fontName,
+  fontHeight: UPM,
+  ascent: UPM,
+  descent: 0,
+  normalize: true,
+  centerHorizontally: false,
+  log: () => {}
+});
+
+let svgFont = '';
+stream.on('data', (chunk) => { svgFont += chunk; });
+stream.on('error', (err) => {
+  process.stderr.write(`svgicons2svgfont: ${err.message}\n`);
+  process.exit(1);
+});
+stream.on('finish', () => {
+  const ttf = svg2ttf(svgFont, { copyright: job.copyright ?? '' });
+  fs.writeFileSync(job.output, Buffer.from(ttf.buffer));
+
+  // Report empty glyphs rather than shipping invisible icons silently.
+  // svgicons2svgfont emits d="" rather than omitting the attribute, so an
+  // absent-d check alone misses exactly the case that matters.
+  const empty = [...svgFont.matchAll(/<glyph glyph-name="([^"]+)"[^>]*\/>/g)]
+    .filter((m) => !/\sd="[^"]+"/.test(m[0]))
+    .map((m) => m[1]);
+  process.stdout.write(JSON.stringify({ bytes: fs.statSync(job.output).size, empty }));
+});
+
+for (const glyph of job.glyphs) {
+  const readable = Readable.from([glyph.svg]);
+  readable.metadata = {
+    unicode: [String.fromCodePoint(glyph.codepoint)],
+    name: glyph.name
+  };
+  stream.write(readable);
+}
+stream.end();

data/lib/fontico/node/extract_glyphs.mjs

@@ -0,0 +1,35 @@
+// Pull already-outlined glyphs out of a provider's own font.
+//
+// Stroke-based icon sets (Lucide) cannot be filled directly as glyphs — a
+// path with fill="none" fills its centreline and produces a blob. The only
+// lossless source of expanded outlines is the provider's own font build,
+// where the expansion has already been done and tuned. Every JS "stroke to
+// fill" package traces a raster and degrades the geometry.
+//
+// stdin:  { fontPath, codepointsPath, size, names: [] }
+// stdout: { glyphs: { name: pathData }, missing: [] }
+import fs from 'fs';
+import opentype from 'opentype.js';
+
+const job = JSON.parse(fs.readFileSync(0, 'utf8'));
+const font = opentype.parse(fs.readFileSync(job.fontPath).buffer);
+const codepoints = JSON.parse(fs.readFileSync(job.codepointsPath, 'utf8'));
+
+const size = job.size ?? 24;
+const glyphs = {};
+const missing = [];
+
+for (const name of job.names) {
+  const cp = codepoints[name];
+  if (cp === undefined) { missing.push(name); continue; }
+
+  const glyph = font.charToGlyph(String.fromCodePoint(cp));
+  if (!glyph || glyph.index === 0) { missing.push(name); continue; }
+
+  // Font space is y-up with the baseline at 0; SVG is y-down in a 0..size
+  // box. Shifting by the ascender puts the glyph inside the viewBox.
+  const path = glyph.getPath(0, size * (font.ascender / font.unitsPerEm), size);
+  glyphs[name] = path.toPathData(3);
+}
+
+process.stdout.write(JSON.stringify({ glyphs, missing }));

data/lib/fontico/node/package.json

@@ -0,0 +1,11 @@
+{
+  "name": "fontico-toolchain",
+  "private": true,
+  "type": "module",
+  "description": "Font assembly toolchain for the fontico gem. Installed on demand into a cache directory; not required unless a font target is built.",
+  "dependencies": {
+    "opentype.js": "^2.0.0",
+    "svgicons2svgfont": "^16.0.0",
+    "svg2ttf": "^6.1.0"
+  }
+}