pacer-js 1.0.4 → 1.0.5

package/Pacer.js

@@ -22,6 +22,7 @@ import {
 
 	isUsefulNumber,
 	isNotUsefulNumber,
+	isUsefulString,
 	normalize,
 	normalize01,
 	lerp
@@ -33,11 +34,13 @@ import {
 
 class Key {
 	
-	constructor( timeAbsolute, values ){
+	constructor( timeAbsolute, values, callback ){
 
 		this.timeAbsolute = timeAbsolute
 		this.values = values instanceof Object ? values : {}
+		this.onKey  = callback
 		this.tween  = Pacer.linear//  Default tween method is linear interpolation.
+		this.label  = ''
 		this.guarantee = true
 	}
 }
@@ -47,10 +50,10 @@ class Key {
 
 class Pacer {
 	
-	constructor( label ){
+	constructor( label, units ){
 		
-		this._label = label
-		this.units = 'ms'// ms, milliseconds, s, seconds, #, n, norm, normalize, normalized, %, percent
+		this._label = isUsefulString( label ) ? label : 'Untitled Pacer instance'
+		this._units = isUsefulString( units ) ? units : 'ms'// ms, milliseconds, s, seconds, #, n, norm, normalize, normalized, %, percent
 
 		this.keys = []
 		this.keyIndex = -1
@@ -60,9 +63,9 @@ class Pacer {
 		this.n = 0
 		this.direction = 1
 		this.isClamped = true
-	
-		this.instanceIndex = Pacer.all.length
+		
 		this.isEnabled = true
+		this.instanceIndex = Pacer.all.length
 		Pacer.all.push( this )
 	}
 	
@@ -71,17 +74,30 @@ class Pacer {
 
 	//  Non-chainable.
 
-	inspect(){
+	inspect( useRelative ){
 
-		// return [ this.timeStart, this.keys ]
-
-		return this.keys
+		const scope = this
+		let out = ''
+		out += '\n'+ this._label
+		out += '\n'+ new Array( this._label.length ).fill( '─' ).join( '' )
+		out += this.keys
 		.reduce( function( output, key ){
 
+			output += '\n'
+			output += useRelative === true && isUsefulNumber( key.timeRelative )
+				? ' +'+ key.timeRelative 
+				: '  '+ key.timeAbsolute
+			output += scope._units +'  '
+			if( isUsefulString( key.label )) output += key.label +'  ' 
+			output += JSON.stringify( key.values )
+			return output
+
+		}, '' )
 
-			return output +'\n'+ key.timeAbsolute +' '+ JSON.stringify( key.values )
 
-		}, '\n'+ this._label )
+		//  Should add things like timeCursor, total n, etc.
+
+		return out +'\n\n'
 	}
 	getFirstKey(){
 
@@ -192,7 +208,7 @@ class Pacer {
 		this.setTimeBounds()
 		return this
 	}
-	key( time, values, isAbsolute ){
+	key( time, values, callback, isAbsolute ){
 
 		if( isAbsolute !== true &&//  Making a theoretical `isRelative` the default for backwards compatibility.
 			this.keys.length > 0 ){
@@ -200,44 +216,74 @@ class Pacer {
 			time += this.getLastKey().timeAbsolute
 		}
 		if( this.keys.length === 0 ) this.values = values
-		const key = new Key( time, values )
+		const key = new Key( time, values, callback )
 		this.lastTouchedKey = key
 		this.keys.push( key )
 		this.sortKeys()
 		if( this.keys.length === 1 ) this.timeCursor = this.timeStart - 1
 		return this
 	}
-	rel( timeRelative, values ){
+	rel( timeRelative, values, callback ){
+
+		return this.key( timeRelative, values, callback, false )
+	}
+	abs( timeAbsolute, values, callback ){
+
+		return this.key( timeAbsolute, values, callback, true )
+	}
+
+
+	labelPacer( s ){
+
+		this._label = s
+		return this
+	}
+	label( s ){
 
-		return this.key( timeRelative, values, false )
+		this.lastTouchedKey.label = s
+		return this
 	}
-	abs( timeAbsolute, values ){
+	values( v ){
 
-		return this.key( timeAbsolute, values, true )
+		this.lastTouchedKey.values = v
+		return this
 	}
 	tween( fn ){
 
 		this.lastTouchedKey.tween = fn
 		return this
 	}
-	label( x ){
+	clamp(){
 
-		this.lastTouchedKey.label = x
+		this.isClamped = true
 		return this
 	}
+	unclamp(){
+
+
+		this.isClamped = false
+		return this
+	}
+	units( u ){
+
+		this._units = u
+		return this
+	}
+
+
 	onKey( fn ){
 
-		this.lastTouchedKey._onKey = fn
+		this.lastTouchedKey.onKey = fn
 		return this
 	}
 	onTween( fn ){
 
-		this.lastTouchedKey._onTween = fn
+		this.lastTouchedKey.onTween = fn
 		return this
 	}
 	onCancel( fn ){
 
-		this.lastTouchedKey._onCancel = fn
+		this.lastTouchedKey.onCancel = fn
 		return this
 	}
 
@@ -415,9 +461,9 @@ class Pacer {
 				if( tempKey instanceof Key &&
 					tempKey.guarantee === true ){
 
-					if( typeof tempKey._onKey === 'function' ){
+					if( typeof tempKey.onKey === 'function' ){
 
-						tempKey._onKey( tempKey.values, this )
+						tempKey.onKey( tempKey.values, this )
 					}
 					if( typeof this._onEveryKey === 'function' ){
 
@@ -440,9 +486,9 @@ class Pacer {
 				if( tempKey instanceof Key &&
 					tempKey.guarantee === true ){
 
-					if( typeof tempKey._onKey === 'function' ){
+					if( typeof tempKey.onKey === 'function' ){
 
-						tempKey._onKey( tempKey.values, this )
+						tempKey.onKey( tempKey.values, this )
 					}
 					if( typeof this._onEveryKey === 'function' ){
 

package/README.md

@@ -21,7 +21,7 @@ Getting you from A to B since 2025.
 
 ##  TL;DR
 
-__Pacer__ is a light-weight keyframing toolkit inspired by [Soledad Penadés](https://soledadpenades.com/)’ original [tween.js](https://soledadpenades.com/projects/tween-js/) masterpiece. List your keyframes as time / value pairs, and __Pacer__ will ✨ tween your numbers and 📞 call your callbacks. __It’s minimal__. Only does what it needs to. __It’s reliable__. We use this in our own professional projects. We found the bumps and sanded them down so you won’t have to ✔️ Either include the `Pacer.js` ES6 module in your codebase, or install the Node package:
+__Pacer__ is a light-weight keyframing toolkit inspired by [Soledad Penadés](https://soledadpenades.com/)’ original [tween.js](https://soledadpenades.com/projects/tween-js/) masterpiece. List your keyframes as time / value pairs, and __Pacer__ will ✨ tween your numbers and 📞 call your callbacks. __It’s minimal__. Only does what it needs to. __It’s reliable__. We use this in our own professional projects. We found the bumps and sanded them down so you won’t have to ✔️ Either include the `Pacer.js` ES6 module in your codebase, or install the [Node package](https://www.npmjs.com/package/pacer-js):
 
 ```shell
 npm install pacer-js
@@ -367,7 +367,11 @@ As you’d hope, __Pacer__ will also call `onEveryKey` when it honors `onKey` fo
 
 ###  Outside the box
 
-What happens outside of your declared keyframes? __Pacer__ automatically extrapolates your first and last tweens forward and backward in time, beyond your declared keyframes. You often don’t need this—but when you do, you do. Let’s say you have two keyframes, __A__ at time __0__, and __B__ at time __2__. They’re tweening a value, `n`, from `0` to `1` using the default linear interpolation easing function. As a result you can see that at time __1__, the tweened value of `n` will be `0.5`—halfway between its keyframed values of `0` and `1`. So far so good?
+What happens outside of your declared keyframes? Nothing. Until you do this with your __Pacer__ instance:
+```javascript
+p.unclamp()
+```
+When your __Pacer__ instance is unclamped, it will automatically extrapolate your first and last tweens forward and backward in time, beyond your declared timeline of keyframes. You often don’t need this—but when you do, you do. Let’s say you have two keyframes, __A__ at time __0__, and __B__ at time __2__. They’re tweening a value, `n`, from `0` to `1` using the default linear interpolation easing function. As a result you can see that at time __1__, the tweened value of `n` will be `0.5`—halfway between its keyframed values of `0` and `1`. So far so good?
 
 
 ```
@@ -440,11 +444,31 @@ Let’s cram in a bunch of different feature highlights into this one verbose ex
 
 ```javascript
 //  We’ll start off with the basics.
+
 //  Did you know you can label a Pacer instance
 //  by passing it a String?
 //  That’s useful for debugging later.
 
-var p = new Pacer( 'My first Pacer' )
+//  We can also optionally declare our time unit.
+//  Let’s use “s” for “seconds.”
+
+var p = new Pacer( 'My first Pacer', 's' )
+
+
+//  Actually, I lied.
+//  This is my SECOND Pacer instance ever.
+//  Let’s correct that:
+
+.labelPacer( 'My SECOND Pacer' )
+
+
+//  And, oops--we’re using milliseconds.
+//  Either way would be fine, 
+//  as Pacer doesn’t care what units you use.
+//  This is more for inspection / debugging,
+//  and human reasoning around more complex Pacers.
+
+.units( 'ms' )
 
 
 //  Three keyframes, alike in dignity.
@@ -466,13 +490,13 @@ var p = new Pacer( 'My first Pacer' )
 //  Now let’s have some fun with tweening.
 
 .key( 2000, { n: 300 })
-.label( 'My first tween!' )
+.label( 'My first tween begins!' )
 .tween( Pacer.sine.in )
 .onKey(( e, p )=> console.log( p.getCurrentKey().label ))
 .onTween(( e )=> console.log( 'Tweened value:', e.n ))
 
 .key( 2000, { n: 400 })
-.label( 'My second tween' )
+.label( 'My second tween begins.' )
 .tween( Pacer.quadratic.out )
 .onKey(( e, p )=> console.log( p.getCurrentKey().label ))
 .onTween(( e )=> console.log( 'Tweened value:', e.n ))
@@ -492,7 +516,7 @@ var p = new Pacer( 'My first Pacer' )
 ))
 
 
-//  Can haz multiple tweens at once?
+//  Can haz multiple tweened values at once?
 //  Of course you can!
 
 .key( 2000, { n: 600, x: 100 })
@@ -500,6 +524,27 @@ var p = new Pacer( 'My first Pacer' )
 .key( 2000, { n: 700, x: -100 })
 
 
+//  Let’s look at some keyframe declaration variations.
+
+.key( 
+	
+	2000, 
+	{ n: 800 }, 
+	( e, p )=> console.log(
+
+		'💫 Did you know, '+
+		'you can actually specify an onKey callback '+
+		'right in the keyframe declaration itself?'
+	)
+)
+.key( 2000 )
+.values({ n: 900 })
+.onKey(( e, p )=> console.log(
+
+	'Or keep each argument entirely separate.'
+))
+
+
 //  Totally commenting these out
 //  in case you copy and paste this whole thing
 //  into your console.
@@ -516,7 +561,24 @@ var p = new Pacer( 'My first Pacer' )
 })
 
 
-//  Note that for “before” `keyIndex` will be 
+//  Pacers are “clamped” by default,
+//  ie. their values do not extend to before their first keyframe
+//  or extend beyond their final keyframe.
+//  Because we’re already clamped, this will do nothing:
+
+.clamp()
+
+
+//  But what if we wanted to take our keyframes and tweens
+//  at either end of the timeline
+//  and extend them outward to infinity?
+//  We’d better unclamp!
+
+.unclamp()
+
+
+//  Now we can have steps beyond our timeline.
+//  Note that for our “before” `keyIndex` will be 
 // “out of bounds” with a value of -1,
 //  so `getCurrentKey()` will return undefined.
 //  This is intended. We’re out of keyframes!

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pacer-js",
-  "version": "1.0.4",
+  "version": "1.0.5",
   "description": "Getting you from A to B since 2025.",
   "keywords": [
     "animate",