@coze-arch/cli 0.0.10 → 0.0.11

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

@@ -0,0 +1,145 @@
+import { StyleSheet } from 'react-native';
+import { tv } from 'tailwind-variants';
+import { combineStyles } from '../../helpers/internal/utils';
+
+/**
+ * Avatar root styles
+ */
+const root = 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 image = tv({
+  base: 'h-full w-full',
+});
+
+/**
+ * Avatar fallback styles with slots
+ */
+const fallback = 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',
+  },
+});
+
+export const avatarClassNames = combineStyles({
+  root,
+  image,
+  fallback,
+});
+
+export const avatarStyleSheet = StyleSheet.create({
+  borderCurve: {
+    borderCurve: 'continuous',
+  },
+});
+
+/**
+ * Export slot types for type-safe classNames props
+ */
+export type AvatarFallbackSlots = keyof ReturnType<typeof fallback>;

package/lib/__templates__/expo/client/heroui/components/avatar/avatar.tsx

@@ -0,0 +1,307 @@
+import { forwardRef, useMemo } from 'react';
+import type { ImageSourcePropType } from 'react-native';
+import Animated from 'react-native-reanimated';
+import { useThemeColor } from '../../helpers/external/hooks';
+import { HeroText } from '../../helpers/internal/components';
+import { AnimationSettingsProvider } from '../../helpers/internal/contexts';
+import { childrenToString } from '../../helpers/internal/utils';
+import * as AvatarPrimitives from '../../primitives/avatar';
+import type { ImageProps } from '../../primitives/avatar/avatar.types';
+import {
+  useAvatarFallbackAnimation,
+  useAvatarImageAnimation,
+  useAvatarRootAnimation,
+} from './avatar.animation';
+import {
+  AVATAR_DEFAULT_ICON_SIZE,
+  AVATAR_DISPLAY_NAME,
+} from './avatar.constants';
+import { AvatarProvider, useInnerAvatarContext } from './avatar.context';
+import { avatarClassNames, avatarStyleSheet } from './avatar.styles';
+import type {
+  AvatarColor,
+  AvatarFallbackProps,
+  AvatarFallbackRef,
+  AvatarImageProps,
+  AvatarImageRef,
+  AvatarRootProps,
+  AvatarRootRef,
+  AvatarSize,
+} from './avatar.types';
+import type { PersonIconProps } from './person-icon';
+import { PersonIcon } from './person-icon';
+
+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 = forwardRef<AvatarRootRef, AvatarRootProps>((props, ref) => {
+  const {
+    children,
+    size = 'md',
+    variant = 'default',
+    color = 'accent',
+    className,
+    style,
+    animation,
+    ...restProps
+  } = props;
+
+  const rootClassName = avatarClassNames.root({
+    variant,
+    size,
+    color,
+    className,
+  });
+
+  const { isAllAnimationsDisabled } = useAvatarRootAnimation({
+    animation,
+  });
+
+  const contextValue = useMemo(
+    () => ({
+      size,
+      color,
+    }),
+    [size, color]
+  );
+
+  const animationSettingsContextValue = useMemo(
+    () => ({
+      isAllAnimationsDisabled,
+    }),
+    [isAllAnimationsDisabled]
+  );
+
+  return (
+    <AnimationSettingsProvider value={animationSettingsContextValue}>
+      <AvatarProvider value={contextValue}>
+        <AvatarPrimitives.Root
+          ref={ref}
+          className={rootClassName}
+          style={[avatarStyleSheet.borderCurve, style]}
+          {...restProps}
+        >
+          {children}
+        </AvatarPrimitives.Root>
+      </AvatarProvider>
+    </AnimationSettingsProvider>
+  );
+});
+
+// --------------------------------------------------
+
+const AvatarImage = forwardRef<AvatarImageRef, AvatarImageProps>(
+  (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 = avatarClassNames.image({
+      className,
+    });
+
+    const imageStyle = isAnimatedStyleActive
+      ? [rImageStyle, styleProp]
+      : styleProp;
+
+    if (asChild) {
+      return (
+        <AvatarPrimitives.Image
+          ref={ref}
+          source={source}
+          className={imageClassName}
+          style={styleProp}
+          asChild
+          {...(restProps as Omit<ImageProps, 'source' | 'style' | 'asChild'>)}
+        />
+      );
+    }
+
+    return (
+      <AvatarPrimitives.Image
+        ref={ref}
+        source={source as ImageSourcePropType}
+        asChild
+      >
+        <Animated.Image
+          style={imageStyle}
+          className={imageClassName}
+          {...restProps}
+        />
+      </AvatarPrimitives.Image>
+    );
+  }
+);
+
+// --------------------------------------------------
+
+const DefaultFallbackIcon = ({ sizeVariant, colorVariant, iconProps }: {
+  sizeVariant: AvatarSize;
+  colorVariant: AvatarColor;
+  iconProps?: PersonIconProps;
+}) => {
+  const [
+    themeColorDefaultForeground,
+    themeColorAccent,
+    themeColorSuccess,
+    themeColorWarning,
+    themeColorDanger,
+  ] = useThemeColor([
+    'default-foreground',
+    'accent',
+    'success',
+    'warning',
+    'danger',
+  ]);
+
+  const iconSize = iconProps?.size ?? AVATAR_DEFAULT_ICON_SIZE[sizeVariant];
+
+  const defaultIconColorMap: Record<AvatarColor, string> = {
+    default: themeColorDefaultForeground,
+    accent: themeColorAccent,
+    success: themeColorSuccess,
+    warning: themeColorWarning,
+    danger: themeColorDanger,
+  };
+
+  const iconColor = iconProps?.color ?? defaultIconColorMap[colorVariant];
+
+  return <PersonIcon size={iconSize} color={iconColor} />;
+};
+
+// --------------------------------------------------
+
+const AvatarFallback = forwardRef<AvatarFallbackRef, AvatarFallbackProps>(
+  (props, ref) => {
+    const { size, color: contextColor } = useInnerAvatarContext();
+
+    const {
+      children,
+      color: colorProp,
+      className,
+      classNames,
+      style,
+      styles,
+      textProps,
+      iconProps,
+      delayMs,
+      animation,
+      ...restProps
+    } = props;
+
+    const stringifiedChildren = childrenToString(children);
+
+    const color = colorProp ?? contextColor;
+
+    const { container, text } = avatarClassNames.fallback({
+      size,
+      color,
+    });
+
+    const fallbackContainerClassName = container({
+      className: [className, classNames?.container],
+    });
+
+    const fallbackTextClassName = text({
+      className: [classNames?.text, textProps?.className],
+    });
+
+    const { entering } = useAvatarFallbackAnimation({
+      animation,
+      delayMs,
+    });
+
+    return (
+      <AnimatedFallback
+        key={AVATAR_DISPLAY_NAME.FALLBACK}
+        ref={ref}
+        entering={entering}
+        className={fallbackContainerClassName}
+        style={[avatarStyleSheet.borderCurve, style, styles?.container]}
+        {...restProps}
+      >
+        {children ? (
+          stringifiedChildren ? (
+            <HeroText
+              className={fallbackTextClassName}
+              style={styles?.text}
+              {...textProps}
+            >
+              {stringifiedChildren}
+            </HeroText>
+          ) : (
+            children
+          )
+        ) : (
+          <DefaultFallbackIcon
+            sizeVariant={size}
+            colorVariant={color}
+            iconProps={iconProps}
+          />
+        )}
+      </AnimatedFallback>
+    );
+  }
+);
+
+// --------------------------------------------------
+
+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://v3.heroui.com/docs/native/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 };

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

@@ -0,0 +1,239 @@
+import type { ImageProps, TextProps, TextStyle, ViewStyle } from 'react-native';
+import type {
+  AnimatedProps,
+  EntryOrExitLayoutType,
+  WithTimingConfig,
+} from 'react-native-reanimated';
+import type {
+  Animation,
+  AnimationRootDisableAll,
+  AnimationValue,
+  ElementSlots,
+} from '../../helpers/internal/types';
+import type {
+  FallbackProps as PrimitiveFallbackProps,
+  FallbackRef as PrimitiveFallbackRef,
+  ImageProps as PrimitiveImageProps,
+  ImageRef as PrimitiveImageRef,
+  RootProps as PrimitiveRootProps,
+  RootRef as PrimitiveRootRef,
+} from '../../primitives/avatar';
+import type { AvatarFallbackSlots } from './avatar.styles';
+import type { PersonIconProps } from './person-icon';
+
+/**
+ * Available sizes for the Avatar component
+ */
+export type AvatarSize = 'sm' | 'md' | 'lg';
+
+/**
+ * Available variants for the Avatar component
+ */
+export type AvatarVariant = 'default' | 'soft';
+
+/**
+ * Available color variants for the Avatar component
+ */
+export type AvatarColor =
+  | 'accent'
+  | 'default'
+  | 'success'
+  | 'warning'
+  | 'danger';
+
+/**
+ * Props for the Avatar root component
+ * Extends primitive root props with styled variants
+ */
+export interface AvatarRootProps extends PrimitiveRootProps {
+  /**
+   * Size of the avatar
+   * @default 'md'
+   */
+  size?: AvatarSize;
+  /**
+   * Visual variant of the avatar
+   * @default 'default'
+   */
+  variant?: AvatarVariant;
+  /**
+   * Color variant of the avatar
+   * @default 'accent'
+   */
+  color?: AvatarColor;
+
+  /**
+   * Additional CSS classes
+   */
+  className?: string;
+
+  /**
+   * Animation configuration for avatar
+   * - `"disable-all"`: Disable all animations including children
+   * - `undefined`: Use default animations
+   */
+  animation?: AnimationRootDisableAll;
+}
+
+/**
+ * Animation configuration for avatar image component
+ */
+export type AvatarImageAnimation = Animation<{
+  opacity?: AnimationValue<{
+    /**
+     * Opacity values [initial, loaded] for image animation
+     * @default [0, 1]
+     */
+    value?: [number, number];
+    /**
+     * Animation timing configuration
+     * @default { duration: 200, easing: Easing.in(Easing.ease) }
+     */
+    timingConfig?: WithTimingConfig;
+  }>;
+}>;
+
+/**
+ * Props for the Avatar image component
+ * Extends primitive image props with styling
+ */
+export type AvatarImageProps =
+  | (AnimatedProps<ImageProps> & {
+      /**
+       * Additional CSS classes
+       *
+       * @note The following style properties are occupied by animations and cannot be set via className:
+       * - `opacity` - Animated for image loading transitions (from 0 to 1 when image loads)
+       *
+       * To customize this property, use the `animation` prop:
+       * ```tsx
+       * <Avatar.Image
+       *   animation={{
+       *     opacity: { value: [0, 1], timingConfig: { duration: 200, easing: Easing.in(Easing.ease) } }
+       *   }}
+       * />
+       * ```
+       *
+       * To completely disable animated styles and use your own via className or style prop, set `isAnimatedStyleActive={false}`.
+       */
+      className?: string;
+      /**
+       * Whether to use the default image directly
+       */
+      asChild?: false;
+      /**
+       * Animation configuration for image
+       * - `false` or `"disabled"`: Disable all animations
+       * - `true` or `undefined`: Use default animations
+       * - `object`: Custom animation configuration
+       */
+      animation?: AvatarImageAnimation;
+      /**
+       * Whether animated styles (react-native-reanimated) are active
+       * When `false`, the animated style is removed and you can implement custom logic
+       * This prop should only be used when you want to write custom styling logic instead of the default animated styles
+       * @default true
+       */
+      isAnimatedStyleActive?: boolean;
+    })
+  | (PrimitiveImageProps & {
+      /**
+       * Additional CSS classes
+       */
+      className?: string;
+      /**
+       * Whether to use the default image directly
+       */
+      asChild: true;
+    });
+
+/**
+ * Animation configuration for avatar fallback component
+ */
+export type AvatarFallbackAnimation = Animation<{
+  entering?: AnimationValue<{
+    /**
+     * Custom entering animation for fallback
+     */
+    value?: EntryOrExitLayoutType;
+  }>;
+}>;
+
+/**
+ * Props for the Avatar fallback component
+ * Extends primitive fallback props with styled variants
+ */
+export interface AvatarFallbackProps
+  extends Omit<AnimatedProps<PrimitiveFallbackProps>, 'entering'> {
+  /**
+   * Delay in milliseconds before the fallback is shown
+   * @default 0
+   */
+  delayMs?: number;
+
+  /**
+   * Color variant of the fallback
+   * Inherits from parent if not specified
+   */
+  color?: AvatarColor;
+
+  /**
+   * Additional CSS classes
+   */
+  className?: string;
+
+  /**
+   * Additional CSS classes for different parts of the fallback
+   */
+  classNames?: ElementSlots<AvatarFallbackSlots>;
+
+  /**
+   * Styles for different parts of the avatar fallback
+   */
+  styles?: {
+    container?: ViewStyle;
+    text?: TextStyle;
+  };
+
+  /**
+   * Props to pass to the Text component when children is a string
+   */
+  textProps?: TextProps;
+
+  /**
+   * Props to pass to the default icon when no children are provided
+   */
+  iconProps?: PersonIconProps;
+
+  /**
+   * Animation configuration for fallback
+   * - `false` or `"disabled"`: Disable all animations
+   * - `true` or `undefined`: Use default animations
+   * - `object`: Custom animation configuration
+   */
+  animation?: AvatarFallbackAnimation;
+}
+
+/**
+ * Context value shared between Avatar components
+ */
+export interface AvatarContextValue {
+  /**
+   * Current size of the avatar
+   */
+  size: AvatarSize;
+
+  /**
+   * Current color variant of the avatar
+   */
+  color: AvatarColor;
+}
+
+/** Reference type for the Avatar root component */
+export type AvatarRootRef = PrimitiveRootRef;
+
+/** Reference type for the Avatar image component */
+export type AvatarImageRef = PrimitiveImageRef;
+
+/** Reference type for the Avatar fallback component */
+export type AvatarFallbackRef = PrimitiveFallbackRef;

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

@@ -0,0 +1,13 @@
+export { default as Avatar, useAvatar } from './avatar';
+export { avatarClassNames } from './avatar.styles';
+export type {
+  AvatarColor,
+  AvatarContextValue,
+  AvatarFallbackProps,
+  AvatarFallbackRef,
+  AvatarImageProps,
+  AvatarImageRef,
+  AvatarRootProps,
+  AvatarRootRef,
+  AvatarSize,
+} from './avatar.types';