You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: docs/examples/table-diff/index.mdx
+1-1Lines changed: 1 addition & 1 deletion
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,6 +1,6 @@
1
1
# Table Diff
2
2
3
-
This example demonstrates how `data-diff-key` preserves table structure while highlighting changes. Notice how only CSS classes are added to cells - no new elements are inserted that would break the table layout.
3
+
This example demonstrates how `data-diff-key` preserves table structure while highlighting changes. Notice how only `data-diff-status` attributes are added to cells—no new elements are inserted that would break the table layout.
**Optional attribute to control diffing behavior.**
62
62
63
-
By default, when text content changes, elements with `data-diff-key` are marked as `diff-modified`. The `data-diff-mode` attribute allows you to specify different diffing behaviors for more control.
63
+
By default, when text content changes, elements with `data-diff-key` are marked with `data-diff-status="modified"`. The `data-diff-mode` attribute allows you to specify different diffing behaviors for more control.
64
64
65
65
### element
66
66
67
-
Use `data-diff-mode="element"` to explicitly mark the element for atomic element diffing. When content changes, the old element is shown as `diff-removed` and the new element is shown as `diff-added`.
67
+
Use `data-diff-mode="element"` to explicitly mark the element for atomic element diffing. When content changes, the old element is shown with `data-diff-status="removed"` and the new element is shown with `data-diff-status="added"`.
68
68
69
69
```html
70
70
<!-- Before -->
@@ -83,7 +83,7 @@ Use `data-diff-mode="element"` to explicitly mark the element for atomic element
Notice how the word-level diffing breaks the HTML structure by inserting `<span>` elements, making the result invalid HTML. The correct approach is to use `data-diff-mode="element"` or no mode at all for complex components.
@@ -181,7 +181,7 @@ Notice how the word-level diffing breaks the HTML structure by inserting `<span>
181
181
182
182
**Optional attribute to show removed elements in the diff result.**
183
183
184
-
By default, when elements are removed, they are not inserted into the diff result - only existing elements get CSS classes. The `data-diff-show-when-removed` attribute tells the diff engine that this element should be displayed with strikethrough styling when removed.
184
+
By default, when elements are removed, they are not inserted into the diff result—only existing elements receive diff attributes. The `data-diff-show-when-removed` attribute tells the diff engine that this element should be displayed with strikethrough styling when removed.
185
185
186
186
### When to use data-diff-show-when-removed
187
187
@@ -234,7 +234,7 @@ By default, when elements are removed, they are not inserted into the diff resul
Copy file name to clipboardExpand all lines: docs/guide/how-it-works.mdx
+6-6Lines changed: 6 additions & 6 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -43,18 +43,18 @@ graph TD
43
43
44
44
The diagram above shows two approaches to building diff views. The **Custom Diff** approach (🟧) requires building and maintaining specialized diff logic and custom renderers for each document type. This means more development effort and one-off solutions that don't generalize.
45
45
46
-
In contrast, the **HTML Diff** approach (🟩) leverages the fact that most applications ultimately render to HTML. Rather than building custom diff logic, it works directly with the rendered HTML output. This requires no adjustments from developers in terms of creating diffed data structures or modifying renderers - it simply takes your existing HTML and adds CSS classes to highlight changes. This approach generalizes across any application UI that renders to HTML, making it a reusable solution.
46
+
In contrast, the **HTML Diff** approach (🟩) leverages the fact that most applications ultimately render to HTML. Rather than building custom diff logic, it works directly with the rendered HTML output. This requires no adjustments from developers in terms of creating diffed data structures or modifying renderers—it simply takes your existing HTML and adds `data-diff-status` attributes to highlight changes. This approach generalizes across any application UI that renders to HTML, making it a reusable solution.
47
47
48
48
## How Elements Are Tracked
49
49
50
50
HTML diff uses `data-diff-key` attributes to track elements across before/after states. Here's what happens:
51
51
52
52
### Structure Preservation
53
53
54
-
Adding `data-diff-key` to elements **only adds CSS classes** - it doesn't modify the HTML structure:
54
+
Adding `data-diff-key` to elements **only adds diff attributes**—it doesn't modify the HTML structure:
55
55
56
56
- ✅ **No structural changes**: Elements keep their original structure, attributes, and content
57
-
- ✅ **Only CSS classes added**: Elements get `diff-added`, `diff-modified`, or `diff-removed` classes
57
+
- ✅ **Only `data-diff-status`added**: Elements get `data-diff-status="added"`, `"modified"`, or `"removed"`
58
58
- ✅ **Preserves layout**: No new elements inserted, so CSS layouts (tables, flexbox, grid) remain intact
59
59
60
60
<Showcase
@@ -78,7 +78,7 @@ Adding `data-diff-key` to elements **only adds CSS classes** - it doesn't modify
78
78
border: 1px solid #ccc;
79
79
padding: 8px;
80
80
}
81
-
.diff-modified {
81
+
[data-diff-status="modified"] {
82
82
background-color: #fff3cd;
83
83
color: #856404;
84
84
}
@@ -88,15 +88,15 @@ Adding `data-diff-key` to elements **only adds CSS classes** - it doesn't modify
88
88
Notice how in the diff result:
89
89
90
90
- Table structure remains intact (no broken layout)
91
-
- Only CSS classes are added to the `<td>` elements
91
+
- Only the `data-diff-status` attribute is added to the `<td>` elements
92
92
- No wrapper elements or structural modifications
93
93
94
94
### Diffing Modes
95
95
96
96
The progression of diffing granularity:
97
97
98
98
1.**No attributes**: No diffing, HTML unchanged
99
-
2.**`data-diff-key` only**: CSS classes added to changed elements
99
+
2.**`data-diff-key` only**: `data-diff-status` attributes added to changed elements
100
100
3.**`data-diff-key` + `data-diff-mode="element"`**: Explicit atomic element diffing (entire element marked as updated)
101
101
4.**`data-diff-key` + `data-diff-mode="words"`**: Granular word-level diffing with spans
/_ Only these 3 classes needed for diff highlighting _/
228
-
229
-
.diff-added { color: #22c55e }
230
-
.diff-modified { color: #f59e0b }
231
-
.diff-removed { color: #ef4444 }`}
227
+
/* Only these selectors needed for diff highlighting */
228
+
[data-diff-status='added'] { color: #22c55e }
229
+
[data-diff-status='modified'] { color: #f59e0b }
230
+
[data-diff-status='removed'] { color: #ef4444 }`}
232
231
/>
233
232
234
-
Notice how your existing `.my-text` styles (large, bold typography) are preserved. Only the diff highlighting is added on top based on your CSS diff classes.
233
+
Notice how your existing `.my-text` styles (large, bold typography) are preserved. Only the diff highlighting is added on top based on your CSS targeting `data-diff-status`.
235
234
236
235
### Step 4: Make diffs more granular (optional)
237
236
@@ -252,9 +251,9 @@ For word-level highlighting within text elements, add the `data-diff-mode="words
Notice how `data-diff-mode="words"` enables word-level highlighting instead of highlighting the entire element. Learn more in the [attributes guide](/guide/attributes).
Copy file name to clipboardExpand all lines: docs/guide/interactivity.mdx
+16-14Lines changed: 16 additions & 14 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,6 +1,6 @@
1
1
# Adding Interactivity
2
2
3
-
The HTML diff engine provides the foundation for building interactive diff experiences. By combining the `data-diff-key` attributes with CSS classes applied by the diff engine, you can create rich interactive features like hover cards, blame views, and detailed change histories.
3
+
The HTML diff engine provides the foundation for building interactive diff experiences. By combining the `data-diff-key` attributes with the `data-diff-status` markers applied by the diff engine, you can create rich interactive features like hover cards, blame views, and detailed change histories.
4
4
5
5
## Live Example
6
6
@@ -12,21 +12,21 @@ import InteractiveShowcase from "../components/interactive-showcase";
12
12
13
13
## Understanding the Data Structure
14
14
15
-
When the diff engine processes your HTML, it adds CSS classes to elements and preserves the `data-diff-key` attributes. This gives you everything needed to build interactive features:
15
+
When the diff engine processes your HTML, it adds `data-diff-status` attributes to elements and preserves the `data-diff-key` attributes. This gives you everything needed to build interactive features:
Welcome to our <spandata-diff-status="removed">comprehensive</span>
21
+
<spandata-diff-status="added">updated</span> guide for new
22
+
<spandata-diff-status="removed">users</span
23
+
><spandata-diff-status="added">developers</span>.
24
24
</p>
25
25
```
26
26
27
27
## Building Interactive Features
28
28
29
-
The key insight is that after calling `renderHtmlDiff()`, you can query the result for elements with diff classes and their `data-diff-key` attributes to add any interactivity you want:
29
+
The key insight is that after calling `renderHtmlDiff()`, you can query the result for elements with diff status attributes and their `data-diff-key` attributes to add any interactivity you want:
0 commit comments