@uistate/react 1.0.0

package/README.md

@@ -0,0 +1,160 @@
+# @uistate/react
+
+React adapter for [@uistate/core](https://www.npmjs.com/package/@uistate/core). Five hooks and a provider — that's the entire API.
+
+## Install
+
+```bash
+npm install @uistate/react @uistate/core react
+```
+
+**Peer dependencies:** `@uistate/core >=5.0.0` and `react >=18.0.0`.
+
+## Quick Start
+
+```jsx
+import { createEventState } from '@uistate/core';
+import { EventStateProvider, usePath, useIntent } from '@uistate/react';
+
+// Store lives outside React
+const store = createEventState({
+  state: { count: 0 },
+});
+
+// Business logic lives outside React
+store.subscribe('intent.increment', () => {
+  store.set('state.count', store.get('state.count') + 1);
+});
+
+function Counter() {
+  const count = usePath('state.count');
+  const increment = useIntent('intent.increment');
+  return <button onClick={() => increment(true)}>Count: {count}</button>;
+}
+
+function App() {
+  return (
+    <EventStateProvider store={store}>
+      <Counter />
+    </EventStateProvider>
+  );
+}
+```
+
+## API
+
+### `<EventStateProvider store={store}>`
+
+Makes a store available to all descendant hooks via React Context. The store is created outside React — the provider is pure dependency injection, not a state container.
+
+```jsx
+<EventStateProvider store={store}>
+  <App />
+</EventStateProvider>
+```
+
+### `useStore()`
+
+Returns the store from context. Throws if called outside a provider.
+
+```jsx
+const store = useStore();
+```
+
+### `usePath(path)`
+
+Subscribe to a dot-path. Re-renders only when the value at that path changes. Uses `useSyncExternalStore` for concurrent-mode safety.
+
+```jsx
+const tasks = usePath('state.tasks');
+const userName = usePath('state.user.name');
+const filtered = usePath('derived.tasks.filtered');
+```
+
+### `useIntent(path)`
+
+Returns a stable, memoized function that publishes a value to a path. Safe to pass as a prop without causing re-renders.
+
+```jsx
+const addTask = useIntent('intent.addTask');
+const setFilter = useIntent('intent.changeFilter');
+
+// In a handler:
+addTask('Buy milk');
+setFilter('active');
+```
+
+### `useWildcard(path)`
+
+Subscribe to a wildcard path. Re-renders when any child of that path changes. Returns the parent object.
+
+```jsx
+const user = useWildcard('state.user.*');
+// Re-renders when state.user.name, state.user.email, etc. change
+```
+
+### `useAsync(path)`
+
+Async data fetching with automatic status tracking. Returns `{ data, status, error, execute, cancel }`.
+
+```jsx
+function UserList() {
+  const { data, status, error, execute, cancel } = useAsync('users');
+
+  useEffect(() => {
+    execute((signal) =>
+      fetch('/api/users', { signal }).then(r => r.json())
+    );
+  }, [execute]);
+
+  if (status === 'loading') return <Spinner />;
+  if (error) return <Error message={error} />;
+  return <ul>{data?.map(u => <li key={u.id}>{u.name}</li>)}</ul>;
+}
+```
+
+Calling `execute` again auto-aborts the previous in-flight request. No race conditions.
+
+## Architecture
+
+The recommended pattern is three namespaces:
+
+| Namespace | Purpose | Hooks |
+|-----------|---------|-------|
+| `state.*` | Authoritative application state | `usePath` |
+| `derived.*` | Computed projections | `usePath` |
+| `intent.*` | Write-only signals from the UI | `useIntent` |
+
+This gives you Model-View-Intent (MVI) inside a single store:
+
+- **state.\*** is the Model
+- **derived.\*** is the ViewModel
+- **intent.\*** is the Controller
+
+```jsx
+// Component only declares what it reads and what it publishes
+function Filters() {
+  const filter = usePath('state.filter');           // read
+  const setFilter = useIntent('intent.changeFilter'); // write
+  return <button onClick={() => setFilter('active')}>{filter}</button>;
+}
+```
+
+Business logic lives in subscribers — testable without React:
+
+```js
+store.subscribe('intent.addTask', (text) => {
+  const tasks = store.get('state.tasks') || [];
+  store.set('state.tasks', [...tasks, { id: genId(), text }]);
+});
+```
+
+## Why a separate package?
+
+- **Zero cost if you don't use React** — `@uistate/core` stays framework-free
+- **React is a peer dependency** — not bundled, no version conflicts
+- **Tiny** — ~50 lines of code, no dependencies beyond React and the core store
+
+## License
+
+MIT

package/eventStateReact.js

@@ -0,0 +1,127 @@
+import { createContext, useContext, useMemo, useSyncExternalStore } from 'react';
+
+// ---- Context ----
+const EventStateContext = createContext(null);
+
+/**
+ * Provider — makes a store available to all child components via hooks.
+ * The store is created *outside* React. The provider is pure dependency injection.
+ *
+ * @param {{ store: object, children: React.ReactNode }} props
+ */
+export function EventStateProvider({ store, children }) {
+  return (
+    <EventStateContext.Provider value={store}>
+      {children}
+    </EventStateContext.Provider>
+  );
+}
+
+/**
+ * useStore — returns the EventState store from context.
+ * Throws if called outside an EventStateProvider.
+ *
+ * @returns {object} The EventState store
+ */
+export function useStore() {
+  const store = useContext(EventStateContext);
+  if (!store) {
+    throw new Error(
+      'useStore: no store found. Wrap your component tree in <EventStateProvider store={store}>.'
+    );
+  }
+  return store;
+}
+
+/**
+ * usePath — subscribe to a dot-path in the store.
+ * Re-renders the component only when the value at that path changes.
+ * Uses React 18's useSyncExternalStore for concurrent-mode safety.
+ *
+ * @param {string} path — dot-separated state path (e.g. 'state.tasks')
+ * @returns {any} The current value at the path
+ */
+export function usePath(path) {
+  const store = useStore();
+
+  const subscribe = useMemo(
+    () => (onStoreChange) => store.subscribe(path, () => onStoreChange()),
+    [store, path]
+  );
+
+  const getSnapshot = useMemo(
+    () => () => store.get(path),
+    [store, path]
+  );
+
+  return useSyncExternalStore(subscribe, getSnapshot, getSnapshot);
+}
+
+/**
+ * useIntent — returns a stable function that publishes a value to a path.
+ * Memoized so it won't cause unnecessary re-renders when passed as a prop.
+ *
+ * @param {string} path — dot-separated intent path (e.g. 'intent.addTask')
+ * @returns {(value: any) => any} A setter function
+ */
+export function useIntent(path) {
+  const store = useStore();
+  return useMemo(
+    () => (value) => store.set(path, value),
+    [store, path]
+  );
+}
+
+/**
+ * useWildcard — subscribe to a wildcard path (e.g. 'state.*').
+ * Re-renders whenever any child of that path changes.
+ * The returned value is the parent object at the path prefix.
+ *
+ * @param {string} wildcardPath — e.g. 'state.tasks.*' or 'state.*'
+ * @returns {any} The current value at the parent path
+ */
+export function useWildcard(wildcardPath) {
+  const store = useStore();
+  const parentPath = wildcardPath.endsWith('.*')
+    ? wildcardPath.slice(0, -2)
+    : wildcardPath;
+
+  const subscribe = useMemo(
+    () => (onStoreChange) => store.subscribe(wildcardPath, () => onStoreChange()),
+    [store, wildcardPath]
+  );
+
+  const getSnapshot = useMemo(
+    () => () => store.get(parentPath),
+    [store, parentPath]
+  );
+
+  return useSyncExternalStore(subscribe, getSnapshot, getSnapshot);
+}
+
+/**
+ * useAsync — trigger an async operation and subscribe to its status.
+ * Returns { data, status, error, execute, cancel }.
+ *
+ * @param {string} path — base path for the async operation
+ * @returns {{ data: any, status: string, error: any, execute: Function, cancel: Function }}
+ */
+export function useAsync(path) {
+  const store = useStore();
+
+  const data = usePath(`${path}.data`);
+  const status = usePath(`${path}.status`);
+  const error = usePath(`${path}.error`);
+
+  const execute = useMemo(
+    () => (fetcher) => store.setAsync(path, fetcher),
+    [store, path]
+  );
+
+  const cancel = useMemo(
+    () => () => store.cancel(path),
+    [store, path]
+  );
+
+  return { data, status, error, execute, cancel };
+}

package/index.js

@@ -0,0 +1,8 @@
+export {
+  EventStateProvider,
+  useStore,
+  usePath,
+  useIntent,
+  useWildcard,
+  useAsync,
+} from './eventStateReact.js';

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@uistate/react",
+  "version": "1.0.0",
+  "description": "React adapter for @uistate/core — usePath, useIntent, useAsync hooks and EventStateProvider",
+  "main": "index.js",
+  "module": "index.js",
+  "type": "module",
+  "exports": {
+    ".": {
+      "import": "./index.js",
+      "default": "./index.js"
+    },
+    "./eventStateReact": {
+      "import": "./eventStateReact.js",
+      "default": "./eventStateReact.js"
+    }
+  },
+  "files": [
+    "index.js",
+    "eventStateReact.js",
+    "README.md"
+  ],
+  "peerDependencies": {
+    "@uistate/core": ">=5.0.0",
+    "react": ">=18.0.0"
+  },
+  "keywords": [
+    "uistate",
+    "react",
+    "state-management",
+    "hooks",
+    "useSyncExternalStore",
+    "event-driven",
+    "dot-path",
+    "external-store",
+    "adapter"
+  ],
+  "author": "Ajdin Imsirovic",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ImsirovicAjdin/uistate-react.git"
+  },
+  "homepage": "https://uistate.com/react.html",
+  "bugs": {
+    "url": "https://github.com/ImsirovicAjdin/uistate-react/issues"
+  }
+}