Graduate merged forwarded refs

[llastflowers]

Part of https://github.com/github/primer/issues/7263

Changelog

New

• None.

Changed

• Components now always preserve forwarded refs while maintaining their internal refs.
• AnchoredOverlay tracks replacement anchor elements without relying on incidental overlay ref updates.
• UnderlinePanels applies the complete ref and keyboard props returned by useTabList.

Removed

• Removed the primer_react_merged_forwarded_refs feature flag and its fallback paths.

Rollout strategy

• No changes needed in github/github-ui
• Needs changes in github/github-ui — after this is released, update @primer/react and remove the client feature flag allowlist entry before deleting the DevPortal flag.
• Ships with feature flag(s)
• Not sure
• None

Testing & Reviewing

• npm test -- --run
• npm run type-check
• npm run lint
• npm run lint:css
• npm run format:diff
• npm run build

[changeset-bot]

🦋 Changeset detected

Latest commit: c2ad1a0

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.

[Copilot]

🔵 Needs a closer look

Cross-component ref lifecycle changes affect focus and positioning and warrant human confirmation without runtime validation.

0 open findings

What changed in this PR

Makes merged forwarded refs unconditional across Primer React, preserving consumer refs alongside internal component refs.

Changes:

• Removes the merged-ref feature flag and fallback paths.
• Updates anchor replacement tracking and applies complete tab-list props in UnderlinePanels.
• Simplifies ref tests and adds a patch changeset.

File	Description
packages/​react/​src/​TooltipV2/​Tooltip.tsx	Always merges trigger and forwarded refs.
packages/​react/​src/​TooltipV2/​__tests__/​Tooltip.test.tsx	Removes flag-dependent test variants.
packages/​react/​src/​TextInput/​TextInput.tsx	Uses merged input refs unconditionally.
packages/​react/​src/​TextInput/​TextInput.test.tsx	Simplifies forwarded-ref tests.
packages/​react/​src/​PageHeader/​PageHeader.tsx	Preserves root and title refs without gating.
packages/​react/​src/​PageHeader/​PageHeader.test.tsx	Simplifies forwarded-ref tests.
packages/​react/​src/​FilteredActionList/​FilteredActionList.tsx	Always merges input and scroll-container refs.
packages/​react/​src/​FilteredActionList/​FilteredActionList.test.tsx	Simplifies ref tests.
packages/​react/​src/​FeatureFlags/​DefaultFeatureFlags.ts	Removes the merged-ref flag.
packages/​react/​src/​experimental/​UnderlinePanels/​UnderlinePanels.tsx	Applies all returned tab-list props.
packages/​react/​src/​experimental/​Tabs/​useTabList.ts	Always merges tab-list refs.
packages/​react/​src/​experimental/​Tabs/​Tabs.test.tsx	Simplifies tab-list ref tests.
packages/​react/​src/​Dialog/​Dialog.tsx	Uses merged autofocus-button refs unconditionally.
packages/​react/​src/​Dialog/​Dialog.test.tsx	Removes flag variants from autofocus testing.
packages/​react/​src/​Checkbox/​Checkbox.tsx	Always merges checkbox refs.
packages/​react/​src/​Checkbox/​Checkbox.test.tsx	Simplifies forwarded-ref tests.
packages/​react/​src/​ButtonGroup/​ButtonGroup.tsx	Always merges group refs.
packages/​react/​src/​ButtonGroup/​ButtonGroup.test.tsx	Simplifies forwarded-ref tests.
packages/​react/​src/​AnchoredOverlay/​AnchoredOverlay.tsx	Tracks anchor replacements and always merges overlay refs.
packages/​react/​src/​AnchoredOverlay/​AnchoredOverlay.test.tsx	Simplifies overlay-ref tests.
packages/​react/​src/​ActionList/​List.tsx	Always merges list refs.
packages/​react/​src/​ActionList/​ActionList.test.tsx	Simplifies forwarded-ref tests.
.changeset/​merged-forwarded-refs.md	Documents the ref-handling patch release.

🧠 Review effort: Balanced

---

💡 Add a code-review agent skill for context-aware, tailored reviews. Learn more in the docs.

[primer-integration]

Integration test results from github/github-ui PR:

  Changes Failed
  CI Failed
  VRT Running
  Projects Passed

Changes check could not confirm that this PR only changes the expected integration paths. Open the Changes run for the unexpected files or error details.

This check is not required for merging.

Integration PRs should only change:

• node_modules/**
• packages/primer/package.json
• package-lock.json
• Top-level npm-pack tarballs in packages/primer/.prc-integration-tarballs/, named for dependencies or devDependencies in the PR base's Primer workspace manifest.
• Removal only (not additions, edits, or renames) of top-level patches in packages/patch-packages/patches/ for packages whose tarballs are added, modified, or renamed in this PR. Existing workflows also support removing @primer/react patches without tarballs.

Fixes made only in an integration PR do not reach github-ui's main branch. After the upstream Primer PR merges, other integration PRs and release PRs can fail because they do not include those fixes.

Before merging your Primer PR:

1. Keep changes backward compatible. If that is not possible, discuss the breaking change before merging.
2. If tests are over-reaching and testing implementation details, fix and merge those tests in github-ui first, then merge the Primer change.
3. If the change and tests are both valid but tests need updating, first make and merge tests that pass with both the old and new Primer versions, as you would for a feature flag. Then merge the Primer change.

Please talk to the release conductor or ask in #primer before merging your Primer PR.

CI check runs linting, type checking, and unit tests. Check the workflow logs for specific failures.

Need help? If you believe this failure is unrelated to your changes, please reach out to the Primer team for assistance.