primer_view_components 0.0.13 → 0.0.18

data/app/components/primer/component.rb

@@ -6,5 +6,19 @@ module Primer
     include ClassNameHelper
     include FetchOrFallbackHelper
     include OcticonsHelper
+    include JoinStyleArgumentsHelper
+
+    # sourced from https://primer.style/doctocat/usage/front-matter#status
+    STATUSES = {
+      deprecated: :deprecated,
+      review: :review,
+      experimental: :experimental,
+      new: :new,
+      stable: :stable
+    }.freeze
+
+    def self.status
+      STATUSES[:experimental]
+    end
   end
 end

data/app/components/primer/counter_component.rb

@@ -7,7 +7,7 @@ module Primer
     SCHEME_MAPPINGS = {
       DEFAULT_SCHEME => "Counter",
       :gray => "Counter Counter--gray",
-      :light_gray => "Counter Counter--gray-light",
+      :light_gray => "Counter Counter--gray-light"
     }.freeze
 
     #
@@ -16,7 +16,7 @@ module Primer
     #
     # @param count [Integer, Float::INFINITY, nil] The number to be displayed (e.x. # of issues, pull requests)
     # @param scheme [Symbol] Color scheme. One of `SCHEME_MAPPINGS.keys`.
-    # @param limit [Integer] Maximum value to display. (e.x. if count == 6,000 and limit == 5000, counter will display "5,000+")
+    # @param limit [Integer, nil] Maximum value to display. Pass `nil` for no limit. (e.x. if `count` == 6,000 and `limit` == 5000, counter will display "5,000+")
     # @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.
@@ -30,17 +30,21 @@ module Primer
       round: false,
       **system_arguments
     )
-      @count, @limit, @hide_if_zero, @text, @round, @system_arguments = count, limit, hide_if_zero, text, round, system_arguments
+      @count = count
+      @limit = limit
+      @hide_if_zero = hide_if_zero
+      @text = text
+      @round = round
+      @system_arguments = system_arguments
 
+      @has_limit = !@limit.nil?
       @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
-        @system_arguments[:hidden] = true
-      end
+      @system_arguments[:hidden] = true if count == 0 && hide_if_zero # rubocop:disable Style/NumericPredicate
     end
 
     def call
@@ -58,8 +62,8 @@ module Primer
         "Infinity"
       else
         count = @count.to_i
-        str = number_with_delimiter([count, @limit].min)
-        str += "+" if count > @limit
+        str = number_with_delimiter(@has_limit ? [count, @limit].min : count)
+        str += "+" if @has_limit && count > @limit
         str
       end
     end
@@ -73,16 +77,16 @@ module Primer
         "∞"
       else
         if @round
-          count = [@count.to_i, @limit].min
+          count = @has_limit ? [@count.to_i, @limit].min : @count.to_i
           precision = count.between?(100_000, 999_999) ? 0 : 1
-          units = {thousand: "k", million: "m", billion: "b"}
+          units = { thousand: "k", million: "m", billion: "b" }
           str = number_to_human(count, precision: precision, significant: false, units: units, format: "%n%u")
         else
           @count = @count.to_i
-          str = number_with_delimiter([@count, @limit].min)
+          str = number_with_delimiter(@has_limit ? [@count, @limit].min : @count)
         end
 
-        str += "+" if @count.to_i > @limit
+        str += "+" if @has_limit && @count.to_i > @limit
         str
       end
     end

data/app/components/primer/details_component.rb

@@ -1,11 +1,7 @@
 # frozen_string_literal: true
 
 module Primer
-  #
-  # overlay - options are `none`, `default` and `dark`. Dictates the type of overlay to render with.
-  # button - options are `default` and `reset`. default will make the target a default primer ``.btn`
-  #          reset will remove all styles from the <summary> element.
-  #
+  # Use DetailsComponent to reveal content after clicking a button.
   class DetailsComponent < Primer::Component
     include ViewComponent::Slotable
 
@@ -13,12 +9,15 @@ module Primer
     OVERLAY_MAPPINGS = {
       NO_OVERLAY => "",
       :default => "details-overlay",
-      :dark => "details-overlay details-overlay-dark",
+      :dark => "details-overlay details-overlay-dark"
     }.freeze
 
     with_slot :body, class_name: "Body"
     with_slot :summary, class_name: "Summary"
 
+    # @param overlay [Symbol] Dictates the type of overlay to render with. <%= one_of(Primer::DetailsComponent::OVERLAY_MAPPINGS.keys) %>
+    # @param reset [Boolean] Defatuls to false. If set to true, it will remove the default caret and remove style from the summary element
+    # @param system_arguments [Hash] <%= link_to_system_arguments_docs %>
     def initialize(overlay: NO_OVERLAY, reset: false, **system_arguments)
       @system_arguments = system_arguments
       @system_arguments[:tag] = :details
@@ -33,7 +32,10 @@ module Primer
       summary.present? && body.present?
     end
 
+    # Use the Summary slot as a trigger to reveal the content.
     class Summary < Primer::Slot
+      # @param button [Boolean] Whether to render the Summary as a button or not.
+      # @param system_arguments [Hash] <%= link_to_system_arguments_docs %>
       def initialize(button: true, **system_arguments)
         @button = button
 
@@ -49,7 +51,9 @@ module Primer
       end
     end
 
+    # Use the Body slot as the main content to be shown when triggered by the Summary.
     class Body < Primer::Slot
+      # @param system_arguments [Hash] <%= link_to_system_arguments_docs %>
       def initialize(**system_arguments)
         @system_arguments = system_arguments
         @system_arguments[:tag] ||= :div

data/app/components/primer/dropdown_menu_component.rb

@@ -1,18 +1,46 @@
 # frozen_string_literal: true
 
 module Primer
+  # DropdownMenus are lightweight context menus for housing navigation and actions.
+  # They're great for instances where you don't need the full power (and code)
+  # of the select menu.
   class DropdownMenuComponent < Primer::Component
     SCHEME_DEFAULT = :default
     SCHEME_MAPPINGS = {
       SCHEME_DEFAULT => "",
-      :dark => "dropdown-menu-dark",
+      :dark => "dropdown-menu-dark"
     }.freeze
 
     DIRECTION_DEFAULT = :se
-    DIRECTION_OPTIONS = [DIRECTION_DEFAULT, :sw, :w, :e, :ne, :s]
+    DIRECTION_OPTIONS = [DIRECTION_DEFAULT, :sw, :w, :e, :ne, :s].freeze
 
+    # @example 200|With a header
+    #   <div style="margin-bottom: 150px">
+    #     <%= render(Primer::DetailsComponent.new(overlay: :default, reset: true, position: :relative)) do |c| %>
+    #       <% c.slot(:summary) do %>
+    #         Dropdown
+    #       <% end %>
+    #
+    #       <% c.slot(:body) do %>
+    #         <%= render(Primer::DropdownMenuComponent.new(header: "Options")) do %>
+    #           <ul>
+    #             <li><a class="dropdown-item" href="#url">Dropdown item</a></li>
+    #             <li><a class="dropdown-item" href="#url">Dropdown item</a></li>
+    #             <li><a class="dropdown-item" href="#url">Dropdown item</a></li>
+    #           </ul>
+    #         <% end %>
+    #       <% end %>
+    #     <% end %>
+    #   </div>
+    #
+    # @param direction [Symbol] <%= one_of(Primer::DropdownMenuComponent::DIRECTION_OPTIONS) %>
+    # @param scheme [Symbol] Pass :dark for dark mode theming
+    # @param header [String] Optional string to display as the header
+    # @param system_arguments [Hash] <%= link_to_system_arguments_docs %>
     def initialize(direction: DIRECTION_DEFAULT, scheme: SCHEME_DEFAULT, header: nil, **system_arguments)
-      @header, @direction, @system_arguments = header, direction, system_arguments
+      @header = header
+      @direction = direction
+      @system_arguments = system_arguments
 
       @system_arguments[:tag] = "details-menu"
       @system_arguments[:role] = "menu"

data/app/components/primer/flash_component.rb

@@ -57,9 +57,8 @@ module Primer
       @system_arguments[:mb] ||= spacious ? 4 : nil
     end
 
-    class Actions < ViewComponent::Slot
-      include ClassNameHelper
-
+    # :nodoc
+    class Actions < Primer::Slot
       attr_reader :system_arguments
 
       # @param system_arguments [Hash] <%= link_to_system_arguments_docs %>

data/app/components/primer/flex_component.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 module Primer
+  # :nodoc
   class FlexComponent < Primer::Component
     JUSTIFY_CONTENT_DEFAULT = nil
     JUSTIFY_CONTENT_MAPPINGS = {
@@ -8,9 +9,9 @@ module Primer
       flex_end: "flex-justify-end",
       center: "flex-justify-center",
       space_between: "flex-justify-between",
-      space_around: "flex-justify-around",
-    }
-    JUSTIFY_CONTENT_OPTIONS = [JUSTIFY_CONTENT_DEFAULT, *JUSTIFY_CONTENT_MAPPINGS.keys]
+      space_around: "flex-justify-around"
+    }.freeze
+    JUSTIFY_CONTENT_OPTIONS = [JUSTIFY_CONTENT_DEFAULT, *JUSTIFY_CONTENT_MAPPINGS.keys].freeze
 
     ALIGN_ITEMS_DEFAULT = nil
     ALIGN_ITEMS_MAPPINGS = {
@@ -18,18 +19,18 @@ module Primer
       end: "flex-items-end",
       center: "flex-items-center",
       baseline: "flex-items-baseline",
-      stretch: "flex-items-stretch",
-    }
-    ALIGN_ITEMS_OPTIONS = [ALIGN_ITEMS_DEFAULT, *ALIGN_ITEMS_MAPPINGS.keys]
+      stretch: "flex-items-stretch"
+    }.freeze
+    ALIGN_ITEMS_OPTIONS = [ALIGN_ITEMS_DEFAULT, *ALIGN_ITEMS_MAPPINGS.keys].freeze
 
     INLINE_DEFAULT = false
-    INLINE_OPTIONS = [INLINE_DEFAULT, true]
+    INLINE_OPTIONS = [INLINE_DEFAULT, true].freeze
 
     FLEX_WRAP_DEFAULT = nil
-    FLEX_WRAP_OPTIONS = [FLEX_WRAP_DEFAULT, true, false]
+    FLEX_WRAP_OPTIONS = [FLEX_WRAP_DEFAULT, true, false].freeze
 
     DEFAULT_DIRECTION = nil
-    ALLOWED_DIRECTIONS = [DEFAULT_DIRECTION, :column, :column_reverse, :row, :row_reverse]
+    ALLOWED_DIRECTIONS = [DEFAULT_DIRECTION, :column, :column_reverse, :row, :row_reverse].freeze
 
     def initialize(
       justify_content: JUSTIFY_CONTENT_DEFAULT,

data/app/components/primer/flex_item_component.rb

@@ -1,9 +1,10 @@
 # frozen_string_literal: true
 
 module Primer
+  # :nodoc
   class FlexItemComponent < Primer::Component
     FLEX_AUTO_DEFAULT = false
-    FLEX_AUTO_ALLOWED_VALUES = [FLEX_AUTO_DEFAULT, true]
+    FLEX_AUTO_ALLOWED_VALUES = [FLEX_AUTO_DEFAULT, true].freeze
 
     def initialize(flex_auto: FLEX_AUTO_DEFAULT, **system_arguments)
       @system_arguments = system_arguments

data/app/components/primer/heading_component.rb

@@ -1,7 +1,14 @@
 # frozen_string_literal: true
 
 module Primer
+  # Use the Heading component to wrap a component that will create a heading element
   class HeadingComponent < Primer::Component
+    # @example 70|Default
+    #   <%= render(Primer::HeadingComponent.new) { "H1 Text" } %>
+    #   <%= render(Primer::HeadingComponent.new(tag: :h2)) { "H2 Text" } %>
+    #   <%= render(Primer::HeadingComponent.new(tag: :h3)) { "H3 Text" } %>
+    #
+    # @param system_arguments [Hash] <%= link_to_system_arguments_docs %>
     def initialize(**system_arguments)
       @system_arguments = system_arguments
       @system_arguments[:tag] ||= :h1

data/app/components/primer/label_component.rb

@@ -3,12 +3,18 @@
 module Primer
   # Use labels to add contextual metadata to a design.
   class LabelComponent < Primer::Component
-    SCHEME_MAPPINGS = {
-      # gray
+    NEW_SCHEME_MAPPINGS = {
+      primary: "Label--primary",
+      secondary: "Label--secondary",
+      info: "Label--info",
+      success: "Label--success",
+      warning: "Label--warning",
+      danger: "Label--danger"
+    }.freeze
+
+    DEPRECATED_SCHEME_MAPPINGS = {
       gray: "Label--gray",
       dark_gray: "Label--gray-darker",
-
-      # colored
       yellow: "Label--yellow",
       orange: "Label--orange",
       red: "Label--red",
@@ -16,16 +22,16 @@ module Primer
       blue: "Label--blue",
       purple: "Label--purple",
       pink: "Label--pink",
-
-      # Deprecated
       outline: "Label--outline",
-      green_outline: "Label--outline-green",
+      green_outline: "Label--outline-green"
     }.freeze
+
+    SCHEME_MAPPINGS = NEW_SCHEME_MAPPINGS.merge(DEPRECATED_SCHEME_MAPPINGS)
     SCHEME_OPTIONS = SCHEME_MAPPINGS.keys << nil
 
     VARIANT_MAPPINGS = {
       large: "Label--large",
-      inline: "Label--inline",
+      inline: "Label--inline"
     }.freeze
     VARIANT_OPTIONS = VARIANT_MAPPINGS.keys << nil
 
@@ -42,7 +48,7 @@ module Primer
     #   <%= render(Primer::LabelComponent.new(title: "Label: Label", variant: :large)) { "Large" } %>
     #
     # @param title [String] `title` attribute for the component element.
-    # @param scheme [Symbol] <%= one_of(Primer::LabelComponent::SCHEME_OPTIONS) %>
+    # @param scheme [Symbol] <%= one_of(Primer::LabelComponent::DEPRECATED_SCHEME_MAPPINGS.keys) %>
     # @param variant [Symbol] <%= one_of(Primer::LabelComponent::VARIANT_OPTIONS) %>
     # @param system_arguments [Hash] <%= link_to_system_arguments_docs %>
     def initialize(title:, scheme: nil, variant: nil, **system_arguments)

data/app/components/primer/link_component.rb

@@ -18,7 +18,7 @@ module Primer
       @system_arguments[:href] = href
       @system_arguments[:classes] = class_names(
         @system_arguments[:classes],
-        "muted-link" => fetch_or_fallback([true, false], muted, false)
+        "muted-link" => fetch_or_fallback_boolean(muted, false)
       )
     end
 

data/app/components/primer/octicon_component.rb

@@ -10,7 +10,7 @@ module Primer
     SIZE_MAPPINGS = {
       SIZE_DEFAULT => 16,
       :medium => 32,
-      :large => 64,
+      :large => 64
     }.freeze
     SIZE_OPTIONS = SIZE_MAPPINGS.keys
 
@@ -27,7 +27,8 @@ module Primer
     # @param size [Symbol] <%= one_of(Primer::OcticonComponent::SIZE_MAPPINGS) %>
     # @param system_arguments [Hash] <%= link_to_system_arguments_docs %>
     def initialize(icon:, size: SIZE_DEFAULT, **system_arguments)
-      @icon, @system_arguments = icon, system_arguments
+      @icon = icon
+      @system_arguments = system_arguments
 
       @system_arguments[:class] = Primer::Classify.call(**@system_arguments)[:class]
       @system_arguments[:height] ||= SIZE_MAPPINGS[size]
@@ -39,7 +40,7 @@ module Primer
     end
 
     def call
-      octicon(@icon, **@system_arguments)
+      octicon(@icon, { **@system_arguments })
     end
   end
 end

data/app/components/primer/popover_component.rb

@@ -57,7 +57,8 @@ module Primer
       body.present?
     end
 
-    class Heading < ViewComponent::Slot
+    # :nodoc
+    class Heading < Primer::Slot
       # @param system_arguments [Hash] <%= link_to_system_arguments_docs %>
       def initialize(**system_arguments)
         @system_arguments = system_arguments
@@ -70,6 +71,7 @@ module Primer
       end
     end
 
+    # :nodoc
     class Body < Slot
       CARET_DEFAULT = :top
       CARET_MAPPINGS = {

data/app/components/primer/progress_bar_component.rb

@@ -12,7 +12,7 @@ module Primer
     SIZE_MAPPINGS = {
       SIZE_DEFAULT => "",
       :small => "Progress--small",
-      :large => "Progress--large",
+      :large => "Progress--large"
     }.freeze
 
     SIZE_OPTIONS = SIZE_MAPPINGS.keys
@@ -48,15 +48,14 @@ module Primer
         SIZE_MAPPINGS[fetch_or_fallback(SIZE_OPTIONS, size, SIZE_DEFAULT)]
       )
       @system_arguments[:tag] = :span
-
     end
 
     def render?
       items.any?
     end
 
-    class Item < ViewComponent::Slot
-      include ClassNameHelper
+    # :nodoc
+    class Item < Primer::Slot
       attr_reader :system_arguments
 
       # @param percentage [Integer] Percentage completion of item.
@@ -68,7 +67,8 @@ module Primer
 
         @system_arguments[:tag] = :span
         @system_arguments[:bg] = bg
-        @system_arguments[:style] = "width: #{@percentage}%;"
+        @system_arguments[:style] =
+          join_style_arguments(@system_arguments[:style], "width: #{@percentage}%;")
         @system_arguments[:classes] = class_names("Progress-item", @system_arguments[:classes])
       end
     end

data/app/components/primer/slot.rb

@@ -5,5 +5,6 @@ module Primer
   class Slot < ViewComponent::Slot
     include ClassNameHelper
     include FetchOrFallbackHelper
+    include JoinStyleArgumentsHelper
   end
 end

data/app/components/primer/spinner_component.rb

@@ -3,12 +3,11 @@
 module Primer
   # Use Primer::SpinnerComponent to let users know that content is being loaded.
   class SpinnerComponent < Primer::Component
-
     DEFAULT_SIZE = :medium
     SIZE_MAPPINGS = {
       :small => 16,
       DEFAULT_SIZE => 32,
-      :large => 64,
+      :large => 64
     }.freeze
     SIZE_OPTIONS = SIZE_MAPPINGS.keys
     # Setting `box-sizing: content-box` allows consumers to add padding
@@ -26,14 +25,14 @@ module Primer
     #   <%= render(Primer::SpinnerComponent.new(size: :large)) %>
     #
     # @param size [Symbol] <%= one_of(Primer::SpinnerComponent::SIZE_MAPPINGS) %>
-    def initialize(size: DEFAULT_SIZE, style: DEFAULT_STYLE, **system_arguments)
+    def initialize(size: DEFAULT_SIZE, **system_arguments)
       @system_arguments = system_arguments
       @system_arguments[:tag] = :svg
+      @system_arguments[:style] ||= DEFAULT_STYLE
       @system_arguments[:width] = SIZE_MAPPINGS[fetch_or_fallback(SIZE_OPTIONS, size, DEFAULT_SIZE)]
       @system_arguments[:height] = SIZE_MAPPINGS[fetch_or_fallback(SIZE_OPTIONS, size, DEFAULT_SIZE)]
       @system_arguments[:viewBox] = "0 0 16 16"
       @system_arguments[:fill] = :none
-      @system_arguments[:style] = DEFAULT_STYLE unless style.nil?
     end
   end
 end