primer_view_components 0.0.10 → 0.0.15

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f4ccf1dd55332ea7b350841d78e04a0f56a0f036749638c30041582500cc561c
-  data.tar.gz: f948087b2dba1cd217296a08260db95a8973cf8e58d4e1240a2c45295ef17e24
+  metadata.gz: c2957082e3fcbcfe88a4bed4f13c1dd8e46971a4792f4e4539cf396293d2b753
+  data.tar.gz: 0cfc136341d4b04c8602851085131fb35eea924439c8b577081993e2540e4992
 SHA512:
-  metadata.gz: 2359e308fa78d78b5cb0f4e76791bfcd6a9714b7295320d04f293f0b7e0351c4fbad90a13743c61e9401de9c69c1269ee791167638715e7fafc594a47b8a242b
-  data.tar.gz: 2089d76d7cdef40b4bce9871d2b0ade0f492751ba057dc99e6fabc4654390656e0cdef57004931d66b1ea75f6189581dbf840bedbb7b89ee6d0fbfdb31d13136
+  metadata.gz: ba13e8bb5fab035a22483269d350ede659f95a36feaf07031c88076750c2ec9775bf3f8a34e65807dfdf5b874a3ba9efb0cdfdfafefcbaa22bef0f55b98e86ee
+  data.tar.gz: d9c0d1615202ddc1f0a193a8555812cb97ad1f371df7e8ed2ce66ee2899f41a266af10d3e9eda205d187fb0e20f154a82034bda8e5f732c48ec17ab0cee9c9ac

data/CHANGELOG.md

@@ -2,6 +2,40 @@
 
 ## main
 
+## 0.0.15
+
+* Add ability to disable `limit` on Counter.
+
+    *Christian Giordano*
+
+* Rename `v` system argument to `visibility`.
+
+    *Joel Hawksley*
+
+## 0.0.14
+
+* Add functional colors to Label.
+
+    *Joel Hawksley*
+
+## 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
@@ -76,7 +110,7 @@
 
 ## 0.0.3
 
-* Add support for responsive `float` style argument.
+* Add support for responsive `float` system argument.
 
     *Joel Hawksley*
 

data/README.md

@@ -8,182 +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](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://primer.style/view-components/](https://primer.style/view-components//) to view documentation.
 
 ## License
 

data/app/components/primer/avatar_component.rb

@@ -15,25 +15,25 @@ module Primer
     # @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
-      @kwargs[:src] = src
-      @kwargs[:alt] = alt
-      @kwargs[:size] = size
-      @kwargs[:height] = size
-      @kwargs[:width] = size
+    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,22 +1,114 @@
 # 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).
+  #
+  # 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>
+  # ```
+  #
+  # ## HTML attributes
+  #
+  # System arguments include most HTML attributes. For example:
+  #
+  # | Name | Type | Description |
+  # | :- | :- | :- |
+  # | `width` | `Integer` | Width. |
+  # | `height` | `Integer` | Height. |
+  # | `data` | `Hash` | Data attributes: `data: { foo: :bar }` renders `data-foo='bar'`. |
+  # | `aria` | `Hash` | Aria attributes: `aria: { label: "foo" }` renders `aria-label='foo'`. |
+  # | `title` | `String` | The `title` attribute. |
+  # | `hidden` | `Boolean` | Whether to assign the `hidden` attribute. |
   class BaseComponent < Primer::Component
     TEST_SELECTOR_TAG = :test_selector
-
+    # @param test_selector [String] Adds `data-test-selector='given value'` in non-Production environments for testing purposes.
+    #
+    # @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 p [Integer] Padding. <%= one_of((0..6).to_a) %>
+    # @param pt [Integer] Padding left. <%= one_of((0..6).to_a) %>
+    # @param pr [Integer] Padding right. <%= one_of((0..6).to_a) %>
+    # @param pb [Integer] Padding bottom. <%= one_of((0..6).to_a) %>
+    # @param pl [Integer] Padding left. <%= one_of((0..6).to_a) %>
+    # @param px [Integer] Horizontal padding. <%= one_of((0..6).to_a) %>
+    # @param py [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 v [Symbol] Visibility. <%= one_of([:hidden, :visible]) %>
+    #
+    # @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 col [Integer] Number of columns.
+    #
+    # @param underline [Boolean] Whether text should be underlined.
+    #
+    # @param color [Symbol] Text color. <%= one_of([:blue, :red, :gray_light, :gray, :gray_dark, :green, :orange, :orange_light, :purple, :pink, :white, :inherit]) %> Note: this API is subject to change as we move to functional colors.
+    # @param bg [String, Symbol] Background color. Accepts either a hex value as a String or a color name as a Symbol.
+    #
+    # @param box_shadow [Boolean, Symbol] Box shadow. <%= one_of([true, :medium, :large, :extra_large, :none]) %>
+    # @param border [Symbol] <%= one_of([:left, :top, :bottom, :right, :y, :x]) %>
+    # @param border_color [Symbol] <%= one_of([:blue, :blue_light, :gray, :gray_dark, :green, :purple, :red, :red_light, :white, :yellow, :black_fade]) %> Note: this API is subject to change as we move to functional colors.
+    # @param border_top [Integer] Set to `0` to remove the top border.
+    # @param border_bottom [Integer] Set to `0` to remove the bottom border.
+    # @param border_left [Integer] Set to `0` to remove the left border.
+    # @param border_right [Integer] Set to `0` to remove the right border.
+    #
+    # @param font_size [String, Integer] <%= one_of(["00", 0, 1, 2, 3, 4, 5, 6]) %>
+    # @param text_align [Symbol] Text alignment. <%= one_of([:left, :right, :center]) %>
+    # @param font_weight [Symbol] Font weight. <%= one_of([:light, :normal, :bold]) %>
+    #
+    # @param flex [Integer, Symbol] <%= one_of([1, :auto]) %>
+    # @param flex_grow [Integer] To enable, set to `0`.
+    # @param flex_shrink [Integer] To enable, set to `0`.
+    # @param align_self [Symbol] <%= one_of([:auto, :start, :end, :center, :baseline, :stretch]) %>
+    # @param justify_content [Symbol] <%= one_of([:flex_start, :flex_end, :center, :space_between, :space_around]) %>
+    # @param align_items [Symbol] <%= one_of([:flex_start, :flex_end, :center, :baseline, :stretch]) %>
+    # @param width [Symbol] <%= one_of([:fit, :fill]) %>
+    # @param height [Symbol] <%= one_of([:fit, :fill]) %>
     #
-    # @example 34|Default
-    #   <%= render(Primer::BaseComponent.new(tag: :a, href: "http://www.google.com", mt: 4)) { "Link" } %>
+    # @param word_break [Symbol] Whether to break words on line breaks. Can only be `:break_all`.
     #
-    # @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)
+    # @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

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

@@ -1,4 +1,4 @@
-<%= render Primer::BaseComponent.new(**@kwargs) do %>
+<%= render Primer::BaseComponent.new(**@system_arguments) do %>
   <% if @icon.present? %>
     <%= render(Primer::OcticonComponent.new(
       icon: @icon,

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) %>
     # @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.
@@ -87,12 +87,12 @@ module Primer
       large: false,
       spacious: false,
 
-      **kwargs
+      **system_arguments
     )
-      @kwargs = kwargs
-      @kwargs[:tag] ||= :div
-      @kwargs[:classes] = class_names(
-        @kwargs[:classes],
+      @system_arguments = system_arguments
+      @system_arguments[:tag] ||= :div
+      @system_arguments[:classes] = class_names(
+        @system_arguments[:classes],
         "blankslate",
         "blankslate-narrow": narrow,
         "blankslate-large": large,

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

@@ -1,25 +1,25 @@
-<%= render Primer::BaseComponent.new(**@kwargs) do %>
+<%= render Primer::BaseComponent.new(**@system_arguments) do %>
   <% if header %>
-    <%= render Primer::BaseComponent.new(**header.kwargs) do %>
+    <%= render Primer::BaseComponent.new(**header.system_arguments) do %>
       <%= header.content %>
     <% end %>
   <% end %>
   <% if body %>
-    <%= render Primer::BaseComponent.new(**body.kwargs) do %>
+    <%= render Primer::BaseComponent.new(**body.system_arguments) do %>
       <%= body.content %>
     <% end %>
   <% end %>
   <% if rows.any? %>
     <ul>
       <% rows.each do |row| %>
-        <%= render Primer::BaseComponent.new(**row.kwargs) do %>
+        <%= render Primer::BaseComponent.new(**row.system_arguments) do %>
           <%= row.content %>
         <% end %>
       <% end %>
     </ul>
   <% end %>
   <% if footer %>
-    <%= render Primer::BaseComponent.new(**footer.kwargs) do %>
+    <%= render Primer::BaseComponent.new(**footer.system_arguments) do %>
       <%= footer.content %>
     <% end %>
   <% end %>