docs: add prop merging ADR and mergeProps utility by Copilot · Pull Request #8248 · primer/react

Copilot · 2026-07-28T20:09:32Z

Closes #

This PR adds ADR-025 and the foundation for using one prop-merging convention across Primer React. This entry owns the ADR, style guide guidance, and the internal mergeProps utility and tests.

Changelog

New

Add ADR-025 for prop merging.
Add the internal mergeProps utility and unit tests.

Changed

Document prop merging conventions, React 19 ref behavior, and typed prop-gating patterns.

Removed

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

This is internal architecture guidance and an unexported utility, so it has no public-facing impact.

Testing & Reviewing

Please review the ADR contract and merge semantics, especially class names, event handlers, styles, refs, and component-owned props.

changeset-bot · 2026-07-28T20:09:37Z

⚠️ No Changeset found

Latest commit: 4274bec

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

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

joshblack

@copilot add the mergeProps.ts utility from: https://github.com/primer/react/pull/8168/changes#diff-b21bbbcb2674bcbc6f8e205e1c9223efea602c2abea46bb150c1d34b8ee06d07 and include tests for it. Also add an ADR for prop merging conventions for me with this decision. Highlight any scenarios that I should be aware of that aren't included already

Copilot · 2026-07-28T21:22:44Z

@copilot add the mergeProps.ts utility from: https://github.com/primer/react/pull/8168/changes#diff-b21bbbcb2674bcbc6f8e205e1c9223efea602c2abea46bb150c1d34b8ee06d07 and include tests for it. Also add ...

Implemented in ba4584c. Added mergeProps with tests, ADR-025, and updated the style guide to use the utility. The ADR highlights refs, shallow style merging, defaultPrevented/stopPropagation, synchronous one-way cancellation, thrown errors, on* callback detection, zero- and multi-argument callbacks, and explicit undefined precedence.

github-actions · 2026-07-28T21:25:22Z

⚠️ 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.

joshblack

@copilot I want to create an eslint rule for this behavior. To do this, let's:

Create a local @primer/eslint-config private package in packages/*
In this, add a rule for the proposed merge props behavior
This rule should look to see if props are spread on the outermost element and prefer using mergeProps
This rule should not be enabled by default (eventually we will turn it on)
Add a new migration report for this rule, reporting on number of places where it is failing that we would need to migrate

joshblack · 2026-07-29T15:01:37Z

+
+The general rules do not cover every form of composition:
+
+- **Refs are not composed.** Use `useMergedRefs` when both the component and


@copilot add a note that this will change in React 19 with refs passed as props

Documented the React 19 ref-as-prop behavior and clarified that refs still require separate composition in 01b40e1.

primer · 2026-08-04T20:57:23Z

🤖 Lint and formatting issues have been automatically fixed and committed to this PR.

Co-authored-by: joshblack <3901764+joshblack@users.noreply.github.com>

Add documentation for mergeProps utility function.

Treat undefined consumer handlers as absent so call sites can pass forwardable props directly to mergeProps. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: faa7e8da-1bd6-4c1c-831d-50b021ccc03b

Document how to forward destructured consumer props without rebuilding the second argument and prefer conventional internal prop values. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: faa7e8da-1bd6-4c1c-831d-50b021ccc03b

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: 9541ca7f-0281-4223-a839-39d75393d922

Copilot AI assigned Copilot and joshblack Jul 28, 2026

joshblack added the skip changeset This change does not need a changelog label Jul 28, 2026 — with Copilot SWE Agent

Copilot finished work on behalf of joshblack July 28, 2026 20:14

Copilot created this pull request from a session on behalf of joshblack July 28, 2026 20:14 View session

Copilot AI requested a review from joshblack July 28, 2026 20:14

joshblack reviewed Jul 28, 2026

View reviewed changes

Copilot started work on behalf of joshblack July 28, 2026 20:54 View session

Copilot AI requested a review from joshblack July 28, 2026 21:23

Copilot finished work on behalf of joshblack July 28, 2026 21:23

github-actions Bot added the integration-tests: recommended This change needs to be tested for breaking changes. See https://arc.net/l/quote/tdmpakpm label Jul 28, 2026

joshblack reviewed Jul 28, 2026

View reviewed changes

Comment thread contributor-docs/style.md Outdated

joshblack reviewed Jul 28, 2026

View reviewed changes

Comment thread contributor-docs/adrs/adr-025-prop-merging.md Outdated

Copilot started work on behalf of joshblack July 28, 2026 21:27 View session

Copilot finished work on behalf of joshblack July 28, 2026 21:32

Copilot AI requested a review from joshblack July 28, 2026 21:32

Copilot started work on behalf of joshblack July 28, 2026 21:32 View session

github-actions Bot temporarily deployed to storybook-preview-8248 July 28, 2026 21:34 Inactive

Copilot finished work on behalf of joshblack July 28, 2026 21:36

joshblack reviewed Jul 29, 2026

View reviewed changes

Copilot started work on behalf of joshblack July 29, 2026 14:20 View session

Copilot stopped work on behalf of joshblack due to an error July 29, 2026 14:49
An unexpected error occurred. For more details, see the detailed logs in GitHub Actions.

Copilot AI requested a review from joshblack July 29, 2026 14:49

joshblack reviewed Jul 29, 2026

View reviewed changes

Copilot started work on behalf of joshblack July 29, 2026 15:02 View session

Copilot AI requested a review from joshblack July 29, 2026 15:23

Copilot finished work on behalf of joshblack July 29, 2026 15:23

Copilot finished work on behalf of joshblack July 30, 2026 16:23

github-actions Bot temporarily deployed to storybook-preview-8248 July 30, 2026 16:28 Inactive

Copilot AI deployed to github-pages July 30, 2026 16:38 View deployment

github-actions Bot temporarily deployed to storybook-preview-8248 July 30, 2026 16:39 Inactive

joshblack force-pushed the copilot/update-style-docs-prop-merging branch from c163b71 to fc7d2ac Compare July 30, 2026 17:01

joshblack deployed to github-pages July 30, 2026 17:11 — with GitHub Actions View deployment

github-actions Bot temporarily deployed to storybook-preview-8248 July 30, 2026 17:11 Inactive

jonrohan approved these changes Jul 31, 2026

View reviewed changes

joshblack force-pushed the copilot/update-style-docs-prop-merging branch from fc7d2ac to 1bc6f64 Compare July 31, 2026 18:35

joshblack mentioned this pull request Jul 31, 2026

Add merge props migration driver #8254

Open

4 tasks

francinelucca reviewed Jul 31, 2026

View reviewed changes

Comment thread packages/eslint-config/src/rules/preferMergeProps.ts Outdated

Comment thread packages/react/src/utils/mergeProps.ts

joshblack mentioned this pull request Jul 31, 2026

docs: create skill for generating ADR migration artifacts #8257

Merged

1 task

francinelucca approved these changes Aug 5, 2026

View reviewed changes

liuliu-dev approved these changes Aug 5, 2026

View reviewed changes

llastflowers approved these changes Aug 7, 2026

View reviewed changes

TylerJDev approved these changes Aug 10, 2026

View reviewed changes

Copilot AI and others added 12 commits August 13, 2026 16:17

Document prop merging conventions

263c25c

Co-authored-by: joshblack <3901764+joshblack@users.noreply.github.com>

Add prop merging utility and ADR

d404b2b

Co-authored-by: joshblack <3901764+joshblack@users.noreply.github.com>

Remove ADR reference from style guide

bc5e845

Co-authored-by: joshblack <3901764+joshblack@users.noreply.github.com>

Mark prop merging ADR as proposed

7c0ad50

Co-authored-by: joshblack <3901764+joshblack@users.noreply.github.com>

Document React 19 ref prop behavior

ff2f94a

Co-authored-by: joshblack <3901764+joshblack@users.noreply.github.com>

docs: add typed prop-gating examples to ADR-025

2c2a9ca

Co-authored-by: joshblack <3901764+joshblack@users.noreply.github.com>

Document mergeProps function behavior

e2d6bd3

Add documentation for mergeProps utility function.

chore: auto-fix lint and formatting issues

7bd1b52

Handle undefined consumer event handlers

a069b88

Treat undefined consumer handlers as absent so call sites can pass forwardable props directly to mergeProps. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: faa7e8da-1bd6-4c1c-831d-50b021ccc03b

Clarify inline class name merging

cd253a0

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: 9541ca7f-0281-4223-a839-39d75393d922

Document ref ordering with mergeProps

4274bec

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: 9541ca7f-0281-4223-a839-39d75393d922

siddharthkp approved these changes Aug 14, 2026

View reviewed changes

Navigation Menu

Uh oh!

docs: add prop merging ADR and mergeProps utility - #8248

docs: add prop merging ADR and mergeProps utility#8248
joshblack with Copilot wants to merge 12 commits into
mainfrom
copilot/update-style-docs-prop-merging

Copilot AI commented Jul 28, 2026 •

edited by joshblack

Loading

Uh oh!

changeset-bot Bot commented Jul 28, 2026 •

edited

Loading

Uh oh!

joshblack left a comment

Uh oh!

Copilot AI commented Jul 28, 2026

Uh oh!

github-actions Bot commented Jul 28, 2026

Uh oh!

Uh oh!

Uh oh!

joshblack left a comment

Uh oh!

joshblack Jul 29, 2026

Uh oh!

Copilot AI Jul 29, 2026

Uh oh!

Uh oh!

Uh oh!

primer Bot commented Aug 4, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

9 participants


		The general rules do not cover every form of composition:

		- Refs are not composed. Use `useMergedRefs` when both the component and

Uh oh!

Conversation

Copilot AI commented Jul 28, 2026 • edited by joshblack Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Changelog

New

Changed

Removed

Rollout strategy

Testing & Reviewing

Uh oh!

changeset-bot Bot commented Jul 28, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

⚠️ No Changeset found

Uh oh!

joshblack left a comment

Choose a reason for hiding this comment

Uh oh!

Copilot AI commented Jul 28, 2026

Uh oh!

github-actions Bot commented Jul 28, 2026

⚠️ Action required

Uh oh!

Uh oh!

Uh oh!

joshblack left a comment

Choose a reason for hiding this comment

Uh oh!

joshblack Jul 29, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jul 29, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

primer Bot commented Aug 4, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

9 participants

Copilot AI commented Jul 28, 2026 •

edited by joshblack

Loading

changeset-bot Bot commented Jul 28, 2026 •

edited

Loading