@thednp/tween 0.0.1 → 0.0.2

package/README.md

@@ -1,30 +1,75 @@
 ## @thednp/tween
+
 [![Coverage Status](https://coveralls.io/repos/github/thednp/tween/badge.svg)](https://coveralls.io/github/thednp/tween)
-[![ci](https://github.com/thednp/tween/actions/workflows/ci.yml/badge.svg)](https://github.com/thednp/tween/actions/workflows/ci.yml)
-[![typescript version](https://img.shields.io/badge/typescript-5.9.3-brightgreen)](https://www.typescriptlang.org/)
-[![vitest version](https://img.shields.io/badge/vitest-4.0.17-brightgreen)](https://vitest.dev/)
-[![vite version](https://img.shields.io/badge/vite-7.3.1-brightgreen)](https://github.com/vitejs)
+[![NPM Version](https://img.shields.io/npm/v/@thednp/tween.svg)](https://www.npmjs.com/package/@thednp/tween)
+[![CI](https://github.com/thednp/tween/actions/workflows/ci.yml/badge.svg)](https://github.com/thednp/tween/actions/workflows/ci.yml)
+
+
+A Typescript sourced tweening engine forked from the excellent [@tweenjs/tweenjs](https://github.com/tweenjs/tween.js). This package has some strongly opinionated implementations for the best performance and DX.
+
+Major popular frameworks supported:
+
+[<img width="32" height="32" src="wiki/assets/react.svg" alt="React" />](wiki/React.md)
+[<img width="32" height="32" src="wiki/assets/solid.svg" alt="SolidJS" />](wiki/Solid.md)
+[<img width="32" height="32" src="wiki/assets/preact.svg" alt="Preact" />](wiki/Preact.md)
+[<img width="32" height="32" src="wiki/assets/svelte.svg" alt="Svelte" />](wiki/Svelte.md)
+[<img width="32" height="32" src="wiki/assets/vue.svg" alt="Vue" />](wiki/Vue.md)
+
+
+## Why @thednp/tween?
+
+It seems **we got it all wrong regarding tweening** since the beginning. We've been working with unpredictable patterns and high risk for errors. We've been doing too much value checking during hot update loop or sometimes got too close to the DOM, to the point that makes it hard to integrate in modern tech. What if... we can change all that?
 
-A Typescript sourced `Tween` engine forked from the excellent [@tweenjs/tweenjs](https://github.com/tweenjs/tween.js).
+**Why you would like it?**
 
-* The package includes `Tween` class for creating most simple tween objects, with most essential controls over the update loop and simple methods for sequencing.
-* Another major addition to this package is a simple to use `Timeline` class which enables an advanced control over the update loop, most importantly a **per-property** control for duration and easing.
-* There are also a series of custom hooks/promitives for popular frameworks like React/SolidJS (more to come), with proper documentation and detailed user guides.
+* It's really easy to use thanks to the built in support for popular UI frameworks via SSR compatible hooks/primitives/composables (hooks only provide initial values required for server rendering runtime and initialization is skipped entirely, hooks only work with hydration of server rendered HTML or single page apps - SPA).
+* It's the solution for a predictable outcome: validate values before and never at the update runtime, explicit specification instead of a guessing game, no object lookup or any kind of overhead.
+* While you can do quite complex animations with CSS3 alone, it's really poor DX to go back and forth and write complex animations to which you have little to no control.
+* The package comes with a feature rich validation system, all to make sure your animations run smooth and never break your app. Values aren't valid? Animation won't start. Missed a configuration step? You will be provided with feedback.
+* SVG math can be troublesome because of its own coordinates system, SVG transforms are also a thing, but with a little learning and our tweening engine you can do anything you really want.
 
 
-### Features
-- Built in custom hooks/primitives for popular frameworks like React/SolidJS 
-- Simple and powerful `Timeline` class for advanced sequencing/overlaps
-- Lightweight fork of tween.js (~half the size)
-- Chainable API for proper DX
-- Easy to extend via custom interpolators
-- Duration/delay in seconds
-- Automatic rAF loop (starts and stops automatically)
-- TypeScript-native, zero dependencies
-- Tested with Vitest 100% code coverage
+## Features
+* The package includes `Tween` class for creating most simple tween objects, with most essential controls, callbacks and methods for sequencing.
+* For more complex scheduling and easier sequencing this package has a simple to use `Timeline` class with similar controls, callbacks, but most importantly it allows setting **per-property** duration, start time / delay and easing.
+* There are also a series of custom hooks/primitives for popular frameworks like React/SolidJS/Svelte/Preact/Vue (more to come), with proper documentation and detailed user guides.
+* Yoyo and generally reverse playback works naturally with inverted easing function (without a `reverseEasing` option) and without re-assigning a `valuesStart` object on repeat iteration end like the original library.
+* By default, only `number` values are supported, which is fine for most use cases, but both `Tween` and `Timeline` provide a way to extend beyond the original prototype. You can use the built-in [extensions](wiki/Extend.md) or creare your own to provide per property validation and interpolation with your design specification. The only limit is that objects are limited to a one level nesting and must be plain objects.
+* All values are **always** validated on initialization from a given `initialValues` object, which, once validated, it becomes the source of truth to the type of values coming later from `to()` / `from()`.
+* Automatic `requestAnimationFrame` loop (you won't need to handle it yourself), it starts when you call `tween.start()` or `timeline.play()` and stops when all tweens are complete.
+* The package has some micro-optimizations for maximum performance:
+  - All loops are executed with `while`;
+  - No value validation of any kind during the update loop;
+  - Supported frameworks (via hooks/primitives/composables) use a `miniStore` designed to store tween values and trigger updates/effects in your UI efficiently, with zero GC pressure, no object lookup or re-assignment, just pure linear interpolation;
+  - The hot update runtime consists of tuples, to optimize GC presure and eliminate object lookup. 
 
 
-### Install
+### Take a minute to check a quick demo
+
+[<img width="32" height="32" src="wiki/assets/react.svg" alt="React" />](https://stackblitz.com/fork/github/thednp/tween/tree/master/playground/react)
+[<img width="32" height="32" src="wiki/assets/solid.svg" alt="SolidJS" />](https://stackblitz.com/fork/github/thednp/tween/tree/master/playground/solid)
+[<img width="32" height="32" src="wiki/assets/preact.svg" alt="Preact" />](https://stackblitz.com/fork/github/thednp/tween/tree/master/playground/preact)
+[<img width="32" height="32" src="wiki/assets/svelte.svg" alt="Svelte" />](https://stackblitz.com/fork/github/thednp/tween/tree/master/playground/svelte)
+[<img width="32" height="32" src="wiki/assets/vue.svg" alt="Vue" />](https://stackblitz.com/fork/github/thednp/tween/tree/master/playground/vue)
+
+Your favorite framework isn't listed? [Let us know](https://github.com/thednp/tween/issues/new)!
+
+
+### Documentation
+* [Tween Guide](wiki/Tween.md) - the official `Tween` documentation
+* [Timeline Guide](wiki/Timeline.md) - the official `Timeline` documentation
+* [Easing Guide](wiki/Easing.md) - the easing functions documentation
+* [Extend Guide](wiki/Extend.md) - the extensions documentation
+* [React Guide](wiki/React.md) - the React documentation (custom hooks)
+* [SolidJS Guide](wiki/Solid.md) - the SolidJS documentation (custom primitives, tips)
+* [Vue Guide](wiki/Vue.md) - the Vue documentation (composables, tips)
+* [Preact Guide](wiki/Preact.md) - the Preact documentation (custom hooks, tips)
+* [Svelte Guide](wiki/Svelte.md) - the Svelte documentation (runes)
+* [The original Tween.js User Guide](https://github.com/tweenjs/tween.js/blob/main/docs/user_guide.md) can also provide valuable tips.
+* [Troubleshooting](wiki/Troubleshooting) - a quick check on issues and how to solve them.
+
+
+### Installation
 ```
 npm install @thednp/tween
 ```
@@ -44,6 +89,8 @@ bun add @thednp/tween
 
 ### Usage
 
+To use `Tween` and `Timeline` with UI frameworks please check the dedicated sections: [React](wiki/React.md), [SolidJS](wiki/Solid.md), [Svelte](wiki/Svelte.md), [Preact](wiki/Preact.md) and [Vue](wiki/Vue.md).
+
 #### Using Tween
 ```ts
 import { Tween, Easing } from '@thednp/tween';
@@ -54,13 +101,11 @@ const target = document.getElementById('my-target');
 // define a tween
 const tween = new Tween({ x: 0 })
   .duration(1.5) // duration/delay accept seconds (e.g., 1.5 = 1.5s)
-  .onUpdate((obj, elapsed, eased) => {
-    // update App state 
-    // OR manipulate the DOM directly
-    Object.assign(target.style, { translate: obj.x + "px"});
+  .onUpdate((obj, elapsed) => {
+    // manipulate the DOM directly
+    Object.assign(target.style, { translate: obj.x + "px" });
     // monitor progress of the tween
     console.log(`Tween progress: ${Math.floor(elapsed * 100)}%`)
-    // do other stuff with the `eased` value
   });
 
 // override any value on the fly
@@ -72,6 +117,7 @@ const moveRight = () => tween
   .start();                     // start the tween
 
 const moveLeft = () => tween
+  .from({ x: 150 })             // set a different from
   .to({ x: -150 })              // set a different to
   .easing(Easing.Elastic.Out)   // override easing
   .duration(1.5)                // override duration in seconds
@@ -86,6 +132,8 @@ button2.onclick = moveLeft;
 
 // The engine does requestAnimationFrame/cancelAnimationFrame for you
 ```
+For an extended guide, check the [Tween Wiki](wiki/Tween.md).
+
 
 #### Using Timeline
 ```ts
@@ -99,145 +147,100 @@ const myTimeline = new Timeline({ x: 0, y: 0 })
   .to({ x: 150, duration: 2.5, easing: Easing.Elastic.Out })
   .to({ y: 150, duration: 1.5, easing: Easing.Elastic.Out }, "-=1")
   .onUpdate((obj, elapsed) => {
-    // update App state 
-    // OR manipulate the DOM directly
+    // manipulate the DOM directly
     Object.assign(target.style, {
       translate: obj.x + "px " + obj.y + "px",
     });
-    // monitor progress of the tween
+    // monitor progress of the timeline
     console.log(`Timeline progress: ${Math.floor(elapsed * 100)}%`)
   });
 
 // trigger any time
-const button = document.getElementById('my-button-1');
+const button = document.getElementById('my-button');
 
 button.onclick = myTimeline.play();
 
 // The engine does requestAnimationFrame/cancelAnimationFrame for you
 ```
-To use `Tween` or `Timeline` with frameworks please check [React](wiki/React.md), [SolidJS](wiki/Solid.md) (more to come).
-
+For an extended guide, check the [Timeline Wiki](wiki/Timeline.md).
 
-### What is different from original?
 
-#### Back to Base
-This `Tween` version is very small, maybe half the size of the current original version. It was developed to create easy to use hooks for UI frameworks like Solid/React and enable customizable animations.
-In fact this is closer to the earlier versions of the original TWEEN.Tween.js.
+### What is Different from Original?
 
+#### Looking Forward
+On the surface, most changes seem superficial, but our `Tween` version is very different from the current source version. It was developed to create easy to use hooks for major popular UI frameworks and deliver a trully predictable outcome.
 
 #### New Features
-This package comes with `Timeline`, which works like a regular `Tween` under the hood, but it provides additional control methods like `pause()`, `resume()` `seek()`.
+This package comes with `Timeline`, which works like a regular `Tween` under the hood, but it provides additional control methods like `seek()` or `label()` and allows per property easing, duration and start time / delay options.
 
-Both `Tween` and `Timeline` have a static method to add custom interpolators, which is a unique way to extend beyond the original design and very different from the original library.
-
-#### Other Notable Changes
-* Some features like `yoyo`, `repeat`, `repeatDelay`, `chain` and 
-* callback options like `onRepeat` or `onEveryStart`, `onFirstStart` are **not** implemented;
-* `duration()` and `delay()` methods accept values in seconds and convert them to milliseconds; 
-* The `pause()` and `resume()` methods have **not** been implemented in `Tween`, but they are implemented in `Timeline`;
-* The update loop which consists of `requestAnimationFrame` / `cancelAnimationFrame` calls is automatic and is integrated in the `Tween` methods;
-* The `onUpdate` callback also uses the value calculated by the easing function as the third parameter of your callback;
-* The original Tween.js array interpolation is **not** supported, however we have a static method to add custom interpolators.
+Both `Tween` and `Timeline` have a method to add a custom **per property extension** that consists of a function to validate and another to interpolate, which is a unique way to extend beyond the original design and very different from the original library.
 
+**Great DX**: Along with type safety, `Tween` and `Timeline` will validate your values on initialization or (re)configuration to enforce it. Calling `Tween.to()`, `Tween.from()` or `Timeline.to()` will use the **validation system** to provide feedback on what went wrong and how to fix, in most cases issues with invalid/incompatible values are mapped internally and only cleared once validated/re-validated. This is to make sure to **never crash** your app.
 
-### Guides and Resources
-* The original Tween.js [User Guide](https://github.com/tweenjs/tween.js/blob/main/docs/user_guide.md)
-* [Tween.md](wiki/Tween.md) - our official `Tween` guide
-* [Timeline.md](wiki/Timeline.md) - our official `Timeline` guide
-* [Easing.md](wiki/Easing.md) - an extensive guide on easing functions.
-* [React.md](wiki/React.md) - use `Tween` / `Timeline` with React with custom hooks.
-* [Solid.md](wiki/Solid.md) - use `Tween` / `Timeline` with SolidJS with primitives.
+#### Other Notable Changes
+* The `chain` feature is **not** implemented;
+* Callback options like `onEveryStart`, `onFirstStart` are **not** implemented;
+* The `duration()`, `delay()`, `repeatDelay()` or `seek()` methods accept values in seconds and convert them to milliseconds; 
+* The update loop which consists of `requestAnimationFrame` is automatic and a queue system is integrated in the `Tween` and `Timeline` methods;
+* The original [Tween.js](https://tweenjs.github.io/tween.js/examples/06_array_interpolation.html) array interpolation is **not** supported;
+* Deeply nested objects are **not supported**, actively discouraged, objects in general are known to have very bad performance metrics;
+* Dynamic end values like the original [Tween.js](https://tweenjs.github.io/tween.js/examples/07_dynamic_to.html) cannot be supported due to the intrinsic changes in the update runtime.
 
 
 ### Technical Notes & Design Choices
 
-**@thednp/tween** is intentionally designed as a **lightweight, state-first** tweening engine. Here's why certain choices were made and how the system works under the hood.
-
-#### Why declarative state-based animation?
+**@thednp/tween** is intentionally designed as a **state-first** tweening engine. Here's why certain choices were made and how the system works under the hood.
 
-Most classic animation libraries (GSAP, KUTE.js, Velocity.js) are **imperative**: they read current DOM styles/attributes at runtime, parse them, compute differences, and write back updates.
+#### Mini-Stores for Supported Frameworks
 
-**@thednp/tween** keeps with the original Tween.js, which is the opposite approach — it's **purely state-driven**:
+Each supported framework make use of a highly specialized `miniStore` to hold tween values and update your UI. This is to ensure great DX and eliminate GC pressure. Even React can work amazing. Check the [Ministore wiki](wiki/Ministore.md) for details.
 
-- You provide **target state values** (numbers, arrays, objects)  
-- The engine interpolates **from current state** (captured at `.start()` / `.play()`)  
-- No DOM reading/parsing ever happens
-- No per browser handling/processing
+#### How the Global Update Loop Works
 
-**Advantages**:
-- Zero runtime style/attribute parsing → much faster startup & safer in concurrent React/Solid renders
-- Perfect for **state-based UI** (React, SolidJS, Vue, Svelte, etc.) — animate your app state, not the DOM directly
-- No surprises from inherited styles, CSS transitions, or computed values
-- Works equally well with **Canvas**, **SVG**, **Three.js**, **WebGL**, or **pure data** — no DOM dependency at all
-- Considerably smaller bundle size (no style parsing code)
-- More power to you due to the simplicity or the prototype
+All tween objects and timelines share **one single `requestAnimationFrame` loop** managed by `Runtime.ts`.
 
-**Trade-offs**:
-- You must manage state yourself (which is the norm in modern frameworks anyway)
-- You must process complex values yourself (values for SVG path morph)
-
-This makes `@thednp/tween` feel more like **a reactive state interpolator** than a traditional DOM tweener.
-
-#### How the global update loop works
-
-All animations share **one single `requestAnimationFrame` loop** managed by `Runtime.ts`.
-
-- When you call `.start()` / `.play()`, the instance is added to a global `Queue`
+- When you call `tween.start()` / `timeline.play()`, the instance is added to a global `Queue`
 - `Runtime()` runs every frame → calls `.update(time)` on every queued item
 - If `.update()` returns `false` (finished/stopped), the item is removed from the Queue
-- When `Queue` becomes empty → `cancelAnimationFrame` is called automatically → loop stops completely
+- When `Queue` becomes empty → `cancelAnimationFrame` is called automatically → loop stops completely.
 
 **Benefits**:
-- Only **one** rAF subscription for the entire app — extremely efficient
+- Only **one** `requestAnimationFrame` subscription for the entire app — extremely efficient
 - No manual start/stop of animation loop per tween/timeline
 - Zero overhead when nothing is animating
 
 This shared loop is why you never need to worry about starting/stopping individual `requestAnimationFrame` calls.
 
-#### Async nature of requestAnimationFrame
+
+#### Async Nature of `requestAnimationFrame`
 
 All updates are **async** by nature:
 
-1. You call `.start()` / `.play()` → instance queued
-2. Next `rAF` tick → `Runtime()` calls `.update(time)` → interpolates → calls `onUpdate`
+1. You call `tween.start()` / `timeline.play()` → instance is queued (added to the main update loop)
+2. Next `requestAnimationFrame` tick → `Runtime()` calls `instance.update(time)` → interpolates values → determines whether to call `cancelAnimationFrame` or continue
 3. DOM/state updates happen **on the next frame(s)** — never synchronous
 
 This means:
 - Visual changes are always **smooth** and **tied to the display refresh rate**
-- You can safely call `.to()`, `.duration()`, etc. **during** an animation — changes apply on the next frame
-- No risk of partial/inconsistent frames (all calculations happen before paint)
+- Very low risk of partial/inconsistent frames (most calculations happen before paint, depending on the stack size and GC queue)
 
 #### Server-Side Rendering (SSR) compatibility
 
-`@thednp/tween` is **SSR-safe** out of the box:
+**@thednp/tween** is **SSR-safe** out of the box:
 
 - No DOM access anywhere in the core
 - `requestAnimationFrame` / `cancelAnimationFrame` are only called in browser (via `Runtime()`)
-- `now()` defaults to `performance.now()` or `Date.now()` — safe fallbacks in Node
-- Hooks/primitives only start animation on client (via mount effects)
-
-Just make sure to **not call `tween.start()` / `timeline.play()`** during SSR (e.g. wrap in `if (typeof window !== 'undefined')` or use `useEffect`).
-
-#### Other important differences from classic tween libraries
+- `now()` defaults to `performance.now()`, but you can switch to `Date.now()` to create safe fallbacks in Node
+- All supported UI frameworks have consistent guards to prevent execution during server rendering, but also provide values required in the rendered HTML.
 
-| Feature/Aspect                     | Classic (GSAP/KUTE/Velocity)              | @thednp/tween                              |
-|------------------------------------|-------------------------------------------|--------------------------------------------|
-| Animation target                   | DOM elements & CSS                        | Any JS object (state, data, Canvas, etc.)  |
-| Value reading                      | Parses current style/attr at runtime      | Captures current JS values at start        |
-| Performance on startup             | Slower (parsing + computation)            | Fastest (no parsing)                       |
-| State-based UI compatibility       | Requires extra glue code                  | Native — ideal for React/Solid/Vue/Svelte  |
-| Global vs per-instance config      | Plugins/global easing                     | Per-instance `.use()` (recommended)        |
-| Bundle size                        | Larger (DOM utils, parsing, plugins)      | Very small (~2–4 KB minzipped)             |
-| Runtime loop                       | Per-tween or managed                      | Single shared global loop (most efficient) |
+Just make sure to **not call `tween.start()` / `timeline.play()`** during SSR (if you're using custom hooks outside those included in this package).
 
-#### Additional notes
 
-- **No pause/resume on single Tween** — use `.stop()` + `.startFromLast()` for pause-like behavior (keeps it simple)
-- **Repeat & yoyo** — not built-in on `Tween` (use `Timeline` for sequencing/repeats)
-- **Custom interpolators** — register per instance with `.use('prop', fn)` (prevents conflicts in large apps)
-- **Testing** — `setNow()` allows perfect time control in tests (override `now()` to fake progression)
+#### Working Around Limitations
 
-We believe this combination of **small size**, **state-first design**, **shared loop**, and **per-instance flexibility** makes **@thednp/tween** uniquely suitable for modern component-based UIs in 2026.
+- **Chaining** — use callbacks to start other `Tween` / `Timeline` (like the above, use `onComplete` callback to trigger the start of other tween/timeline instances)
+- **Custom extensions** — register per instance per property with `.use('propName', extensionConfig)` eliminates the guessing game completely, your values are validated and interpolated exactly how you want it.
+- The original Tween.js **array interpolation** - we have a way to add custom interpolators, might worth a try integrating them later.
 
 
 ### Contributing
@@ -256,4 +259,4 @@ This is a work in progress. For any issue or unclear guides, please [file an iss
 
 
 ### License
-**@thednp/tween** is released under [MIT License](LICENCE).
+**@thednp/tween** is released under [MIT License](LICENSE).

package/dist/preact/preact.d.mts

@@ -0,0 +1,62 @@
+/*!
+* @thednp/tween hooks for Preact v0.0.2 (https://github.com/thednp/tween)
+* Copyright 2026 © thednp
+* Licensed under MIT (https://github.com/thednp/tween/blob/master/LICENSE)
+*/
+"use strict";
+
+import { Timeline, Tween, TweenProps } from "@thednp/tween";
+
+//#region src/preact/miniStore.d.ts
+declare function useMiniStore<T extends TweenProps>(initialValue: T): T;
+//#endregion
+//#region src/preact/index.d.ts
+/**
+ * Hook for updating values with Tween.
+ *
+ * **NOTE**: - configuration must be wrapped in `useEffect` or `eventListener`.
+ * This has two important aspects: never configure or start update loop in SSR
+ * and only configure or start the loop when component is mounted in the client.
+ *
+ * @param initialValues - Initial tween values
+ * @returns [store, tween] Tuple of reactive store and Tween instance
+ * @example
+ * const App = () => {
+ *    const [state, tween] = useTween({ x: 0, y: 0 })
+ *
+ *    useEffect(() => {
+ *      tween.to({ x: 100, y: 100 }, 1000).start()
+ *    }, [])
+ *
+ *    return (
+ *      <div style={{ translate: `${state.x}px ${state.y}px` }} />
+ *    );
+ * }
+ */
+declare function useTween<T extends TweenProps>(initialValues: T): readonly [T, Tween<T>];
+/**
+ * Hook for sequencing values update with Timeline.
+ *
+ * **NOTE**: - configuration must be wrapped in `useEffect` or `eventListener`.
+ * This has two important aspects: never configure or start update loop in SSR
+ * and only configure or start the loop when component is mounted in the client.
+ *
+ * @param initialValues - Initial tween values
+ * @returns [store, timeline] Tuple of reactive store and Timeline instance
+ * @example
+ * const App = () => {
+ *    const [state, timeline] = useTimeline({ x: 0, y: 0 })
+ *
+ *    useEffect(() => {
+ *      timeline.to({ x: 100, y: 100 }).start()
+ *    }, [])
+ *
+ *    return (
+ *      <div style={{ translate: `${state.x}px ${state.y}px` }} />
+ *    );
+ * }
+ */
+declare function useTimeline<T extends TweenProps>(initialValues: T): readonly [T, Timeline<T>];
+//#endregion
+export { Timeline, Tween, useMiniStore, useTimeline, useTween };
+//# sourceMappingURL=preact.d.mts.map

package/dist/preact/preact.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"preact.d.mts","names":[],"sources":["../../src/preact/miniStore.ts","../../src/preact/index.ts"],"mappings":";;;;;;;;;;iBA0JgB,YAAA,WAAuB,UAAA,CAAA,CAAY,YAAA,EAAc,CAAA,GAAC,CAAA;;;AAAlE;;;;;;;;;;;;;;;;;;ACxHA;;;;ADwHA,iBCxHgB,QAAA,WAAmB,UAAA,CAAA,CAAY,aAAA,EAAe,CAAA,aAAC,CAAA,EAAA,KAAA,CAAA,CAAA;;;;;;;;;;;;;;;AA2C/D;;;;;;;;iBAAgB,WAAA,WAAsB,UAAA,CAAA,CAAY,aAAA,EAAe,CAAA,aAAC,CAAA,EAAA,QAAA,CAAA,CAAA"}

package/dist/preact/preact.mjs

@@ -0,0 +1,181 @@
+/*!
+* @thednp/tween hooks for Preact v0.0.2 (https://github.com/thednp/tween)
+* Copyright 2026 © thednp
+* Licensed under MIT (https://github.com/thednp/tween/blob/master/LICENSE)
+*/
+"use strict";
+
+import { useEffect, useRef, useState } from "preact/hooks";
+import { Timeline, Tween, dummyInstance, isArray, isPlainObject, isServer, objectHasProp } from "@thednp/tween";
+
+//#region src/preact/miniStore.ts
+const STATE_PROXY = "_proxy";
+const proxyProps = {
+	value: 1,
+	enumerable: false,
+	configurable: false,
+	writable: false
+};
+function defineArrayProxy(index, value, target, sourceLen, notifyListeners) {
+	const itemIsLast = index === sourceLen - 1;
+	if (isArray(value)) {
+		const subArray = [];
+		const valueLen = value.length;
+		value.forEach((itm, idx) => {
+			const subItemIsLast = itemIsLast && idx === valueLen - 1;
+			let currentItem = itm;
+			Object.defineProperty(subArray, idx, {
+				get: () => currentItem,
+				set: (newValue) => {
+					currentItem = newValue;
+					if (subItemIsLast) notifyListeners();
+				},
+				enumerable: true
+			});
+		});
+		target[index] = subArray;
+	} else {
+		let currentValue = value;
+		const getter = () => currentValue;
+		const setter = (newVal) => {
+			currentValue = newVal;
+			if (itemIsLast) notifyListeners();
+		};
+		Object.defineProperties(target, { [index]: {
+			get: getter,
+			set: setter,
+			enumerable: true
+		} });
+	}
+}
+function defineStateProxy(key, value, target, notifyListeners) {
+	const valueIsArray = isArray(value);
+	let currentValue = value;
+	const getter = () => currentValue;
+	let setter;
+	if (valueIsArray) {
+		const arrayProxy = [];
+		const valLength = value.length;
+		for (let i = 0; i < valLength; i++) defineArrayProxy(i, value[i], arrayProxy, valLength, notifyListeners);
+		currentValue = arrayProxy;
+	} else setter = (newValue) => {
+		if (currentValue !== newValue) {
+			currentValue = newValue;
+			notifyListeners();
+		}
+	};
+	Object.defineProperties(target, {
+		[STATE_PROXY]: proxyProps,
+		[key]: {
+			get: getter,
+			set: setter,
+			enumerable: true
+		}
+	});
+}
+function createMiniState(obj, parentReceiver, notifyListeners) {
+	if (objectHasProp(obj, STATE_PROXY)) return obj;
+	for (const [key, value] of Object.entries(obj)) if (isPlainObject(value)) parentReceiver[key] = createMiniState(value, {}, notifyListeners);
+	else defineStateProxy(key, value, parentReceiver, notifyListeners);
+	return parentReceiver;
+}
+function miniStore(init) {
+	const listeners = /* @__PURE__ */ new Set();
+	const notifyListeners = () => {
+		listeners.forEach((listener) => listener(store));
+	};
+	const store = createMiniState(init, {}, notifyListeners);
+	return {
+		get state() {
+			return store;
+		},
+		subscribe: (listener) => {
+			listeners.add(listener);
+			return () => {
+				listeners.delete(listener);
+			};
+		}
+	};
+}
+function useMiniStore(initialValue) {
+	const storeRef = useRef(null);
+	const [, setVersion] = useState(0);
+	if (!storeRef.current) storeRef.current = miniStore(initialValue);
+	useEffect(() => storeRef.current.subscribe(() => setVersion((v) => v === 2 ? 0 : v + 1)), []);
+	return storeRef.current.state;
+}
+
+//#endregion
+//#region src/preact/index.ts
+/**
+* Hook for updating values with Tween.
+*
+* **NOTE**: - configuration must be wrapped in `useEffect` or `eventListener`.
+* This has two important aspects: never configure or start update loop in SSR
+* and only configure or start the loop when component is mounted in the client.
+*
+* @param initialValues - Initial tween values
+* @returns [store, tween] Tuple of reactive store and Tween instance
+* @example
+* const App = () => {
+*    const [state, tween] = useTween({ x: 0, y: 0 })
+*
+*    useEffect(() => {
+*      tween.to({ x: 100, y: 100 }, 1000).start()
+*    }, [])
+*
+*    return (
+*      <div style={{ translate: `${state.x}px ${state.y}px` }} />
+*    );
+* }
+*/
+function useTween(initialValues) {
+	if (isServer) return [initialValues, dummyInstance];
+	const store = useMiniStore(initialValues);
+	const tweenRef = useRef(null);
+	if (!tweenRef.current) tweenRef.current = new Tween(store);
+	const dispose = () => {
+		tweenRef.current.stop();
+		tweenRef.current.clear();
+	};
+	useEffect(() => dispose, []);
+	return [store, tweenRef.current];
+}
+/**
+* Hook for sequencing values update with Timeline.
+*
+* **NOTE**: - configuration must be wrapped in `useEffect` or `eventListener`.
+* This has two important aspects: never configure or start update loop in SSR
+* and only configure or start the loop when component is mounted in the client.
+*
+* @param initialValues - Initial tween values
+* @returns [store, timeline] Tuple of reactive store and Timeline instance
+* @example
+* const App = () => {
+*    const [state, timeline] = useTimeline({ x: 0, y: 0 })
+*
+*    useEffect(() => {
+*      timeline.to({ x: 100, y: 100 }).start()
+*    }, [])
+*
+*    return (
+*      <div style={{ translate: `${state.x}px ${state.y}px` }} />
+*    );
+* }
+*/
+function useTimeline(initialValues) {
+	if (isServer) return [initialValues, dummyInstance];
+	const store = useMiniStore(initialValues);
+	const timelineRef = useRef(null);
+	if (!timelineRef.current) timelineRef.current = new Timeline(store);
+	const dispose = () => {
+		timelineRef.current.stop();
+		timelineRef.current.clear();
+	};
+	useEffect(() => dispose, []);
+	return [store, timelineRef.current];
+}
+
+//#endregion
+export { Timeline, Tween, useMiniStore, useTimeline, useTween };
+//# sourceMappingURL=preact.mjs.map

package/dist/preact/preact.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"preact.mjs","names":[],"sources":["../../src/preact/miniStore.ts","../../src/preact/index.ts"],"sourcesContent":["import { useEffect, useRef, useState } from \"preact/hooks\";\nimport {\n  type ArrayVal,\n  isArray,\n  isPlainObject,\n  objectHasProp,\n  type TweenProps,\n} from \"@thednp/tween\";\n\nconst STATE_PROXY = \"_proxy\";\nconst proxyProps = {\n  value: 1,\n  enumerable: false,\n  configurable: false,\n  writable: false,\n};\n\ntype Listener<T> = (state: T) => void;\n\nfunction defineArrayProxy<T extends ArrayVal>(\n  index: number,\n  value: T[number] | ArrayVal,\n  target: T | ArrayVal | ArrayVal[],\n  sourceLen: number,\n  notifyListeners: () => void,\n) {\n  const itemIsLast = index === sourceLen - 1;\n\n  if (isArray(value)) {\n    const subArray: typeof value = [];\n    const valueLen = value.length;\n\n    value.forEach((itm, idx) => {\n      const subItemIsLast = itemIsLast && idx === valueLen - 1;\n\n      let currentItem = itm;\n      Object.defineProperty(subArray, idx, {\n        get: () => currentItem,\n        set: (newValue: typeof itm) => {\n          currentItem = newValue;\n\n          // Only notify on last element to batch updates\n          if (subItemIsLast) {\n            notifyListeners();\n          }\n        },\n        enumerable: true,\n      });\n    });\n    target[index] = subArray;\n  } else {\n    let currentValue = value;\n    const getter = () => currentValue;\n    const setter = (newVal: typeof value) => {\n      currentValue = newVal;\n      if (itemIsLast) {\n        notifyListeners();\n      }\n    };\n    Object.defineProperties(target, {\n      [index]: {\n        get: getter,\n        set: setter,\n        enumerable: true,\n      },\n    });\n  }\n}\n\nfunction defineStateProxy<T extends Omit<TweenProps, \"_proxy\">>(\n  key: number | keyof T,\n  value: T[keyof T],\n  target: T | ArrayVal,\n  notifyListeners: () => void,\n) {\n  const valueIsArray = isArray(value);\n  let currentValue = value as ArrayVal | ArrayVal[];\n\n  const getter = () => currentValue;\n  let setter;\n\n  if (valueIsArray) {\n    // Build array proxy structure\n    const arrayProxy: ArrayVal | ArrayVal[] = [];\n    const valLength = value.length;\n\n    for (let i = 0; i < valLength; i++) {\n      defineArrayProxy(\n        i,\n        (value as ArrayVal)[i],\n        arrayProxy as ArrayVal,\n        valLength,\n        notifyListeners,\n      );\n    }\n    currentValue = arrayProxy;\n  } else {\n    setter = (newValue: typeof currentValue) => {\n      if (currentValue !== newValue) {\n        currentValue = newValue;\n        notifyListeners();\n      }\n    };\n  }\n\n  Object.defineProperties(target, {\n    [STATE_PROXY]: proxyProps,\n    [key]: {\n      get: getter,\n      set: setter,\n      enumerable: true,\n    },\n  });\n}\n\nfunction createMiniState<T extends TweenProps>(\n  obj: T,\n  parentReceiver: TweenProps,\n  notifyListeners: () => void,\n) {\n  if (objectHasProp(obj, STATE_PROXY)) return obj;\n\n  for (const [key, value] of Object.entries(obj)) {\n    if (isPlainObject(value)) {\n      parentReceiver[key] = createMiniState(value, {}, notifyListeners);\n    } else {\n      defineStateProxy(key, value, parentReceiver, notifyListeners);\n    }\n  }\n\n  return parentReceiver as T;\n}\n\nexport function miniStore<T extends TweenProps>(init: T) {\n  const listeners = new Set<Listener<T>>();\n  const notifyListeners = () => {\n    listeners.forEach((listener) => listener(store));\n  };\n\n  const store = createMiniState(init, {}, notifyListeners) as T;\n\n  return {\n    get state() {\n      return store;\n    },\n    subscribe: (listener: Listener<T>) => {\n      listeners.add(listener);\n      return () => {\n        listeners.delete(listener);\n      };\n    },\n  };\n}\n\nexport function useMiniStore<T extends TweenProps>(initialValue: T) {\n  const storeRef = useRef<ReturnType<typeof miniStore<T>>>(null);\n  const [, setVersion] = useState(0);\n\n  // istanbul ignore else @preserve\n  if (!storeRef.current) {\n    storeRef.current = miniStore(initialValue);\n  }\n\n  useEffect(\n    () =>\n      storeRef.current!.subscribe(() => setVersion((v) => v === 2 ? 0 : v + 1)),\n    [],\n  );\n\n  return storeRef.current!.state;\n}\n","import { useEffect, useRef } from \"preact/hooks\";\nimport {\n  dummyInstance,\n  isServer,\n  Timeline,\n  Tween,\n  type TweenProps,\n} from \"@thednp/tween\";\nimport { useMiniStore } from \"./miniStore.ts\";\n\nexport { Timeline, Tween, useMiniStore };\n\n/**\n * Hook for updating values with Tween.\n *\n * **NOTE**: - configuration must be wrapped in `useEffect` or `eventListener`.\n * This has two important aspects: never configure or start update loop in SSR\n * and only configure or start the loop when component is mounted in the client.\n *\n * @param initialValues - Initial tween values\n * @returns [store, tween] Tuple of reactive store and Tween instance\n * @example\n * const App = () => {\n *    const [state, tween] = useTween({ x: 0, y: 0 })\n *\n *    useEffect(() => {\n *      tween.to({ x: 100, y: 100 }, 1000).start()\n *    }, [])\n *\n *    return (\n *      <div style={{ translate: `${state.x}px ${state.y}px` }} />\n *    );\n * }\n */\nexport function useTween<T extends TweenProps>(initialValues: T) {\n  if (isServer) {\n    return [initialValues, dummyInstance as unknown as Tween<T>] as const;\n  }\n  const store = useMiniStore(initialValues);\n  const tweenRef = useRef<Tween<T>>(null);\n\n  // istanbul ignore else @preserve\n  if (!tweenRef.current) {\n    tweenRef.current = new Tween(store);\n  }\n\n  const dispose = () => {\n    tweenRef.current!.stop();\n    tweenRef.current!.clear();\n  };\n  useEffect(() => dispose, []);\n\n  return [store, tweenRef.current] as [T, Tween<T>];\n}\n\n/**\n * Hook for sequencing values update with Timeline.\n *\n * **NOTE**: - configuration must be wrapped in `useEffect` or `eventListener`.\n * This has two important aspects: never configure or start update loop in SSR\n * and only configure or start the loop when component is mounted in the client.\n *\n * @param initialValues - Initial tween values\n * @returns [store, timeline] Tuple of reactive store and Timeline instance\n * @example\n * const App = () => {\n *    const [state, timeline] = useTimeline({ x: 0, y: 0 })\n *\n *    useEffect(() => {\n *      timeline.to({ x: 100, y: 100 }).start()\n *    }, [])\n *\n *    return (\n *      <div style={{ translate: `${state.x}px ${state.y}px` }} />\n *    );\n * }\n */\nexport function useTimeline<T extends TweenProps>(initialValues: T) {\n  if (isServer) {\n    return [initialValues, dummyInstance as unknown as Timeline<T>] as const;\n  }\n  const store = useMiniStore(initialValues);\n  const timelineRef = useRef<Timeline<T>>(null);\n\n  // istanbul ignore else @preserve\n  if (!timelineRef.current) {\n    timelineRef.current = new Timeline(store);\n  }\n\n  const dispose = () => {\n    timelineRef.current!.stop();\n    timelineRef.current!.clear();\n  };\n  useEffect(() => dispose, []);\n\n  return [store, timelineRef.current] as [T, Timeline<T>];\n}\n"],"mappings":"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"}