virtual-react-json-diff 1.0.14 → 1.0.16

package/README.md

@@ -1,72 +1,83 @@
-# 📘 virtual-react-json-diff
+# virtual-react-json-diff
 
 [![NPM version][npm-image]][npm-url]
 [![Downloads][download-badge]][npm-url]
 ![bundle size](https://badgen.net/bundlephobia/minzip/virtual-react-json-diff)
 [![BuyMeACoffee](https://raw.githubusercontent.com/pachadotdev/buymeacoffee-badges/main/bmc-yellow.svg)](https://www.buymeacoffee.com/utkuakyuz)
 
-👉 [Try it now](https://virtual-react-json-diff.netlify.app) (See the New Demo Page Including AceEditor)
+👉 [Try it now](https://virtual-react-json-diff.netlify.app)
 
-A high-performance React component for visually comparing large JSON objects. Built on top of [json-diff-kit](https://www.npmjs.com/package/json-diff-kit), this viewer supports:
+A high-performance React JSON diff viewer for **large, real-world JSON data**.
 
-- Virtual scrolling for better performance (especially for large diffs)
-- Custom theming (Soon new themes will be available)
-- Dual Mini Map
-- 🔍 Search functionality
-- ⚛️ Optimized for React (uses `react-window`)
+Built to handle **tens of thousands of lines without freezing the UI**, it uses virtualized rendering to stay fast and responsive even in production-scale scenarios.
 
-This component is developed for dealing with thousands of lines of Json Files, and seamlessly compare then render them on UI. Json Compare is a concept that has insufficient FE components available. This component brings solution to the issues of current diff viewers. Virtualized scroll gives a smooth experience while dual minimap and search ability simplifies the process of comparing JSON objects.
+Powered by [json-diff-kit](https://www.npmjs.com/package/json-diff-kit), it supports virtual scrolling, advanced comparison options, search, dual minimaps, and customizable theming.
 
-## Features
+## Why virtual-react-json-diff exists
 
-- **Compare Large JSON Objects** – Handles big files without freezing the UI
-- **Virtualized Rendering** – Efficient DOM updates using `react-window`
-- **Search Highlighting** – Find matches and scroll directly to them
-- **Mini Map** – Dual scrollable minimap of Json Diff, scaled to better see comparison result
-- **Customizable Styles** – Add your own class names and styles easily (checkout JsonDiffCustomTheme.css)
+Most JSON diff viewers work well for **small examples**, but start breaking down in real-world scenarios:
 
-## Demo
+* Large JSON files cause the UI to freeze or crash
+* Rendering thousands of DOM nodes makes scrolling unusable
+* Array changes are hard to reason about without object-level comparison
+* It’s difficult to understand the *impact* of changes beyond raw diffs
 
-To see how it works, demo available here: https://virtual-react-json-diff.netlify.app
+**virtual-react-json-diff** was built to solve these problems.
 
-## 📦 Installation
+It is designed for internal dashboards and developer tools that need to compare **large, deeply nested JSON objects** efficiently and interactively.
 
-```bash
-npm install virtual-react-json-diff
-# or
-yarn add virtual-react-json-diff
-# or
-pnpm add virtual-react-json-diff
-```
+## Key Features
 
-## Example Screenshot
+virtual-react-json-diff is designed for scenarios where traditional diff viewers become unusable due to size or complexity.
 
-The theme is fully customizable, all colors can be changed. (And soon new themes will be available)
+### Built for Large JSONs
 
-![ExampleScreenshot](https://raw.githubusercontent.com/utkuakyuz/virtual-react-json-diff/main/public/image-1.0.11.png)
+* **Virtualized rendering** powered by `react-window`
+* Smooth scrolling and interaction even with very large diffs
 
-## Usage
+### Navigate Complex Changes
 
-Modify DifferOptions and InlineDiffOptions and see the output.
+* **Dual minimap** with visual change indicators
+* Jump directly to changes using **search highlighting**
+* Optional single minimap for compact layouts
 
-Dual Minimap is defaultly shown, to hide middle minimap, just pass `ShowSingleMinimap` prop to Viewer.
+### Understand Change Impact
 
-To change Diff methods please see `DifferOptions`. By default `virtual-react-json-diff` uses following configuration.
+* **Line count statistics** for added, removed, and modified lines
+* **Object-level statistics** when using compare-key array diffs
+* Quickly assess how big or risky a change really is
 
-```
-new Differ({
-  detectCircular: true,
-  maxDepth: 20,
-  showModifications: true,
-  arrayDiffMethod: "lcs",
-  preserveKeyOrder: "before",
-  ...differOptions,
-}),
-```
+### Advanced Comparison Control
+
+* Ignore specific keys or paths anywhere in the JSON tree
+* Multiple comparison strategies (`strict`, `loose`, `type-aware`)
+* Fine-grained control over how values are considered equal
 
-Simply pass your json objects into Viewer Component. It will find differences and show.
+### Customizable & Extensible
+
+* Custom class names for theming
+* Inline diff customization
+* Access raw diff data for advanced use cases
+
+## Demo
 
+👉 [Try it now](https://virtual-react-json-diff.netlify.app) - Interactive demo with live examples
+
+![Example Screenshot](https://raw.githubusercontent.com/utkuakyuz/virtual-react-json-diff/main/public/image-1.0.15.png)
+
+## Installation
+
+```bash
+npm install virtual-react-json-diff
+# or
+yarn add virtual-react-json-diff
+# or
+pnpm add virtual-react-json-diff
 ```
+
+## Usage
+
+```jsx
 import { VirtualDiffViewer } from "virtual-react-json-diff";
 
 const oldData = { name: "Alice", age: 25 };
@@ -78,86 +89,154 @@ export default function App() {
       oldValue={oldData}
       newValue={newData}
       height={600}
-      className="my-custom-diff"
+      showLineCount={true}
+      showObjectCountStats={false}
     />
   );
 }
 ```
 
----
+## Understanding Diff Configuration
 
-If you need to see or make some calculations on difference objects, you can get the diff data using `getDifferData` callback prop
+The viewer exposes **two different configuration layers**, each serving a distinct purpose.
 
-```
-import { type DiffResult, VirtualDiffViewer } from "virtual-react-json-diff";
+### Quick Mental Model
 
-const [differData, setDifferData] = useState<[DiffResult[], DiffResult[]]>();
+* **`differOptions`** → Controls **how the diff is generated**
+* **`comparisonOptions`** → Controls **what is compared and how values are matched**
 
-<VirtualDiffViewer  {...props}  getDiffData={diffData => setDifferData(diffData)}  />
+### `differOptions` — *How the diff works*
+
+These options are passed directly to the underlying diff engine.
+
+Use them to:
+
+* Choose how arrays are compared (`compare-key`, positional, etc.)
+* Define comparison keys for object arrays
+* Control depth, circular detection, and modification behavior
+
+```jsx
+differOptions={{
+  arrayDiffMethod: "compare-key",
+  compareKey: "id",
+  maxDepth: 999
+}}
 ```
 
-Or if you have a custom Differ or a custom viewer, you can import `Differ` class to create diff objects using your own differ. Moreover you can pass that differ to `VirtualizedDiffViewer`.
+### `comparisonOptions` — *What is considered equal or ignored*
 
-p.s. This is not recommended because you can modify all variables in Differ using `differOptions` prop in Viewer.
+These options affect comparison behavior **without changing the diff structure**.
+
+Use them to:
+
+* Ignore volatile fields (timestamps, metadata)
+* Exclude specific paths
+* Compare values across types
+
+```jsx
+comparisonOptions={{
+  ignoreKeys: ["updatedAt", "__typename"],
+  ignorePaths: ["meta.timestamp"],
+  compareStrategy: "type-aware"
+}}
+```
 
+### Using Both Together
+
+```jsx
+<VirtualDiffViewer
+  oldValue={oldData}
+  newValue={newData}
+  differOptions={{
+    arrayDiffMethod: "compare-key",
+    compareKey: "id"
+  }}
+  comparisonOptions={{
+    ignoreKeys: ["updatedAt"],
+    compareStrategy: "type-aware"
+  }}
+/>
 ```
-import { Differ, VirtualDiffViewer } from "virtual-react-json-diff";
+
+This separation keeps the diff engine flexible while allowing precise control over comparison behavior.
+
+## Props
+
+### Required
+
+| Prop       | Type     | Description                       |
+| ---------- | -------- | --------------------------------- |
+| `oldValue` | `object` | Original JSON object (left side). |
+| `newValue` | `object` | Updated JSON object (right side). |
+
 ---
-  const differOptions: DifferOptions = {
-    showModifications: config.showModifications,
-    arrayDiffMethod: config.arrayDiffMethod,
-  };
-  const differ = new Differ(differOptions);
+
+### Layout & Display
+
+| Prop         | Type     | Default | Description                                     |
+| ------------ | -------- | ------- | ----------------------------------------------- |
+| `height`     | `number` | —       | Height of the diff viewer in pixels.            |
+| `leftTitle`  | `string` | —       | Optional title shown above the left panel.      |
+| `rightTitle` | `string` | —       | Optional title shown above the right panel.     |
+| `className`  | `string` | —       | Custom CSS class applied to the root container. |
 
 ---
 
-// Pass it into Viewer with 'customDiffer' prop
-  <VirtualDiffViewer  {...props}  customDiffer={differ} />
-```
+### Search & Navigation
+
+| Prop                | Type                      | Default | Description                                     |
+| ------------------- | ------------------------- | ------- | ----------------------------------------------- |
+| `hideSearch`        | `boolean`                 | `false` | Hides the search bar when set to `true`.        |
+| `searchTerm`        | `string`                  | `""`    | Initial search term to highlight in the diff.   |
+| `onSearchMatch`     | `(index: number) => void` | —       | Callback fired when a search match is found.    |
+| `showSingleMinimap` | `boolean`                 | `false` | Show a single minimap instead of dual minimaps. |
+| `miniMapWidth`      | `number`                  | `40`    | Width of each minimap in pixels.                |
 
 ---
 
-The component exposes a root container with the class:
+### Statistics & Insights
 
-```
-<div class="diff-viewer-container">...</div>
-```
+| Prop                   | Type      | Default | Description                                                          |
+| ---------------------- | --------- | ------- | -------------------------------------------------------------------- |
+| `showLineCount`        | `boolean` | `false` | Display added, removed, and modified **line** counts.                |
+| `showObjectCountStats` | `boolean` | `false` | Display **object-level** stats (requires compare-key array diffing). |
 
-You can pass your own class name via the className prop to apply custom themes.
+> **Note:** `showObjectCountStats` only works when
+> `differOptions.arrayDiffMethod = "compare-key"` and `compareKey` is provided.
 
-## Props
+---
+
+### Diff Configuration
+
+| Prop                | Type                    | Default            | Description                                                   |
+| ------------------- | ----------------------- | ------------------ | ------------------------------------------------------------- |
+| `differOptions`     | `DifferOptions`         | Engine defaults    | Controls **how the diff is generated** (arrays, depth, keys). |
+| `comparisonOptions` | `DiffComparisonOptions` | —                  | Controls **what is compared and how values match**.           |
+| `inlineDiffOptions` | `InlineDiffOptions`     | `{ mode: "char" }` | Fine-tune inline diff rendering behavior.                     |
+
+---
+
+### Advanced & Utility
+
+| Prop          | Type                                               | Default | Description                                                 |
+| ------------- | -------------------------------------------------- | ------- | ----------------------------------------------------------- |
+| `getDiffData` | `(diffData: [DiffResult[], DiffResult[]]) => void` | —       | Access raw diff results for custom processing or analytics. |
+
+## Styling
 
-| Prop                | Type                                               | Default            | Description                                                            |
-| ------------------- | -------------------------------------------------- | ------------------ | ---------------------------------------------------------------------- |
-| `oldValue`          | `object`                                           | —                  | The original JSON object to compare (left side).                       |
-| `newValue`          | `object`                                           | —                  | The updated JSON object to compare (right side).                       |
-| `height`            | `number`                                           | —                  | Height of the diff viewer in pixels.                                   |
-| `hideSearch`        | `boolean`                                          | `false`            | Hides the search bar if set to `true`.                                 |
-| `searchTerm`        | `string`                                           | `""`               | Initial search keyword to highlight within the diff.                   |
-| `leftTitle`         | `string`                                           | —                  | Optional title to display above the left diff panel.                   |
-| `rightTitle`        | `string`                                           | —                  | Optional title to display above the right diff panel.                  |
-| `onSearchMatch`     | `(index: number) => void`                          | —                  | Callback fired when a search match is found. Receives the match index. |
-| `differOptions`     | `DifferOptions`                                    | `Given Above`      | Advanced options passed to the diffing engine.                         |
-| `showSingleMinimap` | `boolean`                                          | `false`            | If `true`, shows only one minimap instead of two.                      |
-| `className`         | `string`                                           | —                  | Custom CSS class for styling the viewer container.                     |
-| `overScanCount`     | `number`                                           | `28`               | Number of rendered rows outside of the viewport for virtualization     |
-| `miniMapWidth`      | `number`                                           | `40`               | Width of each minimap in pixels.                                       |
-| `inlineDiffOptions` | `InlineDiffOptions`                                | `{'mode': 'char'}` | Options for fine-tuning inline diff rendering.                         |
-| `getDiffData`       | `(diffData: [DiffResult[], DiffResult[]]) => void` | -                  | Get difference data and make operations                                |
-| `customDiffer`      | `Differ`                                           | -                  | Pass custom differ - not recommended                                   |
+The component exposes a root container with class `diff-viewer-container`. You can pass your own class name via the `className` prop to apply custom themes.
 
 ## 🙌 Acknowledgements
 
-Built on top of the awesome json-diff-kit.
+Built on top of the awesome [json-diff-kit](https://www.npmjs.com/package/json-diff-kit).
 
-## 📄 License
+## License
 
 MIT © Utku Akyüz
 
-## 🛠️ Contributing
+## Contributing
 
 Pull requests, suggestions, and issues are welcome!
-Check out the issues or open a PR.
 
 [npm-url]: https://npmjs.org/package/virtual-react-json-diff
 [npm-image]: https://img.shields.io/npm/v/virtual-react-json-diff.svg