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

package/package.json

@@ -1,5 +1,5 @@
 {
-  "version": "1.8.0-beta.2",
+  "version": "1.8.0-beta.4",
   "name": "@tmagic/editor",
   "type": "module",
   "sideEffects": [
@@ -58,11 +58,11 @@
     "moveable": "^0.53.0",
     "serialize-javascript": "^7.0.0",
     "sortablejs": "^1.15.6",
-    "@tmagic/design": "1.8.0-beta.2",
-    "@tmagic/table": "1.8.0-beta.2",
-    "@tmagic/utils": "1.8.0-beta.2",
-    "@tmagic/form": "1.8.0-beta.2",
-    "@tmagic/stage": "1.8.0-beta.2"
+    "@tmagic/design": "1.8.0-beta.4",
+    "@tmagic/form": "1.8.0-beta.4",
+    "@tmagic/stage": "1.8.0-beta.4",
+    "@tmagic/table": "1.8.0-beta.4",
+    "@tmagic/utils": "1.8.0-beta.4"
   },
   "devDependencies": {
     "@types/events": "^3.0.3",
@@ -76,7 +76,7 @@
     "type-fest": "^5.2.0",
     "typescript": "^6.0.3",
     "vue": "^3.5.34",
-    "@tmagic/core": "1.8.0-beta.2"
+    "@tmagic/core": "1.8.0-beta.4"
   },
   "peerDependenciesMeta": {
     "typescript": {

package/src/Editor.vue

@@ -221,6 +221,7 @@ const stageOptions: StageOptions = {
   guidesOptions: props.guidesOptions,
   disabledMultiSelect: props.disabledMultiSelect,
   alwaysMultiSelect: props.alwaysMultiSelect,
+  disabledFlashTip: props.disabledFlashTip,
   beforeDblclick: props.beforeDblclick,
 };
 
@@ -237,6 +238,13 @@ provide('stageOptions', stageOptions);
  */
 provide('extendFormState', props.extendFormState);
 
+/**
+ * 把历史记录面板的自定义扩展 tab 提供给深层的 HistoryListPanel（它挂在 NavMenu 中，
+ * 以 markRaw component 形式渲染，无法直接通过 props 透传）。业务方可借此在历史记录
+ * 面板内追加自定义模块的历史 tab。
+ */
+provide('historyListExtraTabs', props.historyListExtraTabs);
+
 provide<EventBus>('eventBus', new EventEmitter());
 
 const propsPanelMountedHandler = (e: InstanceType<typeof FormPanel>) => {

package/src/components/CompareForm.vue

@@ -24,20 +24,13 @@ import { type CodeBlockContent, type DataSourceSchema, HookType, type MNode } fr
 import { type FormConfig, type FormState, type FormValue, MForm } from '@tmagic/form';
 
 import { useServices } from '@editor/hooks/use-services';
+import type { CompareCategory, CompareFormLoadConfig } from '@editor/type';
 import { getCodeBlockFormConfig } from '@editor/utils/code-block';
 
 defineOptions({
   name: 'MEditorCompareForm',
 });
 
-/**
- * 对比类型：
- * - node: 节点组件，按 `type` 从 propsService 获取属性表单配置
- * - data-source: 数据源，按 `type`(base/http/...) 从 dataSourceService 获取数据源表单配置
- * - code-block: 数据源代码块，使用内置的代码块表单配置
- */
-export type CompareCategory = 'node' | 'data-source' | 'code-block';
-
 const props = withDefaults(
   defineProps<{
     /** 当前值（修改后的值） */
@@ -68,6 +61,12 @@ const props = withDefaults(
      * 因此在差异对比场景下也需要透传，避免出现 `formState.xxx is undefined` 的运行时错误。
      */
     extendState?: (_state: FormState) => Record<string, any> | Promise<Record<string, any>>;
+    /**
+     * 自定义 FormConfig 加载逻辑。传入后将接管内置的按 `category`(node/data-source/code-block)
+     * 取配置逻辑，调用方可根据业务自行返回（或异步返回）表单配置。可通过
+     * `ctx.defaultLoadConfig()` 复用默认结果再做二次加工。返回的 config 直接用于对比展示。
+     */
+    loadConfig?: CompareFormLoadConfig;
   }>(),
   {
     category: 'node',
@@ -153,22 +152,41 @@ const showDiff = ({ curValue, lastValue, config }: { curValue: any; lastValue: a
   return !isEqual(curValue, lastValue);
 };
 
-const loadConfig = async () => {
+const removeStyleDisplayConfig = (formConfig: FormConfig): FormConfig =>
+  formConfig.map((item) => {
+    if (!('type' in item)) return item;
+    if (item?.type !== 'tab' || !Array.isArray(item.items)) return item;
+
+    return {
+      ...item,
+      items: item.items.map((tabPane) => {
+        if (tabPane?.title !== '样式' || !Array.isArray(tabPane.items)) return tabPane;
+
+        return {
+          ...tabPane,
+          display: true,
+        };
+      }),
+    };
+  });
+
+/**
+ * 内置的默认 FormConfig 加载逻辑：按 `category` 从对应 service / 工具取配置。
+ * 作为 ctx.defaultLoadConfig 透传给自定义 `loadConfig`，方便复用与二次加工。
+ */
+const defaultLoadConfig = async (): Promise<FormConfig> => {
   switch (props.category) {
     case 'node': {
       if (!props.type) {
-        config.value = [];
-        return;
+        return [];
       }
-      config.value = await propsService.getPropsConfig(props.type);
-      break;
+      return removeStyleDisplayConfig(await propsService.getPropsConfig(props.type));
     }
     case 'data-source': {
-      config.value = dataSourceService.getFormConfig(props.type || 'base');
-      break;
+      return dataSourceService.getFormConfig(props.type || 'base');
     }
     case 'code-block': {
-      config.value = getCodeBlockFormConfig({
+      return getCodeBlockFormConfig({
         paramColConfig: codeBlockService.getParamsColConfig(),
         // 通过传入 dataSourceType 间接表达"是数据源代码块"——在对比场景下 props.dataSourceType
         // 由调用方按 step 上下文显式传入，未传则视为普通代码块，「执行时机」字段隐藏。
@@ -178,15 +196,28 @@ const loadConfig = async () => {
         // 对比模式只读，不需要校验/语法检查
         editable: false,
       });
-      break;
     }
     default:
-      config.value = [];
+      return [];
+  }
+};
+
+const loadConfig = async () => {
+  if (props.loadConfig) {
+    config.value = await props.loadConfig({
+      category: props.category,
+      type: props.type,
+      dataSourceType: props.dataSourceType,
+      defaultLoadConfig,
+    });
+    return;
   }
+
+  config.value = await defaultLoadConfig();
 };
 
 watch(
-  [() => props.category, () => props.type, () => props.dataSourceType],
+  [() => props.category, () => props.type, () => props.dataSourceType, () => props.loadConfig],
   () => {
     loadConfig();
   },

package/src/editorProps.ts

@@ -15,6 +15,7 @@ import type {
   ComponentGroup,
   CustomContentMenuFunction,
   DatasourceTypeOption,
+  HistoryListExtraTab,
   IsExpandableFunction,
   MenuBarData,
   MenuButton,
@@ -86,6 +87,8 @@ export interface EditorProps {
   alwaysMultiSelect?: boolean;
   /** 禁用页面片 */
   disabledPageFragment?: boolean;
+  /** 禁用「非点击画布选中组件时（如从图层树、面包屑等外部选中），对选中区域做高亮闪烁提示」，默认 false（即默认开启闪烁） */
+  disabledFlashTip?: boolean;
   /** 禁用双击在浮层中单独编辑选中组件 */
   disabledStageOverlay?: boolean;
   /** 禁用属性配置面板右下角显示源码的按钮 */
@@ -125,6 +128,8 @@ export interface EditorProps {
   /** 组件树节点双击前的钩子函数，返回 false 则阻止默认的双击行为 */
   beforeLayerNodeDblclick?: (event: MouseEvent, data: TreeNodeData) => Promise<boolean | void> | boolean | void;
   extendFormState?: (state: FormState) => Record<string, any> | Promise<Record<string, any>>;
+  /** 历史记录面板的自定义扩展 tab，追加在内置的页面/数据源/代码块 tab 之后 */
+  historyListExtraTabs?: HistoryListExtraTab[];
   /** 页面顺序拖拽配置参数 */
   pageBarSortOptions?: PageBarSortOptions;
   /** 页面搜索函数 */
@@ -136,6 +141,7 @@ export const defaultEditorProps = {
   disabledMultiSelect: false,
   alwaysMultiSelect: false,
   disabledPageFragment: false,
+  disabledFlashTip: false,
   disabledStageOverlay: false,
   containerHighlightClassName: CONTAINER_HIGHLIGHT_CLASS_NAME,
   containerHighlightDuration: 800,
@@ -145,6 +151,7 @@ export const defaultEditorProps = {
   disabledCodeBlock: false,
   componentGroupList: () => [],
   datasourceList: () => [],
+  historyListExtraTabs: () => [],
   menu: () => ({ left: [], right: [] }),
   layerContentMenu: () => [],
   stageContentMenu: () => [],

package/src/fields/CodeLink.vue

@@ -4,11 +4,11 @@
 
 <script lang="ts" setup>
 import { computed, reactive, watch } from 'vue';
-import serialize from 'serialize-javascript';
 
 import type { CodeLinkConfig, FieldProps, MLink } from '@tmagic/form';
 
 import { getEditorConfig } from '@editor/utils/config';
+import { serializeConfig } from '@editor/utils/editor';
 
 defineOptions({
   name: 'MFieldsCodeLink',
@@ -47,10 +47,7 @@ watch(
   () => props.model[props.name],
   (value) => {
     modelValue.form = {
-      [props.name]: serialize(value, {
-        space: 2,
-        unsafe: true,
-      }).replace(/"(\w+)":\s/g, '$1: '),
+      [props.name]: serializeConfig(value),
     };
   },
   {

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

@@ -6,7 +6,7 @@ import { tMagicMessage } from '@tmagic/design';
 import type { ContainerChangeEventData } from '@tmagic/form';
 
 import CodeBlockEditor from '@editor/components/CodeBlockEditor.vue';
-import type { Services } from '@editor/type';
+import type { HistoryOpSource, Services } from '@editor/type';
 
 export const useCodeBlockEdit = (codeBlockService: Services['codeBlockService']) => {
   const codeConfig = ref<Omit<CodeBlockContent, 'content'> & { content: string }>();
@@ -58,8 +58,8 @@ export const useCodeBlockEdit = (codeBlockService: Services['codeBlockService'])
   };
 
   // 删除代码块
-  const deleteCode = async (key: string) => {
-    codeBlockService.deleteCodeDslByIds([key]);
+  const deleteCode = async (key: string, { historySource }: { historySource?: HistoryOpSource } = {}) => {
+    codeBlockService.deleteCodeDslByIds([key], { historySource });
   };
 
   const submitCodeBlockHandler = async (values: CodeBlockContent, eventData?: ContainerChangeEventData) => {
@@ -67,6 +67,7 @@ export const useCodeBlockEdit = (codeBlockService: Services['codeBlockService'])
 
     await codeBlockService.setCodeDslById(codeId.value, values, {
       changeRecords: eventData?.changeRecords,
+      historySource: 'props',
     });
 
     codeBlockEditorRef.value?.hide();

package/src/hooks/use-data-source-edit.ts

@@ -27,9 +27,9 @@ export const useDataSourceEdit = (dataSourceService: Services['dataSourceService
 
   const submitDataSourceHandler = (value: DataSourceSchema, eventData: ContainerChangeEventData) => {
     if (value.id) {
-      dataSourceService.update(value, { changeRecords: eventData.changeRecords });
+      dataSourceService.update(value, { changeRecords: eventData.changeRecords, historySource: 'props' });
     } else {
-      dataSourceService.add(value);
+      dataSourceService.add(value, { historySource: 'props' });
     }
 
     editDialog.value?.hide();

package/src/hooks/use-stage.ts

@@ -48,6 +48,7 @@ export const useStage = (stageOptions: StageOptions) => {
     disabledMultiSelect: stageOptions.disabledMultiSelect,
     alwaysMultiSelect: stageOptions.alwaysMultiSelect,
     disabledRule: stageOptions.disabledRule,
+    disabledFlashTip: stageOptions.disabledFlashTip,
   });
 
   watch(
@@ -129,16 +130,16 @@ export const useStage = (stageOptions: StageOptions) => {
     });
     if (configs.length === 0) return;
 
-    editorService.update(configs, { changeRecordList });
+    editorService.update(configs, { changeRecordList, historySource: 'stage' });
   });
 
   stage.on('sort', (ev: SortEventData) => {
-    editorService.sort(ev.src, ev.dist);
+    editorService.sort(ev.src, ev.dist, { historySource: 'stage' });
   });
 
   stage.on('remove', (ev: RemoveEventData) => {
     const nodes = ev.data.map(({ el }) => editorService.getNodeById(getIdFromEl()(el) || ''));
-    editorService.remove(nodes.filter((node) => Boolean(node)) as MNode[]);
+    editorService.remove(nodes.filter((node) => Boolean(node)) as MNode[], { historySource: 'stage' });
   });
 
   stage.on('select-parent', () => {

package/src/index.ts

@@ -71,6 +71,8 @@ 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 HistoryListBucket } from './layouts/history-list/Bucket.vue';
+export { default as HistoryDiffDialog } from './layouts/history-list/HistoryDiffDialog.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

@@ -21,12 +21,12 @@ import { computed, nextTick, onBeforeUnmount, onMounted, onUnmounted, ref, useTe
 import { FullScreen } from '@element-plus/icons-vue';
 import { throttle } from 'lodash-es';
 import type * as Monaco from 'monaco-editor';
-import serialize from 'serialize-javascript';
 
 import { TMagicButton } from '@tmagic/design';
 
 import MIcon from '@editor/components/Icon.vue';
 import { getEditorConfig } from '@editor/utils/config';
+import { serializeConfig } from '@editor/utils/editor';
 import loadMonaco from '@editor/utils/monaco-editor';
 
 defineOptions({
@@ -163,10 +163,7 @@ const toString = (v: string | any, language: string): string => {
     if (language === 'json') {
       value = JSON.stringify(v, null, 2);
     } else {
-      value = serialize(v, {
-        space: 2,
-        unsafe: true,
-      }).replace(/"(\w+)":\s/g, '$1: ');
+      value = serializeConfig(v);
     }
   } else {
     value = v;

package/src/layouts/NavMenu.vue

@@ -80,7 +80,7 @@ const getConfig = (item: MenuItem): (MenuButton | MenuComponent)[] => {
         disabled: () => editorService.get('node')?.type === NodeType.PAGE,
         handler: () => {
           const node = editorService.get('node');
-          node && editorService.remove(node);
+          node && editorService.remove(node, { historySource: 'toolbar' });
         },
       });
       break;

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

@@ -8,13 +8,16 @@
 
     <ul class="m-editor-history-list-ul">
       <GroupRow
-        v-for="(group, gIdx) in groups"
-        :key="`${prefix}-${bucketId}-${gIdx}`"
-        :group-key="`${prefix}-${bucketId}-${gIdx}`"
+        v-for="group in groups"
+        :key="`${prefix}-${bucketId}-${group.steps[0]?.index}`"
+        :group-key="`${prefix}-${bucketId}-${group.steps[0]?.index}`"
         :applied="group.applied"
         :merged="group.steps.length > 1"
         :op-type="group.opType"
         :desc="describeGroup(group)"
+        :source="groupSource(group)"
+        :time="formatHistoryTime(groupTimestamp(group))"
+        :time-title="formatHistoryFullTime(groupTimestamp(group))"
         :step-count="group.steps.length"
         :sub-steps="
           group.steps.map((s: any) => ({
@@ -23,11 +26,15 @@
             isCurrent: s.isCurrent,
             desc: describeStep(s.step),
             diffable: isStepDiffable ? isStepDiffable(s.step) : false,
-            revertable: s.applied,
+            revertable: s.applied && (isStepRevertable ? isStepRevertable(s.step) : true),
+            source: s.step.source,
+            time: formatHistoryTime(s.step.timestamp),
+            timeTitle: formatHistoryFullTime(s.step.timestamp),
           }))
         "
         :is-current="group.isCurrent"
-        :expanded="!!expanded[`${prefix}-${bucketId}-${gIdx}`]"
+        :expanded="!!expanded[`${prefix}-${bucketId}-${group.steps[0]?.index}`]"
+        :goto-enabled="gotoEnabled"
         @toggle="(key: string) => $emit('toggle', key)"
         @goto="(index: number) => $emit('goto', bucketId, index)"
         @diff-step="(index: number) => $emit('diff-step', bucketId, index)"
@@ -36,8 +43,14 @@
       <!--
         初始状态项：永远位于该 bucket 列表底部（同样按倒序展示，最底部 = 最早状态）。
         当 bucket 内所有 group 都未 applied 时即为当前位置。
+        showInitial=false 时不展示（用于没有"撤销到初始状态"语义的自定义历史，如业务模块历史）。
       -->
-      <InitialRow :is-current="isInitial" @goto-initial="$emit('goto-initial', bucketId)" />
+      <InitialRow
+        v-if="showInitial !== false"
+        :is-current="isInitial"
+        :goto-enabled="gotoEnabled"
+        @goto-initial="$emit('goto-initial', bucketId)"
+      />
     </ul>
   </div>
 </template>
@@ -47,6 +60,7 @@ import { computed } from 'vue';
 
 import type { HistoryOpType } from '@editor/type';
 
+import { formatHistoryFullTime, formatHistoryTime, groupSource, groupTimestamp } from './composables';
 import GroupRow from './GroupRow.vue';
 import InitialRow from './InitialRow.vue';
 
@@ -54,29 +68,44 @@ 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>;
-}>();
+const props = withDefaults(
+  defineProps<{
+    /** Bucket 标题，例如 "数据源" / "代码块"，渲染在 bucket 头部。 */
+    title: string;
+    /** 当前 bucket 对应的目标 id（dataSource.id 或 codeBlock.id），同时用于组装子项的 key。 */
+    bucketId: string | number;
+    /**
+     * 子项 key 的命名空间前缀：内置 `ds` 表示数据源，`cb` 表示代码块；
+     * 业务方复用 Bucket 时可传入自定义前缀（如 `mod`）。与上层折叠状态 key 保持一致。
+     */
+    prefix: string;
+    /** 是否展示底部「回到初始状态」入口，默认 true。无 undo cursor 语义的自定义历史可传 false 关闭。 */
+    showInitial?: boolean;
+    /** 当前 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;
+    /** 判断某个 step 是否支持回滚（如更新需带 changeRecords）。由父组件按业务类型注入；不传则已应用即可回滚。 */
+    isStepRevertable?: (_step: any) => boolean;
+    /** 共享的折叠状态表（key -> 是否展开），由顶层 panel 统一维护以便跨 tab 复用。 */
+    expanded: Record<string, boolean>;
+    /** 是否支持「跳转到该记录」(goto)。默认 true。 */
+    gotoEnabled?: boolean;
+  }>(),
+  {
+    showInitial: true,
+    gotoEnabled: true,
+  },
+);
 
 defineEmits<{
   /** 透传子组件 GroupRow 的 toggle，由上层 panel 更新 expanded。 */

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

@@ -0,0 +1,80 @@
+<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="`${prefix}-${bucket.id}`"
+      :title="title"
+      :bucket-id="bucket.id"
+      :prefix="prefix"
+      :groups="bucket.groups"
+      :describe-group="describeGroup"
+      :describe-step="describeStep"
+      :is-step-diffable="isStepDiffable"
+      :is-step-revertable="isStepRevertable"
+      :expanded="expanded"
+      :goto-enabled="gotoEnabled"
+      @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 Bucket from './Bucket.vue';
+
+defineOptions({
+  name: 'MEditorHistoryListBucketTab',
+});
+
+withDefaults(
+  defineProps<{
+    /** bucket 头部展示的标题，例如 "数据源" / "代码块"。 */
+    title: string;
+    /** 子项 key 的命名空间前缀（`ds` 数据源 / `cb` 代码块），与上层折叠状态 key 保持一致。 */
+    prefix: string;
+    /**
+     * 已按目标 id 聚拢成的 bucket 列表，每个 bucket 内部的 groups 已按时间倒序排好。
+     * 空数组时显示空态。
+     */
+    buckets: { id: string | number; groups: any[] }[];
+    /** 组级描述文案生成器，由父组件按业务类型注入。 */
+    describeGroup: (_group: any) => string;
+    /** 单步描述文案生成器，由父组件按业务类型注入。 */
+    describeStep: (_step: any) => string;
+    /** 判断某个 step 是否可查看差异（前后值都存在）。由父组件按业务类型注入。 */
+    isStepDiffable: (_step: any) => boolean;
+    /** 判断某个 step 是否支持回滚（如更新需带 changeRecords）。由父组件按业务类型注入；不传则已应用即可回滚。 */
+    isStepRevertable?: (_step: any) => boolean;
+    /**
+     * 共享的折叠状态表（key -> 是否展开），由顶层 panel 统一维护。
+     * 本 tab 使用 `${prefix}-${id}-${组内首步 index}` 作为 key——以稳定的 step 索引而非展示位置标识分组，
+     * 这样历史数据更新后已展开的分组状态仍能正确保持。
+     */
+    expanded: Record<string, boolean>;
+    /** 是否支持「跳转到该记录」(goto)，透传给 Bucket。默认 true。 */
+    gotoEnabled?: boolean;
+  }>(),
+  {
+    gotoEnabled: true,
+  },
+);
+
+defineEmits<{
+  /** 透传子组件 Bucket 的 toggle 事件给上层 panel，由其更新 expanded。 */
+  (_e: 'toggle', _key: string): void;
+  /** 透传 Bucket 的 goto 事件，携带目标 id 与目标 step 索引。 */
+  (_e: 'goto', _targetId: string | number, _index: number): void;
+  /** 透传 Bucket 的 goto-initial 事件，携带目标 id（回到该目标未修改时的状态）。 */
+  (_e: 'goto-initial', _targetId: string | number): void;
+  /** 透传 Bucket 的 diff-step 事件，携带目标 id 与 step 索引。 */
+  (_e: 'diff-step', _targetId: string | number, _index: number): void;
+  /** 透传 Bucket 的 revert-step 事件，携带目标 id 与 step 索引（类 git revert）。 */
+  (_e: 'revert-step', _targetId: string | number, _index: number): void;
+}>();
+</script>