@everystate/react 1.0.0 → 1.0.2

package/README.md

@@ -2,7 +2,8 @@
 
 **React adapter for EveryState with hooks**
 
-Use EveryState in React with `usePath`, `useIntent`, and `useAsync` hooks.
+Use EveryState in React with `usePath`, `useIntent`, `useWildcard`, and `useAsync` hooks.
+Built on React 18's `useSyncExternalStore` for concurrent-mode safety.
 
 ## Installation
 
@@ -13,20 +14,19 @@ npm install @everystate/react @everystate/core react
 ## Quick Start
 
 ```jsx
-import { createEventState } from '@everystate/core';
-import { EventStateProvider, usePath } from '@everystate/react';
+import { createEveryState } from '@everystate/core';
+import { EventStateProvider, usePath, useIntent } from '@everystate/react';
 
-const store = createEventState({ count: 0 });
+const store = createEveryState({ count: 0 });
 
 function Counter() {
   const count = usePath('count');
+  const setCount = useIntent('count');
 
   return (
     <div>
       <p>Count: {count}</p>
-      <button onClick={() => store.set('count', count + 1)}>
-        Increment
-      </button>
+      <button onClick={() => setCount(count + 1)}>Increment</button>
     </div>
   );
 }
@@ -42,9 +42,27 @@ function App() {
 
 ## Hooks
 
-- **`usePath(path)`** Subscribe to a specific path
-- **`useIntent(intentName, handler)`** Handle user intents
-- **`useAsync(path, fetcher)`** Async data loading
+- **`usePath(path)`** - Subscribe to a dot-path. Re-renders only when that path changes.
+- **`useIntent(path)`** - Returns a stable setter function for a path. Memoized to prevent unnecessary re-renders.
+- **`useWildcard(path)`** - Subscribe to a wildcard path (e.g. `'user.*'`). Returns the parent object.
+- **`useAsync(path)`** - Returns `{ data, status, error, execute, cancel }` for async operations.
+- **`useStore()`** - Returns the raw store from context.
+
+
+## Ecosystem
+
+| Package | Description | License |
+|---|---|---|
+| [@everystate/aliases](https://www.npmjs.com/package/@everystate/aliases) | Ergonomic single-character and short-name DOM aliases for vanilla JS | MIT |
+| [@everystate/core](https://www.npmjs.com/package/@everystate/core) | Path-based state management with wildcard subscriptions and async support. Core state engine (you are here). | MIT |
+| [@everystate/css](https://www.npmjs.com/package/@everystate/css) | Reactive CSSOM engine: design tokens, typed validation, WCAG enforcement, all via path-based state | MIT |
+| [@everystate/examples](https://www.npmjs.com/package/@everystate/examples) | Example applications and patterns | MIT |
+| [@everystate/perf](https://www.npmjs.com/package/@everystate/perf) | Performance monitoring overlay | MIT |
+| [@everystate/react](https://www.npmjs.com/package/@everystate/react) | React hooks adapter: `usePath`, `useIntent`, `useAsync` hooks and `EveryStateProvider` | MIT |
+| [@everystate/renderer](https://www.npmjs.com/package/@everystate/renderer) | Direct-binding reactive renderer: `bind-*`, `set`, `each` attributes. Zero build step | Proprietary |
+| [@everystate/router](https://www.npmjs.com/package/@everystate/router) | SPA routing as state | MIT |
+| [@everystate/test](https://www.npmjs.com/package/@everystate/test) | Event-sequence testing for EveryState stores. Zero dependency. | Proprietary |
+| [@everystate/view](https://www.npmjs.com/package/@everystate/view) | State-driven view: DOMless resolve + surgical DOM projector. View tree as first-class state | MIT |
 
 ## License
 

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.d.ts

@@ -0,0 +1,66 @@
+/**
+ * @everystate/react
+ *
+ * React adapter for EveryState with hooks.
+ * Built on React 18's useSyncExternalStore for concurrent-mode safety.
+ */
+
+import type { EveryStateStore } from '@everystate/core';
+import type { ReactNode } from 'react';
+
+/**
+ * Provider: makes a store available to all child components via hooks.
+ * The store is created *outside* React. The provider is pure dependency injection.
+ */
+export function EventStateProvider(props: {
+  store: EveryStateStore;
+  children: ReactNode;
+}): JSX.Element;
+
+/**
+ * Returns the EveryState store from context.
+ * Throws if called outside an EventStateProvider.
+ */
+export function useStore(): EveryStateStore;
+
+/**
+ * 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 path - Dot-separated state path (e.g. 'user.name')
+ * @returns The current value at the path
+ */
+export function usePath(path: string): any;
+
+/**
+ * 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 path - Dot-separated intent path (e.g. 'intent.addTask')
+ * @returns A setter function
+ */
+export function useIntent(path: string): (value: any) => any;
+
+/**
+ * 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 wildcardPath - e.g. 'state.tasks.*' or 'state.*'
+ * @returns The current value at the parent path
+ */
+export function useWildcard(wildcardPath: string): any;
+
+/**
+ * Trigger an async operation and subscribe to its status.
+ *
+ * @param path - Base path for the async operation
+ */
+export function useAsync(path: string): {
+  data: any;
+  status: string | undefined;
+  error: any;
+  execute: (fetcher: (signal: AbortSignal) => Promise<any>) => Promise<any>;
+  cancel: () => void;
+};

package/index.js

@@ -1,8 +1,15 @@
 /**
  * @everystate/react
  *
- * EveryState wrapper for @uistate/react
- * Re-exports all functionality from the underlying @uistate/react package
+ * React adapter for EveryState with hooks:
+ * EventStateProvider, useStore, usePath, useIntent, useWildcard, useAsync
  */
 
-export * from '@uistate/react';
+export {
+  EventStateProvider,
+  useStore,
+  usePath,
+  useIntent,
+  useWildcard,
+  useAsync,
+} from './eventStateReact.js';

package/package.json

@@ -1,9 +1,10 @@
 {
   "name": "@everystate/react",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "description": "EveryState React: React adapter with usePath, useIntent, useAsync hooks and EventStateProvider",
   "type": "module",
   "main": "index.js",
+  "types": "index.d.ts",
   "keywords": [
     "everystate",
     "react",
@@ -24,7 +25,7 @@
     "type": "git",
     "url": "https://github.com/ImsirovicAjdin/everystate-react"
   },
-  "dependencies": {
-    "@uistate/react": "^1.0.1"
+  "peerDependencies": {
+    "react": ">=18.0.0"
   }
 }

package/self-test.js

@@ -0,0 +1,166 @@
+/**
+ * @everystate/react: zero-dependency self-test
+ *
+ * Since the React adapter uses JSX and React hooks (which require a React
+ * runtime and JSX transform), this self-test verifies:
+ * 1. The module exports exist and are functions
+ * 2. The store-side patterns that the hooks consume work correctly
+ *
+ * The hooks themselves (usePath, useIntent, useWildcard, useAsync) are
+ * thin wrappers around store.subscribe + useSyncExternalStore.
+ * Testing the store patterns proves the hooks will work.
+ */
+
+import { createEveryState } from '@everystate/core';
+
+let passed = 0;
+let failed = 0;
+
+function assert(label, condition) {
+  if (condition) {
+    console.log(`  ✓ ${label}`);
+    passed++;
+  } else {
+    console.error(`  ✗ ${label}`);
+    failed++;
+  }
+}
+
+function section(title) {
+  console.log(`\n${title}`);
+}
+
+// -- 1. usePath pattern: subscribe + get -----------------------------
+
+section('1. usePath pattern: subscribe + get');
+
+const s1 = createEveryState({ user: { name: 'Alice' } });
+let s1snap = s1.get('user.name');
+const unsub1 = s1.subscribe('user.name', () => { s1snap = s1.get('user.name'); });
+assert('initial snapshot', s1snap === 'Alice');
+
+s1.set('user.name', 'Bob');
+assert('snapshot updates on set', s1snap === 'Bob');
+
+unsub1();
+s1.set('user.name', 'Charlie');
+assert('unsubscribe stops updates', s1snap === 'Bob');
+s1.destroy();
+
+// -- 2. useIntent pattern: stable setter -----------------------------
+
+section('2. useIntent pattern: stable setter');
+
+const s2 = createEveryState({ intent: { addTask: null } });
+const setter = (value) => s2.set('intent.addTask', value);
+setter({ text: 'Buy milk' });
+assert('setter writes to path', s2.get('intent.addTask').text === 'Buy milk');
+
+setter(null);
+assert('setter clears value', s2.get('intent.addTask') === null);
+s2.destroy();
+
+// -- 3. useWildcard pattern: subscribe wildcard + get parent ---------
+
+section('3. useWildcard pattern: wildcard subscribe');
+
+const s3 = createEveryState({ state: { tasks: { t1: 'A', t2: 'B' } } });
+let wildcardFires = 0;
+const unsub3 = s3.subscribe('state.tasks.*', () => {
+  wildcardFires++;
+});
+
+s3.set('state.tasks.t1', 'A updated');
+assert('wildcard fires on child change', wildcardFires === 1);
+
+s3.set('state.tasks.t3', 'C');
+assert('wildcard fires on new child', wildcardFires === 2);
+
+const parent = s3.get('state.tasks');
+assert('get parent returns object', typeof parent === 'object');
+assert('parent has t1', parent.t1 === 'A updated');
+assert('parent has t3', parent.t3 === 'C');
+
+unsub3();
+s3.destroy();
+
+// -- 4. useAsync pattern: setAsync lifecycle -------------------------
+
+section('4. useAsync pattern: setAsync lifecycle');
+
+const s4 = createEveryState({});
+const promise = s4.setAsync('users', async () => [{ id: 1, name: 'Alice' }]);
+
+// During loading
+assert('loading: status = loading', s4.get('users.status') === 'loading');
+assert('loading: error = null', s4.get('users.error') === null);
+
+await promise;
+
+// After success
+assert('success: status = success', s4.get('users.status') === 'success');
+assert('success: data is array', Array.isArray(s4.get('users.data')));
+assert('success: data[0].name = Alice', s4.get('users.data')[0].name === 'Alice');
+s4.destroy();
+
+// -- 5. useAsync error pattern ---------------------------------------
+
+section('5. useAsync error pattern');
+
+const s5 = createEveryState({});
+try {
+  await s5.setAsync('data', async () => { throw new Error('Network error'); });
+} catch {}
+assert('error: status = error', s5.get('data.status') === 'error');
+assert('error: error message exists', typeof s5.get('data.error') === 'string' || s5.get('data.error') instanceof Error);
+s5.destroy();
+
+// -- 6. Provider pattern: store as context ---------------------------
+
+section('6. Provider pattern: store as external dependency');
+
+const s6 = createEveryState({ count: 0 });
+// The provider just passes the store via React context.
+// We verify the store is usable as an external store.
+const subscribe = (onStoreChange) => s6.subscribe('count', () => onStoreChange());
+const getSnapshot = () => s6.get('count');
+
+let latestSnapshot = getSnapshot();
+const unsub6 = subscribe(() => { latestSnapshot = getSnapshot(); });
+
+s6.set('count', 10);
+assert('external store subscribe works', latestSnapshot === 10);
+
+s6.set('count', 20);
+assert('external store re-fires', latestSnapshot === 20);
+
+unsub6();
+s6.destroy();
+
+// -- 7. Batch pattern (React 18 automatic batching) ------------------
+
+section('7. batch pattern (React 18 compat)');
+
+const s7 = createEveryState({ a: 0, b: 0 });
+let renderCount = 0;
+s7.subscribe('a', () => { renderCount++; });
+s7.subscribe('b', () => { renderCount++; });
+
+s7.batch(() => {
+  s7.set('a', 1);
+  s7.set('b', 2);
+});
+assert('batch: 2 subscribers fire once each', renderCount === 2);
+assert('batch: a = 1', s7.get('a') === 1);
+assert('batch: b = 2', s7.get('b') === 2);
+s7.destroy();
+
+// -- Summary ---------------------------------------------------------
+
+console.log(`\n@everystate/react v1.0.0 self-test`);
+if (failed > 0) {
+  console.error(`✗ ${failed} assertion(s) failed, ${passed} passed`);
+  process.exit(1);
+} else {
+  console.log(`✓ ${passed} assertions passed`);
+}

package/tests/react.test.js

@@ -0,0 +1,179 @@
+/**
+ * @everystate/react: integration tests via @everystate/test
+ *
+ * Tests the store-side patterns that React hooks consume.
+ * Since EveryState is the IR, testing the IR proves the hooks work.
+ * The hooks are thin wrappers: usePath = subscribe + get,
+ * useIntent = set, useWildcard = subscribe wildcard + get parent.
+ *
+ * JSX/React-specific behavior (re-renders, concurrent mode) requires
+ * a React test environment and is outside the scope of these tests.
+ */
+
+import { createEventTest, runTests } from '@everystate/test';
+import { createEveryState } from '@everystate/core';
+
+const results = runTests({
+
+  // -- usePath patterns ----------------------------------------------
+
+  'usePath: subscribe to exact path': () => {
+    const t = createEventTest({ user: { name: 'Alice', age: 30 } });
+    t.trigger('user.name', 'Bob');
+    t.assertPath('user.name', 'Bob');
+    t.assertType('user.name', 'string');
+    t.assertEventFired('user.name', 1);
+  },
+
+  'usePath: nested path subscription': () => {
+    const t = createEventTest({ app: { settings: { theme: 'dark' } } });
+    t.trigger('app.settings.theme', 'light');
+    t.assertPath('app.settings.theme', 'light');
+    t.assertEventFired('app.settings.theme', 1);
+  },
+
+  'usePath: unsubscribe stops notifications': () => {
+    const store = createEventState({ count: 0 });
+    let fires = 0;
+    const unsub = store.subscribe('count', () => { fires++; });
+    store.set('count', 1);
+    unsub();
+    store.set('count', 2);
+    if (fires !== 1) throw new Error(`Expected 1 fire after unsub, got ${fires}`);
+    store.destroy();
+  },
+
+  // -- useIntent patterns --------------------------------------------
+
+  'useIntent: set value at path': () => {
+    const t = createEventTest({ intent: { addTask: null } });
+    t.trigger('intent.addTask', { text: 'Buy milk', done: false });
+    t.assertPath('intent.addTask', { text: 'Buy milk', done: false });
+    t.assertType('intent.addTask', 'object');
+  },
+
+  'useIntent: reset intent after processing': () => {
+    const t = createEventTest({ intent: { submit: null } });
+    t.trigger('intent.submit', { form: 'login' });
+    t.trigger('intent.submit', null);
+    t.assertPath('intent.submit', null);
+  },
+
+  // -- useWildcard patterns ------------------------------------------
+
+  'useWildcard: fires on any child change': () => {
+    const store = createEventState({ state: { tasks: {} } });
+    let fires = 0;
+    store.subscribe('state.tasks.*', () => { fires++; });
+    store.set('state.tasks.t1', { text: 'A', done: false });
+    store.set('state.tasks.t2', { text: 'B', done: false });
+    if (fires !== 2) throw new Error(`Expected 2 fires, got ${fires}`);
+    store.destroy();
+  },
+
+  'useWildcard: get parent returns full object': () => {
+    const t = createEventTest({ state: { tasks: { t1: 'A', t2: 'B' } } });
+    t.trigger('state.tasks.t3', 'C');
+    t.assertPath('state.tasks', { t1: 'A', t2: 'B', t3: 'C' });
+  },
+
+  // -- useAsync patterns ---------------------------------------------
+
+  'useAsync: loading → success lifecycle': async () => {
+    const store = createEventState({});
+    await store.setAsync('users', async () => [{ id: 1, name: 'Alice' }]);
+    if (store.get('users.status') !== 'success') throw new Error('Expected success');
+    if (!Array.isArray(store.get('users.data'))) throw new Error('Expected array');
+    store.destroy();
+  },
+
+  'useAsync: loading → error lifecycle': async () => {
+    const store = createEventState({});
+    try {
+      await store.setAsync('data', async () => { throw new Error('fail'); });
+    } catch {}
+    if (store.get('data.status') !== 'error') throw new Error('Expected error');
+    store.destroy();
+  },
+
+  'useAsync: status/data/error paths are typed': () => {
+    const t = createEventTest({});
+    t.store.setMany({
+      'users.status': 'success',
+      'users.data': [{ id: 1, name: 'Alice' }],
+      'users.error': null,
+    });
+    t.assertType('users.status', 'string');
+    t.assertArrayOf('users.data', { id: 'number', name: 'string' });
+  },
+
+  // -- Provider pattern ----------------------------------------------
+
+  'provider: store as external store (useSyncExternalStore compat)': () => {
+    const store = createEventState({ count: 0 });
+    // Simulate useSyncExternalStore contract
+    let snapshot = store.get('count');
+    const subscribe = (cb) => store.subscribe('count', () => {
+      snapshot = store.get('count');
+      cb();
+    });
+    let renderCount = 0;
+    const unsub = subscribe(() => { renderCount++; });
+
+    store.set('count', 1);
+    if (snapshot !== 1) throw new Error('Snapshot should be 1');
+    if (renderCount !== 1) throw new Error('Should have rendered once');
+
+    store.set('count', 2);
+    if (snapshot !== 2) throw new Error('Snapshot should be 2');
+    if (renderCount !== 2) throw new Error('Should have rendered twice');
+
+    unsub();
+    store.destroy();
+  },
+
+  // -- batch (React 18 automatic batching compat) --------------------
+
+  'batch: atomic updates (React 18 compat)': () => {
+    const t = createEventTest({ form: { name: '', email: '' } });
+    t.store.batch(() => {
+      t.trigger('form.name', 'Alice');
+      t.trigger('form.email', 'alice@example.com');
+    });
+    t.assertPath('form.name', 'Alice');
+    t.assertPath('form.email', 'alice@example.com');
+    // Each path fires once after batch
+    t.assertEventFired('form.name', 1);
+    t.assertEventFired('form.email', 1);
+  },
+
+  'batch: setMany for atomic route updates': () => {
+    const t = createEventTest({});
+    t.store.setMany({
+      'ui.route.view': 'dashboard',
+      'ui.route.path': '/dashboard',
+      'ui.route.params': {},
+    });
+    t.assertPath('ui.route.view', 'dashboard');
+    t.assertPath('ui.route.path', '/dashboard');
+    t.assertType('ui.route.view', 'string');
+  },
+
+  // -- type generation from React patterns ---------------------------
+
+  'types: React app state shape': () => {
+    const t = createEventTest({
+      user: { name: 'Alice', email: 'alice@example.com', role: 'admin' },
+      tasks: [{ id: 1, text: 'Buy milk', done: false }],
+      ui: { theme: 'dark', sidebarOpen: true },
+    });
+    t.assertShape('user', { name: 'string', email: 'string', role: 'string' });
+    t.assertArrayOf('tasks', { id: 'number', text: 'string', done: 'boolean' });
+    t.assertShape('ui', { theme: 'string', sidebarOpen: 'boolean' });
+
+    const types = t.getTypeAssertions();
+    if (types.length !== 3) throw new Error(`Expected 3 type assertions, got ${types.length}`);
+  },
+});
+
+if (results.failed > 0) process.exit(1);