openproject-primer_view_components 0.6.3

data/app/lib/primer/fetch_or_fallback_helper.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+# Primer::FetchOrFallbackHelper
+# A little helper to enable graceful fallbacks
+#
+# 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*
+# 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
+    mattr_accessor :fallback_raises, default: true
+
+    InvalidValueError = Class.new(StandardError)
+
+    def fetch_or_fallback(allowed_values, given_value, fallback = nil, deprecated_values: nil)
+      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"
+          raise InvalidValueError, <<~MSG
+            fetch_or_fallback was called with an invalid value.
+
+            Expected one of: #{allowed_values.inspect}
+            Got: #{given_value.inspect}
+
+            This will not raise in production, but will instead fallback to: #{fallback.inspect}
+          MSG
+        end
+
+        fallback
+      end
+    end
+
+    # rubocop:disable Style/OptionalBooleanParameter
+    def fetch_or_fallback_boolean(given_value, fallback = false)
+      if [true, false].include?(given_value)
+        given_value
+      else
+        fallback
+      end
+    end
+    # rubocop:enable Style/OptionalBooleanParameter
+
+    def silence_deprecations?
+      Rails.application.config.primer_view_components.silence_deprecations
+    end
+  end
+end

data/app/lib/primer/join_style_arguments_helper.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module Primer
+  # :nodoc:
+  module JoinStyleArgumentsHelper
+    # Join two `style` arguments
+    #
+    # join_style_arguments("width: 100%", "height: 100%") =>
+    #   "width: 100%;height: 100%"
+    def join_style_arguments(*args)
+      args.compact.join(";")
+    end
+  end
+end

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

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module Primer
+  module Octicon
+    # :nodoc:
+    class Cache
+      LOOKUP = {} # rubocop:disable Style/MutableConstant
+      # Preload the top 20 used icons.
+      PRELOADED_ICONS = [:alert, :check, :"chevron-down", :paste, :clock, :"dot-fill", :info, :"kebab-horizontal", :link, :lock, :mail, :pencil, :plus, :question, :repo, :search, :"shield-lock", :star, :trash, :x].freeze
+
+      class << self
+        def get_key(symbol:, size:, width: nil, height: nil)
+          attrs = { symbol: symbol, size: size, width: width, height: height }
+          attrs.compact!
+          attrs.hash
+        end
+
+        def read(key)
+          LOOKUP[key]
+        end
+
+        # Cache size limit.
+        def limit
+          500
+        end
+
+        def set(key, value)
+          LOOKUP[key] = value
+
+          # Remove first item when the cache is too large.
+          LOOKUP.shift if LOOKUP.size > limit
+        end
+
+        def clear!
+          LOOKUP.clear
+        end
+
+        def preload!
+          PRELOADED_ICONS.each { |icon| Primer::Beta::Octicon.new(icon: icon) }
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,44 @@
+# 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,
+        experimental: :experimental
+      }.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/tab_nav_helper.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+require "active_support/concern"
+
+module Primer
+  # Helper to share tab validation logic between components.
+  # The component will raise an error if there are 0 or 2+ selected tabs.
+  module TabNavHelper
+    extend ActiveSupport::Concern
+
+    EXTRA_ALIGN_DEFAULT = :left
+    EXTRA_ALIGN_OPTIONS = [EXTRA_ALIGN_DEFAULT, :right].freeze
+
+    def tab_nav_tab_classes(classes)
+      class_names(
+        "tabnav-tab",
+        classes
+      )
+    end
+
+    def tab_nav_classes(classes)
+      class_names(
+        "tabnav",
+        classes
+      )
+    end
+
+    def tab_nav_body_classes(classes)
+      class_names(
+        "tabnav-tabs",
+        classes
+      )
+    end
+  end
+end

data/app/lib/primer/tabbed_component_helper.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+require "active_support/concern"
+
+module Primer
+  # Helper to share tab validation logic between components.
+  # The component will raise an error if there are 0 or 2+ selected tabs.
+  module TabbedComponentHelper
+    extend ActiveSupport::Concern
+
+    class MultipleSelectedTabsError < StandardError; end
+
+    def before_render
+      validate_single_selected_tab unless Rails.env.production?
+    end
+
+    private
+
+    def aria_label_for_page_nav(label)
+      @system_arguments[:tag] == :nav ? @system_arguments[:"aria-label"] = label : @body_arguments[:"aria-label"] = label
+    end
+
+    def tab_container_wrapper(with_panel:, **system_arguments)
+      return yield unless with_panel
+
+      render Primer::Alpha::TabContainer.new(**system_arguments) do
+        yield if block_given?
+      end
+    end
+
+    def validate_single_selected_tab
+      raise MultipleSelectedTabsError, "only one tab can be selected" if selected_tabs_count > 1
+    end
+
+    def selected_tabs_count
+      @selected_tabs_count ||= tabs.count(&:selected)
+    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_selector: "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

data/app/lib/primer/underline_nav_helper.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+require "active_support/concern"
+
+module Primer
+  # Helper to share tab validation logic between components.
+  # The component will raise an error if there are 0 or 2+ selected tabs.
+  module UnderlineNavHelper
+    extend ActiveSupport::Concern
+
+    ALIGN_DEFAULT = :left
+    ALIGN_OPTIONS = [ALIGN_DEFAULT, :right].freeze
+
+    ACTIONS_TAG_DEFAULT = :div
+    ACTIONS_TAG_OPTIONS = [ACTIONS_TAG_DEFAULT, :span].freeze
+
+    def underline_nav_classes(classes, align)
+      class_names(
+        classes,
+        "UnderlineNav",
+        "UnderlineNav--right" => align == :right
+      )
+    end
+
+    def underline_nav_body_classes(classes)
+      class_names(
+        "UnderlineNav-body",
+        classes,
+        "list-style-none"
+      )
+    end
+
+    def underline_nav_action_classes(classes)
+      class_names("UnderlineNav-actions", classes)
+    end
+
+    def underline_nav_tab_classes(classes)
+      class_names(
+        "UnderlineNav-item",
+        classes
+      )
+    end
+  end
+end

data/app/lib/primer/view_helper.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+# :nocov:
+module Primer
+  # Module to allow shorthand calls for Primer components
+  module ViewHelper
+    class ViewHelperNotFound < StandardError; end
+
+    HELPERS = {
+      octicon: "Primer::Beta::Octicon",
+      heading: "Primer::Beta::Heading",
+      image: "Primer::Alpha::Image"
+    }.freeze
+
+    HELPERS.each do |name, component|
+      define_method "primer_#{name}" do |*args, **kwargs, &block|
+        render component.constantize.new(*args, **kwargs), &block
+      end
+    end
+  end
+end

data/lib/postcss_mixins/activeIndicatorLine.pcss

@@ -0,0 +1,11 @@
+/* active indicator line for navlist items */
+@define-mixin activeIndicatorLine $padding-left: calc(-1 * var(--base-size-8)) {
+  position: absolute;
+  top: calc(50% - 12px);
+  left: $padding-left;
+  width: var(--base-size-4);
+  height: var(--base-size-24);
+  content: '';
+  background: var(--borderColor-accent-emphasis);
+  border-radius: var(--borderRadius-medium);
+}

data/lib/postcss_mixins/clearfix.pcss

@@ -0,0 +1,12 @@
+@define-mixin clearfix {
+  &::before {
+    display: table;
+    content: '';
+  }
+
+  &::after {
+    display: table;
+    clear: both;
+    content: '';
+  }
+}

data/lib/postcss_mixins/focusBoxShadowInset.pcss

@@ -0,0 +1,6 @@
+/* inset box-shadow for form controls */
+@define-mixin focusBoxShadowInset $outlineWidth: 1px, $outlineColor: var(--focus-outlineColor) {
+  border-color: var(--focus-outlineColor);
+  outline: none;
+  box-shadow: inset 0 0 0 $outlineWidth $outlineColor;
+}

data/lib/postcss_mixins/focusOutline.pcss

@@ -0,0 +1,5 @@
+@define-mixin focusOutline $outlineOffset: -2px, $outlineColor: var(--focus-outlineColor) {
+  outline: 2px solid $outlineColor;
+  outline-offset: $outlineOffset;
+  box-shadow: none;
+}

data/lib/postcss_mixins/focusOutlineOnEmphasis.pcss

@@ -0,0 +1,6 @@
+/* outline with fg box-shadow for buttons */
+@define-mixin focusOutlineOnEmphasis $outlineOffset: -2px, $outlineColor: var(--focus-outlineColor) {
+  outline: 2px solid $outlineColor;
+  outline-offset: $outlineOffset;
+  box-shadow: inset 0 0 0 3px var(--fgColor-onEmphasis);
+}

data/lib/postcss_mixins/minTouchTarget.js

@@ -0,0 +1,20 @@
+module.exports = function (mixin, minHeight = '32px', minWidth = null) {
+  let declarations = {
+    position: 'absolute',
+    top: '50%',
+    left: '50%',
+    width: '100%',
+    height: '100%',
+    'min-height': minHeight,
+    content: '""',
+    transform: 'translateX(-50%) translateY(-50%)'
+  }
+
+  if (minWidth) {
+    declarations['min-width'] = minWidth
+  }
+
+  return {
+    '&': declarations
+  }
+}

data/lib/postcss_mixins/targetBoxShadow.pcss

@@ -0,0 +1,6 @@
+/* box-shadow for :target styles (no inset), !important to override PCSS utilities */
+
+@define-mixin targetBoxShadow $outlineWidth: 2px, $outlineColor: var(--focus-outlineColor) {
+  outline: none !important;
+  box-shadow: 0 0 0 $outlineWidth $outlineColor !important;
+}

data/lib/primer/accessibility.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+# :nocov:
+module Primer
+  # :nodoc:
+  module Accessibility
+    # Skip axe checks for components that should be tested as part of a larger component.
+    # Do not add to this list for any other reason!
+    IGNORED_PREVIEWS = [
+      Primer::Beta::MarkdownPreview,
+      Primer::Beta::AutoCompleteItemPreview
+    ].freeze
+
+    # Skip `:region` which relates to preview page structure rather than individual component.
+    # Skip `:color-contrast` which requires primer design-level change.
+    AXE_RULES_TO_SKIP = {
+      # these will be skipped in CI but will still be tracked in Datadog
+      will_fix: {
+        global: %i[
+          color-contrast
+        ],
+
+        per_component: {}
+      },
+
+      # these will always be skipped
+      wont_fix: {
+        global: %i[
+          region
+        ],
+
+        per_component: {
+          Primer::Alpha::ToggleSwitch => {
+            all_scenarios: %i[button-name]
+          }
+        }
+      }
+    }.freeze
+
+    class << self
+      def ignore_preview?(preview_class)
+        preview_class.name.start_with?("Docs::") || IGNORED_PREVIEWS.include?(preview_class)
+      end
+
+      def axe_rules_to_skip(component: nil, scenario_name: nil, flatten: false)
+        to_skip = {
+          wont_fix: Set.new(AXE_RULES_TO_SKIP.dig(:wont_fix, :global) || []),
+          will_fix: Set.new(AXE_RULES_TO_SKIP.dig(:will_fix, :global) || [])
+        }
+
+        if component
+          to_skip[:wont_fix].merge(AXE_RULES_TO_SKIP.dig(:wont_fix, :per_component, component, :all_scenarios) || [])
+          to_skip[:will_fix].merge(AXE_RULES_TO_SKIP.dig(:will_fix, :per_component, component, :all_scenarios) || [])
+
+          if scenario_name
+            to_skip[:wont_fix].merge(AXE_RULES_TO_SKIP.dig(:wont_fix, :per_component, component, scenario_name) || [])
+            to_skip[:will_fix].merge(AXE_RULES_TO_SKIP.dig(:will_fix, :per_component, component, scenario_name) || [])
+          end
+        end
+
+        if flatten
+          flattened = to_skip.each_with_object(Set.new) do |(_, rule_set), memo|
+            memo.merge(rule_set)
+          end
+
+          return flattened.to_a
+        end
+
+        to_skip.transform_values(&:to_a)
+      end
+    end
+  end
+end
+# :nocov:

data/lib/primer/classify/utilities.rb

@@ -0,0 +1,201 @@
+# frozen_string_literal: true
+
+require "yaml"
+
+# :nodoc:
+module Primer
+  class Classify
+    # Handler for PrimerCSS utility classes loaded from utilities.rake
+    class Utilities
+      UTILITIES = YAML.safe_load(
+        File.read(
+          File.join(File.dirname(__FILE__), "utilities.yml")
+        ),
+        permitted_classes: [Symbol]
+      ).freeze
+
+      BREAKPOINTS = ["", "-sm", "-md", "-lg", "-xl"].freeze
+
+      # Replacements for some classnames that end up being a different argument key
+      REPLACEMENT_KEYS = {
+        "^anim" => "animation",
+        "^v-align" => "vertical_align",
+        "^d" => "display",
+        "^wb" => "word_break",
+        "^v" => "visibility",
+        "^width" => "w",
+        "^height" => "h",
+        "^color-bg" => "bg",
+        "^color-border" => "border_color",
+        "^color-fg" => "color"
+      }.freeze
+
+      SUPPORTED_KEY_CACHE = Hash.new { |h, k| h[k] = !UTILITIES[k].nil? }
+      BREAKPOINT_INDEX_CACHE = Hash.new { |h, k| h[k] = BREAKPOINTS.index(k) }
+
+      class << self
+        attr_accessor :validate_class_names
+        alias validate_class_names? validate_class_names
+
+        def classname(key, val, breakpoint = "")
+          # For cases when `argument: false` is passed in, treat like we would nil
+          return nil unless val
+
+          if (valid = validate(key, val, breakpoint))
+            valid
+          else
+            # Get selector
+            UTILITIES[key][val][BREAKPOINT_INDEX_CACHE[breakpoint]]
+          end
+        end
+
+        # Does the Utility class support the given key
+        #
+        # returns Boolean
+        def supported_key?(key)
+          SUPPORTED_KEY_CACHE[key]
+        end
+
+        # Does the Utility class support the given key and value
+        #
+        # returns Boolean
+        def supported_value?(key, val)
+          supported_key?(key) && !UTILITIES[key][val].nil?
+        end
+
+        # Does the given selector exist in the utilities file
+        #
+        # returns Boolean
+        def supported_selector?(selector)
+          # This method is too slow to run in production
+          return false unless validate_class_names?
+
+          find_selector(selector).present?
+        end
+
+        # Is the key and value responsive
+        #
+        # returns Boolean
+        def responsive?(key, val)
+          supported_value?(key, val) && UTILITIES[key][val].count > 1
+        end
+
+        # Get the options for the given key
+        #
+        # returns Array or nil if key not supported
+        def mappings(key)
+          return unless supported_key?(key)
+
+          UTILITIES[key].keys
+        end
+
+        # Extract hash from classes ie. "mr-1 mb-2 foo" => { mr: 1, mb: 2, classes: "foo" }
+        def classes_to_hash(classes)
+          # This method is too slow to run in production
+          return { classes: classes } unless validate_class_names?
+
+          obj = {}
+          classes = classes.split
+          # Loop through all classes supplied and reject ones we find a match for
+          # So when we're at the end of the loop we have classes left with any non-system classes.
+          classes.reject! do |classname|
+            key, value, index = find_selector(classname)
+            next false if key.nil?
+
+            # Create array if nil
+            obj[key] = Array.new(5, nil) if obj[key].nil?
+            # Place the arguments in the responsive array based on index mr: [nil, 2]
+            obj[key][index] = value
+            next true
+          end
+
+          # Transform responsive arrays into arrays without trailing nil, so `mr: [1, nil, nil, nil, nil]` becomes `mr: 1`
+          obj.transform_values! do |value|
+            value = value.reverse.drop_while(&:nil?).reverse
+            if value.count == 1
+              value.first
+            else
+              value
+            end
+          end
+
+          # Add back the non-system classes
+          obj[:classes] = classes.join(" ") if classes.any?
+          obj
+        end
+
+        def classes_to_args(classes)
+          hash_to_args(classes_to_hash(classes))
+        end
+
+        def hash_to_args(hash)
+          hash.map do |key, value|
+            val = case value
+                  when Symbol
+                    ":#{value}"
+                  when String
+                    value.to_json
+                  else
+                    value
+                  end
+
+            "#{key}: #{val}"
+          end.join(", ")
+        end
+
+        def validate(key, val, breakpoint)
+          unless supported_key?(key)
+            raise ArgumentError, "#{key} is not a valid Primer utility key" if validate_class_names?
+
+            return ""
+          end
+
+          unless breakpoint.empty? || responsive?(key, val)
+            raise ArgumentError, "#{key} does not support responsive values" if validate_class_names?
+
+            return ""
+          end
+
+          unless supported_value?(key, val)
+            raise ArgumentError, "#{val} is not a valid value for :#{key}. Use one of #{mappings(key)}" if validate_class_names?
+
+            return nil if [true, false].include?(val)
+
+            return "#{key.to_s.dasherize}-#{val.to_s.dasherize}"
+          end
+
+          nil
+        end
+
+        private
+
+        def find_selector(selector)
+          key = infer_selector_key(selector)
+          value_hash = UTILITIES[key]
+
+          return nil if value_hash.blank?
+
+          # Each value hash will also contain an array of classnames for breakpoints
+          # Key argument `0`, classes `[ "mr-0", "mr-sm-0", "mr-md-0", "mr-lg-0", "mr-xl-0" ]`
+          value_hash.each do |key_argument, classnames|
+            # Skip each value hash until we get one with the selector
+            next unless classnames.include?(selector)
+
+            # Return [:mr, 0, 1]
+            # has index of classname, so we can match it up with responsive array `mr: [nil, 0]`
+            return [key, key_argument, classnames.index(selector)]
+          end
+
+          nil
+        end
+
+        def infer_selector_key(selector)
+          REPLACEMENT_KEYS.each do |k, v|
+            return v.to_sym if selector.match?(Regexp.new(k))
+          end
+          selector.split("-").first.to_sym
+        end
+      end
+    end
+  end
+end