primer_view_components 0.0.121 → 0.0.123

data/lib/primer/form_components.rb

@@ -12,24 +12,44 @@ module Primer
           attr_reader :input_klass
         end
 
-        def initialize(**system_arguments, &block)
+        def initialize(**system_arguments)
           @system_arguments = system_arguments
-          @block = block
         end
 
-        def call
+        def render_in(view_context, &block)
           builder = Primer::Forms::Builder.new(
-            nil, nil, __vc_original_view_context, {}
+            nil, nil, view_context, {}
           )
 
+          # `block` is the block passed to `#render`. We pass it to the
+          # input's constructor here to mimic the way constructors often
+          # yield in the forms framework. Only allowing the block to be
+          # passed to `#initialize` is awkward because `#render` is often
+          # called without parens, making it non-obvious which method the
+          # block is passed to. Moreover, users of view components expect
+          # `#render` to accept a block and for that block to yield the
+          # component, which allows setting slots, etc. They do not expect
+          # that block to be accepted by the component's initializer
+          # instead.
+          #
+          # One caveat here is that not all form input classes yield
+          # themselves to the block. In such a case, the block will
+          # never be called, which is potentially confusing. We could
+          # detect whether or not the block is called and yield the input
+          # if it is not, but that comes with its own set of problems and
+          # could also lead to confusion (for example, if the block is
+          # conditionally called with one set of arguments from the input
+          # and then a different set of arguments here). Since we can't
+          # know which arguments the input will yield, it's safer to simply
+          # pass the block as-is.
           input = self.class.input_klass.new(
             builder: builder,
             form: nil,
             **@system_arguments,
-            &@block
+            &block
           )
 
-          input.to_component.render_in(__vc_original_view_context) { content }
+          input.to_component.render_in(view_context) { content }
         end
       end
     end

data/lib/primer/forms/builder.rb

@@ -29,10 +29,6 @@ module Primer
   module Forms
     # :nodoc:
     class Builder < ActionView::Helpers::FormBuilder
-      include Primer::ClassNameHelper
-
-      UTILITY_KEYS = Primer::Classify::Utilities::UTILITIES.keys.freeze
-
       alias primer_fields_for fields_for
 
       def label(method, text = nil, **options, &block)
@@ -67,20 +63,8 @@ module Primer
 
       private
 
-      # 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!(*UTILITY_KEYS)
-        options[:class] = class_names(options[:class], options.delete(:classes))
-        options
+        Primer::Forms::Utils.classify(options)
       end
     end
   end

data/lib/primer/forms/button.rb

@@ -49,7 +49,10 @@ module Primer
       def input_arguments
         @input_arguments ||= @input.input_arguments.deep_dup.tap do |args|
           # rails uses :class but PVC wants :classes
-          args[:classes] = args.delete(:class)
+          args[:classes] = class_names(
+            args[:classes],
+            args.delete(:class)
+          )
         end
       end
 

data/lib/primer/forms/check_box_group.html.erb

@@ -1,12 +1,17 @@
-<%= content_tag(:fieldset, hidden: @input.hidden?) do %>
-  <% if @input.label %>
-    <%= content_tag(:legend, **@input.label_arguments) do %>
-      <%= @input.label %>
+<%= content_tag(:div, **@input.input_arguments) do %>
+  <fieldset>
+    <% if @input.label %>
+      <%= content_tag(:legend, **@input.label_arguments) do %>
+        <%= @input.label %>
+      <% end %>
     <% end %>
-  <% end %>
-  <%= render(SpacingWrapper.new) do %>
-    <% @input.check_boxes.each do |check_box| %>
-      <%= render(check_box.to_component) %>
+    <%= render(SpacingWrapper.new) do %>
+      <% @input.check_boxes.each do |check_box| %>
+        <%= render(check_box.to_component) %>
+      <% end %>
     <% end %>
-  <% end %>
+  </fieldset>
+  <div class="mt-2">
+    <%= render(Caption.new(input: @input)) %>
+  </div>
 <% end %>

data/lib/primer/forms/check_box_group.rb

@@ -8,6 +8,11 @@ module Primer
 
       def initialize(input:)
         @input = input
+
+        @input.add_label_classes("FormControl-label", "mb-2")
+        @input.add_input_classes("FormControl-check-group-wrap")
+
+        Primer::Forms::Utils.classify(@input.input_arguments)
       end
     end
   end

data/lib/primer/forms/dsl/check_box_group_input.rb

@@ -14,8 +14,6 @@ module Primer
 
           super(**system_arguments)
 
-          add_label_classes("FormControl-label", "mb-2")
-
           yield(self) if block_given?
         end
 
@@ -34,10 +32,11 @@ module Primer
         def check_box(**system_arguments, &block)
           args = {
             name: @name,
-            **system_arguments,
             builder: @builder,
             form: @form,
-            scheme: scheme
+            scheme: scheme,
+            disabled: disabled?,
+            **system_arguments
           }
 
           @check_boxes << CheckBoxInput.new(**args, &block)

data/lib/primer/forms/dsl/input.rb

@@ -5,6 +5,37 @@ module Primer
     module Dsl
       # :nodoc:
       class Input
+        # Use this macro anywhere you want to include the various params all inputs can receive.
+        #
+        # @!macro [new] form_input_arguments
+        #   @param name [String] Value for the HTML name attribute.
+        #   @param id [String] Value for the HTML id attribute.
+        #   @param class [String] CSS classes to include in the input's HTML `class` attribute. Exists for compatibility with Rails form builders.
+        #   @param classes [Array] CSS classes to include in the input's HTML `class` attribute. Combined with the `:class` argument. The list may contain strings, hashes, or `nil` values, and is automatically cleaned up by Primer's [`class_name` helper](https://github.com/primer/view_components/blob/c9cb95c98fee3e2e27f4a10683f555e22285e7f1/app/lib/primer/class_name_helper.rb) (`nils`, falsy entries, and blank strings are ignored).
+        #   @param caption [String] A string describing the field and what sorts of input it expects. Displayed below the input.
+        #   @param label [String] Label text displayed above the input.
+        #   @param visually_hide_label [Boolean] When set to `true`, hides the label. Although the label will be hidden visually, it will still be visible to screen readers.
+        #   @param disabled [Boolean] When set to `true`, the input will not accept keyboard or mouse input.
+        #   @param hidden [Boolean] When set to `true`, visually hides the field.
+        #   @param invalid [Boolean] If set to `true`, the input will be rendered with a red border. Implied if `validation_message` is truthy. This option is set to `true` automatically if the model object associated with the form reports that the input is invalid via Rails validations. It is provided for cases where the form does not have an associated model. If the input is invalid as determined by Rails validations, setting `invalid` to `false` will have no effect.
+        #   @param validation_message [String] A string displayed between the caption and the input indicating the input's contents are invalid. This option is, by default, set to the first Rails validation message for the input (assuming the form is associated with a model object). Use `validation_message` to override the default or to provide a validation message in case there is no associated model object.
+        #   @param label_arguments [Hash] Attributes that will be passed to Rails' `builder.label` method. These can be HTML attributes or any of the other label options Rails supports. They will appear as HTML attributes on the `<label>` tag.
+        #   @param scope_name_to_model [Boolean] Default `true`. When set to `false`, prevents the model name from prefixing the field name. For example, if the field name is `my_field`, Rails will normally emit an HTML name attribute of `model[my_field]`. Setting `scope_name_to_model` to `false` will cause Rails to emit `my_field` instead.
+        #   @param scope_id_to_model [Boolean] Default `true`. When set to `false`, prevents the model name from prefixing the field ID. For example, if the field name is `my_field`, Rails will normally emit an HTML ID attribute of `model_my_field`. Setting `scope_id_to_model` to `false` will cause Rails to emit `my_field` instead.
+        #   @param required [Boolean] Default `false`. When set to `true`, causes an asterisk (*) to appear next to the field's label indicating it is a required field. Note that this option explicitly does _not_ add a `required` HTML attribute. Doing so would enable native browser validations, which are inaccessible and inconsistent with the Primer design system.
+        #   @param aria [Hash] Key/value pairs that represent Aria attributes and their values. Eg. `aria: { current: true }` becomes `aria-current="true"`.
+        #   @param data [Hash] Key/value pairs that represent data attributes and their values. Eg. `data: { foo: "bar" }` becomes `data-foo="bar"`.
+        #   @macro form_system_arguments
+
+        # @!macro [new] form_size_arguments
+        #   @param size [Symbol] The size of the field. <%= one_of(Primer::Forms::Dsl::Input::SIZE_OPTIONS) %>
+
+        # @!macro [new] form_full_width_arguments
+        #   @param full_width [Boolean] When set to `true`, the field will take up all the horizontal space allowed by its container.
+
+        # @!macro [new] form_system_arguments
+        #   @param system_arguments [Hash] A hash of attributes passed to the underlying Rails builder methods. These options may mean something special depending on the type of input, otherwise they are emitted as HTML attributes. See the [Rails documentation](https://guides.rubyonrails.org/form_helpers.html) for more information. In addition, the usual Primer utility arguments are accepted in system arguments. For example, passing `mt: 2` will add the `mt-2` class to the input. See the Primer system arguments docs for details.
+
         SPACE_DELIMITED_ARIA_ATTRIBUTES = %i[describedby].freeze
         DEFAULT_SIZE = :medium
         SIZE_MAPPINGS = {
@@ -181,7 +212,7 @@ module Primer
         end
 
         def disabled?
-          input_arguments.include?(:disabled)
+          !!input_arguments[:disabled]
         end
 
         def full_width?
@@ -241,7 +272,7 @@ module Primer
           {
             class: "FormControl-inlineValidation",
             id: validation_id,
-            hidden: valid?
+            hidden: valid? || validation_messages.empty?
           }
         end
 

data/lib/primer/forms/dsl/input_methods.rb

@@ -5,41 +5,73 @@ module Primer
     module Dsl
       # :nodoc:
       module InputMethods
+        # Used to render another form object.
+        #
+        # @param args [Array] Positional arguments passed to Rails' [`fields_for` helper](https://api.rubyonrails.org/v7.0.4/classes/ActionView/Helpers/FormHelper.html#method-i-fields_for).
+        # @param kwargs [Hash] The options accepted by the form reference input (see forms docs). Includes keyword arguments passed to Rails' [`fields_for` helper](https://api.rubyonrails.org/v7.0.4/classes/ActionView/Helpers/FormHelper.html#method-i-fields_for).
         def fields_for(*args, **kwargs, &block)
           add_input FormReferenceInput.new(*args, builder: builder, form: form, **kwargs, &block)
         end
 
+        # Adds a multi input to this form.
+        #
+        # @param options [Hash] The options accepted by the multi input (see forms docs).
+        # @param block [Proc] A block that will be yielded a reference to the input object so it can be customized.
         def multi(**options, &block)
           add_input MultiInput.new(builder: builder, form: form, **options, &block)
         end
 
+        # Adds a hidden input to this form.
+        #
+        # @param options [Hash] The options accepted by the hidden input (see forms docs).
         def hidden(**options)
           add_input HiddenInput.new(builder: builder, form: form, **options)
         end
 
+        # Adds a check box to this form.
+        #
+        # @param options [Hash] The options accepted by the check box input (see forms docs).
+        # @param block [Proc] A block that will be yielded a reference to the input object so it can be customized.
         def check_box(**options, &block)
           add_input CheckBoxInput.new(builder: builder, form: form, **options, &block)
         end
 
+        # Adds a radio button group to this form.
+        #
+        # @param options [Hash] The options accepted by the radio button group input (see forms docs).
+        # @param block [Proc] A block that will be yielded a reference to the input object so it can be customized.
         def radio_button_group(**options, &block)
           add_input RadioButtonGroupInput.new(builder: builder, form: form, **options, &block)
         end
 
+        # Adds a check box group to this form.
+        #
+        # @param options [Hash] The options accepted by the check box group input (see forms docs).
+        # @param block [Proc] A block that will be yielded a reference to the input object so it can be customized.
         def check_box_group(**options, &block)
           add_input CheckBoxGroupInput.new(builder: builder, form: form, **options, &block)
         end
 
+        # Adds a horizontal separator to the form.
         def separator
           add_input Separator.new
         end
 
         # START text input methods
 
+        # Adds a text field to this form.
+        #
+        # @param options [Hash] The options accepted by the text field input (see forms docs).
+        # @param block [Proc] A block that will be yielded a reference to the input object so it can be customized.
         def text_field(**options, &block)
           options = decorate_options(**options)
           add_input TextFieldInput.new(builder: builder, form: form, **options, &block)
         end
 
+        # Adds a text area to this form.
+        #
+        # @param options [Hash] The options accepted by the text area input (see forms docs).
+        # @param block [Proc] A block that will be yielded a reference to the input object so it can be customized.
         def text_area(**options, &block)
           options = decorate_options(**options)
           add_input TextAreaInput.new(builder: builder, form: form, **options, &block)
@@ -49,20 +81,32 @@ module Primer
 
         # START select input methods
 
+        # Adds a select list to this form.
+        #
+        # @param options [Hash] The options accepted by the select list input (see forms docs).
+        # @param block [Proc] A block that will be yielded a reference to the input object so it can be customized.
         def select_list(**options, &block)
           options = decorate_options(**options)
-          add_input SelectListInput.new(builder: builder, form: form, **options, &block)
+          add_input SelectInput.new(builder: builder, form: form, **options, &block)
         end
 
         # END select input methods
 
         # START button input methods
 
+        # Adds a submit button to this form.
+        #
+        # @param options [Hash] The options accepted by the submit button input (see forms docs).
+        # @param block [Proc] A block that will be yielded a reference to the input object so it can be customized.
         def submit(**options, &block)
           options = decorate_options(**options)
           add_input SubmitButtonInput.new(builder: builder, form: form, **options, &block)
         end
 
+        # Adds a (non-submit) button to this form.
+        #
+        # @param options [Hash] The options accepted by the button input (see forms docs).
+        # @param block [Proc] A block that will be yielded a reference to the input object so it can be customized.
         def button(**options, &block)
           options = decorate_options(**options)
           add_input ButtonInput.new(builder: builder, form: form, **options, &block)
@@ -70,16 +114,20 @@ module Primer
 
         # END button input methods
 
+        # @private
         def inputs
           @inputs ||= []
         end
 
         private
 
+        # @private
         def add_input(input)
           inputs << input
         end
 
+        # @private
+        #
         # Called before the corresponding Input class is instantiated. The return value of this method is passed
         # to the Input class's constructor.
         def decorate_options(**options)

data/lib/primer/forms/dsl/radio_button_group_input.rb

@@ -14,8 +14,6 @@ module Primer
 
           super(**system_arguments)
 
-          add_label_classes("FormControl-label", "mb-2")
-
           yield(self) if block_given?
         end
 
@@ -29,7 +27,8 @@ module Primer
 
         def radio_button(**system_arguments, &block)
           @radio_buttons << RadioButtonInput.new(
-            builder: @builder, form: @form, name: @name, **system_arguments, &block
+            builder: @builder, form: @form, name: @name, disabled: disabled?,
+            **system_arguments, &block
           )
         end
       end

data/lib/primer/forms/dsl/{select_list_input.rb → select_input.rb}

@@ -4,7 +4,7 @@ module Primer
   module Forms
     module Dsl
       # :nodoc:
-      class SelectListInput < Input
+      class SelectInput < Input
         SELECT_ARGUMENTS = %i[multiple include_blank prompt].freeze
 
         # :nodoc:
@@ -41,7 +41,7 @@ module Primer
         end
 
         def to_component
-          SelectList.new(input: self)
+          Select.new(input: self)
         end
 
         # :nocov:

data/lib/primer/forms/dsl/text_field_input.rb

@@ -23,12 +23,14 @@ module Primer
           @monospace = system_arguments.delete(:monospace)
           @auto_check_src = system_arguments.delete(:auto_check_src)
 
-          super(**system_arguments)
+          if @leading_visual
+            @leading_visual[:classes] = class_names(
+              "FormControl-input-leadingVisual",
+              @leading_visual[:classes]
+            )
+          end
 
-          add_input_classes(
-            "FormControl-input",
-            Primer::Forms::Dsl::Input::SIZE_MAPPINGS[size]
-          )
+          super(**system_arguments)
 
           add_input_data(:target, "primer-text-field.inputElement") if auto_check_src.present?
           add_input_classes("FormControl-inset") if inset?

data/lib/primer/forms/form_control.rb

@@ -12,7 +12,6 @@ module Primer
         @form_group_arguments = {
           class: class_names(
             "FormControl",
-            "flex-1",
             "width-full",
             "FormControl--fullWidth" => @input.full_width?
           )

data/lib/primer/forms/group.html.erb

@@ -1,4 +1,4 @@
-<%= content_tag_if(horizontal?, :div, class: "d-flex", style: "gap: 15px;") do %>
+<%= content_tag_if(horizontal?, :div, class: "FormControl-horizontalGroup") do %>
   <% @inputs.each do |input| %>
     <%= render(input.to_component) %>
   <% end %>

data/lib/primer/forms/multi.html.erb

@@ -1,7 +1,9 @@
-<%= render(FormControl.new(input: @input)) do %>
-  <primer-multi-input data-name="<%= @input.name %>">
-    <% @input.inputs.each do |child_input| %>
-      <%= render(child_input.to_component) %>
-    <% end %>
-  </primer-multi-input>
+<%= content_tag(:div, **@input.input_arguments) do %>
+  <%= render(FormControl.new(input: @input)) do %>
+    <primer-multi-input data-name="<%= @input.name %>">
+      <% @input.inputs.each do |child_input| %>
+        <%= render(child_input.to_component) %>
+      <% end %>
+    </primer-multi-input>
+  <% end %>
 <% end %>

data/lib/primer/forms/multi.rb

@@ -8,6 +8,8 @@ module Primer
 
       def initialize(input:)
         @input = input
+
+        Primer::Forms::Utils.classify(@input.input_arguments)
       end
     end
   end

data/lib/primer/forms/radio_button_group.html.erb

@@ -1,12 +1,17 @@
-<%= content_tag(:fieldset, hidden: @input.hidden?) do %>
-  <% if @input.label %>
-    <%= content_tag(:legend, **@input.label_arguments) do %>
-      <%= @input.label %>
+<%= content_tag(:div, **@input.input_arguments) do %>
+  <fieldset>
+    <% if @input.label %>
+      <%= content_tag(:legend, **@input.label_arguments) do %>
+        <%= @input.label %>
+      <% end %>
     <% end %>
-  <% end %>
-  <%= render(SpacingWrapper.new) do %>
-    <% @input.radio_buttons.each do |radio_button| %>
-      <%= render(radio_button.to_component) %>
+    <%= render(SpacingWrapper.new) do %>
+      <% @input.radio_buttons.each do |radio_button| %>
+        <%= render(radio_button.to_component) %>
+      <% end %>
     <% end %>
-  <% end %>
+  </fieldset>
+  <div class="mt-2">
+    <%= render(Caption.new(input: @input)) %>
+  </div>
 <% end %>

data/lib/primer/forms/radio_button_group.rb

@@ -8,6 +8,11 @@ module Primer
 
       def initialize(input:)
         @input = input
+
+        @input.add_label_classes("FormControl-label", "mb-2")
+        @input.add_input_classes("FormControl-radio-group-wrap")
+
+        Primer::Forms::Utils.classify(@input.input_arguments)
       end
     end
   end

data/lib/primer/forms/{select_list.rb → select.rb}

@@ -3,14 +3,14 @@
 module Primer
   module Forms
     # :nodoc:
-    class SelectList < BaseComponent
+    class Select < BaseComponent
       delegate :builder, :form, to: :@input
 
       def initialize(input:)
         @input = input
         @input.add_input_classes(
           "FormControl-select",
-          "FormControl--medium"
+          Primer::Forms::Dsl::Input::SIZE_MAPPINGS[@input.size]
         )
 
         @field_wrap_arguments = {

data/lib/primer/forms/spacing_wrapper.html.erb

@@ -1,3 +1,3 @@
-<div class="d-flex flex-column" style="row-gap: 15px">
+<div class="FormControl-spacingWrapper">
   <%= content %>
 </div>

data/lib/primer/forms/text_area.rb

@@ -8,7 +8,7 @@ module Primer
 
       def initialize(input:)
         @input = input
-        @input.add_input_classes("FormControl-input", "FormControl--medium")
+        @input.add_input_classes("FormControl-input", "FormControl-textarea")
 
         @field_wrap_arguments = {
           class: class_names("FormControl-input-wrap"),

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/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 = 121
+      PATCH = 123
 
       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