feat(ui): add AccountButton view component

.changeset/account-button-switcher.md

@@ -0,0 +1,5 @@
+---
+'@clerk/ui': minor
+---
+
+Add the `AccountButton` Mosaic component: an account and organization switcher that combines multi-session account switching with organization selection, suggestions, and invitations behind a single popover. Exposes the all-in-one `AccountButton` plus the composable `AccountButtonRoot`, `AccountButtonTrigger`, and `AccountButtonPopup` parts, and its slots are themeable via `appearance.elements`.

packages/swingset/src/components/DocsViewer.tsx

@@ -10,6 +10,9 @@ import { ViewSource } from './ViewSource';
 // MDX docs keyed by `group` slug → `component` slug. Group-aware so identically-named
 // entries (the headless `Dialog` primitive vs. the styled `Dialog` component) stay distinct.
 const docModules: Record<string, Record<string, React.ComponentType>> = {
+  account: {
+    'account-button': dynamic(() => import('../stories/account-button.mdx')),
+  },
   organization: {
     'organization-profile': dynamic(() => import('../stories/organization-profile.mdx')),
     'organization-profile-general-panel': dynamic(() => import('../stories/organization-profile-general-panel.mdx')),

packages/swingset/src/lib/registry.ts

@@ -1,5 +1,11 @@
 // Import stories explicitly to control order and avoid type casting through unknown.
 import { meta as accordionMeta } from '../stories/accordion.stories';
+import {
+  Default as AccountButtonDefault,
+  meta as accountButtonMeta,
+  MultipleAccounts as AccountButtonMultipleAccounts,
+  Personal as AccountButtonPersonal,
+} from '../stories/account-button.stories';
 import { meta as autocompleteMeta } from '../stories/autocomplete.stories';
 import { Disabled, meta as buttonMeta, Primary, Sizes } from '../stories/button.stories';
 import {
@@ -121,6 +127,13 @@ const inputModule: StoryModule = { meta: inputMeta, Default, Sizes: InputSizes,
 
 const dialogComponentModule: StoryModule = { meta: dialogComponentMeta, Default: DialogDefault };
 
+const accountButtonModule: StoryModule = {
+  meta: accountButtonMeta,
+  Default: AccountButtonDefault,
+  Personal: AccountButtonPersonal,
+  MultipleAccounts: AccountButtonMultipleAccounts,
+};
+
 const headingModule: StoryModule = {
   meta: headingMeta,
   Default: HeadingDefault,
@@ -159,6 +172,8 @@ const tooltipModule: StoryModule = { meta: tooltipMeta };
 const useDataTableModule: StoryModule = { meta: useDataTableMeta };
 
 export const registry: StoryModule[] = [
+  // Account
+  accountButtonModule,
   // Organization
   organizationProfileModule,
   organizationProfileGeneralPanelModule,

packages/swingset/src/stories/account-button.mdx

@@ -0,0 +1,115 @@
+import * as AccountButtonStories from './account-button.stories';
+
+# 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}
+/>
+
+## Usage
+
+The all-in-one `AccountButton` renders the trigger and popup from a single prop-driven call:
+
+```tsx
+import { AccountButton } from '@clerk/ui/mosaic/account/account-button.view';
+
+<AccountButton
+  status='ready'
+  activeAccount={{ sessionId: 'sess_1', userId: 'user_1', name: 'Preston Booth', email: 'preston@clerk.dev' }}
+  activeOrganizationId='org_clerk_app'
+  hasOrganizations
+  memberships={[
+    { kind: 'membership', organizationId: 'org_clerk_app', name: 'Clerk app', membersCount: 24, planLabel: 'Pro plan', upgradeable: true },
+    { kind: 'membership', organizationId: 'org_clerk_cloud', name: 'Clerk Cloud' },
+  ]}
+  suggestions={[{ kind: 'suggestion', id: 'sug_labs', organizationId: 'org_clerk_labs', name: 'Clerk Labs', status: 'pending' }]}
+  invitations={[]}
+  additionalAccounts={[{ sessionId: 'sess_2', userId: 'user_2', name: 'Preston Booth', email: 'acme@clerk.dev' }]}
+  onSelectOrganization={id => setActive({ organization: id })}
+  onSelectPersonal={() => setActive({ organization: null })}
+  onSwitchAccount={sessionId => setActive({ session: sessionId })}
+  onSignOutAll={() => signOut()}
+/>
+```
+
+For layouts that need to drop the popup into their own trigger, compose the parts directly. The data
+and callbacks live on `AccountButtonRoot` and are read from context by the leaves, so they take no props:
+
+```tsx
+import {
+  AccountButtonRoot,
+  AccountButtonTrigger,
+  AccountButtonPopup,
+} from '@clerk/ui/mosaic/account/account-button.view';
+
+<AccountButtonRoot {...data} {...callbacks}>
+  <AccountButtonTrigger />
+  <AccountButtonPopup />
+</AccountButtonRoot>
+```
+
+The exports are flat (not `AccountButton.Trigger`) so each part can declare its own `'use client'`
+boundary without forcing the consumer's file to become a client component.
+
+## States & scenarios
+
+### Personal (no organizations)
+
+When the active account has no organizations, the header collapses to a personal layout —
+**Manage account / Sign out** — and the organization list is omitted. The trigger still shows the
+account avatar and name.
+
+<Story
+  name='Personal'
+  storyModule={AccountButtonStories}
+/>
+
+### Personal & workspace
+
+One account has workspaces (organizations); an additional account is a personal account (no orgs).
+Switching to it flips the surface to the personal layout.
+
+<Story
+  name='MultipleAccounts'
+  storyModule={AccountButtonStories}
+/>
+
+## Parts
+
+| Part                   | Description                                                                  |
+| ---------------------- | ---------------------------------------------------------------------------- |
+| `AccountButtonRoot`    | Owns the data + callbacks and forwards popover open state to `Popover.Root`. |
+| `AccountButtonTrigger` | The sidebar trigger: active workspace avatar, name, plan badge, selector.    |
+| `AccountButtonPopup`   | The popover surface: header, workspace list, additional accounts, footer.    |
+
+## Styling
+
+The component is themed with a Mosaic slot recipe (`accountButtonRecipe`). Override any slot through
+`appearance.elements` — e.g. `{ 'account-button-popup': { borderRadius: 24 } }`.
+
+| Slot                           | Description                                             |
+| ------------------------------ | ------------------------------------------------------- |
+| `account-button-trigger`       | The trigger button                                      |
+| `account-button-popup`         | The popover surface                                     |
+| `account-button-header`        | Active workspace header                                 |
+| `account-button-action`        | Header action buttons (Settings / Members)              |
+| `account-button-group`         | A divided section (workspace list, additional accounts) |
+| `account-button-item`          | A selectable workspace / account row                    |
+| `account-button-avatar`        | Org (square) / account (circle) avatar                  |
+| `account-button-inline-button` | Row actions (Join / Accept)                             |
+| `account-button-hover-action`  | The hover-revealed Sign out on the active account       |
+| `account-button-footer`        | Sign out of all accounts + branding                     |

packages/swingset/src/stories/account-button.stories.tsx

@@ -0,0 +1,113 @@
+/** @jsxImportSource @emotion/react */
+import { AccountButton, type AccountButtonProps } from '@clerk/ui/mosaic/account/account-button.view';
+
+import type { StoryMeta } from '@/lib/types';
+
+// Exposes this file's own source (via the `?raw` webpack rule) so each `<Story>` example
+// renders a code footer with its function's source. See `StoryModule.__source`.
+export { default as __source } from './account-button.stories?raw';
+
+export const meta: StoryMeta = {
+  group: 'Account',
+  title: 'AccountButton',
+  source: 'packages/ui/src/mosaic/account/account-button.view.tsx',
+};
+
+// The view is presentational, so the fixtures drive every state. All callbacks are wired as
+// no-ops purely so each affordance renders (an unhandled action hides its control).
+const handlers = {
+  onSelectOrganization: () => {},
+  onSelectPersonal: () => {},
+  onAcceptSuggestion: () => {},
+  onAcceptInvitation: () => {},
+  onSwitchAccount: () => {},
+  onSignOutSession: () => {},
+  onSignOutAll: () => {},
+  onManageOrganization: () => {},
+  onManageMembers: () => {},
+  onManageAccount: () => {},
+  onCreateOrganization: () => {},
+  onAddAccount: () => {},
+  onUpgrade: () => {},
+} satisfies Partial<AccountButtonProps>;
+
+const preston = { sessionId: 'sess_1', userId: 'user_1', name: 'Preston Booth', email: 'preston@clerk.dev' };
+
+export function Default(_args: Record<string, unknown>) {
+  return (
+    <AccountButton
+      {...handlers}
+      status='ready'
+      activeAccount={preston}
+      activeOrganizationId='org_clerk_app'
+      hasOrganizations
+      memberships={[
+        {
+          kind: 'membership',
+          organizationId: 'org_clerk_app',
+          name: 'Clerk app',
+          membersCount: 24,
+          planLabel: 'Pro plan',
+          upgradeable: true,
+        },
+        { kind: 'membership', organizationId: 'org_clerk_cloud', name: 'Clerk Cloud' },
+      ]}
+      suggestions={[
+        { kind: 'suggestion', id: 'sug_labs', organizationId: 'org_clerk_labs', name: 'Clerk Labs', status: 'pending' },
+      ]}
+      invitations={[]}
+      additionalAccounts={[{ sessionId: 'sess_2', userId: 'user_2', name: 'Preston Booth', email: 'acme@clerk.dev' }]}
+    />
+  );
+}
+
+export function Personal(_args: Record<string, unknown>) {
+  return (
+    <AccountButton
+      {...handlers}
+      status='ready'
+      activeAccount={{
+        sessionId: 'sess_cam',
+        userId: 'user_cam',
+        name: 'Cameron Walker',
+        email: 'cameron.walker@gmail.com',
+      }}
+      activeOrganizationId={null}
+      hasOrganizations={false}
+      memberships={[]}
+      suggestions={[]}
+      invitations={[]}
+      additionalAccounts={[
+        { sessionId: 'sess_js', userId: 'user_js', name: 'Jeremy Sallee', email: 'jsallee@gmail.com' },
+      ]}
+    />
+  );
+}
+
+export function MultipleAccounts(_args: Record<string, unknown>) {
+  return (
+    <AccountButton
+      {...handlers}
+      status='ready'
+      activeAccount={preston}
+      activeOrganizationId='org_clerk_app'
+      hasOrganizations
+      memberships={[
+        {
+          kind: 'membership',
+          organizationId: 'org_clerk_app',
+          name: 'Clerk app',
+          membersCount: 24,
+          planLabel: 'Pro plan',
+          upgradeable: true,
+        },
+        { kind: 'membership', organizationId: 'org_clerk_cloud', name: 'Clerk Cloud' },
+      ]}
+      suggestions={[]}
+      invitations={[]}
+      additionalAccounts={[
+        { sessionId: 'sess_cam', userId: 'user_cam', name: 'Cameron Walker', email: 'cameron.walker@gmail.com' },
+      ]}
+    />
+  );
+}