@ankhorage/contracts 1.9.0 → 1.11.0

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # @ankhorage/contracts
 
+## 1.11.0
+
+### Minor Changes
+
+- 17b8d75: Add bindable component metadata contracts for declaring data-bindable component props and events.
+
+## 1.10.0
+
+### Minor Changes
+
+- d637fdc: Add provider-neutral UI component metadata contracts for component registries and extension package manifests.
+
 ## 1.9.0
 
 ### Minor Changes

package/dist/index.d.ts

@@ -5,4 +5,5 @@ export * from './db';
 export * from './state';
 export * from './storage';
 export * from './types';
+export * from './ui';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,QAAQ,CAAC;AACvB,cAAc,YAAY,CAAC;AAC3B,cAAc,QAAQ,CAAC;AACvB,cAAc,MAAM,CAAC;AACrB,cAAc,SAAS,CAAC;AACxB,cAAc,WAAW,CAAC;AAC1B,cAAc,SAAS,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,QAAQ,CAAC;AACvB,cAAc,YAAY,CAAC;AAC3B,cAAc,QAAQ,CAAC;AACvB,cAAc,MAAM,CAAC;AACrB,cAAc,SAAS,CAAC;AACxB,cAAc,WAAW,CAAC;AAC1B,cAAc,SAAS,CAAC;AACxB,cAAc,MAAM,CAAC"}

package/dist/index.js

@@ -5,4 +5,5 @@ export * from './db';
 export * from './state';
 export * from './storage';
 export * from './types';
+export * from './ui';
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,QAAQ,CAAC;AACvB,cAAc,YAAY,CAAC;AAC3B,cAAc,QAAQ,CAAC;AACvB,cAAc,MAAM,CAAC;AACrB,cAAc,SAAS,CAAC;AACxB,cAAc,WAAW,CAAC;AAC1B,cAAc,SAAS,CAAC","sourcesContent":["export * from './auth';\nexport * from './bindings';\nexport * from './data';\nexport * from './db';\nexport * from './state';\nexport * from './storage';\nexport * from './types';\n"]}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,QAAQ,CAAC;AACvB,cAAc,YAAY,CAAC;AAC3B,cAAc,QAAQ,CAAC;AACvB,cAAc,MAAM,CAAC;AACrB,cAAc,SAAS,CAAC;AACxB,cAAc,WAAW,CAAC;AAC1B,cAAc,SAAS,CAAC;AACxB,cAAc,MAAM,CAAC","sourcesContent":["export * from './auth';\nexport * from './bindings';\nexport * from './data';\nexport * from './db';\nexport * from './state';\nexport * from './storage';\nexport * from './types';\nexport * from './ui';\n"]}

package/dist/ui.d.ts

@@ -0,0 +1,109 @@
+import type { ComponentEventDtoKind } from './types';
+export type UiComponentCategory = 'component' | 'foundation' | 'layout' | 'pattern';
+export type UiComponentPropType = 'action' | 'array' | 'boolean' | 'color' | 'enum' | 'imageAsset' | 'number' | 'radius' | 'shadow' | 'spacing' | 'string' | 'typographySize' | 'typographyWeight';
+export type UiComponentPropValue = string | number | boolean | null | readonly UiComponentPropValue[] | {
+    readonly [key: string]: UiComponentPropValue;
+};
+export interface UiComponentPropArrayItemSchema {
+    readonly key: string;
+    readonly schema: UiComponentPropSchema;
+}
+export interface UiComponentPropSchema {
+    readonly type: UiComponentPropType;
+    readonly category: string;
+    readonly label?: string;
+    readonly enum?: readonly (number | string)[];
+    readonly default?: UiComponentPropValue;
+    readonly itemSchema?: readonly UiComponentPropArrayItemSchema[];
+}
+export interface UiComponentBlueprintIcon {
+    readonly name: string;
+    readonly provider?: string;
+}
+export interface UiComponentBlueprint {
+    readonly label: string;
+    readonly icon?: UiComponentBlueprintIcon;
+    readonly defaultProps?: Readonly<Record<string, UiComponentPropValue>>;
+}
+export interface UiComponentI18nFieldMeta {
+    readonly keyProp: string;
+    readonly defaultTextProp: string;
+}
+export interface UiComponentI18nMeta {
+    readonly fields: readonly UiComponentI18nFieldMeta[];
+}
+export type UiComponentEventPayloadKind = ComponentEventDtoKind | (string & {});
+export type UiComponentEventPayloadFieldType = 'boolean' | 'number' | 'object' | 'record' | 'string' | 'unknown';
+export interface UiComponentEventPayloadFieldMeta {
+    readonly path: string;
+    readonly type: UiComponentEventPayloadFieldType;
+    readonly label?: string;
+    readonly description?: string;
+}
+export interface UiComponentEventMeta {
+    readonly label: string;
+    readonly eventType: UiComponentEventPayloadKind;
+    readonly description?: string;
+    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[];
+}
+export interface UiComponentMeta {
+    readonly name: string;
+    readonly category: UiComponentCategory;
+    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;
+    readonly slots?: Readonly<Record<string, UiComponentSlotMeta>>;
+    readonly note?: string;
+    readonly props: Readonly<Record<string, UiComponentPropSchema>>;
+}
+export type UiComponentMetaRegistry = Readonly<Record<string, UiComponentMeta>>;
+export interface UiComponentPackageManifest {
+    readonly packageName: string;
+    readonly displayName?: string;
+    readonly components: UiComponentMetaRegistry;
+}
+//# sourceMappingURL=ui.d.ts.map

package/dist/ui.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ui.d.ts","sourceRoot":"","sources":["../src/ui.ts"],"names":[],"mappings":"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"}

package/dist/ui.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=ui.js.map

package/dist/ui.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ui.js","sourceRoot":"","sources":["../src/ui.ts"],"names":[],"mappings":"","sourcesContent":["import type { ComponentEventDtoKind } from './types';\n\nexport type UiComponentCategory = 'component' | 'foundation' | 'layout' | 'pattern';\n\nexport type UiComponentPropType =\n  | 'action'\n  | 'array'\n  | 'boolean'\n  | 'color'\n  | 'enum'\n  | 'imageAsset'\n  | 'number'\n  | 'radius'\n  | 'shadow'\n  | 'spacing'\n  | 'string'\n  | 'typographySize'\n  | 'typographyWeight';\n\nexport type UiComponentPropValue =\n  | string\n  | number\n  | boolean\n  | null\n  | readonly UiComponentPropValue[]\n  | {\n      readonly [key: string]: UiComponentPropValue;\n    };\n\nexport interface UiComponentPropArrayItemSchema {\n  readonly key: string;\n  readonly schema: UiComponentPropSchema;\n}\n\nexport interface UiComponentPropSchema {\n  readonly type: UiComponentPropType;\n  readonly category: string;\n  readonly label?: string;\n  readonly enum?: readonly (number | string)[];\n  readonly default?: UiComponentPropValue;\n  readonly itemSchema?: readonly UiComponentPropArrayItemSchema[];\n}\n\nexport interface UiComponentBlueprintIcon {\n  readonly name: string;\n  readonly provider?: string;\n}\n\nexport interface UiComponentBlueprint {\n  readonly label: string;\n  readonly icon?: UiComponentBlueprintIcon;\n  readonly defaultProps?: Readonly<Record<string, UiComponentPropValue>>;\n}\n\nexport interface UiComponentI18nFieldMeta {\n  readonly keyProp: string;\n  readonly defaultTextProp: string;\n}\n\nexport interface UiComponentI18nMeta {\n  readonly fields: readonly UiComponentI18nFieldMeta[];\n}\n\nexport type UiComponentEventPayloadKind = ComponentEventDtoKind | (string & {});\n\nexport type UiComponentEventPayloadFieldType =\n  | 'boolean'\n  | 'number'\n  | 'object'\n  | 'record'\n  | 'string'\n  | 'unknown';\n\nexport interface UiComponentEventPayloadFieldMeta {\n  readonly path: string;\n  readonly type: UiComponentEventPayloadFieldType;\n  readonly label?: string;\n  readonly description?: string;\n}\n\nexport interface UiComponentEventMeta {\n  readonly label: string;\n  readonly eventType: UiComponentEventPayloadKind;\n  readonly description?: string;\n  readonly payloadFields?: readonly UiComponentEventPayloadFieldMeta[];\n}\n\nexport type UiBindableValueType =\n  | 'array'\n  | 'boolean'\n  | 'date'\n  | 'imageAsset'\n  | 'number'\n  | 'object'\n  | 'record'\n  | 'string'\n  | 'unknown';\n\nexport interface UiBindableValueFieldMeta {\n  readonly path: string;\n  readonly type: UiBindableValueType;\n  readonly label?: string;\n  readonly description?: string;\n  readonly required?: boolean;\n}\n\nexport interface UiBindableValueMeta {\n  readonly type: UiBindableValueType;\n  readonly label?: string;\n  readonly description?: string;\n  readonly fields?: readonly UiBindableValueFieldMeta[];\n  readonly itemType?: UiBindableValueType;\n}\n\nexport interface UiBindablePropMeta {\n  readonly value: UiBindableValueMeta;\n  readonly label?: string;\n  readonly description?: string;\n  readonly required?: boolean;\n  readonly acceptsFallback?: boolean;\n  readonly acceptsTransforms?: boolean;\n}\n\nexport interface UiBindableEventPayloadMeta {\n  readonly eventType: UiComponentEventPayloadKind;\n  readonly fields?: readonly UiComponentEventPayloadFieldMeta[];\n}\n\nexport interface UiBindableEventMeta {\n  readonly label?: string;\n  readonly description?: string;\n  readonly payload?: UiBindableEventPayloadMeta;\n}\n\nexport interface UiComponentBindingMeta {\n  readonly props?: Readonly<Record<string, UiBindablePropMeta>>;\n  readonly events?: Readonly<Record<string, UiBindableEventMeta>>;\n}\n\nexport interface UiComponentSlotMeta {\n  readonly label?: string;\n  readonly allowedChildren?: readonly string[];\n}\n\nexport interface UiComponentMeta {\n  readonly name: string;\n  readonly category: UiComponentCategory;\n  readonly description?: string;\n  readonly directManifestNode: boolean;\n  readonly allowedChildren: readonly string[];\n  readonly bindings?: UiComponentBindingMeta;\n  readonly blueprint?: UiComponentBlueprint;\n  readonly events?: Readonly<Record<string, UiComponentEventMeta>>;\n  readonly i18n?: UiComponentI18nMeta;\n  readonly slots?: Readonly<Record<string, UiComponentSlotMeta>>;\n  readonly note?: string;\n  readonly props: Readonly<Record<string, UiComponentPropSchema>>;\n}\n\nexport type UiComponentMetaRegistry = Readonly<Record<string, UiComponentMeta>>;\n\nexport interface UiComponentPackageManifest {\n  readonly packageName: string;\n  readonly displayName?: string;\n  readonly components: UiComponentMetaRegistry;\n}\n"]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ankhorage/contracts",
-  "version": "1.9.0",
+  "version": "1.11.0",
   "main": "./dist/index.js",
   "dependencies": {
     "@ankhorage/color-theory": "^0.0.7"
@@ -40,6 +40,10 @@
     "./storage": {
       "types": "./dist/storage.d.ts",
       "default": "./dist/storage.js"
+    },
+    "./ui": {
+      "types": "./dist/ui.d.ts",
+      "default": "./dist/ui.js"
     }
   },
   "description": "Serializable app, action, and theme config contracts for Ankhorage.",

package/src/index.ts

@@ -5,3 +5,4 @@ export * from './db';
 export * from './state';
 export * from './storage';
 export * from './types';
+export * from './ui';

package/src/ui.test.ts

@@ -0,0 +1,362 @@
+import { describe, expect, it } from 'bun:test';
+
+import type { UiComponentMeta, UiComponentMetaRegistry, UiComponentPackageManifest } from './index';
+
+function assertSerializable<TValue>(value: TValue): void {
+  expect(JSON.parse(JSON.stringify(value))).toEqual(value);
+}
+
+describe('ui component metadata contracts', () => {
+  it('serializes component metadata with props, events, slots, i18n, and blueprint defaults', () => {
+    const meta: UiComponentMeta = {
+      name: 'Button',
+      category: 'component',
+      description: 'Action component used to trigger an interaction.',
+      directManifestNode: true,
+      allowedChildren: [],
+      blueprint: {
+        label: 'Button',
+        icon: {
+          name: 'cursor-default-click',
+          provider: 'material-community',
+        },
+        defaultProps: {
+          children: 'Continue',
+          disabled: false,
+          size: 'm',
+        },
+      },
+      events: {
+        press: {
+          label: 'Press',
+          eventType: 'button.press',
+          description: 'Emitted when the button is pressed.',
+          payloadFields: [],
+        },
+      },
+      i18n: {
+        fields: [
+          {
+            keyProp: 'i18nKey',
+            defaultTextProp: 'children',
+          },
+        ],
+      },
+      slots: {
+        icon: {
+          label: 'Icon',
+          allowedChildren: ['Icon'],
+        },
+      },
+      props: {
+        children: {
+          type: 'string',
+          category: 'Content',
+          label: 'Label',
+          default: 'Continue',
+        },
+        disabled: {
+          type: 'boolean',
+          category: 'State',
+          label: 'Disabled',
+          default: false,
+        },
+        size: {
+          type: 'enum',
+          category: 'Style',
+          label: 'Size',
+          enum: ['s', 'm', 'l'],
+          default: 'm',
+        },
+      },
+    };
+
+    assertSerializable(meta);
+    expect(meta.events?.press?.eventType).toBe('button.press');
+    expect(meta.props.size?.enum).toEqual(['s', 'm', 'l']);
+  });
+
+  it('serializes component metadata with array item schemas', () => {
+    const meta: UiComponentMeta = {
+      name: 'DataTable',
+      category: 'component',
+      directManifestNode: true,
+      allowedChildren: [],
+      props: {
+        columns: {
+          type: 'array',
+          category: 'Data',
+          label: 'Columns',
+          itemSchema: [
+            {
+              key: 'id',
+              schema: {
+                type: 'string',
+                category: 'Data',
+                label: 'Column id',
+              },
+            },
+            {
+              key: 'label',
+              schema: {
+                type: 'string',
+                category: 'Data',
+                label: 'Column label',
+              },
+            },
+          ],
+        },
+      },
+    };
+
+    assertSerializable(meta);
+    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: {
+        name: 'Text',
+        category: 'component',
+        directManifestNode: true,
+        allowedChildren: [],
+        bindings: {
+          props: {
+            children: {
+              value: {
+                type: 'string',
+              },
+            },
+          },
+        },
+        props: {
+          children: {
+            type: 'string',
+            category: 'Content',
+            label: 'Text',
+          },
+        },
+      },
+      Screen: {
+        name: 'Screen',
+        category: 'layout',
+        directManifestNode: true,
+        allowedChildren: ['Text'],
+        props: {},
+      },
+    };
+
+    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', () => {
+    const manifest: UiComponentPackageManifest = {
+      packageName: '@ankhorage/zora-chessboard',
+      displayName: 'ZORA Chessboard',
+      components: {
+        Chessboard: {
+          name: 'Chessboard',
+          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',
+              eventType: 'chess.move',
+              payloadFields: [
+                {
+                  path: 'payload.from',
+                  type: 'string',
+                  label: 'From square',
+                },
+                {
+                  path: 'payload.to',
+                  type: 'string',
+                  label: 'To square',
+                },
+              ],
+            },
+          },
+          props: {
+            fen: {
+              type: 'string',
+              category: 'Chess',
+              label: 'FEN',
+            },
+            orientation: {
+              type: 'enum',
+              category: 'Chess',
+              label: 'Orientation',
+              enum: ['white', 'black'],
+              default: 'white',
+            },
+          },
+        },
+      },
+    };
+
+    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

@@ -0,0 +1,166 @@
+import type { ComponentEventDtoKind } from './types';
+
+export type UiComponentCategory = 'component' | 'foundation' | 'layout' | 'pattern';
+
+export type UiComponentPropType =
+  | 'action'
+  | 'array'
+  | 'boolean'
+  | 'color'
+  | 'enum'
+  | 'imageAsset'
+  | 'number'
+  | 'radius'
+  | 'shadow'
+  | 'spacing'
+  | 'string'
+  | 'typographySize'
+  | 'typographyWeight';
+
+export type UiComponentPropValue =
+  | string
+  | number
+  | boolean
+  | null
+  | readonly UiComponentPropValue[]
+  | {
+      readonly [key: string]: UiComponentPropValue;
+    };
+
+export interface UiComponentPropArrayItemSchema {
+  readonly key: string;
+  readonly schema: UiComponentPropSchema;
+}
+
+export interface UiComponentPropSchema {
+  readonly type: UiComponentPropType;
+  readonly category: string;
+  readonly label?: string;
+  readonly enum?: readonly (number | string)[];
+  readonly default?: UiComponentPropValue;
+  readonly itemSchema?: readonly UiComponentPropArrayItemSchema[];
+}
+
+export interface UiComponentBlueprintIcon {
+  readonly name: string;
+  readonly provider?: string;
+}
+
+export interface UiComponentBlueprint {
+  readonly label: string;
+  readonly icon?: UiComponentBlueprintIcon;
+  readonly defaultProps?: Readonly<Record<string, UiComponentPropValue>>;
+}
+
+export interface UiComponentI18nFieldMeta {
+  readonly keyProp: string;
+  readonly defaultTextProp: string;
+}
+
+export interface UiComponentI18nMeta {
+  readonly fields: readonly UiComponentI18nFieldMeta[];
+}
+
+export type UiComponentEventPayloadKind = ComponentEventDtoKind | (string & {});
+
+export type UiComponentEventPayloadFieldType =
+  | 'boolean'
+  | 'number'
+  | 'object'
+  | 'record'
+  | 'string'
+  | 'unknown';
+
+export interface UiComponentEventPayloadFieldMeta {
+  readonly path: string;
+  readonly type: UiComponentEventPayloadFieldType;
+  readonly label?: string;
+  readonly description?: string;
+}
+
+export interface UiComponentEventMeta {
+  readonly label: string;
+  readonly eventType: UiComponentEventPayloadKind;
+  readonly description?: string;
+  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[];
+}
+
+export interface UiComponentMeta {
+  readonly name: string;
+  readonly category: UiComponentCategory;
+  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;
+  readonly slots?: Readonly<Record<string, UiComponentSlotMeta>>;
+  readonly note?: string;
+  readonly props: Readonly<Record<string, UiComponentPropSchema>>;
+}
+
+export type UiComponentMetaRegistry = Readonly<Record<string, UiComponentMeta>>;
+
+export interface UiComponentPackageManifest {
+  readonly packageName: string;
+  readonly displayName?: string;
+  readonly components: UiComponentMetaRegistry;
+}