✨ react: add useTag

Author: krispya

README.md

@@ -872,6 +872,23 @@ 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.

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

@@ -0,0 +1,57 @@
+import { $internal, type Entity, type TagTrait, 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 useTag(
+	target: Entity | World | undefined | null,
+	tag: TagTrait
+): boolean | undefined {
+	// Get the world from context.
+	const contextWorld = useWorld();
+
+	// Memoize the target entity and a subscriber function.
+	const memo = useMemo(
+		() => (target ? createSubscriptions(target, tag, contextWorld) : undefined),
+		[target, tag, contextWorld]
+	);
+
+	// Initialize the state with whether the entity has the tag.
+	const [value, setValue] = useState<boolean | undefined>(() => {
+		return memo?.entity.has(tag) ?? 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, tag: TagTrait, 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(tag, (e) => {
+				if (e === entity) setValue(true);
+			});
+
+			const onRemoveUnsub = world.onRemove(tag, (e) => {
+				if (e === entity) setValue(false);
+			});
+
+			setValue(entity.has(tag));
+
+			return () => {
+				onAddUnsub();
+				onRemoveUnsub();
+			};
+		},
+	};
+}

packages/react/src/index.ts

@@ -1,6 +1,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 { 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 { useTrait, useTraitEffect, WorldProvider } from '../src';
+import { useTag, useTrait, useTraitEffect, WorldProvider } from '../src';
 
 declare global {
 	var IS_REACT_ACT_ENVIRONMENT: boolean;
@@ -13,6 +13,7 @@ global.IS_REACT_ACT_ENVIRONMENT = true;
 
 let world: World;
 const Position = trait({ x: 0, y: 0 });
+const IsTagged = trait();
 
 describe('useTrait', () => {
 	beforeEach(() => {
@@ -48,6 +49,34 @@ 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;