@sigrea/vue 0.3.1 → 0.5.0

package/README.md

@@ -6,7 +6,7 @@
 - **Computed subscriptions.** `useComputed` subscribes to computed values, mirroring Vue's `computed` while tracking through Sigrea scopes.
 - **Deep signal subscriptions.** `useDeepSignal` subscribes to deep signal objects and exposes them as mutable refs with automatic cleanup.
 - **Two-way bindings.** `useMutableSignal` wraps primitive signals as `WritableComputedRef` for two-way bindings like `v-model`.
-- **Molecule lifecycles.** `useMolcule` mounts molecule factories and binds their lifecycles to Vue components.
+- **Molecule lifecycles.** `useMolecule` mounts molecule factories and binds their lifecycles to Vue components.
 
 ## Table of Contents
 
@@ -21,7 +21,7 @@
   - [useComputed](#usecomputed)
   - [useDeepSignal](#usedeepsignal)
   - [useMutableSignal](#usemutablesignal)
-  - [useMolcule](#usemolcule)
+  - [useMolecule](#usemolecule)
 - [Testing](#testing)
 - [Handling Scope Cleanup Errors](#handling-scope-cleanup-errors)
 - [Development](#development)
@@ -57,39 +57,62 @@ const value = useSignal(count);
 
 ```ts
 // CounterMolecule.ts
-import { molecule, signal } from "@sigrea/core";
+import { molecule, readonly, signal } from "@sigrea/core";
 
-export const CounterMolecule = molecule((props: { initialCount: number }) => {
+type CounterProps = {
+  initialCount: number;
+  initialStep: number;
+};
+
+export const CounterMolecule = molecule((props: CounterProps) => {
   const count = signal(props.initialCount);
+  const step = signal(props.initialStep);
 
-  const increment = () => {
-    count.value += 1;
-  };
+  function setStep(next: number) {
+    step.value = next;
+  }
+
+  function increment() {
+    count.value += step.value;
+  }
 
-  const reset = () => {
+  function reset() {
     count.value = props.initialCount;
-  };
+  }
 
-  return { count, increment, reset };
+  return {
+    count: readonly(count),
+    step: readonly(step),
+    setStep,
+    increment,
+    reset,
+  };
 });
 ```
 
 ```vue
 <!-- Counter.vue -->
 <script setup lang="ts">
-import { useMolcule, useSignal } from "@sigrea/vue";
+import { useMolecule, useSignal } from "@sigrea/vue";
 import { CounterMolecule } from "./CounterMolecule";
 
-const props = defineProps<{ initialCount: number }>();
-const counter = useMolcule(CounterMolecule, props);
-const value = useSignal(counter.count);
+const props = defineProps<{ initialCount: number; initialStep: number }>();
+
+const counter = useMolecule(CounterMolecule, {
+  initialCount: props.initialCount,
+  initialStep: props.initialStep,
+});
+
+const count = useSignal(counter.count);
+const step = useSignal(counter.step);
 </script>
 
 <template>
   <div>
-    <span>{{ value }}</span>
+    <span>{{ count }}</span>
     <button @click="counter.increment">Increment</button>
     <button @click="counter.reset">Reset</button>
+    <button @click="counter.setStep(step + 1)">Step +</button>
   </div>
 </template>
 ```
@@ -122,7 +145,7 @@ const model = useMutableSignal(count);
 import { deepSignal } from "@sigrea/core";
 import { useDeepSignal } from "@sigrea/vue";
 
-const profile = deepSignal({ name: "Sigrea" });
+const profile = deepSignal({ name: "Mendako" });
 const model = useDeepSignal(profile);
 </script>
 
@@ -170,10 +193,10 @@ function useMutableSignal<T>(signal: Signal<T>): WritableComputedRef<T>
 
 Wraps a Sigrea signal as a Vue `WritableComputedRef` for two-way bindings like `v-model`. Expects a writable signal created by `signal()`. Passing a readonly signal throws at runtime.
 
-### useMolcule
+### useMolecule
 
 ```ts
-function useMolcule<TReturn extends object, TProps = void>(
+function useMolecule<TReturn extends object, TProps extends object | void = void>(
   molecule: MoleculeFactory<TReturn, TProps>,
   ...args: MoleculeArgs<TProps>
 ): MoleculeInstance<TReturn>
@@ -181,6 +204,20 @@ function useMolcule<TReturn extends object, TProps = void>(
 
 Mounts a molecule factory and returns its MoleculeInstance. Sigrea augments the molecule with lifecycle metadata: `onMount` callbacks run after the component mounts, and `onUnmount` callbacks run before it unmounts.
 
+**KeepAlive Support**
+
+When used inside Vue's `<KeepAlive>`, molecule side effects are automatically managed for optimal resource efficiency:
+
+- **On deactivation** (`onDeactivated`): `watch` effects and ongoing work are paused via `unmountMolecule`. The molecule instance itself remains alive, preserving its internal state.
+- **On reactivation** (`onActivated`): Side effects resume via `mountMolecule`, allowing watches and subscriptions to pick up where they left off.
+- **On final unmount**: The molecule is fully disposed via `disposeMolecule`, releasing all resources.
+
+This design prevents unnecessary computation and subscriptions while components are cached but invisible, reducing CPU and memory usage without losing state.
+
+**Props Handling**
+
+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`).
+
 ## Testing
 
 ```ts

package/dist/index.cjs

@@ -3,13 +3,31 @@
 const vue = require('vue');
 const core = require('@sigrea/core');
 
-function useMolcule(molecule, ...args) {
+function useMolecule(molecule, ...args) {
   if (vue.getCurrentInstance() === null) {
     throw new Error(
-      "useMolcule can only be used within a Vue component setup()."
+      "useMolecule can only be used within a Vue component setup()."
     );
   }
-  const instance = molecule(...args);
+  const props = args.length === 0 ? void 0 : args[0];
+  if (props !== void 0 && (typeof props !== "object" || props === null)) {
+    throw new TypeError("useMolecule props must be an object.");
+  }
+  const snapshot = props === void 0 ? void 0 : { ...vue.toRaw(props) };
+  const moleculeArgs = snapshot === void 0 ? [] : [snapshot];
+  const instance = molecule(...moleculeArgs);
+  vue.onMounted(() => {
+    core.mountMolecule(instance);
+  });
+  vue.onActivated(() => {
+    core.mountMolecule(instance);
+  });
+  vue.onDeactivated(() => {
+    core.unmountMolecule(instance);
+  });
+  vue.onBeforeUnmount(() => {
+    core.unmountMolecule(instance);
+  });
   vue.onScopeDispose(() => {
     core.disposeMolecule(instance);
   });
@@ -85,7 +103,7 @@ function useMutableSignal(source) {
 
 exports.useComputed = useComputed;
 exports.useDeepSignal = useDeepSignal;
-exports.useMolcule = useMolcule;
+exports.useMolecule = useMolecule;
 exports.useMutableSignal = useMutableSignal;
 exports.useSignal = useSignal;
 exports.useSnapshot = useSnapshot;

package/dist/index.d.cts

@@ -2,7 +2,7 @@ import { MoleculeFactory, MoleculeArgs, MoleculeInstance, Signal, ReadonlySignal
 import * as vue from 'vue';
 import { DeepReadonly, ShallowRef } from 'vue';
 
-declare function useMolcule<TReturn extends object, TProps = void>(molecule: MoleculeFactory<TReturn, TProps>, ...args: MoleculeArgs<TProps>): MoleculeInstance<TReturn>;
+declare function useMolecule<TReturn extends object, TProps extends object | void = void>(molecule: MoleculeFactory<TReturn, TProps>, ...args: MoleculeArgs<TProps>): MoleculeInstance<TReturn>;
 
 type ReadableSignal<T> = Signal<T> | ReadonlySignal<T>;
 declare function useSignal<T>(source: ReadableSignal<T>): Readonly<vue.Ref<vue.DeepReadonly<T>, vue.DeepReadonly<T>>>;
@@ -21,4 +21,4 @@ declare function useSnapshot<T>(handler: SnapshotHandler<T>, options: UseSnapsho
     mode: "mutable";
 }): ShallowRef<T>;
 
-export { useComputed, useDeepSignal, useMolcule, useMutableSignal, useSignal, useSnapshot };
+export { useComputed, useDeepSignal, useMolecule, useMutableSignal, useSignal, useSnapshot };

package/dist/index.d.mts

@@ -2,7 +2,7 @@ import { MoleculeFactory, MoleculeArgs, MoleculeInstance, Signal, ReadonlySignal
 import * as vue from 'vue';
 import { DeepReadonly, ShallowRef } from 'vue';
 
-declare function useMolcule<TReturn extends object, TProps = void>(molecule: MoleculeFactory<TReturn, TProps>, ...args: MoleculeArgs<TProps>): MoleculeInstance<TReturn>;
+declare function useMolecule<TReturn extends object, TProps extends object | void = void>(molecule: MoleculeFactory<TReturn, TProps>, ...args: MoleculeArgs<TProps>): MoleculeInstance<TReturn>;
 
 type ReadableSignal<T> = Signal<T> | ReadonlySignal<T>;
 declare function useSignal<T>(source: ReadableSignal<T>): Readonly<vue.Ref<vue.DeepReadonly<T>, vue.DeepReadonly<T>>>;
@@ -21,4 +21,4 @@ declare function useSnapshot<T>(handler: SnapshotHandler<T>, options: UseSnapsho
     mode: "mutable";
 }): ShallowRef<T>;
 
-export { useComputed, useDeepSignal, useMolcule, useMutableSignal, useSignal, useSnapshot };
+export { useComputed, useDeepSignal, useMolecule, useMutableSignal, useSignal, useSnapshot };

package/dist/index.d.ts

@@ -2,7 +2,7 @@ import { MoleculeFactory, MoleculeArgs, MoleculeInstance, Signal, ReadonlySignal
 import * as vue from 'vue';
 import { DeepReadonly, ShallowRef } from 'vue';
 
-declare function useMolcule<TReturn extends object, TProps = void>(molecule: MoleculeFactory<TReturn, TProps>, ...args: MoleculeArgs<TProps>): MoleculeInstance<TReturn>;
+declare function useMolecule<TReturn extends object, TProps extends object | void = void>(molecule: MoleculeFactory<TReturn, TProps>, ...args: MoleculeArgs<TProps>): MoleculeInstance<TReturn>;
 
 type ReadableSignal<T> = Signal<T> | ReadonlySignal<T>;
 declare function useSignal<T>(source: ReadableSignal<T>): Readonly<vue.Ref<vue.DeepReadonly<T>, vue.DeepReadonly<T>>>;
@@ -21,4 +21,4 @@ declare function useSnapshot<T>(handler: SnapshotHandler<T>, options: UseSnapsho
     mode: "mutable";
 }): ShallowRef<T>;
 
-export { useComputed, useDeepSignal, useMolcule, useMutableSignal, useSignal, useSnapshot };
+export { useComputed, useDeepSignal, useMolecule, useMutableSignal, useSignal, useSnapshot };

package/dist/index.mjs

@@ -1,13 +1,31 @@
-import { getCurrentInstance, onScopeDispose, shallowRef, readonly, triggerRef, computed } from 'vue';
-import { disposeMolecule, createSignalHandler, createComputedHandler, createDeepSignalHandler } from '@sigrea/core';
+import { getCurrentInstance, toRaw, onMounted, onActivated, onDeactivated, onBeforeUnmount, onScopeDispose, shallowRef, readonly, triggerRef, computed } from 'vue';
+import { mountMolecule, unmountMolecule, disposeMolecule, createSignalHandler, createComputedHandler, createDeepSignalHandler } from '@sigrea/core';
 
-function useMolcule(molecule, ...args) {
+function useMolecule(molecule, ...args) {
   if (getCurrentInstance() === null) {
     throw new Error(
-      "useMolcule can only be used within a Vue component setup()."
+      "useMolecule can only be used within a Vue component setup()."
     );
   }
-  const instance = molecule(...args);
+  const props = args.length === 0 ? void 0 : args[0];
+  if (props !== void 0 && (typeof props !== "object" || props === null)) {
+    throw new TypeError("useMolecule props must be an object.");
+  }
+  const snapshot = props === void 0 ? void 0 : { ...toRaw(props) };
+  const moleculeArgs = snapshot === void 0 ? [] : [snapshot];
+  const instance = molecule(...moleculeArgs);
+  onMounted(() => {
+    mountMolecule(instance);
+  });
+  onActivated(() => {
+    mountMolecule(instance);
+  });
+  onDeactivated(() => {
+    unmountMolecule(instance);
+  });
+  onBeforeUnmount(() => {
+    unmountMolecule(instance);
+  });
   onScopeDispose(() => {
     disposeMolecule(instance);
   });
@@ -81,4 +99,4 @@ function useMutableSignal(source) {
   });
 }
 
-export { useComputed, useDeepSignal, useMolcule, useMutableSignal, useSignal, useSnapshot };
+export { useComputed, useDeepSignal, useMolecule, useMutableSignal, useSignal, useSnapshot };

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@sigrea/vue",
-	"version": "0.3.1",
+	"version": "0.5.0",
 	"description": "Vue adapter bindings for Sigrea molecule modules.",
 	"license": "MIT",
 	"type": "module",
@@ -53,23 +53,25 @@
 		"cicheck": "pnpm test && pnpm typecheck && pnpm format:fix"
 	},
 	"peerDependencies": {
-		"@sigrea/core": "^0.4.3",
+		"@sigrea/core": "^0.5.0",
 		"vue": "^3.4.0"
 	},
 	"devDependencies": {
 		"@biomejs/biome": "1.9.4",
+		"@sigrea/core": "^0.5.0",
 		"@vitejs/plugin-vue": "^5.1.4",
-		"@vue/test-utils": "^2.4.0",
 		"@vitest/coverage-v8": "^3.2.4",
+		"@vue/test-utils": "^2.4.0",
+		"baseline-browser-mapping": "^2.9.13",
 		"changelogen": "^0.6.2",
+		"jsdom": "^24.1.3",
 		"lefthook": "1.13.6",
 		"tsx": "^4.20.5",
 		"typescript": "5.9.3",
 		"unbuild": "3.6.1",
 		"vite": "^5.4.6",
 		"vitest": "^3.2.4",
-		"vue": "^3.4.0",
-		"jsdom": "^24.1.3"
+		"vue": "^3.4.0"
 	},
 	"pnpm": {
 		"onlyBuiltDependencies": [