@coze-arch/cli 0.0.10 → 0.0.11

package/lib/__templates__/expo/client/heroui/components/alert/success-icon.tsx

@@ -0,0 +1,28 @@
+import React from 'react';
+import Svg, { Path } from 'react-native-svg';
+import type { AlertIconProps } from './alert.types';
+
+/**
+ * Success check circle icon for the Alert indicator.
+ * Used for the "success" status value.
+ */
+export const SuccessIcon: React.FC<AlertIconProps> = ({ size = 20, color }) => {
+  return (
+    <Svg
+      width={size}
+      height={size}
+      viewBox="0 0 16 16"
+      fill={color}
+      accessibilityElementsHidden={true}
+      importantForAccessibility="no-hide-descendants"
+    >
+      <Path
+        d="M13.5 8a5.5 5.5 0 1 1-11 0a5.5 5.5 0 0 1 11 0M15 8A7 7 0 1 1 1 8a7 7 0 0 1 14 0m-3.9-1.55a.75.75 0 1 0-1.2-.9L7.419 8.858L6.03 7.47a.75.75 0 0 0-1.06 1.06l2 2a.75.75 0 0 0 1.13-.08z"
+        fillRule="evenodd"
+        clipRule="evenodd"
+      />
+    </Svg>
+  );
+};
+
+SuccessIcon.displayName = 'HeroUINative.Alert.SuccessIcon';

package/lib/__templates__/expo/client/heroui/components/alert/warning-icon.tsx

@@ -0,0 +1,28 @@
+import React from 'react';
+import Svg, { Path } from 'react-native-svg';
+import type { AlertIconProps } from './alert.types';
+
+/**
+ * Warning triangle icon for the Alert indicator.
+ * Used for the "warning" status value.
+ */
+export const WarningIcon: React.FC<AlertIconProps> = ({ size = 20, color }) => {
+  return (
+    <Svg
+      width={size}
+      height={size}
+      viewBox="0 0 16 16"
+      fill={color}
+      accessibilityElementsHidden={true}
+      importantForAccessibility="no-hide-descendants"
+    >
+      <Path
+        d="M7.134 2.994L2.217 11.5a1 1 0 0 0 .866 1.5h9.834a1 1 0 0 0 .866-1.5L8.866 2.993a1 1 0 0 0-1.732 0m3.03-.75c-.962-1.665-3.366-1.665-4.329 0L.918 10.749c-.963 1.666.24 3.751 2.165 3.751h9.834c1.925 0 3.128-2.085 2.164-3.751zM8 5a.75.75 0 0 1 .75.75v2a.75.75 0 0 1-1.5 0v-2A.75.75 0 0 1 8 5m1 5.75a1 1 0 1 1-2 0a1 1 0 0 1 2 0"
+        fillRule="evenodd"
+        clipRule="evenodd"
+      />
+    </Svg>
+  );
+};
+
+WarningIcon.displayName = 'HeroUINative.Alert.WarningIcon';

package/lib/__templates__/expo/client/heroui/components/avatar/avatar.animation.ts

@@ -0,0 +1,123 @@
+import {
+  Easing,
+  FadeIn,
+  useAnimatedStyle,
+  withTiming,
+} from 'react-native-reanimated';
+import { useAnimationSettings } from '../../helpers/internal/contexts';
+import { useCombinedAnimationDisabledState } from '../../helpers/internal/hooks';
+import type { AnimationRootDisableAll } from '../../helpers/internal/types';
+import {
+  getAnimationState,
+  getAnimationValueMergedConfig,
+  getAnimationValueProperty,
+  getIsAnimationDisabledValue,
+} from '../../helpers/internal/utils';
+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/lib/__templates__/expo/client/heroui/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/lib/__templates__/expo/client/heroui/components/avatar/avatar.context.ts

@@ -0,0 +1,11 @@
+import { createContext } from '../../helpers/internal/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/lib/__templates__/expo/client/heroui/components/avatar/avatar.md

@@ -0,0 +1,386 @@
+# Avatar
+
+Displays a user avatar with support for images, text initials, or fallback icons.
+
+## Import
+
+```tsx
+import { Avatar } from '@/heroui';
+```
+
+## 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.
+
+## 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';
+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>
+  );
+}
+```
+
+You can find more examples in the [GitHub repository](<https://github.com/heroui-inc/heroui-native/blob/rc/example/src/app/(home)/components/avatar.tsx>).
+
+## 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                                        |
+| `styles`                | `{ container?: ViewStyle; text?: TextStyle }`                 | -                     | Styles for different parts of the avatar fallback                                 |
+| `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`.
+
+#### `styles`
+
+| prop        | type        | description                 |
+| ----------- | ----------- | --------------------------- |
+| `container` | `ViewStyle` | Styles for the container    |
+| `text`      | `TextStyle` | Styles for the text content |
+
+#### 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)          |
+
+## Hooks
+
+### 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';
+
+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.