feat(ui): migrate Mosaic Heading and Text to StyleX#9244
Conversation
Move both typography components off the Emotion slot-recipe engine onto
StyleX atoms, following the Button migration's contract: a stable
`.cl-heading`/`.cl-text` class plus `data-size`/`data-intent` attrs, with
the consumer's `className`/`style` merged last so they win.
The size and intent axes are identical across the two components, so the
atoms live once in a shared `typography.styles.ts`; Heading only adds its
weight on top and Text adds nothing.
Collapse the `--cl-text-label-*` tokens into one named step scale
(`xs` -> `2xl`) that every text-bearing component sizes against -- the
`label`/`label-sm` steps were byte-identical to `sm`/`xs`. Font weights
become their own `--cl-font-{normal,medium,semibold,bold}` group, since
weight and size vary independently.
`render`, the Heading/Text contexts, and ref forwarding are unchanged.
The `sx` prop is dropped as it was for Button; the three call sites that
used it move to `style`.
…engine `PropTable` appended an `sx` row unconditionally, but StyleX components have no `sx` -- they merge the consumer's `className`/`style` after their own atoms. `meta.styleEngine` now picks the row set, and Button, Heading, and Text declare `'stylex'`.
🦋 Changeset detectedLatest commit: d97f67c The changes in this PR will be included in the next version bump. This PR includes changesets to release 0 packagesWhen 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 |
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
@clerk/astro
@clerk/backend
@clerk/chrome-extension
@clerk/clerk-js
@clerk/electron
@clerk/electron-passkeys
@clerk/eslint-plugin
@clerk/expo
@clerk/expo-google-signin
@clerk/expo-passkeys
@clerk/express
@clerk/fastify
@clerk/hono
@clerk/localizations
@clerk/nextjs
@clerk/nuxt
@clerk/react
@clerk/react-router
@clerk/shared
@clerk/tanstack-react-start
@clerk/testing
@clerk/ui
@clerk/upgrade
@clerk/vue
commit: |
API Changes Report
Summary
No API Changes DetectedAll packages have stable APIs with no detected changes. Report generated by Break Check Last ran on |
|
No actionable comments were generated in the recent review. 🎉 ℹ️ Recent review info⚙️ Run configurationConfiguration used: Repository YAML (base), Organization UI (inherited) Review profile: CHILL Plan: Pro Plus Run ID: 📒 Files selected for processing (7)
🔗 Linked repositories identifiedCodeRabbit considers these linked repositories for cross-repo context during reviews:
💤 Files with no reviewable changes (6)
🚧 Files skipped from review as they are similar to previous changes (1)
📝 WalkthroughWalkthroughMosaic typography is migrated to StyleX through shared size, intent, and font-weight tokens plus new Heading and Text components with context, rendering overrides, ref forwarding, and tests. Story metadata and PropTable now support engine-specific styling props. Mosaic exports, organization views, Button styles, build externalization, release metadata, and repository guidance are updated accordingly. Estimated code review effort: 4 (Complex) | ~45 minutes Possibly related PRs
🚥 Pre-merge checks | ✅ 4 | ❌ 1❌ Failed checks (1 warning)
✅ Passed checks (4 passed)
Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 3
🤖 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-typography-stylex.md:
- Around line 1-2: Replace the empty changeset frontmatter with a non-empty
changeset for the Mosaic package, specifying the appropriate version bump for
the affected package and adding a concise user-facing summary of the `@clerk/ui`
component behavior and customization changes.
In `@packages/ui/src/mosaic/components/heading/heading.test.tsx`:
- Around line 39-44: Add a test alongside the existing callback case in the
heading test suite that passes a React element directly to Heading’s render
prop, then verify the cloned element receives the heading children and merged
slot attributes such as the cl-heading class and data-size value. Use the
existing Heading test patterns and keep the callback coverage unchanged.
In `@packages/ui/src/mosaic/components/text/text.tsx`:
- Around line 20-24: Update Text and its ref typing so the component’s exposed
ref element matches the host selected by render, using the project’s established
polymorphic component pattern; alternatively restrict render to
paragraph-compatible output if polymorphism is unsupported. Preserve the default
<p> behavior and add a regression covering a render override to <span> with the
corresponding ref type.
🪄 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: 49ac35ae-0fc3-4b6d-b542-d765b92416af
📒 Files selected for processing (25)
.changeset/mosaic-typography-stylex.md.claude/skills/clerk-monorepo/SKILL.mdAGENTS.mdpackages/swingset/CLAUDE.mdpackages/swingset/src/components/PropTable.tsxpackages/swingset/src/lib/types.tspackages/swingset/src/stories/button.stories.tsxpackages/swingset/src/stories/heading.stories.tsxpackages/swingset/src/stories/text.stories.tsxpackages/ui/src/mosaic/components/button/button.styles.tspackages/ui/src/mosaic/components/heading.tsxpackages/ui/src/mosaic/components/heading/heading.styles.tspackages/ui/src/mosaic/components/heading/heading.test.tsxpackages/ui/src/mosaic/components/heading/heading.tsxpackages/ui/src/mosaic/components/heading/index.tspackages/ui/src/mosaic/components/text.tsxpackages/ui/src/mosaic/components/text/index.tspackages/ui/src/mosaic/components/text/text.test.tsxpackages/ui/src/mosaic/components/text/text.tsxpackages/ui/src/mosaic/components/typography.styles.tspackages/ui/src/mosaic/organization/organization-profile-domains-section.view.tsxpackages/ui/src/mosaic/organization/organization-profile-members-panel.view.tsxpackages/ui/src/mosaic/styles/index.tspackages/ui/src/mosaic/tokens.stylex.tspackages/ui/tsdown.mosaic.config.mts
🔗 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)
💤 Files with no reviewable changes (2)
- packages/ui/src/mosaic/components/heading.tsx
- packages/ui/src/mosaic/components/text.tsx
| --- | ||
| --- |
There was a problem hiding this comment.
📐 Maintainability & Code Quality | 🟠 Major | ⚡ Quick win
Add a non-empty changeset for the Mosaic package change.
This suppresses release metadata despite changes to @clerk/ui component behavior and customization. Add the appropriate package bump and a user-facing summary; reserve empty changesets for tooling-only work. As per coding guidelines, “use pnpm changeset for package changes” and use an empty changeset only when there is no user-facing impact.
🤖 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-typography-stylex.md around lines 1 - 2, Replace the empty
changeset frontmatter with a non-empty changeset for the Mosaic package,
specifying the appropriate version bump for the affected package and adding a
concise user-facing summary of the `@clerk/ui` component behavior and
customization changes.
Source: Coding guidelines
| it('renders a different element through the render prop, keeping the slot props', () => { | ||
| render(<Heading render={p => <h3 {...p} />}>Title</Heading>); | ||
| const heading = screen.getByRole('heading', { level: 3 }); | ||
| expect(heading).toHaveClass('cl-heading'); | ||
| expect(heading).toHaveAttribute('data-size', 'base'); | ||
| }); |
There was a problem hiding this comment.
🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win
Cover the React-element render branch.
HeadingProps accepts both a callback and a ReactElement, but this only tests the callback form. Add a <Heading render={<h3 />}>…</Heading> case that verifies children and merged slot attributes reach the cloned element. As per coding guidelines, “Unit tests are required for all new functionality.”
🤖 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 `@packages/ui/src/mosaic/components/heading/heading.test.tsx` around lines 39 -
44, Add a test alongside the existing callback case in the heading test suite
that passes a React element directly to Heading’s render prop, then verify the
cloned element receives the heading children and merged slot attributes such as
the cl-heading class and data-size value. Use the existing Heading test patterns
and keep the callback coverage unchanged.
Source: Coding guidelines
| * Themeable body copy. Renders a `<p>` by default, forwards refs, and supports | ||
| * `size` and `intent` variants. Pass `render` for inline copy (`<span>`). | ||
| */ | ||
| export const Text = React.forwardRef<HTMLParagraphElement, TextProps>(function MosaicText(rawProps, ref) { | ||
| const { size = 'sm', intent = 'primary', render, className, style, ...rest } = useContextProps(rawProps, TextContext); |
There was a problem hiding this comment.
🎯 Functional Correctness | 🟠 Major | 🏗️ Heavy lift
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
set -euo pipefail
printf '\n## file\n'
sed -n '1,220p' packages/ui/src/mosaic/components/text/text.tsx
printf '\n## nearby type declarations\n'
rg -n "type TextProps|interface TextProps|render" packages/ui/src/mosaic/components/text -SRepository: clerk/javascript
Length of output: 3795
🏁 Script executed:
#!/bin/bash
set -euo pipefail
printf '\n## usages/tests\n'
rg -n "Text[^\\n]*ref|<Text|TextContext|render:" packages/ui/src -S
printf '\n## text-related tests\n'
fd -a "text.*(test|spec).*" packages/ui/srcRepository: clerk/javascript
Length of output: 39734
🏁 Script executed:
#!/bin/bash
set -euo pipefail
printf '\n## related primitives\n'
rg -n "forwardRef<.*HTMLParagraphElement|makeCustomizable|createVariants|elementDescriptor|render\\s*\\?" packages/ui/src/mosaic packages/ui/src -SRepository: clerk/javascript
Length of output: 50373
🏁 Script executed:
#!/bin/bash
set -euo pipefail
sed -n '1,260p' packages/ui/src/mosaic/components/text/text.tsxRepository: clerk/javascript
Length of output: 1927
🏁 Script executed:
#!/bin/bash
set -euo pipefail
rg -n "function useRender|const useRender|export .*useRender|useRender\\(" . -g '!**/dist/**' -g '!**/build/**' -g '!**/node_modules/**' -S | head -n 80Repository: clerk/javascript
Length of output: 7491
🏁 Script executed:
#!/bin/bash
set -euo pipefail
sed -n '1,220p' packages/ui/src/mosaic/components/text/text.test.tsxRepository: clerk/javascript
Length of output: 2478
🏁 Script executed:
#!/bin/bash
set -euo pipefail
sed -n '1,280p' packages/headless/src/utils/use-render.tsxRepository: clerk/javascript
Length of output: 9028
🏁 Script executed:
#!/bin/bash
set -euo pipefail
sed -n '1,260p' packages/headless/src/utils/use-render.test.tsxRepository: clerk/javascript
Length of output: 6974
🏁 Script executed:
#!/bin/bash
set -euo pipefail
sed -n '1,220p' packages/ui/src/mosaic/components/heading/heading.tsxRepository: clerk/javascript
Length of output: 2040
🏁 Script executed:
#!/bin/bash
set -euo pipefail
rg -n "ref|render prop|span" packages/ui/src/mosaic/components/text/text.test.tsx packages/headless/src/utils/use-render.test.tsx -SRepository: clerk/javascript
Length of output: 3922
Make Text polymorphic when render swaps the host element.
render can return a <span>, but Text is still exposed as Ref<HTMLParagraphElement>, so callers get a paragraph ref type for a span at runtime. Either make the component generic over the rendered element or restrict render to preserve <p>. Add a regression for the override/ref path.
🤖 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 `@packages/ui/src/mosaic/components/text/text.tsx` around lines 20 - 24, Update
Text and its ref typing so the component’s exposed ref element matches the host
selected by render, using the project’s established polymorphic component
pattern; alternatively restrict render to paragraph-compatible output if
polymorphism is unsupported. Preserve the default <p> behavior and add a
regression covering a render override to <span> with the corresponding ref type.
Source: Coding guidelines
1 participant
Description
Moves
HeadingandTextoff the Emotion slot-recipe engine onto StyleX, following theButtonpilot. Same public contract as Button: a stable.cl-heading/.cl-textclass plusdata-size/data-intentattributes, with the consumer'sclassName/stylemerged last so they win over the component's own atoms.Shared typography atoms. Both components render the same size and intent axes, so those atoms live once in
components/typography.styles.ts. Heading composes a weight on top; Text adds nothing.One type scale instead of per-component tokens. The six
--cl-text-label-*tokens are gone.label/label-smwere byte-identical to the newsm/xssteps, so everything that renders text now sizes against a single named scale (xs→2xl), Button included.Font weights are their own token group. Weight and size vary independently (a
smText can be medium; a2xlHeading is semibold), so they don't belong on the step scale:Behavior preserved.
render,HeadingContext/TextContext(Card setsintent: 'mutedForeground'), and ref forwarding are unchanged. Therenderpath stays gated behinduseRender, with a JSX fallback rather thanReact.createElement, so an Emotion parent'scssprop still gets processed instead of leaking to the DOM.Call sites. The
sxprop is dropped as it was for Button; the three call sites that used it move tostyle.Also in here
tsdown.mosaic.config.mtsmarks@clerk/headlessexternal. The bundled dts emit dropped thetypemodifier onimport { RenderProp }and failed the build; that entry only exists to extractstyles.css, so there's nothing to gain from inlining the primitives.<PropTable>appended ansxrow unconditionally. StyleX components have nosx, someta.styleEnginenow selects the escape-hatch rows (sxfor Emotion,className+stylefor StyleX). Button, Heading, and Text declare'stylex'.button.stories.tsxalready does.Checklist
pnpm testruns as expected.pnpm buildruns as expected.Type of change