@ringozz/react-godot 4.7.2-585 → 4.7.2-594

package/README.md

@@ -284,7 +284,7 @@ export function App() {
 | `createPortal(children, container)` | Function | Renders children into a target Godot `Node` (e.g. `CanvasLayer` or `SubViewport`). |
 | `useSignal(signal, callback)` | Hook | Connects a callback to a Godot object signal (e.g. `tree.processFrame`, `node.treeEntered`). Disconnects on unmount. |
 | `useMutableCallback(fn)` | Hook | Returns a `RefObject` whose `.current` always points to the latest callback implementation. |
-| `useTween(create, deps)` | Hook | Reactive tween-as-prop-value. Returns `[spring, tweenRef]` — spread `spring` onto a node; `tweenRef.current` is the live native `Tween`. |
+| `useTween<NodeT>(create, deps)` | Hook | Reactive tween-as-prop-value. Returns `[spring, tweenRef]` — spread `spring` onto a node; `tweenRef.current` is the live native `Tween`. The optional node type (`useTween<Node3D>`) types `to`/`from` array goals as that node's value-type tuples. |
 | `ComponentProps<T>` | Type | Utility type to infer valid React JSX props for any Godot node class `T`. |
 
 ## Animating props with `useTween`
@@ -292,9 +292,9 @@ export function App() {
 `useTween` animates a node's properties declaratively. You describe the target values once per `to` key; spreading the returned `spring` onto a node binds the tween to it. Re-rendering with the same `deps` keeps the same tween (nothing restarts); changing `deps` creates a new `Tween` and animates from the current values.
 
 ```tsx
-const [spring, tweenRef] = useTween(() => ({
-  from: { position: [0, 0, 0] },
-  to:   { position: [0, 2, 0], globalRotation: [0, 90, 0] },
+const [spring, tweenRef] = useTween<Node3D>(() => ({
+  from: { position: [0, 0, 0] },
+  to:   { position: [0, 2, 0], globalRotation: [0, 90, 0] },
   config: { duration: 0.6, transition: TransitionType.TRANS_QUAD, ease: EaseType.EASE_IN_OUT },
   delay: 0, loops: 1, immediate: false,
   onFinished: () => {},
@@ -303,7 +303,8 @@ const [spring, tweenRef] = useTween(() => ({
 return <Node3D {...spring} />;
 ```
 
-- **`spring`** holds one function per `to` key (spread them all onto the node; each contributes its own prop's tweener to the shared `Tween`). Array values are converted to the property's value type.
+- **`spring`** holds one function per `to` key (spread them all onto the node; each contributes its own prop's tweener to the shared `Tween`). Array values are converted to the property's value type.
+- **Node-typed goals**: call `useTween<Node3D>(...)` so `to`/`from` are typed against that node's props — `position: [0, 2, 0]` and nested `basis: [[…]]` infer as `Vector3`/`Basis`, with no `as Vector3` casts. Only scalar-number and value-type props are tweenable (signals, `Node` refs, bools, strings, containers are rejected); the returned `spring` is that whole prop set (all optional), so `{...spring}` stays JSX-spreadable. A bare `useTween(...)` keeps array goals loose (`number[]`).
 - **`tweenRef.current`** is the **live native Godot `Tween`**, created when the node mounts (null before that): `tweenRef.current?.kill()`, `?.pause()`, `?.play()`, `?.setSpeedScale(n)`, `?.isRunning()`, `?.finished`…
 - **`config`** maps to the Godot Tween API: `duration` (seconds), `transition`/`ease` (`TransitionType`/`EaseType` — the tween's defaults), `easing` (a `[0,1]→[0,1]` function → `setCustomInterpolator`), `speedScale`.
 - **`onStart`** fires when the tween is created/bound (on mount or when `deps` change), before it starts stepping.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@ringozz/react-godot",
   "author": "Vladimir Davidovich",
-  "version": "4.7.2-585",
+  "version": "4.7.2-594",
   "description": "A React renderer for Godot Engine via @ringozz/godot",
   "publishConfig": {
     "access": "public"
@@ -23,7 +23,7 @@
     "*.md"
   ],
   "dependencies": {
-    "@ringozz/godot": "^4.7.2-585",
+    "@ringozz/godot": "^4.7.2-594",
     "@types/react-reconciler": "^0.33.0",
     "react-reconciler": "^0.33.0"
   },

package/src/react-hooks.ts

@@ -6,10 +6,10 @@ import type { Signal } from '@ringozz/godot';
 import type { Node } from '@ringozz/godot/Node';
 import type { Object as Instance } from '@ringozz/godot/Object';
 import { PropertyTweener } from '@ringozz/godot/PropertyTweener';
-import { Tween, type EaseType, type TransitionType } from '@ringozz/godot/Tween';
-import type React from 'react';
-import { useEffect, useMemo, useRef } from 'react';
-import { toValueType, type GodotVar } from '@ringozz/godot/runtime';
+import { Tween, type EaseType, type TransitionType } from '@ringozz/godot/Tween';
+import type React from 'react';
+import { useEffect, useMemo, useRef } from 'react';
+import { toValueType } from '@ringozz/godot/runtime';
 
 // Tween/PropertyTweener are only type-used here; value-reference them so their
 // `_R` class registration isn't tree-shaken (otherwise createTween's wrapper
@@ -47,9 +47,24 @@ export function useSignal<T extends (...args: any[]) => any>(signal: Signal<T>,
 // identity diff drops them, so nothing restarts); changing deps creates a new
 // tween (the previous one is killed).
 
-// Value-type goals are named tuples on the JS side — flat ones are `number[]`,
-// nested ones (Transform2D/Basis/Transform3D/Projection/AABB) are `number[][]`.
-export type TweenValue = number | number[] | number[][] | GodotVar;
+// Tweenable goal values: scalars and value-type tuples. `GodotVar` (the base of
+// *every* Godot object) is deliberately NOT a member — `useTween` always wraps
+// goals through `toValueType`, so callers pass plain numbers/tuples, and
+// including `GodotVar` would wrongly admit signals/`Node` refs/object props.
+//
+// When the caller passes a node instance type (e.g. `useTween<Node3D>`), `to`
+// /`from` are contextually typed against that node's settable props, so each
+// array goal infers as the property's value-type tuple (Vector3, Basis, …). A
+// bare `useTween(...)` call keeps the loose behavior below (`number[]` goals).
+type TweenValue = number | number[] | number[][];
+
+// Settable props whose value is a tweenable goal (`number`/value-type tuple).
+// Signals, `Node` refs and other Godot objects are not `TweenValue`s, so they
+// never leak into `spring` (`{...spring}` stays JSX-spreadable). Mapping over
+// `keyof T` lets `to` be contextually typed with the node's value-type tuples.
+type TweenableProps<T> = {
+  [K in keyof T as T[K] extends TweenValue ? K : never]: T[K];
+};
 
 export interface TweenConfig {
   /** Seconds (default 1). */
@@ -64,11 +79,11 @@ export interface TweenConfig {
   speedScale?: number;
 }
 
-export interface TweenProps<T extends Record<string, TweenValue> = Record<string, TweenValue>> {
-  /** Start values, applied on the first build (mount) before animating to `to`. */
-  from?: Partial<T>;
-  /** Target values — one assigner is returned per key. */
-  to: T;
+export interface TweenProps<P extends Record<string, unknown> = Record<string, TweenValue>> {
+  /** Start values, applied on the first build (mount) before animating to `to`. */
+  from?: Partial<P>;
+  /** Target values — one assigner is returned per key. */
+  to: P;
   config?: TweenConfig;
   /** Seconds; per-tweener PropertyTweener.setDelay. */
   delay?: number;
@@ -81,19 +96,19 @@ export interface TweenProps<T extends Record<string, TweenValue> = Record<string
   onFinished?: () => void;
 }
 
-export type Spring<T extends Record<string, TweenValue>> = { [K in keyof T]: T[K] };
+export type Spring<P extends Record<string, unknown>> = { [K in keyof P]: P[K] };
 
 // tweenProperty/set reject generic JS arrays, so array goals are reconstructed
 // as the property's value type by `toValueType` (resolves the node's
 // property type and returns a GodotVar carrier the `_C` tween path unwraps;
 // non-array goals pass through unchanged).
 
-function makeSpring<T extends Record<string, TweenValue>>(
-  tweenRef: { current: Tween | null },
-  props: TweenProps<T>,
-): Spring<T> {
-  const config = props.config ?? {};
-  const spring = {} as Spring<T>;
+function makeSpring<P extends Record<string, unknown>>(
+  tweenRef: { current: Tween | null },
+  props: TweenProps<P>,
+): Spring<P> {
+  const config = props.config ?? {};
+  const spring = {} as Spring<P>;
   let started = false;
   let applyFrom = false;
 
@@ -126,15 +141,18 @@ function makeSpring<T extends Record<string, TweenValue>>(
       if (props.delay !== undefined) tw.setDelay(props.delay);
       if (config.easing) tw.setCustomInterpolator(config.easing);
     };
-    spring[key as keyof T] = assigner as unknown as T[keyof T];
-  }
-  return spring;
-}
-
-export function useTween<T extends Record<string, TweenValue>>(
-  create: () => TweenProps<T>,
-  deps: unknown[] = [],
-): [Spring<T>, React.RefObject<Tween | null>] {
+    spring[key as keyof P] = assigner as unknown as P[keyof P];
+  }
+  return spring;
+}
+
+export function useTween<
+  T extends Instance = any,
+  P extends Partial<TweenableProps<T>> = Partial<TweenableProps<T>>,
+>(
+  create: () => TweenProps<P>,
+  deps: unknown[] = [],
+): [Spring<P>, React.RefObject<Tween | null>] {
   const tweenRef = useRef<Tween | null>(null);
   // 'create' is intentionally re-evaluated via `deps`, not listed here.
   /* oxlint-disable-next-line react-hooks/exhaustive-deps */