ice-entity-designer 0.0.20 → 0.0.21

package/dist/types/react/types.d.mts

@@ -1,7 +1,7 @@
 /**
  * React 绑定层的类型定义。
  */
-import type { EntityDesigner, ProjectLoadReport } from '../index.mjs';
+import type { EntityDesigner, FlowDesigner, FlowLoadReport, FlowNodeKind, ProjectLoadReport } from '../index.mjs';
 export declare type EntityDesignerChangePayload = {
     /** 项目快照，等价于 designer.serializeProject() 的结果 */
     snapshot: string;
@@ -62,3 +62,61 @@ export declare type EntityDesignerCanvasProps = {
     /** 子节点渲染在上下文内部，可直接使用 useEntityDesigner() */
     children?: any;
 };
+export declare type FlowDesignerChangePayload = {
+    /** 流程图快照，等价于 designer.serialize() 的结果 */
+    snapshot: string;
+    /** 当前节点 / 连线条数，便于直接渲染统计信息 */
+    counts: {
+        nodes: number;
+        edges: number;
+    };
+};
+export declare type FlowDesignerHandle = {
+    /** 底层 ICE 实例（卸载后为 null） */
+    ice: any;
+    /** 底层 FlowDesigner 实例（卸载后为 null） */
+    designer: FlowDesigner | null;
+    addNode(kind: FlowNodeKind, props?: any): any;
+    connect(props: any): any;
+    updateNode(id: string, patch: any): any;
+    updateEdge(id: string, patch: any): any;
+    remove(id: string): void;
+    load(json: string): FlowLoadReport;
+    undo(): void;
+    redo(): void;
+    serialize(): string;
+    toSnapshot(): any;
+    fitViewport(padding?: number): void;
+};
+export declare type FlowDesignerCanvasProps = {
+    /**
+     * 受控模式：流程图快照。变化时会同步进画布（内部变更通过 onChange 上报，带循环保护）。
+     * 与 defaultValue 互斥，value 优先。
+     */
+    value?: string;
+    /** 非受控模式：初始流程图快照（等价于 load(defaultValue)） */
+    defaultValue?: string;
+    /** 渲染模式，默认 dirty-rect */
+    renderMode?: 'dirty-rect' | 'full';
+    /**
+     * 流程变更回调（建节点 / 连线 / 改属性 / 画布拖动 / 载入 / undo / redo 之后触发）。
+     * 注意：画布上拖动节点也会触发（FlowDesigner 订阅了引擎的 BEFORE_MOVE / AFTER_MOVE），
+     * 因此依赖它的自动保存能拿到拖拽后的最新坐标。
+     */
+    onChange?: (payload: FlowDesignerChangePayload) => void;
+    /**
+     * 快照载入失败回调（非法 / 结构不合法）。不传时默认 console.error；
+     * 组件内部已捕获，不会把错误抛进 React 渲染树。
+     */
+    onError?: (payload: EntityDesignerErrorPayload) => void;
+    /** 实例就绪回调，回调里拿到命令式句柄 */
+    onReady?: (handle: FlowDesignerHandle) => void;
+    className?: string;
+    /** 容器内联样式（与 width/height 合并） */
+    style?: any;
+    /** 画布宽高（像素），同时作为容器尺寸，默认 1200 x 800 */
+    width?: number;
+    height?: number;
+    /** 子节点渲染在上下文内部，可直接使用 useFlowDesigner() */
+    children?: any;
+};

package/dist/types/react/types.d.ts

@@ -1,7 +1,7 @@
 /**
  * React 绑定层的类型定义。
  */
-import type { EntityDesigner, ProjectLoadReport } from '../index';
+import type { EntityDesigner, FlowDesigner, FlowLoadReport, FlowNodeKind, ProjectLoadReport } from '../index';
 export declare type EntityDesignerChangePayload = {
     /** 项目快照，等价于 designer.serializeProject() 的结果 */
     snapshot: string;
@@ -62,3 +62,61 @@ export declare type EntityDesignerCanvasProps = {
     /** 子节点渲染在上下文内部，可直接使用 useEntityDesigner() */
     children?: any;
 };
+export declare type FlowDesignerChangePayload = {
+    /** 流程图快照，等价于 designer.serialize() 的结果 */
+    snapshot: string;
+    /** 当前节点 / 连线条数，便于直接渲染统计信息 */
+    counts: {
+        nodes: number;
+        edges: number;
+    };
+};
+export declare type FlowDesignerHandle = {
+    /** 底层 ICE 实例（卸载后为 null） */
+    ice: any;
+    /** 底层 FlowDesigner 实例（卸载后为 null） */
+    designer: FlowDesigner | null;
+    addNode(kind: FlowNodeKind, props?: any): any;
+    connect(props: any): any;
+    updateNode(id: string, patch: any): any;
+    updateEdge(id: string, patch: any): any;
+    remove(id: string): void;
+    load(json: string): FlowLoadReport;
+    undo(): void;
+    redo(): void;
+    serialize(): string;
+    toSnapshot(): any;
+    fitViewport(padding?: number): void;
+};
+export declare type FlowDesignerCanvasProps = {
+    /**
+     * 受控模式：流程图快照。变化时会同步进画布（内部变更通过 onChange 上报，带循环保护）。
+     * 与 defaultValue 互斥，value 优先。
+     */
+    value?: string;
+    /** 非受控模式：初始流程图快照（等价于 load(defaultValue)） */
+    defaultValue?: string;
+    /** 渲染模式，默认 dirty-rect */
+    renderMode?: 'dirty-rect' | 'full';
+    /**
+     * 流程变更回调（建节点 / 连线 / 改属性 / 画布拖动 / 载入 / undo / redo 之后触发）。
+     * 注意：画布上拖动节点也会触发（FlowDesigner 订阅了引擎的 BEFORE_MOVE / AFTER_MOVE），
+     * 因此依赖它的自动保存能拿到拖拽后的最新坐标。
+     */
+    onChange?: (payload: FlowDesignerChangePayload) => void;
+    /**
+     * 快照载入失败回调（非法 / 结构不合法）。不传时默认 console.error；
+     * 组件内部已捕获，不会把错误抛进 React 渲染树。
+     */
+    onError?: (payload: EntityDesignerErrorPayload) => void;
+    /** 实例就绪回调，回调里拿到命令式句柄 */
+    onReady?: (handle: FlowDesignerHandle) => void;
+    className?: string;
+    /** 容器内联样式（与 width/height 合并） */
+    style?: any;
+    /** 画布宽高（像素），同时作为容器尺寸，默认 1200 x 800 */
+    width?: number;
+    height?: number;
+    /** 子节点渲染在上下文内部，可直接使用 useFlowDesigner() */
+    children?: any;
+};

package/dist/types/utils/project_codec.d.mts

@@ -0,0 +1,66 @@
+/**
+ * 项目快照的**唯一字段定义**（codec）。
+ *
+ * 设计原则（与引擎的序列化机制保持一致）：
+ * 1. 真相源是组件的 `state`，这里只声明「哪些键要进文档、以及它们的类型」；
+ * 2. 写（serializeProject）与校验（validateProjectSnapshot）**共用这一份定义**，
+ *    不允许 snapshot 与 validator 各写一套字段清单（历史上正是这样漂移出 bug 的）；
+ * 3. 新增 state 字段却忘了登记时，`tests/designer/codec-completeness.test.ts`
+ *    会以「未覆盖的 state 键」形态报红，逼迫补登记或明确列入运行时字段。
+ *
+ * 与引擎的关系：引擎的 Serializer 是「遍历 state 减黑名单」，天然不会漏字段；
+ * 应用层因为要输出**扁平的领域文档**（AI/DSL/工具链消费），才需要这份显式契约，
+ * 但实现方式与引擎保持同构：类型分派走 typeId、可选值缺省即合法、未知类型跳过。
+ */
+export declare type CodecFieldType = 'string' | 'number' | 'boolean' | 'object' | 'array' | 'any';
+export declare type CodecField = {
+    key: string;
+    /** 出现时校验的类型；缺省表示 any（透传） */
+    type?: CodecFieldType;
+    /** 该键必须存在（缺省即合法只对非必填字段成立） */
+    required?: boolean;
+    /** 嵌套结构校验钩子（与字段定义同处一份，避免校验器另起一套） */
+    validate?: (value: any, prefix: string, errors: string[]) => void;
+    /** 文档用途说明（给人看） */
+    doc?: string;
+};
+/**
+ * 应用层自定义 JSON 的透传键。
+ *
+ * 应用层可以把业务元数据挂在 `component.state.data` 上（任意 JSON），
+ * 它会原样写进项目快照并在载入时回填 —— 与引擎序列化对 state 的处理一致。
+ */
+export declare const PASS_THROUGH_KEY = "data";
+/** 引擎运行时派生字段：不写进项目快照，载入后由引擎重算（与 Serializer 的黑名单同源） */
+export declare const DERIVED_STATE_KEYS: string[];
+/** 引擎默认值字段：不入文档，构造时由引擎按默认值补齐（值不变，故不算丢失） */
+export declare const CONSTRUCTOR_DEFAULT_STATE_KEYS: string[];
+/** Entity / Relation 通用字段 */
+export declare const COMPONENT_BASE_FIELDS: CodecField[];
+/** Entity 专有字段 */
+export declare const ENTITY_FIELDS: CodecField[];
+/** Relation 专有字段 */
+export declare const RELATION_FIELDS: CodecField[];
+/** 组装 Entity / Relation 的字段定义（专有 + 通用 + 透传） */
+export declare const ENTITY_DOCUMENT_FIELDS: CodecField[];
+export declare const RELATION_DOCUMENT_FIELDS: CodecField[];
+/**
+ * 按字段定义从 state 里取值，组装成文档节点。
+ *
+ * - 只写「定义里列了、且 state 里不是 undefined」的键（保持文档紧凑、可读）；
+ * - `data` 透传键原样带上。
+ */
+export declare function pickDocumentNode(state: any, fields: CodecField[]): Record<string, any>;
+/**
+ * 按同一份字段定义校验文档节点。
+ *
+ * 约定与引擎一致：**可选值缺省即合法**，只有「出现了但类型不对」才报错 —— 这样
+ * `pickDocumentNode()` 的产物永远能通过校验（读写共用一份定义带来的自洽）。
+ */
+export declare function validateDocumentNode(node: any, prefix: string, fields: CodecField[], errors: string[]): void;
+/**
+ * 找出 state 里既没被字段定义覆盖、也不属于运行时/默认值的那批键。
+ *
+ * 供 codec 完整性测试使用：返回非空即说明「新增了 state 字段但忘了登记」。
+ */
+export declare function uncoveredStateKeys(state: any, fields: CodecField[]): string[];

package/dist/types/utils/project_codec.d.ts

@@ -0,0 +1,66 @@
+/**
+ * 项目快照的**唯一字段定义**（codec）。
+ *
+ * 设计原则（与引擎的序列化机制保持一致）：
+ * 1. 真相源是组件的 `state`，这里只声明「哪些键要进文档、以及它们的类型」；
+ * 2. 写（serializeProject）与校验（validateProjectSnapshot）**共用这一份定义**，
+ *    不允许 snapshot 与 validator 各写一套字段清单（历史上正是这样漂移出 bug 的）；
+ * 3. 新增 state 字段却忘了登记时，`tests/designer/codec-completeness.test.ts`
+ *    会以「未覆盖的 state 键」形态报红，逼迫补登记或明确列入运行时字段。
+ *
+ * 与引擎的关系：引擎的 Serializer 是「遍历 state 减黑名单」，天然不会漏字段；
+ * 应用层因为要输出**扁平的领域文档**（AI/DSL/工具链消费），才需要这份显式契约，
+ * 但实现方式与引擎保持同构：类型分派走 typeId、可选值缺省即合法、未知类型跳过。
+ */
+export declare type CodecFieldType = 'string' | 'number' | 'boolean' | 'object' | 'array' | 'any';
+export declare type CodecField = {
+    key: string;
+    /** 出现时校验的类型；缺省表示 any（透传） */
+    type?: CodecFieldType;
+    /** 该键必须存在（缺省即合法只对非必填字段成立） */
+    required?: boolean;
+    /** 嵌套结构校验钩子（与字段定义同处一份，避免校验器另起一套） */
+    validate?: (value: any, prefix: string, errors: string[]) => void;
+    /** 文档用途说明（给人看） */
+    doc?: string;
+};
+/**
+ * 应用层自定义 JSON 的透传键。
+ *
+ * 应用层可以把业务元数据挂在 `component.state.data` 上（任意 JSON），
+ * 它会原样写进项目快照并在载入时回填 —— 与引擎序列化对 state 的处理一致。
+ */
+export declare const PASS_THROUGH_KEY = "data";
+/** 引擎运行时派生字段：不写进项目快照，载入后由引擎重算（与 Serializer 的黑名单同源） */
+export declare const DERIVED_STATE_KEYS: string[];
+/** 引擎默认值字段：不入文档，构造时由引擎按默认值补齐（值不变，故不算丢失） */
+export declare const CONSTRUCTOR_DEFAULT_STATE_KEYS: string[];
+/** Entity / Relation 通用字段 */
+export declare const COMPONENT_BASE_FIELDS: CodecField[];
+/** Entity 专有字段 */
+export declare const ENTITY_FIELDS: CodecField[];
+/** Relation 专有字段 */
+export declare const RELATION_FIELDS: CodecField[];
+/** 组装 Entity / Relation 的字段定义（专有 + 通用 + 透传） */
+export declare const ENTITY_DOCUMENT_FIELDS: CodecField[];
+export declare const RELATION_DOCUMENT_FIELDS: CodecField[];
+/**
+ * 按字段定义从 state 里取值，组装成文档节点。
+ *
+ * - 只写「定义里列了、且 state 里不是 undefined」的键（保持文档紧凑、可读）；
+ * - `data` 透传键原样带上。
+ */
+export declare function pickDocumentNode(state: any, fields: CodecField[]): Record<string, any>;
+/**
+ * 按同一份字段定义校验文档节点。
+ *
+ * 约定与引擎一致：**可选值缺省即合法**，只有「出现了但类型不对」才报错 —— 这样
+ * `pickDocumentNode()` 的产物永远能通过校验（读写共用一份定义带来的自洽）。
+ */
+export declare function validateDocumentNode(node: any, prefix: string, fields: CodecField[], errors: string[]): void;
+/**
+ * 找出 state 里既没被字段定义覆盖、也不属于运行时/默认值的那批键。
+ *
+ * 供 codec 完整性测试使用：返回非空即说明「新增了 state 字段但忘了登记」。
+ */
+export declare function uncoveredStateKeys(state: any, fields: CodecField[]): string[];

package/package.json

@@ -1,7 +1,7 @@
 {
   "author": "大漠穷秋",
   "name": "ice-entity-designer",
-  "version": "0.0.20",
+  "version": "0.0.21",
   "description": "An entity designer based on ice-render.",
   "repository": {
     "type": "git",