Skip to content

Commit d27ad68

Browse files
Zhang-JiahangHZhang-JiahangH
authored
Merge pull request #1 from Zhang-JiahangH/codex/improve-and-expand-project-readme
docs: improve project README, add Chinese docs, and changelog
2 parents 7bb2504 + 613f413 commit d27ad68

6 files changed

Lines changed: 322 additions & 28 deletions

File tree

‎CHANGELOG.md‎

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
# Changelog
2+
3+
All notable changes to this project will be documented in this file.
4+
5+
The format is based on Keep a Changelog, and this project follows Semantic Versioning.
6+
7+
## [0.1.1] - 2026-04-06
8+
9+
### Added
10+
11+
- Side-by-side diff rendering for text content
12+
- Virtualized rendering via `react-virtuoso` for large files
13+
- Context-line based collapsed unchanged sections
14+
- TypeScript package exports for ESM/CJS + typings
15+
- Demo app using Vite + React
16+
17+
### Docs
18+
19+
- Comprehensive root README (English)
20+
- Chinese README (`README.zh-CN.md`)
21+
- Package-level README for npm consumers (`packages/react/README.md`)
22+
- Roadmap and broader TODO plan for project growth
23+
24+
## [0.1.0] - 2026-04-06
25+
26+
### Added
27+
28+
- Initial public package structure
29+
- Core diff viewer component foundation

‎README.md‎

Lines changed: 94 additions & 27 deletions
Original file line numberDiff line numberDiff line change
@@ -1,77 +1,144 @@
11
# virtualized-diff-viewer
22

3-
A high-performance React diff viewer built for large files.
3+
A high-performance, virtualized React diff viewer designed for **very large text files** and smooth developer experience.
4+
5+
> Package name on npm: **`react-virtualized-diff`**
6+
7+
[中文文档（Chinese README）](./README.zh-CN.md)
8+
9+
---
10+
11+
## Why this project
12+
13+
Most diff viewers are good for small files but become slow when input grows to tens of thousands of lines.
14+
15+
`virtualized-diff-viewer` focuses on:
16+
17+
- **Performance first** rendering with virtualization
18+
- **Readable side-by-side UI** for code/text review
19+
- **Configurable context lines** around changes
20+
- **TypeScript support** for reliable integration
21+
- **Simple React API** for quick adoption
422

523
---
624

7-
## ✨ Features
25+
## Features
826

9-
- Side-by-side diff view
10-
- Virtualized rendering for large files
11-
- Collapsed unchanged blocks
12-
- Configurable context lines
13-
- TypeScript support
27+
- ✅ Side-by-side diff layout
28+
- ✅ Virtualized row rendering (good for large files)
29+
- ✅ Collapsed unchanged blocks with configurable context
30+
- ✅ Lightweight integration in React apps
31+
- ✅ TypeScript declarations out of the box
1432

1533
---
1634

17-
## 📦 Installation
35+
## Installation
1836

1937
```bash
38+
# pnpm
2039
pnpm add react-virtualized-diff
40+
41+
# npm
42+
npm install react-virtualized-diff
43+
44+
# yarn
45+
yarn add react-virtualized-diff
2146
```
2247

2348
---
2449

25-
## 🚀 Usage
50+
## Quick start
2651

2752
```tsx
2853
import { DiffViewer } from 'react-virtualized-diff';
2954

30-
function Example() {
55+
const oldText = `line 1\nline 2\nline 3`;
56+
const newText = `line 1\nline 2 changed\nline 3\nline 4`;
57+
58+
export function Example() {
3159
return (
3260
<DiffViewer
3361
original={oldText}
3462
modified={newText}
3563
contextLines={2}
36-
height={500}
64+
height={480}
3765
/>
3866
);
3967
}
4068
```
4169

4270
---
4371

44-
## 🧠 Why this project?
72+
## API (current)
73+
74+
### `DiffViewer` props
75+
76+
- `original: string` – original text content
77+
- `modified: string` – modified text content
78+
- `contextLines?: number` – unchanged lines to keep around changes (default behavior from component)
79+
- `height?: number | string` – viewport height for virtualization container
80+
81+
> Tip: for best performance with huge files, keep rendering area constrained with a fixed `height`.
4582
46-
Most React diff viewers work well for small files but struggle with large inputs.
83+
---
4784

48-
This project focuses on:
85+
## Monorepo structure
4986

50-
- Rendering large diffs efficiently
51-
- Reducing unnecessary DOM nodes
52-
- Keeping interaction smooth even with 100k+ lines
87+
```text
88+
apps/demo/ # Vite demo app
89+
packages/react/ # npm package: react-virtualized-diff
90+
```
5391

5492
---
5593

56-
## 🛠 Development
94+
## Local development
5795

5896
```bash
5997
pnpm install
60-
pnpm dev
61-
pnpm build
98+
pnpm dev # run demo app
99+
pnpm build # build workspace packages
62100
```
63101

64102
---
65103

66-
## 📊 Roadmap
104+
## npm package README support
105+
106+
To ensure npm users always see correct documentation:
107+
108+
- Package-level README is maintained at `packages/react/README.md`
109+
- `packages/react/package.json` includes README in publish files
110+
- Root README links to the package docs and Chinese docs
111+
112+
---
113+
114+
## Release log
115+
116+
See [CHANGELOG.md](./CHANGELOG.md) for tracked releases and supported capabilities.
117+
118+
---
119+
120+
## Future plan
121+
122+
### Near-term roadmap
123+
124+
- [ ] Optional syntax highlighting (performance-aware)
125+
- [ ] More comprehensive live demo scenarios (big files, mixed edits)
126+
- [ ] Public hosted demo site for quick evaluation
127+
- [ ] Better customization hooks (line renderers, gutters)
128+
129+
### Additional TODOs to make this project more popular
67130

68-
- [ ] Syntax highlighting (optional, performance-aware)
69-
- [ ] Custom render hooks
70-
- [ ] Worker-based diff computation
71-
- [ ] Benchmark suite
131+
- [ ] Detailed benchmark report vs common diff viewers
132+
- [ ] Keyboard navigation + accessibility improvements
133+
- [ ] Dark/light theme presets and design tokens
134+
- [ ] SSR usage guide (Next.js / Remix examples)
135+
- [ ] More real-world examples (JSON, logs, markdown, code)
136+
- [ ] CI release automation + semantic versioning workflow
137+
- [ ] Contribution guide and issue templates
138+
- [ ] International docs beyond English/Chinese
72139

73140
---
74141

75-
## 📄 License
142+
## License
76143

77-
MIT License
144+
MIT

‎README.zh-CN.md‎

Lines changed: 141 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,141 @@
1+
# virtualized-diff-viewer
2+
3+
一个面向**超大文本文件**场景的高性能 React 差异对比组件（虚拟滚动渲染）。
4+
5+
> npm 包名：**`react-virtualized-diff`**
6+
7+
[English README](./README.md)
8+
9+
---
10+
11+
## 项目定位
12+
13+
很多 diff 组件在小文件场景表现不错，但面对数万行甚至十万行文本时，渲染和交互会明显变慢。
14+
15+
`virtualized-diff-viewer` 的目标是：
16+
17+
- **性能优先**：通过虚拟列表减少 DOM 压力
18+
- **可读性优先**：清晰的左右对比视图
19+
- **可配置性**：支持上下文折叠行数配置
20+
- **工程可用性**：TypeScript 友好、接入简单
21+
22+
---
23+
24+
## 功能特性
25+
26+
- ✅ 左右并排差异视图
27+
- ✅ 虚拟化渲染（适合大文件）
28+
- ✅ 未变化区块折叠 + 上下文行
29+
- ✅ React 项目快速接入
30+
- ✅ 开箱即用 TypeScript 类型定义
31+
32+
---
33+
34+
## 安装
35+
36+
```bash
37+
# pnpm
38+
pnpm add react-virtualized-diff
39+
40+
# npm
41+
npm install react-virtualized-diff
42+
43+
# yarn
44+
yarn add react-virtualized-diff
45+
```
46+
47+
---
48+
49+
## 快速开始
50+
51+
```tsx
52+
import { DiffViewer } from 'react-virtualized-diff';
53+
54+
const oldText = `line 1\nline 2\nline 3`;
55+
const newText = `line 1\nline 2 changed\nline 3\nline 4`;
56+
57+
export function Example() {
58+
return (
59+
<DiffViewer
60+
original={oldText}
61+
modified={newText}
62+
contextLines={2}
63+
height={480}
64+
/>
65+
);
66+
}
67+
```
68+
69+
---
70+
71+
## 当前 API
72+
73+
### `DiffViewer` 属性
74+
75+
- `original: string`：原始文本
76+
- `modified: string`：修改后文本
77+
- `contextLines?: number`：变化块周围保留的上下文行数
78+
- `height?: number | string`：组件容器高度（建议固定高度以获得更好性能）
79+
80+
---
81+
82+
## 仓库结构
83+
84+
```text
85+
apps/demo/ # Vite 演示项目
86+
packages/react/ # npm 包：react-virtualized-diff
87+
```
88+
89+
---
90+
91+
## 本地开发
92+
93+
```bash
94+
pnpm install
95+
pnpm dev
96+
pnpm build
97+
```
98+
99+
---
100+
101+
## npm 包 README 支持说明
102+
103+
为确保 npm 页面文档可用：
104+
105+
- 在 `packages/react/README.md` 维护包级说明
106+
- 在 `packages/react/package.json` 发布文件中包含 README
107+
- 根目录 README 与中文文档互相链接
108+
109+
---
110+
111+
## 版本发布记录
112+
113+
详见 [CHANGELOG.md](./CHANGELOG.md)。
114+
115+
---
116+
117+
## 后续规划
118+
119+
### 近期路线
120+
121+
- [ ] 可选语法高亮（性能优先设计）
122+
- [ ] 更完整的在线 Demo 场景（超大文件、复杂编辑）
123+
- [ ] 托管在线示例站点，方便快速体验
124+
- [ ] 更强的自定义能力（行渲染、gutter 等）
125+
126+
### 可提升项目影响力的 TODO
127+
128+
- [ ] 与主流 diff 组件的基准测试报告
129+
- [ ] 键盘导航与无障碍增强
130+
- [ ] 深色/浅色主题预设
131+
- [ ] SSR 集成文档（Next.js / Remix）
132+
- [ ] 更多真实场景示例（JSON、日志、Markdown、代码）
133+
- [ ] CI 自动发布与语义化版本流程
134+
- [ ] 完善贡献指南与 issue 模板
135+
- [ ] 扩展多语言文档
136+
137+
---
138+
139+
## 许可证
140+
141+
MIT

‎packages/react/LICENSE‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
MIT License
2+
3+
Copyright (c) 2026 Jiahang Zhang
4+
5+
Permission is hereby granted, free of charge, to any person obtaining a copy
6+
of this software and associated documentation files (the "Software"), to deal
7+
in the Software without restriction, including without limitation the rights
8+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9+
copies of the Software, and to permit persons to whom the Software is
10+
furnished to do so, subject to the following conditions:
11+
12+
The above copyright notice and this permission notice shall be included in all
13+
copies or substantial portions of the Software.
14+
15+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21+
SOFTWARE.

‎packages/react/README.md‎

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,32 @@
1+
# react-virtualized-diff
2+
3+
React virtualized diff viewer for large text/code files.
4+
5+
> This package is part of the `virtualized-diff-viewer` monorepo.
6+
7+
## Install
8+
9+
```bash
10+
npm install react-virtualized-diff
11+
```
12+
13+
## Usage
14+
15+
```tsx
16+
import { DiffViewer } from 'react-virtualized-diff';
17+
18+
<DiffViewer original={oldText} modified={newText} contextLines={2} height={500} />;
19+
```
20+
21+
## Props
22+
23+
- `original: string`
24+
- `modified: string`
25+
- `contextLines?: number`
26+
- `height?: number | string`
27+
28+
## Links
29+
30+
- Repository README: `../../README.md`
31+
- Chinese README: `../../README.zh-CN.md`
32+
- Changelog: `../../CHANGELOG.md`

0 commit comments

Comments
 (0)