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

package/src/fields/DataSourceFields.vue

@@ -1,8 +1,8 @@
 <template>
   <div class="m-editor-data-source-fields">
-    <MagicTable :data="model[name]" :columns="fieldColumns" :border="true"></MagicTable>
+    <MagicTable :data="model[name]" :columns="displayColumns" :border="true"></MagicTable>
 
-    <div class="m-editor-data-source-fields-footer">
+    <div v-if="!isCompare" class="m-editor-data-source-fields-footer">
       <TMagicButton size="small" :disabled="disabled" plain @click="newFromJsonHandler()">快速添加</TMagicButton>
       <TMagicButton size="small" type="primary" :disabled="disabled" plain @click="newHandler()">添加</TMagicButton>
     </div>
@@ -47,7 +47,7 @@
 </template>
 
 <script setup lang="ts">
-import { inject, Ref, ref } from 'vue';
+import { computed, inject, Ref, ref } from 'vue';
 
 import type { DataSchema } from '@tmagic/core';
 import { TMagicButton, tMagicMessage, tMagicMessageBox } from '@tmagic/design';
@@ -84,6 +84,10 @@ const emit = defineEmits<{
 }>();
 
 const { uiService } = useServices();
+const mForm = inject<FormState | undefined>('mForm');
+
+/** 对比模式下隐藏新增/编辑/删除等操作按钮，仅保留只读展示。 */
+const isCompare = computed(() => Boolean(mForm?.isCompare));
 
 const fieldValues = ref<Record<string, any>>({});
 const fieldTitle = ref('');
@@ -176,6 +180,11 @@ const fieldColumns: ColumnConfig[] = [
   },
 ];
 
+/** 对比模式下移除「操作」列（编辑/删除按钮），仅保留只读列。 */
+const displayColumns = computed<ColumnConfig[]>(() =>
+  isCompare.value ? fieldColumns.filter((col) => !col.actions) : fieldColumns,
+);
+
 const dataSourceFieldsConfig: FormConfig = [
   { name: 'index', type: 'hidden', filter: 'number', defaultValue: -1 },
   {

package/src/fields/DataSourceMethodSelect.vue

@@ -13,7 +13,7 @@
       ></MCascader>
 
       <TMagicTooltip
-        v-if="model[name] && isCustomMethod && hasDataSourceSidePanel"
+        v-if="model[name] && isCustomMethod && hasDataSourceSidePanel && !isCompare"
         :content="notEditable ? '查看' : '编辑'"
       >
         <TMagicButton class="m-fields-select-action-button" :size="size" @click="editCodeHandler">
@@ -81,6 +81,9 @@ const hasDataSourceSidePanel = computed(() =>
 
 const notEditable = computed(() => filterFunction(mForm, props.config.notEditable, props));
 
+/** 对比模式下隐藏查看/编辑操作按钮，仅保留只读展示。 */
+const isCompare = computed(() => Boolean(mForm?.isCompare));
+
 const dataSources = computed(() => dataSourceService.get('dataSources'));
 
 const isCustomMethod = computed(() => {

package/src/fields/DataSourceMethods.vue

@@ -1,8 +1,8 @@
 <template>
   <div class="m-editor-data-source-methods">
-    <MagicTable :data="model[name]" :columns="methodColumns" :border="true"></MagicTable>
+    <MagicTable :data="model[name]" :columns="displayColumns" :border="true"></MagicTable>
 
-    <div class="m-editor-data-source-methods-footer">
+    <div v-if="!isCompare" class="m-editor-data-source-methods-footer">
       <TMagicButton size="small" type="primary" :disabled="disabled" plain @click="createCodeHandler"
         >添加</TMagicButton
       >
@@ -21,12 +21,12 @@
 </template>
 
 <script setup lang="ts">
-import { nextTick, ref, useTemplateRef } from 'vue';
+import { computed, inject, nextTick, ref, useTemplateRef } from 'vue';
 import { cloneDeep } from 'lodash-es';
 
 import type { CodeBlockContent } from '@tmagic/core';
 import { TMagicButton, tMagicMessageBox } from '@tmagic/design';
-import type { ContainerChangeEventData, DataSourceMethodsConfig, FieldProps } from '@tmagic/form';
+import type { ContainerChangeEventData, DataSourceMethodsConfig, FieldProps, FormState } from '@tmagic/form';
 import { type ColumnConfig, MagicTable } from '@tmagic/table';
 
 import CodeBlockEditor from '@editor/components/CodeBlockEditor.vue';
@@ -42,6 +42,11 @@ const props = withDefaults(defineProps<FieldProps<DataSourceMethodsConfig>>(), {
 
 const emit = defineEmits(['change']);
 
+const mForm = inject<FormState | undefined>('mForm');
+
+/** 对比模式下隐藏新增/编辑/删除等操作按钮，仅保留只读展示。 */
+const isCompare = computed(() => Boolean(mForm?.isCompare));
+
 const codeConfig = ref<Omit<CodeBlockContent, 'content'> & { content: string }>();
 const codeBlockEditorRef = useTemplateRef<InstanceType<typeof CodeBlockEditor>>('codeBlockEditor');
 
@@ -107,6 +112,11 @@ const methodColumns: ColumnConfig[] = [
   },
 ];
 
+/** 对比模式下移除「操作」列（编辑/删除按钮），仅保留只读列。 */
+const displayColumns = computed<ColumnConfig[]>(() =>
+  isCompare.value ? methodColumns.filter((col) => !col.actions) : methodColumns,
+);
+
 const createCodeHandler = () => {
   codeConfig.value = {
     name: '',

package/src/fields/DataSourceMocks.vue

@@ -1,8 +1,8 @@
 <template>
   <div class="m-editor-data-source-fields">
-    <MagicTable :data="model[name]" :columns="columns"></MagicTable>
+    <MagicTable :data="model[name]" :columns="displayColumns"></MagicTable>
 
-    <div class="m-editor-data-source-fields-footer">
+    <div v-if="!isCompare" class="m-editor-data-source-fields-footer">
       <TMagicButton size="small" type="primary" :disabled="disabled" plain @click="newHandler()">添加</TMagicButton>
     </div>
 
@@ -28,7 +28,7 @@
 </template>
 
 <script setup lang="ts">
-import { inject, Ref, ref } from 'vue';
+import { computed, inject, Ref, ref } from 'vue';
 
 import type { MockSchema } from '@tmagic/core';
 import { TMagicButton, tMagicMessageBox, TMagicSwitch } from '@tmagic/design';
@@ -54,6 +54,11 @@ const props = withDefaults(defineProps<FieldProps<DataSourceMocksConfig>>(), {
 const emit = defineEmits(['change']);
 
 const { uiService } = useServices();
+const mForm = inject<FormState | undefined>('mForm');
+
+/** 对比模式下隐藏新增/编辑/删除等操作按钮，仅保留只读展示。 */
+const isCompare = computed(() => Boolean(mForm?.isCompare));
+
 const width = defineModel<number>('width', { default: 670 });
 
 const drawerTitle = ref('');
@@ -202,6 +207,11 @@ const columns: ColumnConfig[] = [
   },
 ];
 
+/** 对比模式下移除「操作」列（编辑/删除按钮），仅保留只读列。 */
+const displayColumns = computed<ColumnConfig[]>(() =>
+  isCompare.value ? columns.filter((col) => !col.actions) : columns,
+);
+
 const newHandler = () => {
   const isFirstRow = props.model[props.name].length === 0;
   formValues.value = {

package/src/fields/DataSourceSelect.vue

@@ -11,7 +11,7 @@
       @change="changeHandler"
     ></MSelect>
 
-    <TMagicTooltip v-if="model[name] && hasDataSourceSidePanel" :content="notEditable ? '查看' : '编辑'">
+    <TMagicTooltip v-if="model[name] && hasDataSourceSidePanel && !isCompare" :content="notEditable ? '查看' : '编辑'">
       <TMagicButton class="m-fields-select-action-button" :size="size" @click="editHandler"
         ><MIcon :icon="!notEditable ? Edit : View"></MIcon
       ></TMagicButton>
@@ -56,6 +56,9 @@ const dataSources = computed(() => dataSourceService.get('dataSources'));
 
 const notEditable = computed(() => filterFunction(mForm, props.config.notEditable, props));
 
+/** 对比模式下隐藏查看/编辑操作按钮，仅保留只读展示。 */
+const isCompare = computed(() => Boolean(mForm?.isCompare));
+
 const hasDataSourceSidePanel = computed(() =>
   uiService.get('sideBarItems').find((item) => item.$key === SideItemKey.DATA_SOURCE),
 );

package/src/fields/EventSelect.vue

@@ -6,22 +6,32 @@
       :size="size"
       :disabled="disabled"
       :model="model"
+      :last-values="lastValues"
+      :is-compare="isCompareMode"
       :config="tableConfig"
       @change="onChangeHandler"
     ></MTable>
 
     <div v-else class="fullWidth">
-      <TMagicButton class="create-button" type="primary" :size="size" :disabled="disabled" @click="addEvent()"
+      <TMagicButton
+        v-if="!isCompareMode"
+        class="create-button"
+        type="primary"
+        :size="size"
+        :disabled="disabled"
+        @click="addEvent()"
         >添加事件</TMagicButton
       >
       <MPanel
-        v-for="(cardItem, index) in model[name]"
-        :key="index"
+        v-for="entry in displayList"
+        :key="entry.index"
         :disabled="disabled"
         :size="size"
-        :prop="`${prop}.${index}`"
+        :prop="`${prop}.${entry.index}`"
         :config="actionsConfig"
-        :model="cardItem"
+        :model="entry.cardItem"
+        :last-values="entry.lastCardItem"
+        :is-compare="isCompareMode"
         :label-width="config.labelWidth || '100px'"
         @change="onChangeHandler"
       >
@@ -29,19 +39,22 @@
           <MFormContainer
             class="fullWidth"
             :config="eventNameConfig"
-            :model="cardItem"
+            :model="entry.cardItem"
+            :last-values="entry.lastCardItem"
+            :is-compare="isCompareMode"
             :disabled="disabled"
             :size="size"
-            :prop="`${prop}.${index}`"
+            :prop="`${prop}.${entry.index}`"
             @change="eventNameChangeHandler"
           ></MFormContainer>
           <TMagicButton
+            v-if="!isCompareMode"
             style="color: #f56c6c"
             link
             :icon="Delete"
             :disabled="disabled"
             :size="size"
-            @click="removeEvent(Number(index))"
+            @click="removeEvent(Number(entry.index))"
           ></TMagicButton>
         </template>
       </MPanel>
@@ -374,6 +387,42 @@ const isOldVersion = computed(() => {
   return !has(props.model[props.name][0], 'actions');
 });
 
+/**
+ * 对比模式判定：
+ *
+ * event-select 内部由「事件列表 + 嵌套子表单」组成，属于复合字段。父级 `MFormContainer` 已将其
+ * 归入「自接管对比字段」（见 Container.vue 的 `SELF_DIFF_FIELD_TYPES`），即对比时只渲染一次本组件，
+ * 并把当前值 `model` 与历史值 `lastValues` 一并传入，由本组件把 `is-compare`/`lastValues` 透传给
+ * 内部的 MPanel / MFormContainer，逐项（事件名、动作）展示前后差异。
+ *
+ * 仅当存在历史值时才启用对比，避免 lastValues 缺失时退化为「全部新增」的空对比。
+ */
+const isCompareMode = computed(() => Boolean(props.isCompare && props.lastValues));
+
+/**
+ * 待渲染的事件卡片列表。
+ *
+ * - 非对比模式：直接映射当前事件列表，`lastCardItem` 为空；
+ * - 对比模式：按索引对齐当前值与历史值，取两者长度的最大值，使得「新增」（仅当前有）与
+ *   「删除」（仅历史有）的事件都能被渲染出来；缺失的一侧用空对象兜底，从而让子级正确高亮差异。
+ */
+const displayList = computed<{ cardItem: any; lastCardItem: any; index: number }[]>(() => {
+  const current = props.model[props.name] || [];
+
+  if (!isCompareMode.value) {
+    return current.map((cardItem: any, index: number) => ({ cardItem, lastCardItem: undefined, index }));
+  }
+
+  const last = props.lastValues?.[props.name] || [];
+  const length = Math.max(current.length, last.length);
+
+  return Array.from({ length }, (_, index) => ({
+    cardItem: current[index] ?? {},
+    lastCardItem: last[index] ?? {},
+    index,
+  }));
+});
+
 // 添加事件
 const addEvent = () => {
   const defaultEvent = {

package/src/fields/KeyValue.vue

@@ -19,6 +19,7 @@
         ></TMagicInput>
 
         <TMagicButton
+          v-if="!isCompare"
           class="m-fields-key-value-delete"
           type="danger"
           :size="size"
@@ -30,7 +31,14 @@
         ></TMagicButton>
       </div>
 
-      <TMagicButton type="primary" :size="size" :disabled="disabled" plain :icon="Plus" @click="addHandler"
+      <TMagicButton
+        v-if="!isCompare"
+        type="primary"
+        :size="size"
+        :disabled="disabled"
+        plain
+        :icon="Plus"
+        @click="addHandler"
         >添加</TMagicButton
       >
     </div>
@@ -52,7 +60,7 @@
     ></MagicCodeEditor>
 
     <TMagicButton
-      v-if="config.advanced"
+      v-if="config.advanced && !isCompare"
       size="default"
       :disabled="disabled"
       link
@@ -63,11 +71,11 @@
 </template>
 
 <script setup lang="ts">
-import { ref, watchEffect } from 'vue';
+import { computed, inject, ref, watchEffect } from 'vue';
 import { Delete, Plus } from '@element-plus/icons-vue';
 
 import { TMagicButton, TMagicInput } from '@tmagic/design';
-import type { FieldProps, KeyValueConfig } from '@tmagic/form';
+import type { FieldProps, FormState, KeyValueConfig } from '@tmagic/form';
 
 import CodeIcon from '@editor/icons/CodeIcon.vue';
 import MagicCodeEditor from '@editor/layouts/CodeEditor.vue';
@@ -84,6 +92,11 @@ const emit = defineEmits<{
   change: [value: Record<string, any>];
 }>();
 
+const mForm = inject<FormState | undefined>('mForm');
+
+/** 对比模式下隐藏增删/代码切换等操作按钮，仅保留只读展示。 */
+const isCompare = computed(() => Boolean(mForm?.isCompare));
+
 const records = ref<[string, string][]>([]);
 const showCode = ref(false);
 

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>