@tmagic/editor 1.8.0-beta.1 → 1.8.0-beta.10

package/src/utils/history.ts

@@ -0,0 +1,286 @@
+/*
+ * 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 serialize from 'serialize-javascript';
+
+import type { Id } from '@tmagic/core';
+import type { ChangeRecord } from '@tmagic/form';
+import { guid } from '@tmagic/utils';
+
+import type { BaseStepValue, HistoryGroup, StepDiffItem } 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 由统一的 history.push(stepType, step, id) 处理。
+ * - 不直接驱动业务 service，调用方负责实际写回。
+ */
+export const createStackStep = <T, S extends BaseStepValue<T>>(
+  id: Id,
+  // payload 以 {@link BaseStepValue} 为基础：透传字段（historyDescription / source / operator / rootStep / extra）
+  // 随 BaseStepValue 演进自动同步，原样写入 step；自动生成字段（uuid / data / opType / diff / timestamp / saved）
+  // 从 payload 中排除，由本方法内部构造。oldValue / newValue / changeRecords / name 为构造 diff 与 data 用的输入。
+  payload: Omit<BaseStepValue<T>, 'uuid' | 'data' | 'opType' | 'diff' | 'timestamp' | 'saved'> & {
+    oldValue: T | null;
+    newValue: T | null;
+    changeRecords?: ChangeRecord[];
+    /** 展示名（缺省时从快照 name / title 推断）。 */
+    name?: string;
+  },
+): 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);
+  // 展示名：代码块取 name，数据源取 title，取不到则留空（不影响 undo/redo，仅用于展示）。
+  const schema = (payload.newValue ?? payload.oldValue) as { name?: string; title?: string } | null;
+  const name = payload.name ?? schema?.name ?? schema?.title ?? '';
+
+  const step: BaseStepValue<T> = {
+    uuid: guid(),
+    data: { name, id },
+    opType,
+    diff: [
+      {
+        ...(newSchema !== null ? { newSchema } : {}),
+        ...(oldSchema !== null ? { oldSchema } : {}),
+        ...(opType === 'update' && changeRecords ? { changeRecords } : {}),
+      },
+    ],
+    historyDescription: payload.historyDescription,
+    source: payload.source,
+    operator: payload.operator,
+    rootStep: payload.rootStep,
+    timestamp: Date.now(),
+    extra: payload.extra,
+  };
+
+  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;
+  });
+};
+
+/**
+ * 把单个历史栈（页面 / 代码块 / 数据源 / 扩展类型）的步骤列表按"目标"做相邻合并：
+ * - 单实体的 'update' 按 targetId 与相邻同 targetId 的 update 合并到一个 group，组内可展开查看每步；
+ * - 'add' / 'remove' 始终独立成组（语义上是结构变更，不应被收纳进单实体修改组）；
+ * - 多实体 'update'（如页面批量改属性）也独立成组（无明确单一目标，避免误合并）。
+ *
+ * 各类型行为完全一致，仅 `kind` 与 step 快照类型不同，统一由本方法处理。
+ */
+export const mergeSteps = <T extends BaseStepValue>(
+  kind: string,
+  id: Id,
+  list: T[],
+  cursor: number,
+): HistoryGroup<T>[] => {
+  const groups: HistoryGroup<T>[] = [];
+  let current: HistoryGroup<T> | null = null;
+  const currentIndex = cursor - 1;
+  list.forEach((step, index) => {
+    const applied = index < cursor;
+    const isCurrent = index === currentIndex;
+    const targetId = detectTargetId(step);
+    const targetName = detectTargetName(step);
+    const entry = { 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,
+        id,
+        opType: step.opType,
+        targetId: mergeable ? targetId : undefined,
+        targetName,
+        steps: [entry],
+        applied,
+        isCurrent,
+      };
+      groups.push(current);
+    }
+  });
+  return groups;
+};
+
+/**
+ * 解析 step 中的"目标 id"用于合并：
+ * - 单实体 update：取唯一一项 diff 的快照 id；快照无 id 时（如 CodeBlockContent）回退到 `step.data.id`
+ *   （即资源 id），使代码块 / 数据源同样能按资源合并相邻 update；
+ * - 其它情形（多实体 update / add / remove）：返回 undefined，表示不参与合并。
+ */
+export const detectTargetId = (step: BaseStepValue): Id | undefined => {
+  if (step.opType !== 'update') return undefined;
+  const items = step.diff;
+  if (items?.length !== 1) return undefined;
+  const newSchema = items[0].newSchema as { id?: Id } | undefined;
+  const oldSchema = items[0].oldSchema as { id?: Id } | undefined;
+  return newSchema?.id ?? oldSchema?.id ?? step.data?.id;
+};
+
+/** 解析 step 中的目标可读名（用于 UI 展示）。 */
+export const detectTargetName = (step: BaseStepValue): string | undefined => {
+  const items = step.diff;
+  if (step.opType === 'update') {
+    if (items?.length === 1) {
+      const node = (items[0].newSchema || items[0].oldSchema) as { name?: string; type?: string; id?: Id } | undefined;
+      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 as { name?: string; type?: string; id?: Id } | undefined;
+      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 as { name?: string; type?: string; id?: Id } | undefined;
+      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>`。
+ *
+ * 序列化（深克隆）的同一趟里，只把每条 step 中可能含函数的 `diff` 用 serialize-javascript 序列化成字符串，
+ * 其余字段（uuid / opType / timestamp / `modifiedNodeIds` Map 等）原样保留，交给 IndexedDB 结构化克隆。
+ * 这样既能写入函数，又避免序列化整份快照的开销；读取时再由 {@link parseStacksStepDiff} 还原 diff。
+ * 不含 `diff` 的元素（如通用栈）原样透传。
+ */
+export const serializeStacks = <T extends { diff?: unknown }>(stacks: Record<Id, UndoRedo<T>>) => {
+  const result: Record<Id, ReturnType<UndoRedo<T>['serialize']>> = {};
+  Object.entries(stacks).forEach(([id, undoRedo]) => {
+    if (!undoRedo) return;
+    const serialized = undoRedo.serialize();
+    result[id] = {
+      ...serialized,
+      elementList: serialized.elementList.map((step) =>
+        step.diff === undefined ? step : Object.assign({}, step, { diff: serialize(step.diff) }),
+      ),
+    };
+  });
+  return result;
+};
+
+/**
+ * 把 `Record<Id, SerializedUndoRedo>` 整体还原为 `Record<Id, UndoRedo>`。
+ * 还原时把每个栈的游标定位到最近一条已保存（`saved === true`）记录之后。
+ *
+ * 与 {@link serializeStacks} 相反：当传入 `parse`（parseDSL）时，把每条 step 中以字符串形式存储的 `diff`
+ * 解析回真实对象（含函数）；不含 `diff` 的元素（如通用栈）原样透传。
+ */
+export const deserializeStacks = <T extends { saved?: boolean }>(
+  stacks: Record<Id, ReturnType<UndoRedo<T>['serialize']>> = {},
+  parse?: (serialized: string) => unknown,
+): Record<Id, UndoRedo<T>> => {
+  const result: Record<Id, UndoRedo<T>> = {};
+  Object.entries(stacks).forEach(([id, serialized]) => {
+    if (!serialized) return;
+    const elementList = parse
+      ? serialized.elementList.map((step) => {
+          const { diff } = step as { diff?: unknown };
+          return typeof diff === 'string' ? Object.assign({}, step, { diff: parse(`(${diff})`) }) : step;
+        })
+      : serialized.elementList;
+    result[id] = UndoRedo.fromSerialized<T>(
+      { ...serialized, elementList },
+      { 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。
+ * 适用于所有历史类型（page / codeBlock / dataSource / 扩展），把 cursor 钉在基线之上，
+ * 保证 undo / canUndo / goto 都不会越过初始基线。
+ */
+export const undoFloor = (undoRedo: UndoRedo<any>): number => {
+  return undoRedo.getElementList()[0]?.opType === 'initial' ? 1 : 0;
+};
+
+/** 将单次 push 产生的 history uuid（或 null）转为 *AndGetHistoryId 返回用的 uuid 列表。 */
+export const getLastPushedHistoryIds = (historyId: string | null): string[] => (historyId ? [historyId] : []);

package/src/utils/index.ts

@@ -18,6 +18,7 @@
 
 export * from './config';
 export * from './props';
+export * from './code-block';
 export * from './logger';
 export * from './editor';
 export * from './operator';
@@ -26,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));
@@ -75,5 +138,53 @@ 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 为最早一步）。
+   * 仅用于历史面板等只读展示场景，不应直接修改返回值。
+   */
+  public getElementList(): T[] {
+    return this.elementList.slice();
+  }
+
+  /**
+   * 当前游标位置：表示已应用的步骤数量。
+   * - cursor === 0 表示全部已撤销
+   * - cursor === length 表示已重做到末尾
+   * 历史面板用于区分"已应用 / 已撤销"两段。
+   */
+  public getCursor(): number {
+    return this.listCursor;
+  }
+
+  /** 栈内总步数。 */
+  public getLength(): number {
+    return this.elementList.length;
+  }
 }
 // #endregion UndoRedo