feat(ui): Add an edit username to user profile

.changeset/user-profile-edit-username.md

@@ -0,0 +1,2 @@
+---
+---

packages/swingset/src/stories/fixtures/user-profile-edit-username.ts

@@ -0,0 +1,28 @@
+import type { UserProfileFormError } from '@clerk/ui/mosaic/user-profile/user-profile-account-section/user-profile-account-section.types';
+import { UserProfileSaveError } from '@clerk/ui/mosaic/user-profile/user-profile-account-section/user-profile-account-section.types';
+import { useState } from 'react';
+
+export interface UserProfileEditUsernameFixtureOptions {
+  username?: string;
+  latency?: number;
+  failWith?: UserProfileFormError;
+}
+
+export function useUserProfileEditUsernameFixture({
+  username: initialUsername = 'prestonxyz',
+  latency = 800,
+  failWith,
+}: UserProfileEditUsernameFixtureOptions = {}) {
+  const [username, setUsername] = useState(initialUsername);
+
+  return {
+    username,
+    onSubmitUsername: async (value: string) => {
+      await new Promise(resolve => setTimeout(resolve, latency));
+      if (failWith) {
+        throw new UserProfileSaveError(failWith.message ?? 'Something went wrong.', failWith.fields);
+      }
+      setUsername(value);
+    },
+  };
+}

packages/swingset/src/stories/fixtures/user-profile.ts

@@ -14,6 +14,7 @@ import { useMemo, useState } from 'react';
 
 import { usePreviewImage } from './use-preview-image';
 import { useUserProfileEditNameFixture } from './user-profile-edit-name';
+import { useUserProfileEditUsernameFixture } from './user-profile-edit-username';
 
 export interface UserProfileFixtureOptions {
   /** Replaces the default "append an address" behaviour, e.g. to open a real prompt. */
@@ -44,6 +45,7 @@ const initialAPIKeys: UserProfileAPIKey[] = [
  */
 export function useUserProfileFixture({ onAddEmail }: UserProfileFixtureOptions = {}) {
   const editName = useUserProfileEditNameFixture();
+  const editUsername = useUserProfileEditUsernameFixture();
   const [activePage, setActivePage] = useState<UserProfileViewProps['activePage']>('account');
   const [emails, setEmails] = useState<UserProfileEmail[]>([
     { id: 'email_1', value: 'preston@clerk.dev', isDefault: true, isVerified: true },
@@ -112,10 +114,10 @@ export function useUserProfileFixture({ onAddEmail }: UserProfileFixtureOptions
   const pages: UserProfileViewProps['pages'] = {
     account: {
       ...editName,
+      ...editUsername,
       allowMultipleAccounts: true,
       hasImage: Boolean(imageUrl),
       imageUrl,
-      username: 'prestonxyz',
       emails,
       phones,
       onAddEmail: onAddEmail ?? (() => addEmail(`preston+${emails.length}@clerk.dev`)),
@@ -137,7 +139,6 @@ export function useUserProfileFixture({ onAddEmail }: UserProfileFixtureOptions
       onRemovePhone: id => setPhones(current => current.filter(phone => phone.id !== id)),
       onSetPrimaryEmail: id => setEmails(current => current.map(email => ({ ...email, isDefault: email.id === id }))),
       onSetPrimaryPhone: id => setPhones(current => current.map(phone => ({ ...phone, isDefault: phone.id === id }))),
-      onUsernameChange: () => undefined,
       onVerifyEmail: id =>
         setEmails(current => current.map(email => (email.id === id ? { ...email, isVerified: true } : email))),
       onVerifyPhone: id =>

packages/swingset/src/stories/user-profile-account-section.stories.tsx

@@ -10,6 +10,7 @@ import type { StoryMeta } from '@/lib/types';
 
 import { usePreviewImage } from './fixtures/use-preview-image';
 import { useUserProfileEditNameFixture } from './fixtures/user-profile-edit-name';
+import { useUserProfileEditUsernameFixture } from './fixtures/user-profile-edit-username';
 
 export { default as __source } from './user-profile-account-section.stories?raw';
 
@@ -25,11 +26,14 @@ export const meta: StoryMeta = {
 function AccountSection({
   allowMultipleAccounts,
   failWith,
+  usernameFailWith,
 }: {
   allowMultipleAccounts: boolean;
   failWith?: UserProfileFormError;
+  usernameFailWith?: UserProfileFormError;
 }) {
   const editName = useUserProfileEditNameFixture({ failWith });
+  const editUsername = useUserProfileEditUsernameFixture({ failWith: usernameFailWith });
   const [emails, setEmails] = useState<UserProfileEmail[]>(
     allowMultipleAccounts
       ? [
@@ -46,12 +50,12 @@ function AccountSection({
   return (
     <UserProfileAccountSectionView
       {...editName}
+      {...editUsername}
       allowMultipleAccounts={allowMultipleAccounts}
       emails={emails}
       hasImage={Boolean(imageUrl)}
       imageUrl={imageUrl}
       phones={phones}
-      username='prestonxyz'
       onAddEmail={() =>
         setEmails(current => [
           ...current,
@@ -74,7 +78,6 @@ function AccountSection({
       onRemoveEmail={id => setEmails(current => current.filter(email => email.id !== id))}
       onRemovePhone={id => setPhones(current => current.filter(phone => phone.id !== id))}
       onRemoveProfilePicture={clearImage}
-      onUsernameChange={() => undefined}
     />
   );
 }
@@ -99,3 +102,15 @@ export function EditNameFails() {
     />
   );
 }
+
+export function EditUsernameFails() {
+  return (
+    <AccountSection
+      allowMultipleAccounts={false}
+      usernameFailWith={{
+        message: 'Your username could not be updated.',
+        fields: { username: 'That username is already taken.' },
+      }}
+    />
+  );
+}

packages/swingset/src/stories/user-profile-profile-panel.stories.tsx

@@ -6,6 +6,7 @@ import type { StoryMeta } from '@/lib/types';
 
 import { usePreviewImage } from './fixtures/use-preview-image';
 import { useUserProfileEditNameFixture } from './fixtures/user-profile-edit-name';
+import { useUserProfileEditUsernameFixture } from './fixtures/user-profile-edit-username';
 
 const providerIconUrl = (provider: string) => `https://img.clerk.com/static/${provider}.svg`;
 const profileImageUrl = 'https://avatars.githubusercontent.com/u/51144033?v=4';
@@ -31,10 +32,12 @@ export function Default(_args: Record<string, unknown>) {
   ]);
   const { imageUrl, showFile, clearImage } = usePreviewImage(profileImageUrl);
   const editName = useUserProfileEditNameFixture();
+  const editUsername = useUserProfileEditUsernameFixture();
 
   return (
     <UserProfileProfilePanelView
       {...editName}
+      {...editUsername}
       allowMultipleAccounts
       emails={emails}
       connectedAccounts={[
@@ -66,7 +69,6 @@ export function Default(_args: Record<string, unknown>) {
       hasImage={Boolean(imageUrl)}
       imageUrl={imageUrl}
       phones={phones}
-      username='prestonxyz'
       onAddEmail={() =>
         setEmails(current => [
           ...current,
@@ -99,7 +101,6 @@ export function Default(_args: Record<string, unknown>) {
       onSetPrimaryPhone={() => undefined}
       onVerifyEmail={() => undefined}
       onVerifyPhone={() => undefined}
-      onUsernameChange={() => undefined}
     />
   );
 }

packages/ui/src/mosaic/user-profile/__tests__/user-profile-edit-username.view.test.tsx

@@ -0,0 +1,142 @@
+import { render, screen, waitFor } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import { describe, expect, it, vi } from 'vitest';
+
+import { Button } from '../../components/button';
+import { MosaicProvider } from '../../MosaicProvider';
+import type { UserProfileEditUsernameViewProps } from '../user-profile-account-section/user-profile-edit-username.view';
+import { UserProfileEditUsernameView } from '../user-profile-account-section/user-profile-edit-username.view';
+
+function renderView(overrides: Partial<UserProfileEditUsernameViewProps> = {}) {
+  const props: UserProfileEditUsernameViewProps = {
+    open: true,
+    onOpenChange: vi.fn(),
+    username: 'prestonxyz',
+    onUsernameChange: vi.fn(),
+    onSubmit: vi.fn(),
+    ...overrides,
+  };
+  return {
+    props,
+    ...render(
+      <MosaicProvider>
+        <UserProfileEditUsernameView {...props} />
+      </MosaicProvider>,
+    ),
+  };
+}
+
+const usernameField = () => screen.getByLabelText('Username');
+const saveButton = () => screen.getByRole('button', { name: 'Save changes' });
+
+describe('UserProfileEditUsernameView', () => {
+  it('renders nothing until the caller opens it', () => {
+    renderView({ open: false });
+
+    expect(screen.queryByRole('dialog')).not.toBeInTheDocument();
+  });
+
+  it('names the dialog and shows the value it was given', () => {
+    renderView();
+
+    expect(screen.getByRole('dialog', { name: 'Edit username' })).toBeInTheDocument();
+    expect(usernameField()).toHaveValue('prestonxyz');
+  });
+
+  it('opens on the field rather than the corner dismiss', async () => {
+    renderView();
+
+    // `FloatingFocusManager` moves focus in an effect, hence the wait.
+    await waitFor(() => expect(usernameField()).toHaveFocus());
+  });
+
+  it('asks to open from the trigger', async () => {
+    const onOpenChange = vi.fn();
+    const user = userEvent.setup();
+    renderView({ open: false, onOpenChange, trigger: <Button>Edit username</Button> });
+
+    await user.click(screen.getByRole('button', { name: 'Edit username' }));
+
+    expect(onOpenChange).toHaveBeenCalledWith(true, expect.anything());
+  });
+
+  it('reports each keystroke, holding nothing itself', async () => {
+    const onUsernameChange = vi.fn();
+    const user = userEvent.setup();
+    renderView({ onUsernameChange });
+
+    await user.type(usernameField(), 'x');
+
+    expect(onUsernameChange).toHaveBeenCalledWith('prestonxyzx');
+    // Controlled: the rendered value only moves when the caller says so.
+    expect(usernameField()).toHaveValue('prestonxyz');
+  });
+
+  it('submits from the action and from enter in the field', async () => {
+    const onSubmit = vi.fn();
+    const user = userEvent.setup();
+    renderView({ onSubmit });
+
+    await user.click(saveButton());
+    // One field, so native implicit submission carries Enter with no submit button in the form.
+    await user.type(usernameField(), '{Enter}');
+
+    expect(onSubmit).toHaveBeenCalledTimes(2);
+  });
+
+  it('asks to close from cancel', async () => {
+    const onOpenChange = vi.fn();
+    const user = userEvent.setup();
+    renderView({ onOpenChange });
+
+    await user.click(screen.getByRole('button', { name: 'Cancel' }));
+
+    expect(onOpenChange).toHaveBeenCalledWith(false, expect.anything());
+  });
+
+  it('announces the failure in a negative banner', () => {
+    renderView({ error: { message: 'Your username could not be updated.' } });
+
+    const banner = screen.getByRole('alert');
+    expect(banner).toHaveAttribute('data-color', 'negative');
+    expect(banner).toHaveTextContent('Your username could not be updated.');
+    expect(usernameField()).not.toHaveAttribute('aria-invalid', 'true');
+  });
+
+  it('renders a field-scoped failure with no banner', () => {
+    renderView({ error: { fields: { username: 'That username is taken.' } } });
+
+    expect(screen.queryByRole('alert')).not.toBeInTheDocument();
+    expect(screen.getByText('That username is taken.')).toBeInTheDocument();
+    expect(usernameField()).toHaveAttribute('aria-invalid', 'true');
+  });
+
+  it('withholds the save while the caller says the value is unacceptable', async () => {
+    const onSubmit = vi.fn();
+    const user = userEvent.setup();
+    renderView({ canSave: false, onSubmit });
+
+    // Inert but still reachable, so the reason stays discoverable by keyboard.
+    expect(saveButton()).toHaveAttribute('aria-disabled', 'true');
+    await user.click(saveButton());
+    await user.type(usernameField(), '{Enter}');
+
+    expect(onSubmit).not.toHaveBeenCalled();
+  });
+
+  it('stays inert while the save runs', async () => {
+    const onSubmit = vi.fn();
+    const onUsernameChange = vi.fn();
+    const user = userEvent.setup();
+    renderView({ isSaving: true, onSubmit, onUsernameChange });
+
+    await user.type(usernameField(), 'ada');
+
+    expect(usernameField()).toBeDisabled();
+    expect(onUsernameChange).not.toHaveBeenCalled();
+    // Busy, not unavailable: the pending affordance is `isPending`, not a second disabled state.
+    expect(saveButton()).toHaveAttribute('aria-busy', 'true');
+    await user.click(saveButton());
+    expect(onSubmit).not.toHaveBeenCalled();
+  });
+});

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

@@ -33,7 +33,7 @@ describe('UserProfileProfilePanelView', () => {
     renderView({
       onProfilePictureChange: vi.fn(),
       onSubmitName: () => Promise.resolve(),
-      onUsernameChange: vi.fn(),
+      onSubmitUsername: () => Promise.resolve(),
     });
 
     expect(screen.getByRole('heading', { level: 3, name: 'Account' })).toBeInTheDocument();
@@ -372,6 +372,23 @@ describe('UserProfileProfilePanelView', () => {
     await waitFor(() => expect(screen.queryByRole('dialog', { name: 'Edit name' })).not.toBeInTheDocument());
   });
 
+  it('drives the edit-username dialog from the section, seeded with the saved username', async () => {
+    const onSubmitUsername = vi.fn(() => Promise.resolve());
+    const user = userEvent.setup();
+    renderView({ username: 'prestonxyz', onSubmitUsername });
+
+    await user.click(screen.getByRole('button', { name: 'Edit username' }));
+    const dialog = screen.getByRole('dialog', { name: 'Edit username' });
+    expect(within(dialog).getByLabelText('Username')).toHaveValue('prestonxyz');
+
+    await user.clear(within(dialog).getByLabelText('Username'));
+    await user.type(within(dialog).getByLabelText('Username'), 'preston');
+    await user.click(within(dialog).getByRole('button', { name: 'Save changes' }));
+
+    expect(onSubmitUsername).toHaveBeenCalledWith('preston');
+    await waitFor(() => expect(screen.queryByRole('dialog', { name: 'Edit username' })).not.toBeInTheDocument());
+  });
+
   it('matches the existing conditional contact and connected-account actions', async () => {
     const onVerifyEmail = vi.fn();
     const onSetPrimaryEmail = vi.fn();

packages/ui/src/mosaic/user-profile/user-profile-account-section/user-profile-account-section.messages.ts

@@ -20,7 +20,7 @@ export const userProfileAccountSectionBase = {
     manage: 'Manage profile picture',
     change: 'Change avatar',
     remove: 'Remove avatar',
-    /** Shown under the description when the picker turns a file away. Keyed by rejection reason. */
+
     errors: {
       accept: 'File type not supported. Please upload a JPG, PNG, GIF, or WEBP image.',
       size: 'File size exceeds the maximum limit of 10MB. Please choose a smaller file.',
@@ -30,7 +30,7 @@ export const userProfileAccountSectionBase = {
   name: {
     label: 'Name',
     edit: 'Edit name',
-    /** The dialog behind `edit`. */
+
     dialogTitle: 'Edit name',
     firstNameLabel: 'First name',
     lastNameLabel: 'Last name',
@@ -40,13 +40,18 @@ export const userProfileAccountSectionBase = {
   username: {
     label: 'Username',
     edit: 'Edit username',
+
+    dialogTitle: 'Edit username',
+    fieldLabel: 'Username',
+    cancel: 'Cancel',
+    save: 'Save changes',
   },
   primary: 'Primary',
   add: 'Add',
   manage: 'Manage',
   setPrimary: 'Set as primary',
   completeVerification: 'Complete verification',
-  /** Names the action menu on one contact row, read as e.g. "Manage item1@clerk.dev". */
+
   manageValue: 'Manage {value}',
   email: {
     label: 'Email',