openproject-primer_view_components 0.6.3

data/lib/primer/yard/lookbook_pages_backend.rb

@@ -0,0 +1,231 @@
+# 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_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|
+          # rubocop:disable Style/IfUnlessModifier
+          if Primer::FormsPreview.instance_methods.exclude?(preview_method)
+            raise "Preview '#{preview_method}' does not exist in Primer::FormsPreview"
+          end
+          # rubocop:enable Style/IfUnlessModifier
+
+          "<%= embed Primer::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
+        generate_system_args_docs
+      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
+
+      def generate_system_args_docs
+        docs = registry.find(Primer::BaseComponent)
+
+        path = File.expand_path(
+          File.join(
+            *%w[.. .. .. previews pages system-arguments.md.erb]
+          ), __dir__
+        )
+
+        data = {
+          "description_md" => docs.base_docstring.to_s,
+          "args_md" => view_context.render(inline: docs.constructor.base_docstring)
+        }
+
+        frontmatter = {
+          "title" => "System arguments",
+          "id" => "system_arguments",
+          "data" => data
+        }
+
+        File.write(
+          path, <<~ERB
+            #{YAML.dump(frontmatter)}
+            ---
+            <%= @page.data[:description_md] %>
+            <%= @page.data[:args_md] %>
+          ERB
+        )
+      end
+    end
+  end
+end
+# :nocov:

data/lib/primer/yard/registry.rb

@@ -0,0 +1,136 @@
+# frozen_string_literal: true
+
+# :nocov:
+
+require "view_component/test_helpers"
+
+module Primer
+  module Yard
+    # A wrapper around a YARD class reference that provides convenience methods
+    # for extracting component parameters, accessibility status, etc.
+    class RegistryEntry
+      include DocsHelper
+
+      attr_reader :component, :docs
+
+      delegate_missing_to :docs
+
+      def initialize(component, docs)
+        @component = component
+        @docs = docs
+      end
+
+      def metadata
+        @metadata ||= begin
+          status_module, short_name, class_name = status_module_and_short_name(component)
+          status = component.status.to_s
+          a11y_reviewed = component.audited_at.nil? ? "false" : "true"
+
+          {
+            title: class_name,
+            class_name: class_name,
+            component_id: short_name.underscore,
+            status: status.capitalize,
+            status_module: status_module,
+            short_name: short_name,
+            a11y_reviewed: a11y_reviewed
+          }
+        end
+      end
+
+      def constructor
+        docs.meths.find(&:constructor?)
+      end
+
+      def params
+        constructor&.tags(:param) || []
+      end
+
+      def slot_methods
+        public_methods.select { |mtd| slot_method?(mtd) }
+      end
+
+      def non_slot_methods
+        public_methods.reject { |mtd| slot_method?(mtd) }
+      end
+
+      def slot_method?(mtd)
+        mtd[:renders_one] || mtd[:renders_many]
+      end
+
+      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 do |mtd|
+          mtd.tag(:private) || mtd.name == :initialize
+        end
+      end
+
+      def title
+        metadata[:title]
+      end
+
+      def component_id
+        metadata[:component_id]
+      end
+
+      def status
+        metadata[:status]
+      end
+
+      def status_module
+        metadata[:status_module]
+      end
+
+      def short_name
+        metadata[:short_name]
+      end
+
+      def a11y_reviewed?
+        metadata[:a11y_reviewed]
+      end
+
+      def manifest_entry
+        @manifest_entry ||= ComponentManifest.ref_for(component)
+      end
+    end
+
+    # Wrapper around an instance of YARD::Registry that provides easy access to component
+    # documentation.
+    class Registry
+      class << self
+        include ViewComponent::TestHelpers
+        include Primer::ViewHelper
+        include Primer::Yard::DocsHelper
+
+        def make
+          registry = ::YARD::RegistryStore.new
+          registry.load!(File.expand_path(File.join("..", "..", "..", ".yardoc"), __dir__))
+
+          new(registry)
+        end
+      end
+
+      attr_reader :yard_registry
+
+      def initialize(yard_registry)
+        @yard_registry = yard_registry
+      end
+
+      def find(component)
+        return entries[component] if entries.include?(component)
+
+        return unless (docs = yard_registry.get(component.name))
+
+        entries[component] = RegistryEntry.new(component, docs)
+      end
+
+      private
+
+      def entries
+        @entries ||= {}
+      end
+    end
+  end
+end
+# :nocov:

data/lib/primer/yard/renders_many_handler.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+# :nocov:
+module Primer
+  module Yard
+    # YARD Handler to parse `renders_many` calls.
+    class RendersManyHandler < ::YARD::Handlers::Ruby::Base
+      handles method_call(:renders_many)
+      namespace_only
+
+      process do
+        name = statement.parameters.first.jump(:tstring_content, :ident).source
+        object = ::YARD::CodeObjects::MethodObject.new(namespace, name)
+        register(object)
+        parse_block(statement.last, owner: object)
+
+        object.dynamic = true
+        object[:renders_many] = true
+      end
+    end
+  end
+end
+# :nocov:

data/lib/primer/yard/renders_one_handler.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+# :nocov:
+module Primer
+  module Yard
+    # YARD Handler to parse `renders_one` calls.
+    class RendersOneHandler < ::YARD::Handlers::Ruby::Base
+      handles method_call(:renders_one)
+      namespace_only
+
+      process do
+        name = statement.parameters.first.jump(:tstring_content, :ident).source
+        object = ::YARD::CodeObjects::MethodObject.new(namespace, name)
+        register(object)
+        parse_block(statement.last, owner: object)
+
+        object.dynamic = true
+        object[:renders_one] = true
+      end
+    end
+  end
+end
+# :nocov:

data/lib/primer/yard.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+require "yard"
+
+module Primer
+  # :nodoc:
+  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 :InfoArchDocsHelper,   "primer/yard/info_arch_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"
+
+    ::YARD::Tags::Library.define_tag("Snapshot preview", :snapshot)
+  end
+end

data/lib/rubocop/config/default.yml

@@ -0,0 +1,20 @@
+require:
+  - rubocop/cop/primer
+
+Primer/SystemArgumentInsteadOfClass:
+  Enabled: true
+
+Primer/NoTagMemoize:
+  Enabled: false
+
+Primer/PrimerOcticon:
+  Enabled: true
+
+Primer/DeprecatedArguments:
+  Enabled: true
+
+Primer/DeprecatedComponents:
+  Enabled: true
+
+Primer/TestSelector:
+  Enabled: true

data/lib/rubocop/cop/primer/base_cop.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+require "rubocop"
+require "primer/view_components/statuses"
+require_relative "../../../../app/lib/primer/view_helper"
+
+module RuboCop
+  module Cop
+    module Primer
+      # :nodoc:
+      class BaseCop < RuboCop::Cop::Cop
+        # We only verify SystemArguments if it's a `.new` call on a component or
+        # a ViewHeleper call.
+        def valid_node?(node)
+          return if node.nil?
+
+          view_helpers.include?(node.method_name) || (node.method_name == :new && !node.receiver.nil? && ::Primer::ViewComponents::STATUSES.key?(node.receiver.const_name))
+        end
+
+        private
+
+        def view_helpers
+          ::Primer::ViewHelper::HELPERS.keys.map { |key| "primer_#{key}".to_sym }
+        end
+      end
+    end
+  end
+end

data/lib/rubocop/cop/primer/component_name_migration.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+require "rubocop"
+require "primer/deprecations"
+
+# :nocov:
+module RuboCop
+  module Cop
+    module Primer
+      # This cop ensures that components don't use deprecated component names
+      #
+      # bad
+      # Primer::ComponentNameComponent.new()
+      #
+      # good
+      # Primer::Beta::ComponentName.new()
+      class ComponentNameMigration < BaseCop
+        def on_send(node)
+          return unless node.method_name == :new && !node.receiver.nil? && ::Primer::Deprecations.deprecated?(node.receiver.const_name)
+
+          message = ::Primer::Deprecations.deprecation_message(node.receiver.const_name)
+          add_offense(node.receiver, message: message)
+        end
+
+        def autocorrect(node)
+          lambda do |corrector|
+            component_name = node.const_name
+            return unless ::Primer::Deprecations.correctable?(component_name)
+
+            replacement = ::Primer::Deprecations.replacement(component_name)
+            corrector.replace(node, replacement) if replacement.present?
+          end
+        end
+      end
+    end
+  end
+end