ice-entity-designer 0.0.16 → 0.0.18

package/dist/types/designer/EntityDesigner.d.mts

@@ -0,0 +1,102 @@
+import type { ICE } from '../ice-render/index.mjs';
+import { validateSchema } from '../utils/schema_validator.mjs';
+/** 载入快照时被跳过的节点明细（typeId 未注册） */
+export declare type ProjectLoadSkippedNode = {
+    /** 该节点所在的数组 */
+    bucket: 'entities' | 'relations';
+    /** 该节点在数组中的下标 */
+    index: number;
+    /** 快照里声明的类型标识 */
+    typeId: string;
+    /** 快照里的节点 id（若存在），便于定位数据问题 */
+    id?: string;
+};
+/** loadProject() 的载入报告 */
+export declare type ProjectLoadReport = {
+    /** 是否真的发生了一次项目替换（空值 / 非项目快照为 false） */
+    loaded: boolean;
+    /** 实际创建出的实体数量 */
+    entities: number;
+    /** 实际创建出的关系数量 */
+    relations: number;
+    /** 因未注册被跳过的类型（去重），语义同引擎 `deserializer.unknownTypes` */
+    unknownTypes: string[];
+    /** 被跳过的节点明细 */
+    skipped: ProjectLoadSkippedNode[];
+};
+/**
+ * EntityDesigner 是 Entity / Relation 之上的轻量应用层。
+ *
+ * 它不替代 ICE，也不重复实现底层图元；只负责把 ER 设计器最常用的交互闭环串起来：
+ * 选择、创建、更新、删除、关系连接、Schema 输出。
+ */
+export default class EntityDesigner {
+    ice: ICE;
+    selectedId: string | null;
+    /** 变更订阅者：任何会改变模型的操作完成后都会被通知（React 绑定层用它驱动 onChange） */
+    private __changeListeners;
+    private __mousedownHandler;
+    private __undoStack;
+    private __redoStack;
+    private __historyEnabled;
+    private __maxHistory;
+    constructor(ice: ICE);
+    get entities(): any[];
+    get relations(): any[];
+    get selected(): any;
+    select(id: string | null): this;
+    createEntity(props?: any): any;
+    createRelation(props?: any): any;
+    updateEntity(id: string, patch: any): any;
+    updateRelation(id: string, patch: any): any;
+    removeComponent(id: string): void;
+    toSchemaObject(): object;
+    toSchemaString(): string;
+    validate(): ReturnType<typeof validateSchema>;
+    serializeProject(): string;
+    /**
+     * 载入项目快照（整体替换当前项目）。
+     *
+     * 节点按 `typeId` 分派构造：typeId 已注册 → 用注册的构造函数创建（下游二次开发
+     * 注册的领域图元同样适用）；未注册 → **跳过该节点并记录**，不会导致整份数据打不开，
+     * 与引擎 `Deserializer` 的容错语义一致。旧快照没有 typeId 时，按所在数组
+     * （entities / relations）归位。
+     *
+     * @throws 快照结构非法或 schemaVersion 不兼容时抛错；此时当前项目与历史栈都不会被改动。
+     * @returns 载入报告（创建数量、被跳过的未知类型）
+     */
+    loadProject(json: string): ProjectLoadReport;
+    private __componentBaseSnapshot;
+    private __entitySnapshot;
+    private __slotPoint;
+    private __relationSnapshot;
+    /**
+     * 解析并校验快照。
+     *
+     * @returns 合法快照对象；对于「压根不是项目快照」的输入（例如 `{"nope":true}`）返回 null，
+     *          保持历史行为：静默忽略而不是抛错。结构非法时抛错，由调用方决定如何呈现。
+     */
+    private __parseProject;
+    private __applyProject;
+    /** typeId 优先；缺省时按所在数组归位（兼容没有 typeId 的旧快照） */
+    private __resolveTypeId;
+    /** 由 typeId 反查构造函数：优先问 ICE 的注册表（与引擎反序列化一致） */
+    private __resolveComponentClass;
+    private __recordUnknownType;
+    private __applySnapshot;
+    private __applyHistorySnapshot;
+    canUndo(): boolean;
+    canRedo(): boolean;
+    captureHistory(): void;
+    undo(): void;
+    redo(): void;
+    /**
+     * 订阅模型变更。任何改变模型的操作（增删改 / 载入 / undo / redo）完成后会被通知，
+     * 回调参数是当前项目的序列化快照（与 serializeProject() 一致）。
+     * @returns 取消订阅函数
+     */
+    subscribe(listener: (snapshot: string) => void): () => void;
+    private __emitChange;
+    dispose(): void;
+    private __handleMouseDown;
+}

package/dist/types/designer/EntityDesigner.d.ts

@@ -0,0 +1,102 @@
+import type { ICE } from '../ice-render/index';
+import { validateSchema } from '../utils/schema_validator';
+/** 载入快照时被跳过的节点明细（typeId 未注册） */
+export declare type ProjectLoadSkippedNode = {
+    /** 该节点所在的数组 */
+    bucket: 'entities' | 'relations';
+    /** 该节点在数组中的下标 */
+    index: number;
+    /** 快照里声明的类型标识 */
+    typeId: string;
+    /** 快照里的节点 id（若存在），便于定位数据问题 */
+    id?: string;
+};
+/** loadProject() 的载入报告 */
+export declare type ProjectLoadReport = {
+    /** 是否真的发生了一次项目替换（空值 / 非项目快照为 false） */
+    loaded: boolean;
+    /** 实际创建出的实体数量 */
+    entities: number;
+    /** 实际创建出的关系数量 */
+    relations: number;
+    /** 因未注册被跳过的类型（去重），语义同引擎 `deserializer.unknownTypes` */
+    unknownTypes: string[];
+    /** 被跳过的节点明细 */
+    skipped: ProjectLoadSkippedNode[];
+};
+/**
+ * EntityDesigner 是 Entity / Relation 之上的轻量应用层。
+ *
+ * 它不替代 ICE，也不重复实现底层图元；只负责把 ER 设计器最常用的交互闭环串起来：
+ * 选择、创建、更新、删除、关系连接、Schema 输出。
+ */
+export default class EntityDesigner {
+    ice: ICE;
+    selectedId: string | null;
+    /** 变更订阅者：任何会改变模型的操作完成后都会被通知（React 绑定层用它驱动 onChange） */
+    private __changeListeners;
+    private __mousedownHandler;
+    private __undoStack;
+    private __redoStack;
+    private __historyEnabled;
+    private __maxHistory;
+    constructor(ice: ICE);
+    get entities(): any[];
+    get relations(): any[];
+    get selected(): any;
+    select(id: string | null): this;
+    createEntity(props?: any): any;
+    createRelation(props?: any): any;
+    updateEntity(id: string, patch: any): any;
+    updateRelation(id: string, patch: any): any;
+    removeComponent(id: string): void;
+    toSchemaObject(): object;
+    toSchemaString(): string;
+    validate(): ReturnType<typeof validateSchema>;
+    serializeProject(): string;
+    /**
+     * 载入项目快照（整体替换当前项目）。
+     *
+     * 节点按 `typeId` 分派构造：typeId 已注册 → 用注册的构造函数创建（下游二次开发
+     * 注册的领域图元同样适用）；未注册 → **跳过该节点并记录**，不会导致整份数据打不开，
+     * 与引擎 `Deserializer` 的容错语义一致。旧快照没有 typeId 时，按所在数组
+     * （entities / relations）归位。
+     *
+     * @throws 快照结构非法或 schemaVersion 不兼容时抛错；此时当前项目与历史栈都不会被改动。
+     * @returns 载入报告（创建数量、被跳过的未知类型）
+     */
+    loadProject(json: string): ProjectLoadReport;
+    private __componentBaseSnapshot;
+    private __entitySnapshot;
+    private __slotPoint;
+    private __relationSnapshot;
+    /**
+     * 解析并校验快照。
+     *
+     * @returns 合法快照对象；对于「压根不是项目快照」的输入（例如 `{"nope":true}`）返回 null，
+     *          保持历史行为：静默忽略而不是抛错。结构非法时抛错，由调用方决定如何呈现。
+     */
+    private __parseProject;
+    private __applyProject;
+    /** typeId 优先；缺省时按所在数组归位（兼容没有 typeId 的旧快照） */
+    private __resolveTypeId;
+    /** 由 typeId 反查构造函数：优先问 ICE 的注册表（与引擎反序列化一致） */
+    private __resolveComponentClass;
+    private __recordUnknownType;
+    private __applySnapshot;
+    private __applyHistorySnapshot;
+    canUndo(): boolean;
+    canRedo(): boolean;
+    captureHistory(): void;
+    undo(): void;
+    redo(): void;
+    /**
+     * 订阅模型变更。任何改变模型的操作（增删改 / 载入 / undo / redo）完成后会被通知，
+     * 回调参数是当前项目的序列化快照（与 serializeProject() 一致）。
+     * @returns 取消订阅函数
+     */
+    subscribe(listener: (snapshot: string) => void): () => void;
+    private __emitChange;
+    dispose(): void;
+    private __handleMouseDown;
+}

package/dist/types/er-component/Entity.d.mts

@@ -0,0 +1,104 @@
+/**
+ * Copyright (c) 2022 大漠穷秋.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ */
+import { ICEGroup, ICEPolyLine, ICERect, ICEText } from '../ice-render/index.mjs';
+export declare type EntityField = {
+    name: string;
+    type?: string;
+    length?: number | string;
+    primary?: boolean;
+    foreignKey?: boolean;
+    generated?: boolean;
+    autoIncrement?: boolean;
+    nullable?: boolean;
+    unique?: boolean;
+    default?: any;
+    comment?: string;
+    index?: boolean;
+};
+/**
+ * @class Entity 实体
+ *
+ * 所有参数按照 typeorm 要求的格式传入。
+ *
+ * @see https://typeorm.io/#/separating-entity-definition
+ * @author 大漠穷秋<damoqiongqiu@126.com>
+ */
+export default class Entity extends ICEGroup {
+    /**
+     * 稳定的类型标识。
+     *
+     * 判型与序列化都用它，**不要用 `constructor.name`** —— 下游打包器会 mangle 类名
+     * （实测 webpack 生产构建下 Entity → `Dr`），基于类名的判断会静默失效。
+     * 属性名默认不会被压缩，子类也会继承这个值。
+     */
+    static readonly typeId = "Entity";
+    protected entityNameComponent: ICEText;
+    protected headerBackgroundComponent: ICERect;
+    protected deviderLine: ICEPolyLine;
+    protected entityFieldsComponent: Array<ICEText>;
+    constructor(props: any);
+    protected static arrangeParam(props: any): any;
+    /**
+     * @method syncEntityNameAndFields 同步实体名称和字段
+     * 实体名称和字段随时可能发生变化，当变化发生时，会把原有的实体名称和字段全部删除，然后重新创建新的实例。
+     * 此方法会在 constructor 和 setState 中被调用。
+     * @see setState
+     */
+    protected syncEntityNameAndFields(): void;
+    /**
+     * 把字段信息格式化成画布上的可读文本。
+     * 常见 ER 工具会展示 PK/FK/UQ/AI/NN 等约束标记，这里做轻量实现。
+     */
+    protected fieldDisplay(field: EntityField): {
+        text: string;
+    };
+    /**
+     * @overwrite
+     * @method calcComponentParams
+     *
+     * @see ICEComponent.calcComponentParams
+     * @author 大漠穷秋<damoqiongqiu@126.com>
+     */
+    protected calcComponentParams(): {
+        width: any;
+        height: number;
+    };
+    /**
+     * 实体类的 JSON 格式描述，与 type-orm 规定的格式对应
+     *
+     * {
+     *     name: "category",
+     *     columns: {
+     *         id: {
+     *             type: Number,
+     *             primary: true,
+     *             generated: true
+     *         },
+     *         name: {
+     *             type: String
+     *         }
+     *     }
+     * }
+     *
+     * @see https://orkhan.gitbook.io/typeorm/docs/separating-entity-definition
+     */
+    toEntityObject(): any;
+    setState(newState: any): void;
+    /**
+     * 追加字段，方便应用层以命令式方式维护实体结构。
+     */
+    addField(field: EntityField): this;
+    /**
+     * 按字段名删除字段。
+     */
+    removeField(name: string): this;
+    /**
+     * 全量替换字段列表。
+     */
+    setFields(fields: EntityField[]): this;
+}

package/dist/types/er-component/Entity.d.ts

@@ -1,62 +1,104 @@
-/**
- * Copyright (c) 2022 大漠穷秋.
- *
- * This source code is licensed under the MIT license found in the
- * LICENSE file in the root directory of this source tree.
- *
- */
-import { ICEGroup, ICEPolyLine, ICEText } from 'ice-render';
-/**
- * @class Entity 实体
- *
- * 所有参数按照 typeorm 要求的格式传入。
- *
- * @see https://typeorm.io/#/separating-entity-definition
- * @author 大漠穷秋<damoqiongqiu@126.com>
- */
-export default class Entity extends ICEGroup {
-    protected entityNameComponent: ICEText;
-    protected deviderLine: ICEPolyLine;
-    protected entityFieldsComponent: Array<ICEText>;
-    constructor(props: any);
-    protected static arrangeParam(props: any): any;
-    /**
-     * @method syncEntityNameAndFields 同步实体名称和字段
-     * 实体名称和字段随时可能发生变化，当变化发生时，会把原有的实体名称和字段全部删除，然后重新创建新的实例。
-     * 此方法会在 constructor 和 setState 中被调用。
-     * @see setState
-     */
-    protected syncEntityNameAndFields(): void;
-    /**
-     * @overwrite
-     * @method calcComponentParams
-     *
-     * @see ICEComponent.calcComponentParams
-     * @author 大漠穷秋<damoqiongqiu@126.com>
-     */
-    protected calcComponentParams(): {
-        width: any;
-        height: number;
-    };
-    /**
-     * 实体类的 JSON 格式描述，与 type-orm 规定的格式对应
-     *
-     * {
-     *     name: "category",
-     *     columns: {
-     *         id: {
-     *             type: Number,
-     *             primary: true,
-     *             generated: true
-     *         },
-     *         name: {
-     *             type: String
-     *         }
-     *     }
-     * }
-     *
-     * @see https://orkhan.gitbook.io/typeorm/docs/separating-entity-definition
-     */
-    toEntityObject(): any;
-    setState(newState: any): void;
-}
+/**
+ * Copyright (c) 2022 大漠穷秋.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ */
+import { ICEGroup, ICEPolyLine, ICERect, ICEText } from '../ice-render/index';
+export declare type EntityField = {
+    name: string;
+    type?: string;
+    length?: number | string;
+    primary?: boolean;
+    foreignKey?: boolean;
+    generated?: boolean;
+    autoIncrement?: boolean;
+    nullable?: boolean;
+    unique?: boolean;
+    default?: any;
+    comment?: string;
+    index?: boolean;
+};
+/**
+ * @class Entity 实体
+ *
+ * 所有参数按照 typeorm 要求的格式传入。
+ *
+ * @see https://typeorm.io/#/separating-entity-definition
+ * @author 大漠穷秋<damoqiongqiu@126.com>
+ */
+export default class Entity extends ICEGroup {
+    /**
+     * 稳定的类型标识。
+     *
+     * 判型与序列化都用它，**不要用 `constructor.name`** —— 下游打包器会 mangle 类名
+     * （实测 webpack 生产构建下 Entity → `Dr`），基于类名的判断会静默失效。
+     * 属性名默认不会被压缩，子类也会继承这个值。
+     */
+    static readonly typeId = "Entity";
+    protected entityNameComponent: ICEText;
+    protected headerBackgroundComponent: ICERect;
+    protected deviderLine: ICEPolyLine;
+    protected entityFieldsComponent: Array<ICEText>;
+    constructor(props: any);
+    protected static arrangeParam(props: any): any;
+    /**
+     * @method syncEntityNameAndFields 同步实体名称和字段
+     * 实体名称和字段随时可能发生变化，当变化发生时，会把原有的实体名称和字段全部删除，然后重新创建新的实例。
+     * 此方法会在 constructor 和 setState 中被调用。
+     * @see setState
+     */
+    protected syncEntityNameAndFields(): void;
+    /**
+     * 把字段信息格式化成画布上的可读文本。
+     * 常见 ER 工具会展示 PK/FK/UQ/AI/NN 等约束标记，这里做轻量实现。
+     */
+    protected fieldDisplay(field: EntityField): {
+        text: string;
+    };
+    /**
+     * @overwrite
+     * @method calcComponentParams
+     *
+     * @see ICEComponent.calcComponentParams
+     * @author 大漠穷秋<damoqiongqiu@126.com>
+     */
+    protected calcComponentParams(): {
+        width: any;
+        height: number;
+    };
+    /**
+     * 实体类的 JSON 格式描述，与 type-orm 规定的格式对应
+     *
+     * {
+     *     name: "category",
+     *     columns: {
+     *         id: {
+     *             type: Number,
+     *             primary: true,
+     *             generated: true
+     *         },
+     *         name: {
+     *             type: String
+     *         }
+     *     }
+     * }
+     *
+     * @see https://orkhan.gitbook.io/typeorm/docs/separating-entity-definition
+     */
+    toEntityObject(): any;
+    setState(newState: any): void;
+    /**
+     * 追加字段，方便应用层以命令式方式维护实体结构。
+     */
+    addField(field: EntityField): this;
+    /**
+     * 按字段名删除字段。
+     */
+    removeField(name: string): this;
+    /**
+     * 全量替换字段列表。
+     */
+    setFields(fields: EntityField[]): this;
+}

package/dist/types/er-component/Relation.d.mts

@@ -0,0 +1,50 @@
+/**
+ * Copyright (c) 2022 大漠穷秋.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ */
+import { ICEVisioLink } from '../ice-render/index.mjs';
+/**
+ * @class Relation
+ *
+ * 用来描述实体类之间的关系，外观是一条带箭头的连接线。
+ * 所有参数按照 typeorm 要求的格式传入。
+ *
+ * @see https://typeorm.io/#/separating-entity-definition
+ * @author 大漠穷秋<damoqiongqiu@126.com>
+ */
+export default class Relation extends ICEVisioLink {
+    /**
+     * 稳定的类型标识。判型与序列化都用它，**不要用 `constructor.name`** ——
+     * 下游打包会 mangle 类名（实测 webpack 生产构建下 Relation → `Br`），基于类名的判断会静默失效。
+     */
+    static readonly typeId = "Relation";
+    constructor(props?: any);
+    /**
+     * 根据关系类型推断箭头方向，默认指向 FK 所在的一端。
+     */
+    static defaultArrow(relationType: string): string;
+    /**
+     * 兼容语义化的连接点写法：top/right/bottom/left/center -> T/R/B/L/C。
+     * 内核 ICELinkSlot 使用单字母标识，这里让应用层可以用更直观的单词。
+     */
+    private static normalizeLinks;
+    /**
+     * 允许应用层覆盖两端的基数写法，例如 sourceCardinality: '0..1'。
+     */
+    static cardinalityLabel(relationType: string, props?: any): string;
+    /**
+     * 在基数之外把 onDelete / onUpdate 语义显示到连线标签上，便于评审 schema。
+     */
+    static composeLabel(props: any, relationType: string): string;
+    /**
+     * 根据当前关系参数重新计算标签，忽略已有的 label，供属性面板实时更新使用。
+     */
+    static buildLabel(props: any, relationType: string): string;
+    /**
+     * 实体类的 JSON 格式描述，与 type-orm 规定的格式对应
+     */
+    toEntityObject(): any;
+}

package/dist/types/er-component/Relation.d.ts

@@ -1,24 +1,50 @@
-/**
- * Copyright (c) 2022 大漠穷秋.
- *
- * This source code is licensed under the MIT license found in the
- * LICENSE file in the root directory of this source tree.
- *
- */
-import { ICEVisioLink } from 'ice-render';
-/**
- * @class Relation
- *
- * 用来描述实体类之间的关系，外观是一条带箭头的连接线。
- * 所有参数按照 typeorm 要求的格式传入。
- *
- * @see https://typeorm.io/#/separating-entity-definition
- * @author 大漠穷秋<damoqiongqiu@126.com>
- */
-export default class Relation extends ICEVisioLink {
-    constructor(props: any);
-    /**
-     * 实体类的 JSON 格式描述，与 type-orm 规定的格式对应
-     */
-    toEntityObject(): any;
-}
+/**
+ * Copyright (c) 2022 大漠穷秋.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ */
+import { ICEVisioLink } from '../ice-render/index';
+/**
+ * @class Relation
+ *
+ * 用来描述实体类之间的关系，外观是一条带箭头的连接线。
+ * 所有参数按照 typeorm 要求的格式传入。
+ *
+ * @see https://typeorm.io/#/separating-entity-definition
+ * @author 大漠穷秋<damoqiongqiu@126.com>
+ */
+export default class Relation extends ICEVisioLink {
+    /**
+     * 稳定的类型标识。判型与序列化都用它，**不要用 `constructor.name`** ——
+     * 下游打包会 mangle 类名（实测 webpack 生产构建下 Relation → `Br`），基于类名的判断会静默失效。
+     */
+    static readonly typeId = "Relation";
+    constructor(props?: any);
+    /**
+     * 根据关系类型推断箭头方向，默认指向 FK 所在的一端。
+     */
+    static defaultArrow(relationType: string): string;
+    /**
+     * 兼容语义化的连接点写法：top/right/bottom/left/center -> T/R/B/L/C。
+     * 内核 ICELinkSlot 使用单字母标识，这里让应用层可以用更直观的单词。
+     */
+    private static normalizeLinks;
+    /**
+     * 允许应用层覆盖两端的基数写法，例如 sourceCardinality: '0..1'。
+     */
+    static cardinalityLabel(relationType: string, props?: any): string;
+    /**
+     * 在基数之外把 onDelete / onUpdate 语义显示到连线标签上，便于评审 schema。
+     */
+    static composeLabel(props: any, relationType: string): string;
+    /**
+     * 根据当前关系参数重新计算标签，忽略已有的 label，供属性面板实时更新使用。
+     */
+    static buildLabel(props: any, relationType: string): string;
+    /**
+     * 实体类的 JSON 格式描述，与 type-orm 规定的格式对应
+     */
+    toEntityObject(): any;
+}