@yuhufe/wtool-vdiff 0.0.1

package/README.md

@@ -0,0 +1,165 @@
+# @yuhufe/wtool-vdiff
+
+**Demo**: [https://defghy.github.io/web-toolkits/v-diff/](https://defghy.github.io/web-toolkits/v-diff/)
+
+基于 Monaco 的 DiffViewer。 **框架无关** —— 可直接集成到任何前端项目（React、Vue、原生 JS 等）中。
+
+---
+
+## 特性
+
+- **框架无关** ：通过 Web Component 封装，函数调用即可挂载，无需 Vue 项目
+- **双模式输入** ：支持 `diffPatch`（unified diff 字符串）与 `diffPair`（原始文件对）两种数据格式
+- **自适应高度** ：根据实际变更行数自动计算编辑器高度，避免大量空白
+- **折叠未变更区域** ：默认折叠无差异区域，仅保留变更附近的上下文行
+- **顶部工具栏** ：内置文件名展示、增删行数统计、viewed 标记、raw 展开模式
+
+---
+
+## 安装
+
+```bash
+npm install @yuhufe/wtool-vdiff
+# 或
+pnpm add @yuhufe/wtool-vdiff
+```
+
+---
+
+## 快速开始
+
+### 方式一：`diffPatch` 模式（unified diff 字符串）
+
+```typescript
+import { createDiffViewer } from '@yuhufe/wtool-vdiff'
+
+const viewer = createDiffViewer(document.getElementById('diff-container')!, {
+  diffPatch: `--- a/src/index.ts
++++ b/src/index.ts
+@@ -1,5 +1,6 @@
+ import { foo } from './foo'
+-const x = 1
++const x = 2
++const y = 3
+ export { foo }`,
+})
+
+// 动态更新内容
+viewer.update({ diffPatch: newPatch })
+
+// 销毁
+viewer.destroy()
+```
+
+### 方式二：`diffPair` 模式（完整文件对）
+
+```typescript
+import { createDiffViewer } from '@yuhufe/wtool-vdiff'
+
+const viewer = createDiffViewer(document.getElementById('diff-container')!, {
+  diffPair: [
+    { filename: 'src/index.ts', content: 'const x = 1\nexport { foo }' },
+    { filename: 'src/index.ts', content: 'const x = 2\nconst y = 3\nexport { foo }' },
+  ],
+  language: 'typescript',
+})
+```
+
+---
+
+## loader 配置
+
+库内部通过 `@monaco-editor/loader` 按需加载 Monaco。默认走 jsDelivr CDN，生产环境建议改为本地 bundle。
+
+**方式一：自定义 CDN 路径**
+
+```typescript
+import { loader } from '@yuhufe/wtool-vdiff'
+
+loader.config({
+  paths: { vs: 'https://your-cdn.example.com/monaco-editor/0.53.0/min/vs' },
+})
+```
+
+**方式二：从 node_modules 本地加载（Vite 项目推荐）**
+
+```typescript
+import * as monaco from 'monaco-editor'
+import editorWorker from 'monaco-editor/esm/vs/editor/editor.worker?worker'
+import tsWorker from 'monaco-editor/esm/vs/language/typescript/ts.worker?worker'
+import jsonWorker from 'monaco-editor/esm/vs/language/json/json.worker?worker'
+import cssWorker from 'monaco-editor/esm/vs/language/css/css.worker?worker'
+import htmlWorker from 'monaco-editor/esm/vs/language/html/html.worker?worker'
+import { loader } from '@yuhufe/wtool-vdiff'
+
+self.MonacoEnvironment = {
+  getWorker(_, label) {
+    if (label === 'json') return new jsonWorker()
+    if (label === 'css' || label === 'scss' || label === 'less') return new cssWorker()
+    if (label === 'html' || label === 'handlebars' || label === 'razor') return new htmlWorker()
+    if (label === 'typescript' || label === 'javascript') return new tsWorker()
+    return new editorWorker()
+  },
+}
+
+loader.config({ monaco })
+```
+
+> `loader.config` 必须在任意 `createDiffViewer` 调用之前执行。
+
+---
+
+## API
+
+### `createDiffViewer(target, props?)`
+
+在目标元素内创建并挂载 diff 查看器，返回 `DiffViewerInstance` 实例。
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `target` | `HTMLElement` | ✅ | 挂载目标容器元素 |
+| `props` | `DiffViewerProps` | ❌ | 初始化属性（见下方 Props 说明） |
+
+**返回值：`DiffViewerInstance`**
+
+| 方法 | 签名 | 说明 |
+|------|------|------|
+| `update` | `(props: Partial<DiffViewerProps>) => void` | 动态更新 props |
+| `destroy` | `() => void` | 销毁查看器并从 DOM 移除 |
+
+---
+
+### Props（`DiffViewerProps`）
+
+| 属性 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `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` | — | 查看器外层样式（宽高） |
+
+---
+
+### `WtoolDiffViewerStyle`
+
+| 属性 | 类型 | 说明 |
+|------|------|------|
+| `width` | `string` | 查看器宽度，默认 `100%` |
+| `height` | `string` | 固定高度（设置后忽略自适应逻辑） |
+| `minHeight` | `string` | 自适应高度最小值，默认 `100px` |
+| `maxHeight` | `string` | 自适应高度最大值，默认 `250px` |
+
+> 支持 `px` 和 `vh` 单位。当 `height` 显式设置时，`minHeight` / `maxHeight` 无效。
+
+---
+
+### `DiffEditorOptions`（Monaco 透传）
+
+完整选项参考 [Monaco Editor 官方文档](https://microsoft.github.io/monaco-editor/docs.html)。
+
+---
+
+
+

package/dist/DiffViewer/DiffViewer.vue.d.ts

@@ -0,0 +1,12 @@
+import { DiffEditorOptions, WtoolDiffViewerProps, ModelOptions } from '../types';
+declare const _default: import('../../node_modules/vue/dist/vue.esm-bundler.js').DefineComponent<WtoolDiffViewerProps, {}, {}, {}, {}, import('../../node_modules/vue/dist/vue.esm-bundler.js').ComponentOptionsMixin, import('../../node_modules/vue/dist/vue.esm-bundler.js').ComponentOptionsMixin, {}, string, import('../../node_modules/vue/dist/vue.esm-bundler.js').PublicProps, Readonly<WtoolDiffViewerProps> & Readonly<{}>, {
+    language: string;
+    options: DiffEditorOptions;
+    modelOptions: ModelOptions;
+    diffPair: {
+        filename: string;
+        content: string;
+    }[];
+    diffPatch: string;
+}, {}, {}, {}, string, import('../../node_modules/vue/dist/vue.esm-bundler.js').ComponentProvideOptions, false, {}, HTMLDivElement>;
+export default _default;

package/dist/DiffViewer/MonacoDiffViewer.vue.d.ts

@@ -0,0 +1,24 @@
+import type * as Monaco from 'monaco-editor';
+type DiffEditorOptions = Monaco.editor.IStandaloneDiffEditorConstructionOptions;
+type ModelOptions = Monaco.editor.ITextModelUpdateOptions;
+type __VLS_Props = {
+    originalCode?: string;
+    modifiedCode?: string;
+    language?: string;
+    options?: DiffEditorOptions;
+    modelOptions?: ModelOptions;
+};
+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, {
+    renderComplete: () => any;
+}, string, import('../../node_modules/vue/dist/vue.esm-bundler.js').PublicProps, Readonly<__VLS_Props> & Readonly<{
+    onRenderComplete?: (() => any) | undefined;
+}>, {
+    originalCode: string;
+    modifiedCode: string;
+    language: string;
+    options: DiffEditorOptions;
+    modelOptions: ModelOptions;
+}, {}, {}, {}, string, import('../../node_modules/vue/dist/vue.esm-bundler.js').ComponentProvideOptions, false, {
+    containerEl: HTMLDivElement;
+}, HTMLDivElement>;
+export default _default;

package/dist/DiffViewer/TopBar.vue.d.ts

@@ -0,0 +1,13 @@
+type __VLS_Props = {
+    diffPair?: {
+        filename: string;
+        content: string;
+    }[];
+};
+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, {}, string, import('../../node_modules/vue/dist/vue.esm-bundler.js').PublicProps, Readonly<__VLS_Props> & Readonly<{}>, {
+    diffPair: {
+        filename: string;
+        content: string;
+    }[];
+}, {}, {}, {}, string, import('../../node_modules/vue/dist/vue.esm-bundler.js').ComponentProvideOptions, false, {}, HTMLDivElement>;
+export default _default;

package/dist/DiffViewer/createDiffViewer.d.ts

@@ -0,0 +1,10 @@
+import { WtoolDiffViewerProps } from '../types';
+export type DiffViewerProps = WtoolDiffViewerProps;
+export declare const WTOOL_DIFF_VIEWER_TAG = "wtool-diff-viewer";
+export declare const WtoolDiffViewer: import('../../node_modules/vue/dist/vue.esm-bundler.js').VueElementConstructor<WtoolDiffViewerProps>;
+export declare function register(tagName?: string): void;
+export interface DiffViewerInstance {
+    update(props: Partial<DiffViewerProps>): void;
+    destroy(): void;
+}
+export declare function createDiffViewer(target: HTMLElement, initialProps?: DiffViewerProps): DiffViewerInstance;

package/dist/DiffViewer/index.d.ts

@@ -0,0 +1 @@
+export { WTOOL_DIFF_VIEWER_TAG, WtoolDiffViewer, register as registerDiffViewer, createDiffViewer, type DiffViewerProps, type DiffViewerInstance, } from './createDiffViewer';

package/dist/DiffViewer/useDiffView.d.ts

@@ -0,0 +1,27 @@
+import { Ref } from '../../node_modules/vue/dist/vue.esm-bundler.js';
+export declare const useDiffViewer: ({ isMaster }?: {
+    isMaster?: boolean | undefined;
+}) => {
+    funcs: {
+        viewed: Ref<boolean>;
+        rawed: Ref<boolean>;
+        updateViewed: (viewed: boolean) => any;
+        updateRawed: (args: boolean) => any;
+        updateChangedLines: (args: {
+            added: number;
+            removed: number;
+        }) => any;
+        canUnchangeVisible: Ref<boolean>;
+    };
+    registerFunc: (funcList: Partial<{
+        viewed: Ref<boolean>;
+        rawed: Ref<boolean>;
+        updateViewed: (viewed: boolean) => any;
+        updateRawed: (args: boolean) => any;
+        updateChangedLines: (args: {
+            added: number;
+            removed: number;
+        }) => any;
+        canUnchangeVisible: Ref<boolean>;
+    }>) => void;
+};

package/dist/DiffViewer/utils/autoHeight.d.ts

@@ -0,0 +1,9 @@
+import { WtoolDiffViewerProps } from '../../types';
+export declare const autoHeight: ({ patch, pair, maxHeight, minHeight, unchangedVisiable, unchangedCtxLineNum, }: {
+    patch?: string;
+    pair?: WtoolDiffViewerProps["diffPair"];
+    maxHeight: string;
+    minHeight: string;
+    unchangedVisiable: boolean;
+    unchangedCtxLineNum: number;
+}) => number;

package/dist/DiffViewer/utils/patch2Pair.d.ts

@@ -0,0 +1,27 @@
+export interface FilePair {
+    filename: string;
+    content: string;
+}
+export interface Hunk {
+    origStart: number;
+    origCount: number;
+    modStart: number;
+    modCount: number;
+    lines: string[];
+}
+/**
+ * 解析 unified diff patch，提取文件名与所有 hunk
+ */
+export declare function parseHunks(patch: string): {
+    origFilename: string;
+    modFilename: string;
+    hunks: Hunk[];
+};
+/**
+ * 将 unified diff patch 转换为 [original, modified] 文件对。
+ *
+ * Monaco diff editor 需要两个完整文件内容，而 patch 只记录变更片段。
+ * 未改动的行（hunk 之外）用空行填充，使两侧行号与 hunk 声明的起始位置对齐，
+ * 从而让 Monaco 能在正确的行号位置渲染增删差异。
+ */
+export declare const patch2Pair: (patch: string) => FilePair[];

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export * from './DiffViewer';
+export { default as loader } from '@monaco-editor/loader';

package/dist/types.d.ts

@@ -0,0 +1,20 @@
+import type * as Monaco from 'monaco-editor';
+export type DiffEditorOptions = Monaco.editor.IStandaloneDiffEditorConstructionOptions;
+export type ModelOptions = Monaco.editor.ITextModelUpdateOptions;
+export interface WtoolDiffViewerProps {
+    diffPair?: {
+        filename: string;
+        content: string;
+    }[];
+    diffPatch?: string;
+    language?: string;
+    options?: DiffEditorOptions;
+    modelOptions?: ModelOptions;
+    viewerStyle?: WtoolDiffViewerStyle;
+}
+export interface WtoolDiffViewerStyle {
+    width?: string;
+    height?: string;
+    minHeight?: string;
+    maxHeight?: string;
+}