primer_view_components 0.0.39 → 0.0.40

data/app/components/primer/octicon_component.html.erb

@@ -0,0 +1,7 @@
+<%= render(Primer::BaseComponent.new(**@system_arguments)) do %>
+  <% if @use_symbol %>
+    <use href="#octicon_<%= [@icon.symbol, @icon.height].join("_") %>"></use>
+  <% else %>
+    <%= @icon.path.html_safe %>
+  <% end %>
+<% end %>

data/app/components/primer/octicon_component.rb

@@ -4,14 +4,18 @@ require "octicons"
 
 module Primer
   # `Octicon` renders an <%= link_to_octicons %> with <%= link_to_system_arguments_docs %>.
+  # `Octicon` can also be rendered with the `primer_octicon` helper, which accepts the same arguments.
   class OcticonComponent < Primer::Component
     status :beta
 
     SIZE_DEFAULT = :small
+    SIZE_MEDIUM = :medium
+    SIZE_LARGE = :large
+
     SIZE_MAPPINGS = {
       SIZE_DEFAULT => 16,
-      :medium => 32,
-      :large => 64
+      SIZE_MEDIUM => 32,
+      SIZE_LARGE => 64
     }.freeze
     SIZE_OPTIONS = SIZE_MAPPINGS.keys
 
@@ -25,16 +29,21 @@ module Primer
     # @example Large
     #   <%= render(Primer::OcticonComponent.new("x", size: :large)) %>
     #
+    # @example Helper
+    #   <%= primer_octicon("check") %>
+    #
     # @param icon [String] Name of <%= link_to_octicons %> to use.
     # @param size [Symbol] <%= one_of(Primer::OcticonComponent::SIZE_MAPPINGS) %>
+    # @param use_symbol [Boolean] EXPERIMENTAL (May change or be removed) - Set to true when using with <%= link_to_component(Primer::OcticonSymbolsComponent) %>.
     # @param system_arguments [Hash] <%= link_to_system_arguments_docs %>
-    def initialize(icon_name = nil, icon: nil, size: SIZE_DEFAULT, **system_arguments)
+    def initialize(icon_name = nil, icon: nil, size: SIZE_DEFAULT, use_symbol: false, **system_arguments)
       icon_key = icon_name || icon
-      cache_key = [icon_key, size, system_arguments.slice(:height, :width)].join("_")
+      cache_key = Primer::Octicon::Cache.get_key(symbol: icon_key, size: size, **system_arguments.slice(:height, :width))
 
       @system_arguments = system_arguments
       @system_arguments[:tag] = :svg
       @system_arguments[:aria] ||= {}
+      @use_symbol = use_symbol
 
       if @system_arguments[:aria][:label] || @system_arguments[:"aria-label"]
         @system_arguments[:role] = "img"
@@ -62,10 +71,8 @@ module Primer
       @system_arguments.merge!(@icon.options.except(:class, :'aria-hidden'))
     end
 
-    def call
-      render(Primer::BaseComponent.new(**@system_arguments)) { @icon.path.html_safe } # rubocop:disable Rails/OutputSafety
+    def self._after_compile
+      Primer::Octicon::Cache.preload!
     end
-
-    Primer::Octicon::Cache.preload!
   end
 end

data/app/components/primer/octicon_symbols_component.html.erb

@@ -0,0 +1,3 @@
+<svg xmlns="http://www.w3.org/2000/svg" hidden>
+  <%= symbol_tags %>
+</svg>

data/app/components/primer/octicon_symbols_component.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+require "octicons"
+
+module Primer
+  # OcticonSymbols renders a symbol dictionary using a list of <%= link_to_octicons %>.
+  class OcticonSymbolsComponent < Primer::Component
+    # @example Symbol dictionary
+    #   <%= render(Primer::OcticonComponent.new(icon: :check, use_symbol: true, color: :icon_success)) %>
+    #   <%= render(Primer::OcticonComponent.new(icon: :check, use_symbol: true, color: :text_danger)) %>
+    #   <%= render(Primer::OcticonComponent.new(icon: :check, use_symbol: true, size: :medium)) %>
+    #   <%= render(Primer::OcticonSymbolsComponent.new(icons: [{ symbol: :check }, { symbol: :check, size: :medium }])) %>
+    #
+    # @param icons [Array<Hash>] List of icons to render, in the format { symbol: :icon_name, size: :small }
+    def initialize(icons: [])
+      @icons = {}
+      icons.each do |icon|
+        symbol = icon[:symbol]
+        size = Primer::OcticonComponent::SIZE_MAPPINGS[
+          fetch_or_fallback(Primer::OcticonComponent::SIZE_OPTIONS, icon[:size] || Primer::OcticonComponent::SIZE_DEFAULT, Primer::OcticonComponent::SIZE_DEFAULT)
+        ]
+
+        cache_key = Primer::Octicon::Cache.get_key(symbol: symbol, size: size)
+
+        if (cache_icon = Primer::Octicon::Cache.read(cache_key))
+          icon_instance = cache_icon
+        else
+          icon_instance = Octicons::Octicon.new(symbol, height: size)
+
+          Primer::Octicon::Cache.set(cache_key, icon_instance)
+        end
+
+        # Don't put the same icon twice
+        @icons[[symbol, icon_instance.height]] = icon_instance if @icons[[symbol, icon_instance.height]].nil?
+      end
+    end
+
+    def render?
+      @icons.any?
+    end
+
+    def self._after_compile
+      Primer::Octicon::Cache.preload!
+    end
+
+    def symbol_tags
+      safe_join(
+        @icons.values.map do |icon|
+          content_tag(
+            :symbol,
+            icon.path.html_safe, # rubocop:disable Rails/OutputSafety
+            id: "octicon_#{icon.symbol}_#{icon.height}",
+            viewBox: icon.options[:viewBox],
+            width: icon.width,
+            height: icon.height
+          )
+        end
+      )
+    end
+  end
+end

data/app/components/primer/primer.d.ts

@@ -2,3 +2,4 @@ import './auto_complete/auto_complete';
 import './clipboard_copy_component';
 import './tab_container_component';
 import './time_ago_component';
+import './image_crop';

data/app/components/primer/primer.js

@@ -2,3 +2,4 @@ import './auto_complete/auto_complete';
 import './clipboard_copy_component';
 import './tab_container_component';
 import './time_ago_component';
+import './image_crop';

data/app/components/primer/primer.ts

@@ -2,3 +2,4 @@ import './auto_complete/auto_complete'
 import './clipboard_copy_component'
 import './tab_container_component'
 import './time_ago_component'
+import './image_crop'

data/app/components/primer/spinner_component.rb

@@ -27,10 +27,10 @@ module Primer
     #   <%= render(Primer::SpinnerComponent.new(size: :large)) %>
     #
     # @param size [Symbol] <%= one_of(Primer::SpinnerComponent::SIZE_MAPPINGS) %>
-    def initialize(size: DEFAULT_SIZE, **system_arguments)
+    def initialize(size: DEFAULT_SIZE, style: DEFAULT_STYLE, **system_arguments)
       @system_arguments = system_arguments
       @system_arguments[:tag] = :svg
-      @system_arguments[:style] ||= DEFAULT_STYLE
+      @system_arguments[:style] ||= style
       @system_arguments[:animation] = :rotate
       @system_arguments[:width] = SIZE_MAPPINGS[fetch_or_fallback(SIZE_OPTIONS, size, DEFAULT_SIZE)]
       @system_arguments[:height] = SIZE_MAPPINGS[fetch_or_fallback(SIZE_OPTIONS, size, DEFAULT_SIZE)]

data/app/components/primer/subhead_component.rb

@@ -1,16 +1,28 @@
 # frozen_string_literal: true
 
 module Primer
-  # Use `Subhead` for page headings.
+  # Use `Subhead` as the start of a section. The `:heading` slot will render an `<h2>` font-sized text.
+  #
+  # - Optionally set the `:description` slot to render a short description and the `:actions` slot for a related action.
+  # - Use a succint, one-line description for the `:description` slot. For longer descriptions, omit the description slot and render a paragraph below the `Subhead`.
+  # - Use the actions slot to render a related action to the right of the heading. Use <%= link_to_component(Primer::ButtonComponent) %> or <%= link_to_component(Primer::LinkComponent) %>.
+  #
+  # @accessibility
+  #   The `:heading` slot defaults to rendering a `<div>`. Update the tag to a heading element with the appropriate level to improve page navigation for assistive technologies.
+  #   <%= link_to_heading_practices %>
   class SubheadComponent < Primer::Component
     status :beta
 
+    DEFAULT_HEADING_TAG = :div
+    HEADING_TAG_OPTIONS = [DEFAULT_HEADING_TAG, :h1, :h2, :h3, :h4, :h5, :h6].freeze
+
     # The heading
     #
+    # @param tag [Symbol] <%= one_of(Primer::SubheadComponent::HEADING_TAG_OPTIONS)%>
     # @param danger [Boolean] Whether to style the heading as dangerous.
     # @param system_arguments [Hash] <%= link_to_system_arguments_docs %>
-    renders_one :heading, lambda { |danger: false, **system_arguments|
-      system_arguments[:tag] ||= :div
+    renders_one :heading, lambda { |tag: DEFAULT_HEADING_TAG, danger: false, **system_arguments|
+      system_arguments[:tag] = fetch_or_fallback(HEADING_TAG_OPTIONS, tag, DEFAULT_HEADING_TAG)
       system_arguments[:classes] = class_names(
         system_arguments[:classes],
         "Subhead-heading",
@@ -42,7 +54,7 @@ module Primer
 
     # @example Default
     #   <%= render(Primer::SubheadComponent.new) do |component| %>
-    #     <% component.heading do %>
+    #     <% component.heading(tag: :h3) do %>
     #       My Heading
     #     <% end %>
     #     <% component.description do %>
@@ -50,6 +62,24 @@ module Primer
     #     <% end %>
     #   <% end %>
     #
+    # @example With dangerous heading
+    #   <%= render(Primer::SubheadComponent.new) do |component| %>
+    #     <% component.heading(tag: :h3, danger: true) do %>
+    #       My Heading
+    #     <% end %>
+    #     <% component.description do %>
+    #       My Description
+    #     <% end %>
+    #   <% end %>
+    #
+    # @example With long description
+    #   <%= render(Primer::SubheadComponent.new) do |component| %>
+    #     <% component.heading(tag: :h3) do %>
+    #       My Heading
+    #     <% end %>
+    #   <% end %>
+    #   <p> This is a longer description that is sitting below the Subhead. It's much longer than a description that could sit comfortably in the Subhead. </p>
+    #
     # @example Without border
     #   <%= render(Primer::SubheadComponent.new(hide_border: true)) do |component| %>
     #     <% component.heading do %>

data/app/components/primer/text_component.rb

@@ -5,14 +5,17 @@ module Primer
   class TextComponent < Primer::Component
     status :beta
 
+    DEFAULT_TAG = :span
+
     # @example Default
     #   <%= render(Primer::TextComponent.new(tag: :p, font_weight: :bold)) { "Bold Text" } %>
     #   <%= render(Primer::TextComponent.new(tag: :p, color: :text_danger)) { "Danger Text" } %>
     #
+    # @param tag [Symbol]
     # @param system_arguments [Hash] <%= link_to_system_arguments_docs %>
-    def initialize(**system_arguments)
+    def initialize(tag: DEFAULT_TAG, **system_arguments)
       @system_arguments = system_arguments
-      @system_arguments[:tag] ||= :span
+      @system_arguments[:tag] = tag
     end
 
     def call

data/app/lib/primer/classify.rb

@@ -207,7 +207,7 @@ module Primer
         elsif Primer::Classify::Flex::KEYS.include?(key)
           memo[:classes] << Primer::Classify::Flex.classes(key, val, breakpoint)
         elsif key == WIDTH_KEY || key == HEIGHT_KEY
-          if val == :fit || val == :fill
+          if val == :fit
             memo[:classes] << "#{key}-#{val}"
           else
             memo[key] = val

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

@@ -111,7 +111,7 @@ module Primer
 
           preload(
             keys: [Primer::Classify::WIDTH_KEY, Primer::Classify::HEIGHT_KEY],
-            values: [:fit, :fill]
+            values: [:fit]
           )
 
           preload(

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

@@ -9,6 +9,10 @@ module Primer
       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

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 = 39
+      PATCH = 40
 
       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,312 @@
+# 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::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::TooltipComponent,
+      Primer::Truncate,
+      Primer::UnderlineNavComponent
+    ]
+
+    js_components = [
+      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