intentx-react 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Delpi.Kye
+
+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,357 @@
+# 🧩 intentx-react
+
+[![NPM](https://img.shields.io/npm/v/intentx-react.svg)](https://www.npmjs.com/package/intentx-react) ![Downloads](https://img.shields.io/npm/dt/intentx-react.svg)
+
+<a href="https://codesandbox.io/p/sandbox/7tgzxw" target="_blank">LIVE EXAMPLE</a>
+
+Official React adapter for **intentx-runtime**.   
+Designed for deterministic orchestration across UI, backend, and workers.
+
+> Intent-first business logic. React is just a view layer.
+
+---
+
+## 🧠 What is intentx?
+
+`intentx-runtime` is a deterministic, intent-driven business logic runtime.
+
+`intentx-react` is a thin React binding on top of that runtime.
+
+You can use the runtime:
+
+- In React
+- In Node.js
+- In workers
+- In tests
+- Without any UI
+
+React is optional.
+
+---
+
+## 🏗 Mental Model
+
+```
+UI / HTTP / Queue / Cron
+        ↓
+     emit(intent)
+        ↓
+   middleware / effects
+        ↓
+   intent handlers
+        ↓
+     mutate state
+        ↓
+ computed (derived state)
+```
+
+Core principle:
+
+> Intent is the only mutation entry point.
+> The runtime owns behavior. UI only triggers intent.
+
+---
+
+## 📦 Installation
+
+```bash
+npm install intentx-react
+```
+
+---
+
+## 🚀 Quick Start (Headless Runtime)
+
+Even though this is the React package, the runtime is fully usable without React.
+
+```ts
+import { createLogic } from "intentx-react"
+
+const counterLogic = createLogic({
+  state: { count: 0 },
+
+  intents: bus => {
+    bus.on("inc", ({ setState }) => {
+      setState(s => { s.count++ })
+    })
+
+    bus.on<number>("add", ({ payload, setState }) => {
+      setState(s => { s.count += payload })
+    })
+  },
+
+  computed: {
+    double: ({ state }) => state.count * 2
+  }
+})
+
+async function main() {
+  const runtime = counterLogic.create()
+
+  await runtime.emit("inc")
+  await runtime.emit("add", 5)
+
+  console.log(runtime.state.double)
+}
+
+main()
+```
+
+✔ Deterministic  
+✔ Fully testable  
+✔ No React dependency  
+
+---
+
+## ⚛️ React Integration
+
+React integration is a thin adapter over the runtime.
+
+You have two options:
+
+- `withLogic` (recommended)
+- `useLogic`
+
+---
+
+#### 🧩 Option 1 — withLogic (Recommended)
+
+Keeps your view pure.
+
+```tsx
+import { withLogic } from "intentx-react"
+import { counterLogic } from "./counter.logic"
+
+const CounterView = ({ state, emit }) => {
+  return (
+    <div>
+      <h2>{state.count}</h2>
+      <button onClick={() => emit("inc")}>+</button>
+    </div>
+  )
+}
+
+export const CounterPage =
+  withLogic(counterLogic, CounterView)
+```
+
+Why recommended?
+
+- No hooks inside the view
+- View is easily testable
+- Clear separation of concerns
+- Logic reusable outside React
+
+---
+
+#### 🪝 Option 2 — useLogic
+
+```tsx
+import { useLogic } from "intentx-react"
+import { counterLogic } from "./counter.logic"
+
+export function Counter() {
+  const { state, emit } = useLogic(counterLogic)
+
+  return (
+    <div>
+      <h2>{state.count}</h2>
+      <button onClick={() => emit("inc")}>+</button>
+    </div>
+  )
+}
+```
+
+---
+
+## 🧠 Computed State
+
+```ts
+computed: {
+  double: ({ state }) => state.count * 2,
+  triple: ({ state }) => state.count * 3,
+}
+```
+
+Computed values:
+
+- Are cached
+- Track dependencies automatically
+- Recompute only when needed
+
+---
+
+## 🌊 Async Logic
+
+Async is just another intent.
+
+```ts
+bus.on("fetchUser", async ({ setState }) => {
+  setState(s => { s.loading = true })
+
+  const user = await api.getUser()
+
+  setState(s => {
+    s.user = user
+    s.loading = false
+  })
+})
+```
+
+No special async API required.
+
+---
+
+## 🧪 Unit Testing
+
+```ts
+const logic = createLogic({
+  state: { value: 0 },
+
+  intents: bus => {
+    bus.on<number>("set", ({ payload, setState }) => {
+      setState(s => { s.value = payload })
+    })
+  },
+
+  computed: {
+    squared: ({ state }) => state.value * state.value
+  }
+})
+
+const runtime = logic.create()
+
+await runtime.emit("set", 4)
+
+expect(runtime.state.squared).toBe(16)
+```
+
+---
+
+## 🔄 Multiple Logic Communication
+
+Multiple runtime instances can communicate through a shared intent bus.
+
+By default, each `useLogic` call is fully isolated.  
+To enable communication, you can share a bus.
+
+---
+
+#### 1️⃣ Scoped Global Bus
+
+When `sharedBus = true`, runtimes share a bus **within the same scope**.
+
+```ts
+import { useLogic } from "intentx-react"
+
+// ✅ Same scope → shared bus
+useLogic(counterLogic, "app", true)
+useLogic(userLogic, "app", true)
+
+// ❌ Different scope → isolated
+useLogic(counterLogic, "counter", true)
+useLogic(userLogic, "user", true)
+```
+
+<b>Behavior</b>
+
+- Same scope → runtimes can emit/listen to each other
+
+- Different scope → fully isolated
+
+- No global leakage
+
+This is the recommended way for modular communication.
+
+---
+
+#### 2️⃣ Custom Bus (Advanced)
+
+```ts
+import { createIntentBus, useLogic } from "intentx-react"
+
+const bus = createIntentBus()
+
+useLogic(counterLogic, "counter", bus)
+useLogic(userLogic, "user", bus)
+```
+
+<b>Behavior</b>
+
+- Cross-scope communication
+- Explicit orchestration control
+- Useful for complex workflows or app-wide coordination
+
+---
+
+#### 🧠 Communication Modes
+
+| Mode                            | Isolation | Cross Logic | Control |
+| ------------------------------- | --------- | ----------- | ------- |
+| Default                         | ✅ Full    | ❌ No        | Low     |
+| `sharedBus = true` (same scope) | ⚖ Scoped  | ✅ Yes       | Medium  |
+| Custom bus instance             | ❌ Manual  | ✅ Yes       | High    |
+
+
+<br />
+
+<b>⚠️ Important Notes</b>
+
+- sharedBus = true shares by scope, not globally.
+- Passing a bus instance overrides scope behavior.
+- Scope and bus are immutable after mount.
+
+---
+
+
+## 🧭 Comparison (Conceptual)
+
+| Criteria                       | intentx-runtime | Redux Toolkit  | Zustand | MobX         | Recoil |
+|--------------------------------|----------------|-----------------|---------|---------------|--------|
+| **Primary abstraction**        | 🟢 Intent      | 🟢 Reducer      | 🟢 Store | 🟢 Observable | 🟢 Atom |
+| **Single mutation entry**      | ✅             | ✅              | ❌       | ❌            | ❌     |
+| **Built-in orchestration**     | ✅             | ⚠️ (middleware) | ❌       | ⚠️            | ❌     |
+| **Async as first-class**       | ✅             | ⚠️ (thunk)      | ❌       | ⚠️            | ⚠️     |
+| **Derived state built-in**     | ✅             | ❌              | ⚠️       | ✅            | ✅     |
+| **Deterministic execution**    | ✅             | ⚠️              | ⚠️       | ⚠️            | ⚠️     |
+| **Headless runtime**           | ✅             | ⚠️              | ⚠️       | ⚠️            | ❌     |
+| **Backend / worker ready**     | ✅             | ⚠️              | ⚠️       | ❌            | ❌     |
+| **Behavior-centric design**    | ✅             | ❌              | ❌       | ❌            | ❌     |
+
+<br/>
+
+🟢 = Primary design focus  
+✅ = Built-in / first-class  
+⚠️ = Possible but not first-class or requires extra tooling   
+❌ = Not built-in
+
+Most libraries answer:
+
+> "How is state stored and updated?"
+
+intentx answers:
+
+> "What behavior happens when this event occurs?"
+
+---
+
+## 🎯 When To Use
+
+Use this if:
+
+- You have complex async flows
+- You want deterministic replayable behavior
+- You share logic between frontend and backend
+- You want strict mutation boundaries
+
+Do not use this if:
+
+- Your app only manages simple UI state
+- Your async flows are trivial
+- You don't need orchestration
+
+---
+
+## 🪪 License
+
+MIT

package/build/index.cjs.js

@@ -0,0 +1 @@
+"use strict";var e=require("intentx-runtime"),t=require("react"),n=require("react/jsx-runtime");function r(e){var t=Object.create(null);return e&&Object.keys(e).forEach(function(n){if("default"!==n){var r=Object.getOwnPropertyDescriptor(e,n);Object.defineProperty(t,n,r.get?r:{enumerable:!0,get:function(){return e[n]}})}}),t.default=e,Object.freeze(t)}var c=r(t);const i=new Map;function u(t,n,r){const u=c.useRef(null),o=!0===r?function(t){return t?"string"!=typeof t?e.createIntentBus():(i.has(t)||i.set(t,e.createIntentBus()),i.get(t)):e.createIntentBus()}(n):r||void 0;u.current||(u.current=t.create("string"==typeof n?e.createScope(n):n,o));const s=u.current,a=c.useSyncExternalStore(s.subscribe,s.getSnapshot,s.getSnapshot),f=c.useCallback((e,t)=>s.emit(e,t),[s]);return{runtime:s,state:a,actions:s.actions,emit:f}}Object.defineProperty(exports,"createIntentBus",{enumerable:!0,get:function(){return e.createIntentBus}}),Object.defineProperty(exports,"createLogic",{enumerable:!0,get:function(){return e.createLogic}}),Object.defineProperty(exports,"effect",{enumerable:!0,get:function(){return e.effect}}),exports.setGlobalBus=function(e){},exports.useLogic=function(e,t,n){const{state:r,actions:i,emit:o}=u(e,t,n);return c.useMemo(()=>({state:r,actions:i,emit:o}),[r,i,o])},exports.withLogic=function(e,t,r,c){var i,o;const s=i=>{const{state:o,actions:s,emit:a}=u(e,r,c);return n.jsx(t,{...i,state:o,actions:s,emit:a})};return s.displayName=`withLogic(${null!==(o=null!==(i=t.displayName)&&void 0!==i?i:t.name)&&void 0!==o?o:"View"})`,s};

package/build/index.d.ts

@@ -0,0 +1,8 @@
+export { createLogic } from "intentx-runtime";
+export { createIntentBus } from "intentx-runtime";
+export { effect } from "intentx-runtime";
+export type { LogicFactory, LogicActions, IntentMiddleware, IntentNext, } from "intentx-runtime";
+export { setGlobalBus } from "./react/useLogicRuntime";
+export { withLogic } from "./react/withLogic";
+export type { LogicViewProps } from "./react/withLogic";
+export { useLogic } from "./react/useLogic";

package/build/index.esm.js

@@ -0,0 +1 @@
+import{createScope as t,createIntentBus as e}from"intentx-runtime";export{createIntentBus,createLogic,effect}from"intentx-runtime";import*as n from"react";import{jsx as r}from"react/jsx-runtime";const i=new Map;function o(t){}function s(r,o,s){const c=n.useRef(null),a=!0===s?function(t){return t?"string"!=typeof t?e():(i.has(t)||i.set(t,e()),i.get(t)):e()}(o):s||void 0;c.current||(c.current=r.create("string"==typeof o?t(o):o,a));const u=c.current,m=n.useSyncExternalStore(u.subscribe,u.getSnapshot,u.getSnapshot),f=n.useCallback((t,e)=>u.emit(t,e),[u]);return{runtime:u,state:m,actions:u.actions,emit:f}}function c(t,e,n,i){var o,c;const a=o=>{const{state:c,actions:a,emit:u}=s(t,n,i);return r(e,{...o,state:c,actions:a,emit:u})};return a.displayName=`withLogic(${null!==(c=null!==(o=e.displayName)&&void 0!==o?o:e.name)&&void 0!==c?c:"View"})`,a}function a(t,e,r){const{state:i,actions:o,emit:c}=s(t,e,r);return n.useMemo(()=>({state:i,actions:o,emit:c}),[i,o,c])}export{o as setGlobalBus,a as useLogic,c as withLogic};

package/build/react/useLogic.d.ts

@@ -0,0 +1,7 @@
+import type { LogicActions, LogicFactory } from "intentx-runtime";
+import { ComputedDef } from "./withLogic";
+export declare function useLogic<S extends object, C extends ComputedDef<S>, A extends LogicActions>(logic: LogicFactory<S, C, A>, scope?: string, sharedBus?: any): {
+    state: Readonly<S & import("intentx-runtime/build/core/runtime").InferComputed<C>>;
+    actions: A;
+    emit: (intent: string, payload?: any) => Promise<void>;
+};

package/build/react/useLogicRuntime.d.ts

@@ -0,0 +1,12 @@
+import { Scope, LogicRuntime, LogicActions, LogicFactory, createIntentBus } from "intentx-runtime";
+import { ComputedDef } from "./withLogic";
+type IntentBus = ReturnType<typeof createIntentBus>;
+export declare function getGlobalBus(): IntentBus;
+export declare function setGlobalBus(bus: IntentBus): void;
+export declare function useLogicRuntime<S extends object, C extends ComputedDef<S>, A extends LogicActions>(logic: LogicFactory<S, C, A>, scope?: Scope | string, sharedBus?: boolean | IntentBus): {
+    runtime: LogicRuntime<S, C, A>;
+    state: Readonly<S & import("intentx-runtime/build/core/runtime").InferComputed<C>>;
+    actions: A;
+    emit: (intent: string, payload?: any) => Promise<void>;
+};
+export {};

package/build/react/withLogic.d.ts

@@ -0,0 +1,16 @@
+import * as React from "react";
+import type { ExtractLogicTypes, LogicActions, LogicFactory } from "intentx-runtime";
+export type ComputedDef<S> = Record<string, (context: {
+    state: Readonly<S>;
+}) => any>;
+export type InferComputed<C> = {
+    [K in keyof C]: C[K] extends (...args: any[]) => infer R ? R : never;
+};
+type InjectedProps<S extends object, C extends ComputedDef<S>, A extends LogicActions> = {
+    state: Readonly<S & InferComputed<C>>;
+    actions: A;
+    emit: (intent: string, payload?: any) => Promise<void>;
+};
+export type LogicViewProps<T extends LogicFactory<any, any, any>> = ExtractLogicTypes<T>;
+export declare function withLogic<S extends object, C extends ComputedDef<S>, A extends LogicActions, P extends object>(logic: LogicFactory<S, C, A>, View: React.ComponentType<P & InjectedProps<S, C, A>>, scope?: string, sharedBus?: any): React.FC<Omit<P, keyof InjectedProps<S, C, A>>>;
+export {};

package/package.json

@@ -0,0 +1,86 @@
+{
+  "name": "intentx-react",
+  "version": "0.1.0",
+  "description": "React adapter for intentx-runtime. Intent-first, deterministic business logic orchestration with a headless runtime.",
+  "license": "MIT",
+  "author": "Delpi.Kye",
+  "sideEffects": false,
+  "type": "module",
+
+  "main": "build/index.cjs.js",
+  "module": "build/index.esm.js",
+  "types": "build/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./build/index.d.ts",
+      "import": "./build/index.esm.js",
+      "require": "./build/index.cjs.js"
+    }
+  },
+  "files": [
+    "build"
+  ],
+
+  "scripts": {
+    "clean": "rimraf build",
+    "build": "rollup -c",
+    "cb": "npm run clean && npm run build",
+    "prepublishOnly": "npm run cb"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/delpikye-v/intentx-react.git"
+  },
+  "homepage": "https://github.com/delpikye-v/intentx-react#readme",
+  "bugs": {
+    "url": "https://github.com/delpikye-v/intentx-react/issues"
+  },
+
+  "funding": {
+    "type": "github",
+    "url": "https://github.com/sponsors/delpikye-v"
+  },
+
+  "keywords": [
+    "intent",
+    "intent-first",
+    "business-logic",
+    "logic-runtime",
+    "deterministic",
+    "orchestration",
+    "headless",
+    "framework-agnostic",
+    "react",
+    "react-state",
+    "react-architecture",
+    "external-store",
+    "computed-state",
+    "derived-state",
+    "async-orchestration",
+    "event-driven",
+    "state-management"
+  ],
+
+  "peerDependencies": {
+    "react": ">=18.0.0",
+    "react-dom": ">=18.0.0"
+  },
+  "devDependencies": {
+    "@rollup/plugin-commonjs": "^25.0.0",
+    "@rollup/plugin-node-resolve": "^15.2.3",
+    "@rollup/plugin-terser": "^0.4.4",
+    "@types/react": "^18.2.43",
+    "@types/react-dom": "^18.2.17",
+    "react": "^18.2.0",
+    "react-dom": "^18.2.0",
+    "rimraf": "^5.0.5",
+    "rollup": "^4.9.6",
+    "rollup-plugin-peer-deps-external": "^2.2.4",
+    "rollup-plugin-typescript2": "^0.36.0",
+    "tslib": "^2.6.2",
+    "typescript": "^5.3.3"
+  },
+  "dependencies": {
+    "intentx-runtime": "^0.1.2"
+  }
+}