[parked] perf(UnderlineNav): replace JS DOM measurement with CSS overflow + IntersectionObserver

.changeset/underlinenav-intersection-observer-overflow.md

@@ -0,0 +1,5 @@
+---
+'@primer/react': patch
+---
+
+Improve UnderlineNav overflow performance by replacing synchronous DOM measurements with CSS `overflow: hidden` + `IntersectionObserver`

packages/react/src/UnderlineNav/UnderlineNav.module.css

@@ -1,20 +1,102 @@
+/* Fixed height on the wrapper prevents vertical CLS on first paint.
+   Horizontal clipping is handled by overflow: hidden on the <ul>.
+   The More button is always rendered (visibility: hidden when no overflow)
+   to prevent horizontal CLS. We intentionally omit overflow: hidden here
+   so the underline ::after pseudo-element (which extends ~1px below) is not clipped. */
+.NavWrapper {
+  height: var(--control-xlarge-size, 48px);
+  position: relative;
+}
+
 .MenuItemContent {
   display: flex;
   align-items: center;
   justify-content: space-between;
 }
 
+/* Container for the "More" button and overflow menu.
+   Uses CSS anchor positioning to align with the anchor marker at overflowStartIndex.
+   Falls back to static position (end of flex row) in browsers without support. */
+.MoreMenuContainer {
+  position: absolute;
+  /* stylelint-disable-next-line declaration-property-value-no-unknown, primer/spacing */
+  left: anchor(left);
+  align-self: center;
+  display: flex;
+  align-items: center;
+}
+
+/* Zero-size anchor markers placed after each nav item in the list.
+   They provide anchor points for CSS anchor positioning of the More button. */
+.AnchorMarker {
+  width: 0;
+  padding: 0;
+  margin: 0;
+  overflow: hidden;
+  flex: 0 0 0px;
+}
+
+/* Before IO has fired, the More button is hidden to prevent flash.
+   Since .MoreMenuContainer is position: absolute, this only hides visually. */
+.MoreMenuHidden {
+  visibility: hidden;
+}
+
+/* Overflow list: clips items that don't fit; IO detects which are clipped.
+   Padding-bottom/margin-bottom accommodate the underline ::after pseudo-element. */
+.OverflowList {
+  overflow: hidden;
+  flex: 1;
+  min-width: 0;
+  padding-bottom: var(--base-size-12);
+  margin-bottom: calc(var(--base-size-12) * -1);
+}
+
+/* Divider line before the More button */
+.Divider {
+  display: inline-block;
+  border-left: var(--borderWidth-thin) solid var(--borderColor-muted);
+  width: 1px;
+  margin-right: var(--base-size-4);
+  height: var(--base-size-24);
+}
+
+/* Dropdown overlay for the overflow menu */
+.OverflowMenu {
+  position: absolute;
+  z-index: 1;
+  top: 90%;
+  box-shadow: var(--shadow-resting-medium);
+  border-radius: var(--borderRadius-medium);
+  background: var(--overlay-bgColor);
+  list-style: none;
+  min-width: 192px;
+  max-width: 640px;
+  right: 0;
+  display: none;
+}
+
+.OverflowMenuOpen {
+  display: block;
+}
+
+/* Hide the selected check icon on menu items and reset link decoration */
+.MenuItem {
+  text-decoration: none;
+
+  & > span {
+    display: none;
+  }
+}
+
 /* More button styles migrated from styles.ts (was moreBtnStyles) */
 .MoreButton {
   margin: 0; /* reset Safari extra margin */
   border: 0;
   background: transparent;
   font-weight: var(--base-text-weight-normal);
   box-shadow: none;
-  padding-top: var(--base-size-4);
-  padding-bottom: var(--base-size-4);
-  padding-left: var(--base-size-8);
-  padding-right: var(--base-size-8);
+  padding: var(--base-size-4) var(--base-size-8);
 
   & > [data-component='trailingVisual'] {
     margin-left: 0;

packages/react/src/UnderlineNav/UnderlineNav.test.tsx

@@ -1,6 +1,6 @@
-import {describe, expect, it, vi} from 'vitest'
+import {describe, expect, it, vi, beforeEach, afterEach} from 'vitest'
 import type React from 'react'
-import {render, screen} from '@testing-library/react'
+import {render, screen, act} from '@testing-library/react'
 import userEvent from '@testing-library/user-event'
 import {
   CodeIcon,
@@ -78,7 +78,8 @@ describe('UnderlineNav', () => {
   it('renders icons correctly', () => {
     const {getByRole} = render(<ResponsiveUnderlineNav />)
     const nav = getByRole('navigation')
-    expect(nav.getElementsByTagName('svg').length).toEqual(7)
+    const list = nav.querySelector('[role="list"], ul, ol')!
+    expect(list.getElementsByTagName('svg').length).toEqual(7)
   })
 
   it('fires onSelect on click', async () => {
@@ -253,3 +254,164 @@ describe('Keyboard Navigation', () => {
     expect(nextItem).toHaveFocus()
   })
 })
+
+describe('Overflow detection (IntersectionObserver + ResizeObserver)', () => {
+  const originalIO = window.IntersectionObserver
+  const originalRO = window.ResizeObserver
+
+  let ioCallback: IntersectionObserverCallback
+  let ioInstance: IntersectionObserver
+  let roCallback: ResizeObserverCallback
+  let roInstance: ResizeObserver
+  let observedElements: Element[]
+
+  beforeEach(() => {
+    observedElements = []
+
+    window.IntersectionObserver = vi.fn(function (callback: IntersectionObserverCallback) {
+      ioCallback = callback
+      ioInstance = {
+        observe: vi.fn((el: Element) => observedElements.push(el)),
+        unobserve: vi.fn(),
+        disconnect: vi.fn(),
+        takeRecords: vi.fn().mockReturnValue([]),
+        root: null,
+        rootMargin: '',
+        thresholds: [],
+      }
+      return ioInstance
+    }) as unknown as typeof IntersectionObserver
+
+    window.ResizeObserver = vi.fn(function (callback: ResizeObserverCallback) {
+      roCallback = callback
+      roInstance = {
+        observe: vi.fn(),
+        disconnect: vi.fn(),
+        unobserve: vi.fn(),
+      }
+      return roInstance
+    }) as unknown as typeof ResizeObserver
+  })
+
+  afterEach(() => {
+    window.IntersectionObserver = originalIO
+    window.ResizeObserver = originalRO
+  })
+
+  // Suppress unused variable warnings for roCallback/roInstance
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  const _getRoRefs = () => ({roCallback, roInstance})
+
+  function fireIntersection(entries: Array<{target: Element; intersectionRatio: number}>) {
+    act(() => {
+      ioCallback(
+        entries.map(e => ({...e, isIntersecting: e.intersectionRatio > 0}) as unknown as IntersectionObserverEntry),
+        ioInstance,
+      )
+    })
+  }
+
+  /** Fire IO twice to complete the icon-toggle cycle:
+   *  1st call: icons visible + overflow => hides icons (early return)
+   *  2nd call: icons hidden + still overflow => sets overflowStartIndex */
+  function fireOverflow(visibleCount: number) {
+    const makeEntries = () =>
+      observedElements.map((el, i) => ({
+        target: el,
+        intersectionRatio: i < visibleCount ? 1 : 0,
+      }))
+    // Phase 1: triggers icon hiding
+    fireIntersection(makeEntries())
+    // Phase 2: with icons hidden, sets overflow
+    fireIntersection(makeEntries())
+  }
+
+  it('observes all list items', () => {
+    render(<ResponsiveUnderlineNav />)
+    // 9 nav items in the fixture
+    expect(observedElements).toHaveLength(9)
+  })
+
+  it('shows the "More" button when items overflow', () => {
+    render(<ResponsiveUnderlineNav />)
+    fireOverflow(5)
+    expect(screen.getByRole('button', {name: /More/})).toBeVisible()
+  })
+
+  it('marks overflowing items as aria-hidden', () => {
+    render(<ResponsiveUnderlineNav />)
+    fireOverflow(5)
+
+    const list = screen.getByRole('list')
+    const listItems = Array.from(list.querySelectorAll(':scope > li:not([data-anchor-marker])'))
+
+    // Items at indices 5-8 should be aria-hidden
+    for (let i = 5; i < listItems.length; i++) {
+      expect(listItems[i]).toHaveAttribute('aria-hidden', 'true')
+    }
+
+    // Items at indices 0-4 should not be aria-hidden
+    for (let i = 0; i < 5; i++) {
+      expect(listItems[i]).not.toHaveAttribute('aria-hidden')
+    }
+  })
+
+  it('removes the "More" button when all items become visible', () => {
+    render(<ResponsiveUnderlineNav />)
+    fireOverflow(5)
+    expect(screen.getByRole('button', {name: /More/})).toBeVisible()
+
+    // All items visible again
+    fireIntersection(
+      observedElements.map(el => ({
+        target: el,
+        intersectionRatio: 1,
+      })),
+    )
+
+    // "More" button should no longer be in the document
+    expect(screen.queryByRole('button', {name: /More/})).toBeNull()
+  })
+
+  it('swaps aria-current item from overflow into visible range', () => {
+    // "Settings" is at index 7, which will be in the overflow range
+    render(<ResponsiveUnderlineNav selectedItemText="Settings" />)
+    fireOverflow(5)
+
+    // The aria-current item should be visible (swapped into the last visible position)
+    const currentLink = screen.getByRole('link', {name: /Settings/})
+    expect(currentLink.closest('[aria-hidden]')).toBeNull()
+    expect(currentLink.getAttribute('aria-current')).toBe('page')
+  })
+
+  it('sets data-icons-visible to false when overflow occurs', () => {
+    const {container} = render(<ResponsiveUnderlineNav />)
+    const nav = container.querySelector('nav')!
+
+    // Initially icons are visible
+    expect(nav.getAttribute('data-icons-visible')).toBe('true')
+
+    // Single IO fire with overflow triggers icon hiding
+    fireIntersection(
+      observedElements.map((el, i) => ({
+        target: el,
+        intersectionRatio: i < 5 ? 1 : 0,
+      })),
+    )
+
+    // Icons should be hidden as first attempt to reduce overflow
+    expect(nav.getAttribute('data-icons-visible')).toBe('false')
+  })
+
+  it('ensures overflow menu has at least 2 items (never just 1)', () => {
+    render(<ResponsiveUnderlineNav />)
+
+    // Only 1 item would overflow (last item), but the rule says minimum 2
+    fireOverflow(8)
+
+    const list = screen.getByRole('list')
+    const hiddenItems = Array.from(list.querySelectorAll(':scope > li:not([data-anchor-marker])[aria-hidden="true"]'))
+    // Should have 2 hidden items (pulled one more into overflow to avoid single-item menu)
+    expect(hiddenItems.length).toBeGreaterThanOrEqual(2)
+  })
+})