From 613f413caa9fb8a47d0dc0341e25019c0049b0fb Mon Sep 17 00:00:00 2001 From: Jiahang Zhang Date: Mon, 6 Apr 2026 13:34:51 -0700 Subject: [PATCH] docs: expand README, add Chinese docs, and changelog --- CHANGELOG.md | 29 ++++++++ README.md | 121 ++++++++++++++++++++++++------- README.zh-CN.md | 141 ++++++++++++++++++++++++++++++++++++ packages/react/LICENSE | 21 ++++++ packages/react/README.md | 32 ++++++++ packages/react/package.json | 6 +- 6 files changed, 322 insertions(+), 28 deletions(-) create mode 100644 CHANGELOG.md create mode 100644 README.zh-CN.md create mode 100644 packages/react/LICENSE create mode 100644 packages/react/README.md diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 0000000..b392bec --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,29 @@ +# Changelog + +All notable changes to this project will be documented in this file. + +The format is based on Keep a Changelog, and this project follows Semantic Versioning. + +## [0.1.1] - 2026-04-06 + +### Added + +- Side-by-side diff rendering for text content +- Virtualized rendering via `react-virtuoso` for large files +- Context-line based collapsed unchanged sections +- TypeScript package exports for ESM/CJS + typings +- Demo app using Vite + React + +### Docs + +- Comprehensive root README (English) +- Chinese README (`README.zh-CN.md`) +- Package-level README for npm consumers (`packages/react/README.md`) +- Roadmap and broader TODO plan for project growth + +## [0.1.0] - 2026-04-06 + +### Added + +- Initial public package structure +- Core diff viewer component foundation diff --git a/README.md b/README.md index 2da9a4f..2373359 100644 --- a/README.md +++ b/README.md @@ -1,39 +1,67 @@ # virtualized-diff-viewer -A high-performance React diff viewer built for large files. +A high-performance, virtualized React diff viewer designed for **very large text files** and smooth developer experience. + +> Package name on npm: **`react-virtualized-diff`** + +[中文文档（Chinese README）](./README.zh-CN.md) + +--- + +## Why this project + +Most diff viewers are good for small files but become slow when input grows to tens of thousands of lines. + +`virtualized-diff-viewer` focuses on: + +- **Performance first** rendering with virtualization +- **Readable side-by-side UI** for code/text review +- **Configurable context lines** around changes +- **TypeScript support** for reliable integration +- **Simple React API** for quick adoption --- -## ✨ Features +## Features -- Side-by-side diff view -- Virtualized rendering for large files -- Collapsed unchanged blocks -- Configurable context lines -- TypeScript support +- ✅ Side-by-side diff layout +- ✅ Virtualized row rendering (good for large files) +- ✅ Collapsed unchanged blocks with configurable context +- ✅ Lightweight integration in React apps +- ✅ TypeScript declarations out of the box --- -## 📦 Installation +## Installation ```bash +# pnpm pnpm add react-virtualized-diff + +# npm +npm install react-virtualized-diff + +# yarn +yarn add react-virtualized-diff ``` --- -## 🚀 Usage +## Quick start ```tsx import { DiffViewer } from 'react-virtualized-diff'; -function Example() { +const oldText = `line 1\nline 2\nline 3`; +const newText = `line 1\nline 2 changed\nline 3\nline 4`; + +export function Example() { return ( ); } @@ -41,37 +69,76 @@ function Example() { --- -## 🧠 Why this project? +## API (current) + +### `DiffViewer` props + +- `original: string` – original text content +- `modified: string` – modified text content +- `contextLines?: number` – unchanged lines to keep around changes (default behavior from component) +- `height?: number | string` – viewport height for virtualization container + +> Tip: for best performance with huge files, keep rendering area constrained with a fixed `height`. -Most React diff viewers work well for small files but struggle with large inputs. +--- -This project focuses on: +## Monorepo structure -- Rendering large diffs efficiently -- Reducing unnecessary DOM nodes -- Keeping interaction smooth even with 100k+ lines +```text +apps/demo/ # Vite demo app +packages/react/ # npm package: react-virtualized-diff +``` --- -## 🛠 Development +## Local development ```bash pnpm install -pnpm dev -pnpm build +pnpm dev # run demo app +pnpm build # build workspace packages ``` --- -## 📊 Roadmap +## npm package README support + +To ensure npm users always see correct documentation: + +- Package-level README is maintained at `packages/react/README.md` +- `packages/react/package.json` includes README in publish files +- Root README links to the package docs and Chinese docs + +--- + +## Release log + +See [CHANGELOG.md](./CHANGELOG.md) for tracked releases and supported capabilities. + +--- + +## Future plan + +### Near-term roadmap + +- [ ] Optional syntax highlighting (performance-aware) +- [ ] More comprehensive live demo scenarios (big files, mixed edits) +- [ ] Public hosted demo site for quick evaluation +- [ ] Better customization hooks (line renderers, gutters) + +### Additional TODOs to make this project more popular -- [ ] Syntax highlighting (optional, performance-aware) -- [ ] Custom render hooks -- [ ] Worker-based diff computation -- [ ] Benchmark suite +- [ ] Detailed benchmark report vs common diff viewers +- [ ] Keyboard navigation + accessibility improvements +- [ ] Dark/light theme presets and design tokens +- [ ] SSR usage guide (Next.js / Remix examples) +- [ ] More real-world examples (JSON, logs, markdown, code) +- [ ] CI release automation + semantic versioning workflow +- [ ] Contribution guide and issue templates +- [ ] International docs beyond English/Chinese --- -## 📄 License +## License -MIT License +MIT diff --git a/README.zh-CN.md b/README.zh-CN.md new file mode 100644 index 0000000..505477d --- /dev/null +++ b/README.zh-CN.md @@ -0,0 +1,141 @@ +# virtualized-diff-viewer + +一个面向**超大文本文件**场景的高性能 React 差异对比组件（虚拟滚动渲染）。 + +> npm 包名：**`react-virtualized-diff`** + +[English README](./README.md) + +--- + +## 项目定位 + +很多 diff 组件在小文件场景表现不错，但面对数万行甚至十万行文本时，渲染和交互会明显变慢。 + +`virtualized-diff-viewer` 的目标是： + +- **性能优先**：通过虚拟列表减少 DOM 压力 +- **可读性优先**：清晰的左右对比视图 +- **可配置性**：支持上下文折叠行数配置 +- **工程可用性**：TypeScript 友好、接入简单 + +--- + +## 功能特性 + +- ✅ 左右并排差异视图 +- ✅ 虚拟化渲染（适合大文件） +- ✅ 未变化区块折叠 + 上下文行 +- ✅ React 项目快速接入 +- ✅ 开箱即用 TypeScript 类型定义 + +--- + +## 安装 + +```bash +# pnpm +pnpm add react-virtualized-diff + +# npm +npm install react-virtualized-diff + +# yarn +yarn add react-virtualized-diff +``` + +--- + +## 快速开始 + +```tsx +import { DiffViewer } from 'react-virtualized-diff'; + +const oldText = `line 1\nline 2\nline 3`; +const newText = `line 1\nline 2 changed\nline 3\nline 4`; + +export function Example() { + return ( + + ); +} +``` + +--- + +## 当前 API + +### `DiffViewer` 属性 + +- `original: string`：原始文本 +- `modified: string`：修改后文本 +- `contextLines?: number`：变化块周围保留的上下文行数 +- `height?: number | string`：组件容器高度（建议固定高度以获得更好性能） + +--- + +## 仓库结构 + +```text +apps/demo/ # Vite 演示项目 +packages/react/ # npm 包：react-virtualized-diff +``` + +--- + +## 本地开发 + +```bash +pnpm install +pnpm dev +pnpm build +``` + +--- + +## npm 包 README 支持说明 + +为确保 npm 页面文档可用： + +- 在 `packages/react/README.md` 维护包级说明 +- 在 `packages/react/package.json` 发布文件中包含 README +- 根目录 README 与中文文档互相链接 + +--- + +## 版本发布记录 + +详见 [CHANGELOG.md](./CHANGELOG.md)。 + +--- + +## 后续规划 + +### 近期路线 + +- [ ] 可选语法高亮（性能优先设计） +- [ ] 更完整的在线 Demo 场景（超大文件、复杂编辑） +- [ ] 托管在线示例站点，方便快速体验 +- [ ] 更强的自定义能力（行渲染、gutter 等） + +### 可提升项目影响力的 TODO + +- [ ] 与主流 diff 组件的基准测试报告 +- [ ] 键盘导航与无障碍增强 +- [ ] 深色/浅色主题预设 +- [ ] SSR 集成文档（Next.js / Remix） +- [ ] 更多真实场景示例（JSON、日志、Markdown、代码） +- [ ] CI 自动发布与语义化版本流程 +- [ ] 完善贡献指南与 issue 模板 +- [ ] 扩展多语言文档 + +--- + +## 许可证 + +MIT diff --git a/packages/react/LICENSE b/packages/react/LICENSE new file mode 100644 index 0000000..01a3930 --- /dev/null +++ b/packages/react/LICENSE @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2026 Jiahang Zhang + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. diff --git a/packages/react/README.md b/packages/react/README.md new file mode 100644 index 0000000..b084444 --- /dev/null +++ b/packages/react/README.md @@ -0,0 +1,32 @@ +# react-virtualized-diff + +React virtualized diff viewer for large text/code files. + +> This package is part of the `virtualized-diff-viewer` monorepo. + +## Install + +```bash +npm install react-virtualized-diff +``` + +## Usage + +```tsx +import { DiffViewer } from 'react-virtualized-diff'; + +; +``` + +## Props + +- `original: string` +- `modified: string` +- `contextLines?: number` +- `height?: number | string` + +## Links + +- Repository README: `../../README.md` +- Chinese README: `../../README.zh-CN.md` +- Changelog: `../../CHANGELOG.md` diff --git a/packages/react/package.json b/packages/react/package.json index 55aa73f..ca5ccce 100644 --- a/packages/react/package.json +++ b/packages/react/package.json @@ -12,7 +12,11 @@ "require": "./dist/index.cjs" } }, - "files": ["dist"], + "files": [ + "dist", + "README.md", + "LICENSE" + ], "sideEffects": false, "peerDependencies": { "react": ">=18",