primer_view_components 0.0.10 → 0.0.15

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

@@ -1,5 +1,5 @@
-<%= render Primer::BaseComponent.new(**@kwargs) do %>
+<%= render Primer::BaseComponent.new(**@system_arguments) do %>
   <% items.each do |item| %>
-    <%= render Primer::BaseComponent.new(**item.kwargs) %>
+    <%= render Primer::BaseComponent.new(**item.system_arguments) %>
   <% end %>
 <% end %>

data/app/components/primer/progress_bar_component.rb

@@ -1,23 +1,7 @@
 # frozen_string_literal: true
 
-##
-# Use progress components to visualize task completion.
-
-## Basic example
-#
-# The `Primer::ProgressBarComponent` can take the following arguments:
-#
-# 1. `size` (string). Can be "small" or "large". Increases the height of the progress bar.
-#
-# The `Primer::ProgressBarComponent` 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 accepts a `percentage` parameter, which is used to set the width of the completed bar.
-#
-# ```ruby
-#   <%= render(Primer::ProgressBarComponent.new(size: :small)) do |component| %>
-#     <% component.slot(:item, bg: :blue-4, percentage: 50) %>
-#   <% end %>
-# ```
-##
 module Primer
+  # Use ProgressBar to visualize task completion.
   class ProgressBarComponent < Primer::Component
     include ViewComponent::Slotable
 
@@ -32,15 +16,38 @@ module Primer
     }.freeze
 
     SIZE_OPTIONS = SIZE_MAPPINGS.keys
-
-    def initialize(size: SIZE_DEFAULT, percentage: 0, **kwargs)
-      @kwargs = kwargs
-      @kwargs[:classes] = class_names(
-        @kwargs[:classes],
+    # @example 20|Default
+    #   <%= render(Primer::ProgressBarComponent.new) do |component| %>
+    #     <% component.slot(:item, percentage: 25) %>
+    #   <% end %>
+    #
+    # @example 20|Small
+    #   <%= render(Primer::ProgressBarComponent.new(size: :small)) do |component| %>
+    #     <% component.slot(:item, bg: :blue_4, percentage: 50) %>
+    #   <% end %>
+    #
+    # @example 30|Large
+    #   <%= render(Primer::ProgressBarComponent.new(size: :large)) do |component| %>
+    #     <% component.slot(:item, bg: :red_4, percentage: 75) %>
+    #   <% end %>
+    #
+    # @example 20|Multiple items
+    #   <%= render(Primer::ProgressBarComponent.new) do |component| %>
+    #     <% component.slot(:item, percentage: 10) %>
+    #     <% component.slot(:item, bg: :blue_4, percentage: 20) %>
+    #     <% component.slot(:item, bg: :red_4, percentage: 30) %>
+    #   <% end %>
+    #
+    # @param size [Symbol] <%= one_of(Primer::ProgressBarComponent::SIZE_OPTIONS) %> Increases height.
+    # @param system_arguments [Hash] <%= link_to_system_arguments_docs %>
+    def initialize(size: SIZE_DEFAULT, **system_arguments)
+      @system_arguments = system_arguments
+      @system_arguments[:classes] = class_names(
+        @system_arguments[:classes],
         "Progress",
         SIZE_MAPPINGS[fetch_or_fallback(SIZE_OPTIONS, size, SIZE_DEFAULT)]
       )
-      @kwargs[:tag] = :span
+      @system_arguments[:tag] = :span
 
     end
 
@@ -50,16 +57,19 @@ module Primer
 
     class Item < ViewComponent::Slot
       include ClassNameHelper
-      attr_reader :kwargs
+      attr_reader :system_arguments
 
-      def initialize(percentage: 0, bg: :green, **kwargs)
+      # @param percentage [Integer] Percentage completion of item.
+      # @param bg [Symbol] Color of item.
+      # @param system_arguments [Hash] <%= link_to_system_arguments_docs %>
+      def initialize(percentage: 0, bg: :green, **system_arguments)
         @percentage = percentage
-        @kwargs = kwargs
+        @system_arguments = system_arguments
 
-        @kwargs[:tag] = :span
-        @kwargs[:bg] = bg
-        @kwargs[:style] = "width: #{@percentage}%;"
-        @kwargs[:classes] = class_names("Progress-item", @kwargs[:classes])
+        @system_arguments[:tag] = :span
+        @system_arguments[:bg] = bg
+        @system_arguments[:style] = "width: #{@percentage}%;"
+        @system_arguments[:classes] = class_names("Progress-item", @system_arguments[:classes])
       end
     end
   end

data/app/components/primer/slot.rb

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

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

@@ -1,4 +1,4 @@
-<%= render Primer::BaseComponent.new(**@kwargs) do %>
+<%= 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" />
   <path d="M15 8a7.002 7.002 0 00-7-7" stroke="currentColor" stroke-width="2" stroke-linecap="round" vector-effect="non-scaling-stroke">
     <animateTransform attributeName="transform" type="rotate" from="0 8 8" to="360 8 8" dur="1s" repeatCount="indefinite" />

data/app/components/primer/spinner_component.rb

@@ -11,6 +11,9 @@ module Primer
       :large => 64,
     }.freeze
     SIZE_OPTIONS = SIZE_MAPPINGS.keys
+    # Setting `box-sizing: content-box` allows consumers to add padding
+    # to the spinner without shrinking the icon
+    DEFAULT_STYLE = "box-sizing: content-box; color: var(--color-icon-primary);"
 
     #
     # @example 48|Default
@@ -22,17 +25,15 @@ module Primer
     # @example 80|Large
     #   <%= render(Primer::SpinnerComponent.new(size: :large)) %>
     #
-    # @param size [Symbol] One of <%= Primer::SpinnerComponent::SIZE_OPTIONS.map { |k| "`:#{k}`" }.to_sentence(last_word_connector: ', or ') %>
-    def initialize(size: DEFAULT_SIZE, **kwargs)
-      @kwargs = kwargs
-      @kwargs[:tag] = :svg
-      @kwargs[:width] = SIZE_MAPPINGS[fetch_or_fallback(SIZE_OPTIONS, size, DEFAULT_SIZE)]
-      @kwargs[:height] = SIZE_MAPPINGS[fetch_or_fallback(SIZE_OPTIONS, size, DEFAULT_SIZE)]
-      @kwargs[:viewBox] = "0 0 16 16"
-      @kwargs[:fill] = :none
-      # Setting `box-sizing: content-box` allows consumers to add padding
-      # to the spinner without shrinking the icon
-      @kwargs[:style] = "box-sizing: content-box; color: var(--color-icon-primary);"
+    # @param size [Symbol] <%= one_of(Primer::SpinnerComponent::SIZE_MAPPINGS) %>
+    def initialize(size: DEFAULT_SIZE, style: DEFAULT_STYLE, **system_arguments)
+      @system_arguments = system_arguments
+      @system_arguments[:tag] = :svg
+      @system_arguments[:width] = SIZE_MAPPINGS[fetch_or_fallback(SIZE_OPTIONS, size, DEFAULT_SIZE)]
+      @system_arguments[:height] = SIZE_MAPPINGS[fetch_or_fallback(SIZE_OPTIONS, size, DEFAULT_SIZE)]
+      @system_arguments[:viewBox] = "0 0 16 16"
+      @system_arguments[:fill] = :none
+      @system_arguments[:style] = DEFAULT_STYLE unless style.nil?
     end
   end
 end

data/app/components/primer/state_component.rb

@@ -1,14 +1,8 @@
 # frozen_string_literal: true
 
 module Primer
+  # Component for rendering the status of an item.
   class StateComponent < Primer::Component
-    # Component for rendering the status of an item
-    #
-    # title(string): (required) title attribute
-    # color(symbol): label background color
-    # size(symbol): label size
-    # counter(integer): counter value
-    # **args(hash): utility parameters for Primer::Classify
     COLOR_DEFAULT = :default
     COLOR_MAPPINGS = {
       COLOR_DEFAULT => "",
@@ -28,18 +22,36 @@ module Primer
     TAG_DEFAULT = :span
     TAG_OPTIONS = [TAG_DEFAULT, :div, :a]
 
+    # @example 40|Default
+    #   <%= render(Primer::StateComponent.new(title: "title")) { "State" } %>
+    #
+    # @example 40|Colors
+    #   <%= render(Primer::StateComponent.new(title: "title")) { "Default" } %>
+    #   <%= render(Primer::StateComponent.new(title: "title", color: :green)) { "Green" } %>
+    #   <%= render(Primer::StateComponent.new(title: "title", color: :red)) { "Red" } %>
+    #   <%= render(Primer::StateComponent.new(title: "title", color: :purple)) { "Purple" } %>
+    #
+    # @example 40|Sizes
+    #   <%= render(Primer::StateComponent.new(title: "title")) { "Default" } %>
+    #   <%= render(Primer::StateComponent.new(title: "title", size: :small)) { "Small" } %>
+    #
+    # @param title [String] `title` HTML attribute.
+    # @param color [Symbol] Background color. <%= one_of(Primer::StateComponent::COLOR_OPTIONS) %>
+    # @param tag [Symbol] HTML tag for element. <%= one_of(Primer::StateComponent::TAG_OPTIONS) %>
+    # @param size [Symbol] <%= one_of(Primer::StateComponent::SIZE_OPTIONS) %>
+    # @param system_arguments [Hash] <%= link_to_system_arguments_docs %>
     def initialize(
       title:,
       color: COLOR_DEFAULT,
       tag: TAG_DEFAULT,
       size: SIZE_DEFAULT,
-      **kwargs
+      **system_arguments
     )
-      @kwargs = kwargs
-      @kwargs[:title] = title
-      @kwargs[:tag] = fetch_or_fallback(TAG_OPTIONS, tag, TAG_DEFAULT)
-      @kwargs[:classes] = class_names(
-        @kwargs[:classes],
+      @system_arguments = system_arguments
+      @system_arguments[:title] = title
+      @system_arguments[:tag] = fetch_or_fallback(TAG_OPTIONS, tag, TAG_DEFAULT)
+      @system_arguments[:classes] = class_names(
+        @system_arguments[:classes],
         "State",
         COLOR_MAPPINGS[fetch_or_fallback(COLOR_OPTIONS, color, COLOR_DEFAULT)],
         SIZE_MAPPINGS[fetch_or_fallback(SIZE_OPTIONS, size, SIZE_DEFAULT)]
@@ -47,7 +59,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/subhead_component.html.erb

@@ -1,16 +1,16 @@
-<%= render Primer::BaseComponent.new(**@kwargs) do %>
+<%= render Primer::BaseComponent.new(**@system_arguments) do %>
   <% if heading.present? %>
-    <%= render Primer::BaseComponent.new(**heading.kwargs) do %>
+    <%= render Primer::BaseComponent.new(**heading.system_arguments) do %>
       <%= heading.content %>
     <% end %>
   <% end %>
   <% if actions.present? %>
-    <%= render Primer::BaseComponent.new(**actions.kwargs) do %>
+    <%= render Primer::BaseComponent.new(**actions.system_arguments) do %>
       <%= actions.content %>
     <% end %>
   <% end %>
   <% if description.present? %>
-    <%= render Primer::BaseComponent.new(**description.kwargs) do %>
+    <%= render Primer::BaseComponent.new(**description.system_arguments) do %>
       <%= description.content %>
     <% end %>
   <% end %>

data/app/components/primer/subhead_component.rb

@@ -1,26 +1,7 @@
 # frozen_string_literal: true
 
-# This component consists of a .Subhead container, which has a light gray bottom border.
-
-# Use a heading element whenever possible as they can be
-# used as navigation for assistive technologies, and avoid skipping levels.
-
-# ## Basic example
-
-# The `Primer::SubheadComponent` can take the following arguments:
-
-# 1. `heading` (string). The heading to be rendered.
-# 2. `actions` (content). Slot to render any actions to the right of heading.
-# 3. `description` (string). Slot to render description under the heading.
-
-# ```erb
-# <%= Primer::SubheadComponent.new(heading: "Hello world")) do |component| %>
-#   <% component.slot(:actions) do %>
-#     My Actions
-#   <% end %>
-# <% end %>
-# ```
 module Primer
+  # Use the Subhead component for page headings.
   class SubheadComponent < Primer::Component
     include ViewComponent::Slotable
 
@@ -28,18 +9,58 @@ module Primer
     with_slot :actions, class_name: "Actions"
     with_slot :description, class_name: "Description"
 
-    def initialize(spacious: false, hide_border: false, **kwargs)
-      @kwargs = kwargs
-
-      @kwargs[:tag] = :div
-      @kwargs[:classes] =
+    # @example 95|Default
+    #   <%= render(Primer::SubheadComponent.new) do |component| %>
+    #     <% component.slot(:heading) do %>
+    #       My Heading
+    #     <% end %>
+    #     <% component.slot(:description) do %>
+    #       My Description
+    #     <% end %>
+    #   <% end %>
+    #
+    # @example 95|Without border
+    #   <%= render(Primer::SubheadComponent.new(hide_border: true)) do |component| %>
+    #     <% component.slot(:heading) do %>
+    #       My Heading
+    #     <% end %>
+    #     <% component.slot(:description) do %>
+    #       My Description
+    #     <% end %>
+    #   <% end %>
+    #
+    # @example 95|With actions
+    #   <%= render(Primer::SubheadComponent.new) do |component| %>
+    #     <% component.slot(:heading) do %>
+    #       My Heading
+    #     <% end %>
+    #     <% component.slot(:description) do %>
+    #       My Description
+    #     <% end %>
+    #     <% component.slot(:actions) do %>
+    #       <%= render(
+    #         Primer::ButtonComponent.new(
+    #           tag: :a, href: "http://www.google.com", button_type: :danger
+    #         )
+    #       ) { "Action" } %>
+    #     <% end %>
+    #   <% end %>
+    #
+    # @param spacious [Boolean] Whether to add spacing to the Subhead.
+    # @param hide_border [Boolean] Whether to hide the border under the heading.
+    # @param system_arguments [Hash] <%= link_to_system_arguments_docs %>
+    def initialize(spacious: false, hide_border: false, **system_arguments)
+      @system_arguments = system_arguments
+
+      @system_arguments[:tag] = :div
+      @system_arguments[:classes] =
         class_names(
-          @kwargs[:classes],
+          @system_arguments[:classes],
           "Subhead hx_Subhead--responsive",
           "Subhead--spacious": spacious,
           "border-bottom-0": hide_border
         )
-      @kwargs[:mb] ||= hide_border ? 0 : nil
+      @system_arguments[:mb] ||= hide_border ? 0 : nil
     end
 
     def render?
@@ -49,13 +70,15 @@ module Primer
     class Heading < ViewComponent::Slot
       include ClassNameHelper
 
-      attr_reader :kwargs
+      attr_reader :system_arguments
 
-      def initialize(danger: false, **kwargs)
-        @kwargs = kwargs
-        @kwargs[:tag] ||= :div
-        @kwargs[:classes] = class_names(
-          @kwargs[:classes],
+      # @param danger [Boolean] Whether to style the heading as dangerous.
+      # @param system_arguments [Hash] <%= link_to_system_arguments_docs %>
+      def initialize(danger: false, **system_arguments)
+        @system_arguments = system_arguments
+        @system_arguments[:tag] ||= :div
+        @system_arguments[:classes] = class_names(
+          @system_arguments[:classes],
           "Subhead-heading",
           "Subhead-heading--danger": danger
         )
@@ -65,24 +88,26 @@ module Primer
     class Actions < ViewComponent::Slot
       include ClassNameHelper
 
-      attr_reader :kwargs
+      attr_reader :system_arguments
 
-      def initialize(**kwargs)
-        @kwargs = kwargs
-        @kwargs[:tag] = :div
-        @kwargs[:classes] = class_names(@kwargs[:classes], "Subhead-actions")
+      # @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(@system_arguments[:classes], "Subhead-actions")
       end
     end
 
     class Description < ViewComponent::Slot
       include ClassNameHelper
 
-      attr_reader :kwargs
+      attr_reader :system_arguments
 
-      def initialize(**kwargs)
-        @kwargs = kwargs
-        @kwargs[:tag] = :div
-        @kwargs[:classes] = class_names(@kwargs[:classes], "Subhead-description")
+      # @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(@system_arguments[:classes], "Subhead-description")
       end
     end
   end

data/app/components/primer/text_component.rb

@@ -1,14 +1,20 @@
 # frozen_string_literal: true
 
 module Primer
+  # The Text component is a wrapper component that will apply typography styles to the text inside.
   class TextComponent < Primer::Component
-    def initialize(**kwargs)
-      @kwargs = kwargs
-      @kwargs[:tag] ||= :span
+    # @example 70|Default
+    #   <%= render(Primer::TextComponent.new(tag: :p, font_weight: :bold)) { "Bold Text" } %>
+    #   <%= render(Primer::TextComponent.new(tag: :p, color: :red_5)) { "Red Text" } %>
+    #
+    # @param system_arguments [Hash] <%= link_to_system_arguments_docs %>
+    def initialize(**system_arguments)
+      @system_arguments = system_arguments
+      @system_arguments[:tag] ||= :span
     end
 
     def call
-      render(Primer::BaseComponent.new(**@kwargs)) { content }
+      render(Primer::BaseComponent.new(**@system_arguments)) { content }
     end
   end
 end

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

@@ -1,16 +1,16 @@
-<%= render Primer::BaseComponent.new(**kwargs) do %>
+<%= render Primer::BaseComponent.new(**system_arguments) do %>
   <% if avatar %>
-    <%= render Primer::AvatarComponent.new(alt: avatar.alt, src: avatar.src, size: avatar.size, square: avatar.square, **avatar.kwargs) %>
+    <%= render Primer::AvatarComponent.new(alt: avatar.alt, src: avatar.src, size: avatar.size, square: avatar.square, **avatar.system_arguments) %>
   <% end %>
 
   <% if badge %>
-    <%= render Primer::BaseComponent.new(**badge.kwargs) do %>
+    <%= render Primer::BaseComponent.new(**badge.system_arguments) do %>
       <%= octicon badge.icon %>
     <% end %>
   <% end %>
 
   <% if body %>
-    <%= render Primer::BaseComponent.new(**body.kwargs) do %>
+    <%= render Primer::BaseComponent.new(**body.system_arguments) do %>
       <%= body.content %>
     <% end %>
   <% end %>

data/app/components/primer/timeline_item_component.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 module Primer
+  # Use `TimelineItem` to display items on a vertical timeline, connected by badge elements.
   class TimelineItemComponent < Primer::Component
     include ViewComponent::Slotable
 
@@ -8,14 +9,26 @@ module Primer
     with_slot :badge, class_name: "Badge"
     with_slot :body, class_name: "Body"
 
-    attr_reader :kwargs
-    def initialize(condensed: false, **kwargs)
-      @kwargs = kwargs
-      @kwargs[:tag] = :div
-      @kwargs[:classes] = class_names(
+    attr_reader :system_arguments
+
+    # @example 75|Default
+    #   <div style="padding-left: 60px">
+    #     <%= render(Primer::TimelineItemComponent.new) do |component| %>
+    #       <% component.slot(:avatar, src: "https://github.com/github.png", alt: "github") %>
+    #       <% component.slot(:badge, bg: :green, color: :white, icon: :check) %>
+    #       <% component.slot(:body) { "Success!" } %>
+    #     <% end %>
+    #   </div>
+    #
+    # @param condensed [Boolean] Reduce the vertical padding and remove the background from the badge item. Most commonly used in commits.
+    # @param system_arguments [Hash] <%= link_to_system_arguments_docs %>
+    def initialize(condensed: false, **system_arguments)
+      @system_arguments = system_arguments
+      @system_arguments[:tag] = :div
+      @system_arguments[:classes] = class_names(
         "TimelineItem",
         condensed ? "TimelineItem--condensed" : "",
-        kwargs[:classes]
+        system_arguments[:classes]
       )
     end
 
@@ -24,44 +37,55 @@ module Primer
     end
 
     class Avatar < Primer::Slot
-      attr_reader :kwargs, :alt, :src, :size, :square
-      def initialize(alt: nil, src: nil, size: 40, square: true, **kwargs)
+      attr_reader :system_arguments, :alt, :src, :size, :square
+
+      # @param alt [String] Alt text for avatar image.
+      # @param src [String] Src attribute for avatar image.
+      # @param size [Integer] Image size.
+      # @param square [Boolean] Whether to round the edges of the image.
+      # @param system_arguments [Hash] <%= link_to_system_arguments_docs %>
+      def initialize(alt: nil, src: nil, size: 40, square: true, **system_arguments)
         @alt = alt
         @src = src
         @size = size
         @square = square
 
-        @kwargs = kwargs
-        @kwargs[:tag] = :div
-        @kwargs[:classes] = class_names(
+        @system_arguments = system_arguments
+        @system_arguments[:tag] = :div
+        @system_arguments[:classes] = class_names(
           "TimelineItem-avatar",
-          kwargs[:classes]
+          system_arguments[:classes]
         )
       end
     end
 
     class Badge < Primer::Slot
-      attr_reader :kwargs, :icon
-      def initialize(icon: nil, **kwargs)
+      attr_reader :system_arguments, :icon
+
+      # @param icon [String] Name of [Octicon](https://primer.style/octicons/) to use.
+      # @param system_arguments [Hash] <%= link_to_system_arguments_docs %>
+      def initialize(icon: nil, **system_arguments)
         @icon = icon
 
-        @kwargs = kwargs
-        @kwargs[:tag] = :div
-        @kwargs[:classes] = class_names(
+        @system_arguments = system_arguments
+        @system_arguments[:tag] = :div
+        @system_arguments[:classes] = class_names(
           "TimelineItem-badge",
-          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(
           "TimelineItem-body",
-          kwargs[:classes]
+          system_arguments[:classes]
         )
       end
     end