primer_view_components 0.0.121 → 0.0.122

data/lib/primer/yard/component_manifest.rb

@@ -2,7 +2,7 @@
 
 # :nocov:
 module Primer
-  module YARD
+  module Yard
     # The set of documented components (and associated metadata).
     class ComponentManifest
       COMPONENTS = {
@@ -77,42 +77,61 @@ module Primer
         Primer::Alpha::ActionList::Item => { examples: false },
 
         # Forms
-        Primer::Alpha::TextField => { form_component: true }
+        Primer::Alpha::TextField => { form_component: true },
+        Primer::Alpha::TextArea => { form_component: true, published: false },
+        Primer::Alpha::Select => { form_component: true, published: false },
+        Primer::Alpha::MultiInput => { form_component: true, js: true, published: false },
+        Primer::Alpha::RadioButton => { form_component: true, published: false },
+        Primer::Alpha::RadioButtonGroup => { form_component: true, published: false },
+        Primer::Alpha::CheckBox => { form_component: true, published: false },
+        Primer::Alpha::CheckBoxGroup => { form_component: true, published: false },
+        Primer::Alpha::SubmitButton => { form_component: true, published: false },
+        Primer::Alpha::FormButton => { form_component: true, published: false }
       }.freeze
 
-      class << self
-        def each(&block)
-          COMPONENTS.keys.each(&block)
-        end
+      include Enumerable
 
-        def components_with_docs
-          @components_with_docs ||= COMPONENTS.keys
-        end
+      def initialize(components)
+        @components = components
+      end
+
+      def each
+        return to_enum(__method__) unless block_given?
 
-        def all_components
-          @all_components ||= Primer::Component.descendants - [Primer::BaseComponent]
+        @components.each do |klass|
+          yield self.class.ref_for(klass)
         end
+      end
 
-        def components_without_docs
-          @components_without_docs ||= all_components - components_with_docs
+      def where(**attrs)
+        self.class.where(@components, **attrs)
+      end
+
+      class << self
+        def where(components = COMPONENTS, **desired_attrs)
+          new(
+            components.each_with_object([]) do |(klass, component_attrs), memo|
+              matches = desired_attrs.all? do |name, desired_value|
+                component_attrs.fetch(name, ComponentRef::ATTR_DEFAULTS[name]) == desired_value
+              end
+
+              memo << klass if matches
+            end
+          )
         end
 
-        def components_with_examples
-          @components_with_examples ||= COMPONENTS.keys.select do |c|
-            COMPONENTS[c].fetch(:examples, true)
-          end
+        def all
+          new(COMPONENTS.keys)
         end
 
-        def components_requiring_js
-          @components_requiring_js ||= COMPONENTS.keys.select do |c|
-            COMPONENTS[c].fetch(:js, false)
-          end
+        def ref_for(klass)
+          ref_cache[klass] ||= ComponentRef.new(klass, COMPONENTS[klass])
         end
 
-        def form_components
-          @form_components ||= COMPONENTS.keys.select do |c|
-            COMPONENTS[c].fetch(:form_component, false)
-          end
+        private
+
+        def ref_cache
+          @ref_cache ||= {}
         end
       end
     end

data/lib/primer/yard/component_ref.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+# :nocov:
+module Primer
+  module Yard
+    # :nodoc:
+    class ComponentRef
+      ATTR_DEFAULTS = {
+        js: false,
+        examples: true,
+        published: true,
+        form_component: false
+      }.freeze
+
+      attr_reader :klass, :attrs
+
+      def initialize(klass, attrs)
+        @klass = klass
+        @attrs = attrs
+      end
+
+      def requires_js?
+        @attrs.fetch(:js, ATTR_DEFAULTS[:js])
+      end
+
+      def should_have_examples?
+        @attrs.fetch(:examples, ATTR_DEFAULTS[:examples])
+      end
+
+      def published?
+        @attrs.fetch(:published, ATTR_DEFAULTS[:published])
+      end
+
+      def form_component?
+        @attrs.fetch(:form_component, ATTR_DEFAULTS[:form_component])
+      end
+    end
+  end
+end
+# :nocov:

data/lib/primer/yard/docs_helper.rb

@@ -1,9 +1,8 @@
 # frozen_string_literal: true
 
 # :nocov:
-
 module Primer
-  module YARD
+  module Yard
     # Helper methods to use for yard documentation
     module DocsHelper
       def one_of(enumerable, lower: false, sort: true)
@@ -66,6 +65,20 @@ module Primer
         [m[:status]&.downcase, m[:name].gsub("::", ""), m[:name]]
       end
 
+      def pretty_default_value(tag, component)
+        params = tag.object.parameters.find { |param| [tag.name.to_s, "#{tag.name}:"].include?(param[0]) }
+        default = tag.defaults&.first || params&.second
+
+        return "N/A" unless default
+
+        constant_name = "#{component.name}::#{default}"
+        constant_value = default.safe_constantize || constant_name.safe_constantize
+
+        return pretty_value(default) if constant_value.nil?
+
+        pretty_value(constant_value)
+      end
+
       def pretty_value(val)
         case val
         when nil
@@ -79,3 +92,4 @@ module Primer
     end
   end
 end
+# :nocov:

data/lib/primer/yard/legacy_gatsby_backend.rb

@@ -3,12 +3,8 @@
 # rubocop:disable Naming/MethodParameterName
 
 # :nocov:
-
-require "primer/yard/component_manifest"
-require "primer/yard/backend"
-
 module Primer
-  module YARD
+  module Yard
     # Backend that generates documentation for the legacy, Gatsby-powered PVC docsite.
     class LegacyGatsbyBackend < Backend
       class << self
@@ -29,17 +25,19 @@ module Primer
         end
       end
 
-      attr_reader :registry
+      attr_reader :registry, :manifest
 
-      def initialize(registry)
+      def initialize(registry, manifest)
         @registry = registry
+        @manifest = manifest
       end
 
       def generate
         args_for_components = []
         errors = []
 
-        each_component do |component|
+        each_component do |component_ref|
+          component = component_ref.klass
           docs = registry.find(component)
           status_path = docs.status_module.nil? ? "" : "#{docs.status_module}/"
 
@@ -66,7 +64,7 @@ module Primer
             f.puts
             f.puts("import Example from '#{metadata[:example_path]}'")
 
-            if docs.requires_js?
+            if component_ref.requires_js?
               f.puts("import RequiresJSFlash from '#{metadata[:require_js_path]}'")
               f.puts
               f.puts("<RequiresJSFlash />")
@@ -170,7 +168,7 @@ module Primer
                 f.puts(code.to_s)
                 f.puts("```")
               end
-            elsif manifest.components_with_examples.include?(component)
+            elsif component_ref.should_have_examples?
               errors << { component.name => { example: "No examples found" } }
             end
           end
@@ -219,11 +217,7 @@ module Primer
       end
 
       def each_component(&block)
-        manifest.components_with_docs.sort_by(&:name).each(&block)
-      end
-
-      def manifest
-        Primer::YARD::ComponentManifest
+        manifest.each(&block)
       end
 
       def source_url(component)

data/lib/primer/yard/lookbook_docs_helper.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+# :nocov:
+module Primer
+  module Yard
+    # Helper methods for documentation generated in Lookbook pages.
+    module LookbookDocsHelper
+      # Adheres to the same signature as Primer::Yard::DocsHelper#link_to_component so link_to_component
+      # may be used in a Gatsby or Lookbook context and produce the correct link for each platform.
+      #
+      # @param component [Class] The component class to link to.
+      # @return [String] The link, either in HTML or markdown format.
+      def link_to_component(component)
+        backend = Primer::Yard::LookbookPagesBackend.new(Primer::Yard::Registry.make, nil)
+        component_ref = Primer::Yard::ComponentManifest.ref_for(component)
+        page = backend.page_for(component_ref)
+
+        # If the page_path method is available, we're being rendered into HTML by Lookbook
+        # and should emit an HTML <a> tag. No page_path means we're being rendered into
+        # markdown by LookbookPagesBackend and should emit a markdown + ERB link that
+        # Lookbook will eventually render on page load.
+        if respond_to?(:page_path)
+          link_to(page.docs.short_name, page_path(page.page_id.to_sym.inspect))
+        else
+          # rubocop:disable Rails/OutputSafety
+          "[#{page.docs.short_name}](<%= page_path(#{page.page_id.to_sym.inspect}) %>)".html_safe
+          # rubocop:enable Rails/OutputSafety
+        end
+      end
+    end
+  end
+end

data/lib/primer/yard/lookbook_pages_backend.rb

@@ -0,0 +1,194 @@
+# frozen_string_literal: true
+
+# :nocov:
+module Primer
+  module Yard
+    # A single Lookbook page.
+    class LookbookPage
+      include DocsHelper
+
+      PREVIEW_MAP = {
+        Primer::Alpha::TextField => [:single_text_field_form, :multi_text_field_form],
+        Primer::Alpha::TextArea => [],
+        Primer::Alpha::Select => [:select_list_form],
+        Primer::Alpha::MultiInput => [:multi_input_form],
+        Primer::Alpha::RadioButton => [:radio_button_with_nested_form],
+        Primer::Alpha::RadioButtonGroup => [:radio_button_group_form],
+        Primer::Alpha::CheckBox => [:check_box_with_nested_form],
+        Primer::Alpha::CheckBoxGroup => [:check_box_group_form],
+        Primer::Alpha::SubmitButton => [:submit_button_form],
+        Primer::Alpha::FormButton => [:submit_button_form]
+      }.freeze
+
+      attr_reader :component_ref, :backend, :docs
+
+      def initialize(component_ref, backend, docs)
+        @component_ref = component_ref
+        @backend = backend
+        @docs = docs
+      end
+
+      def page_id
+        @page_id ||= docs.short_name.dasherize.underscore.tap do |page_id|
+          page_id << "_input" unless page_id.end_with?("_input")
+        end
+      end
+
+      def generate
+        path = File.expand_path(
+          File.join(
+            *%w[.. .. .. previews pages forms inputs],
+            "#{docs.short_name.dasherize.underscore}.md.erb"
+          ), __dir__
+        )
+
+        # rubocop:disable Lint/UselessAssignment
+        documented_methods = docs.non_slot_methods.select do |mtd|
+          [component.name, "Primer::Forms::Dsl::InputMethods"].include?(mtd.parent.title)
+        end
+
+        preview_methods = PREVIEW_MAP[component]
+        preview_erbs = preview_methods.map do |preview_method|
+          "<%= embed Primer::Forms::FormsPreview, #{preview_method.inspect} %>"
+        end
+        # rubocop:enable Lint/UselessAssignment
+
+        # rubocop:disable Security/Eval
+        File.open(path, "w") do |f|
+          f.write(eval(Erubi::Engine.new(<<~ERB, trim: true).src))
+            ---
+            title: <%= docs.title.underscore.titleize %>
+            id: <%= page_id %>
+            ---
+
+            <%= docs.base_docstring %>
+
+            ## Usage
+
+            ```ruby
+            <%= docs.tags(:form_usage).first.text %>
+            ```
+
+            <% specific_args = specific_args_from(docs.params) %>
+            <% unless specific_args.empty? %>
+            ## Arguments
+
+            <%= generate_args_table(specific_args) %>
+            <% end %>
+
+            ## Common arguments
+
+            <%= generate_args_table(common_args_from(docs.params)) %>
+
+            <% unless documented_methods.empty? %>
+            ## Methods
+
+              <% documented_methods.each do |method_docs| %>
+            ### `#<%= method_docs.signature.sub(/def /, "") %>`
+
+            <%= method_docs.base_docstring %>
+
+                <% param_tags = method_docs.tags(:param) %>
+
+                <% if param_tags.any? %>
+
+            <%= generate_args_table(param_tags) %>
+                <% end %>
+              <% end %>
+            <% end %>
+
+            <% unless preview_methods.empty? %>
+            ## Examples
+
+            <%= preview_erbs.join("\n") %>
+            <% end %>
+          ERB
+        end
+        # rubocop:enable Security/Eval
+      end
+
+      private
+
+      def registry
+        backend.registry
+      end
+
+      def generate_args_table(params)
+        rows = params.map do |tag|
+          description = backend.view_context.render(inline: tag.text.squish)
+          parts = [
+            "`#{tag.name}`",
+            tag.types.join(", "),
+            description
+          ]
+
+          "| #{parts.join(' | ')} |"
+        end
+
+        <<~MARKDOWN
+          | Name | Type | Description |
+          | :- | :- | :- |
+          #{rows.join("\n")}
+        MARKDOWN
+      end
+
+      def common_args_from(params)
+        params.select { |param| common_form_input_argument_names.include?(param.name) }
+      end
+
+      def specific_args_from(params)
+        params.reject { |param| common_form_input_argument_names.include?(param.name) }
+      end
+
+      def common_form_input_argument_names
+        @common_form_input_argument_names ||= begin
+          macro = registry.yard_registry[".macro.form_input_arguments"]
+          parser = ::YARD::Docstring.parser
+          parser.parse(macro.macro_data)
+          parser
+            .tags
+            .select { |tag| tag.tag_name == "param" }
+            .map(&:name)
+        end
+      end
+
+      def component
+        component_ref.klass
+      end
+    end
+
+    # Backend that generates Lookbook pages.
+    class LookbookPagesBackend < Backend
+      attr_reader :registry, :manifest
+
+      def initialize(registry, manifest)
+        @registry = registry
+        @manifest = manifest
+      end
+
+      def generate
+        each_component do |component_ref|
+          page_for(component_ref).generate
+        end
+      end
+
+      def page_for(component_ref)
+        docs = registry.find(component_ref.klass)
+        LookbookPage.new(component_ref, self, docs)
+      end
+
+      def view_context
+        @view_context ||= super.tap do |vc|
+          vc.singleton_class.include(LookbookDocsHelper)
+        end
+      end
+
+      private
+
+      def each_component(&block)
+        manifest.each(&block)
+      end
+    end
+  end
+end
+# :nocov:

data/lib/primer/yard/registry.rb

@@ -2,12 +2,10 @@
 
 # :nocov:
 
-require "primer/view_components"
-require "primer/yard/docs_helper"
 require "view_component/test_helpers"
 
 module Primer
-  module YARD
+  module Yard
     # A wrapper around a YARD class reference that provides convenience methods
     # for extracting component parameters, accessibility status, etc.
     class RegistryEntry
@@ -62,8 +60,9 @@ module Primer
       def public_methods
         # Returns: only public methods that belong to this class (i.e. no inherited methods)
         # excluding the constructor
-        @public_methods ||=
-          docs.meths.reject { |mtd| mtd.tag(:private) || mtd.name == :initialize }
+        @public_methods ||= docs.meths.reject do |mtd|
+          mtd.tag(:private) || mtd.name == :initialize
+        end
       end
 
       def title
@@ -89,20 +88,6 @@ module Primer
       def a11y_reviewed?
         metadata[:a11y_reviewed]
       end
-
-      def requires_js?
-        manifest.components_requiring_js.include?(component)
-      end
-
-      def includes_examples?
-        manifest.components_with_examples.include?(component)
-      end
-
-      private
-
-      def manifest
-        Primer::YARD::ComponentManifest
-      end
     end
 
     # Wrapper around an instance of YARD::Registry that provides easy access to component
@@ -111,11 +96,11 @@ module Primer
       class << self
         include ViewComponent::TestHelpers
         include Primer::ViewHelper
-        include Primer::YARD::DocsHelper
+        include Primer::Yard::DocsHelper
 
         def make
           registry = ::YARD::RegistryStore.new
-          registry.load!(".yardoc")
+          registry.load!(File.expand_path(File.join("..", "..", "..", ".yardoc"), __dir__))
 
           new(registry)
         end

data/lib/primer/yard/renders_many_handler.rb

@@ -2,7 +2,7 @@
 
 # :nocov:
 module Primer
-  module YARD
+  module Yard
     # YARD Handler to parse `renders_many` calls.
     class RendersManyHandler < ::YARD::Handlers::Ruby::Base
       handles method_call(:renders_many)

data/lib/primer/yard/renders_one_handler.rb

@@ -2,7 +2,7 @@
 
 # :nocov:
 module Primer
-  module YARD
+  module Yard
     # YARD Handler to parse `renders_one` calls.
     class RendersOneHandler < ::YARD::Handlers::Ruby::Base
       handles method_call(:renders_one)

data/lib/primer/yard.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module Primer
+  module Yard
+    autoload :Backend,              "primer/yard/backend"
+    autoload :ComponentManifest,    "primer/yard/component_manifest"
+    autoload :ComponentRef,         "primer/yard/component_ref"
+    autoload :DocsHelper,           "primer/yard/docs_helper"
+    autoload :LegacyGatsbyBackend,  "primer/yard/legacy_gatsby_backend"
+    autoload :Registry,             "primer/yard/registry"
+    autoload :RendersManyHandler,   "primer/yard/renders_many_handler"
+    autoload :RendersOneHandler,    "primer/yard/renders_one_handler"
+  end
+end

data/lib/tasks/docs.rake

@@ -21,12 +21,15 @@ namespace :docs do
     sleep
   end
 
-  task build: [:build_gatsby, :build_gatsby_adrs]
+  task build: [:build_gatsby_pages, :build_gatsby_adrs, :build_lookbook_pages]
 
-  task build_gatsby: :build_yard_registry do
-    registry = Primer::YARD::Registry.make
+  task build_gatsby_pages: :build_yard_registry do
+    require "primer/yard"
+
+    registry = Primer::Yard::Registry.make
 
     require "primer/yard/legacy_gatsby_backend"
+    require "primer/yard/component_manifest"
 
     puts "Converting YARD documentation to Markdown files."
 
@@ -34,7 +37,8 @@ namespace :docs do
     components_content_glob = File.join(*%w[docs content components ** *.md])
     FileUtils.rm_rf(components_content_glob)
 
-    backend = Primer::YARD::LegacyGatsbyBackend.new(registry)
+    manifest = Primer::Yard::ComponentManifest.where(published: true)
+    backend = Primer::Yard::LegacyGatsbyBackend.new(registry, manifest)
     args_for_components, errors = backend.generate
 
     unless errors.empty?
@@ -55,7 +59,8 @@ namespace :docs do
 
     puts "Markdown compiled."
 
-    components_needing_docs = Primer::YARD::ComponentManifest.components_without_docs
+    all_components = Primer::Component.descendants - [Primer::BaseComponent]
+    components_needing_docs = all_components - Primer::Yard::ComponentManifest::COMPONENTS.keys
 
     if components_needing_docs.any?
       puts
@@ -63,6 +68,15 @@ namespace :docs do
     end
   end
 
+  task build_lookbook_pages: :build_yard_registry do
+    require "primer/yard"
+
+    registry = Primer::Yard::Registry.make
+    manifest = Primer::Yard::ComponentManifest.where(form_component: true)
+    backend = Primer::Yard::LookbookPagesBackend.new(registry, manifest)
+    backend.generate
+  end
+
   task :build_gatsby_adrs do
     adr_content_dir = File.join(*%w[docs content adr])
 
@@ -109,16 +123,15 @@ namespace :docs do
   end
 
   task preview: :build_yard_registry do
-    registry = Primer::YARD::Registry.make
-
-    require "primer/yard/legacy_gatsby_backend"
+    require "primer/yard"
 
     FileUtils.rm_rf("previews/primer/docs/")
 
-    manifest = Primer::YARD::ComponentManifest
+    registry = Primer::Yard::Registry.make
 
     # Generate previews from documentation examples
-    manifest.all_components.each do |component|
+    Primer::Yard::ComponentManifest.all.each do |component_ref|
+      component = component_ref.klass
       docs = registry.find(component)
       next unless docs.constructor&.tags(:example)&.any?
 
@@ -132,7 +145,7 @@ namespace :docs do
         f.puts("  class #{docs.short_name}Preview < ViewComponent::Preview")
 
         yard_example_tags.each_with_index do |tag, index|
-          name, _, code = Primer::YARD::LegacyGatsbyBackend.parse_example_tag(tag)
+          name, _, code = Primer::Yard::LegacyGatsbyBackend.parse_example_tag(tag)
           method_name = name.split("|").first.downcase.parameterize.underscore
           f.puts("    def #{method_name}; end")
           f.puts unless index == yard_example_tags.size - 1
@@ -152,11 +165,11 @@ namespace :docs do
   task :init_pvc do
     ENV["RAILS_ENV"] = "test"
     require File.expand_path("./../../demo/config/environment.rb", __dir__)
-    Dir["./app/components/primer/**/*.rb"].sort.each { |file| require file }
+    Dir[File.expand_path("../../app/components/primer/**/*.rb", __dir__)].sort.each { |file| require file }
   end
 
   task build_yard_registry: :init_pvc do
-    require "primer/yard/registry"
+    require "primer/yard"
 
     ::YARD::Rake::YardocTask.new do |task|
       task.options << "--no-output"