@coze-arch/cli 0.0.1-alpha.3002ee → 0.0.1-alpha.3260db

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

@@ -0,0 +1,7 @@
+export { default as Skeleton } from './skeleton';
+export { skeletonClassNames } from './skeleton.styles';
+export type {
+  SkeletonAnimation,
+  SkeletonAnimationContextValue,
+  SkeletonProps,
+} from './skeleton.types';

package/lib/__templates__/expo/client/heroui/components/skeleton/linear-gradient.tsx

@@ -0,0 +1,45 @@
+import React from 'react';
+import { StyleSheet } from 'react-native';
+import Svg, { Defs, LinearGradient, Rect, Stop } from 'react-native-svg';
+import { colorKit } from '../../helpers/external/utils';
+import { DISPLAY_NAME } from './skeleton.constants';
+
+const LinearGradientComponent: React.FC<{ colors?: string[] }> = ({
+  colors = ['transparent', 'rgba(255, 255, 255, 0.5)', 'transparent'],
+}) => {
+  const gradientId = colors.join('-');
+
+  return (
+    <Svg style={StyleSheet.absoluteFill}>
+      <Defs>
+        <LinearGradient id={gradientId} x1={0} y1={0.5} x2={1} y2={0.5}>
+          {colors.map((color, index) => {
+            const isTransparent = color === 'transparent';
+            const processedColor = isTransparent ? '#FFFFFF' : color;
+            const opacity = isTransparent ? 0 : colorKit.getAlpha(color);
+
+            return (
+              <Stop
+                key={index}
+                offset={`${(index / (colors.length - 1)) * 100}%`}
+                stopColor={processedColor}
+                stopOpacity={opacity}
+              />
+            );
+          })}
+        </LinearGradient>
+      </Defs>
+      <Rect
+        x="0"
+        y="0"
+        width="100%"
+        height="100%"
+        fill={`url(#${gradientId})`}
+      />
+    </Svg>
+  );
+};
+
+LinearGradientComponent.displayName = DISPLAY_NAME.LINEAR_GRADIENT;
+
+export default LinearGradientComponent;

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

@@ -0,0 +1,350 @@
+import { useEffect, useMemo } from 'react';
+import type { SharedValue } from 'react-native-reanimated';
+import {
+  cancelAnimation,
+  Easing,
+  FadeIn,
+  FadeOut,
+  interpolate,
+  ReduceMotion,
+  useAnimatedStyle,
+  withRepeat,
+  withTiming,
+} from 'react-native-reanimated';
+import { useUniwind } from 'uniwind';
+import { useThemeColor } from '../../helpers/external/hooks';
+import { colorKit } from '../../helpers/external/utils';
+import { useAnimationSettings } from '../../helpers/internal/contexts';
+import { useCombinedAnimationDisabledState } from '../../helpers/internal/hooks';
+import {
+  createContext,
+  getAnimationState,
+  getAnimationValueProperty,
+  getIsAnimationDisabledValue,
+  getRootAnimationState,
+} from '../../helpers/internal/utils';
+import {
+  DEFAULT_EASING,
+  DEFAULT_PULSE_DURATION,
+  DEFAULT_PULSE_MAX_OPACITY,
+  DEFAULT_PULSE_MIN_OPACITY,
+  DEFAULT_SHIMMER_DURATION,
+  DEFAULT_SPEED,
+} from './skeleton.constants';
+import type {
+  SkeletonAnimation,
+  SkeletonAnimationContextValue,
+  SkeletonRootAnimation,
+} from './skeleton.types';
+
+const [SkeletonAnimationProvider, useSkeletonAnimation] =
+  createContext<SkeletonAnimationContextValue>({
+    name: 'SkeletonAnimationContext',
+  });
+
+export { SkeletonAnimationProvider, useSkeletonAnimation };
+
+// --------------------------------------------------
+
+/**
+ * Animation hook for Skeleton root component
+ * Handles entering/exiting animations, cascades animation disabled state, and manages progress animation
+ */
+export function useSkeletonRootAnimation(options: {
+  animation: SkeletonRootAnimation | undefined;
+  isLoading: boolean;
+  variant: SkeletonAnimation;
+  progress: SharedValue<number>;
+}) {
+  const { animation, isLoading, variant, progress } = options;
+
+  const { isAnimationDisabled: isAnimationDisabledFromRoot } =
+    getRootAnimationState(animation);
+  const isAllAnimationsDisabledFromRoot =
+    useCombinedAnimationDisabledState(animation);
+  const isAllAnimationsDisabled =
+    isAllAnimationsDisabledFromRoot || isAnimationDisabledFromRoot;
+
+  const enteringAnimation = useMemo(() => {
+    return typeof animation === 'object' ? animation?.entering : undefined;
+  }, [animation]);
+
+  const exitingAnimation = useMemo(() => {
+    return typeof animation === 'object' ? animation?.exiting : undefined;
+  }, [animation]);
+
+  const shimmerAnimation = useMemo(() => {
+    return typeof animation === 'object' ? animation?.shimmer : undefined;
+  }, [animation]);
+
+  const pulseAnimation = useMemo(() => {
+    return typeof animation === 'object' ? animation?.pulse : undefined;
+  }, [animation]);
+
+  const {
+    animationConfig: enteringAnimationConfig,
+    isAnimationDisabled: isEnteringAnimationDisabled,
+  } = getAnimationState(enteringAnimation);
+
+  const {
+    animationConfig: exitingAnimationConfig,
+    isAnimationDisabled: isExitingAnimationDisabled,
+  } = getAnimationState(exitingAnimation);
+
+  const { animationConfig: shimmerAnimationConfig } =
+    getAnimationState(shimmerAnimation);
+
+  const { animationConfig: pulseAnimationConfig } =
+    getAnimationState(pulseAnimation);
+
+  const isEnteringAnimationDisabledValue = getIsAnimationDisabledValue({
+    isAnimationDisabled: isEnteringAnimationDisabled,
+    isAllAnimationsDisabled,
+  });
+
+  const isExitingAnimationDisabledValue = getIsAnimationDisabledValue({
+    isAnimationDisabled: isExitingAnimationDisabled,
+    isAllAnimationsDisabled,
+  });
+
+  const enteringValue = getAnimationValueProperty({
+    animationValue: enteringAnimationConfig,
+    property: 'value',
+    defaultValue: FadeIn,
+  });
+
+  const exitingValue = getAnimationValueProperty({
+    animationValue: exitingAnimationConfig,
+    property: 'value',
+    defaultValue: FadeOut,
+  });
+
+  // Extract shimmer animation configuration for progress animation
+  const shimmerDuration = getAnimationValueProperty({
+    animationValue: shimmerAnimationConfig,
+    property: 'duration',
+    defaultValue: DEFAULT_SHIMMER_DURATION,
+  });
+
+  const shimmerSpeed = getAnimationValueProperty({
+    animationValue: shimmerAnimationConfig,
+    property: 'speed',
+    defaultValue: DEFAULT_SPEED,
+  });
+
+  const shimmerEasing = getAnimationValueProperty({
+    animationValue: shimmerAnimationConfig,
+    property: 'easing',
+    defaultValue: DEFAULT_EASING,
+  });
+
+  // Extract pulse animation configuration for progress animation
+  const pulseDuration = getAnimationValueProperty({
+    animationValue: pulseAnimationConfig,
+    property: 'duration',
+    defaultValue: DEFAULT_PULSE_DURATION,
+  });
+
+  const pulseEasing = getAnimationValueProperty({
+    animationValue: pulseAnimationConfig,
+    property: 'easing',
+    defaultValue: Easing.inOut(Easing.ease),
+  });
+
+  // Handle progress animation
+  useEffect(() => {
+    if (isLoading && variant !== 'none' && !isAllAnimationsDisabled) {
+      progress.set(0);
+
+      if (variant === 'shimmer') {
+        progress.value = withRepeat(
+          withTiming(1, {
+            duration: shimmerDuration / shimmerSpeed,
+            easing: shimmerEasing,
+          }),
+          -1,
+          false,
+          undefined,
+          ReduceMotion.System
+        );
+      } else if (variant === 'pulse') {
+        progress.value = withRepeat(
+          withTiming(1, {
+            duration: pulseDuration,
+            easing: pulseEasing,
+          }),
+          -1,
+          true,
+          undefined,
+          ReduceMotion.System
+        );
+      }
+    } else {
+      cancelAnimation(progress);
+      progress.set(0);
+    }
+
+    return () => {
+      cancelAnimation(progress);
+    };
+  }, [
+    isLoading,
+    variant,
+    progress,
+    shimmerDuration,
+    shimmerEasing,
+    shimmerSpeed,
+    pulseDuration,
+    pulseEasing,
+    isAllAnimationsDisabled,
+  ]);
+
+  return {
+    isAllAnimationsDisabled,
+    entering: isEnteringAnimationDisabledValue ? undefined : enteringValue,
+    exiting: isExitingAnimationDisabledValue ? undefined : exitingValue,
+  };
+}
+
+// --------------------------------------------------
+
+/**
+ * Animation hook for Skeleton shimmer component
+ * Handles shimmer animation configuration and animated styles
+ */
+export function useSkeletonShimmerAnimation(options: {
+  animation: SkeletonRootAnimation | undefined;
+}) {
+  const { animation } = options;
+
+  const { componentWidth, offset, progress, screenWidth } =
+    useSkeletonAnimation();
+
+  const { theme } = useUniwind();
+  const themeColorBackground = useThemeColor('background');
+
+  const { isAllAnimationsDisabled } = useAnimationSettings();
+
+  const shimmerAnimation = useMemo(() => {
+    return typeof animation === 'object' ? animation?.shimmer : undefined;
+  }, [animation]);
+
+  const { animationConfig, isAnimationDisabled } =
+    getAnimationState(shimmerAnimation);
+
+  const isAnimationDisabledValue = getIsAnimationDisabledValue({
+    isAnimationDisabled,
+    isAllAnimationsDisabled,
+  });
+
+  // Calculate default highlight color based on theme
+  const defaultHighlightColor = useMemo(() => {
+    return theme === 'dark'
+      ? colorKit
+          .setAlpha(
+            colorKit.increaseBrightness(themeColorBackground, 10).hex(),
+            0.1
+          )
+          .hex()
+      : colorKit
+          .setAlpha(
+            colorKit.decreaseBrightness(themeColorBackground, 10).hex(),
+            0.75
+          )
+          .hex();
+  }, [theme, themeColorBackground]);
+
+  const shimmerHighlightColor =
+    animationConfig?.highlightColor ?? defaultHighlightColor;
+
+  const gradientColors = useMemo(
+    () => ['transparent', shimmerHighlightColor, 'transparent'],
+    [shimmerHighlightColor]
+  );
+
+  const rContainerStyle = useAnimatedStyle(() => {
+    if (isAnimationDisabledValue || componentWidth === 0) {
+      return {
+        transform: [{ translateX: 0 }],
+      };
+    }
+
+    const translateX = interpolate(
+      progress.get(),
+      [0, 1],
+      [-(componentWidth + offset), screenWidth]
+    );
+
+    return {
+      transform: [{ translateX }],
+    };
+  });
+
+  return {
+    rContainerStyle,
+    gradientColors,
+  };
+}
+
+// --------------------------------------------------
+
+/**
+ * Animation hook for Skeleton pulse component
+ * Handles pulse animation configuration and animated styles
+ */
+export function useSkeletonPulseAnimation(options: {
+  animation: SkeletonRootAnimation | undefined;
+}) {
+  const { animation } = options;
+
+  const { variant, progress } = useSkeletonAnimation();
+
+  const { isAllAnimationsDisabled } = useAnimationSettings();
+
+  const pulseAnimation = useMemo(() => {
+    return typeof animation === 'object' ? animation?.pulse : undefined;
+  }, [animation]);
+
+  const { animationConfig, isAnimationDisabled } =
+    getAnimationState(pulseAnimation);
+
+  const isAnimationDisabledValue = getIsAnimationDisabledValue({
+    isAnimationDisabled,
+    isAllAnimationsDisabled,
+  });
+
+  // Pulse animation configuration
+  const pulseMinOpacity = getAnimationValueProperty({
+    animationValue: animationConfig,
+    property: 'minOpacity',
+    defaultValue: DEFAULT_PULSE_MIN_OPACITY,
+  });
+
+  const pulseMaxOpacity = getAnimationValueProperty({
+    animationValue: animationConfig,
+    property: 'maxOpacity',
+    defaultValue: DEFAULT_PULSE_MAX_OPACITY,
+  });
+
+  const rContainerStyle = useAnimatedStyle(() => {
+    if (isAnimationDisabledValue || variant !== 'pulse') {
+      return {
+        opacity: 1,
+      };
+    }
+
+    const opacity = interpolate(
+      progress.get(),
+      [0, 1],
+      [pulseMinOpacity, pulseMaxOpacity]
+    );
+
+    return {
+      opacity,
+    };
+  });
+
+  return {
+    rContainerStyle,
+  };
+}

package/lib/__templates__/expo/client/heroui/components/skeleton/skeleton.constants.ts

@@ -0,0 +1,39 @@
+import { Easing } from 'react-native-reanimated';
+
+/**
+ * Display name constants for the Skeleton component
+ */
+export const DISPLAY_NAME = {
+  SKELETON: 'HeroUINative.Skeleton',
+  LINEAR_GRADIENT: 'HeroUINative.Skeleton.LinearGradient',
+};
+
+/**
+ * Default shimmer animation duration in milliseconds
+ */
+export const DEFAULT_SHIMMER_DURATION = 1500;
+
+/**
+ * Default pulse animation duration in milliseconds
+ */
+export const DEFAULT_PULSE_DURATION = 1000;
+
+/**
+ * Default easing function for animations
+ */
+export const DEFAULT_EASING = Easing.linear;
+
+/**
+ * Default minimum opacity for pulse animation
+ */
+export const DEFAULT_PULSE_MIN_OPACITY = 0.5;
+
+/**
+ * Default maximum opacity for pulse animation
+ */
+export const DEFAULT_PULSE_MAX_OPACITY = 1;
+
+/**
+ * Default animation speed multiplier
+ */
+export const DEFAULT_SPEED = 1;

package/lib/__templates__/expo/client/heroui/components/skeleton/skeleton.md

@@ -0,0 +1,208 @@
+# Skeleton
+
+Displays a loading placeholder with shimmer or pulse animation effects.
+
+## Import
+
+```tsx
+import { Skeleton } from '@/heroui';
+```
+
+## Anatomy
+
+The Skeleton component is a simple wrapper that renders a placeholder for content that is loading. It does not have any child components.
+
+```tsx
+<Skeleton />
+```
+
+## Usage
+
+### Basic Usage
+
+The Skeleton component creates an animated placeholder while content is loading.
+
+```tsx
+<Skeleton className="h-20 w-full rounded-lg" />
+```
+
+### With Content
+
+Show skeleton while loading, then display content when ready.
+
+```tsx
+<Skeleton isLoading={isLoading} className="h-20 rounded-lg">
+  <View className="h-20 bg-primary rounded-lg">
+    <Text>Loaded Content</Text>
+  </View>
+</Skeleton>
+```
+
+### Animation Variants
+
+Control the animation style with the `variant` prop.
+
+```tsx
+<Skeleton variant="shimmer" className="h-20 w-full rounded-lg" />
+<Skeleton variant="pulse" className="h-20 w-full rounded-lg" />
+<Skeleton variant="none" className="h-20 w-full rounded-lg" />
+```
+
+### Custom Shimmer Configuration
+
+Customize the shimmer effect with duration, speed, and highlight color.
+
+```tsx
+<Skeleton
+  className="h-16 w-full rounded-lg"
+  variant="shimmer"
+  animation={{
+    shimmer: {
+      duration: 2000,
+      speed: 2,
+      highlightColor: 'rgba(59, 130, 246, 0.3)',
+    },
+  }}
+>
+  ...
+</Skeleton>
+```
+
+### Custom Pulse Configuration
+
+Configure pulse animation with duration and opacity range.
+
+```tsx
+<Skeleton
+  className="h-16 w-full rounded-lg"
+  variant="pulse"
+  animation={{
+    pulse: {
+      duration: 500,
+      minOpacity: 0.1,
+      maxOpacity: 0.8,
+    },
+  }}
+>
+  ...
+</Skeleton>
+```
+
+### Shape Variations
+
+Create different skeleton shapes using className for styling.
+
+```tsx
+<Skeleton className="h-4 w-full rounded-md" />
+<Skeleton className="h-4 w-3/4 rounded-md" />
+<Skeleton className="h-4 w-1/2 rounded-md" />
+<Skeleton className="size-12 rounded-full" />
+```
+
+### Custom Enter/Exit Animations
+
+Apply custom Reanimated transitions when skeleton appears or disappears.
+
+```tsx
+<Skeleton
+  entering={FadeIn.duration(300)}
+  exiting={FadeOut.duration(300)}
+  isLoading={isLoading}
+  className="h-20 w-full rounded-lg"
+>
+  ...
+</Skeleton>
+```
+
+## Example
+
+```tsx
+import { Avatar, Card, Skeleton } from '@/heroui';
+import { useState } from 'react';
+import { Image, Text, View } from 'react-native';
+
+export default function SkeletonExample() {
+  const [isLoading, setIsLoading] = useState(true);
+
+  return (
+    <Card className="p-4">
+      <View className="flex-row items-center gap-3 mb-4">
+        <Skeleton isLoading={isLoading} className="h-10 w-10 rounded-full">
+          <Avatar size="sm" alt="Avatar">
+            <Avatar.Image source={{ uri: 'https://i.pravatar.cc/150?img=4' }} />
+            <Avatar.Fallback />
+          </Avatar>
+        </Skeleton>
+
+        <View className="flex-1 gap-1">
+          <Skeleton isLoading={isLoading} className="h-3 w-32 rounded-md">
+            <Text className="font-semibold text-foreground">John Doe</Text>
+          </Skeleton>
+          <Skeleton isLoading={isLoading} className="h-3 w-24 rounded-md">
+            <Text className="text-sm text-muted">@johndoe</Text>
+          </Skeleton>
+        </View>
+      </View>
+
+      <Skeleton
+        isLoading={isLoading}
+        className="h-48 w-full rounded-lg"
+        animation={{
+          shimmer: {
+            duration: 1500,
+            speed: 1,
+          },
+        }}
+      >
+        <View className="h-48 bg-surface-tertiary rounded-lg overflow-hidden">
+          <Image
+            source={{
+              uri: 'https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/backgrounds/cards/car1.jpg',
+            }}
+            className="h-full w-full"
+          />
+        </View>
+      </Skeleton>
+    </Card>
+  );
+}
+```
+
+You can find more examples in the [GitHub repository](<https://github.com/heroui-inc/heroui-native/blob/rc/example/src/app/(home)/components/skeleton.tsx>).
+
+## API Reference
+
+### Skeleton
+
+| prop                    | type                             | default     | description                                                  |
+| ----------------------- | -------------------------------- | ----------- | ------------------------------------------------------------ |
+| `children`              | `React.ReactNode`                | -           | Content to show when not loading                             |
+| `isLoading`             | `boolean`                        | `true`      | Whether the skeleton is currently loading                    |
+| `variant`               | `'shimmer' \| 'pulse' \| 'none'` | `'shimmer'` | Animation variant                                            |
+| `animation`             | `SkeletonRootAnimation`          | -           | Animation configuration                                      |
+| `isAnimatedStyleActive` | `boolean`                        | `true`      | Whether animated styles (react-native-reanimated) are active |
+| `className`             | `string`                         | -           | Additional CSS classes for styling                           |
+| `...Animated.ViewProps` | `AnimatedProps<ViewProps>`       | -           | All Reanimated Animated.View props are supported             |
+
+#### SkeletonRootAnimation
+
+Animation configuration for Skeleton component. Can be:
+
+- `false` or `"disabled"`: Disable only root animations
+- `"disable-all"`: Disable all animations including children
+- `true` or `undefined`: Use default animations
+- `object`: Custom animation configuration
+
+| prop                     | type                                     | default                     | description                                     |
+| ------------------------ | ---------------------------------------- | --------------------------- | ----------------------------------------------- |
+| `state`                  | `'disabled' \| 'disable-all' \| boolean` | -                           | Disable animations while customizing properties |
+| `entering.value`         | `EntryOrExitLayoutType`                  | `FadeIn`                    | Custom entering animation                       |
+| `exiting.value`          | `EntryOrExitLayoutType`                  | `FadeOut`                   | Custom exiting animation                        |
+| `shimmer.duration`       | `number`                                 | `1500`                      | Animation duration in milliseconds              |
+| `shimmer.speed`          | `number`                                 | `1`                         | Speed multiplier for the animation              |
+| `shimmer.highlightColor` | `string`                                 | -                           | Highlight color for the shimmer effect          |
+| `shimmer.easing`         | `EasingFunction`                         | `Easing.linear`             | Easing function for the animation               |
+| `pulse.duration`         | `number`                                 | `1000`                      | Animation duration in milliseconds              |
+| `pulse.minOpacity`       | `number`                                 | `0.5`                       | Minimum opacity value                           |
+| `pulse.maxOpacity`       | `number`                                 | `1`                         | Maximum opacity value                           |
+| `pulse.easing`           | `EasingFunction`                         | `Easing.inOut(Easing.ease)` | Easing function for the animation               |

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

@@ -0,0 +1,49 @@
+import { StyleSheet } from 'react-native';
+import { tv } from 'tailwind-variants';
+import { combineStyles } from '../../helpers/internal/utils';
+
+/**
+ * Main skeleton component styles
+ *
+ * @note ANIMATED PROPERTIES (cannot be set via className):
+ * The following property is animated and cannot be overridden using Tailwind classes:
+ * - `opacity` - Animated for pulse variant transitions (min: 0.5, max: 1)
+ *
+ * Note: The shimmer variant uses an internal overlay with `transform` (translateX) animation, which doesn't affect the className prop.
+ *
+ * To customize these properties, use the `animation` prop on `Skeleton`:
+ * ```tsx
+ * <Skeleton
+ *   variant="pulse"
+ *   animation={{
+ *     pulse: { minOpacity: 0.5, maxOpacity: 1, duration: 1000, easing: Easing.inOut(Easing.ease) }
+ *   }}
+ * />
+ * ```
+ *
+ * For shimmer variant:
+ * ```tsx
+ * <Skeleton
+ *   variant="shimmer"
+ *   animation={{
+ *     shimmer: { duration: 1500, speed: 1, highlightColor: '#ffffff', easing: Easing.linear }
+ *   }}
+ * />
+ * ```
+ *
+ * To completely disable animated styles and apply your own via className or style prop,
+ * set `isAnimatedStyleActive={false}` on `Skeleton`.
+ */
+const root = tv({
+  base: 'bg-muted/30 overflow-hidden',
+});
+
+export const skeletonClassNames = combineStyles({
+  root,
+});
+
+export const skeletonStyleSheet = StyleSheet.create({
+  borderCurve: {
+    borderCurve: 'continuous',
+  },
+});