feat(ui): upload, change, and remove the profile picture in place

.changeset/spicy-avatars-change.md

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

.changeset/swingset-toast-todo-status.md

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

packages/swingset/src/components/DocsViewer.tsx

@@ -60,6 +60,7 @@ const docModules: Record<string, Record<string, React.ComponentType>> = {
     profile: dynamic(() => import('../stories/profile.component.mdx')),
     section: dynamic(() => import('../stories/section.mdx')),
     table: dynamic(() => import('../stories/table.mdx')),
+    toast: dynamic(() => import('../stories/toast.mdx')),
     text: dynamic(() => import('../stories/text.mdx')),
     field: dynamic(() => import('../stories/field.component.mdx')),
     flow: dynamic(() => import('../stories/flow.component.mdx')),

packages/swingset/src/lib/registry.ts

@@ -159,6 +159,7 @@ import {
   meta as textMeta,
   Sizes as TextSizes,
 } from '../stories/text.stories';
+import { meta as toastMeta } from '../stories/toast.stories';
 import { meta as tooltipMeta } from '../stories/tooltip.stories';
 import { meta as useDataTableMeta } from '../stories/use-data-table.stories';
 import {
@@ -419,6 +420,7 @@ const useDataTableModule: StoryModule = { meta: useDataTableMeta };
 
 // Planned but not yet implemented; the entry reserves its sidebar slot with a todo dot.
 const tableModule: StoryModule = { meta: tableMeta };
+const toastModule: StoryModule = { meta: toastMeta };
 
 const userProfileApiKeysPanelModule: StoryModule = {
   meta: userProfileApiKeysPanelMeta,
@@ -568,6 +570,7 @@ export const registry: StoryModule[] = [
   sectionModule,
   tableModule,
   textModule,
+  toastModule,
   fieldModule,
   visuallyHiddenModule,
   // Primitives — alphabetical within the group.

packages/swingset/src/stories/fixtures/use-preview-image.ts

@@ -0,0 +1,37 @@
+import { useCallback, useEffect, useRef, useState } from 'react';
+
+/**
+ * Holds the avatar a story is showing and swaps in an object URL for a picked file, revoking the
+ * one it replaces so repeated picks don't retain every earlier file for the life of the page.
+ * Only URLs this hook created are revoked, so the remote avatar it starts on is left alone.
+ */
+export function usePreviewImage(initialUrl?: string) {
+  const [imageUrl, setImageUrl] = useState<string | undefined>(initialUrl);
+  const objectUrlRef = useRef<string | undefined>(undefined);
+
+  const release = useCallback(() => {
+    if (objectUrlRef.current) {
+      URL.revokeObjectURL(objectUrlRef.current);
+      objectUrlRef.current = undefined;
+    }
+  }, []);
+
+  useEffect(() => release, [release]);
+
+  const showFile = useCallback(
+    (file: File) => {
+      release();
+      const next = URL.createObjectURL(file);
+      objectUrlRef.current = next;
+      setImageUrl(next);
+    },
+    [release],
+  );
+
+  const clearImage = useCallback(() => {
+    release();
+    setImageUrl(undefined);
+  }, [release]);
+
+  return { imageUrl, showFile, clearImage };
+}

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

@@ -12,6 +12,8 @@ import type {
 } from '@clerk/ui/mosaic/user-profile/user-profile-security-panel.view';
 import { useMemo, useState } from 'react';
 
+import { usePreviewImage } from './use-preview-image';
+
 export interface UserProfileFixtureOptions {
   /** Replaces the default "append an address" behaviour, e.g. to open a real prompt. */
   onAddEmail?: () => void;
@@ -96,6 +98,7 @@ export function useUserProfileFixture({ onAddEmail }: UserProfileFixtureOptions
   const [apiKeysPageSize, setAPIKeysPageSize] = useState(10);
   const [searchValue, setSearchValue] = useState('');
   const [selectedIds, setSelectedIds] = useState<string[]>([]);
+  const { imageUrl, showFile, clearImage } = usePreviewImage('https://avatars.githubusercontent.com/u/51144033?v=4');
   const visibleAPIKeys = useMemo(
     () => apiKeys.filter(apiKey => apiKey.name.toLowerCase().includes(searchValue.toLowerCase())),
     [apiKeys, searchValue],
@@ -107,7 +110,8 @@ export function useUserProfileFixture({ onAddEmail }: UserProfileFixtureOptions
   const pages: UserProfileViewProps['pages'] = {
     account: {
       allowMultipleAccounts: true,
-      imageUrl: 'https://avatars.githubusercontent.com/u/51144033?v=4',
+      hasImage: Boolean(imageUrl),
+      imageUrl,
       name: 'Preston Booth',
       username: 'prestonxyz',
       emails,
@@ -123,11 +127,12 @@ export function useUserProfileFixture({ onAddEmail }: UserProfileFixtureOptions
           },
         ]),
       onDeleteAccount: () => Promise.resolve(),
-      onEditProfilePicture: () => undefined,
       onManageEmail: () => undefined,
       onManagePhone: () => undefined,
       onNameChange: () => undefined,
+      onProfilePictureChange: showFile,
       onRemoveEmail: id => setEmails(current => current.filter(email => email.id !== id)),
+      onRemoveProfilePicture: clearImage,
       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 }))),

packages/swingset/src/stories/toast.mdx

@@ -0,0 +1,5 @@
+# Toast
+
+Transient, self-dismissing message raised over the surface it belongs to, for feedback that has nowhere of its own to live — a picture the picker turned away, an action that failed after the row it started from is gone. Not yet implemented.
+
+Until it lands, a row that must report a failure renders it inline: `Section.Error` under the row, or `Field.Error` inside a `Field.Root`. The profile picture row is the case this component is meant to take over.

packages/swingset/src/stories/toast.stories.tsx

@@ -0,0 +1,7 @@
+import type { StoryMeta } from '@/lib/types';
+
+export const meta: StoryMeta = {
+  group: 'Components',
+  title: 'Toast',
+  status: 'todo',
+};

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

@@ -7,6 +7,8 @@ import { useState } from 'react';
 
 import type { StoryMeta } from '@/lib/types';
 
+import { usePreviewImage } from './fixtures/use-preview-image';
+
 export { default as __source } from './user-profile-account-section.stories?raw';
 
 export const meta: StoryMeta = {
@@ -30,12 +32,14 @@ function AccountSection({ allowMultipleAccounts }: { allowMultipleAccounts: bool
   const [phones, setPhones] = useState<UserProfilePhone[]>([
     { id: 'phone_1', value: '+1 801-888-8181', isDefault: true, isVerified: true },
   ]);
+  const { imageUrl, showFile, clearImage } = usePreviewImage('https://avatars.githubusercontent.com/u/51144033?v=4');
 
   return (
     <UserProfileAccountSectionView
       allowMultipleAccounts={allowMultipleAccounts}
       emails={emails}
-      imageUrl='https://avatars.githubusercontent.com/u/51144033?v=4'
+      hasImage={Boolean(imageUrl)}
+      imageUrl={imageUrl}
       name='Preston Booth'
       phones={phones}
       username='prestonxyz'
@@ -55,11 +59,12 @@ function AccountSection({ allowMultipleAccounts }: { allowMultipleAccounts: bool
           },
         ])
       }
-      onEditProfilePicture={() => undefined}
       onManageEmail={() => undefined}
       onManagePhone={() => undefined}
+      onProfilePictureChange={showFile}
       onRemoveEmail={id => setEmails(current => current.filter(email => email.id !== id))}
       onRemovePhone={id => setPhones(current => current.filter(phone => phone.id !== id))}
+      onRemoveProfilePicture={clearImage}
       onNameChange={() => undefined}
       onUsernameChange={() => undefined}
     />

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

@@ -4,6 +4,8 @@ import { useState } from 'react';
 
 import type { StoryMeta } from '@/lib/types';
 
+import { usePreviewImage } from './fixtures/use-preview-image';
+
 const providerIconUrl = (provider: string) => `https://img.clerk.com/static/${provider}.svg`;
 const profileImageUrl = 'https://avatars.githubusercontent.com/u/51144033?v=4';
 
@@ -26,6 +28,7 @@ export function Default(_args: Record<string, unknown>) {
   const [phones, setPhones] = useState<UserProfilePhone[]>([
     { id: 'phone_1', value: '+1 801-888-8181', isDefault: true, isVerified: true },
   ]);
+  const { imageUrl, showFile, clearImage } = usePreviewImage(profileImageUrl);
 
   return (
     <UserProfileProfilePanelView
@@ -57,7 +60,8 @@ export function Default(_args: Record<string, unknown>) {
           connected: false,
         },
       ]}
-      imageUrl={profileImageUrl}
+      hasImage={Boolean(imageUrl)}
+      imageUrl={imageUrl}
       name='Preston Booth'
       phones={phones}
       username='prestonxyz'
@@ -79,10 +83,11 @@ export function Default(_args: Record<string, unknown>) {
       }
       onConnectAccount={() => undefined}
       onDeleteAccount={() => Promise.resolve()}
-      onEditProfilePicture={() => undefined}
       onManageEmail={() => undefined}
       onManagePhone={() => undefined}
+      onProfilePictureChange={showFile}
       onRemoveConnectedAccount={() => undefined}
+      onRemoveProfilePicture={clearImage}
       onRemoveEmail={id => setEmails(current => current.filter(email => email.id !== id))}
       onRemovePhone={id => setPhones(current => current.filter(phone => phone.id !== id))}
       onConnectWeb3Wallet={() => undefined}

packages/ui/src/mosaic/components/section/section.styles.ts

@@ -128,5 +128,20 @@ export const styles = stylex.create({
     flexShrink: 0,
     justifyContent: 'flex-end',
   },
+  // Sits under the row's item rather than inside its content, so a message never shifts the
+  // media and actions off the centre line they share.
+  error: {
+    margin: 0,
+    gap: space['1'],
+    alignItems: 'flex-start',
+    color: colorVars['--cl-color-negative'],
+    display: 'flex',
+    textWrap: 'pretty',
+    width: '100%',
+  },
+  errorIcon: {
+    flexShrink: 0,
+    height: '1lh',
+  },
 });
 /* eslint-enable @stylexjs/no-lookahead-selectors */

packages/ui/src/mosaic/components/section/section.test.tsx

@@ -153,4 +153,36 @@ describe('Section', () => {
     expect(screen.getByText('Name')).toHaveStyle({ color: 'rgb(255, 0, 0)' });
     expect(actionsRef.current).toHaveClass('cl-section-actions');
   });
+
+  it('renders a row-level error as a sibling of the item, with the alert glyph', () => {
+    render(
+      <Section.Root>
+        <Section.Group>
+          <Section.Row data-testid='row'>
+            <Section.Item data-testid='item'>
+              <Section.Content>
+                <Section.Label>Profile picture</Section.Label>
+              </Section.Content>
+            </Section.Item>
+            <Section.Error data-testid='error'>File type not supported.</Section.Error>
+          </Section.Row>
+        </Section.Group>
+      </Section.Root>,
+    );
+
+    const error = screen.getByTestId('error');
+    expect(error).toHaveClass('cl-section-error');
+    expect(error.tagName).toBe('P');
+    // A row-level message announces itself; there is no field to describe it.
+    expect(error).toHaveAttribute('role', 'alert');
+    expect(error).toHaveTextContent('File type not supported.');
+    // Outside the item, so the item's media and actions keep their centre line.
+    expect(screen.getByTestId('item')).not.toContainElement(error);
+    expect(screen.getByTestId('row')).toContainElement(error);
+
+    const icon = error.querySelector('.cl-icon');
+    expect(icon).toBeInTheDocument();
+    expect(icon).toHaveAttribute('aria-hidden', 'true');
+    expect(icon).toHaveAttribute('data-size', 'sm');
+  });
 });

packages/ui/src/mosaic/components/section/section.tsx

@@ -6,8 +6,10 @@ import React from 'react';
 import type { MosaicComponentProps } from '../../props';
 import { mergeStyleProps, themeProps } from '../../props';
 import { reset } from '../../utils/reset.styles';
+import { sizes as typographySizes, styles as typographyStyles } from '../../utils/typography.styles';
 import type { HeadingProps } from '../heading';
 import { Heading } from '../heading';
+import { Icon } from '../icon';
 import { sectionItemsMarker } from './section.markers.stylex';
 import { styles } from './section.styles';
 
@@ -23,6 +25,7 @@ export type SectionContentProps = MosaicComponentProps<'div'>;
 export type SectionLabelProps = MosaicComponentProps<'div'>;
 export type SectionDescriptionProps = MosaicComponentProps<'div'>;
 export type SectionActionsProps = MosaicComponentProps<'div'>;
+export type SectionErrorProps = MosaicComponentProps<'p'>;
 
 const mediaSizes = {
   sm: styles.mediaSm,
@@ -250,8 +253,59 @@ const Actions = React.forwardRef<HTMLDivElement, SectionActionsProps>(function S
   });
 });
 
+/**
+ * A row-level message, mirroring `Field.Error` for a row that holds no form control. Place it as a
+ * sibling of `Section.Item` inside `Section.Row`, not inside `Section.Content`: the item stays a
+ * single centred line, so the media and actions hold their position whether or not it is showing.
+ * Carries `role='alert'` for the announcement a `Field.Root` would otherwise wire up.
+ */
+const SectionError = React.forwardRef<HTMLParagraphElement, SectionErrorProps>(function SectionError(
+  { render, className, style, children, ...rest },
+  ref,
+) {
+  return useRender({
+    defaultTagName: 'p',
+    render,
+    ref,
+    props: {
+      ...mergeStyleProps(
+        themeProps('section-error'),
+        stylex.props(reset.base, typographyStyles.base, typographySizes.xs, styles.error),
+        className,
+        style,
+      ),
+      role: 'alert',
+      ...rest,
+      children: (
+        <>
+          <Icon
+            name='alert-circle'
+            size='sm'
+            aria-hidden='true'
+            xstyle={styles.errorIcon}
+          />
+          <span>{children}</span>
+        </>
+      ),
+    },
+  });
+});
+
 /**
  * A compound component that fixes section semantics, surface treatment, row grouping,
  * and item layout while leaving each item's content composable.
  */
-export const Section = { Root, Title, Group, Row, Items, Item, Media, Content, Label, Description, Actions };
+export const Section = {
+  Root,
+  Title,
+  Group,
+  Row,
+  Items,
+  Item,
+  Media,
+  Content,
+  Label,
+  Description,
+  Actions,
+  Error: SectionError,
+};

packages/ui/src/mosaic/icons/registry.tsx

@@ -300,12 +300,16 @@ const ArrowRightTop = glyph(
 );
 
 const Pen = glyph(
-  <path
-    d='M12.03 3.972a1.59 1.59 0 0 0-2.261 0l-.01.01-5.056 4.89a1.25 1.25 0 0 0-.351.627l-.61 2.747 2.542-.598a1.25 1.25 0 0 0 .59-.325L12.085 6.2c.573-.638.549-1.62-.057-2.228M8.71 2.909a3.09 3.09 0 0 1 4.383.005 3.126 3.126 0 0 1 .06 4.341l-5.228 5.138a2.75 2.75 0 0 1-1.298.715l-3.705.872a.75.75 0 0 1-.904-.893l.87-3.914a2.75 2.75 0 0 1 .772-1.38z'
-    fill='currentColor'
-    fillRule='evenodd'
-    clipRule='evenodd'
-  />,
+  <>
+    <path
+      d='M12.2761 2.60927L13.3905 3.72366C13.9112 4.24436 13.9112 5.08858 13.3905 5.60928L12 6.99977L5.19526 13.8046C5.07024 13.9296 4.90067 13.9998 4.72386 13.9998H2V11.276C2 11.0991 2.07024 10.9296 2.19526 10.8046L9 3.9998L10.3905 2.60928C10.9112 2.08858 11.7555 2.08858 12.2761 2.60927Z'
+      {...strokeProps}
+    />
+    <path
+      d='M9 4L12 7'
+      {...strokeProps}
+    />
+  </>,
 );
 
 const LogOut = glyph(