fontist 3.0.28 → 3.0.30

data/lib/fontist/css/styles.rb

@@ -0,0 +1,79 @@
+module Fontist
+  module Css
+    # Style names as listed in formulas, mapped to CSS weights.
+    module Styles
+      # Fixed table: style name (case and separators ignored) => weight.
+      WEIGHTS = {
+        "thin" => 100, "hairline" => 100,
+        "extralight" => 200, "ultralight" => 200,
+        "light" => 300,
+        "regular" => 400, "normal" => 400, "book" => 400,
+        "medium" => 500,
+        "semibold" => 600, "demibold" => 600,
+        "bold" => 700,
+        "extrabold" => 800, "ultrabold" => 800,
+        "black" => 900, "heavy" => 900
+      }.freeze
+
+      # One available style: weight 100..900, italic flag, formula style.
+      Face = Struct.new(:weight, :italic, :style, keyword_init: true) do
+        def tuple
+          [italic ? 1 : 0, weight]
+        end
+
+        def token
+          Styles.token(tuple)
+        end
+      end
+
+      class << self
+        # "300,600i" or ["300", "600i"] => sorted unique [[ital, wght], ...]
+        def parse(styles)
+          Array(styles).flat_map { |s| s.to_s.split(",") }
+            .map(&:strip).reject(&:empty?)
+            .map { |token| parse_token(token) }.uniq.sort
+        end
+
+        def token(tuple)
+          "#{tuple[1]}#{'i' if tuple[0] == 1}"
+        end
+
+        # Faces a formula lists, sorted upright first, by weight.
+        def faces(formula)
+          formula.all_fonts.flat_map(&:styles).filter_map { |s| face_for(s) }
+            .uniq(&:tuple).sort_by(&:tuple)
+        end
+
+        # Face for one formula style; nil when its name is not in the table.
+        def face_for(style)
+          name = (style.preferred_type || style.type).to_s
+          base = name.gsub(/italic|oblique/i, "").downcase.gsub(/[\s_-]+/, "")
+          weight = WEIGHTS[base.empty? ? "regular" : base]
+          return unless weight
+
+          Face.new(weight: weight, italic: name.match?(/italic|oblique/i),
+                   style: style)
+        end
+
+        # Raise unless every requested tuple is among the available faces.
+        def verify(family, faces, requested)
+          have = faces.map(&:tuple)
+          missing = requested.find { |tuple| !have.include?(tuple) }
+          return unless missing
+
+          raise UnavailableStyleError.new(family, token(missing),
+                                          faces.map(&:token))
+        end
+
+        private
+
+        def parse_token(token)
+          match = /\A([1-9]00)(i?)\z/.match(token)
+          raise InvalidStyleError, token unless match
+
+          [match[2] == "i" ? 1 : 0, match[1].to_i]
+        end
+      end
+    end
+  end
+end

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