@sigrea/react 0.3.1 → 0.5.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (7) hide show
  1. package/README.md +53 -22
  2. package/dist/index.cjs +15 -7
  3. package/dist/index.d.cts +2 -2
  4. package/dist/index.d.mts +2 -2
  5. package/dist/index.d.ts +2 -2
  6. package/dist/index.mjs +17 -9
  7. package/package.json +8 -6
package/README.md CHANGED
@@ -5,7 +5,7 @@
5
5
  - **Signal subscriptions.** `useSignal` subscribes to signals and computed values, triggering re-renders when they change.
6
6
  - **Computed subscriptions.** `useComputed` subscribes to computed values and memoizes them per component instance.
7
7
  - **Deep signal subscriptions.** `useDeepSignal` subscribes to deep signal objects and exposes them for direct mutation.
8
- - **Molecule lifecycles.** `useMolcule` mounts molecule factories and binds their lifecycles to React components.
8
+ - **Molecule lifecycles.** `useMolecule` mounts molecule factories and binds their lifecycles to React components.
9
9
 
10
10
  ## Table of Contents
11
11
 
@@ -18,7 +18,7 @@
18
18
  - [useSignal](#usesignal)
19
19
  - [useComputed](#usecomputed)
20
20
  - [useDeepSignal](#usedeepsignal)
21
- - [useMolcule](#usemolcule)
21
+ - [useMolecule](#usemolecule)
22
22
  - [Testing](#testing)
23
23
  - [Handling Scope Cleanup Errors](#handling-scope-cleanup-errors)
24
24
  - [Development](#development)
@@ -51,32 +51,50 @@ export function CounterLabel() {
51
51
  ### Bridge Framework-Agnostic Molecules
52
52
 
53
53
  ```tsx
54
- import { molecule, signal } from "@sigrea/core";
55
- import { useMolcule, useSignal } from "@sigrea/react";
54
+ import { molecule, readonly, signal } from "@sigrea/core";
55
+ import { useMolecule, useSignal } from "@sigrea/react";
56
56
 
57
- const CounterMolecule = molecule((props: { initialCount: number }) => {
57
+ type CounterProps = {
58
+ initialCount: number;
59
+ initialStep: number;
60
+ };
61
+
62
+ const CounterMolecule = molecule((props: CounterProps) => {
58
63
  const count = signal(props.initialCount);
64
+ const step = signal(props.initialStep);
59
65
 
60
- const increment = () => {
61
- count.value += 1;
62
- };
66
+ function setStep(next: number) {
67
+ step.value = next;
68
+ }
63
69
 
64
- const reset = () => {
70
+ function increment() {
71
+ count.value += step.value;
72
+ }
73
+
74
+ function reset() {
65
75
  count.value = props.initialCount;
66
- };
76
+ }
67
77
 
68
- return { count, increment, reset };
78
+ return {
79
+ count: readonly(count),
80
+ step: readonly(step),
81
+ setStep,
82
+ increment,
83
+ reset,
84
+ };
69
85
  });
70
86
 
71
- export function Counter(props: { initialCount: number }) {
72
- const counter = useMolcule(CounterMolecule, props);
73
- const value = useSignal(counter.count);
87
+ export function Counter(props: CounterProps) {
88
+ const counter = useMolecule(CounterMolecule, props);
89
+ const count = useSignal(counter.count);
90
+ const step = useSignal(counter.step);
74
91
 
75
92
  return (
76
93
  <div>
77
- <span>{value}</span>
94
+ <span>{count}</span>
78
95
  <button onClick={counter.increment}>Increment</button>
79
96
  <button onClick={counter.reset}>Reset</button>
97
+ <button onClick={() => counter.setStep(step + 1)}>Step +</button>
80
98
  </div>
81
99
  );
82
100
  }
@@ -88,7 +106,7 @@ export function Counter(props: { initialCount: number }) {
88
106
  import { deepSignal } from "@sigrea/core";
89
107
  import { useDeepSignal } from "@sigrea/react";
90
108
 
91
- const form = deepSignal({ name: "Sigrea" });
109
+ const form = deepSignal({ name: "Mendako" });
92
110
 
93
111
  export function ProfileForm() {
94
112
  const state = useDeepSignal(form);
@@ -133,16 +151,29 @@ function useDeepSignal<T extends object>(signal: DeepSignal<T>): T
133
151
 
134
152
  Exposes a deep signal object for direct mutation within the component. Updates to nested properties trigger re-renders, and the subscription is cleaned up when the component unmounts.
135
153
 
136
- ### useMolcule
154
+ ### useMolecule
137
155
 
138
156
  ```tsx
139
- function useMolcule<TProps, TReturn>(
140
- molecule: MoleculeFactory<TProps, TReturn>,
141
- props?: TProps
142
- ): TReturn
157
+ function useMolecule<TReturn extends object, TProps extends object | void = void>(
158
+ molecule: MoleculeFactory<TReturn, TProps>,
159
+ ...args: MoleculeArgs<TProps>
160
+ ): MoleculeInstance<TReturn>
143
161
  ```
144
162
 
145
- Mounts a molecule factory and returns its public API. The molecule's scope is bound to the component lifecycle: `onMount` callbacks run after the component mounts, and `onUnmount` callbacks run before it unmounts.
163
+ Mounts a molecule factory and returns its MoleculeInstance. The molecule's scope is bound to the component lifecycle: `onMount` callbacks run after the component mounts, and `onUnmount` callbacks run before it unmounts.
164
+
165
+ **Lifecycle Timing**
166
+
167
+ Molecule lifecycles are bound to React's layout effects for precise timing control:
168
+
169
+ - In **browser environments**, molecule mounting happens synchronously after DOM updates but before paint (via `useLayoutEffect`). This matches Vue 3's `onMounted` timing, ensuring consistent behavior across frameworks.
170
+ - In **SSR environments**, lifecycle callbacks are deferred to `useEffect` to avoid hydration warnings while maintaining the same cleanup guarantees.
171
+
172
+ This design ensures that `onMount` callbacks and `watch` effects activate at the right moment—early enough to set up subscriptions before the first paint, yet safely after the component has committed to the DOM.
173
+
174
+ **Props Handling**
175
+
176
+ Props are treated as an initial snapshot. Updating component props does not recreate the molecule instance or update the snapshot; model dynamic values via signals or explicit molecule methods (for example, `setStep`).
146
177
 
147
178
  ## Testing
148
179
 
package/dist/index.cjs CHANGED
@@ -3,24 +3,28 @@
3
3
  const react = require('react');
4
4
  const core = require('@sigrea/core');
5
5
 
6
- function useMolcule(molecule, ...args) {
6
+ const useIsomorphicLayoutEffect = typeof window !== "undefined" ? react.useLayoutEffect : react.useEffect;
7
+ function useMolecule(molecule, ...args) {
7
8
  const props = args.length === 0 ? void 0 : args[0];
9
+ if (props !== void 0 && (typeof props !== "object" || props === null)) {
10
+ throw new TypeError("useMolecule props must be an object.");
11
+ }
8
12
  const stateRef = react.useRef(
9
13
  void 0
10
14
  );
11
15
  const currentState = stateRef.current;
12
- const shouldRemount = currentState === void 0 || currentState.molecule !== molecule || !Object.is(currentState.props, props);
16
+ const shouldRemount = currentState === void 0 || currentState.molecule !== molecule;
13
17
  if (shouldRemount) {
14
18
  if (currentState !== void 0) {
15
19
  currentState.pendingDisposeToken = null;
16
20
  core.disposeMolecule(currentState.instance);
17
21
  stateRef.current = void 0;
18
22
  }
19
- const moleculeArgs = props === void 0 ? [] : [props];
23
+ const snapshot = props === void 0 ? void 0 : { ...props };
24
+ const moleculeArgs = snapshot === void 0 ? [] : [snapshot];
20
25
  stateRef.current = {
21
26
  instance: molecule(...moleculeArgs),
22
27
  molecule,
23
- props,
24
28
  subscribers: 0,
25
29
  disposed: false,
26
30
  pendingDisposeToken: null
@@ -29,11 +33,11 @@ function useMolcule(molecule, ...args) {
29
33
  const state = stateRef.current;
30
34
  if (state === void 0) {
31
35
  throw new Error(
32
- "useMolcule failed to mount the requested molecule instance."
36
+ "useMolecule failed to mount the requested molecule instance."
33
37
  );
34
38
  }
35
39
  const instance = state.instance;
36
- react.useEffect(() => {
40
+ useIsomorphicLayoutEffect(() => {
37
41
  const state2 = stateRef.current;
38
42
  if (state2 === void 0 || state2.instance !== instance) {
39
43
  return () => {
@@ -43,6 +47,9 @@ function useMolcule(molecule, ...args) {
43
47
  state2.pendingDisposeToken = null;
44
48
  }
45
49
  state2.subscribers += 1;
50
+ if (state2.subscribers === 1) {
51
+ core.mountMolecule(instance);
52
+ }
46
53
  return () => {
47
54
  const latest = stateRef.current;
48
55
  if (latest === void 0 || latest.instance !== instance) {
@@ -54,6 +61,7 @@ function useMolcule(molecule, ...args) {
54
61
  latest.subscribers = 0;
55
62
  }
56
63
  if (!latest.disposed && latest.subscribers === 0) {
64
+ core.unmountMolecule(instance);
57
65
  const token = Symbol("pending-dispose");
58
66
  latest.pendingDisposeToken = token;
59
67
  queueMicrotask(() => {
@@ -106,6 +114,6 @@ function useDeepSignal(source) {
106
114
 
107
115
  exports.useComputed = useComputed;
108
116
  exports.useDeepSignal = useDeepSignal;
109
- exports.useMolcule = useMolcule;
117
+ exports.useMolecule = useMolecule;
110
118
  exports.useSignal = useSignal;
111
119
  exports.useSnapshot = useSnapshot;
package/dist/index.d.cts CHANGED
@@ -1,6 +1,6 @@
1
1
  import { MoleculeFactory, MoleculeArgs, MoleculeInstance, Signal, ReadonlySignal, Computed, DeepSignal, SnapshotHandler } from '@sigrea/core';
2
2
 
3
- declare function useMolcule<TReturn extends object, TProps = void>(molecule: MoleculeFactory<TReturn, TProps>, ...args: MoleculeArgs<TProps>): MoleculeInstance<TReturn>;
3
+ declare function useMolecule<TReturn extends object, TProps extends object | void = void>(molecule: MoleculeFactory<TReturn, TProps>, ...args: MoleculeArgs<TProps>): MoleculeInstance<TReturn>;
4
4
 
5
5
  type ReadableSignal<T> = Signal<T> | ReadonlySignal<T>;
6
6
  declare function useSignal<T>(source: ReadableSignal<T>): T;
@@ -11,4 +11,4 @@ declare function useDeepSignal<T extends object>(source: DeepSignal<T>): T;
11
11
 
12
12
  declare function useSnapshot<T>(handler: SnapshotHandler<T>): T;
13
13
 
14
- export { useComputed, useDeepSignal, useMolcule, useSignal, useSnapshot };
14
+ export { useComputed, useDeepSignal, useMolecule, useSignal, useSnapshot };
package/dist/index.d.mts CHANGED
@@ -1,6 +1,6 @@
1
1
  import { MoleculeFactory, MoleculeArgs, MoleculeInstance, Signal, ReadonlySignal, Computed, DeepSignal, SnapshotHandler } from '@sigrea/core';
2
2
 
3
- declare function useMolcule<TReturn extends object, TProps = void>(molecule: MoleculeFactory<TReturn, TProps>, ...args: MoleculeArgs<TProps>): MoleculeInstance<TReturn>;
3
+ declare function useMolecule<TReturn extends object, TProps extends object | void = void>(molecule: MoleculeFactory<TReturn, TProps>, ...args: MoleculeArgs<TProps>): MoleculeInstance<TReturn>;
4
4
 
5
5
  type ReadableSignal<T> = Signal<T> | ReadonlySignal<T>;
6
6
  declare function useSignal<T>(source: ReadableSignal<T>): T;
@@ -11,4 +11,4 @@ declare function useDeepSignal<T extends object>(source: DeepSignal<T>): T;
11
11
 
12
12
  declare function useSnapshot<T>(handler: SnapshotHandler<T>): T;
13
13
 
14
- export { useComputed, useDeepSignal, useMolcule, useSignal, useSnapshot };
14
+ export { useComputed, useDeepSignal, useMolecule, useSignal, useSnapshot };
package/dist/index.d.ts CHANGED
@@ -1,6 +1,6 @@
1
1
  import { MoleculeFactory, MoleculeArgs, MoleculeInstance, Signal, ReadonlySignal, Computed, DeepSignal, SnapshotHandler } from '@sigrea/core';
2
2
 
3
- declare function useMolcule<TReturn extends object, TProps = void>(molecule: MoleculeFactory<TReturn, TProps>, ...args: MoleculeArgs<TProps>): MoleculeInstance<TReturn>;
3
+ declare function useMolecule<TReturn extends object, TProps extends object | void = void>(molecule: MoleculeFactory<TReturn, TProps>, ...args: MoleculeArgs<TProps>): MoleculeInstance<TReturn>;
4
4
 
5
5
  type ReadableSignal<T> = Signal<T> | ReadonlySignal<T>;
6
6
  declare function useSignal<T>(source: ReadableSignal<T>): T;
@@ -11,4 +11,4 @@ declare function useDeepSignal<T extends object>(source: DeepSignal<T>): T;
11
11
 
12
12
  declare function useSnapshot<T>(handler: SnapshotHandler<T>): T;
13
13
 
14
- export { useComputed, useDeepSignal, useMolcule, useSignal, useSnapshot };
14
+ export { useComputed, useDeepSignal, useMolecule, useSignal, useSnapshot };
package/dist/index.mjs CHANGED
@@ -1,24 +1,28 @@
1
- import { useRef, useEffect, useCallback, useSyncExternalStore, useMemo } from 'react';
2
- import { disposeMolecule, createSignalHandler, createComputedHandler, createDeepSignalHandler } from '@sigrea/core';
1
+ import { useRef, useLayoutEffect, useEffect, useCallback, useSyncExternalStore, useMemo } from 'react';
2
+ import { disposeMolecule, mountMolecule, unmountMolecule, createSignalHandler, createComputedHandler, createDeepSignalHandler } from '@sigrea/core';
3
3
 
4
- function useMolcule(molecule, ...args) {
4
+ const useIsomorphicLayoutEffect = typeof window !== "undefined" ? useLayoutEffect : useEffect;
5
+ function useMolecule(molecule, ...args) {
5
6
  const props = args.length === 0 ? void 0 : args[0];
7
+ if (props !== void 0 && (typeof props !== "object" || props === null)) {
8
+ throw new TypeError("useMolecule props must be an object.");
9
+ }
6
10
  const stateRef = useRef(
7
11
  void 0
8
12
  );
9
13
  const currentState = stateRef.current;
10
- const shouldRemount = currentState === void 0 || currentState.molecule !== molecule || !Object.is(currentState.props, props);
14
+ const shouldRemount = currentState === void 0 || currentState.molecule !== molecule;
11
15
  if (shouldRemount) {
12
16
  if (currentState !== void 0) {
13
17
  currentState.pendingDisposeToken = null;
14
18
  disposeMolecule(currentState.instance);
15
19
  stateRef.current = void 0;
16
20
  }
17
- const moleculeArgs = props === void 0 ? [] : [props];
21
+ const snapshot = props === void 0 ? void 0 : { ...props };
22
+ const moleculeArgs = snapshot === void 0 ? [] : [snapshot];
18
23
  stateRef.current = {
19
24
  instance: molecule(...moleculeArgs),
20
25
  molecule,
21
- props,
22
26
  subscribers: 0,
23
27
  disposed: false,
24
28
  pendingDisposeToken: null
@@ -27,11 +31,11 @@ function useMolcule(molecule, ...args) {
27
31
  const state = stateRef.current;
28
32
  if (state === void 0) {
29
33
  throw new Error(
30
- "useMolcule failed to mount the requested molecule instance."
34
+ "useMolecule failed to mount the requested molecule instance."
31
35
  );
32
36
  }
33
37
  const instance = state.instance;
34
- useEffect(() => {
38
+ useIsomorphicLayoutEffect(() => {
35
39
  const state2 = stateRef.current;
36
40
  if (state2 === void 0 || state2.instance !== instance) {
37
41
  return () => {
@@ -41,6 +45,9 @@ function useMolcule(molecule, ...args) {
41
45
  state2.pendingDisposeToken = null;
42
46
  }
43
47
  state2.subscribers += 1;
48
+ if (state2.subscribers === 1) {
49
+ mountMolecule(instance);
50
+ }
44
51
  return () => {
45
52
  const latest = stateRef.current;
46
53
  if (latest === void 0 || latest.instance !== instance) {
@@ -52,6 +59,7 @@ function useMolcule(molecule, ...args) {
52
59
  latest.subscribers = 0;
53
60
  }
54
61
  if (!latest.disposed && latest.subscribers === 0) {
62
+ unmountMolecule(instance);
55
63
  const token = Symbol("pending-dispose");
56
64
  latest.pendingDisposeToken = token;
57
65
  queueMicrotask(() => {
@@ -102,4 +110,4 @@ function useDeepSignal(source) {
102
110
  return useSnapshot(handler);
103
111
  }
104
112
 
105
- export { useComputed, useDeepSignal, useMolcule, useSignal, useSnapshot };
113
+ export { useComputed, useDeepSignal, useMolecule, useSignal, useSnapshot };
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@sigrea/react",
3
- "version": "0.3.1",
3
+ "version": "0.5.0",
4
4
  "description": "React adapter bindings for Sigrea molecule modules.",
5
5
  "license": "MIT",
6
6
  "type": "module",
@@ -53,17 +53,20 @@
53
53
  "cicheck": "pnpm test && pnpm typecheck && pnpm format:fix"
54
54
  },
55
55
  "peerDependencies": {
56
- "@sigrea/core": "^0.4.3",
56
+ "@sigrea/core": "^0.5.0",
57
57
  "react": "^18.0.0 || ^19.0.0",
58
58
  "react-dom": "^18.0.0 || ^19.0.0"
59
59
  },
60
60
  "devDependencies": {
61
61
  "@biomejs/biome": "1.9.4",
62
- "@vitejs/plugin-react": "^4.3.3",
62
+ "@sigrea/core": "^0.5.0",
63
63
  "@types/react": "^19.0.0",
64
64
  "@types/react-dom": "^19.0.0",
65
- "changelogen": "^0.6.2",
65
+ "@vitejs/plugin-react": "^4.3.3",
66
66
  "@vitest/coverage-v8": "^3.2.4",
67
+ "baseline-browser-mapping": "^2.9.13",
68
+ "changelogen": "^0.6.2",
69
+ "jsdom": "^24.1.3",
67
70
  "lefthook": "1.13.6",
68
71
  "react": "^19.0.0",
69
72
  "react-dom": "^19.0.0",
@@ -71,8 +74,7 @@
71
74
  "typescript": "5.9.3",
72
75
  "unbuild": "3.6.1",
73
76
  "vite": "^5.4.6",
74
- "vitest": "^3.2.4",
75
- "jsdom": "^24.1.3"
77
+ "vitest": "^3.2.4"
76
78
  },
77
79
  "pnpm": {
78
80
  "onlyBuiltDependencies": [