primer_view_components 0.1.4 → 0.1.5

data/lib/primer/static/generate_arguments.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+# :nocov:
+
+require "json"
+
+module Primer
+  module Static
+    # :nodoc:
+    module GenerateArguments
+      class << self
+        def call(view_context: self.view_context)
+          Primer::Component.descendants.sort_by(&:name).map do |component|
+            docs = registry.find(component)
+            ref = Primer::Yard::ComponentManifest.ref_for(component)
+
+            args = docs.params.map do |tag|
+              default_value = Primer::Yard::DocsHelper.pretty_default_value(tag, component)
+
+              {
+                "name" => tag.name,
+                "type" => tag.types.join(", "),
+                "default" => default_value,
+                "description" => view_context.render(inline: tag.text.squish)
+              }
+            end
+
+            {
+              "component" => docs.metadata[:title],
+              "status" => component.status.to_s,
+              "a11y_reviewed" => docs.metadata[:a11y_reviewed] == "true",
+              "short_name" => docs.short_name,
+              "source" => ref.source_url,
+              "lookbook" => ref.lookbook_url,
+              "parameters" => args
+            }
+          end
+        end
+
+        private
+
+        def view_context
+          @view_context ||= ApplicationController.new.tap { |c| c.request = ActionDispatch::TestRequest.create }.view_context.tap do |vc|
+            vc.singleton_class.include(Primer::Yard::DocsHelper)
+            vc.singleton_class.include(Primer::ViewHelper)
+          end
+        end
+
+        def registry
+          @registry ||= Primer::Yard::Registry.make
+        end
+      end
+    end
+  end
+end

data/lib/primer/static/generate_audited_at.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+# :nocov:
+module Primer
+  module Static
+    # :nodoc:
+    module GenerateAuditedAt
+      class << self
+        def call
+          Primer::Component.descendants.sort_by(&:name).each_with_object({}) do |component, mem|
+            mem[component.to_s] = component.audited_at.to_s
+          end
+        end
+      end
+    end
+  end
+end

data/lib/primer/static/generate_constants.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+# :nocov:
+module Primer
+  module Static
+    # :nodoc:
+    module GenerateConstants
+      class << self
+        def call
+          Primer::Component.descendants.sort_by(&:name).each_with_object({}) do |component, mem|
+            mem[component.to_s] = component.constants(false).sort.each_with_object({}) do |constant, h|
+              h[constant] = component.const_get(constant)
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/primer/static/generate_info_arch.rb

@@ -0,0 +1,156 @@
+# frozen_string_literal: true
+
+# :nocov:
+
+require "json"
+
+module Primer
+  module Static
+    # :nodoc:
+    module GenerateInfoArch
+      SKIP_METHODS = %i[call before_render].freeze
+
+      class << self
+        def call
+          components = Primer::Component.descendants.sort_by(&:name) - [Primer::BaseComponent]
+
+          component_docs = components.each_with_object({}) do |component, memo|
+            docs = registry.find(component)
+
+            preview_data = previews.find do |preview|
+              preview["component"] == docs.metadata[:title] &&
+                preview["status"] == component.status.to_s
+            end
+
+            arg_data = args.find do |component_args|
+              component_args["component"] == docs.metadata[:title] &&
+                component_args["status"] == component.status.to_s
+            end
+
+            slot_docs = docs.slot_methods.map do |slot_method|
+              param_tags = slot_method.tags(:param)
+
+              {
+                "name" => slot_method.name,
+                # rubocop:disable Style/IfUnlessModifier
+                "description" =>
+                  if slot_method.base_docstring.to_s.present?
+                    view_context.render(inline: slot_method.base_docstring)
+                  end,
+                # rubocop:enable Style/IfUnlessModifier
+                "parameters" => serialize_params(param_tags, component)
+              }
+            end
+
+            mtds = docs.non_slot_methods.select do |mtd|
+              next false if mtd.base_docstring.to_s.blank?
+              next false if SKIP_METHODS.include?(mtd.name)
+
+              method_location, = mtd.files.first
+              class_location, = docs.docs.files.first
+
+              method_location == class_location
+            end
+
+            method_docs = mtds.map do |mtd|
+              param_tags = mtd.tags(:param)
+
+              {
+                "name" => mtd.name,
+                "description" => view_context.render(inline: mtd.base_docstring),
+                "parameters" => serialize_params(param_tags, component)
+              }
+            end
+
+            description =
+              if component == Primer::BaseComponent
+                docs.base_docstring
+              else
+                view_context.render(inline: docs.base_docstring)
+              end
+
+            memo[component] = {
+              "fully_qualified_name" => component.name,
+              "description" => description,
+              **arg_data,
+              "slots" => slot_docs,
+              "methods" => method_docs,
+              "previews" => (preview_data || {}).fetch("examples", []),
+              "subcomponents" => []
+            }
+          end
+
+          statuses = Primer::Status::Dsl::STATUSES.keys.map(&:to_s).map(&:capitalize)
+
+          Primer::Component.descendants.each do |component|
+            fq_class = component.name.to_s.split("::")
+            fq_class.shift # remove Primer::
+            status = fq_class.shift if statuses.include?(fq_class.first) # remove Status::
+
+            parent, *child = *fq_class
+
+            next if child.empty?
+
+            parent_class = Primer
+            parent_class = parent_class.const_get(status) if status
+            parent_class = parent_class.const_get(parent)
+
+            parent_docs = component_docs[parent_class]
+            next unless parent_docs
+
+            if (child_docs = component_docs.delete(component))
+              parent_docs["subcomponents"] << child_docs
+            end
+          end
+
+          component_docs.values + [system_args_docs]
+        end
+
+        private
+
+        def system_args_docs
+          docs = registry.find(Primer::BaseComponent)
+
+          {
+            component: "BaseComponent",
+            fully_qualified_name: "Primer::BaseComponent",
+            description_md: docs.base_docstring,
+            args_md: view_context.render(inline: docs.constructor.base_docstring)
+          }
+        end
+
+        def serialize_params(param_tags, component)
+          param_tags.map do |tag|
+            default_value = Primer::Yard::DocsHelper.pretty_default_value(tag, component)
+
+            {
+              "name" => tag.name,
+              "type" => tag.types&.join(", ") || "",
+              "default" => default_value,
+              "description" => view_context.render(inline: tag.text.squish)
+            }
+          end
+        end
+
+        def previews
+          @previews ||= JSON.parse(Static.read(:previews))
+        end
+
+        def args
+          @args ||= Primer::Static::GenerateArguments.call(view_context: view_context)
+        end
+
+        def view_context
+          @view_context ||= ApplicationController.new.tap { |c| c.request = ActionDispatch::TestRequest.create }.view_context.tap do |vc|
+            vc.singleton_class.include(Primer::Yard::InfoArchDocsHelper)
+            vc.singleton_class.include(Primer::ViewHelper)
+          end
+        end
+
+        def registry
+          @registry ||= Primer::Yard::Registry.make
+        end
+      end
+    end
+  end
+end

data/lib/primer/static/generate_previews.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+# :nocov:
+
+require "json"
+
+module Primer
+  module Static
+    # :nodoc:
+    module GeneratePreviews
+      class << self
+        def call
+          Lookbook.previews.filter_map do |preview|
+            next if preview.preview_class.name.start_with?("Docs::")
+            next if preview.preview_class == Primer::Forms::FormsPreview
+
+            component = preview.components.first&.component_class
+
+            # rubocop:disable Style/IfUnlessModifier
+            unless component
+              raise "Could not determine which component `#{preview.preview_class}` is designed to preview. Please add a `@component` annotation."
+            end
+            # rubocop:enable Style/IfUnlessModifier
+
+            _, _, class_name = Primer::Yard::DocsHelper.status_module_and_short_name(component)
+
+            {
+              name: preview.name,
+              component: class_name,
+              status: component.status.to_s,
+              lookup_path: preview.lookup_path,
+              examples: preview.examples.map do |example|
+                {
+                  inspect_path: example.url_path,
+                  preview_path: example.url_path.sub("/inspect/", "/preview/"),
+                  name: example.name
+                }
+              end
+            }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/primer/static/generate_statuses.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+# :nocov:
+module Primer
+  module Static
+    # :nodoc:
+    module GenerateStatuses
+      class << self
+        def call
+          Primer::Component.descendants.sort_by(&:name).each_with_object({}) do |component, mem|
+            mem[component.to_s] = component.status.to_s
+          end
+        end
+      end
+    end
+  end
+end

data/lib/primer/static.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+# :nocov:
+
+require "json"
+
+module Primer
+  # :nodoc:
+  module Static
+    DEFAULT_STATIC_PATH = File.expand_path("static").freeze
+
+    FILE_NAMES = {
+      statuses: "statuses.json",
+      constants: "constants.json",
+      audited_at: "audited_at.json",
+      arguments: "arguments.json",
+      previews: "previews.json",
+      info_arch: "info_arch.json"
+    }.freeze
+
+    # Returns a hash mapping component names to component statuses (alpha, beta, etc),
+    # sorted alphabetically by the component name.
+    def self.generate_statuses
+      Static::GenerateStatuses.call
+    end
+
+    # Returns a hash mapping component names to the date on which the component passed
+    # an accessibility audit.
+    def self.generate_audited_at
+      Static::GenerateAuditedAt.call
+    end
+
+    # Returns a hash mapping component names to an array of the constants defined inside
+    # the component's class.
+    def self.generate_constants
+      Static::GenerateConstants.call
+    end
+
+    # Returns an array of hashes, one per Primer component, that contains some metadata and
+    # a list of the arguments accepted by the component's constructor. Arguments are enumerated
+    # with their value, data type, and docstring.
+    def self.generate_arguments
+      Static::GenerateArguments.call
+    end
+
+    # Returns an array of hashes, one per Primer component, that contains some metadata and
+    # an array of all the component's previews. The preview data contains the Lookbook URL
+    # to each preview and its name.
+    def self.generate_previews
+      Static::GeneratePreviews.call
+    end
+
+    # Returns an array of hashes, one per Primer component, that contains all the data needed
+    # for the new primer.style docsite.
+    def self.generate_info_arch
+      Static::GenerateInfoArch.call
+    end
+
+    # Generates the requested stat hash and outputs it to a file.
+    def self.dump(stats)
+      File.open(File.join(DEFAULT_STATIC_PATH, FILE_NAMES[stats]), "w") do |f|
+        f.write(JSON.pretty_generate(send("generate_#{stats}")))
+        f.write($INPUT_RECORD_SEPARATOR)
+      end
+    end
+
+    # Returns the contents of the stat file.
+    def self.read(stats)
+      File.read(File.join(DEFAULT_STATIC_PATH, FILE_NAMES[stats]))
+    end
+  end
+end

data/lib/primer/view_components/linters/disallow_component_css_counter.rb

@@ -13,18 +13,57 @@ module ERBLint
   module Linters
     # Counts the number of times a class reserved for ViewComponents is used
     class DisallowComponentCssCounter < BaseLinter
+      CLASSES_COVERED_BY_OTHER_LINTERS =
+        BaseLinter.subclasses.reduce([]) do |html_classes, klass|
+          html_classes.concat(klass.const_get(:CLASSES))
+        end
+
       CLASSES = (
         JSON.parse(
           File.read(
             File.join(__dir__, "..", "..", "..", "..", "static", "classes.json")
           )
-        ) - BaseLinter.subclasses.reduce([]) do |html_classes, klass|
-          html_classes.concat(klass.const_get(:CLASSES))
+        ).reject do |html_class, _ruby_classes|
+          CLASSES_COVERED_BY_OTHER_LINTERS.include?(html_class)
         end
       ).freeze
 
-      TAGS = nil
-      MESSAGE = "Primer ViewComponents defines some HTML classes with associated styles that should not be used outside those components. (These classes might have their styles changed or even disappear in the future.) Instead of using this class directly, please use its component if appropriate or define the styles you need some other way."
+      def run(processed_source)
+        @total_offenses = 0
+        @offenses_not_corrected = 0
+
+        processed_source
+          .parser
+          .nodes_with_type(:tag)
+          .each do |node|
+            tag = BetterHtml::Tree::Tag.from_node(node)
+
+            tag.attributes["class"]&.value&.split(/\s+/)&.each do |class_name|
+              if CLASSES.key? class_name
+                @total_offenses += 1
+                @offenses_not_corrected += 1
+                add_offense(
+                  processed_source.to_source_range(tag.loc),
+                  format_message(class_name)
+                )
+              end
+            end
+          end
+
+        counter_correct?(processed_source)
+
+        dump_data(processed_source) if ENV["DUMP_LINT_DATA"] == "1"
+      end
+
+      private
+
+      def format_message(class_name)
+        "DisallowComponentCssCounter:HTML class \"#{class_name}\" is reserved for Primer ViewComponents. It might disappear or have different styles in the future. You might want to use #{ruby_classes_sentence_string(class_name)} from Primer ViewComponents instead."
+      end
+
+      def ruby_classes_sentence_string(class_name)
+        CLASSES[class_name].to_sentence(last_word_connector: ", or ", two_words_connector: " or ")
+      end
     end
   end
 end

data/lib/primer/view_components/version.rb

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

data/lib/primer/view_components.rb

@@ -7,54 +7,6 @@ require "primer/view_components/engine"
 module Primer
   # :nodoc:
   module ViewComponents
-    DEFAULT_STATIC_PATH = File.expand_path("static")
-    FILE_NAMES = {
-      statuses: "statuses.json",
-      constants: "constants.json",
-      audited_at: "audited_at.json"
-    }.freeze
-
-    # generate_statuses returns a hash mapping component name to
-    # the component's status sorted alphabetically by the component name.
-    def self.generate_statuses
-      Primer::Component.descendants.sort_by(&:name).each_with_object({}) do |component, mem|
-        mem[component.to_s] = component.status.to_s
-      end
-    end
-
-    # generate_audited_at returns a hash mapping component name to
-    # the day the component has passed an accessibility audit.
-    def self.generate_audited_at
-      Primer::Component.descendants.sort_by(&:name).each_with_object({}) do |component, mem|
-        mem[component.to_s] = component.audited_at.to_s
-      end
-    end
-
-    # generate_constants returns a hash mapping component name to
-    # all of its constants.
-    def self.generate_constants
-      Primer::Component.descendants.sort_by(&:name).each_with_object({}) do |component, mem|
-        mem[component.to_s] = component.constants(false).sort.each_with_object({}) do |constant, h|
-          h[constant] = component.const_get(constant)
-        end
-      end
-    end
-
-    # dump generates the requested stat hash and outputs it to a file.
-    def self.dump(stats)
-      require "json"
-
-      File.open(File.join(DEFAULT_STATIC_PATH, FILE_NAMES[stats]), "w") do |f|
-        f.write(JSON.pretty_generate(send("generate_#{stats}")))
-        f.write($INPUT_RECORD_SEPARATOR)
-      end
-    end
-
-    # read returns a JSON string matching the output of the corresponding stat.
-    def self.read(stats)
-      File.read(File.join(DEFAULT_STATIC_PATH, FILE_NAMES[stats]))
-    end
-
     # primer/view_components root directory.
     def self.root
       Pathname(File.expand_path(File.join("..", ".."), __dir__))

data/lib/primer/yard/component_manifest.rb

@@ -65,6 +65,7 @@ module Primer
         Primer::Alpha::Tooltip => { js: true },
         Primer::Alpha::ToggleSwitch => { js: true },
         Primer::Alpha::Overlay => { js: true },
+        Primer::Alpha::ActionMenu => { js: true },
 
         # Examples can be seen in the NavList docs
         Primer::Alpha::NavList => { js: true },

data/lib/primer/yard/component_ref.rb

@@ -34,6 +34,20 @@ module Primer
       def form_component?
         @attrs.fetch(:form_component, ATTR_DEFAULTS[:form_component])
       end
+
+      def source_url
+        @source_url ||= begin
+          path = klass.name.split("::").map(&:underscore).join("/")
+          "https://github.com/primer/view_components/tree/main/app/components/#{path}.rb"
+        end
+      end
+
+      def lookbook_url
+        @lookbook_url ||= begin
+          path = klass.name.underscore.gsub("_component", "")
+          "https://primer.style/view-components/lookbook/inspect/#{path}/default/"
+        end
+      end
     end
   end
 end

data/lib/primer/yard/docs_helper.rb

@@ -2,6 +2,7 @@
 
 # :nocov:
 module Primer
+  # :nodoc:
   module Yard
     # Helper methods to use for yard documentation
     module DocsHelper
@@ -90,6 +91,8 @@ module Primer
         end
       end
     end
+
+    DocsHelper.extend(DocsHelper)
   end
 end
 # :nocov:

data/lib/primer/yard/info_arch_docs_helper.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+# :nocov:
+module Primer
+  module Yard
+    # Helper methods to use for info arch yard documentation
+    module InfoArchDocsHelper
+      include DocsHelper
+
+      def link_to_component(component)
+        "{{#link_to_component}}#{component}{{/link_to_component}}"
+      end
+
+      def link_to_system_arguments_docs
+        "{{link_to_system_arguments_docs}}"
+      end
+
+      def link_to_typography_docs
+        "{{link_to_typography_docs}}"
+      end
+
+      def link_to_accessibility
+        "{{link_to_accessibility}}"
+      end
+
+      def link_to_octicons
+        "{{link_to_octicons}}"
+      end
+    end
+  end
+end

data/lib/primer/yard/legacy_gatsby_backend.rb

@@ -33,7 +33,6 @@ module Primer
       end
 
       def generate
-        args_for_components = []
         errors = []
 
         each_component do |component_ref|
@@ -42,8 +41,8 @@ module Primer
           status_path = docs.status_module.nil? ? "" : "#{docs.status_module}/"
 
           metadata = docs.metadata.merge(
-            source: source_url(component),
-            lookbook: lookbook_url(component),
+            source: component_ref.source_url,
+            lookbook: component_ref.lookbook_url,
             path: "docs/content/components/#{status_path}#{docs.short_name.downcase}.md",
             example_path: example_path(component),
             require_js_path: require_js_path(component)
@@ -113,30 +112,11 @@ module Primer
               errors << { component.name => err }
             end
 
-            args = []
             docs.params.each do |tag|
               default_value = pretty_default_value(tag, component)
-
-              args << {
-                "name" => tag.name,
-                "type" => tag.types.join(", "),
-                "default" => default_value,
-                "description" => view_context.render(inline: tag.text.squish)
-              }
-
               f.puts("| `#{tag.name}` | `#{tag.types.join(', ')}` | #{default_value} | #{view_context.render(inline: tag.text.squish)} |")
             end
 
-            component_args = {
-              "component" => metadata[:title],
-              "status" => component.status.to_s,
-              "source" => metadata[:source],
-              "lookbook" => metadata[:lookbook],
-              "parameters" => args
-            }
-
-            args_for_components << component_args
-
             if docs.slot_methods.any?
               f.puts
               f.puts("## Slots")
@@ -190,7 +170,7 @@ module Primer
           f.puts(view_context.render(inline: system_args_docs.constructor.base_docstring))
         end
 
-        [args_for_components, errors]
+        errors
       end
 
       private
@@ -220,18 +200,6 @@ module Primer
         manifest.each(&block)
       end
 
-      def source_url(component)
-        path = component.name.split("::").map(&:underscore).join("/")
-
-        "https://github.com/primer/view_components/tree/main/app/components/#{path}.rb"
-      end
-
-      def lookbook_url(component)
-        path = component.name.underscore.gsub("_component", "")
-
-        "https://primer.style/view-components/lookbook/inspect/#{path}/default/"
-      end
-
       def example_path(component)
         example_path = "../../src/@primer/gatsby-theme-doctocat/components/example"
         example_path = "../#{example_path}" if status_module?(component)

data/lib/primer/yard/registry.rb

@@ -28,6 +28,7 @@ module Primer
 
           {
             title: class_name,
+            class_name: class_name,
             component_id: short_name.underscore,
             status: status.capitalize,
             status_module: status_module,
@@ -42,7 +43,7 @@ module Primer
       end
 
       def params
-        constructor.tags(:param)
+        constructor&.tags(:param) || []
       end
 
       def slot_methods