# packages/core/src/lib/animation/easing.ts This is the source snapshot used to build these API details. [View this revision on GitHub](https://github.com/benlesh/pibbl/blob/272a94aaf62e0bd6ad8726a4c607a76a9ec44ca1/packages/core/src/lib/animation/easing.ts#L94). [Back to reference](/reference/functions/easing/)
1 import type { tween } from './definition.js';
2 import type { PibblEasing } from './types.js';
3 
4 const NEWTON_ITERATIONS = 8;
5 const BISECTION_ITERATIONS = 50;
6 
7 function clampProgress(progress: number): number {
8   return Math.min(1, Math.max(0, progress));
9 }
10 
11 function assertFiniteControl(value: number, name: string): void {
12   if (!Number.isFinite(value)) {
13     throw new RangeError(`Pibbl cubic bezier ${name} must be finite.`);
14   }
15 }
16 
17 function sampleCurve(t: number, first: number, second: number): number {
18   const inverse = 1 - t;
19   return 3 * inverse * inverse * t * first +
20     3 * inverse * t * t * second +
21     t * t * t;
22 }
23 
24 function sampleDerivative(t: number, first: number, second: number): number {
25   const inverse = 1 - t;
26   return 3 * inverse * inverse * first +
27     6 * inverse * t * (second - first) +
28     3 * t * t * (1 - second);
29 }
30 
31 function cubicBezier(
32   x1: number,
33   y1: number,
34   x2: number,
35   y2: number,
36 ): PibblEasing {
37   assertFiniteControl(x1, 'x1');
38   assertFiniteControl(y1, 'y1');
39   assertFiniteControl(x2, 'x2');
40   assertFiniteControl(y2, 'y2');
41   if (x1 < 0 || x1 > 1 || x2 < 0 || x2 > 1) {
42     throw new RangeError('Pibbl cubic bezier x1 and x2 must be within [0, 1].');
43   }
44 
45   return (input: number): number => {
46     const progress = clampProgress(input);
47     if (progress === 0 || progress === 1) return progress;
48 
49     let parameter = progress;
50     for (let iteration = 0; iteration < NEWTON_ITERATIONS; iteration++) {
51       const x = sampleCurve(parameter, x1, x2) - progress;
52       const slope = sampleDerivative(parameter, x1, x2);
53       if (Math.abs(slope) < 1e-7) break;
54       const candidate = parameter - x / slope;
55       if (candidate < 0 || candidate > 1) break;
56       parameter = candidate;
57     }
58 
59     let lower = 0;
60     let upper = 1;
61     for (let iteration = 0; iteration < BISECTION_ITERATIONS; iteration++) {
62       const x = sampleCurve(parameter, x1, x2);
63       if (x < progress) lower = parameter;
64       else upper = parameter;
65       parameter = (lower + upper) / 2;
66     }
67     return sampleCurve(parameter, y1, y2);
68   };
69 }
70 
71 function steps(count: number, position: 'start' | 'end' = 'end'): PibblEasing {
72   if (!Number.isInteger(count) || count <= 0) {
73     throw new RangeError('Pibbl steps count must be a positive integer.');
74   }
75   if (position !== 'start' && position !== 'end') {
76     throw new TypeError('Pibbl steps position must be "start" or "end".');
77   }
78 
79   return (input: number): number => {
80     const progress = clampProgress(input);
81     if (position === 'start') {
82       return Math.min(1, (Math.floor(progress * count) + 1) / count);
83     }
84     return progress === 1 ? 1 : Math.floor(progress * count) / count;
85   };
86 }
87 
88 /**
89  * Built-in easing functions for mapping normalized animation progress.
90  *
91  * @see {@link PibblEasing}
92  * @see {@link tween}
93  */
94 export const easing = Object.freeze({
95   /**
96    * Returns clamped progress unchanged. See {@link PibblEasing}.
97    * @param progress - Input progress, clamped to the interval [0, 1].
98    * @returns The clamped progress.
99    */
100   linear: (progress: number): number => clampProgress(progress),
101   /**
102    * Creates a cubic Bézier easing; control-point x coordinates must be finite and within [0, 1].
103    * See {@link PibblEasing}.
104    * @param x1 - First control point horizontal coordinate, in [0, 1].
105    * @param y1 - Finite first control point vertical coordinate.
106    * @param x2 - Second control point horizontal coordinate, in [0, 1].
107    * @param y2 - Finite second control point vertical coordinate.
108    * @returns A cubic Bézier easing function. See {@link PibblEasing}.
109    */
110   cubicBezier,
111   /**
112    * Accelerates from rest using the CSS ease-in control points. See {@link easing}.
113    * @param progress - Input progress, clamped to [0, 1].
114    * @returns Eased progress. See {@link PibblEasing}.
115    */
116   easeIn: cubicBezier(0.42, 0, 1, 1),
117   /**
118    * Decelerates toward rest using the CSS ease-out control points. See {@link easing}.
119    * @param progress - Input progress, clamped to [0, 1].
120    * @returns Eased progress. See {@link PibblEasing}.
121    */
122   easeOut: cubicBezier(0, 0, 0.58, 1),
123   /**
124    * Accelerates then decelerates using the CSS ease-in-out control points. See {@link easing}.
125    * @param progress - Input progress, clamped to [0, 1].
126    * @returns Eased progress. See {@link PibblEasing}.
127    */
128   easeInOut: cubicBezier(0.42, 0, 0.58, 1),
129   /**
130    * Creates a stepped easing with a positive integer count and start or end jump placement. See
131    * {@link easing}.
132    * @param count - Positive integer number of steps.
133    * @param position - Whether jumps occur at the start or end of each interval; defaults to end.
134    * @returns A stepped easing function. See {@link PibblEasing}.
135    */
136   steps,
137 });
138
## Documentation version Documentation built with @pibbl/core 0.0.2, revision 272a94a. ALPHA — NOT FOR PRODUCTION USE.