Add a definition for a generic signal to web core (#960)

* Add basic concept of a generic signal

* add test coverage

* add license headers

* Address review comments

Author: ava-cassiopeia

renderers/web_core/package-lock.json

@@ -90,9 +90,11 @@
   "author": "Google",
   "license": "Apache-2.0",
   "devDependencies": {
+    "@angular/core": "^21.2.5",
     "@types/node": "^24.11.0",
     "c8": "^11.0.0",
     "gts": "^7.0.0",
+    "rxjs": "^7.8.2",
     "typescript": "^5.8.3",
     "wireit": "^0.15.0-pre.2"
   },

renderers/web_core/package.json

@@ -0,0 +1,125 @@
+/**
+ * Copyright 2026 Google LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import assert from 'node:assert';
+import {describe, it} from 'node:test';
+import {Signal as PSignal, computed as pComputed} from '@preact/signals-core';
+import {
+  signal as aSignal,
+  computed as aComputed,
+  Signal as ASignal,
+  WritableSignal as AWritableSignal,
+  isSignal,
+} from '@angular/core';
+
+import {FrameworkSignal} from './signals';
+
+describe('FrameworkSignal', () => {
+  // Test FrameworkSignal with two sample implemenations that wrap Angular and
+  // Preact signals. Angular and Preact signals are good representitive samples,
+  // because the two common patterns - `()` vs. `.value` - are represented by
+  // Angular and Preact respectively.
+
+  describe('Angular variation', () => {
+    const AngularSignal: FrameworkSignal<ASignal<any>, AWritableSignal<any>> = {
+      computed: <T>(fn: () => T) => aComputed(fn),
+      isSignal: (val: unknown) => isSignal(val),
+      wrap: <T>(val: T) => aSignal(val),
+      unwrap: <T>(val: ASignal<T>) => val(),
+      set: <T>(signal: AWritableSignal<T>, value: T) => signal.set(value),
+    };
+
+    it('round trip wraps and unwraps successfully', () => {
+      const val = 'hello';
+      const wrapped = AngularSignal.wrap(val);
+      assert.strictEqual(AngularSignal.unwrap(wrapped), val);
+    });
+
+    it('handles updates well', () => {
+      const signal = AngularSignal.wrap('first');
+      const computedVal = AngularSignal.computed(() => `prefix ${signal()}`);
+
+      assert.strictEqual(signal(), 'first');
+      assert.strictEqual(AngularSignal.unwrap(signal), 'first');
+      assert.strictEqual(computedVal(), 'prefix first');
+      assert.strictEqual(AngularSignal.unwrap(computedVal), 'prefix first');
+
+      AngularSignal.set(signal, 'second');
+
+      assert.strictEqual(signal(), 'second');
+      assert.strictEqual(AngularSignal.unwrap(signal), 'second');
+      assert.strictEqual(computedVal(), 'prefix second');
+      assert.strictEqual(AngularSignal.unwrap(computedVal), 'prefix second');
+    });
+
+    describe('.isSignal()', () => {
+      it('validates a signal', () => {
+        const val = 'hello';
+        const wrapped = AngularSignal.wrap(val);
+        assert.ok(AngularSignal.isSignal(wrapped));
+      });
+
+      it('rejects a non-signal', () => {
+        assert.strictEqual(AngularSignal.isSignal('hello'), false);
+      });
+    });
+  });
+
+  describe('Preact variation', () => {
+    const PreactSignal: FrameworkSignal<PSignal> = {
+      computed: <T>(fn: () => T) => pComputed(fn),
+      isSignal: (val: unknown) => val instanceof PSignal,
+      wrap: <T>(val: T) => new PSignal(val),
+      unwrap: <T>(val: PSignal<T>) => val.value,
+      set: <T>(signal: PSignal<T>, value: T) => (signal.value = value),
+    };
+
+    it('round trip wraps and unwraps successfully', () => {
+      const val = 'hello';
+      const wrapped = PreactSignal.wrap(val);
+      assert.strictEqual(PreactSignal.unwrap(wrapped), val);
+    });
+
+    it('handles updates well', () => {
+      const signal = PreactSignal.wrap('first');
+      const computed = PreactSignal.computed(() => `prefix ${signal.value}`);
+
+      assert.strictEqual(signal.value, 'first');
+      assert.strictEqual(PreactSignal.unwrap(signal), 'first');
+      assert.strictEqual(computed.value, 'prefix first');
+      assert.strictEqual(PreactSignal.unwrap(computed), 'prefix first');
+
+      PreactSignal.set(signal, 'second');
+
+      assert.strictEqual(signal.value, 'second');
+      assert.strictEqual(PreactSignal.unwrap(signal), 'second');
+      assert.strictEqual(computed.value, 'prefix second');
+      assert.strictEqual(PreactSignal.unwrap(computed), 'prefix second');
+    });
+
+    describe('.isSignal()', () => {
+      it('validates a signal', () => {
+        const val = 'hello';
+        const wrapped = PreactSignal.wrap(val);
+        assert.ok(PreactSignal.isSignal(wrapped));
+      });
+
+      it('rejects a non-signal', () => {
+        assert.strictEqual(PreactSignal.isSignal('hello'), false);
+      });
+    });
+  });
+});

renderers/web_core/src/v0_9/reactivity/signals.test.ts

@@ -0,0 +1,47 @@
+/**
+ * Copyright 2026 Google LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+/**
+ * A generic representation of a Signal that could come from any framework.
+ * For any library building on top of A2UI's web core lib, this must be
+ * implemented for their associated signals implementation.
+ */
+export interface FrameworkSignal<SignalType, WriteableSignalType = SignalType> {
+  /**
+   * Create a computed signal for this framework.
+   */
+  computed<T>(fn: () => T): SignalType;
+
+  /**
+   * Check if an arbitrary object is a framework signal.
+   */
+  isSignal(val: unknown): val is SignalType;
+
+  /**
+   * Wrap the value in a signal.
+   */
+  wrap<T>(val: T): WriteableSignalType;
+
+  /**
+   * Extract the value from a signal.
+   */
+  unwrap<T>(val: SignalType): T;
+
+  /**
+   * Sets the value of the provided framework signal.
+   */
+  set<T>(signal: WriteableSignalType, value: T): void;
+}

renderers/web_core/src/v0_9/reactivity/signals.ts

@@ -28,7 +28,12 @@
     "strict": true,
     "noUnusedLocals": false,
     "noUnusedParameters": true,
-    "noFallthroughCasesInSwitch": true
+    "noFallthroughCasesInSwitch": true,
+
+    "baseUrl": ".",
+    "paths": {
+      "rxjs/operators": ["./node_modules/rxjs/operators/index.js"]
+    }
   },
-  "include": ["src/**/*.ts", "src/**/*.json"]
+  "include": ["src/**/*.ts", "src/**/*.json"],
 }