@virtuoso.dev/reactive-engine-react 0.0.4 → 0.2.0

package/dist/index.d.ts

@@ -56,8 +56,16 @@ export declare interface EngineProviderProps {
     children: React_2.ReactNode;
     /**
      * Optional stable ID for storage namespacing. Use this for multi-engine apps to prevent storage key conflicts.
+     * Also registers the engine in the global registry for access via `useRemote*` hooks with a string ID.
      */
     engineId?: string;
+    /**
+     * Optional reactive ref to expose the engine instance. Created by {@link useEngineRef}.
+     * Pass to `useRemote*` hooks to access the engine from sibling or ancestor components.
+     *
+     * @remarks An `EngineRef` should only be used with a single `EngineProvider`.
+     */
+    engineRef?: EngineRef;
     /**
      * A callback invoked once when the engine is created. Use this to register nodes and set up subscriptions.
      */
@@ -76,6 +84,40 @@ export declare interface EngineProviderProps {
     updateFn?: (engine: Engine) => void;
 }
 
+/**
+ * A reactive ref that holds an engine instance. Created by {@link useEngineRef}.
+ * Pass it to {@link EngineProvider} via the `engineRef` prop, then use it with
+ * the `useRemote*` hooks to access the engine from anywhere in the component tree.
+ *
+ * @remarks An `EngineRef` should only be used with a single `EngineProvider`.
+ * Using the same ref with multiple providers is unsupported.
+ *
+ * @category React Hooks and Components
+ */
+export declare interface EngineRef {
+    /** The current engine instance, or null if not yet available. */
+    readonly current: Engine | null;
+}
+
+/**
+ * Union type for the engine source parameter accepted by `useRemote*` hooks.
+ * Can be either a string engine ID (for global registry lookup) or an {@link EngineRef}.
+ *
+ * @category React Hooks and Components
+ */
+export declare type EngineSource = EngineRef | string;
+
+/**
+ * Options for the {@link useRemoteCellValues} hook.
+ * @category React Hooks and Components
+ */
+export declare interface RemoteCellValuesOptions<T extends unknown[]> {
+    cells: {
+        [K in keyof T]: Out<T[K]>;
+    };
+    engineSource: EngineSource;
+}
+
 /**
  * Returns a tuple of the current value of a cell and a publisher function (similar to `useState`).
  * The component re-renderes when the cell value changes.
@@ -187,6 +229,29 @@ declare function useCellValueWithStore<T>(cell: Out<T>): T;
  */
 export declare function useEngine(): Engine;
 
+/**
+ * Creates a stable, memoized {@link EngineRef} for use inside a component.
+ * Pass the returned ref to an {@link EngineProvider} via the `engineRef` prop,
+ * and to `useRemote*` hooks to access the engine reactively.
+ *
+ * @example
+ * ```tsx
+ * function App() {
+ *   const engineRef = useEngineRef()
+ *   return (
+ *     <>
+ *       <SiblingComponent engineRef={engineRef} />
+ *       <EngineProvider engineRef={engineRef} initFn={initFn}>
+ *         <NestedComponent />
+ *       </EngineProvider>
+ *     </>
+ *   )
+ * }
+ * ```
+ * @category React Hooks and Components
+ */
+export declare function useEngineRef(): EngineRef;
+
 export declare const useIsomorphicLayoutEffect: typeof React_2.useLayoutEffect;
 
 /**
@@ -213,4 +278,135 @@ export declare const useIsomorphicLayoutEffect: typeof React_2.useLayoutEffect;
  */
 export declare function usePublisher<T>(node$: Inp<T>): (value: T) => void;
 
+/**
+ * Returns a tuple of the current value and a publisher function for a cell in an engine identified by `engineSource`.
+ * Returns `[undefined, noop]` when the engine is not available yet.
+ *
+ * @param cell - The cell to use.
+ * @param engineSource - A string engine ID or an {@link EngineRef}.
+ * @returns A tuple of the current value (or undefined) and a publisher function.
+ * @typeParam T - The type of values that the cell emits/accepts.
+ *
+ * @example
+ * ```tsx
+ * const cell$ = Cell(0)
+ * // ...
+ * function SiblingComponent({ engineRef }: { engineRef: EngineRef }) {
+ *   const [value, setValue] = useRemoteCell(cell$, engineRef)
+ *   if (value === undefined) return <div>Loading...</div>
+ *   return <button onClick={() => setValue(value + 1)}>{value}</button>
+ * }
+ * ```
+ * @category React Hooks and Components
+ */
+export declare function useRemoteCell<T>(cell: NodeRef<T>, engineSource: EngineSource): [T | undefined, (value: T) => void];
+
+/**
+ * Gets the current value of the cell from an engine identified by `engineSource`.
+ * Returns `undefined` when the engine is not available yet.
+ *
+ * @param cell - The cell to read from.
+ * @param engineSource - A string engine ID or an {@link EngineRef} to read from.
+ * @returns The current value of the cell, or `undefined` if the engine is not available.
+ * @typeParam T - The type of the value that the cell carries.
+ *
+ * @example
+ * ```tsx
+ * const cell$ = Cell(0)
+ * // ...
+ * function SiblingComponent({ engineRef }: { engineRef: EngineRef }) {
+ *   const value = useRemoteCellValue(cell$, engineRef)
+ *   if (value === undefined) return <div>Loading...</div>
+ *   return <div>{value}</div>
+ * }
+ * ```
+ * @category React Hooks and Components
+ */
+export declare function useRemoteCellValue<T>(cell: Out<T>, engineSource: EngineSource): T | undefined;
+
+/**
+ * Returns the up-to-date values of the passed cells from an engine identified by `engineId`.
+ * Returns `undefined` when the engine is not available yet.
+ *
+ * @param options - An object containing the cells array and engineId.
+ * @returns An array with the current values of the cells, or `undefined` if the engine is not available.
+ *
+ * @example
+ * ```tsx
+ * const foo$ = Cell('foo')
+ * const bar$ = Cell('bar')
+ * // ...
+ * function SiblingComponent() {
+ *   const values = useRemoteCellValues({ cells: [foo$, bar$], engineId: 'my-engine' })
+ *   if (values === undefined) return <div>Loading...</div>
+ *   const [foo, bar] = values
+ *   return <div>{foo} - {bar}</div>
+ * }
+ * ```
+ * @category React Hooks and Components
+ */
+/** @hidden */
+export declare function useRemoteCellValues<T1>(options: RemoteCellValuesOptions<[T1]>): [T1] | undefined;
+
+/** @hidden */
+export declare function useRemoteCellValues<T1, T2>(options: RemoteCellValuesOptions<[T1, T2]>): [T1, T2] | undefined;
+
+/** @hidden */
+export declare function useRemoteCellValues<T1, T2, T3>(options: RemoteCellValuesOptions<[T1, T2, T3]>): [T1, T2, T3] | undefined;
+
+/** @hidden */
+export declare function useRemoteCellValues<T1, T2, T3, T4>(options: RemoteCellValuesOptions<[T1, T2, T3, T4]>): [T1, T2, T3, T4] | undefined;
+
+/** @hidden */
+export declare function useRemoteCellValues<T1, T2, T3, T4, T5>(options: RemoteCellValuesOptions<[T1, T2, T3, T4, T5]>): [T1, T2, T3, T4, T5] | undefined;
+
+/** @hidden */
+export declare function useRemoteCellValues<T1, T2, T3, T4, T5, T6>(options: RemoteCellValuesOptions<[T1, T2, T3, T4, T5, T6]>): [T1, T2, T3, T4, T5, T6] | undefined;
+
+/** @hidden */
+export declare function useRemoteCellValues<T1, T2, T3, T4, T5, T6, T7>(options: RemoteCellValuesOptions<[T1, T2, T3, T4, T5, T6, T7]>): [T1, T2, T3, T4, T5, T6, T7] | undefined;
+
+/** @hidden */
+export declare function useRemoteCellValues<T1, T2, T3, T4, T5, T6, T7, T8>(options: RemoteCellValuesOptions<[T1, T2, T3, T4, T5, T6, T7, T8]>): [T1, T2, T3, T4, T5, T6, T7, T8] | undefined;
+
+/** @hidden */
+export declare function useRemoteCellValues<T1, T2, T3, T4, T5, T6, T7, T8, T9>(options: RemoteCellValuesOptions<[T1, T2, T3, T4, T5, T6, T7, T8, T9]>): [T1, T2, T3, T4, T5, T6, T7, T8, T9] | undefined;
+
+/** @hidden */
+export declare function useRemoteCellValues<T1, T2, T3, T4, T5, T6, T7, T8, T9, T10>(options: RemoteCellValuesOptions<[T1, T2, T3, T4, T5, T6, T7, T8, T9, T10]>): [T1, T2, T3, T4, T5, T6, T7, T8, T9, T10] | undefined;
+
+/** @hidden */
+export declare function useRemoteCellValues<T1, T2, T3, T4, T5, T6, T7, T8, T9, T10, T11>(options: RemoteCellValuesOptions<[T1, T2, T3, T4, T5, T6, T7, T8, T9, T10, T11]>): [T1, T2, T3, T4, T5, T6, T7, T8, T9, T10, T11] | undefined;
+
+/** @hidden */
+export declare function useRemoteCellValues<T1, T2, T3, T4, T5, T6, T7, T8, T9, T10, T11, T12>(options: RemoteCellValuesOptions<[T1, T2, T3, T4, T5, T6, T7, T8, T9, T10, T11, T12]>): [T1, T2, T3, T4, T5, T6, T7, T8, T9, T10, T11, T12] | undefined;
+
+/** @hidden */
+export declare function useRemoteCellValues<T1, T2, T3, T4, T5, T6, T7, T8, T9, T10, T11, T12, T13>(options: RemoteCellValuesOptions<[T1, T2, T3, T4, T5, T6, T7, T8, T9, T10, T11, T12, T13]>): [T1, T2, T3, T4, T5, T6, T7, T8, T9, T10, T11, T12, T13] | undefined;
+
+/** @hidden */
+export declare function useRemoteCellValues(options: RemoteCellValuesOptions<unknown[]>): undefined | unknown[];
+
+/**
+ * Returns a function that publishes values to a node in an engine identified by `engineSource`.
+ * Returns a no-op function when the engine is not available yet.
+ *
+ * @param node$ - The node to publish to.
+ * @param engineSource - A string engine ID or an {@link EngineRef} to publish to.
+ * @returns A publisher function that accepts values of type T.
+ * @typeParam T - The type of values that the node accepts.
+ *
+ * @example
+ * ```tsx
+ * const trigger$ = Trigger()
+ * // ...
+ * function SiblingComponent({ engineRef }: { engineRef: EngineRef }) {
+ *   const publish = useRemotePublisher(trigger$, engineRef)
+ *   return <button onClick={() => publish()}>Trigger</button>
+ * }
+ * ```
+ * @category React Hooks and Components
+ */
+export declare function useRemotePublisher<T>(node$: Inp<T>, engineSource: EngineSource): (value: T) => void;
+
 export { }

package/dist/index.js

@@ -1,63 +1,185 @@
-import { jsx as C } from "react/jsx-runtime";
-import { Engine as E } from "@virtuoso.dev/reactive-engine-core";
-import * as u from "react";
-import b from "tiny-invariant";
-const a = typeof document < "u" ? u.useLayoutEffect : u.useEffect, g = u.createContext(null);
-function o() {
-  const e = u.useContext(g);
-  return b(e !== null, "useEngine must be used within an EngineProvider"), e;
+import { jsx as p } from "react/jsx-runtime";
+import { Engine as d } from "@virtuoso.dev/reactive-engine-core";
+import * as s from "react";
+import h from "tiny-invariant";
+const c = typeof document < "u" ? s.useLayoutEffect : s.useEffect, y = Symbol("engineRefInternal");
+function x() {
+  let e = null;
+  const n = /* @__PURE__ */ new Set();
+  return {
+    get current() {
+      return e;
+    },
+    [y]: {
+      set(r) {
+        e = r, n.forEach((u) => {
+          u();
+        });
+      },
+      subscribe(r) {
+        return n.add(r), () => {
+          n.delete(r);
+        };
+      }
+    }
+  };
+}
+function j() {
+  const [e] = s.useState(() => x());
+  return e;
+}
+function E(e) {
+  return e[y];
 }
+const f = /* @__PURE__ */ new Map();
 function S(e) {
-  const n = o();
+  let n = f.get(e);
+  return n || (n = { engine: null, subscribers: /* @__PURE__ */ new Set() }, f.set(e, n)), n;
+}
+function R(e, n) {
+  const t = S(e);
+  t.engine = n, t.subscribers.forEach((r) => {
+    r();
+  }), t.subscribers.size === 0 && n === null && f.delete(e);
+}
+function I(e, n) {
+  const t = S(e);
+  return t.subscribers.add(n), () => {
+    t.subscribers.delete(n), t.subscribers.size === 0 && t.engine === null && f.delete(e);
+  };
+}
+function m(e) {
+  var n;
+  return ((n = f.get(e)) == null ? void 0 : n.engine) ?? null;
+}
+const V = s.createContext(null);
+function a() {
+  const e = s.useContext(V);
+  return h(e !== null, "useEngine must be used within an EngineProvider"), e;
+}
+function w(e) {
+  const n = a();
   n.register(e);
-  const t = u.useCallback((r) => n.sub(e, r), [n, e]);
-  return u.useSyncExternalStore(
+  const t = s.useCallback((r) => n.sub(e, r), [n, e]);
+  return s.useSyncExternalStore(
     t,
     () => n.getValue(e),
     () => n.getValue(e)
   );
 }
-function V(e) {
-  const n = o();
+function P(e) {
+  const n = a();
   n.register(e);
-  const [t, r] = u.useState(() => n.getValue(e));
-  return a(() => n.sub(e, r), [n, e]), t;
+  const [t, r] = s.useState(() => n.getValue(e));
+  return c(() => n.sub(e, r), [n, e]), t;
 }
-const f = "useSyncExternalStore" in u ? S : V;
-function h(...e) {
-  const n = o(), t = u.useMemo(() => n.combineCells(e), [n, ...e]);
-  return f(t);
+const v = "useSyncExternalStore" in s ? w : P;
+function k(...e) {
+  const n = a(), t = s.useMemo(() => n.combineCells(e), [n, ...e]);
+  return v(t);
 }
-function x(e) {
-  const n = o();
-  return n.register(e), u.useCallback(
+function N(e) {
+  const n = a();
+  return n.register(e), s.useCallback(
     (t) => {
       n.pub(e, t);
     },
     [n, e]
   );
 }
-function P(e) {
-  return [f(e), x(e)];
-}
-const d = ({ children: e, engineId: n, initFn: t, initWith: r, updateDeps: l, updateFn: i }) => {
-  const [s, m] = u.useState(null);
-  return a(() => {
-    const c = new E(r, n);
-    return m(c), t == null || t(c), () => {
-      c.dispose();
+function A(e) {
+  return [v(e), N(e)];
+}
+function C(e) {
+  const n = typeof e != "string", t = n ? null : e, r = n ? e : null, [u, l] = s.useState(() => t ? m(t) : null);
+  c(() => {
+    if (!t) {
+      l(null);
+      return;
+    }
+    return l(m(t)), I(t, () => {
+      l(m(t));
+    });
+  }, [t]);
+  const [i, o] = s.useState(() => r ? r.current : null);
+  return c(() => {
+    if (!r) {
+      o(null);
+      return;
+    }
+    const b = E(r);
+    return o(r.current), b.subscribe(() => {
+      o(r.current);
+    });
+  }, [r]), n ? i : u;
+}
+function L(e, n) {
+  const t = C(n), [r, u] = s.useState(() => t ? t.getValue(e) : void 0);
+  return c(() => {
+    if (!t) {
+      u(void 0);
+      return;
+    }
+    return t.register(e), u(t.getValue(e)), t.sub(e, u);
+  }, [t, e]), r;
+}
+function M(e, n) {
+  const t = C(n);
+  return c(() => {
+    t && t.register(e);
+  }, [t, e]), s.useCallback(
+    (r) => {
+      t && t.pub(e, r);
+    },
+    [t, e]
+  );
+}
+function G(e, n) {
+  return [L(e, n), M(e, n)];
+}
+function O(e) {
+  const { cells: n, engineSource: t } = e, r = C(t), u = s.useMemo(() => r ? r.combineCells(n) : null, [r, ...n]), [l, i] = s.useState(
+    () => r && u ? r.getValue(u) : void 0
+  );
+  return c(() => {
+    if (!r || !u) {
+      i(void 0);
+      return;
+    }
+    return r.register(u), i(r.getValue(u)), r.sub(u, i);
+  }, [r, u]), l;
+}
+const W = ({
+  children: e,
+  engineId: n,
+  engineRef: t,
+  initFn: r,
+  initWith: u,
+  updateDeps: l,
+  updateFn: i
+}) => {
+  const [o, b] = s.useState(null);
+  return c(() => {
+    const g = new d(u, n);
+    return b(g), r == null || r(g), n && R(n, g), t && E(t).set(g), () => {
+      n && R(n, null), t && E(t).set(null), g.dispose();
     };
-  }, [r, n]), a(() => {
-    s && (i == null || i(s));
-  }, [s, ...l ?? []]), s && /* @__PURE__ */ C(g.Provider, { value: s, children: e });
+  }, [u, n, t]), c(() => {
+    o && (i == null || i(o));
+  }, [o, ...l ?? []]), o && /* @__PURE__ */ p(V.Provider, { value: o, children: e });
 };
 export {
-  g as EngineContext,
-  d as EngineProvider,
-  P as useCell,
-  f as useCellValue,
-  h as useCellValues,
-  o as useEngine,
-  a as useIsomorphicLayoutEffect,
-  x as usePublisher
+  V as EngineContext,
+  W as EngineProvider,
+  A as useCell,
+  v as useCellValue,
+  k as useCellValues,
+  a as useEngine,
+  j as useEngineRef,
+  c as useIsomorphicLayoutEffect,
+  N as usePublisher,
+  G as useRemoteCell,
+  L as useRemoteCellValue,
+  O as useRemoteCellValues,
+  M as useRemotePublisher
 };

package/package.json

@@ -3,7 +3,7 @@
   "private": false,
   "sideEffects": false,
   "type": "module",
-  "version": "0.0.4",
+  "version": "0.2.0",
   "module": "dist/index.js",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -21,13 +21,11 @@
     "tiny-invariant": "^1.3.3"
   },
   "peerDependencies": {
-    "@virtuoso.dev/reactive-engine-core": ">=0.0.3",
+    "@virtuoso.dev/reactive-engine-core": ">=0.0.4",
     "react": ">= 18",
     "react-dom": ">= 18"
   },
   "devDependencies": {
-    "@testing-library/jest-dom": "^6.9.1",
-    "@testing-library/react": "^16.3.0",
     "@types/node": "^22.10.1",
     "@types/react": "^19.2.7",
     "@types/react-dom": "^19.2.3",
@@ -35,7 +33,6 @@
     "@vitest/browser-playwright": "^4.0.16",
     "@vitejs/plugin-react": "^4.5.0",
     "eslint": "^9.24.0",
-    "jsdom": "^27.4.0",
     "playwright": "^1.33.0",
     "prettier": "^3.5.3",
     "react": "^19.2.3",
@@ -46,7 +43,7 @@
     "vitest": "^4.0.16",
     "vitest-browser-react": "^2.0.2",
     "@virtuoso.dev/tooling": "0.1.0",
-    "@virtuoso.dev/reactive-engine-core": "0.0.3"
+    "@virtuoso.dev/reactive-engine-core": "0.0.4"
   },
   "files": [
     "dist"