@pkhex-everywhere/react 0.1.0 → 0.2.1

package/CHANGELOG.md

@@ -1,5 +1,33 @@
 # @pkhex-everywhere/react
 
+## 0.2.1
+
+### Patch Changes
+
+- 92c350e: Document the public types, so editors and the API reference describe each type and field.
+- 4fe8568: Require `@pkhex-everywhere/engine` from the matching minor as a peer, instead of any version.
+- 92c350e: Link the READMEs and npm pages to the new documentation site.
+- Updated dependencies [92c350e]
+- Updated dependencies [55b1b68]
+- Updated dependencies [92c350e]
+  - @pkhex-everywhere/engine@0.2.1
+
+## 0.2.0
+
+### Minor Changes
+
+- fb0df12: Binary inputs take `Uint8Array`, `ArrayBuffer`, `Blob` or `File`, and binary outputs return `Uint8Array`. `game.load(data, fileName?)` takes the name from a `File`. Generated methods and hooks document whether they need a loaded save or an open draft. A missing draft fails with the new `no-draft` error code instead of `not-found`.
+- 938f28c: `createEngine()` starts downloading the runtime as soon as it's created in a browser (`{ lazy: true }` opts out) and reports `engine.status` with file download progress through `engine.onStatusChange`. `wasmHost()` returns one shared runtime per page, so several engines on a page all get changes and events.
+- eab17a2: `react` adds `useEngineStatus()` and `<RequireGame fallback>`, and `useQuery` rewrites `no-save` and `no-draft` messages to name the call and the fix. `engine` no longer exports `createClient`, `affects`, `queryTopics`, `Invoke`, `AssemblyExports` or `EngineExports`, and `engine.call` is gone.
+
+### Patch Changes
+
+- Updated dependencies [fb0df12]
+- Updated dependencies [938f28c]
+- Updated dependencies [38e32c9]
+- Updated dependencies [eab17a2]
+  - @pkhex-everywhere/engine@0.2.0
+
 ## 0.1.0
 
 ### Minor Changes

package/README.md

@@ -2,6 +2,8 @@
 
 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.
 
+**[Documentation](https://arley-space--docs.wawesome.app/docs/guides/react/)** · [API reference](https://arley-space--docs.wawesome.app/docs/reference/react/)
+
 ## Install
 
 ```sh
@@ -10,38 +12,71 @@ npm install @pkhex-everywhere/engine @pkhex-everywhere/react
 
 ## Example
 
+This app opens a save from a file input, lists the party and downloads the edited save:
+
 ```tsx
-import { Suspense } from 'react'
+import { Suspense, type ChangeEvent } from 'react'
 import { createEngine } from '@pkhex-everywhere/engine'
-import { EngineProvider, useParty } from '@pkhex-everywhere/react'
+import { EngineProvider, RequireGame, useEngineStatus, useLoadedGame, useParty } from '@pkhex-everywhere/react'
 
 const engine = createEngine()
 
+function Booting() {
+  const { loaded, total } = useEngineStatus()
+  return <progress value={loaded} max={total || 1} />
+}
+
+function OpenSave() {
+  const { load } = useLoadedGame()
+  const open = (event: ChangeEvent<HTMLInputElement>) => {
+    const file = event.target.files?.[0]
+    if (file) void load(file)
+  }
+  return <input type="file" onChange={open} />
+}
+
 function Party() {
   const { party } = useParty()
   return (
-    <ul>
+    <ul id="party">
       {party.map((pokemon) => (
-        <li key={pokemon.id}>
-          {pokemon.species} Lv. {pokemon.level}
-        </li>
+        <li key={pokemon.id}>{pokemon.species}</li>
       ))}
     </ul>
   )
 }
 
+function Download() {
+  const { export: exportSave } = useLoadedGame()
+  const download = async () => {
+    const { bytes, fileName } = await exportSave()
+    const url = URL.createObjectURL(new Blob([bytes]))
+    const link = document.createElement('a')
+    link.href = url
+    link.download = fileName
+    link.click()
+    setTimeout(() => URL.revokeObjectURL(url))
+  }
+  return <button onClick={download}>Download</button>
+}
+
 export function App() {
   return (
     <EngineProvider engine={engine}>
-      <Suspense fallback="Loading…">
-        <Party />
+      <Suspense fallback={<Booting />}>
+        <RequireGame fallback={<OpenSave />}>
+          <Party />
+          <Download />
+        </RequireGame>
       </Suspense>
     </EngineProvider>
   )
 }
 ```
 
-Load a save with `useLoadedGame().load(base64, fileName)` or `engine.game.load` before rendering hooks that read it.
+The Suspense fallback shows the runtime download with `useEngineStatus()`. `<RequireGame>` renders its fallback until a save is loaded, then its children. If the runtime fails to load, the hooks throw the error to the nearest error boundary.
+
+CI builds this app from the packed packages and runs it.
 
 ## License
 

package/dist/EngineProvider.d.ts

@@ -6,11 +6,15 @@ interface EngineContextValue {
     cache: QueryCache;
 }
 interface EngineProviderProps {
+    /** The engine the hooks below read from, usually created once with `createEngine()`. */
     engine: Engine;
+    /** Called with `EngineError` rejections nothing else handled, for example to show a toast. */
     onUnhandledError?: (error: EngineError) => void;
     children?: ReactNode;
 }
+/** Gives the hooks below it an engine and a query cache that refetches when a command changes the save. */
 export declare function EngineProvider({ engine, onUnhandledError, children }: EngineProviderProps): import("react").JSX.Element;
 export declare function useEngineContext(): EngineContextValue;
+/** The engine from the nearest `EngineProvider`, for any call the hooks don't cover. */
 export declare function useEngine(): Engine;
 export {};

package/dist/RequireGame.d.ts

@@ -0,0 +1,6 @@
+import type { ReactNode } from 'react';
+/** Renders `fallback` until a save is loaded, then `children`. Wrap hooks that need a save in it. */
+export declare function RequireGame({ fallback, children }: {
+    fallback?: ReactNode;
+    children?: ReactNode;
+}): ReactNode;

package/dist/generated/hooks.d.ts

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

package/dist/index.d.ts

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

package/dist/index.js

@@ -1,5 +1,6 @@
 import { createContext, useContext, useEffect, useMemo, useRef, useState, useSyncExternalStore } from "react";
-import { EngineError, affects, queryTopics } from "@pkhex-everywhere/engine";
+import { EngineError } from "@pkhex-everywhere/engine";
+import { affects, call, queryTopics } from "@pkhex-everywhere/engine/internal";
 import { jsx } from "react/jsx-runtime";
 //#region src/cache.ts
 var QueryCache = class {
@@ -55,6 +56,7 @@ var QueryCache = class {
 //#region src/EngineProvider.tsx
 var EngineContext = createContext(null);
 var reported = /* @__PURE__ */ new WeakSet();
+/** Gives the hooks below it an engine and a query cache that refetches when a command changes the save. */
 function EngineProvider({ engine, onUnhandledError, children }) {
 	const [cache] = useState(() => new QueryCache());
 	useEffect(() => engine.subscribe(["*"], cache.invalidate), [engine, cache]);
@@ -86,38 +88,70 @@ function useEngineContext() {
 	if (!context) throw new Error("Engine hooks must be used inside an EngineProvider.");
 	return context;
 }
+/** The engine from the nearest `EngineProvider`, for any call the hooks don't cover. */
 function useEngine() {
 	return useEngineContext().engine;
 }
 //#endregion
 //#region src/useQuery.ts
-function useQuery(call, ...args) {
+var fixes = {
+	"no-save": (name) => `${name} needs a loaded save. Load one with useLoadedGame().load(file) and wrap the component in <RequireGame>.`,
+	"no-draft": (name) => `${name} needs an open draft. Open one with usePokemon(at).edit() or .clone() first.`
+};
+function explain(name, error) {
+	if (!(error instanceof EngineError)) return error;
+	const fix = fixes[error.code];
+	return fix ? new EngineError(error.code, fix(name)) : error;
+}
+/**
+* Runs a query by name and suspends until it resolves. Refetches when a command changes a topic the query reads,
+* and keeps showing the previous value while it does.
+*/
+function useQuery(name, ...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));
+	const key = JSON.stringify([name, args]);
+	const load = () => call(engine, name, args).catch((error) => {
+		throw explain(name, error);
+	});
+	const entry = useSyncExternalStore(cache.subscribe, () => cache.peek(key)) ?? cache.get(key, queryTopics[name], load);
 	if (entry.status === "pending") throw entry.promise;
 	if (entry.status === "error") throw entry.error;
 	return entry.value;
 }
 //#endregion
+//#region src/useEngineStatus.ts
+/** The engine's boot status. Re-renders as the runtime downloads. Works without a save. */
+function useEngineStatus() {
+	const engine = useEngine();
+	const read = () => engine.status;
+	return useSyncExternalStore(engine.onStatusChange, read, read);
+}
+//#endregion
 //#region src/generated/hooks.ts
+/** Requires a loaded save; throws `no-save` otherwise. Wrap in `<RequireGame>`. */
 function useBox() {
 	const engine = useEngine();
 	return {
 		box: useQuery("box.get"),
 		...useMemo(() => ({
+			/** Requires a loaded save; throws `no-save` otherwise. Wrap in `<RequireGame>`. */
 			addEncounter: (index) => engine.box.addEncounter(index),
+			/** Requires a loaded save; throws `no-save` otherwise. Wrap in `<RequireGame>`. */
 			addFromFile: (bytes) => engine.box.addFromFile(bytes)
 		}), [engine])
 	};
 }
+/** Requires a loaded save; throws `no-save` otherwise. Wrap in `<RequireGame>`. */
 function useEvents() {
 	const engine = useEngine();
 	return {
 		events: useQuery("events.get"),
 		...useMemo(() => ({
+			/** Requires a loaded save; throws `no-save` otherwise. Wrap in `<RequireGame>`. */
 			giveTickets: (includeOldSeaMap) => engine.events.giveTickets(includeOldSeaMap),
+			/** Requires a loaded save; throws `no-save` otherwise. Wrap in `<RequireGame>`. */
 			setFlag: (index, value) => engine.events.setFlag(index, value),
+			/** Requires a loaded save; throws `no-save` otherwise. Wrap in `<RequireGame>`. */
 			setWork: (index, value) => engine.events.setWork(index, value)
 		}), [engine])
 	};
@@ -128,6 +162,7 @@ function useLoadedGame() {
 		game: useQuery("game.get"),
 		...useMemo(() => ({
 			close: () => engine.game.close(),
+			/** Requires a loaded save; throws `no-save` otherwise. Wrap in `<RequireGame>`. */
 			export: () => engine.game.export(),
 			file: () => engine.game.file(),
 			load: (data, fileName) => engine.game.load(data, fileName),
@@ -135,16 +170,21 @@ function useLoadedGame() {
 		}), [engine])
 	};
 }
+/** Requires a loaded save; throws `no-save` otherwise. Wrap in `<RequireGame>`. */
 function useInventory() {
 	const engine = useEngine();
 	return {
 		inventory: useQuery("inventory.get"),
-		...useMemo(() => ({ setItem: (at, count) => engine.inventory.setItem(at, count) }), [engine])
+		...useMemo(() => ({ 
+		/** Requires a loaded save; throws `no-save` otherwise. Wrap in `<RequireGame>`. */
+setItem: (at, count) => engine.inventory.setItem(at, count) }), [engine])
 	};
 }
+/** Requires a loaded save; throws `no-save` otherwise. Wrap in `<RequireGame>`. */
 function useParty() {
 	return { party: useQuery("party.get") };
 }
+/** Requires a loaded save; throws `no-save` otherwise. Wrap in `<RequireGame>`. */
 function usePokemon(at) {
 	const engine = useEngine();
 	const pokemon = useQuery("pokemon.get", at);
@@ -152,29 +192,48 @@ function usePokemon(at) {
 	return {
 		pokemon,
 		...useMemo(() => ({
+			/** Requires a loaded save and an open draft; throws `no-save` or `no-draft` otherwise. Wrap in `<RequireGame>`. */
 			addToBox: () => engine.pokemon.addToBox(),
+			/** Requires a loaded save; throws `no-save` otherwise. Wrap in `<RequireGame>`. */
 			clone: () => engine.pokemon.clone(at),
+			/** Requires a loaded save and an open draft; throws `no-save` or `no-draft` otherwise. Wrap in `<RequireGame>`. */
 			commit: () => engine.pokemon.commit(),
+			/** Requires a loaded save; throws `no-save` otherwise. Wrap in `<RequireGame>`. */
 			edit: () => engine.pokemon.edit(at),
+			/** Requires a loaded save; throws `no-save` otherwise. Wrap in `<RequireGame>`. */
 			setLevel: (level) => engine.pokemon.setLevel(at, level),
+			/** Requires a loaded save; throws `no-save` otherwise. Wrap in `<RequireGame>`. */
 			update: (patch) => engine.pokemon.update(at, patch)
 		}), [engine, key])
 	};
 }
+/** Requires a loaded save; throws `no-save` otherwise. Wrap in `<RequireGame>`. */
 function useTrainer() {
 	const engine = useEngine();
 	return {
 		trainer: useQuery("trainer.get"),
 		...useMemo(() => ({
+			/** Requires a loaded save; throws `no-save` otherwise. Wrap in `<RequireGame>`. */
 			setBattlePoints: (value) => engine.trainer.setBattlePoints(value),
+			/** Requires a loaded save; throws `no-save` otherwise. Wrap in `<RequireGame>`. */
 			setGender: (gender) => engine.trainer.setGender(gender),
+			/** Requires a loaded save; throws `no-save` otherwise. Wrap in `<RequireGame>`. */
 			setMoney: (amount) => engine.trainer.setMoney(amount),
+			/** Requires a loaded save; throws `no-save` otherwise. Wrap in `<RequireGame>`. */
 			setName: (name) => engine.trainer.setName(name)
 		}), [engine])
 	};
 }
 //#endregion
+//#region src/RequireGame.tsx
+/** Renders `fallback` until a save is loaded, then `children`. Wrap hooks that need a save in it. */
+function RequireGame({ fallback = null, children }) {
+	const { game } = useLoadedGame();
+	return game ? children : fallback;
+}
+//#endregion
 //#region src/usePokemonDetails.ts
+/** A Pokémon's editable fields and an `update` that applies a patch to it. Requires a loaded save. */
 function usePokemonDetails(at) {
 	const engine = useEngine();
 	const details = useQuery("pokemon.details", at);
@@ -185,4 +244,4 @@ function usePokemonDetails(at) {
 	};
 }
 //#endregion
-export { EngineProvider, useBox, useEngine, useEvents, useInventory, useLoadedGame, useParty, usePokemon, usePokemonDetails, useQuery, useTrainer };
+export { EngineProvider, RequireGame, useBox, useEngine, useEngineStatus, useEvents, useInventory, useLoadedGame, useParty, usePokemon, usePokemonDetails, useQuery, useTrainer };

package/dist/useEngineStatus.d.ts

@@ -0,0 +1,3 @@
+import type { EngineStatus } from '@pkhex-everywhere/engine';
+/** The engine's boot status. Re-renders as the runtime downloads. Works without a save. */
+export declare function useEngineStatus(): EngineStatus;

package/dist/usePokemonDetails.d.ts

@@ -1,4 +1,5 @@
 import type { PokemonHandle, PokemonPatch } from '@pkhex-everywhere/engine';
+/** A Pokémon's editable fields and an `update` that applies a patch to it. Requires a loaded save. */
 export declare function usePokemonDetails(at: PokemonHandle): {
     details: import("@pkhex-everywhere/engine").EditablePokemon;
     update: (patch: PokemonPatch) => Promise<void>;

package/dist/useQuery.d.ts

@@ -1,7 +1,13 @@
 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>>;
+/** The arguments of the call `Name`, such as `[at: PokemonHandle]` for `pokemon.details`. */
 export type CallArgs<Name extends CallName> = Parameters<CallFunction<Name>>;
+/** What the call `Name` resolves to. */
 export type CallResult<Name extends CallName> = Awaited<ReturnType<CallFunction<Name>>>;
-export declare function useQuery<Name extends QueryName>(call: Name, ...args: CallArgs<Name>): CallResult<Name>;
+/**
+ * Runs a query by name and suspends until it resolves. Refetches when a command changes a topic the query reads,
+ * and keeps showing the previous value while it does.
+ */
+export declare function useQuery<Name extends QueryName>(name: Name, ...args: CallArgs<Name>): CallResult<Name>;
 export {};

package/package.json

@@ -1,8 +1,9 @@
 {
   "name": "@pkhex-everywhere/react",
-  "version": "0.1.0",
+  "version": "0.2.1",
   "description": "React hooks for @pkhex-everywhere/engine.",
   "license": "GPL-3.0-or-later",
+  "homepage": "https://arley-space--docs.wawesome.app/docs/",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/arleypadua/PKHeX.Everywhere.git",
@@ -29,7 +30,7 @@
     "test": "vitest run"
   },
   "peerDependencies": {
-    "@pkhex-everywhere/engine": "*",
+    "@pkhex-everywhere/engine": "^0.2.1",
     "react": "^19.0.0"
   },
   "devDependencies": {