react-voodoo 2.6.0 → 2.6.1

package/README.md

@@ -0,0 +1,274 @@
+# react-voodoo
+
+Additive, swipeable, SSR-ready animation engine for React.
+
+[![npm](https://img.shields.io/npm/v/react-voodoo)](https://www.npmjs.com/package/react-voodoo)
+[![license](https://img.shields.io/badge/license-CC--BY--ND--4.0%20OR%20AGPL--3.0-blue)](#license)
+
+## Overview
+
+react-voodoo drives animations by writing CSS **directly to the DOM**, bypassing React's render loop entirely. Scroll positions, drag gestures, and programmatic tweens all feed into the same additive accumulator, so multiple concurrent animations compose without conflict.
+
+The engine is built on [tween-axis](../tween-axis/README.md) and uses its WebAssembly backend for hot-path property accumulation with zero JS-boundary crossings per frame.
+
+---
+
+## Installation
+
+```bash
+npm install react-voodoo
+```
+
+Requires React 16, 17, or 18.
+
+---
+
+## Core concepts
+
+### Delta-based accumulation
+
+Every animation operates on **deltas** — the change from the previous timeline position — rather than absolute target values. On each scroll or animation frame, `goTo(newPos, tweenRefMaps)` emits deltas that are added into a numeric accumulator (`tweenRefMaps`). A separate mux pass then converts those numbers into CSS strings and writes them to `node.style` directly.
+
+This architecture enables:
+- Multiple axes and one-shot animations to animate the same property simultaneously (additive composition).
+- Direct DOM writes that skip React's reconciler entirely.
+- Predictive inertia and physics-based scrolling with no render overhead.
+
+### CSS demux / mux
+
+Tween descriptors specify CSS properties in their `apply` object. Before registering with `TweenAxis`, the `deMuxLine` pass converts each CSS value into a set of flat numeric keys (e.g. `transform_0_translateX_9`). On every frame the inverse `muxToCss` pass reconstructs the CSS strings (including `calc()` for multi-unit values) and writes them to the DOM.
+
+### WASM acceleration
+
+For tween descriptors without event callbacks and with a standard easing function, `CssTweenAxis` (the internal axis class) automatically switches the process to `PROC_WASM` mode. The WebAssembly engine accumulates the property deltas directly inside WASM — no JS function call per property per frame. Results are flushed back into `tweenRefMaps` in a tight loop after `goTo()` returns.
+
+Descriptors that use custom easing functions or event callbacks (`entering`/`moving`/`leaving`) are transparently handled by the JS path (`PROC_RESULT`), so there is no behavioural change — WASM acceleration applies automatically where possible.
+
+---
+
+## Components
+
+### `<Component>` / `asTweener`
+
+The root animation engine. Wrap your animated tree with it to create a `Tweener` context.
+
+```jsx
+import { Component } from "react-voodoo";
+// or with the HOC:
+import { tweener as asTweener } from "react-voodoo";
+
+@asTweener
+class MyScene extends React.Component { ... }
+```
+
+### `<Node>`
+
+An animatable React element. Registers its CSS tween descriptors with the parent `Tweener`.
+
+```jsx
+import { Node } from "react-voodoo";
+
+<Node
+  id="card"
+  style={{ position: "absolute" }}
+  tweenLines={[
+    {
+      from: 0, duration: 500,
+      apply: { opacity: 1, transform: [{ translateY: "100px" }] },
+      easeFn: "easeQuadInOut",
+    }
+  ]}
+/>
+```
+
+### `<Axis>`
+
+A scrollable animation timeline. Attach it to a scroll axis by `id`.
+
+```jsx
+import { Axis } from "react-voodoo";
+
+<Axis
+  id="scrollY"
+  size={1000}
+  defaultPosition={0}
+  inertia={{ snapToBounds: true, wayPoints: [{ at: 0 }, { at: 500 }] }}
+/>
+```
+
+### `<Draggable>`
+
+Maps touch/mouse drag gestures to an axis position.
+
+```jsx
+import { Draggable } from "react-voodoo";
+
+<Draggable axisId="scrollY" />
+```
+
+---
+
+## Hooks
+
+### `useVoodoo(opts?)`
+
+Primary hook. Creates or inherits a `Tweener` instance and returns `[tweener, ViewBox]`.
+
+```jsx
+import { useVoodoo } from "react-voodoo";
+
+function Scene() {
+  const [tweener, ViewBox] = useVoodoo();
+  return <ViewBox>{...}</ViewBox>;
+}
+```
+
+### `useTweener()`
+
+Read-only access to the nearest parent `Tweener`.
+
+```jsx
+import { useTweener } from "react-voodoo";
+
+function Inner() {
+  const tweener = useTweener();
+  // tweener.scrollTo("scrollY", 500, 300);
+}
+```
+
+---
+
+## Tween descriptor
+
+```js
+{
+  from:     0,           // Start position on the axis (omit for sequential chaining)
+  duration: 500,         // Length of this segment
+  target:   "nodeId",    // ID of the Node to animate
+  apply: {
+    opacity:   1,
+    transform: [{ translateX: "100px", translateY: "-50%" }],
+    // Multi-unit values use CSS calc():
+    width:     ["50%", "10vw", "-50px"],
+  },
+  easeFn:   "easeQuadInOut",   // String key into TweenAxis.EasingFunctions (d3-ease)
+  entering: (delta) => {},     // Called when the process activates
+  moving:   (pos, prev, delta) => {},
+  leaving:  (delta) => {},
+}
+```
+
+### Supported CSS properties
+
+All standard animatable CSS properties are supported. Complex properties have dedicated demuxers:
+
+| Property | Notes |
+|----------|-------|
+| `transform` | Array of layer objects; each key is a transform function (`translateX`, `rotate`, etc.) |
+| `boxShadow` | Full multi-shadow support |
+| `filter` | CSS filter functions |
+| `backgroundColor` | RGBA component interpolation |
+| `textShadow` | Multi-shadow support |
+| `opacity`, `zIndex` | Numeric |
+| `width`, `height`, `top`, `left`, `right`, `bottom`, margins, paddings, borders | Length with unit |
+| SVG attributes (`cx`, `cy`, `r`, `x`, `y`, …) | Applied via `setAttribute` |
+
+### Multi-unit values
+
+Arrays of CSS values are resolved with `calc()`:
+
+```js
+width: ["50%", "10vw", "-50px"]
+// → calc(50% + 10vw - 50px)
+```
+
+---
+
+## Axis configuration
+
+```js
+{
+  id:              "scrollY",
+  defaultPosition: 0,
+  size:            1000,          // Timeline length (matches tween descriptor positions)
+  bounds:          { min: 0, max: 1000 },
+  inertia: {
+    snapToBounds: true,
+    wayPoints:    [{ at: 0 }, { at: 500 }, { at: 1000 }],
+    willSnap:     (index, wp) => {},
+    onSnap:       (index, wp) => {},
+  },
+}
+```
+
+---
+
+## Tweener API (imperative)
+
+The `Tweener` instance is accessible via `useVoodoo`, `useTweener`, or `tweenerOptions.ref`.
+
+### `tweener.scrollTo(axisId, position, durationMs?, easing?, noEvents?, tick?, cb?)`
+
+Animate an axis to a position over time.
+
+### `tweener.addScrollableAnim(anim, axisId?)`
+
+Register a tween line (array of descriptors) on a scroll axis at runtime. Returns the `CssTweenAxis` instance.
+
+### `tweener.rmScrollableAnim(sl, axisId?)`
+
+Remove a previously registered tween line.
+
+### `tweener.pushAnim(descriptors, durationMs, cb?, keepResults?)`
+
+Run a one-shot animation that plays to completion and then optionally releases its CSS values.
+
+### `tweener.watchAxis(axisId, listener)`
+
+Subscribe to scroll position changes on an axis. Returns an unsubscribe function.
+
+### `tweener.getScrollPos(axisId)`
+
+Return the current scroll position of an axis.
+
+---
+
+## WASM acceleration in CssTweenAxis
+
+`CssTweenAxis` (the internal class used by every axis) automatically activates PROC_WASM for eligible tween descriptors:
+
+**Eligible** (WASM path):
+- No event callbacks (`entering` / `moving` / `leaving`).
+- `easeFn` is `undefined`/`null` (linear) **or** one of the 10 mapped d3-ease functions.
+
+**Not eligible** (JS path, no change in behaviour):
+- Descriptors with event callbacks.
+- Descriptors using custom easing functions not in the built-in set.
+
+The 10 d3-ease functions that map to WASM built-ins:
+
+| d3-ease name | WASM easing |
+|--------------|-------------|
+| *(none / linear)* | `EASE_LINEAR` |
+| `easeQuadIn` / `easeQuadOut` / `easeQuadInOut` | `EASE_IN/OUT/INOUT_QUAD` |
+| `easeCubicIn` / `easeCubicOut` / `easeCubicInOut` | `EASE_IN/OUT/INOUT_CUBIC` |
+| `easeExpIn` / `easeExpOut` / `easeExpInOut` | `EASE_IN/OUT/INOUT_EXPO` |
+
+No configuration is required — the selection happens automatically during axis construction.
+
+---
+
+## Building
+
+```bash
+cd react-voodoo
+npm run build        # production build via lpack
+npm run devLib       # watch mode
+npm run setupLayers  # initialise lpack layer config
+```
+
+---
+
+## License
+
+Dual-licensed: **CC-BY-ND-4.0** or **AGPL-3.0-only**. See [LICENSE](./LICENSE) for details.