primer_view_components 0.0.39 → 0.0.44

data/app/components/primer/dropdown.d.ts

@@ -0,0 +1 @@
+import './dropdown/menu';

data/app/components/primer/{dropdown_component.html.erb → dropdown.html.erb}

@@ -1,6 +1,7 @@
 <%= render(Primer::DetailsComponent.new(**@system_arguments)) do |c| %>
-  <% c.summary(classes: @summary_classes) do %>
+  <% c.summary(**@button_arguments) do %>
     <%= button %>
+    <% if @with_caret %><div class="dropdown-caret"></div><% end %>
   <% end %>
 
   <% c.body do %>

data/app/components/primer/dropdown.js

@@ -0,0 +1 @@
+import './dropdown/menu';

data/app/components/primer/dropdown.rb

@@ -0,0 +1,149 @@
+# frozen_string_literal: true
+
+module Primer
+  # `Dropdown` is a lightweight context menu for housing navigation and actions.
+  # They're great for instances where you don't need the full power (and code) of the SelectMenu.
+  class Dropdown < Primer::Component
+    # Required trigger for the dropdown. Has the same arguments as <%= link_to_component(Primer::ButtonComponent) %>,
+    # but it is locked as a `summary` tag.
+    renders_one :button, lambda { |**system_arguments, &block|
+      @button_arguments = system_arguments
+      @button_arguments[:button] = true
+
+      view_context.capture { block&.call }
+    }
+
+    # Required context menu for the dropdown.
+    #
+    # @param as [Symbol] When `as` is `:list`, wraps the menu in a `<ul>` with a `<li>` for each item.
+    # @param direction [Symbol] <%= one_of(Primer::Dropdown::Menu::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::Menu"
+
+    # @example Default
+    #   <%= render(Primer::Dropdown.new) do |c| %>
+    #     <% c.button do %>
+    #       Dropdown
+    #     <% end %>
+    #
+    #     <%= c.menu(header: "Options") do |menu|
+    #       menu.item { "Item 1" }
+    #       menu.item { "Item 2" }
+    #       menu.item { "Item 3" }
+    #     end %>
+    #   <% end %>
+    #
+    # @example With dividers
+    #
+    #   @description
+    #     Dividers can be used to separate a group of items. They don't have any content.
+    #   @code
+    #     <%= render(Primer::Dropdown.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" }
+    #         menu.item(divider: true)
+    #         menu.item { "Item 5" }
+    #         menu.item { "Item 6" }
+    #       end %>
+    #     <% end %>
+    #
+    # @example With direction
+    #   <%= render(Primer::Dropdown.new(display: :inline_block)) 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 { "Item 3" }
+    #       menu.item { "Item 4" }
+    #     end %>
+    #   <% end %>
+    #
+    # @example With caret
+    #   <%= render(Primer::Dropdown.new(with_caret: true)) do |c| %>
+    #     <% c.button do %>
+    #       Dropdown
+    #     <% end %>
+    #
+    #     <%= c.menu(header: "Options") do |menu|
+    #       menu.item { "Item 1" }
+    #       menu.item { "Item 2" }
+    #       menu.item { "Item 3" }
+    #       menu.item { "Item 4" }
+    #     end %>
+    #   <% end %>
+    #
+    # @example Customizing the button
+    #   <%= render(Primer::Dropdown.new) do |c| %>
+    #     <% c.button(scheme: :primary, variant: :small) do %>
+    #       Dropdown
+    #     <% end %>
+    #
+    #     <%= c.menu(header: "Options") do |menu|
+    #       menu.item { "Item 1" }
+    #       menu.item { "Item 2" }
+    #       menu.item { "Item 3" }
+    #       menu.item { "Item 4" }
+    #     end %>
+    #   <% end %>
+    #
+    # @example Menu as list
+    #   <%= render(Primer::Dropdown.new) do |c| %>
+    #     <% c.button do %>
+    #       Dropdown
+    #     <% end %>
+    #
+    #     <%= c.menu(as: :list, 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 %>
+    #
+    # @example Customizing menu items
+    #   <%= render(Primer::Dropdown.new) do |c| %>
+    #     <% c.button do %>
+    #       Dropdown
+    #     <% end %>
+    #
+    #     <%= c.menu(header: "Options") do |menu|
+    #       menu.item(tag: :button) { "Item 1" }
+    #       menu.item(classes: "custom-class") { "Item 2" }
+    #       menu.item { "Item 3" }
+    #     end %>
+    #   <% end %>
+    #
+    # @param overlay [Symbol] <%= one_of(Primer::DetailsComponent::OVERLAY_MAPPINGS.keys) %>
+    # @param with_caret [Boolean] Whether or not a caret should be rendered in the button.
+    # @param system_arguments [Hash] <%= link_to_system_arguments_docs %>
+    def initialize(overlay: :default, with_caret: false, **system_arguments)
+      @with_caret = with_caret
+
+      @system_arguments = system_arguments
+      @system_arguments[:overlay] = overlay
+      @system_arguments[:reset] = true
+      @system_arguments[:classes] = class_names(
+        @system_arguments[:classes],
+        "dropdown"
+      )
+    end
+
+    def render?
+      button.present? && menu.present?
+    end
+  end
+end

data/app/components/primer/dropdown.ts

@@ -0,0 +1 @@
+import './dropdown/menu'

data/app/components/primer/dropdown/menu.d.ts

@@ -0,0 +1 @@
+import '@github/details-menu-element';

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

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

data/app/components/primer/dropdown/menu.js

@@ -0,0 +1 @@
+import '@github/details-menu-element';

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

@@ -0,0 +1,99 @@
+# frozen_string_literal: true
+
+module Primer
+  class Dropdown
+    # This component is part of `Dropdown` and should not be
+    # used as a standalone component.
+    class Menu < Primer::Component
+      AS_DEFAULT = :default
+      AS_OPTIONS = [AS_DEFAULT, :list].freeze
+
+      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
+
+      # @param tag [Symbol] <%= one_of(Primer::Dropdown::Menu::Item::TAG_OPTIONS) %>.
+      # @param divider [Boolean] Whether the item is a divider without any function.
+      # @param system_arguments [Hash] <%= link_to_system_arguments_docs %>
+      renders_many :items, lambda { |divider: false, **system_arguments|
+        Primer::Dropdown::Menu::Item.new(as: @as, divider: divider, **system_arguments)
+      }
+
+      # @param as [Symbol] When `as` is `:list`, wraps the menu in a `<ul>` with a `<li>` for each item.
+      # @param direction [Symbol] <%= one_of(Primer::Dropdown::Menu::DIRECTION_OPTIONS) %>.
+      # @param header [String] Header to be displayed above the menu.
+      # @param system_arguments [Hash] <%= link_to_system_arguments_docs %>
+      def initialize(as: AS_DEFAULT, direction: DIRECTION_DEFAULT, scheme: SCHEME_DEFAULT, header: nil, **system_arguments)
+        @header = header
+        @direction = direction
+        @as = fetch_or_fallback(AS_OPTIONS, as, AS_DEFAULT)
+
+        @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
+
+      private
+
+      def list?
+        @as == :list
+      end
+
+      # Items to be rendered in the `Dropdown` menu.
+      class Item < Primer::Component
+        TAG_DEFAULT = :a
+        BUTTON_TAGS = [:button, :summary].freeze
+        TAG_OPTIONS = [TAG_DEFAULT, *BUTTON_TAGS].freeze
+
+        def initialize(as:, tag: TAG_DEFAULT, divider: false, **system_arguments)
+          @divider = divider
+          @as = as
+
+          @system_arguments = system_arguments
+          @system_arguments[:tag] = fetch_or_fallback(TAG_OPTIONS, tag, TAG_DEFAULT)
+          @system_arguments[:tag] = :li if list? && divider?
+          @system_arguments[:role] ||= :menuitem
+          @system_arguments[:role] = :separator if divider
+          @system_arguments[:classes] = class_names(
+            @system_arguments[:classes],
+            "dropdown-item" => !divider,
+            "dropdown-divider" => divider
+          )
+        end
+
+        def call
+          component = if BUTTON_TAGS.include?(@system_arguments[:tag])
+                        Primer::ButtonComponent.new(scheme: :link, **@system_arguments)
+                      else
+                        Primer::BaseComponent.new(**@system_arguments)
+                      end
+
+          # divider has no content
+          render(component) if divider?
+
+          render(component) { content }
+        end
+
+        def divider?
+          @divider
+        end
+
+        def list?
+          @as == :list
+        end
+      end
+    end
+  end
+end

data/app/components/primer/dropdown/menu.ts

@@ -0,0 +1 @@
+import '@github/details-menu-element'

data/app/components/primer/flash_component.rb

@@ -35,7 +35,7 @@ module Primer
     #   <%= render(Primer::FlashComponent.new(dismissible: true)) { "This is a dismissible flash message!" } %>
     #
     # @example Icon
-    #   <%= render(Primer::FlashComponent.new(icon: "people")) { "This is a flash message with an icon!" } %>
+    #   <%= render(Primer::FlashComponent.new(icon: :people)) { "This is a flash message with an icon!" } %>
     #
     # @example With actions
     #   <%= render(Primer::FlashComponent.new) do |component| %>
@@ -48,7 +48,7 @@ module Primer
     # @param full [Boolean] Whether the component should take up the full width of the screen.
     # @param spacious [Boolean] Whether to add margin to the bottom of the component.
     # @param dismissible [Boolean] Whether the component can be dismissed with an X button.
-    # @param icon [String] Name of Octicon icon to use.
+    # @param icon [Symbol] Name of Octicon icon to use.
     # @param scheme [Symbol] <%= one_of(Primer::FlashComponent::SCHEME_MAPPINGS.keys) %>
     # @param system_arguments [Hash] <%= link_to_system_arguments_docs %>
     def initialize(full: false, spacious: false, dismissible: false, icon: nil, scheme: DEFAULT_SCHEME, **system_arguments)

data/app/components/primer/flex_component.rb

@@ -5,7 +5,32 @@ module Primer
   # 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).
+  #
+  # @deprecated
+  #   Use <%= link_to_component(Primer::BoxComponent) %> instead.
+  #
+  #   **Before**:
+  #
+  #   ```erb
+  #   <%%= render Primer::FlexComponent.new(justify_content: :center) %>
+  #   <%%= render Primer::FlexComponent.new(inline: true) %>
+  #   <%%= render Primer::FlexComponent.new(flex_wrap: true) %>
+  #   <%%= render Primer::FlexComponent.new(align_items: :start) %>
+  #   <%%= render Primer::FlexComponent.new(direction: :column) %>
+  #   ```
+  #
+  #   **After**:
+  #
+  #   ```erb
+  #   <%%= render Primer::BoxComponent.new(display: :flex, justify_content: :center) %>
+  #   <%%= render Primer::BoxComponent.new(display: :inline_flex) %>
+  #   <%%= render Primer::BoxComponent.new(display: :flex, flex_wrap: :wrap) %>
+  #   <%%= render Primer::BoxComponent.new(display: :flex, align_items: :start) %>
+  #   <%%= render Primer::BoxComponent.new(display: :flex, direction: :column) %>
+  #   ```
   class FlexComponent < Primer::Component
+    status :deprecated
+
     JUSTIFY_CONTENT_DEFAULT = nil
     JUSTIFY_CONTENT_MAPPINGS = {
       flex_start: "flex-justify-start",
@@ -77,6 +102,8 @@ module Primer
       direction: nil,
       **system_arguments
     )
+      deprecated_component_warning(new_class: Primer::BoxComponent, version: "0.0.40")
+
       @align_items = fetch_or_fallback(ALIGN_ITEMS_OPTIONS, align_items, ALIGN_ITEMS_DEFAULT)
       @justify_content = fetch_or_fallback(JUSTIFY_CONTENT_OPTIONS, justify_content, JUSTIFY_CONTENT_DEFAULT)
       @flex_wrap = fetch_or_fallback(FLEX_WRAP_OPTIONS, flex_wrap, FLEX_WRAP_DEFAULT)

data/app/components/primer/flex_item_component.rb

@@ -38,7 +38,7 @@ module Primer
     # @param flex_auto [Boolean] Fills available space and auto-sizes based on the content. Defaults to <%= Primer::FlexItemComponent::FLEX_AUTO_DEFAULT %>
     # @param system_arguments [Hash] <%= link_to_system_arguments_docs %>
     def initialize(flex_auto: FLEX_AUTO_DEFAULT, **system_arguments)
-      deprecated_component_warning(new_class: Primer::BoxComponent, version: "0.0.39")
+      deprecated_component_warning(new_class: Primer::BoxComponent, version: "0.0.40")
 
       @system_arguments = system_arguments
       @system_arguments[:classes] =

data/app/components/primer/heading_component.rb

@@ -1,20 +1,21 @@
 # frozen_string_literal: true
 
 module Primer
-  # `Heading` can be used to communicate page organization and hierarchy.
+  # `Heading` should be used to communicate page organization and hierarchy.
   #
-  # - Set tag to one of `:h1`, `:h2`, `:h3`, `:h4`, `:h5`, `:h6` based on what is
-  #   appropriate for the page context.
+  # - Set tag to one of `:h1`, `:h2`, `:h3`, `:h4`, `:h5`, `:h6` based on what is appropriate for the page context.
   # - Use `Heading` as the title of a section or sub section.
-  # - Do not use `Heading` for styling alone. To style text without conveying heading semantics,
-  #   consider using <%= link_to_component(Primer::TextComponent) %> with relevant <%= link_to_typography_docs %>.
-  # - Do not jump heading levels. For instance, do not follow a `<h1>` with an `<h3>`. Heading levels should
-  #   increase by one in ascending order.
+  # - Do not use `Heading` for styling alone. For simply styling text, consider using <%= link_to_component(Primer::Beta::Text) %> with relevant <%= link_to_typography_docs %>
+  #   such as `font_size` and `font_weight`.
+  # - Do not jump heading levels. For instance, do not follow a `<h1>` with an `<h3>`. Heading levels should increase by one in ascending order.
   #
   # @accessibility
-  #   Headings convey semantic meaning. Assistive technology users rely on headings to quickly navigate and scan information on a page.
-  #   Inappropriate use of headings can lead to a confusing experience.
-  #   [Learn more about best heading practices (WAI Headings)](https://www.w3.org/WAI/tutorials/page-structure/headings/)
+  #   While sighted users rely on visual cues such as font size changes to determine what the heading is, assistive technology users rely on programatic cues that can be read out.
+  #   When text on a page is visually implied to be a heading, ensure that it is coded as a heading. Additionally, visually implied heading level and coded heading level should be
+  #   consistent. [See WCAG success criteria: 1.3.1: Info and Relationships](https://www.w3.org/WAI/WCAG21/Understanding/info-and-relationships.html)
+  #
+  #   Headings allow assistive technology users to quickly navigate around a page. Navigation to text that is not meant to be a heading can be a confusing experience.
+  #   <%= link_to_heading_practices %>
   class HeadingComponent < Primer::Component
     status :beta
 
@@ -29,14 +30,6 @@ module Primer
     #   <%= render(Primer::HeadingComponent.new(tag: :h5)) { "H5 Text" } %>
     #   <%= render(Primer::HeadingComponent.new(tag: :h6)) { "H6 Text" } %>
     #
-    # @example With `font_size`
-    #   <%= render(Primer::HeadingComponent.new(tag: :h1, font_size: 6)) { "h1 tag, font_size 6" } %>
-    #   <%= render(Primer::HeadingComponent.new(tag: :h2, font_size: 3)) { "h2 tag, font_size 3" } %>
-    #   <%= render(Primer::HeadingComponent.new(tag: :h3, font_size: 2)) { "h3 tag, font_size 2" } %>
-    #   <%= render(Primer::HeadingComponent.new(tag: :h4, font_size: 0)) { "h4 tag, font_size 0" } %>
-    #   <%= render(Primer::HeadingComponent.new(tag: :h5, font_size: 1)) { "h5 tag, font_size 1" } %>
-    #   <%= render(Primer::HeadingComponent.new(tag: :h6, font_size: 4)) { "h6 tag, font_size 4" } %>
-    #
     # @param tag [String]  <%= one_of(Primer::HeadingComponent::TAG_OPTIONS) %>
     # @param system_arguments [Hash] <%= link_to_system_arguments_docs %>
     def initialize(tag:, **system_arguments)

data/app/components/primer/hidden_text_expander.rb

@@ -10,14 +10,14 @@ module Primer
     #   <%= render(Primer::HiddenTextExpander.new(inline: true)) %>
     #
     # @example Styling the button
-    #   <%= render(Primer::HiddenTextExpander.new(button_arguments: { p: 1, classes: "my-custom-class" })) %>
+    #   <%= render(Primer::HiddenTextExpander.new(button_arguments: { p: 1, classes: "custom-class" })) %>
     #
     # @param inline [Boolean] Whether or not the expander is inline.
     # @param button_arguments [Hash] <%= link_to_system_arguments_docs %> for the button element.
     # @param system_arguments [Hash] <%= link_to_system_arguments_docs %>
     def initialize(inline: false, button_arguments: {}, **system_arguments)
       @system_arguments = system_arguments
-      @system_arguments[:tag] ||= :span
+      @system_arguments[:tag] = :span
       @system_arguments[:classes] = class_names(
         "hidden-text-expander",
         @system_arguments[:classes],
@@ -34,7 +34,7 @@ module Primer
 
     def call
       render(Primer::BaseComponent.new(**@system_arguments)) do
-        render(Primer::BaseButton.new(**@button_arguments)) { "&hellip;" }
+        render(Primer::BaseButton.new(**@button_arguments)) { "&hellip;".html_safe }
       end
     end
   end