primer_view_components 0.0.39 → 0.0.44

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

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

data/app/components/primer/primer.js

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

data/app/components/primer/primer.ts

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

data/app/components/primer/spinner_component.rb

@@ -27,10 +27,12 @@ module Primer
     #   <%= render(Primer::SpinnerComponent.new(size: :large)) %>
     #
     # @param size [Symbol] <%= one_of(Primer::SpinnerComponent::SIZE_MAPPINGS) %>
-    def initialize(size: DEFAULT_SIZE, **system_arguments)
+    # @param style [String] Custom element styles.
+    # @param system_arguments [Hash] <%= link_to_system_arguments_docs %>
+    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/subhead_component.rb

@@ -1,16 +1,28 @@
 # frozen_string_literal: true
 
 module Primer
-  # Use `Subhead` 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_nav_component.html.erb

@@ -1,10 +1,14 @@
-<%= wrapper do %>
+<%= wrapper(**@wrapper_arguments) do %>
   <%= render Primer::BaseComponent.new(**@system_arguments) do %>
+    <%= extra if @align == :left %>
+
     <%= render Primer::BaseComponent.new(**@body_arguments) do %>
       <% tabs.each do |tab| %>
         <%= tab %>
       <% end %>
     <% end %>
+
+    <%= extra if @align == :right %>
   <% end %>
 
   <% if @with_panel %>

data/app/components/primer/tab_nav_component.rb

@@ -5,6 +5,11 @@ module Primer
   class TabNavComponent < Primer::Component
     include Primer::TabbedComponentHelper
 
+    status :beta
+
+    DEFAULT_EXTRA_ALIGN = :left
+    EXTRA_ALIGN_OPTIONS = [DEFAULT_EXTRA_ALIGN, :right].freeze
+
     # Tabs to be rendered. For more information, refer to <%= link_to_component(Primer::Navigation::TabComponent) %>.
     #
     # @param selected [Boolean] Whether the tab is selected.
@@ -22,6 +27,15 @@ module Primer
       )
     }
 
+    # Renders extra content to the `TabNav`. This will be rendered after the tabs.
+    #
+    # @param align [Symbol] <%= one_of(Primer::TabNavComponent::EXTRA_ALIGN_OPTIONS) %>
+    renders_one :extra, lambda { |align: DEFAULT_EXTRA_ALIGN, &block|
+      @align = fetch_or_fallback(EXTRA_ALIGN_OPTIONS, align, DEFAULT_EXTRA_ALIGN)
+
+      view_context.capture { block&.call }
+    }
+
     # @example Default
     #   <%= render(Primer::TabNavComponent.new(label: "Default")) do |c| %>
     #     <% c.tab(selected: true, href: "#") { "Tab 1" }%>
@@ -68,12 +82,53 @@ module Primer
     #     <% end %>
     #   <% end %>
     #
+    # @example With extra content
+    #   <%= render(Primer::TabNavComponent.new(label: "With extra content")) 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 %>
+    #
+    # @example Adding extra content after the tabs
+    #   <%= render(Primer::TabNavComponent.new(label: "Adding extra content after the tabs", display: :flex, body_arguments: { flex: 1 })) do |c| %>
+    #     <% c.tab(selected: true, href: "#") { "Tab 1" }%>
+    #     <% c.tab(href: "#") { "Tab 2" } %>
+    #     <% c.tab(href: "#") { "Tab 3" } %>
+    #     <% c.extra(align: :right) do %>
+    #       <div>
+    #         <%= render(Primer::ButtonComponent.new) { "Button" } %>
+    #       </div>
+    #     <% end %>
+    #   <% end %>
+    #
+    # @example Customizing the body
+    #   <%= render(Primer::TabNavComponent.new(label: "Default", body_arguments: { classes: "custom-class", border: true, border_color: :info })) do |c| %>
+    #     <% c.tab(selected: true, href: "#") { "Tab 1" }%>
+    #     <% c.tab(href: "#") { "Tab 2" } %>
+    #     <% c.tab(href: "#") { "Tab 3" } %>
+    #   <% end %>
+    #
+    # @example Customizing the wrapper
+    #   <%= render(Primer::TabNavComponent.new(label: "Default", wrapper_arguments: { classes: "custom-class", border: true, border_color: :info })) do |c| %>
+    #     <% c.tab(selected: true, href: "#") { "Tab 1" }%>
+    #     <% c.tab(href: "#") { "Tab 2" } %>
+    #     <% c.tab(href: "#") { "Tab 3" } %>
+    #   <% 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 wrapper_arguments [Hash] <%= link_to_system_arguments_docs %> for the `TabContainer` wrapper. Only applies if `with_panel` is `true`.
     # @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: {}, wrapper_arguments: {}, **system_arguments)
+      @align = DEFAULT_EXTRA_ALIGN
       @with_panel = with_panel
       @system_arguments = system_arguments
+      @body_arguments = body_arguments
+      @wrapper_arguments = wrapper_arguments
 
       @system_arguments[:tag] ||= :div
       @system_arguments[:classes] = class_names(
@@ -81,15 +136,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/{tooltip_component.rb → tooltip.rb}

@@ -2,7 +2,9 @@
 
 module Primer
   # `Tooltip` is a wrapper component that will apply a tooltip to the provided content.
-  class TooltipComponent < Primer::Component
+  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

@@ -5,6 +5,9 @@ module Primer
   class Truncate < Primer::Component
     status :beta
 
+    DEFAULT_TAG = :div
+    TAG_OPTIONS = [DEFAULT_TAG, :span, :p].freeze
+
     # @example Default
     #   <div class="col-2">
     #     <%= render(Primer::Truncate.new(tag: :p)) { "branch-name-that-is-really-long" } %>
@@ -19,13 +22,14 @@ module Primer
     # @example Custom size
     #   <%= render(Primer::Truncate.new(tag: :span, inline: true, expandable: true, max_width: 100)) { "branch-name-that-is-really-long" } %>
     #
+    # @param tag [Symbol] <%= one_of(Primer::Truncate::TAG_OPTIONS) %>
     # @param inline [Boolean] Whether the element is inline (or inline-block).
     # @param expandable [Boolean] Whether the entire string should be revealed on hover. Can only be used in conjunction with `inline`.
     # @param max_width [Integer] Sets the max-width of the text.
     # @param system_arguments [Hash] <%= link_to_system_arguments_docs %>
-    def initialize(inline: false, expandable: false, max_width: nil, **system_arguments)
+    def initialize(tag: DEFAULT_TAG, inline: false, expandable: false, max_width: nil, **system_arguments)
       @system_arguments = system_arguments
-      @system_arguments[:tag] ||= :div
+      @system_arguments[:tag] = fetch_or_fallback(TAG_OPTIONS, tag, DEFAULT_TAG)
       @system_arguments[:classes] = class_names(
         @system_arguments[:classes],
         "css-truncate",

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

@@ -1,4 +1,4 @@
-<%= wrapper do %>
+<%= wrapper(**@wrapper_arguments) do %>
   <%= render Primer::BaseComponent.new(**@system_arguments) do %>
     <% if @align == :right %>
       <%= actions %>

data/app/components/primer/underline_nav_component.rb

@@ -116,14 +116,30 @@ module Primer
     #     <% end %>
     #   <% end %>
     #
+    # @example Customizing the body
+    #   <%= render(Primer::UnderlineNavComponent.new(label: "Default", body_arguments: { tag: :ul, classes: "custom-class", border: true, border_color: :info })) do |c| %>
+    #     <% c.tab(selected: true, href: "#") { "Tab 1" }%>
+    #     <% c.tab(href: "#") { "Tab 2" } %>
+    #     <% c.tab(href: "#") { "Tab 3" } %>
+    #   <% end %>
+    #
+    # @example Customizing the wrapper
+    #   <%= render(Primer::UnderlineNavComponent.new(label: "Default", wrapper_arguments: { classes: "custom-class", border: true, border_color: :info })) do |c| %>
+    #     <% c.tab(selected: true, href: "#") { "Tab 1" }%>
+    #     <% c.tab(href: "#") { "Tab 2" } %>
+    #     <% c.tab(href: "#") { "Tab 3" } %>
+    #   <% end %>
+    #
     # @param label [String] The `aria-label` on top level `<nav>` element.
     # @param with_panel [Boolean] Whether the TabNav should navigate through pages or panels.
     # @param align [Symbol] <%= one_of(Primer::UnderlineNavComponent::ALIGN_OPTIONS) %> - Defaults to <%= Primer::UnderlineNavComponent::ALIGN_DEFAULT %>
     # @param body_arguments [Hash] <%= link_to_system_arguments_docs %> for the body wrapper.
+    # @param wrapper_arguments [Hash] <%= link_to_system_arguments_docs %> for the `TabContainer` wrapper. Only applies if `with_panel` is `true`.
     # @param system_arguments [Hash] <%= link_to_system_arguments_docs %>
-    def initialize(label:, with_panel: false, align: ALIGN_DEFAULT, body_arguments: { tag: BODY_TAG_DEFAULT }, **system_arguments)
+    def initialize(label:, with_panel: false, align: ALIGN_DEFAULT, body_arguments: { tag: BODY_TAG_DEFAULT }, wrapper_arguments: {}, **system_arguments)
       @with_panel = with_panel
       @align = fetch_or_fallback(ALIGN_OPTIONS, align, ALIGN_DEFAULT)
+      @wrapper_arguments = wrapper_arguments
 
       @system_arguments = system_arguments
       @system_arguments[:tag] = navigation_tag(with_panel)

data/app/lib/primer/classify.rb

@@ -7,7 +7,7 @@ module Primer
     SPACING_KEYS = Primer::Classify::Spacing::KEYS
 
     # 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
+    CONCAT_KEYS = SPACING_KEYS + %i[hide position v float text box_shadow].freeze
 
     INVALID_CLASS_NAME_PREFIXES =
       (["bg-", "color-", "text-", "d-", "v-align-", "wb-", "box-shadow-"] + CONCAT_KEYS.map { |k| "#{k}-" }).freeze
@@ -16,15 +16,16 @@ module Primer
     BG_KEY = :bg
     VERTICAL_ALIGN_KEY = :vertical_align
     WORD_BREAK_KEY = :word_break
-    TEXT_KEYS = %i[text_align font_weight].freeze
+    TEXT_KEYS = %i[font_family font_style font_weight text_align text_transform].freeze
     WIDTH_KEY = :width
     HEIGHT_KEY = :height
     BOX_SHADOW_KEY = :box_shadow
     VISIBILITY_KEY = :visibility
     ANIMATION_KEY = :animation
+    CONTAINER_KEY = :container
 
     BREAKPOINTS = ["", "-sm", "-md", "-lg", "-xl"].freeze
-    RESPONSIVE_KEYS = ([DISPLAY_KEY, :col, :float] + SPACING_KEYS + Primer::Classify::Flex::RESPONSIVE_KEYS).freeze
+    RESPONSIVE_KEYS = ([DISPLAY_KEY, :float, Primer::Classify::Grid::COL_KEY] + SPACING_KEYS + Primer::Classify::Flex::RESPONSIVE_KEYS).freeze
 
     BOOLEAN_MAPPINGS = {
       underline: {
@@ -84,6 +85,7 @@ module Primer
       TYPOGRAPHY_KEYS +
       TEXT_KEYS +
       Primer::Classify::Flex::KEYS +
+      Primer::Classify::Grid::KEYS +
       [
         BORDER_KEY,
         BORDER_COLOR_KEY,
@@ -97,7 +99,8 @@ module Primer
         HEIGHT_KEY,
         BOX_SHADOW_KEY,
         VISIBILITY_KEY,
-        ANIMATION_KEY
+        ANIMATION_KEY,
+        CONTAINER_KEY
       ]
     ).freeze
 
@@ -123,13 +126,13 @@ module Primer
       def validated_class_names(classes)
         return if classes.blank?
 
-        if ENV["RAILS_ENV"] == "development"
+        if force_system_arguments? && !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
@@ -206,8 +209,10 @@ module Primer
           memo[:classes] << "rounded-#{val}"
         elsif Primer::Classify::Flex::KEYS.include?(key)
           memo[:classes] << Primer::Classify::Flex.classes(key, val, breakpoint)
+        elsif Primer::Classify::Grid::KEYS.include?(key)
+          memo[:classes] << Primer::Classify::Grid.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
@@ -215,7 +220,11 @@ module Primer
         elsif TEXT_KEYS.include?(key)
           memo[:classes] << "text-#{val.to_s.dasherize}"
         elsif TYPOGRAPHY_KEYS.include?(key)
-          memo[:classes] << "f#{val.to_s.dasherize}"
+          memo[:classes] << if val == :small || val == :normal
+                              "text-#{val.to_s.dasherize}"
+                            else
+                              "f#{val.to_s.dasherize}"
+                            end
         elsif key == BOX_SHADOW_KEY
           memo[:classes] << if val == true
                               "color-shadow-small"
@@ -236,6 +245,10 @@ module Primer
           memo[:classes] << "#{key.to_s.dasherize}#{breakpoint}-#{val.to_s.dasherize}"
         end
       end
+
+      def force_system_arguments?
+        Rails.application.config.primer_view_components.force_system_arguments
+      end
     end
 
     Cache.preload!

data/app/lib/primer/classify/cache.rb

@@ -54,6 +54,21 @@ module Primer
             values: Primer::Classify::Flex::ALIGN_ITEMS_VALUES
           )
 
+          preload(
+            keys: Primer::Classify::Grid::CONTAINER_KEY,
+            values: Primer::Classify::Grid::CONTAINER_VALUES
+          )
+
+          preload(
+            keys: Primer::Classify::Grid::CLEARFIX_KEY,
+            values: [true]
+          )
+
+          preload(
+            keys: Primer::Classify::Grid::COL_KEY,
+            values: Primer::Classify::Grid::COL_VALUES
+          )
+
           preload(
             keys: Primer::Classify::DISPLAY_KEY,
             values: [:flex, :block, :inline_block, :inline_flex, :none, :table, :table_cell]
@@ -111,7 +126,7 @@ module Primer
 
           preload(
             keys: [Primer::Classify::WIDTH_KEY, Primer::Classify::HEIGHT_KEY],
-            values: [:fit, :fill]
+            values: [:fit]
           )
 
           preload(