refactor(ui): rename Mosaic mergeProps to mergeStyleProps

[alexcarpenter]

Description

@clerk/headless and @clerk/ui (Mosaic) each export a mergeProps, with different signatures and semantics:

• headless mergeProps(a, b) — polymorphic prop merge that chains onXxx handlers, shallow-merges style, concatenates className.
• mosaic mergeProps(themeProps(...), stylex.props(...), className, style) — a positional fuser of styling output that concatenates className and spreads style, and does not chain handlers.

Same name, different behavior is a footgun (the handler-chaining difference is the sharp edge). This renames the Mosaic helper to mergeStyleProps, which describes its actual job (fusing themeProps + stylex.props + consumer className/style) and ends the overlap.

Internal-only: the Mosaic JS is not in any @clerk/ui package export path (only styles.css is public), so this is not a public API change. Empty changeset.

Checklist

• Renamed mergeProps -> mergeStyleProps in props.ts, the styles/index.ts barrel re-export, button.tsx, and props.test.ts.
• pnpm --filter @clerk/ui test src/mosaic/__tests__/props.test.ts passes (13).
• pnpm --filter @clerk/ui type-check clean.

[changeset-bot]

🦋 Changeset detected

Latest commit: 264db12

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

This PR includes changesets to release 0 packages

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

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

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
clerk-js-sandbox	Ready	Preview, Comment	Jul 23, 2026 11:42pm
swingset	Ready	Preview, Comment	Jul 23, 2026 11:42pm

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Repository YAML (base), Organization UI (inherited)

Review profile: CHILL

Plan: Pro Plus

Run ID: 63d3ce12-702c-45f9-ba82-0c6f1801ddad

📥 Commits

Reviewing files that changed from the base of the PR and between 76f1085 and 264db12.

📒 Files selected for processing (5)

• .changeset/mosaic-rename-merge-style-props.md
• packages/ui/src/mosaic/__tests__/props.test.ts
• packages/ui/src/mosaic/components/button/button.tsx
• packages/ui/src/mosaic/props.ts
• packages/ui/src/mosaic/styles/index.ts

🔗 Linked repositories identified

CodeRabbit considers these linked repositories for cross-repo context during reviews:

• clerk/clerk_go (manual)
• clerk/dashboard (manual)
• clerk/accounts (manual)
• clerk/backoffice (manual)
• clerk/clerk (manual)
• clerk/clerk-docs (manual)
• clerk/cloudflare-workers (manual)
• clerk/clerk-ios (auto-detected)
• clerk/cli (auto-detected)
• clerk/clerk-android (auto-detected)

---

📝 Walkthrough

Walkthrough

Renames the Mosaic mergeProps helper to mergeStyleProps, updates the styles barrel export and Button component usage, and revises the associated tests. Adds a changeset documenting the rename.

Estimated code review effort: 2 (Simple) | ~10 minutes

Possibly related PRs

• clerk/javascript#9208: Introduced the Mosaic props utility involved in this rename.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly matches the main change: renaming Mosaic mergeProps to mergeStyleProps.
Description check	✅ Passed	The description is directly related to the PR and accurately explains the rename and its motivation.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

---

_{Comment @coderabbitai help to get the list of available commands.}

[pkg-pr-new]

Open in StackBlitz

@clerk/astro

npm i https://pkg.pr.new/@clerk/astro@9236

@clerk/backend

npm i https://pkg.pr.new/@clerk/backend@9236

@clerk/chrome-extension

npm i https://pkg.pr.new/@clerk/chrome-extension@9236

@clerk/clerk-js

npm i https://pkg.pr.new/@clerk/clerk-js@9236

@clerk/electron

npm i https://pkg.pr.new/@clerk/electron@9236

@clerk/electron-passkeys

npm i https://pkg.pr.new/@clerk/electron-passkeys@9236

@clerk/eslint-plugin

npm i https://pkg.pr.new/@clerk/eslint-plugin@9236

@clerk/expo

npm i https://pkg.pr.new/@clerk/expo@9236

@clerk/expo-google-signin

npm i https://pkg.pr.new/@clerk/expo-google-signin@9236

@clerk/expo-passkeys

npm i https://pkg.pr.new/@clerk/expo-passkeys@9236

@clerk/express

npm i https://pkg.pr.new/@clerk/express@9236

@clerk/fastify

npm i https://pkg.pr.new/@clerk/fastify@9236

@clerk/hono

npm i https://pkg.pr.new/@clerk/hono@9236

@clerk/localizations

npm i https://pkg.pr.new/@clerk/localizations@9236

@clerk/nextjs

npm i https://pkg.pr.new/@clerk/nextjs@9236

@clerk/nuxt

npm i https://pkg.pr.new/@clerk/nuxt@9236

@clerk/react

npm i https://pkg.pr.new/@clerk/react@9236

@clerk/react-router

npm i https://pkg.pr.new/@clerk/react-router@9236

@clerk/shared

npm i https://pkg.pr.new/@clerk/shared@9236

@clerk/tanstack-react-start

npm i https://pkg.pr.new/@clerk/tanstack-react-start@9236

@clerk/testing

npm i https://pkg.pr.new/@clerk/testing@9236

@clerk/ui

npm i https://pkg.pr.new/@clerk/ui@9236

@clerk/upgrade

npm i https://pkg.pr.new/@clerk/upgrade@9236

@clerk/vue

npm i https://pkg.pr.new/@clerk/vue@9236

commit: 264db12

[github-actions]

API Changes Report

Generated by Break Check on 2026-07-23T23:44:14.964Z

Summary

Metric	Count
Packages analyzed	19
Packages with changes	0
🔴 Breaking changes	0
🟡 Non-breaking changes	0
🟢 Additions	0

No API Changes Detected

All packages have stable APIs with no detected changes.

---

Report generated by Break Check

_{Last ran on 264db12.}