Fix and refactor UnderlineNav to resolve CLS issues and improve performance/code quality

[Copilot]

UnderlineNav caused CLS by measuring item widths in JS after hydration to determine overflow. This replaces that approach with CSS-based overflow detection, eliminating layout shift and removing substantial complexity.

How overflow works now:

• Items wrap onto subsequent lines clipped by overflow: hidden — visually disappear without JS
• Overflow menu button visibility controlled by scroll-state container queries (pure CSS)
• Each item registers an IntersectionObserver via context to self-report when overflowed; parent renders those items in the overflow menu
• If any item ever overflowed, all tab icons are suppressed for the component lifetime (prevents icon-size-induced flickering)

What changed:

• Overflow detection: JS width measurement → CSS wrapping + scroll-state container queries
• Overflow menu: custom implementation → ActionMenu (fixes positioning, removes ~100 LOC)
• Item tracking: React.Children API → descendant registry via context
• Icon visibility: JS-controlled props → pure CSS
• Overflow button is now right-aligned (always at the trailing edge, not next to the last visible item)
• Current item styled distinctively when it appears in the overflow menu:
• If the first item has an extremely long label and cannot fit at all, it truncates with ellipsis rather than being moved to the menu:

Breaking behavioral changes:

• The current item is no longer guaranteed to remain visible outside the overflow menu — impossible to guarantee with the CSS wrapping approach
• Items no longer need to be direct children; fragments and wrapper components are now supported

Changelog

New

• UnderlineNav items can now be wrapped in fragments or intermediate components (no longer requires direct children)

Changed

• UnderlineNav overflow detection is now CSS-based, eliminating CLS
• Overflow menu uses ActionMenu; button is right-aligned
• Current item may appear in the overflow menu when space is constrained (styled with a leading indicator)
• Tab icons are suppressed for the component lifetime once any overflow has occurred

Removed

• JS width-measurement logic for overflow calculation
• Custom overflow menu implementation

Rollout strategy

• Patch release
• Minor release
• Major release; if selected, include a written rollout or migration plan
• None; if selected, include a brief description as to why

Testing & Reviewing

Overflow behavior is best verified by resizing the browser window. The flex layout is easiest to inspect using Chrome DevTools' flex inspector — it clearly shows where wrapped items are hiding.

Merge checklist

• Added/updated tests
• Added/updated documentation
• Added/updated previews (Storybook)
• Changes are SSR compatible
• Tested in Chrome
• Tested in Firefox
• Tested in Safari
• Tested in Edge
• (GitHub staff only) Integration tests pass at github/github-ui (Learn more about how to run integration tests)

---

🔒 GitHub Advanced Security automatically protects Copilot coding agent pull requests. You can protect all pull requests by enabling Advanced Security for your repositories. Learn more about Advanced Security.

[changeset-bot]

🦋 Changeset detected

Latest commit: 984b15d

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
@primer/react	Minor

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR