@sigrea/react 0.1.0

package/README.md

@@ -0,0 +1,105 @@
+# @sigrea/react
+
+`@sigrea/react` adapts [@sigrea/core](https://www.npmjs.com/package/@sigrea/core) logic modules and signals so they can participate in React components. It wires scope-aware lifecycles to `useEffect`, keeps signal subscriptions aligned with React rendering, and surfaces ergonomic hooks for both shallow and deep reactivity.
+
+## Installation
+
+```bash
+pnpm add @sigrea/react @sigrea/core react react-dom
+```
+
+React 18+ and Node.js 20+ are required. Equivalent npm or yarn commands work the same way.
+
+## What This Adapter Provides
+
+- **Signal readers** – `useSignal` streams signals and computed values into React components.
+- **Deep signal access** – `useDeepSignal` exposes mutable deep signal objects with automatic teardown.
+- **Derived state** – `useComputed` keeps derived values memoized per component instance.
+- **Logic lifecycles** – `useLogic` mounts `defineLogic` factories and binds `onMount` / `onUnmount` to React’s lifecycle.
+- **Snapshots** – `useSnapshot` provides low-level control when you need direct access to signal handlers.
+
+## Quick Start
+
+### Consume a signal
+
+```tsx
+import { signal } from "@sigrea/core";
+import { useSignal } from "@sigrea/react";
+
+const count = signal(0);
+
+export function CounterLabel() {
+	const value = useSignal(count);
+	return <span>{value}</span>;
+}
+```
+
+### Bridge framework-agnostic logic
+
+```tsx
+import { defineLogic, signal } from "@sigrea/core";
+import { useLogic } from "@sigrea/react";
+
+const CounterLogic = defineLogic<{ initialCount: number }>()((props) => {
+	const count = signal(props.initialCount);
+
+	const increment = () => {
+		count.value += 1;
+	};
+
+	const reset = () => {
+		count.value = props.initialCount;
+	};
+
+	return { count, increment, reset };
+});
+
+export function Counter(props: { initialCount: number }) {
+	const counter = useLogic(CounterLogic, props);
+	const value = useSignal(counter.count);
+
+	return (
+		<div>
+			<span>{value}</span>
+			<button onClick={counter.increment}>Increment</button>
+			<button onClick={counter.reset}>Reset</button>
+		</div>
+	);
+}
+```
+
+### Work with deep signals
+
+```tsx
+import { deepSignal } from "@sigrea/core";
+import { useDeepSignal } from "@sigrea/react";
+
+const form = deepSignal({ name: "Sigrea" });
+
+export function ProfileForm() {
+	const state = useDeepSignal(form);
+
+	return (
+		<label>
+			Name
+			<input
+				value={state.name}
+				onChange={(event) => {
+					state.name = event.target.value;
+				}}
+			/>
+		</label>
+	);
+}
+```
+
+## Testing
+
+- `pnpm install` – install dependencies
+- `pnpm test` – run the Vitest suite
+- `pnpm build` – emit distributable artifacts
+- `pnpm dev` – launch the playground counter demo
+
+## License
+
+MIT — see `LICENSE`.

package/dist/index.cjs

@@ -0,0 +1,103 @@
+'use strict';
+
+const react = require('react');
+const core = require('@sigrea/core');
+
+const scheduleMicrotask = (callback) => {
+  if (typeof globalThis.queueMicrotask === "function") {
+    globalThis.queueMicrotask(callback);
+    return;
+  }
+  Promise.resolve().then(callback);
+};
+function useLogic(logic, ...args) {
+  const props = args.length === 0 ? void 0 : args[0];
+  const stateRef = react.useRef(void 0);
+  const currentState = stateRef.current;
+  const shouldRemount = currentState === void 0 || currentState.logic !== logic || !Object.is(currentState.props, props);
+  if (shouldRemount) {
+    if (currentState !== void 0) {
+      core.cleanupLogic(currentState.instance);
+      stateRef.current = void 0;
+    }
+    const logicArgs = props === void 0 ? [] : [props];
+    stateRef.current = {
+      instance: core.mountLogic(logic, ...logicArgs),
+      logic,
+      props,
+      cleanupScheduled: false,
+      cleanupToken: 0
+    };
+  }
+  const state = stateRef.current;
+  if (state === void 0) {
+    throw new Error("useLogic failed to mount the requested logic instance.");
+  }
+  const instance = state.instance;
+  react.useEffect(() => {
+    const state2 = stateRef.current;
+    if (state2 === void 0 || state2.instance !== instance) {
+      return () => {
+      };
+    }
+    state2.cleanupScheduled = false;
+    return () => {
+      const latest = stateRef.current;
+      if (latest === void 0 || latest.instance !== instance) {
+        core.cleanupLogic(instance);
+        return;
+      }
+      latest.cleanupScheduled = true;
+      const token = latest.cleanupToken + 1;
+      latest.cleanupToken = token;
+      scheduleMicrotask(() => {
+        const updated = stateRef.current;
+        if (updated === void 0 || updated.instance !== instance || !updated.cleanupScheduled || updated.cleanupToken !== token) {
+          return;
+        }
+        updated.cleanupScheduled = false;
+        stateRef.current = void 0;
+        core.cleanupLogic(instance);
+      });
+    };
+  }, [instance]);
+  return instance;
+}
+
+function useSnapshot(handler) {
+  const subscribe = react.useCallback(
+    (onStoreChange) => handler.subscribe(onStoreChange),
+    [handler]
+  );
+  const getSnapshot = react.useCallback(() => handler.getSnapshot(), [handler]);
+  const snapshot = react.useSyncExternalStore(
+    subscribe,
+    getSnapshot,
+    getSnapshot
+  );
+  return snapshot.value;
+}
+
+function useSignal(source) {
+  const handler = react.useMemo(
+    () => core.createSignalHandler(source),
+    [source]
+  );
+  return useSnapshot(handler);
+}
+
+function useComputed(source) {
+  const handler = react.useMemo(() => core.createComputedHandler(source), [source]);
+  return useSnapshot(handler);
+}
+
+function useDeepSignal(source) {
+  const handler = react.useMemo(() => core.createDeepSignalHandler(source), [source]);
+  return useSnapshot(handler);
+}
+
+exports.useComputed = useComputed;
+exports.useDeepSignal = useDeepSignal;
+exports.useLogic = useLogic;
+exports.useSignal = useSignal;
+exports.useSnapshot = useSnapshot;

package/dist/index.d.cts

@@ -0,0 +1,14 @@
+import { LogicFunction, LogicArgs, LogicInstance, Signal, ReadonlySignal, Computed, DeepSignal, SnapshotHandler } from '@sigrea/core';
+
+declare function useLogic<TReturn extends object, TProps = void>(logic: LogicFunction<TReturn, TProps>, ...args: LogicArgs<TProps>): LogicInstance<TReturn>;
+
+type ReadableSignal<T> = Signal<T> | ReadonlySignal<T>;
+declare function useSignal<T>(source: ReadableSignal<T>): T;
+
+declare function useComputed<T>(source: Computed<T>): T;
+
+declare function useDeepSignal<T extends object>(source: DeepSignal<T>): T;
+
+declare function useSnapshot<T>(handler: SnapshotHandler<T>): T;
+
+export { useComputed, useDeepSignal, useLogic, useSignal, useSnapshot };

package/dist/index.d.mts

@@ -0,0 +1,14 @@
+import { LogicFunction, LogicArgs, LogicInstance, Signal, ReadonlySignal, Computed, DeepSignal, SnapshotHandler } from '@sigrea/core';
+
+declare function useLogic<TReturn extends object, TProps = void>(logic: LogicFunction<TReturn, TProps>, ...args: LogicArgs<TProps>): LogicInstance<TReturn>;
+
+type ReadableSignal<T> = Signal<T> | ReadonlySignal<T>;
+declare function useSignal<T>(source: ReadableSignal<T>): T;
+
+declare function useComputed<T>(source: Computed<T>): T;
+
+declare function useDeepSignal<T extends object>(source: DeepSignal<T>): T;
+
+declare function useSnapshot<T>(handler: SnapshotHandler<T>): T;
+
+export { useComputed, useDeepSignal, useLogic, useSignal, useSnapshot };

package/dist/index.d.ts

@@ -0,0 +1,14 @@
+import { LogicFunction, LogicArgs, LogicInstance, Signal, ReadonlySignal, Computed, DeepSignal, SnapshotHandler } from '@sigrea/core';
+
+declare function useLogic<TReturn extends object, TProps = void>(logic: LogicFunction<TReturn, TProps>, ...args: LogicArgs<TProps>): LogicInstance<TReturn>;
+
+type ReadableSignal<T> = Signal<T> | ReadonlySignal<T>;
+declare function useSignal<T>(source: ReadableSignal<T>): T;
+
+declare function useComputed<T>(source: Computed<T>): T;
+
+declare function useDeepSignal<T extends object>(source: DeepSignal<T>): T;
+
+declare function useSnapshot<T>(handler: SnapshotHandler<T>): T;
+
+export { useComputed, useDeepSignal, useLogic, useSignal, useSnapshot };

package/dist/index.mjs

@@ -0,0 +1,97 @@
+import { useRef, useEffect, useCallback, useSyncExternalStore, useMemo } from 'react';
+import { cleanupLogic, mountLogic, createSignalHandler, createComputedHandler, createDeepSignalHandler } from '@sigrea/core';
+
+const scheduleMicrotask = (callback) => {
+  if (typeof globalThis.queueMicrotask === "function") {
+    globalThis.queueMicrotask(callback);
+    return;
+  }
+  Promise.resolve().then(callback);
+};
+function useLogic(logic, ...args) {
+  const props = args.length === 0 ? void 0 : args[0];
+  const stateRef = useRef(void 0);
+  const currentState = stateRef.current;
+  const shouldRemount = currentState === void 0 || currentState.logic !== logic || !Object.is(currentState.props, props);
+  if (shouldRemount) {
+    if (currentState !== void 0) {
+      cleanupLogic(currentState.instance);
+      stateRef.current = void 0;
+    }
+    const logicArgs = props === void 0 ? [] : [props];
+    stateRef.current = {
+      instance: mountLogic(logic, ...logicArgs),
+      logic,
+      props,
+      cleanupScheduled: false,
+      cleanupToken: 0
+    };
+  }
+  const state = stateRef.current;
+  if (state === void 0) {
+    throw new Error("useLogic failed to mount the requested logic instance.");
+  }
+  const instance = state.instance;
+  useEffect(() => {
+    const state2 = stateRef.current;
+    if (state2 === void 0 || state2.instance !== instance) {
+      return () => {
+      };
+    }
+    state2.cleanupScheduled = false;
+    return () => {
+      const latest = stateRef.current;
+      if (latest === void 0 || latest.instance !== instance) {
+        cleanupLogic(instance);
+        return;
+      }
+      latest.cleanupScheduled = true;
+      const token = latest.cleanupToken + 1;
+      latest.cleanupToken = token;
+      scheduleMicrotask(() => {
+        const updated = stateRef.current;
+        if (updated === void 0 || updated.instance !== instance || !updated.cleanupScheduled || updated.cleanupToken !== token) {
+          return;
+        }
+        updated.cleanupScheduled = false;
+        stateRef.current = void 0;
+        cleanupLogic(instance);
+      });
+    };
+  }, [instance]);
+  return instance;
+}
+
+function useSnapshot(handler) {
+  const subscribe = useCallback(
+    (onStoreChange) => handler.subscribe(onStoreChange),
+    [handler]
+  );
+  const getSnapshot = useCallback(() => handler.getSnapshot(), [handler]);
+  const snapshot = useSyncExternalStore(
+    subscribe,
+    getSnapshot,
+    getSnapshot
+  );
+  return snapshot.value;
+}
+
+function useSignal(source) {
+  const handler = useMemo(
+    () => createSignalHandler(source),
+    [source]
+  );
+  return useSnapshot(handler);
+}
+
+function useComputed(source) {
+  const handler = useMemo(() => createComputedHandler(source), [source]);
+  return useSnapshot(handler);
+}
+
+function useDeepSignal(source) {
+  const handler = useMemo(() => createDeepSignalHandler(source), [source]);
+  return useSnapshot(handler);
+}
+
+export { useComputed, useDeepSignal, useLogic, useSignal, useSnapshot };

package/package.json

@@ -0,0 +1,72 @@
+{
+  "name": "@sigrea/react",
+  "version": "0.1.0",
+  "description": "React adapter bindings for Sigrea logic modules.",
+  "license": "MIT",
+  "type": "module",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/sigrea/react.git"
+  },
+  "homepage": "https://github.com/sigrea/react#readme",
+  "bugs": {
+    "url": "https://github.com/sigrea/react/issues"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "main": "./dist/index.cjs",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "keywords": [
+    "signals",
+    "reactivity",
+    "react",
+    "logic",
+    "typescript"
+  ],
+  "peerDependencies": {
+    "@sigrea/core": "^0.1.0",
+    "react": "^18.0.0 || ^19.0.0",
+    "react-dom": "^18.0.0 || ^19.0.0"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "1.9.4",
+    "@vitejs/plugin-react": "^4.3.3",
+    "@changesets/cli": "^2.29.6",
+    "@types/react": "^19.0.0",
+    "@types/react-dom": "^19.0.0",
+    "@vitest/coverage-v8": "^3.2.4",
+    "lefthook": "1.13.6",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
+    "tsx": "^4.20.5",
+    "typescript": "5.9.3",
+    "unbuild": "3.6.1",
+    "vite": "^5.4.6",
+    "vitest": "^3.2.4",
+    "jsdom": "^24.1.3"
+  },
+  "scripts": {
+    "dev": "vite --config playground/vite.config.ts",
+    "build": "unbuild",
+    "test": "vitest run",
+    "test:coverage": "vitest --coverage",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "format": "biome check .",
+    "format:fix": "biome check --write ."
+  }
+}