@zhama/a2ui-core 0.1.0

package/dist/builders/index.d.ts

@@ -0,0 +1,538 @@
+import { TextComponent, ImageComponent, StringOrPath, RowComponent, ListComponent, DividerComponent, TextFieldComponent, ComponentInstance, ChildrenProperty, Action, BooleanOrPath, StringArrayOrPath, ChoicePickerComponent, NumberOrPath, CreateSurfaceMessage, UpdateComponentsMessage, UpdateDataModelMessage, DeleteSurfaceMessage, DataObject, ServerToClientMessageV09, BeginRenderingMessage, ComponentInstanceV08, SurfaceUpdateMessage, ValueMap, DataModelUpdateMessage, DataValue, ServerToClientMessageV08 } from '../types/index.js';
+
+/**
+ * ID Generator
+ *
+ * 生成唯一的组件 ID
+ */
+/**
+ * 生成唯一的组件 ID
+ *
+ * @param prefix - ID 前缀
+ * @returns 唯一的组件 ID
+ *
+ * @example
+ * generateId('text'); // 'text_1703123456789_0'
+ * generateId('btn');  // 'btn_1703123456789_1'
+ */
+declare function generateId(prefix?: string): string;
+/**
+ * 重置 ID 计数器
+ * 在渲染新场景时调用，确保 ID 从 0 开始
+ */
+declare function resetIdCounter(): void;
+/**
+ * 获取当前计数器值（用于测试）
+ */
+declare function getIdCounter(): number;
+
+/**
+ * Component Builder
+ *
+ * 提供 A2UI 组件定义的构建工具函数
+ * 用于创建符合 A2UI v0.9 协议的组件结构
+ */
+
+/**
+ * 组件构建选项基类
+ */
+interface ComponentOptions {
+    /** 组件 ID（可选，自动生成） */
+    id?: string;
+    /** 在 Row/Column 中的权重 */
+    weight?: number;
+}
+/**
+ * Text 组件选项
+ */
+interface TextOptions extends ComponentOptions {
+    usageHint?: TextComponent['usageHint'];
+}
+/**
+ * Image 组件选项
+ */
+interface ImageOptions extends ComponentOptions {
+    fit?: ImageComponent['fit'];
+    usageHint?: ImageComponent['usageHint'];
+}
+/**
+ * Icon 组件选项
+ */
+interface IconOptions extends ComponentOptions {
+}
+/**
+ * Video 组件选项
+ */
+interface VideoOptions extends ComponentOptions {
+}
+/**
+ * AudioPlayer 组件选项
+ */
+interface AudioPlayerOptions extends ComponentOptions {
+    description?: StringOrPath;
+}
+/**
+ * 布局组件选项
+ */
+interface LayoutOptions extends ComponentOptions {
+    alignment?: RowComponent['alignment'];
+    distribution?: RowComponent['distribution'];
+}
+/**
+ * List 组件选项
+ */
+interface ListOptions extends ComponentOptions {
+    direction?: ListComponent['direction'];
+    alignment?: ListComponent['alignment'];
+}
+/**
+ * Card 组件选项
+ */
+interface CardOptions extends ComponentOptions {
+}
+/**
+ * Tabs 组件选项
+ */
+interface TabsOptions extends ComponentOptions {
+}
+/**
+ * Tab 项目
+ */
+interface TabItem {
+    title: string;
+    childId: string;
+}
+/**
+ * Divider 组件选项
+ */
+interface DividerOptions extends ComponentOptions {
+    axis?: DividerComponent['axis'];
+}
+/**
+ * Modal 组件选项
+ */
+interface ModalOptions extends ComponentOptions {
+}
+/**
+ * Button 组件选项
+ */
+interface ButtonOptions extends ComponentOptions {
+    primary?: boolean;
+}
+/**
+ * CheckBox 组件选项
+ */
+interface CheckBoxOptions extends ComponentOptions {
+}
+/**
+ * TextField 组件选项
+ */
+interface TextFieldOptions extends ComponentOptions {
+    usageHint?: TextFieldComponent['usageHint'];
+    validationRegexp?: string;
+}
+/**
+ * DateTimeInput 组件选项
+ */
+interface DateTimeInputOptions extends ComponentOptions {
+    enableDate?: boolean;
+    enableTime?: boolean;
+    outputFormat?: string;
+    label?: StringOrPath;
+}
+/**
+ * ChoicePicker 组件选项
+ */
+interface ChoicePickerOptions extends ComponentOptions {
+    label?: StringOrPath;
+}
+/**
+ * Slider 组件选项
+ */
+interface SliderOptions extends ComponentOptions {
+    label?: StringOrPath;
+    min?: number;
+    max?: number;
+}
+/**
+ * 创建 Text 组件
+ *
+ * @param text - 文本内容或数据路径
+ * @param options - 组件选项
+ *
+ * @example
+ * // 静态文本
+ * text('Hello World', { usageHint: 'h1' });
+ *
+ * // 数据绑定
+ * text({ path: '/user/name' });
+ */
+declare function text(content: StringOrPath, options?: TextOptions): ComponentInstance;
+/**
+ * 创建 Image 组件
+ *
+ * @param url - 图片 URL 或数据路径
+ * @param options - 组件选项
+ */
+declare function image(url: StringOrPath, options?: ImageOptions): ComponentInstance;
+/**
+ * 创建 Icon 组件
+ *
+ * @param name - 图标名称或数据路径
+ * @param options - 组件选项
+ */
+declare function icon(name: StringOrPath, options?: IconOptions): ComponentInstance;
+/**
+ * 创建 Video 组件
+ *
+ * @param url - 视频 URL 或数据路径
+ * @param options - 组件选项
+ */
+declare function video(url: StringOrPath, options?: VideoOptions): ComponentInstance;
+/**
+ * 创建 AudioPlayer 组件
+ *
+ * @param url - 音频 URL 或数据路径
+ * @param options - 组件选项
+ */
+declare function audioPlayer(url: StringOrPath, options?: AudioPlayerOptions): ComponentInstance;
+/**
+ * 创建 Row 组件（水平布局）
+ *
+ * @param children - 子组件 ID 列表或动态模板
+ * @param options - 布局选项
+ *
+ * @example
+ * // 静态子组件
+ * row(['text1', 'text2', 'button1']);
+ *
+ * // 动态模板
+ * row({ componentId: 'itemTemplate', path: '/items' });
+ */
+declare function row(children: ChildrenProperty, options?: LayoutOptions): ComponentInstance;
+/**
+ * 创建 Column 组件（垂直布局）
+ *
+ * @param children - 子组件 ID 列表或动态模板
+ * @param options - 布局选项
+ */
+declare function column(children: ChildrenProperty, options?: LayoutOptions): ComponentInstance;
+/**
+ * 创建 List 组件
+ *
+ * @param children - 子组件 ID 列表或动态模板
+ * @param options - 列表选项
+ */
+declare function list(children: ChildrenProperty, options?: ListOptions): ComponentInstance;
+/**
+ * 创建 Card 组件
+ *
+ * @param childId - 子组件 ID
+ * @param options - 卡片选项
+ */
+declare function card(childId: string, options?: CardOptions): ComponentInstance;
+/**
+ * 创建 Tabs 组件
+ *
+ * @param items - 标签项列表
+ * @param options - Tabs 选项
+ */
+declare function tabs(items: TabItem[], options?: TabsOptions): ComponentInstance;
+/**
+ * 创建 Divider 组件
+ *
+ * @param options - 分割线选项
+ */
+declare function divider(options?: DividerOptions): ComponentInstance;
+/**
+ * 创建 Modal 组件
+ *
+ * @param entryPointChildId - 触发模态框的组件 ID
+ * @param contentChildId - 模态框内容组件 ID
+ * @param options - Modal 选项
+ */
+declare function modal(entryPointChildId: string, contentChildId: string, options?: ModalOptions): ComponentInstance;
+/**
+ * 创建 Button 组件
+ *
+ * @param childId - 按钮内容组件 ID（通常是 Text）
+ * @param action - 点击时触发的操作
+ * @param options - 按钮选项
+ */
+declare function button(childId: string, action: Action, options?: ButtonOptions): ComponentInstance;
+/**
+ * 创建 CheckBox 组件
+ *
+ * @param label - 标签
+ * @param value - 值（布尔值或数据路径）
+ * @param options - 选项
+ */
+declare function checkbox(label: StringOrPath, value: BooleanOrPath, options?: CheckBoxOptions): ComponentInstance;
+/**
+ * 创建 TextField 组件
+ *
+ * @param label - 标签
+ * @param textValue - 值（可选）
+ * @param options - 选项
+ */
+declare function textField(label: StringOrPath, textValue?: StringOrPath, options?: TextFieldOptions): ComponentInstance;
+/**
+ * 创建 DateTimeInput 组件
+ *
+ * @param value - 值（ISO 8601 格式字符串或数据路径）
+ * @param options - 选项
+ */
+declare function dateTimeInput(value: StringOrPath, options?: DateTimeInputOptions): ComponentInstance;
+/**
+ * 创建 ChoicePicker 组件
+ *
+ * @param optionsList - 选项列表
+ * @param value - 当前选中值
+ * @param usageHint - 使用提示
+ * @param options - 组件选项
+ */
+declare function choicePicker(optionsList: Array<{
+    label: StringOrPath;
+    value: string;
+}>, value: StringArrayOrPath, usageHint: ChoicePickerComponent['usageHint'], options?: ChoicePickerOptions): ComponentInstance;
+/**
+ * 创建 Slider 组件
+ *
+ * @param value - 当前值
+ * @param options - 选项
+ */
+declare function slider(value: NumberOrPath, options?: SliderOptions): ComponentInstance;
+/**
+ * 创建带文本的按钮（返回按钮和文本组件）
+ *
+ * @param buttonText - 按钮文本
+ * @param action - 点击操作
+ * @param options - 按钮选项
+ * @returns 包含按钮和文本组件的数组
+ */
+declare function textButton(buttonText: string, action: Action, options?: ButtonOptions & {
+    textId?: string;
+}): [ComponentInstance, ComponentInstance];
+/**
+ * 创建标题组件
+ */
+declare function h1(content: StringOrPath, options?: Omit<TextOptions, 'usageHint'>): ComponentInstance;
+declare function h2(content: StringOrPath, options?: Omit<TextOptions, 'usageHint'>): ComponentInstance;
+declare function h3(content: StringOrPath, options?: Omit<TextOptions, 'usageHint'>): ComponentInstance;
+declare function h4(content: StringOrPath, options?: Omit<TextOptions, 'usageHint'>): ComponentInstance;
+declare function h5(content: StringOrPath, options?: Omit<TextOptions, 'usageHint'>): ComponentInstance;
+declare function caption(content: StringOrPath, options?: Omit<TextOptions, 'usageHint'>): ComponentInstance;
+declare function body(content: StringOrPath, options?: Omit<TextOptions, 'usageHint'>): ComponentInstance;
+
+/**
+ * Message Builder
+ *
+ * 提供 A2UI 协议消息的构建工具函数
+ * 支持 v0.8 和 v0.9 两种消息格式
+ */
+
+/**
+ * 创建 CreateSurface 消息 (v0.9)
+ *
+ * @param surfaceId - Surface ID
+ * @param catalogId - Catalog ID（默认为标准目录）
+ */
+declare function createSurface(surfaceId: string, catalogId?: string): CreateSurfaceMessage;
+/**
+ * 创建 UpdateComponents 消息 (v0.9)
+ *
+ * @param surfaceId - Surface ID
+ * @param components - 组件列表
+ */
+declare function updateComponents(surfaceId: string, components: ComponentInstance[]): UpdateComponentsMessage;
+/**
+ * 创建 UpdateDataModel 消息 (v0.9)
+ *
+ * @param surfaceId - Surface ID
+ * @param value - 数据值
+ * @param path - 数据路径（可选）
+ * @param op - 操作类型（默认为 replace）
+ */
+declare function updateDataModel(surfaceId: string, value: unknown, path?: string, op?: 'add' | 'replace' | 'remove'): UpdateDataModelMessage;
+/**
+ * 创建 DeleteSurface 消息 (v0.9)
+ *
+ * @param surfaceId - 要删除的 Surface ID
+ */
+declare function deleteSurface(surfaceId: string): DeleteSurfaceMessage;
+/**
+ * 创建完整的 v0.9 消息序列
+ *
+ * @param options - 选项
+ * @returns 消息数组（可直接作为 JSONL 流发送）
+ */
+declare function createV09Messages(options: {
+    surfaceId: string;
+    catalogId?: string;
+    components: ComponentInstance[];
+    dataModel?: DataObject;
+}): ServerToClientMessageV09[];
+/**
+ * 创建 BeginRendering 消息 (v0.8)
+ *
+ * @param rootId - 根组件 ID
+ * @param surfaceId - Surface ID
+ * @param styles - 样式配置
+ */
+declare function beginRendering(rootId: string, surfaceId?: string, styles?: Record<string, string>): BeginRenderingMessage;
+/**
+ * 创建 SurfaceUpdate 消息 (v0.8)
+ *
+ * @param components - 组件定义数组
+ * @param surfaceId - Surface ID
+ */
+declare function surfaceUpdate(components: ComponentInstanceV08[], surfaceId?: string): SurfaceUpdateMessage;
+/**
+ * 创建 DataModelUpdate 消息 (v0.8)
+ *
+ * @param contents - ValueMap 数组
+ * @param surfaceId - Surface ID
+ * @param path - 数据路径（可选）
+ */
+declare function dataModelUpdate(contents: ValueMap[], surfaceId?: string, path?: string): DataModelUpdateMessage;
+/**
+ * 创建 DataModel 初始化消息 (v0.8)
+ *
+ * @param data - 初始数据对象
+ * @param surfaceId - Surface ID
+ */
+declare function dataModelInit(data: DataObject, surfaceId?: string): DataModelUpdateMessage;
+/**
+ * 创建路径更新消息 (v0.8)
+ *
+ * @param path - 数据路径
+ * @param value - 新值
+ * @param surfaceId - Surface ID
+ */
+declare function pathUpdate(path: string, value: DataValue, surfaceId?: string): DataModelUpdateMessage;
+/**
+ * 创建 DeleteSurface 消息 (v0.8)
+ *
+ * @param surfaceId - 要删除的 Surface ID
+ */
+declare function deleteSurfaceV08(surfaceId: string): {
+    deleteSurface: {
+        surfaceId: string;
+    };
+};
+/**
+ * 创建完整的 v0.8 消息数组
+ *
+ * @param options - 选项
+ * @returns 消息数组
+ */
+declare function createV08Messages(options: {
+    rootId: string;
+    components: ComponentInstanceV08[];
+    dataModel?: DataObject;
+    surfaceId?: string;
+    styles?: Record<string, string>;
+}): ServerToClientMessageV08[];
+/**
+ * 将消息数组转换为 JSONL 格式字符串
+ *
+ * @param messages - 消息数组
+ * @returns JSONL 格式字符串
+ */
+declare function messagesToJsonl(messages: Array<ServerToClientMessageV08 | ServerToClientMessageV09>): string;
+/**
+ * 从 JSONL 格式字符串解析消息数组
+ *
+ * @param jsonl - JSONL 格式字符串
+ * @returns 消息数组
+ */
+declare function jsonlToMessages(jsonl: string): Array<ServerToClientMessageV08 | ServerToClientMessageV09>;
+
+/**
+ * Data Model Builder
+ *
+ * 提供 DataModel 相关的构建工具函数
+ * 符合 A2UI 协议的 ValueMap 格式
+ */
+
+/**
+ * 路径映射表类型
+ */
+type PathMappings = Record<string, string>;
+/**
+ * 默认路径映射
+ */
+declare const DEFAULT_PATH_MAPPINGS: PathMappings;
+/**
+ * 将 JavaScript 对象转换为 A2UI ValueMap 格式
+ *
+ * @param obj - JavaScript 对象
+ * @param prefix - 路径前缀（用于嵌套对象的 key 生成）
+ *
+ * @example
+ * objectToValueMap({ name: 'John', age: 30 });
+ * // Returns: [
+ * //   { key: '/name', valueString: 'John' },
+ * //   { key: '/age', valueNumber: 30 }
+ * // ]
+ */
+declare function objectToValueMap(obj: DataObject, prefix?: string): ValueMap[];
+/**
+ * 将单个值转换为 A2UI ValueMap 格式
+ *
+ * @param key - 数据路径/键
+ * @param value - JavaScript 值
+ */
+declare function valueToValueMap(key: string, value: DataValue): ValueMap;
+/**
+ * 规范化路径格式
+ * - 将 . 分隔符转换为 /
+ * - 确保路径以 / 开头
+ * - 可选路径映射
+ *
+ * @param path - 原始路径
+ * @param pathMappings - 可选路径映射表
+ *
+ * @example
+ * normalizePath('user.name');        // '/user/name'
+ * normalizePath('/user/name');       // '/user/name'
+ * normalizePath('stats.count', { stats: 'progress' });  // '/progress/count'
+ */
+declare function normalizePath(path: string, pathMappings?: PathMappings): string;
+/**
+ * 更新数据项定义
+ */
+interface UpdateDataItem {
+    /** 数据路径 */
+    path: string;
+    /** 新值 */
+    value: DataValue;
+    /** 值类型（可选，用于类型提示） */
+    valueType?: 'string' | 'number' | 'boolean' | 'list' | 'map';
+    /** 操作类型（可选，用于增量更新） */
+    operation?: 'set' | 'increment' | 'decrement' | 'append' | 'remove';
+}
+/**
+ * 将更新数据项数组转换为 ValueMap
+ *
+ * @param updates - 更新数据项
+ * @param basePath - 基础路径
+ * @param pathMappings - 可选路径映射表
+ */
+declare function updatesToValueMap(updates: UpdateDataItem[], basePath?: string, pathMappings?: PathMappings): ValueMap[];
+/**
+ * 将嵌套对象扁平化为 ValueMap 条目
+ *
+ * @param obj - 要扁平化的对象
+ * @param basePath - 基础路径
+ */
+declare function flattenObjectToValueMap(obj: DataObject, basePath: string): ValueMap[];
+/**
+ * 从 ValueMap 数组中提取普通 JavaScript 对象
+ *
+ * @param valueMaps - ValueMap 数组
+ * @returns JavaScript 对象
+ */
+declare function valueMapToObject(valueMaps: ValueMap[]): DataObject;
+
+export { type AudioPlayerOptions, type ButtonOptions, type CardOptions, type CheckBoxOptions, type ChoicePickerOptions, type ComponentOptions, DEFAULT_PATH_MAPPINGS, type DateTimeInputOptions, type DividerOptions, type IconOptions, type ImageOptions, type LayoutOptions, type ListOptions, type ModalOptions, type PathMappings, type SliderOptions, type TabItem, type TabsOptions, type TextFieldOptions, type TextOptions, type UpdateDataItem, type VideoOptions, audioPlayer, beginRendering, body, button, caption, card, checkbox, choicePicker, column, createSurface, createV08Messages, createV09Messages, dataModelInit, dataModelUpdate, dateTimeInput, deleteSurface, deleteSurfaceV08, divider, flattenObjectToValueMap, generateId, getIdCounter, h1, h2, h3, h4, h5, icon, image, jsonlToMessages, list, messagesToJsonl, modal, normalizePath, objectToValueMap, pathUpdate, resetIdCounter, row, slider, surfaceUpdate, tabs, text, textButton, textField, updateComponents, updateDataModel, updatesToValueMap, valueMapToObject, valueToValueMap, video };