fontist 3.0.28 → 3.0.29

data/lib/fontist/css.rb

@@ -0,0 +1,110 @@
+require "cgi"
+require "fileutils"
+
+module Fontist
+  # Web CSS for fonts.
+  #
+  # - {Css.url} / {Css.link}: Google Fonts CSS2 URL for a Google family.
+  #   No network access, no font installation.
+  # - {Css.local}: copies fonts already installed by fontist into a directory
+  #   and writes a fonts.css with one @font-face per style.
+  module Css
+    class Error < Errors::GeneralError; end
+
+    class UnknownFamilyError < Error
+      def initialize(family)
+        super("Font family '#{family}' was not found in the Fontist " \
+              "formulas. Check the name, or run `fontist update`.")
+      end
+    end
+
+    class AmbiguousFamilyError < Error
+      def initialize(family, keys)
+        super("Font family '#{family}' matches several Google formulas " \
+              "(#{keys.join(', ')}); cannot choose one.")
+      end
+    end
+
+    class NotGoogleFamilyError < Error
+      def initialize(family)
+        super("Font family '#{family}' is not a Google Fonts family, so " \
+              "it has no Google CSS URL. Use `--local` to build CSS from " \
+              "installed font files.")
+      end
+    end
+
+    class InvalidStyleError < Error
+      def initialize(style)
+        super("Invalid style '#{style}'. Use a weight 100-900 with an " \
+              "optional 'i' for italic, e.g. 400, 700i.")
+      end
+    end
+
+    class UnavailableStyleError < Error
+      def initialize(family, style, available)
+        super("Style '#{style}' is not available for '#{family}'. " \
+              "Available styles: #{available.join(', ')}.")
+      end
+    end
+
+    class InvalidDisplayError < Error
+      def initialize(display, allowed)
+        super("Invalid display '#{display}'. Allowed: #{allowed.join(', ')}.")
+      end
+    end
+
+    class InvalidOptionError < Error; end
+
+    DISPLAYS = %w[auto block swap fallback optional].freeze
+    GOOGLE_CSS2 = "https://fonts.googleapis.com/css2".freeze
+
+    class << self
+      # @param family [String] e.g. "Source Sans 3"
+      # @param styles [Array<String>, String, nil] e.g. %w[300 600i]
+      # @param display [String] auto|block|swap|fallback|optional
+      # @return [String] the Google CSS2 URL (raw `&`)
+      def url(family, styles: nil, display: "swap")
+        display = validate_display(display)
+        formula, canonical = GoogleFamily.resolve(family)
+        requested = Styles.parse(styles)
+        Styles.verify(canonical, Styles.faces(formula), requested)
+
+        "#{GOOGLE_CSS2}?family=#{CGI.escape(canonical)}" \
+          "#{axis_spec(requested)}&display=#{display}"
+      end
+
+      # @return [String] an HTML stylesheet link tag for {.url}
+      def link(family, styles: nil, display: "swap")
+        href = CGI.escapeHTML(url(family, styles: styles, display: display))
+        %(<link rel="stylesheet" href="#{href}">)
+      end
+
+      # Copy installed fonts into output_dir and write fonts.css.
+      # @return [String] path of the written fonts.css
+      def local(family, output_dir:, **options)
+        Local.new(family, output_dir: output_dir, **options).call
+      end
+
+      private
+
+      def validate_display(display)
+        value = display.to_s
+        return value if DISPLAYS.include?(value)
+
+        raise InvalidDisplayError.new(display, DISPLAYS)
+      end
+
+      def axis_spec(requested)
+        return "" if requested.empty?
+        return ":wght@#{requested.map(&:last).join(';')}" if
+          requested.none? { |ital, _| ital == 1 }
+
+        ":ital,wght@#{requested.map { |t| t.join(',') }.join(';')}"
+      end
+    end
+  end
+end
+
+require_relative "css/styles"
+require_relative "css/google_family"
+require_relative "css/local"

data/lib/fontist/errors.rb

@@ -248,6 +248,9 @@ module Fontist
       end
     end
 
+    # Variable-font instancing errors
+    class InstanceError < GeneralError; end
+
     # Transcoding errors
     class UnsupportedTranscodeError < GeneralError
       def initialize(source_format, target_format)

data/lib/fontist/font_file.rb

@@ -63,7 +63,8 @@ module Fontist
           font = validate_and_load_single_font(path)
         end
         names = extract_names_from_font(font)
-        font.close
+        # WOFF and WOFF2 fonts from Fontisan hold no open file to close.
+        font.close if font.respond_to?(:close)
         names
       rescue StandardError => e
         raise_font_file_error(e)

data/lib/fontist/font_finder.rb

@@ -50,6 +50,19 @@ module Fontist
       end.flatten
     end
 
+    # Find fonts offered in a format (ttf, otf, woff, woff2, ttc, otc)
+    def by_format(format)
+      matching_formulas.flat_map do |formula|
+        next [] unless formula.v5?
+
+        each_resource(formula).select do |resource|
+          formula.resource_offers_format?(resource, format)
+        end.map do |resource|
+          build_font_match(formula, resource.name, resource, format: format)
+        end
+      end
+    end
+
     # Find fonts by category
     def by_category(category)
       matching_formulas.select do |formula|
@@ -78,12 +91,12 @@ module Fontist
       Array(formula.resources).filter_map(&:name)
     end
 
-    def build_font_match(formula, name, resource)
+    def build_font_match(formula, name, resource, format: resource.format)
       FontMatch.new(
         name: formula.name,
         resource: name,
         axes: resource.axes_tags,
-        format: resource.format,
+        format: format,
         category: extract_category(formula),
       )
     end

data/lib/fontist/font_installer.rb

@@ -122,15 +122,22 @@ module Fontist
       source_files.include?(File.basename(path))
     end
 
+    # Styles already in the requested format. When none is, a plain format
+    # request keeps every style so the files can be converted.
+    def styles_in_requested_format(styles)
+      return styles unless @format_spec&.has_constraints?
+
+      matching = FormatMatcher.new(@format_spec).filter_styles(styles)
+      return matching if matching.any? || @format_spec.variable_requested?
+
+      @format_spec.format ? styles : matching
+    end
+
     def source_files
       @source_files ||= begin
         styles = filtered_styles
 
-        # Use FormatMatcher for filtering
-        if @format_spec&.has_constraints? && @formula.v5?
-          matcher = FormatMatcher.new(@format_spec)
-          styles = matcher.filter_styles(styles)
-        end
+        styles = styles_in_requested_format(styles) if @formula.v5?
 
         file_names = styles.map { |s| s.source_font || s.font }
 
@@ -177,17 +184,93 @@ module Fontist
     end
 
     def install_font_file(source)
-      source_basename = File.basename(source)
-      target_name = target_filename(source_basename) || source_basename
-      source_format = detect_font_format(source)
+      Dir.mktmpdir("fontist-ops") do |workdir|
+        original_name = target_filename(File.basename(source)) ||
+          File.basename(source)
+        prepared, target_name = prepare_font(source, original_name, workdir)
+        result = @location.install_font(prepared, target_name)
+        install_original_too(source, original_name) if
+          converted?(source, prepared)
+        result
+      end
+    end
 
-      # Check if transcoding is needed (format requested but not available)
-      if @format_spec&.format && @format_spec.format != source_format
-        check_transcode_license_warning!
-        install_with_conversion(source, target_name, source_format)
-      else
-        @location.install_font(source, target_name)
+    def converted?(source, prepared)
+      requested = @format_spec&.format
+      requested && detect_font_format(prepared) == requested &&
+        detect_font_format(source) != requested
+    end
+
+    # Keeps the untouched original alongside converted output when the user
+    # asked for it with a transcode_path (existing --keep-original behavior).
+    def install_original_too(source, name)
+      return unless @format_spec&.keep_original && @format_spec.transcode_path
+
+      @location.install_font(source, name)
+    end
+
+    # Applies the requested operations (collection member extraction,
+    # instancing, subsetting, conversion) and returns the file to install and
+    # its name.
+    def prepare_font(source, target_name, workdir)
+      if @format_spec&.specific_collection_index? &&
+          FontOperations::Extract.collection?(source)
+        source = FontOperations::Extract.call(
+          source, index: @format_spec.collection_index, output_dir: workdir
+        )
+        target_name = File.basename(source)
       end
+
+      source, target_name = apply_instance(source, target_name, workdir)
+      source, target_name = apply_subset(source, target_name, workdir)
+      apply_conversion(source, target_name, workdir)
+    end
+
+    def apply_instance(source, target_name, workdir)
+      return [source, target_name] unless @format_spec&.instance_requested?
+
+      check_transcode_license_warning!
+      coordinates = @format_spec.instance_coordinates
+      name = FontOperations::Instance.file_name(target_name, coordinates)
+      output = File.join(workdir, name)
+      FontOperations::Instance.call(source, output, coordinates: coordinates)
+      [output, name]
+    end
+
+    def apply_subset(source, target_name, workdir)
+      return [source, target_name] unless @format_spec&.subset_requested?
+
+      check_transcode_license_warning!
+      output = File.join(workdir, "subset-#{File.basename(source)}")
+      FontOperations::Subset.call(
+        source, output,
+        unicodes: @format_spec.subset_unicodes,
+        text: @format_spec.subset_text
+      )
+      [output, target_name]
+    end
+
+    def apply_conversion(source, target_name, workdir)
+      requested = @format_spec&.format
+      source_format = detect_font_format(source)
+      return [source, target_name] if [nil, source_format].include?(requested)
+
+      check_transcode_license_warning!
+      name = target_name.sub(/\.[^.]+\z/, ".#{requested}")
+      output = File.join(@format_spec.transcode_path || workdir, name)
+      convert_or_fallback(source, target_name, output, name)
+    end
+
+    def convert_or_fallback(source, original_name, output, name)
+      FontOperations::Convert.call(source, @format_spec.format, output)
+      Fontist.ui.success("Converted to #{@format_spec.format}: #{name}")
+      [output, name]
+    rescue Errors::GeneralError => e
+      raise unless @format_spec.fallback_to_original
+
+      Fontist.ui.warn("Could not convert: #{e.message}")
+      Fontist.ui.warn("Installing original format (--fallback-to-original)")
+      [source, original_name]
     end
 
     def detect_font_format(path)
@@ -228,86 +311,6 @@ module Fontist
       Fontist.ui.warn("#{'=' * 60}\n")
     end
 
-    def install_with_conversion(source, target_name, source_format)
-      target_format = @format_spec.format
-
-      # Check if Fontisan can convert between formats
-      matcher = FormatMatcher.new(@format_spec)
-      unless matcher.can_convert?(source_format, target_format)
-        Fontist.ui.warn(
-          "Cannot convert from #{source_format} to #{target_format}",
-        )
-        Fontist.ui.warn("Installing original format instead")
-        return @location.install_font(source, target_name)
-      end
-
-      begin
-        converted_path = convert_with_fontisan(source, target_format)
-
-        # Determine where to save converted font
-        converted_name = target_name.sub(/\.[^.]+$/, ".#{target_format}")
-
-        Fontist.ui.success(
-          "Converted #{source_format} to #{target_format}: #{converted_name}",
-        )
-
-        # Install converted font
-        result = @location.install_font(converted_path, converted_name)
-
-        # Keep original if requested and transcode_path specified
-        if @format_spec.keep_original && @format_spec.transcode_path
-          @location.install_font(source, target_name)
-        end
-
-        # Clean up temp converted file if Fontisan created one
-        cleanup_temp_file(converted_path) if converted_path != source
-
-        result
-      rescue StandardError => e
-        Fontist.ui.warn("Could not convert to #{target_format}: #{e.message}")
-        Fontist.ui.warn("Installing original format instead")
-        @location.install_font(source, target_name)
-      end
-    end
-
-    # Convert font using Fontisan library
-    def convert_with_fontisan(source_path, target_format)
-      require "fontisan"
-
-      font = Fontisan::FontLoader.load(source_path)
-
-      case target_format
-      when "woff"
-        font.to_woff(path: temp_path_for(source_path, "woff"))
-      when "woff2"
-        font.to_woff2(path: temp_path_for(source_path, "woff2"))
-      else
-        raise Errors::UnsupportedTranscodeError.new(
-          File.extname(source_path),
-          target_format,
-        )
-      end
-    rescue LoadError
-      Fontist.ui.error(
-        "Fontisan gem not found. Transcoding requires the fontisan gem.",
-      )
-      Fontist.ui.error("Add it to your Gemfile or run: gem install fontisan")
-      raise
-    end
-
-    def temp_path_for(source_path, format)
-      base = File.basename(source_path, ".*")
-      dir = @format_spec&.transcode_path || Dir.mktmpdir
-      FileUtils.mkdir_p(dir)
-      File.join(dir, "#{base}.#{format}")
-    end
-
-    def cleanup_temp_file(path)
-      FileUtils.rm_f(path)
-    rescue StandardError
-      # Ignore cleanup errors
-    end
-
     def macos_asset_directory
       # Install to: /System/Library/AssetsV2/com_apple_MobileAsset_Font*/
       # Generate unique asset identifier from formula key

data/lib/fontist/font_operations/convert.rb

@@ -0,0 +1,55 @@
+require "fileutils"
+
+module Fontist
+  module FontOperations
+    # Converts a font file to another format via Fontisan.
+    module Convert
+      TARGETS = %w[ttf otf woff woff2].freeze
+      MAGIC = {
+        "ttf" => ["\x00\x01\x00\x00".b, "true".b],
+        "otf" => ["OTTO".b],
+        "woff" => ["wOFF".b],
+        "woff2" => ["wOF2".b],
+      }.freeze
+
+      module_function
+
+      # @param source [String] font file
+      # @param target_format [String] one of TARGETS
+      # @param output [String] where to write the converted font
+      # @return [String] output path (verified to carry the target's magic)
+      def call(source, target_format, output)
+        target = target_format.to_s.downcase
+        FontOperations.guard("Converting to #{target}") do
+          check!(source, target)
+          run(source, target, output)
+          verify!(output, target)
+          output
+        end
+      end
+
+      def check!(source, target)
+        unless TARGETS.include?(target)
+          raise Errors::UnsupportedTranscodeError.new(
+            File.extname(source).delete("."), target
+          )
+        end
+        raise Errors::SourceNotFoundError, source unless File.exist?(source)
+      end
+
+      def run(source, target, output)
+        FileUtils.mkdir_p(File.dirname(output))
+        Fontisan::Commands::ConvertCommand.new(
+          source, to: target, output: output, quiet: true
+        ).run
+      end
+
+      def verify!(path, target)
+        head = File.file?(path) ? File.binread(path, 4) : nil
+        return if MAGIC.fetch(target).include?(head)
+
+        raise Error, "Fontisan did not produce a #{target} file at #{path}"
+      end
+    end
+  end
+end

data/lib/fontist/font_operations/extract.rb

@@ -0,0 +1,53 @@
+require "fileutils"
+
+module Fontist
+  module FontOperations
+    # Extracts one member of a TTC/OTC collection as a standalone font.
+    module Extract
+      module_function
+
+      # @param collection_path [String] TTC/OTC file
+      # @param index [Integer] zero-based member index
+      # @param output_dir [String] directory to write into
+      # @return [String] path of the standalone font
+      def call(collection_path, index:, output_dir:)
+        FontOperations.guard("Extracting member #{index}") do
+          check_index!(collection_path, index)
+          unpack(collection_path, index, output_dir)
+        end
+      end
+
+      def unpack(collection_path, index, output_dir)
+        Fontisan::Commands::UnpackCommand.new(
+          collection_path, output_dir: output_dir, font_index: index
+        ).run[:extracted_files].first
+      end
+
+      def check_index!(path, index)
+        raise Errors::SourceNotFoundError, path unless File.exist?(path)
+
+        count = member_count(path)
+        return if index.is_a?(Integer) && index >= 0 && index < count
+
+        raise Errors::CollectionIndexError.new(index, count - 1)
+      end
+
+      def collection?(path)
+        File.open(path, "rb") { |io| io.read(4) } == "ttcf"
+      rescue SystemCallError
+        false
+      end
+
+      def member_count(path)
+        unless collection?(path)
+          raise Error, "#{path} is not a TTC/OTC collection"
+        end
+
+        File.open(path, "rb") do |io|
+          io.seek(8)
+          io.read(4).unpack1("N")
+        end
+      end
+    end
+  end
+end

data/lib/fontist/font_operations/instance.rb

@@ -0,0 +1,92 @@
+require "fileutils"
+
+module Fontist
+  module FontOperations
+    # Writes a static instance of a variable font at the given axis values,
+    # validated against the font's own fvar axes.
+    module Instance
+      PAIR = /\A([A-Za-z][A-Za-z0-9 ]{2,3})=(-?\d+(\.\d+)?)\z/
+
+      module_function
+
+      # @param source [String] variable font file
+      # @param output [String] where to write the static instance
+      # @param coordinates [Hash{String=>Numeric}, String] {"wght" => 300}
+      #   or "wght=300,wdth=90"
+      # @return [String] output path
+      def call(source, output, coordinates:)
+        FontOperations.guard("Instancing") do
+          raise Errors::SourceNotFoundError, source unless File.exist?(source)
+
+          coords = coordinates.is_a?(String) ? parse(coordinates) : coordinates
+          raise Errors::InstanceError, "No axis values given" if coords.empty?
+
+          write(source, output, normalize(coords))
+        end
+      end
+
+      # "wght=300,wdth=90" => {"wght" => 300.0, "wdth" => 90.0}
+      def parse(value)
+        value.to_s.split(",").map(&:strip).reject(&:empty?).to_h do |pair|
+          match = PAIR.match(pair)
+          unless match
+            raise Errors::InstanceError,
+                  "Invalid instance '#{pair}'. Use e.g. wght=300,wdth=90"
+          end
+
+          [match[1], match[2].to_f]
+        end
+      end
+
+      # File name for the instance: "Font[wght].ttf" => "Font-wght300.ttf"
+      def file_name(name, coordinates)
+        ext = File.extname(name)
+        base = File.basename(name, ext).sub(/\[[^\]]*\]\z/, "")
+        suffix = coordinates.map { |tag, val| "#{tag}#{number(val)}" }.join("-")
+        "#{base}-#{suffix}#{ext}"
+      end
+
+      def normalize(coords)
+        coords.to_h { |tag, value| [tag.to_s, Float(value)] }
+      rescue ArgumentError, TypeError
+        raise Errors::InstanceError, "Axis values must be numbers"
+      end
+
+      def write(source, output, coords)
+        font = Fontisan::FontLoader.load(source)
+        unless font.has_table?("fvar")
+          raise Errors::InstanceError,
+                "#{File.basename(source)} is not a variable font"
+        end
+
+        instancer = Fontisan::Variable::Instancer.new(font)
+        validate!(instancer, coords, File.basename(source))
+        FileUtils.mkdir_p(File.dirname(output))
+        File.binwrite(output, instancer.instance(coords))
+        output
+      end
+
+      def validate!(instancer, coords, name)
+        axes = instancer.axes.to_h { |axis| [axis.tag, axis] }
+        coords.each do |tag, value|
+          axis = axes[tag] || raise(Errors::InstanceError,
+                                    "#{name} has no axis '#{tag}' " \
+                                    "(axes: #{axes.keys.join(', ')})")
+          check_range!(axis, value, name)
+        end
+      end
+
+      def check_range!(axis, value, name)
+        return if value.between?(axis.minimum, axis.maximum)
+
+        raise Errors::InstanceError,
+              "#{axis.tag}=#{number(value)} is out of range for #{name}: " \
+              "#{number(axis.minimum)}-#{number(axis.maximum)}"
+      end
+
+      def number(value)
+        format("%g", value)
+      end
+    end
+  end
+end

data/lib/fontist/font_operations/pack.rb

@@ -0,0 +1,49 @@
+require "fileutils"
+
+module Fontist
+  module FontOperations
+    # Bundles several font files into one TTC/OTC (or dfont) collection.
+    module Pack
+      FORMATS = %w[ttc otc dfont].freeze
+
+      module_function
+
+      # @param output [String] collection path; extension picks the format
+      #   unless +format+ is given
+      # @param files [Array<String>] two or more font files
+      # @return [String] the written collection path
+      def call(output, files, format: nil)
+        FontOperations.guard("Packing collection") do
+          format = (format || File.extname(output).delete(".")).to_s.downcase
+          validate!(files, format)
+          write(output, files, format)
+        end
+      end
+
+      def validate!(files, format)
+        unless FORMATS.include?(format)
+          raise Error, "Unsupported collection format '#{format}'. " \
+                       "Use one of: #{FORMATS.join(', ')}"
+        end
+        if files.size < 2
+          raise Error, "A collection needs at least two font files"
+        end
+
+        missing = files.reject { |f| File.exist?(f) }
+        raise Errors::SourceNotFoundError, missing.first if missing.any?
+      end
+
+      def write(output, files, format)
+        FileUtils.mkdir_p(File.dirname(output))
+        Fontisan::Commands::PackCommand.new(
+          files, output: output, format: format
+        ).run
+        unless File.size?(output)
+          raise Error, "No collection was written to #{output}"
+        end
+
+        output
+      end
+    end
+  end
+end