From ccd92a81f482d7dcf5a41c04509f111da704534e Mon Sep 17 00:00:00 2001
From: Vaceslav Ustinov <vaceslav.ustinov@gmail.com>
Date: Tue, 23 Dec 2025 18:50:38 +0100
Subject: [PATCH 1/4] feat: add text replacement lookup table for HTML entities
 (#64)

Add configurable text replacement feature to transform HTML entities and
custom patterns in template values before Word processing.

- Add TextReplacements static class with HtmlEntities preset
- Add TextReplacements property to PlaceholderReplacementOptions
- Integrate text replacement into PlaceholderVisitor pipeline
- Support <br>, <br/>, <br />, &nbsp;, &lt;, &gt;, &amp;, &quot;, &apos;
- Allow custom user-defined replacement mappings

ADR: Chose lookup table approach over HTML parser for simplicity,
flexibility (custom patterns), predictability, and extensibility.
Paired tags like <b>text</b> can use existing markdown support.

Closes #64
---
 .../TextReplacementsIntegrationTests.cs       | 517 ++++++++++++++++++
 .../Replacements/TextReplacementsTests.cs     | 313 +++++++++++
 .../Core/PlaceholderReplacementOptions.cs     |  37 ++
 .../Replacements/TextReplacements.cs          | 100 ++++
 .../Visitors/PlaceholderVisitor.cs            |   5 +
 5 files changed, 972 insertions(+)
 create mode 100644 TriasDev.Templify.Tests/Integration/TextReplacementsIntegrationTests.cs
 create mode 100644 TriasDev.Templify.Tests/Replacements/TextReplacementsTests.cs
 create mode 100644 TriasDev.Templify/Replacements/TextReplacements.cs

diff --git a/TriasDev.Templify.Tests/Integration/TextReplacementsIntegrationTests.cs b/TriasDev.Templify.Tests/Integration/TextReplacementsIntegrationTests.cs
new file mode 100644
index 0000000..a642801
--- /dev/null
+++ b/TriasDev.Templify.Tests/Integration/TextReplacementsIntegrationTests.cs
@@ -0,0 +1,517 @@
+// Copyright (c) 2025 TriasDev GmbH & Co. KG
+// Licensed under the MIT License. See LICENSE file in the project root for full license information.
+
+using DocumentFormat.OpenXml.Wordprocessing;
+using TriasDev.Templify.Core;
+using TriasDev.Templify.Tests.Helpers;
+using TriasDev.Templify.Replacements;
+
+namespace TriasDev.Templify.Tests.Integration;
+
+/// <summary>
+/// Integration tests for text replacement functionality.
+/// Tests that HTML entities and custom text patterns in variable values
+/// are correctly transformed before being inserted into Word documents.
+/// </summary>
+public sealed class TextReplacementsIntegrationTests
+{
+    [Fact]
+    public void ProcessTemplate_HtmlLineBreak_RendersAsWordBreak()
+    {
+        // Arrange
+        DocumentBuilder builder = new DocumentBuilder();
+        builder.AddParagraph("{{Message}}");
+
+        MemoryStream templateStream = builder.ToStream();
+
+        Dictionary<string, object> data = new Dictionary<string, object>
+        {
+            ["Message"] = "Line 1<br>Line 2"
+        };
+
+        PlaceholderReplacementOptions options = new PlaceholderReplacementOptions
+        {
+            TextReplacements = TextReplacements.HtmlEntities
+        };
+
+        DocumentTemplateProcessor processor = new DocumentTemplateProcessor(options);
+        MemoryStream outputStream = new MemoryStream();
+
+        // Act
+        ProcessingResult result = processor.ProcessTemplate(templateStream, outputStream, data);
+
+        // Assert
+        Assert.True(result.IsSuccess);
+        Assert.Equal(1, result.ReplacementCount);
+
+        using DocumentVerifier verifier = new DocumentVerifier(outputStream);
+        string text = verifier.GetParagraphText(0);
+        Assert.Equal("Line 1Line 2", text); // Text without break, concatenated
+
+        // Verify Break element exists
+        Paragraph paragraph = verifier.GetParagraph(0);
+        List<Break> breaks = paragraph.Descendants<Break>().ToList();
+        Assert.Single(breaks);
+    }
+
+    [Theory]
+    [InlineData("<br>")]
+    [InlineData("<br/>")]
+    [InlineData("<br />")]
+    [InlineData("<BR>")]
+    [InlineData("<BR/>")]
+    [InlineData("<BR />")]
+    public void ProcessTemplate_AllLineBreakVariations_RenderAsWordBreaks(string brTag)
+    {
+        // Arrange
+        DocumentBuilder builder = new DocumentBuilder();
+        builder.AddParagraph("{{Message}}");
+
+        MemoryStream templateStream = builder.ToStream();
+
+        Dictionary<string, object> data = new Dictionary<string, object>
+        {
+            ["Message"] = $"Before{brTag}After"
+        };
+
+        PlaceholderReplacementOptions options = new PlaceholderReplacementOptions
+        {
+            TextReplacements = TextReplacements.HtmlEntities
+        };
+
+        DocumentTemplateProcessor processor = new DocumentTemplateProcessor(options);
+        MemoryStream outputStream = new MemoryStream();
+
+        // Act
+        ProcessingResult result = processor.ProcessTemplate(templateStream, outputStream, data);
+
+        // Assert
+        Assert.True(result.IsSuccess);
+
+        using DocumentVerifier verifier = new DocumentVerifier(outputStream);
+        Paragraph paragraph = verifier.GetParagraph(0);
+        List<Break> breaks = paragraph.Descendants<Break>().ToList();
+        Assert.Single(breaks);
+
+        string text = verifier.GetParagraphText(0);
+        Assert.Equal("BeforeAfter", text);
+    }
+
+    [Fact]
+    public void ProcessTemplate_MultipleHtmlLineBreaks_RendersMultipleBreaks()
+    {
+        // Arrange
+        DocumentBuilder builder = new DocumentBuilder();
+        builder.AddParagraph("{{Message}}");
+
+        MemoryStream templateStream = builder.ToStream();
+
+        Dictionary<string, object> data = new Dictionary<string, object>
+        {
+            ["Message"] = "Line 1<br>Line 2<br/>Line 3<br />Line 4"
+        };
+
+        PlaceholderReplacementOptions options = new PlaceholderReplacementOptions
+        {
+            TextReplacements = TextReplacements.HtmlEntities
+        };
+
+        DocumentTemplateProcessor processor = new DocumentTemplateProcessor(options);
+        MemoryStream outputStream = new MemoryStream();
+
+        // Act
+        ProcessingResult result = processor.ProcessTemplate(templateStream, outputStream, data);
+
+        // Assert
+        Assert.True(result.IsSuccess);
+
+        using DocumentVerifier verifier = new DocumentVerifier(outputStream);
+        Paragraph paragraph = verifier.GetParagraph(0);
+        List<Break> breaks = paragraph.Descendants<Break>().ToList();
+        Assert.Equal(3, breaks.Count);
+    }
+
+    [Fact]
+    public void ProcessTemplate_HtmlEntities_ReplacedCorrectly()
+    {
+        // Arrange
+        DocumentBuilder builder = new DocumentBuilder();
+        builder.AddParagraph("{{Message}}");
+
+        MemoryStream templateStream = builder.ToStream();
+
+        Dictionary<string, object> data = new Dictionary<string, object>
+        {
+            ["Message"] = "5 &lt; 10 &amp; 10 &gt; 5"
+        };
+
+        PlaceholderReplacementOptions options = new PlaceholderReplacementOptions
+        {
+            TextReplacements = TextReplacements.HtmlEntities
+        };
+
+        DocumentTemplateProcessor processor = new DocumentTemplateProcessor(options);
+        MemoryStream outputStream = new MemoryStream();
+
+        // Act
+        ProcessingResult result = processor.ProcessTemplate(templateStream, outputStream, data);
+
+        // Assert
+        Assert.True(result.IsSuccess);
+
+        using DocumentVerifier verifier = new DocumentVerifier(outputStream);
+        string text = verifier.GetParagraphText(0);
+        Assert.Equal("5 < 10 & 10 > 5", text);
+    }
+
+    [Fact]
+    public void ProcessTemplate_NonBreakingSpace_ReplacedCorrectly()
+    {
+        // Arrange
+        DocumentBuilder builder = new DocumentBuilder();
+        builder.AddParagraph("{{Message}}");
+
+        MemoryStream templateStream = builder.ToStream();
+
+        Dictionary<string, object> data = new Dictionary<string, object>
+        {
+            ["Message"] = "Hello&nbsp;World"
+        };
+
+        PlaceholderReplacementOptions options = new PlaceholderReplacementOptions
+        {
+            TextReplacements = TextReplacements.HtmlEntities
+        };
+
+        DocumentTemplateProcessor processor = new DocumentTemplateProcessor(options);
+        MemoryStream outputStream = new MemoryStream();
+
+        // Act
+        ProcessingResult result = processor.ProcessTemplate(templateStream, outputStream, data);
+
+        // Assert
+        Assert.True(result.IsSuccess);
+
+        using DocumentVerifier verifier = new DocumentVerifier(outputStream);
+        string text = verifier.GetParagraphText(0);
+        Assert.Equal("Hello\u00A0World", text);
+    }
+
+    [Fact]
+    public void ProcessTemplate_QuotesAndApostrophes_ReplacedCorrectly()
+    {
+        // Arrange
+        DocumentBuilder builder = new DocumentBuilder();
+        builder.AddParagraph("{{Message}}");
+
+        MemoryStream templateStream = builder.ToStream();
+
+        Dictionary<string, object> data = new Dictionary<string, object>
+        {
+            ["Message"] = "He said &quot;Hello&quot; and &apos;Goodbye&apos;"
+        };
+
+        PlaceholderReplacementOptions options = new PlaceholderReplacementOptions
+        {
+            TextReplacements = TextReplacements.HtmlEntities
+        };
+
+        DocumentTemplateProcessor processor = new DocumentTemplateProcessor(options);
+        MemoryStream outputStream = new MemoryStream();
+
+        // Act
+        ProcessingResult result = processor.ProcessTemplate(templateStream, outputStream, data);
+
+        // Assert
+        Assert.True(result.IsSuccess);
+
+        using DocumentVerifier verifier = new DocumentVerifier(outputStream);
+        string text = verifier.GetParagraphText(0);
+        Assert.Equal("He said \"Hello\" and 'Goodbye'", text);
+    }
+
+    [Fact]
+    public void ProcessTemplate_WithoutTextReplacements_HtmlTagsRemainLiteral()
+    {
+        // Arrange
+        DocumentBuilder builder = new DocumentBuilder();
+        builder.AddParagraph("{{Message}}");
+
+        MemoryStream templateStream = builder.ToStream();
+
+        Dictionary<string, object> data = new Dictionary<string, object>
+        {
+            ["Message"] = "Line 1<br>Line 2"
+        };
+
+        // No TextReplacements option set
+        DocumentTemplateProcessor processor = new DocumentTemplateProcessor();
+        MemoryStream outputStream = new MemoryStream();
+
+        // Act
+        ProcessingResult result = processor.ProcessTemplate(templateStream, outputStream, data);
+
+        // Assert
+        Assert.True(result.IsSuccess);
+
+        using DocumentVerifier verifier = new DocumentVerifier(outputStream);
+        string text = verifier.GetParagraphText(0);
+        Assert.Equal("Line 1<br>Line 2", text); // <br> remains as literal text
+
+        // No Break elements should exist
+        Paragraph paragraph = verifier.GetParagraph(0);
+        List<Break> breaks = paragraph.Descendants<Break>().ToList();
+        Assert.Empty(breaks);
+    }
+
+    [Fact]
+    public void ProcessTemplate_CustomReplacements_WorkCorrectly()
+    {
+        // Arrange
+        DocumentBuilder builder = new DocumentBuilder();
+        builder.AddParagraph("{{Message}}");
+
+        MemoryStream templateStream = builder.ToStream();
+
+        Dictionary<string, object> data = new Dictionary<string, object>
+        {
+            ["Message"] = "Welcome to COMPANY_NAME! Contact us at SUPPORT_EMAIL."
+        };
+
+        PlaceholderReplacementOptions options = new PlaceholderReplacementOptions
+        {
+            TextReplacements = new Dictionary<string, string>
+            {
+                ["COMPANY_NAME"] = "Acme Corp",
+                ["SUPPORT_EMAIL"] = "support@acme.com"
+            }
+        };
+
+        DocumentTemplateProcessor processor = new DocumentTemplateProcessor(options);
+        MemoryStream outputStream = new MemoryStream();
+
+        // Act
+        ProcessingResult result = processor.ProcessTemplate(templateStream, outputStream, data);
+
+        // Assert
+        Assert.True(result.IsSuccess);
+
+        using DocumentVerifier verifier = new DocumentVerifier(outputStream);
+        string text = verifier.GetParagraphText(0);
+        Assert.Equal("Welcome to Acme Corp! Contact us at support@acme.com.", text);
+    }
+
+    [Fact]
+    public void ProcessTemplate_CombinedPresetAndCustomReplacements_WorkCorrectly()
+    {
+        // Arrange
+        DocumentBuilder builder = new DocumentBuilder();
+        builder.AddParagraph("{{Message}}");
+
+        MemoryStream templateStream = builder.ToStream();
+
+        Dictionary<string, object> data = new Dictionary<string, object>
+        {
+            ["Message"] = "COMPANY_NAME &amp; Partners<br>Contact: SUPPORT_EMAIL"
+        };
+
+        // Combine HtmlEntities preset with custom replacements
+        var replacements = new Dictionary<string, string>(TextReplacements.HtmlEntities)
+        {
+            ["COMPANY_NAME"] = "Acme Corp",
+            ["SUPPORT_EMAIL"] = "support@acme.com"
+        };
+
+        PlaceholderReplacementOptions options = new PlaceholderReplacementOptions
+        {
+            TextReplacements = replacements
+        };
+
+        DocumentTemplateProcessor processor = new DocumentTemplateProcessor(options);
+        MemoryStream outputStream = new MemoryStream();
+
+        // Act
+        ProcessingResult result = processor.ProcessTemplate(templateStream, outputStream, data);
+
+        // Assert
+        Assert.True(result.IsSuccess);
+
+        using DocumentVerifier verifier = new DocumentVerifier(outputStream);
+        string text = verifier.GetParagraphText(0);
+        Assert.Equal("Acme Corp & PartnersContact: support@acme.com", text);
+
+        // Verify Break element from <br>
+        Paragraph paragraph = verifier.GetParagraph(0);
+        List<Break> breaks = paragraph.Descendants<Break>().ToList();
+        Assert.Single(breaks);
+    }
+
+    [Fact]
+    public void ProcessTemplate_HtmlBreaksWithMarkdown_BothWorkTogether()
+    {
+        // Arrange
+        DocumentBuilder builder = new DocumentBuilder();
+        builder.AddParagraph("{{Message}}");
+
+        MemoryStream templateStream = builder.ToStream();
+
+        Dictionary<string, object> data = new Dictionary<string, object>
+        {
+            ["Message"] = "**Bold line**<br>*Italic line*"
+        };
+
+        PlaceholderReplacementOptions options = new PlaceholderReplacementOptions
+        {
+            TextReplacements = TextReplacements.HtmlEntities
+        };
+
+        DocumentTemplateProcessor processor = new DocumentTemplateProcessor(options);
+        MemoryStream outputStream = new MemoryStream();
+
+        // Act
+        ProcessingResult result = processor.ProcessTemplate(templateStream, outputStream, data);
+
+        // Assert
+        Assert.True(result.IsSuccess);
+
+        using DocumentVerifier verifier = new DocumentVerifier(outputStream);
+        Paragraph paragraph = verifier.GetParagraph(0);
+
+        // Verify break exists
+        List<Break> breaks = paragraph.Descendants<Break>().ToList();
+        Assert.Single(breaks);
+
+        // Verify bold formatting
+        List<Run> runs = verifier.GetRuns(0);
+        Run? boldRun = runs.FirstOrDefault(r => r.InnerText == "Bold line");
+        Assert.NotNull(boldRun);
+        Assert.NotNull(boldRun.RunProperties?.GetFirstChild<Bold>());
+
+        // Verify italic formatting
+        Run? italicRun = runs.FirstOrDefault(r => r.InnerText == "Italic line");
+        Assert.NotNull(italicRun);
+        Assert.NotNull(italicRun.RunProperties?.GetFirstChild<Italic>());
+    }
+
+    [Fact]
+    public void ProcessTemplate_HtmlBreaksInLoop_WorksCorrectly()
+    {
+        // Arrange
+        DocumentBuilder builder = new DocumentBuilder();
+        builder.AddParagraph("{{#foreach Items}}");
+        builder.AddParagraph("{{.}}");
+        builder.AddParagraph("{{/foreach}}");
+
+        MemoryStream templateStream = builder.ToStream();
+
+        Dictionary<string, object> data = new Dictionary<string, object>
+        {
+            ["Items"] = new List<string>
+            {
+                "Item 1<br>Detail 1",
+                "Item 2<br>Detail 2"
+            }
+        };
+
+        PlaceholderReplacementOptions options = new PlaceholderReplacementOptions
+        {
+            TextReplacements = TextReplacements.HtmlEntities
+        };
+
+        DocumentTemplateProcessor processor = new DocumentTemplateProcessor(options);
+        MemoryStream outputStream = new MemoryStream();
+
+        // Act
+        ProcessingResult result = processor.ProcessTemplate(templateStream, outputStream, data);
+
+        // Assert
+        Assert.True(result.IsSuccess);
+
+        using DocumentVerifier verifier = new DocumentVerifier(outputStream);
+
+        // Each paragraph should have a break
+        Paragraph para0 = verifier.GetParagraph(0);
+        Assert.Single(para0.Descendants<Break>());
+
+        Paragraph para1 = verifier.GetParagraph(1);
+        Assert.Single(para1.Descendants<Break>());
+    }
+
+    [Fact]
+    public void ProcessTemplate_PreservesFormatting_WithHtmlReplacements()
+    {
+        // Arrange
+        DocumentBuilder builder = new DocumentBuilder();
+        RunProperties boldFormatting = DocumentBuilder.CreateFormatting(bold: true);
+        builder.AddParagraph("{{Message}}", boldFormatting);
+
+        MemoryStream templateStream = builder.ToStream();
+
+        Dictionary<string, object> data = new Dictionary<string, object>
+        {
+            ["Message"] = "Line 1<br>Line 2"
+        };
+
+        PlaceholderReplacementOptions options = new PlaceholderReplacementOptions
+        {
+            TextReplacements = TextReplacements.HtmlEntities
+        };
+
+        DocumentTemplateProcessor processor = new DocumentTemplateProcessor(options);
+        MemoryStream outputStream = new MemoryStream();
+
+        // Act
+        ProcessingResult result = processor.ProcessTemplate(templateStream, outputStream, data);
+
+        // Assert
+        Assert.True(result.IsSuccess);
+
+        using DocumentVerifier verifier = new DocumentVerifier(outputStream);
+        List<Run> runs = verifier.GetRuns(0);
+
+        // All text runs should be bold
+        Assert.All(
+            runs.Where(r => !string.IsNullOrEmpty(r.InnerText)),
+            run =>
+            {
+                RunProperties? props = run.RunProperties;
+                Assert.NotNull(props);
+                Assert.NotNull(props.GetFirstChild<Bold>());
+            });
+    }
+
+    [Fact]
+    public void ProcessTemplate_MixedHtmlAndNativeNewlines_BothWork()
+    {
+        // Arrange
+        DocumentBuilder builder = new DocumentBuilder();
+        builder.AddParagraph("{{Message}}");
+
+        MemoryStream templateStream = builder.ToStream();
+
+        // Mix of HTML <br> and native \n newlines
+        Dictionary<string, object> data = new Dictionary<string, object>
+        {
+            ["Message"] = "HTML break<br>Native newline\nAnother line"
+        };
+
+        PlaceholderReplacementOptions options = new PlaceholderReplacementOptions
+        {
+            TextReplacements = TextReplacements.HtmlEntities
+        };
+
+        DocumentTemplateProcessor processor = new DocumentTemplateProcessor(options);
+        MemoryStream outputStream = new MemoryStream();
+
+        // Act
+        ProcessingResult result = processor.ProcessTemplate(templateStream, outputStream, data);
+
+        // Assert
+        Assert.True(result.IsSuccess);
+
+        using DocumentVerifier verifier = new DocumentVerifier(outputStream);
+        Paragraph paragraph = verifier.GetParagraph(0);
+        List<Break> breaks = paragraph.Descendants<Break>().ToList();
+        Assert.Equal(2, breaks.Count); // 1 from <br>, 1 from \n
+    }
+}
diff --git a/TriasDev.Templify.Tests/Replacements/TextReplacementsTests.cs b/TriasDev.Templify.Tests/Replacements/TextReplacementsTests.cs
new file mode 100644
index 0000000..d9f7510
--- /dev/null
+++ b/TriasDev.Templify.Tests/Replacements/TextReplacementsTests.cs
@@ -0,0 +1,313 @@
+// Copyright (c) 2025 TriasDev GmbH & Co. KG
+// Licensed under the MIT License. See LICENSE file in the project root for full license information.
+
+using TriasDev.Templify.Replacements;
+
+namespace TriasDev.Templify.Tests.Replacements;
+
+public class TextReplacementsTests
+{
+    #region HtmlEntities Preset Tests
+
+    [Fact]
+    public void HtmlEntities_ContainsExpectedReplacements()
+    {
+        // Act
+        var entities = TextReplacements.HtmlEntities;
+
+        // Assert
+        Assert.Contains("<br>", entities.Keys);
+        Assert.Contains("<br/>", entities.Keys);
+        Assert.Contains("<br />", entities.Keys);
+        Assert.Contains("&nbsp;", entities.Keys);
+        Assert.Contains("&lt;", entities.Keys);
+        Assert.Contains("&gt;", entities.Keys);
+        Assert.Contains("&amp;", entities.Keys);
+        Assert.Contains("&quot;", entities.Keys);
+        Assert.Contains("&apos;", entities.Keys);
+    }
+
+    [Theory]
+    [InlineData("<br>", "\n")]
+    [InlineData("<br/>", "\n")]
+    [InlineData("<br />", "\n")]
+    [InlineData("<BR>", "\n")]
+    [InlineData("<BR/>", "\n")]
+    [InlineData("<BR />", "\n")]
+    public void HtmlEntities_LineBreakVariations_MapToNewline(string input, string expected)
+    {
+        // Act
+        var entities = TextReplacements.HtmlEntities;
+
+        // Assert
+        Assert.Equal(expected, entities[input]);
+    }
+
+    [Fact]
+    public void HtmlEntities_Nbsp_MapsToNonBreakingSpace()
+    {
+        // Act
+        var entities = TextReplacements.HtmlEntities;
+
+        // Assert
+        Assert.Equal("\u00A0", entities["&nbsp;"]);
+    }
+
+    [Theory]
+    [InlineData("&lt;", "<")]
+    [InlineData("&gt;", ">")]
+    [InlineData("&amp;", "&")]
+    [InlineData("&quot;", "\"")]
+    [InlineData("&apos;", "'")]
+    public void HtmlEntities_CommonEntities_MapCorrectly(string input, string expected)
+    {
+        // Act
+        var entities = TextReplacements.HtmlEntities;
+
+        // Assert
+        Assert.Equal(expected, entities[input]);
+    }
+
+    #endregion
+
+    #region Apply Method Tests
+
+    [Fact]
+    public void Apply_NullInput_ReturnsNull()
+    {
+        // Arrange
+        string? input = null;
+        var replacements = TextReplacements.HtmlEntities;
+
+        // Act
+        string result = TextReplacements.Apply(input!, replacements);
+
+        // Assert
+        Assert.Null(result);
+    }
+
+    [Fact]
+    public void Apply_EmptyInput_ReturnsEmpty()
+    {
+        // Arrange
+        string input = "";
+        var replacements = TextReplacements.HtmlEntities;
+
+        // Act
+        string result = TextReplacements.Apply(input, replacements);
+
+        // Assert
+        Assert.Equal("", result);
+    }
+
+    [Fact]
+    public void Apply_NullReplacements_ReturnsInputUnchanged()
+    {
+        // Arrange
+        string input = "Hello<br>World";
+        Dictionary<string, string>? replacements = null;
+
+        // Act
+        string result = TextReplacements.Apply(input, replacements);
+
+        // Assert
+        Assert.Equal("Hello<br>World", result);
+    }
+
+    [Fact]
+    public void Apply_EmptyReplacements_ReturnsInputUnchanged()
+    {
+        // Arrange
+        string input = "Hello<br>World";
+        var replacements = new Dictionary<string, string>();
+
+        // Act
+        string result = TextReplacements.Apply(input, replacements);
+
+        // Assert
+        Assert.Equal("Hello<br>World", result);
+    }
+
+    [Fact]
+    public void Apply_NoMatchingPatterns_ReturnsInputUnchanged()
+    {
+        // Arrange
+        string input = "Hello World";
+        var replacements = TextReplacements.HtmlEntities;
+
+        // Act
+        string result = TextReplacements.Apply(input, replacements);
+
+        // Assert
+        Assert.Equal("Hello World", result);
+    }
+
+    [Fact]
+    public void Apply_SingleLineBreak_ReplacesCorrectly()
+    {
+        // Arrange
+        string input = "Hello<br>World";
+        var replacements = TextReplacements.HtmlEntities;
+
+        // Act
+        string result = TextReplacements.Apply(input, replacements);
+
+        // Assert
+        Assert.Equal("Hello\nWorld", result);
+    }
+
+    [Fact]
+    public void Apply_MultipleLineBreaks_ReplacesAll()
+    {
+        // Arrange
+        string input = "Line1<br>Line2<br/>Line3<br />Line4";
+        var replacements = TextReplacements.HtmlEntities;
+
+        // Act
+        string result = TextReplacements.Apply(input, replacements);
+
+        // Assert
+        Assert.Equal("Line1\nLine2\nLine3\nLine4", result);
+    }
+
+    [Fact]
+    public void Apply_HtmlEntities_ReplacesAllCorrectly()
+    {
+        // Arrange
+        string input = "5 &lt; 10 &amp; 10 &gt; 5";
+        var replacements = TextReplacements.HtmlEntities;
+
+        // Act
+        string result = TextReplacements.Apply(input, replacements);
+
+        // Assert
+        Assert.Equal("5 < 10 & 10 > 5", result);
+    }
+
+    [Fact]
+    public void Apply_MixedContent_ReplacesAllPatterns()
+    {
+        // Arrange
+        string input = "Hello&nbsp;World<br>&lt;test&gt;";
+        var replacements = TextReplacements.HtmlEntities;
+
+        // Act
+        string result = TextReplacements.Apply(input, replacements);
+
+        // Assert
+        Assert.Equal("Hello\u00A0World\n<test>", result);
+    }
+
+    [Fact]
+    public void Apply_QuotesAndApostrophes_ReplacesCorrectly()
+    {
+        // Arrange
+        string input = "He said &quot;Hello&quot; and &apos;Goodbye&apos;";
+        var replacements = TextReplacements.HtmlEntities;
+
+        // Act
+        string result = TextReplacements.Apply(input, replacements);
+
+        // Assert
+        Assert.Equal("He said \"Hello\" and 'Goodbye'", result);
+    }
+
+    [Fact]
+    public void Apply_CaseSensitiveLineBreaks_UppercaseReplaced()
+    {
+        // Arrange - HtmlEntities includes uppercase variants
+        string input = "Hello<BR>World<BR/>Test<BR />End";
+        var replacements = TextReplacements.HtmlEntities;
+
+        // Act
+        string result = TextReplacements.Apply(input, replacements);
+
+        // Assert
+        Assert.Equal("Hello\nWorld\nTest\nEnd", result);
+    }
+
+    [Fact]
+    public void Apply_CustomReplacements_WorksCorrectly()
+    {
+        // Arrange
+        string input = "Hello COMPANY_NAME, welcome to PRODUCT!";
+        var replacements = new Dictionary<string, string>
+        {
+            ["COMPANY_NAME"] = "Acme Corp",
+            ["PRODUCT"] = "Templify"
+        };
+
+        // Act
+        string result = TextReplacements.Apply(input, replacements);
+
+        // Assert
+        Assert.Equal("Hello Acme Corp, welcome to Templify!", result);
+    }
+
+    [Fact]
+    public void Apply_CombinedPresetAndCustom_WorksCorrectly()
+    {
+        // Arrange
+        string input = "Hello<br>COMPANY_NAME";
+        var replacements = new Dictionary<string, string>(TextReplacements.HtmlEntities)
+        {
+            ["COMPANY_NAME"] = "Acme Corp"
+        };
+
+        // Act
+        string result = TextReplacements.Apply(input, replacements);
+
+        // Assert
+        Assert.Equal("Hello\nAcme Corp", result);
+    }
+
+    [Fact]
+    public void Apply_ChainedReplacements_RequiresExplicitPattern()
+    {
+        // Arrange - Test that replacements are done in a single pass
+        // The input "&amp;nbsp;" does NOT contain literal "&nbsp;" substring,
+        // so &nbsp; replacement won't match until &amp; is replaced first.
+        // Since we do a single pass, the result depends on enumeration order.
+        string input = "&amp;nbsp;";
+        var replacements = TextReplacements.HtmlEntities;
+
+        // Act
+        string result = TextReplacements.Apply(input, replacements);
+
+        // Assert - With single-pass replacement:
+        // - "&amp;" matches and gets replaced with "&", resulting in "&nbsp;"
+        // - The iteration continues but &nbsp; was already checked, so no further replacement
+        // This is expected behavior - use explicit patterns for chained replacements
+        Assert.Equal("&nbsp;", result);
+    }
+
+    [Fact]
+    public void Apply_ConsecutiveEntities_ReplacesAll()
+    {
+        // Arrange
+        string input = "&lt;&gt;&amp;";
+        var replacements = TextReplacements.HtmlEntities;
+
+        // Act
+        string result = TextReplacements.Apply(input, replacements);
+
+        // Assert
+        Assert.Equal("<>&", result);
+    }
+
+    [Fact]
+    public void Apply_OnlyEntity_ReplacesCorrectly()
+    {
+        // Arrange
+        string input = "&nbsp;";
+        var replacements = TextReplacements.HtmlEntities;
+
+        // Act
+        string result = TextReplacements.Apply(input, replacements);
+
+        // Assert
+        Assert.Equal("\u00A0", result);
+    }
+
+    #endregion
+}
diff --git a/TriasDev.Templify/Core/PlaceholderReplacementOptions.cs b/TriasDev.Templify/Core/PlaceholderReplacementOptions.cs
index 7181b80..06f6995 100644
--- a/TriasDev.Templify/Core/PlaceholderReplacementOptions.cs
+++ b/TriasDev.Templify/Core/PlaceholderReplacementOptions.cs
@@ -3,6 +3,7 @@
 
 using System.Globalization;
 using TriasDev.Templify.Formatting;
+using TriasDev.Templify.Replacements;
 
 namespace TriasDev.Templify.Core;
 
@@ -45,6 +46,42 @@ public sealed class PlaceholderReplacementOptions
     /// </summary>
     public bool WarnOnEmptyLoopCollections { get; init; } = true;
 
+    /// <summary>
+    /// Gets or initializes a dictionary of text replacements to apply to variable values before processing.
+    /// Use this to convert HTML entities, custom placeholders, or other text patterns.
+    /// Default is null (no replacements).
+    /// </summary>
+    /// <remarks>
+    /// <para>
+    /// Replacements are applied after value conversion but before newline and markdown processing.
+    /// This allows HTML line breaks (e.g., &lt;br&gt;) to be converted to \n, which then gets
+    /// processed into Word line breaks.
+    /// </para>
+    /// <para>
+    /// Use the built-in <see cref="TextReplacements.HtmlEntities"/> preset for common HTML entities:
+    /// </para>
+    /// <code>
+    /// var options = new PlaceholderReplacementOptions
+    /// {
+    ///     TextReplacements = TextReplacements.HtmlEntities
+    /// };
+    /// </code>
+    /// <para>
+    /// Or define custom replacements:
+    /// </para>
+    /// <code>
+    /// var options = new PlaceholderReplacementOptions
+    /// {
+    ///     TextReplacements = new Dictionary&lt;string, string&gt;
+    ///     {
+    ///         ["&lt;br&gt;"] = "\n",
+    ///         ["COMPANY_NAME"] = "Acme Corp"
+    ///     }
+    /// };
+    /// </code>
+    /// </remarks>
+    public Dictionary<string, string>? TextReplacements { get; init; }
+
     /// <summary>
     /// Creates a new instance of <see cref="PlaceholderReplacementOptions"/> with default settings.
     /// </summary>
diff --git a/TriasDev.Templify/Replacements/TextReplacements.cs b/TriasDev.Templify/Replacements/TextReplacements.cs
new file mode 100644
index 0000000..efd1158
--- /dev/null
+++ b/TriasDev.Templify/Replacements/TextReplacements.cs
@@ -0,0 +1,100 @@
+// Copyright (c) 2025 TriasDev GmbH & Co. KG
+// Licensed under the MIT License. See LICENSE file in the project root for full license information.
+
+namespace TriasDev.Templify.Replacements;
+
+/// <summary>
+/// Provides text replacement functionality and built-in replacement presets.
+/// </summary>
+/// <remarks>
+/// <para>
+/// ADR: Lookup Table vs HTML Parser
+/// </para>
+/// <para>
+/// Context: Need to transform HTML-like strings in template values to Word-compatible output.
+/// </para>
+/// <para>
+/// Decision: Lookup Table approach using simple string-to-string replacement dictionary.
+/// </para>
+/// <para>
+/// Rationale:
+/// <list type="bullet">
+/// <item><description>Simplicity: No complex HTML parsing required, just string.Replace() operations</description></item>
+/// <item><description>Flexibility: Users can define custom mappings beyond HTML</description></item>
+/// <item><description>Predictable: No edge cases from malformed HTML</description></item>
+/// <item><description>Extensible: Easy to add new replacements without code changes</description></item>
+/// <item><description>Sufficient: Paired tags like &lt;b&gt;text&lt;/b&gt; can use existing markdown support</description></item>
+/// </list>
+/// </para>
+/// <para>
+/// Trade-offs:
+/// <list type="bullet">
+/// <item><description>Cannot support opening/closing tag pairs - users should use markdown instead</description></item>
+/// <item><description>Each variation needs explicit entry (e.g., &lt;br&gt;, &lt;br/&gt;, &lt;br /&gt; are separate)</description></item>
+/// </list>
+/// </para>
+/// </remarks>
+public static class TextReplacements
+{
+    /// <summary>
+    /// Built-in preset for common HTML entities and line break tags.
+    /// Converts HTML tags and entities to their Word-compatible equivalents.
+    /// </summary>
+    /// <remarks>
+    /// Includes:
+    /// <list type="bullet">
+    /// <item><description>&lt;br&gt;, &lt;br/&gt;, &lt;br /&gt; → newline (\n)</description></item>
+    /// <item><description>&amp;nbsp; → non-breaking space (U+00A0)</description></item>
+    /// <item><description>&amp;lt; → &lt;</description></item>
+    /// <item><description>&amp;gt; → &gt;</description></item>
+    /// <item><description>&amp;amp; → &amp;</description></item>
+    /// <item><description>&amp;quot; → "</description></item>
+    /// <item><description>&amp;apos; → '</description></item>
+    /// </list>
+    /// </remarks>
+    public static Dictionary<string, string> HtmlEntities { get; } = new Dictionary<string, string>
+    {
+        // Line break variations
+        ["<br>"] = "\n",
+        ["<br/>"] = "\n",
+        ["<br />"] = "\n",
+        ["<BR>"] = "\n",
+        ["<BR/>"] = "\n",
+        ["<BR />"] = "\n",
+
+        // Common HTML entities
+        ["&nbsp;"] = "\u00A0",  // Non-breaking space
+        ["&lt;"] = "<",
+        ["&gt;"] = ">",
+        ["&amp;"] = "&",
+        ["&quot;"] = "\"",
+        ["&apos;"] = "'",
+    };
+
+    /// <summary>
+    /// Applies text replacements to the input string.
+    /// </summary>
+    /// <param name="input">The input string to transform.</param>
+    /// <param name="replacements">Dictionary of text replacements to apply. If null or empty, returns input unchanged.</param>
+    /// <returns>The transformed string with all replacements applied.</returns>
+    /// <remarks>
+    /// Replacements are applied in dictionary enumeration order.
+    /// For predictable behavior with overlapping patterns, consider using an ordered dictionary
+    /// or applying replacements in a specific sequence.
+    /// </remarks>
+    public static string Apply(string input, Dictionary<string, string>? replacements)
+    {
+        if (string.IsNullOrEmpty(input) || replacements == null || replacements.Count == 0)
+        {
+            return input;
+        }
+
+        string result = input;
+        foreach (KeyValuePair<string, string> replacement in replacements)
+        {
+            result = result.Replace(replacement.Key, replacement.Value);
+        }
+
+        return result;
+    }
+}
diff --git a/TriasDev.Templify/Visitors/PlaceholderVisitor.cs b/TriasDev.Templify/Visitors/PlaceholderVisitor.cs
index a4ab121..3e62751 100644
--- a/TriasDev.Templify/Visitors/PlaceholderVisitor.cs
+++ b/TriasDev.Templify/Visitors/PlaceholderVisitor.cs
@@ -9,6 +9,7 @@
 using TriasDev.Templify.Loops;
 using TriasDev.Templify.Markdown;
 using TriasDev.Templify.Placeholders;
+using TriasDev.Templify.Replacements;
 using TriasDev.Templify.Utilities;
 
 namespace TriasDev.Templify.Visitors;
@@ -136,6 +137,10 @@ public void VisitPlaceholder(PlaceholderMatch placeholder, Paragraph paragraph,
                 _options.Culture,
                 placeholder.Format,
                 _options.BooleanFormatterRegistry);
+
+            // Apply text replacements (e.g., HTML entities to Word-compatible text)
+            replacementValue = TextReplacements.Apply(replacementValue, _options.TextReplacements);
+
             ReplacePlaceholderInParagraph(paragraph, placeholder, replacementValue);
             _replacementCount++;
         }

From 4446ba5cb8278a99e65dc3e7c7c020e3e381ee88 Mon Sep 17 00:00:00 2001
From: Vaceslav Ustinov <vaceslav.ustinov@gmail.com>
Date: Tue, 23 Dec 2025 19:00:29 +0100
Subject: [PATCH 2/4] feat(gui): add HTML entity replacement option to GUI

Add checkbox in GUI to enable HTML entity replacement, allowing users
to convert HTML tags (<br>, &nbsp;, etc.) to Word equivalents.

- Add EnableHtmlEntityReplacement property to MainWindowViewModel
- Add checkbox to MainWindow.axaml with tooltip
- Update ITemplifyService interface with enableHtmlEntityReplacement param
- Update TemplifyService to use TextReplacements.HtmlEntities when enabled
- Add user documentation to placeholders.md
---
 .../Services/ITemplifyService.cs              |  8 +-
 .../Services/TemplifyService.cs               | 15 +++-
 .../ViewModels/MainWindowViewModel.cs         | 14 +++-
 TriasDev.Templify.Gui/Views/MainWindow.axaml  | 19 +++--
 docs/for-template-authors/placeholders.md     | 77 +++++++++++++++++++
 5 files changed, 121 insertions(+), 12 deletions(-)

diff --git a/TriasDev.Templify.Gui/Services/ITemplifyService.cs b/TriasDev.Templify.Gui/Services/ITemplifyService.cs
index c418e1e..1d6029f 100644
--- a/TriasDev.Templify.Gui/Services/ITemplifyService.cs
+++ b/TriasDev.Templify.Gui/Services/ITemplifyService.cs
@@ -18,8 +18,12 @@ public interface ITemplifyService
     /// </summary>
     /// <param name="templatePath">Path to the template file (.docx).</param>
     /// <param name="jsonPath">Optional path to JSON data file for validation.</param>
+    /// <param name="enableHtmlEntityReplacement">Enable HTML entity replacement (e.g., &lt;br&gt; to line break).</param>
     /// <returns>Validation result with errors and warnings.</returns>
-    Task<ValidationResult> ValidateTemplateAsync(string templatePath, string? jsonPath = null);
+    Task<ValidationResult> ValidateTemplateAsync(
+        string templatePath,
+        string? jsonPath = null,
+        bool enableHtmlEntityReplacement = false);
 
     /// <summary>
     /// Processes a template with JSON data and generates output.
@@ -27,11 +31,13 @@ public interface ITemplifyService
     /// <param name="templatePath">Path to the template file (.docx).</param>
     /// <param name="jsonPath">Path to JSON data file.</param>
     /// <param name="outputPath">Path for the output file.</param>
+    /// <param name="enableHtmlEntityReplacement">Enable HTML entity replacement (e.g., &lt;br&gt; to line break).</param>
     /// <param name="progress">Optional progress reporter.</param>
     /// <returns>Processing result with statistics and any errors.</returns>
     Task<UiProcessingResult> ProcessTemplateAsync(
         string templatePath,
         string jsonPath,
         string outputPath,
+        bool enableHtmlEntityReplacement = false,
         IProgress<double>? progress = null);
 }
diff --git a/TriasDev.Templify.Gui/Services/TemplifyService.cs b/TriasDev.Templify.Gui/Services/TemplifyService.cs
index 8069ef7..62a2d4b 100644
--- a/TriasDev.Templify.Gui/Services/TemplifyService.cs
+++ b/TriasDev.Templify.Gui/Services/TemplifyService.cs
@@ -8,6 +8,7 @@
 using System.Threading.Tasks;
 using TriasDev.Templify.Core;
 using TriasDev.Templify.Gui.Models;
+using TriasDev.Templify.Replacements;
 using TriasDev.Templify.Utilities;
 
 namespace TriasDev.Templify.Gui.Services;
@@ -20,14 +21,18 @@ public class TemplifyService : ITemplifyService
     /// <summary>
     /// Validates a template file with optional JSON data.
     /// </summary>
-    public async Task<ValidationResult> ValidateTemplateAsync(string templatePath, string? jsonPath = null)
+    public async Task<ValidationResult> ValidateTemplateAsync(
+        string templatePath,
+        string? jsonPath = null,
+        bool enableHtmlEntityReplacement = false)
     {
         return await Task.Run(() =>
         {
             PlaceholderReplacementOptions options = new PlaceholderReplacementOptions
             {
                 MissingVariableBehavior = MissingVariableBehavior.LeaveUnchanged,
-                Culture = CultureInfo.InvariantCulture
+                Culture = CultureInfo.InvariantCulture,
+                TextReplacements = enableHtmlEntityReplacement ? TextReplacements.HtmlEntities : null
             };
 
             DocumentTemplateProcessor processor = new DocumentTemplateProcessor(options);
@@ -57,6 +62,7 @@ public async Task<UiProcessingResult> ProcessTemplateAsync(
         string templatePath,
         string jsonPath,
         string outputPath,
+        bool enableHtmlEntityReplacement = false,
         IProgress<double>? progress = null)
     {
         return await Task.Run(() =>
@@ -76,11 +82,12 @@ public async Task<UiProcessingResult> ProcessTemplateAsync(
 
                 progress?.Report(0.3);
 
-                // Validate template first
+                // Configure options with optional HTML entity replacement
                 PlaceholderReplacementOptions options = new PlaceholderReplacementOptions
                 {
                     MissingVariableBehavior = MissingVariableBehavior.LeaveUnchanged,
-                    Culture = CultureInfo.InvariantCulture
+                    Culture = CultureInfo.InvariantCulture,
+                    TextReplacements = enableHtmlEntityReplacement ? TextReplacements.HtmlEntities : null
                 };
 
                 DocumentTemplateProcessor processor = new DocumentTemplateProcessor(options);
diff --git a/TriasDev.Templify.Gui/ViewModels/MainWindowViewModel.cs b/TriasDev.Templify.Gui/ViewModels/MainWindowViewModel.cs
index 5a5a027..32ef7d6 100644
--- a/TriasDev.Templify.Gui/ViewModels/MainWindowViewModel.cs
+++ b/TriasDev.Templify.Gui/ViewModels/MainWindowViewModel.cs
@@ -48,6 +48,14 @@ public partial class MainWindowViewModel : ViewModelBase
     [ObservableProperty]
     private ObservableCollection<string> _results = new();
 
+    /// <summary>
+    /// Gets or sets whether HTML entity replacement is enabled.
+    /// When enabled, HTML entities like &lt;br&gt;, &amp;nbsp;, etc. are converted
+    /// to their Word equivalents before processing.
+    /// </summary>
+    [ObservableProperty]
+    private bool _enableHtmlEntityReplacement;
+
     public MainWindowViewModel(
         ITemplifyService templifyService,
         IFileDialogService fileDialogService)
@@ -103,7 +111,10 @@ private async Task ValidateTemplateAsync()
 
         try
         {
-            ValidationResult validation = await _templifyService.ValidateTemplateAsync(TemplatePath, JsonPath);
+            ValidationResult validation = await _templifyService.ValidateTemplateAsync(
+                TemplatePath,
+                JsonPath,
+                EnableHtmlEntityReplacement);
 
             if (validation.IsValid)
             {
@@ -177,6 +188,7 @@ private async Task ProcessTemplateAsync()
                 TemplatePath,
                 JsonPath,
                 OutputPath,
+                EnableHtmlEntityReplacement,
                 progressReporter);
 
             if (result.Success)
diff --git a/TriasDev.Templify.Gui/Views/MainWindow.axaml b/TriasDev.Templify.Gui/Views/MainWindow.axaml
index d61c6cf..a2a7baa 100644
--- a/TriasDev.Templify.Gui/Views/MainWindow.axaml
+++ b/TriasDev.Templify.Gui/Views/MainWindow.axaml
@@ -15,7 +15,7 @@
         <vm:MainWindowViewModel/>
     </Design.DataContext>
 
-    <Grid Margin="20" RowDefinitions="Auto,Auto,Auto,Auto,Auto,Auto,*,Auto">
+    <Grid Margin="20" RowDefinitions="Auto,Auto,Auto,Auto,Auto,Auto,Auto,*,Auto">
 
         <!-- Title -->
         <TextBlock Grid.Row="0"
@@ -51,7 +51,7 @@
         </Grid>
 
         <!-- Output File Selection -->
-        <Grid Grid.Row="3" ColumnDefinitions="100,*,100" Margin="0,0,0,20">
+        <Grid Grid.Row="3" ColumnDefinitions="100,*,100" Margin="0,0,0,10">
             <TextBlock Grid.Column="0" Text="Output File:" VerticalAlignment="Center"/>
             <TextBox Grid.Column="1"
                      Text="{Binding OutputPath}"
@@ -63,8 +63,15 @@
                     Command="{Binding BrowseOutputCommand}"/>
         </Grid>
 
+        <!-- Options Section -->
+        <StackPanel Grid.Row="4" Orientation="Horizontal" Margin="0,0,0,20">
+            <CheckBox Content="Enable HTML Entity Replacement"
+                      IsChecked="{Binding EnableHtmlEntityReplacement}"
+                      ToolTip.Tip="Convert HTML entities like &lt;br&gt;, &amp;nbsp;, &amp;lt;, etc. to Word equivalents"/>
+        </StackPanel>
+
         <!-- Action Buttons -->
-        <StackPanel Grid.Row="4" Orientation="Horizontal" Spacing="10" Margin="0,0,0,20">
+        <StackPanel Grid.Row="5" Orientation="Horizontal" Spacing="10" Margin="0,0,0,20">
             <Button Content="Validate Template"
                     Command="{Binding ValidateTemplateCommand}"
                     Width="150"/>
@@ -74,7 +81,7 @@
         </StackPanel>
 
         <!-- Status and Progress -->
-        <StackPanel Grid.Row="5" Margin="0,0,0,10">
+        <StackPanel Grid.Row="6" Margin="0,0,0,10">
             <TextBlock Text="{Binding StatusMessage}"
                        FontWeight="SemiBold"
                        Margin="0,0,0,5"/>
@@ -85,7 +92,7 @@
         </StackPanel>
 
         <!-- Results Display -->
-        <Border Grid.Row="6"
+        <Border Grid.Row="7"
                 BorderBrush="{DynamicResource SystemControlForegroundBaseMediumBrush}"
                 BorderThickness="1"
                 Padding="10"
@@ -104,7 +111,7 @@
         </Border>
 
         <!-- Bottom Action Buttons -->
-        <StackPanel Grid.Row="7" Orientation="Horizontal" Spacing="10" HorizontalAlignment="Right">
+        <StackPanel Grid.Row="8" Orientation="Horizontal" Spacing="10" HorizontalAlignment="Right">
             <Button Content="Open Output File"
                     Command="{Binding OpenOutputFileCommand}"
                     Width="130"/>
diff --git a/docs/for-template-authors/placeholders.md b/docs/for-template-authors/placeholders.md
index 335c867..e662bc0 100644
--- a/docs/for-template-authors/placeholders.md
+++ b/docs/for-template-authors/placeholders.md
@@ -543,6 +543,83 @@ Second line.
 
 All newline formats are supported: `\n` (Unix/Linux/macOS), `\r\n` (Windows), `\r` (legacy Mac).
 
+## HTML Entity Replacement
+
+If your data comes from web applications or APIs, it may contain HTML tags and entities. Templify can automatically convert these to their Word equivalents when enabled.
+
+### Enabling HTML Entity Replacement
+
+In the **Templify GUI**, check the **"Enable HTML Entity Replacement"** checkbox before processing.
+
+In code, use the `TextReplacements` option:
+
+```csharp
+var options = new PlaceholderReplacementOptions
+{
+    TextReplacements = TextReplacements.HtmlEntities
+};
+```
+
+### Supported HTML Tags and Entities
+
+| HTML | Converted To | Description |
+|------|--------------|-------------|
+| `<br>` | Line break | HTML line break |
+| `<br/>` | Line break | Self-closing line break |
+| `<br />` | Line break | Self-closing with space |
+| `&nbsp;` | Non-breaking space | Keeps words together |
+| `&lt;` | `<` | Less than |
+| `&gt;` | `>` | Greater than |
+| `&amp;` | `&` | Ampersand |
+| `&quot;` | `"` | Double quote |
+| `&apos;` | `'` | Single quote |
+
+### Example
+
+**JSON (with HTML from a web form):**
+```json
+{
+  "Description": "Product features:<br>- Fast<br>- Reliable<br>- Easy to use",
+  "Price": "Starting at &lt;$100",
+  "Note": "Contact us at info@company.com&nbsp;&mdash;&nbsp;we're here to help!"
+}
+```
+
+**Template:**
+```
+{{Description}}
+
+Price: {{Price}}
+
+{{Note}}
+```
+
+**Output (with HTML Entity Replacement enabled):**
+```
+Product features:
+- Fast
+- Reliable
+- Easy to use
+
+Price: Starting at <$100
+
+Contact us at info@company.com — we're here to help!
+```
+
+### When to Use HTML Entity Replacement
+
+Enable this option when your data:
+- Comes from web forms or CMS systems
+- Contains HTML line breaks (`<br>`)
+- Includes HTML-encoded special characters (`&lt;`, `&gt;`, `&amp;`)
+- Was exported from web applications
+
+### Limitations
+
+- Only simple tags and entities are supported (see table above)
+- Paired tags like `<b>text</b>` are **not** converted — use markdown (`**text**`) instead
+- This is an opt-in feature (disabled by default) to avoid unexpected changes
+
 **Combining with Markdown:**
 
 You can use both markdown formatting and line breaks together:

From d318c5f851e50d8d090f2f7c31531d2ae1179102 Mon Sep 17 00:00:00 2001
From: Vaceslav Ustinov <vaceslav.ustinov@gmail.com>
Date: Tue, 23 Dec 2025 19:17:16 +0100
Subject: [PATCH 3/4] feat: add em dash and en dash HTML entities to preset
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Add &mdash; (—) and &ndash; (–) to the HtmlEntities preset to support
common typographic dash entities used in web content.
---
 .../Replacements/TextReplacementsTests.cs      | 18 ++++++++++++++++++
 .../Replacements/TextReplacements.cs           |  4 ++++
 docs/for-template-authors/placeholders.md      |  2 ++
 3 files changed, 24 insertions(+)

diff --git a/TriasDev.Templify.Tests/Replacements/TextReplacementsTests.cs b/TriasDev.Templify.Tests/Replacements/TextReplacementsTests.cs
index d9f7510..9b15e9c 100644
--- a/TriasDev.Templify.Tests/Replacements/TextReplacementsTests.cs
+++ b/TriasDev.Templify.Tests/Replacements/TextReplacementsTests.cs
@@ -25,6 +25,8 @@ public void HtmlEntities_ContainsExpectedReplacements()
         Assert.Contains("&amp;", entities.Keys);
         Assert.Contains("&quot;", entities.Keys);
         Assert.Contains("&apos;", entities.Keys);
+        Assert.Contains("&mdash;", entities.Keys);
+        Assert.Contains("&ndash;", entities.Keys);
     }
 
     [Theory]
@@ -59,6 +61,8 @@ public void HtmlEntities_Nbsp_MapsToNonBreakingSpace()
     [InlineData("&amp;", "&")]
     [InlineData("&quot;", "\"")]
     [InlineData("&apos;", "'")]
+    [InlineData("&mdash;", "\u2014")]
+    [InlineData("&ndash;", "\u2013")]
     public void HtmlEntities_CommonEntities_MapCorrectly(string input, string expected)
     {
         // Act
@@ -212,6 +216,20 @@ public void Apply_QuotesAndApostrophes_ReplacesCorrectly()
         Assert.Equal("He said \"Hello\" and 'Goodbye'", result);
     }
 
+    [Fact]
+    public void Apply_Dashes_ReplacesCorrectly()
+    {
+        // Arrange
+        string input = "Contact us&nbsp;&mdash;&nbsp;we're here to help!";
+        var replacements = TextReplacements.HtmlEntities;
+
+        // Act
+        string result = TextReplacements.Apply(input, replacements);
+
+        // Assert
+        Assert.Equal("Contact us\u00A0\u2014\u00A0we're here to help!", result);
+    }
+
     [Fact]
     public void Apply_CaseSensitiveLineBreaks_UppercaseReplaced()
     {
diff --git a/TriasDev.Templify/Replacements/TextReplacements.cs b/TriasDev.Templify/Replacements/TextReplacements.cs
index efd1158..fe32b10 100644
--- a/TriasDev.Templify/Replacements/TextReplacements.cs
+++ b/TriasDev.Templify/Replacements/TextReplacements.cs
@@ -50,6 +50,8 @@ public static class TextReplacements
     /// <item><description>&amp;amp; → &amp;</description></item>
     /// <item><description>&amp;quot; → "</description></item>
     /// <item><description>&amp;apos; → '</description></item>
+    /// <item><description>&amp;mdash; → em dash (—)</description></item>
+    /// <item><description>&amp;ndash; → en dash (–)</description></item>
     /// </list>
     /// </remarks>
     public static Dictionary<string, string> HtmlEntities { get; } = new Dictionary<string, string>
@@ -69,6 +71,8 @@ public static class TextReplacements
         ["&amp;"] = "&",
         ["&quot;"] = "\"",
         ["&apos;"] = "'",
+        ["&mdash;"] = "\u2014", // Em dash (—)
+        ["&ndash;"] = "\u2013", // En dash (–)
     };
 
     /// <summary>
diff --git a/docs/for-template-authors/placeholders.md b/docs/for-template-authors/placeholders.md
index e662bc0..b7a62dc 100644
--- a/docs/for-template-authors/placeholders.md
+++ b/docs/for-template-authors/placeholders.md
@@ -573,6 +573,8 @@ var options = new PlaceholderReplacementOptions
 | `&amp;` | `&` | Ampersand |
 | `&quot;` | `"` | Double quote |
 | `&apos;` | `'` | Single quote |
+| `&mdash;` | `—` | Em dash |
+| `&ndash;` | `–` | En dash |
 
 ### Example
 

From f71a941a7a98b38001e61c93995177985141d481 Mon Sep 17 00:00:00 2001
From: Vaceslav Ustinov <vaceslav.ustinov@gmail.com>
Date: Tue, 23 Dec 2025 19:32:04 +0100
Subject: [PATCH 4/4] fix: address PR review comments for text replacements

- Make HtmlEntities return IReadOnlyDictionary to prevent external modification
- Fix nullable return type in Apply() method (string? instead of string)
- Update PlaceholderReplacementOptions.TextReplacements to IReadOnlyDictionary
- Add documentation note about uppercase <BR> support and case-sensitive entities
- Update tests to handle nullable return type
---
 .../Replacements/TextReplacementsTests.cs     | 34 +++++++-------
 .../Core/PlaceholderReplacementOptions.cs     |  2 +-
 .../Replacements/TextReplacements.cs          | 47 ++++++++++---------
 .../Visitors/PlaceholderVisitor.cs            |  3 +-
 docs/for-template-authors/placeholders.md     |  2 +
 5 files changed, 47 insertions(+), 41 deletions(-)

diff --git a/TriasDev.Templify.Tests/Replacements/TextReplacementsTests.cs b/TriasDev.Templify.Tests/Replacements/TextReplacementsTests.cs
index 9b15e9c..13e5804 100644
--- a/TriasDev.Templify.Tests/Replacements/TextReplacementsTests.cs
+++ b/TriasDev.Templify.Tests/Replacements/TextReplacementsTests.cs
@@ -84,7 +84,7 @@ public void Apply_NullInput_ReturnsNull()
         var replacements = TextReplacements.HtmlEntities;
 
         // Act
-        string result = TextReplacements.Apply(input!, replacements);
+        string? result = TextReplacements.Apply(input!, replacements);
 
         // Assert
         Assert.Null(result);
@@ -98,7 +98,7 @@ public void Apply_EmptyInput_ReturnsEmpty()
         var replacements = TextReplacements.HtmlEntities;
 
         // Act
-        string result = TextReplacements.Apply(input, replacements);
+        string? result = TextReplacements.Apply(input, replacements);
 
         // Assert
         Assert.Equal("", result);
@@ -112,7 +112,7 @@ public void Apply_NullReplacements_ReturnsInputUnchanged()
         Dictionary<string, string>? replacements = null;
 
         // Act
-        string result = TextReplacements.Apply(input, replacements);
+        string? result = TextReplacements.Apply(input, replacements);
 
         // Assert
         Assert.Equal("Hello<br>World", result);
@@ -126,7 +126,7 @@ public void Apply_EmptyReplacements_ReturnsInputUnchanged()
         var replacements = new Dictionary<string, string>();
 
         // Act
-        string result = TextReplacements.Apply(input, replacements);
+        string? result = TextReplacements.Apply(input, replacements);
 
         // Assert
         Assert.Equal("Hello<br>World", result);
@@ -140,7 +140,7 @@ public void Apply_NoMatchingPatterns_ReturnsInputUnchanged()
         var replacements = TextReplacements.HtmlEntities;
 
         // Act
-        string result = TextReplacements.Apply(input, replacements);
+        string? result = TextReplacements.Apply(input, replacements);
 
         // Assert
         Assert.Equal("Hello World", result);
@@ -154,7 +154,7 @@ public void Apply_SingleLineBreak_ReplacesCorrectly()
         var replacements = TextReplacements.HtmlEntities;
 
         // Act
-        string result = TextReplacements.Apply(input, replacements);
+        string? result = TextReplacements.Apply(input, replacements);
 
         // Assert
         Assert.Equal("Hello\nWorld", result);
@@ -168,7 +168,7 @@ public void Apply_MultipleLineBreaks_ReplacesAll()
         var replacements = TextReplacements.HtmlEntities;
 
         // Act
-        string result = TextReplacements.Apply(input, replacements);
+        string? result = TextReplacements.Apply(input, replacements);
 
         // Assert
         Assert.Equal("Line1\nLine2\nLine3\nLine4", result);
@@ -182,7 +182,7 @@ public void Apply_HtmlEntities_ReplacesAllCorrectly()
         var replacements = TextReplacements.HtmlEntities;
 
         // Act
-        string result = TextReplacements.Apply(input, replacements);
+        string? result = TextReplacements.Apply(input, replacements);
 
         // Assert
         Assert.Equal("5 < 10 & 10 > 5", result);
@@ -196,7 +196,7 @@ public void Apply_MixedContent_ReplacesAllPatterns()
         var replacements = TextReplacements.HtmlEntities;
 
         // Act
-        string result = TextReplacements.Apply(input, replacements);
+        string? result = TextReplacements.Apply(input, replacements);
 
         // Assert
         Assert.Equal("Hello\u00A0World\n<test>", result);
@@ -210,7 +210,7 @@ public void Apply_QuotesAndApostrophes_ReplacesCorrectly()
         var replacements = TextReplacements.HtmlEntities;
 
         // Act
-        string result = TextReplacements.Apply(input, replacements);
+        string? result = TextReplacements.Apply(input, replacements);
 
         // Assert
         Assert.Equal("He said \"Hello\" and 'Goodbye'", result);
@@ -224,7 +224,7 @@ public void Apply_Dashes_ReplacesCorrectly()
         var replacements = TextReplacements.HtmlEntities;
 
         // Act
-        string result = TextReplacements.Apply(input, replacements);
+        string? result = TextReplacements.Apply(input, replacements);
 
         // Assert
         Assert.Equal("Contact us\u00A0\u2014\u00A0we're here to help!", result);
@@ -238,7 +238,7 @@ public void Apply_CaseSensitiveLineBreaks_UppercaseReplaced()
         var replacements = TextReplacements.HtmlEntities;
 
         // Act
-        string result = TextReplacements.Apply(input, replacements);
+        string? result = TextReplacements.Apply(input, replacements);
 
         // Assert
         Assert.Equal("Hello\nWorld\nTest\nEnd", result);
@@ -256,7 +256,7 @@ public void Apply_CustomReplacements_WorksCorrectly()
         };
 
         // Act
-        string result = TextReplacements.Apply(input, replacements);
+        string? result = TextReplacements.Apply(input, replacements);
 
         // Assert
         Assert.Equal("Hello Acme Corp, welcome to Templify!", result);
@@ -273,7 +273,7 @@ public void Apply_CombinedPresetAndCustom_WorksCorrectly()
         };
 
         // Act
-        string result = TextReplacements.Apply(input, replacements);
+        string? result = TextReplacements.Apply(input, replacements);
 
         // Assert
         Assert.Equal("Hello\nAcme Corp", result);
@@ -290,7 +290,7 @@ public void Apply_ChainedReplacements_RequiresExplicitPattern()
         var replacements = TextReplacements.HtmlEntities;
 
         // Act
-        string result = TextReplacements.Apply(input, replacements);
+        string? result = TextReplacements.Apply(input, replacements);
 
         // Assert - With single-pass replacement:
         // - "&amp;" matches and gets replaced with "&", resulting in "&nbsp;"
@@ -307,7 +307,7 @@ public void Apply_ConsecutiveEntities_ReplacesAll()
         var replacements = TextReplacements.HtmlEntities;
 
         // Act
-        string result = TextReplacements.Apply(input, replacements);
+        string? result = TextReplacements.Apply(input, replacements);
 
         // Assert
         Assert.Equal("<>&", result);
@@ -321,7 +321,7 @@ public void Apply_OnlyEntity_ReplacesCorrectly()
         var replacements = TextReplacements.HtmlEntities;
 
         // Act
-        string result = TextReplacements.Apply(input, replacements);
+        string? result = TextReplacements.Apply(input, replacements);
 
         // Assert
         Assert.Equal("\u00A0", result);
diff --git a/TriasDev.Templify/Core/PlaceholderReplacementOptions.cs b/TriasDev.Templify/Core/PlaceholderReplacementOptions.cs
index 06f6995..3b4e34b 100644
--- a/TriasDev.Templify/Core/PlaceholderReplacementOptions.cs
+++ b/TriasDev.Templify/Core/PlaceholderReplacementOptions.cs
@@ -80,7 +80,7 @@ public sealed class PlaceholderReplacementOptions
     /// };
     /// </code>
     /// </remarks>
-    public Dictionary<string, string>? TextReplacements { get; init; }
+    public IReadOnlyDictionary<string, string>? TextReplacements { get; init; }
 
     /// <summary>
     /// Creates a new instance of <see cref="PlaceholderReplacementOptions"/> with default settings.
diff --git a/TriasDev.Templify/Replacements/TextReplacements.cs b/TriasDev.Templify/Replacements/TextReplacements.cs
index fe32b10..74dcdce 100644
--- a/TriasDev.Templify/Replacements/TextReplacements.cs
+++ b/TriasDev.Templify/Replacements/TextReplacements.cs
@@ -1,6 +1,8 @@
 // Copyright (c) 2025 TriasDev GmbH & Co. KG
 // Licensed under the MIT License. See LICENSE file in the project root for full license information.
 
+using System.Collections.ObjectModel;
+
 namespace TriasDev.Templify.Replacements;
 
 /// <summary>
@@ -54,39 +56,40 @@ public static class TextReplacements
     /// <item><description>&amp;ndash; → en dash (–)</description></item>
     /// </list>
     /// </remarks>
-    public static Dictionary<string, string> HtmlEntities { get; } = new Dictionary<string, string>
-    {
-        // Line break variations
-        ["<br>"] = "\n",
-        ["<br/>"] = "\n",
-        ["<br />"] = "\n",
-        ["<BR>"] = "\n",
-        ["<BR/>"] = "\n",
-        ["<BR />"] = "\n",
+    public static IReadOnlyDictionary<string, string> HtmlEntities { get; } = new ReadOnlyDictionary<string, string>(
+        new Dictionary<string, string>
+        {
+            // Line break variations (lowercase and uppercase)
+            ["<br>"] = "\n",
+            ["<br/>"] = "\n",
+            ["<br />"] = "\n",
+            ["<BR>"] = "\n",
+            ["<BR/>"] = "\n",
+            ["<BR />"] = "\n",
 
-        // Common HTML entities
-        ["&nbsp;"] = "\u00A0",  // Non-breaking space
-        ["&lt;"] = "<",
-        ["&gt;"] = ">",
-        ["&amp;"] = "&",
-        ["&quot;"] = "\"",
-        ["&apos;"] = "'",
-        ["&mdash;"] = "\u2014", // Em dash (—)
-        ["&ndash;"] = "\u2013", // En dash (–)
-    };
+            // Common HTML entities (lowercase only - per HTML spec, entities are case-sensitive)
+            ["&nbsp;"] = "\u00A0",  // Non-breaking space
+            ["&lt;"] = "<",
+            ["&gt;"] = ">",
+            ["&amp;"] = "&",
+            ["&quot;"] = "\"",
+            ["&apos;"] = "'",
+            ["&mdash;"] = "\u2014", // Em dash (—)
+            ["&ndash;"] = "\u2013", // En dash (–)
+        });
 
     /// <summary>
     /// Applies text replacements to the input string.
     /// </summary>
-    /// <param name="input">The input string to transform.</param>
+    /// <param name="input">The input string to transform. If null, returns null.</param>
     /// <param name="replacements">Dictionary of text replacements to apply. If null or empty, returns input unchanged.</param>
-    /// <returns>The transformed string with all replacements applied.</returns>
+    /// <returns>The transformed string with all replacements applied, or null if input was null.</returns>
     /// <remarks>
     /// Replacements are applied in dictionary enumeration order.
     /// For predictable behavior with overlapping patterns, consider using an ordered dictionary
     /// or applying replacements in a specific sequence.
     /// </remarks>
-    public static string Apply(string input, Dictionary<string, string>? replacements)
+    public static string? Apply(string? input, IReadOnlyDictionary<string, string>? replacements)
     {
         if (string.IsNullOrEmpty(input) || replacements == null || replacements.Count == 0)
         {
diff --git a/TriasDev.Templify/Visitors/PlaceholderVisitor.cs b/TriasDev.Templify/Visitors/PlaceholderVisitor.cs
index 3e62751..d075c83 100644
--- a/TriasDev.Templify/Visitors/PlaceholderVisitor.cs
+++ b/TriasDev.Templify/Visitors/PlaceholderVisitor.cs
@@ -139,7 +139,8 @@ public void VisitPlaceholder(PlaceholderMatch placeholder, Paragraph paragraph,
                 _options.BooleanFormatterRegistry);
 
             // Apply text replacements (e.g., HTML entities to Word-compatible text)
-            replacementValue = TextReplacements.Apply(replacementValue, _options.TextReplacements);
+            // Note: Apply returns null only if input is null, which won't happen here
+            replacementValue = TextReplacements.Apply(replacementValue, _options.TextReplacements)!;
 
             ReplacePlaceholderInParagraph(paragraph, placeholder, replacementValue);
             _replacementCount++;
diff --git a/docs/for-template-authors/placeholders.md b/docs/for-template-authors/placeholders.md
index b7a62dc..38d51a0 100644
--- a/docs/for-template-authors/placeholders.md
+++ b/docs/for-template-authors/placeholders.md
@@ -576,6 +576,8 @@ var options = new PlaceholderReplacementOptions
 | `&mdash;` | `—` | Em dash |
 | `&ndash;` | `–` | En dash |
 
+> **Note:** The `<br>` tag also supports uppercase variants (`<BR>`, `<BR/>`, `<BR />`). However, HTML entities like `&nbsp;` are case-sensitive per the HTML specification and only lowercase versions are supported.
+
 ### Example
 
 **JSON (with HTML from a web form):**