@sigrea/vue 0.1.0 → 0.2.0

package/README.md

@@ -1,29 +1,44 @@
 # @sigrea/vue
 
-`@sigrea/vue` adapts [@sigrea/core](https://www.npmjs.com/package/@sigrea/core) logic modules and signals to Vue 3’s Composition API. It keeps lifecycle scopes aligned with component mounts, forwards deep reactivity, and ships composables that feel first-class inside `<script setup>` or traditional setup functions.
-
-## Installation
+`@sigrea/vue` adapts [@sigrea/core](https://www.npmjs.com/package/@sigrea/core) logic modules and signals for Vue 3's Composition API. It aligns lifecycle scopes with component lifecycles, preserves deep reactivity, and provides composables for `<script setup>` and traditional setup functions.
+
+- **Signal subscriptions.** `useSignal` subscribes to signals and computed values, returning a readonly ref that updates when they change.
+- **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`.
+- **Logic lifecycles.** `useLogic` mounts logic factories and binds their lifecycles to Vue components.
+
+## Table of Contents
+
+- [Install](#install)
+- [Quick Start](#quick-start)
+  - [Consume a Signal](#consume-a-signal)
+  - [Bridge Framework-Agnostic Logic](#bridge-framework-agnostic-logic)
+  - [Bind Writable Primitive Signals](#bind-writable-primitive-signals)
+  - [Bind Deep Reactive Objects](#bind-deep-reactive-objects)
+- [API Reference](#api-reference)
+  - [useSignal](#usesignal)
+  - [useComputed](#usecomputed)
+  - [useDeepSignal](#usedeepsignal)
+  - [useMutableSignal](#usemutablesignal)
+  - [useLogic](#uselogic)
+- [Testing](#testing)
+- [Development](#development)
+- [License](#license)
+
+## Install
 
 ```bash
-pnpm add @sigrea/vue @sigrea/core vue
+npm install @sigrea/vue @sigrea/core vue
 ```
 
-Vue 3.4+ and Node.js 20+ are required. Equivalent npm or yarn commands work as expected.
-
-## What This Adapter Provides
-
-- **Signal readers** – `useSignal` consumes shallow signals and computed values inside Vue components.
-- **Deep signal access** – `useDeepSignal` exposes deeply reactive objects with automatic cleanup.
-- **Derived state** – `useComputed` mirrors Vue’s `computed`, but tracks through Sigrea scopes.
-- **Logic lifecycles** – `useLogic` mounts `defineLogic` factories while honoring `onMount` / `onUnmount`.
-- **Snapshots** – `useSnapshot` grants direct access to low-level signal handlers when needed.
-- **Writable bridge** – `useMutableSignal` exposes primitive `signal()` values as `WritableComputedRef`s for two-way bindings.
+Requires Vue 3.4+ and Node.js 20 or later.
 
 ## Quick Start
 
-### Consume a signal
+### Consume a Signal
 
-```ts
+```vue
 <script setup lang="ts">
 import { signal } from "@sigrea/core";
 import { useSignal } from "@sigrea/vue";
@@ -33,36 +48,35 @@ const value = useSignal(count);
 </script>
 
 <template>
-	<span>{{ value }}</span>
+  <span>{{ value }}</span>
 </template>
 ```
 
-### Bridge framework-agnostic logic
+### Bridge Framework-Agnostic Logic
 
 ```ts
 // CounterLogic.ts
 import { defineLogic, signal } from "@sigrea/core";
 
 export const CounterLogic = defineLogic<{ initialCount: number }>()((props) => {
-	const count = signal(props.initialCount);
+  const count = signal(props.initialCount);
 
-	const increment = () => {
-		count.value += 1;
-	};
+  const increment = () => {
+    count.value += 1;
+  };
 
-	const reset = () => {
-		count.value = props.initialCount;
-	};
+  const reset = () => {
+    count.value = props.initialCount;
+  };
 
-	return { count, increment, reset };
+  return { count, increment, reset };
 });
 ```
 
-```ts
-// Counter.vue
+```vue
+<!-- Counter.vue -->
 <script setup lang="ts">
 import { useLogic, useSignal } from "@sigrea/vue";
-
 import { CounterLogic } from "./CounterLogic";
 
 const props = defineProps<{ initialCount: number }>();
@@ -71,17 +85,17 @@ const value = useSignal(counter.count);
 </script>
 
 <template>
-	<div>
-		<span>{{ value }}</span>
-		<button @click="counter.increment">Increment</button>
-		<button @click="counter.reset">Reset</button>
-	</div>
+  <div>
+    <span>{{ value }}</span>
+    <button @click="counter.increment">Increment</button>
+    <button @click="counter.reset">Reset</button>
+  </div>
 </template>
 ```
 
-### Bind writable primitive signals
+### Bind Writable Primitive Signals
 
-```ts
+```vue
 <script setup lang="ts">
 import { signal } from "@sigrea/core";
 import { useMutableSignal } from "@sigrea/vue";
@@ -91,18 +105,18 @@ const model = useMutableSignal(count);
 </script>
 
 <template>
-	<label>
-		Count
-		<input type="number" v-model.number="model" />
-	</label>
+  <label>
+    Count
+    <input type="number" v-model.number="model" />
+  </label>
 </template>
 ```
 
 `useMutableSignal` expects a writable signal produced by `signal()`. Passing a readonly signal throws at runtime so incorrect bindings fail fast.
 
-### Bind deep reactive objects
+### Bind Deep Reactive Objects
 
-```ts
+```vue
 <script setup lang="ts">
 import { deepSignal } from "@sigrea/core";
 import { useDeepSignal } from "@sigrea/vue";
@@ -112,20 +126,90 @@ const model = useDeepSignal(profile);
 </script>
 
 <template>
-	<label>
-		Name
-		<input v-model="model.name" />
-	</label>
+  <label>
+    Name
+    <input v-model="model.name" />
+  </label>
 </template>
 ```
 
+## API Reference
+
+### useSignal
+
+```ts
+function useSignal<T>(
+  signal: Signal<T> | ReadonlySignal<T>
+): DeepReadonly<ShallowRef<T>>
+```
+
+Subscribes to a signal or computed value and returns a readonly Vue ref that updates when the signal changes. The subscription is cleaned up when the component unmounts.
+
+### useComputed
+
+```ts
+function useComputed<T>(source: Computed<T>): DeepReadonly<ShallowRef<T>>
+```
+
+Subscribes to a computed value and returns a readonly Vue ref that updates when the computed value changes. The subscription is cleaned up when the component unmounts.
+
+### useDeepSignal
+
+```ts
+function useDeepSignal<T extends object>(signal: DeepSignal<T>): ShallowRef<T>
+```
+
+Subscribes to a deep signal and returns a mutable Vue ref. Updates to the deep signal trigger reactivity, and the subscription is cleaned up when the component unmounts. Templates unwrap the ref automatically, so accessing nested properties requires no `.value`. In script blocks, use `state.value` to access the underlying object.
+
+### useMutableSignal
+
+```ts
+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.
+
+### useLogic
+
+```ts
+function useLogic<TReturn extends object, TProps = void>(
+  logic: LogicFunction<TReturn, TProps>,
+  ...args: LogicArgs<TProps>
+): LogicInstance<TReturn>
+```
+
+Mounts a logic factory and returns its LogicInstance. Sigrea augments the logic with lifecycle metadata: `onMount` callbacks run after the component mounts, and `onUnmount` callbacks run before it unmounts.
+
+## Testing
+
+```ts
+// tests/Counter.test.ts
+import { mount } from "@vue/test-utils";
+import { cleanupLogics } from "@sigrea/core";
+import Counter from "../components/Counter.vue";
+
+afterEach(() => cleanupLogics());
+
+it("increments and displays the updated count", async () => {
+  const wrapper = mount(Counter, {
+    props: { initialCount: 10 },
+  });
+
+  await wrapper.find("button").trigger("click");
+
+  expect(wrapper.text()).toContain("11");
+});
+```
+
 ## Development
 
-- `pnpm install` – install dependencies
-- `pnpm test` – run the Vitest suite
-- `pnpm build` – emit distributable artifacts
-- `pnpm dev` – launch the playground counter demo
+Development scripts prefer pnpm. npm or yarn work too, but pnpm keeps dependency resolution identical to CI.
+
+- `pnpm install` — install dependencies.
+- `pnpm test` — run the Vitest suite once (no watch).
+- `pnpm build` — compile via unbuild to produce dual CJS/ESM bundles.
+- `pnpm dev` — launch the playground counter demo.
 
 ## License
 
-MIT — see `LICENSE`.
+MIT — see [LICENSE](./LICENSE).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sigrea/vue",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Vue adapter bindings for Sigrea logic modules.",
   "license": "MIT",
   "type": "module",
@@ -39,15 +39,15 @@
     "typescript"
   ],
   "peerDependencies": {
-    "@sigrea/core": "^0.1.0",
+    "@sigrea/core": "^0.3.1",
     "vue": "^3.4.0"
   },
   "devDependencies": {
     "@biomejs/biome": "1.9.4",
-    "@changesets/cli": "^2.29.6",
     "@vitejs/plugin-vue": "^5.1.4",
     "@vue/test-utils": "^2.4.0",
     "@vitest/coverage-v8": "^3.2.4",
+    "changelogen": "^0.6.2",
     "lefthook": "1.13.6",
     "tsx": "^4.20.5",
     "typescript": "5.9.3",
@@ -60,6 +60,8 @@
   "scripts": {
     "dev": "vite --config playground/vite.config.ts",
     "build": "unbuild",
+    "changelog": "changelogen",
+    "release": "pnpm test && pnpm build && changelogen --release",
     "test": "vitest run",
     "test:coverage": "vitest --coverage",
     "typecheck": "tsc -p tsconfig.json --noEmit",