@idealyst/animate 1.2.58 → 1.2.59

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@idealyst/animate",
-  "version": "1.2.58",
+  "version": "1.2.59",
   "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.58",
+    "@idealyst/theme": "^1.2.59",
     "react": ">=16.8.0",
     "react-native": ">=0.60.0",
     "react-native-reanimated": ">=3.0.0",
@@ -48,7 +48,7 @@
     }
   },
   "devDependencies": {
-    "@idealyst/theme": "^1.2.58",
+    "@idealyst/theme": "^1.2.59",
     "@types/react": "^19.1.0",
     "react": "^19.1.0",
     "react-native": "^0.80.1",

package/src/index.native.ts

@@ -41,6 +41,7 @@ export type {
   AnimatableStyle,
   AnimatableProperties,
   TransformProperty,
+  TransformObject,
   AnimationOptions,
   PlatformOverrides,
   UseAnimatedStyleOptions,

package/src/index.ts

@@ -36,6 +36,7 @@ export type {
   AnimatableStyle,
   AnimatableProperties,
   TransformProperty,
+  TransformObject,
   AnimationOptions,
   PlatformOverrides,
   UseAnimatedStyleOptions,

package/src/normalizeTransform.ts

@@ -0,0 +1,79 @@
+/**
+ * Transform normalization utilities.
+ *
+ * Converts the simplified TransformObject syntax to the React Native
+ * array format used internally by both web and native implementations.
+ */
+
+import type { TransformObject, TransformProperty } from './types';
+
+/**
+ * Type guard to detect if a transform is using the new object syntax
+ * vs the legacy array format.
+ */
+export function isTransformObject(
+  transform: TransformObject | TransformProperty[] | undefined
+): transform is TransformObject {
+  return transform !== undefined && !Array.isArray(transform);
+}
+
+/**
+ * Normalizes a TransformObject to the React Native array format.
+ *
+ * @example
+ * normalizeTransform({ x: 10, y: 20, scale: 1.2, rotate: 45 })
+ * // Returns: [{ translateX: 10 }, { translateY: 20 }, { scale: 1.2 }, { rotate: '45deg' }]
+ */
+export function normalizeTransform(transform: TransformObject): TransformProperty[] {
+  const result: TransformProperty[] = [];
+
+  // Perspective should come first for proper 3D transforms
+  if (transform.perspective !== undefined) {
+    result.push({ perspective: transform.perspective });
+  }
+
+  // Translation
+  if (transform.x !== undefined) {
+    result.push({ translateX: transform.x });
+  }
+  if (transform.y !== undefined) {
+    result.push({ translateY: transform.y });
+  }
+
+  // Scale
+  if (transform.scale !== undefined) {
+    result.push({ scale: transform.scale });
+  }
+  if (transform.scaleX !== undefined) {
+    result.push({ scaleX: transform.scaleX });
+  }
+  if (transform.scaleY !== undefined) {
+    result.push({ scaleY: transform.scaleY });
+  }
+
+  // Rotation - convert number to degrees string
+  if (transform.rotate !== undefined) {
+    const rotation =
+      typeof transform.rotate === 'number' ? `${transform.rotate}deg` : transform.rotate;
+    result.push({ rotate: rotation });
+  }
+  if (transform.rotateX !== undefined) {
+    result.push({ rotateX: transform.rotateX });
+  }
+  if (transform.rotateY !== undefined) {
+    result.push({ rotateY: transform.rotateY });
+  }
+  if (transform.rotateZ !== undefined) {
+    result.push({ rotateZ: transform.rotateZ });
+  }
+
+  // Skew
+  if (transform.skewX !== undefined) {
+    result.push({ skewX: transform.skewX });
+  }
+  if (transform.skewY !== undefined) {
+    result.push({ skewY: transform.skewY });
+  }
+
+  return result;
+}

package/src/types.ts

@@ -9,7 +9,7 @@ import type { Duration, EasingKey, SpringType } from '@idealyst/theme/animation'
 export type AnimatableStyle = ViewStyle | TextStyle | ImageStyle;
 export type StyleValue = string | number | undefined;
 
-// Transform types (React Native style)
+// Transform types (React Native array style - legacy)
 export type TransformProperty =
   | { perspective: number }
   | { rotate: string }
@@ -24,6 +24,41 @@ export type TransformProperty =
   | { skewX: string }
   | { skewY: string };
 
+/**
+ * Simplified transform object syntax.
+ * Cleaner alternative to the React Native array format.
+ *
+ * @example
+ * // Instead of: transform: [{ translateX: 10 }, { translateY: 20 }, { scale: 1.2 }]
+ * // Use: transform: { x: 10, y: 20, scale: 1.2 }
+ */
+export interface TransformObject {
+  /** translateX - horizontal movement in pixels */
+  x?: number;
+  /** translateY - vertical movement in pixels */
+  y?: number;
+  /** Uniform scale (1 = normal, 2 = double, 0.5 = half) */
+  scale?: number;
+  /** Horizontal scale */
+  scaleX?: number;
+  /** Vertical scale */
+  scaleY?: number;
+  /** Rotation in degrees (number) or string ("45deg") */
+  rotate?: number | string;
+  /** X-axis rotation (string, e.g., "45deg") */
+  rotateX?: string;
+  /** Y-axis rotation (string, e.g., "45deg") */
+  rotateY?: string;
+  /** Z-axis rotation (string, e.g., "45deg") */
+  rotateZ?: string;
+  /** X-axis skew (string, e.g., "10deg") */
+  skewX?: string;
+  /** Y-axis skew (string, e.g., "10deg") */
+  skewY?: string;
+  /** Perspective for 3D transforms */
+  perspective?: number;
+}
+
 // Animatable properties (subset that can be animated smoothly)
 export interface AnimatableProperties {
   // Opacity
@@ -55,8 +90,18 @@ export interface AnimatableProperties {
   bottom?: number | string;
   left?: number | string;
 
-  // Transform (preferred for performance)
-  transform?: TransformProperty[];
+  /**
+   * Transform - preferred for performance (GPU accelerated).
+   * Accepts either the new object syntax or legacy array format.
+   *
+   * @example
+   * // New object syntax (recommended)
+   * transform: { x: 10, y: 20, scale: 1.2, rotate: 45 }
+   *
+   * // Legacy array syntax (still supported)
+   * transform: [{ translateX: 10 }, { translateY: 20 }, { scale: 1.2 }]
+   */
+  transform?: TransformObject | TransformProperty[];
 }
 
 // Animation configuration

package/src/useAnimatedStyle.native.ts

@@ -15,7 +15,13 @@ import {
   Easing,
 } from 'react-native-reanimated';
 import { timingConfig, springConfig, isSpringEasing } from '@idealyst/theme/animation';
-import type { AnimatableProperties, UseAnimatedStyleOptions, AnimatableStyle } from './types';
+import type {
+  AnimatableProperties,
+  UseAnimatedStyleOptions,
+  AnimatableStyle,
+  TransformProperty,
+} from './types';
+import { isTransformObject, normalizeTransform } from './normalizeTransform';
 
 /**
  * Hook that returns an animated style object.
@@ -29,14 +35,21 @@ import type { AnimatableProperties, UseAnimatedStyleOptions, AnimatableStyle } f
  * ```tsx
  * import Animated from 'react-native-reanimated';
  *
+ * // New object syntax (recommended)
  * const style = useAnimatedStyle({
  *   opacity: isVisible ? 1 : 0,
- *   transform: [{ translateY: isVisible ? 0 : 20 }],
+ *   transform: { y: isVisible ? 0 : 20 },
  * }, {
  *   duration: 'normal',
  *   easing: 'easeOut',
  * });
  *
+ * // Legacy array syntax (still supported)
+ * const legacyStyle = useAnimatedStyle({
+ *   opacity: isVisible ? 1 : 0,
+ *   transform: [{ translateY: isVisible ? 0 : 20 }],
+ * });
+ *
  * return <Animated.View style={style}>Content</Animated.View>;
  * ```
  */
@@ -53,6 +66,15 @@ export function useAnimatedStyle(
   const useSpring = native?.useSpring ?? isSpringEasing(finalEasing);
   const springType = native?.springType ?? (isSpringEasing(finalEasing) ? finalEasing : 'spring');
 
+  // Normalize transform to array format if using object syntax
+  const normalizedTransform = useMemo((): TransformProperty[] | undefined => {
+    if (!style.transform) return undefined;
+    if (isTransformObject(style.transform)) {
+      return normalizeTransform(style.transform);
+    }
+    return style.transform;
+  }, [style.transform]);
+
   // Create shared values for each animatable property
   const opacity = useSharedValue(style.opacity ?? 1);
   const backgroundColor = useSharedValue(style.backgroundColor ?? 'transparent');
@@ -60,6 +82,14 @@ export function useAnimatedStyle(
   const borderWidth = useSharedValue(style.borderWidth ?? 0);
   const borderRadius = useSharedValue(style.borderRadius ?? 0);
 
+  // Layout properties
+  const top = useSharedValue(style.top ?? 0);
+  const right = useSharedValue(style.right ?? 0);
+  const bottom = useSharedValue(style.bottom ?? 0);
+  const left = useSharedValue(style.left ?? 0);
+  const width = useSharedValue(style.width ?? 'auto');
+  const height = useSharedValue(style.height ?? 'auto');
+
   // Transform values
   const translateX = useSharedValue(0);
   const translateY = useSharedValue(0);
@@ -67,8 +97,14 @@ export function useAnimatedStyle(
   const scaleX = useSharedValue(1);
   const scaleY = useSharedValue(1);
   const rotate = useSharedValue('0deg');
+  const rotateX = useSharedValue('0deg');
+  const rotateY = useSharedValue('0deg');
+  const rotateZ = useSharedValue('0deg');
+  const skewX = useSharedValue('0deg');
+  const skewY = useSharedValue('0deg');
+  const perspective = useSharedValue(1000);
 
-  // Extract transform values from style
+  // Extract transform values from normalized array
   const transforms = useMemo(() => {
     const result = {
       translateX: 0,
@@ -77,10 +113,16 @@ export function useAnimatedStyle(
       scaleX: 1,
       scaleY: 1,
       rotate: '0deg',
+      rotateX: '0deg',
+      rotateY: '0deg',
+      rotateZ: '0deg',
+      skewX: '0deg',
+      skewY: '0deg',
+      perspective: 1000,
     };
 
-    if (style.transform) {
-      style.transform.forEach((t) => {
+    if (normalizedTransform) {
+      normalizedTransform.forEach((t) => {
         const [key, value] = Object.entries(t)[0];
         if (key in result) {
           (result as any)[key] = value;
@@ -89,7 +131,7 @@ export function useAnimatedStyle(
     }
 
     return result;
-  }, [style.transform]);
+  }, [normalizedTransform]);
 
   // Animate function
   const animate = (sharedValue: any, targetValue: any, isString = false) => {
@@ -113,6 +155,7 @@ export function useAnimatedStyle(
 
   // Update shared values when style changes
   useEffect(() => {
+    // Visual properties
     if (style.opacity !== undefined) {
       opacity.value = animate(opacity, style.opacity);
     }
@@ -129,6 +172,26 @@ export function useAnimatedStyle(
       borderRadius.value = animate(borderRadius, style.borderRadius);
     }
 
+    // Layout properties
+    if (style.top !== undefined) {
+      top.value = animate(top, style.top);
+    }
+    if (style.right !== undefined) {
+      right.value = animate(right, style.right);
+    }
+    if (style.bottom !== undefined) {
+      bottom.value = animate(bottom, style.bottom);
+    }
+    if (style.left !== undefined) {
+      left.value = animate(left, style.left);
+    }
+    if (style.width !== undefined) {
+      width.value = animate(width, style.width);
+    }
+    if (style.height !== undefined) {
+      height.value = animate(height, style.height);
+    }
+
     // Update transform values
     translateX.value = animate(translateX, transforms.translateX);
     translateY.value = animate(translateY, transforms.translateY);
@@ -136,32 +199,60 @@ export function useAnimatedStyle(
     scaleX.value = animate(scaleX, transforms.scaleX);
     scaleY.value = animate(scaleY, transforms.scaleY);
     rotate.value = animate(rotate, transforms.rotate, true);
+    rotateX.value = animate(rotateX, transforms.rotateX, true);
+    rotateY.value = animate(rotateY, transforms.rotateY, true);
+    rotateZ.value = animate(rotateZ, transforms.rotateZ, true);
+    skewX.value = animate(skewX, transforms.skewX, true);
+    skewY.value = animate(skewY, transforms.skewY, true);
+    perspective.value = animate(perspective, transforms.perspective);
   }, [
     style.opacity,
     style.backgroundColor,
     style.borderColor,
     style.borderWidth,
     style.borderRadius,
+    style.top,
+    style.right,
+    style.bottom,
+    style.left,
+    style.width,
+    style.height,
     transforms,
   ]);
 
-  // Create animated style
+  // Create animated style - only include properties that were specified
   const animatedStyle = useReanimatedStyle(() => {
-    return {
+    const result: Record<string, any> = {
       opacity: opacity.value,
       backgroundColor: backgroundColor.value,
       borderColor: borderColor.value,
       borderWidth: borderWidth.value,
       borderRadius: borderRadius.value,
       transform: [
+        { perspective: perspective.value },
         { translateX: translateX.value },
         { translateY: translateY.value },
         { scale: scale.value },
         { scaleX: scaleX.value },
         { scaleY: scaleY.value },
         { rotate: rotate.value },
+        { rotateX: rotateX.value },
+        { rotateY: rotateY.value },
+        { rotateZ: rotateZ.value },
+        { skewX: skewX.value },
+        { skewY: skewY.value },
       ],
     };
+
+    // Only include layout properties if they were specified (avoid overriding with defaults)
+    if (style.top !== undefined) result.top = top.value;
+    if (style.right !== undefined) result.right = right.value;
+    if (style.bottom !== undefined) result.bottom = bottom.value;
+    if (style.left !== undefined) result.left = left.value;
+    if (style.width !== undefined) result.width = width.value;
+    if (style.height !== undefined) result.height = height.value;
+
+    return result;
   });
 
   return animatedStyle as AnimatableStyle;

package/src/useAnimatedStyle.ts

@@ -5,9 +5,15 @@
  * Uses CSS transitions for smooth, performant animations.
  */
 
-import { useMemo, useRef, useEffect } from 'react';
-import { cssTransition, resolveDuration, resolveEasing } from '@idealyst/theme/animation';
-import type { AnimatableProperties, UseAnimatedStyleOptions, AnimatableStyle } from './types';
+import { useMemo } from 'react';
+import { resolveDuration, resolveEasing } from '@idealyst/theme/animation';
+import type {
+  AnimatableProperties,
+  UseAnimatedStyleOptions,
+  AnimatableStyle,
+  TransformProperty,
+} from './types';
+import { isTransformObject, normalizeTransform } from './normalizeTransform';
 
 /**
  * Hook that returns an animated style object.
@@ -19,14 +25,21 @@ import type { AnimatableProperties, UseAnimatedStyleOptions, AnimatableStyle } f
  *
  * @example
  * ```tsx
+ * // New object syntax (recommended)
  * const style = useAnimatedStyle({
  *   opacity: isVisible ? 1 : 0,
- *   transform: [{ translateY: isVisible ? 0 : 20 }],
+ *   transform: { y: isVisible ? 0 : 20 },
  * }, {
  *   duration: 'normal',
  *   easing: 'easeOut',
  * });
  *
+ * // Legacy array syntax (still supported)
+ * const legacyStyle = useAnimatedStyle({
+ *   opacity: isVisible ? 1 : 0,
+ *   transform: [{ translateY: isVisible ? 0 : 20 }],
+ * });
+ *
  * return <div style={style}>Content</div>;
  * ```
  */
@@ -41,20 +54,22 @@ export function useAnimatedStyle(
   const finalEasing = web?.easing ?? easing;
   const finalDelay = web?.delay ?? delay;
 
-  // Track if this is the initial render
-  const isInitialRender = useRef(true);
-
-  useEffect(() => {
-    isInitialRender.current = false;
-  }, []);
+  // Normalize transform to array format if using object syntax
+  const normalizedTransform = useMemo((): TransformProperty[] | undefined => {
+    if (!style.transform) return undefined;
+    if (isTransformObject(style.transform)) {
+      return normalizeTransform(style.transform);
+    }
+    return style.transform;
+  }, [style.transform]);
 
   // Convert transform array to CSS transform string
   const transformString = useMemo(() => {
-    if (!style.transform || !Array.isArray(style.transform)) {
+    if (!normalizedTransform) {
       return undefined;
     }
 
-    return style.transform
+    return normalizedTransform
       .map((t) => {
         const [key, value] = Object.entries(t)[0];
         // Handle different transform types
@@ -79,63 +94,23 @@ export function useAnimatedStyle(
         }
       })
       .join(' ');
-  }, [style.transform]);
+  }, [normalizedTransform]);
 
-  // Build the transition string
+  // Build the transition string - use 'all' for simplicity and to catch any property
   const transition = useMemo(() => {
     // Use custom transition if provided
     if (web?.transition) {
       return web.transition;
     }
 
-    // Get all animatable property names from the style
-    const properties = Object.keys(style).filter((key) => key !== 'transform');
-    if (style.transform) {
-      properties.push('transform');
-    }
-
-    if (properties.length === 0) {
-      return undefined;
-    }
-
-    // Map RN property names to CSS property names
-    const cssProperties = properties.map((prop) => {
-      switch (prop) {
-        case 'backgroundColor':
-          return 'background-color';
-        case 'borderColor':
-          return 'border-color';
-        case 'borderWidth':
-          return 'border-width';
-        case 'borderRadius':
-          return 'border-radius';
-        case 'borderTopLeftRadius':
-          return 'border-top-left-radius';
-        case 'borderTopRightRadius':
-          return 'border-top-right-radius';
-        case 'borderBottomLeftRadius':
-          return 'border-bottom-left-radius';
-        case 'borderBottomRightRadius':
-          return 'border-bottom-right-radius';
-        case 'maxHeight':
-          return 'max-height';
-        case 'maxWidth':
-          return 'max-width';
-        case 'minHeight':
-          return 'min-height';
-        case 'minWidth':
-          return 'min-width';
-        default:
-          return prop;
-      }
-    });
-
     const durationMs = resolveDuration(finalDuration);
     const easingCss = resolveEasing(finalEasing);
     const delayStr = finalDelay > 0 ? ` ${finalDelay}ms` : '';
 
-    return cssProperties.map((prop) => `${prop} ${durationMs}ms ${easingCss}${delayStr}`).join(', ');
-  }, [style, finalDuration, finalEasing, finalDelay, web?.transition]);
+    // Use 'all' to animate any property that changes
+    // This is simpler and catches properties we might not explicitly list
+    return `all ${durationMs}ms ${easingCss}${delayStr}`;
+  }, [finalDuration, finalEasing, finalDelay, web?.transition]);
 
   // Build the final style object
   const animatedStyle = useMemo(() => {
@@ -153,8 +128,9 @@ export function useAnimatedStyle(
       result.transform = transformString;
     }
 
-    // Add transition (skip on initial render to avoid animation on mount)
-    if (transition && !isInitialRender.current) {
+    // Always include transition - CSS handles the timing correctly
+    // The transition property must be present BEFORE values change for animation to work
+    if (transition) {
       result.transition = transition;
     }
 

package/src/usePresence.native.ts

@@ -4,7 +4,7 @@
  * Manages mount/unmount animations using Reanimated.
  */
 
-import { useState, useEffect, useRef, useCallback } from 'react';
+import { useState, useEffect, useRef, useCallback, useMemo } from 'react';
 import {
   useSharedValue,
   useAnimatedStyle,
@@ -15,7 +15,14 @@ import {
   runOnJS,
 } from 'react-native-reanimated';
 import { timingConfig, springConfig, isSpringEasing, resolveDuration } from '@idealyst/theme/animation';
-import type { UsePresenceOptions, UsePresenceResult, AnimatableStyle } from './types';
+import type {
+  UsePresenceOptions,
+  UsePresenceResult,
+  AnimatableStyle,
+  AnimatableProperties,
+  TransformProperty,
+} from './types';
+import { isTransformObject, normalizeTransform } from './normalizeTransform';
 
 /**
  * Hook that manages presence animations for mount/unmount.
@@ -57,23 +64,37 @@ export function usePresence(isVisible: boolean, options: UsePresenceOptions): Us
   const exitOpacity = exit.opacity ?? 0;
   const initialOpacity = initial?.opacity ?? exitOpacity;
 
-  // Extract transform values
+  // Normalize transforms to array format
+  const normalizedEnterTransform = useMemo((): TransformProperty[] => {
+    if (!enter.transform) return [];
+    return isTransformObject(enter.transform)
+      ? normalizeTransform(enter.transform)
+      : enter.transform;
+  }, [enter.transform]);
+
+  const normalizedExitTransform = useMemo((): TransformProperty[] => {
+    if (!exit.transform) return [];
+    return isTransformObject(exit.transform)
+      ? normalizeTransform(exit.transform)
+      : exit.transform;
+  }, [exit.transform]);
+
+  // Extract transform values from normalized arrays
   const getTransformValue = (
-    style: typeof enter | typeof exit,
+    transforms: TransformProperty[],
     key: string,
     defaultValue: number | string
   ) => {
-    if (!style.transform) return defaultValue;
-    const transform = style.transform.find((t) => key in t);
+    const transform = transforms.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;
+  const enterTranslateY = getTransformValue(normalizedEnterTransform, 'translateY', 0) as number;
+  const exitTranslateY = getTransformValue(normalizedExitTransform, 'translateY', 0) as number;
+  const enterTranslateX = getTransformValue(normalizedEnterTransform, 'translateX', 0) as number;
+  const exitTranslateX = getTransformValue(normalizedExitTransform, 'translateX', 0) as number;
+  const enterScale = getTransformValue(normalizedEnterTransform, 'scale', 1) as number;
+  const exitScale = getTransformValue(normalizedExitTransform, 'scale', 1) as number;
 
   // Animation helper
   const animateTo = useCallback(

package/src/usePresence.ts

@@ -7,7 +7,14 @@
 
 import { useState, useEffect, useRef, useMemo, useCallback } from 'react';
 import { resolveDuration, resolveEasing } from '@idealyst/theme/animation';
-import type { UsePresenceOptions, UsePresenceResult, AnimatableStyle } from './types';
+import type {
+  UsePresenceOptions,
+  UsePresenceResult,
+  AnimatableStyle,
+  AnimatableProperties,
+  TransformProperty,
+} from './types';
+import { isTransformObject, normalizeTransform } from './normalizeTransform';
 
 /**
  * Hook that manages presence animations for mount/unmount.
@@ -87,11 +94,18 @@ export function usePresence(isVisible: boolean, options: UsePresenceOptions): Us
     }, durationMs + delay);
   }, [durationMs, delay]);
 
-  // Convert transform array to CSS transform string
-  const transformToString = (transform: any[] | undefined): string | undefined => {
+  // Convert transform to CSS transform string (handles both object and array formats)
+  const transformToString = (
+    transform: AnimatableProperties['transform']
+  ): string | undefined => {
     if (!transform) return undefined;
 
-    return transform
+    // Normalize if it's an object
+    const normalizedTransform: TransformProperty[] = isTransformObject(transform)
+      ? normalizeTransform(transform)
+      : transform;
+
+    return normalizedTransform
       .map((t) => {
         const [key, value] = Object.entries(t)[0];
         switch (key) {