@sigrea/react 0.4.0 → 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 +48 -17
  2. package/dist/index.cjs +12 -4
  3. package/dist/index.d.cts +1 -1
  4. package/dist/index.d.mts +1 -1
  5. package/dist/index.d.ts +1 -1
  6. package/dist/index.mjs +14 -6
  7. package/package.json +8 -6
package/README.md CHANGED
@@ -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";
54
+ import { molecule, readonly, signal } from "@sigrea/core";
55
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 }) {
87
+ export function Counter(props: CounterProps) {
72
88
  const counter = useMolecule(CounterMolecule, props);
73
- const value = useSignal(counter.count);
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);
@@ -136,13 +154,26 @@ Exposes a deep signal object for direct mutation within the component. Updates t
136
154
  ### useMolecule
137
155
 
138
156
  ```tsx
139
- function useMolecule<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
+ const useIsomorphicLayoutEffect = typeof window !== "undefined" ? react.useLayoutEffect : react.useEffect;
6
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
@@ -33,7 +37,7 @@ function useMolecule(molecule, ...args) {
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 useMolecule(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 useMolecule(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(() => {
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 useMolecule<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;
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 useMolecule<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;
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 useMolecule<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;
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
+ const useIsomorphicLayoutEffect = typeof window !== "undefined" ? useLayoutEffect : useEffect;
4
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
@@ -31,7 +35,7 @@ function useMolecule(molecule, ...args) {
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 useMolecule(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 useMolecule(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(() => {
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@sigrea/react",
3
- "version": "0.4.0",
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": [