primer_view_components 0.0.36 → 0.0.41

data/app/components/primer/popover_component.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module Primer
-  # Use popovers to bring attention to specific user interface elements, typically to suggest an action or to guide users through a new experience.
+  # Use `Popover` to bring attention to specific user interface elements, typically to suggest an action or to guide users through a new experience.
   #
   # By default, the popover renders with absolute positioning, meaning it should usually be wrapped in an element with a relative position in order to be positioned properly. To render the popover with relative positioning, use the relative property.
   class PopoverComponent < Primer::Component

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

@@ -1,3 +1,6 @@
 import './auto_complete/auto_complete';
+import './clipboard_copy_component';
 import './tab_container_component';
 import './time_ago_component';
+import './local_time';
+import './image_crop';

data/app/components/primer/primer.js

@@ -1,3 +1,6 @@
 import './auto_complete/auto_complete';
+import './clipboard_copy_component';
 import './tab_container_component';
 import './time_ago_component';
+import './local_time';
+import './image_crop';

data/app/components/primer/primer.ts

@@ -1,3 +1,6 @@
 import './auto_complete/auto_complete'
+import './clipboard_copy_component'
 import './tab_container_component'
 import './time_ago_component'
+import './local_time'
+import './image_crop'

data/app/components/primer/progress_bar_component.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module Primer
-  # Use ProgressBar to visualize task completion.
+  # Use `ProgressBar` to visualize task completion.
   class ProgressBarComponent < Primer::Component
     status :beta
 

data/app/components/primer/spinner_component.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module Primer
-  # Use Primer::SpinnerComponent to let users know that content is being loaded.
+  # Use `Spinner` to let users know that content is being loaded.
   class SpinnerComponent < Primer::Component
     status :beta
 
@@ -27,10 +27,10 @@ module Primer
     #   <%= render(Primer::SpinnerComponent.new(size: :large)) %>
     #
     # @param size [Symbol] <%= one_of(Primer::SpinnerComponent::SIZE_MAPPINGS) %>
-    def initialize(size: DEFAULT_SIZE, **system_arguments)
+    def initialize(size: DEFAULT_SIZE, style: DEFAULT_STYLE, **system_arguments)
       @system_arguments = system_arguments
       @system_arguments[:tag] = :svg
-      @system_arguments[:style] ||= DEFAULT_STYLE
+      @system_arguments[:style] ||= style
       @system_arguments[:animation] = :rotate
       @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)]

data/app/components/primer/state_component.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module Primer
-  # Component for rendering the status of an item.
+  # Use `State` for rendering the status of an item.
   class StateComponent < Primer::Component
     status :beta
 
@@ -29,7 +29,7 @@ module Primer
     SIZE_OPTIONS = SIZE_MAPPINGS.keys
 
     TAG_DEFAULT = :span
-    TAG_OPTIONS = [TAG_DEFAULT, :div, :a].freeze
+    TAG_OPTIONS = [TAG_DEFAULT, :div].freeze
 
     # @example Default
     #   <%= render(Primer::StateComponent.new(title: "title")) { "State" } %>

data/app/components/primer/subhead_component.rb

@@ -1,16 +1,28 @@
 # frozen_string_literal: true
 
 module Primer
-  # Use the Subhead component for page headings.
+  # Use `Subhead` as the start of a section. The `:heading` slot will render an `<h2>` font-sized text.
+  #
+  # - Optionally set the `:description` slot to render a short description and the `:actions` slot for a related action.
+  # - Use a succint, one-line description for the `:description` slot. For longer descriptions, omit the description slot and render a paragraph below the `Subhead`.
+  # - Use the actions slot to render a related action to the right of the heading. Use <%= link_to_component(Primer::ButtonComponent) %> or <%= link_to_component(Primer::LinkComponent) %>.
+  #
+  # @accessibility
+  #   The `:heading` slot defaults to rendering a `<div>`. Update the tag to a heading element with the appropriate level to improve page navigation for assistive technologies.
+  #   <%= link_to_heading_practices %>
   class SubheadComponent < Primer::Component
     status :beta
 
+    DEFAULT_HEADING_TAG = :div
+    HEADING_TAG_OPTIONS = [DEFAULT_HEADING_TAG, :h1, :h2, :h3, :h4, :h5, :h6].freeze
+
     # The heading
     #
+    # @param tag [Symbol] <%= one_of(Primer::SubheadComponent::HEADING_TAG_OPTIONS)%>
     # @param danger [Boolean] Whether to style the heading as dangerous.
     # @param system_arguments [Hash] <%= link_to_system_arguments_docs %>
-    renders_one :heading, lambda { |danger: false, **system_arguments|
-      system_arguments[:tag] ||= :div
+    renders_one :heading, lambda { |tag: DEFAULT_HEADING_TAG, danger: false, **system_arguments|
+      system_arguments[:tag] = fetch_or_fallback(HEADING_TAG_OPTIONS, tag, DEFAULT_HEADING_TAG)
       system_arguments[:classes] = class_names(
         system_arguments[:classes],
         "Subhead-heading",
@@ -42,7 +54,7 @@ module Primer
 
     # @example Default
     #   <%= render(Primer::SubheadComponent.new) do |component| %>
-    #     <% component.heading do %>
+    #     <% component.heading(tag: :h3) do %>
     #       My Heading
     #     <% end %>
     #     <% component.description do %>
@@ -50,6 +62,24 @@ module Primer
     #     <% end %>
     #   <% end %>
     #
+    # @example With dangerous heading
+    #   <%= render(Primer::SubheadComponent.new) do |component| %>
+    #     <% component.heading(tag: :h3, danger: true) do %>
+    #       My Heading
+    #     <% end %>
+    #     <% component.description do %>
+    #       My Description
+    #     <% end %>
+    #   <% end %>
+    #
+    # @example With long description
+    #   <%= render(Primer::SubheadComponent.new) do |component| %>
+    #     <% component.heading(tag: :h3) do %>
+    #       My Heading
+    #     <% end %>
+    #   <% end %>
+    #   <p> This is a longer description that is sitting below the Subhead. It's much longer than a description that could sit comfortably in the Subhead. </p>
+    #
     # @example Without border
     #   <%= render(Primer::SubheadComponent.new(hide_border: true)) do |component| %>
     #     <% component.heading do %>

data/app/components/primer/tab_container_component.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module Primer
-  # Use TabContainer to create tabbed content with keyboard support. This component does not add any styles.
+  # Use `TabContainer` to create tabbed content with keyboard support. This component does not add any styles.
   # It only provides the tab functionality. If you want styled Tabs you can look at <%= link_to_component(Primer::TabNavComponent) %>.
   #
   # This component requires javascript.

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

@@ -1,5 +1,7 @@
 <%= wrapper do %>
   <%= render Primer::BaseComponent.new(**@system_arguments) do %>
+    <%= extra %>
+
     <%= render Primer::BaseComponent.new(**@body_arguments) do %>
       <% tabs.each do |tab| %>
         <%= tab %>

data/app/components/primer/tab_nav_component.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module Primer
-  # Use TabNav to style navigation with a tab-based selected state, typically used for navigation placed at the top of the page.
+  # Use `TabNav` to style navigation with a tab-based selected state, typically used for navigation placed at the top of the page.
   class TabNavComponent < Primer::Component
     include Primer::TabbedComponentHelper
 
@@ -22,6 +22,9 @@ module Primer
       )
     }
 
+    # Renders extra content to the `TabNav`. This will be rendered after the tabs.
+    renders_one :extra
+
     # @example Default
     #   <%= render(Primer::TabNavComponent.new(label: "Default")) do |c| %>
     #     <% c.tab(selected: true, href: "#") { "Tab 1" }%>
@@ -68,12 +71,24 @@ module Primer
     #     <% end %>
     #   <% end %>
     #
+    # @example With extra content
+    #   <%= render(Primer::TabNavComponent.new(label: "Default")) do |c| %>
+    #     <% c.tab(selected: true, href: "#") { "Tab 1" }%>
+    #     <% c.tab(href: "#") { "Tab 2" } %>
+    #     <% c.tab(href: "#") { "Tab 3" } %>
+    #     <% c.extra do %>
+    #       <%= render(Primer::ButtonComponent.new(float: :right)) { "Button" } %>
+    #     <% end %>
+    #   <% end %>
+    #
     # @param label [String] Used to set the `aria-label` on the top level `<nav>` element.
     # @param with_panel [Boolean] Whether the TabNav should navigate through pages or panels.
+    # @param body_arguments [Hash] <%= link_to_system_arguments_docs %> for the body wrapper.
     # @param system_arguments [Hash] <%= link_to_system_arguments_docs %>
-    def initialize(label:, with_panel: false, **system_arguments)
+    def initialize(label:, with_panel: false, body_arguments: {}, **system_arguments)
       @with_panel = with_panel
       @system_arguments = system_arguments
+      @body_arguments = body_arguments
 
       @system_arguments[:tag] ||= :div
       @system_arguments[:classes] = class_names(
@@ -81,15 +96,13 @@ module Primer
         system_arguments[:classes]
       )
 
-      @body_arguments = {
-        tag: navigation_tag(with_panel),
-        classes: "tabnav-tabs",
-        aria: {
-          label: label
-        }
-      }
-
+      @body_arguments[:tag] = navigation_tag(with_panel)
+      @body_arguments[:"aria-label"] = label
       @body_arguments[:role] = :tablist if @with_panel
+      @body_arguments[:classes] = class_names(
+        "tabnav-tabs",
+        body_arguments[:classes]
+      )
     end
   end
 end

data/app/components/primer/text_component.rb

@@ -1,18 +1,21 @@
 # frozen_string_literal: true
 
 module Primer
-  # The Text component is a wrapper component that will apply typography styles to the text inside.
+  # `Text` is a wrapper component that will apply typography styles to the text inside.
   class TextComponent < Primer::Component
     status :beta
 
+    DEFAULT_TAG = :span
+
     # @example Default
     #   <%= render(Primer::TextComponent.new(tag: :p, font_weight: :bold)) { "Bold Text" } %>
     #   <%= render(Primer::TextComponent.new(tag: :p, color: :text_danger)) { "Danger Text" } %>
     #
+    # @param tag [Symbol]
     # @param system_arguments [Hash] <%= link_to_system_arguments_docs %>
-    def initialize(**system_arguments)
+    def initialize(tag: DEFAULT_TAG, **system_arguments)
       @system_arguments = system_arguments
-      @system_arguments[:tag] ||= :span
+      @system_arguments[:tag] = tag
     end
 
     def call

data/app/components/primer/time_ago_component.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module Primer
-  # Use Primer::TimeAgoComponent to display a time relative to how long ago it was. This component requires JavaScript.
+  # Use `TimeAgo` to display a time relative to how long ago it was. This component requires JavaScript.
   class TimeAgoComponent < Primer::Component
     status :beta
 

data/app/components/primer/timeline_item_component.rb

@@ -19,7 +19,7 @@ module Primer
 
     # Badge that will be connected to other TimelineItems.
     #
-    # @param icon [String] Name of [Octicon](https://primer.style/octicons/) to use.
+    # @param icon [String] Name of <%= link_to_octicons %> to use.
     # @param system_arguments [Hash] <%= link_to_system_arguments_docs %>
     renders_one :badge, "BadgeComponent"
 

data/app/components/primer/{tooltip_component.rb → tooltip.rb}

@@ -1,8 +1,10 @@
 # frozen_string_literal: true
 
 module Primer
-  # The Tooltip component is a wrapper component that will apply a tooltip to the provided content.
-  class TooltipComponent < Primer::Component
+  # `Tooltip` is a wrapper component that will apply a tooltip to the provided content.
+  class Tooltip < Primer::Component
+    status :beta
+
     DIRECTION_DEFAULT = :n
     ALIGN_DEFAULT = :default
     MULTILINE_DEFAULT = false
@@ -28,34 +30,34 @@ module Primer
 
     # @example Default
     #   <div class="pt-5">
-    #     <%= render(Primer::TooltipComponent.new(label: "Even bolder")) { "Default Bold Text" } %>
+    #     <%= render(Primer::Tooltip.new(label: "Even bolder")) { "Default Bold Text" } %>
     #   </div>
     #
     # @example Wrapping another component
     #   <div class="pt-5">
-    #     <%= render(Primer::TooltipComponent.new(label: "Even bolder")) do %>
+    #     <%= render(Primer::Tooltip.new(label: "Even bolder")) do %>
     #       <%= render(Primer::ButtonComponent.new) { "Bold Button" } %>
     #     <% end %>
     #   </div>
     #
     # @example With a direction
     #   <div class="pt-5">
-    #     <%= render(Primer::TooltipComponent.new(label: "Even bolder", direction: :s)) { "Bold Text With a Direction" } %>
+    #     <%= render(Primer::Tooltip.new(label: "Even bolder", direction: :s)) { "Bold Text With a Direction" } %>
     #   </div>
     #
     # @example With an alignment
     #   <div class="pt-5">
-    #     <%= render(Primer::TooltipComponent.new(label: "Even bolder", direction: :s, alignment: :right_1)) { "Bold Text With an Alignment" } %>
+    #     <%= render(Primer::Tooltip.new(label: "Even bolder", direction: :s, alignment: :right_1)) { "Bold Text With an Alignment" } %>
     #   </div>
     #
     # @example Without a delay
     #   <div class="pt-5">
-    #     <%= render(Primer::TooltipComponent.new(label: "Even bolder", direction: :s, no_delay: true)) { "Bold Text without a delay" } %>
+    #     <%= render(Primer::Tooltip.new(label: "Even bolder", direction: :s, no_delay: true)) { "Bold Text without a delay" } %>
     #   </div>
     #
     # @param label [String] the text to appear in the tooltip
-    # @param direction [String] Direction of the tooltip. <%= one_of(Primer::TooltipComponent::DIRECTION_OPTIONS) %>
-    # @param align [String] Align tooltips to the left or right of an element, combined with a `direction` to specify north or south. <%= one_of(Primer::TooltipComponent::ALIGN_MAPPING.keys) %>
+    # @param direction [String] Direction of the tooltip. <%= one_of(Primer::Tooltip::DIRECTION_OPTIONS) %>
+    # @param align [String] Align tooltips to the left or right of an element, combined with a `direction` to specify north or south. <%= one_of(Primer::Tooltip::ALIGN_MAPPING.keys) %>
     # @param multiline [Boolean] Use this when you have long content
     # @param no_delay [Boolean] By default the tooltips have a slight delay before appearing. Set true to override this
     # @param system_arguments [Hash] <%= link_to_system_arguments_docs %>

data/app/components/primer/truncate.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module Primer
-  # Use Truncate to shorten overflowing text with an ellipsis.
+  # Use `Truncate` to shorten overflowing text with an ellipsis.
   class Truncate < Primer::Component
     status :beta
 

data/app/components/primer/underline_nav_component.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module Primer
-  # Use the UnderlineNav component to style navigation with a minimal
+  # Use `UnderlineNav` to style navigation with a minimal
   # underlined selected state, typically used for navigation placed at the top
   # of the page.
   class UnderlineNavComponent < Primer::Component

data/app/lib/primer/classify.rb

@@ -3,35 +3,29 @@
 module Primer
   # :nodoc:
   class Classify
-    DIRECTION_KEY = :direction
-    JUSTIFY_CONTENT_KEY = :justify_content
-    ALIGN_ITEMS_KEY = :align_items
     DISPLAY_KEY = :display
     SPACING_KEYS = Primer::Classify::Spacing::KEYS
-    RESPONSIVE_KEYS = ([DISPLAY_KEY, DIRECTION_KEY, JUSTIFY_CONTENT_KEY, ALIGN_ITEMS_KEY, :col, :float] + SPACING_KEYS).freeze
-    BREAKPOINTS = ["", "-sm", "-md", "-lg", "-xl"].freeze
 
     # Keys where we can simply translate { key: value } into ".key-value"
     CONCAT_KEYS = SPACING_KEYS + %i[hide position v float col text box_shadow].freeze
 
     INVALID_CLASS_NAME_PREFIXES =
-      (["bg-", "color-", "text-", "d-", "v-align-", "wb-", "text-", "box-shadow-"] + CONCAT_KEYS.map { |k| "#{k}-" }).freeze
+      (["bg-", "color-", "text-", "d-", "v-align-", "wb-", "box-shadow-"] + CONCAT_KEYS.map { |k| "#{k}-" }).freeze
 
     COLOR_KEY = :color
     BG_KEY = :bg
     VERTICAL_ALIGN_KEY = :vertical_align
     WORD_BREAK_KEY = :word_break
     TEXT_KEYS = %i[text_align font_weight].freeze
-    FLEX_KEY = :flex
-    FLEX_GROW_KEY = :flex_grow
-    FLEX_SHRINK_KEY = :flex_shrink
-    ALIGN_SELF_KEY = :align_self
     WIDTH_KEY = :width
     HEIGHT_KEY = :height
     BOX_SHADOW_KEY = :box_shadow
     VISIBILITY_KEY = :visibility
     ANIMATION_KEY = :animation
 
+    BREAKPOINTS = ["", "-sm", "-md", "-lg", "-xl"].freeze
+    RESPONSIVE_KEYS = ([DISPLAY_KEY, :col, :float] + SPACING_KEYS + Primer::Classify::Flex::RESPONSIVE_KEYS).freeze
+
     BOOLEAN_MAPPINGS = {
       underline: {
         mappings: [
@@ -89,6 +83,7 @@ module Primer
       BORDER_MARGIN_KEYS +
       TYPOGRAPHY_KEYS +
       TEXT_KEYS +
+      Primer::Classify::Flex::KEYS +
       [
         BORDER_KEY,
         BORDER_COLOR_KEY,
@@ -98,13 +93,6 @@ module Primer
         DISPLAY_KEY,
         VERTICAL_ALIGN_KEY,
         WORD_BREAK_KEY,
-        DIRECTION_KEY,
-        JUSTIFY_CONTENT_KEY,
-        ALIGN_ITEMS_KEY,
-        FLEX_KEY,
-        FLEX_GROW_KEY,
-        FLEX_SHRINK_KEY,
-        ALIGN_SELF_KEY,
         WIDTH_KEY,
         HEIGHT_KEY,
         BOX_SHADOW_KEY,
@@ -120,7 +108,7 @@ module Primer
         extracted_results[:class] = [
           validated_class_names(classes),
           extracted_results.delete(:classes)
-        ].compact.join(" ").presence
+        ].compact.join(" ").strip.presence
 
         extracted_results[:style] = [
           extracted_results.delete(:styles),
@@ -135,13 +123,13 @@ module Primer
       def validated_class_names(classes)
         return if classes.blank?
 
-        if ENV["RAILS_ENV"] == "development"
+        if ENV["RAILS_ENV"] == "development" && !ENV["PRIMER_WARNINGS_DISABLED"]
           invalid_class_names =
             classes.split(" ").each_with_object([]) do |class_name, memo|
               memo << class_name if INVALID_CLASS_NAME_PREFIXES.any? { |prefix| class_name.start_with?(prefix) }
             end
 
-          raise ArgumentError, "Use System Arguments (https://primer.style/view-components/system-arguments) instead of Primer CSS class #{'name'.pluralize(invalid_class_names.length)} #{invalid_class_names.to_sentence}. This warning will not be raised in production." if invalid_class_names.any?
+          raise ArgumentError, "Use System Arguments (https://primer.style/view-components/system-arguments) instead of Primer CSS class #{'name'.pluralize(invalid_class_names.length)} #{invalid_class_names.to_sentence}. This warning will not be raised in production. Set PRIMER_WARNINGS_DISABLED=1 to disable this warning." if invalid_class_names.any?
         end
 
         classes
@@ -216,23 +204,10 @@ module Primer
           memo[:classes] << "#{key.to_s.dasherize}-#{val}"
         elsif key == BORDER_RADIUS_KEY
           memo[:classes] << "rounded-#{val}"
-        elsif key == DIRECTION_KEY
-          memo[:classes] << "flex#{breakpoint}-#{val.to_s.dasherize}"
-        elsif key == JUSTIFY_CONTENT_KEY
-          formatted_value = val.to_s.gsub(/(flex\_|space\_)/, "")
-          memo[:classes] << "flex#{breakpoint}-justify-#{formatted_value}"
-        elsif key == ALIGN_ITEMS_KEY
-          memo[:classes] << "flex#{breakpoint}-items-#{val.to_s.gsub('flex_', '')}"
-        elsif key == FLEX_KEY
-          memo[:classes] << "flex-#{val}"
-        elsif key == FLEX_GROW_KEY
-          memo[:classes] << "flex-grow-#{val}"
-        elsif key == FLEX_SHRINK_KEY
-          memo[:classes] << "flex-shrink-#{val}"
-        elsif key == ALIGN_SELF_KEY
-          memo[:classes] << "flex-self-#{val}"
+        elsif Primer::Classify::Flex::KEYS.include?(key)
+          memo[:classes] << Primer::Classify::Flex.classes(key, val, breakpoint)
         elsif key == WIDTH_KEY || key == HEIGHT_KEY
-          if val == :fit || val == :fill
+          if val == :fit
             memo[:classes] << "#{key}-#{val}"
           else
             memo[key] = val