primer_view_components 0.0.9 → 0.0.14

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (48) hide show
  1. checksums.yaml +4 -4
  2. data/CHANGELOG.md +31 -1
  3. data/README.md +2 -175
  4. data/app/components/primer/avatar_component.rb +22 -11
  5. data/app/components/primer/base_component.rb +56 -11
  6. data/app/components/primer/blankslate_component.html.erb +1 -1
  7. data/app/components/primer/blankslate_component.rb +71 -116
  8. data/app/components/primer/border_box_component.html.erb +5 -5
  9. data/app/components/primer/border_box_component.rb +45 -33
  10. data/app/components/primer/box_component.rb +6 -4
  11. data/app/components/primer/breadcrumb_component.html.erb +2 -2
  12. data/app/components/primer/breadcrumb_component.rb +23 -30
  13. data/app/components/primer/button_component.rb +26 -9
  14. data/app/components/primer/component.rb +1 -0
  15. data/app/components/primer/counter_component.rb +13 -9
  16. data/app/components/primer/details_component.html.erb +1 -1
  17. data/app/components/primer/details_component.rb +18 -18
  18. data/app/components/primer/dropdown_menu_component.html.erb +1 -1
  19. data/app/components/primer/dropdown_menu_component.rb +6 -6
  20. data/app/components/primer/flash_component.html.erb +2 -2
  21. data/app/components/primer/flash_component.rb +42 -12
  22. data/app/components/primer/flex_component.rb +5 -5
  23. data/app/components/primer/flex_item_component.rb +5 -5
  24. data/app/components/primer/heading_component.rb +4 -4
  25. data/app/components/primer/label_component.rb +37 -14
  26. data/app/components/primer/layout_component.html.erb +1 -1
  27. data/app/components/primer/layout_component.rb +22 -5
  28. data/app/components/primer/link_component.rb +17 -7
  29. data/app/components/primer/octicon_component.rb +20 -7
  30. data/app/components/primer/popover_component.html.erb +1 -1
  31. data/app/components/primer/popover_component.rb +61 -23
  32. data/app/components/primer/progress_bar_component.html.erb +2 -2
  33. data/app/components/primer/progress_bar_component.rb +40 -30
  34. data/app/components/primer/slot.rb +1 -0
  35. data/app/components/primer/spinner_component.html.erb +6 -0
  36. data/app/components/primer/spinner_component.rb +39 -0
  37. data/app/components/primer/state_component.rb +26 -14
  38. data/app/components/primer/subhead_component.html.erb +4 -4
  39. data/app/components/primer/subhead_component.rb +68 -43
  40. data/app/components/primer/text_component.rb +10 -4
  41. data/app/components/primer/timeline_item_component.html.erb +4 -4
  42. data/app/components/primer/timeline_item_component.rb +48 -24
  43. data/app/components/primer/underline_nav_component.html.erb +1 -1
  44. data/app/components/primer/underline_nav_component.rb +5 -5
  45. data/app/components/primer/view_components.rb +1 -0
  46. data/lib/primer/classify.rb +2 -4
  47. data/lib/primer/view_components/version.rb +1 -1
  48. metadata +4 -2
checksums.yaml CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA256:
3
- metadata.gz: ee845a3614e0d347957e7f16cf83750c9616bc63828d6ef9adaac62d6b5eb18d
4
- data.tar.gz: 24d5d20ee47acdc6ed411c0ec609870fa7b8788d1debbdf15001a7851f7be54f
3
+ metadata.gz: 9cb2ccfdc2a705a1395c0b18dd535b305cf0b00ef77f778fe6bbc9b6417c3f4a
4
+ data.tar.gz: fa2cea6523b0281502b65d654c11ab4224d345d25a3608a63e92f8680aaeb742
5
5
  SHA512:
6
- metadata.gz: ade2e2c9febaa32e5be37d60efe47c5ef8c7b17f41602e6f470bee8c21a499ab98ff52992aa484c4de3ab2f40f654f1ddc226fa1ac45077285e4349834dec542
7
- data.tar.gz: 3d1eed4c85f4d513234f6ea9cdde584f83e54f7f2b6cf9197137b8e0ca6eeb6f15e2f51798b411d502452f910c5d1309ef0c1269b2b91559920048a2dfeb05f8
6
+ metadata.gz: c4506031b1c2e99c36aa9b868e210b15b396b8b38a8347e1b06785510e3caee7b6edb2e4fe0eafb178effa74cd2287e6e7d421d5c04394f5bead62cb0c3b9ffa
7
+ data.tar.gz: 7e3a7b3a2ca8932cbdb563738d040b5ceb1239736ecf7603a3c9cdfa3cf3bc24aa9df3faa251568b9f8020a119bb75ed439a9881342e7e307b708a742fa42897
@@ -2,6 +2,36 @@
2
2
 
3
3
  ## main
4
4
 
5
+ ## 0.0.14
6
+
7
+ * Add functional colors to Label.
8
+
9
+ *Joel Hawksley*
10
+
11
+ ## 0.0.13
12
+
13
+ * Add support for `xl` breakpoint.
14
+
15
+ *Joel Hawksley*
16
+
17
+ ## 0.0.12
18
+
19
+ * Adds support for disabling inline box-sizing style for `SpinnerComponent` via style parameter `Primer::SpinnerComponent.new(style: nil)`.
20
+
21
+ *Chris Wilson*
22
+
23
+ ## 0.0.11
24
+
25
+ * Renames DetailsComponent::OVERLAY_DEFAULT to DetailsComponent::NO_OVERLAY to more correctly describe its value.
26
+
27
+ *Justin Kenyon*
28
+
29
+ ## 0.0.10
30
+
31
+ * Add SpinnerComponent
32
+
33
+ *Cole Bemis*
34
+
5
35
  ## 0.0.9
6
36
 
7
37
  * BREAKING CHANGE: OcticonComponent no longer accepts `class` parameter; use `classes` instead.
@@ -70,7 +100,7 @@
70
100
 
71
101
  ## 0.0.3
72
102
 
73
- * Add support for responsive `float` style argument.
103
+ * Add support for responsive `float` system argument.
74
104
 
75
105
  *Joel Hawksley*
76
106
 
data/README.md CHANGED
@@ -8,182 +8,9 @@
8
8
 
9
9
  _Note: This library is in pre-release development and should not be considered stable._
10
10
 
11
- ## Design philosophy
11
+ ## Documentation
12
12
 
13
- 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.
14
-
15
- ## Installation
16
-
17
- In `Gemfile`, add:
18
-
19
- ```ruby
20
- gem "primer_view_components"
21
- ```
22
-
23
- In `config/application.rb`, add **after the application definition**
24
-
25
- ```ruby
26
- require "primer/view_components/engine"
27
- ```
28
-
29
- ## Usage
30
-
31
- ### Built-in styling arguments
32
-
33
- 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.
34
-
35
- Example label built with Primer CSS:
36
-
37
- ```html
38
- <span title="Label: Suggested" class="Label Label--outline Label--outline-green ml-2 v-align-middle">Suggested</span>
39
- ```
40
-
41
- The same label using `Primer::LabelComponent`:
42
-
43
- ```erb
44
- <%= render Primer::LabelComponent.new(ml: 2, vertical_align: :middle, scheme: :green, title: "Label: Suggested") do %>
45
- Suggested
46
- <% end %>
47
- ```
48
-
49
- Some components have their own specific arguments, but they can all be styled with the following arguments.
50
-
51
- | Component argument | Primer class | Example |
52
- | --------------- | --------------- | -------- |
53
- | `m` | `m-<value>` | `m: 4` → `.m-4` |
54
- | `my` | `my-<value>` | `my: 4` → `.my-4` |
55
- | `mx` | `my-<value>` | `mx: 4` → `.mx-4` |
56
- | `mt` | `mt-<value>` | `mt: 4` → `.mt-4` |
57
- | `mb` | `mb-<value>` | `mb: 4` → `.mb-4` |
58
- | `ml` | `ml-<value>` | `ml: 4` → `.ml-4` |
59
- | `mr` | `mr-<value>` | `mr: 4` → `.mr-4` |
60
- | `p` | `p-<value>` | `p: 4` → `.p-4` |
61
- | `py` | `py-<value>` | `py: 4` → `.py-4` |
62
- | `px` | `py-<value>` | `px: 4` → `.px-4` |
63
- | `pt` | `pt-<value>` | `pt: 4` → `.pt-4` |
64
- | `pb` | `pb-<value>` | `pb: 4` → `.pb-4` |
65
- | `pl` | `pl-<value>` | `pl: 4` → `.pl-4` |
66
- | `pr` | `pr-<value>` | `pr: 4` → `.pr-4` |
67
- | `pr` | `pr-<value>` | `pr: 4` → `.pr-4` |
68
- | `f` | `f-<value>` | `f: 4` → `.f-4` |
69
- | `color` | `color-<value>` | `color: :red_500` → `.color-red-500` |
70
- | `text` | `text-<value>` | `text: :green` → `.text-green` |
71
- | `bg` | `bg-<value>` | `bg: :blue_light` → `.bg-blue-light` |
72
- | `display` | `d-<value>` | `display: :none` → `.d-none` |
73
- | `float` | `float-<value>` | `float: :right` → `.float-right` |
74
- | `vertical_align` | `v-align-<value>` | `vertical_align: :baseline` → `.v-align-baseline` |
75
- | `text_align` | `text-<value>` | `text_align: :right` → `.text-right` |
76
- | `font_size` | `f<value>` | `font_size: 4` → `.f4` |
77
- | `font_weight` | `text-<value>` | `font_weight: :bold` → `.text-bold` |
78
- | `border` | `border-<value>` | `border: :bottom` → `.border-bottom` |
79
- | `border_color` | `border-<value>` | `border: :green` → `.border-green` |
80
- | `border_top` | `border-top-<value>` | `border_top: 0` → `.border-top-0` |
81
- | `border_bottom` | `border-bottom-<value>` | `border_bottom: 0` → `.border-bottom-0` |
82
- | `border_left` | `border-left-<value>` | `border_left: 0` → `.border-left-0` |
83
- | `border_right` | `border-right-<value>` | `border_right: 0` → `.border-right-0` |
84
- | `word_break` | `wb-<value>` | `word_break: :break_all` → `.wb-break-all` |
85
- | `direction` | `flex-<value>` | `direction: :row` → `.flex-row` |
86
- | `justify_content` | `flex-justify-<value>` | `justify_content: :center` → `.flex-justify-center` |
87
- | `align_items` | `flex-items-<value>` | `align_items: :baseline` → `.flex-items-baseline` |
88
- | `box_shadow` | `box-shadow-<value>` | `box_shadow: :medium` → `.box-shadow-medium` |
89
-
90
- #### Boolean arguments
91
-
92
- | Component arguments | True | False |
93
- | -------------- | ------- | ------ |
94
- | `underline` | `underline: true` → `.text-underline` | `underline: false` → `.no-underline` |
95
- | `top` | n/a | `top: false` → `.top-0` |
96
- | `bottom` | n/a | `bottom: false` → `.bottom-0` |
97
- | `left` | n/a | `left: false` → `.left-0` |
98
- | `right` | n/a | `right: false` → `.right-0` |
99
-
100
- #### Responsive arguments
101
-
102
- 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`.
103
-
104
- Example heading built with Primer CSS:
105
-
106
- ```html
107
- <h1 class="mt-0 mt-lg-4">Hello world</h1>
108
- ```
109
-
110
- The same label using `Primer::HeadingComponent`:
111
-
112
- ```erb
113
- <%= render Primer::HeadingComponent.new(mt: [0, nil, nil, 4]) do %>
114
- Hello world
115
- <% end %>
116
- ```
117
-
118
- ## Contributing
119
-
120
- 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.
121
-
122
- ### Setting up
123
-
124
- Run
125
-
126
- ```bash
127
- script/setup
128
- ```
129
-
130
- To install all necessary dependencies.
131
-
132
- ### Running tests
133
-
134
- To run the full test suite:
135
-
136
- ```bash
137
- bundle exec rake
138
- ```
139
-
140
- ### Writing documentation
141
-
142
- 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).
143
-
144
- ### Storybook / Documentation
145
-
146
- To run Storybook and the documentation site, run:
147
-
148
- ```bash
149
- script/dev
150
- ```
151
-
152
- _Note: Overmind is required to run script/dev._
153
-
154
- ### Developing with another app
155
-
156
- In your `Gemfile`, change:
157
-
158
- ```ruby
159
- gem "primer_view_components"
160
- ```
161
-
162
- to
163
-
164
- ```ruby
165
- gem "primer_view_components", path: "path_to_the_gem" # e.g. path: "~/primer/view_components"
166
- ```
167
-
168
- Then, `bundle install` to update references. You'll now be able to see changes from the gem without having to build it.
169
- Remember that restarting the Rails server is necessary to see changes, as the gem is loaded at boot time.
170
-
171
- To minimize the number of restarts, we recommend checking the component in Storybook first, and then when it's in a good state,
172
- you can check it in your app.
173
-
174
- ### Documentation
175
-
176
- Document components with [YARD](https://yardoc.org/). Docs are published to [RubyDoc.info](https://rubydoc.info/github/primer/view_components).
177
-
178
- ## Deploying to Heroku
179
-
180
- We have both `staging` and `production` environments. To deploy Storybook to Heroku, run the following in `#primer-view-components-ops`:
181
-
182
- ```bash
183
- .deploy primer-view-components</branch> to <environment>
184
- ```
185
-
186
- If no `branch` is passed, `main` will be deployed.
13
+ Visit [https://primer.style/view-components/](https://primer.style/view-components//) to view documentation.
187
14
 
188
15
  ## License
189
16
 
@@ -1,28 +1,39 @@
1
1
  # frozen_string_literal: true
2
2
 
3
3
  module Primer
4
+ # Avatars are images used to represent users and organizations on GitHub.
5
+ # Use the default round avatar for users, and the `square` argument
6
+ # for organizations or any other non-human avatars.
4
7
  class AvatarComponent < Primer::Component
5
8
  SMALL_THRESHOLD = 24
6
9
 
7
- def initialize(src:, alt:, size: 20, square: false, **kwargs)
8
- @kwargs = kwargs
9
- @kwargs[:tag] = :img
10
- @kwargs[:src] = src
11
- @kwargs[:alt] = alt
12
- @kwargs[:size] = size
13
- @kwargs[:height] = size
14
- @kwargs[:width] = size
10
+ #
11
+ # @example 34|Default
12
+ # <%= render(Primer::AvatarComponent.new(src: "http://placekitten.com/200/200", alt: "@kittenuser")) %>
13
+ #
14
+ # @param src [String] The source url of the avatar image
15
+ # @param alt [String] Passed through to alt on img tag
16
+ # @param size [Integer] Adds the avatar-small class if less than 24
17
+ # @param square [Boolean] Used to create a square avatar.
18
+ def initialize(src:, alt:, size: 20, square: false, **system_arguments)
19
+ @system_arguments = system_arguments
20
+ @system_arguments[:tag] = :img
21
+ @system_arguments[:src] = src
22
+ @system_arguments[:alt] = alt
23
+ @system_arguments[:size] = size
24
+ @system_arguments[:height] = size
25
+ @system_arguments[:width] = size
15
26
 
16
- @kwargs[:classes] = class_names(
27
+ @system_arguments[:classes] = class_names(
17
28
  "avatar",
18
- kwargs[:classes],
29
+ system_arguments[:classes],
19
30
  "avatar--small" => size < SMALL_THRESHOLD,
20
31
  "CircleBadge" => !square
21
32
  )
22
33
  end
23
34
 
24
35
  def call
25
- render(Primer::BaseComponent.new(**@kwargs)) { content }
36
+ render(Primer::BaseComponent.new(**@system_arguments)) { content }
26
37
  end
27
38
  end
28
39
  end
@@ -1,25 +1,70 @@
1
1
  # frozen_string_literal: true
2
2
 
3
3
  module Primer
4
- # Base component used by other Primer components.
4
+ # 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).
5
5
  #
6
- # tag(symbol): HTML tag name to be passed to tag.send(tag)
7
- # class_names(string): CSS class name value to be concatenated with generated Primer CSS classes
8
- # args(hash): Combination of arguments for classes_from_hash and content_tag
6
+ # 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).
7
+ #
8
+ # ## Responsive values
9
+ #
10
+ # 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`.
11
+ #
12
+ # For example:
13
+ #
14
+ # ```erb
15
+ # <%= render Primer::HeadingComponent.new(mt: [0, nil, nil, 4, 2]) do %>
16
+ # Hello world
17
+ # <% end %>
18
+ # ```
19
+ #
20
+ # Renders:
21
+ #
22
+ # ```html
23
+ # <h1 class="mt-0 mt-lg-4 mt-xl-2">Hello world</h1>
24
+ # ```
9
25
  #
10
- # Example usage:
11
- # <%= render Primer::BaseComponent, tag: :a, href: "http://www.google.com", mt: 4 do %>Link<% end %>
12
- # generates:
13
- # <a href="http://www.google.com" class="mt-4">Link</a>
14
26
  class BaseComponent < Primer::Component
15
27
  TEST_SELECTOR_TAG = :test_selector
16
28
 
17
- def initialize(tag:, classes: nil, **args)
29
+ # @param m [Integer] Margin. <%= one_of((-6..6).to_a) %>
30
+ # @param mt [Integer] Margin left. <%= one_of((-6..6).to_a) %>
31
+ # @param mr [Integer] Margin right. <%= one_of((-6..6).to_a) %>
32
+ # @param mb [Integer] Margin bottom. <%= one_of((-6..6).to_a) %>
33
+ # @param ml [Integer] Margin left. <%= one_of((-6..6).to_a) %>
34
+ # @param mx [Integer] Horizontal margins. <%= one_of((-6..6).to_a + [:auto]) %>
35
+ # @param my [Integer] Vertical margins. <%= one_of((-6..6).to_a) %>
36
+ # @param m [Integer] Padding. <%= one_of((0..6).to_a) %>
37
+ # @param mt [Integer] Padding left. <%= one_of((0..6).to_a) %>
38
+ # @param mr [Integer] Padding right. <%= one_of((0..6).to_a) %>
39
+ # @param mb [Integer] Padding bottom. <%= one_of((0..6).to_a) %>
40
+ # @param ml [Integer] Padding left. <%= one_of((0..6).to_a) %>
41
+ # @param mx [Integer] Horizontal padding. <%= one_of((0..6).to_a) %>
42
+ # @param my [Integer] Vertical padding. <%= one_of((0..6).to_a) %>
43
+ #
44
+ # @param position [Symbol] <%= one_of([:relative, :absolute, :fixed]) %>
45
+ #
46
+ # @param top [Boolean] If `false`, sets `top: 0`.
47
+ # @param right [Boolean] If `false`, sets `right: 0`.
48
+ # @param bottom [Boolean] If `false`, sets `bottom: 0`.
49
+ # @param left [Boolean] If `false`, sets `left: 0`.
50
+ #
51
+ # @param display [Symbol] <%= one_of([:block, :none, :inline, :inline_block, :table, :table_cell]) %>
52
+ #
53
+ # @param hide [Symbol] Hide the element at a specific breakpoint. <%= one_of([:sm, :md, :lg, :xl]) %>
54
+ #
55
+ # @param vertical_align [Symbol] <%= one_of([:baseline, :top, :middle, :bottom, :text_top, :text_bottom]) %>
56
+ #
57
+ # @param float [Symbol] <%= one_of([:left, :right]) %>
58
+ #
59
+ # @param font_size [String] <%= one_of(["00", "0", "1", "2", "3", "4", "5", "6"]) %>
60
+ # @param tag [Symbol] HTML tag name to be passed to `tag.send`
61
+ # @param classes [String] CSS class name value to be concatenated with generated Primer CSS classes
62
+ def initialize(tag:, classes: nil, **system_arguments)
18
63
  @tag = tag
19
- @result = Primer::Classify.call(**args.merge(classes: classes))
64
+ @result = Primer::Classify.call(**system_arguments.merge(classes: classes))
20
65
 
21
66
  # Filter out Primer keys so they don't get assigned as HTML attributes
22
- @content_tag_args = add_test_selector(args).except(*Primer::Classify::VALID_KEYS)
67
+ @content_tag_args = add_test_selector(system_arguments).except(*Primer::Classify::VALID_KEYS)
23
68
  end
24
69
 
25
70
  def call
@@ -1,4 +1,4 @@
1
- <%= render Primer::BaseComponent.new(**@kwargs) do %>
1
+ <%= render Primer::BaseComponent.new(**@system_arguments) do %>
2
2
  <% if @icon.present? %>
3
3
  <%= render(Primer::OcticonComponent.new(
4
4
  icon: @icon,
@@ -1,118 +1,73 @@
1
1
  # frozen_string_literal: true
2
2
 
3
3
  module Primer
4
- # 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.
5
- #
6
- # ## Basic example
7
- #
8
- # The `Primer::BlankslateComponent` supports the following arguments to add a basic blankslate:
9
- #
10
- # 1. `title` (`String` optional). Text that appears in a larger bold font.
11
- # 2. `description` (`String` optional). Text that appears below the title. Typically a whole sentence.
12
- #
13
- # ```ruby
14
- # <%= render Primer::BlankslateComponent.new(
15
- # title: "Title",
16
- # description: "Description",
17
- # ) %>
18
- # ```
19
- #
20
- # ## Icon or graphic (optional)
21
- #
22
- # Add an `icon` to give additional context. Please refer to the [Octicons](https://primer.style/octicons/) documentation to choose an icon.
23
- #
24
- # ```ruby
25
- # <%= render Primer::BlankslateComponent.new(
26
- # icon: "octoface",
27
- # title: "Title",
28
- # description: "Description",
29
- # ) %>
30
- # ```
31
- #
32
- # 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.
33
- #
34
- # ```ruby
35
- # <%= render Primer::BlankslateComponent.new(
36
- # image_src: "file.svg",
37
- # image_alt: "Description of the image",
38
- # title: "Title",
39
- # description: "Description",
40
- # ) %>
41
- # ```
42
- #
43
- # Both icon and graphic will appear above the title.
44
- #
45
- #
46
- # ## Custom content (optional)
47
- #
48
- # You can add any custom content that typically is used instead of the description:
49
- #
50
- # ```ruby
51
- # <%= render Primer::BlankslateComponent.new(
52
- # icon: "octoface",
53
- # title: "Title",
54
- # ) do %>
55
- # <p>Your custom content here</p>
56
- # <% end %>
57
- # ```
58
- #
59
- # ## Action button (optional)
60
- #
61
- # 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:
62
- #
63
- # - `button_text` (`String` optional). The text of the button.
64
- # - `button_url` (`String` optional). The URL where the user will be taken after clicking the button.
65
- #
66
- # ```ruby
67
- # <%= render Primer::BlankslateComponent.new(
68
- # icon: "book",
69
- # title: "Welcome to the mona wiki!",
70
- # 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.",
71
- #
72
- # button_text: "Create the first page",
73
- # button_url: "https://github.com/monalisa/mona/wiki/_new",
74
- # ) %>
75
- # ```
76
- #
77
- # ## Link (optional)
78
- #
79
- # Add an additional link to help users learn more about a feature. The link will be shown at the very bottom:
80
- #
81
- # - `link_text` (`String` optional). The text of the link.
82
- # - `link_url` (`String` optional). The URL where the user will be taken after clicking the link.
83
- #
84
- # ```ruby
85
- # <%= render Primer::BlankslateComponent.new(
86
- # icon: "book",
87
- # title: "Welcome to the mona wiki!",
88
- # 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.",
89
- # button_text: "Create the first page",
90
- # button_url: "https://github.com/monalisa/mona/wiki/_new",
91
- # link_text: "Learn more about wikis",
92
- # link_url: "https://docs.github.com/en/github/building-a-strong-community/about-wikis",
93
- # ) %>
94
- # ```
95
- #
96
- # ## Variations (optional)
97
- #
98
- # There are a few variations of how the Blankslate appears:
99
- #
100
- # - `narrow` (`Boolean` optional). Adds a maximum width.
101
- # - `large` (`Boolean` optional). Increaeses the font size.
102
- # - `spacious` (`Boolean` optional). Adds extra padding.
103
- #
104
- # ```ruby
105
- # <%= render Primer::BlankslateComponent.new(
106
- # icon: "book",
107
- # title: "Welcome to the mona wiki!",
108
- # 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.",
109
- #
110
- # narrow: true,
111
- # large: true,
112
- # spacious: true,
113
- # ) %>
114
- # ```
4
+ # 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.
115
5
  class BlankslateComponent < Primer::Component
6
+ #
7
+ # @example 150|Basic
8
+ # <%= render Primer::BlankslateComponent.new(
9
+ # title: "Title",
10
+ # description: "Description",
11
+ # ) %>
12
+ #
13
+ # @example 190|Icon|Add an `icon` to give additional context. Refer to the [Octicons](https://primer.style/octicons/) documentation to choose an icon.
14
+ # <%= render Primer::BlankslateComponent.new(
15
+ # icon: "octoface",
16
+ # title: "Title",
17
+ # description: "Description",
18
+ # ) %>
19
+ #
20
+ # @example 150|Custom content|Pass custom content as a block in place of `description`.
21
+ # <%= render Primer::BlankslateComponent.new(
22
+ # title: "Title",
23
+ # ) do %>
24
+ # <em>Your custom content here</em>
25
+ # <% end %>
26
+ #
27
+ # @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.
28
+ # <%= render Primer::BlankslateComponent.new(
29
+ # icon: "book",
30
+ # title: "Welcome to the mona wiki!",
31
+ # 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.",
32
+ #
33
+ # button_text: "Create the first page",
34
+ # button_url: "https://github.com/monalisa/mona/wiki/_new",
35
+ # ) %>
36
+ #
37
+ # @example 225|Link|Add an additional link to help users learn more about a feature. The link will be shown at the very bottom:
38
+ # <%= render Primer::BlankslateComponent.new(
39
+ # icon: "book",
40
+ # title: "Welcome to the mona wiki!",
41
+ # 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.",
42
+ # link_text: "Learn more about wikis",
43
+ # link_url: "https://docs.github.com/en/github/building-a-strong-community/about-wikis",
44
+ # ) %>
45
+ #
46
+ # @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.
47
+ # <%= render Primer::BlankslateComponent.new(
48
+ # icon: "book",
49
+ # title: "Welcome to the mona wiki!",
50
+ # 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.",
51
+ # narrow: true,
52
+ # large: true,
53
+ # spacious: true,
54
+ # ) %>
55
+ #
56
+ # @param title [String] Text that appears in a larger bold font.
57
+ # @param title_tag [Symbol] HTML tag to use for title.
58
+ # @param icon [String] Octicon icon to use at top of component.
59
+ # @param icon_size [Symbol] <%= one_of(Primer::OcticonComponent::SIZE_MAPPINGS) %>
60
+ # @param image_src [String] Image to display.
61
+ # @param image_alt [String] Alt text for image.
62
+ # @param description [String] Text that appears below the title. Typically a whole sentence.
63
+ # @param button_text [String] The text of the button.
64
+ # @param button_url [String] The URL where the user will be taken after clicking the button.
65
+ # @param button_classes [String] Classes to apply to action button
66
+ # @param link_text [String] The text of the link.
67
+ # @param link_url [String] The URL where the user will be taken after clicking the link.
68
+ # @param narrow [Boolean] Adds a maximum width.
69
+ # @param large [Boolean] Increases the font size.
70
+ # @param spacious [Boolean] Adds extra padding.
116
71
  def initialize(
117
72
  title: "",
118
73
  title_tag: :h3,
@@ -132,12 +87,12 @@ module Primer
132
87
  large: false,
133
88
  spacious: false,
134
89
 
135
- **kwargs
90
+ **system_arguments
136
91
  )
137
- @kwargs = kwargs
138
- @kwargs[:tag] ||= :div
139
- @kwargs[:classes] = class_names(
140
- @kwargs[:classes],
92
+ @system_arguments = system_arguments
93
+ @system_arguments[:tag] ||= :div
94
+ @system_arguments[:classes] = class_names(
95
+ @system_arguments[:classes],
141
96
  "blankslate",
142
97
  "blankslate-narrow": narrow,
143
98
  "blankslate-large": large,