primer_view_components 0.0.38 → 0.0.43

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

@@ -2,3 +2,5 @@ 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

@@ -2,3 +2,5 @@ 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

@@ -2,3 +2,5 @@ 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
 

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,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

@@ -1,10 +1,15 @@
 # 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
 
+    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/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,10 +1,13 @@
 # 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
 
+    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

@@ -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
@@ -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)