primer_view_components 0.0.36 → 0.0.41

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

@@ -40,18 +40,18 @@ module Primer
           )
 
           preload(
-            keys: Primer::Classify::DIRECTION_KEY,
-            values: [:row, :column]
+            keys: Primer::Classify::Flex::DIRECTION_KEY,
+            values: Primer::Classify::Flex::DIRECTION_VALUES
           )
 
           preload(
-            keys: Primer::Classify::JUSTIFY_CONTENT_KEY,
-            values: [:flex_start, :flex_end, :center, :space_between, :space_around]
+            keys: Primer::Classify::Flex::JUSTIFY_CONTENT_KEY,
+            values: Primer::Classify::Flex::JUSTIFY_CONTENT_VALUES
           )
 
           preload(
-            keys: Primer::Classify::ALIGN_ITEMS_KEY,
-            values: [:flex_start, :flex_end, :center, :baseline, :stretch]
+            keys: Primer::Classify::Flex::ALIGN_ITEMS_KEY,
+            values: Primer::Classify::Flex::ALIGN_ITEMS_VALUES
           )
 
           preload(
@@ -61,12 +61,12 @@ module Primer
 
           preload(
             keys: [Primer::Classify::COLOR_KEY],
-            values: [*Primer::Classify::FunctionalTextColors::OPTIONS, *Primer::Classify::FunctionalTextColors::DEPRECATED_OPTIONS]
+            values: Primer::Classify::FunctionalTextColors::OPTIONS
           )
 
           preload(
             keys: [Primer::Classify::BG_KEY],
-            values: [*Primer::Classify::FunctionalBackgroundColors::OPTIONS, *Primer::Classify::FunctionalBackgroundColors::DEPRECATED_OPTIONS]
+            values: Primer::Classify::FunctionalBackgroundColors::OPTIONS
           )
 
           preload(
@@ -90,23 +90,28 @@ module Primer
           )
 
           preload(
-            keys: Primer::Classify::FLEX_KEY,
-            values: [1, :auto]
+            keys: Primer::Classify::Flex::FLEX_KEY,
+            values: Primer::Classify::Flex::FLEX_VALUES
           )
 
           preload(
-            keys: [Primer::Classify::FLEX_GROW_KEY, Primer::Classify::FLEX_SHRINK_KEY],
-            values: [0]
+            keys: Primer::Classify::Flex::GROW_KEY,
+            values: Primer::Classify::Flex::GROW_VALUES
           )
 
           preload(
-            keys: [Primer::Classify::ALIGN_SELF_KEY],
-            values: [:auto, :start, :end, :center, :baseline, :stretch]
+            keys: Primer::Classify::Flex::SHRINK_KEY,
+            values: Primer::Classify::Flex::SHRINK_VALUES
+          )
+
+          preload(
+            keys: Primer::Classify::Flex::ALIGN_SELF_KEY,
+            values: Primer::Classify::Flex::ALIGN_SELF_VALUES
           )
 
           preload(
             keys: [Primer::Classify::WIDTH_KEY, Primer::Classify::HEIGHT_KEY],
-            values: [:fit, :fill]
+            values: [:fit]
           )
 
           preload(

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

@@ -0,0 +1,111 @@
+# frozen_string_literal: true
+
+module Primer
+  class Classify
+    # Handler for PrimerCSS flex classes.
+    class Flex
+      extend Primer::FetchOrFallbackHelper
+
+      FLEX_KEY = :flex
+      FLEX_VALUES = [1, :auto].freeze
+
+      WRAP_KEY = :flex_wrap
+      WRAP_MAPPINGS = {
+        wrap: "flex-wrap",
+        nowrap: "flex-nowrap",
+        reverse: "flex-wrap-reverse"
+      }.freeze
+
+      SHRINK_KEY = :flex_shrink
+      SHRINK_VALUES = [0].freeze
+
+      GROW_KEY = :flex_grow
+      GROW_VALUES = [0].freeze
+
+      ALIGN_SELF_KEY = :align_self
+      ALIGN_SELF_VALUES = [:auto, :start, :end, :center, :baseline, :stretch].freeze
+
+      DIRECTION_KEY = :direction
+      DIRECTION_VALUES = [:column, :column_reverse, :row, :row_reverse].freeze
+
+      JUSTIFY_CONTENT_KEY = :justify_content
+      JUSTIFY_CONTENT_VALUES = [:flex_start, :flex_end, :center, :space_between, :space_around].freeze
+
+      ALIGN_ITEMS_KEY = :align_items
+      ALIGN_ITEMS_VALUES = [:flex_start, :flex_end, :center, :baseline, :stretch].freeze
+
+      KEYS = [FLEX_KEY, WRAP_KEY, SHRINK_KEY, GROW_KEY, ALIGN_SELF_KEY, DIRECTION_KEY, JUSTIFY_CONTENT_KEY, ALIGN_ITEMS_KEY].freeze
+      RESPONSIVE_KEYS = [DIRECTION_KEY, JUSTIFY_CONTENT_KEY, ALIGN_ITEMS_KEY].freeze
+
+      class << self
+        def classes(key, value, breakpoint)
+          send(key, value, breakpoint)
+        end
+
+        private
+
+        def flex(value, _breakpoint)
+          generate(
+            value: value,
+            allowed_values: FLEX_VALUES,
+            prefix: "flex"
+          )
+        end
+
+        def flex_shrink(value, _breakpoint)
+          generate(
+            value: value,
+            allowed_values: SHRINK_VALUES,
+            prefix: "flex-shrink"
+          )
+        end
+
+        def flex_grow(value, _breakpoint)
+          generate(
+            value: value,
+            allowed_values: GROW_VALUES,
+            prefix: "flex-grow"
+          )
+        end
+
+        def align_self(value, _breakpoint)
+          generate(
+            value: value,
+            allowed_values: ALIGN_SELF_VALUES,
+            prefix: "flex-self"
+          )
+        end
+
+        def flex_wrap(value, _breakpoint)
+          WRAP_MAPPINGS[fetch_or_fallback(WRAP_MAPPINGS.keys, value)]
+        end
+
+        def direction(value, breakpoint)
+          val = fetch_or_fallback(DIRECTION_VALUES, value)
+
+          "flex#{breakpoint}-#{val.to_s.dasherize}"
+        end
+
+        def justify_content(value, breakpoint)
+          val = fetch_or_fallback(JUSTIFY_CONTENT_VALUES, value)
+
+          formatted_value = val.to_s.gsub(/(flex\_|space\_)/, "")
+          "flex#{breakpoint}-justify-#{formatted_value}"
+        end
+
+        def align_items(value, breakpoint)
+          val = fetch_or_fallback(ALIGN_ITEMS_VALUES, value)
+
+          formatted_value = val.to_s.gsub("flex_", "")
+          "flex#{breakpoint}-items-#{formatted_value}"
+        end
+
+        def generate(value:, allowed_values:, prefix:)
+          val = fetch_or_fallback(allowed_values, value)
+
+          "#{prefix}-#{val}"
+        end
+      end
+    end
+  end
+end

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

@@ -13,8 +13,7 @@ module Primer
         success: :success,
         warning: :warning,
         danger: :danger,
-        inverse: :inverse,
-        overlay: :overlay
+        inverse: :inverse
       }.freeze
 
       MAPPINGS = {

data/app/lib/primer/fetch_or_fallback_helper.rb

@@ -25,10 +25,10 @@ module Primer
 
     InvalidValueError = Class.new(StandardError)
 
-    def fetch_or_fallback(allowed_values, given_value, fallback = nil, deprecated_values: [])
+    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)
+      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

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

@@ -0,0 +1,42 @@
+# 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", :clippy, :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)
+          [symbol, size, width, height].join("_")
+        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::OcticonComponent.new(icon: icon) }
+        end
+      end
+    end
+  end
+end

data/app/lib/primer/view_helper.rb

@@ -8,7 +8,8 @@ module Primer
     HELPERS = {
       octicon: "Primer::OcticonComponent",
       heading: "Primer::HeadingComponent",
-      time_ago: "Primer::TimeAgoComponent"
+      time_ago: "Primer::TimeAgoComponent",
+      image: "Primer::Image"
     }.freeze
 
     HELPERS.each do |name, component|

data/lib/primer/view_components.rb

@@ -27,7 +27,7 @@ module Primer
       statuses = generate_statuses
 
       File.open(File.join(path, DEFAULT_STATUS_FILE_NAME), "w") do |f|
-        f.write(statuses.to_json)
+        f.write(JSON.pretty_generate(statuses))
         f.write($INPUT_RECORD_SEPARATOR)
       end
     end

data/lib/primer/view_components/version.rb

@@ -5,7 +5,7 @@ module Primer
     module VERSION
       MAJOR = 0
       MINOR = 0
-      PATCH = 36
+      PATCH = 41
 
       STRING = [MAJOR, MINOR, PATCH].join(".")
     end

data/lib/tasks/coverage.rake

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+namespace :coverage do
+  task :report do
+    require "simplecov"
+    require "simplecov-console"
+
+    SimpleCov.minimum_coverage 100
+
+    SimpleCov.collate Dir["simplecov-resultset-*/.resultset.json"], "rails" do
+      formatter SimpleCov::Formatter::Console
+    end
+  end
+end

data/lib/tasks/docs.rake

@@ -0,0 +1,315 @@
+# frozen_string_literal: true
+
+namespace :docs do
+  task :livereload do
+    require "listen"
+
+    Rake::Task["docs:build"].execute
+
+    puts "Listening for changes to documentation..."
+
+    listener = Listen.to("app") do |modified, added, removed|
+      puts "modified absolute path: #{modified}"
+      puts "added absolute path: #{added}"
+      puts "removed absolute path: #{removed}"
+
+      Rake::Task["docs:build"].execute
+    end
+    listener.start # not blocking
+    sleep
+  end
+
+  task :build do
+    require File.expand_path("./../../demo/config/environment.rb", __dir__)
+    require "primer/view_components"
+    require "yard/docs_helper"
+    require "view_component/test_helpers"
+    include ViewComponent::TestHelpers
+    include Primer::ViewHelper
+    include YARD::DocsHelper
+
+    Dir["./app/components/primer/**/*.rb"].sort.each { |file| require file }
+
+    YARD::Rake::YardocTask.new
+
+    # Custom tags for yard
+    YARD::Tags::Library.define_tag("Accessibility", :accessibility)
+    YARD::Tags::Library.define_tag("Deprecation", :deprecation)
+
+    puts "Building YARD documentation."
+    Rake::Task["yard"].execute
+
+    puts "Converting YARD documentation to Markdown files."
+
+    # Rails controller for rendering arbitrary ERB
+    view_context = ApplicationController.new.tap { |c| c.request = ActionDispatch::TestRequest.create }.view_context
+
+    registry = YARD::RegistryStore.new
+    registry.load!(".yardoc")
+    components = [
+      Primer::Image,
+      Primer::LocalTime,
+      Primer::OcticonSymbolsComponent,
+      Primer::ImageCrop,
+      Primer::IconButton,
+      Primer::AutoComplete,
+      Primer::AutoComplete::Item,
+      Primer::AvatarComponent,
+      Primer::AvatarStackComponent,
+      Primer::BaseButton,
+      Primer::BlankslateComponent,
+      Primer::BorderBoxComponent,
+      Primer::BoxComponent,
+      Primer::BreadcrumbComponent,
+      Primer::ButtonComponent,
+      Primer::ButtonGroup,
+      Primer::ButtonMarketingComponent,
+      Primer::ClipboardCopy,
+      Primer::CloseButton,
+      Primer::CounterComponent,
+      Primer::DetailsComponent,
+      Primer::DropdownComponent,
+      Primer::DropdownMenuComponent,
+      Primer::FlashComponent,
+      Primer::FlexComponent,
+      Primer::FlexItemComponent,
+      Primer::HeadingComponent,
+      Primer::HiddenTextExpander,
+      Primer::LabelComponent,
+      Primer::LayoutComponent,
+      Primer::LinkComponent,
+      Primer::Markdown,
+      Primer::MenuComponent,
+      Primer::Navigation::TabComponent,
+      Primer::OcticonComponent,
+      Primer::PopoverComponent,
+      Primer::ProgressBarComponent,
+      Primer::StateComponent,
+      Primer::SpinnerComponent,
+      Primer::SubheadComponent,
+      Primer::TabContainerComponent,
+      Primer::TabNavComponent,
+      Primer::TextComponent,
+      Primer::TimeAgoComponent,
+      Primer::TimelineItemComponent,
+      Primer::Tooltip,
+      Primer::Truncate,
+      Primer::UnderlineNavComponent
+    ]
+
+    js_components = [
+      Primer::LocalTime,
+      Primer::ImageCrop,
+      Primer::AutoComplete,
+      Primer::ClipboardCopy,
+      Primer::TabContainerComponent,
+      Primer::TabNavComponent,
+      Primer::TimeAgoComponent,
+      Primer::UnderlineNavComponent
+    ]
+
+    all_components = Primer::Component.descendants - [Primer::BaseComponent]
+    components_needing_docs = all_components - components
+
+    components_without_examples = []
+    args_for_components = []
+    classes_found_in_examples = []
+
+    components.each do |component|
+      documentation = registry.get(component.name)
+
+      # Primer::AvatarComponent => Avatar
+      short_name = component.name.gsub(/Primer|::|Component/, "")
+
+      path = Pathname.new("docs/content/components/#{short_name.downcase}.md")
+      path.dirname.mkdir unless path.dirname.exist?
+      File.open(path, "w") do |f|
+        f.puts("---")
+        f.puts("title: #{short_name}")
+        f.puts("status: #{component.status.to_s.capitalize}")
+        f.puts("source: https://github.com/primer/view_components/tree/main/app/components/primer/#{component.to_s.demodulize.underscore}.rb")
+        f.puts("storybook: https://primer.style/view-components/stories/?path=/story/primer-#{short_name.underscore.dasherize}-component")
+        f.puts("---")
+        f.puts
+        f.puts("import Example from '../../src/@primer/gatsby-theme-doctocat/components/example'")
+
+        if js_components.include?(component)
+          f.puts("import RequiresJSFlash from '../../src/@primer/gatsby-theme-doctocat/components/requires-js-flash'")
+          f.puts
+          f.puts("<RequiresJSFlash />")
+        end
+
+        f.puts
+        f.puts("<!-- Warning: AUTO-GENERATED file, do not edit. Add code comments to your Ruby instead <3 -->")
+        f.puts
+        f.puts(view_context.render(inline: documentation.base_docstring))
+
+        if documentation.tags(:accessibility).any?
+          f.puts
+          f.puts("## Accessibility")
+          documentation.tags(:accessibility).each do |tag|
+            f.puts
+            f.puts view_context.render(inline: tag.text)
+          end
+        end
+
+        if documentation.tags(:deprecated).any?
+          f.puts
+          f.puts("## Deprecation")
+          documentation.tags(:deprecated).each do |tag|
+            f.puts
+            f.puts view_context.render(inline: tag.text)
+          end
+        end
+
+        initialize_method = documentation.meths.find(&:constructor?)
+
+        if initialize_method.tags(:example).any?
+          f.puts
+          f.puts("## Examples")
+        else
+          components_without_examples << component
+        end
+
+        initialize_method.tags(:example).each do |tag|
+          (name, description) = tag.name.split("|")
+          f.puts
+          f.puts("### #{name}")
+          if description
+            f.puts
+            f.puts(description)
+          end
+          f.puts
+          html = view_context.render(inline: tag.text)
+          html.scan(/class="([^"]*)"/) do |classnames|
+            classes_found_in_examples.concat(classnames[0].split(" ").reject { |c| c.starts_with?("octicon", "js", "my-") }.map { ".#{_1}"})
+          end
+          f.puts("<Example src=\"#{html.tr('"', "\'").delete("\n")}\" />")
+          f.puts
+          f.puts("```erb")
+          f.puts(tag.text.to_s)
+          f.puts("```")
+        end
+
+        params = initialize_method.tags(:param)
+        if params.any?
+          f.puts
+          f.puts("## Arguments")
+          f.puts
+          f.puts("| Name | Type | Default | Description |")
+          f.puts("| :- | :- | :- | :- |")
+
+          args = []
+          params.each do |tag|
+            params = tag.object.parameters.find { |param| [tag.name.to_s, tag.name.to_s + ":"].include?(param[0]) }
+
+            default =
+              if params && params[1]
+                constant_name = "#{component.name}::#{params[1]}"
+                constant_value = constant_name.safe_constantize
+                if constant_value.nil?
+                  pretty_value(params[1])
+                else
+                  pretty_value(constant_value)
+                end
+              else
+                "N/A"
+              end
+
+            args << {
+              "name" => tag.name,
+              "type" => tag.types.join(", "),
+              "default" => default,
+              "description" => view_context.render(inline: tag.text)
+            }
+
+            f.puts("| `#{tag.name}` | `#{tag.types.join(', ')}` | #{default} | #{view_context.render(inline: tag.text)} |")
+          end
+
+          component_args = {
+            "component" => short_name,
+            "source" => "https://github.com/primer/view_components/tree/main/app/components/primer/#{component.to_s.demodulize.underscore}.rb",
+            "parameters" => args
+          }
+
+          args_for_components << component_args
+        end
+
+        # Slots V2 docs
+        slot_v2_methods = documentation.meths.select { |x| x[:renders_one] || x[:renders_many] }
+
+        if slot_v2_methods.any?
+          f.puts
+          f.puts("## Slots")
+
+          slot_v2_methods.each do |slot_documentation|
+            f.puts
+            f.puts("### `#{slot_documentation.name.to_s.capitalize}`")
+
+            if slot_documentation.base_docstring.present?
+              f.puts
+              f.puts(view_context.render(inline: slot_documentation.base_docstring))
+            end
+
+            param_tags = slot_documentation.tags(:param)
+            if param_tags.any?
+              f.puts
+              f.puts("| Name | Type | Default | Description |")
+              f.puts("| :- | :- | :- | :- |")
+            end
+
+            param_tags.each do |tag|
+              params = tag.object.parameters.find { |param| [tag.name.to_s, tag.name.to_s + ":"].include?(param[0]) }
+
+              default =
+                if params && params[1]
+                  "`#{params[1]}`"
+                else
+                  "N/A"
+                end
+
+              f.puts("| `#{tag.name}` | `#{tag.types.join(', ')}` | #{default} | #{view_context.render(inline: tag.text)} |")
+            end
+          end
+        end
+      end
+    end
+
+    File.open("static/classes.yml", "w") do |f|
+      f.puts YAML.dump(classes_found_in_examples.sort.uniq)
+    end
+
+    File.open("static/arguments.yml", "w") do |f|
+      f.puts YAML.dump(args_for_components)
+    end
+
+    # Build system arguments docs from BaseComponent
+    documentation = registry.get(Primer::BaseComponent.name)
+    File.open("docs/content/system-arguments.md", "w") do |f|
+      f.puts("---")
+      f.puts("title: System arguments")
+      f.puts("---")
+      f.puts
+      f.puts("<!-- Warning: AUTO-GENERATED file, do not edit. Add code comments to your Ruby instead <3 -->")
+      f.puts
+      f.puts(documentation.base_docstring)
+      f.puts
+
+      initialize_method = documentation.meths.find(&:constructor?)
+
+      f.puts(view_context.render(inline: initialize_method.base_docstring))
+    end
+
+    puts "Markdown compiled."
+
+    if components_without_examples.any?
+      puts
+      puts "The following components have no examples defined: #{components_without_examples.map(&:name).join(', ')}. Consider adding an example?"
+    end
+
+    if components_needing_docs.any?
+      puts
+      puts "The following components needs docs. Care to contribute them? #{components_needing_docs.map(&:name).join(', ')}"
+    end
+  end
+end