Update schema resolution to use decoupled metadata with Zod chained prototype operators

Author: josemontespg

renderers/angular/src/v0_9/core/types.ts

@@ -73,24 +73,28 @@ type DataBindingType = z.infer<typeof DataBindingSchema>;
 type FunctionCallType = z.infer<typeof FunctionCallSchema>;
 type DynamicTypes = DataBindingType | FunctionCallType;
 
-type ResolveAngularProp<T> = T extends any
-  ? T extends null | undefined
-    ? T
-    : [T] extends [ChildList]
-      ? Child[]
-      : [T] extends [ComponentId]
-        ? Child
-        : Exclude<T, DynamicTypes> extends never
-          ? any
-          : ResolveAngularPropNested<Exclude<T, DynamicTypes>>
-  : never;
+type UnwrappedDynamic<T> = Exclude<T, DynamicTypes>;
 
 type ResolveAngularPropNested<T> = T extends (infer U)[]
   ? ResolveAngularProp<U>[]
   : T extends object
     ? {[K in keyof T]: ResolveAngularProp<T[K]>}
     : T;
 
+type ResolveNonComponentProp<T> = UnwrappedDynamic<T> extends never
+  ? any
+  : ResolveAngularPropNested<UnwrappedDynamic<T>>;
+
+type ResolveNonNullAngularProp<T> = [T] extends [ChildList]
+  ? Child[]
+  : [T] extends [ComponentId]
+    ? Child
+    : ResolveNonComponentProp<T>;
+
+export type ResolveAngularProp<T> = T extends null | undefined
+  ? T
+  : ResolveNonNullAngularProp<T>;
+
 type InferredInterfaceToProps<InferredSchema> = {
   [K in keyof InferredSchema]: BoundProperty<ResolveAngularProp<InferredSchema[K]>>;
 };

renderers/web_core/src/v0_9/processing/message-processor.test.ts

@@ -67,11 +67,11 @@ describe('MessageProcessor', () => {
       assert.deepStrictEqual(buttonSchema.allOf[1].required, ['component', 'label']);
     });
 
-    it('transforms REF: descriptions into valid $ref nodes', () => {
+    it('transforms schemas with refPath into valid $ref nodes', () => {
       const customApi: ComponentApi = {
         name: 'Custom',
         schema: z.object({
-          title: z.string().describe('REF:common_types.json#/$defs/DynamicString|The title'),
+          title: z.string().describe('The title').setRefPath('common_types.json#/$defs/DynamicString'),
         }),
       };
       const cat = new Catalog('cat-ref', [customApi]);
@@ -105,7 +105,7 @@ describe('MessageProcessor', () => {
       };
 
       const themeSchema = z.object({
-        primaryColor: z.string().describe('REF:common_types.json#/$defs/Color|The main color'),
+        primaryColor: z.string().describe('The main color').setRefPath('common_types.json#/$defs/Color'),
       });
 
       const cat = new Catalog('cat-full', [buttonApi], [addFn], themeSchema);
@@ -151,7 +151,8 @@ describe('MessageProcessor', () => {
             z.object({
               action: z
                 .string()
-                .describe('REF:common_types.json#/$defs/Action|The action to perform'),
+                .describe('The action to perform')
+                .setRefPath('common_types.json#/$defs/Action'),
             }),
           ),
         }),
@@ -172,8 +173,8 @@ describe('MessageProcessor', () => {
       const edgeApi: ComponentApi = {
         name: 'EdgeComp',
         schema: z.object({
-          noPipe: z.string().describe('REF:common_types.json#/$defs/NoPipe'),
-          multiPipe: z.string().describe('REF:common_types.json#/$defs/MultiPipe|First|Second'),
+          noPipe: z.string().setRefPath('common_types.json#/$defs/NoPipe'),
+          multiPipe: z.string().describe('First|Second').setRefPath('common_types.json#/$defs/MultiPipe'),
         }),
       };
       const cat = new Catalog('cat-edge', [edgeApi]);
@@ -186,7 +187,7 @@ describe('MessageProcessor', () => {
       assert.strictEqual(properties.noPipe.description, undefined);
 
       assert.strictEqual(properties.multiPipe.$ref, 'common_types.json#/$defs/MultiPipe');
-      assert.strictEqual(properties.multiPipe.description, 'First');
+      assert.strictEqual(properties.multiPipe.description, 'First|Second');
     });
 
     it('handles multiple catalogs correctly', () => {

renderers/web_core/src/v0_9/processing/message-processor.ts

@@ -19,7 +19,9 @@ 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 {zodToJsonSchema} from 'zod-to-json-schema';
+import {zodToJsonSchema, ignoreOverride} from 'zod-to-json-schema';
+import {A2uiTypeDef} from '../schema/common-types.js';
+import '../schema/common-types.js';
 
 import {
   A2uiMessage,
@@ -41,6 +43,20 @@ export interface CapabilitiesOptions {
   includeInlineCatalogs?: boolean;
 }
 
+const zodToJsonSchemaOptions = {
+  target: 'jsonSchema2019-09' as const,
+  override: (def: any) => {
+    const a2uiDef = def as A2uiTypeDef;
+    if (a2uiDef.refPath) {
+      return {
+        $ref: a2uiDef.refPath,
+        description: (def as any).description,
+      };
+    }
+    return ignoreOverride;
+  },
+};
+
 /**
  * The central processor for A2UI messages.
  * @template T The concrete type of the ComponentApi.
@@ -88,12 +104,7 @@ export class MessageProcessor<T extends ComponentApi> {
     const components: Record<string, any> = {};
 
     for (const [name, api] of catalog.components.entries()) {
-      const zodSchema = zodToJsonSchema(api.schema, {
-        target: 'jsonSchema2019-09',
-      }) as any;
-
-      // Clean up Zod-specific artifacts and process REF: tags
-      this.processRefs(zodSchema);
+      const zodSchema = zodToJsonSchema(api.schema as any, zodToJsonSchemaOptions) as any;
 
       // Wrap in standard A2UI component envelope (ComponentCommon)
       components[name] = {
@@ -112,11 +123,7 @@ export class MessageProcessor<T extends ComponentApi> {
 
     const functions: any[] = [];
     for (const api of catalog.functions.values()) {
-      const zodSchema = zodToJsonSchema(api.schema, {
-        target: 'jsonSchema2019-09',
-      }) as any;
-
-      this.processRefs(zodSchema);
+      const zodSchema = zodToJsonSchema(api.schema as any, zodToJsonSchemaOptions) as any;
 
       functions.push({
         name: api.name,
@@ -128,11 +135,7 @@ export class MessageProcessor<T extends ComponentApi> {
 
     let theme: Record<string, any> | undefined;
     if (catalog.themeSchema) {
-      const zodSchema = zodToJsonSchema(catalog.themeSchema, {
-        target: 'jsonSchema2019-09',
-      }) as any;
-
-      this.processRefs(zodSchema);
+      const zodSchema = zodToJsonSchema(catalog.themeSchema as any, zodToJsonSchemaOptions) as any;
       theme = zodSchema.properties;
     }
 
@@ -144,39 +147,7 @@ export class MessageProcessor<T extends ComponentApi> {
     };
   }
 
-  private processRefs(node: any): void {
-    if (typeof node !== 'object' || node === null) return;
-
-    // If the node itself is a REF target, transform it and stop recursion.
-    if (typeof node.description === 'string' && node.description.startsWith('REF:')) {
-      const parts = node.description.substring(4).split('|');
-      const ref = parts[0];
-      const desc = parts[1] || '';
-
-      // Clear the node of all other properties.
-      for (const k of Object.keys(node)) {
-        delete node[k];
-      }
 
-      // Re-add only the $ref and an optional description.
-      node['$ref'] = ref;
-      if (desc) {
-        node['description'] = desc;
-      }
-      return;
-    }
-
-    // If not a REF target, recurse into its children.
-    if (Array.isArray(node)) {
-      for (const item of node) {
-        this.processRefs(item);
-      }
-    } else {
-      for (const key of Object.keys(node)) {
-        this.processRefs(node[key]);
-      }
-    }
-  }
 
   /**
    * Returns the aggregated data model for all surfaces that have 'sendDataModel' enabled.

renderers/web_core/src/v0_9/rendering/generic-binder.ts

@@ -146,26 +146,30 @@ type IsDynamic<T> = DataBinding extends NonNullable<T> ? true : false;
  * Maps raw Zod inferred types to their resolved runtime equivalents.
  * For example, an `Action` object becomes a callable `() => void` function.
  */
-export type ResolveA2uiProp<T> = T extends any
-  ? T extends null | undefined
-    ? T
-    : [T] extends [Action]
-      ? () => void
-      : [T] extends [ChildList]
-        ? any
-        : [T] extends [ComponentId]
-          ? {id: ComponentId; basePath: string}
-          : Exclude<T, DynamicTypes> extends never
-            ? any
-            : ResolveA2uiPropNested<Exclude<T, DynamicTypes>>
-  : never;
+type UnwrappedDynamic<T> = Exclude<T, DynamicTypes>;
 
 type ResolveA2uiPropNested<T> = T extends (infer U)[]
   ? ResolveA2uiProp<U>[]
   : T extends object
     ? {[K in keyof T]: ResolveA2uiProp<T[K]>}
     : T;
 
+type ResolveNonComponentA2uiProp<T> = UnwrappedDynamic<T> extends never
+  ? any
+  : ResolveA2uiPropNested<UnwrappedDynamic<T>>;
+
+type ResolveNonNullA2uiProp<T> = [T] extends [Action]
+  ? () => void
+  : [T] extends [ChildList]
+    ? any
+    : [T] extends [ComponentId]
+      ? {id: ComponentId; basePath: string}
+      : ResolveNonComponentA2uiProp<T>;
+
+export type ResolveA2uiProp<T> = T extends null | undefined
+  ? T
+  : ResolveNonNullA2uiProp<T>;
+
 /**
  * Automatically generates two-way binding setters for dynamic properties.
  * If a schema has a `value: DynamicString`, this type generates a `setValue(val: string)` method.