primer_view_components 0.0.10 → 0.0.11

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f4ccf1dd55332ea7b350841d78e04a0f56a0f036749638c30041582500cc561c
-  data.tar.gz: f948087b2dba1cd217296a08260db95a8973cf8e58d4e1240a2c45295ef17e24
+  metadata.gz: befa90070fd7a8cd5a5668c8ac39697fb4baf39d11ebc50f938f72eb1805543a
+  data.tar.gz: c9b3abe81ae870566a2a2decf6135b8f13158842c43fd46b40346aba6fcc6e45
 SHA512:
-  metadata.gz: 2359e308fa78d78b5cb0f4e76791bfcd6a9714b7295320d04f293f0b7e0351c4fbad90a13743c61e9401de9c69c1269ee791167638715e7fafc594a47b8a242b
-  data.tar.gz: 2089d76d7cdef40b4bce9871d2b0ade0f492751ba057dc99e6fabc4654390656e0cdef57004931d66b1ea75f6189581dbf840bedbb7b89ee6d0fbfdb31d13136
+  metadata.gz: 16cbb49509d19431d5dba889847c350c5720b471452a62d5452de2ce454376826edc37628b5b65711255dbe4bd50357f7b7c0d158b2c595b15685db974e11607
+  data.tar.gz: aea1f3880d89157176c509eba04c7a79d9fd443e9f8ca8d5e3f40960e27ed94e100c69bfde39c86bba76471e76d6afca4f6ed7919d398e35b076a4ef5f659309

data/CHANGELOG.md

@@ -2,6 +2,12 @@
 
 ## main
 
+## 0.0.11
+
+* Renames DetailsComponent::OVERLAY_DEFAULT to DetailsComponent::NO_OVERLAY to more correctly describe its value.
+
+    *Justin Kenyon*
+
 ## 0.0.10
 
 * Add SpinnerComponent

data/README.md

@@ -8,182 +8,7 @@
 
 _Note: This library is in pre-release development and should not be considered stable._
 
-## Design philosophy
-
-Primer ViewComponents aims to mimic the API of [Primer Components](https://github.com/primer/components), while using [Primer CSS](https://github.com/primer/css) under the hood.
-
-## Installation
-
-In `Gemfile`, add:
-
-```ruby
-gem "primer_view_components"
-```
-
-In `config/application.rb`, add **after the application definition**
-
-```ruby
-require "primer/view_components/engine"
-```
-
-## Usage
-
-### Built-in styling arguments
-
-Primer components should be styled using the built-in arguments when possible. Most Primer utility classes for spacing, alignment, display, and colors have equivalent component arguments.
-
-Example label built with Primer CSS:
-
-```html
-<span title="Label: Suggested" class="Label Label--outline Label--outline-green ml-2 v-align-middle">Suggested</span>
-```
-
-The same label using `Primer::LabelComponent`:
-
-```erb
-<%= render Primer::LabelComponent.new(ml: 2, vertical_align: :middle, scheme: :green, title: "Label: Suggested") do %>
-  Suggested
-<% end %>
-```
-
-Some components have their own specific arguments, but they can all be styled with the following arguments.
-
-| Component argument | Primer class    | Example |
-| --------------- | --------------- | -------- |
-| `m`            | `m-<value>`     | `m: 4` → `.m-4` |
-| `my`            | `my-<value>`   | `my: 4` → `.my-4` |
-| `mx`            | `my-<value>`   | `mx: 4` → `.mx-4` |
-| `mt`            | `mt-<value>`   | `mt: 4` → `.mt-4` |
-| `mb`            | `mb-<value>`   | `mb: 4` → `.mb-4` |
-| `ml`            | `ml-<value>`   | `ml: 4` → `.ml-4` |
-| `mr`            | `mr-<value>`   | `mr: 4` → `.mr-4` |
-| `p`             | `p-<value>`    | `p: 4` → `.p-4` |
-| `py`            | `py-<value>`   | `py: 4` → `.py-4` |
-| `px`            | `py-<value>`   | `px: 4` → `.px-4` |
-| `pt`            | `pt-<value>`   | `pt: 4` → `.pt-4` |
-| `pb`            | `pb-<value>`   | `pb: 4` → `.pb-4` |
-| `pl`            | `pl-<value>`   | `pl: 4` → `.pl-4` |
-| `pr`            | `pr-<value>`   | `pr: 4` → `.pr-4` |
-| `pr`            | `pr-<value>`   | `pr: 4` → `.pr-4` |
-| `f`            | `f-<value>`   | `f: 4` → `.f-4` |
-| `color`            | `color-<value>`   | `color: :red_500` → `.color-red-500` |
-| `text`         | `text-<value>`   | `text: :green` → `.text-green` |
-| `bg`         | `bg-<value>`   | `bg: :blue_light` → `.bg-blue-light` |
-| `display`     | `d-<value>` | `display: :none` → `.d-none` |
-| `float`         | `float-<value>`   | `float: :right` → `.float-right` |
-| `vertical_align`         | `v-align-<value>`   | `vertical_align: :baseline` → `.v-align-baseline` |
-| `text_align`     | `text-<value>` | `text_align: :right` → `.text-right` |
-| `font_size`     | `f<value>` | `font_size: 4` → `.f4` |
-| `font_weight`     | `text-<value>` | `font_weight: :bold` → `.text-bold` |
-| `border`     | `border-<value>` | `border: :bottom` → `.border-bottom` |
-| `border_color`     | `border-<value>` | `border: :green` → `.border-green` |
-| `border_top`     | `border-top-<value>` | `border_top: 0` → `.border-top-0` |
-| `border_bottom`     | `border-bottom-<value>` | `border_bottom: 0` → `.border-bottom-0` |
-| `border_left`     | `border-left-<value>` | `border_left: 0` → `.border-left-0` |
-| `border_right`     | `border-right-<value>` | `border_right: 0` → `.border-right-0` |
-| `word_break`     | `wb-<value>` | `word_break: :break_all` → `.wb-break-all` |
-| `direction`     | `flex-<value>` | `direction: :row` → `.flex-row` |
-| `justify_content`    | `flex-justify-<value>` | `justify_content: :center` → `.flex-justify-center` |
-| `align_items`   | `flex-items-<value>` | `align_items: :baseline` → `.flex-items-baseline` |
-| `box_shadow` | `box-shadow-<value>` | `box_shadow: :medium` → `.box-shadow-medium` |
-
-#### Boolean arguments
-
-| Component arguments | True    | False |
-| -------------- | ------- | ------ |
-| `underline`   | `underline: true` → `.text-underline`  | `underline: false` → `.no-underline` |
-| `top`    | n/a | `top: false` → `.top-0`  |
-| `bottom` | n/a | `bottom: false` → `.bottom-0`  |
-| `left`   | n/a | `left: false` → `.left-0`  |
-| `right`  | n/a | `right: false` → `.right-0`  |
-
-#### Responsive arguments
-
-Different classes can be used for different breakpoints just like in Primer CSS. Simply use an array with the four values required for `[none, small, medium, large]`. If no breakpoint is needed for a breakpoint, pass `nil`.
-
-Example heading built with Primer CSS:
-
-```html
-<h1 class="mt-0 mt-lg-4">Hello world</h1>
-```
-
-The same label using `Primer::HeadingComponent`:
-
-```erb
-<%= render Primer::HeadingComponent.new(mt: [0, nil, nil, 4]) do %>
-  Hello world
-<% end %>
-```
-
-## Contributing
-
-Bug reports and pull requests are welcome on GitHub at [https://github.com/primer/view_components](https://github.com/primer/view_components). This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [Contributor Covenant](http://contributor-covenant.org) code of conduct.
-
-### Setting up
-
-Run
-
-```bash
-script/setup
-```
-
-To install all necessary dependencies.
-
-### Running tests
-
-To run the full test suite:
-
-```bash
-bundle exec rake
-```
-
-### Writing documentation
-
-Documentation is written as [YARD](https://yardoc.org/) comments directly in the source code, compiled into Markdown via `rake docs:build` and served by [Doctocat](https://github.com/primer/doctocat).
-
-### Storybook / Documentation
-
-To run Storybook and the documentation site, run:
-
-```bash
-script/dev
-```
-
-_Note: Overmind is required to run script/dev._
-
-### Developing with another app
-
-In your `Gemfile`, change:
-
-```ruby
-gem "primer_view_components"
-```
-
-to
-
-```ruby
-gem "primer_view_components", path: "path_to_the_gem" # e.g. path: "~/primer/view_components"
-```
-
-Then, `bundle install` to update references. You'll now be able to see changes from the gem without having to build it.
-Remember that restarting the Rails server is necessary to see changes, as the gem is loaded at boot time.
-
-To minimize the number of restarts, we recommend checking the component in Storybook first, and then when it's in a good state,
-you can check it in your app.
-
-### Documentation
-
-Document components with [YARD](https://yardoc.org/). Docs are published to [RubyDoc.info](https://rubydoc.info/github/primer/view_components).
-
-## Deploying to Heroku
-
-We have both `staging` and `production` environments. To deploy Storybook to Heroku, run the following in `#primer-view-components-ops`:
-
-```bash
-.deploy primer-view-components</branch> to <environment>
-```
-
-If no `branch` is passed, `main` will be deployed.
+Visit [https://view-components.primer.vercel.app/](https://view-components.primer.vercel.app/) to view documentation.
 
 ## License
 

data/app/components/primer/blankslate_component.rb

@@ -56,7 +56,7 @@ module Primer
     # @param title [String] Text that appears in a larger bold font.
     # @param title_tag [Symbol] HTML tag to use for title.
     # @param icon [String] Octicon icon to use at top of component.
-    # @param icon_size [Symbol] One of <%= Primer::OcticonComponent::SIZE_MAPPINGS.keys.map { |k| "`:#{k}`" }.to_sentence %>
+    # @param icon_size [Symbol] <%= one_of(Primer::OcticonComponent::SIZE_MAPPINGS.keys) %>
     # @param image_src [String] Image to display.
     # @param image_alt [String] Alt text for image.
     # @param description [String] Text that appears below the title. Typically a whole sentence.

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,

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/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, OVERLAY_DEFAULT)],
+        OVERLAY_MAPPINGS[fetch_or_fallback(OVERLAY_MAPPINGS.keys, overlay, NO_OVERLAY)],
         "details-reset" => reset
       )
     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,7 +14,35 @@ module Primer
       :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
@@ -33,6 +62,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/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,6 +12,22 @@ 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, DEFAULT_SIDE)

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

@@ -1,6 +1,7 @@
 # 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
@@ -13,6 +14,18 @@ module Primer
     }.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
 

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.rb

@@ -22,7 +22,7 @@ module Primer
     # @example 80|Large
     #   <%= render(Primer::SpinnerComponent.new(size: :large)) %>
     #
-    # @param size [Symbol] One of <%= Primer::SpinnerComponent::SIZE_OPTIONS.map { |k| "`:#{k}`" }.to_sentence(last_word_connector: ', or ') %>
+    # @param size [Symbol] <%= one_of(Primer::SpinnerComponent::SIZE_OPTIONS) %>
     def initialize(size: DEFAULT_SIZE, **kwargs)
       @kwargs = kwargs
       @kwargs[:tag] = :svg

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/lib/primer/view_components/version.rb

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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: primer_view_components
 version: !ruby/object:Gem::Version
-  version: 0.0.10
+  version: 0.0.11
 platform: ruby
 authors:
 - GitHub Open Source
-autorequire: 
+autorequire:
 bindir: bin
 cert_chain: []
-date: 2020-10-19 00:00:00.000000000 Z
+date: 2020-10-26 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -182,7 +182,7 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: 0.9.25
-description: 
+description:
 email:
 - opensource+primer_view_components@github.com
 executables: []
@@ -245,7 +245,7 @@ licenses:
 - MIT
 metadata:
   allowed_push_host: https://rubygems.org
-post_install_message: 
+post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -260,8 +260,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.0.3
-signing_key: 
+rubygems_version: 3.1.2
+signing_key:
 specification_version: 4
 summary: ViewComponents for the Primer Design System
 test_files: []