feat(hooks): add useRef

Author: remarkablemark

README.md

@@ -163,6 +163,44 @@ If you need nesting and relative positioning, use `Container`:
 
 ## Hooks
 
+### `useRef`
+
+Create a ref for your game object:
+
+```ts
+import { useRef } from 'phaser-jsx';
+
+function MyComponent() {
+  const textRef = useRef<Phaser.GameObjects.Text>();
+  // ...
+}
+```
+
+Pass your ref to the JSX element:
+
+```tsx
+// ...
+return <Text ref={textRef} onPointerDown={handleClick} />;
+```
+
+Access your game object:
+
+```ts
+function handleClick() {
+  textRef.current?.text = 'Clicked';
+}
+```
+
+Alternatively, you can get the game object with a callback ref:
+
+```tsx
+<Text
+  ref={(gameObject) => {
+    gameObject.text = 'Hello, world!';
+  }}
+/>
+```
+
 ### `useScene`
 
 Retrieve the current Scene with the `useScene` hook:

src/hooks/index.ts

@@ -1 +1,2 @@
+export * from './useRef';
 export * from './useScene';

src/hooks/useRef.test.ts

@@ -0,0 +1,16 @@
+import { useRef } from './useRef';
+
+it('defaults initial value to null', () => {
+  expect(useRef()).toEqual({ current: null });
+});
+
+it('creates ref with inital value', () => {
+  expect(useRef(true)).toEqual({ current: true });
+});
+
+it('sets ref current value', () => {
+  const ref = useRef<string>();
+  expect(ref).toEqual({ current: null });
+  ref.current = 'value';
+  expect(ref).toEqual({ current: 'value' });
+});

src/hooks/useRef.ts

@@ -0,0 +1,15 @@
+import type { RefObject } from 'react';
+
+/**
+ * A hook that lets you reference a value that’s not needed for rendering.
+ *
+ * @param initialValue - The value you want the ref object’s current property to be initially. It can be a value of any type. This argument is ignored after the initial render.
+ * @returns - Returns an object with a single property `current` (initially set to the `initialValue` you have passed).
+ */
+export function useRef<Type = null>(
+  initialValue: Type | null = null,
+): RefObject<Type | null> {
+  return {
+    current: initialValue,
+  };
+}

src/index.test.mjs

@@ -10,15 +10,18 @@ import {
   Image,
   jsx,
   render,
+  useRef,
   useScene,
   Video,
 } from '../cjs/index.js';
 
-[createElement, Image, render, Video, useScene].forEach((fun) => {
-  it(`exports ${fun.name}`, () => {
-    assert.strictEqual(typeof fun, 'function');
-  });
-});
+[createElement, createRef, Image, render, Video, useRef, useScene].forEach(
+  (fn) => {
+    it(`exports ${fn.name}`, () => {
+      assert.strictEqual(typeof fn, 'function');
+    });
+  },
+);
 
 it('exports createElement', () => {
   assert.deepEqual(createElement(Image, { x: 42 }), {
@@ -28,8 +31,10 @@ it('exports createElement', () => {
   });
 });
 
-it('exports createRef', () => {
-  assert.deepEqual(createRef(), { current: null });
+[createRef, useRef].forEach((fn) => {
+  it(`exports ${fn.name}`, () => {
+    assert.deepEqual(fn(), { current: null });
+  });
 });
 
 it('exports jsx', () => {

src/index.test.ts

@@ -1,19 +1,27 @@
 import {
   Container,
   createElement,
+  createRef,
   jsx,
   Rectangle,
   render,
   Text,
+  useRef,
   useScene,
 } from '.';
 
-it.each([Container, Rectangle, Text, createElement, render, useScene])(
-  'exports %p',
-  (fun) => {
-    expect(fun).toBeInstanceOf(Function);
-  },
-);
+it.each([
+  Container,
+  Rectangle,
+  Text,
+  createElement,
+  createRef,
+  render,
+  useRef,
+  useScene,
+])('exports %p', (fn) => {
+  expect(fn).toBeInstanceOf(Function);
+});
 
 it('exports jsx', () => {
   expect(jsx).toBe(createElement);

src/index.ts

@@ -1,6 +1,6 @@
 export * from './components';
 export { createElement, jsx } from './element';
-export { useScene } from './hooks';
+export { useRef, useScene } from './hooks';
 export { createRef } from './ref';
 export { render } from './render';
 export type { GameObjectProps, Ref } from './types';

src/ref/createRef.ts

@@ -1,11 +1,13 @@
-import type { Ref } from '../types';
+import type { RefObject } from 'react';
 
 /**
  * Creates a ref object which can contain arbitrary value.
  *
+ * @deprecated Use {@link useRef} instead.
+ *
  * @returns - Creates an object with a single property `current` (initially set to `null`).
  */
-export function createRef<Type>(): Ref<Type> {
+export function createRef<Type>(): RefObject<Type | null> {
   return {
     current: null,
   };

src/render/ref.test.ts

@@ -1,6 +1,6 @@
 import type Phaser from 'phaser';
 
-import { createRef } from '..';
+import { createRef, useRef } from '..';
 import { attachRef } from './ref';
 
 const gameObject = {} as Phaser.GameObjects.GameObject;
@@ -20,6 +20,16 @@ it('attaches ref callback', () => {
 
 it('attaches ref object', () => {
   const ref = createRef<Phaser.GameObjects.GameObject>();
-  expect(attachRef(gameObject, ref));
+  expect(
+    attachRef(gameObject, ref as { current: Phaser.GameObjects.GameObject }),
+  );
+  expect(ref).toEqual({ current: gameObject });
+});
+
+it('attaches ref', () => {
+  const ref = useRef<Phaser.GameObjects.GameObject>();
+  expect(
+    attachRef(gameObject, ref as { current: Phaser.GameObjects.GameObject }),
+  );
   expect(ref).toEqual({ current: gameObject });
 });

src/types/props.ts

@@ -1,12 +1,12 @@
-import type { JSX } from 'react';
+import type { JSX, RefObject } from 'react';
 
-import type { Events, GameObject, RecursivePartial, Ref } from '.';
+import type { Events, GameObject, RecursivePartial } from '.';
 
 type RefCallback<Type> = (gameObject: Type) => void;
 
 interface ObjectProps<Type> extends Partial<Events> {
   children?: JSX.Element | JSX.Element[] | null;
-  ref?: RefCallback<Type> | Ref<Type>;
+  ref?: RefCallback<Type> | RefObject<Type>;
 }
 
 export type GameObjectProps<Type = GameObject> = ObjectProps<Type> &