primer_view_components 0.0.25 → 0.0.30

data/app/lib/primer/classify.rb

@@ -17,7 +17,6 @@ module Primer
 
     INVALID_CLASS_NAME_PREFIXES =
       (["bg-", "color-", "text-", "d-", "v-align-", "wb-", "text-", "box-shadow-"] + CONCAT_KEYS.map { |k| "#{k}-" }).freeze
-    FUNCTIONAL_COLOR_REGEX = /(primary|secondary|tertiary|link|success|warning|danger|info)/.freeze
 
     COLOR_KEY = :color
     BG_KEY = :bg
@@ -80,18 +79,20 @@ module Primer
         ]
       }
     }.freeze
-    BORDER_KEYS = %i[border border_color].freeze
+    BORDER_KEY = :border
+    BORDER_COLOR_KEY = :border_color
     BORDER_MARGIN_KEYS = %i[border_top border_bottom border_left border_right].freeze
     BORDER_RADIUS_KEY = :border_radius
     TYPOGRAPHY_KEYS = [:font_size].freeze
     VALID_KEYS = (
       CONCAT_KEYS +
       BOOLEAN_MAPPINGS.keys +
-      BORDER_KEYS +
       BORDER_MARGIN_KEYS +
       TYPOGRAPHY_KEYS +
       TEXT_KEYS +
       [
+        BORDER_KEY,
+        BORDER_COLOR_KEY,
         BORDER_RADIUS_KEY,
         COLOR_KEY,
         BG_KEY,
@@ -198,25 +199,17 @@ module Primer
           if val.to_s.start_with?("#")
             memo[:styles] << "background-color: #{val};"
           else
-            memo[:classes] << "bg-#{val.to_s.dasherize}"
+            memo[:classes] << Primer::Classify::FunctionalBackgroundColors.color(val)
           end
         elsif key == COLOR_KEY
-          char_code = val[-1].ord
-          # Does this string end in a character that is NOT a number?
-          memo[:classes] <<
-            if (char_code >= 48 && char_code <= 57) || # 48 is the charcode for 0; 57 is the charcode for 9
-               FUNCTIONAL_COLOR_REGEX.match?(val)
-              "color-#{val.to_s.dasherize}"
-            else
-              "text-#{val.to_s.dasherize}"
-            end
+          memo[:classes] << Primer::Classify::FunctionalTextColors.color(val)
         elsif key == DISPLAY_KEY
           memo[:classes] << "d#{breakpoint}-#{val.to_s.dasherize}"
         elsif key == VERTICAL_ALIGN_KEY
           memo[:classes] << "v-align-#{val.to_s.dasherize}"
         elsif key == WORD_BREAK_KEY
           memo[:classes] << "wb-#{val.to_s.dasherize}"
-        elsif BORDER_KEYS.include?(key)
+        elsif key == BORDER_KEY
           border_value = if val == true
                            "border"
                          else
@@ -224,6 +217,8 @@ module Primer
                          end
 
           memo[:classes] << border_value
+        elsif key == BORDER_COLOR_KEY
+          memo[:classes] << Primer::Classify::FunctionalBorderColors.color(val)
         elsif BORDER_MARGIN_KEYS.include?(key)
           memo[:classes] << "#{key.to_s.dasherize}-#{val}"
         elsif key == BORDER_RADIUS_KEY
@@ -257,9 +252,11 @@ module Primer
           memo[:classes] << "#{key.to_s.dasherize}#{breakpoint}-n#{val.abs}"
         elsif key == BOX_SHADOW_KEY
           memo[:classes] << if val == true
-                              "box-shadow"
+                              "color-shadow-small"
+                            elsif val == :none || val.blank?
+                              "box-shadow-none"
                             else
-                              "box-shadow-#{val.to_s.dasherize}"
+                              "color-shadow-#{val.to_s.dasherize}"
                             end
         elsif key == VISIBILITY_KEY
           memo[:classes] << "v-#{val.to_s.dasherize}"

data/app/lib/primer/classify/cache.rb

@@ -50,8 +50,13 @@ module Primer
           )
 
           preload(
-            keys: [Primer::Classify::COLOR_KEY, Primer::Classify::BG_KEY],
-            values: [:blue, :gray_dark, :gray, :gray_light, :red, :orange, :orange_light, :yellow, :green, :purple, :white, :pink]
+            keys: [Primer::Classify::COLOR_KEY],
+            values: [*Primer::Classify::FunctionalTextColors::OPTIONS, *Primer::Classify::FunctionalTextColors::DEPRECATED_OPTIONS]
+          )
+
+          preload(
+            keys: [Primer::Classify::BG_KEY],
+            values: [*Primer::Classify::FunctionalBackgroundColors::OPTIONS, *Primer::Classify::FunctionalBackgroundColors::DEPRECATED_OPTIONS]
           )
 
           preload(
@@ -96,7 +101,7 @@ module Primer
 
           preload(
             keys: Primer::Classify::BOX_SHADOW_KEY,
-            values: [true, :medium, :large, :extra_large, :none]
+            values: [true, :small, :medium, :large, :extra_large, :none]
           )
 
           preload(

data/app/lib/primer/classify/functional_background_colors.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module Primer
+  class Classify
+    # Background specific functional colors
+    # https://primer-css-git-mkt-color-modes-docs-primer.vercel.app/css/support/v16-migration#background
+    class FunctionalBackgroundColors < FunctionalColors
+      FUNCTIONAL_OPTIONS = {
+        primary: :primary,
+        secondary: :secondary,
+        tertiary: :tertiary,
+        canvas: :canvas,
+        canvas_inset: :canvas_inset,
+        canvas_inverse: :canvas_inverse,
+        info: :info,
+        info_inverse: :info_inverse,
+        success: :success,
+        success_inverse: :success_inverse,
+        warning: :warning,
+        warning_inverse: :warning_inverse,
+        danger: :danger,
+        danger_inverse: :danger_inverse,
+        overlay: :overlay
+      }.freeze
+
+      MAPPINGS = {
+        white: FUNCTIONAL_OPTIONS[:primary],
+        gray_light: FUNCTIONAL_OPTIONS[:secondary],
+        gray: FUNCTIONAL_OPTIONS[:tertiary],
+        gray_dark: FUNCTIONAL_OPTIONS[:canvas_inverse],
+        blue_light: FUNCTIONAL_OPTIONS[:info],
+        blue: FUNCTIONAL_OPTIONS[:info_inverse],
+        green_light: FUNCTIONAL_OPTIONS[:success],
+        green: FUNCTIONAL_OPTIONS[:success_inverse],
+        yellow_light: FUNCTIONAL_OPTIONS[:warning],
+        yellow: FUNCTIONAL_OPTIONS[:warning_inverse],
+        red_light: FUNCTIONAL_OPTIONS[:danger],
+        red: FUNCTIONAL_OPTIONS[:danger_inverse]
+      }.freeze
+
+      OPTIONS = FUNCTIONAL_OPTIONS.values.freeze
+      OPTIONS_WITHOUT_MAPPINGS = [:purple_light, :purple, :yellow_dark, :orange, :pink].freeze
+      DEPRECATED_OPTIONS = [*MAPPINGS.keys, *OPTIONS_WITHOUT_MAPPINGS].freeze
+
+      class << self
+        def color(val)
+          functional_color(
+            key: "background",
+            value: val,
+            mappings: MAPPINGS,
+            non_functional_prefix: "bg",
+            functional_prefix: "color-bg",
+            number_prefix: "bg",
+            functional_options: OPTIONS,
+            options_without_mappigs: OPTIONS_WITHOUT_MAPPINGS
+          )
+        end
+      end
+    end
+  end
+end

data/app/lib/primer/classify/functional_border_colors.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module Primer
+  class Classify
+    # Border specific functional colors
+    # https://primer-css-git-mkt-color-modes-docs-primer.vercel.app/css/support/v16-migration#border
+    class FunctionalBorderColors < FunctionalColors
+      FUNCTIONAL_OPTIONS = {
+        primary: :primary,
+        secondary: :secondary,
+        tertiary: :tertiary,
+        info: :info,
+        success: :success,
+        warning: :warning,
+        danger: :danger,
+        inverse: :inverse,
+        overlay: :overlay
+      }.freeze
+
+      MAPPINGS = {
+        gray: FUNCTIONAL_OPTIONS[:primary],
+        gray_light: FUNCTIONAL_OPTIONS[:secondary],
+        gray_dark: FUNCTIONAL_OPTIONS[:tertiary],
+        blue: FUNCTIONAL_OPTIONS[:info],
+        green: FUNCTIONAL_OPTIONS[:success],
+        yellow: FUNCTIONAL_OPTIONS[:warning],
+        red: FUNCTIONAL_OPTIONS[:danger],
+        white: FUNCTIONAL_OPTIONS[:inverse]
+      }.freeze
+
+      OPTIONS = FUNCTIONAL_OPTIONS.values.freeze
+      OPTIONS_WITHOUT_MAPPINGS = [:gray_darker, :blue_light, :red_light, :purple, :black_fade, :white_fade].freeze
+      DEPRECATED_OPTIONS = [*MAPPINGS.keys, *OPTIONS_WITHOUT_MAPPINGS].freeze
+
+      class << self
+        def color(val)
+          functional_color(
+            key: "border",
+            value: val,
+            mappings: MAPPINGS,
+            non_functional_prefix: "border",
+            functional_prefix: "color-border",
+            number_prefix: "border",
+            functional_options: OPTIONS,
+            options_without_mappigs: OPTIONS_WITHOUT_MAPPINGS
+          )
+        end
+      end
+    end
+  end
+end

data/app/lib/primer/classify/functional_colors.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+module Primer
+  class Classify
+    # https://primer-css-git-mkt-color-modes-docs-primer.vercel.app/css/support/v16-migration
+    class FunctionalColors
+      class << self
+        def color(val)
+          # Implemented by class' childrens.
+        end
+
+        private
+
+        # @param key [String|Symbol] Option name.
+        # @param value [String|Symbol] Option value.
+        # @param mappings [Hash] A `color` => `functional_color` mapping hash.
+        # @param non_functional_prefix [String] The prefix to use for the non-functional color classes. E.g. "text" would create "text-value".
+        # @param functional_prefix [String] The prefix to use for the functional color classes. E.g. "color-text" would create "color-text-value".
+        # @param number_prefix [String] The prefix to use for colors ending with number. E.g. "text" would create "text-value-1".
+        # @param functional_options [Array] All the acceptable functional values.
+        # @param options_without_mappigs [Array] Non functional values that don't have an associated functional color.
+        def functional_color(
+          key:,
+          value:,
+          mappings:,
+          non_functional_prefix:,
+          functional_prefix: "",
+          number_prefix: "",
+          functional_options:,
+          options_without_mappigs: []
+        )
+          sym_value = value.to_sym
+          dasherized_value = value.to_s.dasherize
+          # the value is a functional color
+          return "#{number_prefix}-#{dasherized_value}" if ends_with_number?(sym_value)
+          return "#{functional_prefix}-#{dasherized_value}" if functional_options.include?(sym_value)
+          # if the app still allows non functional colors
+          return "#{non_functional_prefix}-#{dasherized_value}" unless force_functional_colors?
+
+          if mappings.key?(sym_value) || options_without_mappigs.include?(sym_value)
+            functional_color = mappings[sym_value]
+            # colors without functional mapping stay the same
+            return "#{non_functional_prefix}-#{dasherized_value}" if functional_color.blank?
+
+            ActiveSupport::Deprecation.warn("#{key} #{value} is deprecated. Please use #{functional_color} instead.") unless Rails.env.production? || silence_deprecations?
+
+            return "#{functional_prefix}-#{functional_color.to_s.dasherize}"
+          end
+
+          raise ArgumentError, "#{key} #{value} does not exist." unless Rails.env.production?
+        end
+
+        def ends_with_number?(val)
+          char_code = val[-1].ord
+          char_code >= 48 && char_code <= 57
+        end
+
+        def force_functional_colors?
+          Rails.application.config.primer_view_components.force_functional_colors
+        end
+
+        def silence_deprecations?
+          Rails.application.config.primer_view_components.silence_deprecations
+        end
+      end
+    end
+  end
+end

data/app/lib/primer/classify/functional_text_colors.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module Primer
+  class Classify
+    # Text specific functional colors.
+    # https://primer-css-git-mkt-color-modes-docs-primer.vercel.app/css/support/v16-migration#text
+    class FunctionalTextColors < FunctionalColors
+      FUNCTIONAL_OPTIONS = {
+        primary: :text_primary,
+        secondary: :text_secondary,
+        tertiary: :text_tertiary,
+        link: :text_link,
+        success: :text_success,
+        warning: :text_warning,
+        danger: :text_danger,
+        white: :text_white,
+        inverse: :text_inverse
+      }.freeze
+
+      # colors mapping to `nil` will preserve the old classes.
+      # e.g. `text: :orange` will generate `text-orange`.
+      MAPPINGS = {
+        gray_dark: FUNCTIONAL_OPTIONS[:primary],
+        gray: FUNCTIONAL_OPTIONS[:secondary],
+        gray_light: FUNCTIONAL_OPTIONS[:tertiary],
+        blue: FUNCTIONAL_OPTIONS[:link],
+        green: FUNCTIONAL_OPTIONS[:success],
+        yellow: FUNCTIONAL_OPTIONS[:warning],
+        red: FUNCTIONAL_OPTIONS[:danger],
+        white: FUNCTIONAL_OPTIONS[:white]
+      }.freeze
+
+      OPTIONS = [
+        :icon_primary,
+        :icon_secondary,
+        :icon_tertiary,
+        :icon_info,
+        :icon_success,
+        :icon_warning,
+        :icon_danger,
+        *FUNCTIONAL_OPTIONS.values
+      ].freeze
+      OPTIONS_WITHOUT_MAPPINGS = [:black, :orange, :orange_light, :purple, :pink, :inherit].freeze
+      DEPRECATED_OPTIONS = [*MAPPINGS.keys, *OPTIONS_WITHOUT_MAPPINGS].freeze
+
+      class << self
+        def color(val)
+          functional_color(
+            key: "color",
+            value: val,
+            mappings: MAPPINGS,
+            non_functional_prefix: "text",
+            functional_prefix: "color",
+            number_prefix: "color",
+            functional_options: OPTIONS,
+            options_without_mappigs: OPTIONS_WITHOUT_MAPPINGS
+          )
+        end
+      end
+    end
+  end
+end

data/app/lib/primer/fetch_or_fallback_helper.rb

@@ -6,13 +6,18 @@
 # Use this helper to quietly ensure a value is
 # one that you expect:
 #
-# allowed_values  - allowed options for *value*
-# given_value     - input being coerced
-# fallback        - returned if *given_value* is not included in *allowed_values*
+# allowed_values    - allowed options for *value*
+# given_value       - input being coerced
+# fallback          - returned if *given_value* is not included in *allowed_values*
+# deprecated_values - deprecated options for *value*. Will warn of deprecation if not in production
 #
 # fetch_or_fallback([1,2,3], 5, 2) => 2
 # fetch_or_fallback([1,2,3], 1, 2) => 1
 # fetch_or_fallback([1,2,3], nil, 2) => 2
+#
+# With deprecations:
+# fetch_or_fallback([1,2], 3, 2, deprecated_values: [3]) => 3
+# fetch_or_fallback([1,2], nil, 2, deprecated_values: [3]) => 2
 module Primer
   # :nodoc:
   module FetchOrFallbackHelper
@@ -20,8 +25,12 @@ module Primer
 
     InvalidValueError = Class.new(StandardError)
 
-    def fetch_or_fallback(allowed_values, given_value, fallback = nil)
+    def fetch_or_fallback(allowed_values, given_value, fallback = nil, deprecated_values: [])
       if allowed_values.include?(given_value)
+        given_value
+      elsif deprecated_values.include?(given_value)
+        ActiveSupport::Deprecation.warn("#{given_value} is deprecated and will be removed in a future version.") unless Rails.env.production? || silence_deprecations?
+
         given_value
       else
         if fallback_raises && ENV["RAILS_ENV"] != "production" && ENV["STORYBOOK"] != "true"
@@ -46,5 +55,9 @@ module Primer
         fallback
       end
     end
+
+    def silence_deprecations?
+      Rails.application.config.primer_view_components.silence_deprecations
+    end
   end
 end

data/app/lib/primer/status/dsl.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+require "active_support/concern"
+
+module Primer
+  # :nodoc:
+  module Status
+    # DSL to allow components to register their status.
+    #
+    # Example:
+    #
+    # class MyComponent < ViewComponent::Base
+    #   include Primer::Status::Dsl
+    #   status :beta
+    # end
+    module Dsl
+      extend ActiveSupport::Concern
+
+      STATUSES = {
+        alpha: :alpha,
+        beta: :beta,
+        stable: :stable,
+        deprecated: :deprecated
+      }.freeze
+
+      class UnknownStatusError < StandardError; end
+
+      included do
+        class_attribute :component_status, instance_writer: false, default: STATUSES[:alpha]
+      end
+
+      class_methods do
+        def status(status = nil)
+          return component_status if status.nil?
+
+          raise UnknownStatusError, "status #{status} does not exist" if STATUSES[status].nil?
+
+          self.component_status = STATUSES[status]
+        end
+      end
+    end
+  end
+end

data/app/lib/primer/test_selector_helper.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Primer
+  # Module to allow components to deal with the `test_selector` argument.
+  # It will only add the selector if env is not Production.
+  #
+  # test_selecotr: "foo" => data-test-selector="foo"
+  module TestSelectorHelper
+    TEST_SELECTOR_TAG = :test_selector
+
+    def add_test_selector(args)
+      if args.key?(TEST_SELECTOR_TAG) && !Rails.env.production?
+        args[:data] ||= {}
+        args[:data][TEST_SELECTOR_TAG] = args[TEST_SELECTOR_TAG]
+      end
+
+      args.except(TEST_SELECTOR_TAG)
+    end
+  end
+end