primer_view_components 0.0.8 → 0.0.13

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 25626f31190d4622e822db5eb8f435f103c0a77668cb78c1db16eec60ac4dfb9
-  data.tar.gz: e551785879e69a0bd7c2ae62a97a39f311dc3dbc415bc5dade637d97fa297910
+  metadata.gz: 055f773c8e99df5c9bce23d6a5199e71148d0331d6abe6c02fd1f16321a54130
+  data.tar.gz: e5310f927e76533daa46918acb24b48ea7bdd684a8f8e4c9090e3545a2e7f3fd
 SHA512:
-  metadata.gz: 6a77219748e0c7018f789df844cd6f6e83159b2fef82a5b81985c277d0427d85442e4e14c6f9934e387afc3f1d2291f31a3d88c9630c8f4910bae992d39a0188
-  data.tar.gz: 15b0b2a9faa1603f57d263a2a6b18f2eb4e1aa325d8c261bfce9f803571ae9a5075b1d51f8a5f3bf31bc7f12662dbe914f7380f71518fe6896b947f2d000757b
+  metadata.gz: e6b7159b56e4a0674a7ec68e4aa0666bb2a3e3cb5ef7b90e8c418149200af1255789adc87e4b3955a9a2d6e97afb9ebe2746928ccb32ece3395c28de315206dc
+  data.tar.gz: cc962a06f62249016eccfd224ab3655117ac193fa7f6ebb40aff91212690464047f95e2822bf4b5c8ae83d8c82df02e955f0c8ffc350e9aed85c313623388a61

data/CHANGELOG.md

@@ -1,6 +1,38 @@
-# main
+# CHANGELOG
 
-# 0.0.8
+## main
+
+## 0.0.13
+
+* Add support for `xl` breakpoint.
+
+    *Joel Hawksley*
+
+## 0.0.12
+
+* Adds support for disabling inline box-sizing style for `SpinnerComponent` via style parameter `Primer::SpinnerComponent.new(style: nil)`.
+
+    *Chris Wilson*
+
+## 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`.
 
@@ -10,19 +42,17 @@
 
     *Joel Hawksley*
 
-## Breaking changes
-
-* BlankslateComponent accepts `icon_size` instead of `icon_height`.
+* BREAKING CHANGE: BlankslateComponent accepts `icon_size` instead of `icon_height`.
 
     *Joel Hawksley*
 
-# 0.0.7
+## 0.0.7
 
 * Use `octicons_helper` v11.0.0.
 
     *Joel Hawksley*
 
-# 0.0.6
+## 0.0.6
 
 * Updated the invalid class name error message
 
@@ -40,21 +70,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.
 
@@ -63,19 +91,20 @@
 * Added support for custom layout sizes.
 
     *Manuel Puyol*
-# 0.0.3
 
-* Add support for responsive `float` style argument.
+## 0.0.3
+
+* Add support for responsive `float` system argument.
 
     *Joel Hawksley*
 
 * Add components:
-    * Avatar
-    * Blankslate
+  * Avatar
+  * Blankslate
 
     *Manuel Puyol, Ben Emdon*
 
-# 0.0.1
+## 0.0.1
 
 * Add initial gem configuration.
 
@@ -90,24 +119,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,168 +8,9 @@
 
 _Note: This library is in pre-release development and should not be considered stable._
 
-## Design philosophy
+## Documentation
 
-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. 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://primer.style/view-components/](https://primer.style/view-components//) to view documentation.
 
 ## License
 

data/app/components/primer/avatar_component.rb

@@ -1,28 +1,39 @@
 # 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
 
-    def initialize(src:, alt:, size: 20, square: false, **kwargs)
-      @kwargs = kwargs
-      @kwargs[:tag] = :img
-      @kwargs[:src] = src
-      @kwargs[:alt] = alt
-      @kwargs[:size] = size
-      @kwargs[:height] = size
-      @kwargs[:width] = size
+    #
+    # @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, **system_arguments)
+      @system_arguments = system_arguments
+      @system_arguments[:tag] = :img
+      @system_arguments[:src] = src
+      @system_arguments[:alt] = alt
+      @system_arguments[:size] = size
+      @system_arguments[:height] = size
+      @system_arguments[:width] = size
 
-      @kwargs[:classes] = class_names(
+      @system_arguments[:classes] = class_names(
         "avatar",
-        kwargs[:classes],
+        system_arguments[:classes],
         "avatar--small" => size < SMALL_THRESHOLD,
         "CircleBadge" => !square
       )
     end
 
     def call
-      render(Primer::BaseComponent.new(**@kwargs)) { content }
+      render(Primer::BaseComponent.new(**@system_arguments)) { content }
     end
   end
 end

data/app/components/primer/base_component.rb

@@ -1,25 +1,70 @@
 # frozen_string_literal: true
 
 module Primer
-  # Base component used by other Primer components.
+  # All Primer ViewComponents accept a standard set of options called System Arguments, mimicking the [styled-system API](https://styled-system.com/table) [used by Primer React](https://primer.style/components/system-props).
   #
-  # 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
+  # Under the hood, System Arguments are [mapped](https://github.com/primer/view_components/blob/main/lib/primer/classify.rb) to Primer CSS classes, with any remaining options passed to Rails' [`content_tag`](https://api.rubyonrails.org/classes/ActionView/Helpers/TagHelper.html#method-i-content_tag).
+  #
+  # ## Responsive values
+  #
+  # To apply different values across responsive breakpoints, pass an array with up to five values in the order `[default, small, medium, large, xlarge]`. To skip a breakpoint, pass `nil`.
+  #
+  # For example:
+  #
+  # ```erb
+  # <%= render Primer::HeadingComponent.new(mt: [0, nil, nil, 4, 2]) do %>
+  #   Hello world
+  # <% end %>
+  # ```
+  #
+  # Renders:
+  #
+  # ```html
+  # <h1 class="mt-0 mt-lg-4 mt-xl-2">Hello world</h1>
+  # ```
   #
-  # 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
 
-    def initialize(tag:, classes: nil, **args)
+    # @param m [Integer] Margin. <%= one_of((-6..6).to_a) %>
+    # @param mt [Integer] Margin left. <%= one_of((-6..6).to_a) %>
+    # @param mr [Integer] Margin right. <%= one_of((-6..6).to_a) %>
+    # @param mb [Integer] Margin bottom. <%= one_of((-6..6).to_a) %>
+    # @param ml [Integer] Margin left. <%= one_of((-6..6).to_a) %>
+    # @param mx [Integer] Horizontal margins. <%= one_of((-6..6).to_a + [:auto]) %>
+    # @param my [Integer] Vertical margins. <%= one_of((-6..6).to_a) %>
+    # @param m [Integer] Padding. <%= one_of((0..6).to_a) %>
+    # @param mt [Integer] Padding left. <%= one_of((0..6).to_a) %>
+    # @param mr [Integer] Padding right. <%= one_of((0..6).to_a) %>
+    # @param mb [Integer] Padding bottom. <%= one_of((0..6).to_a) %>
+    # @param ml [Integer] Padding left. <%= one_of((0..6).to_a) %>
+    # @param mx [Integer] Horizontal padding. <%= one_of((0..6).to_a) %>
+    # @param my [Integer] Vertical padding. <%= one_of((0..6).to_a) %>
+    #
+    # @param position [Symbol] <%= one_of([:relative, :absolute, :fixed]) %>
+    #
+    # @param top [Boolean] If `false`, sets `top: 0`.
+    # @param right [Boolean] If `false`, sets `right: 0`.
+    # @param bottom [Boolean] If `false`, sets `bottom: 0`.
+    # @param left [Boolean] If `false`, sets `left: 0`.
+    #
+    # @param display [Symbol] <%= one_of([:block, :none, :inline, :inline_block, :table, :table_cell]) %>
+    #
+    # @param hide [Symbol] Hide the element at a specific breakpoint. <%= one_of([:sm, :md, :lg, :xl]) %>
+    #
+    # @param vertical_align [Symbol] <%= one_of([:baseline, :top, :middle, :bottom, :text_top, :text_bottom]) %>
+    #
+    # @param float [Symbol] <%= one_of([:left, :right]) %>
+    #
+    # @param font_size [String] <%= one_of(["00", "0", "1", "2", "3", "4", "5", "6"]) %>
+    # @param tag [Symbol] HTML tag name to be passed to `tag.send`
+    # @param classes [String] CSS class name value to be concatenated with generated Primer CSS classes
+    def initialize(tag:, classes: nil, **system_arguments)
       @tag = tag
-      @result = Primer::Classify.call(**args.merge(classes: classes))
+      @result = Primer::Classify.call(**system_arguments.merge(classes: classes))
 
       # Filter out Primer keys so they don't get assigned as HTML attributes
-      @content_tag_args = add_test_selector(args).except(*Primer::Classify::VALID_KEYS)
+      @content_tag_args = add_test_selector(system_arguments).except(*Primer::Classify::VALID_KEYS)
     end
 
     def call