@ankhorage/contracts 1.10.0 → 1.12.0

package/src/contracts.test.ts

@@ -5,8 +5,6 @@ import { COLOR_HARMONIES } from '@ankhorage/color-theory';
 import { describe, expect, it } from 'bun:test';
 
 import {
-  type ActionBinding,
-  type ActionValueSource,
   APP_CATEGORIES,
   type AppCategory,
   AUTH_PROVIDERS,
@@ -21,22 +19,16 @@ import {
   type DbAdapter,
   type DbAdminAdapter,
   type DbChangeEvent,
-  type DbPersistActionBinding,
-  type DbPersistCommand,
   type DbRealtimeAdapter,
   DEPLOYMENT_TARGETS,
-  type EmailSendActionBinding,
   type FormSubmitEventDto,
   type ImageAssetSource,
-  type KnownActionBinding,
-  type KnownCommandDto,
   NAVIGATOR_TYPES,
   type StoragePublicUrlResult,
   type StorageResult,
   type StorageUploadResult,
   type ThemeConfig,
   type ThemeModeConfig,
-  type UiNode,
 } from './index';
 
 async function collectTypeScriptFiles(directory: string): Promise<string[]> {
@@ -236,55 +228,6 @@ describe('contracts', () => {
     expect(JSON.parse(JSON.stringify(source))).toEqual(source);
   });
 
-  it('serializes node event bindings for submit actions', () => {
-    const node: UiNode = {
-      id: 'contact-form',
-      type: 'Form',
-      props: {
-        title: 'Contact us',
-      },
-      events: {
-        submit: [
-          {
-            type: 'email.send',
-            payload: {
-              to: 'info@example.com',
-              subject: 'New contact message',
-              bodyFrom: 'payload.values.message',
-            },
-          },
-          {
-            type: 'db.persist',
-            payload: {
-              collection: 'contact_messages',
-              mode: 'columns',
-            },
-          },
-        ],
-      },
-    };
-
-    expect(JSON.parse(JSON.stringify(node))).toEqual(node);
-    expect(node.events?.submit?.map((action) => action.type)).toEqual(['email.send', 'db.persist']);
-  });
-
-  it('accepts conditional node event bindings', () => {
-    const binding: ActionBinding = {
-      type: 'db.persist',
-      payload: {
-        collection: 'contact_messages',
-      },
-      when: {
-        source: 'event',
-        path: 'payload.values.email',
-        operator: 'exists',
-      },
-    };
-
-    expect(binding.when?.operator).toBe('exists');
-    expect(binding.payload?.collection).toBe('contact_messages');
-  });
-
   it('serializes normalized form submit event DTOs', () => {
     const event: FormSubmitEventDto = {
       type: 'form.submit',
@@ -344,121 +287,6 @@ describe('contracts', () => {
     expect(knownEventType).toBe('form.submit');
   });
 
-  it('serializes provider-neutral value sources for action payloads', () => {
-    const sources: readonly ActionValueSource[] = [
-      { source: 'event', path: 'payload.values.email' },
-      { source: 'literal', value: 'website-contact-form' },
-      { source: 'context', path: 'auth.user.id' },
-      { source: 'state', path: 'forms.contact.isSubmitting' },
-    ];
-
-    expect(JSON.parse(JSON.stringify(sources))).toEqual(sources);
-    expect(sources.map((source) => source.source)).toEqual([
-      'event',
-      'literal',
-      'context',
-      'state',
-    ]);
-  });
-
-  it('serializes a typed db.persist action binding', () => {
-    const binding: DbPersistActionBinding = {
-      type: 'db.persist',
-      payload: {
-        collection: 'contact_messages',
-        mode: 'columns',
-        values: [
-          {
-            field: 'firstname',
-            valueFrom: { source: 'event', path: 'payload.values.firstname' },
-            transform: 'trim',
-          },
-          {
-            field: 'message',
-            valueFrom: { source: 'event', path: 'payload.values.message' },
-          },
-          {
-            field: 'source',
-            valueFrom: { source: 'literal', value: 'website-contact-form' },
-          },
-        ],
-      },
-    };
-
-    expect(JSON.parse(JSON.stringify(binding))).toEqual(binding);
-    expect(binding.payload.values.map((value) => value.field)).toEqual([
-      'firstname',
-      'message',
-      'source',
-    ]);
-  });
-
-  it('serializes a typed email.send action binding', () => {
-    const binding: EmailSendActionBinding = {
-      type: 'email.send',
-      payload: {
-        to: 'info@example.com',
-        subject: 'New contact message',
-        bodyFrom: { source: 'event', path: 'payload.values.message' },
-      },
-    };
-
-    expect(JSON.parse(JSON.stringify(binding))).toEqual(binding);
-    expect(binding.payload.bodyFrom?.source).toBe('event');
-  });
-
-  it('accepts typed action bindings in node event bindings', () => {
-    const persist: DbPersistActionBinding = {
-      type: 'db.persist',
-      payload: {
-        collection: 'contact_messages',
-        values: [
-          {
-            field: 'message',
-            valueFrom: { source: 'event', path: 'payload.values.message' },
-          },
-        ],
-      },
-    };
-    const email: EmailSendActionBinding = {
-      type: 'email.send',
-      payload: {
-        to: 'info@example.com',
-        bodyFrom: { source: 'event', path: 'payload.values.message' },
-      },
-    };
-    const node: UiNode = {
-      id: 'contact-form',
-      type: 'Form',
-      events: {
-        submit: [persist, email],
-      },
-    };
-    const known: KnownActionBinding = persist;
-
-    expect(node.events?.submit?.map((action) => action.type)).toEqual(['db.persist', 'email.send']);
-    expect(known.type).toBe('db.persist');
-  });
-
-  it('serializes a normalized db.persist command DTO', () => {
-    const command: DbPersistCommand = {
-      type: 'db.persist.command',
-      payload: {
-        operation: 'insert',
-        collection: 'contact_messages',
-        mode: 'columns',
-        values: {
-          firstname: 'Fabio',
-          message: 'This is my contact message',
-        },
-      },
-    };
-    const knownCommand: KnownCommandDto = command;
-
-    expect(JSON.parse(JSON.stringify(command))).toEqual(command);
-    expect(knownCommand.type).toBe('db.persist.command');
-  });
-
   it('accepts a provider-neutral CRUD database adapter', async () => {
     const adapter: DbAdapter = {
       capabilities: {

package/src/types.ts

@@ -1,7 +1,8 @@
 import type { ColorHarmony } from '@ankhorage/color-theory';
 
 import type { AuthFlowConfig, AuthIdentifierKind, AuthSignUpField } from './auth';
-import type { NodePropBinding } from './bindings';
+import type { ComponentDataBindingRegistry } from './bindings';
+import type { DataSourceRegistry } from './data';
 
 export interface ThemeModeConfig {
   primaryColor: string;
@@ -89,121 +90,6 @@ export type ManifestValue =
   | readonly ManifestValue[]
   | { readonly [key: string]: ManifestValue };
 
-export type ActionValue = ManifestValue;
-
-export type ActionBindingPayload = Record<string, ActionValue>;
-
-export type ActionConditionSource = 'context' | 'event' | 'state';
-
-export type ActionConditionOperator = 'eq' | 'exists' | 'neq' | 'notExists';
-
-export interface ActionCondition {
-  readonly source: ActionConditionSource;
-  readonly path: string;
-  readonly operator: ActionConditionOperator;
-  readonly value?: ActionValue;
-}
-
-export type ActionValueSource =
-  | {
-      readonly source: 'context';
-      readonly path: string;
-    }
-  | {
-      readonly source: 'event';
-      readonly path: string;
-    }
-  | {
-      readonly source: 'literal';
-      readonly value: ActionValue;
-    }
-  | {
-      readonly source: 'state';
-      readonly path: string;
-    };
-
-export type ActionValueTransform = 'lowercase' | 'trim' | 'uppercase';
-
-export interface ActionValueBinding {
-  readonly valueFrom: ActionValueSource;
-  readonly transform?: ActionValueTransform | readonly ActionValueTransform[];
-}
-
-export interface ActionBinding<
-  TType extends string = string,
-  TPayload extends object = ActionBindingPayload,
-> {
-  readonly type: TType;
-  readonly payload?: TPayload;
-  readonly when?: ActionCondition;
-}
-
-export type DbPersistMode = 'columns' | 'json';
-
-export interface DbPersistFieldBinding {
-  readonly field: string;
-  readonly valueFrom: ActionValueSource;
-  readonly transform?: ActionValueTransform | readonly ActionValueTransform[];
-}
-
-export interface DbPersistActionPayload {
-  readonly collection: string;
-  readonly kind?: string;
-  readonly mode?: DbPersistMode;
-  readonly jsonField?: string;
-  readonly values: readonly DbPersistFieldBinding[];
-}
-
-export interface DbPersistActionBinding extends ActionBinding<
-  'db.persist',
-  DbPersistActionPayload
-> {
-  readonly payload: DbPersistActionPayload;
-}
-
-export interface EmailSendActionPayload {
-  readonly to: string;
-  readonly subject?: string;
-  readonly body?: string;
-  readonly bodyFrom?: ActionValueSource;
-}
-
-export interface EmailSendActionBinding extends ActionBinding<
-  'email.send',
-  EmailSendActionPayload
-> {
-  readonly payload: EmailSendActionPayload;
-}
-
-export type KnownActionBinding = DbPersistActionBinding | EmailSendActionBinding;
-
-export type UiNodeEventBindings = Record<string, readonly ActionBinding<string, object>[]>;
-
-export interface CommandDto<
-  TType extends string = string,
-  TPayload extends object = Record<string, ActionValue>,
-> {
-  readonly type: TType;
-  readonly payload: TPayload;
-}
-
-export type DbPersistOperation = 'insert';
-
-export type DbPersistCommandValues = Record<string, ActionValue>;
-
-export interface DbPersistCommandPayload {
-  readonly operation: DbPersistOperation;
-  readonly collection: string;
-  readonly kind?: string;
-  readonly mode?: DbPersistMode;
-  readonly jsonField?: string;
-  readonly values: DbPersistCommandValues;
-}
-
-export type DbPersistCommand = CommandDto<'db.persist.command', DbPersistCommandPayload>;
-
-export type KnownCommandDto = DbPersistCommand;
-
 export type ComponentEventPayloadValue = ManifestValue;
 
 export interface ComponentEventDto<
@@ -331,10 +217,8 @@ export interface UiNode {
   type: string;
   alias?: string;
   props?: Record<string, unknown>;
-  bindings?: readonly NodePropBinding[];
   children?: UiNode[];
   style?: Record<string, number | string>;
-  events?: UiNodeEventBindings;
 }
 
 export interface ScreenSpec {
@@ -437,6 +321,8 @@ export interface AppManifest {
   infra: InfraManifest;
   navigator: NavigatorSpec;
   screens: Record<string, ScreenSpec>;
+  dataSources?: DataSourceRegistry;
+  dataBindings?: ComponentDataBindingRegistry;
   settings: {
     apiBaseUrl?: string;
     localization: {

package/src/ui.test.ts

@@ -113,6 +113,134 @@ describe('ui component metadata contracts', () => {
     expect(meta.props.columns?.itemSchema?.map((item) => item.key)).toEqual(['id', 'label']);
   });
 
+  it('serializes bindable prop and event metadata on component metadata', () => {
+    const meta: UiComponentMeta = {
+      name: 'Button',
+      category: 'component',
+      directManifestNode: true,
+      allowedChildren: [],
+      bindings: {
+        props: {
+          children: {
+            label: 'Label',
+            description: 'Text content rendered inside the button.',
+            acceptsFallback: true,
+            acceptsTransforms: true,
+            value: {
+              type: 'string',
+              label: 'Button label',
+            },
+          },
+          disabled: {
+            label: 'Disabled',
+            value: {
+              type: 'boolean',
+            },
+          },
+        },
+        events: {
+          press: {
+            label: 'Press',
+            description: 'Runs when the button is pressed.',
+            payload: {
+              eventType: 'button.press',
+              fields: [],
+            },
+          },
+        },
+      },
+      events: {
+        press: {
+          label: 'Press',
+          eventType: 'button.press',
+        },
+      },
+      props: {
+        children: {
+          type: 'string',
+          category: 'Content',
+          label: 'Label',
+        },
+        disabled: {
+          type: 'boolean',
+          category: 'State',
+          label: 'Disabled',
+        },
+      },
+    };
+
+    assertSerializable(meta);
+    expect(meta.bindings?.props?.children?.value.type).toBe('string');
+    expect(meta.bindings?.events?.press?.payload?.eventType).toBe('button.press');
+  });
+
+  it('serializes bindable collection item metadata with nested value fields', () => {
+    const meta: UiComponentMeta = {
+      name: 'List',
+      category: 'pattern',
+      directManifestNode: true,
+      allowedChildren: [],
+      bindings: {
+        props: {
+          items: {
+            label: 'Items',
+            value: {
+              type: 'array',
+              itemType: 'object',
+              fields: [
+                {
+                  path: '$.id',
+                  type: 'string',
+                  label: 'ID',
+                  required: true,
+                },
+                {
+                  path: '$.title',
+                  type: 'string',
+                  label: 'Title',
+                },
+              ],
+            },
+          },
+        },
+        events: {
+          itemPress: {
+            label: 'Item press',
+            payload: {
+              eventType: 'collection.itemPress',
+              fields: [
+                {
+                  path: 'payload.itemId',
+                  type: 'string',
+                  label: 'Item ID',
+                },
+                {
+                  path: 'payload.item',
+                  type: 'record',
+                  label: 'Item',
+                },
+              ],
+            },
+          },
+        },
+      },
+      props: {
+        items: {
+          type: 'array',
+          category: 'Data',
+          label: 'Items',
+        },
+      },
+    };
+
+    assertSerializable(meta);
+    expect(meta.bindings?.props?.items?.value.fields?.map((field) => field.path)).toEqual([
+      '$.id',
+      '$.title',
+    ]);
+    expect(meta.bindings?.events?.itemPress?.payload?.eventType).toBe('collection.itemPress');
+  });
+
   it('serializes a component metadata registry', () => {
     const registry: UiComponentMetaRegistry = {
       Text: {
@@ -120,6 +248,15 @@ describe('ui component metadata contracts', () => {
         category: 'component',
         directManifestNode: true,
         allowedChildren: [],
+        bindings: {
+          props: {
+            children: {
+              value: {
+                type: 'string',
+              },
+            },
+          },
+        },
         props: {
           children: {
             type: 'string',
@@ -139,6 +276,7 @@ describe('ui component metadata contracts', () => {
 
     assertSerializable(registry);
     expect(registry.Screen?.allowedChildren).toEqual(['Text']);
+    expect(registry.Text?.bindings?.props?.children?.value.type).toBe('string');
   });
 
   it('serializes a component package manifest for extension packages', () => {
@@ -151,6 +289,36 @@ describe('ui component metadata contracts', () => {
           category: 'component',
           directManifestNode: true,
           allowedChildren: [],
+          bindings: {
+            props: {
+              fen: {
+                value: {
+                  type: 'string',
+                  label: 'FEN',
+                },
+              },
+            },
+            events: {
+              move: {
+                label: 'Move',
+                payload: {
+                  eventType: 'chess.move',
+                  fields: [
+                    {
+                      path: 'payload.from',
+                      type: 'string',
+                      label: 'From square',
+                    },
+                    {
+                      path: 'payload.to',
+                      type: 'string',
+                      label: 'To square',
+                    },
+                  ],
+                },
+              },
+            },
+          },
           events: {
             move: {
               label: 'Move',
@@ -189,5 +357,6 @@ describe('ui component metadata contracts', () => {
 
     assertSerializable(manifest);
     expect(manifest.components.Chessboard?.events?.move?.eventType).toBe('chess.move');
+    expect(manifest.components.Chessboard?.bindings?.props?.fen?.value.type).toBe('string');
   });
 });

package/src/ui.ts

@@ -85,6 +85,58 @@ export interface UiComponentEventMeta {
   readonly payloadFields?: readonly UiComponentEventPayloadFieldMeta[];
 }
 
+export type UiBindableValueType =
+  | 'array'
+  | 'boolean'
+  | 'date'
+  | 'imageAsset'
+  | 'number'
+  | 'object'
+  | 'record'
+  | 'string'
+  | 'unknown';
+
+export interface UiBindableValueFieldMeta {
+  readonly path: string;
+  readonly type: UiBindableValueType;
+  readonly label?: string;
+  readonly description?: string;
+  readonly required?: boolean;
+}
+
+export interface UiBindableValueMeta {
+  readonly type: UiBindableValueType;
+  readonly label?: string;
+  readonly description?: string;
+  readonly fields?: readonly UiBindableValueFieldMeta[];
+  readonly itemType?: UiBindableValueType;
+}
+
+export interface UiBindablePropMeta {
+  readonly value: UiBindableValueMeta;
+  readonly label?: string;
+  readonly description?: string;
+  readonly required?: boolean;
+  readonly acceptsFallback?: boolean;
+  readonly acceptsTransforms?: boolean;
+}
+
+export interface UiBindableEventPayloadMeta {
+  readonly eventType: UiComponentEventPayloadKind;
+  readonly fields?: readonly UiComponentEventPayloadFieldMeta[];
+}
+
+export interface UiBindableEventMeta {
+  readonly label?: string;
+  readonly description?: string;
+  readonly payload?: UiBindableEventPayloadMeta;
+}
+
+export interface UiComponentBindingMeta {
+  readonly props?: Readonly<Record<string, UiBindablePropMeta>>;
+  readonly events?: Readonly<Record<string, UiBindableEventMeta>>;
+}
+
 export interface UiComponentSlotMeta {
   readonly label?: string;
   readonly allowedChildren?: readonly string[];
@@ -96,6 +148,7 @@ export interface UiComponentMeta {
   readonly description?: string;
   readonly directManifestNode: boolean;
   readonly allowedChildren: readonly string[];
+  readonly bindings?: UiComponentBindingMeta;
   readonly blueprint?: UiComponentBlueprint;
   readonly events?: Readonly<Record<string, UiComponentEventMeta>>;
   readonly i18n?: UiComponentI18nMeta;