@tmagic/editor 1.8.0-beta.0 → 1.8.0-beta.2

package/src/fields/UISelect.vue

@@ -6,7 +6,7 @@
   </div>
   <div class="m-fields-ui-select" v-else style="display: flex">
     <template v-if="val">
-      <TMagicTooltip content="清除" placement="top">
+      <TMagicTooltip v-if="!isCompare" content="清除" placement="top">
         <TMagicButton
           style="padding: 0"
           type="danger"
@@ -32,7 +32,7 @@
       </TMagicTooltip>
     </template>
 
-    <TMagicTooltip v-else content="点击此处选择" placement="top">
+    <TMagicTooltip v-else-if="!isCompare" content="点击此处选择" placement="top">
       <TMagicButton link style="padding: 0; margin: 0" :disabled="disabled" :size="size" @click="startSelect"
         >点击此处选择</TMagicButton
       >
@@ -67,6 +67,9 @@ const mForm = inject<FormState>('mForm');
 const val = computed(() => props.model[props.name]);
 const uiSelectMode = ref(false);
 
+/** 对比模式下隐藏清除/选择等操作按钮，仅保留只读展示。 */
+const isCompare = computed(() => Boolean(mForm?.isCompare));
+
 const cancelHandler = () => {
   uiService.set('uiSelectMode', false);
   uiSelectMode.value = false;

package/src/hooks/use-code-block-edit.ts

@@ -3,6 +3,7 @@ import { cloneDeep } from 'lodash-es';
 
 import type { CodeBlockContent } from '@tmagic/core';
 import { tMagicMessage } from '@tmagic/design';
+import type { ContainerChangeEventData } from '@tmagic/form';
 
 import CodeBlockEditor from '@editor/components/CodeBlockEditor.vue';
 import type { Services } from '@editor/type';
@@ -61,10 +62,12 @@ export const useCodeBlockEdit = (codeBlockService: Services['codeBlockService'])
     codeBlockService.deleteCodeDslByIds([key]);
   };
 
-  const submitCodeBlockHandler = async (values: CodeBlockContent) => {
+  const submitCodeBlockHandler = async (values: CodeBlockContent, eventData?: ContainerChangeEventData) => {
     if (!codeId.value) return;
 
-    await codeBlockService.setCodeDslById(codeId.value, values);
+    await codeBlockService.setCodeDslById(codeId.value, values, {
+      changeRecords: eventData?.changeRecords,
+    });
 
     codeBlockEditorRef.value?.hide();
   };

package/src/hooks/use-stage.ts

@@ -97,23 +97,39 @@ export const useStage = (stageOptions: StageOptions) => {
 
   stage.on('update', (ev: UpdateEventData) => {
     if (ev.parentEl) {
-      for (const data of ev.data) {
-        const id = getIdFromEl()(data.el);
-        const pId = getIdFromEl()(ev.parentEl);
-        id && pId && editorService.moveToContainer({ id, style: data.style }, pId);
+      // 拖动多选元素到一个新容器：整批合成一次 moveToContainer，只产生一条历史记录
+      const pId = getIdFromEl()(ev.parentEl);
+      if (!pId) return;
+      const configs = ev.data
+        .map((data) => {
+          const id = getIdFromEl()(data.el);
+          if (!id) return null;
+          const cfg: MNode = { id, style: data.style };
+          return cfg;
+        })
+        .filter((cfg): cfg is MNode => Boolean(cfg));
+      if (configs.length > 0) {
+        editorService.moveToContainer(configs, pId);
       }
       return;
     }
 
-    // 为每个元素单独更新，确保 changeRecords 与对应的元素关联
+    // 多选拖动 / 多选缩放：所有元素整批走一次 update，避免历史栈被切成 N 条
+    // changeRecordList 与 configs 同序，每个节点保留自己的 records；
+    // 不能把多个节点的 records 合并到同一个数组里，否则 doUpdate / nodeUpdateHandler 会把别的节点的 propPath 当成自己的。
+    const configs: MNode[] = [];
+    const changeRecordList: ReturnType<typeof buildChangeRecords>[] = [];
     ev.data.forEach((data) => {
       const id = getIdFromEl()(data.el);
       if (!id) return;
 
       const { style = {} } = data;
-
-      editorService.update({ id, style }, { changeRecords: buildChangeRecords(style, 'style') });
+      configs.push({ id, style });
+      changeRecordList.push(buildChangeRecords(style, 'style'));
     });
+    if (configs.length === 0) return;
+
+    editorService.update(configs, { changeRecordList });
   });
 
   stage.on('sort', (ev: SortEventData) => {

package/src/index.ts

@@ -70,6 +70,7 @@ export { default as LayoutContainer } from './components/SplitView.vue';
 export { default as SplitView } from './components/SplitView.vue';
 export { default as Resizer } from './components/Resizer.vue';
 export { default as CodeBlockEditor } from './components/CodeBlockEditor.vue';
+export { default as CompareForm } from './components/CompareForm.vue';
 export { default as FloatingBox } from './components/FloatingBox.vue';
 export { default as Tree } from './components/Tree.vue';
 export { default as TreeNode } from './components/TreeNode.vue';

package/src/layouts/CodeEditor.vue

@@ -330,6 +330,21 @@ watch(
   },
 );
 
+// diff 模式下，对比的"当前值"（modifiedValues）也可能在外部变化（例如 lastValues 不变、当前 model 变了），
+// 此时同样需要重新设置编辑器值，否则右侧编辑器内容会停留在初始化时的快照。
+watch(
+  () => props.modifiedValues,
+  (v, preV) => {
+    if (props.type !== 'diff') return;
+    if (v !== preV) {
+      setEditorValue(props.initValues, props.modifiedValues);
+    }
+  },
+  {
+    deep: true,
+  },
+);
+
 watch(
   () => props.options,
   (v) => {

package/src/layouts/Framework.vue

@@ -23,15 +23,15 @@
       left-class="m-editor-framework-left"
       center-class="m-editor-framework-center"
       right-class="m-editor-framework-right"
-      :left="columnWidth.left"
+      :left="hideSidebar ? undefined : columnWidth.left"
       :right="columnWidth.right"
-      :min-left="MIN_LEFT_COLUMN_WIDTH"
+      :min-left="hideSidebar ? 0 : MIN_LEFT_COLUMN_WIDTH"
       :min-right="MIN_RIGHT_COLUMN_WIDTH"
       :min-center="MIN_CENTER_COLUMN_WIDTH"
       :width="frameworkRect.width"
       @change="columnWidthChange"
     >
-      <template #left>
+      <template v-if="!hideSidebar" #left>
         <slot name="sidebar"></slot>
       </template>
 
@@ -94,10 +94,12 @@ defineOptions({
   name: 'MEditorFramework',
 });
 
-defineProps<{
+const props = defineProps<{
   disabledPageFragment: boolean;
   pageBarSortOptions?: PageBarSortOptions;
   pageFilterFunction?: (_page: MPage | MPageFragment, _keyword: string) => boolean;
+  /** 是否隐藏左侧面板 */
+  hideSidebar?: boolean;
 }>();
 
 const codeOptions = inject('codeOptions', {});
@@ -132,7 +134,10 @@ watch(
 );
 
 const columnWidthChange = (columnW: GetColumnWidth) => {
-  storageService.setItem(LEFT_COLUMN_WIDTH_STORAGE_KEY, columnW.left, { protocol: Protocol.NUMBER });
+  // 隐藏左侧面板时 left 恒为 0，不覆盖已持久化的左栏宽度，避免重新展示时丢失宽度
+  if (!props.hideSidebar) {
+    storageService.setItem(LEFT_COLUMN_WIDTH_STORAGE_KEY, columnW.left, { protocol: Protocol.NUMBER });
+  }
   storageService.setItem(RIGHT_COLUMN_WIDTH_STORAGE_KEY, columnW.right, { protocol: Protocol.NUMBER });
 
   uiService.set('columnWidth', columnW);

package/src/layouts/NavMenu.vue

@@ -19,6 +19,7 @@ import { NodeType } from '@tmagic/core';
 import { useServices } from '@editor/hooks/use-services';
 import { ColumnLayout, MenuBarData, MenuButton, MenuComponent, MenuItem } from '@editor/type';
 
+import HistoryListPanel from './history-list/HistoryListPanel.vue';
 import NavMenuColumn from './NavMenuColumn.vue';
 
 defineOptions({
@@ -103,6 +104,14 @@ const getConfig = (item: MenuItem): (MenuButton | MenuComponent)[] => {
         handler: () => editorService.redo(),
       });
       break;
+    case 'history-list':
+      // 历史记录面板：以 component 形式挂入，自带 popover；点击 nav 上的图标弹出。
+      config.push({
+        type: 'component',
+        className: 'history-list',
+        component: markRaw(HistoryListPanel),
+      });
+      break;
     case 'zoom-in':
       config.push({
         type: 'button',

package/src/layouts/history-list/Bucket.vue

@@ -0,0 +1,99 @@
+<template>
+  <div class="m-editor-history-list-bucket">
+    <div class="m-editor-history-list-bucket-title">
+      <span>{{ title }}</span>
+      <code>{{ String(bucketId) }}</code>
+      <span class="m-editor-history-list-bucket-count">{{ groups.length }} 组</span>
+    </div>
+
+    <ul class="m-editor-history-list-ul">
+      <GroupRow
+        v-for="(group, gIdx) in groups"
+        :key="`${prefix}-${bucketId}-${gIdx}`"
+        :group-key="`${prefix}-${bucketId}-${gIdx}`"
+        :applied="group.applied"
+        :merged="group.steps.length > 1"
+        :op-type="group.opType"
+        :desc="describeGroup(group)"
+        :step-count="group.steps.length"
+        :sub-steps="
+          group.steps.map((s: any) => ({
+            index: s.index,
+            applied: s.applied,
+            isCurrent: s.isCurrent,
+            desc: describeStep(s.step),
+            diffable: isStepDiffable ? isStepDiffable(s.step) : false,
+            revertable: s.applied,
+          }))
+        "
+        :is-current="group.isCurrent"
+        :expanded="!!expanded[`${prefix}-${bucketId}-${gIdx}`]"
+        @toggle="(key: string) => $emit('toggle', key)"
+        @goto="(index: number) => $emit('goto', bucketId, index)"
+        @diff-step="(index: number) => $emit('diff-step', bucketId, index)"
+        @revert-step="(index: number) => $emit('revert-step', bucketId, index)"
+      />
+      <!--
+        初始状态项：永远位于该 bucket 列表底部（同样按倒序展示，最底部 = 最早状态）。
+        当 bucket 内所有 group 都未 applied 时即为当前位置。
+      -->
+      <InitialRow :is-current="isInitial" @goto-initial="$emit('goto-initial', bucketId)" />
+    </ul>
+  </div>
+</template>
+
+<script lang="ts" setup>
+import { computed } from 'vue';
+
+import type { HistoryOpType } from '@editor/type';
+
+import GroupRow from './GroupRow.vue';
+import InitialRow from './InitialRow.vue';
+
+defineOptions({
+  name: 'MEditorHistoryListBucket',
+});
+
+const props = defineProps<{
+  /** Bucket 标题，例如 "数据源" / "代码块"，渲染在 bucket 头部。 */
+  title: string;
+  /** 当前 bucket 对应的目标 id（dataSource.id 或 codeBlock.id），同时用于组装子项的 key。 */
+  bucketId: string | number;
+  /** 子项 key 的命名空间前缀：`ds` 表示数据源，`cb` 表示代码块。与上层折叠状态 key 保持一致。 */
+  prefix: 'ds' | 'cb';
+  /** 当前 bucket 下的所有历史分组，按时间倒序展示（最近的操作在前）。 */
+  groups: {
+    applied: boolean;
+    isCurrent?: boolean;
+    opType: HistoryOpType;
+    steps: { index: number; applied: boolean; isCurrent?: boolean; step: any }[];
+  }[];
+  /** 组级描述文案生成器，接收一个 group，返回展示文本。由父组件按业务类型注入。 */
+  describeGroup: (_group: any) => string;
+  /** 单步描述文案生成器，接收一个 step，返回展示文本。用于合并组展开后的子步列表。 */
+  describeStep: (_step: any) => string;
+  /** 判断某个 step 是否可查看差异（前后值都存在）。由父组件按业务类型注入；不传则一律不展示差异入口。 */
+  isStepDiffable?: (_step: any) => boolean;
+  /** 共享的折叠状态表（key -> 是否展开），由顶层 panel 统一维护以便跨 tab 复用。 */
+  expanded: Record<string, boolean>;
+}>();
+
+defineEmits<{
+  /** 透传子组件 GroupRow 的 toggle，由上层 panel 更新 expanded。 */
+  (_e: 'toggle', _key: string): void;
+  /**
+   * 透传子组件 GroupRow 的 goto，并附带当前 bucket 对应的 id（dataSourceId / codeBlockId），
+   * 上层据此调用对应 service.goto(id, targetCursor)。
+   */
+  (_e: 'goto', _bucketId: string | number, _index: number): void;
+  /** 用户点击初始项希望该 bucket 回到未修改状态；携带 bucketId 用于上层路由到正确的 service。 */
+  (_e: 'goto-initial', _bucketId: string | number): void;
+  /** 用户点击"查看差异"，携带 bucketId 与 step 索引。 */
+  (_e: 'diff-step', _bucketId: string | number, _index: number): void;
+  /** 用户点击"回滚"按钮，携带 bucketId 与 step 索引，类 git revert。 */
+  (_e: 'revert-step', _bucketId: string | number, _index: number): void;
+}>();
+
+/** 该 bucket 是否处于初始状态（栈 cursor=0），等价于全部 group 都未 applied。 */
+const isInitial = computed(() => props.groups.length > 0 && props.groups.every((g) => !g.applied));
+</script>

package/src/layouts/history-list/CodeBlockTab.vue

@@ -0,0 +1,61 @@
+<template>
+  <div v-if="!buckets.length" class="m-editor-history-list-empty">暂无操作记录</div>
+  <TMagicScrollbar v-else max-height="360px">
+    <Bucket
+      v-for="bucket in buckets"
+      :key="`cb-${bucket.id}`"
+      title="代码块"
+      :bucket-id="bucket.id"
+      prefix="cb"
+      :groups="bucket.groups"
+      :describe-group="describeCodeBlockGroup"
+      :describe-step="describeCodeBlockStep"
+      :is-step-diffable="isCodeBlockStepDiffable"
+      :expanded="expanded"
+      @toggle="(key: string) => $emit('toggle', key)"
+      @goto="(id: string | number, index: number) => $emit('goto', id, index)"
+      @goto-initial="(id: string | number) => $emit('goto-initial', id)"
+      @diff-step="(id: string | number, index: number) => $emit('diff-step', id, index)"
+      @revert-step="(id: string | number, index: number) => $emit('revert-step', id, index)"
+    />
+  </TMagicScrollbar>
+</template>
+
+<script lang="ts" setup>
+import { TMagicScrollbar } from '@tmagic/design';
+
+import type { CodeBlockHistoryGroup, CodeBlockStepValue } from '@editor/type';
+
+import Bucket from './Bucket.vue';
+import { describeCodeBlockGroup, describeCodeBlockStep } from './composables';
+
+defineOptions({
+  name: 'MEditorHistoryListCodeBlockTab',
+});
+
+defineProps<{
+  /**
+   * 已按 codeBlock.id 聚拢成的 bucket 列表，每个 bucket 内部的 groups 已按时间倒序排好。
+   * 空数组时显示空态。
+   */
+  buckets: { id: string | number; groups: CodeBlockHistoryGroup[] }[];
+  /** 共享的折叠状态表（key -> 是否展开），由顶层 panel 统一维护。本 tab 使用 `cb-${id}-${idx}` 作为 key。 */
+  expanded: Record<string, boolean>;
+}>();
+
+defineEmits<{
+  /** 透传子组件 Bucket 的 toggle 事件给上层 panel，由其更新 expanded。 */
+  (_e: 'toggle', _key: string): void;
+  /** 透传 Bucket 的 goto 事件，携带 codeBlock id 与目标 step 索引。 */
+  (_e: 'goto', _codeBlockId: string | number, _index: number): void;
+  /** 透传 Bucket 的 goto-initial 事件，携带 codeBlock id（回到该代码块未修改时的状态）。 */
+  (_e: 'goto-initial', _codeBlockId: string | number): void;
+  /** 透传 Bucket 的 diff-step 事件，携带 codeBlock id 与 step 索引。 */
+  (_e: 'diff-step', _codeBlockId: string | number, _index: number): void;
+  /** 透传 Bucket 的 revert-step 事件，携带 codeBlock id 与 step 索引（类 git revert）。 */
+  (_e: 'revert-step', _codeBlockId: string | number, _index: number): void;
+}>();
+
+/** 仅 update（前后 content 都存在）时可查看差异。 */
+const isCodeBlockStepDiffable = (step: CodeBlockStepValue) => Boolean(step.oldContent && step.newContent);
+</script>

package/src/layouts/history-list/DataSourceTab.vue

@@ -0,0 +1,61 @@
+<template>
+  <div v-if="!buckets.length" class="m-editor-history-list-empty">暂无操作记录</div>
+  <TMagicScrollbar v-else max-height="360px">
+    <Bucket
+      v-for="bucket in buckets"
+      :key="`ds-${bucket.id}`"
+      title="数据源"
+      :bucket-id="bucket.id"
+      prefix="ds"
+      :groups="bucket.groups"
+      :describe-group="describeDataSourceGroup"
+      :describe-step="describeDataSourceStep"
+      :is-step-diffable="isDataSourceStepDiffable"
+      :expanded="expanded"
+      @toggle="(key: string) => $emit('toggle', key)"
+      @goto="(id: string | number, index: number) => $emit('goto', id, index)"
+      @goto-initial="(id: string | number) => $emit('goto-initial', id)"
+      @diff-step="(id: string | number, index: number) => $emit('diff-step', id, index)"
+      @revert-step="(id: string | number, index: number) => $emit('revert-step', id, index)"
+    />
+  </TMagicScrollbar>
+</template>
+
+<script lang="ts" setup>
+import { TMagicScrollbar } from '@tmagic/design';
+
+import type { DataSourceHistoryGroup, DataSourceStepValue } from '@editor/type';
+
+import Bucket from './Bucket.vue';
+import { describeDataSourceGroup, describeDataSourceStep } from './composables';
+
+defineOptions({
+  name: 'MEditorHistoryListDataSourceTab',
+});
+
+defineProps<{
+  /**
+   * 已按 dataSource.id 聚拢成的 bucket 列表，每个 bucket 内部的 groups 已按时间倒序排好。
+   * 空数组时显示空态。
+   */
+  buckets: { id: string | number; groups: DataSourceHistoryGroup[] }[];
+  /** 共享的折叠状态表（key -> 是否展开），由顶层 panel 统一维护。本 tab 使用 `ds-${id}-${idx}` 作为 key。 */
+  expanded: Record<string, boolean>;
+}>();
+
+defineEmits<{
+  /** 透传子组件 Bucket 的 toggle 事件给上层 panel，由其更新 expanded。 */
+  (_e: 'toggle', _key: string): void;
+  /** 透传 Bucket 的 goto 事件，携带 dataSource id 与目标 step 索引。 */
+  (_e: 'goto', _dataSourceId: string | number, _index: number): void;
+  /** 透传 Bucket 的 goto-initial 事件，携带 dataSource id（回到该数据源未修改时的状态）。 */
+  (_e: 'goto-initial', _dataSourceId: string | number): void;
+  /** 透传 Bucket 的 diff-step 事件，携带 dataSource id 与 step 索引。 */
+  (_e: 'diff-step', _dataSourceId: string | number, _index: number): void;
+  /** 透传 Bucket 的 revert-step 事件，携带 dataSource id 与 step 索引（类 git revert）。 */
+  (_e: 'revert-step', _dataSourceId: string | number, _index: number): void;
+}>();
+
+/** 仅 update（前后 schema 都存在）时可查看差异。 */
+const isDataSourceStepDiffable = (step: DataSourceStepValue) => Boolean(step.oldSchema && step.newSchema);
+</script>

package/src/layouts/history-list/GroupRow.vue

@@ -0,0 +1,207 @@
+<template>
+  <li
+    class="m-editor-history-list-item m-editor-history-list-group"
+    :class="{ 'is-undone': !applied, 'is-merged': merged, 'is-current': isCurrent }"
+  >
+    <div
+      class="m-editor-history-list-group-head"
+      :class="{ 'is-clickable': isHeadClickable }"
+      :title="headTitle"
+      @click="onHeadClick"
+    >
+      <span class="m-editor-history-list-item-index" :title="headIndexTitle">{{ headIndexLabel }}</span>
+      <span class="m-editor-history-list-item-op" :class="`op-${opType}`">{{ opLabel(opType) }}</span>
+      <span class="m-editor-history-list-item-desc">{{ desc }}</span>
+      <span v-if="isCurrent" class="m-editor-history-list-item-current">当前</span>
+      <span
+        v-if="!merged && headDiffable"
+        class="m-editor-history-list-item-diff"
+        title="查看修改差异"
+        @click.stop="onDiffClick(subSteps[0].index)"
+        >查看差异</span
+      >
+      <span v-if="merged" class="m-editor-history-list-item-merge">合并 {{ stepCount }} 步</span>
+      <span
+        v-if="!merged && headRevertable"
+        class="m-editor-history-list-item-revert"
+        title="将该步骤的修改作为一次新操作反向应用（不影响后续历史）"
+        @click.stop="onRevertClick(subSteps[0].index)"
+        >回滚</span
+      >
+      <span v-if="merged" class="m-editor-history-list-group-toggle" :class="{ 'is-expanded': expanded }">▾</span>
+    </div>
+
+    <ul v-if="merged && expanded" class="m-editor-history-list-substeps">
+      <li
+        v-for="s in subStepsDisplay"
+        :key="s.index"
+        :class="{ 'is-undone': !s.applied, 'is-current': s.isCurrent, 'is-clickable': !s.isCurrent }"
+        :title="s.isCurrent ? '当前所在记录' : '点击跳转到该记录'"
+        @click="onSubStepClick(s)"
+      >
+        <span class="m-editor-history-list-item-index">#{{ s.index + 1 }}</span>
+        <span class="m-editor-history-list-substep-desc">{{ s.desc }}</span>
+        <span v-if="s.isCurrent" class="m-editor-history-list-item-current">当前</span>
+        <span
+          v-if="s.diffable"
+          class="m-editor-history-list-item-diff"
+          title="查看修改差异"
+          @click.stop="onDiffClick(s.index)"
+          >查看差异</span
+        >
+        <span
+          v-if="s.revertable"
+          class="m-editor-history-list-item-revert"
+          title="将该步骤的修改作为一次新操作反向应用（不影响后续历史）"
+          @click.stop="onRevertClick(s.index)"
+          >回滚</span
+        >
+      </li>
+    </ul>
+  </li>
+</template>
+
+<script lang="ts" setup>
+import { computed } from 'vue';
+
+import type { HistoryOpType } from '@editor/type';
+
+import { opLabel } from './composables';
+
+defineOptions({
+  name: 'MEditorHistoryListGroupRow',
+});
+
+const props = defineProps<{
+  /** 唯一标识当前组的 key，作为 toggle 事件的 payload 回传给上层。形如 `pg-${idx}` / `ds-${id}-${idx}` / `cb-${id}-${idx}`。 */
+  groupKey: string;
+  /** 该组当前是否处于已应用状态（false 表示已被 undo 撤销，UI 会显示为灰态）。 */
+  applied: boolean;
+  /** 是否为合并组（即组内 step 数大于 1，由多次连续操作合并而来）。决定是否展示合并标记与可展开的子步列表。 */
+  merged: boolean;
+  /** 操作类型：`add` / `remove` / `update`，用于决定操作徽标的颜色和文案。 */
+  opType: HistoryOpType;
+  /** 组的整体描述文案，由上层根据 step / group 计算后传入，例如 "修改 button · style.color"。 */
+  desc: string;
+  /** 组内的 step 总数，仅在 merged 为 true 时显示为 "合并 N 步"。 */
+  stepCount: number;
+  /** 子步列表，用于在展开状态下逐条展示每个 step 的索引、应用状态与描述文案。 */
+  subSteps: {
+    index: number;
+    applied: boolean;
+    desc: string;
+    isCurrent?: boolean;
+    diffable?: boolean;
+    /** 是否可对该子步执行「回滚」（已应用 + 业务侧确认支持反向）。父级根据 step 与 applied 决定。 */
+    revertable?: boolean;
+  }[];
+  /** 当前组是否处于展开状态。仅在 merged 为 true 时生效，控制子步列表是否渲染。 */
+  expanded: boolean;
+  /** 是否为当前所在的分组（包含栈中最近一次已应用步骤的那一组），UI 高亮展示。 */
+  isCurrent?: boolean;
+}>();
+
+const emit = defineEmits<{
+  /**
+   * 用户点击合并组头部时触发，携带 groupKey；上层用其切换 expanded 状态。
+   * 对单步组（非合并）头部点击不会发该事件——因为单步组没有"展开"的概念。
+   */
+  (_e: 'toggle', _key: string): void;
+  /**
+   * 用户希望跳转到该记录时触发，携带"目标 step 在所属栈中的索引"——上层据此计算目标 cursor (= index + 1)。
+   * 触发场景：
+   * - 单步组（merged=false）头部：取该唯一 step 的 index；
+   * - 子步条目：取该子步的 index。
+   * 合并组头部不再触发 goto，避免与展开/收起冲突；用户应展开后点具体子步精准跳转。
+   * 当前所在的步骤（isCurrent）始终不会触发 goto。
+   */
+  (_e: 'goto', _index: number): void;
+  /**
+   * 用户希望查看该 step 的修改差异（旧值 vs 新值）。
+   * 只在 step 满足"前后值都存在"（如 update / 数据源、代码块的 update）时由父级标记 `diffable=true`。
+   * payload 为该 step 在所属栈中的索引，由上层根据 index 取 step 内容并展示对比。
+   */
+  (_e: 'diff-step', _index: number): void;
+  /**
+   * 用户希望「回滚」该 step——把它的修改作为一次新操作反向应用（类 git revert）。
+   * payload 为该 step 在所属栈中的索引。仅在单步组头部（headRevertable）或合并组的可回滚子步上触发。
+   */
+  (_e: 'revert-step', _index: number): void;
+}>();
+
+/** 单步组：头部可点击 goto；合并组：头部可点击切换展开。当前组（isCurrent）的单步组头部不可点击。 */
+const isHeadClickable = computed(() => {
+  if (props.merged) return true;
+  return !props.isCurrent;
+});
+
+const headTitle = computed(() => {
+  if (props.merged) return props.expanded ? '点击收起子步' : '点击展开子步';
+  if (props.isCurrent) return '当前所在记录';
+  return '点击跳转到该记录';
+});
+
+/**
+ * 头部点击行为分流：
+ * - 合并组：仅切换展开 / 收起，不触发 goto；
+ * - 单步组：跳转到该唯一步骤；当前组忽略点击。
+ */
+const onHeadClick = () => {
+  if (props.merged) {
+    emit('toggle', props.groupKey);
+    return;
+  }
+  if (props.isCurrent) return;
+  if (!props.subSteps.length) return;
+  emit('goto', props.subSteps[0].index);
+};
+
+const onSubStepClick = (s: { index: number; isCurrent?: boolean }) => {
+  if (s.isCurrent) return;
+  emit('goto', s.index);
+};
+
+/** 单步组头部是否展示"查看差异"入口：要求该唯一子步本身可对比。 */
+const headDiffable = computed(() => !props.merged && Boolean(props.subSteps[0]?.diffable));
+
+/** 单步组头部是否展示"回滚"入口：要求该唯一子步本身可回滚（已应用）。 */
+const headRevertable = computed(() => !props.merged && Boolean(props.subSteps[0]?.revertable));
+
+/**
+ * 合并组展开后的子步渲染顺序：与外层分组列表保持一致——倒序展示（最新的子步在最上方）。
+ * 外层 page tab / bucket 都已对 groups 做了 reverse，子步沿用同样的视觉规则更直观。
+ * 注意：仅用于渲染，原 `subSteps` 保持时间正序，`headIndexLabel` 等基于首尾索引的展示语义不变。
+ */
+const subStepsDisplay = computed(() => props.subSteps.slice().reverse());
+
+/**
+ * 头部索引展示：
+ * - 单步组（merged=false）：显示该唯一 step 的编号，如 `#5`；
+ * - 合并组：显示组内 step 的编号范围，如 `#3-#7`（首尾相同则退化为 `#5`）。
+ *
+ * 这里展示的是 step.index + 1（与子步列表 `#{{ s.index + 1 }}` 保持一致），从 1 起编号更符合直觉。
+ */
+const headIndexLabel = computed(() => {
+  const list = props.subSteps;
+  if (!list.length) return '';
+  const first = list[0].index + 1;
+  const last = list[list.length - 1].index + 1;
+  if (!props.merged || first === last) return `#${first}`;
+  return `#${first}-#${last}`;
+});
+
+const headIndexTitle = computed(() => {
+  if (!props.merged) return `历史步骤编号 #${props.subSteps[0]?.index + 1}`;
+  return `合并了第 ${props.subSteps[0]?.index + 1} 至第 ${
+    props.subSteps[props.subSteps.length - 1]?.index + 1
+  } 共 ${props.subSteps.length} 条历史步骤`;
+});
+
+const onDiffClick = (index: number) => {
+  emit('diff-step', index);
+};
+
+const onRevertClick = (index: number) => {
+  emit('revert-step', index);
+};
+</script>