primer_view_components 0.0.10 → 0.0.15

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

data/app/components/primer/button_component.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 module Primer
+  # Use buttons for actions (e.g. in forms). Use links for destinations, or moving from one page to another.
   class ButtonComponent < Primer::Component
     DEFAULT_BUTTON_TYPE = :default
     BUTTON_TYPE_MAPPINGS = {
@@ -25,26 +26,42 @@ module Primer
     DEFAULT_TYPE = :button
     TYPE_OPTIONS = [DEFAULT_TYPE, :reset, :submit].freeze
 
+    # @example 50|Button types
+    #   <%= render(Primer::ButtonComponent.new) { "Default" } %>
+    #   <%= render(Primer::ButtonComponent.new(button_type: :primary)) { "Primary" } %>
+    #   <%= render(Primer::ButtonComponent.new(button_type: :danger)) { "Danger" } %>
+    #   <%= render(Primer::ButtonComponent.new(button_type: :outline)) { "Outline" } %>
+    #
+    # @example 50|Variants
+    #   <%= render(Primer::ButtonComponent.new(variant: :small)) { "Small" } %>
+    #   <%= render(Primer::ButtonComponent.new(variant: :medium)) { "Medium" } %>
+    #   <%= render(Primer::ButtonComponent.new(variant: :large)) { "Large" } %>
+    #
+    # @param button_type [Symbol] <%= one_of(Primer::ButtonComponent::BUTTON_TYPE_OPTIONS) %>
+    # @param variant [Symbol] <%= one_of(Primer::ButtonComponent::VARIANT_OPTIONS) %>
+    # @param tag [Symbol] <%= one_of(Primer::ButtonComponent::TAG_OPTIONS) %>
+    # @param type [Symbol] <%= one_of(Primer::ButtonComponent::TYPE_OPTIONS) %>
+    # @param group_item [Boolean] Whether button is part of a ButtonGroup.
     def initialize(
       button_type: DEFAULT_BUTTON_TYPE,
       variant: DEFAULT_VARIANT,
       tag: DEFAULT_TAG,
       type: DEFAULT_TYPE,
       group_item: false,
-      **kwargs
+      **system_arguments
     )
-      @kwargs = kwargs
-      @kwargs[:tag] = fetch_or_fallback(TAG_OPTIONS, tag, DEFAULT_TAG)
+      @system_arguments = system_arguments
+      @system_arguments[:tag] = fetch_or_fallback(TAG_OPTIONS, tag, DEFAULT_TAG)
 
-      if @kwargs[:tag] == :a
-        @kwargs[:role] = :button
+      if @system_arguments[:tag] == :a
+        @system_arguments[:role] = :button
       else
-        @kwargs[:type] = type
+        @system_arguments[:type] = type
       end
 
-      @kwargs[:classes] = class_names(
+      @system_arguments[:classes] = class_names(
         "btn",
-        kwargs[:classes],
+        system_arguments[:classes],
         BUTTON_TYPE_MAPPINGS[fetch_or_fallback(BUTTON_TYPE_OPTIONS, button_type, DEFAULT_BUTTON_TYPE)],
         VARIANT_MAPPINGS[fetch_or_fallback(VARIANT_OPTIONS, variant, DEFAULT_VARIANT)],
         "BtnGroup-item" => group_item
@@ -52,7 +69,7 @@ module Primer
     end
 
     def call
-      render(Primer::BaseComponent.new(**@kwargs)) { content }
+      render(Primer::BaseComponent.new(**@system_arguments)) { content }
     end
   end
 end

data/app/components/primer/component.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 module Primer
+  # @private
   class Component < ViewComponent::Base
     include ClassNameHelper
     include FetchOrFallbackHelper

data/app/components/primer/counter_component.rb

@@ -16,11 +16,11 @@ module Primer
     #
     # @param count [Integer, Float::INFINITY, nil] The number to be displayed (e.x. # of issues, pull requests)
     # @param scheme [Symbol] Color scheme. One of `SCHEME_MAPPINGS.keys`.
-    # @param limit [Integer] Maximum value to display. (e.x. if count == 6,000 and limit == 5000, counter will display "5,000+")
+    # @param limit [Integer, nil] Maximum value to display. Pass `nil` for no limit. (e.x. if `count` == 6,000 and `limit` == 5000, counter will display "5,000+")
     # @param hide_if_zero [Boolean] If true, a `hidden` attribute is added to the counter if `count` is zero.
     # @param text [String] Text to display instead of count.
     # @param round [Boolean] Whether to apply our standard rounding logic to value.
-    # @param kwargs [Hash] Style arguments to be passed to Primer::Classify
+    # @param system_arguments [Hash] <%= link_to_system_arguments_docs %>
     def initialize(
       count: 0,
       scheme: DEFAULT_SCHEME,
@@ -28,23 +28,24 @@ module Primer
       hide_if_zero: false,
       text: "",
       round: false,
-      **kwargs
+      **system_arguments
     )
-      @count, @limit, @hide_if_zero, @text, @round, @kwargs = count, limit, hide_if_zero, text, round, kwargs
+      @count, @limit, @hide_if_zero, @text, @round, @system_arguments = count, limit, hide_if_zero, text, round, system_arguments
 
-      @kwargs[:title] = title
-      @kwargs[:tag] = :span
-      @kwargs[:classes] = class_names(
-        @kwargs[:classes],
+      @has_limit = !@limit.nil?
+      @system_arguments[:title] = title
+      @system_arguments[:tag] = :span
+      @system_arguments[:classes] = class_names(
+        @system_arguments[:classes],
         SCHEME_MAPPINGS[fetch_or_fallback(SCHEME_MAPPINGS.keys, scheme, DEFAULT_SCHEME)]
       )
       if count == 0 && hide_if_zero
-        @kwargs[:hidden] = true
+        @system_arguments[:hidden] = true
       end
     end
 
     def call
-      render(Primer::BaseComponent.new(**@kwargs)) { value }
+      render(Primer::BaseComponent.new(**@system_arguments)) { value }
     end
 
     private
@@ -58,8 +59,8 @@ module Primer
         "Infinity"
       else
         count = @count.to_i
-        str = number_with_delimiter([count, @limit].min)
-        str += "+" if count > @limit
+        str = number_with_delimiter(@has_limit ? [count, @limit].min : count)
+        str += "+" if (@has_limit && count > @limit)
         str
       end
     end
@@ -73,16 +74,16 @@ module Primer
         "∞"
       else
         if @round
-          count = [@count.to_i, @limit].min
+          count = @has_limit ? [@count.to_i, @limit].min : @count.to_i
           precision = count.between?(100_000, 999_999) ? 0 : 1
           units = {thousand: "k", million: "m", billion: "b"}
           str = number_to_human(count, precision: precision, significant: false, units: units, format: "%n%u")
         else
           @count = @count.to_i
-          str = number_with_delimiter([@count, @limit].min)
+          str = number_with_delimiter(@has_limit ? [@count, @limit].min : @count)
         end
 
-        str += "+" if @count.to_i > @limit
+        str += "+" if (@has_limit && @count.to_i > @limit)
         str
       end
     end

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

@@ -1,4 +1,4 @@
-<%= render Primer::BaseComponent.new(**@kwargs) do %>
+<%= render Primer::BaseComponent.new(**@system_arguments) do %>
   <%= render summary.component do %>
     <%= summary.content %>
   <% end %>

data/app/components/primer/details_component.rb

@@ -9,9 +9,9 @@ module Primer
   class DetailsComponent < Primer::Component
     include ViewComponent::Slotable
 
-    OVERLAY_DEFAULT = :none
+    NO_OVERLAY = :none
     OVERLAY_MAPPINGS = {
-      OVERLAY_DEFAULT => "",
+      NO_OVERLAY => "",
       :default => "details-overlay",
       :dark => "details-overlay details-overlay-dark",
     }.freeze
@@ -19,12 +19,12 @@ module Primer
     with_slot :body, class_name: "Body"
     with_slot :summary, class_name: "Summary"
 
-    def initialize(overlay: OVERLAY_DEFAULT, reset: false, **kwargs)
-      @kwargs = kwargs
-      @kwargs[:tag] = :details
-      @kwargs[:classes] = class_names(
-        kwargs[:classes],
-        OVERLAY_MAPPINGS[fetch_or_fallback(OVERLAY_MAPPINGS.keys, overlay, OVERLAY_DEFAULT)],
+    def initialize(overlay: NO_OVERLAY, reset: false, **system_arguments)
+      @system_arguments = system_arguments
+      @system_arguments[:tag] = :details
+      @system_arguments[:classes] = class_names(
+        system_arguments[:classes],
+        OVERLAY_MAPPINGS[fetch_or_fallback(OVERLAY_MAPPINGS.keys, overlay, NO_OVERLAY)],
         "details-reset" => reset
       )
     end
@@ -34,29 +34,29 @@ module Primer
     end
 
     class Summary < Primer::Slot
-      def initialize(button: true, **kwargs)
+      def initialize(button: true, **system_arguments)
         @button = button
 
-        @kwargs = kwargs
-        @kwargs[:tag] = :summary
-        @kwargs[:role] = "button"
+        @system_arguments = system_arguments
+        @system_arguments[:tag] = :summary
+        @system_arguments[:role] = "button"
       end
 
       def component
-        return Primer::BaseComponent.new(**@kwargs) unless @button
+        return Primer::BaseComponent.new(**@system_arguments) unless @button
 
-        Primer::ButtonComponent.new(**@kwargs)
+        Primer::ButtonComponent.new(**@system_arguments)
       end
     end
 
     class Body < Primer::Slot
-      def initialize(**kwargs)
-        @kwargs = kwargs
-        @kwargs[:tag] ||= :div
+      def initialize(**system_arguments)
+        @system_arguments = system_arguments
+        @system_arguments[:tag] ||= :div
       end
 
       def component
-        Primer::BaseComponent.new(**@kwargs)
+        Primer::BaseComponent.new(**@system_arguments)
       end
     end
   end