feat(mosaic): add UserAvatar

.changeset/mosaic-user-avatar.md

@@ -0,0 +1,5 @@
+---
+'@clerk/mosaic': patch
+---
+
+Add `<UserAvatar />`, which shows the signed-in user's profile image. It takes `shape`, `size` and `fallback`, renders nothing when nobody is signed in, and can be styled through `.cl-user-avatar`.

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

@@ -0,0 +1,87 @@
+import { screen, waitFor } from '@testing-library/react';
+import { describe, expect, it } from 'vitest';
+
+import { holdRequests, serveFapi } from '../../../__tests__/feature/fake-fapi';
+import { fapiClient, fapiEmailAddress, fapiSession, fapiUser } from '../../../__tests__/feature/fapi';
+import { renderWithClerk } from '../../../__tests__/feature/render';
+import type { UserAvatarProps } from '../user-avatar';
+import { UserAvatar } from '../user-avatar';
+
+const PIXEL =
+  'data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mNkYAAAAAYAAjCB0C8AAAAASUVORK5CYII=';
+
+const email = fapiEmailAddress({ id: 'idn_alice', email_address: 'alice@example.com' });
+
+const alice = fapiUser({ id: 'user_1', first_name: 'Alice', last_name: 'Smith', email_addresses: [email] });
+
+function signedInAs(user = alice) {
+  return { client: fapiClient([fapiSession({ id: 'sess_1', user })]) };
+}
+
+function tree(props: UserAvatarProps = {}) {
+  return (
+    <div data-testid='host'>
+      <UserAvatar {...props} />
+    </div>
+  );
+}
+
+const host = () => screen.getByTestId('host');
+
+describe('UserAvatar', () => {
+  it('renders its fallback while Clerk is still loading', async () => {
+    serveFapi(signedInAs());
+    const client = holdRequests('get', '/v1/client');
+    const rendering = renderWithClerk(tree({ fallback: <output data-testid='fallback'>Loading</output> }));
+
+    await waitFor(() => expect(client.requests).toHaveLength(1));
+    expect(screen.getByTestId('fallback')).toBeInTheDocument();
+
+    client.release();
+    await rendering;
+    expect(screen.queryByTestId('fallback')).toBeNull();
+    expect(screen.getByRole('img', { name: 'Alice Smith' })).toBeInTheDocument();
+  });
+
+  it('renders nothing, not even its fallback, when nobody is signed in', async () => {
+    serveFapi({ client: fapiClient() });
+    await renderWithClerk(tree({ fallback: <output>Loading</output> }));
+
+    expect(host()).toBeEmptyDOMElement();
+  });
+
+  it('holds the initials in the placeholder for a user with no profile image', async () => {
+    serveFapi(signedInAs());
+    await renderWithClerk(tree());
+
+    const avatar = screen.getByRole('img', { name: 'Alice Smith' });
+    expect(avatar).toHaveTextContent('AS');
+    expect(avatar.querySelector('img')).toBeNull();
+  });
+
+  it('shows the profile image once it loads', async () => {
+    serveFapi(signedInAs(fapiUser({ ...alice, image_url: PIXEL, has_image: true })));
+    await renderWithClerk(tree());
+
+    const avatar = screen.getByRole('img', { name: 'Alice Smith' });
+    await waitFor(() => expect(avatar.querySelector('img')).toHaveAttribute('src', PIXEL));
+    expect(avatar).not.toHaveTextContent('AS');
+  });
+
+  it('is named by the identifier, and holds its first letter, for a user with no name', async () => {
+    serveFapi(signedInAs(fapiUser({ id: 'user_2', email_addresses: [email] })));
+    await renderWithClerk(tree());
+
+    expect(screen.getByRole('img', { name: 'alice@example.com' })).toHaveTextContent('A');
+  });
+
+  it('takes the shape and size it is given', async () => {
+    serveFapi(signedInAs());
+    await renderWithClerk(tree({ shape: 'square', size: 'lg' }));
+
+    const avatar = screen.getByRole('img', { name: 'Alice Smith' });
+    expect(avatar).toHaveClass('cl-user-avatar', 'cl-avatar');
+    expect(avatar).toHaveAttribute('data-shape', 'square');
+    expect(avatar).toHaveAttribute('data-size', 'lg');
+  });
+});

packages/mosaic/src/features/user-avatar/user-avatar.model.ts

@@ -0,0 +1,27 @@
+import { getFullName, getIdentifier, getInitials } from '@clerk/shared/internal/clerk-js/user';
+import { useUser } from '@clerk/shared/react';
+
+import type { UserAvatarData } from './user-avatar.types';
+
+export type UserAvatarModel = { status: 'loading' } | { status: 'hidden' } | (UserAvatarData & { status: 'ready' });
+
+export function useUserAvatarModel(): UserAvatarModel {
+  const { isLoaded, user } = useUser();
+
+  if (!isLoaded) {
+    return { status: 'loading' };
+  }
+
+  if (!user) {
+    return { status: 'hidden' };
+  }
+
+  const name = getFullName(user) || getIdentifier(user);
+
+  return {
+    status: 'ready',
+    name,
+    initials: (getInitials(user) || name.charAt(0)).toUpperCase(),
+    imageUrl: user.imageUrl || undefined,
+  };
+}

packages/mosaic/src/features/user-avatar/user-avatar.tsx

@@ -0,0 +1,64 @@
+'use client';
+
+import type { ReactElement, ReactNode } from 'react';
+
+import { useUserAvatarModel } from './user-avatar.model';
+import type { UserAvatarAppearanceProps } from './user-avatar.view';
+import { UserAvatarView } from './user-avatar.view';
+
+/** Everything `<UserAvatar />` takes: its shape and size, and what stands in while Clerk loads. */
+export interface UserAvatarProps extends UserAvatarAppearanceProps {
+  /**
+   * Fallback while loading.
+   *
+   * Note that the component renders nothing when the user is signed out, so using this on
+   * pages that are reachable while both signed-out and signed-in can result in Fallback->Nothing.
+   */
+  fallback?: ReactNode;
+}
+
+/**
+ * The signed-in user's profile image. It reads the user from Clerk, so it takes no data. It renders
+ * `fallback` until Clerk answers, and nothing at all when nobody is signed in. Assistive technology
+ * reads it as an image named for the user.
+ *
+ * @example
+ * ```tsx
+ * import { UserAvatar } from '@clerk/mosaic';
+ *
+ * <UserAvatar />
+ * ```
+ *
+ * @example
+ * `shape` and `size` take the same values as `Avatar`.
+ * ```tsx
+ * <UserAvatar shape='square' size='lg' />
+ * ```
+ *
+ * @example
+ * `fallback` holds the space while Clerk is still answering. Nothing stands in once the answer is
+ * that nobody is signed in.
+ * ```tsx
+ * <UserAvatar fallback={<AvatarSkeleton />} />
+ * ```
+ */
+export function UserAvatar({ fallback, ...appearance }: UserAvatarProps = {}): ReactElement | null {
+  const model = useUserAvatarModel();
+
+  if (model.status === 'loading') {
+    return <>{fallback}</>;
+  }
+
+  if (model.status === 'hidden') {
+    return null;
+  }
+
+  const { status: _status, ...data } = model;
+
+  return (
+    <UserAvatarView
+      {...data}
+      {...appearance}
+    />
+  );
+}

packages/mosaic/src/features/user-avatar/user-avatar.types.ts

@@ -0,0 +1,7 @@
+import type { UserResource } from '@clerk/shared/types';
+
+export interface UserAvatarData extends Partial<Pick<UserResource, 'imageUrl'>> {
+  /** The user's full name, or their identifier when they have none. */
+  name: string;
+  initials: string;
+}

packages/mosaic/src/features/user-avatar/user-avatar.view.tsx

@@ -0,0 +1,49 @@
+import type { ReactElement } from 'react';
+
+import type { AvatarProps } from '../../components/avatar';
+import { Avatar } from '../../components/avatar';
+import { themeProps } from '../../props';
+import type { UserAvatarData } from './user-avatar.types';
+
+export interface UserAvatarAppearanceProps {
+  /**
+   * The outline of the avatar.
+   *
+   * @default 'circle'
+   */
+  shape?: AvatarProps['shape'];
+  /**
+   * The size of the avatar. `fit` fills the element it sits in.
+   *
+   * @default 'sm'
+   */
+  size?: AvatarProps['size'];
+}
+
+export interface UserAvatarViewProps extends UserAvatarData, UserAvatarAppearanceProps {}
+
+export function UserAvatarView({
+  name,
+  initials,
+  imageUrl,
+  shape = 'circle',
+  size = 'sm',
+}: UserAvatarViewProps): ReactElement {
+  return (
+    <Avatar.Root
+      {...themeProps('user-avatar')}
+      role='img'
+      aria-label={name}
+      shape={shape}
+      size={size}
+    >
+      {imageUrl ? (
+        <Avatar.Image
+          src={imageUrl}
+          alt=''
+        />
+      ) : null}
+      <Avatar.Fallback>{initials}</Avatar.Fallback>
+    </Avatar.Root>
+  );
+}

packages/mosaic/src/index.ts

@@ -2,6 +2,8 @@
 
 export type { UserButtonProps } from './features/user-button/user-button';
 export { UserButton } from './features/user-button/user-button';
+export type { UserAvatarProps } from './features/user-avatar/user-avatar';
+export { UserAvatar } from './features/user-avatar/user-avatar';
 export type { OrganizationSwitcherProps } from './features/organization-switcher/organization-switcher';
 export { OrganizationSwitcher } from './features/organization-switcher/organization-switcher';
 export { MosaicProvider } from './mosaic-provider';

packages/swingset/src/components/DocsViewer.tsx

@@ -53,6 +53,7 @@ const docModules: Record<string, Record<string, React.ComponentType>> = {
   },
   misc: {
     'organization-switcher': dynamic(() => import('../stories/organization-switcher.mdx')),
+    'user-avatar': dynamic(() => import('../stories/user-avatar.mdx')),
     'api-keys-table': dynamic(() => import('../stories/api-keys-table.mdx')),
     reverification: dynamic(() => import('../stories/reverification.mdx')),
   },

packages/swingset/src/lib/registry.ts

@@ -339,6 +339,13 @@ import {
 } from '../stories/tooltip.component.stories';
 import { meta as tooltipMeta } from '../stories/tooltip.stories';
 import { Default as UseFormDefault, meta as useFormMeta } from '../stories/use-form.stories';
+import {
+  Default as UserAvatarDefault,
+  meta as userAvatarMeta,
+  NoImage as UserAvatarNoImage,
+  Shapes as UserAvatarShapes,
+  Sizes as UserAvatarSizes,
+} from '../stories/user-avatar.stories';
 import {
   Combined as UserButtonCombined,
   meta as userButtonMeta,
@@ -670,6 +677,14 @@ const userButtonModule: StoryModule = {
   User: UserButtonUser,
 };
 
+const userAvatarModule: StoryModule = {
+  meta: userAvatarMeta,
+  Default: UserAvatarDefault,
+  NoImage: UserAvatarNoImage,
+  Shapes: UserAvatarShapes,
+  Sizes: UserAvatarSizes,
+};
+
 const organizationSwitcherModule: StoryModule = {
   meta: organizationSwitcherMeta,
   Default: OrganizationSwitcherDefault,
@@ -1046,6 +1061,7 @@ export const registry: StoryModule[] = [
   organizationProfileDangerSectionModule,
   // Misc
   organizationSwitcherModule,
+  userAvatarModule,
   apiKeysTableModule,
   reverificationModule,
   // Blocks — flows assembled from components, wired by the caller's machine.

packages/swingset/src/stories/user-avatar.mdx

@@ -0,0 +1,72 @@
+import * as UserAvatarStories from './user-avatar.stories';
+
+# UserAvatar
+
+The signed-in user's profile image on its own. It reads the user from Clerk and takes no data.
+Assistive technology reads it as an image named for the user, by their full name or, without one,
+their username, email, or phone number.
+
+It renders `fallback` while Clerk loads, and nothing when nobody is signed in.
+
+## Example
+
+<Story
+  name='Default'
+  storyModule={UserAvatarStories}
+  composition={[{ name: 'Avatar', href: '/components/avatar', layer: 'Components' }]}
+/>
+
+## Usage
+
+```tsx
+import { UserAvatar } from '@clerk/mosaic';
+
+<UserAvatar />;
+```
+
+## Props
+
+| Prop       | Type                                    | Default    | Description                                     |
+| ---------- | --------------------------------------- | ---------- | ----------------------------------------------- |
+| `shape`    | `'circle' \| 'square'`                  | `'circle'` | The outline of the avatar.                      |
+| `size`     | `'xs' \| 'sm' \| 'md' \| 'lg' \| 'fit'` | `'sm'`     | The size of the avatar. `fit` fills its parent. |
+| `fallback` | `ReactNode`                             | —          | Rendered while Clerk loads.                     |
+
+## Without an image
+
+Until the image loads, or when it fails, a blank placeholder holds its place. The user's initials sit
+inside it, hidden; see [Styling](#styling) to paint them.
+
+<Story
+  name='NoImage'
+  storyModule={UserAvatarStories}
+/>
+
+## Shapes
+
+<Story
+  name='Shapes'
+  storyModule={UserAvatarStories}
+/>
+
+## Sizes
+
+<Story
+  name='Sizes'
+  storyModule={UserAvatarStories}
+/>
+
+## Styling
+
+| Slot              | Attributes                                 |
+| ----------------- | ------------------------------------------ |
+| `.cl-user-avatar` | `data-shape`, `data-size`, `data-bordered` |
+
+The avatar also carries the `.cl-avatar` slot and its parts, so anything that styles `Avatar` applies
+here too. `.cl-user-avatar` targets this one alone.
+
+```css
+.cl-user-avatar .cl-avatar-fallback-content {
+  visibility: visible;
+}
+```