@triggery/signals 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,9 @@
+# @triggery/signals
+
+## 0.1.0
+
+First public preview release.
+
+Signals adapter for Triggery — read a signal's value from a trigger condition without engaging signal-tracking on the host component
+
+See the [repository-level CHANGELOG](../../CHANGELOG.md#010--2026-05-16) for the full set of packages and the umbrella feature list. Future entries on this file are appended automatically by changesets.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Aleksey Skhomenko
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,71 @@
+# @triggery/signals
+
+Read a signal from a Triggery condition without engaging signal-tracking on the host component. Compatible with:
+
+* [`@preact/signals-core`](https://github.com/preactjs/signals)
+* [`alien-signals`](https://github.com/stackblitz/alien-signals)
+* Any structurally-similar signal exposing `peek()` or `.value`
+
+## Install
+
+```bash
+pnpm add @triggery/core @triggery/react @triggery/signals
+# + the signal library of your choice, e.g.
+pnpm add @preact/signals-core
+```
+
+## Usage
+
+```tsx
+import { signal } from '@preact/signals-core';
+import { createTrigger } from '@triggery/core';
+import { useSignalCondition } from '@triggery/signals';
+
+const settings = signal({ sound: true, notifications: true });
+
+const messageTrigger = createTrigger<{
+  events: { 'new-message': { text: string } };
+  conditions: { settings: { sound: boolean; notifications: boolean } };
+  actions: { showToast: { body: string } };
+}>({
+  id: 'message-received',
+  events: ['new-message'],
+  required: ['settings'],
+  handler({ event, conditions, actions }) {
+    if (!conditions.settings.notifications) return;
+    actions.showToast?.({ body: event.payload.text });
+  },
+});
+
+function SettingsBridge() {
+  useSignalCondition(messageTrigger, 'settings', settings);
+  return null;
+}
+```
+
+With a selector:
+
+```ts
+useSignalCondition(messageTrigger, 'settings', profile, (p) => p.settings);
+```
+
+## How it works
+
+Pull-only: the signal is read **only** when a trigger fires. The adapter prefers `peek()` (no dependency tracking) and falls back to `.value` if `peek` is missing. Either way, no subscriber is registered against the signal, so the host component never re-renders on signal updates.
+
+If a component also needs to render the signal, use `useSignal()` from `@preact/signals-react` or the equivalent in your signal library — the two paths are orthogonal.
+
+## API
+
+```ts
+useSignalCondition<V, S, K>(
+  trigger: Trigger<S>,
+  name: K,
+  signal: { peek?(): V; readonly value?: V },
+  selector?: (value: V) => ConditionMap<S>[K],
+): void
+```
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,42 @@
+import { TriggerSchema, ConditionKey, Trigger, ConditionMap } from '@triggery/core';
+
+/**
+ * Structural shape that matches every signal flavour we know about: a `peek()`
+ * method (preferred — never engages dependency tracking) plus a `.value`
+ * accessor (used as a fallback).
+ *
+ *   - `@preact/signals-core` ✓ has both `peek()` and `.value`
+ *   - `alien-signals`        ✓ uses `.peek()` / `.value`
+ *   - any TC39-style Signal  ✓ if the `peek` method is present
+ */
+interface SignalLike<V> {
+    peek?(): V;
+    readonly value?: V;
+}
+/**
+ * Wire a signal into a Triggery condition.
+ *
+ * The runtime is pull-only — the signal is read **only** when a trigger
+ * fires, via `peek()` so no dependency tracking is engaged. The host
+ * component is never subscribed to the signal.
+ *
+ * If a component also needs to render the signal, use the signal library's
+ * own integration (`useSignal()`, `<Signal />`, etc.) — the two paths are
+ * orthogonal.
+ *
+ * @example
+ * ```tsx
+ * import { signal } from '@preact/signals-core';
+ * import { useSignalCondition } from '@triggery/signals';
+ *
+ * const settings = signal({ sound: true, notifications: true });
+ *
+ * function SettingsBridge() {
+ *   useSignalCondition(messageTrigger, 'settings', settings);
+ *   return null;
+ * }
+ * ```
+ */
+declare function useSignalCondition<V, S extends TriggerSchema, K extends ConditionKey<S>>(trigger: Trigger<S>, name: K, signal: SignalLike<V>, selector?: (value: V) => ConditionMap<S>[K]): void;
+
+export { type SignalLike, useSignalCondition };

package/dist/index.js

@@ -0,0 +1,22 @@
+import { useCondition } from '@triggery/react';
+
+// src/index.ts
+function readSignal(signal) {
+  if (typeof signal.peek === "function") return signal.peek();
+  return signal.value;
+}
+function useSignalCondition(trigger, name, signal, selector) {
+  useCondition(
+    trigger,
+    name,
+    () => {
+      const value = readSignal(signal);
+      return selector ? selector(value) : value;
+    },
+    [signal, selector]
+  );
+}
+
+export { useSignalCondition };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts"],"names":[],"mappings":";;;AAqBA,SAAS,WAAc,MAAA,EAA0B;AAC/C,EAAA,IAAI,OAAO,MAAA,CAAO,IAAA,KAAS,UAAA,EAAY,OAAO,OAAO,IAAA,EAAK;AAC1D,EAAA,OAAO,MAAA,CAAO,KAAA;AAChB;AA0BO,SAAS,kBAAA,CACd,OAAA,EACA,IAAA,EACA,MAAA,EACA,QAAA,EACM;AACN,EAAA,YAAA;AAAA,IACE,OAAA;AAAA,IACA,IAAA;AAAA,IACA,MAAM;AACJ,MAAA,MAAM,KAAA,GAAQ,WAAW,MAAM,CAAA;AAC/B,MAAA,OAAO,QAAA,GAAW,QAAA,CAAS,KAAK,CAAA,GAAK,KAAA;AAAA,IACvC,CAAA;AAAA,IACA,CAAC,QAAQ,QAAQ;AAAA,GACnB;AACF","file":"index.js","sourcesContent":["import type { ConditionKey, ConditionMap, Trigger, TriggerSchema } from '@triggery/core';\nimport { useCondition } from '@triggery/react';\n\n/**\n * Structural shape that matches every signal flavour we know about: a `peek()`\n * method (preferred — never engages dependency tracking) plus a `.value`\n * accessor (used as a fallback).\n *\n *   - `@preact/signals-core` ✓ has both `peek()` and `.value`\n *   - `alien-signals`        ✓ uses `.peek()` / `.value`\n *   - any TC39-style Signal  ✓ if the `peek` method is present\n */\nexport interface SignalLike<V> {\n  peek?(): V;\n  readonly value?: V;\n}\n\n/**\n * Read a signal's value without engaging dependency tracking.\n * Prefers `peek()` when available, falls back to `.value`.\n */\nfunction readSignal<V>(signal: SignalLike<V>): V {\n  if (typeof signal.peek === 'function') return signal.peek();\n  return signal.value as V;\n}\n\n/**\n * Wire a signal into a Triggery condition.\n *\n * The runtime is pull-only — the signal is read **only** when a trigger\n * fires, via `peek()` so no dependency tracking is engaged. The host\n * component is never subscribed to the signal.\n *\n * If a component also needs to render the signal, use the signal library's\n * own integration (`useSignal()`, `<Signal />`, etc.) — the two paths are\n * orthogonal.\n *\n * @example\n * ```tsx\n * import { signal } from '@preact/signals-core';\n * import { useSignalCondition } from '@triggery/signals';\n *\n * const settings = signal({ sound: true, notifications: true });\n *\n * function SettingsBridge() {\n *   useSignalCondition(messageTrigger, 'settings', settings);\n *   return null;\n * }\n * ```\n */\nexport function useSignalCondition<V, S extends TriggerSchema, K extends ConditionKey<S>>(\n  trigger: Trigger<S>,\n  name: K,\n  signal: SignalLike<V>,\n  selector?: (value: V) => ConditionMap<S>[K],\n): void {\n  useCondition(\n    trigger,\n    name,\n    () => {\n      const value = readSignal(signal);\n      return selector ? selector(value) : (value as unknown as ConditionMap<S>[K]);\n    },\n    [signal, selector],\n  );\n}\n"]}

package/package.json

@@ -0,0 +1,85 @@
+{
+  "name": "@triggery/signals",
+  "version": "0.1.0",
+  "description": "Signals adapter for Triggery — read a signal's value from a trigger condition without engaging signal-tracking on the host component",
+  "license": "MIT",
+  "author": "Aleksey Skhomenko",
+  "homepage": "https://triggeryjs.github.io/triggery",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/triggeryjs/triggery.git",
+    "directory": "packages/signals"
+  },
+  "bugs": "https://github.com/triggeryjs/triggery/issues",
+  "funding": [
+    {
+      "type": "patreon",
+      "url": "https://www.patreon.com/triggery"
+    },
+    {
+      "type": "boosty",
+      "url": "https://boosty.to/triggery"
+    }
+  ],
+  "keywords": [
+    "triggery",
+    "signals",
+    "preact",
+    "adapter",
+    "react"
+  ],
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "source": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md"
+  ],
+  "sideEffects": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "peerDependencies": {
+    "react": ">=18.0.0",
+    "@triggery/core": "0.1.0",
+    "@triggery/react": "0.1.0"
+  },
+  "peerDependenciesMeta": {
+    "@preact/signals-core": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@preact/signals-core": "^1.13.2",
+    "@testing-library/react": "^16.3.2",
+    "@types/react": "^19.2.14",
+    "happy-dom": "^20.9.0",
+    "react": "^19.2.6",
+    "react-dom": "^19.2.6",
+    "tsup": "^8.5.1",
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.6",
+    "@triggery/react": "0.1.0",
+    "@triggery/core": "0.1.0"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "clean": "rm -rf dist *.tsbuildinfo"
+  }
+}