primer_view_components 0.8.0 → 0.10.0

data/app/components/primer/beta/nav_list.rb

@@ -0,0 +1,212 @@
+# frozen_string_literal: true
+
+module Primer
+  module Beta
+    # `NavList` provides a simple way to render side navigation, i.e. navigation
+    # that appears to the left or right side of some main content. Each group in a
+    # nav list is a list of links.
+    #
+    # Nav list groups can contain sub items. Rather than navigating to a URL, groups
+    # with sub items expand and collapse on click. To indicate this functionality, the
+    # group will automatically render with a trailing chevron icon that changes direction
+    # when the group expands and collapses.
+    #
+    # Nav list items appear visually active when selected. Each nav item must have one
+    # or more ID values that determine which item will appear selected. Use the
+    # `selected_item_id` argument to select the appropriate item.
+    class NavList < Primer::Component
+      status :beta
+      audited_at "2023-07-10"
+
+      # @private
+      def self.custom_element_name
+        "nav-list"
+      end
+
+      # The heading for the list at large. Accepts the arguments accepted by <%= link_to_component(Primer::Beta::NavList::Heading) %>.
+      #
+      renders_one :heading, Primer::Beta::NavList::Heading
+
+      # @!parse
+      #   # Adds an item to the list.
+      #   #
+      #   # @param component_klass [Class] The class to use instead of the default <%= link_to_component(Primer::Beta::NavList::Item) %>
+      #   # @param system_arguments [Hash] These arguments are forwarded to <%= link_to_component(Primer::Beta::NavList::Item) %>, or whatever class is passed as the `component_klass` argument.
+      #   def with_item(component_klass: Primer::Beta::NavList::Item, **system_arguments, &block)
+      #   end
+
+      # @!parse
+      #   # Adds an avatar item to the list. Avatar items are a convenient way to accessibly add an item with a leading avatar image.
+      #   #
+      #   # @param src [String] The source url of the avatar image.
+      #   # @param username [String] The username associated with the avatar.
+      #   # @param full_name [String] Optional. The user's full name.
+      #   # @param full_name_scheme [Symbol] Optional. How to display the user's full name. <%= one_of(Primer::Alpha::ActionList::Item::DESCRIPTION_SCHEME_OPTIONS) %>
+      #   # @param component_klass [Class] The class to use instead of the default <%= link_to_component(Primer::Beta::NavList::Item) %>
+      #   # @param avatar_arguments [Hash] Optional. The arguments accepted by <%= link_to_component(Primer::Beta::Avatar) %>
+      #   # @param system_arguments [Hash] These arguments are forwarded to <%= link_to_component(Primer::Beta::NavList::Item) %>, or whatever class is passed as the `component_klass` argument.
+      #   def with_avatar_item(src:, username:, full_name: nil, full_name_scheme: Primer::Alpha::ActionList::Item::DEFAULT_DESCRIPTION_SCHEME, component_klass: Primer::Beta::NavList::Item, avatar_arguments: {}, **system_arguments, &block)
+      #   end
+
+      # @!parse
+      #   # Adds a group to the list. A group is a list of links and a (required) heading.
+      #   #
+      #   # @param system_arguments [Hash] The arguments accepted by <%= link_to_component(Primer::Beta::NavList::Group) %>.
+      #   def with_group(**system_arguments, &block)
+      #   end
+
+      # @!parse
+      #   # Adds a divider to the list. Dividers visually separate items and groups.
+      #   #
+      #   # @param system_arguments [Hash] The arguments accepted by <%= link_to_component(Primer::Beta::NavList::Divider) %>.
+      #   def with_divider(**system_arguments, &block)
+      #   end
+
+      # Items. Items can be individual items, dividers, or groups. See the documentation for `#with_item`, `#with_divider`, and `#with_group` respectively for more information.
+      #
+      renders_many :items, types: {
+        item: {
+          renders: lambda { |**system_arguments, &block|
+            build_item(**system_arguments, &block)
+          },
+
+          as: :item
+        },
+
+        avatar_item: {
+          renders: lambda { |**system_arguments|
+            build_avatar_item(**system_arguments)
+          },
+
+          as: :avatar_item
+        },
+
+        divider: {
+          renders: Primer::Beta::NavList::Divider,
+          as: :divider
+        },
+
+        group: {
+          renders: lambda { |**system_arguments, &block|
+            Primer::Beta::NavList::Group.new(
+              selected_item_id: @selected_item_id,
+              **system_arguments,
+              &block
+            )
+          },
+
+          as: :group
+        }
+      }
+
+      # @param selected_item_id [Symbol] The ID of the currently selected item. The default is `nil`, meaning no item is selected.
+      # @param system_arguments [Hash] <%= link_to_system_arguments_docs %>
+      def initialize(selected_item_id: nil, **system_arguments)
+        @system_arguments = system_arguments
+        @selected_item_id = selected_item_id
+      end
+
+      # Builds a new item but does not add it to the list. Use this method
+      # instead of the `#with_item` slot if you need to render an item outside
+      # the context of a list, eg. if rendering additional items to append to
+      # an existing list, perhaps via a separate HTTP request.
+      #
+      # @param component_klass [Class] The class to use instead of the default <%= link_to_component(Primer::Beta::NavList::Item) %>
+      # @param system_arguments [Hash] These arguments are forwarded to <%= link_to_component(Primer::Beta::NavList::Item) %>, or whatever class is passed as the `component_klass` argument.
+      def build_item(component_klass: Primer::Beta::NavList::Item, **system_arguments, &block)
+        component_klass.new(
+          list: top_level_group,
+          selected_item_id: @selected_item_id,
+          **system_arguments,
+          &block
+        )
+      end
+
+      # Builds a new avatar item but does not add it to the list. Avatar items
+      # are a convenient way to accessibly add an item with a leading avatar
+      # image. Use this method instead of the `#with_avatar_item` slot if you
+      # need to render an avatar item outside the context of a list, eg. if
+      # rendering additional items to append to an existing list, perhaps via
+      # a separate HTTP request.
+      #
+      # @param src [String] The source url of the avatar image.
+      # @param username [String] The username associated with the avatar.
+      # @param full_name [String] Optional. The user's full name.
+      # @param full_name_scheme [Symbol] Optional. How to display the user's full name. <%= one_of(Primer::Alpha::ActionList::Item::DESCRIPTION_SCHEME_OPTIONS) %>
+      # @param component_klass [Class] The class to use instead of the default <%= link_to_component(Primer::Beta::NavList::Item) %>
+      # @param avatar_arguments [Hash] Optional. The arguments accepted by <%= link_to_component(Primer::Beta::Avatar) %>
+      # @param system_arguments [Hash] These arguments are forwarded to <%= link_to_component(Primer::Beta::NavList::Item) %>, or whatever class is passed as the `component_klass` argument.
+      def build_avatar_item(src:, username:, full_name: nil, full_name_scheme: Primer::Alpha::ActionList::Item::DEFAULT_DESCRIPTION_SCHEME, component_klass: Primer::Beta::NavList::Item, avatar_arguments: {}, **system_arguments)
+        component_klass.new(
+          list: top_level_group,
+          selected_item_id: @selected_item_id,
+          label: username,
+          description_scheme: full_name_scheme,
+          **system_arguments
+        ).tap do |item|
+          item.with_leading_visual_raw_content do
+            # no alt text necessary
+            item.render(Primer::Beta::Avatar.new(src: src, **avatar_arguments, role: :presentation, size: 16))
+          end
+
+          item.with_description_content(full_name) if full_name
+        end
+      end
+
+      private
+
+      def before_render
+        if heading?
+          raise ArgumentError, "Please don't set an aria-label if a heading is provided" if aria(:label, @system_arguments)
+
+          @system_arguments[:aria] = merge_aria(
+            @system_arguments,
+            { aria: { labelledby: heading.id } }
+          )
+        else
+          raise ArgumentError, "When no heading is provided, an aria-label must be given" unless aria(:label, @system_arguments)
+        end
+      end
+
+      # Lists that contain top-level items (i.e. items outside of a group) should be wrapped in a <ul>
+      def render_outer_list?
+        items.any? { |item| !group?(item) }
+      end
+
+      def render_divider_between?(item1, item2)
+        return false if either_is_divider?(item1, item2)
+
+        both_are_groups?(item1, item2) || heterogeneous?(item1, item2)
+      end
+
+      def both_are_groups?(item1, item2)
+        group?(item1) && group?(item2)
+      end
+
+      def heterogeneous?(item1, item2)
+        kind(item1) != kind(item2)
+      end
+
+      def either_is_divider?(item1, item2)
+        divider?(item1) || divider?(item2)
+      end
+
+      def group?(item)
+        kind(item) == :group
+      end
+
+      def divider?(item)
+        kind(item) == :divider
+      end
+
+      def kind(item)
+        item.respond_to?(:kind) ? item.kind : :item
+      end
+
+      def top_level_group
+        # dummy group for the list: argument in the item slot above
+        @top_level_group ||= Primer::Beta::NavList::Group.new(selected_item_id: @selected_item_id)
+      end
+    end
+  end
+end

data/app/components/primer/beta/spinner.html.erb

@@ -1,4 +1,4 @@
 <%= render Primer::BaseComponent.new(**@system_arguments) do %>
-  <circle cx="8" cy="8" r="7" stroke="currentColor" stroke-opacity="0.25" stroke-width="2" vector-effect="non-scaling-stroke" />
+  <circle cx="8" cy="8" r="7" stroke="currentColor" stroke-opacity="0.25" stroke-width="2" vector-effect="non-scaling-stroke" fill="none" />
   <path d="M15 8a7.002 7.002 0 00-7-7" stroke="currentColor" stroke-width="2" stroke-linecap="round" vector-effect="non-scaling-stroke" />
 <% end %>

data/app/components/primer/focus_group.js

@@ -11,7 +11,8 @@ var __classPrivateFieldGet = (this && this.__classPrivateFieldGet) || function (
 };
 var _FocusGroupElement_instances, _FocusGroupElement_abortController, _FocusGroupElement_items_get;
 import '@oddbird/popover-polyfill';
-const menuItemSelector = '[role="menuitem"],[role="menuitemcheckbox"],[role="menuitemradio"]';
+const validSelectors = ['[role="menuitem"]', '[role="menuitemcheckbox"]', '[role="menuitemradio"]'];
+const menuItemSelector = validSelectors.map(selector => `:not([hidden]) > ${selector}`).join(', ');
 const getMnemonicFor = (item) => { var _a; return (_a = item.textContent) === null || _a === void 0 ? void 0 : _a.trim()[0].toLowerCase(); };
 const printable = /^\S$/;
 export default class FocusGroupElement extends HTMLElement {

data/app/components/primer/focus_group.ts

@@ -1,6 +1,7 @@
 import '@oddbird/popover-polyfill'
 
-const menuItemSelector = '[role="menuitem"],[role="menuitemcheckbox"],[role="menuitemradio"]'
+const validSelectors = ['[role="menuitem"]', '[role="menuitemcheckbox"]', '[role="menuitemradio"]']
+const menuItemSelector = validSelectors.map(selector => `:not([hidden]) > ${selector}`).join(', ')
 
 const getMnemonicFor = (item: Element) => item.textContent?.trim()[0].toLowerCase()
 

data/app/components/primer/primer.d.ts

@@ -6,7 +6,7 @@ import './anchored_position';
 import './focus_group';
 import './alpha/image_crop';
 import './alpha/modal_dialog';
-import './alpha/nav_list';
+import './beta/nav_list';
 import './alpha/segmented_control';
 import './alpha/toggle_switch';
 import './alpha/tool_tip';

data/app/components/primer/primer.js

@@ -6,7 +6,7 @@ import './anchored_position';
 import './focus_group';
 import './alpha/image_crop';
 import './alpha/modal_dialog';
-import './alpha/nav_list';
+import './beta/nav_list';
 import './alpha/segmented_control';
 import './alpha/toggle_switch';
 import './alpha/tool_tip';

data/app/components/primer/primer.ts

@@ -6,7 +6,7 @@ import './anchored_position'
 import './focus_group'
 import './alpha/image_crop'
 import './alpha/modal_dialog'
-import './alpha/nav_list'
+import './beta/nav_list'
 import './alpha/segmented_control'
 import './alpha/toggle_switch'
 import './alpha/tool_tip'

data/app/helpers/primer/form_helper.rb

@@ -19,5 +19,15 @@ module Primer
         &block
       )
     end
+
+    def inline_form(*args, &block)
+      Primer::Forms.inline_form(*args, &block)
+    end
+
+    def render_inline_form(*args, &block)
+      # rubocop:disable GitHub/RailsViewRenderLiteral
+      render(inline_form(*args, &block))
+      # rubocop:enable GitHub/RailsViewRenderLiteral
+    end
   end
 end

data/lib/primer/deprecations.yml

@@ -5,6 +5,26 @@
 # See 'docs/contributors/deprecations.md' for information on configuration options.
 
 deprecations:
+  - component: "Primer::Alpha::NavList::Divider"
+    autocorrect: true
+    replacement: "Primer::Beta::NavList::Divider"
+
+  - component: "Primer::Alpha::NavList::Item"
+    autocorrect: true
+    replacement: "Primer::Beta::NavList::Item"
+
+  - component: "Primer::Alpha::NavList::Heading"
+    autocorrect: true
+    replacement: "Primer::Beta::NavList::Heading"
+
+  - component: "Primer::Alpha::NavList::Group"
+    autocorrect: true
+    replacement: "Primer::Beta::NavList::Group"
+
+  - component: "Primer::Alpha::NavList"
+    autocorrect: true
+    replacement: "Primer::Beta::NavList"
+
   - component: "Primer::Alpha::AutoComplete"
     autocorrect: true
     replacement: "Primer::Beta::AutoComplete"

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

@@ -11,6 +11,9 @@
       <% end %>
     <% end %>
   </fieldset>
+  <div class="mt-2">
+    <%= render(ValidationMessage.new(input: @input)) %>
+  </div>
   <div class="mt-2">
     <%= render(Caption.new(input: @input)) %>
   </div>

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

@@ -5,7 +5,7 @@ module Primer
     module Dsl
       # :nodoc:
       class CheckBoxGroupInput < Input
-        attr_reader :label, :check_boxes
+        attr_reader :name, :label, :check_boxes
 
         def initialize(name: nil, label: nil, **system_arguments)
           @name = name
@@ -21,10 +21,6 @@ module Primer
           CheckBoxGroup.new(input: self)
         end
 
-        def name
-          nil
-        end
-
         def type
           :check_box_group
         end

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

@@ -26,6 +26,11 @@ module Primer
           yield(self) if block_given?
         end
 
+        # check boxes cannot be invalid, as both checked and unchecked are valid states
+        def valid?
+          true
+        end
+
         def to_component
           CheckBox.new(input: self)
         end

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

@@ -17,6 +17,11 @@ module Primer
           yield(self) if block_given?
         end
 
+        # radio buttons cannot be invalid, as both selected and unselected are valid states
+        def valid?
+          true
+        end
+
         def to_component
           RadioButton.new(input: self)
         end

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

@@ -9,10 +9,7 @@
       <% end %>
     <% end %>
     <%= content %>
-    <%= content_tag(:div, **@input.validation_arguments) do %>
-      <span class="FormControl-inlineValidation--visual"><%= render(Primer::Beta::Octicon.new(icon: :"alert-fill", size: :xsmall, aria: { hidden: true })) %></span>
-      <%= content_tag(:span, @input.invalid? ? @input.validation_messages.first : "", **@input.validation_message_arguments) %>
-    <% end %>
+    <%= render(ValidationMessage.new(input: @input)) %>
     <%= render(Caption.new(input: @input)) %>
   <% end %>
 <% else %>

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

@@ -11,6 +11,9 @@
       <% end %>
     <% end %>
   </fieldset>
+  <div class="mt-2">
+    <%= render(ValidationMessage.new(input: @input)) %>
+  </div>
   <div class="mt-2">
     <%= render(Caption.new(input: @input)) %>
   </div>

data/lib/primer/forms/utils.rb

@@ -15,6 +15,8 @@ module Primer
       # conventions, so it should work ok. Zeitwerk also has this information but lacks a
       # public API to map constants to source files.
       def const_source_location(class_name)
+        return nil unless class_name
+
         # NOTE: underscore respects namespacing, i.e. will convert Foo::Bar to foo/bar.
         class_path = "#{class_name.underscore}.rb"
 

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

@@ -0,0 +1,4 @@
+<%= content_tag(:div, **@input.validation_arguments) do %>
+  <span class="FormControl-inlineValidation--visual"><%= render(Primer::Beta::Octicon.new(icon: :"alert-fill", size: :xsmall, aria: { hidden: true })) %></span>
+  <%= content_tag(:span, @input.invalid? ? @input.validation_messages.first : "", **@input.validation_message_arguments) %>
+<% end %>

data/lib/primer/forms/validation_message.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module Primer
+  module Forms
+    # :nodoc:
+    class ValidationMessage < BaseComponent
+      attr_reader :input
+
+      def initialize(input:)
+        @input = input
+      end
+    end
+  end
+end

data/lib/primer/forms.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module Primer
+  # :nodoc:
+  module Forms
+    def self.inline_form(builder, base = nil, &block)
+      base ||= defined?(ApplicationForm) ? ApplicationForm : Primer::Forms::Base
+
+      klass = Class.new(base) do
+        form(&block)
+      end
+
+      klass.new(builder)
+    end
+  end
+end

data/lib/primer/view_components/linters/migrations/iconbutton_component.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module RuboCop
+  module Cop
+    module Migrations
+      # Lint and autocorrect deprecated IconButton
+      class IconButtonComponent < RuboCop::Cop::Cop
+        INVALID_MESSAGE = <<~STR
+          `Primer::IconButton` is deprecated. Please use `Primer::Beta::IconButton` instead.
+        STR
+
+        def_node_matcher :icon_button, <<~PATTERN
+          (send $(const (const nil? :Primer) :IconButton) :new ...)
+        PATTERN
+
+        def_node_matcher :hash_with_box_value?, <<~PATTERN
+          (hash ... (pair (sym :box) (...)) ... )
+        PATTERN
+
+        def on_send(node)
+          return unless icon_button(node)
+
+          add_offense(node, message: INVALID_MESSAGE)
+        end
+
+        def autocorrect(node)
+          return if hash_with_box_value?(node.arguments.first)
+
+          lambda do |corrector|
+            corrector.replace(icon_button(node), "Primer::Beta::IconButton")
+          end
+        end
+      end
+    end
+  end
+  end

data/lib/primer/view_components/version.rb

@@ -5,7 +5,7 @@ module Primer
   module ViewComponents
     module VERSION
       MAJOR = 0
-      MINOR = 8
+      MINOR = 10
       PATCH = 0
 
       STRING = [MAJOR, MINOR, PATCH].join(".")

data/lib/primer/yard/component_manifest.rb

@@ -73,6 +73,10 @@ module Primer
         Primer::Alpha::NavList::Item => { js: true, examples: false },
         Primer::Alpha::NavList::Group => { js: true, examples: false },
 
+        Primer::Beta::NavList => { js: true },
+        Primer::Beta::NavList::Item => { js: true, examples: false },
+        Primer::Beta::NavList::Group => { js: true, examples: false },
+
         # ActionList is a base component that should not be used by itself, and thus
         # does not have examples of its own
         Primer::Alpha::ActionList => { js: true, examples: false },

data/previews/primer/alpha/check_box_group_preview.rb

@@ -9,17 +9,20 @@ module Primer
       # @param name text
       # @param label text
       # @param caption text
+      # @param validation_message text
       # @param disabled toggle
       def playground(
         name: "my-check-group",
         label: "I would go into battle with:",
         caption: "Qa'pla!",
+        validation_message: nil,
         disabled: false
       )
         system_arguments = {
           name: name,
           label: label,
           caption: caption,
+          validation_message: validation_message,
           disabled: disabled
         }
 
@@ -41,6 +44,16 @@ module Primer
         end
       end
 
+      # @label Invalid
+      def invalid
+        render(Primer::Alpha::CheckBoxGroup.new(validation_message: "Please choose at least one", name: "my-check-group", label: "I would go into battle with:")) do |component|
+          component.check_box(label: "Jean-Luc Picard", value: "picard4")
+          component.check_box(label: "Hikaru Sulu", value: "sulu4")
+          component.check_box(label: "Kathryn Janeway", value: "janeway4")
+          component.check_box(label: "Benjamin Sisko", value: "sisko4")
+        end
+      end
+
       # @!group Options
       # @snapshot
       #

data/previews/primer/alpha/dialog_preview/with_header.html.erb

@@ -0,0 +1,5 @@
+<%= render(Primer::Alpha::Dialog.new(id: "my-dialog", title: title, subtitle: subtitle)) do |d| %>
+  <% d.with_show_button { button_text } %>
+  <% d.with_body { "Content" } %>
+  <% d.with_header(show_divider: show_divider, variant: header_variant) %>
+<% end %>

data/previews/primer/alpha/dialog_preview.rb

@@ -60,6 +60,23 @@ module Primer
         end
       end
 
+      # @label With Header
+      #
+      # @param title [String] text
+      # @param subtitle [String] text
+      # @param header_variant [Symbol] select [medium, large]
+      # @param button_text [String] text
+      # @param show_divider [Boolean] toggle
+      def with_header(title: "Test Dialog", subtitle: nil, header_variant: :medium, button_text: "Show Dialog", show_divider: true)
+        render_with_template(locals: {
+                               title: title,
+                               subtitle: subtitle,
+                               header_variant: header_variant,
+                               button_text: button_text,
+                               show_divider: show_divider
+                             })
+      end
+
       # @label With Footer
       #
       # @param title [String] text

data/previews/primer/alpha/overlay_preview/in_an_action_menu.html.erb

@@ -0,0 +1,13 @@
+<%= render(Primer::Alpha::ActionMenu.new()) do |menu| %>
+  <% menu.with_show_button { "Menu" } %>
+  <% menu.with_item(label: "Open Overlay", content_arguments: { id: "overlay-show-my-overlay", popovertarget: "my-overlay" }) %>
+<% end %>
+<%= render(Primer::Alpha::Overlay.new(
+  id: "my-overlay",
+  title: "An overlay",
+  role: :dialog,
+  popover: "manual",
+)) do |d| %>
+  <% d.with_header(title: "An overlay") %>
+  <% d.with_body { "This is an overlay" } %>
+<% end %>

data/previews/primer/alpha/overlay_preview.rb

@@ -164,6 +164,11 @@ module Primer
                              })
       end
 
+      # @label In an ActionMenu
+      def in_an_action_menu
+        render_with_template(locals: {})
+      end
+
       # @label Dialog with header and footer
       #
       def dialog_with_header_footer

data/previews/primer/alpha/radio_button_group_preview.rb

@@ -9,17 +9,20 @@ module Primer
       # @param name text
       # @param label text
       # @param caption text
+      # @param validation_message text
       # @param disabled toggle
       def playground(
         name: "my-radio-group",
         label: "Question: what kind of bear is best?",
         caption: "There are basically two schools of thought",
+        validation_message: nil,
         disabled: false
       )
         system_arguments = {
           name: name,
           label: label,
           caption: caption,
+          validation_message: validation_message,
           disabled: disabled
         }
 
@@ -40,6 +43,16 @@ module Primer
         end
       end
 
+      # @label Invalid
+      # @snapshot
+      def invalid
+        render(Primer::Alpha::RadioButtonGroup.new(validation_message: "Please select an option", name: "my-radio-group", label: "Question: what kind of bear is best?")) do |component|
+          component.radio_button(label: "Bears", value: "bears")
+          component.radio_button(label: "Beets", value: "beets")
+          component.radio_button(label: "Battlestar Galactica", value: "bsg")
+        end
+      end
+
       # @!group Options
       #
       # @label With caption

data/previews/primer/alpha/radio_button_preview.rb

@@ -51,7 +51,7 @@ module Primer
       # @label Checked
       # @snapshot
       def checked
-        render(Primer::Alpha::RadioButton.new(name: "my-radio-button", label: "Battlestar Galactica", value: "bsg2", checked: true ))
+        render(Primer::Alpha::RadioButton.new(name: "my-radio-button", label: "Battlestar Galactica", value: "bsg2", checked: true))
       end
 
       # @label Visually hidden label