Add tooltip to navList if the text is truncated

.changeset/lucky-phones-burn.md

@@ -0,0 +1,5 @@
+---
+"@primer/view-components": minor
+---
+
+Add the ability to show a tooltip for navlists on text truncation

app/components/primer/alpha/action_list.html.erb

@@ -1,20 +1,22 @@
-<%= render(Primer::BaseComponent.new(tag: :div)) do %>
-  <% if acts_as_form_input? %>
-    <span data-list-inputs="true">
-      <%= @form_builder.hidden_field(@input_name, multiple: multi_select?, skip_default_ids: true) %>
-    </span>
-  <% end %>
-  <% if heading %>
-    <%= heading %>
-  <% end %>
-  <%= render(Primer::BaseComponent.new(tag: :ul, **@system_arguments)) do %>
-    <% items.each_with_index do |item, index| %>
-      <%# the conditions here make sure two dividers are never rendered one after the other %>
-      <% if index > 0 && @show_dividers && !item.is_a?(Divider) && !items[index - 1].is_a?(Divider) %>
-        <%= render(Primer::Alpha::ActionList::Divider.new) %>
+<action-list>
+  <%= render(Primer::BaseComponent.new(tag: :div)) do %>
+    <% if acts_as_form_input? %>
+      <span data-list-inputs="true">
+        <%= @form_builder.hidden_field(@input_name, multiple: multi_select?, skip_default_ids: true) %>
+      </span>
+    <% end %>
+    <% if heading %>
+      <%= heading %>
+    <% end %>
+    <%= render(Primer::BaseComponent.new(tag: :ul, **@system_arguments)) do %>
+      <% items.each_with_index do |item, index| %>
+        <%# the conditions here make sure two dividers are never rendered one after the other %>
+        <% if index > 0 && @show_dividers && !item.is_a?(Divider) && !items[index - 1].is_a?(Divider) %>
+          <%= render(Primer::Alpha::ActionList::Divider.new) %>
+        <% end %>
+        <%= item %>
       <% end %>
-      <%= item %>
     <% end %>
+    <%= capture(&post_list_content_block) if post_list_content_block %>
   <% end %>
-  <%= capture(&post_list_content_block) if post_list_content_block %>
-<% end %>
+</action-list>

app/components/primer/alpha/action_list.pcss

@@ -4,6 +4,14 @@
 
 /* ActionList */
 
+action-list {
+  display: block;
+}
+
+nav-list {
+  display: block;
+}
+
 .ActionListHeader {
   margin-left: var(--base-size-8);
   margin-bottom: var(--base-size-16);

app/components/primer/alpha/action_list.ts

@@ -0,0 +1,58 @@
+import {controller} from '@github/catalyst'
+
+// eslint-disable-next-line custom-elements/no-exports-with-element
+export class ActionListTruncationObserver {
+  resizeObserver = new ResizeObserver(entries => {
+    for (const entry of entries) {
+      const action = entry.target
+
+      if (action instanceof HTMLElement) {
+        this.update(action)
+      }
+    }
+  })
+
+  constructor(el: HTMLElement) {
+    this.resizeObserver.observe(el)
+  }
+
+  unobserve(el: HTMLElement) {
+    this.resizeObserver.unobserve(el)
+  }
+
+  update(el: HTMLElement) {
+    const label = el.querySelector('.ActionListItem-label')
+    if (!label) return
+
+    const tooltip = el.querySelector('.ActionListItem-truncationTooltip') as HTMLElement | null
+    if (!tooltip) return
+
+    const isTruncated = label.scrollWidth > label.clientWidth
+
+    if (isTruncated) {
+      tooltip.style.display = ''
+    } else {
+      tooltip.style.display = 'none'
+    }
+  }
+}
+
+@controller
+// eslint-disable-next-line custom-elements/expose-class-on-global
+export class ActionListElement extends HTMLElement {
+  #truncationObserver: ActionListTruncationObserver
+
+  connectedCallback() {
+    this.#truncationObserver = new ActionListTruncationObserver(this)
+  }
+
+  disconnectedCallback() {
+    this.#truncationObserver.unobserve(this)
+  }
+}
+
+declare global {
+  interface Window {
+    ActionListElement: typeof ActionListElement
+  }
+}

app/components/primer/alpha/action_list/item.rb

@@ -28,6 +28,16 @@ class Item < Primer::Component
         }.freeze
         SCHEME_OPTIONS = SCHEME_MAPPINGS.keys.freeze
 
+        DEFAULT_TRUNCATION_BEHAVIOR = :none
+        TRUNCATION_BEHAVIOR_MAPPINGS = {
+          DEFAULT_TRUNCATION_BEHAVIOR => nil,
+          false => nil,
+          :show_tooltip => "ActionListItem-label--truncate",
+          :truncate => "ActionListItem-label--truncate",
+          true => "ActionListItem-label--truncate"
+        }
+        TRUNCATION_BEHAVIOR_OPTIONS = TRUNCATION_BEHAVIOR_MAPPINGS.keys.freeze
+
         # Description content that complements the item's label. See `ActionList`'s `description_scheme` argument
         # for layout options.
         renders_one :description
@@ -120,6 +130,8 @@ class Item < Primer::Component
           system_arguments[:for_id] = @id
           system_arguments[:type] ||= :description
 
+          system_arguments[:classes] = class_names(system_arguments[:classes], "ActionListItem-truncationTooltip") if @truncate_label == :show_tooltip
+
           Primer::Alpha::Tooltip.new(**system_arguments)
         }
 
@@ -148,7 +160,7 @@ class Item < Primer::Component
         # @param label_arguments [Hash] <%= link_to_system_arguments_docs %> used to construct the label.
         # @param content_arguments [Hash] <%= link_to_system_arguments_docs %> used to construct the item's anchor or button tag.
         # @param form_arguments [Hash] Allows the item to submit a form on click. The URL passed in the `href:` option will be used as the form action. Pass the `method:` option to this hash to control what kind of request is made, <%= one_of(Primer::Alpha::ActionList::FormWrapper::HTTP_METHOD_OPTIONS) %> The `name:` option is required and specifies the desired name of the field that will be included in the params sent to the server on form submission. Specify the `value:` option to send a custom value to the server; otherwise the value of `name:` is sent.
-        # @param truncate_label [Boolean] Truncate label with ellipsis.
+        # @param truncate_label [Boolean | Symbol] How the label should be truncated when the text does not fit inside the bounds of the list item. <%= one_of(Primer::Alpha::ActionList::Item::TRUNCATION_BEHAVIOR_OPTIONS) %> Pass `false` or `:none` to wrap label text. Pass `true` or `:truncate` to truncate labels with ellipses. Pass `:show_tooltip` to show the entire label contents in a tooltip when the item is hovered.
         # @param href [String] Link URL.
         # @param role [String] ARIA role describing the function of the item.
         # @param size [Symbol] Controls block sizing of the item.
@@ -168,7 +180,7 @@ def initialize(
           content_arguments: {},
           form_arguments: {},
           parent: nil,
-          truncate_label: false,
+          truncate_label: :none,
           href: nil,
           role: nil,
           size: DEFAULT_SIZE,
@@ -206,9 +218,6 @@ def initialize(
             "ActionListItem--disabled" => @disabled
           )
 
-          @system_arguments[:data] ||= {}
-          @system_arguments[:data][:targets] = "#{list_class.custom_element_name}.items"
-
           @system_arguments[:data] = merge_data(
             @system_arguments, {
               data: {
@@ -224,7 +233,7 @@ def initialize(
               label_classes,
               label_arguments[:classes],
               "ActionListItem-label",
-              "ActionListItem-label--truncate" => @truncate_label
+              TRUNCATION_BEHAVIOR_MAPPINGS[@truncate_label],
             )
           }
 
@@ -293,6 +302,10 @@ def before_render
             "ActionListItem--withActions" => trailing_action.present?
           )
 
+          if @truncate_label == :show_tooltip && !tooltip?
+            with_tooltip(text: @label)
+          end
+
           return unless leading_visual
 
           @content_arguments[:classes] = class_names(

app/components/primer/beta/nav_list.html.erb

@@ -1,7 +1,7 @@
 <%= render(Primer::BaseComponent.new(tag: :nav, **@system_arguments)) do %>
   <%= heading %>
   <nav-list>
-    <%= render(Primer::ConditionalWrapper.new(condition: render_outer_list?, tag: :ul, classes: "ActionListWrap")) do %>
+    <%= render(Primer::ConditionalWrapper.new(condition: render_outer_list?, tag: :ul, classes: "ActionListWrap", data: { target: "nav-list.topLevelList" })) do %>
       <% items.each_with_index do |item, index| %>
         <% if index > 0 && render_divider_between?(item, items[index - 1]) %>
           <%= render(Primer::Alpha::ActionList::Divider.new) %>

app/components/primer/beta/nav_list.ts

@@ -1,9 +1,26 @@
 /* eslint-disable custom-elements/expose-class-on-global */
-import {controller, targets} from '@github/catalyst'
+import {controller, target, targets} from '@github/catalyst'
+import {ActionListTruncationObserver} from '../alpha/action_list'
 
 @controller
 export class NavListElement extends HTMLElement {
   @targets items: HTMLElement[]
+  @target topLevelList: HTMLElement
+
+  #truncationObserver: ActionListTruncationObserver
+
+  connectedCallback() {
+    // groups are wrapped in <action-list>, which handles resizing on its own
+    if (this.topLevelList) {
+      this.#truncationObserver = new ActionListTruncationObserver(this.topLevelList)
+    }
+  }
+
+  disconnectedCallback() {
+    if (this.topLevelList) {
+      this.#truncationObserver.unobserve(this.topLevelList)
+    }
+  }
 
   selectItemById(itemId: string | null): boolean {
     if (!itemId) return false

app/components/primer/beta/nav_list_group_element.ts

@@ -1,4 +1,5 @@
 import {controller, target, targets} from '@github/catalyst'
+import {ActionListTruncationObserver} from '../alpha/action_list'
 
 @controller
 export class NavListGroupElement extends HTMLElement {
@@ -86,6 +87,8 @@ export class NavListGroupElement extends HTMLElement {
     template.innerHTML = html
     return document.importNode(template.content, true)
   }
+
+  #truncateObserver = new ActionListTruncationObserver(this)
 }
 
 declare global {

app/components/primer/primer.ts

@@ -1,4 +1,5 @@
 import '@github/include-fragment-element'
+import './alpha/action_list'
 import './alpha/action_bar_element'
 import './alpha/dropdown'
 import './anchored_position'

previews/primer/alpha/action_list_preview.rb

@@ -459,6 +459,48 @@ def item_active
           component.with_item(label: "Active item", href: "/", active: true)
         end
       end
+
+      # @label Long label
+      #
+      # @param truncate_label [Symbol] select [none, truncate, show_tooltip]
+      # @snapshot
+      def long_label_with_tooltip(truncate_label: :show_tooltip)
+        render(Primer::Alpha::ActionList.new(aria: { label: "List heading" })) do |component|
+          component.with_item(
+            label: "Really really long label that may wrap, truncate, or appear as a tooltip",
+            truncate_label: truncate_label
+          )
+        end
+      end
+
+      def long_label_wrap(truncate_label: :none)
+        render(Primer::Alpha::ActionList.new(aria: { label: "List heading" })) do |component|
+          component.with_item(
+            label: "Really really long label that may wrap, truncate, or appear as a tooltip",
+            truncate_label: truncate_label
+          )
+        end
+      end
+
+      def long_label_truncate_no_tooltip(truncate_label: :truncate)
+        render(Primer::Alpha::ActionList.new(aria: { label: "List heading" })) do |component|
+          component.with_item(
+            label: "Really really long label that may wrap, truncate, or appear as a tooltip",
+            truncate_label: truncate_label
+          )
+        end
+      end
+
+      def long_label_show_tooltip_with_truncate_label(truncate_label: :none)
+        render(Primer::Alpha::ActionList.new(aria: { label: "List heading" })) do |component|
+          component.with_item(
+            label: "Really really long label that may wrap, truncate, or appear as a tooltip",
+            truncate_label: truncate_label
+          ) do |item|
+            item.with_tooltip(text: "this is a tooltip")
+          end
+        end
+      end
     end
   end
 end

previews/primer/beta/nav_list_preview.rb

@@ -129,6 +129,49 @@ def show_more_item
       # @label Trailing action
       # @snapshot
       def trailing_action; end
+
+      # @label Long label truncate overflow
+      #
+      # @param truncate_label [Symbol] select [none, truncate, show_tooltip]
+      # @snapshot
+      def long_label_with_tooltip(truncate_label: :show_tooltip)
+        render(Primer::Beta::NavList.new(aria: { label: "List heading" })) do |component|
+          component.with_item(
+            label: "Really really long label that may wrap, truncate, or appear as a tooltip",
+            truncate_label: truncate_label
+          ) do |item|
+            item.with_trailing_visual_icon(icon: :plus)
+          end
+        end
+      end
+
+      def long_label_wrap(truncate_label: :none)
+        render(Primer::Beta::NavList.new(aria: { label: "List heading" })) do |component|
+          component.with_item(
+            label: "Really really long label that may wrap, truncate, or appear as a tooltip",
+            truncate_label: truncate_label
+          )
+        end
+      end
+
+      def long_label_truncate_no_tooltip(truncate_label: :truncate)
+        render(Primer::Beta::NavList.new(aria: { label: "List heading" })) do |component|
+          component.with_item(
+            label: "Really really long label that may wrap, truncate, or appear as a tooltip",
+            truncate_label: truncate_label
+          )
+        end
+      end
+
+      def long_label_show_tooltip_no_truncate_label
+        render(Primer::Beta::NavList.new(aria: { label: "List heading" })) do |component|
+          component.with_item(
+            label: "Really really long label that may wrap, truncate, or appear as a tooltip",
+          ) do |item|
+            item.with_tooltip(text: "this is a tooltip")
+          end
+        end
+      end
     end
   end
 end

test/components/alpha/action_list_test.rb

@@ -41,6 +41,24 @@ def test_item_with_leading_icon
         assert_selector(".octicon-arrow-down")
       end
 
+      def test_item_text_truncates_with_tooltip
+        render_inline(Primer::Alpha::ActionList.new(aria: { label: "List" })) do |component|
+          component.with_item(label: "Item 1", href: "/item1", truncate_label: :show_tooltip)
+        end
+
+        assert_selector "li.ActionListItem", text: "Item 1"
+        assert_selector "li.ActionListItem span.ActionListItem-label--truncate"
+      end
+
+      def test_item_text_wraps
+        render_inline(Primer::Alpha::ActionList.new(aria: { label: "List" })) do |component|
+          component.with_item(label: "Item 1", href: "/item1", truncate_label: :none)
+        end
+
+        assert_selector "li.ActionListItem", text: "Item 1"
+        assert_selector "li.ActionListItem span.ActionListItem-label"
+      end
+
       def test_list_labelled_by_heading
         render_preview(:default)
 

test/css/component_specific_selectors_test.rb

@@ -28,7 +28,8 @@ class ComponentSpecificSelectorsTest < Minitest::Test
       ".ActionListItem.ActionListItem--hasSubItem>.ActionListContent",
       ".ActionListItem--subItem>.ActionListContent>.ActionListItem-label",
       ".ActionListHeader", # used exclusively by NavList
-      ".ActionListItem.ActionListItem--navActive" # used exclusively by NavList
+      ".ActionListItem.ActionListItem--navActive", # used exclusively by NavList
+      "nav-list" # used exclusively by NavList
     ],
     Primer::Alpha::AutoComplete => [
       ".autocomplete-item"