primer_view_components 0.0.7 → 0.0.12

data/app/components/primer/popover_component.rb

@@ -1,12 +1,46 @@
 # 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"
 
+    # @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 kwargs [Hash] <%= link_to_style_arguments_docs %>
     def initialize(**kwargs)
       @kwargs = kwargs
       @kwargs[:tag] ||= :div
@@ -24,6 +58,7 @@ module Primer
     end
 
     class Heading < ViewComponent::Slot
+      # @param kwargs [Hash] <%= link_to_style_arguments_docs %>
       def initialize(**kwargs)
         @kwargs = kwargs
         @kwargs[:mb] ||= 2
@@ -52,6 +87,9 @@ module Primer
         :top_right => "Popover-message--top-right"
       }.freeze
 
+      # @param caret [Symbol] <%= one_of(Primer::PopoverComponent::Body::CARET_MAPPINGS.keys) %>
+      # @param large [Boolean] Whether to use the large version of the component.
+      # @param kwargs [Hash] <%= link_to_style_arguments_docs %>
       def initialize(caret: CARET_DEFAULT, large: false, **kwargs)
         @kwargs = kwargs
         @kwargs[:classes] = class_names(

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,8 +16,31 @@ module Primer
     }.freeze
 
     SIZE_OPTIONS = SIZE_MAPPINGS.keys
-
-    def initialize(size: SIZE_DEFAULT, percentage: 0, **kwargs)
+    # @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 kwargs [Hash] <%= link_to_style_arguments_docs %>
+    def initialize(size: SIZE_DEFAULT, **kwargs)
       @kwargs = kwargs
       @kwargs[:classes] = class_names(
         @kwargs[:classes],
@@ -52,6 +59,9 @@ module Primer
       include ClassNameHelper
       attr_reader :kwargs
 
+      # @param percentage [Integer] Percentage completion of item.
+      # @param bg [Symbol] Color of item.
+      # @param kwargs [Hash] <%= link_to_style_arguments_docs %>
       def initialize(percentage: 0, bg: :green, **kwargs)
         @percentage = percentage
         @kwargs = kwargs

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(**@kwargs) 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_OPTIONS) %>
+    def initialize(size: DEFAULT_SIZE, style: DEFAULT_STYLE, **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
+      @kwargs[: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,6 +22,24 @@ 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 kwargs [Hash] <%= link_to_style_arguments_docs %>
     def initialize(
       title:,
       color: COLOR_DEFAULT,

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,6 +9,46 @@ module Primer
     with_slot :actions, class_name: "Actions"
     with_slot :description, class_name: "Description"
 
+    # @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 kwargs [Hash] <%= link_to_style_arguments_docs %>
     def initialize(spacious: false, hide_border: false, **kwargs)
       @kwargs = kwargs
 
@@ -51,6 +72,8 @@ module Primer
 
       attr_reader :kwargs
 
+      # @param danger [Boolean] Whether to style the heading as dangerous.
+      # @param kwargs [Hash] <%= link_to_style_arguments_docs %>
       def initialize(danger: false, **kwargs)
         @kwargs = kwargs
         @kwargs[:tag] ||= :div
@@ -67,6 +90,7 @@ module Primer
 
       attr_reader :kwargs
 
+      # @param kwargs [Hash] <%= link_to_style_arguments_docs %>
       def initialize(**kwargs)
         @kwargs = kwargs
         @kwargs[:tag] = :div
@@ -79,6 +103,7 @@ module Primer
 
       attr_reader :kwargs
 
+      # @param kwargs [Hash] <%= link_to_style_arguments_docs %>
       def initialize(**kwargs)
         @kwargs = kwargs
         @kwargs[:tag] = :div

data/app/components/primer/text_component.rb

@@ -1,7 +1,13 @@
 # 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
+    # @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 kwargs [Hash] <%= link_to_style_arguments_docs %>
     def initialize(**kwargs)
       @kwargs = kwargs
       @kwargs[:tag] ||= :span

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
 
@@ -9,6 +10,18 @@ module Primer
     with_slot :body, class_name: "Body"
 
     attr_reader :kwargs
+
+    # @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 kwargs [Hash] <%= link_to_style_arguments_docs %>
     def initialize(condensed: false, **kwargs)
       @kwargs = kwargs
       @kwargs[:tag] = :div
@@ -25,6 +38,12 @@ module Primer
 
     class Avatar < Primer::Slot
       attr_reader :kwargs, :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 kwargs [Hash] <%= link_to_style_arguments_docs %>
       def initialize(alt: nil, src: nil, size: 40, square: true, **kwargs)
         @alt = alt
         @src = src
@@ -42,6 +61,9 @@ module Primer
 
     class Badge < Primer::Slot
       attr_reader :kwargs, :icon
+
+      # @param icon [String] Name of [Octicon](https://primer.style/octicons/) to use.
+      # @param kwargs [Hash] <%= link_to_style_arguments_docs %>
       def initialize(icon: nil, **kwargs)
         @icon = icon
 
@@ -56,6 +78,8 @@ module Primer
 
     class Body < Primer::Slot
       attr_reader :kwargs
+
+      # @param kwargs [Hash] <%= link_to_style_arguments_docs %>
       def initialize(**kwargs)
         @kwargs = kwargs
         @kwargs[:tag] = :div

data/app/components/primer/view_components.rb

@@ -33,14 +33,17 @@ require_relative "button_component"
 require_relative "counter_component"
 require_relative "details_component"
 require_relative "dropdown_menu_component"
+require_relative "flash_component"
 require_relative "flex_component"
 require_relative "flex_item_component"
 require_relative "heading_component"
 require_relative "label_component"
 require_relative "layout_component"
 require_relative "link_component"
+require_relative "octicon_component"
 require_relative "popover_component"
 require_relative "progress_bar_component"
+require_relative "spinner_component"
 require_relative "state_component"
 require_relative "subhead_component"
 require_relative "text_component"

data/lib/primer/classify.rb

@@ -78,11 +78,13 @@ module Primer
       }
     }.freeze
     BORDER_KEYS = [:border, :border_color].freeze
+    BORDER_MARGIN_KEYS = [:border_top, :border_bottom, :border_left, :border_right].freeze
     TYPOGRAPHY_KEYS = [:font_size].freeze
     VALID_KEYS = (
       CONCAT_KEYS +
       BOOLEAN_MAPPINGS.keys +
       BORDER_KEYS +
+      BORDER_MARGIN_KEYS +
       TYPOGRAPHY_KEYS +
       TEXT_KEYS +
       [
@@ -196,6 +198,8 @@ module Primer
               memo[:classes] << "wb-#{dasherized_val}"
             elsif BORDER_KEYS.include?(key)
               memo[:classes] << "border-#{dasherized_val}"
+            elsif BORDER_MARGIN_KEYS.include?(key)
+              memo[:classes] << "#{key.to_s.dasherize}-#{val}"
             elsif key == DIRECTION_KEY
               memo[:classes] << "flex#{breakpoint}-#{dasherized_val}"
             elsif key == JUSTIFY_CONTENT_KEY

data/lib/primer/view_components/version.rb

@@ -5,7 +5,7 @@ module Primer
     module VERSION
       MAJOR = 0
       MINOR = 0
-      PATCH = 7
+      PATCH = 12
 
       STRING = [MAJOR, MINOR, PATCH].join(".")
     end