physics-animator 0.16.0 → 1.0.0

package/README.md

@@ -12,19 +12,20 @@ Why use this over other animation systems?
 
 This library focuses on simplicity and correctness – I've generally run into design troubles with popular animation libraries like framer motion: for example complex framer animations become convoluted and don't correctly handled interruptions without discontinuities in velocity
 
-For example in react, to animate opacity we could do
+For example in react, to animate DOM opacity we could do
 
 ```tsx
 useSpringValue(
-    { initial: 0, target: 1, duration_s: 0.8 },
-    value => el.style.opacity = value
+    1.0, // target
+    { duration_s: 0.8 },
+    value => el.style.opacity = value // onChange
 )
 ```
 
 Or via state
 
 ```tsx
-const opacitySpring = useSpringState({ initial: 0, duration_s: 0.8, target: opacity })
+const opacitySpring = useSpringState(opacity, { duration_s: 0.8 })
 
 return <div style={{ opacity: opacitySpring }} />
 ```
@@ -32,8 +33,8 @@ return <div style={{ opacity: opacitySpring }} />
 It works with arrays and objects
 
 ```tsx
-const rgb = useSpringState({ initial: [0, 0, 0], target: [1, 0, 0], duration_s: 0.8 })
-const xy = useSpringState({ initial: { x: 0, y: 0 }, target: {x: mouse.x, y: mouse.y}, duration_s: 0.1 })
+const rgb = useSpringState([1, 0, 0], { initial: [0, 0, 0], duration_s: 0.8 })
+const xy = useSpringState({x: mouse.x, y: mouse.y})
 ```
 
 Outside of react we use the animator object

package/dist/cjs/react/useSpringState.js

@@ -14,12 +14,11 @@ const useSpringValue_js_1 = require("./useSpringValue.js");
  *
  * See {@link useSpringValue} for a version that does not cause re-renders.
  */
-function useSpringState(options) {
-    const [state, setState] = (0, react_1.useState)(options.initial);
-    (0, useSpringValue_js_1.useSpringValue)({
-        ...options,
-        initial: options.initial,
-        target: options.target,
-    }, setState);
+function useSpringState(value, options = {
+    duration_s: 0.5,
+}) {
+    // type N = WidenNumber<T>;
+    const [state, setState] = (0, react_1.useState)(value);
+    (0, useSpringValue_js_1.useSpringValue)(value, options, setState);
     return state;
 }

package/dist/cjs/react/useSpringValue.js

@@ -4,35 +4,16 @@ exports.useSpringValue = useSpringValue;
 const use_initializer_1 = require("use-initializer");
 const useAnimator_js_1 = require("./useAnimator.js");
 const react_1 = require("react");
-/**
- * A value that animates to a target value using a spring animation.
- * This will **not** cause a re-render when the value changes.
- *
- * Usage example:
- * ```tsx
- * useSpringValue(
- *    { initial: 0, target: 1, duration_s: 0.8 },
- *    // onChange
- *    value => el.style.opacity = value
- * );
- * ```
- *
- * See {@link useSpringState} for a version that does cause re-renders.
- */
-function useSpringValue(options, onChange) {
+function useSpringValue(value, optionsOrOnChange, maybeOnChange) {
+    const options = typeof optionsOrOnChange === 'function'
+        ? { duration_s: 0.5 }
+        : optionsOrOnChange;
+    const onChange = typeof optionsOrOnChange === 'function'
+        ? optionsOrOnChange
+        : maybeOnChange;
     const animator = (0, useAnimator_js_1.useAnimator)(options.animator);
-    const springValue = (0, use_initializer_1.useInitializer)(() => {
-        return {
-            value: structuredClone(options.initial),
-        };
-    });
-    (0, react_1.useEffect)(() => {
-        let remove = animator.onChange(springValue, () => {
-            onChange(springValue.value);
-        }).remove;
-        return () => {
-            remove();
-        };
-    }, [springValue, onChange]);
-    animator.springTo(springValue, { value: options.target }, options);
+    const springObject = (0, use_initializer_1.useInitializer)(() => ({ value: options.initial ?? value }));
+    (0, react_1.useEffect)(() => animator.onChange(springObject, () => onChange(springObject.value)).remove // return the cleanup function
+    , [springObject, onChange]);
+    animator.springTo(springObject, { value }, options);
 }

package/dist/esm/react/useSpringState.js

@@ -11,12 +11,11 @@ import { useSpringValue } from "./useSpringValue.js";
  *
  * See {@link useSpringValue} for a version that does not cause re-renders.
  */
-export function useSpringState(options) {
-    const [state, setState] = useState(options.initial);
-    useSpringValue({
-        ...options,
-        initial: options.initial,
-        target: options.target,
-    }, setState);
+export function useSpringState(value, options = {
+    duration_s: 0.5,
+}) {
+    // type N = WidenNumber<T>;
+    const [state, setState] = useState(value);
+    useSpringValue(value, options, setState);
     return state;
 }

package/dist/esm/react/useSpringValue.js

@@ -1,35 +1,16 @@
 import { useInitializer } from "use-initializer";
 import { useAnimator } from "./useAnimator.js";
 import { useEffect } from "react";
-/**
- * A value that animates to a target value using a spring animation.
- * This will **not** cause a re-render when the value changes.
- *
- * Usage example:
- * ```tsx
- * useSpringValue(
- *    { initial: 0, target: 1, duration_s: 0.8 },
- *    // onChange
- *    value => el.style.opacity = value
- * );
- * ```
- *
- * See {@link useSpringState} for a version that does cause re-renders.
- */
-export function useSpringValue(options, onChange) {
+export function useSpringValue(value, optionsOrOnChange, maybeOnChange) {
+    const options = typeof optionsOrOnChange === 'function'
+        ? { duration_s: 0.5 }
+        : optionsOrOnChange;
+    const onChange = typeof optionsOrOnChange === 'function'
+        ? optionsOrOnChange
+        : maybeOnChange;
     const animator = useAnimator(options.animator);
-    const springValue = useInitializer(() => {
-        return {
-            value: structuredClone(options.initial),
-        };
-    });
-    useEffect(() => {
-        let remove = animator.onChange(springValue, () => {
-            onChange(springValue.value);
-        }).remove;
-        return () => {
-            remove();
-        };
-    }, [springValue, onChange]);
-    animator.springTo(springValue, { value: options.target }, options);
+    const springObject = useInitializer(() => ({ value: options.initial ?? value }));
+    useEffect(() => animator.onChange(springObject, () => onChange(springObject.value)).remove // return the cleanup function
+    , [springObject, onChange]);
+    animator.springTo(springObject, { value }, options);
 }

package/dist/types/Animator.d.ts

@@ -53,21 +53,8 @@ export declare class Animator {
     easeInOutTo<Obj>(object: Obj, target: Partial<Public<Obj>>, duration_s: number): void;
     easeInTo<Obj>(object: Obj, target: Partial<Public<Obj>>, duration_s: number): void;
     easeOutTo<Obj>(object: Obj, target: Partial<Public<Obj>>, duration_s: number): void;
-    onCompleteField<Obj, Name extends keyof Obj>(object: Obj, field: Name, callback: (object: Obj, field: Name) => void, once?: 'once'): {
-        priority: number;
-        listener: (event: {
-            object: any;
-            field: FieldKey;
-        }) => void;
-        remove: () => void;
-    };
-    onComplete<Obj>(object: Obj, callback: (object: Obj) => void, once?: 'once'): {
-        priority: number;
-        listener: (event: {
-            object: any;
-        }) => void;
-        remove: () => void;
-    };
+    onCompleteField<Obj, Name extends keyof Obj>(object: Obj, field: Name, callback: (object: Obj, field: Name) => void, once?: 'once'): EventSignal.Listener;
+    onComplete<Obj>(object: Obj, callback: (object: Obj) => void, once?: 'once'): EventSignal.Listener;
     /**
      * Execute a callback when a specific field of an object is changed by the animator
      */
@@ -80,20 +67,8 @@ export declare class Animator {
     onChange<Obj>(object: Obj, callback: (object: Obj) => void): {
         remove: () => void;
     };
-    onBeforeStep(callback: (dt_s: number) => void): {
-        priority: number;
-        listener: (event: {
-            dt_s: number;
-        }) => void;
-        remove: () => void;
-    };
-    onAfterStep(callback: (dt_s: number) => void): {
-        priority: number;
-        listener: (event: {
-            dt_s: number;
-        }) => void;
-        remove: () => void;
-    };
+    onBeforeStep(callback: (dt_s: number) => void): EventSignal.Listener;
+    onAfterStep(callback: (dt_s: number) => void): EventSignal.Listener;
     step(dt_s: number): void;
     private t_last;
     tick(): number;

package/dist/types/react/useSpringState.d.ts

@@ -1,6 +1,5 @@
 import { Animator } from "../Animator.js";
 import { SpringParameters } from "../animators/SpringAnimator.js";
-type WidenNumber<T> = T extends number ? number : T;
 /**
  * A value that animates to a target value using a spring animation.
  * This **will** cause a re-render when the value changes.
@@ -14,9 +13,7 @@ type WidenNumber<T> = T extends number ? number : T;
  */
 export declare function useSpringState<T extends number | number[] | {
     [field: PropertyKey]: number;
-}>(options: {
+}>(value: T, options?: {
     animator?: Animator;
-    initial: T;
-    target: T;
-} & SpringParameters): WidenNumber<T>;
-export {};
+    initial?: T;
+} & SpringParameters): T;

package/dist/types/react/useSpringValue.d.ts

@@ -1,5 +1,9 @@
 import { Animator } from "../Animator.js";
 import { SpringParameters } from "../animators/SpringAnimator.js";
+type SpringOptions<T> = {
+    animator?: Animator;
+    initial?: T;
+} & SpringParameters;
 /**
  * A value that animates to a target value using a spring animation.
  * This will **not** cause a re-render when the value changes.
@@ -7,18 +11,24 @@ import { SpringParameters } from "../animators/SpringAnimator.js";
  * Usage example:
  * ```tsx
  * useSpringValue(
- *    { initial: 0, target: 1, duration_s: 0.8 },
+ *    1,
+ *    { initial: 0, duration_s: 0.8 },
  *    // onChange
  *    value => el.style.opacity = value
  * );
  * ```
  *
+ * Or with default options:
+ * ```tsx
+ * useSpringValue(1, value => el.style.opacity = value);
+ * ```
+ *
  * See {@link useSpringState} for a version that does cause re-renders.
  */
 export declare function useSpringValue<T extends number | number[] | {
     [field: PropertyKey]: number;
-}>(options: {
-    animator?: Animator;
-    initial: T;
-    target: T;
-} & SpringParameters, onChange: (value: T) => void): void;
+}>(value: T, onChange: (value: T) => void): void;
+export declare function useSpringValue<T extends number | number[] | {
+    [field: PropertyKey]: number;
+}>(value: T, options: SpringOptions<T>, onChange: (value: T) => void): void;
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "physics-animator",
-  "version": "0.16.0",
+  "version": "1.0.0",
   "author": "haxiomic (George Corney)",
   "license": "MIT",
   "description": "A TypeScript animation system grounded in physics with three.js and react support.",
@@ -47,7 +47,7 @@
     "typescript": "^5.0.0"
   },
   "dependencies": {
-    "@haxiomic/event-signal": "^1.1.0",
+    "@haxiomic/event-signal": "^1.2.0",
     "use-initializer": "^1.1.0"
   },
   "peerDependencies": {