@sigrea/vue 0.1.0

package/README.md

@@ -0,0 +1,131 @@
+# @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
+
+```bash
+pnpm add @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.
+
+## Quick Start
+
+### Consume a signal
+
+```ts
+<script setup lang="ts">
+import { signal } from "@sigrea/core";
+import { useSignal } from "@sigrea/vue";
+
+const count = signal(0);
+const value = useSignal(count);
+</script>
+
+<template>
+	<span>{{ value }}</span>
+</template>
+```
+
+### 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 increment = () => {
+		count.value += 1;
+	};
+
+	const reset = () => {
+		count.value = props.initialCount;
+	};
+
+	return { count, increment, reset };
+});
+```
+
+```ts
+// Counter.vue
+<script setup lang="ts">
+import { useLogic, useSignal } from "@sigrea/vue";
+
+import { CounterLogic } from "./CounterLogic";
+
+const props = defineProps<{ initialCount: number }>();
+const counter = useLogic(CounterLogic, props);
+const value = useSignal(counter.count);
+</script>
+
+<template>
+	<div>
+		<span>{{ value }}</span>
+		<button @click="counter.increment">Increment</button>
+		<button @click="counter.reset">Reset</button>
+	</div>
+</template>
+```
+
+### Bind writable primitive signals
+
+```ts
+<script setup lang="ts">
+import { signal } from "@sigrea/core";
+import { useMutableSignal } from "@sigrea/vue";
+
+const count = signal(0);
+const model = useMutableSignal(count);
+</script>
+
+<template>
+	<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
+
+```ts
+<script setup lang="ts">
+import { deepSignal } from "@sigrea/core";
+import { useDeepSignal } from "@sigrea/vue";
+
+const profile = deepSignal({ name: "Sigrea" });
+const model = useDeepSignal(profile);
+</script>
+
+<template>
+	<label>
+		Name
+		<input v-model="model.name" />
+	</label>
+</template>
+```
+
+## Development
+
+- `pnpm install` – install dependencies
+- `pnpm test` – run the Vitest suite
+- `pnpm build` – emit distributable artifacts
+- `pnpm dev` – launch the playground counter demo
+
+## License
+
+MIT — see `LICENSE`.

package/dist/index.cjs

@@ -0,0 +1,91 @@
+'use strict';
+
+const vue = require('vue');
+const core = require('@sigrea/core');
+
+function useLogic(logic, ...args) {
+  if (vue.getCurrentInstance() === null) {
+    throw new Error(
+      "useLogic can only be used within a Vue component setup()."
+    );
+  }
+  const instance = core.mountLogic(logic, ...args);
+  vue.onScopeDispose(() => {
+    core.cleanupLogic(instance);
+  });
+  return instance;
+}
+
+function useSnapshot(handler, options) {
+  if (vue.getCurrentInstance() === null) {
+    throw new Error(
+      "useSnapshot can only be used within a Vue component setup()."
+    );
+  }
+  const state = vue.shallowRef(handler.getSnapshot().value);
+  const update = () => {
+    const next = handler.getSnapshot().value;
+    if (!Object.is(next, state.value)) {
+      state.value = next;
+      return;
+    }
+    vue.triggerRef(state);
+  };
+  const unsubscribe = handler.subscribe(update);
+  vue.onScopeDispose(() => {
+    unsubscribe();
+  });
+  if (options?.mode === "mutable") {
+    return state;
+  }
+  return vue.readonly(state);
+}
+
+function useSignal(source) {
+  const handler = core.createSignalHandler(source);
+  return useSnapshot(handler);
+}
+
+function useComputed(source) {
+  const handler = core.createComputedHandler(source);
+  return useSnapshot(handler);
+}
+
+function useDeepSignal(source) {
+  const handler = core.createDeepSignalHandler(source);
+  return useSnapshot(handler, { mode: "mutable" });
+}
+
+function assertWritableSignal(source) {
+  let prototype = source;
+  let descriptor;
+  while (prototype !== null) {
+    descriptor = Object.getOwnPropertyDescriptor(prototype, "value");
+    if (descriptor !== void 0) {
+      break;
+    }
+    prototype = Object.getPrototypeOf(prototype);
+  }
+  if (descriptor?.set === void 0) {
+    throw new Error(
+      "useMutableSignal requires a writable signal instance created by signal()."
+    );
+  }
+}
+function useMutableSignal(source) {
+  assertWritableSignal(source);
+  const state = useSignal(source);
+  return vue.computed({
+    get: () => state.value,
+    set: (value) => {
+      source.value = value;
+    }
+  });
+}
+
+exports.useComputed = useComputed;
+exports.useDeepSignal = useDeepSignal;
+exports.useLogic = useLogic;
+exports.useMutableSignal = useMutableSignal;
+exports.useSignal = useSignal;
+exports.useSnapshot = useSnapshot;

package/dist/index.d.cts

@@ -0,0 +1,24 @@
+import { LogicFunction, LogicArgs, LogicInstance, Signal, ReadonlySignal, Computed, DeepSignal, SnapshotHandler } from '@sigrea/core';
+import * as vue from 'vue';
+import { DeepReadonly, ShallowRef } from 'vue';
+
+declare function useLogic<TReturn extends object, TProps = void>(logic: LogicFunction<TReturn, TProps>, ...args: LogicArgs<TProps>): LogicInstance<TReturn>;
+
+type ReadableSignal<T> = Signal<T> | ReadonlySignal<T>;
+declare function useSignal<T>(source: ReadableSignal<T>): Readonly<vue.Ref<vue.DeepReadonly<T>, vue.DeepReadonly<T>>>;
+
+declare function useComputed<T>(source: Computed<T>): Readonly<vue.Ref<vue.DeepReadonly<T>, vue.DeepReadonly<T>>>;
+
+declare function useDeepSignal<T extends object>(source: DeepSignal<T>): vue.ShallowRef<T>;
+
+declare function useMutableSignal<T>(source: Signal<T>): vue.WritableComputedRef<vue.DeepReadonly<T>, T>;
+
+interface UseSnapshotOptions {
+    mode?: "readonly" | "mutable";
+}
+declare function useSnapshot<T>(handler: SnapshotHandler<T>): DeepReadonly<ShallowRef<T>>;
+declare function useSnapshot<T>(handler: SnapshotHandler<T>, options: UseSnapshotOptions & {
+    mode: "mutable";
+}): ShallowRef<T>;
+
+export { useComputed, useDeepSignal, useLogic, useMutableSignal, useSignal, useSnapshot };

package/dist/index.d.mts

@@ -0,0 +1,24 @@
+import { LogicFunction, LogicArgs, LogicInstance, Signal, ReadonlySignal, Computed, DeepSignal, SnapshotHandler } from '@sigrea/core';
+import * as vue from 'vue';
+import { DeepReadonly, ShallowRef } from 'vue';
+
+declare function useLogic<TReturn extends object, TProps = void>(logic: LogicFunction<TReturn, TProps>, ...args: LogicArgs<TProps>): LogicInstance<TReturn>;
+
+type ReadableSignal<T> = Signal<T> | ReadonlySignal<T>;
+declare function useSignal<T>(source: ReadableSignal<T>): Readonly<vue.Ref<vue.DeepReadonly<T>, vue.DeepReadonly<T>>>;
+
+declare function useComputed<T>(source: Computed<T>): Readonly<vue.Ref<vue.DeepReadonly<T>, vue.DeepReadonly<T>>>;
+
+declare function useDeepSignal<T extends object>(source: DeepSignal<T>): vue.ShallowRef<T>;
+
+declare function useMutableSignal<T>(source: Signal<T>): vue.WritableComputedRef<vue.DeepReadonly<T>, T>;
+
+interface UseSnapshotOptions {
+    mode?: "readonly" | "mutable";
+}
+declare function useSnapshot<T>(handler: SnapshotHandler<T>): DeepReadonly<ShallowRef<T>>;
+declare function useSnapshot<T>(handler: SnapshotHandler<T>, options: UseSnapshotOptions & {
+    mode: "mutable";
+}): ShallowRef<T>;
+
+export { useComputed, useDeepSignal, useLogic, useMutableSignal, useSignal, useSnapshot };

package/dist/index.d.ts

@@ -0,0 +1,24 @@
+import { LogicFunction, LogicArgs, LogicInstance, Signal, ReadonlySignal, Computed, DeepSignal, SnapshotHandler } from '@sigrea/core';
+import * as vue from 'vue';
+import { DeepReadonly, ShallowRef } from 'vue';
+
+declare function useLogic<TReturn extends object, TProps = void>(logic: LogicFunction<TReturn, TProps>, ...args: LogicArgs<TProps>): LogicInstance<TReturn>;
+
+type ReadableSignal<T> = Signal<T> | ReadonlySignal<T>;
+declare function useSignal<T>(source: ReadableSignal<T>): Readonly<vue.Ref<vue.DeepReadonly<T>, vue.DeepReadonly<T>>>;
+
+declare function useComputed<T>(source: Computed<T>): Readonly<vue.Ref<vue.DeepReadonly<T>, vue.DeepReadonly<T>>>;
+
+declare function useDeepSignal<T extends object>(source: DeepSignal<T>): vue.ShallowRef<T>;
+
+declare function useMutableSignal<T>(source: Signal<T>): vue.WritableComputedRef<vue.DeepReadonly<T>, T>;
+
+interface UseSnapshotOptions {
+    mode?: "readonly" | "mutable";
+}
+declare function useSnapshot<T>(handler: SnapshotHandler<T>): DeepReadonly<ShallowRef<T>>;
+declare function useSnapshot<T>(handler: SnapshotHandler<T>, options: UseSnapshotOptions & {
+    mode: "mutable";
+}): ShallowRef<T>;
+
+export { useComputed, useDeepSignal, useLogic, useMutableSignal, useSignal, useSnapshot };

package/dist/index.mjs

@@ -0,0 +1,84 @@
+import { getCurrentInstance, onScopeDispose, shallowRef, readonly, triggerRef, computed } from 'vue';
+import { mountLogic, cleanupLogic, createSignalHandler, createComputedHandler, createDeepSignalHandler } from '@sigrea/core';
+
+function useLogic(logic, ...args) {
+  if (getCurrentInstance() === null) {
+    throw new Error(
+      "useLogic can only be used within a Vue component setup()."
+    );
+  }
+  const instance = mountLogic(logic, ...args);
+  onScopeDispose(() => {
+    cleanupLogic(instance);
+  });
+  return instance;
+}
+
+function useSnapshot(handler, options) {
+  if (getCurrentInstance() === null) {
+    throw new Error(
+      "useSnapshot can only be used within a Vue component setup()."
+    );
+  }
+  const state = shallowRef(handler.getSnapshot().value);
+  const update = () => {
+    const next = handler.getSnapshot().value;
+    if (!Object.is(next, state.value)) {
+      state.value = next;
+      return;
+    }
+    triggerRef(state);
+  };
+  const unsubscribe = handler.subscribe(update);
+  onScopeDispose(() => {
+    unsubscribe();
+  });
+  if (options?.mode === "mutable") {
+    return state;
+  }
+  return readonly(state);
+}
+
+function useSignal(source) {
+  const handler = createSignalHandler(source);
+  return useSnapshot(handler);
+}
+
+function useComputed(source) {
+  const handler = createComputedHandler(source);
+  return useSnapshot(handler);
+}
+
+function useDeepSignal(source) {
+  const handler = createDeepSignalHandler(source);
+  return useSnapshot(handler, { mode: "mutable" });
+}
+
+function assertWritableSignal(source) {
+  let prototype = source;
+  let descriptor;
+  while (prototype !== null) {
+    descriptor = Object.getOwnPropertyDescriptor(prototype, "value");
+    if (descriptor !== void 0) {
+      break;
+    }
+    prototype = Object.getPrototypeOf(prototype);
+  }
+  if (descriptor?.set === void 0) {
+    throw new Error(
+      "useMutableSignal requires a writable signal instance created by signal()."
+    );
+  }
+}
+function useMutableSignal(source) {
+  assertWritableSignal(source);
+  const state = useSignal(source);
+  return computed({
+    get: () => state.value,
+    set: (value) => {
+      source.value = value;
+    }
+  });
+}
+
+export { useComputed, useDeepSignal, useLogic, useMutableSignal, useSignal, useSnapshot };

package/package.json

@@ -0,0 +1,69 @@
+{
+  "name": "@sigrea/vue",
+  "version": "0.1.0",
+  "description": "Vue adapter bindings for Sigrea logic modules.",
+  "license": "MIT",
+  "type": "module",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/sigrea/vue.git"
+  },
+  "homepage": "https://github.com/sigrea/vue#readme",
+  "bugs": {
+    "url": "https://github.com/sigrea/vue/issues"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "main": "./dist/index.cjs",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "keywords": [
+    "signals",
+    "reactivity",
+    "vue",
+    "logic",
+    "typescript"
+  ],
+  "peerDependencies": {
+    "@sigrea/core": "^0.1.0",
+    "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",
+    "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"
+  },
+  "scripts": {
+    "dev": "vite --config playground/vite.config.ts",
+    "build": "unbuild",
+    "test": "vitest run",
+    "test:coverage": "vitest --coverage",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "format": "biome check .",
+    "format:fix": "biome check --write ."
+  }
+}