Implement outline painting (CSS 2.1 §18.1) - was parsed but never painted

outline-style/-color/-width had CSS-OM parsing (and a shorthand) but
no CssBoxProperties fields and no paint code anywhere - an authored
outline had zero visual effect.

Adds OutlineDrawHandler: unlike border, an outline isn't part of the
box model and has no per-side bevel/corner-joining to account for, so
it paints as four flat filled rectangles forming a ring around the
border-box edge, hooked in right after DrawBoxBorders in
FragmentPainter (matching CSS2.1 Appendix E's after-border painting
order). Deliberately scoped to the common case: only solid/auto
paint (every other style is a no-op, same as none/hidden), and
outline-offset isn't implemented - this fork's CSS-OM has no
OutlineOffsetProperty at all to read a value from, and adding
outline-style:auto recognition would require a dedicated converter
rather than a shared-map edit (Map.LineStyles is also border-style's
own keyword table - adding "auto" there would wrongly make it a
legal border-style value too). outline-color falls back to
currentColor when unset, matching real browser behavior for the
property's nominal (and here unimplemented) "invert" initial value.

Ports the CSS2.1-relevant subset of PeachPDF's
OutlineStylePaintIntegrationTests.cs against this simpler
implementation - solid ring geometry, currentColor fallback,
paint-order after border, none/hidden/zero-width no-op all pass;
auto and outline-offset are ported [Ignore]d with the gaps above.

Author: jhaygood86

Source/HtmlRenderer/Core/Dom/CssBoxProperties.cs

@@ -81,6 +81,9 @@ internal abstract class CssBoxProperties
         private string _left = "auto";
         private string _counterReset = CssConstants.None;
         private string _counterIncrement = CssConstants.None;
+        private string _outlineStyle = CssConstants.None;
+        private string _outlineColor = string.Empty;
+        private string _outlineWidth = "medium";
         private string _lineHeight = "normal";
         private string _listStyleType = "disc";
         private string _listStyleImage = string.Empty;
@@ -740,6 +743,61 @@ public string CounterIncrement
             set { _counterIncrement = value; }
         }
 
+        public string OutlineStyle
+        {
+            get { return _outlineStyle; }
+            set { _outlineStyle = value; }
+        }
+
+        public string OutlineColor
+        {
+            get { return _outlineColor; }
+            set { _outlineColor = value; }
+        }
+
+        public string OutlineWidth
+        {
+            get { return _outlineWidth; }
+            set { _outlineWidth = value; }
+        }
+
+        /// <summary>
+        /// The resolved <c>outline-width</c> in pixels ("thin"/"medium"/"thick" keywords resolved, like
+        /// <see cref="ActualBorderTopWidth"/>), or 0 when <c>outline-style</c> is <c>none</c>/<c>hidden</c>
+        /// (an outline with a style of none/hidden never paints, regardless of width - CSS 2.1 §18.1's
+        /// invert/no-op default matches border's own "no style, no width" rule).
+        /// </summary>
+        public double ActualOutlineWidth
+        {
+            get
+            {
+                if (string.IsNullOrEmpty(OutlineStyle) || OutlineStyle == CssConstants.None || OutlineStyle == CssConstants.Hidden)
+                {
+                    return 0;
+                }
+                return CssValueParser.GetActualBorderWidth(OutlineWidth, this);
+            }
+        }
+
+        /// <summary>
+        /// The resolved paint color for <c>outline-color</c> - falls back to this box's own
+        /// <see cref="ActualColor"/> (i.e. <c>currentColor</c>) when <c>outline-color</c> is unset, which
+        /// is what every real browser does today for the property's nominal <c>invert</c> initial value
+        /// (true color inversion is not implemented here).
+        /// </summary>
+        public RColor ActualOutlineColor
+        {
+            get
+            {
+                // "transparent" is OutlineColorProperty's own cascaded initial value (Color.Transparent) -
+                // treated the same as unset, since an invisible-by-default outline would defeat the point
+                // of the property entirely.
+                return string.IsNullOrEmpty(OutlineColor) || OutlineColor == "transparent"
+                    ? ActualColor
+                    : GetActualColor(OutlineColor);
+            }
+        }
+
         /// <summary>
         /// This box's resolved named-counter values (CSS 2.1 §12.4), as of just after its own
         /// <c>counter-reset</c>/<c>counter-increment</c> have been applied - populated once, by

Source/HtmlRenderer/Core/Handlers/OutlineDrawHandler.cs

@@ -0,0 +1,60 @@
+// "Therefore those skilled at the unorthodox
+// are infinite as heaven and earth,
+// inexhaustible as the great rivers.
+// When they come to an end,
+// they begin again,
+// like the days and months;
+// they die and are reborn,
+// like the four seasons."
+//
+// - Sun Tsu,
+// "The Art of War"
+
+using TheArtOfDev.HtmlRenderer.Adapters;
+using TheArtOfDev.HtmlRenderer.Adapters.Entities;
+using TheArtOfDev.HtmlRenderer.Core.Dom;
+using TheArtOfDev.HtmlRenderer.Core.Utils;
+
+namespace TheArtOfDev.HtmlRenderer.Core.Handlers
+{
+    /// <summary>
+    /// Paints <c>outline</c> (CSS 2.1 §18.1) as a plain rectangular ring around the box's own border-box
+    /// edge - unlike <see cref="BordersDrawHandler"/>, an outline has no per-side bevel/corner-joining to
+    /// account for (it isn't part of the box model and doesn't affect layout), so this is a single flat
+    /// four-rectangle fill rather than a per-side polygon.<br/>
+    /// Deliberately a subset of the full property: only <c>solid</c> (and <c>auto</c>, treated the same
+    /// as <c>solid</c> per spec) is painted - <c>dotted</c>/<c>dashed</c>/<c>double</c>/<c>groove</c>/
+    /// <c>ridge</c>/<c>inset</c>/<c>outset</c> are not (a box with one of those styles simply paints no
+    /// outline, same as <c>none</c>). <c>outline-offset</c> is not implemented either (the CSS-OM here has
+    /// no <c>outline-offset</c> property at all to read a value from), so the ring always sits flush
+    /// against the border-box edge.
+    /// </summary>
+    internal static class OutlineDrawHandler
+    {
+        /// <summary>
+        /// Paints <paramref name="box"/>'s outline around <paramref name="borderBoxRect"/> (the same
+        /// border-box rectangle <see cref="BordersDrawHandler.DrawBoxBorders"/> was just given for this
+        /// line) if it has a paintable one.
+        /// </summary>
+        public static void Draw(RGraphics g, CssBox box, RRect borderBoxRect)
+        {
+            var width = box.ActualOutlineWidth;
+            if (width <= 0 || borderBoxRect.Width <= 0 || borderBoxRect.Height <= 0) return;
+
+            var style = box.OutlineStyle;
+            var isSolid = style == CssConstants.Solid || style == CssConstants.Auto;
+            if (!isSolid) return;
+
+            var brush = g.GetSolidBrush(box.ActualOutlineColor);
+
+            // Top band (full width, including the corners) ...
+            g.DrawRectangle(brush, borderBoxRect.X - width, borderBoxRect.Y - width, borderBoxRect.Width + 2 * width, width);
+            // ... bottom band ...
+            g.DrawRectangle(brush, borderBoxRect.X - width, borderBoxRect.Bottom, borderBoxRect.Width + 2 * width, width);
+            // ... left band (between the top/bottom bands, not overlapping their corners) ...
+            g.DrawRectangle(brush, borderBoxRect.X - width, borderBoxRect.Y, width, borderBoxRect.Height);
+            // ... right band.
+            g.DrawRectangle(brush, borderBoxRect.Right, borderBoxRect.Y, width, borderBoxRect.Height);
+        }
+    }
+}

Source/HtmlRenderer/Core/Paint/FragmentPainter.cs

@@ -216,6 +216,7 @@ private void PaintFragmentContent(RGraphics g, BoxFragment fragment)
                 {
                     box.PaintBackground(g, actualRect, i == 0, i == lines.Count - 1);
                     BordersDrawHandler.DrawBoxBorders(g, box, actualRect, i == 0, i == lines.Count - 1);
+                    OutlineDrawHandler.Draw(g, box, actualRect);
                 }
             }
 

Source/HtmlRenderer/Core/Utils/CssUtils.cs

@@ -50,6 +50,7 @@ internal static class CssUtils
             "page-break-inside", "break-inside", "break-before", "break-after", "page-break-before", "page-break-after",
             "widows", "orphans", "page",
             "left", "top", "right", "bottom", "counter-reset", "counter-increment",
+            "outline-style", "outline-color", "outline-width",
             "width", "max-width", "height", "min-height", "max-height",
             "background-color", "background-image", "background-position", "background-repeat",
             "content", "color", "display", "direction", "empty-cells", "float", "clear", "box-sizing", "position",
@@ -180,6 +181,12 @@ public static string GetPropertyValue(CssBox cssBox, string propName)
                     return cssBox.CounterReset;
                 case "counter-increment":
                     return cssBox.CounterIncrement;
+                case "outline-style":
+                    return cssBox.OutlineStyle;
+                case "outline-color":
+                    return cssBox.OutlineColor;
+                case "outline-width":
+                    return cssBox.OutlineWidth;
                 case "width":
                     return cssBox.Width;
                 case "max-width":
@@ -397,6 +404,15 @@ public static void SetPropertyValue(CssBox cssBox, string propName, string value
                 case "counter-increment":
                     cssBox.CounterIncrement = value;
                     break;
+                case "outline-style":
+                    cssBox.OutlineStyle = value;
+                    break;
+                case "outline-color":
+                    cssBox.OutlineColor = value;
+                    break;
+                case "outline-width":
+                    cssBox.OutlineWidth = value;
+                    break;
                 case "width":
                     cssBox.Width = value;
                     break;

Source/Test/HtmlRenderer.IntegrationTest/Painting/OutlineStylePaintIntegrationTests.cs

@@ -0,0 +1,133 @@
+using System.Linq;
+using HtmlRenderer.IntegrationTest.TestSupport;
+using TheArtOfDev.HtmlRenderer.Adapters.Entities;
+
+namespace HtmlRenderer.IntegrationTest.Painting;
+
+/// <summary>
+/// Ported from PeachPDF.Tests' OutlineStylePaintIntegrationTests.cs, adapted to this fork's new (and more
+/// limited) <c>OutlineDrawHandler</c> - see that class's remarks for exactly what's implemented: a plain
+/// rectangular ring for <c>solid</c>/<c>auto</c> only, no <c>outline-offset</c> (this fork's CSS-OM has no
+/// such property to read a value from), and every other style (<c>dotted</c>/<c>dashed</c>/<c>double</c>/
+/// <c>groove</c>/<c>ridge</c>/<c>inset</c>/<c>outset</c>) paints nothing, same as <c>none</c>.
+/// </summary>
+[DoNotParallelize]
+[TestClass]
+public sealed class OutlineStylePaintIntegrationTests
+{
+    [TestMethod]
+    public void SolidOutline_PaintsAFourSidedRingAroundTheBorderBox()
+    {
+        var (root, container) = PaintHarness.Layout(PaintHarness.Wrap(
+            "<div id='b' style='width:100px;height:50px;outline:5px solid rgb(51,51,51)'>x</div>"));
+        var div = PaintHarness.FindById(root, "b")!;
+
+        var g = PaintHarness.PaintBox(container, div);
+        var rects = g.Log.OfType<RecordingGraphics.DrawRectCall>()
+            .Where(r => r.Color == RColor.FromArgb(51, 51, 51)).ToList();
+
+        Assert.AreEqual(4, rects.Count, "expected one filled rect per side of the outline ring");
+
+        // Two of the four bands are 5px tall (top/bottom, spanning the full outer width including
+        // corners) and two are 5px wide (left/right, spanning just the box's own height) - regardless of
+        // which order OutlineDrawHandler emits them in.
+        Assert.AreEqual(2, rects.Count(r => System.Math.Abs(r.Height - 5) < 0.1));
+        Assert.AreEqual(2, rects.Count(r => System.Math.Abs(r.Width - 5) < 0.1));
+    }
+
+    [Ignore("outline-style:auto cannot be parsed at all on this fork: Map.LineStyles (Core/CssEngine/Model/" +
+            "Map.cs), the shared keyword table outline-style's converter reuses from border-style, has no " +
+            "\"auto\" entry - adding one there would also make it a legal (but spec-invalid) border-style " +
+            "value, so this needs its own dedicated converter rather than a shared-map edit, which is out of " +
+            "scope for this pass. OutlineDrawHandler.Draw's own \"style == Auto\" check is consequently dead " +
+            "code today - reachable only by setting the property programmatically, never via CSS text.")]
+    [TestMethod]
+    public void OutlineAuto_PaintsTheSameAsSolid()
+    {
+        var (root, container) = PaintHarness.Layout(PaintHarness.Wrap(
+            "<div id='b' style='width:100px;height:50px;outline:5px auto rgb(51,51,51)'>x</div>"));
+        var div = PaintHarness.FindById(root, "b")!;
+
+        var g = PaintHarness.PaintBox(container, div);
+        var rects = g.Log.OfType<RecordingGraphics.DrawRectCall>()
+            .Where(r => r.Color == RColor.FromArgb(51, 51, 51)).ToList();
+
+        Assert.AreEqual(4, rects.Count);
+    }
+
+    [TestMethod]
+    public void OutlineColorUnset_FallsBackToCurrentColor()
+    {
+        var (root, container) = PaintHarness.Layout(PaintHarness.Wrap(
+            "<div id='b' style='width:100px;height:50px;color:rgb(10,20,30);outline-style:solid;outline-width:5px'>x</div>"));
+        var div = PaintHarness.FindById(root, "b")!;
+
+        var g = PaintHarness.PaintBox(container, div);
+        var rects = g.Log.OfType<RecordingGraphics.DrawRectCall>().ToList();
+
+        Assert.AreEqual(4, rects.Count);
+        Assert.IsTrue(rects.All(r => r.Color == RColor.FromArgb(10, 20, 30)));
+    }
+
+    [TestMethod]
+    public void Outline_PaintsAfterBorder()
+    {
+        // Paint-order: DrawBoxBorders runs, then OutlineDrawHandler - the outline's draw calls must come
+        // after the border's in the recording.
+        var (root, container) = PaintHarness.Layout(PaintHarness.Wrap(
+            "<div id='b' style='width:100px;height:50px;border:3px solid rgb(1,2,3);outline:5px solid rgb(4,5,6)'>x</div>"));
+        var div = PaintHarness.FindById(root, "b")!;
+
+        var g = PaintHarness.PaintBox(container, div);
+
+        var borderIndex = g.Log.FindIndex(c => c is RecordingGraphics.DrawLineCall line && line.Color == RColor.FromArgb(1, 2, 3));
+        var outlineIndex = g.Log.FindIndex(c => c is RecordingGraphics.DrawRectCall rect && rect.Color == RColor.FromArgb(4, 5, 6));
+
+        Assert.IsTrue(borderIndex >= 0 && outlineIndex >= 0);
+        Assert.IsTrue(outlineIndex > borderIndex, "outline must paint after (on top of) the border");
+    }
+
+    [TestMethod]
+    [DataRow("none")]
+    [DataRow("hidden")]
+    public void OutlineStyleNoneOrHidden_PaintsNothing(string style)
+    {
+        var (root, container) = PaintHarness.Layout(PaintHarness.Wrap(
+            $"<div id='b' style='width:100px;height:50px;outline:5px {style} rgb(51,51,51)'>x</div>"));
+        var div = PaintHarness.FindById(root, "b")!;
+
+        var g = PaintHarness.PaintBox(container, div);
+
+        Assert.IsFalse(g.Log.OfType<RecordingGraphics.DrawRectCall>().Any(r => r.Color == RColor.FromArgb(51, 51, 51)));
+    }
+
+    [TestMethod]
+    public void ZeroWidthOutline_PaintsNothing()
+    {
+        var (root, container) = PaintHarness.Layout(PaintHarness.Wrap(
+            "<div id='b' style='width:100px;height:50px;outline:0 solid rgb(51,51,51)'>x</div>"));
+        var div = PaintHarness.FindById(root, "b")!;
+
+        var g = PaintHarness.PaintBox(container, div);
+
+        Assert.IsFalse(g.Log.OfType<RecordingGraphics.DrawRectCall>().Any(r => r.Color == RColor.FromArgb(51, 51, 51)));
+    }
+
+    [Ignore("outline-offset is not implemented on this fork: the CSS-OM here has no OutlineOffsetProperty at " +
+            "all (confirmed - no PropertyNames.OutlineOffset, no case in PropertyFactory), so there is no value " +
+            "for OutlineDrawHandler to read; the ring always sits flush against the border-box edge instead of " +
+            "the requested 10px further out.")]
+    [TestMethod]
+    public void OutlineOffset_PushesTheRingFurtherFromTheBorderBox()
+    {
+        var (root, container) = PaintHarness.Layout(PaintHarness.Wrap(
+            "<div id='b' style='width:100px;height:50px;outline:5px solid rgb(51,51,51);outline-offset:10px'>x</div>"));
+        var div = PaintHarness.FindById(root, "b")!;
+
+        var g = PaintHarness.PaintBox(container, div);
+        var borderBox = div.Rectangles.Values.Single();
+        var top = g.Log.OfType<RecordingGraphics.DrawRectCall>().First(r => r.Color == RColor.FromArgb(51, 51, 51));
+
+        Assert.AreEqual(borderBox.Y - 10 - 5, top.Y, 0.1);
+    }
+}