Make popover in AnchoredOverlay opt-in

[TylerJDev]

Closes https://github.com/github/primer/issues/6556 & https://github.com/github/primer/issues/6557

Makes usage of the popover API opt-in, rather than have it on by default.
We may want to have the popover API enabled by default in the future, so the prop usage could be temporary.

Changelog

Changed

• Make popover API usage in AnchoredOverlay | Overlay opt-in

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

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)

[changeset-bot]

🦋 Changeset detected

Latest commit: 73d3763

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

[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.

[Copilot]

Pull request overview

This PR makes use of the browser Popover API in AnchoredOverlay opt-in (instead of implicitly enabling it whenever the CSS anchor positioning feature flag is active), aligning with the intent to treat popover behavior as an optional enhancement behind a feature flag.

Changes:

• Added a new usePopover?: boolean prop to AnchoredOverlay, defaulting to false.
• Gated Popover API wiring (popoverTarget, popover="manual", id, and showPopover()) behind usePopover && cssAnchorPositioning.
• Added a changeset describing the behavioral change.

Show a summary per file

File	Description
packages/react/src/AnchoredOverlay/AnchoredOverlay.tsx	Introduces usePopover and gates Popover API usage behind an explicit opt-in.
.changeset/hot-phones-sing.md	Records the change in release notes (currently marked as a patch bump).

Copilot's findings

Comments suppressed due to low confidence (2)

packages/react/src/AnchoredOverlay/AnchoredOverlay.tsx:176

• shouldUsePopover is introduced, but onAnchorClick still calls event.preventDefault() based on cssAnchorPositioning. With usePopover={false} and native CSS anchor positioning enabled, this will still prevent the anchor’s default action (e.g. link navigation) even though no popoverTarget is set. Gate the preventDefault() (and the callback deps) on shouldUsePopover instead of cssAnchorPositioning.

  const cssAnchorPositioningFlag = useFeatureFlag('primer_react_css_anchor_positioning')
  const supportsNativeCSSAnchorPositioning = useRef(false)
  const cssAnchorPositioning = cssAnchorPositioningFlag && supportsNativeCSSAnchorPositioning.current
  // Only use Popover API when both CSS anchor positioning is enabled AND usePopover is true
  const shouldUsePopover = cssAnchorPositioning && usePopover
  const anchorRef = useProvidedRefOrCreate(externalAnchorRef)

packages/react/src/AnchoredOverlay/AnchoredOverlay.tsx:175

• This change makes Popover API usage opt-in, but there are no tests asserting the new default behavior (e.g. when the feature flag + native support are present, usePopover defaults to off and no popoverTarget/popover="manual" is applied; and when usePopover is on, showPopover() is invoked). Adding a focused unit test would help prevent regressions.

  usePopover = false,
}) => {
  const cssAnchorPositioningFlag = useFeatureFlag('primer_react_css_anchor_positioning')
  const supportsNativeCSSAnchorPositioning = useRef(false)
  const cssAnchorPositioning = cssAnchorPositioningFlag && supportsNativeCSSAnchorPositioning.current
  // Only use Popover API when both CSS anchor positioning is enabled AND usePopover is true
  const shouldUsePopover = cssAnchorPositioning && usePopover

• Files reviewed: 2/2 changed files
• Comments generated: 2

[siddharthkp]

Trust you with the implementation. Left a couple comments about direction and naming.

[primer-integration]

👋 Hi from github/github-ui! Your integration PR is ready: https://github.com/github/github-ui/pull/18924

[primer-integration]

Integration test results from github/github-ui:

  CI Passed
  VRT Passed
  Projects Passed

All checks passed!