sf_symbol_converter 0.1.0 → 1.0.0.alpha.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a73ca5114d60907080d27034713195e7dfd459aae8f332f8d9ca9dcdb0ff03da
-  data.tar.gz: f9336910f51849ebca69a10561dacfcdefac5a0c0de792a75a74af9f5e76158f
+  metadata.gz: 0e0b93f63a04053685cf2a51ebe9b02a56d3a9e333c9f9e63ed1935e1b7449fb
+  data.tar.gz: 836bffc5c81f0f9950071375b0f6f03a4d0e7717a1b6c266247bc9b8da09e1ee
 SHA512:
-  metadata.gz: 6922fe44fefd4ac87ad6a2f76a9245d63c19eead6338ea959049725da965b10792066204df14e3a60362b6e31c361dc964dc952c7cd74728d68682bab0ccf4a3
-  data.tar.gz: d2caa2b4f7bb4fa1c4c1b20b26a7e37d56acddd222042ad1d0409fa7c6e9ccab71b86ce6b56745deaa44e804551e8320e8ae79481dd9b52108b4db7009343ae9
+  metadata.gz: 37bcddbbfa459d27137591ddc501ebefbbeebaa980ba6502c2211ed64ef9f8197663046061e3bde34025f54abbf8f8970d178f1378c1fc560faa5d9f45d1faa2
+  data.tar.gz: ad89602632caab227db154c7e3c71216402b7dedc6cb8489d0e7ff5eae02c57c3e5c47b8035c4e0bc605b9680be6e40ba51d547a0ba60b9e6b1cdecc6ef1fd1a

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Yang Liu and Tycho Tatitscheff
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,68 @@
+# SFSymbol Icon Convertor
+
+
+Given a SVG icon with viewBox that respect [material icon principles](https://m3.material.io/styles/icons/designing-icons), generate appropriate SFSymbol.
+
+## Longer rational
+
+Designers often use the **material guidelines** to produce icon.
+
+<img src="docs/images/material_viewbox.png" alt="Material Viewbox" width=200>
+
+Inside this viewbox of 24x24px, there is a mandatory margin of 2px.  
+The icon is supposed to respect a guideline.
+
+<img src="docs/images/material_guideline.png" alt="Material Guideline" width=200>
+
+For instance theese icons respect material guidelines:
+
+<img src="docs/images/material_example1.png" alt="Material Example" width=150>
+<img src="docs/images/material_example2.png" alt="Material Example" width=150>
+<img src="docs/images/material_example3.png" alt="Material Example" width=150>
+<img src="docs/images/material_example4.png" alt="Material Example" width=150>
+
+More info here: https://m3.material.io/styles/icons/designing-icons
+
+---
+
+On the other side, and while it is still possible to use `svg`, Apple pushes for the use of SfSymbol.
+
+SFSymbols have multiple benefits:
+- performance
+- ability to mix text and image in a proper way
+- ability to do bi (or multi) color icon
+
+<img src="docs/images/sfsymbol_bicolor.png" alt="Material Example" width=400>
+
+More info here: 
+- https://developer.apple.com/documentation/uikit/uiimage/creating_custom_symbol_images_for_your_app
+- https://developer.apple.com/design/human-interface-guidelines/sf-symbols
+
+It require the developper to take a template, and insert the icon inside, while respecting the size and the margin.
+
+<img src="docs/images/sfsymbol_template.png" alt="SfSymbol Template" width=650>
+
+Since a few version, you can provide only three variations:
+- ultralight-S
+- regular-S
+- black-S
+
+And the system (UIKit, or SwiftUI) will interpolate the rest.
+
+<img src="docs/images/sfsymbol_interpolation.png" alt="SfSymbol Template" width=500>
+
+We provide the small, but to respect the material system, you are supposed to use the `.medium`
+
+<img src="docs/images/sfsymbol_size.png" alt="SfSymbol Template" width=500>
+
+## Instalation and usage
+
+`gem install sf_symbol_converter`
+
+Then convert icon one by one:
+
+`sf_symbol_converter convert ./input.svg output.svg`
+
+Or batch convert:
+
+`sf_symbol_converter batch_convert ./input_dir/ ./output_dir`

data/bin/sf-symbol-converter

@@ -1,41 +1,9 @@
 #! /usr/bin/env ruby
 # frozen_string_literal: true
 
-require 'thor'
-require 'nokogiri'
-require './lib/sf_symbol_converter'
-
-# CLI for converting SF Symbols
-class SFSymbolCli < Thor
-  include Thor::Actions
-
-  TEMPLATE_PATH = 'assets/template.svg'
-
-  desc 'convert ICON_SVG [OUTPUT_SVG]', 'Converts an SF Symbol SVG to a template SVG'
-  def convert(icon_svg_path, output_path = 'output.svg')
-    template_svg = Nokogiri::XML(File.open(TEMPLATE_PATH))
-    icon_svg = Nokogiri::XML(File.open(icon_svg_path))
-
-    output_path = output_path || 'output.svg'
-
-    converter = SFSymbolConverter.new(template_svg, icon_svg)
-    converted_svg = converter.convert
-
-    pretty_printed_svg = Nokogiri::XML(converted_svg.to_s, &:noblanks).to_xml(indent: 2)
-
-    File.open(output_path, 'w') { |file| file.write(pretty_printed_svg) }
-  end
-
-  desc 'batch_convert INPUT_DIR OUTPUT_DIR', 'Converts all SVGs in a directory to SFSymbols'
-  def batch_convert(input_dir, output_dir)
-    Dir.glob("#{input_dir}/*.svg").each do |icon_svg_path|
-      icon_svg = Nokogiri::XML(File.open(icon_svg_path))
-
-      output_path = "#{output_dir}/#{File.basename(icon_svg_path)}"
-      convert(icon_svg_path, output_path)
-    end
-  end
-end
+# Add the lib directory to the load path
+$LOAD_PATH.unshift File.expand_path('../../lib', __FILE__)
 
+require 'sf_symbol_converter'
 
 SFSymbolCli.start(ARGV)

data/lib/sf_symbol_converter/cli/sf_symbol_converter.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+require "thor"
+require "nokogiri"
+
+require "sf_symbol_converter"
+
+# CLI for converting SF Symbols
+class SFSymbolCli < Thor
+  include Thor::Actions
+
+  # Determine the root directory of the gem
+  GEM_ROOT = File.expand_path("../../..", __dir__)
+
+  TEMPLATE_PATH = File.join(GEM_ROOT, "assets", "template.svg")
+
+  desc "convert ICON_SVG [OUTPUT_SVG]", "Converts an SF Symbol SVG to a template SVG"
+
+  def convert(icon_svg_path, output_path = "output.svg")
+    template_svg = Nokogiri::XML(File.open(TEMPLATE_PATH))
+    icon_svg = Nokogiri::XML(File.open(icon_svg_path))
+
+    output_path = output_path || "output.svg"
+
+    converter = SFSymbolConverter.new(template_svg, icon_svg)
+    converted_svg = converter.convert
+
+    pretty_printed_svg = Nokogiri::XML(converted_svg.to_s, &:noblanks).to_xml(indent: 2)
+
+    File.open(output_path, "w") { |file| file.write(pretty_printed_svg) }
+  end
+
+  desc "batch_convert INPUT_DIR OUTPUT_DIR", "Converts all SVGs in a directory to SFSymbols"
+
+  def batch_convert(input_dir, output_dir)
+    Dir.glob("#{input_dir}/*.svg").each do |icon_svg_path|
+      icon_svg = Nokogiri::XML(File.open(icon_svg_path))
+
+      output_path = "#{output_dir}/#{File.basename(icon_svg_path)}"
+      convert(icon_svg_path, output_path)
+    end
+  end
+end

data/lib/sf_symbol_converter/converter.rb

@@ -0,0 +1,117 @@
+# frozen_string_literal: true
+
+require "nokogiri"
+
+# Given a source SVG and a SFSymbol template, generate a SFSymbol
+class SFSymbolConverter
+  SOURCE_ICON_VIEWBOX_SIZE = 24
+
+  REFERENCE_SFSYMBOL_FONT_CAPS_HEIGHT = 14
+  TARGET_SYMBOL_HEIGHT_MEDIUM = 16
+
+  SFSYMBOL_MEDIUM_TO_SMALL_SCALE = 0.783
+
+  MARGIN_LINE_WIDTH = 0.5
+
+  attr_accessor :template_svg
+  attr_reader :icon_svg, :icon_validator, :template_validator
+
+  def initialize(template_svg, icon_svg)
+    @template_svg = template_svg
+    @icon_svg = icon_svg
+
+    @icon_validator = IconValidator.new(SOURCE_ICON_VIEWBOX_SIZE)
+    @template_validator = TemplateValidator.new
+
+    @template_trimmer = TemplateTrimmer.new
+
+    @icon_validator.validate(icon_svg)
+    @template_validator.validate(template_svg)
+  end
+
+  def convert
+    @template_svg = @template_trimmer.trim(template_svg)
+    replace_template_symbols_with_source_icons
+    adjust_guidelines
+    @template_svg
+  end
+
+  private
+
+  def cap_height_small
+    baseline_y = get_guide_value(template_svg, :y, "Baseline-S")
+    capline_y = get_guide_value(template_svg, :y, "Capline-S")
+
+    (baseline_y - capline_y).abs
+  end
+
+  def scale_factor_small
+    cap_height_small / REFERENCE_SFSYMBOL_FONT_CAPS_HEIGHT * SFSYMBOL_MEDIUM_TO_SMALL_SCALE
+  end
+
+  def scaled_size_small
+    SOURCE_ICON_VIEWBOX_SIZE * scale_factor_small
+  end
+
+  def vertical_center_small
+    baseline_y = get_guide_value(template_svg, :y, "Baseline-S")
+    capline_y = get_guide_value(template_svg, :y, "Capline-S")
+
+    (baseline_y + capline_y) / 2
+  end
+
+  def horizontal_center(symbol)
+    left_margin = get_guide_value(template_svg, :x, "left-margin-#{symbol}")
+    right_margin = get_guide_value(template_svg, :x, "right-margin-#{symbol}")
+
+    (left_margin + right_margin) / 2
+  end
+
+  def adjusted_left_margin(symbol)
+    # TODO: is it really (MARGIN_LINE_WIDTH / 2) or just MARGIN_LINE_WIDTH
+    horizontal_center(symbol) - scaled_size_small / 2 - (MARGIN_LINE_WIDTH / 2)
+  end
+
+  def adjusted_right_margin(symbol)
+    # TODO: is it really (MARGIN_LINE_WIDTH / 2) or just MARGIN_LINE_WIDTH
+    horizontal_center(symbol) + scaled_size_small / 2 + (MARGIN_LINE_WIDTH / 2)
+  end
+
+  def transform_matrix(symbol)
+    translation_x = horizontal_center(symbol) - scaled_size_small / 2
+    translation_y = vertical_center_small - scaled_size_small / 2
+
+    matrix_text = "%<scale>.6f 0 0 %<scale>.6f %<trans_x>.6f %<trans_y>.6f"
+    parameters = { scale: scale_factor_small, trans_x: translation_x, trans_y: translation_y }
+
+    format(matrix_text, parameters)
+  end
+
+  IDS_TO_REPLACE = %w[Ultralight-S Regular-S Black-S].freeze
+
+  def replace_template_symbols_with_source_icons
+    IDS_TO_REPLACE.each do |symbol|
+      template_symbol_node = template_svg.at_css("##{symbol}")
+
+      template_symbol_node["transform"] = "matrix(#{transform_matrix(symbol)})"
+
+      paths = icon_svg.dup.root.children
+      paths.each do |node|
+        node.delete("fill")
+        node["class"] = "SFSymbolsPreviewWireframe"
+      end
+
+      template_symbol_node.children = paths
+    end
+  end
+
+  def adjust_guidelines
+    IDS_TO_REPLACE.each do |symbol|
+      left_margin_node = template_svg.at_css("#left-margin-#{symbol}")
+      left_margin_node["x1"] = left_margin_node["x2"] = adjusted_left_margin(symbol).to_s
+
+      right_margin_node = template_svg.at_css("#right-margin-#{symbol}")
+      right_margin_node["x1"] = right_margin_node["x2"] = adjusted_right_margin(symbol).to_s
+    end
+  end
+end

data/lib/sf_symbol_converter/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module SFSymbolConverter
+  VERSION = "1.0.0.alpha.1"
+end

data/lib/sf_symbol_converter.rb

@@ -1,122 +1,9 @@
 # frozen_string_literal: true
 
-require 'nokogiri'
-require './lib/utils'
+require_relative 'sf_symbol_converter/utils/get_guide_value'
+require_relative 'sf_symbol_converter/validators/icon_validator'
+require_relative 'sf_symbol_converter/validators/template_validator'
+require_relative 'sf_symbol_converter/trimmer/template_trimmer'
+require_relative 'sf_symbol_converter/converter'
+require_relative 'sf_symbol_converter/cli/sf_symbol_converter'
 
-require './lib/validators/icon_validator'
-require './lib/validators/template_validator'
-require './lib/trimmer/template_trimmer'
-
-# Given a source SVG and a SFSymbol template, generate a SFSymbol
-class SFSymbolConverter
-  SOURCE_ICON_VIEWBOX_SIZE = 24
-
-  REFERENCE_SFSYMBOL_FONT_CAPS_HEIGHT = 14
-  TARGET_SYMBOL_HEIGHT_MEDIUM = 16
-
-  SFSYMBOL_MEDIUM_TO_SMALL_SCALE = 0.783
-
-  MARGIN_LINE_WIDTH = 0.5
-
-  attr_accessor :template_svg
-  attr_reader :icon_svg, :icon_validator, :template_validator
-
-  def initialize(template_svg, icon_svg)
-    @template_svg = template_svg
-    @icon_svg = icon_svg
-
-    @icon_validator = IconValidator.new(SOURCE_ICON_VIEWBOX_SIZE)
-    @template_validator = TemplateValidator.new
-
-    @template_trimmer = TemplateTrimmer.new
-
-    @icon_validator.validate(icon_svg)
-    @template_validator.validate(template_svg)
-  end
-
-  def convert
-    @template_svg = @template_trimmer.trim(template_svg)
-    replace_template_symbols_with_source_icons
-    adjust_guidelines
-    @template_svg
-  end
-
-  private
-
-  def cap_height_small
-    baseline_y = get_guide_value(template_svg, :y, 'Baseline-S')
-    capline_y = get_guide_value(template_svg, :y, 'Capline-S')
-
-    (baseline_y - capline_y).abs
-  end
-
-  def scale_factor_small
-    cap_height_small / REFERENCE_SFSYMBOL_FONT_CAPS_HEIGHT * SFSYMBOL_MEDIUM_TO_SMALL_SCALE
-  end
-
-  def scaled_size_small
-    SOURCE_ICON_VIEWBOX_SIZE * scale_factor_small
-  end
-
-  def vertical_center_small
-    baseline_y = get_guide_value(template_svg, :y, 'Baseline-S')
-    capline_y = get_guide_value(template_svg, :y, 'Capline-S')
-
-    (baseline_y + capline_y) / 2
-  end
-
-  def horizontal_center(symbol)
-    left_margin = get_guide_value(template_svg, :x, "left-margin-#{symbol}")
-    right_margin = get_guide_value(template_svg, :x, "right-margin-#{symbol}")
-
-    (left_margin + right_margin) / 2
-  end
-
-  def adjusted_left_margin(symbol)
-    # TODO: is it really (MARGIN_LINE_WIDTH / 2) or just MARGIN_LINE_WIDTH
-    horizontal_center(symbol) - scaled_size_small / 2 - (MARGIN_LINE_WIDTH / 2)
-  end
-
-  def adjusted_right_margin(symbol)
-    # TODO: is it really (MARGIN_LINE_WIDTH / 2) or just MARGIN_LINE_WIDTH
-    horizontal_center(symbol) + scaled_size_small / 2 + (MARGIN_LINE_WIDTH / 2)
-  end
-
-  def transform_matrix(symbol)
-    translation_x = horizontal_center(symbol) - scaled_size_small / 2
-    translation_y = vertical_center_small - scaled_size_small / 2
-
-    matrix_text = '%<scale>.6f 0 0 %<scale>.6f %<trans_x>.6f %<trans_y>.6f'
-    parameters = { scale: scale_factor_small, trans_x: translation_x, trans_y: translation_y }
-
-    format(matrix_text, parameters)
-  end
-
-  IDS_TO_REPLACE = %w[Ultralight-S Regular-S Black-S].freeze
-
-  def replace_template_symbols_with_source_icons
-    IDS_TO_REPLACE.each do |symbol|
-      template_symbol_node = template_svg.at_css("##{symbol}")
-
-      template_symbol_node['transform'] = "matrix(#{transform_matrix(symbol)})"
-
-      paths = icon_svg.dup.root.children
-      paths.each do |node|
-        node.delete('fill')
-        node['class'] = 'SFSymbolsPreviewWireframe'
-      end
-
-      template_symbol_node.children = paths
-    end
-  end
-
-  def adjust_guidelines
-    IDS_TO_REPLACE.each do |symbol|
-      left_margin_node = template_svg.at_css("#left-margin-#{symbol}")
-      left_margin_node['x1'] = left_margin_node['x2'] = adjusted_left_margin(symbol).to_s
-
-      right_margin_node = template_svg.at_css("#right-margin-#{symbol}")
-      right_margin_node['x1'] = right_margin_node['x2'] = adjusted_right_margin(symbol).to_s
-    end
-  end
-end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: sf_symbol_converter
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 1.0.0.alpha.1
 platform: ruby
 authors:
 - Yang Liu
@@ -51,8 +51,35 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: 1.1.0
-description: Given a SVG icon with viewBox that respect [material icon principles](https://m3.material.io/styles/icons/designing-icons),
-  generate appropriate SFSymbol
+description: "# SFSymbol Icon Convertor\n\n\nGiven a SVG icon with viewBox that respect
+  [material icon principles](https://m3.material.io/styles/icons/designing-icons),
+  generate appropriate SFSymbol.\n\n## Longer rational\n\nDesigners often use the
+  **material guidelines** to produce icon.\n\n<img src=\"docs/images/material_viewbox.png\"
+  alt=\"Material Viewbox\" width=200>\n\nInside this viewbox of 24x24px, there is
+  a mandatory margin of 2px.  \nThe icon is supposed to respect a guideline.\n\n<img
+  src=\"docs/images/material_guideline.png\" alt=\"Material Guideline\" width=200>\n\nFor
+  instance theese icons respect material guidelines:\n\n<img src=\"docs/images/material_example1.png\"
+  alt=\"Material Example\" width=150>\n<img src=\"docs/images/material_example2.png\"
+  alt=\"Material Example\" width=150>\n<img src=\"docs/images/material_example3.png\"
+  alt=\"Material Example\" width=150>\n<img src=\"docs/images/material_example4.png\"
+  alt=\"Material Example\" width=150>\n\nMore info here: https://m3.material.io/styles/icons/designing-icons\n\n---\n\nOn
+  the other side, and while it is still possible to use `svg`, Apple pushes for the
+  use of SfSymbol.\n\nSFSymbols have multiple benefits:\n- performance\n- ability
+  to mix text and image in a proper way\n- ability to do bi (or multi) color icon\n\n<img
+  src=\"docs/images/sfsymbol_bicolor.png\" alt=\"Material Example\" width=400>\n\nMore
+  info here: \n- https://developer.apple.com/documentation/uikit/uiimage/creating_custom_symbol_images_for_your_app\n-
+  https://developer.apple.com/design/human-interface-guidelines/sf-symbols\n\nIt require
+  the developper to take a template, and insert the icon inside, while respecting
+  the size and the margin.\n\n<img src=\"docs/images/sfsymbol_template.png\" alt=\"SfSymbol
+  Template\" width=650>\n\nSince a few version, you can provide only three variations:\n-
+  ultralight-S\n- regular-S\n- black-S\n\nAnd the system (UIKit, or SwiftUI) will
+  interpolate the rest.\n\n<img src=\"docs/images/sfsymbol_interpolation.png\" alt=\"SfSymbol
+  Template\" width=500>\n\nWe provide the small, but to respect the material system,
+  you are supposed to use the `.medium`\n\n<img src=\"docs/images/sfsymbol_size.png\"
+  alt=\"SfSymbol Template\" width=500>\n\n## Instalation and usage\n\n`gem install
+  sf_symbol_converter`\n\nThen convert icon one by one:\n\n`sf_symbol_converter convert
+  ./input.svg output.svg`\n\nOr batch convert:\n\n`sf_symbol_converter batch_convert
+  ./input_dir/ ./output_dir`"
 email:
 - yangl@bam.tech
 - tychot@bam.tech
@@ -61,13 +88,18 @@ executables:
 extensions: []
 extra_rdoc_files: []
 files:
+- LICENSE
+- README.md
 - assets/template.svg
 - bin/sf-symbol-converter
 - lib/sf_symbol_converter.rb
-- lib/trimmer/template_trimmer.rb
-- lib/utils.rb
-- lib/validators/icon_validator.rb
-- lib/validators/template_validator.rb
+- lib/sf_symbol_converter/cli/sf_symbol_converter.rb
+- lib/sf_symbol_converter/converter.rb
+- lib/sf_symbol_converter/trimmer/template_trimmer.rb
+- lib/sf_symbol_converter/utils/get_guide_value.rb
+- lib/sf_symbol_converter/validators/icon_validator.rb
+- lib/sf_symbol_converter/validators/template_validator.rb
+- lib/sf_symbol_converter/version.rb
 homepage: https://github.com/tychota/SfSymbolExporter
 licenses:
 - MIT