✨ react: add useHas (#177)

Author: krispya

README.md

@@ -872,23 +872,6 @@ function App() {
 }
 ```
 
-### `useTag`
-
-Observes an entity, or world, for a given tag and reactively updates when it is added or removed. Returns `true` when the tag is present or `false` when absent. Use this instead of `useTrait` for tag traits (traits with no data).
-
-```js
-const IsActive = trait()
-
-function ActiveIndicator({ entity }) {
-  // Returns true if the entity has the tag, false otherwise
-  const isActive = useTag(entity, IsActive)
-
-  if (!isActive) return null
-
-  return <div>🟢 Active</div>
-}
-```
-
 ### `useTrait`
 
 Observes an entity, or world, for a given trait and reactively updates when it is added, removed or changes value. The returned trait snapshot maybe `undefined` if the trait is no longer on the target. This can be used to conditionally render.
@@ -930,6 +913,40 @@ return (
 )
 ```
 
+### `useTag`
+
+Observes an entity, or world, for a tag and reactively updates when it is added or removed. Returns `true` when the tag is present or `false` when absent. Use this instead of `useTrait` for tags. For tracking the presence of non-tag traits, use `useHas`.
+
+```js
+const IsActive = trait()
+
+function ActiveIndicator({ entity }) {
+  // Returns true if the entity has the tag, false otherwise
+  const isActive = useTag(entity, IsActive)
+
+  if (!isActive) return null
+
+  return <div>🟢 Active</div>
+}
+```
+
+### `useHas`
+
+Observes an entity, or world, for any trait and reactively updates when it is added or removed. Returns `true` when the trait is present or `false` when absent. Unlike `useTrait`, this only tracks presence and not the trait's value.
+
+```js
+const Health = trait({ amount: 100 })
+
+function HealthIndicator({ entity }) {
+  // Returns true if the entity has the trait, false otherwise
+  const hasHealth = useHas(entity, Health)
+
+  if (!hasHealth) return null
+
+  return <div>❤️ Has Health</div>
+}
+```
+
 ### `useTraitEffect`
 
 Subscribes a callback to a trait on an entity. This callback fires as an effect whenever it is added, removed or changes value without rerendering.

packages/react/src/hooks/use-has.ts

@@ -0,0 +1,54 @@
+import { $internal, Trait, type Entity, type World } from '@koota/core';
+import { useEffect, useMemo, useState } from 'react';
+import { isWorld } from '../utils/is-world';
+import { useWorld } from '../world/use-world';
+
+export function useHas(target: Entity | World | undefined | null, trait: Trait): boolean | undefined {
+	// Get the world from context.
+	const contextWorld = useWorld();
+
+	// Memoize the target entity and a subscriber function.
+	const memo = useMemo(
+		() => (target ? createSubscriptions(target, trait, contextWorld) : undefined),
+		[target, trait, contextWorld]
+	);
+
+	// Initialize the state with whether the entity has the tag.
+	const [value, setValue] = useState<boolean | undefined>(() => {
+		return memo?.entity.has(trait) ?? false;
+	});
+
+	// Subscribe to add/remove events for the tag.
+	useEffect(() => {
+		if (!memo) return;
+		const unsubscribe = memo.subscribe(setValue);
+		return () => unsubscribe();
+	}, [memo]);
+
+	return value;
+}
+
+function createSubscriptions(target: Entity | World, trait: Trait, contextWorld: World) {
+	const world = isWorld(target) ? target : contextWorld;
+	const entity = isWorld(target) ? target[$internal].worldEntity : target;
+
+	return {
+		entity,
+		subscribe: (setValue: (value: boolean | undefined) => void) => {
+			const onAddUnsub = world.onAdd(trait, (e) => {
+				if (e === entity) setValue(true);
+			});
+
+			const onRemoveUnsub = world.onRemove(trait, (e) => {
+				if (e === entity) setValue(false);
+			});
+
+			setValue(entity.has(trait));
+
+			return () => {
+				onAddUnsub();
+				onRemoveUnsub();
+			};
+		},
+	};
+}

packages/react/src/index.ts

@@ -2,6 +2,7 @@ export { useActions } from './hooks/use-actions';
 export { useQuery } from './hooks/use-query';
 export { useQueryFirst } from './hooks/use-query-first';
 export { useTag } from './hooks/use-tag';
+export { useHas } from './hooks/use-has';
 export { useTrait } from './hooks/use-trait';
 export { useTraitEffect } from './hooks/use-trait-effect';
 export { useWorld } from './world/use-world';

packages/react/tests/trait.test.tsx

@@ -2,7 +2,7 @@ import { createWorld, trait, universe, type Entity, type TraitRecord, type World
 import { render } from '@testing-library/react';
 import { act, StrictMode, useEffect, useState } from 'react';
 import { beforeEach, describe, expect, it } from 'vitest';
-import { useTag, useTrait, useTraitEffect, WorldProvider } from '../src';
+import { useHas, useTag, useTrait, useTraitEffect, WorldProvider } from '../src';
 
 declare global {
 	var IS_REACT_ACT_ENVIRONMENT: boolean;
@@ -49,34 +49,6 @@ describe('useTrait', () => {
 		expect(position).toEqual({ x: 1, y: 1 });
 	});
 
-	it('reactively returns the trait value for a tag trait', async () => {
-		const entity = world.spawn(IsTagged);
-		let isTagged: boolean | undefined;
-
-		function Test() {
-			isTagged = useTag(entity, IsTagged);
-			return null;
-		}
-
-		await act(async () => {
-			render(
-				<StrictMode>
-					<WorldProvider world={world}>
-						<Test />
-					</WorldProvider>
-				</StrictMode>
-			);
-		});
-
-		expect(isTagged).toBe(true);
-
-		await act(async () => {
-			entity.remove(IsTagged);
-		});
-
-		expect(isTagged).toBe(false);
-	});
-
 	it('reactively works with an entity at effect time', async () => {
 		let entity: Entity | undefined;
 		let position: TraitRecord<typeof Position> | undefined;
@@ -206,6 +178,76 @@ describe('useTrait', () => {
 	});
 });
 
+describe('useTag', () => {
+	beforeEach(() => {
+		universe.reset();
+		world = createWorld();
+	});
+
+	it('reactively returns a boolean for a trait', async () => {
+		const entity = world.spawn(IsTagged);
+		let isTagged: boolean | undefined;
+
+		function Test() {
+			isTagged = useTag(entity, IsTagged);
+			return null;
+		}
+
+		await act(async () => {
+			render(
+				<StrictMode>
+					<WorldProvider world={world}>
+						<Test />
+					</WorldProvider>
+				</StrictMode>
+			);
+		});
+
+		expect(isTagged).toBe(true);
+
+		await act(async () => {
+			entity.remove(IsTagged);
+		});
+
+		expect(isTagged).toBe(false);
+	});
+});
+
+describe('useHas', () => {
+	beforeEach(() => {
+		universe.reset();
+		world = createWorld();
+	});
+
+	it('reactively returns a boolean for any trait', async () => {
+		const entity = world.spawn(Position);
+		let hasPosition: boolean | undefined;
+
+		function Test() {
+			hasPosition = useHas(entity, Position);
+			return null;
+		}
+
+		await act(async () => {
+			render(
+				<StrictMode>
+					<WorldProvider world={world}>
+						<Test />
+					</WorldProvider>
+				</StrictMode>
+			);
+		});
+
+		expect(hasPosition).toBe(true);
+
+		await act(async () => {
+			entity.remove(Position);
+		});
+
+		expect(hasPosition).toBe(false);
+	});
+});
+
 describe('useTraitEffect', () => {
 	beforeEach(() => {
 		universe.reset();