@idealyst/animate 1.2.29

package/package.json

@@ -0,0 +1,72 @@
+{
+  "name": "@idealyst/animate",
+  "version": "1.2.29",
+  "description": "Cross-platform animation hooks for React and React Native",
+  "readme": "README.md",
+  "main": "src/index.ts",
+  "module": "src/index.ts",
+  "types": "src/index.ts",
+  "react-native": "src/index.native.ts",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/IdealystIO/idealyst-framework.git",
+    "directory": "packages/animate"
+  },
+  "author": "Idealyst <contact@idealyst.io>",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "exports": {
+    ".": {
+      "react-native": "./src/index.native.ts",
+      "import": "./src/index.ts",
+      "require": "./src/index.ts",
+      "types": "./src/index.ts"
+    }
+  },
+  "scripts": {
+    "prepublishOnly": "echo 'Publishing TypeScript source directly'",
+    "publish:npm": "npm publish"
+  },
+  "peerDependencies": {
+    "@idealyst/theme": "^1.2.29",
+    "react": ">=16.8.0",
+    "react-native": ">=0.60.0",
+    "react-native-reanimated": ">=3.0.0",
+    "react-native-svg": ">=13.0.0"
+  },
+  "peerDependenciesMeta": {
+    "react-native": {
+      "optional": true
+    },
+    "react-native-reanimated": {
+      "optional": true
+    },
+    "react-native-svg": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@idealyst/theme": "^1.2.29",
+    "@types/react": "^19.1.0",
+    "react": "^19.1.0",
+    "react-native": "^0.80.1",
+    "react-native-reanimated": "^4.1.3",
+    "react-native-svg": "^15.14.0",
+    "typescript": "^5.0.0"
+  },
+  "files": [
+    "src",
+    "README.md"
+  ],
+  "keywords": [
+    "react",
+    "react-native",
+    "animation",
+    "hooks",
+    "cross-platform",
+    "reanimated",
+    "css-transitions"
+  ]
+}

package/src/index.native.ts

@@ -0,0 +1,66 @@
+/**
+ * @idealyst/animate - Native exports
+ *
+ * Cross-platform animation hooks for React and React Native.
+ * This module provides a unified API for creating smooth animations
+ * that work on both web and native platforms.
+ *
+ * On native, animations use Reanimated for UI thread performance.
+ *
+ * @example
+ * ```tsx
+ * import Animated from 'react-native-reanimated';
+ * import { useAnimatedStyle, usePresence, useGradientBorder } from '@idealyst/animate';
+ *
+ * // State-driven animations
+ * const style = useAnimatedStyle({
+ *   opacity: isVisible ? 1 : 0,
+ * }, { duration: 'normal', easing: 'easeOut' });
+ *
+ * return <Animated.View style={style}>Content</Animated.View>;
+ *
+ * // Mount/unmount animations
+ * const { isPresent, style } = usePresence(isOpen, {
+ *   enter: { opacity: 1 },
+ *   exit: { opacity: 0 },
+ * });
+ *
+ * // Gradient borders
+ * const { containerStyle, contentStyle, GradientBorder } = useGradientBorder({
+ *   colors: ['#3b82f6', '#8b5cf6'],
+ *   animation: 'spin',
+ * });
+ * ```
+ */
+
+// Type exports
+export type {
+  AnimatableStyle,
+  AnimatableProperties,
+  TransformProperty,
+  AnimationOptions,
+  PlatformOverrides,
+  UseAnimatedStyleOptions,
+  AnimatedValue,
+  InterpolationConfig,
+  SequenceStep,
+  UseSequenceResult,
+  KeyframePercentage,
+  KeyframeDefinition,
+  UseKeyframesOptions,
+  UseKeyframesResult,
+  UsePresenceOptions,
+  UsePresenceResult,
+  GradientAnimation,
+  UseGradientBorderOptions,
+  UseGradientBorderResult,
+} from './types';
+
+// Hook exports (native implementations)
+export { useAnimatedStyle } from './useAnimatedStyle.native';
+export { useAnimatedValue } from './useAnimatedValue.native';
+export { usePresence } from './usePresence.native';
+export { useGradientBorder } from './useGradientBorder.native';
+
+// Re-export animation tokens for convenience
+export { durations, easings, presets } from '@idealyst/theme/animation';

package/src/index.ts

@@ -0,0 +1,64 @@
+/**
+ * @idealyst/animate - Web exports
+ *
+ * Cross-platform animation hooks for React and React Native.
+ * This module provides a unified API for creating smooth animations
+ * that work on both web and native platforms.
+ *
+ * On web, animations use CSS transitions and requestAnimationFrame
+ * for optimal performance.
+ *
+ * @example
+ * ```tsx
+ * import { useAnimatedStyle, usePresence, useGradientBorder } from '@idealyst/animate';
+ *
+ * // State-driven animations
+ * const style = useAnimatedStyle({
+ *   opacity: isVisible ? 1 : 0,
+ * }, { duration: 'normal', easing: 'easeOut' });
+ *
+ * // Mount/unmount animations
+ * const { isPresent, style } = usePresence(isOpen, {
+ *   enter: { opacity: 1 },
+ *   exit: { opacity: 0 },
+ * });
+ *
+ * // Gradient borders
+ * const { containerStyle, contentStyle } = useGradientBorder({
+ *   colors: ['#3b82f6', '#8b5cf6'],
+ *   animation: 'spin',
+ * });
+ * ```
+ */
+
+// Type exports
+export type {
+  AnimatableStyle,
+  AnimatableProperties,
+  TransformProperty,
+  AnimationOptions,
+  PlatformOverrides,
+  UseAnimatedStyleOptions,
+  AnimatedValue,
+  InterpolationConfig,
+  SequenceStep,
+  UseSequenceResult,
+  KeyframePercentage,
+  KeyframeDefinition,
+  UseKeyframesOptions,
+  UseKeyframesResult,
+  UsePresenceOptions,
+  UsePresenceResult,
+  GradientAnimation,
+  UseGradientBorderOptions,
+  UseGradientBorderResult,
+} from './types';
+
+// Hook exports
+export { useAnimatedStyle } from './useAnimatedStyle';
+export { useAnimatedValue } from './useAnimatedValue';
+export { usePresence } from './usePresence';
+export { useGradientBorder, createGradientBorderStyle } from './useGradientBorder';
+
+// Re-export animation tokens for convenience
+export { durations, easings, presets } from '@idealyst/theme/animation';

package/src/types.ts

@@ -0,0 +1,208 @@
+/**
+ * Type definitions for @idealyst/animate
+ */
+
+import type { ViewStyle, TextStyle, ImageStyle } from 'react-native';
+import type { Duration, EasingKey, SpringType } from '@idealyst/theme/animation';
+
+// Style types
+export type AnimatableStyle = ViewStyle | TextStyle | ImageStyle;
+export type StyleValue = string | number | undefined;
+
+// Transform types (React Native style)
+export type TransformProperty =
+  | { perspective: number }
+  | { rotate: string }
+  | { rotateX: string }
+  | { rotateY: string }
+  | { rotateZ: string }
+  | { scale: number }
+  | { scaleX: number }
+  | { scaleY: number }
+  | { translateX: number }
+  | { translateY: number }
+  | { skewX: string }
+  | { skewY: string };
+
+// Animatable properties (subset that can be animated smoothly)
+export interface AnimatableProperties {
+  // Opacity
+  opacity?: number;
+
+  // Background
+  backgroundColor?: string;
+
+  // Border
+  borderColor?: string;
+  borderWidth?: number;
+  borderRadius?: number;
+  borderTopLeftRadius?: number;
+  borderTopRightRadius?: number;
+  borderBottomLeftRadius?: number;
+  borderBottomRightRadius?: number;
+
+  // Dimensions (use sparingly - triggers layout)
+  width?: number | string;
+  height?: number | string;
+  maxHeight?: number | string;
+  maxWidth?: number | string;
+  minHeight?: number | string;
+  minWidth?: number | string;
+
+  // Positioning (use sparingly - triggers layout)
+  top?: number | string;
+  right?: number | string;
+  bottom?: number | string;
+  left?: number | string;
+
+  // Transform (preferred for performance)
+  transform?: TransformProperty[];
+}
+
+// Animation configuration
+export interface AnimationOptions {
+  /** Duration in ms or token key */
+  duration?: Duration;
+  /** Easing function key */
+  easing?: EasingKey;
+  /** Delay before animation starts (ms) */
+  delay?: number;
+}
+
+// Platform-specific overrides
+export interface PlatformOverrides {
+  /** Web-specific options */
+  web?: AnimationOptions & {
+    /** Custom CSS transition string */
+    transition?: string;
+  };
+  /** Native-specific options */
+  native?: AnimationOptions & {
+    /** Use spring animation instead of timing */
+    useSpring?: boolean;
+    /** Spring type if useSpring is true */
+    springType?: SpringType;
+  };
+}
+
+// useAnimatedStyle options
+export interface UseAnimatedStyleOptions extends AnimationOptions, PlatformOverrides {}
+
+// useAnimatedValue return type
+export interface AnimatedValue {
+  /** Current value (for reading) */
+  readonly value: number;
+  /** Set value with animation */
+  set: (target: number, options?: AnimationOptions) => void;
+  /** Set value immediately without animation */
+  setImmediate: (target: number) => void;
+  /** Interpolate value to another range */
+  interpolate: <T extends string | number>(config: InterpolationConfig<T>) => T;
+}
+
+export interface InterpolationConfig<T> {
+  inputRange: number[];
+  outputRange: T[];
+  extrapolate?: 'extend' | 'clamp' | 'identity';
+  extrapolateLeft?: 'extend' | 'clamp' | 'identity';
+  extrapolateRight?: 'extend' | 'clamp' | 'identity';
+}
+
+// useSequence types
+export interface SequenceStep {
+  /** Style properties for this step */
+  style?: AnimatableProperties;
+  /** Duration for this step */
+  duration?: Duration;
+  /** Easing for this step */
+  easing?: EasingKey;
+  /** Delay before this step */
+  delay?: number;
+}
+
+export interface UseSequenceResult {
+  /** Current animated style */
+  style: AnimatableStyle;
+  /** Start/restart the sequence */
+  play: () => void;
+  /** Reset to initial state */
+  reset: () => void;
+  /** Pause animation (web only) */
+  pause: () => void;
+  /** Whether animation is currently playing */
+  isPlaying: boolean;
+}
+
+// useKeyframes types
+export type KeyframePercentage = `${number}%` | 'from' | 'to';
+export type KeyframeDefinition = Partial<Record<KeyframePercentage, AnimatableProperties>>;
+
+export interface UseKeyframesOptions extends AnimationOptions {
+  /** Number of iterations (default: 1) */
+  iterations?: number | 'infinite';
+  /** Animation direction */
+  direction?: 'normal' | 'reverse' | 'alternate' | 'alternate-reverse';
+  /** Fill mode */
+  fillMode?: 'none' | 'forwards' | 'backwards' | 'both';
+  /** Auto-play on mount */
+  autoPlay?: boolean;
+}
+
+export interface UseKeyframesResult {
+  /** Animated style to apply */
+  style: AnimatableStyle;
+  /** Start animation */
+  play: () => void;
+  /** Pause animation */
+  pause: () => void;
+  /** Reset to initial state */
+  reset: () => void;
+  /** Whether animation is playing */
+  isPlaying: boolean;
+}
+
+// usePresence types
+export interface UsePresenceOptions extends AnimationOptions {
+  /** Style when entering/visible */
+  enter: AnimatableProperties;
+  /** Style when exiting/hidden */
+  exit: AnimatableProperties;
+  /** Initial style (defaults to exit) */
+  initial?: AnimatableProperties;
+}
+
+export interface UsePresenceResult {
+  /** Whether element should be rendered */
+  isPresent: boolean;
+  /** Animated style to apply */
+  style: AnimatableStyle;
+  /** Trigger exit animation manually */
+  exit: () => void;
+}
+
+// useGradientBorder types
+export type GradientAnimation = 'spin' | 'pulse' | 'wave';
+
+export interface UseGradientBorderOptions {
+  /** Gradient colors */
+  colors: string[];
+  /** Border width in pixels */
+  borderWidth?: number;
+  /** Border radius in pixels */
+  borderRadius?: number;
+  /** Animation duration in ms or token */
+  duration?: Duration;
+  /** Animation type */
+  animation?: GradientAnimation;
+  /** Whether animation is active */
+  active?: boolean;
+}
+
+export interface UseGradientBorderResult {
+  /** Style for the outer container */
+  containerStyle: AnimatableStyle;
+  /** Style for the inner content wrapper */
+  contentStyle: AnimatableStyle;
+  /** Whether gradient CSS has been injected (web only) */
+  isReady: boolean;
+}

package/src/useAnimatedStyle.native.ts

@@ -0,0 +1,168 @@
+/**
+ * useAnimatedStyle - Native implementation
+ *
+ * Creates an animated style using Reanimated.
+ * Uses either timing or spring animations based on configuration.
+ */
+
+import { useEffect, useMemo } from 'react';
+import {
+  useSharedValue,
+  useAnimatedStyle as useReanimatedStyle,
+  withTiming,
+  withSpring,
+  withDelay,
+  Easing,
+} from 'react-native-reanimated';
+import { timingConfig, springConfig, isSpringEasing } from '@idealyst/theme/animation';
+import type { AnimatableProperties, UseAnimatedStyleOptions, AnimatableStyle } from './types';
+
+/**
+ * Hook that returns an animated style object.
+ * When the style properties change, they animate smoothly using Reanimated.
+ *
+ * @param style - The target style properties
+ * @param options - Animation configuration
+ * @returns Animated style object to spread onto an Animated component
+ *
+ * @example
+ * ```tsx
+ * import Animated from 'react-native-reanimated';
+ *
+ * const style = useAnimatedStyle({
+ *   opacity: isVisible ? 1 : 0,
+ *   transform: [{ translateY: isVisible ? 0 : 20 }],
+ * }, {
+ *   duration: 'normal',
+ *   easing: 'easeOut',
+ * });
+ *
+ * return <Animated.View style={style}>Content</Animated.View>;
+ * ```
+ */
+export function useAnimatedStyle(
+  style: AnimatableProperties,
+  options: UseAnimatedStyleOptions = {}
+): AnimatableStyle {
+  const { duration = 'normal', easing = 'easeOut', delay = 0, native } = options;
+
+  // Use native-specific options if provided
+  const finalDuration = native?.duration ?? duration;
+  const finalEasing = native?.easing ?? easing;
+  const finalDelay = native?.delay ?? delay;
+  const useSpring = native?.useSpring ?? isSpringEasing(finalEasing);
+  const springType = native?.springType ?? (isSpringEasing(finalEasing) ? finalEasing : 'spring');
+
+  // Create shared values for each animatable property
+  const opacity = useSharedValue(style.opacity ?? 1);
+  const backgroundColor = useSharedValue(style.backgroundColor ?? 'transparent');
+  const borderColor = useSharedValue(style.borderColor ?? 'transparent');
+  const borderWidth = useSharedValue(style.borderWidth ?? 0);
+  const borderRadius = useSharedValue(style.borderRadius ?? 0);
+
+  // Transform values
+  const translateX = useSharedValue(0);
+  const translateY = useSharedValue(0);
+  const scale = useSharedValue(1);
+  const scaleX = useSharedValue(1);
+  const scaleY = useSharedValue(1);
+  const rotate = useSharedValue('0deg');
+
+  // Extract transform values from style
+  const transforms = useMemo(() => {
+    const result = {
+      translateX: 0,
+      translateY: 0,
+      scale: 1,
+      scaleX: 1,
+      scaleY: 1,
+      rotate: '0deg',
+    };
+
+    if (style.transform) {
+      style.transform.forEach((t) => {
+        const [key, value] = Object.entries(t)[0];
+        if (key in result) {
+          (result as any)[key] = value;
+        }
+      });
+    }
+
+    return result;
+  }, [style.transform]);
+
+  // Animate function
+  const animate = (sharedValue: any, targetValue: any, isString = false) => {
+    'worklet';
+    if (useSpring && !isString) {
+      const config = springConfig(springType as any);
+      return finalDelay > 0
+        ? withDelay(finalDelay, withSpring(targetValue, config))
+        : withSpring(targetValue, config);
+    } else {
+      const config = timingConfig(finalDuration, finalEasing);
+      const timingOptions = {
+        duration: config.duration,
+        easing: Easing.bezier(config.easing[0], config.easing[1], config.easing[2], config.easing[3]),
+      };
+      return finalDelay > 0
+        ? withDelay(finalDelay, withTiming(targetValue, timingOptions))
+        : withTiming(targetValue, timingOptions);
+    }
+  };
+
+  // Update shared values when style changes
+  useEffect(() => {
+    if (style.opacity !== undefined) {
+      opacity.value = animate(opacity, style.opacity);
+    }
+    if (style.backgroundColor !== undefined) {
+      backgroundColor.value = animate(backgroundColor, style.backgroundColor, true);
+    }
+    if (style.borderColor !== undefined) {
+      borderColor.value = animate(borderColor, style.borderColor, true);
+    }
+    if (style.borderWidth !== undefined) {
+      borderWidth.value = animate(borderWidth, style.borderWidth);
+    }
+    if (style.borderRadius !== undefined) {
+      borderRadius.value = animate(borderRadius, style.borderRadius);
+    }
+
+    // Update transform values
+    translateX.value = animate(translateX, transforms.translateX);
+    translateY.value = animate(translateY, transforms.translateY);
+    scale.value = animate(scale, transforms.scale);
+    scaleX.value = animate(scaleX, transforms.scaleX);
+    scaleY.value = animate(scaleY, transforms.scaleY);
+    rotate.value = animate(rotate, transforms.rotate, true);
+  }, [
+    style.opacity,
+    style.backgroundColor,
+    style.borderColor,
+    style.borderWidth,
+    style.borderRadius,
+    transforms,
+  ]);
+
+  // Create animated style
+  const animatedStyle = useReanimatedStyle(() => {
+    return {
+      opacity: opacity.value,
+      backgroundColor: backgroundColor.value,
+      borderColor: borderColor.value,
+      borderWidth: borderWidth.value,
+      borderRadius: borderRadius.value,
+      transform: [
+        { translateX: translateX.value },
+        { translateY: translateY.value },
+        { scale: scale.value },
+        { scaleX: scaleX.value },
+        { scaleY: scaleY.value },
+        { rotate: rotate.value },
+      ],
+    };
+  });
+
+  return animatedStyle as AnimatableStyle;
+}