0
# Popmotion
1

2
Popmotion is a powerful, low-level JavaScript animation library designed to be the animator's toolbox. It provides comprehensive animation capabilities including keyframe, spring, and decay animations for numbers, colors, and complex strings. Built with TypeScript, it offers over 95% test coverage and maintains a tiny footprint (~4.5kb for the animate function).
3

4
## Package Information
5

6
- **Package Name**: popmotion  
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install popmotion`
10

11
## Core Imports
12

13
```typescript
14
import { animate, spring, decay, keyframes } from "popmotion";
15
```
16

17
For CommonJS:
18

19
```javascript
20
const { animate, spring, decay, keyframes } = require("popmotion");
21
```
22

23
## Basic Usage
24

25
```typescript
26
import { animate, spring, interpolate, mix } from "popmotion";
27

28
// Basic animation
29
animate({
30
  from: 0,
31
  to: 100,
32
  duration: 1000,
33
  ease: "easeInOut",
34
  onUpdate: (latest) => console.log(latest),
35
  onComplete: () => console.log("Animation complete")
36
});
37

38
// Spring animation
39
animate({
40
  from: 0,
41
  to: 100,
42
  type: "spring",
43
  stiffness: 400,
44
  damping: 40,
45
  onUpdate: (value) => element.style.left = value + "px"
46
});
47

48
// Color interpolation
49
const mixColors = interpolate([0, 1], ["#ff0000", "#0000ff"]);
50
console.log(mixColors(0.5)); // Mixed color
51
```
52

53
## Architecture
54

55
Popmotion is built around several key components:
56

57
- **Core Animation Engine**: The `animate` function providing unified interface for all animation types
58
- **Animation Generators**: Specialized generators for spring, decay, and keyframe animations
59
- **Utility Functions**: Mathematical and interpolation utilities for animation calculations
60
- **Easing System**: Comprehensive set of easing functions with custom easing support
61
- **Type System**: Full TypeScript integration with generic type preservation across all operations
62

63
## Capabilities
64

65
### Core Animation
66

67
Primary animation function with support for spring, decay, and keyframe animations. Includes repeat modes, playback controls, and lifecycle callbacks.
68

69
```typescript { .api }
70
function animate<V = number>(options: AnimationOptions<V>): PlaybackControls;
71

72
interface PlaybackControls {
73
  stop: () => void;
74
}
75

76
type AnimationOptions<V> = PlaybackOptions<V> & 
77
  (DecayOptions | KeyframeOptions<V> | SpringOptions);
78

79
interface PlaybackOptions<V> {
80
  autoplay?: boolean;
81
  driver?: Driver;
82
  elapsed?: number;
83
  from?: V;
84
  repeat?: number;
85
  repeatType?: "loop" | "reverse" | "mirror";
86
  repeatDelay?: number;
87
  type?: "spring" | "decay" | "keyframes";
88
  onUpdate?: (latest: V) => void;
89
  onPlay?: () => void;
90
  onComplete?: () => void;
91
  onRepeat?: () => void;
92
  onStop?: () => void;
93
}
94
```
95

96
[Core Animation](./core-animation.md)
97

98
### Animation Generators
99

100
Specialized animation generators for creating different types of motion with precise control over physics parameters and timing.
101

102
```typescript { .api }
103
function spring(options: SpringOptions): Animation<number>;
104
function decay(options: DecayOptions): Animation<number>;  
105
function keyframes(options: KeyframeOptions): Animation<number | string>;
106

107
interface SpringOptions extends PhysicsSpringOptions {
108
  from?: number;
109
  to?: number;
110
  duration?: number;
111
  bounce?: number;
112
  restSpeed?: number;
113
  restDelta?: number;
114
}
115

116
interface DecayOptions {
117
  from?: number;
118
  to?: number;
119
  velocity?: number;
120
  power?: number;
121
  timeConstant?: number;
122
  modifyTarget?: (target: number) => number;
123
  restDelta?: number;
124
}
125

126
interface KeyframeOptions<V = number> {
127
  to: V | V[];
128
  from?: V;
129
  duration?: number;
130
  ease?: Easing | Easing[];
131
  offset?: number[];
132
}
133
```
134

135
[Animation Generators](./animation-generators.md)
136

137
### Easing Functions
138

139
Comprehensive collection of easing functions for natural motion feel, plus utilities for creating custom easing curves and modifying existing ones.
140

141
```typescript { .api }
142
type Easing = (v: number) => number;
143

144
// Basic easing functions
145
const linear: Easing;
146
const easeIn: Easing;
147
const easeOut: Easing;
148
const easeInOut: Easing;
149

150
// Custom easing generators
151
function cubicBezier(mX1: number, mY1: number, mX2: number, mY2: number): Easing;
152
function steps(steps: number, direction?: Direction): Easing;
153
function createExpoIn(power: number): Easing;
154
function createBackIn(power: number): Easing;
155
function createAnticipate(power: number): Easing;
156

157
// Easing modifiers
158
function mirrorEasing(easing: Easing): Easing;
159
function reverseEasing(easing: Easing): Easing;
160
```
161

162
[Easing Functions](./easing.md)
163

164
### Utility Functions
165

166
Mathematical and interpolation utilities for animation calculations, including value mixing, clamping, geometric operations, type conversion, and attraction effects.
167

168
```typescript { .api }
169
function interpolate<T>(
170
  input: number[], 
171
  output: T[], 
172
  options?: InterpolateOptions<T>
173
): (v: number) => T;
174

175
function mix(from: number, to: number, progress: number): number;
176
function clamp(min: number, max: number, v: number): number;
177
function progress(from: number, to: number, value: number): number;
178
function attract(constant: number, origin: number, v: number): number;
179
function attractExpo(constant: number, origin: number, v: number): number;
180

181
interface InterpolateOptions<T> {
182
  clamp?: boolean;
183
  ease?: Easing | Easing[];
184
  mixer?: MixerFactory<T>;
185
}
186
```
187

188
[Utility Functions](./utilities.md)
189

190
### Inertia Animation
191

192
Specialized inertia animation combining decay with spring physics for scroll-like behaviors with boundaries.
193

194
```typescript { .api }
195
function inertia(options: InertiaOptions): PlaybackControls;
196

197
interface InertiaOptions extends DecayOptions {
198
  bounceStiffness?: number;
199
  bounceDamping?: number;
200
  min?: number;
201
  max?: number;
202
  restSpeed?: number;
203
  restDelta?: number;
204
  driver?: Driver;
205
  onUpdate?: (v: number) => void;
206
  onComplete?: () => void;
207
  onStop?: () => void;
208
}
209
```
210

211
[Inertia Animation](./inertia.md)
212

213
## Core Types
214

215
```typescript { .api }
216
interface Animation<V> {
217
  next: (t: number) => { value: V; done: boolean };
218
  flipTarget: () => void;
219
}
220

221
interface AnimationState<V> {
222
  value: V;
223
  done: boolean;
224
}
225

226
type Driver = (update: (timestamp: number) => void) => DriverControls;
227

228
interface DriverControls {
229
  start: () => void;
230
  stop: () => void;
231
}
232

233
type Point2D = {
234
  x: number;
235
  y: number;
236
};
237

238
type Point3D = Point2D & {
239
  z: number;
240
};
241

242
type Point = Point2D | Point3D;
243

244
interface PhysicsSpringOptions {
245
  velocity?: number;
246
  stiffness?: number;
247
  damping?: number;
248
  mass?: number;
249
}
250

251
type MixerFactory<T> = (from: T, to: T) => (v: number) => T;
252
```