react-voodoo 2.5.16 → 2.6.0

package/jest.config.js

@@ -0,0 +1,16 @@
+module.exports = {
+	testEnvironment: 'jest-environment-jsdom',
+
+	setupFilesAfterEnv: ['<rootDir>/etc/tests/jest.setup.js'],
+
+	transform: {
+		'^.+\\.[jt]sx?$': 'babel-jest',
+	},
+
+testMatch: ['<rootDir>/etc/tests/**/*.test.{js,jsx}'],
+
+	// tween-axis ships a CJS dist — no transformation needed.
+	// d3-ease and color-rgba expose CJS-compatible builds.
+	// The local dist/ bundle is already compiled CJS — skip babel on it too.
+	transformIgnorePatterns: ['/node_modules/', '/dist/'],
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-voodoo",
-  "version": "2.5.16",
+  "version": "2.6.0",
   "license": "(CC-BY-ND-4.0 OR AGPL-3.0-only)",
   "main": "./dist/react-voodoo.js",
   "author": "Nathan Braun <n8tz.js@gmail.com>",
@@ -9,8 +9,9 @@
   "scripts": {
     "build": "lpack",
     "devLib": "lpack :staging -w",
-    "test": "echo ok",
-    "testAuto": "nodemon --watch ./dist/react-voodoo.js --watch ./etc/tests/**/*.js --exec \"npm test\"",
+    "test": "jest",
+    "test:watch": "jest --watch",
+    "testAuto": "nodemon --watch ./src --watch ./etc/tests --exec \"npm test\"",
     "setupLayers": "lpack-setup"
   },
   "peerDependencies": {
@@ -25,13 +26,18 @@
     "fast-deep-equal": "^3.1.3",
     "is": "^3.3.0",
     "shortid": "^2.2.16",
-    "tween-axis": "^2.0.3"
+    "tween-axis": "^2.1.0"
   },
   "devDependencies": {
+    "@babel/preset-env": "^7.24.0",
+    "@babel/preset-react": "^7.24.0",
     "@babel/register": "^7.24.6",
     "@testing-library/jest-dom": "^6.4.6",
     "@testing-library/react": "^16.0.0",
+    "babel-jest": "^29.0.0",
     "docdash": "^2.0.2",
+    "jest": "^29.0.0",
+    "jest-environment-jsdom": "^29.0.0",
     "jsdoc": "^4.0.3",
     "layer-pack": "^3.0.7",
     "lpack-react": "^2.2.0",

package/readme.md

@@ -1,62 +1,94 @@
 <h1 align="center">react-voodoo</h1>
-<p align="center">Fast, SSR ready, additive & swipeable, tween composition engine for React</p>
-
-___
-<p align="center"><img  width="192" src ="https://github.com/react-voodoo/react-voodoo/raw/master/doc/assets/logo-v0.png?sanitize=true" /></p>
+<p align="center"><b>Additive · Swipeable · SSR-ready · Physics-based</b><br/>A delta-driven tween composition engine for React</p>
 
+<p align="center"><img width="192" src="https://github.com/react-voodoo/react-voodoo/raw/master/doc/assets/logo-v0.png?sanitize=true" /></p>
 
 <p align="center">
-<a href="https://www.npmjs.com/package/react-voodoo">
-<img src="https://img.shields.io/npm/v/react-voodoo.svg" alt="Npm version" /></a>
-<a href="https://travis-ci.org/react-voodoo/react-voodoo">
-<img src="https://travis-ci.org/react-voodoo/react-voodoo.svg?branch=master" alt="Build Status" /></a>
+<a href="https://www.npmjs.com/package/react-voodoo"><img src="https://img.shields.io/npm/v/react-voodoo.svg" alt="npm version" /></a>
+<a href="https://travis-ci.org/react-voodoo/react-voodoo"><img src="https://travis-ci.org/react-voodoo/react-voodoo.svg?branch=master" alt="Build Status" /></a>
 <img src="https://img.shields.io/badge/contributions-welcome-brightgreen.svg?style=flat" />
 <br/>
-<a href="http://creativecommons.org/licenses/by-nd/4.0">
-<img src="https://img.shields.io/badge/License-CC%20BY--ND%204.0-lightgrey.svg" alt="License: CC BY-ND 4.0" /></a>
-<a href="http://www.gnu.org/licenses/agpl-3.0">
-<img src="https://img.shields.io/badge/License-AGPL%20v3-blue.svg" alt="License: AGPL v3" /></a>
+<a href="http://creativecommons.org/licenses/by-nd/4.0"><img src="https://img.shields.io/badge/License-CC%20BY--ND%204.0-lightgrey.svg" alt="License: CC BY-ND 4.0" /></a>
+<a href="http://www.gnu.org/licenses/agpl-3.0"><img src="https://img.shields.io/badge/License-AGPL%20v3-blue.svg" alt="License: AGPL v3" /></a>
 </p>
 
-## Why another animation engine ?
+<p align="center">
+  <a href="doc/readme.md"><b>Full documentation</b></a> &nbsp;·&nbsp;
+  <a href="https://react-voodoo.github.io/react-voodoo-samples/"><b>Live demos & CodeSandbox</b></a> &nbsp;·&nbsp;
+  <a href="https://github.com/react-voodoo/react-voodoo-samples"><b>Sample sources</b></a>
+</p>
 
-Classic Tween engines can only output absolute values, which quickly results in very complex code when we have to
-gradually compose values from multiple sources (e.g. when merging multiple animations based on user drag interactions )
-.<br/>
+<p align="center"><img src="https://github.com/react-voodoo/react-voodoo/raw/master/doc/assets/demo.gif?sanitize=true" /></p>
 
-React-Voodoo use a delta-based interpolation engine that solves this problem, it allows:
+---
 
-- Additive tween 
-- Swipeable complex animations ( like Android & iOS )
-- Fast & direct DOM updates ( not bound to the React rendering loop )
-- Server Side Rendering of any scroll / swipe position
-- Easily connect sensors / gestures to complex animations
-- Hot switching scrollable anims ( responsive )
-- Predictive inertia ( knowing where inertia will stop while animating )
-- Multitouch dragging ( drag multiple things at once )
-- Intuitive & flexible animation system
-- Cool ( & performant ) React integration
-- Automatically deal with multiple units using css "calc( ... )"
-- etc...
+## Why react-voodoo?
 
-## Basic documentation [here](doc/readme.md)
+Most animation libraries output **absolute values** — they own a CSS property and write a number to it each frame. That works fine for isolated transitions, but breaks down the moment you need to combine sources: a scroll position driving `translateY`, a drag gesture adding to the same `translateY`, and a parallax offset stacking on top. The libraries fight each other and you end up writing glue code.
 
-## Live demo & codesandbox [here](https://react-voodoo.github.io/react-voodoo-samples/)
+React-voodoo takes a different approach: its engine computes **deltas** — the *change* from the previous frame — and accumulates them additively across any number of axes. Multiple animations on the same property simply add together. No ownership, no conflicts.
 
-<p align="center"><img src ="https://github.com/react-voodoo/react-voodoo/raw/master/doc/assets/demo.gif?sanitize=true" /></p>
+This unlocks a set of features that are unique to the delta model:
 
-## Samples sources [here](https://github.com/react-voodoo/react-voodoo-samples)
+| Feature | How |
+|---|---|
+| **Additive multi-axis composition** | Each axis contributes a delta; they stack without coordination code. |
+| **Swipeable / draggable animations** | Drag gestures are mapped directly to axis positions with realistic momentum. |
+| **Predictive inertia** | The engine computes the final snap target *at the moment of release*, before the animation plays out — useful for preloading the next slide. |
+| **SSR with correct initial styles** | Axes have a `defaultPosition`; styles are computed server-side and rendered inline — no flash on first paint. |
+| **DOM writes bypass React** | Style updates go straight to `node.style` via direct DOM writes, never triggering a re-render. |
+| **Multi-unit CSS via `calc()`** | Mix `%`, `px`, `vw`, `bw`/`bh` (box-relative units) in a single value — compiled to `calc()` automatically. |
 
-## You... like it / it saved your day / you stole all the code / you want more?
+---
 
-[![contributions welcome](https://img.shields.io/badge/contributions-welcome-brightgreen.svg?style=flat)](#)
+## Comparison
+
+### Feature matrix
+
+| | **react-voodoo** | Framer Motion | GSAP + ScrollTrigger | react-spring | Motion One | anime.js |
+|---|:---:|:---:|:---:|:---:|:---:|:---:|
+| Scroll-linked animation | ✅ | ✅ `useScroll` | ✅ | ⚠️ manual | ✅ | ⚠️ manual |
+| Drag-linked animation | ✅ native | ✅ `drag` | ⚠️ manual | ✅ `@use-gesture` | ⚠️ manual | ❌ |
+| **Additive multi-axis composition** | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ |
+| Physics / momentum inertia | ✅ predictive | ✅ spring | ❌ | ✅ spring | ❌ | ❌ |
+| **Predictive snap target** | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ |
+| **SSR — correct initial styles** | ✅ | ⚠️ flash | ⚠️ flash | ⚠️ flash | ⚠️ flash | ❌ |
+| Bypasses React render loop | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
+| Transform layer composition | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ |
+| SVG geometry attributes | ✅ | ⚠️ limited | ✅ | ❌ | ⚠️ | ✅ |
+| Multitouch (drag multiple axes) | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ |
+| Bundle size (approx. gzip) | ~18 kB | ~50 kB | ~75 kB | ~30 kB | ~18 kB | ~14 kB |
+| React dependency | ≥ 16 | ≥ 18 | none | ≥ 16 | none | none |
+
+### When to pick react-voodoo
+
+- Swipeable carousels and full-page scroll scenes where drag, inertia, and animation must be one system
+- Any UI where **multiple animation "tracks"** compose onto the same elements (parallax, pinned sequences, overlapping effects)
+- **SSR-first** projects where the initial paint must already reflect the animated state
+- Scenarios requiring **predictive callbacks** — e.g. preloading slide N+1 before the swipe animation finishes
 
-BTC     : bc1qh43j8jh6dr8v3f675jwqq3nqymtsj8pyq0kh5a<br/>
-Paypal  : <span class="badge-paypal"><a href="https://www.paypal.com/donate/?hosted_button_id=ECHYGKY3GR7CN" title="Donate to this project using Paypal"><img src="https://img.shields.io/badge/paypal-donate-yellow.svg" alt="PayPal donate button" /></a></span>
+### When to look elsewhere
 
-## Basics
+- Simple enter/exit transitions → **Framer Motion** (`AnimatePresence` is excellent for this)
+- Complex GSAP-style timeline sequencing without scroll/drag → **GSAP**
+- Spring-physics micro-interactions → **react-spring** or **Framer Motion**
+- Lightweight imperative animation on non-React pages → **anime.js** or **Motion One**
 
-"all in one" example :
+---
+
+## Installation
+
+```bash
+npm install react-voodoo
+```
+
+**Peer dependencies:** `react >= 16`, `react-dom >= 16`
+
+---
+
+## All-in-one example
+
+Every major feature in a single component, with comments explaining each part.
 
 ```jsx harmony
 import React                                  from "react";
@@ -68,13 +100,13 @@ const styleSample = {
 	 * Voodoo.Node style property and the tween descriptors use classic CSS-in-JS declaration
 	 * exept we can specify values using the "box" unit which is a [0-1] ratio of the parent ViewBox height / width
 	 */
-	
+
 	height: "50%",
-	
-	// the tweener deal with multiple units 
-	// it will use css calc fn to add them if there's more than 1 unit used 
+
+	// the tweener deal with multiple units
+	// it will use css calc fn to add them if there's more than 1 unit used
 	width: ["50%", "10vw", "-50px", ".2box"],
-	
+
 	// transform can use multiple "layers"
 	transform: [
 		{
@@ -85,7 +117,7 @@ const styleSample = {
 			translateZ: "-.2box"
 		}
 	],
-	
+
 	filter:
 		{
 			blur: "5px"
@@ -97,8 +129,8 @@ const axisSample  = [// Examples of tween descriptors
 		from    : 0,                // tween start position
 		duration: 100,              // tween duration
 		easeFn  : "easeCircleIn",   // function or easing fn id from [d3-ease](https://github.com/d3/d3-ease)
-		
-		apply: {// relative css values to be applied  
+
+		apply: {// relative css values to be applied
 			// Same syntax as the styles
 			transform: [{}, {
 				translateZ: "-.2box"
@@ -108,16 +140,16 @@ const axisSample  = [// Examples of tween descriptors
 	{
 		from    : 40,
 		duration: 20,
-		
-		// triggered when axis has scrolled in the Event period 
+
+		// triggered when axis has scrolled in the Event period
 		// delta : a float value between [-1,1] is the update inside the Event period
 		entering: ( delta ) => false,
-		
+
 		// triggered when axis has scrolled in the Event period
 		// newPos, precPos : float values between [0,1] position inside the Event period
 		// delta : a float value between  [-1,1] is the update inside the Event period
 		moving: ( newPos, precPos, delta ) => false,
-		
+
 		// triggered when axis has scrolled out the Event period
 		// delta : a float value between  [-1,1] is the update inside the Event period
 		leaving: ( delta ) => false
@@ -125,7 +157,7 @@ const axisSample  = [// Examples of tween descriptors
 ];
 
 const Sample = ( {} ) => {
-	
+
 	/**
 	 * Voodoo tweener instanciation
 	 */
@@ -142,86 +174,86 @@ const Sample = ( {} ) => {
 			maxClickTm: 200,
 			// max drag offset in px before a click become a drag
 			maxClickOffset: 100,
-			// lock to only 1 drag direction  
+			// lock to only 1 drag direction
 			dragDirectionLock: false,
 			// allow dragging with mouse
 			enableMouseDrag: false
 		}
 	);
-	// get a named parent tweener 
+	// get a named parent tweener
 	const [nammedParentTweener]                = Voodoo.hook("root")
-	
+
 	/**
 	 * once first render done, axes expose the following values & functions :
 	 */
 	// Theirs actual position in :
 	// tweener.axes.(axisId).scrollPos
-	
+
 	// The "scrollTo" function allowing to manually move the axes positions :
 	// tweener.axes.(axisId).scrollTo(targetPos, duration, easeFn)
 	// tweener.scrollTo(targetPos, duration, axisId, easeFn)
-	
+
 	// They can also be watched using the "watchAxis" function;
 	// When called, the returned function will disable the listener if executed :
 	React.useEffect(
 		e => tweener?.watchAxis("scrollY", ( pos ) => doSomething()),
 		[tweener]
 	)
-	
+
 	return <ViewBox className={"container"}>
 		<Voodoo.Axis
-			
+
 			id={"scrollY"}          // Tween axis Id
 			defaultPosition={100}   // optional initial position ( default : 0 )
-			
+
 			// optional Array of tween descriptors with theirs Voodoo.Node target ids ( see axisSample )
 			items={tweenArrayWithTargets}
-			
+
 			// optional size of the scrollable window for drag synchronisation
 			scrollableWindow={200}
-			
-			// optional length of this scrollable axis (default to last tween desciptor position+duration) 
+
+			// optional length of this scrollable axis (default to last tween desciptor position+duration)
 			size={1000}
-			
+
 			// optional bounds ( inertia will target them if target pos is out )
 			bounds={{ min: 100, max: 900 }}
-			
+
 			// optional inertia cfg ( false to disable it )
 			inertia={
 				{
 					// called when inertia is updated
 					// should return instantaneous move to do if wanted
 					shouldLoop: ( currentPos ) => (currentPos > 500 ? -500 : null),
-					
+
 					// called when inertia know where it will end ( when the user stop dragging )
 					willEnd: ( targetPos, targetDelta, duration ) => {
 					},
-					
+
 					// called when inertia know where it will snap ( when the user stop dragging )
 					willSnap: ( currentSnapIndex, targetWayPointObj ) => {
 					},
-					
+
 					// called when inertia end
 					onStop: ( pos, targetWayPointObj ) => {
 					},
-					
+
 					// called when inertia end on a snap
 					onSnap: ( snapIndex, targetWayPointObj ) => {
 					},
-					
+
 					// list of waypoints object ( only support auto snap 50/50 for now )
 					wayPoints: [{ at: 100 }, { at: 200 }]
 				}
 			}
 		/>
-		
+
 		<Voodoo.Node
 			id={"testItem"} // optional id
-			
+
 			style={styleSample}// optional styles applied before any style coming from axes : css syntax + voodoo tweener units & transform management
-			
+
 			axes={{ scrollY: axisSample }} // optional Array of tween by axis Id with no target node id required ( it will be ignored )
-			
+
 			onClick={// all unknow props are passed to the child node
 				( e ) => {
 					// start playing an anim ( prefer scrolling Axes )
@@ -239,23 +271,23 @@ const Sample = ( {} ) => {
 			<Voodoo.Draggable
 				// make drag y move the scrollAnAxis axis
 				// xAxis={ "scrollAnAxis" }
-				
+
 				// scale / inverse dispatched delta
-				// xHook={(delta)=>modify(delta)} 
-				
-				// React ref to the box, default to the parent ViewBox 
-				// scale is as follow : (delta / ((xBoxRef||ViewBox).offsetWidth)) * ( axis.scrollableWindow || axis.duration )  
-				// xBoxRef={ref} 
-				
+				// xHook={(delta)=>modify(delta)}
+
+				// React ref to the box, default to the parent ViewBox
+				// scale is as follow : (delta / ((xBoxRef||ViewBox).offsetWidth)) * ( axis.scrollableWindow || axis.duration )
+				// xBoxRef={ref}
+
 				yAxis={"scrollY"}// make drag y move the scrollY axis
 				// yHook={(delta)=>modify(delta)}
-				// yBoxRef={ref} 
-				
+				// yBoxRef={ref}
+
 				// mouseDrag={true} // listen for mouse drag ( default to false )
 				// touchDrag={false} // listen for touch drag ( default to true )
-				
+
 				// button={1-3} // limit mouse drag to the specified event.button === ( default to 1; the left btn )
-				
+
 				// * actually Draggable create it's own div node
 			>
 				<div>
@@ -267,11 +299,40 @@ const Sample = ( {} ) => {
 }
 ```
 
-## License ?
+For a more complete annotated example with inertia callbacks, `watchAxis`, and programmatic scrolling, see the [full documentation](doc/readme.md).
+
+---
+
+## Core concepts in 30 seconds
+
+**Axis** — a virtual number line. Move its position (by drag, scroll, or code) and it drives CSS animations on any number of nodes.
+
+**Node** — a React element whose styles are controlled by one or more axes. Style updates go straight to `node.style`, no re-renders.
+
+**Delta composition** — each axis contributes a *change* per frame. Stack a horizontal drag axis and a parallax axis on the same `translateX` and they simply add together. No ownership, no conflicts.
+
+```
+axis position ──► tween engine ──► Δ per property ──► node.style (direct DOM write)
+                                         ▲
+                              other axes add their Δ here
+```
+
+---
+
+## License
 
-Using CC BY-ND, you can use it in commercial apps, but you can't distribute modified versions.<br/>
-Using AGPL, you can distribute modified versions but theses versions must be AGPL too.
+React-voodoo is dual-licensed:
 
+- **[CC BY-ND 4.0](http://creativecommons.org/licenses/by-nd/4.0)** — use freely in commercial projects; distribution of modified versions is not permitted.
+- **[AGPL v3](http://www.gnu.org/licenses/agpl-3.0)** — distribute modified versions under the same open-source license.
+
+---
+
+## Support the project
+
+If react-voodoo saved you a day of work, consider supporting it:
 
 [![contributions welcome](https://img.shields.io/badge/contributions-welcome-brightgreen.svg?style=flat)](#)
-[![*](https://www.google-analytics.com/collect?v=1&tid=UA-82058889-1&cid=555&t=event&ec=project&ea=view&dp=%2Fproject%2Freact-voodoo&dt=readme)](#)
+
+**BTC** — `bc1qh43j8jh6dr8v3f675jwqq3nqymtsj8pyq0kh5a`
+**PayPal** — <a href="https://www.paypal.com/donate/?hosted_button_id=ECHYGKY3GR7CN"><img src="https://img.shields.io/badge/paypal-donate-yellow.svg" alt="PayPal donate" /></a>