@idealyst/animate 1.2.29

package/src/useGradientBorder.native.tsx

@@ -0,0 +1,229 @@
+/**
+ * useGradientBorder - Native implementation
+ *
+ * Creates animated gradient border effects using react-native-svg
+ * and Reanimated for performant animations.
+ */
+
+import React, { useMemo, useEffect } from 'react';
+import { View, StyleSheet } from 'react-native';
+import {
+  useSharedValue,
+  useAnimatedProps,
+  withRepeat,
+  withTiming,
+  Easing,
+} from 'react-native-reanimated';
+import Svg, { Defs, LinearGradient, Stop, Rect } from 'react-native-svg';
+import Animated from 'react-native-reanimated';
+import { resolveDuration } from '@idealyst/theme/animation';
+import type { UseGradientBorderOptions, UseGradientBorderResult, AnimatableStyle } from './types';
+
+const AnimatedSvg = Animated.createAnimatedComponent(Svg);
+const AnimatedRect = Animated.createAnimatedComponent(Rect);
+const AnimatedLinearGradient = Animated.createAnimatedComponent(LinearGradient);
+
+/**
+ * Hook that creates an animated gradient border effect.
+ * Uses SVG with Reanimated for smooth animations on native.
+ *
+ * @param options - Configuration for the gradient border
+ * @returns Container and content styles to apply
+ *
+ * @example
+ * ```tsx
+ * const { containerStyle, contentStyle, GradientBorder } = useGradientBorder({
+ *   colors: ['#3b82f6', '#8b5cf6', '#ec4899'],
+ *   borderWidth: 2,
+ *   borderRadius: 8,
+ *   animation: 'spin',
+ *   duration: 2000,
+ * });
+ *
+ * return (
+ *   <View style={containerStyle}>
+ *     <GradientBorder />
+ *     <View style={contentStyle}>
+ *       Content here
+ *     </View>
+ *   </View>
+ * );
+ * ```
+ */
+export function useGradientBorder(options: UseGradientBorderOptions): UseGradientBorderResult & {
+  GradientBorder: React.FC<{ width: number; height: number }>;
+} {
+  const {
+    colors,
+    borderWidth = 2,
+    borderRadius = 8,
+    duration = 2000,
+    animation = 'spin',
+    active = true,
+  } = options;
+
+  const durationMs = resolveDuration(duration);
+
+  // Animation value for rotation (0-360) or progress (0-1)
+  const animationValue = useSharedValue(0);
+
+  // Start animation
+  useEffect(() => {
+    if (!active) {
+      animationValue.value = 0;
+      return;
+    }
+
+    switch (animation) {
+      case 'spin':
+        animationValue.value = withRepeat(
+          withTiming(360, {
+            duration: durationMs,
+            easing: Easing.linear,
+          }),
+          -1, // infinite
+          false // don't reverse
+        );
+        break;
+      case 'pulse':
+        animationValue.value = withRepeat(
+          withTiming(1, {
+            duration: durationMs / 2,
+            easing: Easing.inOut(Easing.ease),
+          }),
+          -1,
+          true // reverse
+        );
+        break;
+      case 'wave':
+        animationValue.value = withRepeat(
+          withTiming(1, {
+            duration: durationMs,
+            easing: Easing.inOut(Easing.ease),
+          }),
+          -1,
+          false
+        );
+        break;
+    }
+  }, [active, animation, durationMs]);
+
+  // Container style
+  const containerStyle = useMemo<AnimatableStyle>(() => {
+    return {
+      position: 'relative',
+      overflow: 'hidden',
+    } as AnimatableStyle;
+  }, []);
+
+  // Content style
+  const contentStyle = useMemo<AnimatableStyle>(() => {
+    return {
+      position: 'absolute',
+      top: borderWidth,
+      left: borderWidth,
+      right: borderWidth,
+      bottom: borderWidth,
+      borderRadius,
+      backgroundColor: 'white', // This should be set by the consumer
+      overflow: 'hidden',
+    } as AnimatableStyle;
+  }, [borderWidth, borderRadius]);
+
+  // Gradient border component
+  const GradientBorder: React.FC<{ width: number; height: number }> = useMemo(() => {
+    return ({ width, height }) => {
+      // Animated props for the gradient
+      const animatedGradientProps = useAnimatedProps(() => {
+        if (animation === 'spin') {
+          // Rotate the gradient
+          const angle = animationValue.value;
+          const radians = (angle * Math.PI) / 180;
+          const x2 = 0.5 + 0.5 * Math.cos(radians);
+          const y2 = 0.5 + 0.5 * Math.sin(radians);
+          const x1 = 1 - x2;
+          const y1 = 1 - y2;
+          return {
+            x1: String(x1),
+            y1: String(y1),
+            x2: String(x2),
+            y2: String(y2),
+          };
+        } else if (animation === 'wave') {
+          // Move gradient position
+          const progress = animationValue.value;
+          return {
+            x1: String(-1 + progress * 2),
+            y1: '0',
+            x2: String(progress * 2),
+            y2: '0',
+          };
+        }
+        return {
+          x1: '0',
+          y1: '0',
+          x2: '1',
+          y2: '1',
+        };
+      });
+
+      const animatedRectProps = useAnimatedProps(() => {
+        if (animation === 'pulse') {
+          const opacity = 0.5 + animationValue.value * 0.5;
+          return { opacity };
+        }
+        return { opacity: 1 };
+      });
+
+      return (
+        <Svg
+          width={width}
+          height={height}
+          style={StyleSheet.absoluteFill}
+        >
+          <Defs>
+            <AnimatedLinearGradient
+              id="gradient"
+              animatedProps={animatedGradientProps}
+            >
+              {colors.map((color, index) => (
+                <Stop
+                  key={index}
+                  offset={`${(index / (colors.length - 1)) * 100}%`}
+                  stopColor={color}
+                />
+              ))}
+            </AnimatedLinearGradient>
+          </Defs>
+          <AnimatedRect
+            x={0}
+            y={0}
+            width={width}
+            height={height}
+            rx={borderRadius + borderWidth}
+            ry={borderRadius + borderWidth}
+            fill="url(#gradient)"
+            animatedProps={animatedRectProps}
+          />
+          {/* Inner cutout (white background) */}
+          <Rect
+            x={borderWidth}
+            y={borderWidth}
+            width={width - borderWidth * 2}
+            height={height - borderWidth * 2}
+            rx={borderRadius}
+            ry={borderRadius}
+            fill="white"
+          />
+        </Svg>
+      );
+    };
+  }, [colors, borderWidth, borderRadius, animation, animationValue]);
+
+  return {
+    containerStyle,
+    contentStyle,
+    isReady: true,
+    GradientBorder,
+  };
+}

package/src/useGradientBorder.ts

@@ -0,0 +1,180 @@
+/**
+ * useGradientBorder - Web implementation
+ *
+ * Creates animated gradient border effects using CSS @property
+ * and conic gradients for performant animations.
+ */
+
+import { useMemo, useEffect, useRef } from 'react';
+import { resolveDuration, injectGradientCSS } from '@idealyst/theme/animation';
+import type { UseGradientBorderOptions, UseGradientBorderResult, AnimatableStyle } from './types';
+
+/**
+ * Hook that creates an animated gradient border effect.
+ * Uses CSS @property for smooth, GPU-accelerated gradient animations.
+ *
+ * @param options - Configuration for the gradient border
+ * @returns Container and content styles to apply
+ *
+ * @example
+ * ```tsx
+ * const { containerStyle, contentStyle, isReady } = useGradientBorder({
+ *   colors: ['#3b82f6', '#8b5cf6', '#ec4899'],
+ *   borderWidth: 2,
+ *   borderRadius: 8,
+ *   animation: 'spin',
+ *   duration: 2000,
+ * });
+ *
+ * return (
+ *   <div style={containerStyle}>
+ *     <div style={contentStyle}>
+ *       Content here
+ *     </div>
+ *   </div>
+ * );
+ * ```
+ */
+export function useGradientBorder(options: UseGradientBorderOptions): UseGradientBorderResult {
+  const {
+    colors,
+    borderWidth = 2,
+    borderRadius = 8,
+    duration = 2000,
+    animation = 'spin',
+    active = true,
+  } = options;
+
+  const isReady = useRef(false);
+  const durationMs = resolveDuration(duration);
+
+  // Inject gradient CSS on first use
+  useEffect(() => {
+    injectGradientCSS();
+    isReady.current = true;
+  }, []);
+
+  // Generate the color string for conic gradient
+  const colorString = useMemo(() => {
+    // For spinning gradient, distribute colors evenly
+    if (animation === 'spin') {
+      return colors.join(', ');
+    }
+    // For pulse/wave, use linear gradient
+    return colors.join(', ');
+  }, [colors, animation]);
+
+  // Container style (the gradient background)
+  const containerStyle = useMemo<AnimatableStyle>(() => {
+    const baseStyle: Record<string, any> = {
+      position: 'relative',
+      padding: borderWidth,
+      borderRadius: borderRadius + borderWidth,
+      overflow: 'hidden',
+    };
+
+    if (!active) {
+      // When inactive, show a solid border color
+      baseStyle.background = colors[0];
+      return baseStyle as AnimatableStyle;
+    }
+
+    switch (animation) {
+      case 'spin':
+        return {
+          ...baseStyle,
+          background: `conic-gradient(from var(--gradient-angle, 0deg), ${colorString})`,
+          animation: `spin-gradient ${durationMs}ms linear infinite`,
+        } as AnimatableStyle;
+
+      case 'pulse':
+        return {
+          ...baseStyle,
+          background: `linear-gradient(135deg, ${colorString})`,
+          animation: `pulse-gradient ${durationMs}ms ease-in-out infinite`,
+        } as AnimatableStyle;
+
+      case 'wave':
+        // Wave uses a moving gradient position
+        return {
+          ...baseStyle,
+          background: `linear-gradient(
+            90deg,
+            ${colors[0]} var(--gradient-position, 0%),
+            ${colors[colors.length - 1]} calc(var(--gradient-position, 0%) + 50%),
+            ${colors[0]} calc(var(--gradient-position, 0%) + 100%)
+          )`,
+          backgroundSize: '200% 100%',
+          animation: `wave-gradient ${durationMs}ms ease-in-out infinite`,
+        } as AnimatableStyle;
+
+      default:
+        return baseStyle as AnimatableStyle;
+    }
+  }, [colors, colorString, borderWidth, borderRadius, durationMs, animation, active]);
+
+  // Content style (the inner container with solid background)
+  const contentStyle = useMemo<AnimatableStyle>(() => {
+    return {
+      borderRadius,
+      backgroundColor: 'inherit',
+      // Ensure content fills the container minus the border
+      width: '100%',
+      height: '100%',
+    } as AnimatableStyle;
+  }, [borderRadius]);
+
+  return {
+    containerStyle,
+    contentStyle,
+    isReady: isReady.current,
+  };
+}
+
+/**
+ * Utility to create inline gradient border styles without the hook.
+ * Useful for static gradient borders or server-side rendering.
+ *
+ * Note: You must call injectGradientCSS() somewhere in your app for animations to work.
+ */
+export function createGradientBorderStyle(
+  colors: string[],
+  borderWidth: number = 2,
+  borderRadius: number = 8,
+  animation: 'spin' | 'pulse' | 'wave' = 'spin',
+  durationMs: number = 2000
+): { container: Record<string, any>; content: Record<string, any> } {
+  const colorString = colors.join(', ');
+
+  const container: Record<string, any> = {
+    position: 'relative',
+    padding: borderWidth,
+    borderRadius: borderRadius + borderWidth,
+    overflow: 'hidden',
+  };
+
+  switch (animation) {
+    case 'spin':
+      container.background = `conic-gradient(from var(--gradient-angle, 0deg), ${colorString})`;
+      container.animation = `spin-gradient ${durationMs}ms linear infinite`;
+      break;
+    case 'pulse':
+      container.background = `linear-gradient(135deg, ${colorString})`;
+      container.animation = `pulse-gradient ${durationMs}ms ease-in-out infinite`;
+      break;
+    case 'wave':
+      container.background = `linear-gradient(90deg, ${colors[0]}, ${colors[colors.length - 1]}, ${colors[0]})`;
+      container.backgroundSize = '200% 100%';
+      container.animation = `wave-gradient ${durationMs}ms ease-in-out infinite`;
+      break;
+  }
+
+  const content = {
+    borderRadius,
+    backgroundColor: 'inherit',
+    width: '100%',
+    height: '100%',
+  };
+
+  return { container, content };
+}

package/src/usePresence.native.ts

@@ -0,0 +1,157 @@
+/**
+ * usePresence - Native implementation
+ *
+ * Manages mount/unmount animations using Reanimated.
+ */
+
+import { useState, useEffect, useRef, useCallback } from 'react';
+import {
+  useSharedValue,
+  useAnimatedStyle,
+  withTiming,
+  withSpring,
+  withDelay,
+  Easing,
+  runOnJS,
+} from 'react-native-reanimated';
+import { timingConfig, springConfig, isSpringEasing, resolveDuration } from '@idealyst/theme/animation';
+import type { UsePresenceOptions, UsePresenceResult, AnimatableStyle } from './types';
+
+/**
+ * Hook that manages presence animations for mount/unmount.
+ * The element stays rendered during exit animation.
+ *
+ * @param isVisible - Whether the element should be visible
+ * @param options - Animation configuration with enter/exit styles
+ * @returns Object with isPresent, style, and exit function
+ *
+ * @example
+ * ```tsx
+ * import Animated from 'react-native-reanimated';
+ *
+ * const { isPresent, style } = usePresence(isOpen, {
+ *   enter: { opacity: 1, transform: [{ translateY: 0 }] },
+ *   exit: { opacity: 0, transform: [{ translateY: -20 }] },
+ *   duration: 'normal',
+ * });
+ *
+ * return isPresent && <Animated.View style={style}>Content</Animated.View>;
+ * ```
+ */
+export function usePresence(isVisible: boolean, options: UsePresenceOptions): UsePresenceResult {
+  const { enter, exit, initial, duration = 'normal', easing = 'easeOut', delay = 0 } = options;
+
+  // Track whether the element should be in the DOM
+  const [isPresent, setIsPresent] = useState(isVisible);
+  // Track initial mount
+  const isInitialMount = useRef(true);
+
+  const durationMs = resolveDuration(duration);
+  const useSpring = isSpringEasing(easing);
+
+  // Shared value for animation progress (0 = exit, 1 = enter)
+  const progress = useSharedValue(isVisible ? 1 : 0);
+
+  // Extract values from enter/exit styles
+  const enterOpacity = enter.opacity ?? 1;
+  const exitOpacity = exit.opacity ?? 0;
+  const initialOpacity = initial?.opacity ?? exitOpacity;
+
+  // Extract transform values
+  const getTransformValue = (
+    style: typeof enter | typeof exit,
+    key: string,
+    defaultValue: number | string
+  ) => {
+    if (!style.transform) return defaultValue;
+    const transform = style.transform.find((t) => key in t);
+    return transform ? (transform as any)[key] : defaultValue;
+  };
+
+  const enterTranslateY = getTransformValue(enter, 'translateY', 0) as number;
+  const exitTranslateY = getTransformValue(exit, 'translateY', 0) as number;
+  const enterTranslateX = getTransformValue(enter, 'translateX', 0) as number;
+  const exitTranslateX = getTransformValue(exit, 'translateX', 0) as number;
+  const enterScale = getTransformValue(enter, 'scale', 1) as number;
+  const exitScale = getTransformValue(exit, 'scale', 1) as number;
+
+  // Animation helper
+  const animateTo = useCallback(
+    (target: number, onComplete?: () => void) => {
+      'worklet';
+      const withCallback = (animation: any) => {
+        if (onComplete) {
+          return {
+            ...animation,
+            callback: (finished: boolean) => {
+              if (finished) {
+                runOnJS(onComplete)();
+              }
+            },
+          };
+        }
+        return animation;
+      };
+
+      if (useSpring) {
+        const config = springConfig(easing as any);
+        return delay > 0
+          ? withDelay(delay, withSpring(target, config, onComplete ? (finished) => finished && runOnJS(onComplete)() : undefined))
+          : withSpring(target, config, onComplete ? (finished) => finished && runOnJS(onComplete)() : undefined);
+      } else {
+        const config = timingConfig(duration, easing);
+        const timingOptions = {
+          duration: config.duration,
+          easing: Easing.bezier(config.easing[0], config.easing[1], config.easing[2], config.easing[3]),
+        };
+        return delay > 0
+          ? withDelay(delay, withTiming(target, timingOptions, onComplete ? (finished) => finished && runOnJS(onComplete)() : undefined))
+          : withTiming(target, timingOptions, onComplete ? (finished) => finished && runOnJS(onComplete)() : undefined);
+      }
+    },
+    [useSpring, easing, duration, delay]
+  );
+
+  // Handle visibility changes
+  useEffect(() => {
+    if (isVisible) {
+      // Entering: mount first, then animate
+      setIsPresent(true);
+      progress.value = animateTo(1);
+    } else if (!isInitialMount.current) {
+      // Exiting: animate, then unmount
+      progress.value = animateTo(0, () => {
+        setIsPresent(false);
+      });
+    }
+
+    isInitialMount.current = false;
+  }, [isVisible]);
+
+  // Manual exit trigger
+  const triggerExit = useCallback(() => {
+    progress.value = animateTo(0, () => {
+      setIsPresent(false);
+    });
+  }, [animateTo]);
+
+  // Animated style
+  const style = useAnimatedStyle(() => {
+    const p = progress.value;
+
+    return {
+      opacity: exitOpacity + (enterOpacity - exitOpacity) * p,
+      transform: [
+        { translateX: exitTranslateX + (enterTranslateX - exitTranslateX) * p },
+        { translateY: exitTranslateY + (enterTranslateY - exitTranslateY) * p },
+        { scale: exitScale + (enterScale - exitScale) * p },
+      ],
+    };
+  });
+
+  return {
+    isPresent,
+    style: style as AnimatableStyle,
+    exit: triggerExit,
+  };
+}