@erquhart/heroui-native 1.0.0-beta.10.1

package/lib/module/components/avatar/avatar.constants.js

@@ -0,0 +1,20 @@
+"use strict";
+
+/**
+ * Display names for Avatar components
+ */
+export const AVATAR_DISPLAY_NAME = {
+  ROOT: 'HeroUINative.Avatar',
+  IMAGE: 'HeroUINative.Avatar.Image',
+  FALLBACK: 'HeroUINative.Avatar.Fallback'
+};
+
+/**
+ * Default icon sizes for different avatar sizes
+ */
+export const AVATAR_DEFAULT_ICON_SIZE = {
+  sm: 14,
+  md: 16,
+  lg: 20
+};
+//# sourceMappingURL=avatar.constants.js.map

package/lib/module/components/avatar/avatar.constants.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["AVATAR_DISPLAY_NAME","ROOT","IMAGE","FALLBACK","AVATAR_DEFAULT_ICON_SIZE","sm","md","lg"],"sourceRoot":"../../../../src","sources":["components/avatar/avatar.constants.ts"],"mappings":";;AAEA;AACA;AACA;AACA,OAAO,MAAMA,mBAAmB,GAAG;EACjCC,IAAI,EAAE,qBAAqB;EAC3BC,KAAK,EAAE,2BAA2B;EAClCC,QAAQ,EAAE;AACZ,CAAC;;AAED;AACA;AACA;AACA,OAAO,MAAMC,wBAAoD,GAAG;EAClEC,EAAE,EAAE,EAAE;EACNC,EAAE,EAAE,EAAE;EACNC,EAAE,EAAE;AACN,CAAC","ignoreList":[]}

package/lib/module/components/avatar/avatar.context.js

@@ -0,0 +1,11 @@
+"use strict";
+
+import { createContext } from "../../helpers/utils/index.js";
+/**
+ * Avatar context provider and hook
+ * Provides size, color, and animation state to child components
+ */
+export const [AvatarProvider, useInnerAvatarContext] = createContext({
+  name: 'AvatarContext'
+});
+//# sourceMappingURL=avatar.context.js.map

package/lib/module/components/avatar/avatar.context.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["createContext","AvatarProvider","useInnerAvatarContext","name"],"sourceRoot":"../../../../src","sources":["components/avatar/avatar.context.ts"],"mappings":";;AAAA,SAASA,aAAa,QAAQ,8BAAqB;AAGnD;AACA;AACA;AACA;AACA,OAAO,MAAM,CAACC,cAAc,EAAEC,qBAAqB,CAAC,GAClDF,aAAa,CAAqB;EAChCG,IAAI,EAAE;AACR,CAAC,CAAC","ignoreList":[]}

package/lib/module/components/avatar/avatar.js

@@ -0,0 +1,222 @@
+"use strict";
+
+import { forwardRef, useMemo } from 'react';
+import Animated from 'react-native-reanimated';
+import { HeroText } from "../../helpers/components/index.js";
+import { AnimationSettingsProvider } from "../../helpers/contexts/animation-settings-context.js";
+import { useThemeColor } from "../../helpers/theme/index.js";
+import { childrenToString } from "../../helpers/utils/index.js";
+import * as AvatarPrimitives from "../../primitives/avatar/index.js";
+import { useAvatarFallbackAnimation, useAvatarImageAnimation, useAvatarRootAnimation } from "./avatar.animation.js";
+import { AVATAR_DEFAULT_ICON_SIZE, AVATAR_DISPLAY_NAME } from "./avatar.constants.js";
+import { AvatarProvider, useInnerAvatarContext } from "./avatar.context.js";
+import avatarStyles, { styleSheet } from "./avatar.styles.js";
+import { PersonIcon } from "./person-icon.js";
+import { jsx as _jsx } from "react/jsx-runtime";
+const AnimatedFallback = Animated.createAnimatedComponent(AvatarPrimitives.Fallback);
+
+/**
+ * Hook to access Avatar primitive root context
+ * Provides access to avatar status and other root-level state
+ */
+const useAvatar = AvatarPrimitives.useRootContext;
+
+// --------------------------------------------------
+
+const AvatarRoot = /*#__PURE__*/forwardRef((props, ref) => {
+  const {
+    children,
+    size = 'md',
+    variant = 'default',
+    color = 'accent',
+    className,
+    style,
+    animation,
+    ...restProps
+  } = props;
+  const tvStyles = avatarStyles.root({
+    variant,
+    size,
+    color,
+    className
+  });
+  const {
+    isAllAnimationsDisabled
+  } = useAvatarRootAnimation({
+    animation
+  });
+  const contextValue = useMemo(() => ({
+    size,
+    color
+  }), [size, color]);
+  const animationSettingsContextValue = useMemo(() => ({
+    isAllAnimationsDisabled
+  }), [isAllAnimationsDisabled]);
+  return /*#__PURE__*/_jsx(AnimationSettingsProvider, {
+    value: animationSettingsContextValue,
+    children: /*#__PURE__*/_jsx(AvatarProvider, {
+      value: contextValue,
+      children: /*#__PURE__*/_jsx(AvatarPrimitives.Root, {
+        ref: ref,
+        className: tvStyles,
+        style: [styleSheet.borderCurve, style],
+        ...restProps,
+        children: children
+      })
+    })
+  });
+});
+
+// --------------------------------------------------
+
+const AvatarImage = /*#__PURE__*/forwardRef((props, ref) => {
+  const {
+    className,
+    style: styleProp,
+    source,
+    asChild,
+    ...restProps
+  } = props;
+  const animation = asChild ? undefined : 'animation' in props ? props.animation : undefined;
+  const isAnimatedStyleActive = asChild ? true : 'isAnimatedStyleActive' in props ? props.isAnimatedStyleActive ?? true : true;
+  const {
+    rImageStyle
+  } = useAvatarImageAnimation({
+    animation
+  });
+  const imageClassName = avatarStyles.image({
+    className
+  });
+  const imageStyle = isAnimatedStyleActive ? [rImageStyle, styleProp] : styleProp;
+  if (asChild) {
+    return /*#__PURE__*/_jsx(AvatarPrimitives.Image, {
+      ref: ref,
+      className: imageClassName,
+      ...props
+    });
+  }
+  return /*#__PURE__*/_jsx(AvatarPrimitives.Image, {
+    ref: ref,
+    source: source,
+    asChild: true,
+    children: /*#__PURE__*/_jsx(Animated.Image, {
+      style: imageStyle,
+      className: imageClassName,
+      ...restProps
+    })
+  });
+});
+
+// --------------------------------------------------
+
+const DefaultFallbackIcon = ({
+  sizeVariant,
+  colorVariant,
+  iconProps
+}) => {
+  const [themeColorDefaultForeground, themeColorAccent, themeColorSuccess, themeColorWarning, themeColorDanger] = useThemeColor(['default-foreground', 'accent', 'success', 'warning', 'danger']);
+  const iconSize = iconProps?.size ?? AVATAR_DEFAULT_ICON_SIZE[sizeVariant];
+  const defaultIconColorMap = {
+    default: themeColorDefaultForeground,
+    accent: themeColorAccent,
+    success: themeColorSuccess,
+    warning: themeColorWarning,
+    danger: themeColorDanger
+  };
+  const iconColor = iconProps?.color ?? defaultIconColorMap[colorVariant];
+  return /*#__PURE__*/_jsx(PersonIcon, {
+    size: iconSize,
+    color: iconColor
+  });
+};
+
+// --------------------------------------------------
+
+const AvatarFallback = /*#__PURE__*/forwardRef((props, ref) => {
+  const {
+    size,
+    color: contextColor
+  } = useInnerAvatarContext();
+  const {
+    children,
+    color: colorProp,
+    className,
+    classNames,
+    textProps,
+    iconProps,
+    style,
+    delayMs,
+    animation,
+    ...restProps
+  } = props;
+  const stringifiedChildren = childrenToString(children);
+  const color = colorProp ?? contextColor;
+  const {
+    container,
+    text
+  } = avatarStyles.fallback({
+    size,
+    color
+  });
+  const tvContainerStyles = container({
+    className: [className, classNames?.container]
+  });
+  const tvTextStyles = text({
+    className: [classNames?.text, textProps?.className]
+  });
+  const {
+    entering
+  } = useAvatarFallbackAnimation({
+    animation,
+    delayMs
+  });
+  return /*#__PURE__*/_jsx(AnimatedFallback, {
+    ref: ref,
+    entering: entering,
+    className: tvContainerStyles,
+    style: [styleSheet.borderCurve, style],
+    ...restProps,
+    children: children ? stringifiedChildren ? /*#__PURE__*/_jsx(HeroText, {
+      className: tvTextStyles,
+      ...textProps,
+      children: stringifiedChildren
+    }) : children : /*#__PURE__*/_jsx(DefaultFallbackIcon, {
+      sizeVariant: size,
+      colorVariant: color,
+      iconProps: iconProps
+    })
+  }, AVATAR_DISPLAY_NAME.FALLBACK);
+});
+
+// --------------------------------------------------
+
+AvatarRoot.displayName = AVATAR_DISPLAY_NAME.ROOT;
+AvatarImage.displayName = AVATAR_DISPLAY_NAME.IMAGE;
+AvatarFallback.displayName = AVATAR_DISPLAY_NAME.FALLBACK;
+
+/**
+ * Compound Avatar component with sub-components
+ *
+ * @component Avatar - Main container that manages avatar display state.
+ * Provides color and size context to child components.
+ *
+ * @component Avatar.Image - Optional image component that displays the avatar image.
+ * Handles loading states and errors automatically.
+ *
+ * @component Avatar.Fallback - Optional fallback component shown when image fails to load.
+ * Supports text initials or custom content with optional delay.
+ *
+ * Props flow from Avatar to sub-components via context (size, color).
+ * Fallback can override color with its own prop.
+ *
+ * @see Full documentation: https://heroui.com/components/avatar
+ */
+const Avatar = Object.assign(AvatarRoot, {
+  /** @optional Displays the avatar image with loading state management */
+  Image: AvatarImage,
+  /** @optional Shows fallback content when image is unavailable */
+  Fallback: AvatarFallback
+});
+export default Avatar;
+export { Avatar, useAvatar };
+//# sourceMappingURL=avatar.js.map

package/lib/module/components/avatar/avatar.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["forwardRef","useMemo","Animated","HeroText","AnimationSettingsProvider","useThemeColor","childrenToString","AvatarPrimitives","useAvatarFallbackAnimation","useAvatarImageAnimation","useAvatarRootAnimation","AVATAR_DEFAULT_ICON_SIZE","AVATAR_DISPLAY_NAME","AvatarProvider","useInnerAvatarContext","avatarStyles","styleSheet","PersonIcon","jsx","_jsx","AnimatedFallback","createAnimatedComponent","Fallback","useAvatar","useRootContext","AvatarRoot","props","ref","children","size","variant","color","className","style","animation","restProps","tvStyles","root","isAllAnimationsDisabled","contextValue","animationSettingsContextValue","value","Root","borderCurve","AvatarImage","styleProp","source","asChild","undefined","isAnimatedStyleActive","rImageStyle","imageClassName","image","imageStyle","Image","DefaultFallbackIcon","sizeVariant","colorVariant","iconProps","themeColorDefaultForeground","themeColorAccent","themeColorSuccess","themeColorWarning","themeColorDanger","iconSize","defaultIconColorMap","default","accent","success","warning","danger","iconColor","AvatarFallback","contextColor","colorProp","classNames","textProps","delayMs","stringifiedChildren","container","text","fallback","tvContainerStyles","tvTextStyles","entering","FALLBACK","displayName","ROOT","IMAGE","Avatar","Object","assign"],"sourceRoot":"../../../../src","sources":["components/avatar/avatar.tsx"],"mappings":"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","ignoreList":[]}

package/lib/module/components/avatar/avatar.md

@@ -0,0 +1,376 @@
+# Avatar
+
+Displays a user avatar with support for images, text initials, or fallback icons.
+
+## Imports
+
+Note: Before importing this component, ensure you have completed the setup as per the [Quick Start guide](../../../README.md).
+
+```tsx
+import { Avatar } from 'heroui-native';
+```
+
+## Usage
+
+### Basic Usage
+
+The Avatar component displays a default person icon when no image or text is provided.
+
+```tsx
+<Avatar>
+  <Avatar.Fallback />
+</Avatar>
+```
+
+### With Image
+
+Display an avatar image with automatic fallback handling.
+
+```tsx
+<Avatar>
+  <Avatar.Image source={{ uri: 'https://example.com/avatar.jpg' }} />
+  <Avatar.Fallback>JD</Avatar.Fallback>
+</Avatar>
+```
+
+### With Text Initials
+
+Show text initials as the avatar content.
+
+```tsx
+<Avatar>
+  <Avatar.Fallback>AB</Avatar.Fallback>
+</Avatar>
+```
+
+### With Custom Icon
+
+Provide a custom icon as fallback content.
+
+```tsx
+<Avatar>
+  <Avatar.Fallback>
+    <Ionicons name="person" size={18} />
+  </Avatar.Fallback>
+</Avatar>
+```
+
+### Sizes
+
+Control the avatar size with the size prop.
+
+```tsx
+<Avatar size="sm">
+  <Avatar.Fallback />
+</Avatar>
+
+<Avatar size="md">
+  <Avatar.Fallback />
+</Avatar>
+
+<Avatar size="lg">
+  <Avatar.Fallback />
+</Avatar>
+```
+
+### Variants
+
+Choose between different visual styles with the `variant` prop.
+
+```tsx
+<Avatar variant="default">
+  <Avatar.Fallback>DF</Avatar.Fallback>
+</Avatar>
+
+<Avatar variant="soft">
+  <Avatar.Fallback>SF</Avatar.Fallback>
+</Avatar>
+```
+
+### Colors
+
+Apply different color variants to the avatar.
+
+```tsx
+<Avatar color="default">
+  <Avatar.Fallback>DF</Avatar.Fallback>
+</Avatar>
+
+<Avatar color="accent">
+  <Avatar.Fallback>AC</Avatar.Fallback>
+</Avatar>
+
+<Avatar color="success">
+  <Avatar.Fallback>SC</Avatar.Fallback>
+</Avatar>
+
+<Avatar color="warning">
+  <Avatar.Fallback>WR</Avatar.Fallback>
+</Avatar>
+
+<Avatar color="danger">
+  <Avatar.Fallback>DG</Avatar.Fallback>
+</Avatar>
+```
+
+### Delayed Fallback
+
+Show fallback after a delay to prevent flashing during image load.
+
+```tsx
+<Avatar>
+  <Avatar.Image source={{ uri: imageUrl }} />
+  <Avatar.Fallback delayMs={600}>NA</Avatar.Fallback>
+</Avatar>
+```
+
+### Custom Image Component
+
+Use a custom image component with the asChild prop.
+
+```tsx
+import { Image } from 'expo-image';
+
+<Avatar>
+  <Avatar.Image source={{ uri: imageUrl }} asChild>
+    <Image style={{ width: '100%', height: '100%' }} contentFit="cover" />
+  </Avatar.Image>
+  <Avatar.Fallback>EI</Avatar.Fallback>
+</Avatar>;
+```
+
+### Animation Control
+
+Control animations at different levels of the Avatar component.
+
+#### Disable All Animations
+
+Disable all animations including children from the root component:
+
+```tsx
+<Avatar animation="disable-all">
+  <Avatar.Image source={{ uri: imageUrl }} />
+  <Avatar.Fallback>JD</Avatar.Fallback>
+</Avatar>
+```
+
+#### Custom Image Animation
+
+Customize the image opacity animation:
+
+```tsx
+<Avatar>
+  <Avatar.Image
+    source={{ uri: imageUrl }}
+    animation={{
+      opacity: {
+        value: [0.3, 1],
+        timingConfig: { duration: 300 },
+      },
+    }}
+  />
+  <Avatar.Fallback>JD</Avatar.Fallback>
+</Avatar>
+```
+
+#### Custom Fallback Animation
+
+Customize the fallback entering animation:
+
+```tsx
+import { FadeInDown } from 'react-native-reanimated';
+
+<Avatar>
+  <Avatar.Image source={{ uri: imageUrl }} />
+  <Avatar.Fallback
+    animation={{
+      entering: {
+        value: FadeInDown.duration(400),
+      },
+    }}
+  >
+    JD
+  </Avatar.Fallback>
+</Avatar>;
+```
+
+#### Disable Individual Animations
+
+Disable animations for specific components:
+
+```tsx
+<Avatar>
+  <Avatar.Image source={{ uri: imageUrl }} animation={false} />
+  <Avatar.Fallback animation="disabled">JD</Avatar.Fallback>
+</Avatar>
+```
+
+## Example
+
+```tsx
+import { Avatar } from 'heroui-native';
+import { View } from 'react-native';
+
+export default function AvatarExample() {
+  const users = [
+    { id: 1, image: 'https://example.com/user1.jpg', name: 'John Doe' },
+    { id: 2, image: 'https://example.com/user2.jpg', name: 'Jane Smith' },
+    { id: 3, image: 'https://example.com/user3.jpg', name: 'Bob Johnson' },
+  ];
+
+  return (
+    <View className="flex-row gap-4">
+      {users.map((user) => (
+        <Avatar key={user.id} size="lg" color="accent">
+          <Avatar.Image source={{ uri: user.image }} />
+          <Avatar.Fallback>
+            {user.name
+              .split(' ')
+              .map((n) => n[0])
+              .join('')}
+          </Avatar.Fallback>
+        </Avatar>
+      ))}
+    </View>
+  );
+}
+```
+
+## Anatomy
+
+```tsx
+<Avatar>
+  <Avatar.Image />
+  <Avatar.Fallback />
+</Avatar>
+```
+
+- **Avatar**: Main container that manages avatar display state. Provides size and color context to child components. Supports animation configuration to control all child animations.
+- **Avatar.Image**: Optional image component that displays the avatar image. Handles loading states and errors automatically with opacity-based fade-in animation.
+- **Avatar.Fallback**: Optional fallback component shown when image fails to load or is unavailable. Displays a default person icon when no children are provided. Supports configurable entering animations with delay support.
+
+## API Reference
+
+### Avatar
+
+| prop           | type                                                          | default     | description                                                                               |
+| -------------- | ------------------------------------------------------------- | ----------- | ----------------------------------------------------------------------------------------- |
+| `children`     | `React.ReactNode`                                             | -           | Avatar content (Image and/or Fallback components)                                         |
+| `size`         | `'sm' \| 'md' \| 'lg'`                                        | `'md'`      | Size of the avatar                                                                        |
+| `variant`      | `'default' \| 'soft'`                                         | `'default'` | Visual variant of the avatar                                                              |
+| `color`        | `'default' \| 'accent' \| 'success' \| 'warning' \| 'danger'` | `'accent'`  | Color variant of the avatar                                                               |
+| `className`    | `string`                                                      | -           | Additional CSS classes to apply                                                           |
+| `animation`    | `"disable-all"` \| `undefined`                                | `undefined` | Animation configuration. Use `"disable-all"` to disable all animations including children |
+| `alt`          | `string`                                                      | -           | Alternative text description for accessibility                                            |
+| `...ViewProps` | `ViewProps`                                                   | -           | All standard React Native View props are supported                                        |
+
+### Avatar.Image
+
+Props extend different base types depending on the `asChild` prop value:
+
+- When `asChild={false}` (default): extends `AnimatedProps<ImageProps>` from React Native Reanimated
+- When `asChild={true}`: extends primitive image props for custom image components
+
+**Note:** When using `asChild={true}` with custom image components, the `className` prop may not be applied in some cases depending on the custom component's implementation. Ensure your custom component properly handles style props.
+
+| prop                    | type                                           | default | description                                                  |
+| ----------------------- | ---------------------------------------------- | ------- | ------------------------------------------------------------ |
+| `source`                | `ImageSourcePropType`                          | -       | Image source (required when `asChild={false}`)               |
+| `asChild`               | `boolean`                                      | `false` | Whether to use a custom image component as child             |
+| `className`             | `string`                                       | -       | Additional CSS classes to apply                              |
+| `animation`             | `AvatarImageAnimation`                         | -       | Animation configuration                                      |
+| `isAnimatedStyleActive` | `boolean`                                      | `true`  | Whether animated styles (react-native-reanimated) are active |
+| `...AnimatedProps`      | `AnimatedProps<ImageProps>` or primitive props | -       | Additional props based on `asChild` value                    |
+
+#### AvatarImageAnimation
+
+Animation configuration for avatar image component. Can be:
+
+- `false` or `"disabled"`: Disable all animations
+- `true` or `undefined`: Use default animations
+- `object`: Custom animation configuration
+
+| prop                   | type                          | default                                             | description                                          |
+| ---------------------- | ----------------------------- | --------------------------------------------------- | ---------------------------------------------------- |
+| `state`                | `'disabled' \| boolean`       | -                                                   | Disable animations while customizing properties      |
+| `opacity.value`        | `[number, number]`            | `[0, 1]`                                            | Opacity values [initial, loaded] for image animation |
+| `opacity.timingConfig` | `WithTimingConfig`            | `{ duration: 200, easing: Easing.in(Easing.ease) }` | Animation timing configuration                       |
+
+**Note:** Animation is automatically disabled when `asChild={true}`
+
+### Avatar.Fallback
+
+| prop                    | type                                                          | default               | description                                                                       |
+| ----------------------- | ------------------------------------------------------------- | --------------------- | --------------------------------------------------------------------------------- |
+| `children`              | `React.ReactNode`                                             | -                     | Fallback content (text, icon, or custom element)                                  |
+| `delayMs`               | `number`                                                      | `0`                   | Delay in milliseconds before showing the fallback (applied to entering animation) |
+| `color`                 | `'default' \| 'accent' \| 'success' \| 'warning' \| 'danger'` | inherited from parent | Color variant of the fallback                                                     |
+| `className`             | `string`                                                      | -                     | Additional CSS classes for the container                                          |
+| `classNames`            | `ElementSlots<AvatarFallbackSlots>`                           | -                     | Additional CSS classes for different parts                                        |
+| `textProps`             | `TextProps`                                                   | -                     | Props to pass to Text component when children is a string                         |
+| `iconProps`             | `PersonIconProps`                                             | -                     | Props to customize the default person icon                                        |
+| `animation`             | `AvatarFallbackAnimation`                                     | -                     | Animation configuration                                                           |
+| `...Animated.ViewProps` | `Animated.ViewProps`                                          | -                     | All Reanimated Animated.View props are supported                                  |
+
+**classNames prop:** `ElementSlots<AvatarFallbackSlots>` provides type-safe CSS classes for different parts of the fallback component. Available slots: `container`, `text`.
+
+#### AvatarFallbackAnimation
+
+Animation configuration for avatar fallback component. Can be:
+
+- `false` or `"disabled"`: Disable all animations
+- `true` or `undefined`: Use default animations
+- `object`: Custom animation configuration
+
+| prop             | type                          | default                                                                             | description                            |
+| ---------------- | ----------------------------- | ----------------------------------------------------------------------------------- | -------------------------------------- |
+| `state`          | `'disabled' \| boolean`       | -                                                                                   | Disable animations while customizing properties |
+| `entering.value` | `EntryOrExitLayoutType`       | `FadeIn`<br/>`.duration(200)`<br/>`.easing(Easing.in(Easing.ease))`<br/>`.delay(0)` | Custom entering animation for fallback |
+
+#### PersonIconProps
+
+| prop    | type     | description                           |
+| ------- | -------- | ------------------------------------- |
+| `size`  | `number` | Size of the icon in pixels (optional) |
+| `color` | `string` | Color of the icon (optional)          |
+
+### useAvatar Hook
+
+Hook to access Avatar primitive root context. Provides access to avatar status.
+
+**Note:** The `status` property is particularly useful for adding a skeleton loader while the image is loading.
+
+```tsx
+import { Avatar, useAvatar, Skeleton } from 'heroui-native';
+
+function AvatarWithSkeleton() {
+  return (
+    <Avatar>
+      <Avatar.Image source={{ uri: imageUrl }} />
+      <AvatarContent />
+      <Avatar.Fallback>JD</Avatar.Fallback>
+    </Avatar>
+  );
+}
+
+function AvatarContent() {
+  const { status } = useAvatar();
+
+  if (status === 'loading') {
+    return <Skeleton className="absolute inset-0 rounded-full" />;
+  }
+
+  return null;
+}
+```
+
+| property    | type                                                 | description                                                 |
+| ----------- | ---------------------------------------------------- | ----------------------------------------------------------- |
+| `status`    | `'loading' \| 'loaded' \| 'error'`                   | Current loading state of the avatar image.                  |
+| `setStatus` | `(status: 'loading' \| 'loaded' \| 'error') => void` | Function to manually set the avatar status (advanced usage) |
+
+**Status Values:**
+
+- `'loading'`: Image is currently being loaded. Use this state to show a skeleton loader.
+- `'loaded'`: Image has successfully loaded.
+- `'error'`: Image failed to load or source is invalid. The fallback component is automatically shown in this state.