primer_view_components 0.0.12 → 0.0.13

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c05ad651f3b5b7815ccb7f623f098b488019c938c11b1d00ee93e467ec535b55
-  data.tar.gz: aafd79851c5e551d193d5282536806a1446ada7e12d1d25ba29437e58d7b1212
+  metadata.gz: 055f773c8e99df5c9bce23d6a5199e71148d0331d6abe6c02fd1f16321a54130
+  data.tar.gz: e5310f927e76533daa46918acb24b48ea7bdd684a8f8e4c9090e3545a2e7f3fd
 SHA512:
-  metadata.gz: 30d274cb5271343b460ca8bfc1dc08317eff24ef71213633537acedf34eca63ffcb58a1581b5a95a678d5b88d1ec5229467c5b96dc7c3f2fa7aa918ce45b8426
-  data.tar.gz: 7806725e6845939d302bde336a73a89a1b1918e878a6b15666b157e2d8b4ce53535d630e2960d1077cc8bb7ba7867a60eadfd346ecda15fabce07aaacaabbb3d
+  metadata.gz: e6b7159b56e4a0674a7ec68e4aa0666bb2a3e3cb5ef7b90e8c418149200af1255789adc87e4b3955a9a2d6e97afb9ebe2746928ccb32ece3395c28de315206dc
+  data.tar.gz: cc962a06f62249016eccfd224ab3655117ac193fa7f6ebb40aff91212690464047f95e2822bf4b5c8ae83d8c82df02e955f0c8ffc350e9aed85c313623388a61

data/CHANGELOG.md

@@ -2,6 +2,12 @@
 
 ## 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)`.
@@ -88,7 +94,7 @@
 
 ## 0.0.3
 
-* Add support for responsive `float` style argument.
+* Add support for responsive `float` system argument.
 
     *Joel Hawksley*
 

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,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).
+  #
+  # 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>
+  # ```
+  #
   class BaseComponent < Primer::Component
     TEST_SELECTOR_TAG = :test_selector
 
+    # @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) %>
     #
-    # @example 34|Default
-    #   <%= render(Primer::BaseComponent.new(tag: :a, href: "http://www.google.com", mt: 4)) { "Link" } %>
+    # @param position [Symbol] <%= one_of([:relative, :absolute, :fixed]) %>
     #
-    # @param tag [Symbol] HTML tag name to be passed to tag.send(tag)
+    # @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, **args)
+    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) %>
+    # @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 %>

data/app/components/primer/border_box_component.rb

@@ -20,13 +20,13 @@ module Primer
     #     component.slot(:footer) { "Footer" }
     #   end %>
     #
-    # @param kwargs [Hash] <%= link_to_style_arguments_docs %>
-    def initialize(**kwargs)
-      @kwargs = kwargs
-      @kwargs[:tag] = :div
-      @kwargs[:classes] = class_names(
+    # @param system_arguments [Hash] <%= link_to_system_arguments_docs %>
+    def initialize(**system_arguments)
+      @system_arguments = system_arguments
+      @system_arguments[:tag] = :div
+      @system_arguments[:classes] = class_names(
         "Box",
-        kwargs[:classes]
+        system_arguments[:classes]
       )
     end
 
@@ -35,53 +35,53 @@ 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
-        @kwargs[:classes] = class_names(
+      attr_reader :system_arguments
+      # @param system_arguments [Hash] <%= link_to_system_arguments_docs %>
+      def initialize(**system_arguments)
+        @system_arguments = system_arguments
+        @system_arguments[:tag] = :div
+        @system_arguments[:classes] = class_names(
           "Box-header",
-          kwargs[:classes]
+          system_arguments[:classes]
         )
       end
     end
 
     class Body < Primer::Slot
-      attr_reader :kwargs
-      # @param kwargs [Hash] <%= link_to_style_arguments_docs %>
-      def initialize(**kwargs)
-        @kwargs = kwargs
-        @kwargs[:tag] = :div
-        @kwargs[:classes] = class_names(
+      attr_reader :system_arguments
+      # @param system_arguments [Hash] <%= link_to_system_arguments_docs %>
+      def initialize(**system_arguments)
+        @system_arguments = system_arguments
+        @system_arguments[:tag] = :div
+        @system_arguments[:classes] = class_names(
           "Box-body",
-          kwargs[:classes]
+          system_arguments[:classes]
         )
       end
     end
 
     class Footer < Primer::Slot
-      attr_reader :kwargs
-      # @param kwargs [Hash] <%= link_to_style_arguments_docs %>
-      def initialize(**kwargs)
-        @kwargs = kwargs
-        @kwargs[:tag] = :div
-        @kwargs[:classes] = class_names(
+      attr_reader :system_arguments
+      # @param system_arguments [Hash] <%= link_to_system_arguments_docs %>
+      def initialize(**system_arguments)
+        @system_arguments = system_arguments
+        @system_arguments[:tag] = :div
+        @system_arguments[:classes] = class_names(
           "Box-footer",
-          kwargs[:classes]
+          system_arguments[:classes]
         )
       end
     end
 
     class Row < Primer::Slot
-      attr_reader :kwargs
-      # @param kwargs [Hash] <%= link_to_style_arguments_docs %>
-      def initialize(**kwargs)
-        @kwargs = kwargs
-        @kwargs[:tag] = :li
-        @kwargs[:classes] = class_names(
+      attr_reader :system_arguments
+      # @param system_arguments [Hash] <%= link_to_system_arguments_docs %>
+      def initialize(**system_arguments)
+        @system_arguments = system_arguments
+        @system_arguments[:tag] = :li
+        @system_arguments[:classes] = class_names(
           "Box-row",
-          kwargs[:classes]
+          system_arguments[:classes]
         )
       end
     end

data/app/components/primer/box_component.rb

@@ -3,14 +3,14 @@
 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
+    # @param system_arguments [Hash] <%= link_to_system_arguments_docs %>
+    def initialize(**system_arguments)
+      @system_arguments = system_arguments
+      @system_arguments[:tag] = :div
     end
 
     def call
-      render(Primer::BaseComponent.new(**@kwargs)) { content }
+      render(Primer::BaseComponent.new(**@system_arguments)) { content }
     end
   end
 end

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

@@ -1,8 +1,8 @@
-<%= render Primer::BaseComponent.new(**@kwargs) do %>
+<%= render Primer::BaseComponent.new(**@system_arguments) do %>
   <ol>
     <% items.each do |item| %>
       <%# The <li> and <a> need to be on the same line to prevent unwanted whitespace %>
-      <%= render Primer::BaseComponent.new(**item.kwargs) do %><%- if item.href.present? %><a href="<%= item.href %>"><%= item.content %></a><%- else %><%= item.content %><%- end %><%- end %>
+      <%= render Primer::BaseComponent.new(**item.system_arguments) do %><%- if item.href.present? %><a href="<%= item.href %>"><%= item.content %></a><%- else %><%= item.content %><%- end %><%- end %>
     <% end %>
   </ol>
 <% end %>

data/app/components/primer/breadcrumb_component.rb

@@ -14,11 +14,11 @@ module Primer
     #     <% 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
-      @kwargs[:aria] = { label: "Breadcrumb" }
+    # @param system_arguments [Hash] <%= link_to_system_arguments_docs %>
+    def initialize(**system_arguments)
+      @system_arguments = system_arguments
+      @system_arguments[:tag] = :nav
+      @system_arguments[:aria] = { label: "Breadcrumb" }
     end
 
     def render?
@@ -27,18 +27,18 @@ module Primer
 
     # _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
+      attr_reader :href, :system_arguments
 
       # @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
+      # @param system_arguments [Hash] <%= link_to_system_arguments_docs %>
+      def initialize(href: nil, selected: false, **system_arguments)
+        @href, @system_arguments = href, system_arguments
 
         @href = nil if selected
-        @kwargs[:tag] = :li
-        @kwargs[:"aria-current"] = "page" if selected
-        @kwargs[:classes] = "breadcrumb-item #{@kwargs[:classes]}"
+        @system_arguments[:tag] = :li
+        @system_arguments[:"aria-current"] = "page" if selected
+        @system_arguments[:classes] = "breadcrumb-item #{@system_arguments[:classes]}"
       end
     end
   end

data/app/components/primer/button_component.rb

@@ -48,20 +48,20 @@ module Primer
       tag: DEFAULT_TAG,
       type: DEFAULT_TYPE,
       group_item: false,
-      **kwargs
+      **system_arguments
     )
-      @kwargs = kwargs
-      @kwargs[:tag] = fetch_or_fallback(TAG_OPTIONS, tag, DEFAULT_TAG)
+      @system_arguments = system_arguments
+      @system_arguments[:tag] = fetch_or_fallback(TAG_OPTIONS, tag, DEFAULT_TAG)
 
-      if @kwargs[:tag] == :a
-        @kwargs[:role] = :button
+      if @system_arguments[:tag] == :a
+        @system_arguments[:role] = :button
       else
-        @kwargs[:type] = type
+        @system_arguments[:type] = type
       end
 
-      @kwargs[:classes] = class_names(
+      @system_arguments[:classes] = class_names(
         "btn",
-        kwargs[:classes],
+        system_arguments[:classes],
         BUTTON_TYPE_MAPPINGS[fetch_or_fallback(BUTTON_TYPE_OPTIONS, button_type, DEFAULT_BUTTON_TYPE)],
         VARIANT_MAPPINGS[fetch_or_fallback(VARIANT_OPTIONS, variant, DEFAULT_VARIANT)],
         "BtnGroup-item" => group_item
@@ -69,7 +69,7 @@ module Primer
     end
 
     def call
-      render(Primer::BaseComponent.new(**@kwargs)) { content }
+      render(Primer::BaseComponent.new(**@system_arguments)) { content }
     end
   end
 end

data/app/components/primer/counter_component.rb

@@ -20,7 +20,7 @@ module Primer
     # @param hide_if_zero [Boolean] If true, a `hidden` attribute is added to the counter if `count` is zero.
     # @param text [String] Text to display instead of count.
     # @param round [Boolean] Whether to apply our standard rounding logic to value.
-    # @param kwargs [Hash] Style arguments to be passed to Primer::Classify
+    # @param system_arguments [Hash] <%= link_to_system_arguments_docs %>
     def initialize(
       count: 0,
       scheme: DEFAULT_SCHEME,
@@ -28,23 +28,23 @@ module Primer
       hide_if_zero: false,
       text: "",
       round: false,
-      **kwargs
+      **system_arguments
     )
-      @count, @limit, @hide_if_zero, @text, @round, @kwargs = count, limit, hide_if_zero, text, round, kwargs
+      @count, @limit, @hide_if_zero, @text, @round, @system_arguments = count, limit, hide_if_zero, text, round, system_arguments
 
-      @kwargs[:title] = title
-      @kwargs[:tag] = :span
-      @kwargs[:classes] = class_names(
-        @kwargs[:classes],
+      @system_arguments[:title] = title
+      @system_arguments[:tag] = :span
+      @system_arguments[:classes] = class_names(
+        @system_arguments[:classes],
         SCHEME_MAPPINGS[fetch_or_fallback(SCHEME_MAPPINGS.keys, scheme, DEFAULT_SCHEME)]
       )
       if count == 0 && hide_if_zero
-        @kwargs[:hidden] = true
+        @system_arguments[:hidden] = true
       end
     end
 
     def call
-      render(Primer::BaseComponent.new(**@kwargs)) { value }
+      render(Primer::BaseComponent.new(**@system_arguments)) { value }
     end
 
     private