feat(mosaic): wire up user profile Web3 wallets

.changeset/web3-wallets-wire-up.md

@@ -0,0 +1,6 @@
+---
+"@clerk/mosaic": patch
+---
+
+Show wallet discovery errors consistently with other dialogs and ask users to refresh the page when Solana wallets cannot load.
+Localize Web3 wallet connection errors through the shared error catalog, including custom translations for unavailable providers and missing wallet extensions.

packages/mosaic/AGENTS.md

@@ -43,6 +43,7 @@ Most problems a feature hits already have a shared answer. Find the row for your
 | A debounced, abortable async check as the user types                    | `useDebouncedAsync` (`src/hooks/`)                                                                            |
 | A spinner that should not flash or flicker                              | `useSpinDelay` (`src/hooks/`)                                                                                 |
 | Current time for display labels                                         | `useNow` + `MosaicProvider` ([#10098](https://github.com/clerk/javascript/pull/10098), once available)        |
+| Whether enterprise SSO permits adding another identification            | `allowsIdentificationCreation` (`src/utils/allows-identification-creation.ts`)                                |
 | An inline message row that animates open and closed                     | `useHeldMessage`, `useMessageHeight`, `FeedbackBody` (`src/utils/feedback.tsx`) + `styles/feedback.styles.ts` |
 | A table whose sorting, paging and search are done by the server         | `useServerDataTable` (`src/hooks/`)                                                                           |
 | Siblings that slide when an item is added or removed                    | `useLayoutAnimation` (`src/primitives/hooks/`)                                                                |

packages/mosaic/eslint-suppressions.json

@@ -59,7 +59,7 @@
       "count": 1
     }
   },
-  "src/features/user-profile/user-profile-web3-wallet-row.view.tsx": {
+  "src/features/user-profile/user-profile-web3-wallets-section/user-profile-web3-wallet-row.view.tsx": {
     "sonarjs/cognitive-complexity": {
       "count": 1
     }
@@ -162,4 +162,4 @@
       "count": 1
     }
   }
-}
+}

packages/mosaic/package.json

@@ -64,7 +64,8 @@
   },
   "dependencies": {
     "@clerk/shared": "workspace:^",
-    "@floating-ui/react": "catalog:repo"
+    "@floating-ui/react": "catalog:repo",
+    "@wallet-standard/core": "catalog:module-manager"
   },
   "devDependencies": {
     "@clerk/clerk-js": "workspace:^",

packages/mosaic/src/__tests__/feature/fake-fapi-user.feature.test.tsx

@@ -0,0 +1,32 @@
+import { describe, expect, it } from 'vitest';
+
+import { fapiUrl, serveFapi } from './fake-fapi';
+import { fapiClient, fapiSession, fapiUser, fapiWeb3Wallet } from './fapi';
+
+describe('fake FAPI user updates', () => {
+  it('updates profile fields without clearing omitted identification fields', async () => {
+    const user = fapiUser({
+      id: 'user_1',
+      first_name: 'Austin',
+      last_name: 'Original',
+      username: 'austin',
+      primary_web3_wallet_id: 'wallet_1',
+      web3_wallets: [fapiWeb3Wallet({ id: 'wallet_1', web3_wallet: '0x1234' })],
+    });
+    const fapi = serveFapi({ client: fapiClient([fapiSession({ id: 'sess_1', user })]) });
+
+    const response = await fetch(`${fapiUrl('/v1/me')}?_method=PATCH`, {
+      method: 'POST',
+      body: new URLSearchParams({ first_name: 'Updated', last_name: 'Name', username: 'updated' }),
+    });
+
+    expect(response.ok).toBe(true);
+    expect(fapi.client.sessions[0]?.user).toMatchObject({
+      first_name: 'Updated',
+      last_name: 'Name',
+      username: 'updated',
+      primary_web3_wallet_id: 'wallet_1',
+      web3_wallets: user.web3_wallets,
+    });
+  });
+});

packages/mosaic/src/__tests__/feature/fake-fapi.ts

@@ -9,6 +9,7 @@ import type {
   SessionJSON,
   UserJSON,
   UserOrganizationInvitationJSON,
+  Web3WalletJSON,
 } from '@clerk/shared/types';
 import { http, HttpResponse } from 'msw';
 import { setupWorker } from 'msw/browser';
@@ -33,6 +34,7 @@ import {
   fapiPage,
   fapiToken,
   fapiVerification,
+  fapiWeb3Wallet,
 } from './fapi';
 
 export const PUBLISHABLE_KEY = 'pk_live_Y2xlcmsuYWJjZWYuMTIzNDUucHJvZC5sY2xjbGVyay5jb20k';
@@ -121,6 +123,20 @@ function deleteOrganization(state: FakeFapiState, organizationId: string): void
   };
 }
 
+function findWeb3Wallet(state: FakeFapiState, id: unknown): Web3WalletJSON | undefined {
+  return activeUser(state)?.web3_wallets.find(wallet => wallet.id === id);
+}
+
+function updateWeb3Wallet(state: FakeFapiState, wallet: Web3WalletJSON): void {
+  const user = activeUser(state);
+  if (user) {
+    updateUser(state, {
+      ...user,
+      web3_wallets: user.web3_wallets.map(current => (current.id === wallet.id ? wallet : current)),
+    });
+  }
+}
+
 export function serveFapi(seed: FakeFapiSeed = {}): FakeFapiState {
   const { verification, enterpriseLinking, passkeys, ...rest } = seed;
   const state: FakeFapiState = {
@@ -221,6 +237,107 @@ export function serveFapi(seed: FakeFapiSeed = {}): FakeFapiState {
       updateUser(state, { ...user, external_accounts: user.external_accounts.filter(item => item.id !== account.id) });
       return envelope({ ...account, object: 'external_account' }, state.client);
     }),
+    http.post(fapiUrl('/v1/me/web3_wallets'), async ({ request }) => {
+      const user = activeUser(state);
+      if (!user) {
+        return missing();
+      }
+      const body = new URLSearchParams(await request.text());
+      const address = body.get('web3_wallet');
+      if (!address) {
+        return missing();
+      }
+      const wallet = fapiWeb3Wallet({
+        id: `wallet_${user.web3_wallets.length + 1}`,
+        web3_wallet: address,
+        verification: fapiVerification('', { expire_at: 0 }),
+      });
+      updateUser(state, { ...user, web3_wallets: [...user.web3_wallets, wallet] });
+      return envelope(wallet, state.client);
+    }),
+    http.post(fapiUrl('/v1/me/web3_wallets/:id/prepare_verification'), async ({ params, request }) => {
+      const wallet = findWeb3Wallet(state, params.id);
+      if (!wallet) {
+        return missing();
+      }
+      const body = new URLSearchParams(await request.text());
+      const prepared = fapiWeb3Wallet({
+        ...wallet,
+        verification: fapiVerification(body.get('strategy') ?? '', {
+          message: 'Sign this wallet challenge',
+          expire_at: 0,
+        }),
+      });
+      updateWeb3Wallet(state, prepared);
+      return envelope(prepared, state.client);
+    }),
+    http.post(fapiUrl('/v1/me/web3_wallets/:id/attempt_verification'), ({ params }) => {
+      const wallet = findWeb3Wallet(state, params.id);
+      if (!wallet) {
+        return missing();
+      }
+      const verified = fapiWeb3Wallet({
+        ...wallet,
+        verification: fapiVerification(wallet.verification?.strategy ?? '', {
+          ...wallet.verification,
+          status: 'verified',
+          verified_at_client: '',
+          attempts: 1,
+        }),
+      });
+      updateWeb3Wallet(state, verified);
+      const user = activeUser(state);
+      if (user && !user.primary_web3_wallet_id) {
+        updateUser(state, { ...user, primary_web3_wallet_id: verified.id });
+      }
+      return envelope(verified, state.client);
+    }),
+    http.post(fapiUrl('/v1/me/web3_wallets/:id'), ({ params, request }) => {
+      if (new URL(request.url).searchParams.get('_method') !== 'DELETE') {
+        return undefined;
+      }
+      const user = activeUser(state);
+      const wallet = findWeb3Wallet(state, params.id);
+      if (!user || !wallet) {
+        return missing();
+      }
+      const remainingWallets = user.web3_wallets.filter(current => current.id !== wallet.id);
+      updateUser(state, {
+        ...user,
+        web3_wallets: remainingWallets,
+        primary_web3_wallet_id:
+          user.primary_web3_wallet_id === wallet.id
+            ? (remainingWallets.find(current => current.verification?.status === 'verified')?.id ?? null)
+            : user.primary_web3_wallet_id,
+      });
+      return envelope({ object: 'web3_wallet', id: wallet.id, deleted: true }, state.client);
+    }),
+    http.post(fapiUrl('/v1/me'), async ({ request }) => {
+      if (new URL(request.url).searchParams.get('_method') !== 'PATCH') {
+        return undefined;
+      }
+      const user = activeUser(state);
+      if (!user) {
+        return missing();
+      }
+      const body = new URLSearchParams(await request.text());
+      const updated = { ...user };
+      const fields = [
+        'first_name',
+        'last_name',
+        'username',
+        'primary_email_address_id',
+        'primary_phone_number_id',
+        'primary_web3_wallet_id',
+      ] as const;
+      for (const field of fields) {
+        if (body.has(field)) {
+          updated[field] = body.get(field);
+        }
+      }
+      updateUser(state, updated);
+      return envelope(updated, state.client);
+    }),
     http.post(fapiUrl('/v1/client/sessions/:id/tokens'), ({ params }) => {
       const session = findSession(state, params.id);
       return session

packages/mosaic/src/__tests__/feature/fapi.ts

@@ -26,11 +26,20 @@ import type {
   UserOrganizationInvitationJSON,
   UserSettingsJSON,
   VerificationJSON,
+  Web3Strategy,
+  Web3WalletJSON,
 } from '@clerk/shared/types';
 
 type Settings<T> = Omit<T, 'id' | 'object'>;
 
-export type FapiUserSettings = Omit<Settings<UserSettingsJSON>, 'social'> & { social: Partial<OAuthProviders> };
+type FapiWeb3Attribute = Omit<AttributeDataJSON, 'first_factors'> & {
+  first_factors: Array<AttributeDataJSON['first_factors'][number] | Web3Strategy>;
+};
+
+export type FapiUserSettings = Omit<Settings<UserSettingsJSON>, 'social' | 'attributes'> & {
+  social: Partial<OAuthProviders>;
+  attributes: Omit<AttributesJSON, 'web3_wallet'> & { web3_wallet: FapiWeb3Attribute };
+};
 
 export type FapiEnvironment = Omit<EnvironmentJSON, 'user_settings' | 'organization_settings'> & {
   user_settings: FapiUserSettings;
@@ -354,6 +363,21 @@ export function fapiEnterpriseAccount(
   };
 }
 
+export function fapiWeb3Wallet(
+  overrides: Partial<Web3WalletJSON> & Pick<Web3WalletJSON, 'id' | 'web3_wallet'>,
+): Web3WalletJSON {
+  return {
+    object: 'web3_wallet',
+    verification: fapiVerification('web3_metamask_signature', {
+      status: 'verified',
+      verified_at_client: '',
+      attempts: 1,
+      expire_at: 0,
+    }),
+    ...overrides,
+  };
+}
+
 export function fapiSession(overrides: Partial<SessionJSON> & Pick<SessionJSON, 'id' | 'user'>): SessionJSON {
   const { user } = overrides;
   const primaryEmail = user.email_addresses.find(email => email.id === user.primary_email_address_id);

packages/mosaic/src/components/action-menu/action-menu.test.tsx

@@ -36,4 +36,35 @@ describe('Mosaic ActionMenu', () => {
 
     expect(onClick).toHaveBeenCalledOnce();
   });
+  it('disables both the trigger and existing menu items while busy', async () => {
+    const onClick = vi.fn();
+    const actions = [{ label: 'Remove', onClick }];
+    const view = render(
+      <MosaicProvider>
+        <ActionMenu
+          label='Manage wallet'
+          actions={actions}
+        />
+      </MosaicProvider>,
+    );
+    const user = userEvent.setup();
+    await user.click(screen.getByRole('button', { name: 'Manage wallet' }));
+    expect(await screen.findByRole('menuitem', { name: 'Remove' })).toBeInTheDocument();
+
+    view.rerender(
+      <MosaicProvider>
+        <ActionMenu
+          label='Manage wallet'
+          actions={actions}
+          disabled
+        />
+      </MosaicProvider>,
+    );
+
+    expect(screen.getByRole('button', { name: 'Manage wallet' })).toBeDisabled();
+    const remove = screen.getByRole('menuitem', { name: 'Remove' });
+    expect(remove).toHaveAttribute('aria-disabled', 'true');
+    await user.click(remove);
+    expect(onClick).not.toHaveBeenCalled();
+  });
 });

packages/mosaic/src/components/action-menu/action-menu.tsx

@@ -15,9 +15,10 @@ export interface ActionMenuProps {
   label: string;
   actions: ActionMenuAction[];
   triggerRef?: Ref<HTMLButtonElement>;
+  disabled?: boolean;
 }
 
-export function ActionMenu({ label, actions, triggerRef }: ActionMenuProps) {
+export function ActionMenu({ label, actions, triggerRef, disabled }: ActionMenuProps) {
   if (actions.length === 0) {
     return null;
   }
@@ -27,6 +28,7 @@ export function ActionMenu({ label, actions, triggerRef }: ActionMenuProps) {
       <Menu.Trigger
         ref={triggerRef}
         aria-label={label}
+        disabled={disabled}
       />
       <Menu.Popup>
         {actions.map(action => (
@@ -35,6 +37,7 @@ export function ActionMenu({ label, actions, triggerRef }: ActionMenuProps) {
             color={action.color}
             label={action.label}
             onClick={action.onClick}
+            disabled={disabled}
           >
             {action.icon ? (
               <Menu.Media>

packages/mosaic/src/features/user-profile/__tests__/user-profile-profile-panel.view.test.tsx

@@ -9,7 +9,7 @@ import { MosaicProvider } from '../../../mosaic-provider';
 import { UserProfileDangerSectionView } from '../user-profile-danger-section/user-profile-danger-section.view';
 import type { UserProfileProfilePanelViewProps } from '../user-profile-profile-panel.view';
 import { UserProfileProfilePanelView } from '../user-profile-profile-panel.view';
-import { UserProfileWeb3WalletsSectionView } from '../user-profile-web3-wallets-section.view';
+import { UserProfileWeb3WalletsSectionView } from '../user-profile-web3-wallets-section/user-profile-web3-wallets-section.view';
 
 function DeleteAccount() {
   const controller = useDestructiveController({ onDelete: () => Promise.resolve() });