a4b-spring

A TypeScript library for creating spring animations with multiple configuration approaches. Convert between different spring parameter representations and generate physics-based animation parameters.

Features

• 🎯 4 Configuration Methods: Duration/Bounce, Mass/Stiffness/Damping, Response/Damping Ratio, Settling Duration
• 🔄 Bidirectional Conversion: Convert between different parameter representations
• 🎛️ Type-Safe: Full TypeScript support with proper type guards
• 🧮 Physics-Based: Uses actual spring physics calculations
• 🎨 Animation-Ready: Generate parameters perfect for animation libraries
• ⚡ Zero Dependencies: Optimized for performance

Installation

bun add a4b-spring

Or with npm/yarn:

npm install a4b-spring
yarn add a4b-spring

Quick Start

import { createSpring, BOUNCE_PRESET } from 'a4b-spring';

// Create a spring using duration and bounce
const spring = createSpring({
  duration: 0.6,
  bounce: BOUNCE_PRESET.SNAPPY // 0.15
});

console.log(spring);
// {
//   mass: 1,
//   stiffness: 109.66,
//   damping: 18.85,
//   duration: 0.6,
//   bounce: 0.15
// }

Configuration Methods

1. Duration & Bounce

Most intuitive for designers and animators:

const spring = createSpring({
  duration: 0.8,    // Animation duration in seconds
  bounce: 0.3       // Bounce amount (-1 to 1)
});

2. Mass, Stiffness & Damping

Direct physics parameters:

const spring = createSpring({
  mass: 1,
  stiffness: 100,
  damping: 15,
  allowOverDamping: false // Optional: prevent over-damping
});

3. Response & Damping Ratio

Control system approach:

const spring = createSpring({
  response: 0.5,      // Response time
  dampingRatio: 0.8   // Damping ratio (0 = no damping, 1 = critical)
});

4. Settling Duration & Damping Ratio

Specify when animation settles:

const spring = createSpring({
  settlingDuration: 1.0,  // Time to settle within epsilon
  dampingRatio: 0.7,      // Damping ratio
  epsilon: 0.01           // Settlement threshold (default: 0.01)
});

Presets

import { BOUNCE_PRESET } from 'a4b-spring';

const smoothSpring = createSpring({
  duration: 0.5,
  bounce: BOUNCE_PRESET.SMOOTH  // 0
});

const snappySpring = createSpring({
  duration: 0.5,
  bounce: BOUNCE_PRESET.SNAPPY  // 0.15
});

const bouncySpring = createSpring({
  duration: 0.5,
  bounce: BOUNCE_PRESET.BOUNCY  // 0.3
});

Utility Functions

Type Guards

import { 
  isDurationBounceConfig,
  isMassStiffnessDampingConfig,
  isResponseDampingRatioConfig,
  isSettlingDurationConfig 
} from 'a4b-spring';

if (isDurationBounceConfig(config)) {
  // TypeScript knows config has duration and bounce properties
}

Spring Analysis

import { isStableSpring, formatSpring, getPhysicsParams, getAnimationParams } from 'a4b-spring';

const spring = createSpring({ duration: 0.6, bounce: 0.2 });

// Check if spring is stable
console.log(isStableSpring(spring)); // true

// Format spring for display
console.log(formatSpring(spring)); 
// "Spring(duration: 0.60, bounce: 0.20) → (mass: 1, stiffness: 109.66, damping: 20.11)"

// Extract specific parameters
const physics = getPhysicsParams(spring);    // { mass, stiffness, damping }
const animation = getAnimationParams(spring); // { duration, bounce }

Batch Operations

import { createSprings, transformSpring } from 'a4b-spring';

// Create multiple springs
const springs = createSprings([
  { duration: 0.3, bounce: 0.1 },
  { duration: 0.6, bounce: 0.2 },
  { duration: 0.9, bounce: 0.3 }
]);

// Transform a spring
const fasterSpring = transformSpring(spring, ({ duration }) => ({
  duration: duration * 0.5
}));

Use Cases

React Spring

import { useSpring } from '@react-spring/web';
import { createSpring } from 'a4b-spring';

const springConfig = createSpring({ duration: 0.6, bounce: 0.15 });

const styles = useSpring({
  transform: isOpen ? 'scale(1)' : 'scale(0)',
  config: {
    mass: springConfig.mass,
    tension: springConfig.stiffness,
    friction: springConfig.damping
  }
});

Framer Motion

import { motion } from 'framer-motion';
import { createSpring } from 'a4b-spring';

const springConfig = createSpring({ duration: 0.8, bounce: 0.2 });

<motion.div
  animate={{ scale: 1 }}
  transition={{
    type: "spring",
    mass: springConfig.mass,
    stiffness: springConfig.stiffness,
    damping: springConfig.damping
  }}
/>

CSS Springs (via CSS Custom Properties)

const spring = createSpring({ duration: 0.5, bounce: 0.1 });

document.documentElement.style.setProperty('--spring-mass', spring.mass.toString());
document.documentElement.style.setProperty('--spring-stiffness', spring.stiffness.toString());
document.documentElement.style.setProperty('--spring-damping', spring.damping.toString());

API Reference

Types

type SpringResult = {
  mass: number;
  stiffness: number;
  damping: number;
  duration: number;
  bounce: number;
};

type SpringConfig = 
  | DurationBounceConfig
  | MassStiffnessDampingConfig  
  | ResponseDampingConfig
  | SettlingDurationConfig;

Main Functions

• createSpring(config: SpringConfig): SpringResult - Create a spring from any config type
• isStableSpring(spring: SpringResult): boolean - Check if spring parameters are stable
• formatSpring(spring: SpringResult): string - Format spring for display
• createSprings(configs: SpringConfig[]): SpringResult[] - Create multiple springs
• transformSpring(spring, modifier): SpringResult - Transform spring parameters

Development

# Install dependencies
bun install

# Run tests
bun test

# Run tests in watch mode
bun test:watch

# Build the package
bun run build
bun run build:types

License

MIT License

Keywords

spring, easing, animation, physics, typescript, bun, react-spring, framer-motion