Add a framework-agnostic data layer and docs to the web core library (#631)

Author: jacobsimionato

renderers/web_core/package-lock.json

@@ -35,7 +35,7 @@
     "prepack": "npm run build",
     "build": "wireit",
     "build:tsc": "wireit",
-    "copy-spec": "wireit"
+    "test": "wireit"
   },
   "wireit": {
     "copy-spec": {
@@ -68,6 +68,12 @@
         "!dist/**/*.min.js{,.map}"
       ],
       "clean": "if-file-deleted"
+    },
+    "test": {
+      "command": "node --test dist/**/*.test.js",
+      "dependencies": [
+        "build"
+      ]
     }
   },
   "author": "Google",
@@ -76,5 +82,9 @@
     "@types/node": "^24.10.1",
     "typescript": "^5.8.3",
     "wireit": "^0.15.0-pre.2"
+  },
+  "dependencies": {
+    "zod": "^3.25.76",
+    "zod-to-json-schema": "^3.25.1"
   }
 }

renderers/web_core/package.json

@@ -0,0 +1,38 @@
+import { z } from 'zod';
+
+/**
+ * A definition of a UI component's API.
+ * This interface defines the contract for a component's capabilities and properties,
+ * independent of any specific rendering implementation.
+ */
+export interface ComponentApi {
+  /** The name of the component as it appears in the A2UI JSON (e.g., 'Button'). */
+  name: string;
+
+  /**
+   * The Zod schema describing the **properties** of this component.
+   * 
+   * - MUST include catalog-specific common properties (e.g. 'weight', 'accessibility').
+   * - MUST NOT include 'component' or 'id' as those are handled by the framework/envelope.
+   */
+  readonly schema: z.ZodType<any>;
+}
+
+export class Catalog<T extends ComponentApi> {
+  readonly id: string;
+
+  /** 
+   * A map of available components. 
+   * This is readonly to encourage immutable extension patterns.
+   */
+  readonly components: ReadonlyMap<string, T>;
+
+  constructor(id: string, components: T[]) {
+    this.id = id;
+    const map = new Map<string, T>();
+    for (const comp of components) {
+      map.set(comp.name, comp);
+    }
+    this.components = map;
+  }
+}

renderers/web_core/src/v0_9/catalog/types.ts

@@ -0,0 +1,44 @@
+/** Standard cleanup interface returned by all subscriptions. */
+export interface Subscription {
+  unsubscribe(): void;
+}
+
+/** The listener function signature. */
+export type EventListener<T> = (data: T) => void | Promise<void>;
+
+/** 
+ * Public interface exposed by models. 
+ * Allows ONLY subscribing to events.
+ */
+export interface EventSource<T> {
+  subscribe(listener: EventListener<T>): Subscription;
+}
+
+/** 
+ * Internal implementation used by the model. 
+ * Implements EventSource but also provides the 'emit' method.
+ */
+export class EventEmitter<T> implements EventSource<T> {
+  private listeners = new Set<EventListener<T>>();
+
+  subscribe(listener: EventListener<T>): Subscription {
+    this.listeners.add(listener);
+    return {
+      unsubscribe: () => this.listeners.delete(listener)
+    };
+  }
+
+  async emit(data: T): Promise<void> {
+    for (const listener of this.listeners) {
+      try {
+        await listener(data);
+      } catch (e) {
+        console.error('EventEmitter error:', e);
+      }
+    }
+  }
+
+  dispose(): void {
+    this.listeners.clear();
+  }
+}

renderers/web_core/src/v0_9/common/events.ts

@@ -0,0 +1,12 @@
+
+export * from './state/data-model.js';
+export * from './common/events.js';
+export * from './rendering/data-context.js';
+export * from './state/surface-model.js';
+export * from './processing/message-processor.js';
+export * from './catalog/types.js';
+export * from './rendering/component-context.js';
+export * from './state/surface-group-model.js';
+export * from './state/surface-components-model.js';
+export * from './schema/index.js';
+

renderers/web_core/src/v0_9/index.ts

@@ -0,0 +1,133 @@
+import assert from 'node:assert';
+import { test, describe, it, beforeEach } from 'node:test';
+import { MessageProcessor } from './message-processor.js';
+import { Catalog, ComponentApi } from '../catalog/types.js';
+
+describe('MessageProcessor', () => {
+  let processor: MessageProcessor<ComponentApi>;
+  let testCatalog: Catalog<ComponentApi>;
+  let actions: any[] = [];
+
+  beforeEach(() => {
+    actions = [];
+    testCatalog = new Catalog('test-catalog', []);
+    processor = new MessageProcessor<ComponentApi>([testCatalog], async (a) => { actions.push(a); });
+  });
+
+  it('creates surface', () => {
+    processor.processMessages([{
+      createSurface: {
+        surfaceId: 's1',
+        catalogId: 'test-catalog',
+        theme: {}
+      }
+    }]);
+    const surface = processor.model.getSurface('s1');
+    assert.ok(surface);
+    assert.strictEqual(surface.id, 's1');
+  });
+
+  it('updates components on correct surface', () => {
+    processor.processMessages([{
+      createSurface: { surfaceId: 's1', catalogId: 'test-catalog' }
+    }]);
+
+    processor.processMessages([{
+      updateComponents: {
+        surfaceId: 's1',
+        components: [{ id: 'root', component: 'Box' }]
+      }
+    }]);
+
+    const surface = processor.model.getSurface('s1');
+    assert.ok(surface?.componentsModel.get('root'));
+  });
+
+  it('updates existing components via message', () => {
+    processor.processMessages([{
+      createSurface: { surfaceId: 's1', catalogId: 'test-catalog' }
+    }]);
+
+    // Create
+    processor.processMessages([{
+      updateComponents: {
+        surfaceId: 's1',
+        components: [{ id: 'btn', component: 'Button', label: 'Initial' }]
+      }
+    }]);
+
+    const surface = processor.model.getSurface('s1');
+    const btn = surface?.componentsModel.get('btn');
+    assert.strictEqual(btn?.properties.label, 'Initial');
+
+    // Update
+    processor.processMessages([{
+      updateComponents: {
+        surfaceId: 's1',
+        components: [{ id: 'btn', component: 'Button', label: 'Updated' }]
+      }
+    }]);
+
+    assert.strictEqual(btn?.properties.label, 'Updated');
+  });
+
+  it('deletes surface', () => {
+    processor.processMessages([{
+      createSurface: { surfaceId: 's1', catalogId: 'test-catalog' }
+    }]);
+    assert.ok(processor.model.getSurface('s1'));
+
+    processor.processMessages([{
+      deleteSurface: { surfaceId: 's1' }
+    }]);
+    assert.strictEqual(processor.model.getSurface('s1'), undefined);
+  });
+
+  it('routes data model updates', () => {
+    processor.processMessages([{
+      createSurface: { surfaceId: 's1', catalogId: 'test-catalog' }
+    }]);
+
+    processor.processMessages([{
+      updateDataModel: {
+        surfaceId: 's1',
+        path: '/foo',
+        value: 'bar'
+      }
+    }]);
+
+    const surface = processor.model.getSurface('s1');
+    assert.strictEqual(surface?.dataModel.get('/foo'), 'bar');
+  });
+
+  it('notifies lifecycle listeners', () => {
+    let created: any = null;
+    let deletedId: string | null = null;
+
+    const sub = processor.onSurfaceCreated((s) => { created = s; });
+    const sub2 = processor.onSurfaceDeleted((id) => { deletedId = id; });
+
+    // Create
+    processor.processMessages([{
+      createSurface: { surfaceId: 's1', catalogId: 'test-catalog' }
+    }]);
+    assert.ok(created);
+    assert.strictEqual(created.id, 's1');
+
+    // Delete
+    processor.processMessages([{
+      deleteSurface: { surfaceId: 's1' }
+    }]);
+    assert.strictEqual(deletedId, 's1');
+
+    // Test Unsubscribe
+    created = null;
+    sub.unsubscribe();
+    processor.processMessages([{
+      createSurface: { surfaceId: 's2', catalogId: 'test-catalog' }
+    }]);
+    assert.strictEqual(created, null);
+    
+    sub2.unsubscribe();
+  });
+});