@djvlc/sandbox 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,406 @@
+import { PageSchema, ComponentInstance } from '@djvlc/contracts-types';
+
+/**
+ * 沙箱通信协议
+ * 定义 Editor 与 iframe 预览之间的消息格式
+ */
+
+/**
+ * 消息类型枚举
+ */
+declare enum MessageType {
+    READY = "ready",
+    INIT = "init",
+    DESTROY = "destroy",
+    LOAD_PAGE = "load_page",
+    UPDATE_SCHEMA = "update_schema",
+    REFRESH = "refresh",
+    SELECT_COMPONENT = "select_component",
+    HOVER_COMPONENT = "hover_component",
+    UPDATE_COMPONENT = "update_component",
+    DELETE_COMPONENT = "delete_component",
+    ADD_COMPONENT = "add_component",
+    MOVE_COMPONENT = "move_component",
+    SYNC_STATE = "sync_state",
+    SYNC_VARIABLES = "sync_variables",
+    COMPONENT_CLICK = "component_click",
+    COMPONENT_HOVER = "component_hover",
+    COMPONENT_CONTEXT_MENU = "component_context_menu",
+    COMPONENT_DRAG_START = "component_drag_start",
+    COMPONENT_DRAG_END = "component_drag_end",
+    ERROR = "error",
+    LOG = "log"
+}
+/**
+ * 基础消息结构
+ */
+interface BaseMessage<T = unknown> {
+    /** 消息类型 */
+    type: MessageType;
+    /** 消息 ID（用于请求/响应匹配） */
+    id: string;
+    /** 消息数据 */
+    data: T;
+    /** 时间戳 */
+    timestamp: number;
+}
+/**
+ * 响应消息
+ */
+interface ResponseMessage<T = unknown> extends BaseMessage<T> {
+    /** 是否成功 */
+    success: boolean;
+    /** 错误信息 */
+    error?: string;
+    /** 请求 ID */
+    requestId: string;
+}
+/**
+ * Ready 消息数据
+ */
+interface ReadyMessageData {
+    /** 运行时版本 */
+    runtimeVersion: string;
+    /** 支持的功能 */
+    capabilities: string[];
+}
+/**
+ * Init 消息数据
+ */
+interface InitMessageData {
+    /** 页面 UID */
+    pageUid?: string;
+    /** API 基础 URL */
+    apiBaseUrl: string;
+    /** CDN 基础 URL */
+    cdnBaseUrl: string;
+    /** 预览 Token */
+    previewToken?: string;
+    /** 调试模式 */
+    debug?: boolean;
+}
+/**
+ * Load Page 消息数据
+ */
+interface LoadPageMessageData {
+    /** 页面 UID */
+    pageUid: string;
+    /** 预览 Token */
+    previewToken?: string;
+}
+/**
+ * Update Schema 消息数据
+ */
+interface UpdateSchemaMessageData {
+    /** 完整 Schema */
+    schema: PageSchema;
+    /** 是否全量更新 */
+    fullUpdate?: boolean;
+}
+/**
+ * Select Component 消息数据
+ */
+interface SelectComponentMessageData {
+    /** 组件 ID */
+    componentId: string | null;
+    /** 是否多选 */
+    multi?: boolean;
+}
+/**
+ * Hover Component 消息数据
+ */
+interface HoverComponentMessageData {
+    /** 组件 ID */
+    componentId: string | null;
+}
+/**
+ * Update Component 消息数据
+ */
+interface UpdateComponentMessageData {
+    /** 组件 ID */
+    componentId: string;
+    /** 更新的属性 */
+    props?: Record<string, unknown>;
+    /** 更新的样式 */
+    style?: Record<string, unknown>;
+    /** 完整组件实例 */
+    component?: ComponentInstance;
+}
+/**
+ * Add Component 消息数据
+ */
+interface AddComponentMessageData {
+    /** 组件实例 */
+    component: ComponentInstance;
+    /** 父组件 ID */
+    parentId?: string;
+    /** 插入位置索引 */
+    index?: number;
+}
+/**
+ * Move Component 消息数据
+ */
+interface MoveComponentMessageData {
+    /** 组件 ID */
+    componentId: string;
+    /** 目标父组件 ID */
+    targetParentId?: string;
+    /** 目标位置索引 */
+    targetIndex: number;
+}
+/**
+ * Delete Component 消息数据
+ */
+interface DeleteComponentMessageData {
+    /** 组件 ID */
+    componentId: string;
+}
+/**
+ * Component Event 消息数据
+ */
+interface ComponentEventMessageData {
+    /** 组件 ID */
+    componentId: string;
+    /** 组件类型 */
+    componentType: string;
+    /** 组件边界信息 */
+    bounds?: DOMRect;
+    /** 鼠标位置 */
+    position?: {
+        x: number;
+        y: number;
+    };
+}
+/**
+ * Sync State 消息数据
+ */
+interface SyncStateMessageData {
+    /** 当前阶段 */
+    phase: string;
+    /** 页面信息 */
+    page?: {
+        pageUid: string;
+        pageVersionId: string;
+    };
+    /** 已选中组件 */
+    selectedComponents: string[];
+    /** 悬停组件 */
+    hoveredComponent: string | null;
+}
+/**
+ * Error 消息数据
+ */
+interface ErrorMessageData {
+    /** 错误代码 */
+    code: string;
+    /** 错误信息 */
+    message: string;
+    /** 错误详情 */
+    details?: Record<string, unknown>;
+}
+/**
+ * 生成消息 ID
+ */
+declare function generateMessageId(): string;
+/**
+ * 创建消息
+ */
+declare function createMessage<T>(type: MessageType, data: T): BaseMessage<T>;
+/**
+ * 创建响应消息
+ */
+declare function createResponse<T>(requestId: string, type: MessageType, success: boolean, data?: T, error?: string): ResponseMessage<T>;
+/**
+ * 检查是否为 DJVLC 消息
+ */
+declare function isDjvlcMessage(data: unknown): data is BaseMessage;
+
+/**
+ * 沙箱宿主端
+ * 在 Editor 中使用，控制 iframe 预览
+ */
+
+/**
+ * 沙箱宿主配置
+ */
+interface SandboxHostOptions {
+    /** iframe 元素 */
+    iframe: HTMLIFrameElement;
+    /** 目标 origin */
+    targetOrigin: string;
+    /** 就绪回调 */
+    onReady?: () => void;
+    /** 组件点击回调 */
+    onComponentClick?: (componentId: string, data: ComponentEventMessageData) => void;
+    /** 组件悬停回调 */
+    onComponentHover?: (componentId: string | null, data: ComponentEventMessageData) => void;
+    /** 组件右键菜单回调 */
+    onComponentContextMenu?: (componentId: string, data: ComponentEventMessageData) => void;
+    /** 状态同步回调 */
+    onSyncState?: (state: SyncStateMessageData) => void;
+    /** 错误回调 */
+    onError?: (error: {
+        code: string;
+        message: string;
+    }) => void;
+    /** 日志回调 */
+    onLog?: (level: string, message: string, ...args: unknown[]) => void;
+    /** 超时时间 */
+    timeout?: number;
+    /** 调试模式 */
+    debug?: boolean;
+}
+/**
+ * 沙箱宿主
+ */
+declare class SandboxHost {
+    private options;
+    private pendingRequests;
+    private isReady;
+    private readyPromise;
+    private readyResolve;
+    constructor(options: SandboxHostOptions);
+    /**
+     * 连接到 iframe
+     */
+    connect(): void;
+    /**
+     * 断开连接
+     */
+    disconnect(): void;
+    /**
+     * 等待就绪
+     */
+    waitReady(): Promise<void>;
+    /**
+     * 检查是否就绪
+     */
+    get ready(): boolean;
+    /**
+     * 初始化
+     */
+    init(data: InitMessageData): Promise<void>;
+    /**
+     * 加载页面
+     */
+    loadPage(data: LoadPageMessageData): Promise<void>;
+    /**
+     * 更新 Schema
+     */
+    updateSchema(data: UpdateSchemaMessageData): Promise<void>;
+    /**
+     * 刷新
+     */
+    refresh(): Promise<void>;
+    /**
+     * 选择组件
+     */
+    selectComponent(componentId: string | null, multi?: boolean): Promise<void>;
+    /**
+     * 悬停组件
+     */
+    hoverComponent(componentId: string | null): Promise<void>;
+    /**
+     * 更新组件
+     */
+    updateComponent(data: UpdateComponentMessageData): Promise<void>;
+    /**
+     * 添加组件
+     */
+    addComponent(data: AddComponentMessageData): Promise<void>;
+    /**
+     * 移动组件
+     */
+    moveComponent(data: MoveComponentMessageData): Promise<void>;
+    /**
+     * 删除组件
+     */
+    deleteComponent(componentId: string): Promise<void>;
+    /**
+     * 同步变量
+     */
+    syncVariables(variables: Record<string, unknown>): Promise<void>;
+    private handleMessage;
+    private send;
+    private log;
+}
+
+/**
+ * 沙箱客户端
+ * 在 iframe 预览中使用，响应 Editor 的控制
+ */
+/**
+ * 运行时接口（避免直接依赖 @djvlc/runtime-core）
+ */
+interface RuntimeLike {
+    getState(): {
+        phase: string;
+        page: {
+            pageUid: string;
+            pageVersionId: string;
+        } | null;
+    };
+    updateComponent(componentId: string, props: Record<string, unknown>): void;
+    setVariable(key: string, value: unknown): void;
+}
+/**
+ * 沙箱客户端配置
+ */
+interface SandboxClientOptions {
+    /** 目标 origin（Editor 的 origin） */
+    targetOrigin?: string;
+    /** 调试模式 */
+    debug?: boolean;
+}
+/**
+ * 沙箱客户端
+ */
+declare class SandboxClient {
+    private options;
+    private runtime;
+    private selectedComponents;
+    private hoveredComponent;
+    constructor(options?: SandboxClientOptions);
+    /**
+     * 设置运行时实例
+     */
+    setRuntime(runtime: RuntimeLike): void;
+    /**
+     * 连接到父窗口
+     */
+    connect(): void;
+    /**
+     * 断开连接
+     */
+    disconnect(): void;
+    /**
+     * 初始化组件事件监听
+     */
+    initComponentEventListeners(): void;
+    /**
+     * 注入编辑器样式
+     */
+    injectEditorStyles(): void;
+    private handleMessage;
+    private handleInit;
+    private handleLoadPage;
+    private handleUpdateSchema;
+    private handleRefresh;
+    private handleSelectComponent;
+    private handleHoverComponent;
+    private handleUpdateComponent;
+    private handleAddComponent;
+    private handleMoveComponent;
+    private handleDeleteComponent;
+    private handleSyncVariables;
+    private updateSelectionStyles;
+    private syncState;
+    private sendReady;
+    private sendComponentEvent;
+    private send;
+    private sendResponse;
+    private findComponentElement;
+    private log;
+}
+
+export { type AddComponentMessageData, type BaseMessage, type ComponentEventMessageData, type DeleteComponentMessageData, type ErrorMessageData, type HoverComponentMessageData, type InitMessageData, type LoadPageMessageData, MessageType, type MoveComponentMessageData, type ReadyMessageData, type ResponseMessage, SandboxClient, type SandboxClientOptions, SandboxHost, type SandboxHostOptions, type SelectComponentMessageData, type SyncStateMessageData, type UpdateComponentMessageData, type UpdateSchemaMessageData, createMessage, createResponse, generateMessageId, isDjvlcMessage };