primer_view_components 0.0.6 → 0.0.11

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: cc85888949a3628a056ecc2b0d6ee97267a5adb688498f2268dda1e54bcd72ce
-  data.tar.gz: 915dcfcbc1033baf6c0c635cbdd37e759045bee86fc92c3fbe7671f316b3cb7c
+  metadata.gz: befa90070fd7a8cd5a5668c8ac39697fb4baf39d11ebc50f938f72eb1805543a
+  data.tar.gz: c9b3abe81ae870566a2a2decf6135b8f13158842c43fd46b40346aba6fcc6e45
 SHA512:
-  metadata.gz: 47d296a7d90be6d0bf8794e68c3042a7ed5f1a70e0acabbef88a2f094e485a59910b96ee212e4ae77cf24695621f28ff149dfb2f444d839a4e5905e8e40d25d2
-  data.tar.gz: db4e16e23b4ef0c65e1ba0457e99b7acf8ac95b403187e7dcf36692e2a4e5d678f8733655e5b8fbadecb00755a3b395dc3cd7d7c6247ce32260de6f6ee3ee3ff
+  metadata.gz: 16cbb49509d19431d5dba889847c350c5720b471452a62d5452de2ce454376826edc37628b5b65711255dbe4bd50357f7b7c0d158b2c595b15685db974e11607
+  data.tar.gz: aea1f3880d89157176c509eba04c7a79d9fd443e9f8ca8d5e3f40960e27ed94e100c69bfde39c86bba76471e76d6afca4f6ed7919d398e35b076a4ef5f659309

data/CHANGELOG.md

@@ -1,4 +1,46 @@
-# 0.0.6
+# CHANGELOG
+
+## 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
+
+    *Cole Bemis*
+
+## 0.0.9
+
+* BREAKING CHANGE: OcticonComponent no longer accepts `class` parameter; use `classes` instead.
+
+    *heynan0*
+
+## 0.0.8
+
+* Add support for border margins, such as: `border_top: 0`.
+
+    *Natasha Umer*
+
+* Add FlashComponent and OcticonComponent.
+
+    *Joel Hawksley*
+
+* BREAKING CHANGE: BlankslateComponent accepts `icon_size` instead of `icon_height`.
+
+    *Joel Hawksley*
+
+## 0.0.7
+
+* Use `octicons_helper` v11.0.0.
+
+    *Joel Hawksley*
+
+## 0.0.6
 
 * Updated the invalid class name error message
 
@@ -16,21 +58,19 @@
 
     *Manuel Puyol*
 
-## Breaking changes
-
-* Changed `DetailsComponent` summary and body to be slots
+* BREAKING CHANGE: Changed `DetailsComponent` summary and body to be slots
 
     *Manuel Puyol*
 
-# 0.0.5
+## 0.0.5
 
 * Add support for box_shadow
 * Add components:
-    * Popover
+  * Popover
 
     *Sarah Vessels*
 
-# 0.0.4
+## 0.0.4
 
 * Added support for mx: and my: :auto.
 
@@ -39,19 +79,20 @@
 * Added support for custom layout sizes.
 
     *Manuel Puyol*
-# 0.0.3
+
+## 0.0.3
 
 * Add support for responsive `float` style argument.
 
     *Joel Hawksley*
 
 * Add components:
-    * Avatar
-    * Blankslate
+  * Avatar
+  * Blankslate
 
     *Manuel Puyol, Ben Emdon*
 
-# 0.0.1
+## 0.0.1
 
 * Add initial gem configuration.
 
@@ -66,24 +107,24 @@
     *Manuel Puyol*
 
 * Add components:
-    * BorderBox
-    * Box
-    * Breadcrumb
-    * Button
-    * Counter
-    * Details
-    * Dropdown
-    * Flex
-    * FlexItem
-    * Heading
-    * Label
-    * Layout
-    * Link
-    * ProgressBar
-    * State
-    * Subhead
-    * Text
-    * TimelineItem
-    * UnderlineNav
+  * BorderBox
+  * Box
+  * Breadcrumb
+  * Button
+  * Counter
+  * Details
+  * Dropdown
+  * Flex
+  * FlexItem
+  * Heading
+  * Label
+  * Layout
+  * Link
+  * ProgressBar
+  * State
+  * Subhead
+  * Text
+  * TimelineItem
+  * UnderlineNav
 
     *Manuel Puyol*

data/README.md

@@ -8,164 +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` |
-| `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. 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
-```
-
-### Storybook
-
-*We recommend having [overmind](https://github.com/DarthSim/overmind) installed to run both rails and storybook, but it is not required.*
-
-To run storybook:
-
-```bash
-script/storybook
-```
-
-### 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).
+Visit [https://view-components.primer.vercel.app/](https://view-components.primer.vercel.app/) to view documentation.
 
 ## License
 

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
+  # for organizations or any other non-human avatars.
   class AvatarComponent < Primer::Component
     SMALL_THRESHOLD = 24
 
+    #
+    # @example 34|Default
+    #   <%= render(Primer::AvatarComponent.new(src: "http://placekitten.com/200/200", alt: "@kittenuser")) %>
+    #
+    # @param src [String] The source url of the avatar image
+    # @param alt [String] Passed through to alt on img tag
+    # @param size [Integer] Adds the avatar-small class if less than 24
+    # @param square [Boolean] Used to create a square avatar.
     def initialize(src:, alt:, size: 20, square: false, **kwargs)
       @kwargs = kwargs
       @kwargs[:tag] = :img

data/app/components/primer/base_component.rb

@@ -2,18 +2,15 @@
 
 module Primer
   # Base component used by other Primer components.
-  #
-  # tag(symbol): HTML tag name to be passed to tag.send(tag)
-  # class_names(string): CSS class name value to be concatenated with generated Primer CSS classes
-  # args(hash): Combination of arguments for classes_from_hash and content_tag
-  #
-  # Example usage:
-  # <%= render Primer::BaseComponent, tag: :a, href: "http://www.google.com", mt: 4 do %>Link<% end %>
-  # generates:
-  # <a href="http://www.google.com" class="mt-4">Link</a>
   class BaseComponent < Primer::Component
     TEST_SELECTOR_TAG = :test_selector
 
+    #
+    # @example 34|Default
+    #   <%= render(Primer::BaseComponent.new(tag: :a, href: "http://www.google.com", mt: 4)) { "Link" } %>
+    #
+    # @param tag [Symbol] HTML tag name to be passed to tag.send(tag)
+    # @param classes [String] CSS class name value to be concatenated with generated Primer CSS classes
     def initialize(tag:, classes: nil, **args)
       @tag = tag
       @result = Primer::Classify.call(**args.merge(classes: classes))
@@ -23,9 +20,7 @@ module Primer
     end
 
     def call
-      tag.public_send(
-        @tag, content, **@content_tag_args.merge(@result)
-      )
+      content_tag(@tag, content, **@content_tag_args.merge(@result))
     end
 
     private

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

@@ -1,13 +1,19 @@
 <%= render Primer::BaseComponent.new(**@kwargs) do %>
   <% if @icon.present? %>
-    <%= octicon @icon, height: @icon_height, class: "blankslate-icon" %>
+    <%= render(Primer::OcticonComponent.new(
+      icon: @icon,
+      size: @icon_size,
+      classes: "blankslate-icon"
+    )) %>
   <% end %>
 
   <% if @image_src.present? && @image_alt.present? %>
     <%= image_tag "#{@image_src}", class: "mb-3", size: "56x56", alt: "#{@image_alt}" %>
   <% end %>
 
-  <<%= @title_tag %> class="mb-1"><%= @title %></<%= @title_tag %>>
+  <% if @title.present? %>
+    <%= render Primer::BaseComponent.new(tag: @title_tag, mb: 1) do %><%= @title %><% end %>
+  <% end %>
 
   <% if @description.present? %>
     <p><%= @description %></p>

data/app/components/primer/blankslate_component.rb

@@ -1,126 +1,78 @@
 # frozen_string_literal: true
 
 module Primer
-  # Blankslates are for when there is a lack of content within a page or section. Use them as placeholders to tell users why something isn't there.
-  #
-  # ## Basic example
-  #
-  # The `Primer::BlankslateComponent` supports the following arguments to add a basic blankslate:
-  #
-  # 1. `title` (`String` required). Text that appears in a larger bold font.
-  # 2. `description` (`String` optional). Text that appears below the title. Typically a whole sentence.
-  #
-  # ```ruby
-  # <%= render Primer::BlankslateComponent.new(
-  #   title: "Title",
-  #   description: "Description",
-  # ) %>
-  # ```
-  #
-  # ## Icon or graphic (optional)
-  #
-  # Add an `icon` to give additional context. Please refer to the [Octicons](https://primer.style/octicons/) documentation to choose an icon.
-  #
-  # ```ruby
-  # <%= render Primer::BlankslateComponent.new(
-  #   icon: "octoface",
-  #   title: "Title",
-  #   description: "Description",
-  # ) %>
-  # ```
-  #
-  # Alternatively you can also add a graphic by providing a path (`image_src`) to an image instead.Also, make sure to add an alternative description (`image_alt`). It will be used for the `alt` tag.
-  #
-  # ```ruby
-  # <%= render Primer::BlankslateComponent.new(
-  #   image_src: "file.svg",
-  #   image_alt: "Description of the image",
-  #   title: "Title",
-  #   description: "Description",
-  # ) %>
-  # ```
-  #
-  # Both icon and graphic will appear above the title.
-  #
-  #
-  # ## Custom content (optional)
-  #
-  # You can add any custom content that typically is used instead of the description:
-  #
-  # ```ruby
-  # <%= render Primer::BlankslateComponent.new(
-  #   icon: "octoface",
-  #   title: "Title",
-  # ) do %>
-  #   <p>Your custom content here</p>
-  # <% end %>
-  # ```
-  #
-  # ## Action button (optional)
-  #
-  # You can provide an action button to help users replace the blankslate. The button will appear below the description and custom content. It takes the following arguments:
-  #
-  # - `button_text` (`String` optional). The text of the button.
-  # - `button_url` (`String` optional). The URL where the user will be taken after clicking the button.
-  #
-  # ```ruby
-  # <%= render Primer::BlankslateComponent.new(
-  #   icon: "book",
-  #   title: "Welcome to the mona wiki!",
-  #   description: "Wikis provide a place in your repository to lay out the roadmap of your project, show the current status, and document software better, together.",
-  #
-  #   button_text: "Create the first page",
-  #   button_url: "https://github.com/monalisa/mona/wiki/_new",
-  # ) %>
-  # ```
-  #
-  # ## Link (optional)
-  #
-  # Add an additional link to help users learn more about a feature. The link will be shown at the very bottom:
-  #
-  # - `link_text` (`String` optional). The text of the link.
-  # - `link_url` (`String` optional). The URL where the user will be taken after clicking the link.
-  #
-  # ```ruby
-  # <%= render Primer::BlankslateComponent.new(
-  #   icon: "book",
-  #   title: "Welcome to the mona wiki!",
-  #   description: "Wikis provide a place in your repository to lay out the roadmap of your project, show the current status, and document software better, together.",
-  #   button_text: "Create the first page",
-  #   button_url: "https://github.com/monalisa/mona/wiki/_new",
-  #   link_text: "Learn more about wikis",
-  #   link_url: "https://docs.github.com/en/github/building-a-strong-community/about-wikis",
-  # ) %>
-  # ```
-  #
-  # ## Variations (optional)
-  #
-  # There are a few variations of how the Blankslate appears:
-  #
-  # - `narrow` (`Boolean` optional). Adds a maximum width.
-  # - `large` (`Boolean` optional). Increaeses the font size.
-  # - `spacious` (`Boolean` optional). Adds extra padding.
-  #
-  # ```ruby
-  # <%= render Primer::BlankslateComponent.new(
-  #   icon: "book",
-  #   title: "Welcome to the mona wiki!",
-  #   description: "Wikis provide a place in your repository to lay out the roadmap of your project, show the current status, and document software better, together.",
-  #
-  #   narrow: true,
-  #   large: true,
-  #   spacious: true,
-  # ) %>
-  # ```
+  # 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.
   class BlankslateComponent < Primer::Component
+    #
+    # @example 150|Basic
+    #   <%= render Primer::BlankslateComponent.new(
+    #     title: "Title",
+    #     description: "Description",
+    #   ) %>
+    #
+    # @example 190|Icon|Add an `icon` to give additional context. Refer to the [Octicons](https://primer.style/octicons/) documentation to choose an icon.
+    #   <%= render Primer::BlankslateComponent.new(
+    #     icon: "octoface",
+    #     title: "Title",
+    #     description: "Description",
+    #   ) %>
+    #
+    # @example 150|Custom content|Pass custom content as a block in place of `description`.
+    #   <%= render Primer::BlankslateComponent.new(
+    #     title: "Title",
+    #   ) do %>
+    #     <em>Your custom content here</em>
+    #   <% end %>
+    #
+    # @example 270|Action button|Provide a button to guide users to take action from the blankslate. The button appears below the description and custom content.
+    #   <%= render Primer::BlankslateComponent.new(
+    #     icon: "book",
+    #     title: "Welcome to the mona wiki!",
+    #     description: "Wikis provide a place in your repository to lay out the roadmap of your project, show the current status, and document software better, together.",
+    #
+    #     button_text: "Create the first page",
+    #     button_url: "https://github.com/monalisa/mona/wiki/_new",
+    #   ) %>
+    #
+    # @example 225|Link|Add an additional link to help users learn more about a feature. The link will be shown at the very bottom:
+    #   <%= render Primer::BlankslateComponent.new(
+    #     icon: "book",
+    #     title: "Welcome to the mona wiki!",
+    #     description: "Wikis provide a place in your repository to lay out the roadmap of your project, show the current status, and document software better, together.",
+    #     link_text: "Learn more about wikis",
+    #     link_url: "https://docs.github.com/en/github/building-a-strong-community/about-wikis",
+    #   ) %>
+    #
+    # @example 340|Variations|There are a few variations of how the Blankslate appears: `narrow` adds a maximum width, `large` increases the font size, and `spacious` adds extra padding.
+    #   <%= render Primer::BlankslateComponent.new(
+    #     icon: "book",
+    #     title: "Welcome to the mona wiki!",
+    #     description: "Wikis provide a place in your repository to lay out the roadmap of your project, show the current status, and document software better, together.",
+    #     narrow: true,
+    #     large: true,
+    #     spacious: true,
+    #   ) %>
+    #
+    # @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) %>
+    # @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.
+    # @param button_text [String] The text of the button.
+    # @param button_url [String] The URL where the user will be taken after clicking the button.
+    # @param button_classes [String] Classes to apply to action button
+    # @param link_text [String] The text of the link.
+    # @param link_url [String] The URL where the user will be taken after clicking the link.
+    # @param narrow [Boolean] Adds a maximum width.
+    # @param large [Boolean] Increases the font size.
+    # @param spacious [Boolean] Adds extra padding.
     def initialize(
-      # required
-      title:,
-
-      # optional
+      title: "",
       title_tag: :h3,
       icon: "",
-      icon_height: 32,
+      icon_size: :medium,
       image_src: "",
       image_alt: " ",
       description: "",
@@ -138,7 +90,7 @@ module Primer
       **kwargs
     )
       @kwargs = kwargs
-      @kwargs[:tag] = :div
+      @kwargs[:tag] ||= :div
       @kwargs[:classes] = class_names(
         @kwargs[:classes],
         "blankslate",
@@ -149,7 +101,7 @@ module Primer
 
       @title_tag = title_tag
       @icon = icon
-      @icon_height = icon_height
+      @icon_size = icon_size
       @image_src = image_src
       @image_alt = image_alt
       @title = title