feat: add Avatar support for ComboBoxItem and PickerItem

packages/@react-spectrum/s2/chromatic/Combobox.stories.tsx

@@ -10,7 +10,7 @@
  * governing permissions and limitations under the License.
  */
 
-import {AsyncComboBoxStory, AsyncComboBoxStoryType, ContextualHelpExample, CustomWidth, Dynamic, EmptyCombobox, Example, Sections, WithIcons} from '../stories/ComboBox.stories';
+import {AsyncComboBoxStory, AsyncComboBoxStoryType, ContextualHelpExample, CustomWidth, Dynamic, EmptyCombobox, Example, Sections, WithAvatars, WithIcons} from '../stories/ComboBox.stories';
 import {ComboBox} from '../src';
 import {expect} from '@storybook/jest';
 import type {Meta, StoryObj} from '@storybook/react';
@@ -58,6 +58,12 @@ export const Icons: Story = {
   play: Static.play
 };
 
+export const Avatars: Story = {
+  ...WithAvatars,
+  name: 'With Avatars',
+  play: Static.play
+};
+
 export const ContextualHelp: Story = {
   ...ContextualHelpExample,
   play: async ({canvasElement}) => {

packages/@react-spectrum/s2/chromatic/ComboboxRTL.stories.tsx

@@ -23,4 +23,4 @@ const meta: Meta<typeof ComboBox<any>> = {
 };
 
 export default meta;
-export {Static, WithSections, WithDynamic, Icons, ContextualHelp, WithCustomWidth} from './Combobox.stories';
+export {Static, WithSections, WithDynamic, Icons, Avatars, ContextualHelp, WithCustomWidth} from './Combobox.stories';

packages/@react-spectrum/s2/chromatic/Picker.stories.tsx

@@ -10,7 +10,7 @@
  * governing permissions and limitations under the License.
  */
 
-import {AsyncPickerStory, AsyncPickerStoryType, ContextualHelpExample, CustomWidth, Dynamic, Example, Sections, WithIcons} from '../stories/Picker.stories';
+import {AsyncPickerStory, AsyncPickerStoryType, ContextualHelpExample, CustomWidth, Dynamic, Example, Sections, WithAvatars, WithIcons} from '../stories/Picker.stories';
 import {expect} from '@storybook/jest';
 import type {Meta, StoryObj} from '@storybook/react';
 import {Picker} from '../src';
@@ -56,6 +56,12 @@ export const Icons: Story = {
   play: Default.play
 };
 
+export const Avatars: Story = {
+  ...WithAvatars,
+  name: 'With Avatars',
+  play: Default.play
+};
+
 export const WithCustomWidth: Story = {
   ...CustomWidth,
   play: Default.play

packages/@react-spectrum/s2/chromatic/PickerRTL.stories.tsx

@@ -22,4 +22,4 @@ const meta: Meta<typeof Picker<any>> = {
 };
 
 export default meta;
-export {Default, WithSections, DynamicExample, Icons, WithCustomWidth, ContextualHelp} from './Picker.stories';
+export {Default, WithSections, DynamicExample, Icons, Avatars, WithCustomWidth, ContextualHelp} from './Picker.stories';

packages/@react-spectrum/s2/src/Avatar.tsx

@@ -11,7 +11,7 @@
  */
 
 import {ContextValue, SlotProps} from 'react-aria-components';
-import {createContext, forwardRef} from 'react';
+import {createContext, forwardRef, ReactNode} from 'react';
 import {DOMProps, DOMRef, DOMRefValue} from '@react-types/shared';
 import {filterDOMProps} from '@react-aria/utils';
 import {getAllowedOverrides, StylesPropWithoutWidth, UnsafeStyles} from './style-utils' with {type: 'macro'};
@@ -53,13 +53,17 @@ const imageStyles = style({
   }
 }, getAllowedOverrides({width: false}));
 
-export const AvatarContext = createContext<ContextValue<Partial<AvatarProps>, DOMRefValue<HTMLImageElement>>>(null);
+export interface AvatarContextValue extends AvatarProps {
+  render?: (avatar: ReactNode) => ReactNode
+}
+
+export const AvatarContext = createContext<ContextValue<Partial<AvatarContextValue>, DOMRefValue<HTMLImageElement>>>(null);
 
 /**
  * An avatar is a thumbnail representation of an entity, such as a user or an organization.
  */
 export const Avatar = forwardRef(function Avatar(props: AvatarProps, ref: DOMRef<HTMLImageElement>) {
-  [props, ref] = useSpectrumContextProps(props, ref, AvatarContext);
+  [props, ref] = useSpectrumContextProps(props as AvatarContextValue, ref, AvatarContext);
   let domRef = useDOMRef(ref);
   let {
     alt = '',
@@ -71,11 +75,12 @@ export const Avatar = forwardRef(function Avatar(props: AvatarProps, ref: DOMRef
     slot = 'avatar',
     ...otherProps
   } = props;
+  let render = (props as AvatarContextValue).render;
   const domProps = filterDOMProps(otherProps);
 
   let remSize = size / 16 + 'rem';
   let isLarge = size >= 64;
-  return (
+  let image = (
     <Image
       {...domProps}
       ref={domRef}
@@ -90,4 +95,10 @@ export const Avatar = forwardRef(function Avatar(props: AvatarProps, ref: DOMRef
       styles={imageStyles({isOverBackground, isLarge}, props.styles)}
       src={src} />
   );
+
+  if (render) {
+    return render(image);
+  }
+
+  return image;
 });

packages/@react-spectrum/s2/src/ComboBox.tsx

@@ -34,8 +34,9 @@ import {
   Virtualizer
 } from 'react-aria-components';
 import {AsyncLoadable, GlobalDOMAttributes, HelpTextProps, LoadingState, SpectrumLabelableProps} from '@react-types/shared';
+import {AvatarContext} from './Avatar';
 import {BaseCollection, CollectionNode, createLeafComponent} from '@react-aria/collections';
-import {baseColor, edgeToText, focusRing, space, style} from '../style' with {type: 'macro'};
+import {baseColor, edgeToText, focusRing, fontRelative, space, style} from '../style' with {type: 'macro'};
 import {centerBaseline} from './CenterBaseline';
 import {centerPadding, control, controlBorderRadius, controlFont, controlSize, field, fieldInput, getAllowedOverrides, StyleProps} from './style-utils' with {type: 'macro'};
 import {
@@ -306,6 +307,13 @@ const dividerStyle = style({
   width: 'full'
 });
 
+const avatar = style({
+  gridArea: 'icon',
+  marginEnd: 'text-to-visual',
+  marginTop: fontRelative(6), // made up, need feedback
+  alignSelf: 'center'
+});
+
 // Not from any design, just following the sizing of the existing rows
 export const LOADER_ROW_HEIGHTS = {
   S: {
@@ -365,6 +373,13 @@ export interface ComboBoxItemProps extends Omit<ListBoxItemProps, 'children' | '
   children: ReactNode
 }
 
+const avatarSize = {
+  S: 16,
+  M: 20,
+  L: 22,
+  XL: 26
+} as const;
+
 const checkmarkIconSize = {
   S: 'XS',
   M: 'M',
@@ -394,6 +409,11 @@ export function ComboBoxItem(props: ComboBoxItemProps): ReactNode {
                     icon: {render: centerBaseline({slot: 'icon', styles: iconCenterWrapper}), styles: icon}
                   }
                 }],
+                [AvatarContext, {
+                  slots: {
+                    avatar: {size: avatarSize[size], styles: avatar}
+                  }
+                }],
                 [TextContext, {
                   slots: {
                     label: {styles: label({size})},

packages/@react-spectrum/s2/src/Picker.tsx

@@ -33,7 +33,8 @@ import {
   Virtualizer
 } from 'react-aria-components';
 import {AsyncLoadable, FocusableRef, FocusableRefValue, GlobalDOMAttributes, HelpTextProps, LoadingState, PressEvent, RefObject, SpectrumLabelableProps} from '@react-types/shared';
-import {baseColor, edgeToText, focusRing, style} from '../style' with {type: 'macro'};
+import {AvatarContext} from './Avatar';
+import {baseColor, edgeToText, focusRing, fontRelative, style} from '../style' with {type: 'macro'};
 import {box, iconStyles as checkboxIconStyles} from './Checkbox';
 import {centerBaseline} from './CenterBaseline';
 import {
@@ -241,6 +242,16 @@ const iconStyles = style({
   }
 });
 
+const buttonAvatar = style({
+  gridArea: 'icon',
+  marginEnd: 'text-to-visual',
+  alignSelf: 'center'
+});
+
+const itemAvatar = mergeStyles(buttonAvatar, style({
+  marginTop: fontRelative(6) // made up, need feedback
+}));
+
 const loadingWrapperStyles = style({
   gridColumnStart: '1',
   gridColumnEnd: '-1',
@@ -468,6 +479,13 @@ function PickerProgressCircle(props) {
   );
 }
 
+const avatarSize = {
+  S: 16,
+  M: 20,
+  L: 22,
+  XL: 26
+} as const;
+
 interface PickerButtonInnerProps<T extends object> extends PickerStyleProps, Omit<AriaSelectRenderProps, 'isRequired' | 'isFocused'>, Pick<PickerProps<T>, 'loadingState'> {
   loadingCircle: ReactNode,
   buttonRef: RefObject<HTMLButtonElement | null>
@@ -532,6 +550,14 @@ const PickerButton = createHideableComponent(function PickerButton<T extends obj
                           }
                         }
                       }],
+                      [AvatarContext, {
+                        slots: {
+                          avatar: {
+                            render: centerBaseline({slot: 'avatar', styles: iconCenterWrapper}),
+                            size: avatarSize[size ?? 'M'], styles: buttonAvatar
+                          }
+                        }
+                      }],
                       [TextContext, {
                         slots: {
                           description: {},
@@ -606,21 +632,27 @@ export function PickerItem(props: PickerItemProps): ReactNode {
               icon: {render: centerBaseline({slot: 'icon', styles: iconCenterWrapper}), styles: icon}
             }}}>
             <DefaultProvider
-              context={TextContext}
-              value={{
-                slots: {
-                  [DEFAULT_SLOT]: {styles: label({size})},
-                  label: {styles: label({size})},
-                  description: {styles: description({...renderProps, size})}
-                }
-              }}>
-              {renderProps.selectionMode === 'single' && !isLink && <CheckmarkIcon size={checkmarkIconSize[size]} className={checkmark({...renderProps, size})} />}
-              {renderProps.selectionMode === 'multiple' && !isLink && (
-                <div className={mergeStyles(checkbox, box(checkboxRenderProps))}>
-                  <CheckmarkIcon size={size} className={checkboxIconStyles} />
-                </div>
+              context={AvatarContext}
+              value={{slots: {
+                avatar: {size: avatarSize[size], styles: itemAvatar}
+              }}}>
+              <DefaultProvider
+                context={TextContext}
+                value={{
+                  slots: {
+                    [DEFAULT_SLOT]: {styles: label({size})},
+                    label: {styles: label({size})},
+                    description: {styles: description({...renderProps, size})}
+                  }
+                }}>
+                {renderProps.selectionMode === 'single' && !isLink && <CheckmarkIcon size={checkmarkIconSize[size]} className={checkmark({...renderProps, size})} />}
+                {renderProps.selectionMode === 'multiple' && !isLink && (
+                  <div className={mergeStyles(checkbox, box(checkboxRenderProps))}>
+                    <CheckmarkIcon size={size} className={checkboxIconStyles} />
+                  </div>
               )}
-              {typeof children === 'string' ? <Text slot="label">{children}</Text> : children}
+                {typeof children === 'string' ? <Text slot="label">{children}</Text> : children}
+              </DefaultProvider>
             </DefaultProvider>
           </DefaultProvider>
         );

packages/@react-spectrum/s2/src/index.ts

@@ -102,7 +102,7 @@ export type {ActionButtonProps} from './ActionButton';
 export type {ActionButtonGroupProps} from './ActionButtonGroup';
 export type {ActionMenuProps} from './ActionMenu';
 export type {AlertDialogProps} from './AlertDialog';
-export type {AvatarProps} from './Avatar';
+export type {AvatarProps, AvatarContextValue} from './Avatar';
 export type {AvatarGroupProps} from './AvatarGroup';
 export type {BreadcrumbsProps, BreadcrumbProps} from './Breadcrumbs';
 export type {BadgeProps} from './Badge';

packages/@react-spectrum/s2/stories/ComboBox.stories.tsx

@@ -10,7 +10,7 @@
  * governing permissions and limitations under the License.
  */
 
-import {Button, ComboBox, ComboBoxItem, ComboBoxSection, Content, ContextualHelp, Footer, Form, Header, Heading, Link, Text} from '../src';
+import {Avatar, Button, ComboBox, ComboBoxItem, ComboBoxSection, Content, ContextualHelp, Footer, Form, Header, Heading, Link, Text} from '../src';
 import {categorizeArgTypes, getActionArgs} from './utils';
 import {ComboBoxProps} from 'react-aria-components';
 import DeviceDesktopIcon from '../s2wf-icons/S2_Icon_DeviceDesktop_20_N.svg';
@@ -154,6 +154,33 @@ export const WithIcons: Story = {
   }
 };
 
+const SRC_URL_1 = 'https://i.imgur.com/xIe7Wlb.png';
+const SRC_URL_2 = 'https://mir-s3-cdn-cf.behance.net/project_modules/disp/690bc6105945313.5f84bfc9de488.png';
+
+export const WithAvatars: Story = {
+  render: (args) => (
+    <ComboBox {...args}>
+      <ComboBoxItem textValue="User One">
+        <Avatar slot="avatar" src={SRC_URL_1} />
+        <Text slot="label">User One</Text>
+        <Text slot="description">user.one@example.com</Text>
+      </ComboBoxItem>
+      <ComboBoxItem textValue="User Two">
+        <Avatar slot="avatar" src={SRC_URL_2} />
+        <Text slot="label">User Two</Text>
+        <Text slot="description">user.two@example.com<br />123-456-7890</Text>
+      </ComboBoxItem>
+      <ComboBoxItem textValue="User Three">
+        <Avatar slot="avatar" src={SRC_URL_2} />
+        <Text slot="label">User Three</Text>
+      </ComboBoxItem>
+    </ComboBox>
+  ),
+  args: {
+    label: 'Share'
+  }
+};
+
 export const Validation: Story = {
   render: (args) => (
     <Form>

packages/@react-spectrum/s2/stories/Picker.stories.tsx

@@ -11,6 +11,7 @@
  */
 
 import {
+  Avatar,
   Button,
   Content,
   ContextualHelp,
@@ -142,6 +143,33 @@ export const WithIcons: Story = {
   }
 };
 
+const SRC_URL_1 = 'https://i.imgur.com/xIe7Wlb.png';
+const SRC_URL_2 = 'https://mir-s3-cdn-cf.behance.net/project_modules/disp/690bc6105945313.5f84bfc9de488.png';
+
+export const WithAvatars: Story = {
+  render: (args) => (
+    <Picker {...args}>
+      <PickerItem textValue="User One">
+        <Avatar slot="avatar" src={SRC_URL_1} />
+        <Text slot="label">User One</Text>
+        <Text slot="description">user.one@example.com</Text>
+      </PickerItem>
+      <PickerItem textValue="User Two">
+        <Avatar slot="avatar" src={SRC_URL_2} />
+        <Text slot="label">User Two</Text>
+        <Text slot="description">user.two@example.com<br />123-456-7890</Text>
+      </PickerItem>
+      <PickerItem textValue="User Three">
+        <Avatar slot="avatar" src={SRC_URL_2} />
+        <Text slot="label">User Three</Text>
+      </PickerItem>
+    </Picker>
+  ),
+  args: {
+    label: 'Share'
+  }
+};
+
 function VirtualizedPicker(props) {
   let items: IExampleItem[] = [];
   for (let i = 0; i < 10000; i++) {

packages/dev/s2-docs/pages/s2/ComboBox.mdx

@@ -53,7 +53,7 @@ function Example() {
 
 ### Slots
 
-`ComboBoxItem` supports icons, and `label` and `description` text slots.
+`ComboBoxItem` supports icons, avatars, and `label` and `description` text slots.
 
 ```tsx render
 "use client";
@@ -83,6 +83,30 @@ import UserSettings from '@react-spectrum/s2/icons/UserSettings';
 </ComboBox>
 ```
 
+```tsx render
+"use client";
+import {Avatar, ComboBox, ComboBoxItem, Text} from '@react-spectrum/s2';
+
+const users = Array.from({length: 10}, (_, i) => ({
+  id: `user${i + 1}`,
+  name: `User ${i + 1}`,
+  email: `user${i + 1}@example.com`,
+  avatar: 'https://i.imgur.com/kJOwAdv.png'
+}));
+
+<ComboBox label="Share" items={users}>
+  {(item) => (
+    <ComboBoxItem id={item.id} textValue={item.name}>
+      {/*- begin highlight -*/}
+      <Avatar slot="avatar" src={item.avatar} />
+      {/*- end highlight -*/}
+      <Text slot="label">{item.name}</Text>
+      <Text slot="description">{item.email}</Text>
+    </ComboBoxItem>
+  )}
+</ComboBox>
+```
+
 <InlineAlert variant="notice">
   <Heading>Accessibility</Heading>
   <Content>Interactive elements (e.g. buttons) within picker items are not allowed. This will break keyboard and screen reader navigation. Only add textual or decorative graphics (e.g. icons) as children.</Content>