@idealyst/animate 1.2.80 → 1.2.81

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@idealyst/animate",
-  "version": "1.2.80",
+  "version": "1.2.81",
   "description": "Cross-platform animation hooks for React and React Native",
   "readme": "README.md",
   "main": "src/index.ts",
@@ -30,7 +30,7 @@
     "publish:npm": "npm publish"
   },
   "peerDependencies": {
-    "@idealyst/theme": "^1.2.80",
+    "@idealyst/theme": "^1.2.81",
     "react": ">=16.8.0",
     "react-native": ">=0.60.0",
     "react-native-reanimated": ">=3.0.0",
@@ -48,7 +48,7 @@
     }
   },
   "devDependencies": {
-    "@idealyst/theme": "^1.2.80",
+    "@idealyst/theme": "^1.2.81",
     "@types/react": "^19.1.0",
     "react": "^19.1.0",
     "react-native": "^0.80.1",

package/src/examples/AnimateExamples.tsx

@@ -268,6 +268,111 @@ const PresenceDemo: React.FC = () => {
   );
 };
 
+// =============================================================================
+// Spring Animation Demo (Web CSS Approximation)
+// =============================================================================
+
+const SpringAnimationDemo: React.FC = () => {
+  const [isPressed, setIsPressed] = useState(false);
+  const [springType, setSpringType] = useState<'spring' | 'springStiff' | 'springBouncy'>('spring');
+
+  // Using spring easing - on web, this automatically uses CSS approximation
+  // On native, it uses actual Reanimated spring physics
+  const buttonStyle = useAnimatedStyle(
+    {
+      transform: { scale: isPressed ? 0.95 : 1 },
+    },
+    { easing: springType }
+  );
+
+  const cardStyle = useAnimatedStyle(
+    {
+      transform: { y: isPressed ? 4 : 0 },
+      opacity: isPressed ? 0.9 : 1,
+    },
+    { easing: springType }
+  );
+
+  return (
+    <Card padding="md" gap="md">
+      <Text typography="h4" weight="semibold">Spring Animations</Text>
+      <Text color="secondary">
+        Spring easings are automatically converted to CSS approximations on web,
+        providing GPU-accelerated animations that match native spring feel.
+      </Text>
+
+      <View direction="row" gap="sm" style={{ justifyContent: 'center' }}>
+        <Button
+          type={springType === 'spring' ? 'contained' : 'outlined'}
+          onPress={() => setSpringType('spring')}
+          size="sm"
+        >
+          Spring
+        </Button>
+        <Button
+          type={springType === 'springStiff' ? 'contained' : 'outlined'}
+          onPress={() => setSpringType('springStiff')}
+          size="sm"
+        >
+          Stiff
+        </Button>
+        <Button
+          type={springType === 'springBouncy' ? 'contained' : 'outlined'}
+          onPress={() => setSpringType('springBouncy')}
+          size="sm"
+        >
+          Bouncy
+        </Button>
+      </View>
+
+      <View style={{ alignItems: 'center', padding: 20 }}>
+        <View
+          style={{
+            width: 160,
+            height: 100,
+            backgroundColor: '#6366f1',
+            borderRadius: 12,
+            justifyContent: 'center',
+            alignItems: 'center',
+            cursor: 'pointer',
+            ...buttonStyle,
+            ...cardStyle,
+          }}
+          // @ts-ignore - web events
+          onMouseDown={() => setIsPressed(true)}
+          onMouseUp={() => setIsPressed(false)}
+          onMouseLeave={() => setIsPressed(false)}
+        >
+          <Text style={{ color: '#fff' }} weight="semibold">Press Me</Text>
+          <Text style={{ color: 'rgba(255,255,255,0.8)' }} typography="caption">
+            {springType}
+          </Text>
+        </View>
+      </View>
+
+      <View background="secondary" padding="sm" radius="sm">
+        <Text typography="caption" style={{ fontFamily: 'monospace' }}>
+          {`// Spring easings work cross-platform!
+const style = useAnimatedStyle({
+  transform: { scale: isPressed ? 0.95 : 1 },
+}, { easing: '${springType}' });
+
+// Web: CSS cubic-bezier approximation
+// Native: Reanimated withSpring`}
+        </Text>
+      </View>
+
+      <View padding="sm" background="tertiary" radius="sm">
+        <Text typography="caption" color="secondary">
+          <Text weight="semibold">Web Performance: </Text>
+          Spring animations use CSS transitions with calculated bezier curves,
+          running entirely on the GPU compositor thread. No JavaScript RAF loops.
+        </Text>
+      </View>
+    </Card>
+  );
+};
+
 // =============================================================================
 // useGradientBorder Demo
 // =============================================================================
@@ -391,6 +496,7 @@ export const AnimateExamples: React.FC = () => {
         <Divider />
 
         <AnimatedStyleDemo />
+        <SpringAnimationDemo />
         <AnimatedValueDemo />
         <PresenceDemo />
         <GradientBorderDemo />

package/src/useAnimatedStyle.ts

@@ -3,10 +3,16 @@
  *
  * Creates an animated style that transitions when properties change.
  * Uses CSS transitions for smooth, performant animations.
+ *
+ * For spring easings, automatically converts to CSS approximations
+ * with calculated durations that match the spring's settling time.
  */
 
 import { useMemo } from 'react';
-import { resolveDuration, resolveEasing } from '@idealyst/theme/animation';
+import {
+  resolveDuration,
+  resolveEasingWithDuration,
+} from '@idealyst/theme/animation';
 import type {
   AnimatableProperties,
   UseAnimatedStyleOptions,
@@ -103,8 +109,15 @@ export function useAnimatedStyle(
       return web.transition;
     }
 
-    const durationMs = resolveDuration(finalDuration);
-    const easingCss = resolveEasing(finalEasing);
+    const baseDuration = resolveDuration(finalDuration);
+
+    // For spring easings, resolveEasingWithDuration calculates the optimal
+    // duration based on the spring's settling time, giving better approximation
+    const { css: easingCss, duration: durationMs } = resolveEasingWithDuration(
+      finalEasing,
+      baseDuration
+    );
+
     const delayStr = finalDelay > 0 ? ` ${finalDelay}ms` : '';
 
     // Use 'all' to animate any property that changes

package/src/useAnimatedValue.ts

@@ -3,12 +3,28 @@
  *
  * Creates an animated numeric value that can be interpolated.
  * Uses requestAnimationFrame for smooth animations on web.
+ *
+ * NOTE: This hook uses RAF which is less performant than CSS transitions.
+ * Consider using useAnimatedStyle for style-based animations instead.
  */
 
 import { useState, useRef, useCallback, useMemo } from 'react';
 import { resolveDuration, resolveEasing } from '@idealyst/theme/animation';
 import type { AnimatedValue, AnimationOptions, InterpolationConfig } from './types';
 
+// Warn about RAF usage in development (once per session)
+let hasWarnedAboutRAF = false;
+function warnRAFUsage(hookName: string) {
+  if (process.env.NODE_ENV === 'development' && !hasWarnedAboutRAF) {
+    hasWarnedAboutRAF = true;
+    console.warn(
+      `[@idealyst/animate] ${hookName} uses requestAnimationFrame for animations, ` +
+        `which is less performant than CSS transitions. Consider using useAnimatedStyle ` +
+        `for style-based animations to leverage GPU-accelerated CSS transitions.`
+    );
+  }
+}
+
 // Bezier curve evaluation for custom easing
 function bezierEval(t: number, p1: number, p2: number, p3: number, p4: number): number {
   const cx = 3 * p1;
@@ -102,6 +118,8 @@ export function useAnimatedValue(initialValue: number): AnimatedValue {
   // Set value with animation
   const set = useCallback(
     (target: number, options: AnimationOptions = {}) => {
+      warnRAFUsage('useAnimatedValue');
+
       const { duration = 'normal', easing = 'easeOut', delay = 0 } = options;
       const durationMs = resolveDuration(duration);
       const easingCss = resolveEasing(easing);

package/src/usePresence.ts

@@ -3,6 +3,10 @@
  *
  * Manages mount/unmount animations by keeping elements in the DOM
  * during exit animations.
+ *
+ * NOTE: This hook uses double RAF for DOM synchronization. The actual
+ * animation uses CSS transitions (performant), but the RAF is needed
+ * to ensure proper timing of state changes.
  */
 
 import { useState, useEffect, useRef, useMemo, useCallback } from 'react';
@@ -16,6 +20,19 @@ import type {
 } from './types';
 import { isTransformObject, normalizeTransform } from './normalizeTransform';
 
+// Warn about RAF usage in development (once per session)
+let hasWarnedAboutPresenceRAF = false;
+function warnPresenceRAF() {
+  if (process.env.NODE_ENV === 'development' && !hasWarnedAboutPresenceRAF) {
+    hasWarnedAboutPresenceRAF = true;
+    console.warn(
+      `[@idealyst/animate] usePresence uses requestAnimationFrame for DOM synchronization. ` +
+        `The animation itself uses CSS transitions, but RAF is required to coordinate ` +
+        `mount/unmount timing with the browser's rendering cycle.`
+    );
+  }
+}
+
 /**
  * Hook that manages presence animations for mount/unmount.
  * The element stays rendered during exit animation.
@@ -61,6 +78,7 @@ export function usePresence(isVisible: boolean, options: UsePresenceOptions): Us
       // Entering: mount immediately, then animate in
       setIsPresent(true);
       // Use double RAF to ensure DOM is ready before animating
+      warnPresenceRAF();
       requestAnimationFrame(() => {
         requestAnimationFrame(() => {
           setIsEntering(true);