refactor(ui): share one base props type across Mosaic components by alexcarpenter · Pull Request #9267 · clerk/javascript

alexcarpenter · 2026-07-28T19:41:19Z

Description

Heading, Text and Badge each accept render and each expose color as a variant, but all three derived their props differently: two base types (React.ComponentPropsWithRef vs headless ComponentProps), two different things omitted (color vs render), the render union restated inline in one and imported in the other, and two mechanisms for narrowing color — Omit then redeclare in the interfaces, silent intersection in the type alias.

This introduces one shared base in mosaic/props.ts, mirroring Base UI's BaseUIComponentProps:

export type MosaicComponentProps<Tag extends keyof React.JSX.IntrinsicElements> =
  Omit<React.ComponentPropsWithRef<Tag>, 'color'> & {
    render?: RenderPropOrElement<Tag>;
  };

color is omitted once rather than per component, so the next component to expose it as a variant inherits the narrowing instead of rediscovering the collision with the non-standard HTML color attribute. Badge also stops omitting render only to re-add it.

Type-only — all three components resolve to the same props as before, so no changeset body.

Stacked on carp/mosaic-typography-stylex (#9244); merge that first.

Checklist

pnpm test runs as expected.
pnpm build runs as expected.
(If applicable) JSDoc comments have been added or updated for any package exports
(If applicable) Documentation has been updated

Type of change

changeset-bot · 2026-07-28T19:41:24Z

🦋 Changeset detected

Latest commit: ae6a5ae

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 · 2026-07-28T19:41:26Z

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

Project	Deployment	Actions	Updated (UTC)
clerk-js-sandbox	Ready	Preview, Comment	Jul 29, 2026 12:23am
swingset	Ready	Preview, Comment	Jul 29, 2026 12:23am

Heading, Text and Badge each derived their props differently: two base types (`React.ComponentPropsWithRef` vs headless `ComponentProps`), two things omitted (`color` vs `render`), the render union restated inline in one and imported in the other, and two ways of narrowing `color` — `Omit` then redeclare in the interfaces, silent intersection in the type alias. Collapse all of it into `MosaicComponentProps<Tag>`, mirroring Base UI's `BaseUIComponentProps`. `color` is omitted once, so the next component to expose it as a variant inherits the narrowing instead of rediscovering it. Type-only: all three components resolve to the same props as before.

pkg-pr-new · 2026-07-29T00:24:15Z

Open in StackBlitz

@clerk/astro

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

@clerk/backend

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

@clerk/chrome-extension

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

@clerk/clerk-js

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

@clerk/electron

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

@clerk/electron-passkeys

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

@clerk/eslint-plugin

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

@clerk/expo

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

@clerk/expo-google-signin

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

@clerk/expo-passkeys

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

@clerk/express

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

@clerk/fastify

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

@clerk/hono

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

@clerk/localizations

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

@clerk/nextjs

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

@clerk/nuxt

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

@clerk/react

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

@clerk/react-router

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

@clerk/shared

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

@clerk/tanstack-react-start

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

@clerk/testing

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

@clerk/ui

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

@clerk/upgrade

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

@clerk/vue

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

commit: ae6a5ae

github-actions · 2026-07-29T00:24:39Z

API Changes Report

Generated by Break Check on 2026-07-29T00:24:37.055Z

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 ae6a5ae.}

coderabbitai · 2026-07-29T00:26:48Z

📝 Walkthrough

Walkthrough

Adds the exported generic MosaicComponentProps type, combining intrinsic element props with centralized render typing while omitting color. Updates Badge, Heading, and Text public prop types to use it, retaining their component-specific variant props. Adds a changeset describing the update.

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

Possibly related PRs

clerk/javascript#9221: Adds the Mosaic Badge component and its render and prop surface.
clerk/javascript#9244: Migrates Mosaic Heading and Text typings and overlaps with these shared prop contracts.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly summarizes the main refactor: sharing one base props type across Mosaic components.
Description check	✅ Passed	The description directly matches the refactor and explains the shared Mosaic component props change.
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.

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

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

coderabbitai

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In @.changeset/mosaic-component-props.md:
- Around line 1-2: Make .changeset/mosaic-component-props.md intentional: either
add the appropriate `@clerk/ui` package entry and release note describing the
public Mosaic prop type changes, or remove the empty changeset file when this
change should not be released.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

Push a commit to this branch (recommended)
Create a new PR with the fixes

ℹ️ Review info

⚙️ Run configuration

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

Review profile: CHILL

Plan: Pro Plus

Run ID: 4913f54e-d13a-4996-b8d2-87c731507673

📥 Commits

Reviewing files that changed from the base of the PR and between e16bd7f and ae6a5ae.

📒 Files selected for processing (5)

.changeset/mosaic-component-props.md
packages/ui/src/mosaic/components/badge/badge.tsx
packages/ui/src/mosaic/components/heading/heading.tsx
packages/ui/src/mosaic/components/text/text.tsx
packages/ui/src/mosaic/props.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)

coderabbitai · 2026-07-29T00:26:51Z

+---
+---


📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win

🧩 Analysis chain

🏁 Script executed:

#!/bin/bash set -euo pipefail echo "== changeset file ==" cat -n .changeset/mosaic-component-props.md || true echo echo "== changeset files ==" find .changeset -maxdepth 1 -type f -print | sort | sed -n '1,80p' echo echo "== package manifests mentioning `@clerk/ui` / packages/ui ==" rg -n '"`@clerk/ui`"|packages/ui|`@clerk/ui`' package.json packages .changeset --glob '!pnpm-lock.yaml' --glob '!node_modules/**' | sed -n '1,200p' echo echo "== recent diff stat ==" git diff --stat HEAD~1 HEAD || true

Repository: clerk/javascript

Length of output: 26894

Make the changeset intentional.

.changeset/mosaic-component-props.md only has empty Changeset delimiters, so it does not version or document @clerk/ui. Add the appropriate package entry/release note for the public Mosaic prop type changes, or remove the no-op file if this change is intentionally excluded from the release.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In @.changeset/mosaic-component-props.md around lines 1 - 2, Make .changeset/mosaic-component-props.md intentional: either add the appropriate `@clerk/ui` package entry and release note describing the public Mosaic prop type changes, or remove the empty changeset file when this change should not be released.

Source: Coding guidelines

vercel Bot deployed to Preview – swingset July 28, 2026 19:41 View deployment

github-actions Bot added the ui label Jul 28, 2026

alexcarpenter force-pushed the carp/mosaic-typography-stylex branch from 71384a1 to 27b88a3 Compare July 28, 2026 19:49

alexcarpenter force-pushed the carp/mosaic-component-props branch from aecb873 to 2f669ec Compare July 28, 2026 19:50

vercel Bot deployed to Preview – clerk-js-sandbox July 28, 2026 19:51 View deployment

vercel Bot deployed to Preview – swingset July 28, 2026 19:53 View deployment

alexcarpenter force-pushed the carp/mosaic-component-props branch from 2f669ec to a934303 Compare July 28, 2026 19:59

vercel Bot deployed to Preview – clerk-js-sandbox July 28, 2026 20:00 View deployment

vercel Bot deployed to Preview – swingset July 28, 2026 20:02 View deployment

maxyinger approved these changes Jul 28, 2026

View reviewed changes

Base automatically changed from carp/mosaic-typography-stylex to main July 28, 2026 22:21

alexcarpenter force-pushed the carp/mosaic-component-props branch from a934303 to ae6a5ae Compare July 29, 2026 00:21

vercel Bot deployed to Preview – clerk-js-sandbox July 29, 2026 00:22 View deployment

alexcarpenter enabled auto-merge (squash) July 29, 2026 00:22

vercel Bot deployed to Preview – swingset July 29, 2026 00:23 View deployment

coderabbitai Bot reviewed Jul 29, 2026

View reviewed changes

alexcarpenter merged commit 19f7bc6 into main Jul 29, 2026
52 checks passed

alexcarpenter deleted the carp/mosaic-component-props branch July 29, 2026 00:29

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

refactor(ui): share one base props type across Mosaic components - #9267

refactor(ui): share one base props type across Mosaic components#9267
alexcarpenter merged 1 commit into
mainfrom
carp/mosaic-component-props

alexcarpenter commented Jul 28, 2026

Uh oh!

changeset-bot Bot commented Jul 28, 2026 •

edited

Loading

Uh oh!

vercel Bot commented Jul 28, 2026 •

edited

Loading

Uh oh!

pkg-pr-new Bot commented Jul 29, 2026

Uh oh!

github-actions Bot commented Jul 29, 2026

Uh oh!

coderabbitai Bot commented Jul 29, 2026

Walkthrough

Uh oh!

coderabbitai Bot left a comment

Uh oh!

coderabbitai Bot Jul 29, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

		---
		---

Uh oh!

Conversation

alexcarpenter commented Jul 28, 2026

Description

Checklist

Type of change

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!

🦋 Changeset detected

Uh oh!

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

Uh oh!

Uh oh!

pkg-pr-new Bot commented Jul 29, 2026

Uh oh!

github-actions Bot commented Jul 29, 2026

API Changes Report

Summary

No API Changes Detected

Uh oh!

coderabbitai Bot commented Jul 29, 2026

Walkthrough

Uh oh!

coderabbitai Bot left a comment

Choose a reason for hiding this comment

Uh oh!

coderabbitai Bot Jul 29, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

changeset-bot Bot commented Jul 28, 2026 •

edited

Loading

vercel Bot commented Jul 28, 2026 •

edited

Loading