primer_view_components 0.0.17 → 0.0.22

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

@@ -1,8 +1,4 @@
 <%= render Primer::BaseComponent.new(**@system_arguments) do %>
-  <%= render summary.component do %>
-    <%= summary.content %>
-  <% end %>
-  <%= render body.component do %>
-    <%= body.content %>
-  <% end %>
+  <%= summary %>
+  <%= body %>
 <% end %>

data/app/components/primer/details_component.rb

@@ -1,24 +1,42 @@
 # 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
+    include ViewComponent::SlotableV2
 
     NO_OVERLAY = :none
     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"
-
+    # Use the Summary slot as a trigger to reveal the content.
+    #
+    # @param button [Boolean] Whether to render the Summary as a button or not.
+    # @param kwargs [Hash] The same arguments as <%= link_to_system_arguments_docs %>.
+    renders_one :summary, lambda { |button = true, **system_arguments|
+      system_arguments = system_arguments
+      system_arguments[:tag] = :summary
+      system_arguments[:role] = "button"
+
+      Primer::BaseComponent.new(**system_arguments) unless button
+
+      Primer::ButtonComponent.new(**system_arguments)
+    }
+
+    # Use the Body slot as the main content to be shown when triggered by the Summary.
+    #
+    # @param kwargs [Hash] The same arguments as <%= link_to_system_arguments_docs %>.
+    renders_one :body, lambda { |**system_arguments|
+      system_arguments[:tag] ||= :div
+      Primer::BaseComponent.new(**system_arguments)
+    }
+
+    # @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
@@ -32,32 +50,5 @@ module Primer
     def render?
       summary.present? && body.present?
     end
-
-    class Summary < Primer::Slot
-      def initialize(button: true, **system_arguments)
-        @button = button
-
-        @system_arguments = system_arguments
-        @system_arguments[:tag] = :summary
-        @system_arguments[:role] = "button"
-      end
-
-      def component
-        return Primer::BaseComponent.new(**@system_arguments) unless @button
-
-        Primer::ButtonComponent.new(**@system_arguments)
-      end
-    end
-
-    class Body < Primer::Slot
-      def initialize(**system_arguments)
-        @system_arguments = system_arguments
-        @system_arguments[:tag] ||= :div
-      end
-
-      def component
-        Primer::BaseComponent.new(**@system_arguments)
-      end
-    end
   end
 end

data/app/components/primer/dropdown/menu_component.html.erb

@@ -0,0 +1,12 @@
+<%= render Primer::BaseComponent.new(**@system_arguments) do %>
+  <% if @header.present? %>
+    <div class="dropdown-header">
+      <%= @header %>
+    </div>
+  <% end %>
+  <ul>
+    <% items.each do |item| %>
+      <%= item %>
+    <% end %>
+  </ul>
+<% end %>

data/app/components/primer/dropdown/menu_component.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module Primer
+  module Dropdown
+    # This component is part of `Primer::DropdownComponent` and should not be
+    # used as a standalone component.
+    class MenuComponent < Primer::Component
+      include ViewComponent::SlotableV2
+
+      SCHEME_DEFAULT = :default
+      SCHEME_MAPPINGS = {
+        SCHEME_DEFAULT => "",
+        :dark => "dropdown-menu-dark"
+      }.freeze
+
+      DIRECTION_DEFAULT = :se
+      DIRECTION_OPTIONS = [DIRECTION_DEFAULT, :sw, :w, :e, :ne, :s].freeze
+
+      renders_many :items, lambda { |divider: false, **system_arguments|
+        system_arguments[:tag] = :li
+        system_arguments[:role] = :none if divider
+        system_arguments[:classes] = class_names(
+          system_arguments[:classes],
+          "dropdown-item" => !divider,
+          "dropdown-divider" => divider
+        )
+
+        Primer::BaseComponent.new(**system_arguments)
+      }
+
+      def initialize(direction: DIRECTION_DEFAULT, scheme: SCHEME_DEFAULT, header: nil, **system_arguments)
+        @header = header
+        @direction = direction
+        @system_arguments = system_arguments
+
+        @system_arguments[:tag] = "details-menu"
+        @system_arguments[:role] = "menu"
+
+        @system_arguments[:classes] = class_names(
+          @system_arguments[:classes],
+          "dropdown-menu",
+          "dropdown-menu-#{fetch_or_fallback(DIRECTION_OPTIONS, direction, DIRECTION_DEFAULT)}",
+          SCHEME_MAPPINGS[fetch_or_fallback(SCHEME_MAPPINGS.keys, scheme, SCHEME_DEFAULT)]
+        )
+      end
+    end
+  end
+end

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

@@ -0,0 +1,9 @@
+<%= render(Primer::DetailsComponent.new(**@system_arguments)) do |c| %>
+  <% c.summary(classes: @summary_classes) do %>
+    <%= button %>
+  <% end %>
+
+  <% c.body do %>
+    <%= menu %>
+  <% end %>
+<% end %>

data/app/components/primer/dropdown_component.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+module Primer
+  # Dropdowns 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 DropdownComponent < Primer::Component
+    include ViewComponent::SlotableV2
+
+    # Required trigger for the dropdown. Only accepts a content.
+    # Its classes can be customized by the `summary_classes` param in the parent component
+    renders_one :button
+
+    # Required context menu for the dropdown
+    #
+    # @param direction [Symbol] <%= one_of(Primer::Dropdown::MenuComponent::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 %>
+    renders_one :menu, Primer::Dropdown::MenuComponent
+
+    # @example Default
+    #   <div>
+    #     <%= render(Primer::DropdownComponent.new) do |c| %>
+    #       <% c.button do %>
+    #         Dropdown
+    #       <% end %>
+    #
+    #       <%= c.menu(header: "Options") do |menu|
+    #         menu.item { "Item 1" }
+    #         menu.item { "Item 2" }
+    #         menu.item(divider: true)
+    #         menu.item { "Item 3" }
+    #         menu.item { "Item 4" }
+    #       end %>
+    #     <% end %>
+    #   </div>
+    #
+    # @example With Direction
+    #   <div>
+    #     <%= render(Primer::DropdownComponent.new) do |c| %>
+    #       <% c.button do %>
+    #         Dropdown
+    #       <% end %>
+    #
+    #       <%= c.menu(header: "Options", direction: :s) do |menu|
+    #         menu.item { "Item 1" }
+    #         menu.item { "Item 2" }
+    #         menu.item(divider: true)
+    #         menu.item { "Item 3" }
+    #         menu.item { "Item 4" }
+    #       end %>
+    #     <% end %>
+    #   </div>
+    #
+    # @param overlay [Symbol] <%= one_of(Primer::DetailsComponent::OVERLAY_MAPPINGS.keys) %>
+    # @param reset [Boolean] Whether to hide the default caret on the button
+    # @param summary_classes [String] Custom classes to add to the button
+    # @param system_arguments [Hash] <%= link_to_system_arguments_docs %>
+    def initialize(overlay: :default, reset: true, summary_classes: "", **system_arguments)
+      @system_arguments = system_arguments
+      @system_arguments[:overlay] = overlay
+      @system_arguments[:reset] = reset
+      @system_arguments[:position] = :relative
+      @system_arguments[:classes] = class_names(
+        @system_arguments[:classes],
+        "dropdown"
+      )
+      @summary_classes = summary_classes
+    end
+
+    def render?
+      button.present? && menu.present?
+    end
+  end
+end

data/app/components/primer/dropdown_menu_component.rb

@@ -1,18 +1,50 @@
 # 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
 
+    def self.status
+      STATUSES[:deprecated]
+    end
+
+    # @example With a header
+    #   <div>
+    #     <%= render(Primer::DetailsComponent.new(overlay: :default, reset: true, position: :relative)) do |c| %>
+    #       <% c.summary do %>
+    #         Dropdown
+    #       <% end %>
+    #
+    #       <% c.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.html.erb

@@ -1,14 +1,11 @@
 <%= render Primer::BaseComponent.new(**@system_arguments) do %>
-  <%= render(Primer::OcticonComponent.new(icon: @icon)) if @icon %>
+  <%= primer(:octicon, icon: @icon) if @icon %>
   <%= content %>
   <% if @dismissible %>
     <button class="flash-close js-flash-close" type="button" aria-label="Close">
-      <%= render(Primer::OcticonComponent.new(icon: "x")) %>
+      <%= primer(:octicon, icon: "x") %>
     </button>
   <% end %>
-  <% if actions.present? %>
-    <%= render Primer::BaseComponent.new(**actions.system_arguments) do %>
-      <%= actions.content %>
-    <% end %>
-  <% end %>
+
+  <%= action %>
 <% end %>

data/app/components/primer/flash_component.rb

@@ -3,9 +3,17 @@
 module Primer
   # Use the Flash component to inform users of successful or pending actions.
   class FlashComponent < Primer::Component
-    include ViewComponent::Slotable
+    include ViewComponent::SlotableV2
 
-    with_slot :actions, class_name: "Actions"
+    # Optional action content showed on the right side of the component.
+    #
+    # @param system_arguments [Hash] <%= link_to_system_arguments_docs %>
+    renders_one :action, lambda { |**system_arguments|
+      system_arguments[:tag] = :div
+      system_arguments[:classes] = class_names(system_arguments[:classes], "flash-action")
+
+      Primer::BaseComponent.new(**system_arguments)
+    }
 
     DEFAULT_VARIANT = :default
     VARIANT_MAPPINGS = {
@@ -14,25 +22,25 @@ module Primer
       :danger => "flash-error",
       :success => "flash-success"
     }.freeze
-    # @example 280|Variants
+    # @example Variants
     #   <%= render(Primer::FlashComponent.new) { "This is a flash message!" } %>
     #   <%= render(Primer::FlashComponent.new(variant: :warning)) { "This is a warning flash message!" } %>
     #   <%= render(Primer::FlashComponent.new(variant: :danger)) { "This is a danger flash message!" } %>
     #   <%= render(Primer::FlashComponent.new(variant: :success)) { "This is a success flash message!" } %>
     #
-    # @example 80|Full width
+    # @example Full width
     #   <%= render(Primer::FlashComponent.new(full: true)) { "This is a full width flash message!" } %>
     #
-    # @example 80|Dismissible
+    # @example Dismissible
     #   <%= render(Primer::FlashComponent.new(dismissible: true)) { "This is a dismissible flash message!" } %>
     #
-    # @example 80|Icon
+    # @example Icon
     #   <%= render(Primer::FlashComponent.new(icon: "people")) { "This is a flash message with an icon!" } %>
     #
-    # @example 80|With actions
+    # @example With actions
     #   <%= render(Primer::FlashComponent.new) do |component| %>
     #     This is a flash message with actions!
-    #     <% component.slot(:actions) do %>
+    #     <% component.action do %>
     #       <%= render(Primer::ButtonComponent.new(variant: :small)) { "Take action" } %>
     #     <% end %>
     #   <% end %>
@@ -57,15 +65,8 @@ module Primer
       @system_arguments[:mb] ||= spacious ? 4 : nil
     end
 
-    class Actions < Primer::Slot
-      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(@system_arguments[:classes], "flash-action")
-      end
+    def self.status
+      Primer::Component::STATUSES[:beta]
     end
   end
 end

data/app/components/primer/flex_component.rb

@@ -1,6 +1,10 @@
 # frozen_string_literal: true
 
 module Primer
+  # Use FlexComponent to make an element lay out its content using the flexbox model.
+  # Before using these utilities, you should be familiar with CSS3 Flexible Box
+  # spec. If you are not, check out MDN's guide  [Using CSS Flexible
+  # Boxes](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Flexible_Box_Layout/Basic_Concepts_of_Flexbox).
   class FlexComponent < Primer::Component
     JUSTIFY_CONTENT_DEFAULT = nil
     JUSTIFY_CONTENT_MAPPINGS = {
@@ -8,9 +12,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,19 +22,53 @@ 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
 
+    # @example Default
+    #   <%= render(Primer::FlexComponent.new(bg: :gray)) do %>
+    #     <%= render(Primer::BoxComponent.new(p: 5, bg: :gray_light, classes: "border")) { "Item 1" } %>
+    #     <%= render(Primer::BoxComponent.new(p: 5, bg: :gray_light, classes: "border")) { "Item 2" } %>
+    #     <%= render(Primer::BoxComponent.new(p: 5, bg: :gray_light, classes: "border")) { "Item 3" } %>
+    #   <% end %>
+    #
+    # @example Justify center
+    #   <%= render(Primer::FlexComponent.new(justify_content: :center, bg: :gray)) do %>
+    #     <%= render(Primer::BoxComponent.new(p: 5, bg: :gray_light, classes: "border")) { "Item 1" } %>
+    #     <%= render(Primer::BoxComponent.new(p: 5, bg: :gray_light, classes: "border")) { "Item 2" } %>
+    #     <%= render(Primer::BoxComponent.new(p: 5, bg: :gray_light, classes: "border")) { "Item 3" } %>
+    #   <% end %>
+    #
+    # @example Align end
+    #   <%= render(Primer::FlexComponent.new(align_items: :end, bg: :gray)) do %>
+    #     <%= render(Primer::BoxComponent.new(p: 5, bg: :gray_light, classes: "border")) { "Item 1" } %>
+    #     <%= render(Primer::BoxComponent.new(p: 5, bg: :gray_light, classes: "border")) { "Item 2" } %>
+    #     <%= render(Primer::BoxComponent.new(p: 5, bg: :gray_light, classes: "border")) { "Item 3" } %>
+    #   <% end %>
+    #
+    # @example Direction column
+    #   <%= render(Primer::FlexComponent.new(direction: :column, bg: :gray)) do %>
+    #     <%= render(Primer::BoxComponent.new(p: 5, bg: :gray_light, classes: "border")) { "Item 1" } %>
+    #     <%= render(Primer::BoxComponent.new(p: 5, bg: :gray_light, classes: "border")) { "Item 2" } %>
+    #     <%= render(Primer::BoxComponent.new(p: 5, bg: :gray_light, classes: "border")) { "Item 3" } %>
+    #   <% end %>
+    #
+    # @param justify_content [Symbol] Use this param to distribute space between and around flex items along the main axis of the container. <%= one_of(Primer::FlexComponent::JUSTIFY_CONTENT_OPTIONS) %>
+    # @param inline [Boolean] Defaults to false.
+    # @param flex_wrap [Boolean] Defaults to nil.
+    # @param align_items [Symbol] Use this param to align items on the cross axis. <%= one_of(Primer::FlexComponent::ALIGN_ITEMS_OPTIONS) %>
+    # @param direction [Symbol] Use this param to define the orientation of the main axis (row or column). By default, flex items will display in a row. <%= one_of(Primer::FlexComponent::ALLOWED_DIRECTIONS) %>
+    # @param system_arguments [Hash] <%= link_to_system_arguments_docs %>
     def initialize(
       justify_content: JUSTIFY_CONTENT_DEFAULT,
       inline: INLINE_DEFAULT,