@bemedev/app-reactjs 1.6.0

package/README.md

@@ -0,0 +1,72 @@
+# @bemedev/app-reactjs
+
+ReactJS state hook binding for `@bemedev/app` state machines.
+
+`@bemedev/app-reactjs` provides a lightweight hook to track and select
+state from a `@bemedev/app` interpreter service inside ReactJS component
+trees.
+
+<br/>
+
+## Installation
+
+```bash
+npm install @bemedev/app-reactjs
+# or
+pnpm add @bemedev/app-reactjs
+```
+
+> **Requirements:** Node.js ≥ 24 · `@bemedev/app` ≥ 1.2.0 · React ≥ 18.0.0
+
+<br/>
+
+## Quick Start
+
+```typescript
+import { interpret } from '@bemedev/app';
+import { useService } from '@bemedev/app-reactjs';
+import { myMachine } from './my.machine';
+
+const service = interpret(myMachine, { context: { count: 0 } });
+service.start();
+
+function MyComponent() {
+  // 1. Select a specific slice of context
+  const count = useService(service, s => s.context.count);
+
+  // 2. Or track the active state value
+  const stateValue = useService(service, s => s.value);
+
+  // 3. Or track the whole state object
+  const state = useService(service);
+
+  return (
+    <div>
+      <p>Count: {count}</p>
+      <p>State: {JSON.stringify(stateValue)}</p>
+    </div>
+  );
+}
+```
+
+<br/>
+
+## API Reference
+
+### `useService(service, selector?)`
+
+Creates a React state hook that updates whenever the interpreter
+transitions, using deep comparison to prevent unnecessary renders.
+
+| Parameter  | Type                    | Description                                                            |
+| ---------- | ----------------------- | ---------------------------------------------------------------------- |
+| `service`  | `Interpreter`           | The `@bemedev/app` interpreter service instance.                       |
+| `selector` | `(state: State) => any` | Optional selector function to slice and track specific parts of state. |
+
+Returns the selected state or slice.
+
+<br/>
+
+## License
+
+MIT

package/lib/index.cjs

@@ -0,0 +1,3 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_useService = require("./useService.cjs");
+exports.useService = require_useService.useService;

package/lib/index.d.ts

@@ -0,0 +1,2 @@
+export * from './useService';
+//# sourceMappingURL=index.d.ts.map

package/lib/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,cAAc,CAAC"}

package/lib/index.js

@@ -0,0 +1,2 @@
+import { useService } from "./useService.js";
+export { useService };

package/lib/useService.cjs

@@ -0,0 +1,25 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+let _bemedev_app_utils = require("@bemedev/app/utils");
+let react = require("react");
+//#region src/useService.ts
+/**
+* A hook that creates a React state from a service with a subscribe function.
+*
+* @param service - The service containing the state and subscribe method.
+* @param selector - A function to select the desired slice of state.
+* @returns The selected state.
+*/
+function useService(service, selector = (s) => s) {
+	const [state, setState] = (0, react.useState)(() => selector(service.state));
+	const sub = service.subscribe((nextState) => {
+		setState(selector(nextState));
+	}, { equals: (first, next) => {
+		return (0, _bemedev_app_utils.deepEqual)(selector(first), selector(next));
+	} });
+	(0, react.useEffect)(() => sub.unsubscribe, [service, selector]);
+	return state;
+}
+//#endregion
+exports.useService = useService;
+
+//# sourceMappingURL=useService.cjs.map

package/lib/useService.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"useService.cjs","names":[],"sources":["../src/useService.ts"],"sourcesContent":["import type {\n  AddSubscriber_F,\n  EventObject,\n  PrimitiveObject,\n  State,\n} from '@bemedev/app/types';\nimport { deepEqual } from '@bemedev/app/utils';\nimport { useEffect, useState } from 'react';\n\n/**\n * A hook that creates a React state from a service with a subscribe function.\n *\n * @param service - The service containing the state and subscribe method.\n * @param selector - A function to select the desired slice of state.\n * @returns The selected state.\n */\nexport function useService<\n  Tc extends PrimitiveObject,\n  Ta extends string,\n  Eo extends EventObject,\n  T = State<Eo, Tc, Ta>,\n>(\n  service: {\n    subscribe: AddSubscriber_F<Tc, Ta, Eo>;\n    state: State<Eo, Tc, Ta>;\n  },\n  selector: (state: State<Eo, Tc, Ta>) => T = (s: State<Eo, Tc, Ta>) =>\n    s as unknown as T,\n): T {\n  const [state, setState] = useState<T>(() => selector(service.state));\n\n  const sub = service.subscribe(\n    nextState => {\n      setState(selector(nextState));\n    },\n    {\n      equals: (first, next) => {\n        const _first = selector(first);\n        const _next = selector(next);\n        return deepEqual(_first, _next);\n      },\n    },\n  );\n\n  useEffect(() => sub.unsubscribe, [service, selector]);\n  return state;\n}\n"],"mappings":";;;;;;;;;;;AAgBA,SAAgB,WAMd,SAIA,YAA6C,MAC3C,GACC;CACH,MAAM,CAAC,OAAO,aAAA,GAAA,MAAA,SAAA,OAA8B,SAAS,QAAQ,KAAK,CAAC;CAEnE,MAAM,MAAM,QAAQ,WAClB,cAAa;EACX,SAAS,SAAS,SAAS,CAAC;CAC9B,GACA,EACE,SAAS,OAAO,SAAS;EAGvB,QAAA,GAAA,mBAAA,UAAA,CAFe,SAAS,KAEF,GADR,SAAS,IACM,CAAC;CAChC,EACF,CACF;CAEA,CAAA,GAAA,MAAA,UAAA,OAAgB,IAAI,aAAa,CAAC,SAAS,QAAQ,CAAC;CACpD,OAAO;AACT"}

package/lib/useService.d.ts

@@ -0,0 +1,13 @@
+import type { AddSubscriber_F, EventObject, PrimitiveObject, State } from '@bemedev/app/types';
+/**
+ * A hook that creates a React state from a service with a subscribe function.
+ *
+ * @param service - The service containing the state and subscribe method.
+ * @param selector - A function to select the desired slice of state.
+ * @returns The selected state.
+ */
+export declare function useService<Tc extends PrimitiveObject, Ta extends string, Eo extends EventObject, T = State<Eo, Tc, Ta>>(service: {
+    subscribe: AddSubscriber_F<Tc, Ta, Eo>;
+    state: State<Eo, Tc, Ta>;
+}, selector?: (state: State<Eo, Tc, Ta>) => T): T;
+//# sourceMappingURL=useService.d.ts.map

package/lib/useService.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useService.d.ts","sourceRoot":"","sources":["../src/useService.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,eAAe,EACf,WAAW,EACX,eAAe,EACf,KAAK,EACN,MAAM,oBAAoB,CAAC;AAI5B;;;;;;GAMG;AACH,wBAAgB,UAAU,CACxB,EAAE,SAAS,eAAe,EAC1B,EAAE,SAAS,MAAM,EACjB,EAAE,SAAS,WAAW,EACtB,CAAC,GAAG,KAAK,CAAC,EAAE,EAAE,EAAE,EAAE,EAAE,CAAC,EAErB,OAAO,EAAE;IACP,SAAS,EAAE,eAAe,CAAC,EAAE,EAAE,EAAE,EAAE,EAAE,CAAC,CAAC;IACvC,KAAK,EAAE,KAAK,CAAC,EAAE,EAAE,EAAE,EAAE,EAAE,CAAC,CAAC;CAC1B,EACD,QAAQ,GAAE,CAAC,KAAK,EAAE,KAAK,CAAC,EAAE,EAAE,EAAE,EAAE,EAAE,CAAC,KAAK,CACrB,GAClB,CAAC,CAkBH"}

package/lib/useService.js

@@ -0,0 +1,24 @@
+import { deepEqual } from "@bemedev/app/utils";
+import { useEffect, useState } from "react";
+//#region src/useService.ts
+/**
+* A hook that creates a React state from a service with a subscribe function.
+*
+* @param service - The service containing the state and subscribe method.
+* @param selector - A function to select the desired slice of state.
+* @returns The selected state.
+*/
+function useService(service, selector = (s) => s) {
+	const [state, setState] = useState(() => selector(service.state));
+	const sub = service.subscribe((nextState) => {
+		setState(selector(nextState));
+	}, { equals: (first, next) => {
+		return deepEqual(selector(first), selector(next));
+	} });
+	useEffect(() => sub.unsubscribe, [service, selector]);
+	return state;
+}
+//#endregion
+export { useService };
+
+//# sourceMappingURL=useService.js.map

package/lib/useService.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"useService.js","names":[],"sources":["../src/useService.ts"],"sourcesContent":["import type {\n  AddSubscriber_F,\n  EventObject,\n  PrimitiveObject,\n  State,\n} from '@bemedev/app/types';\nimport { deepEqual } from '@bemedev/app/utils';\nimport { useEffect, useState } from 'react';\n\n/**\n * A hook that creates a React state from a service with a subscribe function.\n *\n * @param service - The service containing the state and subscribe method.\n * @param selector - A function to select the desired slice of state.\n * @returns The selected state.\n */\nexport function useService<\n  Tc extends PrimitiveObject,\n  Ta extends string,\n  Eo extends EventObject,\n  T = State<Eo, Tc, Ta>,\n>(\n  service: {\n    subscribe: AddSubscriber_F<Tc, Ta, Eo>;\n    state: State<Eo, Tc, Ta>;\n  },\n  selector: (state: State<Eo, Tc, Ta>) => T = (s: State<Eo, Tc, Ta>) =>\n    s as unknown as T,\n): T {\n  const [state, setState] = useState<T>(() => selector(service.state));\n\n  const sub = service.subscribe(\n    nextState => {\n      setState(selector(nextState));\n    },\n    {\n      equals: (first, next) => {\n        const _first = selector(first);\n        const _next = selector(next);\n        return deepEqual(_first, _next);\n      },\n    },\n  );\n\n  useEffect(() => sub.unsubscribe, [service, selector]);\n  return state;\n}\n"],"mappings":";;;;;;;;;;AAgBA,SAAgB,WAMd,SAIA,YAA6C,MAC3C,GACC;CACH,MAAM,CAAC,OAAO,YAAY,eAAkB,SAAS,QAAQ,KAAK,CAAC;CAEnE,MAAM,MAAM,QAAQ,WAClB,cAAa;EACX,SAAS,SAAS,SAAS,CAAC;CAC9B,GACA,EACE,SAAS,OAAO,SAAS;EAGvB,OAAO,UAFQ,SAAS,KAEF,GADR,SAAS,IACM,CAAC;CAChC,EACF,CACF;CAEA,gBAAgB,IAAI,aAAa,CAAC,SAAS,QAAQ,CAAC;CACpD,OAAO;AACT"}

package/package.json

@@ -0,0 +1,133 @@
+{
+  "name": "@bemedev/app-reactjs",
+  "version": "1.6.0",
+  "description": "Middleware between @bemedev/app and reactjs",
+  "keywords": [
+    "app",
+    "bemedev",
+    "middleware",
+    "reactjs",
+    "react",
+    "state-machines"
+  ],
+  "license": "MIT",
+  "author": {
+    "name": "chlbri",
+    "email": "bri_lvi@icloud.com",
+    "url": "https://bemedev.vercel.app"
+  },
+  "maintainers": [
+    {
+      "email": "bri_lvi@icloud.com",
+      "name": "chlbri",
+      "url": "https://bemedev.vercel.app"
+    }
+  ],
+  "contributors": [
+    {
+      "email": "bri_lvi@icloud.com",
+      "name": "chlbri",
+      "url": "https://bemedev.vercel.app"
+    }
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/chlbri/app"
+  },
+  "files": [
+    "lib",
+    "public"
+  ],
+  "type": "module",
+  "main": "lib/index.js",
+  "module": "lib/index.js",
+  "types": "lib/index.d.ts",
+  "devDependencies": {
+    "@bemedev/decompose": "2.2.0",
+    "@bemedev/dev-utils": "^0.8.3",
+    "@bemedev/sleep": "^0.2.2",
+    "@size-limit/file": "^12.1.0",
+    "@testing-library/jest-dom": "^6.9.1",
+    "@testing-library/react": "^16.2.0",
+    "@testing-library/user-event": "^14.6.1",
+    "@types/node": "^26.1.0",
+    "@types/react": "^19.0.0",
+    "@types/react-dom": "^19.0.0",
+    "@vitest/coverage-v8": "^4.1.9",
+    "@vitest/ui": "4.1.9",
+    "glob": "^13.0.6",
+    "globals": "^17.7.0",
+    "husky": "^9.1.7",
+    "jsdom": "^29.1.1",
+    "onchange": "^7.1.0",
+    "oxfmt": "^0.57.0",
+    "oxlint": "^1.72.0",
+    "prettier": "^3.9.4",
+    "pretty-quick": "^4.2.2",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
+    "rolldown": "1.1.4",
+    "rolldown-plugin-dts": "^0.26.0",
+    "size-limit": "^12.1.0",
+    "tslib": "^2.8.1",
+    "tsx": "^4.22.4",
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.9",
+    "@bemedev/app": "^1.6.0",
+    "@bemedev/app-vitest": "^1.6.0"
+  },
+  "peerDependencies": {
+    "@bemedev/decompose": "2.2.0",
+    "react": "^18.0.0 || ^19.0.0",
+    "@bemedev/app": "^1.6.0"
+  },
+  "size-limit": [
+    {
+      "path": "lib/*.js",
+      "limit": "10 KB"
+    },
+    {
+      "path": "lib/*.cjs",
+      "limit": "10 KB"
+    }
+  ],
+  "engines": {
+    "node": ">=24"
+  },
+  "scripts": {
+    "build": "pnpm run rm:lib && pnpm run rolldown",
+    "_ci": "pnpm run lint && pnpm run test",
+    "ci": "CI_START=$(date +%s) && pnpm run config:off && pnpm run lint && pnpm run test && echo \"\n✅ CI takes $(($(date +%s) - CI_START))s\n\"",
+    "ci:admin": "pnpm run rm && pnpm run upgrade && pnpm run ci",
+    "generate": "app-cli generate -c ./src/__tests__",
+    "clean": "pnpm run rm && pnpm run config",
+    "config": "pnpm install",
+    "config:off": "pnpm run config --offline",
+    "fmt": "oxfmt",
+    "fmt:check": "oxfmt --check",
+    "gen:app": "app generate -c ./src/__tests__",
+    "gen:app:watch": "pnpm run gen:app --watch",
+    "_lint": "oxlint",
+    "lint:fix": "oxlint --fix",
+    "lint": "pnpm run fmt && pnpm run lint:fix",
+    "lint:watch": "onchange --await-write-finish 5500 \"**/*\" -- pnpm run lint",
+    "posttest": "pnpm run fmt",
+    "pretest": "pnpm run build && pnpm run size",
+    "prettier": "prettier --write \"src/**/*.{ts,tsx}\"",
+    "p-q": "pretty-quick",
+    "rinit": "pnpm run rm && pnpm run config",
+    "rinit:off": "pnpm run rm && pnpm run config:off",
+    "rimraf": "pnpx rimraf -rf",
+    "rm": "pnpm run rimraf -- node_modules pnpm-lock.yaml",
+    "rm:lib": "pnpm run rimraf -- lib",
+    "rolldown": "rolldown -c",
+    "size": "size-limit",
+    "test": "pnpm run test:coverage",
+    "test:only": "pnpm run test:coverage --no-coverage",
+    "test:coverage": "vitest run",
+    "test:ui": "vitest ui",
+    "test:watch": "vitest",
+    "upgrade": "pnpm upgrade --latest",
+    "upgrade:safe": "pnpm run upgrade"
+  }
+}