primer_view_components 0.0.120 → 0.0.122

data/lib/primer/forms/text_field.rb

@@ -9,10 +9,14 @@ module Primer
       def initialize(input:)
         @input = input
 
+        @input.add_input_classes(
+          "FormControl-input",
+          Primer::Forms::Dsl::Input::SIZE_MAPPINGS[@input.size]
+        )
+
         @field_wrap_arguments = {
           class: class_names(
             "FormControl-input-wrap",
-            Primer::Forms::Dsl::Input::SIZE_MAPPINGS[@input.size],
             "FormControl-input-wrap--trailingAction": @input.show_clear_button?,
             "FormControl-input-wrap--leadingVisual": @input.leading_visual?
           ),

data/lib/primer/forms/toggle_switch_form.rb

@@ -32,8 +32,10 @@ module Primer
     #
     class ToggleSwitchForm < Primer::Forms::Base
       # Define the form on subclasses so render(Subclass.new) works as expected.
-      def self.inherited(base)
-        base.form do |toggle_switch_form|
+      # (this is called directly on this class, but also on classes
+      # that inherit from this class)
+      def self.define_form_on(klass)
+        klass.form do |toggle_switch_form|
           input = Dsl::ToggleSwitchInput.new(
             builder: toggle_switch_form.builder, form: self, **@system_arguments
           )
@@ -42,8 +44,13 @@ module Primer
         end
       end
 
+      def self.inherited(base)
+        super
+        define_form_on(base)
+      end
+
       # Define the form on self so render(ToggleSwitchForm.new) works as expected.
-      inherited(self)
+      define_form_on(self)
 
       # Override to avoid accepting a builder argument. We create our own builder
       # on render. See the implementation of render_in below.

data/lib/primer/forms/utils.rb

@@ -5,6 +5,10 @@ module Primer
   module Forms
     # :nodoc:
     module Utils
+      include Primer::ClassNameHelper
+
+      PRIMER_UTILITY_KEYS = Primer::Classify::Utilities::UTILITIES.keys.freeze
+
       # Unfortunately this bug (https://github.com/ruby/ruby/pull/5646) prevents us from using
       # Ruby's native Module.const_source_location. Instead we have to fudge it by searching
       # for the file in the configured autoload paths. Doing so relies on Rails' autoloading
@@ -21,6 +25,22 @@ module Primer
 
         nil
       end
+
+      # This method does the following:
+      #
+      # 1. Runs Primer's classify routine to convert entries like mb: 1 to mb-1.
+      # 2. Runs classify on both options[:class] and options[:classes]. The first
+      #    is expected by Rails/HTML while the second is specific to Primer.
+      # 3. Combines options[:class] and options[:classes] into options[:class]
+      #    so the options hash can be easily passed to Rails form builder methods.
+      #
+      def classify(options)
+        options[:classes] = class_names(options.delete(:class), options[:classes])
+        options.merge!(Primer::Classify.call(options))
+        options.except!(*PRIMER_UTILITY_KEYS)
+        options[:class] = class_names(options[:class], options.delete(:classes))
+        options
+      end
     end
 
     Utils.extend(Utils)

data/lib/primer/view_components/engine.rb

@@ -43,7 +43,7 @@ module Primer
       end
 
       initializer "primer.forms.helpers" do
-        ActiveSupport.on_load :action_controller do
+        ActiveSupport.on_load :action_controller_base do
           require "primer/form_helper"
           helper Primer::FormHelper
 

data/lib/primer/view_components/version.rb

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

data/lib/primer/yard/backend.rb

@@ -2,27 +2,13 @@
 
 # :nocov:
 module Primer
-  module YARD
+  module Yard
     # Shared functionality for generating documentation from YARD comments.
     class Backend
       include DocsHelper
 
       private
 
-      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 view_context
         @view_context ||= begin
           # Rails controller for rendering arbitrary ERB

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 = {
@@ -13,7 +13,6 @@ module Primer
         Primer::Alpha::Layout => {},
         Primer::Alpha::HellipButton => {},
         Primer::Alpha::Image => {},
-        Primer::LocalTime => { js: true },
         Primer::Alpha::OcticonSymbols => {},
         Primer::Alpha::ImageCrop => { js: true },
         Primer::IconButton => { js: true },
@@ -54,7 +53,6 @@ module Primer
         Primer::Beta::Subhead => {},
         Primer::Alpha::TabContainer => { js: true },
         Primer::Beta::Text => {},
-        Primer::TimeAgoComponent => { js: true },
         Primer::Beta::TimelineItem => {},
         Primer::Tooltip => {},
         Primer::Truncate => {},
@@ -79,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)