@ringozz/react-godot 1.0.0-0 → 1.0.0-10

package/src/react-hooks.ts

@@ -1,22 +1,148 @@
-/**********************************************************************
- Copyright (c) Vladimir Davidovich. All rights reserved.
-***********************************************************************/
-
-import type { Signal } from '@ringozz/godot';
-import type React from 'react';
-import { useEffect, useRef } from 'react';
-
-export function useMutableCallback<T>(fn: T): React.RefObject<T> {
-  const ref = useRef<T>(fn);
-  useEffect(() => void (ref.current = fn), [fn]);
-  return ref;
-}
-
-export function useSignal<T extends (...args: any[]) => any>(signal: Signal<T>, handler: T): void {
-  const ref = useMutableCallback(handler);
-  useEffect(() => {
-    const fn = ((...args: any[]) => ref.current(...args)) as T;
-    signal.connect(fn);
-    return () => signal.disconnect(fn);
-  }, [signal.getObjectId(), signal.getName()]);
-}
+/**********************************************************************
+ Copyright (c) Vladimir Davidovich. All rights reserved.
+***********************************************************************/
+
+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 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';
+
+// Tween/PropertyTweener are only type-used here; value-reference them so their
+// `_R` class registration isn't tree-shaken (otherwise createTween's wrapper
+// falls back to an ancestor class and loses pause/play/tweenProperty).
+void Tween;
+void PropertyTweener;
+
+export function useMutableCallback<T>(fn: T): React.RefObject<T> {
+  const ref = useRef<T>(fn);
+  useEffect(() => void (ref.current = fn), [fn]);
+  return ref;
+}
+
+export function useSignal<T extends (...args: any[]) => any>(signal: Signal<T>, handler: T): void {
+  const ref = useMutableCallback(handler);
+  useEffect(() => {
+    const fn = ((...args: any[]) => ref.current(...args)) as T;
+    signal.connect(fn);
+    return () => signal.disconnect(fn);
+  // do not specify 'signal' dependency, because it changes often.
+  // specify invariant contents instead.
+  /* oxlint-disable-next-line react-hooks/exhaustive-deps */
+  }, [signal.getObjectId(), signal.getName()]);
+}
+
+// ---- useTween: tween-as-prop-value ----
+//
+// useTween(create, deps) returns [spring, tweenRef]. `spring` holds one
+// value-assigner per `to` key — a plain function spread onto the node
+// (`<Node3D {...spring} />`). Instance.assign (C++) treats any function on a
+// non-signal prop as a value-assigner and invokes it with (node, nativeName);
+// each contributes its own prop's tweener to one shared native Tween created on
+// the first invocation. `tweenRef.current` is that Tween (null until mounted).
+// Re-rendering with the same deps keeps the same assigners (the reconciler's
+// identity diff drops them, so nothing restarts); changing deps creates a new
+// tween (the previous one is killed).
+
+export type TweenValue = number | number[] | GodotVar;
+
+export interface TweenConfig {
+  /** Seconds (default 1). */
+  duration?: number;
+  /** Tween.setTrans — the default for the tween's tweeners. */
+  transition?: TransitionType;
+  /** Tween.setEase — the default for the tween's tweeners. */
+  ease?: EaseType;
+  /** PropertyTweener.setCustomInterpolator — a [0,1]→[0,1] easing function. */
+  easing?: (t: number) => number;
+  /** Tween.setSpeedScale. */
+  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;
+  config?: TweenConfig;
+  /** Seconds; per-tweener PropertyTweener.setDelay. */
+  delay?: number;
+  /** Tween.setLoops (0 = infinite). */
+  loops?: number;
+  /** Snap to `to` instead of animating. */
+  immediate?: boolean;
+  onStart?: () => void;
+  /** Fires on natural completion only (Godot's `finished`); kills/unmount don't fire it. */
+  onFinished?: () => void;
+}
+
+export type Spring<T extends Record<string, TweenValue>> = { [K in keyof T]: T[K] };
+
+// tweenProperty/set reject JS arrays, so array goals are reconstructed as the
+// property's value type (read via get(native).constructor).
+function toValueType(node: Instance, native: string, value: TweenValue): unknown {
+  if (!Array.isArray(value)) return value;
+  const Ctor = (node.get(native) as any)?.constructor;
+  if (typeof Ctor === 'function') return new Ctor(...value);
+  return value;
+}
+
+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>;
+  let started = false;
+  let applyFrom = false;
+
+  for (const [key, value] of Object.entries(props.to)) {
+    const fromValue = props.from?.[key];
+    const assigner = (node: Instance, native: string) => {
+      if (props.immediate) {
+        tweenRef.current?.kill();
+        tweenRef.current = null;
+        node.set(native, toValueType(node, native, value));
+        return;
+      }
+      if (!started) {
+        started = true;
+        applyFrom = tweenRef.current === null; // first build (mount) ⇒ apply `from`
+        tweenRef.current?.kill();
+        const t = (node as unknown as Node).createTween();
+        tweenRef.current = t;
+        if (config.transition !== undefined) t.setTrans(config.transition);
+        if (config.ease !== undefined) t.setEase(config.ease);
+        if (config.speedScale !== undefined) t.setSpeedScale(config.speedScale);
+        if (props.loops !== undefined) t.setLoops(props.loops);
+        if (props.onFinished) t.finished.connect(props.onFinished);
+        t.bindNode(node as unknown as Node);
+        t.setParallel(true);
+        props.onStart?.();
+      }
+      const tw = tweenRef.current!.tweenProperty(node, native, toValueType(node, native, value), config.duration ?? 1);
+      if (applyFrom && fromValue !== undefined) tw.from(toValueType(node, native, fromValue));
+      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>] {
+  const tweenRef = useRef<Tween | null>(null);
+  // 'create' is intentionally re-evaluated via `deps`, not listed here.
+  /* oxlint-disable-next-line react-hooks/exhaustive-deps */
+  const spring = useMemo(() => makeSpring(tweenRef, create()), deps);
+  // No unmount kill: the tween is `createTween()`-bound to the node, so Godot
+  // kills it when the node exits the tree. A `useEffect` cleanup would also run
+  // on StrictMode's synthetic mount teardown and kill the just-created tween.
+  return [spring, tweenRef];
+}

package/src/react-jsx.ts

@@ -1,41 +1,45 @@
-/**********************************************************************
- Copyright (c) Vladimir Davidovich. All rights reserved.
-***********************************************************************/
-
-import { jsxDEV as reactJsxDEV } from 'react/jsx-dev-runtime';
-import type * as ReactJSX from 'react/jsx-runtime';
-import { Fragment, jsx as reactJsx, jsxs as reactJsxs } from 'react/jsx-runtime';
-import type { ComponentProps, Instance } from './react-types.ts';
-import { GodotVar } from '@ringozz/godot/runtime';
-
-export function jsx(type: any, props?: any, key?: any) {
-  return reactJsx(GodotVar.isPrototypeOf(type) ? type.name : type, props, key);
-}
-
-export function jsxs(type: any, props?: any, key?: any) {
-  return reactJsxs(GodotVar.isPrototypeOf(type) ? type.name : type, props, key);
-}
-
-export function jsxDEV(type: any, props?: any, key?: any, isStatic?: any, source?: any, self?: any) {
-  return reactJsxDEV(GodotVar.isPrototypeOf(type) ? type.name : type, props, key, isStatic, source, self);
-}
-
-export { Fragment };
-
-declare module '@ringozz/react-godot/jsx-runtime' {
-  export namespace JSX {
-    interface IntrinsicElements extends ReactJSX.JSX.IntrinsicElements { }
-    interface Element extends ReactJSX.JSX.Element { }
-
-    type GodotConstructor = { new(...args: any[]): Instance } & Function;
-
-    type ElementType =
-      | ReactJSX.JSX.ElementType
-      | GodotConstructor;
-
-    type LibraryManagedAttributes<C, P> =
-      C extends GodotConstructor
-      ? ComponentProps<C>
-      : ReactJSX.JSX.LibraryManagedAttributes<C, P>;
-  }
-}
+/**********************************************************************
+ Copyright (c) Vladimir Davidovich. All rights reserved.
+***********************************************************************/
+
+import { jsxDEV as reactJsxDEV } from 'react/jsx-dev-runtime';
+import type * as ReactJSX from 'react/jsx-runtime';
+import { Fragment, jsx as reactJsx, jsxs as reactJsxs } from 'react/jsx-runtime';
+import type { ComponentProps, GodotConstructor } from './react-types.ts';
+import { GodotVar } from '@ringozz/godot/runtime';
+
+export function jsx(type: any, props?: any, key?: any) {
+  return reactJsx(GodotVar.isPrototypeOf(type) ? type.name : type, props, key);
+}
+
+export function jsxs(type: any, props?: any, key?: any) {
+  return reactJsxs(GodotVar.isPrototypeOf(type) ? type.name : type, props, key);
+}
+
+export function jsxDEV(type: any, props?: any, key?: any, isStatic?: any, source?: any, self?: any) {
+  return reactJsxDEV(GodotVar.isPrototypeOf(type) ? type.name : type, props, key, isStatic, source, self);
+}
+
+export { Fragment };
+
+// JSX namespace augmentation: these types are the public JSX contract for the
+// `@ringozz/react-godot/jsx-runtime` import source, consumed by TypeScript in
+// consumer files. They are intentionally not referenced within this module.
+/* oxlint-disable no-unused-vars */
+declare module '@ringozz/react-godot/jsx-runtime' {
+  export namespace JSX {
+    interface IntrinsicAttributes extends ReactJSX.JSX.IntrinsicAttributes { }
+    interface IntrinsicElements extends ReactJSX.JSX.IntrinsicElements { }
+    interface Element extends ReactJSX.JSX.Element { }
+
+    type ElementType =
+      | ReactJSX.JSX.ElementType
+      | GodotConstructor;
+
+    type LibraryManagedAttributes<C, P> =
+      C extends GodotConstructor
+      ? ComponentProps<C>
+      : ReactJSX.JSX.LibraryManagedAttributes<C, P>;
+  }
+}
+/* oxlint-enable no-unused-vars */

package/src/react-types.ts

@@ -4,33 +4,49 @@
 
 import type React from 'react';
 import type { Object } from '@ringozz/godot/Object';
-import type { ValueTypes } from '@ringozz/godot';
+import type { Signal, ValueTypes } from '@ringozz/godot';
+import type { PackedScene } from '@ringozz/godot/PackedScene';
+
+// Identity check sensitive to readonly (deferred-conditional trick; the
+// comparison lives in return-type position, so it is independent of
+// strictFunctionTypes).
+type Equal<X, Y> = (<T>() => T extends X ? 1 : 2) extends
+  (<T>() => T extends Y ? 1 : 2) ? true : false;
 
-type FunctionKeys<T> = { [K in keyof T]: T[K] extends Function ? K : never }[keyof T];
-type Properties<T> = Omit<T, FunctionKeys<T>>;
-type Overwrite<P, O> = Properties<P> & O;
-type Mutable<P> = { [K in keyof P]: P[K] | Readonly<P[K]> };
 type ConstructorRepresentation<T = any> = new (...args: any[]) => T;
 
 export type Instance = Object;
 
+export type GodotConstructor<T extends Instance = Instance> = ConstructorRepresentation<T> & Function;
+
 export type InstanceProps<T extends Instance = Instance> = {
   /** An existing instance to render instead of creating a new one. */
-  object?: T;
+  object?: T | PackedScene;
   /** Attaches the element to a named property of the parent instead of adding it as a child. */
   attach?: string;
 };
 
 type ReactProps<P> = React.PropsWithChildren<React.RefAttributes<P>>;
 
-type WidenVT<T> = {
-  [K in keyof T]: T[K] extends ValueTypes ? T[K] | number[] : T[K];
+// Settable, non-method keys. `Pick<T, K>` preserves the readonly modifier, so
+// getter-only (read-only) props, e.g. Node.multiplayer, compare unequal to
+// their `-readonly` copy and drop out; write-only accessors pass through with
+// their setter parameter type.
+type SettableKey<T, K extends keyof T> =
+  Equal<Pick<T, K>, { -readonly [P in K]: T[K] }> extends true
+    ? (T[K] extends Function ? never : K)
+    : never;
+
+// JSX props are settable instance members, typed as the setter accepts them:
+// ValueTypes also accept JSX arrays, and signals (getter `Signal<CB>`, setter
+// `CB | null`) take the callback directly. Maps over `keyof T` (homomorphic)
+// so optional/readonly modifiers survive.
+type Properties<T> = {
+  [K in keyof T as SettableKey<T, K>]:
+    T[K] extends ValueTypes ? T[K] | number[]
+    : T[K] extends Signal<infer CB> ? CB | null
+    : T[K];
 };
 
-type ElementProps<T extends ConstructorRepresentation, P = InstanceType<T>> = Partial<
-  Overwrite<WidenVT<P>, ReactProps<P>>
->;
-
-export type ComponentProps<T extends ConstructorRepresentation> = Mutable<
-  Overwrite<ElementProps<T>, Omit<InstanceProps<InstanceType<T>>, 'object'>>
->;
+export type ComponentProps<T extends GodotConstructor, P extends Instance = InstanceType<T>> =
+  Partial<Properties<P> & ReactProps<P>> & InstanceProps<P>;