@idosgames/react 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 iDos Games
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,22 @@
+# @idosgames/react
+
+Shared React glue for the iDosGames host shell and its composable modules — the pieces every module
+used to copy-paste, extracted into one package.
+
+- `IDosGamesProvider` / `useIDosGamesClient` — provide and read the one shared SDK client.
+- `StatusProvider` / `useStatus` — a transient status line shared across the app.
+- `useUserState` / `useSdkEvent` — live SDK state hooks (re-render on cache changes / typed events).
+- `createControllerContext<T>(name)` — factory for a module's typed controller context (replaces the
+  hand-written Provider + guarded `useContext` pair each module used to write).
+
+```ts
+import {
+  useIDosGamesClient,
+  useUserState,
+  createControllerContext,
+} from "@idosgames/react";
+```
+
+Built for [`@idosgames/core`](https://www.npmjs.com/package/@idosgames/core) and the module contract
+in [`@idosgames/module-sdk`](https://www.npmjs.com/package/@idosgames/module-sdk). React is a peer
+dependency. See `docs/composable-modules-architecture.md` for the architecture.

package/dist/index.cjs

@@ -0,0 +1 @@
+'use strict';var react=require('react'),jsxRuntime=require('react/jsx-runtime');var u=react.createContext(null);function f({client:e,children:t}){return jsxRuntime.jsx(u.Provider,{value:e,children:t})}function n(){let e=react.useContext(u);if(!e)throw new Error("useIDosGamesClient must be used within <IDosGamesProvider>.");return e}var l=react.createContext(null);function y({children:e}){let[t,o]=react.useState(null),s=react.useCallback((c,p="info")=>{o({text:c,kind:p});},[]),r=react.useCallback(()=>{o(null);},[]),i=react.useMemo(()=>({message:t,setStatus:s,clear:r}),[t,s,r]);return jsxRuntime.jsx(l.Provider,{value:i,children:e})}function D(){let e=react.useContext(l);if(!e)throw new Error("useStatus must be used within <StatusProvider>.");return e}function R(){let e=n(),[,t]=react.useReducer(o=>o+1,0);return react.useEffect(()=>e.on("user:anyUpdated",()=>{t();}),[e]),e.data.user.state}function N(e,t){let o=n();react.useEffect(()=>o.on(e,t),[o,e,t]);}function E(e){let t=react.createContext(null);function o({controller:r,children:i}){return jsxRuntime.jsx(t.Provider,{value:r,children:i})}function s(){let r=react.useContext(t);if(r===null)throw new Error(`use${e} must be used within its <${e}Provider>.`);return r}return [o,s]}exports.IDosGamesProvider=f;exports.StatusProvider=y;exports.createControllerContext=E;exports.useIDosGamesClient=n;exports.useSdkEvent=N;exports.useStatus=D;exports.useUserState=R;

package/dist/index.d.cts

@@ -0,0 +1,44 @@
+import { ReactNode } from 'react';
+import { IDosGamesClient, SdkEvents, UserState } from '@idosgames/core';
+
+declare function IDosGamesProvider({ client, children, }: {
+    client: IDosGamesClient;
+    children: ReactNode;
+}): ReactNode;
+declare function useIDosGamesClient(): IDosGamesClient;
+
+type StatusKind = "info" | "success" | "error";
+interface StatusMessage {
+    text: string;
+    kind: StatusKind;
+}
+interface StatusApi {
+    message: StatusMessage | null;
+    setStatus: (text: string, kind?: StatusKind) => void;
+    clear: () => void;
+}
+declare function StatusProvider({ children, }: {
+    children: ReactNode;
+}): ReactNode;
+declare function useStatus(): StatusApi;
+
+/** Live user state that re-renders the component whenever the SDK cache changes. */
+declare function useUserState(): UserState | null;
+/** Subscribe to a typed SDK event for the lifetime of the component. */
+declare function useSdkEvent<K extends keyof SdkEvents>(event: K, handler: (payload: SdkEvents[K]) => void): void;
+
+interface ControllerProviderProps<T> {
+    controller: T;
+    children: ReactNode;
+}
+/**
+ * Build a typed controller context.
+ *
+ *   const [BoardControllerProvider, useBoardController] =
+ *     createControllerContext<BoardController>("BoardController");
+ *
+ * @param name Used only in the "must be used within its provider" error message.
+ */
+declare function createControllerContext<T>(name: string): readonly [(props: ControllerProviderProps<T>) => ReactNode, () => T];
+
+export { type ControllerProviderProps, IDosGamesProvider, type StatusKind, type StatusMessage, StatusProvider, createControllerContext, useIDosGamesClient, useSdkEvent, useStatus, useUserState };

package/dist/index.d.ts

@@ -0,0 +1,44 @@
+import { ReactNode } from 'react';
+import { IDosGamesClient, SdkEvents, UserState } from '@idosgames/core';
+
+declare function IDosGamesProvider({ client, children, }: {
+    client: IDosGamesClient;
+    children: ReactNode;
+}): ReactNode;
+declare function useIDosGamesClient(): IDosGamesClient;
+
+type StatusKind = "info" | "success" | "error";
+interface StatusMessage {
+    text: string;
+    kind: StatusKind;
+}
+interface StatusApi {
+    message: StatusMessage | null;
+    setStatus: (text: string, kind?: StatusKind) => void;
+    clear: () => void;
+}
+declare function StatusProvider({ children, }: {
+    children: ReactNode;
+}): ReactNode;
+declare function useStatus(): StatusApi;
+
+/** Live user state that re-renders the component whenever the SDK cache changes. */
+declare function useUserState(): UserState | null;
+/** Subscribe to a typed SDK event for the lifetime of the component. */
+declare function useSdkEvent<K extends keyof SdkEvents>(event: K, handler: (payload: SdkEvents[K]) => void): void;
+
+interface ControllerProviderProps<T> {
+    controller: T;
+    children: ReactNode;
+}
+/**
+ * Build a typed controller context.
+ *
+ *   const [BoardControllerProvider, useBoardController] =
+ *     createControllerContext<BoardController>("BoardController");
+ *
+ * @param name Used only in the "must be used within its provider" error message.
+ */
+declare function createControllerContext<T>(name: string): readonly [(props: ControllerProviderProps<T>) => ReactNode, () => T];
+
+export { type ControllerProviderProps, IDosGamesProvider, type StatusKind, type StatusMessage, StatusProvider, createControllerContext, useIDosGamesClient, useSdkEvent, useStatus, useUserState };

package/dist/index.js

@@ -0,0 +1 @@
+import {createContext,useContext,useState,useCallback,useMemo,useReducer,useEffect}from'react';import {jsx}from'react/jsx-runtime';var u=createContext(null);function f({client:e,children:t}){return jsx(u.Provider,{value:e,children:t})}function n(){let e=useContext(u);if(!e)throw new Error("useIDosGamesClient must be used within <IDosGamesProvider>.");return e}var l=createContext(null);function y({children:e}){let[t,o]=useState(null),s=useCallback((c,p="info")=>{o({text:c,kind:p});},[]),r=useCallback(()=>{o(null);},[]),i=useMemo(()=>({message:t,setStatus:s,clear:r}),[t,s,r]);return jsx(l.Provider,{value:i,children:e})}function D(){let e=useContext(l);if(!e)throw new Error("useStatus must be used within <StatusProvider>.");return e}function R(){let e=n(),[,t]=useReducer(o=>o+1,0);return useEffect(()=>e.on("user:anyUpdated",()=>{t();}),[e]),e.data.user.state}function N(e,t){let o=n();useEffect(()=>o.on(e,t),[o,e,t]);}function E(e){let t=createContext(null);function o({controller:r,children:i}){return jsx(t.Provider,{value:r,children:i})}function s(){let r=useContext(t);if(r===null)throw new Error(`use${e} must be used within its <${e}Provider>.`);return r}return [o,s]}export{f as IDosGamesProvider,y as StatusProvider,E as createControllerContext,n as useIDosGamesClient,N as useSdkEvent,D as useStatus,R as useUserState};

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "@idosgames/react",
+  "version": "0.1.0",
+  "description": "Shared React glue for the iDosGames host shell and modules: the client provider, status provider, live-state hooks, and a controller-context factory. Extracted from what every template used to copy-paste.",
+  "type": "module",
+  "license": "MIT",
+  "author": "iDos Games",
+  "homepage": "https://github.com/iDos-Games/iDosGamesSDK_TS#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/iDos-Games/iDosGamesSDK_TS.git",
+    "directory": "packages/react"
+  },
+  "bugs": {
+    "url": "https://github.com/iDos-Games/iDosGamesSDK_TS/issues"
+  },
+  "keywords": [
+    "idosgames",
+    "sdk",
+    "react",
+    "hooks"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "sideEffects": false,
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "typecheck": "tsc --noEmit -p tsconfig.json"
+  },
+  "//": "react is a peer (consumer-provided, never bundled). @idosgames/core is a real range for the same reason as in @idosgames/wallet — a published package must pin the core whose types it references.",
+  "dependencies": {
+    "@idosgames/core": "^0.1.1"
+  },
+  "peerDependencies": {
+    "react": "^18.3.1 || ^19.0.0"
+  },
+  "devDependencies": {
+    "@types/react": "^19.2.17",
+    "react": "^19.2.7"
+  }
+}