@hoosk/minisignals-vue 0.0.0-stage → 1.0.0

package/README.md

@@ -1,3 +1,86 @@
-# Temporary Holding Version
+# @hoosk/minisignals-vue
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The Vue 3 adapter for `@hoosk/minisignals`.
+
+This package exposes minisignals values as native Vue refs, so they auto-unwrap in templates, work with `v-model`, `watch`, and `computed`, and are cleaned up automatically with the component or `effectScope`.
+
+## Installation
+
+```bash
+npm install @hoosk/minisignals @hoosk/minisignals-vue
+```
+
+## Basic Usage
+
+```vue
+<script setup lang="ts">
+import { useSignal } from '@hoosk/minisignals-vue';
+
+const count = useSignal(0);
+</script>
+
+<template>
+  <p>Count: {{ count }}</p>
+  <button @click="count++">Increment</button>
+</template>
+```
+
+## API
+
+### `useSignal(initialValue): Ref<T>`
+
+Creates a local signal and returns a writable Vue ref backed by it. Usable directly with `v-model`.
+
+### `useSignalRef(sig): Ref<T>`
+
+Bridges an existing `Signal<T>` to a writable ref. Useful when the signal lives in a store outside the component:
+
+```ts
+import { signal } from '@hoosk/minisignals';
+import { useSignalRef } from '@hoosk/minisignals-vue';
+
+export const count = signal(0);
+
+// inside setup()
+const countRef = useSignalRef(count);
+```
+
+### `useSignalValue(sig): Readonly<Ref<T>>`
+
+Subscribes to any `Signal` or `Computed` and returns a read-only ref.
+
+### `useComputed(fn): Readonly<Ref<T>>`
+
+Creates a computed signal and returns a read-only ref. The computed instance is disposed automatically when the component or `effectScope` stops.
+
+```vue
+<script setup lang="ts">
+import { signal } from '@hoosk/minisignals';
+import { useComputed } from '@hoosk/minisignals-vue';
+
+const price = signal(100);
+const quantity = signal(2);
+const total = useComputed(() => price.value * quantity.value);
+</script>
+
+<template>
+  <p>Total: {{ total }}</p>
+</template>
+```
+
+### `useSignalEffect(fn): () => void`
+
+Runs a core `effect` bound to the Vue lifecycle. The callback may return a cleanup function, which runs before each re-execution and when the scope stops. Returns a manual stop function.
+
+```ts
+import { useSignalEffect } from '@hoosk/minisignals-vue';
+
+useSignalEffect(() => {
+  document.title = `Count: ${count.value}`;
+  return () => console.log('cleanup');
+});
+```
+
+All composables register their teardown through `onScopeDispose`, so they also work inside `effectScope` outside of components.
+
+For full documentation, please refer to the [main repository README](https://github.com/Hoosk/minisignals#readme).

package/dist/index.cjs

@@ -0,0 +1,111 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  useComputed: () => useComputed,
+  useSignal: () => useSignal,
+  useSignalEffect: () => useSignalEffect,
+  useSignalRef: () => useSignalRef,
+  useSignalValue: () => useSignalValue
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/useSignalValue.ts
+var import_vue2 = require("vue");
+var import_minisignals2 = require("@hoosk/minisignals");
+
+// src/bridge.ts
+var import_vue = require("vue");
+var import_minisignals = require("@hoosk/minisignals");
+function disposeOnScope(stop) {
+  if ((0, import_vue.getCurrentScope)()) (0, import_vue.onScopeDispose)(stop);
+}
+function signalToRef(sig) {
+  return (0, import_vue.customRef)((track, trigger) => {
+    const stop = (0, import_minisignals.effect)(() => {
+      sig.value;
+      trigger();
+    });
+    disposeOnScope(stop);
+    return {
+      get() {
+        track();
+        return sig.value;
+      },
+      set(value) {
+        sig.value = value;
+      }
+    };
+  });
+}
+
+// src/useSignalValue.ts
+function useSignalValue(sig) {
+  const ref = (0, import_vue2.customRef)((track, trigger) => {
+    const stop = (0, import_minisignals2.effect)(() => {
+      sig.value;
+      trigger();
+    });
+    disposeOnScope(stop);
+    return {
+      get() {
+        track();
+        return sig.value;
+      },
+      set() {
+      }
+    };
+  });
+  return ref;
+}
+
+// src/useSignal.ts
+var import_minisignals3 = require("@hoosk/minisignals");
+function useSignal(initialValue) {
+  return useSignalRef((0, import_minisignals3.signal)(initialValue));
+}
+function useSignalRef(sig) {
+  return signalToRef(sig);
+}
+
+// src/useComputed.ts
+var import_minisignals4 = require("@hoosk/minisignals");
+function useComputed(fn) {
+  const derived = (0, import_minisignals4.computed)(fn);
+  disposeOnScope(() => derived.dispose());
+  return useSignalValue(derived);
+}
+
+// src/useSignalEffect.ts
+var import_minisignals5 = require("@hoosk/minisignals");
+function useSignalEffect(fn) {
+  const stop = (0, import_minisignals5.effect)(fn);
+  disposeOnScope(stop);
+  return stop;
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  useComputed,
+  useSignal,
+  useSignalEffect,
+  useSignalRef,
+  useSignalValue
+});

package/dist/index.d.cts

@@ -0,0 +1,52 @@
+import { Ref } from 'vue';
+import { ReadonlySignal, Signal } from '@hoosk/minisignals';
+
+/**
+ * Subscribes to a Signal or Computed and exposes its value as a read-only Vue
+ * Ref. The subscription is torn down automatically when the component (or
+ * effectScope) is disposed.
+ *
+ * @param sig Any ReadonlySignal (Signal or Computed) to observe.
+ * @returns A read-only Ref that updates with the signal.
+ */
+declare function useSignalValue<T>(sig: ReadonlySignal<T>): Readonly<Ref<T>>;
+
+/**
+ * Creates a local signal and exposes it as a writable Vue Ref. The ref can be
+ * used directly in templates (auto-unwrapping) and with `v-model`.
+ *
+ * @param initialValue The starting value of the signal.
+ * @returns A writable Ref backed by a stable Signal.
+ */
+declare function useSignal<T>(initialValue: T): Ref<T>;
+/**
+ * Bridges an existing Signal to a writable Vue Ref.
+ */
+declare function useSignalRef<T>(sig: Signal<T>): Ref<T>;
+
+/**
+ * Creates a computed signal derived from other signals and exposes it as a
+ * read-only Vue Ref.
+ *
+ * The computed instance is disposed automatically when the component or
+ * effectScope is torn down, preventing source signals from retaining
+ * subscriptions to unmounted components.
+ *
+ * @param fn The derivation function.
+ * @returns A read-only Ref that updates when dependencies change.
+ */
+declare function useComputed<T>(fn: () => T): Readonly<Ref<T>>;
+
+/**
+ * Runs a reactive effect tied to the component's lifecycle.
+ *
+ * The effect is stopped automatically when the component (or effectScope) is
+ * disposed. The callback may return a cleanup function, which runs before each
+ * re-execution and when the effect is stopped.
+ *
+ * @param fn The effect callback.
+ * @returns A stop function for manual teardown.
+ */
+declare function useSignalEffect(fn: () => void | (() => void)): () => void;
+
+export { useComputed, useSignal, useSignalEffect, useSignalRef, useSignalValue };

package/dist/index.d.ts

@@ -0,0 +1,52 @@
+import { Ref } from 'vue';
+import { ReadonlySignal, Signal } from '@hoosk/minisignals';
+
+/**
+ * Subscribes to a Signal or Computed and exposes its value as a read-only Vue
+ * Ref. The subscription is torn down automatically when the component (or
+ * effectScope) is disposed.
+ *
+ * @param sig Any ReadonlySignal (Signal or Computed) to observe.
+ * @returns A read-only Ref that updates with the signal.
+ */
+declare function useSignalValue<T>(sig: ReadonlySignal<T>): Readonly<Ref<T>>;
+
+/**
+ * Creates a local signal and exposes it as a writable Vue Ref. The ref can be
+ * used directly in templates (auto-unwrapping) and with `v-model`.
+ *
+ * @param initialValue The starting value of the signal.
+ * @returns A writable Ref backed by a stable Signal.
+ */
+declare function useSignal<T>(initialValue: T): Ref<T>;
+/**
+ * Bridges an existing Signal to a writable Vue Ref.
+ */
+declare function useSignalRef<T>(sig: Signal<T>): Ref<T>;
+
+/**
+ * Creates a computed signal derived from other signals and exposes it as a
+ * read-only Vue Ref.
+ *
+ * The computed instance is disposed automatically when the component or
+ * effectScope is torn down, preventing source signals from retaining
+ * subscriptions to unmounted components.
+ *
+ * @param fn The derivation function.
+ * @returns A read-only Ref that updates when dependencies change.
+ */
+declare function useComputed<T>(fn: () => T): Readonly<Ref<T>>;
+
+/**
+ * Runs a reactive effect tied to the component's lifecycle.
+ *
+ * The effect is stopped automatically when the component (or effectScope) is
+ * disposed. The callback may return a cleanup function, which runs before each
+ * re-execution and when the effect is stopped.
+ *
+ * @param fn The effect callback.
+ * @returns A stop function for manual teardown.
+ */
+declare function useSignalEffect(fn: () => void | (() => void)): () => void;
+
+export { useComputed, useSignal, useSignalEffect, useSignalRef, useSignalValue };

package/dist/index.js

@@ -0,0 +1,80 @@
+// src/useSignalValue.ts
+import { customRef as customRef2 } from "vue";
+import { effect as effect2 } from "@hoosk/minisignals";
+
+// src/bridge.ts
+import { customRef, getCurrentScope, onScopeDispose } from "vue";
+import { effect } from "@hoosk/minisignals";
+function disposeOnScope(stop) {
+  if (getCurrentScope()) onScopeDispose(stop);
+}
+function signalToRef(sig) {
+  return customRef((track, trigger) => {
+    const stop = effect(() => {
+      sig.value;
+      trigger();
+    });
+    disposeOnScope(stop);
+    return {
+      get() {
+        track();
+        return sig.value;
+      },
+      set(value) {
+        sig.value = value;
+      }
+    };
+  });
+}
+
+// src/useSignalValue.ts
+function useSignalValue(sig) {
+  const ref = customRef2((track, trigger) => {
+    const stop = effect2(() => {
+      sig.value;
+      trigger();
+    });
+    disposeOnScope(stop);
+    return {
+      get() {
+        track();
+        return sig.value;
+      },
+      set() {
+      }
+    };
+  });
+  return ref;
+}
+
+// src/useSignal.ts
+import { signal } from "@hoosk/minisignals";
+function useSignal(initialValue) {
+  return useSignalRef(signal(initialValue));
+}
+function useSignalRef(sig) {
+  return signalToRef(sig);
+}
+
+// src/useComputed.ts
+import { computed as coreComputed } from "@hoosk/minisignals";
+function useComputed(fn) {
+  const derived = coreComputed(fn);
+  disposeOnScope(() => derived.dispose());
+  return useSignalValue(derived);
+}
+
+// src/useSignalEffect.ts
+import { effect as effect3 } from "@hoosk/minisignals";
+function useSignalEffect(fn) {
+  const stop = effect3(fn);
+  disposeOnScope(stop);
+  return stop;
+}
+export {
+  useComputed,
+  useSignal,
+  useSignalEffect,
+  useSignalRef,
+  useSignalValue
+};

package/package.json

@@ -1,6 +1,54 @@
 {
   "name": "@hoosk/minisignals-vue",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.0",
+  "description": "Vue 3 adapter for @hoosk/minisignals",
+  "type": "module",
+  "sideEffects": false,
+  "main": "dist/index.cjs",
+  "module": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "peerDependencies": {
+    "vue": ">=3.0.0"
+  },
+  "dependencies": {
+    "@hoosk/minisignals": "^1.2.0"
+  },
+  "devDependencies": {
+    "@vue/test-utils": "^2.4.6",
+    "tsup": "^8.5.0",
+    "vue": "^3.4.0"
+  },
+  "scripts": {
+    "build": "tsup src/index.ts --format cjs,esm --dts --clean",
+    "dev": "tsup src/index.ts --format cjs,esm --watch --dts",
+    "prepare": "npm run build",
+    "test": "vitest run"
+  },
+  "keywords": [
+    "signals",
+    "reactive",
+    "reactivity",
+    "state",
+    "vue",
+    "composables",
+    "signal"
+  ],
+  "author": "Hoosk",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Hoosk/minisignals.git",
+    "directory": "packages/vue"
+  }
+}