@ankhorage/contracts 25.2.0 → 26.0.1

package/src/bindings.test.ts

@@ -1,15 +1,13 @@
-import { readOwnProperty } from '@ankhorage/utility/object';
 import { describe, expect, it } from 'bun:test';
 
+import {
+  isComponentDataBindingRegistry,
+  isScreenDataLoaderDefinition,
+} from './appManifest/bindings';
 import type {
-  AppManifest,
-  BindingInputMap,
-  BindingValueSource,
-  ComponentDataBinding,
+  BindingExpression,
+  BindingInvocation,
   ComponentDataBindingRegistry,
-  EventBinding,
-  OperationScreenDataLoaderDefinition,
-  PropBinding,
   ScreenDataLoaderDefinition,
 } from './index';
 
@@ -17,420 +15,80 @@ function assertSerializable<TValue>(value: TValue): void {
   expect(JSON.parse(JSON.stringify(value))).toEqual(value);
 }
 
-describe('component data-binding contracts', () => {
-  it('serializes a component prop bound to an operation response path', () => {
-    const binding: ComponentDataBinding = {
-      componentId: 'hero-title',
-      componentType: 'Text',
-      props: {
-        children: {
-          source: {
-            kind: 'operation',
-            operation: {
-              apiId: 'cms',
-              endpointId: 'pages',
-              operationId: 'pages.getHome',
-            },
-            path: '$.data.title',
-          },
-          fallback: {
-            value: 'Untitled',
-          },
-          loading: {
-            state: 'loading',
-            fallback: {
-              value: 'Loading…',
-            },
-          },
-          error: {
-            state: 'error',
-            message: 'Could not load title.',
-            fallback: {
-              value: 'Untitled',
-            },
-          },
-          transforms: ['trim'],
-        },
-      },
-    };
-
-    assertSerializable(binding);
-    expect(binding.props?.children?.source.kind).toBe('operation');
-  });
-
-  it('serializes literal, context, event, state, and operation value sources', () => {
-    const sources: readonly BindingValueSource[] = [
-      { kind: 'literal', value: { fallback: 'Untitled' } },
-      { kind: 'context', path: 'auth.user.displayName' },
-      { kind: 'event', path: 'payload.values.search' },
-      { kind: 'state', path: 'forms.search.query' },
-      {
-        kind: 'operation',
-        operation: {
-          apiId: 'search-api',
-          operationId: 'search.query',
-        },
-        path: '$.results',
-      },
-    ];
-
-    assertSerializable(sources);
-    expect(sources.map((source) => source.kind)).toEqual([
-      'literal',
-      'context',
-      'event',
-      'state',
-      'operation',
-    ]);
-  });
-
-  it('serializes an event binding that executes an API operation', () => {
-    const input: BindingInputMap = {
-      email: {
-        kind: 'source',
-        source: {
-          kind: 'event',
-          path: 'payload.values.email',
-        },
-        transforms: ['trim', 'lowercase'],
-      },
-      message: {
-        kind: 'source',
-        source: {
-          kind: 'event',
-          path: 'payload.values.message',
-        },
-      },
-      source: {
-        kind: 'literal',
-        value: 'contact-form',
-      },
-      metadata: {
-        kind: 'object',
-        fields: {
-          userId: {
-            kind: 'source',
-            source: {
-              kind: 'context',
-              path: 'auth.user.id',
-            },
-          },
-        },
-      },
+describe('capability binding contracts', () => {
+  it('uses an emitted capability as a readable reference with a projected path', () => {
+    const reference: BindingExpression = {
+      capability: 'event.formChanged',
+      path: 'payload.values.email',
     };
 
-    const binding: EventBinding = {
-      target: {
-        kind: 'operation',
-        operation: {
-          apiId: 'contact-api',
-          endpointId: 'messages',
-          operationId: 'messages.create',
-        },
-      },
-      input,
-      when: {
-        source: {
-          kind: 'event',
-          path: 'payload.values.email',
-        },
-        operator: 'exists',
-      },
-    };
-
-    assertSerializable(binding);
-    expect(binding.target.kind).toBe('operation');
-    expect(binding.input?.email?.kind).toBe('source');
+    assertSerializable(reference);
+    expect(reference).toEqual({ capability: 'event.formChanged', path: 'payload.values.email' });
   });
 
-  it('serializes an event binding that targets a named action', () => {
-    const binding: EventBinding = {
-      target: {
-        kind: 'action',
-        type: 'toast.show',
-      },
+  it('uses an invoke capability as the one event target shape', () => {
+    const target: BindingInvocation = {
+      capability: 'api.contact.createMessage',
       input: {
-        message: {
-          kind: 'literal',
-          value: 'Saved successfully.',
-        },
+        email: { capability: 'event.formChanged', path: 'payload.values.email' },
       },
+      result: 'submittedMessage',
     };
 
-    assertSerializable(binding);
-    expect(binding.target.kind).toBe('action');
-  });
-
-  it('serializes canonical operation screen data loaders', () => {
-    const loader: ScreenDataLoaderDefinition = {
-      kind: 'operation',
-      id: 'product-detail',
-      operation: {
-        apiId: 'nutrition',
-        endpointId: 'products',
-        operationId: 'nutrition.products.getById',
-      },
-      input: {
-        id: {
-          kind: 'source',
-          source: {
-            kind: 'context',
-            path: 'route.params.id',
-          },
-        },
-      },
-    } satisfies OperationScreenDataLoaderDefinition;
-
-    assertSerializable(loader);
-    expect(loader.kind).toBe('operation');
+    assertSerializable(target);
+    expect(target.capability).toBe('api.contact.createMessage');
   });
 
-  it('serializes scanner lookup and conditional navigation intent using existing generic bindings', () => {
-    const productLookupOperation = {
-      apiId: 'nutrition',
-      endpointId: 'products',
-      operationId: 'products.lookupByBarcode',
-    } as const;
-
-    const bindings: ComponentDataBindingRegistry = {
-      scanner: {
-        componentId: 'scanner',
-        componentType: 'BarcodeScannerView',
-        events: {
-          barcodeScanned: [
-            {
-              target: {
-                kind: 'operation',
-                operation: productLookupOperation,
-              },
-              input: {
-                barcode: {
-                  kind: 'source',
-                  source: {
-                    kind: 'event',
-                    path: 'payload.value',
-                  },
-                  transforms: ['trim'],
-                },
-              },
-              when: {
-                source: {
-                  kind: 'event',
-                  path: 'payload.value',
-                },
-                operator: 'exists',
-              },
-            },
-            {
-              target: {
-                kind: 'action',
-                type: 'navigate',
-              },
-              input: {
-                route: {
-                  kind: 'literal',
-                  value: 'product-detail',
-                },
-                params: {
-                  kind: 'object',
-                  fields: {
-                    barcode: {
-                      kind: 'source',
-                      source: {
-                        kind: 'event',
-                        path: 'payload.value',
-                      },
-                      transforms: ['trim'],
-                    },
-                    productId: {
-                      kind: 'source',
-                      source: {
-                        kind: 'operation',
-                        operation: productLookupOperation,
-                        path: 'product.id',
-                      },
-                    },
-                  },
-                },
-              },
-              when: {
-                source: {
-                  kind: 'operation',
-                  operation: productLookupOperation,
-                  path: 'product.id',
-                },
-                operator: 'exists',
-              },
-            },
-            {
-              target: {
-                kind: 'action',
-                type: 'navigate',
-              },
-              input: {
-                route: {
-                  kind: 'literal',
-                  value: 'product-capture',
-                },
-                params: {
-                  kind: 'object',
-                  fields: {
-                    barcode: {
-                      kind: 'source',
-                      source: {
-                        kind: 'event',
-                        path: 'payload.value',
-                      },
-                      transforms: ['trim'],
-                    },
-                  },
-                },
-              },
-              when: {
-                source: {
-                  kind: 'operation',
-                  operation: productLookupOperation,
-                  path: 'product.id',
-                },
-                operator: 'notExists',
-              },
-            },
-          ],
-        },
-      },
+  it('references a cached invocation result without modelling another execution target', () => {
+    const reference: BindingExpression = {
+      capability: 'api.products.lookup',
+      result: 'lookup',
+      path: 'product.id',
     };
 
-    assertSerializable(bindings);
-    expect(bindings.scanner?.events?.barcodeScanned).toHaveLength(3);
-    expect(bindings.scanner?.events?.barcodeScanned?.[0]?.target.kind).toBe('operation');
-    expect(bindings.scanner?.events?.barcodeScanned?.[1]?.when?.source.kind).toBe('operation');
-    expect(bindings.scanner?.events?.barcodeScanned?.[2]?.target.type).toBe('navigate');
+    assertSerializable(reference);
+    expect(reference.result).toBe('lookup');
   });
 
-  it('serializes repeated container nodes with generic item-context bindings', () => {
-    const productsListOperation = {
-      apiId: 'catalog-api',
-      endpointId: 'products',
-      operationId: 'products.list',
-    } as const;
-
-    const root: AppManifest['screens'][string]['root'] = {
-      id: 'products-grid',
-      type: 'Grid',
-      repeat: {
-        source: {
-          kind: 'operation',
-          operation: productsListOperation,
-        },
-        itemAlias: 'item',
-        keyPath: 'id',
-      },
-      children: [
-        {
-          id: 'product-card-template',
-          type: 'ProductCard',
-        },
-      ],
-    };
-
-    const bindings: ComponentDataBindingRegistry = {
-      'product-card-template': {
-        componentId: 'product-card-template',
-        componentType: 'ProductCard',
-        props: {
-          title: {
-            source: {
-              kind: 'context',
-              path: 'item.name',
-            },
-          },
-          brand: {
-            source: {
-              kind: 'context',
-              path: 'item.brand',
-            },
-          },
-          description: {
-            source: {
-              kind: 'context',
-              path: 'item.barcode',
+  it('keeps nested literal and reference objects and arrays expressible', () => {
+    const expression: BindingExpression = {
+      kind: 'object',
+      fields: {
+        route: { kind: 'literal', value: '/products/[id]' },
+        params: {
+          kind: 'object',
+          fields: {
+            id: { capability: 'api.products.lookup', result: 'lookup', path: 'product.id' },
+            tags: {
+              kind: 'array',
+              items: [
+                { kind: 'literal', value: 'featured' },
+                { capability: 'state.search', path: 'selectedTag' },
+              ],
             },
           },
         },
-        events: {
-          press: [
-            {
-              target: {
-                kind: 'action',
-                type: 'navigate',
-              },
-              input: {
-                route: {
-                  kind: 'literal',
-                  value: '/products/[id]',
-                },
-                params: {
-                  kind: 'object',
-                  fields: {
-                    id: {
-                      kind: 'source',
-                      source: {
-                        kind: 'context',
-                        path: 'item.id',
-                      },
-                    },
-                  },
-                },
-              },
-            },
-          ],
-        },
       },
     };
 
-    assertSerializable({ root, bindings });
-    expect(root.repeat).toEqual({
-      source: {
-        kind: 'operation',
-        operation: productsListOperation,
-      },
-      itemAlias: 'item',
-      keyPath: 'id',
-    });
-    expect(bindings['product-card-template']?.props?.title?.source).toEqual({
-      kind: 'context',
-      path: 'item.name',
-    });
-    expect(bindings['product-card-template']?.events?.press?.[0]?.input?.params).toEqual({
-      kind: 'object',
-      fields: {
-        id: {
-          kind: 'source',
-          source: {
-            kind: 'context',
-            path: 'item.id',
-          },
-        },
-      },
-    });
+    assertSerializable(expression);
+    expect(expression.kind).toBe('object');
   });
 
-  it('serializes component data-binding registries', () => {
+  it('uses recursive expressions for transforms, conditions and fallbacks', () => {
     const bindings: ComponentDataBindingRegistry = {
-      'submit-button': {
-        componentId: 'submit-button',
-        componentType: 'Button',
+      submit: {
+        componentId: 'submit',
         props: {
           children: {
-            source: {
-              kind: 'literal',
-              value: 'Send',
-            },
-          },
-          disabled: {
-            source: {
-              kind: 'state',
-              path: 'forms.contact.isSubmitting',
+            value: {
+              kind: 'fallback',
+              value: {
+                kind: 'transform',
+                value: { capability: 'state.profile', path: 'displayName' },
+                transforms: ['trim'],
+              },
+              fallback: { kind: 'literal', value: 'Guest' },
             },
           },
         },
@@ -438,11 +96,13 @@ describe('component data-binding contracts', () => {
           press: [
             {
               target: {
-                kind: 'operation',
-                operation: {
-                  apiId: 'contact-api',
-                  operationId: 'messages.create',
-                },
+                capability: 'navigator.navigate',
+                input: { route: { kind: 'literal', value: 'home' } },
+              },
+              when: {
+                source: { capability: 'event.press', path: 'payload.enabled' },
+                operator: 'eq',
+                value: { kind: 'literal', value: true },
               },
             },
           ],
@@ -451,124 +111,34 @@ describe('component data-binding contracts', () => {
     };
 
     assertSerializable(bindings);
-    expect(bindings['submit-button']?.events?.press?.[0]?.target.kind).toBe('operation');
+    expect(isComponentDataBindingRegistry(bindings)).toBe(true);
   });
 
-  it('serializes app-level APIs and dataBindings on the manifest', () => {
-    const propBinding: PropBinding = {
-      source: {
-        kind: 'operation',
-        operation: {
-          apiId: 'cms',
-          endpointId: 'pages',
-          operationId: 'pages.getHome',
-        },
-        path: '$.data.heroTitle',
-      },
+  it('uses the same invocation shape for screen loaders', () => {
+    const loader: ScreenDataLoaderDefinition = {
+      capability: 'api.products.getById',
+      result: 'product',
+      input: { id: { capability: 'context.route', path: 'params.id' } },
     };
 
-    const manifest: AppManifest = {
-      metadata: {
-        name: 'Demo',
-        slug: 'demo',
-        version: '1.0.0',
-        category: 'developer_tools',
-        themeId: 'default',
-      },
-      themes: {
-        default: {
-          id: 'default',
-          name: 'Default',
-          light: {
-            primaryColor: '#3366ff',
-            harmony: 'analogous',
-          },
-          dark: {
-            primaryColor: '#3366ff',
-            harmony: 'analogous',
-          },
-        },
-      },
-      activeThemeId: 'default',
-      infra: {
-        environments: {
-          local: {
-            deployment: { compute: { provider: 'local' }, runtime: { provider: 'minikube' } },
-          },
-        },
-        apis: {
-          cms: {
-            id: 'cms',
-            origin: 'external',
-            protocol: 'rest',
-            baseUrl: 'https://cms.example.com',
-            endpoints: {
-              pages: {
-                id: 'pages',
-                kind: 'http',
-                path: '/pages/home',
-                operations: {
-                  'pages.getHome': {
-                    id: 'pages.getHome',
-                    endpointId: 'pages',
-                    protocol: 'http',
-                    intent: 'read',
-                    method: 'GET',
-                    path: '/pages/home',
-                  },
-                },
-              },
-            },
-          },
-        },
-        modules: {},
-      },
-      navigator: {
-        type: 'stack',
-        routes: [
-          {
-            name: 'home',
-            screenId: 'home',
-          },
-        ],
-      },
-      screens: {
-        home: {
-          id: 'home',
-          name: 'Home',
-          root: {
-            id: 'screen-root',
-            type: 'Screen',
-            children: [
-              {
-                id: 'hero-title',
-                type: 'Text',
-              },
-            ],
-          },
-        },
-      },
-      dataBindings: {
-        'hero-title': {
-          componentId: 'hero-title',
-          componentType: 'Text',
-          props: {
-            children: propBinding,
-          },
-        },
-      },
-      settings: {
-        localization: {
-          defaultLocale: 'en',
-          locales: ['en'],
-        },
-      },
-    };
+    assertSerializable(loader);
+    expect(isScreenDataLoaderDefinition(loader)).toBe(true);
+  });
 
-    assertSerializable(manifest);
-    expect(manifest.dataBindings?.['hero-title']?.props?.children?.source.kind).toBe('operation');
-    expect(manifest.infra.apis ? readOwnProperty(manifest.infra.apis, 'cms')?.id : undefined).toBe(
-      'cms',
-    );
+  it('rejects superseded action, operation and source union shapes', () => {
+    expect(
+      isComponentDataBindingRegistry({
+        submit: {
+          componentId: 'submit',
+          events: { press: [{ target: { kind: 'action', type: 'navigate' } }] },
+        },
+      }),
+    ).toBe(false);
+    expect(
+      isScreenDataLoaderDefinition({
+        kind: 'operation',
+        operation: { apiId: 'products', operationId: 'products.list' },
+      }),
+    ).toBe(false);
   });
 });