@a2ui/web_core 0.8.0 → 0.9.1-alpha.0

package/src/v0_9/processing/message-processor.test.ts

@@ -1,133 +0,0 @@
-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();
-  });
-});

package/src/v0_9/processing/message-processor.ts

@@ -1,150 +0,0 @@
-import { SurfaceModel, ActionListener } from '../state/surface-model.js';
-import { Catalog, ComponentApi } from '../catalog/types.js';
-import { SurfaceGroupModel } from '../state/surface-group-model.js';
-import { ComponentModel } from '../state/component-model.js';
-import { Subscription } from '../common/events.js';
-
-import { A2uiMessage } from '../schema/server-to-client.js';
-
-/**
- * The central processor for A2UI messages.
- * @template T The concrete type of the ComponentApi.
- */
-export class MessageProcessor<T extends ComponentApi> {
-  readonly model: SurfaceGroupModel<T>;
-
-  /**
-   * @param catalogs A list of available catalogs.
-   * @param actionHandler A global handler for actions from all surfaces.
-   */
-  constructor(
-    private catalogs: Catalog<T>[],
-    private actionHandler: ActionListener
-  ) {
-    this.model = new SurfaceGroupModel<T>();
-    this.model.onAction.subscribe(this.actionHandler);
-  }
-
-  /**
-   * Subscribes to surface creation events.
-   */
-  onSurfaceCreated(handler: (surface: SurfaceModel<T>) => void): Subscription {
-    return this.model.onSurfaceCreated.subscribe(handler);
-  }
-
-  /**
-   * Subscribes to surface deletion events.
-   */
-  onSurfaceDeleted(handler: (id: string) => void): Subscription {
-    return this.model.onSurfaceDeleted.subscribe(handler);
-  }
-
-  processMessages(messages: A2uiMessage[]): void {
-    for (const message of messages) {
-      this.processMessage(message);
-    }
-  }
-
-  private processMessage(message: A2uiMessage): void {
-    if (message.createSurface) {
-      this.processCreateSurfaceMessage(message);
-      return;
-    }
-
-    const updateTypes = ['updateComponents', 'updateDataModel', 'deleteSurface'].filter(k => (message as any)[k]);
-    if (updateTypes.length > 1) {
-      console.warn(`Message contains multiple update types: ${updateTypes.join(', ')}. Ignoring.`);
-      return;
-    }
-
-    if (message.deleteSurface) {
-      this.processDeleteSurfaceMessage(message);
-      return;
-    }
-
-    if (message.updateComponents) {
-      this.processUpdateComponentsMessage(message);
-      return;
-    }
-
-    if (message.updateDataModel) {
-      this.processUpdateDataModelMessage(message);
-      return;
-    }
-  }
-
-  private processCreateSurfaceMessage(message: A2uiMessage): void {
-    const payload = message.createSurface!;
-    const { surfaceId, catalogId, theme } = payload;
-
-    // Find catalog
-    const catalog = this.catalogs.find(c => c.id === catalogId);
-    if (!catalog) {
-      console.warn(`Catalog not found: ${catalogId}`);
-      return;
-    }
-
-    if (this.model.getSurface(surfaceId)) {
-      console.warn(`Surface ${surfaceId} already exists. Ignoring.`);
-      return;
-    }
-
-    const surface = new SurfaceModel<T>(surfaceId, catalog, theme);
-    this.model.addSurface(surface);
-  }
-
-  private processDeleteSurfaceMessage(message: A2uiMessage): void {
-    const payload = message.deleteSurface!;
-    if (!payload.surfaceId) return;
-    this.model.deleteSurface(payload.surfaceId);
-  }
-
-  private processUpdateComponentsMessage(message: A2uiMessage): void {
-    const payload = message.updateComponents!;
-    if (!payload.surfaceId) return;
-
-    const surface = this.model.getSurface(payload.surfaceId);
-    if (!surface) {
-      console.warn(`Surface not found for message: ${payload.surfaceId}`);
-      return;
-    }
-
-    for (const comp of payload.components) {
-      const { id, component, ...properties } = comp;
-
-      const existing = surface.componentsModel.get(id);
-      if (existing) {
-        if (component && component !== existing.type) {
-          // Recreate component if type changes
-          surface.componentsModel.removeComponent(id);
-          const newComponent = new ComponentModel(id, component, properties);
-          surface.componentsModel.addComponent(newComponent);
-        } else {
-          existing.properties = properties;
-        }
-      } else {
-        if (!component) {
-          console.warn(`Cannot create component ${id} without a type.`);
-          continue;
-        }
-        const newComponent = new ComponentModel(id, component, properties);
-        surface.componentsModel.addComponent(newComponent);
-      }
-    }
-  }
-
-  private processUpdateDataModelMessage(message: A2uiMessage): void {
-    const payload = message.updateDataModel!;
-    if (!payload.surfaceId) return;
-
-    const surface = this.model.getSurface(payload.surfaceId);
-    if (!surface) {
-      console.warn(`Surface not found for message: ${payload.surfaceId}`);
-      return;
-    }
-
-    const path = payload.path || '/';
-    const value = payload.value;
-    surface.dataModel.set(path, value);
-  }
-}

package/src/v0_9/rendering/component-context.ts

@@ -1,36 +0,0 @@
-import { DataContext } from './data-context.js';
-import { ComponentModel } from '../state/component-model.js';
-import type { SurfaceModel } from '../state/surface-model.js';
-import type { ComponentApi } from '../catalog/types.js';
-import type { SurfaceComponentsModel } from '../state/surface-components-model.js';
-
-/**
- * Context provided to components during rendering.
- * It provides access to the component's model, the data context, and a way to dispatch actions.
- */
-export class ComponentContext {
-  readonly componentModel: ComponentModel;
-  readonly dataContext: DataContext;
-  readonly surfaceComponents: SurfaceComponentsModel;
-
-  constructor(
-    surface: SurfaceModel<any>,
-    componentId: string,
-    dataModelBasePath: string = '/'
-  ) {
-    const model = surface.componentsModel.get(componentId);
-    if (!model) {
-      throw new Error(`Component not found: ${componentId}`);
-    }
-    this.componentModel = model;
-    this.surfaceComponents = surface.componentsModel;
-    this.dataContext = new DataContext(surface.dataModel, dataModelBasePath);
-    this._actionDispatcher = (action) => surface.dispatchAction(action);
-  }
-
-  private _actionDispatcher: (action: any) => Promise<void>;
-
-  dispatchAction(action: any): Promise<void> {
-    return this._actionDispatcher(action);
-  }
-}

package/src/v0_9/rendering/data-context.test.ts

@@ -1,85 +0,0 @@
-import assert from 'node:assert';
-import { test, describe, it, beforeEach } from 'node:test';
-import { DataModel } from '../state/data-model.js';
-import { DataContext } from './data-context.js';
-
-describe('DataContext', () => {
-  let model: DataModel;
-  let context: DataContext;
-
-  beforeEach(() => {
-    model = new DataModel({
-      user: {
-        name: 'Alice',
-        address: {
-          city: 'Wonderland'
-        }
-      },
-      list: ['a', 'b']
-    });
-    context = new DataContext(model, '/user');
-  });
-
-  it('resolves relative paths', () => {
-    assert.strictEqual(context.resolveDynamicValue({ path: 'name' }), 'Alice');
-  });
-
-  it('resolves absolute paths', () => {
-    assert.strictEqual(context.resolveDynamicValue({ path: '/list/0' }), 'a');
-  });
-
-  it('resolves nested paths', () => {
-    assert.strictEqual(context.resolveDynamicValue({ path: 'address/city' }), 'Wonderland');
-  });
-
-  it('updates data via relative path', () => {
-    context.set('name', 'Bob');
-    assert.strictEqual(model.get('/user/name'), 'Bob');
-  });
-
-  it('creates nested context', () => {
-    const addressContext = context.nested('address');
-    assert.strictEqual(addressContext.path, '/user/address');
-    assert.strictEqual(addressContext.resolveDynamicValue({ path: 'city' }), 'Wonderland');
-  });
-
-  it('handles root context', () => {
-    const rootContext = new DataContext(model, '/');
-    assert.strictEqual(rootContext.resolveDynamicValue({ path: 'user/name' }), 'Alice');
-  });
-
-  it('subscribes relative path', () => {
-    let called = false;
-    const sub = context.subscribeDynamicValue({ path: 'name' }, (val) => {
-      assert.strictEqual(val, 'Charlie');
-      called = true;
-    });
-    context.set('name', 'Charlie');
-    assert.strictEqual(called, true, 'Callback was never called');
-  });
-
-  it('resolves using resolveDynamicValue() method with literals', () => {
-    // Literal
-    assert.strictEqual(context.resolveDynamicValue('literal'), 'literal');
-    
-    // Path
-    assert.strictEqual(context.resolveDynamicValue({ path: 'name' }), 'Alice');
-    
-    // Absolute Path
-    assert.strictEqual(context.resolveDynamicValue({ path: '/list/0' }), 'a');
-  });
-
-  it('resolves literal arrays', () => {
-    assert.deepStrictEqual(context.resolveDynamicValue(['literal', 'array']), ['literal', 'array']);
-  });
-
-  it('subscribes literal arrays as static', () => {
-    let called = false;
-    const sub = context.subscribeDynamicValue(['literal', 'array'], () => { called = true; });
-    assert.deepStrictEqual(sub.value, ['literal', 'array']);
-    
-    // Simulate some generic path update that shouldn't trigger anything for this static sub
-    context.set('name', 'Charlie');
-    assert.strictEqual(called, false);
-  });
-});

package/src/v0_9/rendering/data-context.ts

@@ -1,110 +0,0 @@
-import { DataModel, DataSubscription } from '../state/data-model.js';
-import type { DynamicValue, DataBinding, FunctionCall } from '../schema/common-types.js';
-
-/**
- * A contextual view of the main DataModel, serving as the unified interface for resolving 
- * DynamicValues (literals, data paths, function calls) within a specific scope.
- */
-export class DataContext {
-  /**
-   * @param dataModel The shared DataModel instance.
-   * @param path The absolute path this context is currently pointing to.
-   */
-  constructor(
-    readonly dataModel: DataModel,
-    readonly path: string
-  ) { }
-
-  /**
-   * Updates the data model at the specified path, resolving it against the current context.
-   * This is the only method for mutating the data model.
-   */
-  set(path: string, value: any): void {
-    const absolutePath = this.resolvePath(path);
-    this.dataModel.set(absolutePath, value);
-  }
-
-  /**
-   * Resolves a DynamicValue to its current evaluation.
-   * Does not set up any subscriptions.
-   */
-  resolveDynamicValue<V>(value: DynamicValue): V {
-    // 1. Literal Check
-    if (typeof value !== 'object' || value === null || Array.isArray(value)) {
-      // TODO: Define error handling when V doesn't match
-      return value as V;
-    }
-
-    // 2. Path Check: { path: "..." }
-    if ('path' in value) {
-      const absolutePath = this.resolvePath((value as DataBinding).path);
-      return this.dataModel.get(absolutePath);
-    }
-
-    // 3. Function Call: { call: "...", args: ... }
-    if ('call' in value) {
-      // TODO: Implement function calls (expected for now)
-      // For now, return as is or undefined
-    }
-
-    // TODO: Define error handling when V doesn't match
-    return value as V;
-  }
-
-  /**
-   * Subscribes to changes in a DynamicValue.
-   * Returns a Subscription object that provides the current value and allows listening for updates.
-   */
-  subscribeDynamicValue<V>(value: DynamicValue, onChange: (value: V | undefined) => void): DataSubscription<V> {
-    // 1. Literal: Return a static subscription
-    if (typeof value !== 'object' || value === null || Array.isArray(value)) {
-      return {
-        // TODO: Define error handling when V doesn't match
-        value: value as V,
-        unsubscribe: () => { }
-      };
-    }
-
-    // 2. Path Check: { path: "..." }
-    if ('path' in value) {
-      const absolutePath = this.resolvePath((value as DataBinding).path);
-      return this.dataModel.subscribe(absolutePath, onChange);
-    }
-
-    // 3. Function Call (TODO)
-    return {
-      // TODO: Define error handling when V doesn't match
-      value: value as V,
-      unsubscribe: () => { }
-    };
-  }
-
-  /**
-   * Creates a new, nested DataContext for a child component.
-   * Used by list/template components for their children.
-   */
-  nested(relativePath: string): DataContext {
-    const newPath = this.resolvePath(relativePath);
-    return new DataContext(this.dataModel, newPath);
-  }
-
-  private resolvePath(path: string): string {
-    // Absolute path - no resolution required.
-    if (path.startsWith('/')) {
-      return path;
-    }
-    // Handle specific cases like '.' or empty
-    if (path === '' || path === '.') {
-      return this.path;
-    }
-
-    // Normalize current path (remove trailing slash if exists, unless root)
-    let base = this.path;
-    if (base.endsWith('/') && base.length > 1) {
-      base = base.slice(0, -1);
-    }
-    if (base === '/') base = '';
-
-    return `${base}/${path}`;
-  }
-}

package/src/v0_9/schema/common-types.ts

@@ -1,125 +0,0 @@
-import { z } from 'zod';
-
-export const DataBindingSchema = z.object({
-    path: z.string().describe('A JSON Pointer path to a value in the data model.')
-});
-
-export const FunctionCallSchema = z.object({
-    call: z.string().describe('The name of the function to call.'),
-    args: z.record(z.any()).describe('Arguments passed to the function.'),
-    returnType: z.enum(['string', 'number', 'boolean', 'array', 'object', 'any', 'void']).default('boolean')
-});
-
-export const LogicExpressionSchema: z.ZodType<any> = z.lazy(() => z.union([
-    z.object({ and: z.array(LogicExpressionSchema).min(1) }),
-    z.object({ or: z.array(LogicExpressionSchema).min(1) }),
-    z.object({ not: LogicExpressionSchema }),
-    z.intersection(FunctionCallSchema, z.object({ returnType: z.literal('boolean').optional() })), // FunctionCall returning boolean
-    z.object({ true: z.literal(true) }),
-    z.object({ false: z.literal(false) })
-]));
-
-export const DynamicStringSchema = z.union([
-    z.string(),
-    DataBindingSchema,
-    // FunctionCall returning string (simplified schema for Zod, stricter in JSON Schema)
-    FunctionCallSchema
-]);
-
-export const DynamicNumberSchema = z.union([
-    z.number(),
-    DataBindingSchema,
-    FunctionCallSchema
-]);
-
-export const DynamicBooleanSchema = z.union([
-    z.boolean(),
-    DataBindingSchema,
-    LogicExpressionSchema
-]);
-
-export const DynamicStringListSchema = z.union([
-    z.array(z.string()),
-    DataBindingSchema,
-    FunctionCallSchema
-]);
-
-export const DynamicValueSchema = z.union([
-    z.string(),
-    z.number(),
-    z.boolean(),
-    z.array(z.any()),
-    DataBindingSchema,
-    FunctionCallSchema
-]);
-
-export type DataBinding = z.infer<typeof DataBindingSchema>;
-export type FunctionCall = z.infer<typeof FunctionCallSchema>;
-export type LogicExpression = z.infer<typeof LogicExpressionSchema>;
-export type DynamicString = z.infer<typeof DynamicStringSchema>;
-export type DynamicNumber = z.infer<typeof DynamicNumberSchema>;
-export type DynamicBoolean = z.infer<typeof DynamicBooleanSchema>;
-export type DynamicStringList = z.infer<typeof DynamicStringListSchema>;
-export type DynamicValue = z.infer<typeof DynamicValueSchema>;
-
-export const ComponentIdSchema = z.string().describe('The unique identifier for a component.');
-export type ComponentId = z.infer<typeof ComponentIdSchema>;
-
-export const ChildListSchema = z.union([
-    z.array(ComponentIdSchema).describe('A static list of child component IDs.'),
-    z.object({
-        componentId: ComponentIdSchema,
-        path: z.string().describe('The path to the list of component property objects in the data model.')
-    }).describe('A template for generating a dynamic list of children.')
-]);
-export type ChildList = z.infer<typeof ChildListSchema>;
-
-export const ActionSchema = z.union([
-    z.object({
-        event: z.object({
-            name: z.string(),
-            context: z.record(DynamicValueSchema).optional()
-        })
-    }).describe('Triggers a server-side event.'),
-    z.object({
-        functionCall: FunctionCallSchema
-    }).describe('Executes a local client-side function.')
-]);
-export type Action = z.infer<typeof ActionSchema>;
-
-export const CheckRuleSchema = z.intersection(
-    LogicExpressionSchema,
-    z.object({
-        message: z.string().describe('The error message to display if the check fails.')
-    })
-);
-export type CheckRule = z.infer<typeof CheckRuleSchema>;
-
-export const CheckableSchema = z.object({
-    checks: z.array(CheckRuleSchema).optional().describe('A list of checks to perform.')
-});
-export type Checkable = z.infer<typeof CheckableSchema>;
-
-export const AccessibilityAttributesSchema = z.object({
-    label: DynamicStringSchema.optional().describe('REF:common_types.json#/$defs/DynamicString|A short string used by assistive technologies to convey the purpose of an element.'),
-    description: DynamicStringSchema.optional().describe('REF:common_types.json#/$defs/DynamicString|Additional information provided by assistive technologies about an element.')
-}).describe('REF:common_types.json#/$defs/AccessibilityAttributes|Attributes to enhance accessibility.');
-
-export type AccessibilityAttributes = z.infer<typeof AccessibilityAttributesSchema>;
-
-export const CommonSchemas = {
-    ComponentId: ComponentIdSchema,
-    ChildList: ChildListSchema,
-    DataBinding: DataBindingSchema,
-    DynamicValue: DynamicValueSchema,
-    DynamicString: DynamicStringSchema,
-    DynamicNumber: DynamicNumberSchema,
-    DynamicBoolean: DynamicBooleanSchema,
-    DynamicStringList: DynamicStringListSchema,
-    FunctionCall: FunctionCallSchema,
-    LogicExpression: LogicExpressionSchema,
-    CheckRule: CheckRuleSchema,
-    Checkable: CheckableSchema,
-    Action: ActionSchema,
-    AccessibilityAttributes: AccessibilityAttributesSchema,
-};

package/src/v0_9/schema/index.ts

@@ -1,2 +0,0 @@
-export * from './common-types.js';
-export * from './server-to-client.js';

package/src/v0_9/schema/server-to-client.ts

@@ -1,23 +0,0 @@
-import { z } from 'zod';
-
-export const A2uiMessageSchema = z.object({
-  createSurface: z.object({
-    surfaceId: z.string(),
-    catalogId: z.string(),
-    theme: z.any().optional(),
-  }).optional(),
-  updateComponents: z.object({
-    surfaceId: z.string(),
-    components: z.array(z.record(z.any())),
-  }).optional(),
-  updateDataModel: z.object({
-    surfaceId: z.string(),
-    path: z.string().optional(),
-    value: z.any(),
-  }).optional(),
-  deleteSurface: z.object({
-    surfaceId: z.string(),
-  }).optional(),
-});
-
-export type A2uiMessage = z.infer<typeof A2uiMessageSchema>;