primer_view_components 0.0.8 → 0.0.13

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

@@ -1,4 +1,4 @@
-<%= render(Primer::FlexComponent.new(**@kwargs)) do %>
+<%= render(Primer::FlexComponent.new(**@system_arguments)) do %>
   <% if @side == :left %>
     <%= render Primer::BaseComponent.new(tag: :div, classes: "flex-shrink-0", col: (@responsive ? [12, nil, @sidebar_col] : @sidebar_col), mb: (@responsive ? [4, nil, 0] : nil)) do %>
       <%= sidebar %>

data/app/components/primer/layout_component.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 module Primer
+  # Use Layout to build a main/sidebar layout.
   class LayoutComponent < Primer::Component
     with_content_areas :main, :sidebar
 
@@ -11,15 +12,31 @@ module Primer
     DEFAULT_SIDEBAR_COL = 3
     ALLOWED_SIDEBAR_COLS = (1..(MAX_COL - 1)).to_a.freeze
 
-    def initialize(responsive: false, side: DEFAULT_SIDE, sidebar_col: DEFAULT_SIDEBAR_COL, **kwargs)
-      @kwargs = kwargs
-      @side = fetch_or_fallback(ALLOWED_SIDES, side.to_sym, DEFAULT_SIDE)
+    # @example 40|Default
+    #   <%= render(Primer::LayoutComponent.new) do |component| %>
+    #     <% component.with(:sidebar) { "Sidebar" } %>
+    #     <% component.with(:main) { "Main" } %>
+    #   <% end %>
+    #
+    # @example 40|Left sidebar
+    #   <%= render(Primer::LayoutComponent.new(side: :left)) do |component| %>
+    #     <% component.with(:sidebar) { "Sidebar" } %>
+    #     <% component.with(:main) { "Main" } %>
+    #   <% end %>
+    #
+    # @param responsive [Boolean] Whether to collapse layout to a single column at smaller widths.
+    # @param side [Symbol] Which side to display the sidebar on. <%= one_of(Primer::LayoutComponent::ALLOWED_SIDES) %>
+    # @param sidebar_col [Integer] Sidebar column width.
+    # @param system_arguments [Hash] <%= link_to_system_arguments_docs %>
+    def initialize(responsive: false, side: DEFAULT_SIDE, sidebar_col: DEFAULT_SIDEBAR_COL, **system_arguments)
+      @system_arguments = system_arguments
+      @side = fetch_or_fallback(ALLOWED_SIDES, side, DEFAULT_SIDE)
       @responsive = responsive
-      @kwargs[:classes] = class_names(
+      @system_arguments[:classes] = class_names(
         "gutter-condensed gutter-lg",
-        @kwargs[:classes]
+        @system_arguments[:classes]
       )
-      @kwargs[:direction] = responsive ? [:column, nil, :row] : nil
+      @system_arguments[:direction] = responsive ? [:column, nil, :row] : nil
 
       @sidebar_col = fetch_or_fallback(ALLOWED_SIDEBAR_COLS, sidebar_col, DEFAULT_SIDEBAR_COL)
       @main_col = MAX_COL - @sidebar_col

data/app/components/primer/link_component.rb

@@ -1,19 +1,29 @@
 # frozen_string_literal: true
 
 module Primer
+  # Use links for moving from one page to another. The Link component styles anchor tags with default blue styling and hover text-decoration.
   class LinkComponent < Primer::Component
-    def initialize(href:, muted: false, **kwargs)
-      @kwargs = kwargs
-      @kwargs[:tag] = :a
-      @kwargs[:href] = href
-      @kwargs[:classes] = class_names(
-        @kwargs[:classes],
+    # @example 40|Default
+    #   <%= render(Primer::LinkComponent.new(href: "http://www.google.com")) { "Link" } %>
+    #
+    # @example 40|Muted
+    #   <%= render(Primer::LinkComponent.new(href: "http://www.google.com", muted: true)) { "Link" } %>
+    #
+    # @param href [String] URL to be used for the Link
+    # @param muted [Boolean] Uses light gray for Link color, and blue on hover
+    # @param system_arguments [Hash] <%= link_to_system_arguments_docs %>
+    def initialize(href:, muted: false, **system_arguments)
+      @system_arguments = system_arguments
+      @system_arguments[:tag] = :a
+      @system_arguments[:href] = href
+      @system_arguments[:classes] = class_names(
+        @system_arguments[:classes],
         "muted-link" => fetch_or_fallback([true, false], muted, false)
       )
     end
 
     def call
-      render(Primer::BaseComponent.new(**@kwargs)) { content }
+      render(Primer::BaseComponent.new(**@system_arguments)) { content }
     end
   end
 end

data/app/components/primer/octicon_component.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 module Primer
+  # Renders an [Octicon](https://primer.style/octicons/) with <%= link_to_system_arguments_docs %>.
   class OcticonComponent < Primer::Component
     include Primer::ClassNameHelper
     include OcticonsHelper
@@ -13,15 +14,32 @@ module Primer
     }.freeze
     SIZE_OPTIONS = SIZE_MAPPINGS.keys
 
-    def initialize(icon:, size: SIZE_DEFAULT, **kwargs)
-      @icon, @kwargs = icon, kwargs
+    # @example 25|Default
+    #   <%= render(Primer::OcticonComponent.new(icon: "check")) %>
+    #
+    # @example 40|Medium
+    #   <%= render(Primer::OcticonComponent.new(icon: "people", size: :medium)) %>
+    #
+    # @example 80|Large
+    #   <%= render(Primer::OcticonComponent.new(icon: "x", size: :large)) %>
+    #
+    # @param icon [String] Name of [Octicon](https://primer.style/octicons/) to use.
+    # @param size [Symbol] <%= one_of(Primer::OcticonComponent::SIZE_MAPPINGS) %>
+    # @param system_arguments [Hash] <%= link_to_system_arguments_docs %>
+    def initialize(icon:, size: SIZE_DEFAULT, **system_arguments)
+      @icon, @system_arguments = icon, system_arguments
 
-      @kwargs[:height] = SIZE_MAPPINGS[size.to_sym]
-      @kwargs[:class] = class_names(@kwargs[:class], Primer::Classify.call(**@kwargs)[:class])
+      @system_arguments[:class] = Primer::Classify.call(**@system_arguments)[:class]
+      @system_arguments[:height] ||= SIZE_MAPPINGS[size]
+
+      # Filter out classify options to prevent them from becoming invalid html attributes.
+      # Note height and width are both classify options and valid html attributes.
+      octicon_helper_options = @system_arguments.slice(:height, :width)
+      @system_arguments = @system_arguments.except(*Primer::Classify::VALID_KEYS, :classes).merge(octicon_helper_options)
     end
 
     def call
-      octicon(@icon, **@kwargs)
+      octicon(@icon, **@system_arguments)
     end
   end
 end

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

@@ -1,4 +1,4 @@
-<%= render Primer::BaseComponent.new(**@kwargs) do %>
+<%= render Primer::BaseComponent.new(**@system_arguments) do %>
   <%= render body.component do %>
     <% if heading %>
       <%= render heading.component do %>

data/app/components/primer/popover_component.rb

@@ -1,22 +1,56 @@
 # frozen_string_literal: true
 
 module Primer
+  # Use popovers to bring attention to specific user interface elements, typically to suggest an action or to guide users through a new experience.
+  #
+  # By default, the popover renders with absolute positioning, meaning it should usually be wrapped in an element with a relative position in order to be positioned properly. To render the popover with relative positioning, use the relative property.
   class PopoverComponent < Primer::Component
     include ViewComponent::Slotable
 
     with_slot :heading, class_name: "Heading"
     with_slot :body, class_name: "Body"
 
-    def initialize(**kwargs)
-      @kwargs = kwargs
-      @kwargs[:tag] ||= :div
-      @kwargs[:classes] = class_names(
-        kwargs[:classes],
+    # @example 150|Default
+    #   <%= render Primer::PopoverComponent.new do |component| %>
+    #     <% component.slot(:heading) do %>
+    #       Activity feed
+    #     <% end %>
+    #     <% component.slot(:body) do %>
+    #       This is the Popover body.
+    #     <% end %>
+    #   <% end %>
+    #
+    # @example 150|Large
+    #   <%= render Primer::PopoverComponent.new do |component| %>
+    #     <% component.slot(:heading) do %>
+    #       Activity feed
+    #     <% end %>
+    #     <% component.slot(:body, large: true) do %>
+    #       This is the large Popover body.
+    #     <% end %>
+    #   <% end %>
+    #
+    # @example 150|Caret position
+    #   <%= render Primer::PopoverComponent.new do |component| %>
+    #     <% component.slot(:heading) do %>
+    #       Activity feed
+    #     <% end %>
+    #     <% component.slot(:body, caret: :left) do %>
+    #       This is the large Popover body.
+    #     <% end %>
+    #   <% 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(
+        system_arguments[:classes],
         "Popover"
       )
-      @kwargs[:position] ||= :relative
-      @kwargs[:right] = false unless kwargs.key?(:right)
-      @kwargs[:left] = false unless kwargs.key?(:left)
+      @system_arguments[:position] ||= :relative
+      @system_arguments[:right] = false unless system_arguments.key?(:right)
+      @system_arguments[:left] = false unless system_arguments.key?(:left)
     end
 
     def render?
@@ -24,14 +58,15 @@ module Primer
     end
 
     class Heading < ViewComponent::Slot
-      def initialize(**kwargs)
-        @kwargs = kwargs
-        @kwargs[:mb] ||= 2
-        @kwargs[:tag] ||= :h4
+      # @param system_arguments [Hash] <%= link_to_system_arguments_docs %>
+      def initialize(**system_arguments)
+        @system_arguments = system_arguments
+        @system_arguments[:mb] ||= 2
+        @system_arguments[:tag] ||= :h4
       end
 
       def component
-        Primer::HeadingComponent.new(**@kwargs)
+        Primer::HeadingComponent.new(**@system_arguments)
       end
     end
 
@@ -52,23 +87,26 @@ module Primer
         :top_right => "Popover-message--top-right"
       }.freeze
 
-      def initialize(caret: CARET_DEFAULT, large: false, **kwargs)
-        @kwargs = kwargs
-        @kwargs[:classes] = class_names(
-          kwargs[:classes],
+      # @param caret [Symbol] <%= one_of(Primer::PopoverComponent::Body::CARET_MAPPINGS.keys) %>
+      # @param large [Boolean] Whether to use the large version of the component.
+      # @param system_arguments [Hash] <%= link_to_system_arguments_docs %>
+      def initialize(caret: CARET_DEFAULT, large: false, **system_arguments)
+        @system_arguments = system_arguments
+        @system_arguments[:classes] = class_names(
+          system_arguments[:classes],
           "Popover-message Box",
           CARET_MAPPINGS[fetch_or_fallback(CARET_MAPPINGS.keys, caret, CARET_DEFAULT)],
           "Popover-message--large" => large
         )
-        @kwargs[:p] ||= 4
-        @kwargs[:mt] ||= 2
-        @kwargs[:mx] ||= :auto
-        @kwargs[:text_align] ||= :left
-        @kwargs[:box_shadow] ||= :large
+        @system_arguments[:p] ||= 4
+        @system_arguments[:mt] ||= 2
+        @system_arguments[:mx] ||= :auto
+        @system_arguments[:text_align] ||= :left
+        @system_arguments[:box_shadow] ||= :large
       end
 
       def component
-        Primer::BoxComponent.new(**@kwargs)
+        Primer::BoxComponent.new(**@system_arguments)
       end
     end
   end

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

@@ -0,0 +1,6 @@
+<%= 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" />
+  </path>
+<% end %>

data/app/components/primer/spinner_component.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module Primer
+  # Use Primer::SpinnerComponent to let users know that content is being loaded.
+  class SpinnerComponent < Primer::Component
+
+    DEFAULT_SIZE = :medium
+    SIZE_MAPPINGS = {
+      :small => 16,
+      DEFAULT_SIZE => 32,
+      :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
+    #   <%= render(Primer::SpinnerComponent.new) %>
+    #
+    # @example 32|Small
+    #   <%= render(Primer::SpinnerComponent.new(size: :small)) %>
+    #
+    # @example 80|Large
+    #   <%= render(Primer::SpinnerComponent.new(size: :large)) %>
+    #
+    # @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