@pkhex-everywhere/react 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,12 @@
+# @pkhex-everywhere/react
+
+## 0.1.0
+
+### Minor Changes
+
+- c1bc8fa: First release.
+
+### Patch Changes
+
+- Updated dependencies [c1bc8fa]
+  - @pkhex-everywhere/engine@0.1.0

package/README.md

@@ -0,0 +1,48 @@
+# @pkhex-everywhere/react
+
+React hooks for [`@pkhex-everywhere/engine`](https://www.npmjs.com/package/@pkhex-everywhere/engine). Hooks suspend until their data arrives and refetch when a command changes it.
+
+## Install
+
+```sh
+npm install @pkhex-everywhere/engine @pkhex-everywhere/react
+```
+
+## Example
+
+```tsx
+import { Suspense } from 'react'
+import { createEngine } from '@pkhex-everywhere/engine'
+import { EngineProvider, useParty } from '@pkhex-everywhere/react'
+
+const engine = createEngine()
+
+function Party() {
+  const { party } = useParty()
+  return (
+    <ul>
+      {party.map((pokemon) => (
+        <li key={pokemon.id}>
+          {pokemon.species} Lv. {pokemon.level}
+        </li>
+      ))}
+    </ul>
+  )
+}
+
+export function App() {
+  return (
+    <EngineProvider engine={engine}>
+      <Suspense fallback="Loading…">
+        <Party />
+      </Suspense>
+    </EngineProvider>
+  )
+}
+```
+
+Load a save with `useLoadedGame().load(base64, fileName)` or `engine.game.load` before rendering hooks that read it.
+
+## License
+
+GPL-3.0-or-later.

package/dist/EngineProvider.d.ts

@@ -0,0 +1,16 @@
+import { type ReactNode } from 'react';
+import { EngineError, type Engine } from '@pkhex-everywhere/engine';
+import { QueryCache } from './cache';
+interface EngineContextValue {
+    engine: Engine;
+    cache: QueryCache;
+}
+interface EngineProviderProps {
+    engine: Engine;
+    onUnhandledError?: (error: EngineError) => void;
+    children?: ReactNode;
+}
+export declare function EngineProvider({ engine, onUnhandledError, children }: EngineProviderProps): import("react").JSX.Element;
+export declare function useEngineContext(): EngineContextValue;
+export declare function useEngine(): Engine;
+export {};

package/dist/cache.d.ts

@@ -0,0 +1,21 @@
+type Entry = {
+    status: 'pending';
+    promise: Promise<void>;
+} | {
+    status: 'success';
+    value: unknown;
+} | {
+    status: 'error';
+    error: unknown;
+};
+export declare class QueryCache {
+    private readonly queries;
+    private readonly listeners;
+    get(key: string, topics: readonly string[], fetch: () => Promise<unknown>): Entry;
+    peek(key: string): Entry | undefined;
+    subscribe: (listener: () => void) => () => undefined;
+    invalidate: (changed: readonly string[]) => void;
+    private load;
+    private settle;
+}
+export {};

package/dist/generated/hooks.d.ts

@@ -0,0 +1,43 @@
+import type { Base64, ItemHandle, PokemonHandle, PokemonPatch, TrainerGender } from '@pkhex-everywhere/engine';
+export declare function useBox(): {
+    addEncounter: (index: number) => Promise<import("@pkhex-everywhere/engine").AddedPokemon>;
+    addFromFile: (bytes: Base64) => Promise<import("@pkhex-everywhere/engine").AddedPokemon>;
+    box: import("@pkhex-everywhere/engine").PokemonSummary[];
+};
+export declare function useEvents(): {
+    giveTickets: (includeOldSeaMap: boolean) => Promise<string[]>;
+    setFlag: (index: number, value: boolean) => Promise<void>;
+    setWork: (index: number, value: number) => Promise<void>;
+    events: import("@pkhex-everywhere/engine").SaveEvents | null;
+};
+export declare function useLoadedGame(): {
+    close: () => Promise<void>;
+    export: () => Promise<import("@pkhex-everywhere/engine").ExportedSave>;
+    file: () => Promise<import("@pkhex-everywhere/engine").LoadedSave | null>;
+    load: (data: Base64, fileName: string) => Promise<void>;
+    loadBlank: (version: number) => Promise<void>;
+    game: import("@pkhex-everywhere/engine").SaveSummary | null;
+};
+export declare function useInventory(): {
+    setItem: (at: ItemHandle, count: number) => Promise<void>;
+    inventory: import("@pkhex-everywhere/engine").Pouch[];
+};
+export declare function useParty(): {
+    party: import("@pkhex-everywhere/engine").PokemonSummary[];
+};
+export declare function usePokemon(at: PokemonHandle): {
+    addToBox: () => Promise<import("@pkhex-everywhere/engine").AddedPokemon>;
+    clone: () => Promise<void>;
+    commit: () => Promise<import("@pkhex-everywhere/engine").PokemonId>;
+    edit: () => Promise<void>;
+    setLevel: (level: number) => Promise<void>;
+    update: (patch: PokemonPatch) => Promise<void>;
+    pokemon: import("@pkhex-everywhere/engine").PokemonSummary;
+};
+export declare function useTrainer(): {
+    setBattlePoints: (value: number) => Promise<void>;
+    setGender: (gender: TrainerGender) => Promise<void>;
+    setMoney: (amount: number) => Promise<void>;
+    setName: (name: string) => Promise<void>;
+    trainer: import("@pkhex-everywhere/engine").TrainerCard;
+};

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export { EngineProvider, useEngine } from './EngineProvider';
+export { useQuery, type CallArgs, type CallResult } from './useQuery';
+export * from './generated/hooks';
+export { usePokemonDetails } from './usePokemonDetails';

package/dist/index.js

@@ -0,0 +1,188 @@
+import { createContext, useContext, useEffect, useMemo, useRef, useState, useSyncExternalStore } from "react";
+import { EngineError, affects, queryTopics } from "@pkhex-everywhere/engine";
+import { jsx } from "react/jsx-runtime";
+//#region src/cache.ts
+var QueryCache = class {
+	queries = /* @__PURE__ */ new Map();
+	listeners = /* @__PURE__ */ new Set();
+	get(key, topics, fetch) {
+		const existing = this.queries.get(key);
+		if (existing) return existing.entry;
+		const query = {
+			topics,
+			fetch,
+			generation: 0
+		};
+		this.queries.set(key, query);
+		this.load(key, query);
+		return query.entry;
+	}
+	peek(key) {
+		return this.queries.get(key)?.entry;
+	}
+	subscribe = (listener) => {
+		this.listeners.add(listener);
+		return () => void this.listeners.delete(listener);
+	};
+	invalidate = (changed) => {
+		for (const [key, query] of this.queries) {
+			if (!affects(changed, query.topics)) continue;
+			if (query.entry.status === "error") this.queries.delete(key);
+			else this.load(key, query);
+		}
+	};
+	load(key, query) {
+		const generation = ++query.generation;
+		const promise = query.fetch().then((value) => this.settle(key, query, generation, {
+			status: "success",
+			value
+		}), (error) => this.settle(key, query, generation, {
+			status: "error",
+			error
+		}));
+		if (query.entry?.status !== "success") query.entry = {
+			status: "pending",
+			promise
+		};
+	}
+	settle(key, query, generation, entry) {
+		if (query.generation !== generation || this.queries.get(key) !== query) return;
+		query.entry = entry;
+		this.listeners.forEach((listener) => listener());
+	}
+};
+//#endregion
+//#region src/EngineProvider.tsx
+var EngineContext = createContext(null);
+var reported = /* @__PURE__ */ new WeakSet();
+function EngineProvider({ engine, onUnhandledError, children }) {
+	const [cache] = useState(() => new QueryCache());
+	useEffect(() => engine.subscribe(["*"], cache.invalidate), [engine, cache]);
+	const report = useRef(onUnhandledError);
+	report.current = onUnhandledError;
+	const reports = onUnhandledError !== void 0;
+	useEffect(() => {
+		if (!reports) return;
+		const handle = (event) => {
+			const { reason } = event;
+			if (!(reason instanceof EngineError) || reported.has(reason)) return;
+			reported.add(reason);
+			event.preventDefault();
+			report.current?.(reason);
+		};
+		window.addEventListener("unhandledrejection", handle);
+		return () => window.removeEventListener("unhandledrejection", handle);
+	}, [reports]);
+	return /* @__PURE__ */ jsx(EngineContext, {
+		value: {
+			engine,
+			cache
+		},
+		children
+	});
+}
+function useEngineContext() {
+	const context = useContext(EngineContext);
+	if (!context) throw new Error("Engine hooks must be used inside an EngineProvider.");
+	return context;
+}
+function useEngine() {
+	return useEngineContext().engine;
+}
+//#endregion
+//#region src/useQuery.ts
+function useQuery(call, ...args) {
+	const { engine, cache } = useEngineContext();
+	const key = JSON.stringify([call, args]);
+	const entry = useSyncExternalStore(cache.subscribe, () => cache.peek(key)) ?? cache.get(key, queryTopics[call], () => engine.call(call, args));
+	if (entry.status === "pending") throw entry.promise;
+	if (entry.status === "error") throw entry.error;
+	return entry.value;
+}
+//#endregion
+//#region src/generated/hooks.ts
+function useBox() {
+	const engine = useEngine();
+	return {
+		box: useQuery("box.get"),
+		...useMemo(() => ({
+			addEncounter: (index) => engine.box.addEncounter(index),
+			addFromFile: (bytes) => engine.box.addFromFile(bytes)
+		}), [engine])
+	};
+}
+function useEvents() {
+	const engine = useEngine();
+	return {
+		events: useQuery("events.get"),
+		...useMemo(() => ({
+			giveTickets: (includeOldSeaMap) => engine.events.giveTickets(includeOldSeaMap),
+			setFlag: (index, value) => engine.events.setFlag(index, value),
+			setWork: (index, value) => engine.events.setWork(index, value)
+		}), [engine])
+	};
+}
+function useLoadedGame() {
+	const engine = useEngine();
+	return {
+		game: useQuery("game.get"),
+		...useMemo(() => ({
+			close: () => engine.game.close(),
+			export: () => engine.game.export(),
+			file: () => engine.game.file(),
+			load: (data, fileName) => engine.game.load(data, fileName),
+			loadBlank: (version) => engine.game.loadBlank(version)
+		}), [engine])
+	};
+}
+function useInventory() {
+	const engine = useEngine();
+	return {
+		inventory: useQuery("inventory.get"),
+		...useMemo(() => ({ setItem: (at, count) => engine.inventory.setItem(at, count) }), [engine])
+	};
+}
+function useParty() {
+	return { party: useQuery("party.get") };
+}
+function usePokemon(at) {
+	const engine = useEngine();
+	const pokemon = useQuery("pokemon.get", at);
+	const key = JSON.stringify(at);
+	return {
+		pokemon,
+		...useMemo(() => ({
+			addToBox: () => engine.pokemon.addToBox(),
+			clone: () => engine.pokemon.clone(at),
+			commit: () => engine.pokemon.commit(),
+			edit: () => engine.pokemon.edit(at),
+			setLevel: (level) => engine.pokemon.setLevel(at, level),
+			update: (patch) => engine.pokemon.update(at, patch)
+		}), [engine, key])
+	};
+}
+function useTrainer() {
+	const engine = useEngine();
+	return {
+		trainer: useQuery("trainer.get"),
+		...useMemo(() => ({
+			setBattlePoints: (value) => engine.trainer.setBattlePoints(value),
+			setGender: (gender) => engine.trainer.setGender(gender),
+			setMoney: (amount) => engine.trainer.setMoney(amount),
+			setName: (name) => engine.trainer.setName(name)
+		}), [engine])
+	};
+}
+//#endregion
+//#region src/usePokemonDetails.ts
+function usePokemonDetails(at) {
+	const engine = useEngine();
+	const details = useQuery("pokemon.details", at);
+	const key = JSON.stringify(at);
+	return {
+		details,
+		update: useMemo(() => (patch) => engine.pokemon.update(at, patch), [engine, key])
+	};
+}
+//#endregion
+export { EngineProvider, useBox, useEngine, useEvents, useInventory, useLoadedGame, useParty, usePokemon, usePokemonDetails, useQuery, useTrainer };

package/dist/usePokemonDetails.d.ts

@@ -0,0 +1,5 @@
+import type { PokemonHandle, PokemonPatch } from '@pkhex-everywhere/engine';
+export declare function usePokemonDetails(at: PokemonHandle): {
+    details: import("@pkhex-everywhere/engine").EditablePokemon;
+    update: (patch: PokemonPatch) => Promise<void>;
+};

package/dist/useQuery.d.ts

@@ -0,0 +1,7 @@
+import { type CallName, type EngineClient, type QueryName } from '@pkhex-everywhere/engine';
+type Lookup<T, Path extends string> = Path extends `${infer Head}.${infer Rest}` ? Head extends keyof T ? Lookup<T[Head], Rest> : never : Path extends keyof T ? T[Path] : never;
+type CallFunction<Name extends CallName> = Extract<Lookup<EngineClient, Name>, (...args: never[]) => Promise<unknown>>;
+export type CallArgs<Name extends CallName> = Parameters<CallFunction<Name>>;
+export type CallResult<Name extends CallName> = Awaited<ReturnType<CallFunction<Name>>>;
+export declare function useQuery<Name extends QueryName>(call: Name, ...args: CallArgs<Name>): CallResult<Name>;
+export {};

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@pkhex-everywhere/react",
+  "version": "0.1.0",
+  "description": "React hooks for @pkhex-everywhere/engine.",
+  "license": "GPL-3.0-or-later",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/arleypadua/PKHeX.Everywhere.git",
+    "directory": "src/PKHeX.Everywhere.Engine.Sdk/packages/react"
+  },
+  "type": "module",
+  "exports": {
+    ".": {
+      "source": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "CHANGELOG.md"
+  ],
+  "publishConfig": {
+    "provenance": true
+  },
+  "scripts": {
+    "build": "vite build && tsc -p tsconfig.build.json",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run"
+  },
+  "peerDependencies": {
+    "@pkhex-everywhere/engine": "*",
+    "react": "^19.0.0"
+  },
+  "devDependencies": {
+    "@testing-library/react": "^16.3.3",
+    "@types/react": "^19.3.0",
+    "@types/react-dom": "^19.3.0",
+    "jsdom": "^30.1.1",
+    "react": "^19.3.0",
+    "react-dom": "^19.3.0",
+    "typescript": "~7.0.2",
+    "vite": "^8.3.1",
+    "vitest": "^5.0.3"
+  }
+}