Spring Animation Hooks

/**
 * Creates a single spring animation
 * @param config - Spring configuration with from/to values and options  
 * @returns Object with animated values for each configured property
 */
function useSpring(config: SpringConfig): SpringValues;
function useSpring(config: () => SpringConfig): SpringValues;
function useSpring(from: any, to: any): SpringValues;

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

// Basic spring animation
function BasicSpring() {
  const springs = useSpring({
    position: [0, 1, 0],
    rotation: [0, Math.PI, 0],
    from: { position: [0, 0, 0], rotation: [0, 0, 0] },
    config: { tension: 200, friction: 25 },
  });

  return (
    <animated.mesh {...springs}>
      <boxGeometry />
      <meshStandardMaterial />
    </animated.mesh>
  );
}

// Functional config for dynamic values
function DynamicSpring({ active }) {
  const springs = useSpring(() => ({
    scale: active ? [1.2, 1.2, 1.2] : [1, 1, 1],
    color: active ? "#ff6b6b" : "#4ecdc4",
  }));

  return (
    <animated.mesh scale={springs.scale}>
      <boxGeometry />
      <animated.meshStandardMaterial color={springs.color} />
    </animated.mesh>
  );
}

/**
 * Creates multiple spring animations
 * @param count - Number of springs to create
 * @param configs - Array of configurations or function returning configs
 * @returns Array of spring value objects
 */
function useSprings(count: number, configs: SpringConfig[]): SpringValues[];
function useSprings(count: number, configFn: (index: number) => SpringConfig): SpringValues[];

import { animated, useSprings } from "@react-spring/three";

function SpringsList({ items }) {
  const springs = useSprings(
    items.length,
    items.map((item, index) => ({
      position: [index * 2, 0, 0],
      rotation: [0, item.rotation, 0],
      from: { position: [0, -10, 0], rotation: [0, 0, 0] },
      delay: index * 100,
    }))
  );

  return (
    <>
      {springs.map((spring, index) => (
        <animated.mesh key={index} {...spring}>
          <boxGeometry />
          <meshStandardMaterial color={items[index].color} />
        </animated.mesh>
      ))}
    </>
  );
}

/**
 * Creates a single animated value
 * @param initial - Initial value
 * @returns SpringValue instance with control methods
 */
function useSpringValue(initial: any): SpringValue;

import { animated, useSpringValue } from "@react-spring/three";
import { useEffect } from "react";

function SingleValueSpring() {
  const opacity = useSpringValue(0);

  useEffect(() => {
    opacity.start({ to: 1, config: { duration: 1000 } });
  }, []);

  return (
    <mesh>
      <boxGeometry />
      <animated.meshStandardMaterial transparent opacity={opacity} />
    </mesh>
  );
}

/**
 * Creates a spring reference for imperative control
 * @returns SpringRef with control methods
 */
function useSpringRef(): SpringRef;

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

function ImperativeSpring() {
  const ref = useSpringRef();
  const springs = useSpring({
    ref,
    position: [0, 0, 0],
    from: { position: [0, -5, 0] },
    config: { tension: 280, friction: 60 },
  });

  const handleClick = () => {
    ref.start({ position: [Math.random() * 4 - 2, Math.random() * 4 - 2, 0] });
  };

  return (
    <animated.mesh {...springs} onClick={handleClick}>
      <boxGeometry />
      <meshStandardMaterial />
    </animated.mesh>
  );
}

/**
 * Creates a trail of staggered springs
 * @param count - Number of items in trail
 * @param config - Spring configuration applied to all items
 * @returns Array of spring values with staggered timing
 */
function useTrail(count: number, config: SpringConfig): SpringValues[];
function useTrail(count: number, configFn: (index: number) => SpringConfig): SpringValues[];

import { animated, useTrail } from "@react-spring/three";

function TrailAnimation({ items }) {
  const trail = useTrail(items.length, {
    position: items.map((_, i) => [i * 2, 0, 0]),
    opacity: 1,
    from: { position: [0, -10, 0], opacity: 0 },
    config: { mass: 5, tension: 2000, friction: 200 },
  });

  return (
    <>
      {trail.map((springs, index) => (
        <animated.mesh key={index} {...springs}>
          <sphereGeometry args={[0.5]} />
          <animated.meshStandardMaterial transparent />
        </animated.mesh>
      ))}
    </>
  );
}

/**
 * Creates enter/exit transitions for dynamic lists
 * @param items - Array of items to transition
 * @param config - Transition configuration with enter/leave/update
 * @returns Array of transition render props
 */
function useTransition<T>(
  items: T[],
  config: TransitionConfig<T>
): TransitionValues<T>[];

interface TransitionConfig<T> {
  from?: any;
  enter?: any;
  update?: any;
  leave?: any;
  keys?: (item: T) => any;
  trail?: number;
  expires?: boolean | number;
  config?: SpringConfig["config"];
}

interface TransitionValues<T> {
  item: T;
  key: any;
  props: SpringValues;
}

import { animated, useTransition } from "@react-spring/three";

function TransitionList({ items }) {
  const transitions = useTransition(items, {
    from: { position: [0, -2, 0], opacity: 0, scale: [0, 0, 0] },
    enter: { position: [0, 0, 0], opacity: 1, scale: [1, 1, 1] },
    leave: { position: [0, 2, 0], opacity: 0, scale: [0, 0, 0] },
    keys: (item) => item.id,
  });

  return (
    <>
      {transitions.map(({ item, key, props }) => (
        <animated.mesh key={key} {...props}>
          <boxGeometry />
          <meshStandardMaterial color={item.color} />
        </animated.mesh>
      ))}
    </>
  );
}

interface SpringConfig {
  from?: any;
  to?: any;
  config?: {
    tension?: number;
    friction?: number;
    mass?: number;
    clamp?: boolean;
    precision?: number;
    velocity?: number;
    duration?: number;
    easing?: (t: number) => number;
  };
  loop?: boolean | LoopConfig;
  delay?: number;
  immediate?: boolean;
  reset?: boolean;
  reverse?: boolean;
  cancel?: boolean;
  pause?: boolean;
  onStart?: (result: AnimationResult) => void;
  onChange?: (result: AnimationResult) => void;
  onRest?: (result: AnimationResult) => void;
}

interface SpringValues {
  [key: string]: SpringValue;
}

interface SpringRef {
  start(config?: Partial<SpringConfig>): Promise<void>;
  stop(): void;
  update(config: Partial<SpringConfig>): void;
  set(values: any): void;
}

class SpringValue {
  get(): any;
  set(value: any): void;
  start(config?: SpringConfig): Promise<void>;
  stop(): void;
  to(value: any): Promise<void>;
}

interface LoopConfig {
  reverse?: boolean;
  reset?: boolean;
}

interface AnimationResult {
  value: any;
  finished: boolean;
  cancelled: boolean;
}