backpack 0.4.3 → 0.4.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f408e759a5f6ded65d78dcea7fc361c186230082e7dc82a7a4213d905206a159
-  data.tar.gz: fdbb02fcb38015cf8687ab2085f929acda73eaed25b516d3e093171b58be066b
+  metadata.gz: 9a8c87ef7641484c2cbe0d63bb971dedb9b18151e516ba8af4c34b6cec28c570
+  data.tar.gz: 538a37e07c7f1945c6d7b481426f0f9b447c1162896d28f2f1964e6ca7005385
 SHA512:
-  metadata.gz: 03fb80e4313ac7d799a7c56711b25555fe41915c479d1cb8a2ffc7aaf7c856463a95fa6d854fd77c686ff4d296f912cd2863b102bdfe28adada02ef0e30ff0d6
-  data.tar.gz: 35862131f1a63f798b6caafb8ecc870f08d21d1477dff78c16fd92adb8a0080e582652dae7f126e700d9e1f1d29a4d5f711503e1f180cbb91859876c9e25f484
+  metadata.gz: c525b847afa1b38ba852f3b5aa184c38ca3de2b67c20c64454b84750818fc556f70dfb5022d147d163d6570f10647f9946b735b6e71a8190f9a96e7e50a905de
+  data.tar.gz: 361da155d08c619b13e8c28adf494c97471f73507d827b777411c6b36653c646cfc7364dac208f577f1c92bee6e6162883787fe2d38b397ff07a2b4f6c83cd20

data/README.md

@@ -2,23 +2,26 @@
 
 ## Getting started
 
+Install Backpack globally, then import it in your Rails project.
+
 ```bash
 gem install backpack
+
+# At your Rails project root:
 backpack import
-gem uninstall backpack
 ```
 
 ## Usage
 
 ### Configure colors tokens
 
-Open `lib/backpack/stylesheets/tokens/_colors.scss` and follow the instructions.
+Open `app/assets/stylesheets/tokens/_colors.scss` and follow the instructions.
 
 ### Sync tokens with Figma
 
 1. Use [Export/Import variables](https://www.figma.com/community/plugin/1256972111705530093/export-import-variables) plugin to export the Backpack group.
 2. Save `Backpack.json` in the `figma/` directory.
-3. Run `bin/sync`
+3. Run `backpack sync`
 
 ## Development
 

data/lib/backpack/cli.rb

@@ -1,17 +1,20 @@
 require "thor"
 require "backpack"
+require "json"
+require_relative "commands/sync"
 
 module Backpack
   class CLI < Thor
     include Thor::Actions
 
-    desc "import", "Import Backpack in the current project"
-
     source_root File.expand_path(__dir__)
 
+    desc "import", "Import Backpack in the current project"
     def import
       say ascii_art, :green
 
+      add_radix_colors_dependency if File.exist?("package.json")
+
       directory "stylesheets", "app/assets/stylesheets", recursive: true
       directory "components", "app/components", recursive: true
 
@@ -23,10 +26,44 @@ module Backpack
       directory "../../spec/components", "spec/components", recursive: true do |content|
         content.gsub("require 'spec_helper'", "require 'rails_helper'")
       end
+      directory "../../spec/fixtures/icons", "spec/fixtures/icons", recursive: true
+
+      copy_file "../../vendor/normalize.css", "vendor/normalize.css"
+    end
+
+    desc "sync", "Sync design tokens from Figma to CSS files"
+    def sync
+      Backpack::Commands::Sync.new(shell).sync
+    end
+
+    def self.exit_on_failure?
+      true
     end
 
     private
 
+    def add_radix_colors_dependency
+      package_json_path = "package.json"
+
+      # Read existing package.json or create minimal structure
+      if File.exist?(package_json_path) && !File.zero?(package_json_path)
+        begin
+          package_data = JSON.parse(File.read(package_json_path))
+        rescue JSON::ParserError
+          package_data = {}
+        end
+      else
+        package_data = {}
+      end
+
+      # Add the dependency
+      package_data["dependencies"] ||= {}
+      package_data["dependencies"]["@radix-ui/colors"] = "^3.0.0"
+
+      # Write back to file
+      File.write(package_json_path, "#{JSON.pretty_generate(package_data)}\n")
+    end
+
     def ascii_art
       <<~ASCII
       ┌┐ ┌─┐┌─┐┬┌─┌─┐┌─┐┌─┐┬┌─

data/lib/backpack/commands/sync.rb

@@ -0,0 +1,156 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'date'
+require 'thor'
+
+module Backpack
+  module Commands
+    # Sync command for importing design tokens from Figma to CSS files
+    #
+    # This command looks for files in the current working directory:
+    # - figma/Backpack.json (Figma design tokens export)
+    # - lib/backpack/stylesheets/tokens/*.css (CSS token files to update)
+    #
+    # Usage: backpack sync
+    class Sync
+      include Thor::Actions
+
+      def initialize(shell = Thor::Base.shell.new)
+        @shell = shell
+      end
+
+      def sync
+        @shell.say "Syncing design tokens from Figma...", :green
+
+        layout_json = File.read(layout_tokens_file)
+        layout = JSON.parse(layout_json, symbolize_names: true)
+
+        raise "Wrong name" if layout[:name] != NAME
+
+        modes = layout[:modes]
+        tokens = extract_tokens(layout[:variables], modes)
+
+        # Read all CSS files
+        tokens_css_files = Dir.glob("#{tokens_folder}/*.css")
+
+        rewritten_lines_count = 0
+        remaining_tokens = tokens.keys
+
+        tokens_css_files.each do |file|
+          lines_rewritten = process_css_file(file, tokens, remaining_tokens)
+          rewritten_lines_count += lines_rewritten
+
+          if lines_rewritten > 0
+            file_name = File.basename(file)
+            @shell.say "#{file_name}: #{lines_rewritten} lines rewritten", :yellow
+          end
+        end
+
+        if remaining_tokens.any?
+          @shell.say ""
+          @shell.say "#{remaining_tokens.size} tokens have not been found:", :red
+          remaining_tokens.each do |token|
+            @shell.say token
+          end
+          @shell.say "Please check that these tokens are correctly named."
+        else
+          @shell.say "All tokens synced successfully!", :green
+        end
+      end
+
+      private
+
+      NAME = "Backpack"
+      CSS_VARIABLE_REGEXP = /var\(--([^:]+)\)/
+      CSS_LINE_REGEXP = /--([^:]+): ([^;]+);(.*)/
+      APPEND_PX = proc { |value| "#{value}px" }
+      APPEND_REM = proc { |value| "#{value}rem" }
+      CONVERT_TO_REM = proc { |value| "#{value.to_f / 10.0}rem".gsub(".0rem", "rem") }
+      CONVERSION_RULES = {
+        /(font|height|radius|space)-(\d+|base|full)/ => CONVERT_TO_REM,
+        /(breakpoint)-(.+)/ => APPEND_PX,
+        /container-width/ => APPEND_REM
+      }
+
+      def layout_tokens_file
+        ENV['BACKPACK_TEST_FIGMA_PATH'] || File.expand_path("figma/#{NAME}.json")
+      end
+
+      def tokens_folder
+        ENV['BACKPACK_TEST_TOKENS_PATH'] || File.expand_path("lib/backpack/stylesheets/tokens")
+      end
+
+      def normalized_figma_variable(name)
+        name.split('/').last.downcase.gsub(' ', '-')
+      end
+
+      def extract_tokens(variables, modes)
+        tokens = {}
+
+        variables.each do |variable|
+          name = if (css_name = variable.dig(:codeSyntax, :WEB))
+                   CSS_VARIABLE_REGEXP.match(css_name)[1]
+                 else
+                   normalized_figma_variable(variable[:name])
+                 end
+
+          value = variable[:resolvedValuesByMode][modes.keys[0]]
+
+          final_value = if value[:aliasName]
+                          "var(--#{normalized_figma_variable(value[:aliasName])})"
+                        else
+                          apply_conversion_rules(name, value[:resolvedValue])
+                        end
+
+          tokens[name] = final_value
+        end
+
+        tokens
+      end
+
+      def apply_conversion_rules(name, value)
+        CONVERSION_RULES.each do |pattern, conversion|
+          return conversion.call(value) if pattern.match?(name)
+        end
+        value
+      end
+
+      def process_css_file(file, tokens, remaining_tokens)
+        lines = []
+        lines_rewritten = 0
+
+        File.open(file, 'r') do |css_file|
+          css_file.each_line do |line|
+            variable = line.match(CSS_LINE_REGEXP)
+
+            unless variable
+              lines << line
+              next
+            end
+
+            token_name = variable[1]
+            token_value = tokens[token_name]
+
+            unless token_value
+              lines << line
+              next
+            end
+
+            rewritten_line = line.gsub(CSS_LINE_REGEXP) do |_match|
+              "--#{variable[1]}: #{token_value}; /* imported from Figma on #{Date.today} */"
+            end
+
+            lines_rewritten += 1
+            remaining_tokens.delete(token_name)
+            lines << rewritten_line
+          end
+        end
+
+        File.write(file, lines.join) if lines_rewritten > 0
+
+        lines_rewritten
+      end
+    end
+  end
+end

data/lib/backpack/components/button/button.css

@@ -133,8 +133,8 @@
 
 /* ghost */
 .variant-ghost {
-  color: var(--accent-9);
   background-color: transparent;
+  color: var(--accent-9);
 }
 
 @media (hover: hover) {

data/lib/backpack/components/icon_sprite.rb

@@ -1,19 +1,20 @@
 # frozen_string_literal: true
 
-require 'rails-html-sanitizer'
+require "rails-html-sanitizer"
 
 class Components::IconSprite < Components::Base
   ICON_PATHS = [
     Rails.root&.join("app/assets/icons"),
-    Rails.root&.join("node_modules/lucide-static/icons"),
-    File.expand_path("../../../spec/fixtures/icons", __dir__)
+    Rails.root&.join("node_modules/lucide-static/icons")
   ].compact.freeze
 
   def view_template
     svg(**mix({ class: root_classes }, @attributes, hidden: true)) do |s|
       s.defs do
         Current.icons.sort.map do |key|
+          # rubocop:disable Rails/OutputSafety
           raw Icon.new(key).as_svg_symbol
+          # rubocop:enable Rails/OutputSafety
         end
       end
     end
@@ -28,7 +29,7 @@ class Components::IconSprite < Components::Base
     prop :key, String, :positional
 
     def as_svg_symbol
-      icon_files = Dir.glob("{#{ICON_PATHS.join(',')}}/#{@key}.svg")
+      icon_files = Dir.glob("{#{ICON_PATHS.join(",")}}/#{@key}.svg")
 
       return if icon_files.empty?
 
@@ -39,6 +40,7 @@ class Components::IconSprite < Components::Base
 
     private
 
+    # rubocop:disable Rails/OutputSafety
     def sanitized_svg(svg_string)
       Rails::Html::SafeListSanitizer
         .new
@@ -48,6 +50,7 @@ class Components::IconSprite < Components::Base
         .strip
         .html_safe
     end
+    # rubocop:enable Rails/OutputSafety
 
     def allowed_tags
       %w[svg path circle rect line polyline polygon ellipse g defs use]

data/lib/backpack/stylesheets/utilities/_sr-only.css

@@ -21,14 +21,14 @@
 
 .sr-only,
 .sr-only-focusable:not(:focus, :focus-within) {
-	border: 0 !important;
-	clip-path: inset(50%) !important; /* 2 */
-	height: 1px !important;
-	margin: -1px !important;
-	overflow: hidden !important;
-	padding: 0 !important;
-	width: 1px !important;
-	white-space: nowrap !important; /* 3 */
+  border: 0 !important;
+  clip-path: inset(50%) !important; /* 2 */
+  height: 1px !important;
+  margin: -1px !important;
+  overflow: hidden !important;
+  padding: 0 !important;
+  width: 1px !important;
+  white-space: nowrap !important; /* 3 */
 }
 
 /*
@@ -37,7 +37,7 @@
 */
 .sr-only:not(caption),
 .sr-only-focusable:not(caption):not(:focus, :focus-within) {
-	position: absolute !important;
+  position: absolute !important;
 }
 
 /*
@@ -46,5 +46,5 @@
 */
 .sr-only *,
 .sr-only-focusable:not(:focus, :focus-within) * {
-	overflow: hidden !important;
+  overflow: hidden !important;
 }

data/lib/backpack/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Backpack
-  VERSION = "0.4.3"
+  VERSION = "0.4.5"
 end

data/spec/cli/import_spec.rb

@@ -30,6 +30,7 @@ describe Backpack::CLI, type: :cli do
       expect(output).to include("create  spec/components/button_spec.rb")
       expect(output).to include("create  spec/components/previews/button_preview.rb")
       expect(output).to include("create  spec/components/previews/button_preview/overview.html.erb")
+      expect(output).to include("create  vendor/normalize.css")
     end
 
     it "copies the folders" do
@@ -38,14 +39,27 @@ describe Backpack::CLI, type: :cli do
       expect(File.directory?("app/components")).to be true
       expect(File.directory?("spec/components")).to be true
       expect(File.directory?("spec/components/previews")).to be true
+      expect(File.directory?("spec/fixtures/icons")).to be true
     end
 
-    it "copies the lib files" do
+    it "copies the lib & vendor files" do
       command
       expect(File.exist?("lib/backpack/attributes.rb")).to be true
       expect(File.exist?("lib/backpack/classes.rb")).to be true
       expect(File.exist?("lib/backpack/identifier.rb")).to be true
       expect(File.exist?("lib/backpack/tokens.rb")).to be true
+      expect(File.exist?("vendor/normalize.css")).to be true
+    end
+
+    context "when there is a package.json" do
+      before do
+        FileUtils.touch("package.json")
+      end
+
+      it "installs radix colors" do
+        command
+        expect(File.read("package.json")).to include('"@radix-ui/colors": "^3.0.0"')
+      end
     end
   end
 end

data/spec/cli/sync_spec.rb

@@ -0,0 +1,266 @@
+require 'spec_helper'
+
+describe Backpack::CLI, type: :cli do
+  sandbox_dir = "sandbox"
+
+  around do |example|
+    FileUtils.mkdir(sandbox_dir) unless File.exist?(sandbox_dir)
+    within_dir(sandbox_dir) do
+      example.run
+    end
+  ensure
+    FileUtils.rm_rf(sandbox_dir)
+  end
+
+  describe "sync" do
+    let(:figma_fixture_path) { File.expand_path("../fixtures/figma/Backpack.json", __dir__) }
+    let(:css_fixture_path) { File.expand_path("../fixtures/tokens/_test.css", __dir__) }
+    let(:figma_dir) { "figma" }
+    let(:tokens_dir) { "lib/backpack/stylesheets/tokens" }
+    let(:figma_file) { "#{figma_dir}/Backpack.json" }
+    let(:css_file) { "#{tokens_dir}/_test.css" }
+
+    before do
+      # Create directory structure
+      FileUtils.mkdir_p(figma_dir)
+      FileUtils.mkdir_p(tokens_dir)
+
+      # Copy fixtures to test environment
+      FileUtils.cp(figma_fixture_path, figma_file)
+      FileUtils.cp(css_fixture_path, css_file)
+
+      # Set environment variables to override paths for testing
+      ENV['BACKPACK_TEST_FIGMA_PATH'] = File.expand_path(figma_file)
+      ENV['BACKPACK_TEST_TOKENS_PATH'] = File.expand_path(tokens_dir)
+    end
+
+    after do
+      # Clean up environment variables
+      ENV.delete('BACKPACK_TEST_FIGMA_PATH')
+      ENV.delete('BACKPACK_TEST_TOKENS_PATH')
+    end
+
+    context "when figma file exists and tokens are found" do
+      let(:command) { `bundle exec ruby ../bin/backpack sync 2>&1` }
+      let(:output) { command.chomp }
+
+      it "successfully syncs tokens from Figma to CSS files" do
+        expect(output).to include("Syncing design tokens from Figma...")
+        expect(output).to include("_test.css: 6 lines rewritten")
+      end
+
+      it "updates CSS variables with converted values" do
+        command
+        css_content = File.read(css_file)
+
+        # Font sizes should be converted to rem
+        expect(css_content).to include("--font-1: 1.2rem; /* imported from Figma on #{Date.today} */")
+        expect(css_content).to include("--font-2: 1.4rem; /* imported from Figma on #{Date.today} */")
+
+        # Radius should be converted to rem
+        expect(css_content).to include("--radius-1: 0.2rem; /* imported from Figma on #{Date.today} */")
+
+        # Space should be converted to rem
+        expect(css_content).to include("--space-1: var(--space-base); /* imported from Figma on #{Date.today} */")
+        expect(css_content).to include("--space-base: 0.2rem; /* imported from Figma on #{Date.today} */")
+
+        # Container width should be converted to rem
+        expect(css_content).to include("--container-width: 128rem; /* imported from Figma on #{Date.today} */")
+      end
+
+      it "preserves unchanged CSS variables" do
+        command
+        css_content = File.read(css_file)
+
+        # These should remain unchanged
+        expect(css_content).to include("--font-unchanged: 20px;")
+        expect(css_content).to include("--unknown-token: 999px;")
+      end
+
+      it "handles alias references correctly" do
+        command
+        css_content = File.read(css_file)
+
+        # space-1 should reference space-base as an alias
+        expect(css_content).to include("--space-1: var(--space-base);")
+      end
+
+      it "reports remaining unmatched tokens" do
+        # Create a CSS file that doesn't have all tokens
+        limited_css = ":root {\n  --font-1: 10px;\n}"
+        File.write(css_file, limited_css)
+
+        output = `bundle exec ruby ../bin/backpack sync 2>&1`.chomp
+
+        expect(output).to include("5 tokens have not been found:")
+        expect(output).to include("font-2")
+        expect(output).to include("radius-1")
+        expect(output).to include("space-1")
+        expect(output).to include("space-base")
+        expect(output).to include("container-width")
+        expect(output).to include("Please check that these tokens are correctly named.")
+      end
+
+      it "reports success when all tokens are matched" do
+        expect(output).to include("All tokens synced successfully!")
+      end
+    end
+
+    context "when figma file is missing" do
+      before do
+        FileUtils.rm(figma_file)
+      end
+
+      let(:command) { `bundle exec ruby ../bin/backpack sync 2>&1` }
+
+      it "raises an error" do
+        expect { command }.not_to raise_error
+        expect(command).to include("No such file or directory")
+      end
+    end
+
+    context "when figma file has wrong name" do
+      before do
+        wrong_figma_data = File.read(figma_file).gsub('"name": "Backpack"', '"name": "WrongName"')
+        File.write(figma_file, wrong_figma_data)
+      end
+
+      let(:command) { `bundle exec ruby ../bin/backpack sync 2>&1` }
+
+      it "raises an error for wrong name" do
+        expect { command }.not_to raise_error
+        expect(command).to include("Wrong name")
+      end
+    end
+
+    context "when no CSS files exist in tokens directory" do
+      before do
+        FileUtils.rm_rf(tokens_dir)
+        FileUtils.mkdir_p(tokens_dir)
+      end
+
+      let(:command) { `bundle exec ruby ../bin/backpack sync 2>&1` }
+      let(:output) { command.chomp }
+
+      it "completes without errors but reports unmatched tokens" do
+        expect(output).to include("Syncing design tokens from Figma...")
+        expect(output).to include("6 tokens have not been found:")
+        expect(output).to include("Please check that these tokens are correctly named.")
+      end
+    end
+
+    context "when CSS files exist but have no matching tokens" do
+      before do
+        empty_css = ":root {\n  /* no matching tokens */\n  --other-token: 123px;\n}"
+        File.write(css_file, empty_css)
+      end
+
+      let(:command) { `bundle exec ruby ../bin/backpack sync 2>&1` }
+      let(:output) { command.chomp }
+
+      it "reports all tokens as unmatched" do
+        expect(output).to include("6 tokens have not been found:")
+        expect(output).to include("font-1")
+        expect(output).to include("font-2")
+        expect(output).to include("radius-1")
+        expect(output).to include("space-1")
+        expect(output).to include("space-base")
+        expect(output).to include("container-width")
+      end
+    end
+
+    describe "conversion rules" do
+      before do
+        # Create specific test cases for conversion rules
+        test_css = <<~CSS
+          :root {
+            --font-1: 10px;
+            --height-1: 10px;
+            --radius-1: 1px;
+            --space-1: 1px;
+            --breakpoint-xs: 100px;
+            --container-width: 100px;
+          }
+        CSS
+        File.write(css_file, test_css)
+
+        # Create figma data with breakpoint token
+        figma_data = JSON.parse(File.read(figma_file))
+        figma_data["variables"] << {
+          "id" => "VariableID:test:1",
+          "name" => "Layout/Media queries/Breakpoint XS",
+          "type" => "FLOAT",
+          "valuesByMode" => { "1:0" => 576 },
+          "resolvedValuesByMode" => { "1:0" => { "resolvedValue" => 576, "alias" => nil } },
+          "codeSyntax" => {}
+        }
+        figma_data["variables"] << {
+          "id" => "VariableID:test:2",
+          "name" => "Typography/Line height/height-1",
+          "type" => "FLOAT",
+          "valuesByMode" => { "1:0" => 16 },
+          "resolvedValuesByMode" => { "1:0" => { "resolvedValue" => 16, "alias" => nil } },
+          "codeSyntax" => {}
+        }
+        File.write(figma_file, JSON.generate(figma_data))
+      end
+
+      let(:command) { `bundle exec ruby ../bin/backpack sync 2>&1` }
+
+      it "applies correct conversion rules" do
+        command
+        css_content = File.read(css_file)
+
+        # Font and height should convert to rem (value / 10)
+        expect(css_content).to include("--font-1: 1.2rem;")
+        expect(css_content).to include("--height-1: 1.6rem;")
+
+        # Radius should convert to rem (value / 10)
+        expect(css_content).to include("--radius-1: 0.2rem;")
+
+        # Space should convert to rem (value / 10)
+        expect(css_content).to include("--space-1: var(--space-base);")
+
+        # Breakpoint should append px
+        expect(css_content).to include("--breakpoint-xs: 576px;")
+
+        # Container width should append rem
+        expect(css_content).to include("--container-width: 128rem;")
+      end
+    end
+
+    describe "help command" do
+      let(:help_output) { `bundle exec ruby ../bin/backpack help sync 2>&1`.chomp }
+
+      it "shows sync command in help" do
+        expect(help_output).to include("Usage:")
+        expect(help_output).to include("backpack sync")
+        expect(help_output).to include("Sync design tokens from Figma to CSS files")
+      end
+    end
+
+    describe "command availability" do
+      let(:commands_output) { `bundle exec ruby ../bin/backpack help 2>&1`.chomp }
+
+      it "lists sync as an available command" do
+        expect(commands_output).to include("backpack sync")
+        expect(commands_output).to include("Sync design tokens from Figma to CSS files")
+      end
+    end
+
+    describe "working directory behavior" do
+      it "uses current working directory for file paths" do
+        # This test verifies that the sync command looks for files in the current
+        # working directory rather than relative to the gem installation
+
+        # The other tests already demonstrate this behavior by using environment
+        # variables to override paths. This test documents the expected behavior.
+        sync_cmd = Backpack::Commands::Sync.new
+
+        # Without environment variables, paths should be relative to current directory
+        expect(sync_cmd.send(:layout_tokens_file)).to eq(File.expand_path("figma/Backpack.json"))
+        expect(sync_cmd.send(:tokens_folder)).to eq(File.expand_path("lib/backpack/stylesheets/tokens"))
+      end
+    end
+  end
+end