primer_view_components 0.0.38 → 0.0.43

data/app/components/primer/button_group.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module Primer
-  # Use ButtonGroup to render a series of buttons.
+  # Use `ButtonGroup` to render a series of buttons.
   class ButtonGroup < Primer::Component
     status :beta
 
@@ -22,7 +22,7 @@ module Primer
     #     <% component.button(scheme: :primary) { "Primary" } %>
     #     <% component.button(scheme: :danger) { "Danger" } %>
     #     <% component.button(scheme: :outline) { "Outline" } %>
-    #     <% component.button(classes: "my-class") { "Custom class" } %>
+    #     <% component.button(classes: "custom-class") { "Custom class" } %>
     #   <% end %>
     #
     # @example Variants
@@ -46,7 +46,7 @@ module Primer
     def initialize(variant: Primer::ButtonComponent::DEFAULT_VARIANT, **system_arguments)
       @variant = variant
       @system_arguments = system_arguments
-      @system_arguments[:tag] ||= :div
+      @system_arguments[:tag] = :div
 
       @system_arguments[:classes] = class_names(
         "BtnGroup",

data/app/components/primer/button_marketing_component.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module Primer
-  # Use buttons for actions (e.g. in forms). Use links for destinations, or moving from one page to another.
+  # Use `ButtonMarketing` for actions (e.g. in forms). Use links for destinations, or moving from one page to another.
   class ButtonMarketingComponent < Primer::Component
     DEFAULT_SCHEME = :default
     SCHEME_MAPPINGS = {

data/app/components/primer/clipboard_copy.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module Primer
-  # Use ClipboardCopy to copy element text content or input values to the clipboard.
+  # Use `ClipboardCopy` to copy element text content or input values to the clipboard.
   class ClipboardCopy < Primer::Component
     status :alpha
 

data/app/components/primer/clipboard_copy_component.js

@@ -1,4 +1,5 @@
 import '@github/clipboard-copy-element';
+const CLIPBOARD_COPY_TIMER_DURATION = 2000;
 function toggleSVG(svg) {
     if (svg.style.display === '' || svg.style.display === 'block') {
         svg.style.display = 'none';
@@ -10,16 +11,24 @@ function toggleSVG(svg) {
 // Toggle a copy button.
 function toggleCopyButton(button) {
     const [clippyIcon, checkIcon] = button.querySelectorAll('.octicon');
-    if (clippyIcon) {
-        toggleSVG(clippyIcon);
-    }
-    if (checkIcon) {
-        toggleSVG(checkIcon);
-    }
+    if (!clippyIcon || !checkIcon)
+        return;
+    toggleSVG(clippyIcon);
+    toggleSVG(checkIcon);
 }
+const clipboardCopyElementTimers = new WeakMap();
 document.addEventListener('clipboard-copy', function ({ target }) {
     if (!(target instanceof HTMLElement))
         return;
-    toggleCopyButton(target);
-    setTimeout(toggleCopyButton, 2000, target);
+    if (!target.hasAttribute('data-view-component'))
+        return;
+    const currentTimeout = clipboardCopyElementTimers.get(target);
+    if (currentTimeout) {
+        clearTimeout(currentTimeout);
+        clipboardCopyElementTimers.delete(target);
+    }
+    else {
+        toggleCopyButton(target);
+    }
+    clipboardCopyElementTimers.set(target, setTimeout(toggleCopyButton, CLIPBOARD_COPY_TIMER_DURATION, target));
 });

data/app/components/primer/clipboard_copy_component.ts

@@ -1,5 +1,7 @@
 import '@github/clipboard-copy-element'
 
+const CLIPBOARD_COPY_TIMER_DURATION = 2000
+
 function toggleSVG(svg: SVGElement) {
   if (svg.style.display === '' || svg.style.display === 'block') {
     svg.style.display = 'none'
@@ -12,17 +14,26 @@ function toggleSVG(svg: SVGElement) {
 function toggleCopyButton(button: HTMLElement) {
   const [clippyIcon, checkIcon] = button.querySelectorAll<SVGElement>('.octicon')
 
-  if (clippyIcon) {
-    toggleSVG(clippyIcon)
-  }
-  if (checkIcon) {
-    toggleSVG(checkIcon)
-  }
+  if (!clippyIcon || !checkIcon) return
+
+  toggleSVG(clippyIcon)
+  toggleSVG(checkIcon)
 }
 
+const clipboardCopyElementTimers = new WeakMap<HTMLElement, number>()
+
 document.addEventListener('clipboard-copy', function ({target}) {
   if (!(target instanceof HTMLElement)) return
-  toggleCopyButton(target)
+  if (!target.hasAttribute('data-view-component')) return
+
+  const currentTimeout = clipboardCopyElementTimers.get(target)
+
+  if (currentTimeout) {
+    clearTimeout(currentTimeout)
+    clipboardCopyElementTimers.delete(target)
+  } else {
+    toggleCopyButton(target)
+  }
 
-  setTimeout(toggleCopyButton, 2000, target)
+  clipboardCopyElementTimers.set(target, setTimeout(toggleCopyButton, CLIPBOARD_COPY_TIMER_DURATION, target))
 })

data/app/components/primer/close_button.rb

@@ -1,13 +1,15 @@
 # frozen_string_literal: true
 
 module Primer
-  # Use CloseButton to render an `×` without default button styles.
+  # Use `CloseButton` to render an `×` without default button styles.
   #
   # @accessibility
-  #   CloseButton has a default `aria-label` of "Close" to provides assistive technologies with an accessible label.
+  #   `CloseButton` has a default `aria-label` of "Close" to provides assistive technologies with an accessible label.
   #   You may choose to override this label with something more descriptive via [system_arguments][0].
   # [0]: https://primer.style/view-components/system-arguments#html-attributes
   class CloseButton < Primer::Component
+    status :beta
+
     DEFAULT_TYPE = :button
     TYPE_OPTIONS = [DEFAULT_TYPE, :submit].freeze
 

data/app/components/primer/component.rb

@@ -1,18 +1,37 @@
 # frozen_string_literal: true
 
-require "octicons_helper/helper"
 require "view_component/version"
 
 module Primer
   # @private
   class Component < ViewComponent::Base
-    include ViewComponent::SlotableV2 unless ViewComponent::VERSION::STRING.to_f >= 2.28
+    include ViewComponent::SlotableV2 unless ViewComponent::Base < ViewComponent::SlotableV2
     include ClassNameHelper
     include FetchOrFallbackHelper
-    include OcticonsHelper
     include TestSelectorHelper
     include JoinStyleArgumentsHelper
     include ViewHelper
     include Status::Dsl
+
+    private
+
+    def deprecated_component_warning(new_class: nil, version: nil)
+      return if Rails.env.production? || silence_deprecations?
+
+      message = "#{self.class.name} is deprecated"
+      message += " and will be removed in v#{version}." if version
+      message += " Use #{new_class.name} instead." if new_class
+
+      ActiveSupport::Deprecation.warn(message)
+    end
+
+    def validate_aria_label
+      aria_label = @system_arguments[:"aria-label"] || @system_arguments.dig(:aria, :label)
+      raise ArgumentError, "`aria-label` is required." if aria_label.nil? && !Rails.env.production?
+    end
+
+    def silence_deprecations?
+      Rails.application.config.primer_view_components.silence_deprecations
+    end
   end
 end

data/app/components/primer/counter_component.rb

@@ -1,7 +1,12 @@
 # frozen_string_literal: true
 
 module Primer
-  # Use Primer::CounterComponent to add a count to navigational elements and buttons.
+  # Use `Counter` to add a count to navigational elements and buttons.
+  #
+  # @accessibility
+  #   Always use `Counter` with adjacent text that provides supplementary information regarding what the count is for. For instance, `Counter`
+  #   should be accompanied with text such as `issues` or `pull requests`.
+  #
   class CounterComponent < Primer::Component
     status :beta
 

data/app/components/primer/details_component.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module Primer
-  # Use DetailsComponent to reveal content after clicking a button.
+  # Use `DetailsComponent` to reveal content after clicking a button.
   class DetailsComponent < Primer::Component
     status :beta
 

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

@@ -2,7 +2,7 @@
 
 module Primer
   module Dropdown
-    # This component is part of `Primer::DropdownComponent` and should not be
+    # This component is part of `Dropdown` and should not be
     # used as a standalone component.
     class MenuComponent < Primer::Component
       SCHEME_DEFAULT = :default

data/app/components/primer/dropdown_component.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module Primer
-  # Dropdowns are lightweight context menus for housing navigation and actions.
+  # `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 select menu.
   class DropdownComponent < Primer::Component
     # Required trigger for the dropdown. Only accepts a content.

data/app/components/primer/flash_component.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module Primer
-  # Use the Flash component to inform users of successful or pending actions.
+  # Use `Flash` to inform users of successful or pending actions.
   class FlashComponent < Primer::Component
     status :beta
 
@@ -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

@@ -1,11 +1,36 @@
 # frozen_string_literal: true
 
 module Primer
-  # Use FlexComponent to make an element lay out its content using the flexbox model.
+  # Use `Flex` 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).
+  #
+  # @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

@@ -1,9 +1,26 @@
 # frozen_string_literal: true
 
 module Primer
-  # Use FlexItemComponent to specify the ability of a flex item to alter its
+  # Use `FlexItem` to specify the ability of a flex item to alter its
   # dimensions to fill available space
+  #
+  # @deprecated
+  #   Use <%= link_to_component(Primer::BoxComponent) %> instead.
+  #
+  #   **Before**:
+  #
+  #   ```erb
+  #   <%%= render Primer::FlexItemComponent.new(flex_auto: :auto) %>
+  #   ```
+  #
+  #   **After**:
+  #
+  #   ```erb
+  #   <%%= render Primer::BoxComponent.new(flex: :auto) %>
+  #   ```
   class FlexItemComponent < Primer::Component
+    status :deprecated
+
     FLEX_AUTO_DEFAULT = false
     FLEX_AUTO_ALLOWED_VALUES = [FLEX_AUTO_DEFAULT, true].freeze
 
@@ -21,6 +38,8 @@ 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.40")
+
       @system_arguments = system_arguments
       @system_arguments[:classes] =
         class_names(

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.
-  # - 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.
+  # - 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. For simply styling text, consider using <%= link_to_component(Primer::TextComponent) %> 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

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module Primer
-  # Use HiddenTextExpander to indicate and toggle hidden text.
+  # Use `HiddenTextExpander` to indicate and toggle hidden text.
   class HiddenTextExpander < Primer::Component
     # @example Default
     #   <%= render(Primer::HiddenTextExpander.new) %>
@@ -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

data/app/components/primer/icon_button.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+module Primer
+  # Use `IconButton` to render Icon-only buttons without the default button styles.
+  #
+  # @accessibility
+  #   `IconButton` requires an `aria-label`, which will provide assistive technologies with an accessible label.
+  #   The `aria-label` should describe the action to be invoked rather than the icon itself. For instance,
+  #   if your `IconButton` renders a magnifying glass icon and invokves a search action, the `aria-label` should be
+  #   `"Search"` instead of `"Magnifying glass"`.
+  #   [Learn more about best functional image practices (WAI Images)](https://www.w3.org/WAI/tutorials/images/functional)
+  class IconButton < Primer::Component
+    status :beta
+
+    DEFAULT_SCHEME = :default
+    SCHEME_MAPPINGS = {
+      DEFAULT_SCHEME => "",
+      :danger => "btn-octicon-danger"
+    }.freeze
+    SCHEME_OPTIONS = SCHEME_MAPPINGS.keys
+    # @example Default
+    #
+    #   <%= render(Primer::IconButton.new(icon: :search, "aria-label": "Search")) %>
+    #
+    # @example Schemes
+    #
+    #   <%= render(Primer::IconButton.new(icon: :search, "aria-label": "Search")) %>
+    #   <%= render(Primer::IconButton.new(icon: :trash, "aria-label": "Delete", scheme: :danger)) %>
+    #
+    # @example In a BorderBox
+    #
+    #   <%= render(Primer::BorderBoxComponent.new) do |component| %>
+    #     <% component.body do %>
+    #       <%= render(Primer::TextComponent.new(pr: 2)) { "Body" } %>
+    #       <%= render(Primer::IconButton.new(icon: :pencil, box: true, "aria-label": "Edit")) %>
+    #     <% end %>
+    #   <% end %>
+    #
+    # @param scheme [Symbol] <%= one_of(Primer::IconButton::SCHEME_OPTIONS) %>
+    # @param icon [String] Name of <%= link_to_octicons %> to use.
+    # @param tag [Symbol] <%= one_of(Primer::BaseButton::TAG_OPTIONS) %>
+    # @param type [Symbol] <%= one_of(Primer::BaseButton::TYPE_OPTIONS) %>
+    # @param box [Boolean] Whether the button is in a <%= link_to_component(Primer::BorderBoxComponent) %>. If `true`, the button will have the `Box-btn-octicon` class.
+    # @param system_arguments [Hash] <%= link_to_system_arguments_docs %>
+    def initialize(scheme: DEFAULT_SCHEME, icon:, box: false, **system_arguments)
+      @icon = icon
+
+      @system_arguments = system_arguments
+      @system_arguments[:classes] = class_names(
+        "btn-octicon",
+        SCHEME_MAPPINGS[fetch_or_fallback(SCHEME_OPTIONS, scheme, DEFAULT_SCHEME)],
+        system_arguments[:classes],
+        "Box-btn-octicon" => box
+      )
+
+      validate_aria_label
+    end
+
+    def call
+      render(Primer::BaseButton.new(**@system_arguments)) do
+        render(Primer::OcticonComponent.new(icon: @icon))
+      end
+    end
+  end
+end