@yuhufe/wtool-vdiff 0.0.7 → 0.0.8

package/README.md

@@ -2,17 +2,18 @@
 
 **Demo**: [https://defghy.github.io/web-toolkits/v-diff/](https://defghy.github.io/web-toolkits/v-diff/)
 
-基于 Monaco 的 DiffViewer。 **框架无关** —— 可直接集成到任何前端项目（React、Vue、原生 JS 等）中。
+基于 Monaco 的框架无关 DiffViewer，可集成到 React、Vue、原生 JS 等前端项目。
 
 ---
 
 ## 特性
 
-- **框架无关** ：通过 Web Component 封装，函数调用即可挂载，无需 Vue 项目
-- **双模式输入** ：支持 `diffPatch`（unified diff 字符串）与 `diffPair`（原始文件对）两种数据格式
-- **自适应高度** ：根据实际变更行数自动计算编辑器高度，避免大量空白
-- **折叠未变更区域** ：默认折叠无差异区域，仅保留变更附近的上下文行
-- **顶部工具栏** ：内置文件名展示、增删行数统计、viewed 标记、raw 展开模式
+- **框架无关** ：通过 Web Component 封装，函数调用即可挂载
+- **双模式输入** ：支持 `diffPatch`（unified diff）和 `diffPair`（文件对）
+- **自适应高度** ：按变更行数计算编辑器高度，减少空白
+- **折叠未变更区域** ：默认折叠无差异区域，保留变更上下文
+- **顶部工具栏** ：提供文件名、增删行统计、viewed 标记和 raw 模式
+- **文件列表 Diff** ：通过文件数组生成可搜索的文件树，支持选择联动和虚拟滚动
 
 ---
 
@@ -28,7 +29,7 @@ pnpm add @yuhufe/wtool-vdiff
 
 ## 快速开始
 
-### 方式一：`diffPatch` 模式（unified diff 字符串）
+### 方式一：`diffPatch`（unified diff）
 
 ```typescript
 import { createDiffViewer } from '@yuhufe/wtool-vdiff'
@@ -44,14 +45,14 @@ const viewer = createDiffViewer(document.getElementById('diff-container')!, {
  export { foo }`,
 })
 
-// 动态更新内容
+// 更新
 viewer.update({ diffPatch: newPatch })
 
 // 销毁
 viewer.destroy()
 ```
 
-### 方式二：`diffPair` 模式（完整文件对）
+### 方式二：`diffPair`（文件对）
 
 ```typescript
 import { createDiffViewer } from '@yuhufe/wtool-vdiff'
@@ -67,9 +68,73 @@ const viewer = createDiffViewer(document.getElementById('diff-container')!, {
 
 ---
 
+## 文件列表 Diff
+
+`createDiffFiles` 展示可搜索的文件树和虚拟滚动 Diff 列表，选择文件时自动滚动并高亮。
+
+```html
+<div id="diff-files-container"></div>
+
+<style>
+  #diff-files-container {
+    width: 100%;
+    height: 560px;
+    overflow: hidden;
+  }
+</style>
+```
+
+```typescript
+import { createDiffFiles, type DiffFile } from '@yuhufe/wtool-vdiff'
+
+const diffFiles: DiffFile[] = [
+  {
+    diffPatch: `--- src/index.ts
++++ src/index.ts
+@@ -1,2 +1,3 @@
+ import { foo } from './foo'
+-export { foo }
++const version = 2
++export { foo, version }`,
+  },
+  {
+    diffPair: [
+      {
+        filename: 'src/utils/sum.ts',
+        content: 'export const sum = (a: number, b: number) => a + b',
+      },
+      {
+        filename: 'src/utils/sum.ts',
+        content: 'export function sum(a: number, b: number) {\n  return a + b\n}',
+      },
+    ],
+  },
+]
+
+const filesViewer = createDiffFiles(document.getElementById('diff-files-container')!, {
+  diffFiles,
+  viewerStyle: { maxHeight: '360px' },
+})
+
+// 销毁
+filesViewer.destroy()
+```
+
+> 组件根据 `fullPath` 构建目录树。外层容器需设置明确高度，且每个文件的最终 `fullPath` 必须唯一。文件内容通过 `diffPatch` 或 `diffPair` 提供。
+
+省略 `fullPath` 时，组件按以下顺序推导文件路径：
+
+1. 显式 `fullPath`
+2. `diffPair` 中修改后文件的 `filename`，其次为原文件
+3. `diffPatch` 的 `+++` 头部
+
+`diffPatch` 中的文件名会原样保留，也可通过 `fullPath` 覆盖。无法确定路径时，组件会抛出带数组下标的 `TypeError`。
+
+---
+
 ## loader 配置
 
-库内部通过 `@monaco-editor/loader` 按需加载 Monaco。默认走 jsDelivr CDN，生产环境建议改为本地 bundle。
+库通过 `@monaco-editor/loader` 按需加载 Monaco。默认使用 jsDelivr CDN，生产环境建议本地加载。
 
 **方式一：自定义 CDN 路径**
 
@@ -81,7 +146,7 @@ loader.config({
 })
 ```
 
-**方式二：从 node_modules 本地加载（Vite 项目推荐）**
+**方式二：本地加载（Vite 推荐）**
 
 ```typescript
 import * as monaco from 'monaco-editor'
@@ -105,7 +170,7 @@ self.MonacoEnvironment = {
 loader.config({ monaco })
 ```
 
-> `loader.config` 必须在任意 `createDiffViewer` 调用之前执行。
+> 请在首次调用 `createDiffViewer` 前配置 `loader`。
 
 ---
 
@@ -113,53 +178,87 @@ loader.config({ monaco })
 
 ### `createDiffViewer(target, props?)`
 
-在目标元素内创建并挂载 diff 查看器，返回 `DiffViewerInstance` 实例。
+挂载 DiffViewer。
 
-| 参数 | 类型 | 必填 | 说明 |
-|------|------|------|------|
-| `target` | `HTMLElement` | ✅ | 挂载目标容器元素 |
-| `props` | `DiffViewerProps` | ❌ | 初始化属性（见下方 Props 说明） |
+| 参数     | 类型              | 必填 | 说明     |
+| -------- | ----------------- | ---- | -------- |
+| `target` | `HTMLElement`     | ✅   | 挂载容器 |
+| `props`  | `DiffViewerProps` | ❌   | 初始属性 |
 
 **返回值：`DiffViewerInstance`**
 
-| 方法 | 签名 | 说明 |
-|------|------|------|
-| `update` | `(props: Partial<DiffViewerProps>) => void` | 动态更新 props |
-| `destroy` | `() => void` | 销毁查看器并从 DOM 移除 |
+| 方法      | 签名                                        | 说明         |
+| --------- | ------------------------------------------- | ------------ |
+| `update`  | `(props: Partial<DiffViewerProps>) => void` | 更新 props   |
+| `destroy` | `() => void`                                | 销毁并从 DOM 移除 |
 
 ---
 
-### Props（`DiffViewerProps`）
+### `createDiffFiles(target, props?)`
 
-| 属性 | 类型 | 默认值 | 说明 |
-|------|------|--------|------|
-| `diffPatch` | `string` | `''` | Unified diff 格式字符串（与 `diffPair` 二选一） |
-| `diffPair` | `{ filename: string; content: string }[]` | `[]` | 原始文件对，数组长度为 2，分别为原始文件与修改后文件（与 `diffPatch` 二选一） |
-| `language` | `string` | `'plaintext'` | Monaco 语言标识，影响语法高亮（如 `'typescript'`、`'python'`） |
-| `options` | `DiffEditorOptions` | `{}` | Monaco `IStandaloneDiffEditorConstructionOptions`，透传给 Monaco 编辑器 |
-| `modelOptions` | `ModelOptions` | `{}` | Monaco `ITextModelUpdateOptions`，透传给文本模型 |
-| `viewerStyle` | `WtoolDiffViewerStyle` | — | 查看器外层样式（宽高） |
+挂载文件列表 Diff。
 
----
+| 参数     | 类型             | 必填 | 说明     |
+| -------- | ---------------- | ---- | -------- |
+| `target` | `HTMLElement`    | ✅   | 挂载容器 |
+| `props`  | `DiffFilesProps` | ❌   | 初始属性 |
 
-### `WtoolDiffViewerStyle`
+**返回值：`DiffFilesInstance`**
+
+| 方法      | 签名                                       | 说明         |
+| --------- | ------------------------------------------ | ------------ |
+| `update`  | `(props: Partial<DiffFilesProps>) => void` | 更新 props   |
+| `destroy` | `() => void`                               | 销毁并从 DOM 移除 |
+
+### `DiffFilesProps`
+
+| 属性          | 类型                   | 默认值 | 说明                  |
+| ------------- | ---------------------- | ------ | --------------------- |
+| `diffFiles`   | `DiffFile[]`           | `[]`   | 文件数组              |
+| `viewerStyle` | `WtoolDiffViewerStyle` | `{}`   | 单个 DiffViewer 的样式 |
+
+### `DiffFile`
 
-| 属性 | 类型 | 说明 |
-|------|------|------|
-| `width` | `string` | 查看器宽度，默认 `100%` |
-| `height` | `string` | 固定高度（设置后忽略自适应逻辑） |
-| `minHeight` | `string` | 自适应高度最小值，默认 `100px` |
-| `maxHeight` | `string` | 自适应高度最大值，默认 `250px` |
+| 属性          | 类型                                              | 必填 | 说明                                                     |
+| ------------- | ------------------------------------------------- | ---- | -------------------------------------------------------- |
+| `fullPath`    | `string`                                          | ❌   | 文件完整路径；省略时根据 `diffPair` 或 `diffPatch` 推导  |
+| `diffPatch`   | `string`                                          | ❌   | Unified diff 字符串，与 `diffPair` 二选一                |
+| `diffPair`    | `{ filename: string; content: string \| null }[]` | ❌   | 原文件和修改后文件                                       |
 
-> 支持 `px` 和 `vh` 单位。当 `height` 显式设置时，`minHeight` / `maxHeight` 无效。
+> `FileTree` 是 `DiffFile` 的废弃别名，建议迁移到 `DiffFile`。
 
 ---
 
-### `DiffEditorOptions`（Monaco 透传）
+### `DiffViewerProps`
 
-完整选项参考 [Monaco Editor 官方文档](https://microsoft.github.io/monaco-editor/docs.html)。
+| 属性           | 类型                                      | 默认值        | 说明                                                  |
+| -------------- | ----------------------------------------- | ------------- | ----------------------------------------------------- |
+| `diffPatch`    | `string`                                  | `''`          | Unified diff 字符串，与 `diffPair` 二选一             |
+| `diffPair`     | `{ filename: string; content: string }[]` | `[]`          | 原文件和修改后文件，与 `diffPatch` 二选一             |
+| `language`     | `string`                                  | `'plaintext'` | Monaco 语言标识，如 `'typescript'`、`'python'`        |
+| `options`      | `DiffEditorOptions`                       | `{}`          | 透传至 Monaco Diff Editor                             |
+| `modelOptions` | `ModelOptions`                            | `{}`          | 透传至 Monaco 文本模型                                |
+| `viewerStyle`  | `WtoolDiffViewerStyle`                    | —             | 外层尺寸                                              |
 
 ---
 
+### `WtoolDiffViewerStyle`
+
+| 属性        | 类型      | 说明                           |
+| ----------- | --------- | ------------------------------ |
+| `width`     | `string`  | 宽度，默认 `100%`              |
+| `height`    | `string`  | 固定高度，优先于自适应高度     |
+| `minHeight` | `string`  | 最小高度，默认 `100px`         |
+| `maxHeight` | `string`  | 最大高度，默认 `250px`         |
+| `viewed`    | `boolean` | 是否已读的初始值，默认 `false` |
+| `rawed`     | `boolean` | 是否显示原始文件，默认 `false` |
 
+> 尺寸支持 `px` 和 `vh`。
+
+---
 
+### `DiffEditorOptions`（Monaco 透传）
+
+选项见 [Monaco Editor 官方文档](https://microsoft.github.io/monaco-editor/docs.html)。
+
+---

package/dist/DiffFiles/DiffFiles.vue.d.ts

@@ -0,0 +1,12 @@
+import { WtoolDiffFilesProps } from '../types';
+import { DiffFileSelection } from './FileExplore/fileTree';
+declare const _default: import('../../node_modules/vue/dist/vue.esm-bundler.js').DefineComponent<WtoolDiffFilesProps, {}, {}, {}, {}, import('../../node_modules/vue/dist/vue.esm-bundler.js').ComponentOptionsMixin, import('../../node_modules/vue/dist/vue.esm-bundler.js').ComponentOptionsMixin, {
+    "select-file": (selection: DiffFileSelection) => any;
+}, string, import('../../node_modules/vue/dist/vue.esm-bundler.js').PublicProps, Readonly<WtoolDiffFilesProps> & Readonly<{
+    "onSelect-file"?: ((selection: DiffFileSelection) => any) | undefined;
+}>, {
+    viewerStyle: import('.').WtoolDiffViewerStyle;
+    diffFiles: import('.').DiffFile[];
+    fileOverScan: number;
+}, {}, {}, {}, string, import('../../node_modules/vue/dist/vue.esm-bundler.js').ComponentProvideOptions, false, {}, HTMLDivElement>;
+export default _default;

package/dist/DiffFiles/DiffList/DiffList.vue.d.ts

@@ -0,0 +1,94 @@
+import { DiffFileState, FileItem } from '../types';
+import { WtoolDiffViewerStyle } from '../../types';
+type __VLS_Props = {
+    diffFiles: FileItem[];
+    fileOverScan?: number;
+    fileViewMap: Record<string, DiffFileState>;
+    viewerStyle?: WtoolDiffViewerStyle;
+};
+declare const _default: import('../../../node_modules/vue/dist/vue.esm-bundler.js').DefineComponent<__VLS_Props, {}, {}, {}, {}, import('../../../node_modules/vue/dist/vue.esm-bundler.js').ComponentOptionsMixin, import('../../../node_modules/vue/dist/vue.esm-bundler.js').ComponentOptionsMixin, {
+    "view-state-change": (file: FileItem, state: Partial<DiffFileState>) => any;
+}, string, import('../../../node_modules/vue/dist/vue.esm-bundler.js').PublicProps, Readonly<__VLS_Props> & Readonly<{
+    "onView-state-change"?: ((file: FileItem, state: Partial<DiffFileState>) => any) | undefined;
+}>, {
+    viewerStyle: WtoolDiffViewerStyle;
+    diffFiles: FileItem[];
+    fileOverScan: number;
+    fileViewMap: Record<string, DiffFileState>;
+}, {}, {}, {}, string, import('../../../node_modules/vue/dist/vue.esm-bundler.js').ComponentProvideOptions, false, {
+    virtualScrollRef: import('../../../node_modules/vue/dist/vue.esm-bundler.js').CreateComponentPublicInstanceWithMixins<Readonly<import('../../../node_modules/vue/dist/vue.esm-bundler.js').ExtractPropTypes<{
+        items: {
+            required: true;
+            type: import('../../../node_modules/vue/dist/vue.esm-bundler.js').PropType<any[]>;
+        };
+        itemSize: {
+            required: true;
+            type: import('../../../node_modules/vue/dist/vue.esm-bundler.js').PropType<number | ((item: any, index: number) => number)>;
+        };
+        keyField: {
+            default: string;
+            type: StringConstructor;
+        };
+        overscan: {
+            default: number;
+            type: NumberConstructor;
+        };
+    }>> & Readonly<{}>, {
+        scrollCtn: import('../../../node_modules/vue/dist/vue.esm-bundler.js').Ref<HTMLElement, HTMLElement>;
+        onScroll: (evt: Event) => void;
+        totalHeight: import('../../../node_modules/vue/dist/vue.esm-bundler.js').ComputedRef<number>;
+        virtualItems: import('../../../node_modules/vue/dist/vue.esm-bundler.js').ComputedRef<{
+            key: any;
+            index: number;
+            start: number;
+            end: number;
+            size: number;
+            lane: number;
+        }[]>;
+        getVirtualer: () => import('@tanstack/vue-virtual').Virtualizer<HTMLElement, Element>;
+    }, {}, {}, {}, import('../../../node_modules/vue/dist/vue.esm-bundler.js').ComponentOptionsMixin, import('../../../node_modules/vue/dist/vue.esm-bundler.js').ComponentOptionsMixin, {}, import('../../../node_modules/vue/dist/vue.esm-bundler.js').PublicProps, {
+        keyField: string;
+        overscan: number;
+    }, true, {}, {}, import('../../../node_modules/vue/dist/vue.esm-bundler.js').GlobalComponents, import('../../../node_modules/vue/dist/vue.esm-bundler.js').GlobalDirectives, string, {}, any, import('../../../node_modules/vue/dist/vue.esm-bundler.js').ComponentProvideOptions, {
+        P: {};
+        B: {};
+        D: {};
+        C: {};
+        M: {};
+        Defaults: {};
+    }, Readonly<import('../../../node_modules/vue/dist/vue.esm-bundler.js').ExtractPropTypes<{
+        items: {
+            required: true;
+            type: import('../../../node_modules/vue/dist/vue.esm-bundler.js').PropType<any[]>;
+        };
+        itemSize: {
+            required: true;
+            type: import('../../../node_modules/vue/dist/vue.esm-bundler.js').PropType<number | ((item: any, index: number) => number)>;
+        };
+        keyField: {
+            default: string;
+            type: StringConstructor;
+        };
+        overscan: {
+            default: number;
+            type: NumberConstructor;
+        };
+    }>> & Readonly<{}>, {
+        scrollCtn: import('../../../node_modules/vue/dist/vue.esm-bundler.js').Ref<HTMLElement, HTMLElement>;
+        onScroll: (evt: Event) => void;
+        totalHeight: import('../../../node_modules/vue/dist/vue.esm-bundler.js').ComputedRef<number>;
+        virtualItems: import('../../../node_modules/vue/dist/vue.esm-bundler.js').ComputedRef<{
+            key: any;
+            index: number;
+            start: number;
+            end: number;
+            size: number;
+            lane: number;
+        }[]>;
+        getVirtualer: () => import('@tanstack/vue-virtual').Virtualizer<HTMLElement, Element>;
+    }, {}, {}, {}, {
+        keyField: string;
+        overscan: number;
+    }> | null;
+}, any>;
+export default _default;