@tmagic/editor 1.8.0-beta.4 → 1.8.0-beta.5

package/src/utils/history.ts

@@ -0,0 +1,298 @@
+/*
+ * Tencent is pleased to support the open source community by making TMagicEditor available.
+ *
+ * Copyright (C) 2025 Tencent.  All rights reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import { cloneDeep } from 'lodash-es';
+
+import type { Id } from '@tmagic/core';
+import type { ChangeRecord } from '@tmagic/form';
+import { guid } from '@tmagic/utils';
+
+import type {
+  BaseStepValue,
+  HistoryOpSource,
+  HistoryOpType,
+  PageHistoryGroup,
+  PageHistoryStepEntry,
+  StepDiffItem,
+  StepValue,
+} from '@editor/type';
+
+import { UndoRedo } from './undo-redo';
+
+/**
+ * 「回滚」生成的新 step 简短描述。代码块 / 数据源共用。
+ * 二者逻辑一致，仅展示名取值字段不同（代码块取 `name`，数据源取 `title`），
+ * 因此通过 `getLabel` 注入取值方式。
+ *
+ * @param id 关联的代码块 / 数据源 id
+ * @param diff 单条变更 diff（缺省视为空）
+ * @param getLabel 从快照取展示名
+ */
+export const describeRevertStep = <T extends object>(
+  id: Id,
+  { oldSchema, newSchema, changeRecords }: StepDiffItem<T> = {},
+  getLabel: (schema: T) => string | undefined,
+): string => {
+  const labelOf = (schema: T) => getLabel(schema) || (schema as { id?: Id }).id;
+  if (!oldSchema && newSchema) return `撤回新增 ${labelOf(newSchema) || id}`;
+  if (oldSchema && !newSchema) return `还原已删除的 ${labelOf(oldSchema) || id}`;
+  const label = (newSchema && getLabel(newSchema)) || (oldSchema && getLabel(oldSchema)) || `${id}`;
+  const propPath = changeRecords?.[0]?.propPath;
+  return propPath ? `还原 ${label} · ${propPath}` : `还原 ${label}`;
+};
+
+/**
+ * 根据 old/new 是否为 null 推断 opType（与 push 时的约定一致）。
+ */
+export const detectStackOpType = (oldVal: unknown, newVal: unknown): 'add' | 'remove' | 'update' => {
+  if (oldVal === null && newVal !== null) return 'add';
+  if (oldVal !== null && newVal === null) return 'remove';
+  return 'update';
+};
+
+/**
+ * 构造一条代码块 / 数据源「按 id 分栈」的历史记录：两者除 payload 字段命名外完全一致。
+ *
+ * - `add`：oldValue = null；`remove`：newValue = null；`update`：两者都有，可带 changeRecords 做局部更新。
+ * - 内容会做 cloneDeep 防止后续被外部引用篡改；opType 依据 old/new 是否为 null 推断。
+ * - 仅负责构造 step 并返回，入栈与事件 emit 由各公共方法（pushCodeBlock / pushDataSource）自行处理。
+ * - 不直接驱动业务 service，调用方负责实际写回。
+ */
+export const createStackStep = <T, S extends BaseStepValue<T> & { id: Id }>(
+  id: Id,
+  payload: {
+    oldValue: T | null;
+    newValue: T | null;
+    changeRecords?: ChangeRecord[];
+    historyDescription?: string;
+    source?: HistoryOpSource;
+  },
+): S | null => {
+  if (!id) return null;
+
+  const oldSchema = payload.oldValue ? cloneDeep(payload.oldValue) : null;
+  const newSchema = payload.newValue ? cloneDeep(payload.newValue) : null;
+  const changeRecords = payload.changeRecords?.length ? cloneDeep(payload.changeRecords) : undefined;
+  const opType = detectStackOpType(payload.oldValue, payload.newValue);
+
+  const step: BaseStepValue<T> & { id: Id } = {
+    uuid: guid(),
+    id,
+    opType,
+    diff: [
+      {
+        ...(newSchema !== null ? { newSchema } : {}),
+        ...(oldSchema !== null ? { oldSchema } : {}),
+        ...(opType === 'update' && changeRecords ? { changeRecords } : {}),
+      },
+    ],
+    historyDescription: payload.historyDescription,
+    source: payload.source,
+    timestamp: Date.now(),
+  };
+
+  return step as S;
+};
+
+export const markStackSaved = <S extends { saved?: boolean }>(undoRedo?: UndoRedo<S>): void => {
+  if (!undoRedo) return;
+  undoRedo.updateElements((element) => {
+    element.saved = false;
+  });
+  undoRedo.updateCurrentElement((element) => {
+    element.saved = true;
+  });
+};
+
+/**
+ * 把单个「按 id 分栈」的历史栈（代码块 / 数据源）拆成若干 group：
+ * - 把"新增/删除"独立成组（语义上属于一次性事件，不应与 update 合并）；
+ * - 连续 'update' 合并到同一组，组内 steps 顺序就是发生顺序。
+ *
+ * 代码块与数据源除 `kind` 外结构完全一致，统一由本方法处理；`kind` 决定返回的具体分组类型。
+ */
+export const mergeStackSteps = <S extends BaseStepValue, K extends 'code-block' | 'data-source'>(
+  kind: K,
+  id: Id,
+  list: S[],
+  cursor: number,
+): {
+  kind: K;
+  id: Id;
+  opType: HistoryOpType;
+  steps: { step: S; index: number; applied: boolean; isCurrent?: boolean }[];
+  applied: boolean;
+  isCurrent?: boolean;
+}[] => {
+  type Group = {
+    kind: K;
+    id: Id;
+    opType: HistoryOpType;
+    steps: { step: S; index: number; applied: boolean; isCurrent?: boolean }[];
+    applied: boolean;
+    isCurrent?: boolean;
+  };
+  const groups: Group[] = [];
+  let current: Group | null = null;
+  const currentIndex = cursor - 1;
+  list.forEach((step, index) => {
+    const { opType } = step;
+    const applied = index < cursor;
+    const isCurrent = index === currentIndex;
+    if (opType === 'update' && current?.opType === 'update') {
+      current.steps.push({ step, index, applied, isCurrent });
+      current.applied = applied;
+      if (isCurrent) current.isCurrent = true;
+    } else {
+      current = {
+        kind,
+        id,
+        opType,
+        steps: [{ step, index, applied, isCurrent }],
+        applied,
+        isCurrent,
+      };
+      groups.push(current);
+    }
+  });
+  return groups;
+};
+
+/**
+ * 把页面栈拆成若干 group：
+ * - 单节点的 'update' 按 targetId 与相邻同 targetId 的 update 合并到一个 group；
+ * - 'add' / 'remove' 始终独立成组（语义上是结构变更，不应被收纳进单节点修改组）；
+ * - 多节点 'update'（如批量改属性）也独立成组（无明确单一目标，避免误合并）。
+ */
+export const mergePageSteps = (pageId: Id, list: StepValue[], cursor: number): PageHistoryGroup[] => {
+  const groups: PageHistoryGroup[] = [];
+  let current: PageHistoryGroup | null = null;
+  const currentIndex = cursor - 1;
+  list.forEach((step, index) => {
+    const applied = index < cursor;
+    const isCurrent = index === currentIndex;
+    const targetId = detectPageTargetId(step);
+    const targetName = detectPageTargetName(step);
+    const entry: PageHistoryStepEntry = { step, index, applied, isCurrent };
+
+    // 仅"单节点 update"参与合并；其它情形（add/remove/多节点 update）始终独立成组。
+    const mergeable = step.opType === 'update' && targetId !== undefined;
+    if (mergeable && current?.opType === 'update' && current.targetId === targetId) {
+      current.steps.push(entry);
+      current.applied = applied;
+      if (isCurrent) current.isCurrent = true;
+      // 保持目标名为最近一次的（节点重命名时也能反映）
+      if (targetName) current.targetName = targetName;
+    } else {
+      current = {
+        kind: 'page',
+        pageId,
+        opType: step.opType,
+        targetId: mergeable ? targetId : undefined,
+        targetName,
+        steps: [entry],
+        applied,
+        isCurrent,
+      };
+      groups.push(current);
+    }
+  });
+  return groups;
+};
+
+/**
+ * 解析 StepValue 中的"目标节点 id"用于合并：
+ * - 单节点 update：取唯一一项 updatedItems 的节点 id；
+ * - 其它情形（多节点 update / add / remove）：返回 undefined，表示不参与合并。
+ */
+export const detectPageTargetId = (step: StepValue): Id | undefined => {
+  if (step.opType !== 'update') return undefined;
+  const items = step.diff;
+  if (items?.length !== 1) return undefined;
+  return items[0].newSchema?.id ?? items[0].oldSchema?.id;
+};
+
+/** 解析 StepValue 中的目标节点可读名（用于 UI 展示）。 */
+export const detectPageTargetName = (step: StepValue): string | undefined => {
+  const items = step.diff;
+  if (step.opType === 'update') {
+    if (items?.length === 1) {
+      const node = items[0].newSchema || items[0].oldSchema;
+      return (node?.name as string) || (node?.type as string) || (node?.id !== undefined ? `${node.id}` : undefined);
+    }
+    return items?.length ? `${items.length} 个节点` : undefined;
+  }
+  if (step.opType === 'add') {
+    if (items?.length === 1) {
+      const n = items[0].newSchema;
+      return (n?.name as string) || (n?.type as string) || `${n?.id}`;
+    }
+    return items?.length ? `${items.length} 个节点` : undefined;
+  }
+  if (step.opType === 'remove') {
+    if (items?.length === 1) {
+      const n = items[0].oldSchema;
+      return (n?.name as string) || (n?.type as string) || `${n?.id}`;
+    }
+    return items?.length ? `${items.length} 个节点` : undefined;
+  }
+  return undefined;
+};
+
+/** 把 `Record<Id, UndoRedo>` 整体序列化为 `Record<Id, SerializedUndoRedo>`。 */
+export const serializeStacks = <T>(stacks: Record<Id, UndoRedo<T>>) => {
+  const result: Record<Id, ReturnType<UndoRedo<T>['serialize']>> = {};
+  Object.entries(stacks).forEach(([id, undoRedo]) => {
+    if (undoRedo) result[id] = undoRedo.serialize();
+  });
+  return result;
+};
+
+/**
+ * 把 `Record<Id, SerializedUndoRedo>` 整体还原为 `Record<Id, UndoRedo>`。
+ * 还原时把每个栈的游标定位到最近一条已保存（`saved === true`）记录之后。
+ */
+export const deserializeStacks = <T extends { saved?: boolean }>(
+  stacks: Record<Id, ReturnType<UndoRedo<T>['serialize']>> = {},
+): Record<Id, UndoRedo<T>> => {
+  const result: Record<Id, UndoRedo<T>> = {};
+  Object.entries(stacks).forEach(([id, serialized]) => {
+    if (serialized) {
+      result[id] = UndoRedo.fromSerialized<T>(serialized, { isSavedStep: (element) => element.saved === true });
+    }
+  });
+  return result;
+};
+
+/**
+ * 按 id 从「按 id 分栈」的记录表（代码块 / 数据源）中获取（或创建）对应的 UndoRedo 栈。
+ */
+export const getOrCreateStack = <T>(stacks: Record<Id, UndoRedo<T>>, id: Id): UndoRedo<T> => {
+  if (!stacks[id]) {
+    stacks[id] = new UndoRedo<T>();
+  }
+  return stacks[id];
+};
+
+/**
+ * 撤销下限：当页面栈 index 0 是 `opType: 'initial'` 的基线 step 时为 1（基线不可被撤销），否则为 0。
+ * 用于把 cursor 钉在基线之上，保证 undo / canUndo / goto 都不会越过初始基线。
+ */
+export const undoFloor = (undoRedo: UndoRedo<StepValue>): number => {
+  return undoRedo.getElementList()[0]?.opType === 'initial' ? 1 : 0;
+};

package/src/utils/index.ts

@@ -27,5 +27,7 @@ export * from './dep/idle-task';
 export * from './scroll-viewer';
 export * from './tree';
 export * from './undo-redo';
+export * from './indexed-db';
+export * from './history';
 export * from './const';
 export { default as loadMonaco } from './monaco-editor';

package/src/utils/indexed-db.ts

@@ -0,0 +1,122 @@
+/*
+ * Tencent is pleased to support the open source community by making TMagicEditor available.
+ *
+ * Copyright (C) 2025 Tencent.  All rights reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+/**
+ * 一组极简的、基于原生 IndexedDB 的 Promise KV 工具，避免引入额外依赖。
+ * 仅用于浏览器环境；在不支持 IndexedDB 的环境（如 SSR / 部分测试环境）下会 reject。
+ */
+
+/** 是否处于支持 IndexedDB 的环境。 */
+export const isIndexedDBSupported = (): boolean => typeof indexedDB !== 'undefined' && indexedDB !== null;
+
+/**
+ * 打开（必要时升级）数据库，确保目标 objectStore 存在后返回连接。
+ *
+ * 由于 objectStore 只能在 `onupgradeneeded` 内创建，这里先以当前版本打开，
+ * 若发现 store 不存在则关闭连接、以更高版本重开来按需创建，兼容动态 storeName。
+ */
+export const openIndexedDB = (dbName: string, storeName: string): Promise<IDBDatabase> =>
+  new Promise((resolve, reject) => {
+    if (!isIndexedDBSupported()) {
+      reject(new Error('当前环境不支持 IndexedDB'));
+      return;
+    }
+
+    const request = indexedDB.open(dbName);
+
+    request.onupgradeneeded = () => {
+      const db = request.result;
+      if (!db.objectStoreNames.contains(storeName)) {
+        db.createObjectStore(storeName);
+      }
+    };
+
+    request.onerror = () => reject(request.error);
+
+    request.onsuccess = () => {
+      const db = request.result;
+      if (db.objectStoreNames.contains(storeName)) {
+        resolve(db);
+        return;
+      }
+
+      // store 不存在：以更高版本重开，在 onupgradeneeded 中创建。
+      const nextVersion = db.version + 1;
+      db.close();
+      const upgradeRequest = indexedDB.open(dbName, nextVersion);
+      upgradeRequest.onupgradeneeded = () => {
+        const upgradeDb = upgradeRequest.result;
+        if (!upgradeDb.objectStoreNames.contains(storeName)) {
+          upgradeDb.createObjectStore(storeName);
+        }
+      };
+      upgradeRequest.onerror = () => reject(upgradeRequest.error);
+      upgradeRequest.onsuccess = () => resolve(upgradeRequest.result);
+    };
+  });
+
+/** 写入（覆盖）一条记录。value 通过结构化克隆存储，支持 Map / Set 等结构。 */
+export const idbSet = async (dbName: string, storeName: string, key: IDBValidKey, value: unknown): Promise<void> => {
+  const db = await openIndexedDB(dbName, storeName);
+  try {
+    await new Promise<void>((resolve, reject) => {
+      const tx = db.transaction(storeName, 'readwrite');
+      tx.objectStore(storeName).put(value, key);
+      tx.oncomplete = () => resolve();
+      tx.onabort = () => reject(tx.error);
+      tx.onerror = () => reject(tx.error);
+    });
+  } finally {
+    db.close();
+  }
+};
+
+/** 读取一条记录，不存在时返回 undefined。 */
+export const idbGet = async <T = unknown>(
+  dbName: string,
+  storeName: string,
+  key: IDBValidKey,
+): Promise<T | undefined> => {
+  const db = await openIndexedDB(dbName, storeName);
+  try {
+    return await new Promise<T | undefined>((resolve, reject) => {
+      const tx = db.transaction(storeName, 'readonly');
+      const request = tx.objectStore(storeName).get(key);
+      request.onsuccess = () => resolve(request.result as T | undefined);
+      request.onerror = () => reject(request.error);
+    });
+  } finally {
+    db.close();
+  }
+};
+
+/** 删除一条记录。 */
+export const idbDelete = async (dbName: string, storeName: string, key: IDBValidKey): Promise<void> => {
+  const db = await openIndexedDB(dbName, storeName);
+  try {
+    await new Promise<void>((resolve, reject) => {
+      const tx = db.transaction(storeName, 'readwrite');
+      tx.objectStore(storeName).delete(key);
+      tx.oncomplete = () => resolve();
+      tx.onabort = () => reject(tx.error);
+      tx.onerror = () => reject(tx.error);
+    });
+  } finally {
+    db.close();
+  }
+};

package/src/utils/undo-redo.ts

@@ -18,8 +18,59 @@
 
 import { cloneDeep } from 'lodash-es';
 
+// #region SerializedUndoRedo
+/**
+ * UndoRedo 栈的可序列化快照，用于持久化（如写入 IndexedDB）后再还原。
+ */
+export interface SerializedUndoRedo<T = any> {
+  /** 栈内全部元素（按时间正序，索引 0 为最早一步）。 */
+  elementList: T[];
+  /** 游标位置（已应用步骤数量）。 */
+  listCursor: number;
+  /** 栈容量上限。 */
+  listMaxSize: number;
+}
+// #endregion SerializedUndoRedo
+
 // #region UndoRedo
 export class UndoRedo<T = any> {
+  /**
+   * 由 {@link UndoRedo.serialize} 产出的快照重建一个 UndoRedo 实例。
+   * 游标会被夹紧到 [0, length] 区间，避免脏数据导致越界。
+   *
+   * @param options.isSavedStep 可选谓词：若提供，则把游标定位到「最近一条满足该谓词的记录」之后
+   *   （即恢复到最近一个已保存点）；找不到匹配记录时退回快照中的原游标。
+   */
+  public static fromSerialized<T = any>(
+    data: SerializedUndoRedo<T>,
+    options: { isSavedStep?: (element: T) => boolean } = {},
+  ): UndoRedo<T> {
+    const undoRedo = new UndoRedo<T>(data.listMaxSize);
+    const list = Array.isArray(data.elementList) ? data.elementList.map((item) => cloneDeep(item)) : [];
+    let cursor = Number.isFinite(data.listCursor) ? data.listCursor : list.length;
+
+    // 本地数据同样遵循容量上限：超出时裁掉最旧的记录（与 pushElement 的 shift 行为一致），并同步回退游标。
+    const overflow = list.length - undoRedo.listMaxSize;
+    if (overflow > 0) {
+      list.splice(0, overflow);
+      cursor -= overflow;
+    }
+
+    // 若指定了「已保存」谓词，则把游标移动到最近一条已保存记录之后；在裁剪后的 list 上查找以保证索引正确。
+    if (options.isSavedStep) {
+      for (let i = list.length - 1; i >= 0; i--) {
+        if (options.isSavedStep(list[i])) {
+          cursor = i + 1;
+          break;
+        }
+      }
+    }
+
+    undoRedo.elementList = list;
+    undoRedo.listCursor = Math.max(0, Math.min(cursor, list.length));
+    return undoRedo;
+  }
+
   private elementList: T[];
   private listCursor: number;
   private listMaxSize: number;
@@ -31,6 +82,18 @@ export class UndoRedo<T = any> {
     this.listMaxSize = listMaxSize > minListMaxSize ? listMaxSize : minListMaxSize;
   }
 
+  /**
+   * 导出当前栈的可序列化快照（深克隆，避免外部改动污染内部状态）。
+   * 配合 {@link UndoRedo.fromSerialized} 可在持久化后完整还原撤销/重做栈。
+   */
+  public serialize(): SerializedUndoRedo<T> {
+    return {
+      elementList: this.elementList.map((item) => cloneDeep(item)),
+      listCursor: this.listCursor,
+      listMaxSize: this.listMaxSize,
+    };
+  }
+
   public pushElement(element: T): void {
     // 新元素进来时，把游标之外的元素全部丢弃，并把新元素放进来
     this.elementList.splice(this.listCursor, this.elementList.length - this.listCursor, cloneDeep(element));
@@ -76,6 +139,31 @@ export class UndoRedo<T = any> {
     return cloneDeep(this.elementList[this.listCursor - 1]);
   }
 
+  /**
+   * 用 `element` 替换当前游标所在元素（cursor - 1），并丢弃其后的重做尾部（与 {@link pushElement} 的丢尾一致），
+   * 游标位置保持不变（元素数量不增）。cursor 为 0（无已应用元素）时不做任何操作并返回 false。
+   * 用于「连续同类记录合并」等就地替换最新一条的场景。
+   */
+  public replaceCurrentElement(element: T): boolean {
+    if (this.listCursor < 1) return false;
+    this.elementList.splice(this.listCursor - 1, this.elementList.length - (this.listCursor - 1), cloneDeep(element));
+    return true;
+  }
+
+  /**
+   * 对当前游标所在元素（cursor - 1）做就地更新；cursor 为 0（全部已撤销）时不做任何操作。
+   * 用于给「当前步骤」打标记（如标记为已保存）等元数据写入场景。
+   */
+  public updateCurrentElement(updater: (element: T) => void): void {
+    if (this.listCursor < 1) return;
+    updater(this.elementList[this.listCursor - 1]);
+  }
+
+  /** 对栈内全部元素做就地更新。用于批量清理元数据（如清空所有元素的已保存标记）。 */
+  public updateElements(updater: (element: T, index: number) => void): void {
+    this.elementList.forEach(updater);
+  }
+
   /**
    * 返回栈内全部元素的浅克隆数组（按时间顺序，索引 0 为最早一步）。
    * 仅用于历史面板等只读展示场景，不应直接修改返回值。