@ankhorage/contracts 25.2.0 → 26.0.1

package/src/bindings.ts

@@ -1,123 +1,76 @@
+import type { Capability } from './capability';
 import type { EntityRegistry, ValueMap } from './collections';
-import type { ApiId, EndpointId, OperationId } from './data';
 import type { SerializableValue } from './serializable';
 
 export type ComponentInstanceId = string;
 export type ComponentTypeId = string;
-
 export type BindingValue = SerializableValue;
-
 export type BindingDataPath = string;
-
 export type BindingValueTransform = 'lowercase' | 'trim' | 'uppercase';
 
-export interface BindingOperationRef {
-  readonly apiId: ApiId;
-  readonly operationId: OperationId;
-  readonly endpointId?: EndpointId;
+/** A portable reference to a readable capability value or a cached invocation result. */
+export interface BindingCapabilityReference {
+  readonly capability: Capability['id'];
+  readonly path?: BindingDataPath;
+  readonly result?: string;
 }
 
-export type BindingValueSource =
-  | {
-      readonly kind: 'context';
-      readonly path: BindingDataPath;
-    }
-  | {
-      readonly kind: 'event';
-      readonly path: BindingDataPath;
-    }
-  | {
-      readonly kind: 'literal';
-      readonly value: BindingValue;
-    }
+/** A portable request to invoke a capability and optionally retain its result in a local slot. */
+export interface BindingInvocation {
+  readonly capability: Capability['id'];
+  readonly input?: BindingInputMap;
+  readonly result?: string;
+}
+
+/** A recursive, serializable value expression used by bindings and invocation inputs. */
+export type BindingExpression =
+  | BindingCapabilityReference
+  | { readonly kind: 'array'; readonly items: readonly BindingExpression[] }
   | {
-      readonly kind: 'operation';
-      readonly operation: BindingOperationRef;
-      readonly path?: BindingDataPath;
+      readonly kind: 'fallback';
+      readonly value: BindingExpression;
+      readonly fallback: BindingExpression;
     }
+  | { readonly kind: 'literal'; readonly value: BindingValue }
+  | { readonly kind: 'object'; readonly fields: ValueMap<string, BindingExpression> }
   | {
-      readonly kind: 'state';
-      readonly path: BindingDataPath;
+      readonly kind: 'transform';
+      readonly value: BindingExpression;
+      readonly transforms: readonly BindingValueTransform[];
     };
 
-export interface BindingValueExpression {
-  readonly source: BindingValueSource;
-  readonly transforms?: readonly BindingValueTransform[];
-}
+export type BindingInputValue = BindingExpression;
+export type BindingInputMap = ValueMap<string, BindingInputValue>;
+export type BindingConditionOperator = 'eq' | 'exists' | 'neq' | 'notExists';
 
-export interface BindingFallback {
-  readonly value?: BindingValue;
-  readonly source?: BindingValueSource;
+/** A condition evaluated from portable binding expressions. */
+export interface BindingCondition {
+  readonly source: BindingExpression;
+  readonly operator: BindingConditionOperator;
+  readonly value?: BindingExpression;
 }
 
-export type BindingLifecycleState = 'empty' | 'error' | 'loading';
-
+/** A lifecycle-specific expression rendered when a bound value reaches one state. */
 export interface BindingLifecycleBehavior {
   readonly state: BindingLifecycleState;
-  readonly fallback?: BindingFallback;
+  readonly value?: BindingExpression;
   readonly message?: string;
 }
 
+export type BindingLifecycleState = 'empty' | 'error' | 'loading';
+
 export interface PropBinding {
-  readonly source: BindingValueSource;
-  readonly fallback?: BindingFallback;
+  readonly value: BindingExpression;
   readonly loading?: BindingLifecycleBehavior;
   readonly error?: BindingLifecycleBehavior;
   readonly empty?: BindingLifecycleBehavior;
-  readonly transforms?: readonly BindingValueTransform[];
 }
 
-export type BindingInputValue =
-  | {
-      readonly kind: 'array';
-      readonly items: readonly BindingInputValue[];
-    }
-  | {
-      readonly kind: 'literal';
-      readonly value: BindingValue;
-    }
-  | {
-      readonly kind: 'object';
-      readonly fields: ValueMap<string, BindingInputValue>;
-    }
-  | {
-      readonly kind: 'source';
-      readonly source: BindingValueSource;
-      readonly transforms?: readonly BindingValueTransform[];
-    };
-
-export type BindingInputMap = ValueMap<string, BindingInputValue>;
-
-export interface OperationScreenDataLoaderDefinition {
-  readonly kind: 'operation';
-  readonly id?: string;
-  readonly operation: BindingOperationRef;
-  readonly input?: BindingInputMap;
-}
-
-export type ScreenDataLoaderDefinition = OperationScreenDataLoaderDefinition;
-
-export type BindingConditionOperator = 'eq' | 'exists' | 'neq' | 'notExists';
-
-export interface BindingCondition {
-  readonly source: BindingValueSource;
-  readonly operator: BindingConditionOperator;
-  readonly value?: BindingValue;
-}
-
-export type EventBindingTarget =
-  | {
-      readonly kind: 'action';
-      readonly type: string;
-    }
-  | {
-      readonly kind: 'operation';
-      readonly operation: BindingOperationRef;
-    };
+/** A screen loader is one capability invocation, optionally storing its result by slot name. */
+export type ScreenDataLoaderDefinition = BindingInvocation;
 
 export interface EventBinding {
-  readonly target: EventBindingTarget;
-  readonly input?: BindingInputMap;
+  readonly target: BindingInvocation;
   readonly when?: BindingCondition;
 }
 

package/src/contracts.test.ts

@@ -219,7 +219,7 @@ describe('contracts', () => {
     expect(theme.recipes?.patterns?.Panel?.padding).toBe('xl');
   });
 
-  it('accepts screens with operation data loaders and repeat empty-state nodes', () => {
+  it('accepts screens with capability loaders and repeat empty-state nodes', () => {
     const manifest: Pick<AppManifest, 'screens'> = {
       screens: {
         products: {
@@ -230,12 +230,8 @@ describe('contracts', () => {
             type: 'Grid',
             repeat: {
               source: {
-                kind: 'operation',
-                operation: {
-                  dataSourceId: 'nutrition-api',
-                  endpointId: 'products',
-                  operationId: 'nutrition.products.list',
-                },
+                capability: 'api.nutrition.productsList',
+                result: 'products',
                 path: 'products',
               },
               empty: [
@@ -252,20 +248,12 @@ describe('contracts', () => {
           },
           dataLoaders: [
             {
-              kind: 'operation',
-              id: 'product-detail',
-              operation: {
-                dataSourceId: 'nutrition-api',
-                endpointId: 'products',
-                operationId: 'nutrition.products.getById',
-              },
+              capability: 'api.nutrition.productsGetById',
+              result: 'product',
               input: {
                 id: {
-                  kind: 'source',
-                  source: {
-                    kind: 'context',
-                    path: 'route.params.id',
-                  },
+                  capability: 'context.route',
+                  path: 'params.id',
                 },
               },
             },
@@ -275,7 +263,9 @@ describe('contracts', () => {
     };
 
     expect(JSON.parse(JSON.stringify(manifest))).toEqual(manifest);
-    expect(manifest.screens.products?.dataLoaders?.[0]?.kind).toBe('operation');
+    expect(manifest.screens.products?.dataLoaders?.[0]?.capability).toBe(
+      'api.nutrition.productsGetById',
+    );
     expect(manifest.screens.products?.root.repeat?.empty?.[0]?.type).toBe('Notice');
   });
 

package/src/structure/generated.ts

@@ -2,12 +2,12 @@
 import type { StructureDescriptorDocument } from '@ankhorage/contracts/structure';
 
 export const STRUCTURE_DESCRIPTOR_COMPILER_VERSION = '6.0.3';
-export const STRUCTURE_DESCRIPTOR_FINGERPRINT = 'sha256:e6117f029e0a0fde13ed1d08fe1a39d7e06a9f83a0d32198865446501875e27d';
+export const STRUCTURE_DESCRIPTOR_FINGERPRINT = 'sha256:241a40ac622d83197bcad3df767803ab8757978774bf935cee990416d3e2774e';
 
 export const STRUCTURE_DESCRIPTOR = {
   "protocolVersion": 1,
   "packageName": "@ankhorage/contracts",
-  "packageVersion": "25.2.0",
+  "packageVersion": "26.0.1",
   "roots": {
     "auth-flow": "AuthFlowConfig",
     "auth-profile": "AuthProfileSpec",

package/src/types.ts

@@ -2,7 +2,7 @@ import type { ColorHarmony } from '@ankhorage/color-theory';
 
 import type { AuthIdentifierKind, AuthSignUpField } from './auth';
 import type {
-  BindingValueSource,
+  BindingExpression,
   ComponentDataBindingRegistry,
   ScreenDataLoaderDefinition,
 } from './bindings';
@@ -153,7 +153,7 @@ export interface SvgIconSpec extends IconPresentationSpec {
 export type IconSpec = NamedIconSpec | SvgIconSpec;
 
 export interface UiNodeRepeatSpec {
-  source: BindingValueSource;
+  source: BindingExpression;
   itemAlias?: string;
   keyPath?: string;
   empty?: readonly UiNode[];