feat(ui): add UserButton controller

[alexcarpenter]

Summary

Stacked on #9184 (the presentational view). Adds the controller layer that connects UserButton to live Clerk data, plus its tests (TDD).

• useUserButtonController() (user-button.controller.tsx) — a plain hook (no machine) returning a 'loading' | 'hidden' | 'ready' discriminated union. When ready it carries UserButtonData & UserButtonCallbacks 1:1 with the contract in user-button.view.tsx.
• UserButton (user-button.tsx) — the connected container. Owns popover open state and close-on-success (Option A: wraps each one-shot callback with .finally(close); manage/create navigations do not auto-close).
• Renamed the view's all-in-one export UserButton → UserButtonView, reserving the bare UserButton for the connected container. Updated the swingset story + mdx.

Data mapping (Clerk → contract)

• activeSession from useUser() + useSession(), name fallback first+last > username > email.
• activeOrganizationId from useOrganization() (null = personal).
• memberships/suggestions/invitations from useOrganizationList(organizationListParams) (reused from the legacy switcher).
• hasOrganizations from userMemberships.count (never array length).
• additionalSessions from clerk.client.signedInSessions, excluding the active user's session.
• membershipRequestCount only on the active-org row and only with org:sys_memberships:manage.
• planLabel / upgradeable deferred (undefined).

Actions (navigation mode)

setActive for select/switch, signOut for sign-out, router.navigate(clerk.build*Url()) for manage/create, .accept() + revalidate() for invitations/suggestions.

Tests

12 controller tests (__tests__/user-button.controller.test.tsx) using the mosaic vi.mock('@clerk/shared/react') harness (copied from organization-profile-delete-section.controller.test.tsx). Written failing first, then implemented to green.

Notes / deviations from the handoff

Two points where the handoff wasn't directly implementable; resolved as follows:

1. onSelectOrganization navigation. The handoff referenced displayConfig.afterSelectOrganizationUrl, but that field only exists as a component prop, not on the environment. Per decision, navigation goes through setActive({ organization, redirectUrl }) (matching the legacy switcher), using displayConfig.afterCreateOrganizationUrl as the redirect. Fully type-safe, no cast.
2. Container loading render. The handoff described loading → <UserButtonView status="loading" />, but the view requires activeSession (which is only present when ready) and the view was out of scope to restructure. The container renders null while loading/hidden and the view only when ready. The controller still exposes status: 'loading' for future use.

Checklist

• turbo test --filter @clerk/ui (12 new + full suite: 2666 passing)
• type-check clean
• eslint clean (0 errors)
• Empty changeset (feature ships under base PR feat(ui): add UserButton view component #9184 changeset)

[vercel]

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

Project	Deployment	Actions	Updated (UTC)
clerk-js-sandbox	Ready	Preview	Aug 3, 2026 8:11pm
swingset	Ready	Preview	Aug 3, 2026 8:11pm

[changeset-bot]

⚠️ No Changeset found

Latest commit: 6ff2457

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

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

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

Review profile: CHILL

Plan: Pro Plus

Run ID: 7a04aed4-0d7c-4b2c-a512-143674d4ca8d

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

---

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