@thednp/tween 0.0.1

package/wiki/React.md

@@ -0,0 +1,255 @@
+## React Hooks for @thednp/tween
+
+Simple, performant hooks that integrate `Tween` and `Timeline` seamlessly with React state.  
+
+They handle React's frequent re-renders and `<StrictMode>` double-mounting safely, so you can focus on animation logic instead of fighting the framework.
+
+
+Don't forget to install.
+```
+npm install @thednp/tween
+# or pnpm/yarn/bun/deno
+```
+
+### useTween
+Creates a new [`state`, `tween`, `configureTween`] tuple that updates from current values and updates React's state on every frame.
+
+To eliminate the possibility of JANK or values overprocessing, it is recommended that you wrap the configuration of your persistent `Tween` objects inside wrappers, like shown in the examples below:
+
+
+#### Example 1
+
+Use all available items of the hook - **recommended**.
+```tsx
+import { useTween } from "@thednp/tween/react";
+import { Easing } from "@thednp/tween";
+
+function AnimatedBox() {
+  const [styles, tween, configureTween] = useTween({ x: 0, opacity: 1 });
+
+  setupTween((tw) => 
+    tw
+      .to({ x: 300, opacity: 0.5 })
+      .duration(1.5)
+      .easing(Easing.Elastic.Out)
+  );
+
+  const handleClick = () => tween.start();
+
+  return (
+    <div
+      onClick={handleClick}
+      style={{
+        translate: `${styles.x}px`,
+        opacity: styles.opacity,
+        width: 100,
+        height: 100,
+        background: "blue",
+        cursor: "pointer",
+      }}
+    >
+      Click to animate
+    </div>
+  );
+}
+```
+
+#### Example 2
+
+Use React's `useEffect` to configure your Tween - classic React way.
+```tsx
+import { useEffect } from "react";
+import { useTween, Easing } from "@thednp/tween/react";
+
+function AnimatedBox() {
+  const [styles, tween] = useTween({ x: 0, opacity: 1 });
+
+  useEffect(() => {
+    tween
+      .to({ x: 300, opacity: 0.5 })
+      .duration(1.5)
+      .easing(Easing.Elastic.Out)
+  }, []);
+
+  const handleClick = () => tween.start();
+
+  return (
+    <div
+      onClick={handleClick}
+      style={{
+        translate: `${styles.x}px`,
+        opacity: styles.opacity,
+        width: 100,
+        height: 100,
+        background: "blue",
+        cursor: "pointer",
+      }}
+    >
+      Click to animate
+    </div>
+  );
+}
+```
+
+
+#### Example 3
+
+Override all values on the fly on every `start()` call.
+```tsx
+import { useTween, Easing } from "@thednp/tween/react";
+
+function AnimatedBox() {
+  const [styles, tween] = useTween({ x: 0, opacity: 1 });
+
+  const handleClick = () => {
+    tween
+      .from({ x: 0, opacity: 1 })
+      .to({ x: 300, opacity: 0.5 })
+      .duration(1.5)
+      .easing(Easing.Elastic.Out)
+      .start();
+  };
+
+  return (
+    <div
+      onClick={handleClick}
+      style={{
+        translate: `${styles.x}px`,
+        opacity: styles.opacity,
+        width: 100,
+        height: 100,
+        background: "blue",
+        cursor: "pointer",
+      }}
+    >
+      Click to animate
+    </div>
+  );
+}
+```
+
+#### API
+
+`useTween(initialValues: T) → [state: T, tween: Tween<T>, configureTween]`
+
+* `state` is a React state object object updated on every tween frame
+* `tween` is the persistent `Tween` instance (chain .to(), .duration(), .start(), etc.)
+* `configureTween` is a small utility to register a configure callback for your `Tween` object.
+
+Automatically stops on component unmount (via tween.stop())
+
+**Notes**
+- Uses a separate mutable object internally → safe for React (no direct state mutation)
+- Shallow copy on update → efficient for flat/nested props (deep clones rare in animations)
+- Supports nested objects via `Tween`'s built-in recursion
+
+
+### useTimeline
+Creates a new [`state`, `timeline`, `configureTimeline`] tuple that updates from current values and updates React's state on every frame.
+
+To eliminate the possibility of JANK or values overprocessing, it's **important** that you wrap the configuration of your persistent `Timeline` objects inside wrappers, like shown in the examples below:
+
+#### Example 1
+
+Create a new `Timeline` and use all available items of the hook - **recommended**.
+```tsx
+import { useTimeline, Easing } from "@thednp/tween/react";
+
+function AnimatedSequence() {
+  const [pos, timeline, configureTimeline] = useTimeline({ x: 0, y: 0 });
+
+  configureTimeline((tl) => 
+    tl
+      .to({ x: 200, duration: 1, easing: Easing.Quad.Out })
+      .to({ y: 150, duration: 0.8, easing: Easing.Bounce.Out }, "-=0.5")
+  );
+
+  const playAnim = () => {
+    timeline.play();
+  };
+
+  return (
+    <div onClick={playAnim} style={{ translate: `${pos.x}px ${pos.y}px` }}>
+      Click to sequence
+    </div>
+  );
+}
+```
+
+#### Example 2
+
+Use React's `useEffect` to configure your Timeline - classic React way.
+```tsx
+import { useEffect } from "react";
+import { useTimeline, Easing } from "@thednp/tween/react";
+
+function AnimatedSequence() {
+  const [pos, timeline] = useTimeline({ x: 0, y: 0 });
+
+  useEffect(() => {
+    timeline
+      .to({ x: 200, duration: 1, easing: Easing.Quad.Out })
+      .to({ y: 150, duration: 0.8, easing: Easing.Bounce.Out }, "-=0.5")
+  }, []);
+
+  const playAnim = () => {
+    timeline.play();
+  };
+
+  return (
+    <div onClick={playAnim} style={{ translate: `${pos.x}px ${pos.y}px` }}>
+      Click to sequence
+    </div>
+  );
+}
+```
+
+#### Example 3
+
+Override all entries on the fly on every `play()` call.
+```tsx
+import { useTimeline, Easing } from "@thednp/tween/react";
+
+function AnimatedSequence() {
+  const [pos, timeline] = useTimeline({ x: 0, y: 0 });
+
+  const playAnim = () => {
+    timeline
+      .onComplete(() => timeline.clear()) // it's important to clear entries when overriding them over and over
+      .to({ x: 200, duration: 1, easing: Easing.Quad.Out })
+      .to({ y: 150, duration: 0.8, easing: Easing.Bounce.Out }, "-=0.5")
+      .play();
+  };
+
+  return (
+    <div onClick={playAnim} style={{ translate: `${pos.x}px ${pos.y}px` }}>
+      Click to sequence
+    </div>
+  );
+}
+```
+
+Same API notes as `useTween` — persistent instance, auto-cleanup, reactive state.
+
+
+### Which pattern should I use?
+
+Any pattern works, it all comes down to your preference, here's why:
+
+- **The cleanest**: Use the `configure` callback (third item in the array) — declarative, zero boilerplate, StrictMode-safe.
+- **Classic React style**: Use `useEffect` with empty deps — perfect when config depends on props/state - also StrictMode-safe.
+- **Dynamic/override style**: Call `.to()` / `.from()` directly on the tween/timeline instance inside event handlers — great for user-triggered animations, StrictMode-safe.
+
+
+### Troubleshooting
+
+- **Never chain `.to()`, `.duration()`, etc. directly in the component body** without safeguards. This is the most common cause of duplicate/infinite animations in development. Always use one of the three supported patterns above. This is an important note we have to go over because React re-renders everything on every state change, which is why configuring your `Tween` or `Timeline` objects has to be done within either event listeners, the provided `configure` (third item of the returned elements of the hook) or within `useEffect()` callback. Can't stress this enough how important this is, especially with `Timeline` which has the habit of re-adding its entries on every re-render, producing an infinite loop and breaking your React application.
+
+**CSS gotchas** — Properties like `top`/`left` require `position`: `absolute`/`relative` on the element and its parent. `transform`/`translate` usually works best for animations.
+
+**Updates never happen** - this is due to one of the main factors:
+1) The missmatch of start and end values types, if you're using vanilla JavaScript instead of TypeScript with active linting, you may experience this and not know what happens.
+2) Values are missing due to the incorrect use of lifecycle hooks.
+3) You never called `start()` / `play()`?
+
+On a general note, refer to the [README](../README.md) for other tricks and quirks.

package/wiki/Solid.md

@@ -0,0 +1,149 @@
+## SolidJS Primitives for @thednp/tween
+
+Leverage SolidJS's fine-grained reactivity with `Tween` and `Timeline` through ultra-lightweight primitives.  
+
+Unlike the [React hooks](./React.md), these require no additional boilerplate — mutations are tracked automatically, and configuration is free-form.
+
+**Note**: These primitives use a lightweight internal `miniStore` optimized for simple flat non-nested numeric objects. For deeply structured or non-numeric state, override `onUpdate` manually to preserve reactivity.
+
+
+Don't forget to install.
+```
+npm install @thednp/tween
+# or pnpm/yarn/bun/deno
+```
+
+### createTween
+
+Creates a [store, tween] tuple that animates from current values and updates SolidJS reactive store on every frame.
+
+```tsx
+import { createTween } from "@thednp/tween/solid";
+import { Easing } from "@thednp/tween";
+
+function AnimatedBox() {
+  const [styles, tween] = createTween({ x: 0, opacity: 1 });
+
+  /** Configure your Tween anywhere, no re-renders ever happen */
+  // tween
+  //   .to({ x: 300, opacity: 0.5 })
+  //   .duration(1.5)
+  //   .easing(Easing.Elastic.Out)
+
+  // Or setup your Tween on the fly
+  const handleClick = () => {
+    tween
+      .from({ x: 0, opacity: 1 })
+      .to({ x: 300, opacity: 0.5 })
+      .duration(1.5)
+      .easing(Easing.Elastic.Out)
+      .start();
+  };
+
+  return (
+    <div
+      onClick={handleClick}
+      style={{
+        translate: `${styles.x}px`,
+        opacity: styles.opacity,
+        width: 100,
+        height: 100,
+        background: "blue",
+        cursor: "pointer",
+      }}
+    >
+      Click to animate
+    </div>
+  );
+}
+```
+
+#### API
+
+`createTween(initialValues: T) → [state: T, tween: Tween<T>]`
+
+* `state` is a SolidJS store object that updated on every frame
+* `tween` is a `Tween` instance (chain `.to()`, `.duration()`, `.start()`, etc.)
+
+Automatically stops on component unmount (via `tween.stop()`).
+
+**Notes**
+- Direct mutations are tracked automatically — no manual `onUpdate` or copying needed
+- Works great with nested objects (Tween recursion)
+- For non-numeric or complex state, override `onUpdate` to help preserve reactivity
+
+
+### createTimeline
+
+Same pattern for `Timeline` sequencing.
+
+```tsx
+import { createTimeline } from "@thednp/tween/solid";
+import { Easing } from "@thednp/tween";
+
+function AnimatedSequence() {
+  const [pos, timeline] = createTimeline({ x: 0, y: 0 });
+
+  /** Configure your Timeline anywhere, no re-renders ever happen */
+  timeline
+    .to({ x: 200, duration: 1, easing: Easing.Quad.Out })
+    .to({ y: 150, duration: 0.8, easing: Easing.Bounce.Out }, "-=0.5");
+
+  const playAnim = () => {
+    // or configure your Timeline entries on the fly
+    // timeline
+    //   .onComplete(() => timeline.clear())
+    //   .to({ x: 200, duration: 1, easing: Easing.Quad.Out })
+    //   .to({ y: 150, duration: 0.8, easing: Easing.Bounce.Out }, "-=0.5");
+
+    timeline.play();
+  };
+
+  return (
+    <div onClick={playAnim} style={{ translate: `${pos.x}px ${pos.y}px` }}>
+      Click to sequence
+    </div>
+  );
+}
+```
+
+Same API notes as `createTween` — persistent instance, auto-cleanup, reactive state.
+
+
+### Troubleshooting
+
+**miniStore limitation** — The internal store is optimized for simple numeric objects (flat and non-nested). For deeply structured or non-numeric state (arrays of objects, strings, etc.), override `onUpdate` manually:
+```ts
+timeline.onUpdate((obj) => {
+  // Custom deep merge or setState logic
+  setSomeSignalOrStore({ ...obj });
+});
+```
+Otherwise reactivity may break for untouched properties.
+
+The type of values `Tween` and `Timeline` can work with:
+```ts
+type MorphPathSegment =
+  | ["M" | "L", number, number]
+  | ["C", number, number, number, number, number, number]
+  | ["Z"];
+
+type MorphPathArray = MorphPathSegment[];
+
+type BaseTweenProps = Record<string, number | number[]>;
+type TweenProps = Record<
+  string,
+  number | number[] | BaseTweenProps | MorphPathArray
+>;
+```
+
+**CSS gotchas** — Properties like `top`/`left` require `position`: `absolute`/`relative` on the element and its parent. `transform`/`translate` usually works best for animations.
+
+**No re-renders** — Unlike React, SolidJS doesn't re-render the whole component on state change — only the accessed reactive properties update. This is why configuration can safely live anywhere.
+
+**Updates never happen** - this is due to one of the main factors:
+1) The missmatch of start and end values types, if you're using vanilla JavaScript instead of TypeScript with active linting, you may experience this and not know what happens.
+2) Values are missing due to the incorrect use of lifecycle hooks.
+3) You never called `start()` / `play()`?
+
+On a general note, refer to the [README](../README.md) for other tricks and quirks.

package/wiki/Timeline.md

@@ -0,0 +1,207 @@
+## Timeline
+
+A tiny, ultra-fast `Timeline` tween scheduler. This is simple, just pure flexible chaining similar to `Tween` and stripped to essentials: sequential/overlapping updates, labels, repeat, seek, play/pause/stop/resume. It's a great addition that goes beyond what Tween does and for more complex animations and with far more flexibility and control.
+
+Perfect for reactive stores (SolidJS, Svelte, React, etc), SVG/Canvas animations, or anything needing precise control without the overhead.
+
+
+### Features
+- Chainable methods with for best DX;
+* Relative positions (`"+=0"`, `"-=1.5"` offsets, labels);
+- Proper chaining (later entries start from current state);
+- Labels for jumping/seeking;
+- Repeats (including Infinity);
+- Seek anytime (playing or paused, with instant state update);
+- Multiple callbacks: `onStart`, `onUpdate`, `onComplete`, `onStop`, `onPause`, `onResume` (all receive `state`, `progress`);
+- Custom interpolators via `Timeline.use()`;
+- Nested/objects, arrays, custom types supported out-of-box;
+- ~200 lines, blazing fast (while loops for entries);
+* `requestAnimationFrame` loop handled automatically when `.play()` called.
+
+
+### Usage
+
+```ts
+import { Timeline, Easing } from '@thednp/tween';
+
+// Initial state
+const obj = { x: 0, y: 0, rotate: 0 };
+
+// Define Timeline object
+const tl = new Timeline(obj)
+  .onUpdate((state, progress) => {
+    setState(state) // React/Svelte/store/etc.
+    // OR manipulate DOM elements directly
+    // make use of [0-1] progress value to update other state
+  })   
+  .label('loopStart', 0)                // Back to start (manual "reverse")
+  .repeat(Infinity);                    // OR an INT number
+
+// Add entries
+tl
+  .to({ x: 100, easing: Easing.Elastic.Out }, '+=1')    // 1s to x:100
+  .to({ y: 200, rotate: 360, duration: 1.5 }, '-=0.5')  // Overlap last 0.5s, rotate full turn in 1.5 sec
+  .to({ x: 0, y: 0 }, '+=1');                           // Back to original position after 1 sec delay
+
+// Start update loop
+tl.play();
+
+// Stop update loop
+tl.stop();
+
+// Pause update loop
+tl.pause();
+
+// Resume update loop
+tl.resume();                // OR tl.start();
+
+// Seek
+tl.seek('loopStart');       // Jump to label
+```
+
+### API
+
+#### `new Timeline(initialValues)`
+Creates a new **Timeline** instance targeting the provided object, which means this object is updated during the update runtime.
+
+#### `.to(props & config, position?)`
+
+Adds a new entry in the Timeline instance.
+
+**Parameters**
+* `props & config` allows you to set new prop values we want to change as well as `duration` (in seconds) and `easing` function;
+* `position` allows you to specify a fixed start time (in seconds), a label or a positive (delay) `"+=1"` or negative `"-=1"` offset;
+
+#### `.play() / .pause() / .resume() / .stop()`
+Public methods that allow you to start/stop/pause/resume the update. When paused `start()` will also resume.
+
+#### `.seek(time | label | relative)`
+A public methods that allows you to jump to a certain point in the update:
+* at a specified *label*,
+* at fixed number of seconds (a number smalled than of the total duration).
+
+#### `.repeat(count : number)`
+Allows you to set how many times the update should repeat. You can also use `Infinity`. 
+
+#### `.label(name, position?)`
+Allows you to register a new label for a given string name and a label or INT number value (less than the total duration).
+
+#### Callbacks
+The `.onStart(cb)` / `onUpdate(cb)` / `onComplete(cb)` / `onStop(cb)` / `onPause(cb)` / `onResume(cb)` are a series of public methods that allow you to configure a callback for each invokation: start, stop, update, complete or pause.
+
+#### Custom Interpolators
+The `.use(propName: string, interpolationFunction: InterpolatorFunction)` allows you to add custom interpolator functions for your instance.
+
+```ts
+const timeline = new Timeline({ x: 0 });
+
+// A regular callback
+timeline.onStart(obj, progress) => {
+  console.log("At " + Math.round(progress * 100) + "%, state is", obj);
+})
+
+// An update callback has an additional parameter `value`
+timeline.onUpdate((obj, progress) => {
+  // update the App state or manipulate the DOM directly
+  // progress is a [0-1] value, where 0 is the start and 1 is the end
+  console.log("At " + Math.round(progress * 100) + "%, state is", obj);
+})
+```
+
+#### `state`, `progress`, `duration`, `isPlaying`, `isPaused`
+A series of getters and properties that reflect the state of the update:
+* the `state` object with all values (not a getter)
+* the [0-1] value `progress` which indicates how much of the `Timeline` update is complete
+* the total `duration` of all the `Timeline` entries 
+* `isPlaying` and `isPaused` are *boolean* getters and their returned values reflect the current `Timeline` state.
+
+
+### Custom Interpolators
+
+For interpolation of various other object types, `Timeline` allows you to add custom interpolation functions.
+
+The package already comes with 2 built in interpolation functions:
+
+#### interpolateArray
+This allows you to interpolate arrays for translate/rotate/scape, RGB/RGBA, HSL/HSLA, etc.
+
+```ts
+import { Timeline, interpolateArray } from "@thednp/tween";
+
+const target = document.getElementById("my-target");
+const tl = new Timeline({ rgb: [255,0,0] }) // start from red
+  // the `rgb` property will now use the custom interpolation
+  .use('rgb', interpolateArray);
+  // set an update function
+  .onUpdate((state) => {
+    // update App state or update DOM elements directly
+    Object.assign(
+      target.style,
+      { "background-color": "rgb(" + state.rgb.join(",") + ")" }),
+  });
+
+// set new value
+tl.to({ rgb: [0,255,0], duration: 1.5 }); // fade to green
+
+// start animation
+tl.play();
+```
+
+#### interpolatePath
+
+This adds SVG morph capability and assumes compatible paths (same segment count/types and coordinate counts — use [svg-path-commander](https://github.com/thednp/svg-path-commander) to process if needed).
+
+```ts
+import { Timeline, interpolatePath } from "@thednp/tween";
+
+// Use a fast `PathArray` to string
+// For faster performance use `pathToString` from svg-path-commander
+function pathToString(path: ["M" | "C" | "L", ...number[]][]) {
+  return p.map(([c, ...args]) => c + args.join(",")).join(" ");
+}
+
+// target a <path> element
+const path = document.getElementById("my-path");
+
+// "M0,0 L600,0 L600,300 L600,600 L0,600 Z"
+const square = [
+  ["M", 0, 0],
+  ["L", 600, 0],
+  ["L", 600, 300], // mid
+  ["L", 600, 600],
+  ["L", 0, 600],
+  ["Z"],
+];
+
+// "M0,0 L300,150 L600,300 L300,450 L0,600 Z"
+const triangle = [
+  ["M", 150, 0],
+  ["L", 300, 150], // mid
+  ["L", 450, 300],
+  ["L", 300, 450], // mid
+  ["L", 150, 600],
+  ["Z"],
+];
+
+const tl = new Timeline({ path: square })
+  .use('path', interpolatePath);
+  // you can use any property name you want,
+  // `d` might be a good choice as well
+  // set an update function
+  .onUpdate((state) => {
+    // update App state
+    // OR update DOM elements directly
+    target.setAttribute("d", pathToString(state.path))
+  })
+
+// set new value
+tl.to({ path: triangle, duration: 1.5 });
+
+// start animation
+tl.play();
+```
+
+**Notes**
+* The example provides ready-made `PathArray` objects, they usually require prior preparation manually or using some script to [equalize segments](https://minus-ze.ro/posts/morphing-arbitrary-paths-in-svg/);
+* Continuous `path` updates between multiple shapes requires that **all** path values are compatible, which means they all have same amount of segments and all segments are of the same type (ideal are `[[M, x, y], ...[L, x, y]], ` OR `[[M, x, y], ...[C, cx1, cy1, cx2, cy2, x, y]], `);
+* Our [svg-path-commander](https://github.com/thednp/svg-path-commander/) provides all the tools necessary to process path strings, optimize and even equalize segments (work in progress).