@coze-arch/cli 0.0.10 → 0.0.11

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

@@ -0,0 +1,150 @@
+import { useEffect, useMemo } from 'react';
+import {
+  cancelAnimation,
+  Easing,
+  useAnimatedStyle,
+  useSharedValue,
+  withRepeat,
+  withSequence,
+  withTiming,
+} from 'react-native-reanimated';
+import { useAnimationSettings } from '../../helpers/internal/contexts';
+import { useCombinedAnimationDisabledState } from '../../helpers/internal/hooks';
+import {
+  getAnimationState,
+  getAnimationValueProperty,
+  getIsAnimationDisabledValue,
+  getRootAnimationState,
+} from '../../helpers/internal/utils';
+import {
+  DEFAULT_ROTATION_DURATION,
+  DEFAULT_SPINNER_INDICATOR_ENTERING,
+  DEFAULT_SPINNER_INDICATOR_EXITING,
+} from './spinner.constants';
+import type {
+  SpinnerIndicatorAnimation,
+  SpinnerRootAnimation,
+} from './spinner.types';
+
+// --------------------------------------------------
+
+/**
+ * Animation hook for Spinner root component
+ * Handles entering and exiting animations for the spinner container
+ */
+export function useSpinnerRootAnimation(options: {
+  animation: SpinnerRootAnimation | undefined;
+}) {
+  const { animation } = options;
+
+  const { animationConfig, isAnimationDisabled } =
+    getRootAnimationState(animation);
+
+  const isAllAnimationsDisabled = useCombinedAnimationDisabledState(animation);
+
+  const isAnimationDisabledValue = getIsAnimationDisabledValue({
+    isAnimationDisabled,
+    isAllAnimationsDisabled,
+  });
+
+  // Entering animation
+  const enteringValue = getAnimationValueProperty({
+    animationValue: animationConfig?.entering,
+    property: 'value',
+    defaultValue: DEFAULT_SPINNER_INDICATOR_ENTERING,
+  });
+
+  // Exiting animation
+  const exitingValue = getAnimationValueProperty({
+    animationValue: animationConfig?.exiting,
+    property: 'value',
+    defaultValue: DEFAULT_SPINNER_INDICATOR_EXITING,
+  });
+
+  return {
+    entering: isAnimationDisabledValue ? undefined : enteringValue,
+    exiting: isAnimationDisabledValue ? undefined : exitingValue,
+    isAllAnimationsDisabled,
+  };
+}
+
+// --------------------------------------------------
+
+/**
+ * Animation hook for Spinner Indicator component
+ * Handles rotation animation for the spinner indicator
+ */
+export function useSpinnerIndicatorAnimation(options: {
+  animation: SpinnerIndicatorAnimation | undefined;
+  isLoading: boolean;
+}) {
+  const { animation, isLoading } = options;
+
+  // Read from global animation context (always available in compound parts)
+  const { isAllAnimationsDisabled } = useAnimationSettings();
+
+  const { animationConfig, isAnimationDisabled } = getAnimationState(animation);
+
+  const isAnimationDisabledValue = getIsAnimationDisabledValue({
+    isAnimationDisabled,
+    isAllAnimationsDisabled,
+  });
+
+  // Rotation animation configuration
+  const rotationSpeed = getAnimationValueProperty({
+    animationValue: animationConfig?.rotation,
+    property: 'speed',
+    defaultValue: 1.1,
+  });
+
+  const rotationEasing = getAnimationValueProperty({
+    animationValue: animationConfig?.rotation,
+    property: 'easing',
+    defaultValue: Easing.linear,
+  });
+
+  const rotationTimingConfig = useMemo(() => {
+    return {
+      duration: DEFAULT_ROTATION_DURATION / rotationSpeed,
+      easing: rotationEasing,
+    };
+  }, [rotationSpeed, rotationEasing]);
+
+  const rotation = useSharedValue(0);
+
+  useEffect(() => {
+    if (isLoading) {
+      if (isAnimationDisabledValue) {
+        rotation.set(0);
+      } else {
+        rotation.set(
+          withRepeat(
+            withSequence(withTiming(360, rotationTimingConfig)),
+            -1,
+            false
+          )
+        );
+      }
+    } else {
+      rotation.set(withTiming(0, { duration: 300 }));
+    }
+
+    return () => {
+      cancelAnimation(rotation);
+    };
+  }, [isLoading, isAnimationDisabledValue, rotation, rotationTimingConfig]);
+
+  const rContainerStyle = useAnimatedStyle(() => {
+    return {
+      transform: [
+        {
+          rotate: `${rotation.get()}deg`,
+        },
+      ],
+    };
+  });
+
+  return {
+    rContainerStyle,
+  };
+}

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

@@ -0,0 +1,36 @@
+import { Easing, FadeIn, FadeOut } from 'react-native-reanimated';
+
+/**
+ * Display names for Spinner components
+ */
+export const DISPLAY_NAME = {
+  ROOT: 'HeroUINative.Spinner.Root',
+  INDICATOR: 'HeroUINative.Spinner.Indicator',
+  ICON: 'HeroUINative.Spinner.Icon',
+} as const;
+
+/**
+ * Default animation duration for spinner rotation (in milliseconds)
+ */
+export const DEFAULT_ROTATION_DURATION = 1000;
+
+/**
+ * Size mappings for spinner icon dimensions
+ */
+export const SPINNER_SIZE_MAP = {
+  sm: 16,
+  md: 24,
+  lg: 32,
+} as const;
+
+/**
+ * Default entering animation configuration for spinner indicator
+ */
+export const DEFAULT_SPINNER_INDICATOR_ENTERING = FadeIn.duration(200).easing(
+  Easing.out(Easing.ease)
+);
+
+/**
+ * Default exiting animation configuration for spinner indicator
+ */
+export const DEFAULT_SPINNER_INDICATOR_EXITING = FadeOut.duration(100);

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

@@ -0,0 +1,199 @@
+# Spinner
+
+Displays an animated loading indicator.
+
+## Import
+
+```tsx
+import { Spinner } from '@/heroui';
+```
+
+## Anatomy
+
+```tsx
+<Spinner>
+  <Spinner.Indicator>...</Spinner.Indicator>
+</Spinner>
+```
+
+- **Spinner**: Main container that controls loading state, size, and color. Renders a default animated indicator if no children provided.
+- **Spinner.Indicator**: Optional sub-component for customizing animation configuration and icon appearance. Accepts custom children to replace the default icon.
+
+## Usage
+
+### Basic Usage
+
+The Spinner component displays a rotating loading indicator.
+
+```tsx
+<Spinner />
+```
+
+### Sizes
+
+Control the spinner size with the `size` prop.
+
+```tsx
+<Spinner size="sm" />
+<Spinner size="md" />
+<Spinner size="lg" />
+```
+
+### Colors
+
+Use predefined color variants or custom colors.
+
+```tsx
+<Spinner color="default" />
+<Spinner color="success" />
+<Spinner color="warning" />
+<Spinner color="danger" />
+<Spinner color="#8B5CF6" />
+```
+
+### Loading State
+
+Control the visibility of the spinner with the `isLoading` prop.
+
+```tsx
+<Spinner isLoading={true} />
+<Spinner isLoading={false} />
+```
+
+### Animation Speed
+
+Customize the rotation speed using the `animation` prop on the Indicator component.
+
+```tsx
+<Spinner>
+  <Spinner.Indicator animation={{ rotation: { speed: 0.5 } }} />
+</Spinner>
+
+<Spinner>
+  <Spinner.Indicator animation={{ rotation: { speed: 2 } }} />
+</Spinner>
+```
+
+### Custom Icon
+
+Replace the default spinner icon with custom content.
+
+```tsx
+const themeColorForeground = useThemeColor('foreground')
+
+<Spinner>
+  <Spinner.Indicator>
+    <Ionicons name="refresh" size={24} color={themeColorForeground} />
+  </Spinner.Indicator>
+</Spinner>
+
+<Spinner>
+  <Spinner.Indicator>
+    <Text>⏳</Text>
+  </Spinner.Indicator>
+</Spinner>
+```
+
+## Example
+
+```tsx
+import { Spinner } from '@/heroui';
+import { Ionicons } from '@expo/vector-icons';
+import React from 'react';
+import { Text, TouchableOpacity, View } from 'react-native';
+
+export default function SpinnerExample() {
+  const [isLoading, setIsLoading] = React.useState(true);
+
+  return (
+    <View className="gap-4 p-4 bg-background">
+      <View className="flex-row items-center gap-2 p-4 rounded-lg bg-stone-200">
+        <Spinner size="sm" color="default" />
+        <Text className="text-stone-500">Loading content...</Text>
+      </View>
+
+      <View className="items-center p-8 rounded-2xl bg-stone-200">
+        <Spinner size="lg" color="success" isLoading={isLoading} />
+        <Text className="text-stone-500 mt-4">Processing...</Text>
+        <TouchableOpacity onPress={() => setIsLoading(!isLoading)}>
+          <Text className="text-primary mt-2 text-sm">
+            {isLoading ? 'Tap to stop' : 'Tap to start'}
+          </Text>
+        </TouchableOpacity>
+      </View>
+
+      <View className="flex-row gap-4 items-center justify-center">
+        <Spinner size="md" color="#EC4899">
+          <Spinner.Indicator animation={{ rotation: { speed: 0.7 } }}>
+            <Ionicons name="refresh" size={24} color="#EC4899" />
+          </Spinner.Indicator>
+        </Spinner>
+      </View>
+    </View>
+  );
+}
+```
+
+You can find more examples in the [GitHub repository](<https://github.com/heroui-inc/heroui-native/blob/rc/example/src/app/(home)/components/spinner.tsx>).
+
+## API Reference
+
+### Spinner
+
+| prop           | type                                                        | default     | description                                        |
+| -------------- | ----------------------------------------------------------- | ----------- | -------------------------------------------------- |
+| `children`     | `React.ReactNode`                                           | `undefined` | Content to render inside the spinner               |
+| `size`         | `'sm' \| 'md' \| 'lg'`                                      | `'md'`      | Size of the spinner                                |
+| `color`        | `'default' \| 'success' \| 'warning' \| 'danger' \| string` | `'default'` | Color theme of the spinner                         |
+| `isLoading`    | `boolean`                                                   | `true`      | Whether the spinner is loading                     |
+| `className`    | `string`                                                    | `undefined` | Custom class name for the spinner                  |
+| `animation`    | `SpinnerRootAnimation`                                      | -           | Animation configuration                            |
+| `...ViewProps` | `ViewProps`                                                 | -           | All standard React Native View props are supported |
+
+#### SpinnerRootAnimation
+
+Animation configuration for Spinner 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`<br/>`.duration(200)`<br/>`.easing(Easing.out(Easing.ease))` | Custom entering animation                       |
+| `exiting.value`  | `EntryOrExitLayoutType`                  | `FadeOut`<br/>`.duration(100)`                                       | Custom exiting animation                        |
+
+### Spinner.Indicator
+
+| prop                    | type                        | default     | description                                                  |
+| ----------------------- | --------------------------- | ----------- | ------------------------------------------------------------ |
+| `children`              | `React.ReactNode`           | `undefined` | Content to render inside the indicator                       |
+| `iconProps`             | `SpinnerIconProps`          | `undefined` | Props for the default icon                                   |
+| `className`             | `string`                    | `undefined` | Custom class name for the indicator element                  |
+| `animation`             | `SpinnerIndicatorAnimation` | -           | Animation configuration                                      |
+| `isAnimatedStyleActive` | `boolean`                   | `true`      | Whether animated styles (react-native-reanimated) are active |
+| `...Animated.ViewProps` | `Animated.ViewProps`        | -           | All Reanimated Animated.View props are supported             |
+
+#### SpinnerIndicatorAnimation
+
+Animation configuration for Spinner.Indicator 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 |
+| `rotation.speed`  | `number`                     | `1.1`           | Rotation speed multiplier                       |
+| `rotation.easing` | `WithTimingConfig['easing']` | `Easing.linear` | Animation easing configuration                  |
+
+### SpinnerIconProps
+
+| prop     | type               | default          | description        |
+| -------- | ------------------ | ---------------- | ------------------ |
+| `width`  | `number \| string` | `24`             | Width of the icon  |
+| `height` | `number \| string` | `24`             | Height of the icon |
+| `color`  | `string`           | `'currentColor'` | Color of the icon  |

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

@@ -0,0 +1,44 @@
+import { tv } from 'tailwind-variants';
+import { combineStyles } from '../../helpers/internal/utils';
+
+const root = tv({
+  base: 'items-center justify-center',
+  variants: {
+    size: {
+      sm: 'size-4',
+      md: 'size-6',
+      lg: 'size-8',
+    },
+  },
+  defaultVariants: {
+    size: 'md',
+  },
+});
+
+/**
+ * Indicator style definition
+ *
+ * @note ANIMATED PROPERTIES (cannot be set via className):
+ * The following property is animated and cannot be overridden using Tailwind classes:
+ * - `transform` (specifically `rotate`) - Animated for continuous rotation animation
+ *
+ * To customize this property, use the `animation` prop on `Spinner.Indicator`:
+ * ```tsx
+ * <Spinner.Indicator
+ *   animation={{
+ *     rotation: { speed: 1.1, easing: Easing.linear }
+ *   }}
+ * />
+ * ```
+ *
+ * To completely disable animated styles and apply your own via className or style prop,
+ * set `isAnimatedStyleActive={false}` on `Spinner.Indicator`.
+ */
+const indicator = tv({
+  base: 'size-full items-center justify-center',
+});
+
+export const spinnerClassNames = combineStyles({
+  root,
+  indicator,
+});

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

@@ -0,0 +1,198 @@
+import { forwardRef, useMemo } from 'react';
+import type { View } from 'react-native';
+import Animated from 'react-native-reanimated';
+import { useThemeColor } from '../../helpers/external/hooks';
+import { AnimationSettingsProvider } from '../../helpers/internal/contexts';
+import {
+  createContext,
+  getElementWithDefault,
+} from '../../helpers/internal/utils';
+import * as ActivityIndicatorPrimitives from '../../primitives/activity-indicator';
+import { SpinnerIcon } from './spinner-icon';
+import {
+  useSpinnerIndicatorAnimation,
+  useSpinnerRootAnimation,
+} from './spinner.animation';
+import { DISPLAY_NAME, SPINNER_SIZE_MAP } from './spinner.constants';
+import { spinnerClassNames } from './spinner.styles';
+import type {
+  SpinnerContextValue,
+  SpinnerIndicatorProps,
+  SpinnerProps,
+} from './spinner.types';
+
+const AnimatedRoot = Animated.createAnimatedComponent(
+  ActivityIndicatorPrimitives.Root
+);
+
+const AnimatedIndicator = Animated.createAnimatedComponent(
+  ActivityIndicatorPrimitives.Indicator
+);
+
+const [SpinnerProvider, useSpinnerContext] = createContext<SpinnerContextValue>(
+  {
+    name: 'SpinnerContext',
+  }
+);
+
+const SpinnerRoot = forwardRef<View, SpinnerProps>((props, ref) => {
+  const {
+    children,
+    size = 'md',
+    color = 'default',
+    isLoading = true,
+    className,
+    animation,
+    ...restProps
+  } = props;
+
+  const rootClassName = spinnerClassNames.root({
+    size,
+    className,
+  });
+
+  const { entering, exiting, isAllAnimationsDisabled } =
+    useSpinnerRootAnimation({
+      animation,
+    });
+
+  const indicatorElement = useMemo(
+    () =>
+      getElementWithDefault(
+        children,
+        DISPLAY_NAME.INDICATOR,
+        <SpinnerIndicator />
+      ),
+    [children]
+  );
+
+  const contextValue = useMemo(
+    () => ({
+      size,
+      color,
+      isLoading,
+    }),
+    [size, color, isLoading]
+  );
+
+  const animationSettingsContextValue = useMemo(
+    () => ({
+      isAllAnimationsDisabled,
+    }),
+    [isAllAnimationsDisabled]
+  );
+
+  return (
+    <AnimationSettingsProvider value={animationSettingsContextValue}>
+      <SpinnerProvider value={contextValue}>
+        <AnimatedRoot
+          ref={ref}
+          entering={entering}
+          exiting={exiting}
+          isLoading={isLoading}
+          className={rootClassName}
+          {...restProps}
+        >
+          {children || indicatorElement}
+        </AnimatedRoot>
+      </SpinnerProvider>
+    </AnimationSettingsProvider>
+  );
+});
+
+// --------------------------------------------------
+
+const SpinnerIndicator = forwardRef<View, SpinnerIndicatorProps>(
+  (props, ref) => {
+    const {
+      children,
+      className,
+      style,
+      iconProps,
+      animation,
+      isAnimatedStyleActive = true,
+      ...restProps
+    } = props;
+
+    const { size, color, isLoading } = useSpinnerContext();
+
+    const [
+      themeColorAccent,
+      themeColorSuccess,
+      themeColorWarning,
+      themeColorDanger,
+    ] = useThemeColor(['accent', 'success', 'warning', 'danger']);
+
+    const indicatorClassName = spinnerClassNames.indicator({
+      className,
+    });
+
+    const iconSize = SPINNER_SIZE_MAP[size];
+
+    const colorMap: Record<string, string> = {
+      default: themeColorAccent,
+      success: themeColorSuccess,
+      warning: themeColorWarning,
+      danger: themeColorDanger,
+    };
+
+    const iconColor = colorMap[color] || color;
+
+    const { rContainerStyle } = useSpinnerIndicatorAnimation({
+      animation,
+      isLoading,
+    });
+
+    const indicatorStyle = isAnimatedStyleActive
+      ? [rContainerStyle, style]
+      : style;
+
+    if (!isLoading) {
+      return null;
+    }
+
+    return (
+      <AnimatedIndicator
+        ref={ref}
+        className={indicatorClassName}
+        style={indicatorStyle}
+        {...restProps}
+      >
+        {children || (
+          <SpinnerIcon
+            width={iconProps?.width ?? iconSize}
+            height={iconProps?.height ?? iconSize}
+            color={iconProps?.color ?? iconColor}
+          />
+        )}
+      </AnimatedIndicator>
+    );
+  }
+);
+
+// --------------------------------------------------
+
+SpinnerRoot.displayName = DISPLAY_NAME.ROOT;
+SpinnerIndicator.displayName = DISPLAY_NAME.INDICATOR;
+
+/**
+ * Compound Spinner component with sub-components
+ *
+ * @component Spinner - Main container that controls loading state, size, and color.
+ * Renders a default animated indicator if no children provided.
+ *
+ * @component Spinner.Indicator - Optional sub-component for customizing animation configuration
+ * and icon appearance. Accepts custom children to replace the default icon.
+ * When omitted, Spinner uses a default indicator with standard animation settings.
+ *
+ * Props flow from Spinner to Indicator via context (size, color, isLoading).
+ * The indicator only renders when isLoading is true.
+ *
+ * @see Full documentation: https://v3.heroui.com/docs/native/components/spinner
+ */
+const CompoundSpinner = Object.assign(SpinnerRoot, {
+  /** @optional Customize animation configuration and icon appearance */
+  Indicator: SpinnerIndicator,
+});
+
+export default CompoundSpinner;