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

package/src/utils/editor.ts

@@ -35,7 +35,7 @@ import {
   isValueIncludeDataSource,
 } from '@tmagic/utils';
 
-import type { EditorNodeInfo } from '@editor/type';
+import type { EditorNodeInfo, StepValue } from '@editor/type';
 import { LayerOffset, Layout } from '@editor/type';
 
 export const COPY_STORAGE_KEY = '$MagicEditorCopyData';
@@ -132,6 +132,34 @@ const getMiddleTop = (node: MNode, parentNode: MNode, stage: StageCore | null) =
   return (Math.min(parentHeight, wrapperHeightDeal) - height) / 2;
 };
 
+// 同时存在一对相反的定位属性（如 left/right）时只保留一个，避免元素被拉伸
+const removeConflictPosition = (style: Record<string, any>, primary: string, secondary: string) => {
+  // '' / 0 / undefined / null 视为无效值
+  const isInvalid = (value: any) => value === '' || value === 0 || value === undefined || value === null;
+
+  if (!(primary in style) || !(secondary in style)) {
+    return;
+  }
+
+  const primaryValue = style[primary];
+  const secondaryValue = style[secondary];
+  const primaryInvalid = isInvalid(primaryValue);
+  const secondaryInvalid = isInvalid(secondaryValue);
+
+  if (primaryInvalid && !secondaryInvalid) {
+    delete style[primary];
+  } else if (secondaryInvalid && !primaryInvalid) {
+    delete style[secondary];
+  } else if (primaryInvalid && secondaryInvalid) {
+    // 都是无效值时优先保留 0，否则保留 primary（left/top）
+    if (secondaryValue === 0 && primaryValue !== 0) {
+      delete style[primary];
+    } else {
+      delete style[secondary];
+    }
+  }
+};
+
 export const getInitPositionStyle = (style: Record<string, any> = {}, layout: Layout) => {
   if (layout === Layout.ABSOLUTE) {
     const newStyle: Record<string, any> = {
@@ -139,6 +167,9 @@ export const getInitPositionStyle = (style: Record<string, any> = {}, layout: La
       position: 'absolute',
     };
 
+    removeConflictPosition(newStyle, 'left', 'right');
+    removeConflictPosition(newStyle, 'top', 'bottom');
+
     if (typeof newStyle.left === 'undefined' && typeof newStyle.right === 'undefined') {
       newStyle.left = 0;
     }
@@ -178,43 +209,68 @@ export const setLayout = (node: MNode, layout: Layout) => {
   return node;
 };
 
-export const change2Fixed = (node: MNode, root: MApp) => {
-  const style = {
-    ...(node.style || {}),
-  };
+type PositionKey = 'left' | 'top' | 'right' | 'bottom';
 
-  const path = getNodePath(node.id, root.items);
-  const offset = {
-    left: 0,
-    top: 0,
-  };
+// 判断 style 是否显式设置了某个定位属性，使用 typeof 判断以避免将 0（如 right: 0）误判为未设置
+const hasPositionValue = (style: Record<string, any> | undefined, key: PositionKey): boolean =>
+  typeof style?.[key] !== 'undefined' && style?.[key] !== '';
 
-  if (!node.style?.right && isNumber(node.style?.left || 0)) {
-    for (const value of path) {
-      if (value.style?.right || !isNumber(value.style?.left || 0)) {
-        offset.left = 0;
-        break;
-      }
-      offset.left = offset.left + Number(value.style?.left || 0);
+/**
+ * 沿节点路径累加（或抵消）某一方向上的定位偏移量
+ * 当路径上的祖先使用了反方向定位（例如计算 left 时祖先用了 right）或非数值定位时，
+ * 无法简单地通过求和换算坐标，此时返回 0 表示放弃补偿、保持原值
+ * @param path 从根到目标节点的路径（含节点自身）
+ * @param dir 需要累加的定位方向
+ * @param opposite 反方向定位属性
+ * @param sign change2Fixed 取 1（累加祖先偏移），Fixed2Other 取 -1（抵消祖先偏移）
+ * @param init 偏移量初始值
+ */
+const accumulatePositionOffset = (
+  path: MNode[],
+  dir: PositionKey,
+  opposite: PositionKey,
+  sign: 1 | -1,
+  init = 0,
+): number => {
+  let offset = init;
+  for (const value of path) {
+    if (hasPositionValue(value.style, opposite) || !isNumber(value.style?.[dir] || 0)) {
+      return 0;
     }
+    offset = offset + sign * Number(value.style?.[dir] || 0);
   }
+  return offset;
+};
 
-  if (!node.style?.bottom && isNumber(node.style?.top || 0)) {
-    for (const value of path) {
-      if (value.style?.bottom || !isNumber(value.style?.top || 0)) {
-        offset.top = 0;
-        break;
-      }
-      offset.top = offset.top + Number(value.style?.top || 0);
-    }
-  }
+export const change2Fixed = (node: MNode, path: MNode[]) => {
+  const style = {
+    ...(node.style || {}),
+  };
 
-  if (offset.left) {
-    style.left = offset.left;
+  // 水平方向：以 left 锚定则累加祖先 left，以 right 锚定则累加祖先 right
+  if (!hasPositionValue(node.style, 'right') && isNumber(node.style?.left || 0)) {
+    const left = accumulatePositionOffset(path, 'left', 'right', 1);
+    if (left) {
+      style.left = left;
+    }
+  } else if (hasPositionValue(node.style, 'right') && isNumber(node.style?.right || 0)) {
+    const right = accumulatePositionOffset(path, 'right', 'left', 1);
+    if (right) {
+      style.right = right;
+    }
   }
 
-  if (offset.top) {
-    style.top = offset.top;
+  // 垂直方向：以 top 锚定则累加祖先 top，以 bottom 锚定则累加祖先 bottom
+  if (!hasPositionValue(node.style, 'bottom') && isNumber(node.style?.top || 0)) {
+    const top = accumulatePositionOffset(path, 'top', 'bottom', 1);
+    if (top) {
+      style.top = top;
+    }
+  } else if (hasPositionValue(node.style, 'bottom') && isNumber(node.style?.bottom || 0)) {
+    const bottom = accumulatePositionOffset(path, 'bottom', 'top', 1);
+    if (bottom) {
+      style.bottom = bottom;
+    }
   }
 
   return style;
@@ -222,34 +278,29 @@ export const change2Fixed = (node: MNode, root: MApp) => {
 
 export const Fixed2Other = async (
   node: MNode,
-  root: MApp,
+  path: MNode[],
   getLayout: (parent: MNode, node?: MNode) => Promise<Layout>,
 ) => {
-  const path = getNodePath(node.id, root.items);
   const cur = path.pop();
   const offset = {
-    left: cur?.style?.left || 0,
-    top: cur?.style?.top || 0,
+    left: 0,
+    top: 0,
+    right: 0,
+    bottom: 0,
   };
 
-  if (!node.style?.right && isNumber(node.style?.left || 0)) {
-    for (const value of path) {
-      if (value.style?.right || !isNumber(value.style?.left || 0)) {
-        offset.left = 0;
-        break;
-      }
-      offset.left = offset.left - Number(value.style?.left || 0);
-    }
+  // 水平方向：抵消祖先在对应锚定方向上的偏移量，初始值为节点自身的偏移
+  if (!hasPositionValue(node.style, 'right') && isNumber(node.style?.left || 0)) {
+    offset.left = accumulatePositionOffset(path, 'left', 'right', -1, Number(cur?.style?.left || 0));
+  } else if (hasPositionValue(node.style, 'right') && isNumber(node.style?.right || 0)) {
+    offset.right = accumulatePositionOffset(path, 'right', 'left', -1, Number(cur?.style?.right || 0));
   }
 
-  if (!node.style?.bottom && isNumber(node.style?.top || 0)) {
-    for (const value of path) {
-      if (value.style?.bottom || !isNumber(value.style?.top || 0)) {
-        offset.top = 0;
-        break;
-      }
-      offset.top = offset.top - Number(value.style?.top || 0);
-    }
+  // 垂直方向：同上
+  if (!hasPositionValue(node.style, 'bottom') && isNumber(node.style?.top || 0)) {
+    offset.top = accumulatePositionOffset(path, 'top', 'bottom', -1, Number(cur?.style?.top || 0));
+  } else if (hasPositionValue(node.style, 'bottom') && isNumber(node.style?.bottom || 0)) {
+    offset.bottom = accumulatePositionOffset(path, 'bottom', 'top', -1, Number(cur?.style?.bottom || 0));
   }
 
   const style = node.style || {};
@@ -269,6 +320,14 @@ export const Fixed2Other = async (
       style.top = offset.top;
     }
 
+    if (offset.right) {
+      style.right = offset.right;
+    }
+
+    if (offset.bottom) {
+      style.bottom = offset.bottom;
+    }
+
     return {
       ...style,
       position: 'absolute',
@@ -316,11 +375,18 @@ export const fixNodePosition = (config: MNode, parent: MContainer, stage: StageC
     return config.style;
   }
 
-  return {
-    ...(config.style || {}),
-    top: getMiddleTop(config, parent, stage),
-    left: fixNodeLeft(config, parent, stage?.renderer?.contentWindow?.document),
-  };
+  const style = { ...(config.style || {}) };
+  const baseStyle = config.style || {};
+
+  if ('left' in baseStyle && !('right' in baseStyle)) {
+    style.left = fixNodeLeft(config, parent, stage?.renderer?.contentWindow?.document);
+  }
+
+  if ('top' in baseStyle && !('bottom' in baseStyle)) {
+    style.top = getMiddleTop(config, parent, stage);
+  }
+
+  return style;
 };
 
 // 序列化配置
@@ -460,11 +526,11 @@ export const resolveSelectedNode = (
     throw new Error('没有ID，无法选中');
   }
 
-  const { node, parent, page } = getNodeInfoFn(id);
+  const { node, parent, page, path } = getNodeInfoFn(id);
   if (!node) throw new Error('获取不到组件信息');
   if (node.id === rootId) throw new Error('不能选根节点');
 
-  return { node, parent, page };
+  return { node, parent, page, path };
 };
 
 /**
@@ -479,16 +545,16 @@ export const resolveSelectedNode = (
 export const toggleFixedPosition = async (
   dist: MNode,
   src: MNode,
-  root: MApp,
+  path: MNode[],
   getLayoutFn: (parent: MNode, node?: MNode | null) => Promise<Layout>,
 ): Promise<MNode> => {
   const newConfig = cloneDeep(dist);
 
   if (!isPop(src) && newConfig.style?.position) {
     if (isFixed(newConfig.style) && !isFixed(src.style || {})) {
-      newConfig.style = change2Fixed(newConfig, root);
+      newConfig.style = change2Fixed(newConfig, path);
     } else if (!isFixed(newConfig.style) && isFixed(src.style || {})) {
-      newConfig.style = await Fixed2Other(newConfig, root, getLayoutFn);
+      newConfig.style = await Fixed2Other(newConfig, path, getLayoutFn);
     }
   }
 
@@ -684,3 +750,43 @@ export const classifyDragSources = (
 
   return { sameParentIndices, crossParentConfigs, aborted: false };
 };
+
+/**
+ * 给「回滚」生成的新 step 用的简短描述生成器。
+ * 与 UI 层 `describePageStep` 同义，但避免 service 反向依赖 layouts/，故放在此工具函数中。
+ */
+export const describeStepForRevert = (step: StepValue): string => {
+  const items = step.diff ?? [];
+  // 在可读名后拼接组件 id，便于在历史面板中精确定位被回滚的组件；id 缺失时退化为仅展示名称。
+  const withId = (node: MNode | undefined, label: string): string => {
+    const id = node?.id;
+    if (id === undefined || id === null || `${id}` === '') return label;
+    return label ? `${label}（id: ${id}）` : `id: ${id}`;
+  };
+  switch (step.opType) {
+    case 'add': {
+      const count = items.length;
+      const node = items[0]?.newSchema;
+      const label = node?.name || node?.type || '';
+      return `撤回新增 ${count} 个节点${count === 1 ? `（${withId(node, label)}）` : ''}`;
+    }
+    case 'remove': {
+      const count = items.length;
+      const node = items[0]?.oldSchema;
+      const label = node?.name || node?.type || '';
+      return `还原已删除的 ${count} 个节点${count === 1 ? `（${withId(node, label)}）` : ''}`;
+    }
+    case 'update':
+    default: {
+      if (items.length === 1) {
+        const { newSchema, oldSchema, changeRecords } = items[0];
+        const node = newSchema || oldSchema;
+        const label = newSchema?.name || newSchema?.type || oldSchema?.name || oldSchema?.type || '';
+        const target = withId(node, label);
+        const propPath = changeRecords?.[0]?.propPath;
+        return propPath ? `还原 ${target} · ${propPath}` : `还原 ${target}`;
+      }
+      return `还原 ${items.length} 个节点的修改`;
+    }
+  }
+};

package/src/utils/history.ts

@@ -0,0 +1,308 @@
+/*
+ * 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,
+  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 合并（与页面历史的合并策略不同）。
+ *
+ * 代码块与数据源除 `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;
+}[] => {
+  const currentIndex = cursor - 1;
+  return list.map((step, index) => {
+    const applied = index < cursor;
+    const isCurrent = index === currentIndex;
+    return {
+      kind,
+      id,
+      opType: step.opType,
+      steps: [{ step, index, applied, isCurrent }],
+      applied,
+      isCurrent,
+    };
+  });
+};
+
+/**
+ * 把页面栈拆成若干 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>`。
+ *
+ * 序列化（深克隆）的同一趟里，只把每条 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。
+ * 用于把 cursor 钉在基线之上，保证 undo / canUndo / goto 都不会越过初始基线。
+ */
+export const undoFloor = (undoRedo: UndoRedo<StepValue>): 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

@@ -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';