@erquhart/heroui-native 1.0.0-beta.10.1

package/src/components/accordion/index.ts

@@ -0,0 +1,16 @@
+export {
+  default as Accordion,
+  useAccordion,
+  useAccordionItem,
+} from './accordion';
+export { ACCORDION_LAYOUT_TRANSITION as AccordionLayoutTransition } from './accordion.constants';
+
+export type {
+  AccordionContentProps,
+  AccordionContextValue,
+  AccordionIndicatorProps,
+  AccordionItemProps,
+  AccordionRootProps,
+  AccordionTriggerProps,
+  AccordionVariant,
+} from './accordion.types';

package/src/components/avatar/avatar.animation.ts

@@ -0,0 +1,123 @@
+import {
+  Easing,
+  FadeIn,
+  useAnimatedStyle,
+  withTiming,
+} from 'react-native-reanimated';
+import { useAnimationSettings } from '../../helpers/contexts/animation-settings-context';
+import { useCombinedAnimationDisabledState } from '../../helpers/hooks';
+import type { AnimationRootDisableAll } from '../../helpers/types/animation';
+import {
+  getAnimationState,
+  getAnimationValueMergedConfig,
+  getAnimationValueProperty,
+  getIsAnimationDisabledValue,
+} from '../../helpers/utils/animation';
+import * as AvatarPrimitives from '../../primitives/avatar';
+import type {
+  AvatarFallbackAnimation,
+  AvatarImageAnimation,
+} from './avatar.types';
+
+/**
+ * Animation hook for Avatar root component
+ * Handles root-level animation configuration and provides context for child components
+ */
+export function useAvatarRootAnimation(options: {
+  animation: AnimationRootDisableAll | undefined;
+}) {
+  const { animation } = options;
+
+  const isAllAnimationsDisabled = useCombinedAnimationDisabledState(animation);
+
+  return {
+    isAllAnimationsDisabled,
+  };
+}
+
+/**
+ * Animation hook for Avatar Image component
+ * Handles opacity animation for the avatar image based on loading status
+ */
+export function useAvatarImageAnimation(options: {
+  animation: AvatarImageAnimation | undefined;
+}) {
+  const { animation } = options;
+
+  // Read from global animation context (always available in compound parts)
+  const { isAllAnimationsDisabled } = useAnimationSettings();
+
+  const { status } = AvatarPrimitives.useRootContext();
+
+  const { animationConfig, isAnimationDisabled } = getAnimationState(animation);
+
+  const isAnimationDisabledValue = getIsAnimationDisabledValue({
+    isAnimationDisabled,
+    isAllAnimationsDisabled,
+  });
+
+  // Opacity animation
+  const opacityValue = getAnimationValueProperty({
+    animationValue: animationConfig?.opacity,
+    property: 'value',
+    defaultValue: [0, 1] as [number, number],
+  });
+  const opacityTimingConfig = getAnimationValueMergedConfig({
+    animationValue: animationConfig?.opacity,
+    property: 'timingConfig',
+    defaultValue: { duration: 200, easing: Easing.in(Easing.ease) },
+  });
+
+  const rImageStyle = useAnimatedStyle(() => {
+    const isLoaded = status === 'loaded';
+    const targetOpacity = isLoaded ? opacityValue[1] : opacityValue[0];
+
+    if (isAnimationDisabledValue) {
+      return {
+        opacity: targetOpacity,
+      };
+    }
+
+    return {
+      opacity: withTiming(targetOpacity, opacityTimingConfig),
+    };
+  });
+
+  return {
+    rImageStyle,
+  };
+}
+
+/**
+ * Animation hook for Avatar Fallback component
+ * Handles entering animation for the avatar fallback
+ */
+export function useAvatarFallbackAnimation(options: {
+  animation: AvatarFallbackAnimation | undefined;
+  delayMs?: number;
+}) {
+  const { animation, delayMs } = options;
+
+  // Read from global animation context (always available in compound parts)
+  const { isAllAnimationsDisabled } = useAnimationSettings();
+
+  const { animationConfig, isAnimationDisabled } = getAnimationState(animation);
+
+  const isAnimationDisabledValue = getIsAnimationDisabledValue({
+    isAnimationDisabled,
+    isAllAnimationsDisabled,
+  });
+
+  // Entering animation
+  const enteringValue = getAnimationValueProperty({
+    animationValue: animationConfig?.entering,
+    property: 'value',
+    defaultValue: FadeIn.duration(200)
+      .easing(Easing.in(Easing.ease))
+      .delay(delayMs ?? 0),
+  });
+
+  return {
+    entering: isAnimationDisabledValue ? undefined : enteringValue,
+  };
+}

package/src/components/avatar/avatar.constants.ts

@@ -0,0 +1,19 @@
+import type { AvatarSize } from './avatar.types';
+
+/**
+ * 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: Record<AvatarSize, number> = {
+  sm: 14,
+  md: 16,
+  lg: 20,
+};

package/src/components/avatar/avatar.context.ts

@@ -0,0 +1,11 @@
+import { createContext } from '../../helpers/utils';
+import type { AvatarContextValue } from './avatar.types';
+
+/**
+ * Avatar context provider and hook
+ * Provides size, color, and animation state to child components
+ */
+export const [AvatarProvider, useInnerAvatarContext] =
+  createContext<AvatarContextValue>({
+    name: 'AvatarContext',
+  });

package/src/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.

package/src/components/avatar/avatar.styles.ts

@@ -0,0 +1,153 @@
+import { StyleSheet } from 'react-native';
+import { tv } from 'tailwind-variants';
+import { combineStyles } from '../../helpers/theme/utils/combine-styles';
+
+/**
+ * Avatar root styles
+ */
+const avatarRoot = tv({
+  base: 'items-center justify-center overflow-hidden rounded-full',
+  variants: {
+    variant: {
+      default: 'bg-default',
+      soft: '',
+    },
+    size: {
+      sm: 'size-10',
+      md: 'size-12',
+      lg: 'size-16',
+    },
+    color: {
+      accent: '',
+      default: '',
+      success: '',
+      warning: '',
+      danger: '',
+    },
+  },
+  compoundVariants: [
+    // Soft variant colors
+    {
+      variant: 'soft',
+      color: 'accent',
+      className: 'bg-accent/15',
+    },
+    {
+      variant: 'soft',
+      color: 'default',
+      className: 'bg-default',
+    },
+    {
+      variant: 'soft',
+      color: 'success',
+      className: 'bg-success/15',
+    },
+    {
+      variant: 'soft',
+      color: 'warning',
+      className: 'bg-warning/15',
+    },
+    {
+      variant: 'soft',
+      color: 'danger',
+      className: 'bg-danger/15',
+    },
+  ],
+  defaultVariants: {
+    variant: 'default',
+    size: 'md',
+    color: 'accent',
+  },
+});
+
+/**
+ * Avatar image styles
+ *
+ * @note ANIMATED PROPERTIES (cannot be set via className):
+ * The following property is animated and cannot be overridden using Tailwind classes:
+ * - `opacity` - Animated for image loading transitions (from 0 to 1 when image loads)
+ *
+ * To customize this property, use the `animation` prop on `Avatar.Image`:
+ * ```tsx
+ * <Avatar.Image
+ *   animation={{
+ *     opacity: { value: [0, 1], timingConfig: { duration: 200, easing: Easing.in(Easing.ease) } }
+ *   }}
+ * />
+ * ```
+ *
+ * To completely disable animated styles and apply your own via className or style prop,
+ * set `isAnimatedStyleActive={false}` on `Avatar.Image`.
+ */
+const avatarImage = tv({
+  base: 'h-full w-full',
+});
+
+/**
+ * Avatar fallback styles with slots
+ */
+const avatarFallback = tv({
+  slots: {
+    container: 'h-full w-full items-center justify-center rounded-full',
+    text: 'font-medium',
+  },
+  variants: {
+    size: {
+      sm: {
+        text: 'text-xs',
+      },
+      md: {
+        text: 'text-sm',
+      },
+      lg: {
+        text: 'text-base',
+      },
+    },
+    color: {
+      default: {
+        text: 'text-default-foreground',
+      },
+      accent: {
+        text: 'text-accent',
+      },
+      success: {
+        text: 'text-success',
+      },
+      warning: {
+        text: 'text-warning',
+      },
+      danger: {
+        text: 'text-danger',
+      },
+    },
+  },
+  defaultVariants: {
+    size: 'md',
+    color: 'default',
+  },
+});
+
+/**
+ * Native styles for border curves
+ */
+export const styleSheet = StyleSheet.create({
+  borderCurve: {
+    borderCurve: 'continuous',
+  },
+});
+
+/**
+ * Combined avatar styles
+ */
+const avatarStyles = combineStyles({
+  root: avatarRoot,
+  image: avatarImage,
+  fallback: avatarFallback,
+});
+
+/**
+ * Export slot types for type-safe classNames props
+ */
+export type AvatarFallbackSlots = keyof ReturnType<typeof avatarFallback>;
+
+export default avatarStyles;