tessl/npm-react-spring--web

React DOM support for the react-spring animation library with spring-physics based animations

—

Pending

Overview

Eval results

Files

Transform System

Name: tessl/npm-react-spring--web
Author: tessl

Web-specific transform handling with optimized CSS transform generation and shorthand properties. The transform system automatically handles unit conversion, combines transforms efficiently, and optimizes for performance.

Capabilities

Transform Properties

Extended CSS transform properties with automatic unit handling and optimization.

interface TransformProps {
  /** Transform string (overrides all other transform properties) */
  transform?: string;
  
  /** Translation shortcuts */
  x?: Length;
  y?: Length;
  z?: Length;
  
  /** Standard translation properties */
  translate?: Length | readonly [Length, Length];
  translateX?: Length;
  translateY?: Length;
  translateZ?: Length;
  translate3d?: readonly [Length, Length, Length];
  
  /** Rotation properties */
  rotate?: Angle;
  rotateX?: Angle;
  rotateY?: Angle;
  rotateZ?: Angle;
  rotate3d?: readonly [number, number, number, Angle];
  
  /** Scale properties */
  scale?: number | readonly [number, number] | string;
  scaleX?: number;
  scaleY?: number;
  scaleZ?: number;
  scale3d?: readonly [number, number, number];
  
  /** Skew properties */
  skew?: Angle | readonly [Angle, Angle];
  skewX?: Angle;
  skewY?: Angle;
  
  /** Matrix transformations */
  matrix?: readonly [number, number, number, number, number, number];
  matrix3d?: readonly [
    number, number, number, number,
    number, number, number, number,
    number, number, number, number,
    number, number, number, number
  ];
}

type Length = number | string;
type Angle = number | string;

Usage Examples:

import { useSpring, animated } from "@react-spring/web";

function TransformDemo() {
  const styles = useSpring({
    from: {
      x: 0,
      y: 0,
      rotate: 0,
      scale: 0.8,
    },
    to: {
      x: 100,
      y: 50,
      rotate: 45,
      scale: 1,
    },
  });

  return <animated.div style={styles}>Transformed element</animated.div>;
}

// Advanced transform combinations
function AdvancedTransforms() {
  const styles = useSpring({
    from: {
      translateX: '0px',
      rotateZ: '0deg',
      scaleX: 1,
      scaleY: 1,
    },
    to: {
      translateX: '200px',
      rotateZ: '180deg',
      scaleX: 1.5,
      scaleY: 0.8,
    },
  });

  return <animated.div style={styles}>Complex transforms</animated.div>;
}

Automatic Unit Addition

The transform system automatically adds appropriate units to numeric values.

interface UnitRules {
  /** Translation properties get 'px' units by default */
  translation: 'px';
  /** Rotation and skew properties get 'deg' units by default */
  rotation: 'deg';
  /** Scale properties are unitless */
  scale: 'unitless';
}

Transform Unit Examples:

// These are equivalent:
const styles1 = useSpring({
  x: 100,        // Becomes '100px'
  rotate: 45,    // Becomes '45deg'
  scale: 1.2,    // Remains 1.2 (unitless)
});

const styles2 = useSpring({
  x: '100px',
  rotate: '45deg',
  scale: 1.2,
});

Transform Optimization

The system optimizes transforms by combining similar operations and detecting identity transforms.

interface TransformOptimization {
  /** Combines x, y, z into single translate3d() */
  translation: 'translate3d(x, y, z)';
  /** Identity transforms become 'none' */
  identity: 'none';
  /** Similar transforms are combined efficiently */
  combination: 'optimized';
}

Optimization Examples:

// x, y, z are combined into translate3d
const styles = useSpring({
  x: 50,    // \
  y: 100,   //  > Combined into: translate3d(50px, 100px, 0px)
  z: 0,     // /
  rotate: 0, // Identity rotation is optimized out
});

// Results in: transform: translate3d(50px, 100px, 0px)

AnimatedStyle Class

Internal class handling CSS transform processing and optimization.

/**
 * Specialized AnimatedObject for handling CSS transforms
 * Automatically processes x, y, z shortcuts and optimizes transform strings
 */
class AnimatedStyle extends AnimatedObject {
  constructor(style: StyleProps & TransformProps): AnimatedStyle;
}

interface StyleProps extends CSSProperties, TransformProps {
  [key: string]: any;
}

Transform Processing

How different transform properties are processed internally.

interface TransformProcessing {
  /** Shorthand properties (x, y, z) */
  shortcuts: {
    /** Combined into translate3d for optimal performance */
    xyz: 'translate3d(x, y, z)';
  };
  
  /** Standard transform functions */
  functions: {
    translate: '(value)' | '(x, y)';
    translateX: '(value)';
    translateY: '(value)';
    translateZ: '(value)';
    translate3d: '(x, y, z)';
    rotate: '(angle)';
    rotateX: '(angle)';
    rotateY: '(angle)';
    rotateZ: '(angle)';
    rotate3d: '(x, y, z, angle)';
    scale: '(value)' | '(x, y)';
    scaleX: '(value)';
    scaleY: '(value)';
    scaleZ: '(value)';
    scale3d: '(x, y, z)';
    skew: '(angle)' | '(x, y)';
    skewX: '(angle)';
    skewY: '(angle)';
    matrix: '(a, b, c, d, e, f)';
    matrix3d: '(a1, b1, c1, d1, a2, b2, c2, d2, a3, b3, c3, d3, a4, b4, c4, d4)';
  };
}

Performance Considerations

Transform system optimizations for better animation performance.

interface PerformanceOptimizations {
  /** Use translate3d to trigger hardware acceleration */
  hardware_acceleration: 'translate3d()';
  
  /** Combine transforms to minimize reflows */
  transform_combination: 'single_transform_property';
  
  /** Optimize identity transforms */
  identity_detection: 'none_for_identity';
  
  /** Efficient unit addition */
  unit_processing: 'automatic_px_deg_addition';
}

Performance Best Practices:

// Good: Uses shortcuts that combine into translate3d
const efficientStyles = useSpring({
  x: targetX,
  y: targetY,
  rotate: targetRotation,
});

// Less efficient: Separate transform functions
const lessEfficientStyles = useSpring({
  translateX: targetX,
  translateY: targetY,
  rotateZ: targetRotation,
});

// Good: Single transform string for complex cases
const complexStyles = useSpring({
  transform: 'translate3d(100px, 50px, 0) rotate(45deg) scale(1.2)',
});

Identity Transform Detection

The system detects when transforms have no visual effect and optimizes them.

interface IdentityValues {
  /** Translation identity values */
  translation: 0;
  /** Rotation identity values */
  rotation: 0;
  /** Scale identity values */
  scale: 1;
  /** Skew identity values */
  skew: 0;
}

Identity Detection Examples:

// These result in transform: none (optimized out)
const identityStyles = useSpring({
  x: 0,
  y: 0,
  rotate: 0,
  scale: 1,
});

// Mixed identity and non-identity
const mixedStyles = useSpring({
  x: 100,      // Applied
  y: 0,        // Part of translate3d but with 0 value
  rotate: 0,   // Optimized out (identity)
  scale: 1,    // Optimized out (identity)
});
// Results in: transform: translate3d(100px, 0px, 0px)

Custom Transform Strings

When you need complete control over transforms, use the transform property directly.

interface CustomTransforms {
  /** Direct transform string bypasses all processing */
  transform: string;
}

Custom Transform Examples:

// Custom transform string
const customStyles = useSpring({
  transform: 'perspective(1000px) rotateX(45deg) translateZ(100px)',
});

// Interpolated custom transforms
const interpolatedStyles = useSpring({
  transform: progress => `rotate(${progress * 360}deg) scale(${1 + progress * 0.5})`,
});

Install with Tessl CLI