feat: support polymorphic avatar root

Author: pawelgrimm

src/avatar/avatar.stories.tsx

@@ -5,6 +5,7 @@ import { Avatar, Box, Inline, Stack, Text } from '../index'
 import { AVATAR_SIZES, getAvatarMetaColorIndex } from './utils'
 
 import type { Meta, StoryObj } from '@storybook/react-vite'
+import type { AvatarProps } from './avatar'
 
 const sizes = AVATAR_SIZES
 
@@ -159,11 +160,11 @@ function AvatarExample({ label, children }: { label: string; children: React.Rea
     )
 }
 
-function UserAvatar(props: Omit<React.ComponentProps<typeof Avatar>, 'shape'>) {
+function UserAvatar(props: Omit<AvatarProps, 'shape'>) {
     return <Avatar shape="circle" {...props} />
 }
 
-function WorkspaceAvatarExample(props: Omit<React.ComponentProps<typeof Avatar>, 'shape'>) {
+function WorkspaceAvatarExample(props: Omit<AvatarProps, 'shape'>) {
     return <Avatar shape="rounded" {...props} />
 }
 
@@ -177,7 +178,7 @@ function AvatarColorExample({ index, name }: { index: number; name: string }) {
 
 type PlaygroundImage = keyof typeof playgroundImages
 
-type PlaygroundArgs = Omit<React.ComponentProps<typeof Avatar>, 'image'> & {
+type PlaygroundArgs = Omit<AvatarProps, 'image'> & {
     image?: PlaygroundImage
 }
 

src/avatar/avatar.test.tsx

@@ -193,6 +193,36 @@ describe('Avatar', () => {
         expect(screen.getByTestId('avatar')).toHaveTextContent('')
     })
 
+    it('can render the root as a different element', () => {
+        render(<Avatar as="section" data-testid="avatar" size={36} name="Jane Doe" />)
+
+        expect(screen.getByTestId('avatar').tagName).toBe('SECTION')
+    })
+
+    it('derives the root ref type from the element rendered with as', () => {
+        const anchorRef = React.createRef<HTMLAnchorElement>()
+        const buttonRef = React.createRef<HTMLButtonElement>()
+
+        render(
+            <Avatar
+                as="a"
+                data-testid="avatar"
+                href="/profile"
+                ref={anchorRef}
+                size={36}
+                name="Jane Doe"
+            />,
+        )
+
+        expect(anchorRef.current).toBe(screen.getByTestId('avatar'))
+
+        const invalidRefElement = (
+            // @ts-expect-error refs must match the element selected with as
+            <Avatar as="a" href="/profile" ref={buttonRef} size={36} name="Jane Doe" />
+        )
+        expect(invalidRefElement).toBeTruthy()
+    })
+
     it('supports rounded shape with size-aware radius', () => {
         render(<Avatar data-testid="avatar" size={50} shape="rounded" name="Design" />)
 

src/avatar/avatar.tsx

@@ -3,6 +3,7 @@ import * as React from 'react'
 import classNames from 'classnames'
 
 import { Box } from '../box'
+import { polymorphicComponent } from '../utils/polymorphism'
 
 import {
     getAvailableImageSources,
@@ -16,8 +17,8 @@ import {
 
 import styles from './avatar.module.css'
 
-import type { ComponentProps } from 'react'
 import type { ObfuscatedClassName } from '../utils/common-types'
+import type { PolymorphicComponentProps } from '../utils/polymorphism'
 import type { AvatarImage, AvatarShape, AvatarSize, ImageSources } from './utils'
 
 type AvatarStyle = React.CSSProperties & {
@@ -28,7 +29,7 @@ type AvatarStyle = React.CSSProperties & {
 /**
  * Props for the `Avatar` component.
  */
-type AvatarProps = ObfuscatedClassName & {
+type AvatarOwnProps = ObfuscatedClassName & {
     /**
      * The rendered avatar size, in CSS pixels.
      */
@@ -69,99 +70,116 @@ type AvatarProps = ObfuscatedClassName & {
      * Test identifier applied to the avatar root element.
      */
     'data-testid'?: string
-} & Omit<ComponentProps<'div'>, 'className' | 'style'>
-
-const AvatarContent = React.forwardRef<HTMLDivElement, AvatarProps>(function AvatarContent(
-    {
-        size,
-        shape = 'circle',
-        name,
-        image,
-        alt,
-        exceptionallySetClassName,
-        'data-testid': testId,
-        'aria-hidden': ariaHidden,
-        'aria-label': ariaLabel,
-        ...restProps
-    },
-    ref,
-) {
-    const imageSources = getSources(image, size)
-    const [failedImageSources, setFailedImageSources] = React.useState<string[]>([])
-    const availableImageSources = getAvailableImageSources(imageSources, failedImageSources)
-    const normalizedName = normalizeAvatarName(name)
-    const initials = availableImageSources ? '' : getInitials(name)
 
-    const hasInitials = initials !== ''
-    const label = ariaLabel ?? alt ?? normalizedName
-    const isDecorative = ariaHidden || label === ''
-    const metaColorIndex = hasInitials ? getAvatarMetaColorIndex(name) : undefined
+    /**
+     * Avatar owns its root sizing styles. Use `exceptionallySetClassName` for the styling escape
+     * hatch.
+     */
+    style?: never
+}
 
-    return (
-        <Box
-            ref={ref}
-            className={classNames(
-                styles.avatar,
-                styles[`shape-${shape}`],
-                metaColorIndex !== undefined && styles[`meta-color-${metaColorIndex}`],
-                !availableImageSources && !hasInitials && styles.empty,
-                exceptionallySetClassName,
-            )}
-            style={getAvatarStyle(size)}
-            data-testid={testId}
-            aria-hidden={isDecorative || undefined}
-            display="inlineFlex"
-            alignItems="center"
-            justifyContent="center"
-            flexShrink={0}
-            overflow="hidden"
-            textAlign="center"
-            {...restProps}
-        >
-            {availableImageSources ? (
-                <img
-                    className={styles.image}
-                    src={availableImageSources.src}
-                    srcSet={availableImageSources.srcSet}
-                    sizes={availableImageSources.sizes}
-                    alt={label ?? ''}
-                    onError={(event) => {
-                        const failedSource = getFailedImageSource(
-                            availableImageSources,
-                            event.currentTarget,
-                        )
-
-                        setFailedImageSources((currentFailedSources) =>
-                            currentFailedSources.includes(failedSource)
-                                ? currentFailedSources
-                                : [...currentFailedSources, failedSource],
-                        )
-                    }}
-                />
-            ) : hasInitials ? (
-                <div
-                    className={styles.initials}
-                    role={label ? 'img' : undefined}
-                    aria-label={label}
-                >
-                    {initials}
-                </div>
-            ) : null}
-        </Box>
-    )
-})
+type AvatarProps<ComponentType extends React.ElementType = 'div'> = PolymorphicComponentProps<
+    ComponentType,
+    AvatarOwnProps,
+    'omitClassName'
+>
+
+const AvatarContent = polymorphicComponent<'div', AvatarOwnProps, 'omitClassName'>(
+    function AvatarContent(
+        {
+            as,
+            size,
+            shape = 'circle',
+            name,
+            image,
+            alt,
+            exceptionallySetClassName,
+            'data-testid': testId,
+            'aria-hidden': ariaHidden,
+            'aria-label': ariaLabel,
+            ...restProps
+        },
+        ref,
+    ) {
+        const imageSources = getSources(image, size)
+        const [failedImageSources, setFailedImageSources] = React.useState<string[]>([])
+        const availableImageSources = getAvailableImageSources(imageSources, failedImageSources)
+        const normalizedName = normalizeAvatarName(name)
+        const initials = availableImageSources ? '' : getInitials(name)
+
+        const hasInitials = initials !== ''
+        const label = ariaLabel ?? alt ?? normalizedName
+        const isDecorative = ariaHidden || label === ''
+        const metaColorIndex = hasInitials ? getAvatarMetaColorIndex(name) : undefined
+
+        return (
+            <Box
+                as={as}
+                ref={ref}
+                className={classNames(
+                    styles.avatar,
+                    styles[`shape-${shape}`],
+                    metaColorIndex !== undefined && styles[`meta-color-${metaColorIndex}`],
+                    !availableImageSources && !hasInitials && styles.empty,
+                    exceptionallySetClassName,
+                )}
+                style={getAvatarStyle(size)}
+                data-testid={testId}
+                aria-hidden={isDecorative || undefined}
+                display="inlineFlex"
+                alignItems="center"
+                justifyContent="center"
+                flexShrink={0}
+                overflow="hidden"
+                textAlign="center"
+                {...restProps}
+            >
+                {availableImageSources ? (
+                    <img
+                        className={styles.image}
+                        src={availableImageSources.src}
+                        srcSet={availableImageSources.srcSet}
+                        sizes={availableImageSources.sizes}
+                        alt={label ?? ''}
+                        onError={(event) => {
+                            const failedSource = getFailedImageSource(
+                                availableImageSources,
+                                event.currentTarget,
+                            )
+
+                            setFailedImageSources((currentFailedSources) =>
+                                currentFailedSources.includes(failedSource)
+                                    ? currentFailedSources
+                                    : [...currentFailedSources, failedSource],
+                            )
+                        }}
+                    />
+                ) : hasInitials ? (
+                    <div
+                        className={styles.initials}
+                        role={label ? 'img' : undefined}
+                        aria-label={label}
+                    >
+                        {initials}
+                    </div>
+                ) : null}
+            </Box>
+        )
+    },
+)
 
 /**
  * Displays an avatar from an image URL, a source map keyed by intrinsic
  * image width, or initials derived from the provided name (with a background
  * color).
  */
-const Avatar = React.forwardRef<HTMLDivElement, AvatarProps>(function Avatar(
-    { image, ...restProps },
+const Avatar = polymorphicComponent<'div', AvatarOwnProps, 'omitClassName'>(function Avatar(
+    { as, image, ...restProps },
     ref,
 ) {
     return (
         <AvatarContent
+            as={as}
             ref={ref}
             // Allows `AvatarContent` to remount when the image map changes,
             // which resets error states

src/utils/polymorphism.ts

@@ -197,5 +197,5 @@ function polymorphicComponent<
     >
 }
 
-export type { PolymorphicComponent }
+export type { PolymorphicComponent, PolymorphicComponentProps }
 export { polymorphicComponent }