feat(avatar): add loading state to avatar and AIConversation (#5777)

Author: dbanksdesign

.changeset/olive-bats-obey.md

@@ -0,0 +1,12 @@
+---
+"@aws-amplify/ui-react-ai": minor
+"@aws-amplify/ui-react": minor
+"@aws-amplify/ui": minor
+---
+
+feat(avatar): add loading state to avatar and AIConversation
+
+
+```jsx
+<Avatar isLoading />
+```

docs/__tests__/__snapshots__/props-table.test.ts.snap

@@ -1123,6 +1123,13 @@ exports[`Props Table 1`] = `
                         "category": "BaseAvatarProps",
                         "isOptional": true
                     },
+                    "isLoading": {
+                        "name": "isLoading",
+                        "type": "boolean | undefined",
+                        "description": "The isLoading property will display a loader around the avatar",
+                        "category": "BaseAvatarProps",
+                        "isOptional": true
+                    },
                     "isDisabled": {
                         "name": "isDisabled",
                         "type": "boolean | undefined",

docs/src/components/ComponentsMetadata.ts

@@ -285,6 +285,11 @@ export const ComponentsMetadata: ComponentClassNameItems = {
     components: ['Avatar'],
     description: 'Class applied to the icon element',
   },
+  AvatarLoader: {
+    className: ComponentClassName.AvatarLoader,
+    components: ['Avatar'],
+    description: 'Class applied to the loader element',
+  },
   Badge: {
     className: ComponentClassName.Badge,
     components: ['Badge'],

docs/src/pages/[platform]/components/avatar/examples/AvatarLoadingExample.tsx

@@ -0,0 +1,11 @@
+import { Avatar, Flex } from '@aws-amplify/ui-react';
+
+export default function AvatarLoadingExample() {
+  return (
+    <Flex>
+      <Avatar isLoading />
+      <Avatar isLoading colorTheme="info" />
+      <Avatar isLoading variation="outlined" colorTheme="success" />
+    </Flex>
+  );
+}

docs/src/pages/[platform]/components/avatar/examples/index.ts

@@ -6,3 +6,4 @@ export { default as AvatarVariationExample } from './AvatarVariationExample';
 export { default as AvatarStyleExample } from './AvatarStyleExample';
 export { default as AvatarThemeExample } from './AvatarThemeExample';
 export { default as AvatarAccessibilityExample } from './AvatarAccessibilityExample';
+export { default as AvatarLoadingExample } from './AvatarLoadingExample';

docs/src/pages/[platform]/components/avatar/react.mdx

@@ -15,6 +15,7 @@ import {
   AvatarStyleExample,
   AvatarThemeExample,
   AvatarAccessibilityExample,
+  AvatarLoadingExample,
 } from './examples';
 
 ## Demo
@@ -89,6 +90,23 @@ Import the Avatar primitive and styles.
   </ExampleCode>
 </Example>
 
+
+### Loading
+
+<Example>
+  <View>
+    <AvatarLoadingExample />
+  </View>
+  
+  <ExampleCode>
+
+```jsx file=./examples/AvatarLoadingExample.tsx
+
+```
+
+  </ExampleCode>
+</Example>
+
 ### Changing the default icon
 
 You can use the `<IconsProvider>` to change the default icon for all Avatars in your application. 

packages/react-ai/src/components/AIConversation/views/default/MessageList.tsx

@@ -14,6 +14,7 @@ import {
   classNameModifier,
   classNames,
 } from '@aws-amplify/ui';
+import { LoadingContext } from '../../context/LoadingContext';
 
 const MessageMeta = ({ message }: { message: ConversationMessage }) => {
   // need to pass this in as props in order for it to be overridable
@@ -34,6 +35,35 @@ const MessageMeta = ({ message }: { message: ConversationMessage }) => {
   );
 };
 
+const LoadingMessage = () => {
+  const avatars = React.useContext(AvatarsContext);
+  const variant = React.useContext(MessageVariantContext);
+  const avatar = avatars?.ai;
+
+  return (
+    <View
+      className={classNames(
+        ComponentClassName.AIConversationMessage,
+        classNameModifier(ComponentClassName.AIConversationMessage, variant),
+        classNameModifier(ComponentClassName.AIConversationMessage, 'assistant')
+      )}
+    >
+      <View className={ComponentClassName.AIConversationMessageAvatar}>
+        <Avatar isLoading>{avatar?.avatar}</Avatar>
+      </View>
+      <View className={ComponentClassName.AIConversationMessageBody}>
+        <View className={ComponentClassName.AIConversationMessageSender}>
+          <Text
+            className={ComponentClassName.AIConversationMessageSenderUsername}
+          >
+            {avatar?.username}
+          </Text>
+        </View>
+      </View>
+    </View>
+  );
+};
+
 const Message = ({ message }: { message: ConversationMessage }) => {
   const avatars = React.useContext(AvatarsContext);
   const variant = React.useContext(MessageVariantContext);
@@ -68,11 +98,13 @@ const Message = ({ message }: { message: ConversationMessage }) => {
 export const MessageList: ControlsContextProps['MessageList'] = ({
   messages,
 }) => {
+  const isLoading = React.useContext(LoadingContext);
   return (
     <View className={ComponentClassName.AIConversationMessageList}>
       {messages.map((message, i) => (
         <Message key={`message-${i}`} message={message} />
       ))}
+      {isLoading ? <LoadingMessage /> : null}
     </View>
   );
 };

packages/react/__tests__/__snapshots__/exports.ts.snap

@@ -1129,6 +1129,9 @@ exports[`primitive catalog should match primitives catalog snapshot 1`] = `
       "isDisabled": {
         "type": "boolean",
       },
+      "isLoading": {
+        "type": "boolean",
+      },
       "left": {
         "type": "string",
       },

packages/react/src/primitives/Avatar/Avatar.tsx

@@ -10,9 +10,20 @@ import { View } from '../View';
 import { IconUser, useIcons } from '../Icon';
 import { Image } from '../Image';
 import { AvatarProps, BaseAvatarProps } from './types';
+import { Loader } from '../Loader';
 
 const AvatarPrimitive: Primitive<AvatarProps, 'span'> = (
-  { className, children, variation, colorTheme, size, src, alt, ...rest },
+  {
+    className,
+    children,
+    variation,
+    colorTheme,
+    size,
+    src,
+    alt,
+    isLoading,
+    ...rest
+  },
   ref
 ) => {
   const icons = useIcons('avatar');
@@ -40,6 +51,9 @@ const AvatarPrimitive: Primitive<AvatarProps, 'span'> = (
           </View>
         )
       )}
+      {isLoading ? (
+        <Loader className={ComponentClassName.AvatarLoader} />
+      ) : null}
     </View>
   );
 };

packages/react/src/primitives/Avatar/types.ts

@@ -37,6 +37,12 @@ export interface BaseAvatarProps extends BaseViewProps {
    * The size property will affect the size of the avatar.
    */
   size?: AvatarSizes;
+
+  /**
+   * @description
+   * The isLoading property will display a loader around the avatar
+   */
+  isLoading?: boolean;
 }
 
 export type AvatarProps<Element extends ElementType = 'span'> = PrimitiveProps<

packages/ui/src/theme/components/avatar.ts

@@ -8,4 +8,11 @@ import {
 
 export type AvatarTheme<Required extends boolean = false> = ComponentStyles &
   Modifiers<Size | ColorTheme | 'filled' | 'outlined', Required> &
-  Elements<{ icon?: ComponentStyles; image?: ComponentStyles }, Required>;
+  Elements<
+    {
+      icon?: ComponentStyles;
+      image?: ComponentStyles;
+      loader?: ComponentStyles;
+    },
+    Required
+  >;

packages/ui/src/theme/css/component/avatar.scss

@@ -10,6 +10,7 @@
 
   --amplify-components-icon-height: 100%;
 
+  position: relative;
   display: inline-flex;
   align-items: center;
   justify-content: center;
@@ -66,6 +67,9 @@
     --avatar-filled-color: var(
       --amplify-components-avatar-warning-background-color
     );
+    --amplify-components-loader-stroke-filled: var(
+      --amplify-components-avatar-warning-color
+    );
   }
 
   &--error {
@@ -80,6 +84,9 @@
     --avatar-filled-color: var(
       --amplify-components-avatar-error-background-color
     );
+    --amplify-components-loader-stroke-filled: var(
+      --amplify-components-avatar-error-color
+    );
   }
 
   &--info {
@@ -94,6 +101,10 @@
     --avatar-filled-color: var(
       --amplify-components-avatar-info-background-color
     );
+
+    --amplify-components-loader-stroke-filled: var(
+      --amplify-components-avatar-info-color
+    );
   }
 
   &--success {
@@ -110,6 +121,10 @@
     --avatar-filled-color: var(
       --amplify-components-avatar-success-background-color
     );
+
+    --amplify-components-loader-stroke-filled: var(
+      --amplify-components-avatar-success-color
+    );
   }
 
   // elements
@@ -126,4 +141,13 @@
     object-fit: cover;
     display: block;
   }
+
+  &__loader {
+    position: absolute;
+    inset: 0;
+    width: 100%;
+    height: 100%;
+    // This will make the empty part of the loader not show up
+    stroke: transparent;
+  }
 }

packages/ui/src/types/primitives/componentClassName.ts

@@ -20,6 +20,7 @@ export const ComponentClassName = {
   Avatar: 'amplify-avatar',
   AvatarIcon: 'amplify-avatar__icon',
   AvatarImage: 'amplify-avatar__image',
+  AvatarLoader: 'amplify-avatar__loader',
   AIConversation: 'amplify-ai-conversation',
   AIConversationAttachment: 'amplify-ai-conversation__attachment',
   AIConversationAttachmentList: 'amplify-ai-conversation__attachment__list',