primer_view_components 0.0.35 → 0.0.40

data/app/components/primer/avatar_component.rb

@@ -1,9 +1,20 @@
 # frozen_string_literal: true
 
 module Primer
-  # Avatars are images used to represent users and organizations on GitHub.
-  # Use the default round avatar for users, and the `square` argument
+  # `Avatar` can be used to represent users and organizations on GitHub.
+  #
+  # - Use the default round avatar for users, and the `square` argument
   # for organizations or any other non-human avatars.
+  # - By default, `Avatar` will render a static `<img>`. To have `Avatar` function as a link, set the `href` which will wrap the `<img>` in a `<a>`.
+  # - Set `size` to update the height and width of the `Avatar` in pixels.
+  # - To stack multiple avatars together, use <%= link_to_component(Primer::AvatarStackComponent) %>.
+  #
+  # @accessibility
+  #   Images should have text alternatives that describe the information or function represented.
+  #   If the avatar functions as a link, provide alt text that helps convey the function. For instance,
+  #   if `Avatar` is a link to a user profile, the alt attribute should be `@kittenuser profile`
+  #   rather than `@kittenuser`.
+  #   [Learn more about best image practices (WAI Images)](https://www.w3.org/WAI/tutorials/images/)
   class AvatarComponent < Primer::Component
     status :beta
 
@@ -16,7 +27,15 @@ module Primer
     #   <%= render(Primer::AvatarComponent.new(src: "http://placekitten.com/200/200", alt: "@kittenuser", square: true)) %>
     #
     # @example Link
-    #   <%= render(Primer::AvatarComponent.new(href: "#", src: "http://placekitten.com/200/200", alt: "@kittenuser")) %>
+    #   <%= render(Primer::AvatarComponent.new(href: "#", src: "http://placekitten.com/200/200", alt: "@kittenuser profile")) %>
+    #
+    # @example With size
+    #   <%= render(Primer::AvatarComponent.new(src: "http://placekitten.com/200/200", alt: "@kittenuser", size: 16)) %>
+    #   <%= render(Primer::AvatarComponent.new(src: "http://placekitten.com/200/200", alt: "@kittenuser", size: 20)) %>
+    #   <%= render(Primer::AvatarComponent.new(src: "http://placekitten.com/200/200", alt: "@kittenuser", size: 24)) %>
+    #   <%= render(Primer::AvatarComponent.new(src: "http://placekitten.com/200/200", alt: "@kittenuser", size: 28)) %>
+    #   <%= render(Primer::AvatarComponent.new(src: "http://placekitten.com/200/200", alt: "@kittenuser", size: 32)) %>
+    #   <%= render(Primer::AvatarComponent.new(src: "http://placekitten.com/200/200", alt: "@kittenuser", size: 36)) %>
     #
     # @param src [String] The source url of the avatar image.
     # @param alt [String] Passed through to alt on img tag.

data/app/components/primer/avatar_stack_component.rb

@@ -1,13 +1,15 @@
 # frozen_string_literal: true
 
 module Primer
-  # Use AvatarStack to stack multiple avatars together.
+  # Use `AvatarStack` to stack multiple avatars together.
   class AvatarStackComponent < Primer::Component
     status :beta
 
     ALIGN_DEFAULT = :left
     ALIGN_OPTIONS = [ALIGN_DEFAULT, :right].freeze
 
+    DEFAULT_TAG = :div
+    TAG_OPTIONS = [DEFAULT_TAG, :span].freeze
     # Required list of stacked avatars.
     #
     # @param kwargs [Hash] The same arguments as <%= link_to_component(Primer::AvatarComponent) %>.
@@ -34,11 +36,12 @@ module Primer
     #     <%= c.avatar(src: "http://placekitten.com/200/200", alt: "@kittenuser") %>
     #   <% end  %>
     #
+    # @param tag [Symbol] <%= one_of(Primer::AvatarStackComponent::TAG_OPTIONS) %>
     # @param align [Symbol] <%= one_of(Primer::AvatarStackComponent::ALIGN_OPTIONS) %>
     # @param tooltipped [Boolean] Whether to add a tooltip to the stack or not.
     # @param body_arguments [Hash] Parameters to add to the Body. If `tooltipped` is set, has the same arguments as <%= link_to_component(Primer::TooltipComponent) %>.
     # @param system_arguments [Hash] <%= link_to_system_arguments_docs %>
-    def initialize(align: ALIGN_DEFAULT, tooltipped: false, body_arguments: {}, **system_arguments)
+    def initialize(tag: DEFAULT_TAG, align: ALIGN_DEFAULT, tooltipped: false, body_arguments: {}, **system_arguments)
       @align = fetch_or_fallback(ALIGN_OPTIONS, align, ALIGN_DEFAULT)
       @system_arguments = system_arguments
       @tooltipped = tooltipped
@@ -50,7 +53,7 @@ module Primer
         @body_arguments[:classes]
       )
 
-      @system_arguments[:tag] ||= :div
+      @system_arguments[:tag] = fetch_or_fallback(TAG_OPTIONS, tag, DEFAULT_TAG)
       @system_arguments[:classes] = class_names(
         "AvatarStack",
         system_arguments[:classes],

data/app/components/primer/base_button.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module Primer
+  # Use `BaseButton` to render an unstyled `<button>` tag that can be customized.
+  class BaseButton < Primer::Component
+    status :beta
+
+    DEFAULT_TAG = :button
+    TAG_OPTIONS = [DEFAULT_TAG, :a, :summary].freeze
+
+    DEFAULT_TYPE = :button
+    TYPE_OPTIONS = [DEFAULT_TYPE, :reset, :submit].freeze
+
+    # @example Block
+    #   <%= render(Primer::BaseButton.new(block: :true)) { "Block" } %>
+    #   <%= render(Primer::BaseButton.new(block: :true, scheme: :primary)) { "Primary block" } %>
+    #
+    # @param tag [Symbol] <%= one_of(Primer::BaseButton::TAG_OPTIONS) %>
+    # @param type [Symbol] <%= one_of(Primer::BaseButton::TYPE_OPTIONS) %>
+    # @param block [Boolean] Whether button is full-width with `display: block`.
+    # @param system_arguments [Hash] <%= link_to_system_arguments_docs %>
+    def initialize(
+      tag: DEFAULT_TAG,
+      type: DEFAULT_TYPE,
+      block: false,
+      **system_arguments
+    )
+      @system_arguments = system_arguments
+      @system_arguments[:tag] = fetch_or_fallback(TAG_OPTIONS, tag, DEFAULT_TAG)
+
+      if @system_arguments[:tag] == :button
+        @system_arguments[:type] = fetch_or_fallback(TYPE_OPTIONS, type, DEFAULT_TYPE)
+      else
+        @system_arguments[:role] = :button
+      end
+
+      @system_arguments[:classes] = class_names(
+        system_arguments[:classes],
+        "btn-block" => block
+      )
+    end
+
+    def call
+      render(Primer::BaseComponent.new(**@system_arguments)) { content }
+    end
+  end
+end

data/app/components/primer/base_component.rb

@@ -69,13 +69,15 @@ module Primer
     #
     # | Name | Type | Description |
     # | :- | :- | :- |
-    # | `align_items` | Symbol | <%= one_of([:flex_start, :flex_end, :center, :baseline, :stretch]) %> |
-    # | `align_self` | Symbol | <%= one_of([:auto, :start, :end, :center, :baseline, :stretch]) %> |
+    # | `align_items` | Symbol | <%= one_of(Primer::Classify::Flex::ALIGN_ITEMS_VALUES) %> |
+    # | `align_self` | Symbol | <%= one_of(Primer::Classify::Flex::ALIGN_SELF_VALUES) %> |
+    # | `direction` | Symbol | <%= one_of(Primer::Classify::Flex::DIRECTION_VALUES) %> |
+    # | `flex` | Integer, Symbol | <%= one_of(Primer::Classify::Flex::FLEX_VALUES) %> |
     # | `flex_grow` | Integer | To enable, set to `0`. |
     # | `flex_shrink` | Integer | To enable, set to `0`. |
-    # | `flex` | Integer, Symbol | <%= one_of([1, :auto]) %> |
-    # | `justify_content` | Symbol | <%= one_of([:flex_start, :flex_end, :center, :space_between, :space_around]) %> |
-    # | `width` | Symbol | <%= one_of([:fit, :fill]) %> |
+    # | `flex_wrap` | Symbol | <%= one_of(Primer::Classify::Flex::WRAP_MAPPINGS.keys) %> |
+    # | `justify_content` | Symbol | <%= one_of(Primer::Classify::Flex::JUSTIFY_CONTENT_VALUES) %> |
+    # | `width` | Symbol | <%= one_of([:fit]) %> |
     #
     # ## Grid
     #
@@ -87,8 +89,8 @@ module Primer
     #
     # | Name | Type | Description |
     # | :- | :- | :- |
-    # | `display` | Symbol | <%= one_of([:none, :block, :flex, :inline, :inline_block, :table, :table_cell]) %> |
-    # | `height` | Symbol | <%= one_of([:fit, :fill]) %> |
+    # | `display` | Symbol | <%= one_of([:none, :block, :flex, :inline, :inline_block, :inline_flex, :table, :table_cell]) %> |
+    # | `height` | Symbol | <%= one_of([:fit]) %> |
     # | `hide` | Symbol | Hide the element at a specific breakpoint. <%= one_of([:sm, :md, :lg, :xl]) %> |
     # | `v` | Symbol | Visibility. <%= one_of([:hidden, :visible]) %> |
     # | `vertical_align` | Symbol | <%= one_of([:baseline, :top, :middle, :bottom, :text_top, :text_bottom]) %> |
@@ -138,7 +140,6 @@ module Primer
     # | Name | Type | Description |
     # | :- | :- | :- |
     # | classes | String | CSS class name value to be concatenated with generated Primer CSS classes. |
-    # | tag | Symbol | HTML tag name to be passed to `content_tag`. |
     # | test_selector | String | Adds `data-test-selector='given value'` in non-Production environments for testing purposes. |
     def initialize(tag:, classes: nil, **system_arguments)
       @tag = tag

data/app/components/primer/blankslate_component.rb

@@ -1,7 +1,10 @@
 # frozen_string_literal: true
 
 module Primer
-  # Use Primer::BlankslateComponent when there is a lack of content within a page or section. Use as placeholder to tell users why something isn't there.
+  # Use `Blankslate` when there is a lack of content within a page or section. Use as placeholder to tell users why something isn't there.
+  # @accessibility
+  #   `Blankslate` renders an `<h3>` element for the title by default. Update the heading level based on what is appropriate for your page hierarchy by setting `title_tag`.
+  #   <%= link_to_heading_practices %>
   class BlankslateComponent < Primer::Component
     status :beta
 
@@ -108,7 +111,7 @@ module Primer
       **system_arguments
     )
       @system_arguments = system_arguments
-      @system_arguments[:tag] ||= :div
+      @system_arguments[:tag] = :div
       @system_arguments[:classes] = class_names(
         @system_arguments[:classes],
         "blankslate",

data/app/components/primer/border_box_component.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module Primer
-  # BorderBox is a Box component with a border.
+  # `BorderBox` is a Box component with a border.
   class BorderBoxComponent < Primer::Component
     status :beta
 

data/app/components/primer/box_component.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module Primer
-  # A basic wrapper component for most layout related needs.
+  # `Box` is a basic wrapper component for most layout related needs.
   class BoxComponent < Primer::Component
     status :stable
 

data/app/components/primer/breadcrumb_component.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 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.
+  # Use `Breadcrumb` 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
     status :beta
 

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

@@ -0,0 +1,9 @@
+<%= render Primer::BaseButton.new(**@system_arguments) do %>
+  <%= icon %>
+  <%= content %>
+  <%= counter %>
+
+  <% if @caret %>
+    <%= primer_octicon("triangle-down") %>
+  <% end %>
+<% end %>

data/app/components/primer/button_component.rb

@@ -1,16 +1,19 @@
 # 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.
+  # Use `Button` for actions (e.g. in forms). Use links for destinations, or moving from one page to another.
   class ButtonComponent < Primer::Component
     status :beta
 
     DEFAULT_SCHEME = :default
+    LINK_SCHEME = :link
     SCHEME_MAPPINGS = {
       DEFAULT_SCHEME => "",
       :primary => "btn-primary",
       :danger => "btn-danger",
-      :outline => "btn-outline"
+      :outline => "btn-outline",
+      :invisible => "btn-invisible",
+      LINK_SCHEME => "btn-link"
     }.freeze
     SCHEME_OPTIONS = SCHEME_MAPPINGS.keys
 
@@ -22,56 +25,90 @@ module Primer
     }.freeze
     VARIANT_OPTIONS = VARIANT_MAPPINGS.keys
 
-    DEFAULT_TAG = :button
-    TAG_OPTIONS = [DEFAULT_TAG, :a, :summary].freeze
+    # Icon to be rendered in the button.
+    #
+    # @param system_arguments [Hash] Same arguments as <%= link_to_component(Primer::OcticonComponent) %>.
+    renders_one :icon, Primer::OcticonComponent
 
-    DEFAULT_TYPE = :button
-    TYPE_OPTIONS = [DEFAULT_TYPE, :reset, :submit].freeze
+    # Counter to be rendered in the button.
+    #
+    # @param system_arguments [Hash] Same arguments as <%= link_to_component(Primer::CounterComponent) %>.
+    renders_one :counter, Primer::CounterComponent
 
     # @example Schemes
     #   <%= render(Primer::ButtonComponent.new) { "Default" } %>
     #   <%= render(Primer::ButtonComponent.new(scheme: :primary)) { "Primary" } %>
     #   <%= render(Primer::ButtonComponent.new(scheme: :danger)) { "Danger" } %>
     #   <%= render(Primer::ButtonComponent.new(scheme: :outline)) { "Outline" } %>
+    #   <%= render(Primer::ButtonComponent.new(scheme: :invisible)) { "Invisible" } %>
+    #   <%= render(Primer::ButtonComponent.new(scheme: :link)) { "Link" } %>
     #
     # @example Variants
     #   <%= render(Primer::ButtonComponent.new(variant: :small)) { "Small" } %>
     #   <%= render(Primer::ButtonComponent.new(variant: :medium)) { "Medium" } %>
     #   <%= render(Primer::ButtonComponent.new(variant: :large)) { "Large" } %>
     #
+    # @example Block
+    #   <%= render(Primer::ButtonComponent.new(block: :true)) { "Block" } %>
+    #   <%= render(Primer::ButtonComponent.new(block: :true, scheme: :primary)) { "Primary block" } %>
+    #
+    # @example With icons
+    #   <%= render(Primer::ButtonComponent.new) do |c| %>
+    #     <% c.icon(icon: :star) %>
+    #     Button
+    #   <% end %>
+    #
+    # @example With counter
+    #   <%= render(Primer::ButtonComponent.new) do |c| %>
+    #     <% c.counter(count: 15) %>
+    #     Button
+    #   <% end %>
+    #
+    # @example With icons and counter
+    #   <%= render(Primer::ButtonComponent.new) do |c| %>
+    #     <% c.icon(icon: :star) %>
+    #     <% c.counter(count: 15) %>
+    #     Button
+    #   <% end %>
+    #
+    # @example With caret
+    #   <%= render(Primer::ButtonComponent.new(caret: true)) do %>
+    #     Button
+    #   <% end %>
+    #
     # @param scheme [Symbol] <%= one_of(Primer::ButtonComponent::SCHEME_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 tag [Symbol] <%= one_of(Primer::BaseButton::TAG_OPTIONS) %>
+    # @param type [Symbol] <%= one_of(Primer::BaseButton::TYPE_OPTIONS) %>
     # @param group_item [Boolean] Whether button is part of a ButtonGroup.
+    # @param block [Boolean] Whether button is full-width with `display: block`.
+    # @param caret [Boolean] Whether or not to render a caret.
     def initialize(
       scheme: DEFAULT_SCHEME,
       variant: DEFAULT_VARIANT,
-      tag: DEFAULT_TAG,
-      type: DEFAULT_TYPE,
       group_item: false,
+      block: false,
+      caret: false,
       **system_arguments
     )
-      @system_arguments = system_arguments
-      @system_arguments[:tag] = fetch_or_fallback(TAG_OPTIONS, tag, DEFAULT_TAG)
-
-      if @system_arguments[:tag] == :a
-        @system_arguments[:role] = :button
-      else
-        @system_arguments[:type] = type
-      end
+      @scheme = scheme
+      @caret = caret
 
+      @system_arguments = system_arguments
       @system_arguments[:classes] = class_names(
-        "btn",
         system_arguments[:classes],
         SCHEME_MAPPINGS[fetch_or_fallback(SCHEME_OPTIONS, scheme, DEFAULT_SCHEME)],
         VARIANT_MAPPINGS[fetch_or_fallback(VARIANT_OPTIONS, variant, DEFAULT_VARIANT)],
+        "btn" => !link?,
+        "btn-block" => block,
         "BtnGroup-item" => group_item
       )
     end
 
-    def call
-      render(Primer::BaseComponent.new(**@system_arguments)) { content }
+    private
+
+    def link?
+      @scheme == LINK_SCHEME
     end
   end
 end

data/app/components/primer/button_group.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module Primer
+  # Use `ButtonGroup` to render a series of buttons.
+  class ButtonGroup < Primer::Component
+    status :beta
+
+    # Required list of buttons to be rendered.
+    #
+    # @param kwargs [Hash] The same arguments as <%= link_to_component(Primer::ButtonComponent) %> except for `variant` and `group_item`.
+    renders_many :buttons, lambda { |**kwargs|
+      kwargs[:group_item] = true
+      kwargs[:variant] = @variant
+
+      Primer::ButtonComponent.new(**kwargs)
+    }
+
+    # @example Default
+    #
+    #   <%= render(Primer::ButtonGroup.new) do |component| %>
+    #     <% component.button { "Default" } %>
+    #     <% component.button(scheme: :primary) { "Primary" } %>
+    #     <% component.button(scheme: :danger) { "Danger" } %>
+    #     <% component.button(scheme: :outline) { "Outline" } %>
+    #     <% component.button(classes: "my-class") { "Custom class" } %>
+    #   <% end %>
+    #
+    # @example Variants
+    #
+    #   <%= render(Primer::ButtonGroup.new(variant: :small)) do |component| %>
+    #     <% component.button { "Default" } %>
+    #     <% component.button(scheme: :primary) { "Primary" } %>
+    #     <% component.button(scheme: :danger) { "Danger" } %>
+    #     <% component.button(scheme: :outline) { "Outline" } %>
+    #   <% end %>
+    #
+    #   <%= render(Primer::ButtonGroup.new(variant: :large)) do |component| %>
+    #     <% component.button { "Default" } %>
+    #     <% component.button(scheme: :primary) { "Primary" } %>
+    #     <% component.button(scheme: :danger) { "Danger" } %>
+    #     <% component.button(scheme: :outline) { "Outline" } %>
+    #   <% end %>
+    #
+    # @param variant [Symbol] <%= one_of(Primer::ButtonComponent::VARIANT_OPTIONS) %>
+    # @param system_arguments [Hash] <%= link_to_system_arguments_docs %>
+    def initialize(variant: Primer::ButtonComponent::DEFAULT_VARIANT, **system_arguments)
+      @variant = variant
+      @system_arguments = system_arguments
+      @system_arguments[:tag] = :div
+
+      @system_arguments[:classes] = class_names(
+        "BtnGroup",
+        system_arguments[:classes]
+      )
+    end
+
+    def render?
+      buttons.any?
+    end
+  end
+end

data/app/components/primer/button_marketing_component.rb

@@ -1,7 +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.
+  # Use `ButtonMarketing` for actions (e.g. in forms). Use links for destinations, or moving from one page to another.
   class ButtonMarketingComponent < Primer::Component
     DEFAULT_SCHEME = :default
     SCHEME_MAPPINGS = {
@@ -50,14 +50,9 @@ module Primer
       **system_arguments
     )
       @system_arguments = system_arguments
+      @system_arguments[:block] = false
       @system_arguments[:tag] = fetch_or_fallback(TAG_OPTIONS, tag, DEFAULT_TAG)
-
-      if @system_arguments[:tag] == :a
-        @system_arguments[:role] = :button
-      else
-        @system_arguments[:type] = fetch_or_fallback(TYPE_OPTIONS, type, DEFAULT_TYPE)
-      end
-
+      @system_arguments[:type] = fetch_or_fallback(TYPE_OPTIONS, type, DEFAULT_TYPE)
       @system_arguments[:classes] = class_names(
         "btn-mktg",
         SCHEME_MAPPINGS[fetch_or_fallback(SCHEME_OPTIONS, scheme, DEFAULT_SCHEME)],
@@ -67,7 +62,7 @@ module Primer
     end
 
     def call
-      render(Primer::BaseComponent.new(**@system_arguments)) { content }
+      render(Primer::BaseButton.new(**@system_arguments)) { content }
     end
   end
 end