feat(ui): add UserButton view component - #9184
Open
alexcarpenter wants to merge 17 commits into
Open
Conversation
🦋 Changeset detectedLatest commit: 36f9c06 The changes in this PR will be included in the next version bump. This PR includes changesets to release 3 packages
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.
|
Contributor
|
Note Reviews pausedIt looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the Use the following commands to manage reviews:
Use the checkboxes below for quick actions:
📝 WalkthroughWalkthroughAdds a client-side Mosaic Estimated code review effort: 4 (Complex) | ~45 minutes Possibly related PRs
🚥 Pre-merge checks | ✅ 4 | ❌ 1❌ Failed checks (1 warning)
✅ Passed checks (4 passed)
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. Comment |
@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: |
Contributor
API Changes Report
Summary
No API Changes DetectedAll packages have stable APIs with no detected changes. Report generated by Break Check Last ran on |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
Actionable comments posted: 7
🤖 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 `@packages/swingset/src/lib/registry.ts`:
- Around line 3-8: Update the manually constructed AccountButton story module to
preserve the story’s raw __source export. Import __source from
account-button.stories and include it in the module object alongside
AccountButtonDefault, AccountButtonMultipleAccounts, AccountButtonPersonal, and
accountButtonMeta; apply the same change to the corresponding second
construction.
In `@packages/swingset/src/stories/account-button.mdx`:
- Around line 3-21: Restructure the AccountButton MDX documentation into
Archetype C format: replace the current descriptive sections with one short
paragraph covering owned state and the wired lower-layer pieces, then provide
exactly one Story. Add a composition array to that Story listing each direct
dependency, including the headless popover primitive and slot recipes, and
remove the current multi-story layout.
In `@packages/swingset/src/stories/account-button.stories.tsx`:
- Around line 10-14: Update the AccountButton story metadata to assign
accountButtonRecipe to meta.styles. In each story function, cast the knobs
Record<string, unknown> through knobsAsProps and spread the resulting props into
AccountButton so playground values are applied.
In `@packages/ui/src/mosaic/components/account-button.view.tsx`:
- Around line 446-808: Split the presentational leaves and sections from
account-button.view.tsx into focused React modules, extracting symbols such as
Avatar, Row, Header, WorkspaceList, AccountsSection, and Footer while preserving
their current behavior and context usage. Keep the public compound component
composition and exports in account-button.view.tsx, and update imports as needed
so the file remains focused and within the project’s preferred component size.
- Around line 21-85: Add comprehensive customer-facing JSDoc to the exported
AccountButtonAccount, AccountButtonMembership, AccountButtonSuggestion,
AccountButtonInvitation, AccountButtonData, AccountButtonCallbacks, and props
contracts, documenting field semantics including onUpgrade. Add explicit
React.JSX.Element return types to all four exported AccountButton components,
then request Docs-team review for the generated public API documentation.
- Around line 57-68: Remove the inert status field from AccountButtonData for
v1, since the current loading value still requires and renders ready-state data.
Update AccountButton consumers, including the account-button view, to rely on
the existing ready-state shape without status checks; only retain status if you
introduce a genuine discriminated union with a separate loading rendering path.
- Around line 488-535: Update the selection control rendered by Row to expose
its active state through the appropriate aria-current attribute, using the
active prop’s value. Apply the attribute to the interactive button and the
non-interactive div consistently, while leaving the visual check icon behavior
unchanged.
🪄 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), Repository UI (inherited)
Review profile: CHILL
Plan: Pro Plus
Run ID: 05507a88-c836-4e0f-b43f-e0d914595582
📒 Files selected for processing (8)
.changeset/account-button-switcher.mdpackages/swingset/src/components/DocsViewer.tsxpackages/swingset/src/lib/registry.tspackages/swingset/src/stories/account-button.mdxpackages/swingset/src/stories/account-button.stories.tsxpackages/ui/src/mosaic/components/account-button.view.tsxpackages/ui/src/mosaic/icons/registry.tsxpackages/ui/src/mosaic/primitives/popover.tsx
Comment on lines
+3
to
+8
| import { | ||
| Default as AccountButtonDefault, | ||
| meta as accountButtonMeta, | ||
| MultipleAccounts as AccountButtonMultipleAccounts, | ||
| Personal as AccountButtonPersonal, | ||
| } from '../stories/account-button.stories'; |
Contributor
There was a problem hiding this comment.
🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win
Preserve __source when constructing the story module.
The story exports its raw source, but this manually built module drops it, preventing AccountButton code footers from rendering.
Proposed fix
import {
+ __source as accountButtonSource,
Default as AccountButtonDefault,
meta as accountButtonMeta,
MultipleAccounts as AccountButtonMultipleAccounts,
Personal as AccountButtonPersonal,
} from '../stories/account-button.stories';
const accountButtonModule: StoryModule = {
meta: accountButtonMeta,
+ __source: accountButtonSource,
Default: AccountButtonDefault,As per path instructions, Components-layer stories export __source to enable code footers.
Also applies to: 130-135
🤖 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/swingset/src/lib/registry.ts` around lines 3 - 8, Update the
manually constructed AccountButton story module to preserve the story’s raw
__source export. Import __source from account-button.stories and include it in
the module object alongside AccountButtonDefault, AccountButtonMultipleAccounts,
AccountButtonPersonal, and accountButtonMeta; apply the same change to the
corresponding second construction.
Source: Path instructions
Comment on lines
+3
to
+21
| # AccountButton | ||
|
|
||
| The account & organization switcher that sits behind the user button. The active account sits at the | ||
| top with its organizations (including any **suggested** workspaces you can Join), and **additional | ||
| accounts** are listed below. Hovering the active account reveals **Sign out**; clicking any additional | ||
| account switches to it. **Settings / Members** open the combined profile modal, and the surface also | ||
| exposes **Add organization**, **Add account**, and **Sign out of all accounts**. | ||
|
|
||
| It is the styled Mosaic component composed from the headless `@clerk/headless` popover primitive plus | ||
| slot recipes, and inherits the primitive's open/close behavior, focus management, and ARIA wiring. This | ||
| first pass is presentational: the parts render from the props on `AccountButtonRoot` (mock data in the | ||
| examples). A `useAccountButtonController()` that reads live Clerk resources is a drop-in follow-up. | ||
|
|
||
| ## Example | ||
|
|
||
| <Story | ||
| name='Default' | ||
| storyModule={AccountButtonStories} | ||
| /> |
Contributor
There was a problem hiding this comment.
📐 Maintainability & Code Quality | 🟠 Major | 🏗️ Heavy lift
Use the Archetype C documentation structure.
Lead with one short paragraph describing owned state and wired lower-layer pieces, followed by one <Story> whose composition array names each direct dependency. The current multiple-story layout follows neither requirement.
As per path instructions, Archetype C MDX must use a single ownership/composition paragraph followed by one Story with a dependency composition array.
Also applies to: 68-89
🤖 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/swingset/src/stories/account-button.mdx` around lines 3 - 21,
Restructure the AccountButton MDX documentation into Archetype C format: replace
the current descriptive sections with one short paragraph covering owned state
and the wired lower-layer pieces, then provide exactly one Story. Add a
composition array to that Story listing each direct dependency, including the
headless popover primitive and slot recipes, and remove the current multi-story
layout.
Source: Path instructions
Comment on lines
+10
to
+14
| export const meta: StoryMeta = { | ||
| group: 'Components', | ||
| title: 'AccountButton', | ||
| source: 'packages/ui/src/mosaic/components/account-button.view.tsx', | ||
| }; |
Contributor
There was a problem hiding this comment.
🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win
Wire the stories into the playground knobs.
Set meta.styles to accountButtonRecipe, add the local knobsAsProps cast, and spread the resulting props into each AccountButton. The current stories discard every playground value.
As per path instructions, story functions must cast Record<string, unknown> through knobsAsProps, and Mosaic recipe metadata must be assigned to meta.styles.
Also applies to: 36-112
🤖 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/swingset/src/stories/account-button.stories.tsx` around lines 10 -
14, Update the AccountButton story metadata to assign accountButtonRecipe to
meta.styles. In each story function, cast the knobs Record<string, unknown>
through knobsAsProps and spread the resulting props into AccountButton so
playground values are applied.
Source: Path instructions
Comment on lines
+21
to
+85
| export interface AccountButtonAccount { | ||
| sessionId: string; | ||
| userId: string; | ||
| name: string; | ||
| email: string; | ||
| imageUrl?: string; | ||
| } | ||
|
|
||
| export interface AccountButtonMembership { | ||
| kind: 'membership'; | ||
| organizationId: string; | ||
| name: string; | ||
| imageUrl?: string; | ||
| membersCount?: number; | ||
| planLabel?: string; | ||
| upgradeable?: boolean; | ||
| membershipRequestCount?: number; | ||
| } | ||
|
|
||
| export interface AccountButtonSuggestion { | ||
| kind: 'suggestion'; | ||
| id: string; | ||
| organizationId: string; | ||
| name: string; | ||
| imageUrl?: string; | ||
| status: 'pending' | 'accepted'; | ||
| } | ||
|
|
||
| export interface AccountButtonInvitation { | ||
| kind: 'invitation'; | ||
| id: string; | ||
| organizationId: string; | ||
| organizationName: string; | ||
| imageUrl?: string; | ||
| } | ||
|
|
||
| export interface AccountButtonData { | ||
| status: 'loading' | 'ready'; | ||
| activeAccount: AccountButtonAccount; | ||
| /** `null` => the personal workspace is active. */ | ||
| activeOrganizationId: string | null; | ||
| /** Explicit; do not derive from `memberships.length`. */ | ||
| hasOrganizations: boolean; | ||
| memberships: AccountButtonMembership[]; | ||
| suggestions: AccountButtonSuggestion[]; | ||
| invitations: AccountButtonInvitation[]; | ||
| additionalAccounts: AccountButtonAccount[]; | ||
| } | ||
|
|
||
| /** All optional. An unhandled action hides (or de-activates) the affordance it drives. */ | ||
| export interface AccountButtonCallbacks { | ||
| onSelectOrganization?: (organizationId: string) => void; | ||
| onSelectPersonal?: () => void; | ||
| onAcceptSuggestion?: (suggestionId: string) => void; | ||
| onAcceptInvitation?: (invitationId: string) => void; | ||
| onSwitchAccount?: (sessionId: string) => void; | ||
| onSignOutSession?: (sessionId: string) => void; | ||
| onSignOutAll?: () => void; | ||
| onManageOrganization?: () => void; | ||
| onManageMembers?: () => void; | ||
| onManageAccount?: () => void; | ||
| onCreateOrganization?: () => void; | ||
| onAddAccount?: () => void; | ||
| onUpgrade?: () => void; | ||
| } |
Contributor
There was a problem hiding this comment.
📐 Maintainability & Code Quality | 🟠 Major | 🏗️ Heavy lift
Complete the public API documentation and return types.
The exported resource, callback, and props contracts—especially onUpgrade—lack customer-facing field semantics, while the four exported components have no explicit return types. Add comprehensive JSDoc and React.JSX.Element annotations, then request Docs-team review.
As per coding guidelines, all public APIs require comprehensive JSDoc and explicit return types. As per path instructions, public JSDoc under packages/** feeds generated Clerk Docs.
Also applies to: 812-839, 841-905
🤖 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/account-button.view.tsx` around lines 21 -
85, Add comprehensive customer-facing JSDoc to the exported
AccountButtonAccount, AccountButtonMembership, AccountButtonSuggestion,
AccountButtonInvitation, AccountButtonData, AccountButtonCallbacks, and props
contracts, documenting field semantics including onUpgrade. Add explicit
React.JSX.Element return types to all four exported AccountButton components,
then request Docs-team review for the generated public API documentation.
Sources: Coding guidelines, Path instructions
Comment on lines
+57
to
+68
| export interface AccountButtonData { | ||
| status: 'loading' | 'ready'; | ||
| activeAccount: AccountButtonAccount; | ||
| /** `null` => the personal workspace is active. */ | ||
| activeOrganizationId: string | null; | ||
| /** Explicit; do not derive from `memberships.length`. */ | ||
| hasOrganizations: boolean; | ||
| memberships: AccountButtonMembership[]; | ||
| suggestions: AccountButtonSuggestion[]; | ||
| invitations: AccountButtonInvitation[]; | ||
| additionalAccounts: AccountButtonAccount[]; | ||
| } |
Contributor
There was a problem hiding this comment.
🎯 Functional Correctness | 🟠 Major | ⚡ Quick win
Do not publish an inert status state.
status='loading' renders the complete ready UI and still requires every ready-state resource. Remove status for v1, or make AccountButtonData a real discriminated union with a loading rendering path; correcting this after release would constrain @clerk/ui compatibility.
As per coding guidelines, use discriminated unions for state management and keep packages/ui APIs backwards-compatible.
🤖 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/account-button.view.tsx` around lines 57 -
68, Remove the inert status field from AccountButtonData for v1, since the
current loading value still requires and renders ready-state data. Update
AccountButton consumers, including the account-button view, to rely on the
existing ready-state shape without status checks; only retain status if you
introduce a genuine discriminated union with a separate loading rendering path.
Source: Coding guidelines
Comment on lines
+488
to
+535
| function Row({ name, secondary, shape, imageUrl, onSelect, active, badge, trailing, hoverAction }: RowProps) { | ||
| const { item, select, name: nameSlot, secondary: secondarySlot } = useRecipe(accountButtonRecipe); | ||
| const inner = ( | ||
| <> | ||
| <Avatar | ||
| name={name} | ||
| imageUrl={imageUrl} | ||
| shape={shape} | ||
| size='md' | ||
| /> | ||
| <span css={{ display: 'flex', flexDirection: 'column', minWidth: 0, flex: 1 }}> | ||
| <span css={{ display: 'flex', alignItems: 'center', gap: '0.375rem', minWidth: 0 }}> | ||
| <span {...nameSlot}>{name}</span> | ||
| {badge} | ||
| </span> | ||
| {secondary ? <span {...secondarySlot}>{secondary}</span> : null} | ||
| </span> | ||
| </> | ||
| ); | ||
| return ( | ||
| <div {...item}> | ||
| {onSelect ? ( | ||
| <button | ||
| type='button' | ||
| onClick={onSelect} | ||
| {...select} | ||
| > | ||
| {inner} | ||
| </button> | ||
| ) : ( | ||
| <div | ||
| {...select} | ||
| style={{ cursor: 'default' }} | ||
| > | ||
| {inner} | ||
| </div> | ||
| )} | ||
| {active ? ( | ||
| <Icon | ||
| name='check' | ||
| size='sm' | ||
| sx={t => ({ color: t.color.cardForeground, flexShrink: 0 })} | ||
| /> | ||
| ) : null} | ||
| {trailing} | ||
| {hoverAction} | ||
| </div> | ||
| ); |
Contributor
There was a problem hiding this comment.
🔒 Security & Privacy | 🟡 Minor | ⚡ Quick win
Expose the active row to assistive technology.
The check icon is purely visual. Mark the selection control with aria-current so screen-reader users can identify the active account or organization.
Proposed fix
<button
type='button'
+ aria-current={active ? 'true' : undefined}
onClick={onSelect}
{...select}As per coding guidelines, React components must implement proper ARIA attributes.
🤖 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/account-button.view.tsx` around lines 488 -
535, Update the selection control rendered by Row to expose its active state
through the appropriate aria-current attribute, using the active prop’s value.
Apply the attribute to the interactive button and the non-interactive div
consistently, while leaving the visual check icon behavior unchanged.
Source: Coding guidelines
4 tasks
alexcarpenter
changed the title
This was referenced Jul 22, 2026
alexcarpenter
force-pushed
the
carp/account-button-switcher
branch
from
July 30, 2026 18:38
dfae67d to
ef35f2d
Compare
alexcarpenter
changed the title
alexcarpenter
force-pushed
the
carp/account-button-switcher
branch
from
July 31, 2026 13:32
ef35f2d to
8f7ffa2
Compare
…, Avatar, and Menu Replaces the 24-slot user-button recipe and the hand-rolled Row/Avatar leaves with the shared components. The trigger is now the avatar alone, and the per-account actions (Create organization, Manage account, Sign out) move into an Item.Actions menu on the account label row.
An xs row is a single line; a title plus a description only fits on md.
A menu rendered inside a popover has a floating parent node id, so keying nesting off that alone made it hover-open, place itself side-start, and swallow mouse clicks. Require a parent menu context too.
Portalled siblings share a container and stack by DOM order, so a menu opened from inside a popover already paints above it. The explicit z-index only defeated that and buried the menu.
The workspace list is grouped under its account's email, so the personal row no longer repeats there. Every account renders as that email row with a `•••` menu. Without organizations there is nothing to head, so other accounts become md rows you click to switch.
…element Escape now closes one level: the menu, leaving its parent popover or menu open. An outside press still dismisses the whole stack.
The trigger hardcoded a full radius, so a square workspace mark got a circular focus ring. It now takes the same radius token the avatar uses for that shape.
Popover.Trigger now carries the public .cl-popover-trigger class, so it can be targeted like the positioner and popup. A consumer className still merges rather than replacing it.
--cl-radius-inner/control/element/container become sm/md/lg/xl.
Nudges the popup along the alignment axis, the counterpart to sideOffset.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
New Mosaic
UserButton: account + org switcher (multi-session + org select/suggest/invite) behind a popover. Presentational view only; controller is follow-up.UserButtonRoot/Trigger/Popup+ all-in-oneUserButtonDeferred:
useUserButtonController(), pagination, real avatars.Note: added optional
onUpgrade(design shows Upgrade link); accent purple hardcoded (no token yet).