primer_view_components 0.0.8 → 0.0.13

data/app/components/primer/blankslate_component.html.erb

@@ -1,9 +1,9 @@
-<%= render Primer::BaseComponent.new(**@kwargs) do %>
+<%= render Primer::BaseComponent.new(**@system_arguments) do %>
   <% if @icon.present? %>
     <%= render(Primer::OcticonComponent.new(
       icon: @icon,
       size: @icon_size,
-      class: "blankslate-icon"
+      classes: "blankslate-icon"
     )) %>
   <% end %>
 

data/app/components/primer/blankslate_component.rb

@@ -1,118 +1,73 @@
 # frozen_string_literal: true
 
 module Primer
-  # Blankslates are for when there is a lack of content within a page or section. Use them as placeholders to tell users why something isn't there.
-  #
-  # ## Basic example
-  #
-  # The `Primer::BlankslateComponent` supports the following arguments to add a basic blankslate:
-  #
-  # 1. `title` (`String` optional). Text that appears in a larger bold font.
-  # 2. `description` (`String` optional). Text that appears below the title. Typically a whole sentence.
-  #
-  # ```ruby
-  # <%= render Primer::BlankslateComponent.new(
-  #   title: "Title",
-  #   description: "Description",
-  # ) %>
-  # ```
-  #
-  # ## Icon or graphic (optional)
-  #
-  # Add an `icon` to give additional context. Please refer to the [Octicons](https://primer.style/octicons/) documentation to choose an icon.
-  #
-  # ```ruby
-  # <%= render Primer::BlankslateComponent.new(
-  #   icon: "octoface",
-  #   title: "Title",
-  #   description: "Description",
-  # ) %>
-  # ```
-  #
-  # Alternatively you can also add a graphic by providing a path (`image_src`) to an image instead.Also, make sure to add an alternative description (`image_alt`). It will be used for the `alt` tag.
-  #
-  # ```ruby
-  # <%= render Primer::BlankslateComponent.new(
-  #   image_src: "file.svg",
-  #   image_alt: "Description of the image",
-  #   title: "Title",
-  #   description: "Description",
-  # ) %>
-  # ```
-  #
-  # Both icon and graphic will appear above the title.
-  #
-  #
-  # ## Custom content (optional)
-  #
-  # You can add any custom content that typically is used instead of the description:
-  #
-  # ```ruby
-  # <%= render Primer::BlankslateComponent.new(
-  #   icon: "octoface",
-  #   title: "Title",
-  # ) do %>
-  #   <p>Your custom content here</p>
-  # <% end %>
-  # ```
-  #
-  # ## Action button (optional)
-  #
-  # You can provide an action button to help users replace the blankslate. The button will appear below the description and custom content. It takes the following arguments:
-  #
-  # - `button_text` (`String` optional). The text of the button.
-  # - `button_url` (`String` optional). The URL where the user will be taken after clicking the button.
-  #
-  # ```ruby
-  # <%= render Primer::BlankslateComponent.new(
-  #   icon: "book",
-  #   title: "Welcome to the mona wiki!",
-  #   description: "Wikis provide a place in your repository to lay out the roadmap of your project, show the current status, and document software better, together.",
-  #
-  #   button_text: "Create the first page",
-  #   button_url: "https://github.com/monalisa/mona/wiki/_new",
-  # ) %>
-  # ```
-  #
-  # ## Link (optional)
-  #
-  # Add an additional link to help users learn more about a feature. The link will be shown at the very bottom:
-  #
-  # - `link_text` (`String` optional). The text of the link.
-  # - `link_url` (`String` optional). The URL where the user will be taken after clicking the link.
-  #
-  # ```ruby
-  # <%= render Primer::BlankslateComponent.new(
-  #   icon: "book",
-  #   title: "Welcome to the mona wiki!",
-  #   description: "Wikis provide a place in your repository to lay out the roadmap of your project, show the current status, and document software better, together.",
-  #   button_text: "Create the first page",
-  #   button_url: "https://github.com/monalisa/mona/wiki/_new",
-  #   link_text: "Learn more about wikis",
-  #   link_url: "https://docs.github.com/en/github/building-a-strong-community/about-wikis",
-  # ) %>
-  # ```
-  #
-  # ## Variations (optional)
-  #
-  # There are a few variations of how the Blankslate appears:
-  #
-  # - `narrow` (`Boolean` optional). Adds a maximum width.
-  # - `large` (`Boolean` optional). Increaeses the font size.
-  # - `spacious` (`Boolean` optional). Adds extra padding.
-  #
-  # ```ruby
-  # <%= render Primer::BlankslateComponent.new(
-  #   icon: "book",
-  #   title: "Welcome to the mona wiki!",
-  #   description: "Wikis provide a place in your repository to lay out the roadmap of your project, show the current status, and document software better, together.",
-  #
-  #   narrow: true,
-  #   large: true,
-  #   spacious: true,
-  # ) %>
-  # ```
+  # Use Primer::BlankslateComponent when there is a lack of content within a page or section. Use as placeholder to tell users why something isn't there.
   class BlankslateComponent < Primer::Component
+    #
+    # @example 150|Basic
+    #   <%= render Primer::BlankslateComponent.new(
+    #     title: "Title",
+    #     description: "Description",
+    #   ) %>
+    #
+    # @example 190|Icon|Add an `icon` to give additional context. Refer to the [Octicons](https://primer.style/octicons/) documentation to choose an icon.
+    #   <%= render Primer::BlankslateComponent.new(
+    #     icon: "octoface",
+    #     title: "Title",
+    #     description: "Description",
+    #   ) %>
+    #
+    # @example 150|Custom content|Pass custom content as a block in place of `description`.
+    #   <%= render Primer::BlankslateComponent.new(
+    #     title: "Title",
+    #   ) do %>
+    #     <em>Your custom content here</em>
+    #   <% end %>
+    #
+    # @example 270|Action button|Provide a button to guide users to take action from the blankslate. The button appears below the description and custom content.
+    #   <%= render Primer::BlankslateComponent.new(
+    #     icon: "book",
+    #     title: "Welcome to the mona wiki!",
+    #     description: "Wikis provide a place in your repository to lay out the roadmap of your project, show the current status, and document software better, together.",
+    #
+    #     button_text: "Create the first page",
+    #     button_url: "https://github.com/monalisa/mona/wiki/_new",
+    #   ) %>
+    #
+    # @example 225|Link|Add an additional link to help users learn more about a feature. The link will be shown at the very bottom:
+    #   <%= render Primer::BlankslateComponent.new(
+    #     icon: "book",
+    #     title: "Welcome to the mona wiki!",
+    #     description: "Wikis provide a place in your repository to lay out the roadmap of your project, show the current status, and document software better, together.",
+    #     link_text: "Learn more about wikis",
+    #     link_url: "https://docs.github.com/en/github/building-a-strong-community/about-wikis",
+    #   ) %>
+    #
+    # @example 340|Variations|There are a few variations of how the Blankslate appears: `narrow` adds a maximum width, `large` increases the font size, and `spacious` adds extra padding.
+    #   <%= render Primer::BlankslateComponent.new(
+    #     icon: "book",
+    #     title: "Welcome to the mona wiki!",
+    #     description: "Wikis provide a place in your repository to lay out the roadmap of your project, show the current status, and document software better, together.",
+    #     narrow: true,
+    #     large: true,
+    #     spacious: true,
+    #   ) %>
+    #
+    # @param title [String] Text that appears in a larger bold font.
+    # @param title_tag [Symbol] HTML tag to use for title.
+    # @param icon [String] Octicon icon to use at top of component.
+    # @param icon_size [Symbol] <%= one_of(Primer::OcticonComponent::SIZE_MAPPINGS) %>
+    # @param image_src [String] Image to display.
+    # @param image_alt [String] Alt text for image.
+    # @param description [String] Text that appears below the title. Typically a whole sentence.
+    # @param button_text [String] The text of the button.
+    # @param button_url [String] The URL where the user will be taken after clicking the button.
+    # @param button_classes [String] Classes to apply to action button
+    # @param link_text [String] The text of the link.
+    # @param link_url [String] The URL where the user will be taken after clicking the link.
+    # @param narrow [Boolean] Adds a maximum width.
+    # @param large [Boolean] Increases the font size.
+    # @param spacious [Boolean] Adds extra padding.
     def initialize(
       title: "",
       title_tag: :h3,
@@ -132,12 +87,12 @@ module Primer
       large: false,
       spacious: false,
 
-      **kwargs
+      **system_arguments
     )
-      @kwargs = kwargs
-      @kwargs[:tag] ||= :div
-      @kwargs[:classes] = class_names(
-        @kwargs[:classes],
+      @system_arguments = system_arguments
+      @system_arguments[:tag] ||= :div
+      @system_arguments[:classes] = class_names(
+        @system_arguments[:classes],
         "blankslate",
         "blankslate-narrow": narrow,
         "blankslate-large": large,

data/app/components/primer/border_box_component.html.erb

@@ -1,25 +1,25 @@
-<%= render Primer::BaseComponent.new(**@kwargs) do %>
+<%= render Primer::BaseComponent.new(**@system_arguments) do %>
   <% if header %>
-    <%= render Primer::BaseComponent.new(**header.kwargs) do %>
+    <%= render Primer::BaseComponent.new(**header.system_arguments) do %>
       <%= header.content %>
     <% end %>
   <% end %>
   <% if body %>
-    <%= render Primer::BaseComponent.new(**body.kwargs) do %>
+    <%= render Primer::BaseComponent.new(**body.system_arguments) do %>
       <%= body.content %>
     <% end %>
   <% end %>
   <% if rows.any? %>
     <ul>
       <% rows.each do |row| %>
-        <%= render Primer::BaseComponent.new(**row.kwargs) do %>
+        <%= render Primer::BaseComponent.new(**row.system_arguments) do %>
           <%= row.content %>
         <% end %>
       <% end %>
     </ul>
   <% end %>
   <% if footer %>
-    <%= render Primer::BaseComponent.new(**footer.kwargs) do %>
+    <%= render Primer::BaseComponent.new(**footer.system_arguments) do %>
       <%= footer.content %>
     <% end %>
   <% end %>

data/app/components/primer/border_box_component.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 module Primer
+  # BorderBox is a Box component with a border.
   class BorderBoxComponent < Primer::Component
     include ViewComponent::Slotable
 
@@ -9,12 +10,23 @@ module Primer
     with_slot :footer, class_name: "Footer"
     with_slot :row, collection: true, class_name: "Row"
 
-    def initialize(**kwargs)
-      @kwargs = kwargs
-      @kwargs[:tag] = :div
-      @kwargs[:classes] = class_names(
+    # @example 350|Header, body, rows, and footer
+    #   <%= render(Primer::BorderBoxComponent.new) do |component|
+    #     component.slot(:header) { "Header" }
+    #     component.slot(:body) { "Body" }
+    #     component.slot(:row) { "Row one" }
+    #     component.slot(:row) { "Row two" }
+    #     component.slot(:row) { "Row three" }
+    #     component.slot(:footer) { "Footer" }
+    #   end %>
+    #
+    # @param system_arguments [Hash] <%= link_to_system_arguments_docs %>
+    def initialize(**system_arguments)
+      @system_arguments = system_arguments
+      @system_arguments[:tag] = :div
+      @system_arguments[:classes] = class_names(
         "Box",
-        kwargs[:classes]
+        system_arguments[:classes]
       )
     end
 
@@ -23,53 +35,53 @@ module Primer
     end
 
     class Header < Primer::Slot
-
-      attr_reader :kwargs
-      def initialize(**kwargs)
-        @kwargs = kwargs
-        @kwargs[:tag] = :div
-        @kwargs[:classes] = class_names(
+      attr_reader :system_arguments
+      # @param system_arguments [Hash] <%= link_to_system_arguments_docs %>
+      def initialize(**system_arguments)
+        @system_arguments = system_arguments
+        @system_arguments[:tag] = :div
+        @system_arguments[:classes] = class_names(
           "Box-header",
-          kwargs[:classes]
+          system_arguments[:classes]
         )
       end
     end
 
     class Body < Primer::Slot
-
-      attr_reader :kwargs
-      def initialize(**kwargs)
-        @kwargs = kwargs
-        @kwargs[:tag] = :div
-        @kwargs[:classes] = class_names(
+      attr_reader :system_arguments
+      # @param system_arguments [Hash] <%= link_to_system_arguments_docs %>
+      def initialize(**system_arguments)
+        @system_arguments = system_arguments
+        @system_arguments[:tag] = :div
+        @system_arguments[:classes] = class_names(
           "Box-body",
-          kwargs[:classes]
+          system_arguments[:classes]
         )
       end
     end
 
     class Footer < Primer::Slot
-
-      attr_reader :kwargs
-      def initialize(**kwargs)
-        @kwargs = kwargs
-        @kwargs[:tag] = :div
-        @kwargs[:classes] = class_names(
+      attr_reader :system_arguments
+      # @param system_arguments [Hash] <%= link_to_system_arguments_docs %>
+      def initialize(**system_arguments)
+        @system_arguments = system_arguments
+        @system_arguments[:tag] = :div
+        @system_arguments[:classes] = class_names(
           "Box-footer",
-          kwargs[:classes]
+          system_arguments[:classes]
         )
       end
     end
 
     class Row < Primer::Slot
-
-      attr_reader :kwargs
-      def initialize(**kwargs)
-        @kwargs = kwargs
-        @kwargs[:tag] = :li
-        @kwargs[:classes] = class_names(
+      attr_reader :system_arguments
+      # @param system_arguments [Hash] <%= link_to_system_arguments_docs %>
+      def initialize(**system_arguments)
+        @system_arguments = system_arguments
+        @system_arguments[:tag] = :li
+        @system_arguments[:classes] = class_names(
           "Box-row",
-          kwargs[:classes]
+          system_arguments[:classes]
         )
       end
     end

data/app/components/primer/box_component.rb

@@ -1,14 +1,16 @@
 # frozen_string_literal: true
 
 module Primer
+  # A basic wrapper component for most layout related needs.
   class BoxComponent < Primer::Component
-    def initialize(**kwargs)
-      @kwargs = kwargs
-      @kwargs[:tag] = :div
+    # @param system_arguments [Hash] <%= link_to_system_arguments_docs %>
+    def initialize(**system_arguments)
+      @system_arguments = system_arguments
+      @system_arguments[:tag] = :div
     end
 
     def call
-      render(Primer::BaseComponent.new(**@kwargs)) { content }
+      render(Primer::BaseComponent.new(**@system_arguments)) { content }
     end
   end
 end

data/app/components/primer/breadcrumb_component.html.erb

@@ -1,8 +1,8 @@
-<%= render Primer::BaseComponent.new(**@kwargs) do %>
+<%= render Primer::BaseComponent.new(**@system_arguments) do %>
   <ol>
     <% items.each do |item| %>
       <%# The <li> and <a> need to be on the same line to prevent unwanted whitespace %>
-      <%= render Primer::BaseComponent.new(**item.kwargs) do %><%- if item.href.present? %><a href="<%= item.href %>"><%= item.content %></a><%- else %><%= item.content %><%- end %><%- end %>
+      <%= render Primer::BaseComponent.new(**item.system_arguments) do %><%- if item.href.present? %><a href="<%= item.href %>"><%= item.content %></a><%- else %><%= item.content %><%- end %><%- end %>
     <% end %>
   </ol>
 <% end %>

data/app/components/primer/breadcrumb_component.rb

@@ -1,51 +1,44 @@
 # frozen_string_literal: true
 
-##
-# Breadcrumbs are used to display page hierarchy within a section of the site. All of the items in the breadcrumb "trail" are links except for the final item which is a plain string indicating the current page.
-#
-# ## Example
-#
-# The `Primer::BreadcrumbComponent` uses the [Slots API](https://github.com/github/view_component#slots-experimental) and at least one slot is required for the component to render. Each slot can accept the following parameters:
-#
-# 1. `href` (string). The URL to link to.
-# 2. `selected` (boolean, default=false). Flag indicating whether or not the item is selected and not rendered as a link.
-#
-# Note that if if both `href` and `selected: true` are passed in, `href` will be ignored and the item will not be rendered as a link.
-#
-# ```ruby
-# <%= render(Primer::BreadcrumbComponent.new) do |component| %>
-#   <% component.slot(:item, href: "/") do %>Home<% end %>
-#   <% component.slot(:item, href: "/about") do %>About<% end %>
-#   <% component.slot(:item, selected: true) do %>Team<% end %>
-# <% end %>
-# ```
-##
 module Primer
+  # Use breadcrumbs to display page hierarchy within a section of the site. All of the items in the breadcrumb "trail" are links except for the final item, which is a plain string indicating the current page.
   class BreadcrumbComponent < Primer::Component
     include ViewComponent::Slotable
 
     with_slot :item, collection: true, class_name: "BreadcrumbItem"
 
-    def initialize(**kwargs)
-      @kwargs = kwargs
-      @kwargs[:tag] = :nav
-      @kwargs[:aria] = { label: "Breadcrumb" }
+    # @example 40|Basic
+    #   <%= render(Primer::BreadcrumbComponent.new) do |component| %>
+    #     <% component.slot(:item, href: "/") do %>Home<% end %>
+    #     <% component.slot(:item, href: "/about") do %>About<% end %>
+    #     <% component.slot(:item, selected: true) do %>Team<% end %>
+    #   <% end %>
+    #
+    # @param system_arguments [Hash] <%= link_to_system_arguments_docs %>
+    def initialize(**system_arguments)
+      @system_arguments = system_arguments
+      @system_arguments[:tag] = :nav
+      @system_arguments[:aria] = { label: "Breadcrumb" }
     end
 
     def render?
       items.any?
     end
 
+    # _Note: if both `href` and `selected: true` are passed in, `href` will be ignored and the item will not be rendered as a link._
     class BreadcrumbItem < Primer::Slot
-      attr_reader :href, :kwargs
+      attr_reader :href, :system_arguments
 
-      def initialize(href: nil, selected: false, **kwargs)
-        @href, @kwargs = href, kwargs
+      # @param href [String] The URL to link to.
+      # @param selected [Boolean] Whether or not the item is selected and not rendered as a link.
+      # @param system_arguments [Hash] <%= link_to_system_arguments_docs %>
+      def initialize(href: nil, selected: false, **system_arguments)
+        @href, @system_arguments = href, system_arguments
 
         @href = nil if selected
-        @kwargs[:tag] = :li
-        @kwargs[:"aria-current"] = "page" if selected
-        @kwargs[:classes] = "breadcrumb-item #{@kwargs[:classes]}"
+        @system_arguments[:tag] = :li
+        @system_arguments[:"aria-current"] = "page" if selected
+        @system_arguments[:classes] = "breadcrumb-item #{@system_arguments[:classes]}"
       end
     end
   end