feat(bindings): add component data-binding contracts

.changeset/component-data-binding-contracts.md

@@ -0,0 +1,5 @@
+---
+'@ankhorage/contracts': minor
+---
+
+Replace node-local prop bindings with app-level component data-binding contracts that reference data-source operations.

src/bindings.test.ts

@@ -1,96 +1,316 @@
 import { describe, expect, it } from 'bun:test';
 
 import type {
+  AppManifest,
+  BindingInputMap,
   BindingValueSource,
-  DbCollectionQueryBinding,
-  NodePropBinding,
-  UiNode,
+  ComponentDataBinding,
+  ComponentDataBindingRegistry,
+  EventBinding,
+  PropBinding,
 } from './index';
 
-describe('binding contracts', () => {
-  it('serializes a node prop bound to state', () => {
-    const binding: NodePropBinding = {
-      prop: 'value',
-      valueFrom: {
-        source: 'state',
-        path: 'forms.contact.values.firstname',
-      },
-      transform: 'trim',
-    };
-    const node: UiNode = {
-      id: 'firstname-input',
-      type: 'Input',
+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: {
-        label: 'Firstname',
+        children: {
+          source: {
+            kind: 'operation',
+            operation: {
+              dataSourceId: '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'],
+        },
       },
-      bindings: [binding],
     };
 
-    expect(JSON.parse(JSON.stringify(node))).toEqual(node);
-    expect(node.bindings?.[0]?.valueFrom.source).toBe('state');
+    assertSerializable(binding);
+    expect(binding.props?.children?.source.kind).toBe('operation');
   });
 
-  it('serializes a node prop bound to a DB collection query', () => {
-    const query: DbCollectionQueryBinding = {
-      collection: 'posts',
-      schema: 'public',
-      columns: ['id', 'title', 'published'],
-      filters: [{ field: 'published', operator: 'eq', value: true }],
-      sort: [{ field: 'created_at', direction: 'desc' }],
-      page: { limit: 10, offset: 0 },
-      refresh: 'live',
-    };
-    const node: UiNode = {
-      id: 'posts-list',
-      type: 'CollectionList',
-      bindings: [
-        {
-          prop: 'items',
-          valueFrom: {
-            source: 'db.collection',
-            query,
+  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: {
+          dataSourceId: '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 a data-source 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',
+            },
           },
         },
-      ],
+      },
+    };
+
+    const binding: EventBinding = {
+      target: {
+        kind: 'operation',
+        operation: {
+          dataSourceId: 'contact-api',
+          endpointId: 'messages',
+          operationId: 'messages.create',
+        },
+      },
+      input,
+      when: {
+        source: {
+          kind: 'event',
+          path: 'payload.values.email',
+        },
+        operator: 'exists',
+      },
     };
 
-    expect(JSON.parse(JSON.stringify(node))).toEqual(node);
-    expect(node.bindings?.[0]?.valueFrom.source).toBe('db.collection');
+    assertSerializable(binding);
+    expect(binding.target.kind).toBe('operation');
+    expect(binding.input?.email?.kind).toBe('source');
   });
 
-  it('supports literal, context, and event value sources', () => {
-    const sources: readonly BindingValueSource[] = [
-      { source: 'literal', value: { fallback: 'Untitled' } },
-      { source: 'context', path: 'auth.user.displayName' },
-      { source: 'event', path: 'payload.values.search' },
-    ];
+  it('serializes an event binding that targets a named action', () => {
+    const binding: EventBinding = {
+      target: {
+        kind: 'action',
+        type: 'toast.show',
+      },
+      input: {
+        message: {
+          kind: 'literal',
+          value: 'Saved successfully.',
+        },
+      },
+    };
 
-    expect(JSON.parse(JSON.stringify(sources))).toEqual(sources);
-    expect(sources.map((source) => source.source)).toEqual(['literal', 'context', 'event']);
+    assertSerializable(binding);
+    expect(binding.target.kind).toBe('action');
   });
 
-  it('supports static, focus, poll, and live refresh intent', () => {
-    const refreshModes = ['static', 'focus', 'poll', 'live'] as const;
-    const bindings = refreshModes.map(
-      (refresh): NodePropBinding => ({
-        prop: `items.${refresh}`,
-        valueFrom: {
-          source: 'db.collection',
-          query: {
-            collection: 'posts',
-            refresh,
-            pollIntervalMs: refresh === 'poll' ? 30_000 : undefined,
+  it('serializes component data-binding registries', () => {
+    const bindings: ComponentDataBindingRegistry = {
+      'submit-button': {
+        componentId: 'submit-button',
+        componentType: 'Button',
+        props: {
+          children: {
+            source: {
+              kind: 'literal',
+              value: 'Send',
+            },
+          },
+          disabled: {
+            source: {
+              kind: 'state',
+              path: 'forms.contact.isSubmitting',
+            },
           },
         },
-      }),
-    );
+        events: {
+          press: [
+            {
+              target: {
+                kind: 'operation',
+                operation: {
+                  dataSourceId: 'contact-api',
+                  operationId: 'messages.create',
+                },
+              },
+            },
+          ],
+        },
+      },
+    };
 
-    expect(JSON.parse(JSON.stringify(bindings))).toEqual(bindings);
-    expect(bindings.map((binding) => binding.valueFrom.source)).toEqual([
-      'db.collection',
-      'db.collection',
-      'db.collection',
-      'db.collection',
-    ]);
+    assertSerializable(bindings);
+    expect(bindings['submit-button']?.events?.press?.[0]?.target.kind).toBe('operation');
+  });
+
+  it('serializes app-level dataSources and dataBindings on the manifest', () => {
+    const propBinding: PropBinding = {
+      source: {
+        kind: 'operation',
+        operation: {
+          dataSourceId: 'cms',
+          endpointId: 'pages',
+          operationId: 'pages.getHome',
+        },
+        path: '$.data.heroTitle',
+      },
+    };
+
+    const manifest: AppManifest = {
+      metadata: {
+        name: 'Demo',
+        slug: 'demo',
+        version: '1.0.0',
+        themeId: 'default',
+      },
+      themes: [
+        {
+          id: 'default',
+          name: 'Default',
+          light: {
+            primaryColor: '#3366ff',
+            harmony: 'analogous',
+          },
+          dark: {
+            primaryColor: '#3366ff',
+            harmony: 'analogous',
+          },
+        },
+      ],
+      activeThemeId: 'default',
+      infra: {
+        plugins: [],
+      },
+      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',
+              },
+            ],
+          },
+        },
+      },
+      dataSources: {
+        cms: {
+          id: 'cms',
+          kind: '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',
+                },
+              },
+            },
+          },
+        },
+      },
+      dataBindings: {
+        'hero-title': {
+          componentId: 'hero-title',
+          componentType: 'Text',
+          props: {
+            children: propBinding,
+          },
+        },
+      },
+      settings: {
+        localization: {
+          defaultLocale: 'en',
+          locales: ['en'],
+        },
+        authFlow: {
+          signInRoute: '/sign-in',
+          signUpRoute: '/sign-up',
+          signOutRoute: '/sign-out',
+          forgotPasswordRoute: '/forgot-password',
+          postSignInRoute: '/',
+          unauthorizedRoute: '/sign-in',
+        },
+      },
+    };
+
+    assertSerializable(manifest);
+    expect(manifest.dataBindings?.['hero-title']?.props?.children?.source.kind).toBe('operation');
+    expect(manifest.dataSources?.cms?.kind).toBe('rest');
   });
 });