@zhama/a2ui-core 0.1.0

package/dist/types/index.d.ts

@@ -0,0 +1,711 @@
+/**
+ * A2UI Primitive Types
+ *
+ * 基础值类型定义，支持字面值和数据绑定路径
+ * These types represent values that can be either literal values or data bindings
+ */
+/**
+ * 字符串值 - 可以是字面值或数据路径绑定
+ * @example
+ * // Literal value
+ * { literalString: "Hello World" }
+ * // or simply a string (v0.9 format)
+ * "Hello World"
+ *
+ * // Data binding
+ * { path: "/user/name" }
+ */
+type StringOrPath = string | {
+    path: string;
+};
+/**
+ * 数值 - 可以是字面值或数据路径绑定
+ */
+type NumberOrPath = number | {
+    path: string;
+};
+/**
+ * 布尔值 - 可以是字面值或数据路径绑定
+ */
+type BooleanOrPath = boolean | {
+    path: string;
+};
+/**
+ * 字符串数组 - 可以是字面值或数据路径绑定
+ */
+type StringArrayOrPath = string[] | {
+    path: string;
+};
+/**
+ * v0.8 格式的字符串值（带有 literalString/path 区分）
+ */
+interface StringValue {
+    path?: string;
+    literalString?: string;
+    /** @deprecated 使用 literalString */
+    literal?: string;
+}
+/**
+ * v0.8 格式的数值（带有 literalNumber/path 区分）
+ */
+interface NumberValue {
+    path?: string;
+    literalNumber?: number;
+    /** @deprecated 使用 literalNumber */
+    literal?: number;
+}
+/**
+ * v0.8 格式的布尔值（带有 literalBoolean/path 区分）
+ */
+interface BooleanValue {
+    path?: string;
+    literalBoolean?: boolean;
+    /** @deprecated 使用 literalBoolean */
+    literal?: boolean;
+}
+/**
+ * v0.8 格式的字符串数组值
+ */
+interface StringArrayValue {
+    path?: string;
+    literalArray?: string[];
+}
+/**
+ * Context value - 用于 Action context 中的值
+ */
+type ContextValue = string | number | boolean | {
+    path: string;
+};
+
+/**
+ * A2UI Component Types
+ *
+ * 标准组件目录中的组件类型定义
+ * Based on A2UI v0.9 specification
+ */
+
+/**
+ * 用户操作定义
+ * Dispatched when interactive components (like Button) are activated
+ */
+interface Action {
+    /**
+     * 操作名称，用于标识操作类型
+     * @example "submit_form", "navigate", "select_item"
+     */
+    name: string;
+    /**
+     * 操作上下文，键值对形式
+     * Values can be literals or data bindings
+     */
+    context?: Record<string, StringOrPath | NumberOrPath | BooleanOrPath>;
+}
+/**
+ * v0.8 格式的 Action 上下文项
+ */
+interface ActionContextItem {
+    key: string;
+    value: {
+        path?: string;
+        literalString?: string;
+        literalNumber?: number;
+        literalBoolean?: boolean;
+    };
+}
+/**
+ * v0.8 格式的 Action
+ */
+interface ActionV08 {
+    name: string;
+    context?: ActionContextItem[];
+}
+/**
+ * 组件公共属性
+ */
+interface ComponentCommon {
+    /**
+     * 组件唯一标识符
+     */
+    id: string;
+    /**
+     * 在 Row 或 Column 中的相对权重（类似 CSS flex-grow）
+     */
+    weight?: number;
+}
+/**
+ * Text 组件 - 显示文本内容
+ */
+interface TextComponent {
+    component: 'Text';
+    /**
+     * 文本内容，支持简单 Markdown
+     */
+    text: StringOrPath;
+    /**
+     * 文本样式提示
+     */
+    usageHint?: 'h1' | 'h2' | 'h3' | 'h4' | 'h5' | 'caption' | 'body';
+}
+/**
+ * Image 组件 - 显示图片
+ */
+interface ImageComponent {
+    component: 'Image';
+    /**
+     * 图片 URL
+     */
+    url: StringOrPath;
+    /**
+     * 图片适应方式
+     */
+    fit?: 'contain' | 'cover' | 'fill' | 'none' | 'scale-down';
+    /**
+     * 图片尺寸/样式提示
+     */
+    usageHint?: 'icon' | 'avatar' | 'smallFeature' | 'mediumFeature' | 'largeFeature' | 'header';
+}
+/**
+ * Icon 组件 - 显示图标
+ */
+interface IconComponent {
+    component: 'Icon';
+    /**
+     * 图标名称，支持标准图标集
+     */
+    name: StringOrPath;
+}
+/**
+ * 标准图标名称
+ */
+type StandardIconName = 'accountCircle' | 'add' | 'arrowBack' | 'arrowForward' | 'attachFile' | 'calendarToday' | 'call' | 'camera' | 'check' | 'close' | 'delete' | 'download' | 'edit' | 'event' | 'error' | 'fastForward' | 'favorite' | 'favoriteOff' | 'folder' | 'help' | 'home' | 'info' | 'locationOn' | 'lock' | 'lockOpen' | 'mail' | 'menu' | 'moreVert' | 'moreHoriz' | 'notificationsOff' | 'notifications' | 'pause' | 'payment' | 'person' | 'phone' | 'photo' | 'play' | 'print' | 'refresh' | 'rewind' | 'search' | 'send' | 'settings' | 'share' | 'shoppingCart' | 'skipNext' | 'skipPrevious' | 'star' | 'starHalf' | 'starOff' | 'stop' | 'upload' | 'visibility' | 'visibilityOff' | 'volumeDown' | 'volumeMute' | 'volumeOff' | 'volumeUp' | 'warning';
+/**
+ * Video 组件 - 显示视频
+ */
+interface VideoComponent {
+    component: 'Video';
+    /**
+     * 视频 URL
+     */
+    url: StringOrPath;
+}
+/**
+ * AudioPlayer 组件 - 音频播放器
+ */
+interface AudioPlayerComponent {
+    component: 'AudioPlayer';
+    /**
+     * 音频 URL
+     */
+    url: StringOrPath;
+    /**
+     * 音频描述/标题
+     */
+    description?: StringOrPath;
+}
+/**
+ * 子组件引用 - 静态列表或动态模板
+ */
+type ChildrenProperty = string[] | {
+    componentId: string;
+    path: string;
+};
+/**
+ * Row 组件 - 水平布局
+ */
+interface RowComponent {
+    component: 'Row';
+    /**
+     * 子组件 ID 列表或动态模板
+     */
+    children: ChildrenProperty;
+    /**
+     * 主轴方向上的分布方式
+     */
+    distribution?: 'start' | 'center' | 'end' | 'spaceBetween' | 'spaceAround' | 'spaceEvenly' | 'stretch';
+    /**
+     * 交叉轴方向上的对齐方式
+     */
+    alignment?: 'start' | 'center' | 'end' | 'stretch';
+}
+/**
+ * Column 组件 - 垂直布局
+ */
+interface ColumnComponent {
+    component: 'Column';
+    /**
+     * 子组件 ID 列表或动态模板
+     */
+    children: ChildrenProperty;
+    /**
+     * 主轴方向上的分布方式
+     */
+    distribution?: 'start' | 'center' | 'end' | 'spaceBetween' | 'spaceAround' | 'spaceEvenly' | 'stretch';
+    /**
+     * 交叉轴方向上的对齐方式
+     */
+    alignment?: 'start' | 'center' | 'end' | 'stretch';
+}
+/**
+ * List 组件 - 列表布局
+ */
+interface ListComponent {
+    component: 'List';
+    /**
+     * 子组件 ID 列表或动态模板
+     */
+    children: ChildrenProperty;
+    /**
+     * 列表方向
+     */
+    direction?: 'vertical' | 'horizontal';
+    /**
+     * 对齐方式
+     */
+    alignment?: 'start' | 'center' | 'end' | 'stretch';
+}
+/**
+ * Card 组件 - 卡片容器
+ */
+interface CardComponent {
+    component: 'Card';
+    /**
+     * 单个子组件 ID
+     */
+    child: string;
+}
+/**
+ * Tabs 组件 - 标签页
+ */
+interface TabsComponent {
+    component: 'Tabs';
+    /**
+     * 标签项列表
+     */
+    tabItems: Array<{
+        title: StringOrPath;
+        child: string;
+    }>;
+}
+/**
+ * Divider 组件 - 分割线
+ */
+interface DividerComponent {
+    component: 'Divider';
+    /**
+     * 方向
+     */
+    axis?: 'horizontal' | 'vertical';
+}
+/**
+ * Modal 组件 - 模态框
+ */
+interface ModalComponent {
+    component: 'Modal';
+    /**
+     * 触发模态框的组件 ID
+     */
+    entryPointChild: string;
+    /**
+     * 模态框内容组件 ID
+     */
+    contentChild: string;
+}
+/**
+ * Button 组件 - 按钮
+ */
+interface ButtonComponent {
+    component: 'Button';
+    /**
+     * 按钮内容组件 ID（通常是 Text）
+     */
+    child: string;
+    /**
+     * 是否为主按钮样式
+     */
+    primary?: boolean;
+    /**
+     * 点击时触发的操作
+     */
+    action: Action;
+}
+/**
+ * CheckBox 组件 - 复选框
+ */
+interface CheckBoxComponent {
+    component: 'CheckBox';
+    /**
+     * 标签文本
+     */
+    label: StringOrPath;
+    /**
+     * 选中状态
+     */
+    value: BooleanOrPath;
+}
+/**
+ * TextField 组件 - 文本输入框
+ */
+interface TextFieldComponent {
+    component: 'TextField';
+    /**
+     * 输入框标签
+     */
+    label: StringOrPath;
+    /**
+     * 输入框值
+     */
+    text?: StringOrPath;
+    /**
+     * 输入类型提示
+     */
+    usageHint?: 'longText' | 'number' | 'shortText' | 'obscured';
+    /**
+     * 验证正则表达式
+     */
+    validationRegexp?: string;
+}
+/**
+ * DateTimeInput 组件 - 日期时间选择器
+ */
+interface DateTimeInputComponent {
+    component: 'DateTimeInput';
+    /**
+     * 当前值（ISO 8601 格式）
+     */
+    value: StringOrPath;
+    /**
+     * 是否允许选择日期
+     */
+    enableDate?: boolean;
+    /**
+     * 是否允许选择时间
+     */
+    enableTime?: boolean;
+    /**
+     * 输出格式
+     */
+    outputFormat?: string;
+    /**
+     * 标签
+     */
+    label?: StringOrPath;
+}
+/**
+ * ChoicePicker 组件 - 选择器
+ */
+interface ChoicePickerComponent {
+    component: 'ChoicePicker';
+    /**
+     * 标签
+     */
+    label?: StringOrPath;
+    /**
+     * 使用提示
+     */
+    usageHint: 'multipleSelection' | 'mutuallyExclusive';
+    /**
+     * 选项列表
+     */
+    options: Array<{
+        label: StringOrPath;
+        value: string;
+    }>;
+    /**
+     * 当前选中的值
+     */
+    value: StringArrayOrPath;
+}
+/**
+ * Slider 组件 - 滑块
+ */
+interface SliderComponent {
+    component: 'Slider';
+    /**
+     * 标签
+     */
+    label?: StringOrPath;
+    /**
+     * 最小值
+     */
+    min?: number;
+    /**
+     * 最大值
+     */
+    max?: number;
+    /**
+     * 当前值
+     */
+    value: NumberOrPath;
+}
+/**
+ * 任意标准组件类型
+ */
+type AnyComponent = TextComponent | ImageComponent | IconComponent | VideoComponent | AudioPlayerComponent | RowComponent | ColumnComponent | ListComponent | CardComponent | TabsComponent | DividerComponent | ModalComponent | ButtonComponent | CheckBoxComponent | TextFieldComponent | DateTimeInputComponent | ChoicePickerComponent | SliderComponent;
+/**
+ * 组件类型名称
+ */
+type ComponentType = AnyComponent['component'];
+/**
+ * 组件实例 - 带有 ID 和可选权重的组件
+ */
+interface ComponentInstance extends ComponentCommon {
+    component: string;
+    [key: string]: unknown;
+}
+
+/**
+ * A2UI Message Types
+ *
+ * 服务器到客户端的消息类型定义
+ * Based on A2UI v0.9 specification
+ */
+
+/**
+ * A2UI 主题配置
+ */
+interface Theme {
+    /**
+     * 主要字体
+     */
+    font?: string;
+    /**
+     * 主题色（十六进制格式，如 '#00BFFF'）
+     */
+    primaryColor?: string;
+    /**
+     * 其他自定义样式
+     */
+    [key: string]: string | undefined;
+}
+/**
+ * CreateSurface 消息 - 创建新的 UI Surface
+ */
+interface CreateSurfaceMessage {
+    createSurface: {
+        /**
+         * Surface 唯一标识符
+         */
+        surfaceId: string;
+        /**
+         * 组件目录 ID
+         * @example "https://a2ui.dev/specification/0.9/standard_catalog_definition.json"
+         */
+        catalogId: string;
+    };
+}
+/**
+ * UpdateComponents 消息 - 更新 Surface 中的组件
+ */
+interface UpdateComponentsMessage {
+    updateComponents: {
+        /**
+         * Surface 唯一标识符
+         */
+        surfaceId: string;
+        /**
+         * 组件列表（扁平化，通过 ID 引用建立关系）
+         */
+        components: ComponentInstance[];
+    };
+}
+/**
+ * UpdateDataModel 消息 - 更新数据模型
+ */
+interface UpdateDataModelMessage {
+    updateDataModel: {
+        /**
+         * Surface 唯一标识符
+         */
+        surfaceId: string;
+        /**
+         * 数据路径（可选，默认为根路径）
+         * @example "/user/name"
+         */
+        path?: string;
+        /**
+         * 操作类型
+         */
+        op?: 'add' | 'replace' | 'remove';
+        /**
+         * 数据值（add/replace 操作需要）
+         */
+        value?: unknown;
+    };
+}
+/**
+ * DeleteSurface 消息 - 删除 Surface
+ */
+interface DeleteSurfaceMessage {
+    deleteSurface: {
+        /**
+         * 要删除的 Surface ID
+         */
+        surfaceId: string;
+    };
+}
+/**
+ * v0.9 服务器到客户端消息
+ */
+type ServerToClientMessageV09 = CreateSurfaceMessage | UpdateComponentsMessage | UpdateDataModelMessage | DeleteSurfaceMessage;
+/**
+ * BeginRendering 消息 (v0.8) - 开始渲染
+ */
+interface BeginRenderingMessage {
+    beginRendering: {
+        /**
+         * Surface ID
+         */
+        surfaceId: string;
+        /**
+         * 根组件 ID
+         */
+        root: string;
+        /**
+         * 样式配置
+         */
+        styles?: Theme;
+    };
+}
+/**
+ * SurfaceUpdate 消息 (v0.8) - 更新组件
+ */
+interface SurfaceUpdateMessage {
+    surfaceUpdate: {
+        surfaceId: string;
+        components: ComponentInstanceV08[];
+    };
+}
+/**
+ * v0.8 组件实例格式
+ */
+interface ComponentInstanceV08 {
+    id: string;
+    weight?: number;
+    component: Record<string, unknown>;
+}
+/**
+ * DataModelUpdate 消息 (v0.8) - 更新数据模型
+ */
+interface DataModelUpdateMessage {
+    dataModelUpdate: {
+        surfaceId: string;
+        path?: string;
+        contents: ValueMap[];
+    };
+}
+/**
+ * DeleteSurface 消息 (v0.8)
+ */
+interface DeleteSurfaceMessageV08 {
+    deleteSurface: {
+        surfaceId: string;
+    };
+}
+/**
+ * v0.8 ValueMap 格式
+ */
+interface ValueMap {
+    key: string;
+    valueString?: string;
+    valueNumber?: number;
+    valueBoolean?: boolean;
+    valueMap?: ValueMap[];
+}
+/**
+ * v0.8 服务器到客户端消息
+ */
+type ServerToClientMessageV08 = BeginRenderingMessage | SurfaceUpdateMessage | DataModelUpdateMessage | DeleteSurfaceMessageV08;
+/**
+ * 服务器到客户端消息（支持 v0.8 和 v0.9）
+ */
+type ServerToClientMessage = ServerToClientMessageV08 | ServerToClientMessageV09;
+/**
+ * 判断是否为 v0.9 消息
+ */
+declare function isV09Message(message: ServerToClientMessage): message is ServerToClientMessageV09;
+/**
+ * 判断是否为 v0.8 消息
+ */
+declare function isV08Message(message: ServerToClientMessage): message is ServerToClientMessageV08;
+/**
+ * 用户操作事件
+ */
+interface UserActionEvent {
+    /**
+     * 操作名称
+     */
+    actionName: string;
+    /**
+     * 触发组件的 ID
+     */
+    sourceComponentId: string;
+    /**
+     * 时间戳（ISO 8601 格式）
+     */
+    timestamp: string;
+    /**
+     * 操作上下文（解析后的值）
+     */
+    context?: Record<string, unknown>;
+}
+/**
+ * 数据变更事件
+ */
+interface DataChangeEvent {
+    /**
+     * Surface ID
+     */
+    surfaceId: string;
+    /**
+     * 数据路径
+     */
+    path: string;
+    /**
+     * 新值
+     */
+    value: unknown;
+    /**
+     * 触发组件的 ID
+     */
+    sourceComponentId: string;
+}
+/**
+ * 客户端到服务器消息
+ */
+type ClientToServerMessage = {
+    userAction: UserActionEvent;
+} | {
+    dataChange: DataChangeEvent;
+};
+/**
+ * 数据模型值类型
+ */
+type DataValue = string | number | boolean | null | DataObject | DataArray;
+/**
+ * 数据对象
+ */
+interface DataObject {
+    [key: string]: DataValue;
+}
+/**
+ * 数据数组
+ */
+type DataArray = DataValue[];
+/**
+ * A2UI 标准 Catalog ID
+ */
+declare const STANDARD_CATALOG_ID = "https://a2ui.dev/specification/0.9/standard_catalog_definition.json";
+/**
+ * A2UI 扩展 URI (v0.8)
+ */
+declare const A2UI_EXTENSION_URI_V08 = "https://a2ui.org/a2a-extension/a2ui/v0.8";
+/**
+ * A2UI 扩展 URI (v0.9)
+ */
+declare const A2UI_EXTENSION_URI = "https://a2ui.dev/specification/0.9";
+/**
+ * A2UI MIME 类型
+ */
+declare const A2UI_MIME_TYPE = "application/json+a2ui";
+
+export { A2UI_EXTENSION_URI, A2UI_EXTENSION_URI_V08, A2UI_MIME_TYPE, type Action, type ActionContextItem, type ActionV08, type AnyComponent, type AudioPlayerComponent, type BeginRenderingMessage, type BooleanOrPath, type BooleanValue, type ButtonComponent, type CardComponent, type CheckBoxComponent, type ChildrenProperty, type ChoicePickerComponent, type ClientToServerMessage, type ColumnComponent, type ComponentCommon, type ComponentInstance, type ComponentInstanceV08, type ComponentType, type ContextValue, type CreateSurfaceMessage, type DataArray, type DataChangeEvent, type DataModelUpdateMessage, type DataObject, type DataValue, type DateTimeInputComponent, type DeleteSurfaceMessage, type DeleteSurfaceMessageV08, type DividerComponent, type IconComponent, type ImageComponent, type ListComponent, type ModalComponent, type NumberOrPath, type NumberValue, type RowComponent, STANDARD_CATALOG_ID, type ServerToClientMessage, type ServerToClientMessageV08, type ServerToClientMessageV09, type SliderComponent, type StandardIconName, type StringArrayOrPath, type StringArrayValue, type StringOrPath, type StringValue, type SurfaceUpdateMessage, type TabsComponent, type TextComponent, type TextFieldComponent, type Theme, type UpdateComponentsMessage, type UpdateDataModelMessage, type UserActionEvent, type ValueMap, type VideoComponent, isV08Message, isV09Message };

package/dist/types/index.js

@@ -0,0 +1,15 @@
+// src/types/messages.ts
+function isV09Message(message) {
+  return "createSurface" in message || "updateComponents" in message || "updateDataModel" in message;
+}
+function isV08Message(message) {
+  return "beginRendering" in message || "surfaceUpdate" in message || "dataModelUpdate" in message;
+}
+var STANDARD_CATALOG_ID = "https://a2ui.dev/specification/0.9/standard_catalog_definition.json";
+var A2UI_EXTENSION_URI_V08 = "https://a2ui.org/a2a-extension/a2ui/v0.8";
+var A2UI_EXTENSION_URI = "https://a2ui.dev/specification/0.9";
+var A2UI_MIME_TYPE = "application/json+a2ui";
+
+export { A2UI_EXTENSION_URI, A2UI_EXTENSION_URI_V08, A2UI_MIME_TYPE, STANDARD_CATALOG_ID, isV08Message, isV09Message };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map