feat(ui): add AvatarButton block

Author: austincalvelage

.changeset/avatar-button-block.md

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

packages/swingset/src/components/DocsViewer.tsx

@@ -28,6 +28,7 @@ const docModules: Record<string, Record<string, React.ComponentType>> = {
     'organization-profile-delete-section': dynamic(() => import('../stories/organization-profile-delete-section.mdx')),
   },
   blocks: {
+    'avatar-button': dynamic(() => import('../stories/avatar-button.mdx')),
     destructive: dynamic(() => import('../stories/destructive.mdx')),
     'settings-group': dynamic(() => import('../stories/settings-group.mdx')),
   },

packages/swingset/src/lib/registry.ts

@@ -8,6 +8,11 @@ import {
   Shapes as AvatarShapes,
   Sizes as AvatarSizes,
 } from '../stories/avatar.stories';
+import {
+  Default as AvatarButtonDefault,
+  Fallback as AvatarButtonFallback,
+  meta as avatarButtonMeta,
+} from '../stories/avatar-button.stories';
 import {
   Colors as BadgeColors,
   meta as badgeMeta,
@@ -132,6 +137,11 @@ import { toSlug } from './slug';
 import type { StoryModule } from './types';
 
 const destructiveModule: StoryModule = { meta: destructiveMeta, Default: DestructiveDefault };
+const avatarButtonModule: StoryModule = {
+  meta: avatarButtonMeta,
+  Default: AvatarButtonDefault,
+  Fallback: AvatarButtonFallback,
+};
 const settingsGroupModule: StoryModule = {
   meta: settingsGroupMeta,
   Default: SettingsGroupDefault,
@@ -280,6 +290,7 @@ export const registry: StoryModule[] = [
   organizationProfileLeaveSectionModule,
   organizationProfileDeleteSectionModule,
   // Blocks
+  avatarButtonModule,
   destructiveModule,
   settingsGroupModule,
   // Components

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

@@ -0,0 +1,11 @@
+import * as AvatarButtonStories from './avatar-button.stories';
+
+# AvatarButton
+
+An interactive profile avatar with a stable edit affordance, accessible button semantics, and initials fallback.
+
+<Story name='Default' storyModule={AvatarButtonStories} composition={[{ name: 'Avatar', href: '/components/avatar', layer: 'Components' }, { name: 'Button', href: '/components/button', layer: 'Components' }]} />
+
+## Fallback
+
+<Story name='Fallback' storyModule={AvatarButtonStories} />

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

@@ -0,0 +1,32 @@
+/** @jsxImportSource @emotion/react */
+import { AvatarButton } from '@clerk/ui/mosaic/block/avatar-button';
+
+import type { StoryMeta } from '@/lib/types';
+
+export { default as __source } from './avatar-button.stories?raw';
+
+export const meta: StoryMeta = {
+  group: 'Blocks',
+  title: 'AvatarButton',
+  source: 'packages/ui/src/mosaic/block/avatar-button.tsx',
+  styleEngine: 'stylex',
+};
+
+export function Default() {
+  return (
+    <AvatarButton
+      imageUrl='https://avatars.githubusercontent.com/u/51144033?v=4'
+      name='Preston Booth'
+      onClick={() => undefined}
+    />
+  );
+}
+
+export function Fallback() {
+  return (
+    <AvatarButton
+      name='Preston Booth'
+      onClick={() => undefined}
+    />
+  );
+}

packages/swingset/src/stories/icon.stories.tsx

@@ -17,7 +17,7 @@ export const meta: StoryMeta = {
   styleEngine: 'stylex',
   styles: {
     _variants: {
-      size: { sm: {}, md: {}, lg: {} },
+      size: { xs: {}, sm: {}, md: {}, lg: {} },
     },
     _defaultVariants: {
       size: 'md',
@@ -44,6 +44,11 @@ export function Default(props: Record<string, unknown>) {
 export function Sizes(props: Record<string, unknown>) {
   return (
     <div style={{ display: 'flex', gap: 12, alignItems: 'center' }}>
+      <Icon
+        {...knobsAsProps(props)}
+        name='chevron-right'
+        size='xs'
+      />
       <Icon
         {...knobsAsProps(props)}
         name='chevron-right'

packages/ui/src/mosaic/block/avatar-button.test.tsx

@@ -0,0 +1,40 @@
+import { fireEvent, render, screen } from '@testing-library/react';
+import React from 'react';
+import { describe, expect, it, vi } from 'vitest';
+
+import { AvatarButton } from './avatar-button';
+
+describe('AvatarButton', () => {
+  it('renders an accessible avatar action with a stable edit treatment', () => {
+    render(
+      <AvatarButton
+        imageUrl='avatar.png'
+        name='Ada Lovelace'
+      />,
+    );
+
+    const button = screen.getByRole('button', { name: 'Edit profile picture' });
+    expect(button).toHaveClass('cl-avatar-button');
+    expect(button).toHaveAttribute('data-shape', 'circle');
+    expect(button).toHaveAttribute('data-size', 'lg');
+    expect(button.querySelector('.cl-avatar')).toHaveAttribute('aria-hidden', 'true');
+    expect(button.querySelector('.cl-avatar-button-edit-surface')).not.toBeNull();
+  });
+
+  it('derives fallback initials and forwards button behavior', () => {
+    const onClick = vi.fn();
+    const ref = React.createRef<HTMLButtonElement>();
+    render(
+      <AvatarButton
+        ref={ref}
+        name='Ada Lovelace'
+        onClick={onClick}
+      />,
+    );
+
+    expect(screen.getByText('AL')).toBeInTheDocument();
+    fireEvent.click(screen.getByRole('button', { name: 'Edit profile picture' }));
+    expect(onClick).toHaveBeenCalledOnce();
+    expect(ref.current).toBeInstanceOf(HTMLButtonElement);
+  });
+});

packages/ui/src/mosaic/block/avatar-button.tsx

@@ -0,0 +1,94 @@
+import * as stylex from '@stylexjs/stylex';
+import React from 'react';
+
+import { Avatar } from '../components/avatar';
+import type { ButtonProps } from '../components/button';
+import { Button } from '../components/button';
+import { Icon } from '../components/icon';
+import { mergeStyleProps, themeProps } from '../props';
+import { colorVars, radiusVars } from '../tokens.stylex';
+
+export interface AvatarButtonProps extends Omit<ButtonProps, 'children' | 'shape' | 'size'> {
+  imageUrl?: string;
+  name: string;
+  fallback?: React.ReactNode;
+}
+
+const styles = stylex.create({
+  root: {
+    borderWidth: 0,
+    position: 'relative',
+  },
+  editSurface: {
+    borderColor: colorVars['--cl-color-border'],
+    borderRadius: radiusVars['--cl-radius-full'],
+    borderStyle: 'solid',
+    borderWidth: '1px',
+    alignItems: 'center',
+    backgroundColor: colorVars['--cl-color-card'],
+    boxSizing: 'border-box',
+    display: 'flex',
+    insetInlineStart: '-4.5px',
+    justifyContent: 'center',
+    position: 'absolute',
+    height: '20px',
+    top: '25px',
+    width: '20px',
+  },
+});
+
+export const AvatarButton = React.forwardRef<HTMLButtonElement, AvatarButtonProps>(function AvatarButton(
+  {
+    imageUrl,
+    name,
+    fallback,
+    color = 'neutral',
+    variant = 'ghost',
+    className,
+    style,
+    'aria-label': ariaLabel = 'Edit profile picture',
+    ...rest
+  },
+  ref,
+) {
+  const initials = name
+    .split(/\s+/)
+    .map(part => part[0])
+    .join('')
+    .slice(0, 2)
+    .toUpperCase();
+
+  return (
+    <Button
+      ref={ref}
+      aria-label={ariaLabel}
+      color={color}
+      shape='circle'
+      size='lg'
+      variant={variant}
+      {...mergeStyleProps(themeProps('avatar-button'), stylex.props(styles.root), className, style)}
+      {...rest}
+    >
+      <Avatar.Root
+        aria-hidden
+        size='md'
+      >
+        <Avatar.Image
+          alt=''
+          src={imageUrl}
+        />
+        <Avatar.Fallback>{fallback ?? initials}</Avatar.Fallback>
+      </Avatar.Root>
+      <span
+        aria-hidden
+        {...mergeStyleProps(themeProps('avatar-button-edit-surface'), stylex.props(styles.editSurface))}
+      >
+        <Icon
+          aria-hidden
+          name='pen'
+          size='xs'
+        />
+      </span>
+    </Button>
+  );
+});

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

@@ -20,6 +20,7 @@ export const styles = stylex.create({
 });
 
 export const sizes = stylex.create({
+  xs: { height: space['3'], width: space['3'] },
   sm: { height: space['3.5'], width: space['3.5'] },
   md: { height: space['4'], width: space['4'] },
   lg: { height: space['5'], width: space['5'] },

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

@@ -41,6 +41,19 @@ describe('Mosaic Icon', () => {
     expect(svg).toHaveStyle({ marginTop: '8px' });
   });
 
+  it('renders the pen with its native 12px geometry', () => {
+    const { container } = wrap(
+      <Icon
+        name='pen'
+        size='xs'
+      />,
+    );
+    const svg = container.querySelector('svg');
+    expect(svg).toHaveAttribute('data-size', 'xs');
+    expect(svg).toHaveAttribute('viewBox', '0 0 12 12');
+    expect(svg?.querySelector('path')).toHaveAttribute('fill', 'currentColor');
+  });
+
   it('emits no placement attribute when the icon is not placed', () => {
     const { container } = wrap(<Icon name='chevron-right' />);
     expect(container.querySelector('svg')).not.toHaveAttribute('data-icon');