feat(mosaic): add Switcher and make UserButton list accounts only

.changeset/mosaic-switcher.md

@@ -0,0 +1,16 @@
+---
+'@clerk/mosaic': minor
+---
+
+**Breaking:** Add `Switcher`, the account and organization menu, and make `UserButton` list accounts only. `Switcher` takes `mode`: `'combined'` (the default) lists accounts and organizations, `'user'` lists accounts only, and `'organization'` lists organizations. `<UserButton />` is now `<Switcher mode='user' />` and `<OrganizationSwitcher />` is `<Switcher mode='organization' />`. Each mode takes only its own props, so TypeScript flags organization options on `UserButton` and `triggerVariant` outside `combined`. A `mode` chosen at runtime takes only the props every mode shares.
+
+| Before                                                                                                          | After                                                   |
+| --------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------- |
+| `<UserButton />` (accounts and organizations)                                                                   | `<Switcher />`                                          |
+| `<UserButton combined={false} />`                                                                               | `<UserButton />` or `<Switcher mode='user' />`          |
+| `<UserButton triggerVariant='condensed' />`                                                                     | `<Switcher triggerVariant='condensed' />`               |
+| Organization props on `UserButton` (`hidePersonal`, `afterSelectOrganizationUrl`, `createOrganizationUrl`, ...) | The same props on `Switcher`                            |
+| `UserButtonProps` (combined menu)                                                                               | `CombinedSwitcherProps`                                 |
+| `UserButtonProps` (user-only menu)                                                                              | `UserButtonProps`, which now takes account options only |
+
+Find usages with `git grep -n "UserButton"`.

integration/templates/next-app-router-mosaic/src/app/custom/page.tsx

@@ -1,6 +1,6 @@
 'use client';
 
-import { MosaicProvider, UserButton } from '@clerk/mosaic';
+import { Switcher, MosaicProvider } from '@clerk/mosaic';
 
 export default function Page() {
   return (
@@ -12,7 +12,7 @@ export default function Page() {
         },
       }}
     >
-      <UserButton customMenuItems={[{ id: 'custom-link', label: 'Custom link', href: '/custom/link-target' }]} />
+      <Switcher customMenuItems={[{ id: 'custom-link', label: 'Custom link', href: '/custom/link-target' }]} />
     </MosaicProvider>
   );
 }

integration/templates/next-app-router-mosaic/src/app/mosaic-user-button.tsx

@@ -1,11 +1,11 @@
 'use client';
 
-import { MosaicProvider, UserButton } from '@clerk/mosaic';
+import { Switcher, MosaicProvider } from '@clerk/mosaic';
 
 export function MosaicUserButton() {
   return (
     <MosaicProvider experimental={{ newProfiles: true }}>
-      <UserButton />
+      <Switcher />
     </MosaicProvider>
   );
 }

packages/mosaic/.claude/skills/verify-mosaic/SKILL.md

@@ -61,7 +61,7 @@ $ CS ab eval '(() => document.querySelector("[role=dialog]").dataset.variant)()'
 
 Conventions:
 
-- Routes are `/<group-slug>/<component-slug>`: `/components/button`, `/components/dialog`, `/user-button/user-button`, `/misc/organization-switcher`. The slug is the story's `meta.group` and `meta.title` run through `packages/swingset/src/lib/slug.ts`. A wrong path still returns 200 with `No docs found`, so check the level-1 heading. Read the paths of the expanded sidebar groups with `CS ab eval '(() => [...document.querySelectorAll("[data-sidebar] a")].map(a => a.getAttribute("href")))()'`, or click the link with `CS ab click 'a[href="/user-button/user-button"]'`.
+- Routes are `/<group-slug>/<component-slug>`: `/components/button`, `/components/dialog`, `/switcher/switcher`, `/misc/organization-switcher`. The slug is the story's `meta.group` and `meta.title` run through `packages/swingset/src/lib/slug.ts`. A wrong path still returns 200 with `No docs found`, so check the level-1 heading. Read the paths of the expanded sidebar groups with `CS ab eval '(() => [...document.querySelectorAll("[data-sidebar] a")].map(a => a.getAttribute("href")))()'`, or click the link with `CS ab click 'a[href="/switcher/switcher"]'`.
 - Prefer role and accessible name (`find role button --name …`). When `find` cannot resolve a name, as with the header switches, take `snapshot -i` and use the `@ref`. Refs change after every navigation and every re-render, so take a new snapshot first.
 - Mosaic parts carry their identity in the DOM: a `.cl-<slot>` class plus `data-<axis>` attributes (`data-variant`, `data-size`, `data-color`, `data-open`). Assert on those, not on computed colours or class hashes. `data-style-src` lists the StyleX source lines that styled the element.
 - Wrap every `eval` body in an IIFE. The page keeps `const`s between `eval` calls, and a second `const b` throws.

packages/mosaic/.claude/skills/verify-mosaic/notes.md

@@ -26,7 +26,7 @@ Prove it looks right in every state you touched.
 
 Prove it works the way a user would test it: do the task end to end and check the result on the page.
 
-- Pages are under the flow's group: `/user-button/...`, `/user-profile/...`, `/organization-profile/...`, `/misc/...`, `/blocks/...`. A section page such as `/user-profile/user-profile-email-section` has the default story first, then error and pending stories below it.
+- Pages are under the flow's group: `/switcher/...`, `/user-profile/...`, `/organization-profile/...`, `/misc/...`, `/blocks/...`. A section page such as `/user-profile/user-profile-email-section` has the default story first, then error and pending stories below it.
 - The data is fixtures, and they keep state on the page. On the email section, `Add email` → type an address → `Continue` → type `424242` adds `Manage <address>` to the list.
 - Drive the default story through the change, then the error story for the failure path. Prove the end state with a snapshot, not a screenshot alone.
 - Turn on Chaos to check long and multi-script data.

packages/mosaic/README.md

@@ -58,13 +58,13 @@ Import the stylesheet and render Mosaic components beneath the SDK `ClerkProvide
 
 ```tsx
 import { ClerkProvider } from '@clerk/react';
-import { UserButton } from '@clerk/mosaic';
+import { Switcher } from '@clerk/mosaic';
 import '@clerk/mosaic/styles.css';
 
 export function App({ children }) {
   return (
     <ClerkProvider publishableKey={process.env.CLERK_PUBLISHABLE_KEY}>
-      <UserButton />
+      <Switcher />
       {children}
     </ClerkProvider>
   );

packages/mosaic/docs/documenting-components.md

@@ -2,7 +2,7 @@
 
 Read this when you add or change a Swingset page for a Mosaic component, block, hook or style: a `<name>.stories.tsx` or `<name>.mdx` in `packages/swingset/src/stories/`. It covers what to write once the page is wired; how the app works is in `packages/swingset/CLAUDE.md`, and the registry, `docModules` and redirect wiring is in `packages/swingset/README.md`.
 
-Worked examples: `button.stories.tsx` and `button.mdx` (archetype A, simple), `popover.component.mdx` (A, compound), `accordion.mdx` (B), `user-button.mdx` (C).
+Worked examples: `button.stories.tsx` and `button.mdx` (archetype A, simple), `popover.component.mdx` (A, compound), `accordion.mdx` (B), `switcher.mdx` (C).
 
 ## Rules
 
@@ -19,7 +19,7 @@ Worked examples: `button.stories.tsx` and `button.mdx` (archetype A, simple), `p
 
 | Group                  | What lives here                                                                                                                      | Archetype   |
 | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------ | ----------- |
-| `User Button`          | Composed flow UI (e.g. `UserButton`)                                                                                                 | C           |
+| `Switcher`             | Composed flow UI (e.g. `Switcher`)                                                                                                   | C           |
 | `User Profile`         | Composed flow UI (e.g. `UserProfileProfilePanel`)                                                                                    | C           |
 | `Organization Profile` | Composed flow UI (e.g. `OrganizationProfileGeneralPanel`)                                                                            | C           |
 | `Misc`                 | Standalone composed components (e.g. `OrganizationSwitcher`, `Waitlist`)                                                             | C           |
@@ -31,7 +31,7 @@ Worked examples: `button.stories.tsx` and `button.mdx` (archetype A, simple), `p
 | `Hooks`                | Headless hooks (`useForm`)                                                                                                           | B (adapted) |
 | `Localization`         | The `localization` prop on `MosaicProvider`: catalogs, overrides, locale, and the message helpers                                    | B (adapted) |
 
-`User Button` / `User Profile` / `Organization Profile` / `Misc` / `Blocks` → `Components` → `Primitives` runs high-level-composition → low-level-primitive. Composed layers are documented as compositions of lower layers (archetype C); leaf layers (Components, Primitives) get full prop/knob docs (archetypes A and B).
+`Switcher` / `User Profile` / `Organization Profile` / `Misc` / `Blocks` → `Components` → `Primitives` runs high-level-composition → low-level-primitive. Composed layers are documented as compositions of lower layers (archetype C); leaf layers (Components, Primitives) get full prop/knob docs (archetypes A and B).
 
 `Styles` and `Hooks` are the non-component layers: there is no element to knob, so they follow
 archetype B's shape (Example → Usage → Parts → Styling) with `Props` replaced by whatever the export
@@ -205,14 +205,14 @@ The story is `meta` (no `styles`) plus a single `Default` export that renders th
 
 Every props table has a **Default** column, and the `Type` stays a plain union, never with the default inlined. The auto `<PropTable>` fills it from `meta.styles._defaultVariants`; hand-written tables (`Prop | Type | Default | Description`) fill it by hand. Name the default member (`'bottom-start'`), use `—` when there is none and append `(required)` for a required prop, and state a behavioral default in words (`inherits Root`).
 
-## Archetype C — composed layer (`User Button`, `User Profile`, `Organization Profile`, `Misc`, `Blocks`, `Authentication`)
+## Archetype C — composed layer (`Switcher`, `User Profile`, `Organization Profile`, `Misc`, `Blocks`, `Authentication`)
 
 These compose lower layers, so the docs lead with the composition rather than knobs. Required MDX:
 
 ```mdx
-import * as SwitcherStories from './user-button.stories';
+import * as SwitcherStories from './switcher.stories';
 
-# UserButton
+# Switcher
 
 <!-- One paragraph: what state this owns and which lower-layer pieces it wires together. -->
 

packages/mosaic/docs/testing.md

@@ -2,7 +2,7 @@
 
 Read this when you write, move or review a test in `packages/mosaic` (`*.test.ts(x)`, `*.feature.test.tsx`, `*.browser.test.tsx`, `*.visual.test.tsx`, `*.test-d.ts`, or anything under `__tests__/`). It covers which tier a behavior belongs in, where test files go, the feature-test toolkit and screenshot tests; what a feature test should assert for each layer is in the Testing section of [Models](models.md#testing), [Controllers](controllers.md#testing) and [Views](views.md#testing).
 
-Worked example: `src/features/user-button/__tests__/user-button.feature.test.tsx`.
+Worked example: `src/features/switcher/__tests__/switcher.feature.test.tsx`.
 
 ## Rules
 
@@ -64,7 +64,7 @@ it('makes the selected organization active and closes', async () => {
     client: fapiClient([fapiSession({ id: 'sess_1', user: alice, last_active_organization_id: 'org_1' })]),
     memberships: [fapiMembership(acme), fapiMembership(other)],
   });
-  await renderWithClerk(<UserButton />);
+  await renderWithClerk(<Switcher />);
   const user = userEvent.setup();
 
   await user.click(screen.getByRole('button', { name: /Open account menu/ }));

packages/mosaic/src/features/organization-switcher/__tests__/organization-switcher.feature.test.tsx

@@ -18,7 +18,7 @@ import {
 } from '../../../__tests__/feature/fapi';
 import { renderWithClerk } from '../../../__tests__/feature/render';
 import type { MosaicProfile } from '../../profile-pages/use-mosaic-profile';
-import type { OrganizationSwitcherProps } from '../organization-switcher';
+import type { OrganizationSwitcherProps } from '../../switcher/switcher';
 import { OrganizationSwitcher } from '../organization-switcher';
 
 beforeAll(async () => {

packages/mosaic/src/features/organization-switcher/organization-switcher.tsx

@@ -2,24 +2,15 @@
 
 import type { ReactElement } from 'react';
 
-import type { SwitcherProps } from '../switcher/switcher';
+import type { OrganizationSwitcherProps } from '../switcher/switcher';
 import { Switcher } from '../switcher/switcher';
-import type { OrganizationSwitcherModelOptions } from '../switcher/switcher.model';
-import type { SwitcherMenuProps } from '../switcher/switcher.types';
-import type { SwitcherTriggerProps } from '../switcher/switcher.view';
-
-/** Everything `<OrganizationSwitcher />` takes: trigger content, and the app's own menu rows. */
-export type OrganizationSwitcherProps = OrganizationSwitcherModelOptions &
-  SwitcherTriggerProps &
-  SwitcherMenuProps &
-  Pick<SwitcherProps, 'fallback'>;
 
 /**
  * The active organization's avatar, and the menu behind it: switch organization or back to the
  * personal account, join a suggested or invited one, create one, invite members, and open the
  * organization's settings. It reads the active session and organization from Clerk, so it takes no
  * data. It renders `fallback` until Clerk answers, and nothing at all when nobody is signed in or the
- * instance has organizations turned off.
+ * instance has organizations turned off. It is `<Switcher mode='organization' />`.
  *
  * @example
  * ```tsx

packages/mosaic/src/features/user-button/__tests__/user-button-avatar.feature.test.tsx → packages/mosaic/src/features/switcher/__tests__/switcher-avatar.feature.test.tsx

@@ -13,7 +13,7 @@ import {
   fapiUser,
 } from '../../../__tests__/feature/fapi';
 import { renderWithClerk } from '../../../__tests__/feature/render';
-import { UserButton } from '../user-button';
+import { Switcher } from '../switcher';
 
 const GAP = 4;
 
@@ -27,7 +27,7 @@ const alice = fapiUser({
   organization_memberships: memberships,
 });
 
-describe('UserButton badged avatar customization', () => {
+describe('Switcher badged avatar customization', () => {
   it('keeps the gap around a resized badge in the trigger', async () => {
     customize(`.cl-user-button-avatar { --cl-avatar-badge-size: 24px; --cl-avatar-badge-gap: ${GAP}px; }`);
     await renderSignedIn();
@@ -74,7 +74,7 @@ async function renderSignedIn() {
     client: fapiClient([fapiSession({ id: 'sess_1', user: alice, last_active_organization_id: acme.id })]),
     memberships,
   });
-  await renderWithClerk(<UserButton />);
+  await renderWithClerk(<Switcher />);
 }
 
 async function triggerAvatar(): Promise<HTMLElement> {