@pkhex-everywhere/react 0.2.0 → 0.2.1

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # @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

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
@@ -76,17 +78,6 @@ The Suspense fallback shows the runtime download with `useEngineStatus()`. `<Req
 
 CI builds this app from the packed packages and runs it.
 
-## Hooks that need a save
-
-Most hooks throw `no-save` when no save is loaded, so render them inside `<RequireGame>`. Hover a hook to see what it needs. A hook that runs without a save fails with a message naming the call and the fix, and the error's `code` stays `no-save`. The same goes for `no-draft`.
-
-These work without a save:
-
-- `useEngineStatus()`
-- `useEngine()`
-- `useLoadedGame()`, where `game` is `null` until a save is loaded
-- `useQuery` with `game.get`, `game.version`, `game.blankVersions`, `catalog.names` and the `plugins.*` queries
-
 ## License
 
 GPL-3.0-or-later.

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

@@ -1,4 +1,5 @@
 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;

package/dist/index.js

@@ -56,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]);
@@ -87,6 +88,7 @@ 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;
 }
@@ -101,6 +103,10 @@ function explain(name, 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([name, args]);
@@ -114,6 +120,7 @@ function useQuery(name, ...args) {
 }
 //#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;
@@ -219,12 +226,14 @@ function useTrainer() {
 }
 //#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);

package/dist/useEngineStatus.d.ts

@@ -1,2 +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>>>;
+/**
+ * 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.2.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": {