primer_view_components 0.0.6 → 0.0.11

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,6 +10,17 @@ module Primer
     with_slot :footer, class_name: "Footer"
     with_slot :row, collection: true, class_name: "Row"
 
+    # @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 kwargs [Hash] <%= link_to_style_arguments_docs %>
     def initialize(**kwargs)
       @kwargs = kwargs
       @kwargs[:tag] = :div
@@ -23,8 +35,8 @@ module Primer
     end
 
     class Header < Primer::Slot
-
       attr_reader :kwargs
+      # @param kwargs [Hash] <%= link_to_style_arguments_docs %>
       def initialize(**kwargs)
         @kwargs = kwargs
         @kwargs[:tag] = :div
@@ -36,8 +48,8 @@ module Primer
     end
 
     class Body < Primer::Slot
-
       attr_reader :kwargs
+      # @param kwargs [Hash] <%= link_to_style_arguments_docs %>
       def initialize(**kwargs)
         @kwargs = kwargs
         @kwargs[:tag] = :div
@@ -49,8 +61,8 @@ module Primer
     end
 
     class Footer < Primer::Slot
-
       attr_reader :kwargs
+      # @param kwargs [Hash] <%= link_to_style_arguments_docs %>
       def initialize(**kwargs)
         @kwargs = kwargs
         @kwargs[:tag] = :div
@@ -62,8 +74,8 @@ module Primer
     end
 
     class Row < Primer::Slot
-
       attr_reader :kwargs
+      # @param kwargs [Hash] <%= link_to_style_arguments_docs %>
       def initialize(**kwargs)
         @kwargs = kwargs
         @kwargs[:tag] = :li

data/app/components/primer/box_component.rb

@@ -1,7 +1,9 @@
 # frozen_string_literal: true
 
 module Primer
+  # A basic wrapper component for most layout related needs.
   class BoxComponent < Primer::Component
+    # @param kwargs [Hash] <%= link_to_style_arguments_docs %>
     def initialize(**kwargs)
       @kwargs = kwargs
       @kwargs[:tag] = :div

data/app/components/primer/breadcrumb_component.rb

@@ -1,31 +1,20 @@
 # 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"
 
+    # @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 kwargs [Hash] <%= link_to_style_arguments_docs %>
     def initialize(**kwargs)
       @kwargs = kwargs
       @kwargs[:tag] = :nav
@@ -36,9 +25,13 @@ module Primer
       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
 
+      # @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 kwargs [Hash] <%= link_to_style_arguments_docs %>
       def initialize(href: nil, selected: false, **kwargs)
         @href, @kwargs = href, kwargs
 

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,6 +26,22 @@ 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,
@@ -34,19 +51,19 @@ module Primer
       **kwargs
     )
       @kwargs = kwargs
-      @kwargs[:tag] = fetch_or_fallback(TAG_OPTIONS, tag.to_sym, DEFAULT_TAG)
+      @kwargs[:tag] = fetch_or_fallback(TAG_OPTIONS, tag, DEFAULT_TAG)
 
       if @kwargs[:tag] == :a
         @kwargs[:role] = :button
       else
-        @kwargs[:type] = type.to_sym
+        @kwargs[:type] = type
       end
 
       @kwargs[: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)],
+        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

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,6 +10,10 @@ 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+")

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)
+    def initialize(overlay: NO_OVERLAY, 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)],
+        OVERLAY_MAPPINGS[fetch_or_fallback(OVERLAY_MAPPINGS.keys, overlay, NO_OVERLAY)],
         "details-reset" => reset
       )
     end

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

@@ -0,0 +1,14 @@
+<%= render Primer::BaseComponent.new(**@kwargs) do %>
+  <%= render(Primer::OcticonComponent.new(icon: @icon)) if @icon %>
+  <%= content %>
+  <% if @dismissible %>
+    <button class="flash-close js-flash-close" type="button" aria-label="Close">
+      <%= render(Primer::OcticonComponent.new(icon: "x")) %>
+    </button>
+  <% end %>
+  <% if actions.present? %>
+    <%= render Primer::BaseComponent.new(**actions.kwargs) do %>
+      <%= actions.content %>
+    <% end %>
+  <% end %>
+<% end %>

data/app/components/primer/flash_component.rb

@@ -0,0 +1,73 @@
+# 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
+
+    with_slot :actions, class_name: "Actions"
+
+    DEFAULT_VARIANT = :default
+    VARIANT_MAPPINGS = {
+      DEFAULT_VARIANT => "",
+      :warning => "flash-warn",
+      :danger => "flash-error",
+      :success => "flash-success"
+    }.freeze
+    # @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 kwargs [Hash] <%= link_to_style_arguments_docs %>
+    def initialize(full: false, spacious: false, dismissible: false, icon: nil, variant: DEFAULT_VARIANT, **kwargs)
+      @icon = icon
+      @dismissible = dismissible
+      @kwargs = kwargs
+      @kwargs[:tag] = :div
+      @kwargs[:classes] = class_names(
+        @kwargs[:classes],
+        "flash",
+        VARIANT_MAPPINGS[fetch_or_fallback(VARIANT_MAPPINGS.keys, variant, DEFAULT_VARIANT)],
+        "flash-full": full
+      )
+      @kwargs[:mb] ||= spacious ? 4 : nil
+    end
+
+    class Actions < ViewComponent::Slot
+      include ClassNameHelper
+
+      attr_reader :kwargs
+
+      # @param kwargs [Hash] <%= link_to_style_arguments_docs %>
+      def initialize(**kwargs)
+        @kwargs = kwargs
+        @kwargs[:tag] = :div
+        @kwargs[:classes] = class_names(@kwargs[:classes], "flash-action")
+      end
+    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,6 +29,22 @@ module Primer
     }.freeze
     VARIANT_OPTIONS = VARIANT_MAPPINGS.keys << nil
 
+    # @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 kwargs [Hash] <%= link_to_style_arguments_docs %>
     def initialize(title:, scheme: nil, variant: nil, **kwargs)
       @kwargs = kwargs
       @kwargs[:bg] = :blue if scheme.nil?

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,9 +12,25 @@ module Primer
     DEFAULT_SIDEBAR_COL = 3
     ALLOWED_SIDEBAR_COLS = (1..(MAX_COL - 1)).to_a.freeze
 
+    # @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 kwargs [Hash] <%= link_to_style_arguments_docs %>
     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)
+      @side = fetch_or_fallback(ALLOWED_SIDES, side, DEFAULT_SIDE)
       @responsive = responsive
       @kwargs[:classes] = class_names(
         "gutter-condensed gutter-lg",

data/app/components/primer/link_component.rb

@@ -1,7 +1,17 @@
 # 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
+    # @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 kwargs [Hash] <%= link_to_style_arguments_docs %>
     def initialize(href:, muted: false, **kwargs)
       @kwargs = kwargs
       @kwargs[:tag] = :a

data/app/components/primer/octicon_component.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module Primer
+  # Renders an [Octicon](https://primer.style/octicons/) with <%= link_to_style_arguments_docs %>.
+  class OcticonComponent < Primer::Component
+    include Primer::ClassNameHelper
+    include OcticonsHelper
+
+    SIZE_DEFAULT = :small
+    SIZE_MAPPINGS = {
+      SIZE_DEFAULT => 16,
+      :medium => 32,
+      :large => 64,
+    }.freeze
+    SIZE_OPTIONS = SIZE_MAPPINGS.keys
+
+    # @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_OPTIONS) %>
+    # @param kwargs [Hash] <%= link_to_style_arguments_docs %>
+    def initialize(icon:, size: SIZE_DEFAULT, **kwargs)
+      @icon, @kwargs = icon, kwargs
+
+      @kwargs[:class] = Primer::Classify.call(**@kwargs)[:class]
+      @kwargs[: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 = @kwargs.slice(:height, :width)
+      @kwargs = @kwargs.except(*Primer::Classify::VALID_KEYS, :classes).merge(octicon_helper_options)
+    end
+
+    def call
+      octicon(@icon, **@kwargs)
+    end
+  end
+end