perf(UnderlinePanels): eliminate cascading renders on mount and resize

[mattcosta7]

Closes #

Summary

Removes the cascading-render anti-patterns from UnderlinePanels —
specifically the one mount-after-effect cycle (props mirrored into state via
useEffect), the extra commit from storing listWidth in state when nothing
in render reads it, and the tablist-wide reconciliation that happened every
time iconsVisible flipped because cloneElement baked the flag into every
Tab element.

Behavior is identical. The component now renders once on mount instead of
twice, never produces an empty-tablist frame, and resize-driven icon toggles
only update each Tab's context-consuming subtree instead of forcing the
whole tablist through reconciliation.

What was wrong

packages/react/src/experimental/UnderlinePanels/UnderlinePanels.tsx on main
had three independent sources of unnecessary renders:

1. Props mirrored in state via useEffect

const [tabs, setTabs] = useState<React.ReactNode[]>([])
const [tabPanels, setTabPanels] = useState<React.ReactNode[]>([])

useEffect(() => {
  // clone children → newTabs / newTabPanels
  setTabs(newTabs)
  setTabPanels(newTabPanels)
}, [children, parentId, loadingCounters, iconsVisible])

The React docs flag this exact pattern as an anti-pattern. Mount sequence:

• Render 1: tabs = [], tabPanels = [] → renders an empty tablist for one frame.
• Effect runs → two setStates (batched into one commit).
• Render 2: actual tabs appear.

Every prop change re-ran the effect → another setState → another commit.

2. listWidth stored in state but only read inside the resize callback

const [listWidth, setListWidth] = useState(0)
useIsomorphicLayoutEffect(() => {
  setListWidth(listRef.current?.getBoundingClientRect().width ?? 0)
}, [tabsHaveIcons])

useResizeObserver(([entry]) => {
  setIconsVisible(entry.contentRect.width > listWidth)
}, wrapperRef, [])

Render never reads listWidth. The state existed solely to be read inside
the resize-observer callback. Each write was a wasted commit.

3. iconsVisible and loadingCounters baked into every Tab via cloneElement

return cloneElement(child, {id: `${parentId}-tab-${tabIndex++}`, loadingCounters, iconsVisible})

Both flags were in the effect's deps array, so the moment iconsVisible
flipped (from the resize observer), the effect re-ran, every Tab element was
re-cloned with new props, and React reconciled fresh Tab elements across the
entire tablist. A consumer with 12 tabs would see all 12 Tab function bodies
re-execute on every resize that crossed the icon-fits threshold.

What this PR does

Four commits, each independently shippable and tests-green:

perf(UnderlinePanels): derive tabs and panels in render, not from state

Replaces the useState + useEffect pair with a single useMemo that walks
children, clones tabs/panels with their IDs, and returns the partitioned
arrays. The empty-tablist mount frame is gone; consumer rerenders no longer
do the two-commit dance.

perf(UnderlinePanels): keep list width in a ref, not state

listWidth moves from useState to useRef. The layout effect writes
ref.current; the resize-observer callback reads ref.current. The only
state setter left in the resize path is setIconsVisible, which only fires
when the decision actually flips.

perf(UnderlinePanels): pass iconsVisible / loadingCounters via context

Introduces a new internal UnderlinePanelsContext carrying iconsVisible
and loadingCounters. The cloneElement call now only assigns the
generated id, and the memo deps drop to [children, parentId]. Tabs read
the flags from context, so they still react to resize-driven toggles —
context propagation does the work, not element re-cloning.

React.memo(Tab) ties the bow: with referentially-stable Tab elements +
memo, an iconsVisible flip updates only each Tab's context-consuming
subtree, not the surrounding tablist.

test(UnderlinePanels): pin no-empty-frame, bounded mount renders, memo stability

Three new tests that pin every claim above:

1. renders tabs synchronously on mount (no empty-tablist frame) — runs
   render(...), queries [role="tab"] immediately, expects 3 tabs. If a
   future change reintroduces state-from-effect, the count is 0 on render
   return and this trips.
2. bounds parent renders on initial mount — wraps UnderlinePanels
   in a render-counted host and asserts the host renders ≤ 1 time on mount.
3. does not re-render tabs when an unrelated re-render of the parent occurs —
   renders a stable tree reference, triggers three unrelated parent
   re-renders via rerender(...), asserts the TabBody count inside Tabs
   stays at its mount-time value. Catches any future change that re-bakes
   iconsVisible / loadingCounters into Tab via cloneElement or drops the
   React.memo wrapper.

Plus a patch changeset.

Profiles

	Before	After
Mount renders of UnderlinePanels	2 (initial + effect-setState)	1
Empty-tablist frame on mount	yes (1 frame)	no
listWidth setState	per mount + per list-width change	gone
Tab re-renders on iconsVisible flip	every Tab, every flip	only context consumers; surrounding subtree untouched
Cascade through unrelated parent re-renders	yes (Tab elements re-cloned)	no (memo + context)

Changelog

New

• Internal UnderlinePanelsContext carrying iconsVisible and
  loadingCounters for the Tab component.

Changed

• UnderlinePanels derives tabs/panels in render (useMemo) instead of
  syncing props into state via useEffect.
• UnderlinePanels.Tab is wrapped in React.memo and reads
  iconsVisible / loadingCounters from context instead of via
  cloneElement-injected props.
• listWidth is kept in a ref instead of state.

Removed

• The mount-time empty-tablist frame.
• The setListWidth state setter (its value lives in a ref now).

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

UnderlinePanels is experimental. Public API is unchanged; consumers get
the perf win automatically.

Testing & Reviewing

cd packages/react
npx vitest run --project '@primer/react (chromium)' src/experimental/UnderlinePanels/UnderlinePanels.test.tsx
# 14 tests pass (11 pre-existing + 3 new perf-regression pins)

Reviewer focus:

1. The useMemo deps are [children, parentId] — iconsVisible and
   loadingCounters are no longer in there. Verify this is correct: those
   flags reach Tab via context, so the memo doesn't need to invalidate when
   they change.
2. The React.memo(Tab) cast: Tab.__SLOT__ and Tab.displayName are
   still set correctly on the memo wrapper so isSlot(child, Tab) and
   child.type === Tab keep working through cloneElement.
3. The third regression test (does not re-render tabs when an unrelated re-render of the parent occurs) relies on Tab having referentially
   stable React element identity across the host's rerender(...) —
   verify the tree constant pattern in the test models real consumer
   usage.

Merge checklist

• Added/updated tests
• Added/updated documentation (changeset)
• 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)

[changeset-bot]

🦋 Changeset detected

Latest commit: 61f3421

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	Patch

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

[github-actions]

⚠️ Action required

👋 Hi, this pull request contains changes to the source code that github/github-ui depends on. If you are GitHub staff, test these changes with github/github-ui using the integration workflow. Check the integration testing docs for step-by-step instructions. Or, apply the integration-tests: skipped manually label to skip these checks.

To publish a canary release for integration testing, apply the Canary Release label to this PR.