primer_view_components 0.0.8 → 0.0.13

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,34 +26,50 @@ 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.to_sym, 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.to_sym
+        @system_arguments[:type] = type
       end
 
-      @kwargs[:classes] = class_names(
+      @system_arguments[:classes] = class_names(
         "btn",
-        kwargs[:classes],
-        BUTTON_TYPE_MAPPINGS[fetch_or_fallback(BUTTON_TYPE_OPTIONS, button_type.to_sym, DEFAULT_BUTTON_TYPE)],
-        VARIANT_MAPPINGS[fetch_or_fallback(VARIANT_OPTIONS, variant.to_sym, DEFAULT_VARIANT)],
+        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
       )
     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

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 module Primer
+  # Use Primer::CounterComponent to add a count to navigational elements and buttons.
   class CounterComponent < Primer::Component
     DEFAULT_SCHEME = :default
     SCHEME_MAPPINGS = {
@@ -9,13 +10,17 @@ module Primer
       :light_gray => "Counter Counter--gray-light",
     }.freeze
 
+    #
+    # @example 34|Default
+    #   <%= render(Primer::CounterComponent.new(count: 25)) %>
+    #
     # @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 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,
@@ -23,23 +28,23 @@ 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],
+      @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

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.to_sym, 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

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

@@ -1,4 +1,4 @@
-<%= render Primer::BaseComponent.new(**@kwargs) do %>
+<%= render Primer::BaseComponent.new(**@system_arguments) do %>
   <% if @header.present? %>
     <div class="dropdown-header">
       <%= @header %>

data/app/components/primer/dropdown_menu_component.rb

@@ -11,14 +11,14 @@ module Primer
     DIRECTION_DEFAULT = :se
     DIRECTION_OPTIONS = [DIRECTION_DEFAULT, :sw, :w, :e, :ne, :s]
 
-    def initialize(direction: DIRECTION_DEFAULT, scheme: SCHEME_DEFAULT, header: nil, **kwargs)
-      @header, @direction, @kwargs = header, direction, kwargs
+    def initialize(direction: DIRECTION_DEFAULT, scheme: SCHEME_DEFAULT, header: nil, **system_arguments)
+      @header, @direction, @system_arguments = header, direction, system_arguments
 
-      @kwargs[:tag] = "details-menu"
-      @kwargs[:role] = "menu"
+      @system_arguments[:tag] = "details-menu"
+      @system_arguments[:role] = "menu"
 
-      @kwargs[:classes] = class_names(
-        @kwargs[:classes],
+      @system_arguments[:classes] = class_names(
+        @system_arguments[:classes],
         "dropdown-menu",
         "dropdown-menu-#{fetch_or_fallback(DIRECTION_OPTIONS, direction, DIRECTION_DEFAULT)}",
         SCHEME_MAPPINGS[fetch_or_fallback(SCHEME_MAPPINGS.keys, scheme, SCHEME_DEFAULT)]

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

@@ -1,4 +1,4 @@
-<%= render Primer::BaseComponent.new(**@kwargs) do %>
+<%= render Primer::BaseComponent.new(**@system_arguments) do %>
   <%= render(Primer::OcticonComponent.new(icon: @icon)) if @icon %>
   <%= content %>
   <% if @dismissible %>
@@ -7,7 +7,7 @@
     </button>
   <% end %>
   <% if actions.present? %>
-    <%= render Primer::BaseComponent.new(**actions.kwargs) do %>
+    <%= render Primer::BaseComponent.new(**actions.system_arguments) do %>
       <%= actions.content %>
     <% end %>
   <% end %>

data/app/components/primer/flash_component.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 module Primer
+  # Use the Flash component to inform users of successful or pending actions.
   class FlashComponent < Primer::Component
     include ViewComponent::Slotable
 
@@ -13,30 +14,59 @@ module Primer
       :danger => "flash-error",
       :success => "flash-success"
     }.freeze
-
-    def initialize(full: false, spacious: false, dismissible: false, icon: nil, variant: DEFAULT_VARIANT, **kwargs)
+    # @example 280|Variants
+    #   <%= render(Primer::FlashComponent.new) { "This is a flash message!" } %>
+    #   <%= render(Primer::FlashComponent.new(variant: :warning)) { "This is a warning flash message!" } %>
+    #   <%= render(Primer::FlashComponent.new(variant: :danger)) { "This is a danger flash message!" } %>
+    #   <%= render(Primer::FlashComponent.new(variant: :success)) { "This is a success flash message!" } %>
+    #
+    # @example 80|Full width
+    #   <%= render(Primer::FlashComponent.new(full: true)) { "This is a full width flash message!" } %>
+    #
+    # @example 80|Dismissible
+    #   <%= render(Primer::FlashComponent.new(dismissible: true)) { "This is a dismissible flash message!" } %>
+    #
+    # @example 80|Icon
+    #   <%= render(Primer::FlashComponent.new(icon: "people")) { "This is a flash message with an icon!" } %>
+    #
+    # @example 80|With actions
+    #   <%= render(Primer::FlashComponent.new) do |component| %>
+    #     This is a flash message with actions!
+    #     <% component.slot(:actions) do %>
+    #       <%= render(Primer::ButtonComponent.new(variant: :small)) { "Take action" } %>
+    #     <% end %>
+    #   <% end %>
+    #
+    # @param full [Boolean] Whether the component should take up the full width of the screen.
+    # @param spacious [Boolean] Whether to add margin to the bottom of the component.
+    # @param dismissible [Boolean] Whether the component can be dismissed with an X button.
+    # @param icon [String] Name of Octicon icon to use.
+    # @param variant [Symbol] <%= one_of(Primer::FlashComponent::VARIANT_MAPPINGS.keys) %>
+    # @param system_arguments [Hash] <%= link_to_system_arguments_docs %>
+    def initialize(full: false, spacious: false, dismissible: false, icon: nil, variant: DEFAULT_VARIANT, **system_arguments)
       @icon = icon
       @dismissible = dismissible
-      @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],
         "flash",
-        VARIANT_MAPPINGS[fetch_or_fallback(VARIANT_MAPPINGS.keys, variant.to_sym, DEFAULT_VARIANT)],
+        VARIANT_MAPPINGS[fetch_or_fallback(VARIANT_MAPPINGS.keys, variant, DEFAULT_VARIANT)],
         "flash-full": full
       )
-      @kwargs[:mb] ||= spacious ? 4 : nil
+      @system_arguments[:mb] ||= spacious ? 4 : nil
     end
 
     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], "flash-action")
+      # @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], "flash-action")
       end
     end
   end

data/app/components/primer/flex_component.rb

@@ -37,7 +37,7 @@ module Primer
       flex_wrap: FLEX_WRAP_DEFAULT,
       align_items: ALIGN_ITEMS_DEFAULT,
       direction: nil,
-      **kwargs
+      **system_arguments
     )
       @align_items = fetch_or_fallback(ALIGN_ITEMS_OPTIONS, align_items, ALIGN_ITEMS_DEFAULT)
       @justify_content = fetch_or_fallback(JUSTIFY_CONTENT_OPTIONS, justify_content, JUSTIFY_CONTENT_DEFAULT)
@@ -51,13 +51,13 @@ module Primer
           DEFAULT_DIRECTION
         end
 
-      @kwargs = kwargs.merge({ direction: @direction }.compact)
-      @kwargs[:classes] = class_names(@kwargs[:classes], component_class_names)
-      @kwargs[:display] = fetch_or_fallback(INLINE_OPTIONS, inline, INLINE_DEFAULT) ? :inline_flex : :flex
+      @system_arguments = system_arguments.merge({ direction: @direction }.compact)
+      @system_arguments[:classes] = class_names(@system_arguments[:classes], component_class_names)
+      @system_arguments[:display] = fetch_or_fallback(INLINE_OPTIONS, inline, INLINE_DEFAULT) ? :inline_flex : :flex
     end
 
     def call
-      render(Primer::BoxComponent.new(**@kwargs)) { content }
+      render(Primer::BoxComponent.new(**@system_arguments)) { content }
     end
 
     private

data/app/components/primer/flex_item_component.rb

@@ -5,17 +5,17 @@ module Primer
     FLEX_AUTO_DEFAULT = false
     FLEX_AUTO_ALLOWED_VALUES = [FLEX_AUTO_DEFAULT, true]
 
-    def initialize(flex_auto: FLEX_AUTO_DEFAULT, **kwargs)
-      @kwargs = kwargs
-      @kwargs[:classes] =
+    def initialize(flex_auto: FLEX_AUTO_DEFAULT, **system_arguments)
+      @system_arguments = system_arguments
+      @system_arguments[:classes] =
         class_names(
-          @kwargs[:classes],
+          @system_arguments[:classes],
           "flex-auto" => fetch_or_fallback(FLEX_AUTO_ALLOWED_VALUES, flex_auto, FLEX_AUTO_DEFAULT)
         )
     end
 
     def call
-      render(Primer::BoxComponent.new(**@kwargs)) { content }
+      render(Primer::BoxComponent.new(**@system_arguments)) { content }
     end
   end
 end

data/app/components/primer/heading_component.rb

@@ -2,13 +2,13 @@
 
 module Primer
   class HeadingComponent < Primer::Component
-    def initialize(**kwargs)
-      @kwargs = kwargs
-      @kwargs[:tag] ||= :h1
+    def initialize(**system_arguments)
+      @system_arguments = system_arguments
+      @system_arguments[:tag] ||= :h1
     end
 
     def call
-      render(Primer::BaseComponent.new(**@kwargs)) { content }
+      render(Primer::BaseComponent.new(**@system_arguments)) { content }
     end
   end
 end

data/app/components/primer/label_component.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 module Primer
+  # Use labels to add contextual metadata to a design.
   class LabelComponent < Primer::Component
     SCHEME_MAPPINGS = {
       # gray
@@ -28,21 +29,37 @@ module Primer
     }.freeze
     VARIANT_OPTIONS = VARIANT_MAPPINGS.keys << nil
 
-    def initialize(title:, scheme: nil, variant: nil, **kwargs)
-      @kwargs = kwargs
-      @kwargs[:bg] = :blue if scheme.nil?
-      @kwargs[:tag] ||= :span
-      @kwargs[:title] = title
-      @kwargs[:classes] = class_names(
+    # @example 40|Schemes
+    #   <%= render(Primer::LabelComponent.new(title: "Label: Label")) { "default" } %>
+    #   <%= render(Primer::LabelComponent.new(title: "Label: Label", scheme: :gray)) { "gray" } %>
+    #   <%= render(Primer::LabelComponent.new(title: "Label: Label", scheme: :dark_gray)) { "dark_gray" } %>
+    #   <%= render(Primer::LabelComponent.new(title: "Label: Label", scheme: :yellow)) { "yellow" } %>
+    #   <%= render(Primer::LabelComponent.new(title: "Label: Label", scheme: :green)) { "green" } %>
+    #   <%= render(Primer::LabelComponent.new(title: "Label: Label", scheme: :purple)) { "purple" } %>
+    #
+    # @example 40|Variants
+    #   <%= render(Primer::LabelComponent.new(title: "Label: Label")) { "Default" } %>
+    #   <%= render(Primer::LabelComponent.new(title: "Label: Label", variant: :large)) { "Large" } %>
+    #
+    # @param title [String] `title` attribute for the component element.
+    # @param scheme [Symbol] <%= one_of(Primer::LabelComponent::SCHEME_OPTIONS) %>
+    # @param variant [Symbol] <%= one_of(Primer::LabelComponent::VARIANT_OPTIONS) %>
+    # @param system_arguments [Hash] <%= link_to_system_arguments_docs %>
+    def initialize(title:, scheme: nil, variant: nil, **system_arguments)
+      @system_arguments = system_arguments
+      @system_arguments[:bg] = :blue if scheme.nil?
+      @system_arguments[:tag] ||= :span
+      @system_arguments[:title] = title
+      @system_arguments[:classes] = class_names(
         "Label",
-        kwargs[:classes],
+        system_arguments[:classes],
         SCHEME_MAPPINGS[fetch_or_fallback(SCHEME_OPTIONS, scheme)],
         VARIANT_MAPPINGS[fetch_or_fallback(VARIANT_OPTIONS, variant)]
       )
     end
 
     def call
-      render(Primer::BaseComponent.new(**@kwargs)) { content }
+      render(Primer::BaseComponent.new(**@system_arguments)) { content }
     end
   end
 end