1.4.0, correcting template fragment support

pimbrouwers · pimbrouwers · commit 05b85ba0d0bf · 2025-09-09T21:13:42.000-04:00
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -2,13 +2,23 @@
 
 All notable changes to this project will be documented in this file.
 
+## [1.4.0] 2025-09-16
+
+### Added
+
+- `XmlNodeRenderer.renderFragment` to render template fragments based on `id` attribute lookup.
+
+### Fixed
+
+- Removed `XmlNode.NodeList`, `Elem.createFragment`, and `Elem.empty` to restore functionality, from 1.2.0 and correctly provide template fragment support.
+
 ## [1.3.0] 2025-09-09
 
 ### Added
 
-- `XmlNode.NodeList` to represent HTML fragments.
-- `Elem.createFragment` to create HTML fragments from a list of `XmlNode`.
-- `Elem.empty` leverages `Elem.createFragment` and `XmlNode.NodeList` to represent an empty HTML fragment.
+- (Reverted in 1.4.0) `XmlNode.NodeList` to represent [template fragments](https://htmx.org/essays/template-fragments/).
+- (Reverted in 1.4.0) `Elem.createFragment` to create template fragments from a list of `XmlNode`.
+- (Reverted in 1.4.0) `Elem.empty` leverages `Elem.createFragment` and `XmlNode.NodeList` to represent an empty template fragment.
 
 ## [1.2.0] 2025-06-26
 
@@ -28,7 +38,6 @@ All notable changes to this project will be documented in this file.
       ```
 - Unified DSL module ensures backward compatibility while providing a cleaner syntax for new code.
 
-
 ## [1.1.1] 2024-03-28
 
 ###
diff --git a/README.md b/README.md
@@ -31,6 +31,7 @@ renderHtml doc
 - Should be simple, extensible and integrate with existing .NET libraries.
 - Can be easily learned.
 - Match HTML [spec](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference) as closely as possible.
+- Support rendering full documents as well as fragments.
 
 ## Overview
 
@@ -47,7 +48,7 @@ Each of the primary modules can be access using the name directly, or using the
 | `Elem` | `_h1 [] []` |
 | `Attr` | `_class_ "my-class"` |
 | `Text` | `_text "Hello world!"` |
-| `Text` shortcuts | `_h1' "Hello world"` |
+| `Text` shortcuts | `_h1' "Hello world"` (note the trailing apostrophe) |
 
 
 ```fsharp
@@ -336,6 +337,11 @@ let xmlDoc =
 let xml = renderXml xmlDoc
 ```
 
+## HTML Fragments
+
+Sometimes you may want to create a fragment of HTML, without the surrounding `<html>`, `<head>` and `<body>` tags. Or, any wrapper element for that matter.
+
+
 ## SVG
 
 Much of the SVG spec has been mapped to element and attributes functions. There is also an SVG template to help initialize a new drawing with a valid viewbox.
diff --git a/src/Falco.Markup/Elem.fs b/src/Falco.Markup/Elem.fs
@@ -9,12 +9,6 @@ module Elem =
     let createSelfClosing (tag : string) (attr : XmlAttribute list) =
         SelfClosingNode (tag, attr)
 
-    let createFragment (nodes : XmlNode list) =
-        NodeList nodes
-
-    let empty =
-        NodeList []
-
     //
     // Main root
 
diff --git a/src/Falco.Markup/Falco.Markup.fsproj b/src/Falco.Markup/Falco.Markup.fsproj
@@ -3,7 +3,7 @@
   <PropertyGroup>
     <AssemblyName>Falco.Markup</AssemblyName>
     <RootNamespace>Falco</RootNamespace>
-    <Version>1.3.0</Version>
+    <Version>1.4.0</Version>
 
     <!-- General info -->
     <Description>An F# DSL for generating markup, including HTML, SVG and XML.</Description>
diff --git a/src/Falco.Markup/TestHelpers.fs b/src/Falco.Markup/TestHelpers.fs
@@ -121,7 +121,6 @@ module TestHelpers =
 
                                     | ParentNode _
                                     | SelfClosingNode _
-                                    | NodeList _
                                     | TextNode _ -> ()
 
                             // <option></option>
@@ -130,7 +129,6 @@ module TestHelpers =
 
                             | ParentNode _
                             | SelfClosingNode _
-                            | NodeList _
                             | TextNode _ -> () ]
 
                     if selected.Length = 0 then
@@ -143,9 +141,6 @@ module TestHelpers =
                     for c in children do
                         buildNameValues c
 
-                | NodeList nodes ->
-                    for node in nodes do
-                        buildNameValues node
                 | SelfClosingNode _
                 | TextNode _ -> ()
 
diff --git a/src/Falco.Markup/XmlNode.fs b/src/Falco.Markup/XmlNode.fs
@@ -18,7 +18,6 @@ type XmlElement =
 type XmlNode =
     | TextNode        of string
     | SelfClosingNode of XmlElement
-    | NodeList        of XmlNode list
     | ParentNode      of XmlElement * XmlNode list
 
 [<AbstractClass; Sealed>]
@@ -64,7 +63,7 @@ module internal XmlNodeSerializer =
     let [<Literal>] _equals = '='
     let [<Literal>] _quote = '"'
 
-    let serialize (w : StringWriter, xml : XmlNode) =
+    let serialize (w : TextWriter, xml : XmlNode) =
         let writeAttributes attrs =
             for attr in (attrs : XmlAttribute list) do
                 if attrs.Length > 0 then
@@ -81,25 +80,18 @@ module internal XmlNodeSerializer =
                     w.Write attrValue
                     w.Write _quote
 
-        let inline writeElement (tag : string, attrs) =
-            w.Write _openChar
-            w.Write tag
-            writeAttributes attrs
-            w.Write _space
-            w.Write _term
-            w.Write _closeChar
-
         let rec buildXml tag =
             match tag with
             | TextNode text ->
                 w.Write text
 
-            | SelfClosingNode el ->
-                writeElement el
-
-            | NodeList nodes ->
-                for node in nodes do
-                    buildXml node
+            | SelfClosingNode (tag, attrs) ->
+                w.Write _openChar
+                w.Write tag
+                writeAttributes attrs
+                w.Write _space
+                w.Write _term
+                w.Write _closeChar
 
             | ParentNode ((tag, attrs), children) ->
                 w.Write _openChar
@@ -117,26 +109,52 @@ module internal XmlNodeSerializer =
 
         buildXml xml
 
-        StringBuilderCache.GetString(w.GetStringBuilder())
-
 [<AutoOpen>]
 module XmlNodeRenderer =
-    /// Render XmlNode as string
-    let renderNode (tag : XmlNode) =
+    let private render (tag : XmlNode) (header : string option) =
         let sb = StringBuilderCache.Acquire()
         let w = new StringWriter(sb, CultureInfo.InvariantCulture)
+        match header with
+        | Some x -> w.Write x
+        | None   -> ()
         XmlNodeSerializer.serialize(w, tag)
+        StringBuilderCache.GetString(w.GetStringBuilder())
+
+    /// Render XmlNode as string
+    let renderNode (tag : XmlNode) =
+        render tag None
 
     /// Render XmlNode as HTML string
     let renderHtml (tag : XmlNode) =
-        let sb = StringBuilderCache.Acquire()
-        let w = new StringWriter(sb, CultureInfo.InvariantCulture)
-        w.Write "<!DOCTYPE html>"
-        XmlNodeSerializer.serialize(w, tag)
+        render tag (Some "<!DOCTYPE html>")
 
     /// Render XmlNode as XML string
     let renderXml (tag : XmlNode) =
-        let sb = StringBuilderCache.Acquire()
-        let w = new StringWriter(sb, CultureInfo.InvariantCulture)
-        w.Write "<?xml version=\"1.0\" encoding=\"UTF-8\"?>"
-        XmlNodeSerializer.serialize(w, tag)
+        render tag (Some "<?xml version=\"1.0\" encoding=\"UTF-8\"?>")
+
+    /// Render a fragment of XmlNode by id as string
+    let renderFragment (tag : XmlNode) (id : string) =
+        let isIdMatch attr =
+            match attr with
+            | KeyValueAttr ("id", v) when v = id -> true
+            | _ -> false
+
+        let rec findId tag =
+            match tag with
+            | TextNode _ ->
+                None
+
+            | SelfClosingNode ((_, attrs)) ->
+                attrs
+                |> List.tryFind isIdMatch
+                |> Option.map (fun _ -> tag)
+
+            | ParentNode ((_, attrs), children) ->
+                attrs
+                |> List.tryFind isIdMatch
+                |> Option.map (fun _ -> tag)
+                |> Option.orElse (children |> List.tryPick findId)
+
+        match findId tag with
+        | Some node -> render node None
+        | None      -> String.Empty
diff --git a/test/Falco.Markup.Tests/ElemTests.fs b/test/Falco.Markup.Tests/ElemTests.fs
@@ -12,33 +12,45 @@ let ``Self-closing tag should render with trailing slash`` () =
 [<Fact>]
 let ``Self-closing tag with attrs should render with trailing slash`` () =
     let t = Elem.createSelfClosing "hr" [ _class_ "my-class" ]
-    renderNode t |> should equal "<hr class=\"my-class\" />"
+    renderNode t |> should equal """<hr class="my-class" />"""
 
 [<Fact>]
 let ``Standard tag should render with multiple attributes`` () =
     let t = Elem.create "div" [ Attr.create "class" "my-class"; _autofocus_; Attr.create "data-bind" "slider" ] []
-    renderNode t |> should equal "<div class=\"my-class\" autofocus data-bind=\"slider\"></div>"
+    renderNode t |> should equal """<div class="my-class" autofocus data-bind="slider"></div>"""
 
+[<Fact>]
+let ``Script should contain src, lang and async`` () =
+    let t = _script [ _src_ "http://example.org/example.js";  _lang_ "javascript"; _async_ ] []
+    renderNode t |> should equal """<script src="http://example.org/example.js" lang="javascript" async></script>"""
 
 [<Fact>]
-let ``Can render NodeList with items``() =
-    Elem.createFragment [
-        for i = 1 to 3 do
-            yield _div [] [ _textf "%i" i ]
-    ]
-    |> renderNode
-    |> should equal "<div>1</div><div>2</div><div>3</div>"
+let ``Should render text node with special characters`` () =
+    let doc = _div [] [ _text "5 < 10 & 10 > 5 \"quoted\"" ]
+    renderNode doc |> should equal """<div>5 < 10 & 10 > 5 "quoted"</div>"""
 
 [<Fact>]
-let ``Can render empty NodeList``() =
-    Elem.empty
-    |> renderNode
-    |> should equal ""
+let ``Should render attribute with empty value`` () =
+    let doc = _input [ Attr.create "value" "" ]
+    renderNode doc |> should equal """<input value="" />"""
 
 [<Fact>]
-let ``Script should contain src, lang and async`` () =
-    let t = _script [ _src_ "http://example.org/example.js";  _lang_ "javascript"; _async_ ] []
-    renderNode t |> should equal "<script src=\"http://example.org/example.js\" lang=\"javascript\" async></script>"
+let ``Should render deeply nested elements`` () =
+    let rec nest n acc =
+        if n = 0 then acc
+        else nest (n - 1) (_div [] [ acc ])
+    let doc = nest 10 (_span [] [ _text "deep" ])
+    renderNode doc |> should equal "<div><div><div><div><div><div><div><div><div><div><span>deep</span></div></div></div></div></div></div></div></div></div></div>"
+
+[<Fact>]
+let ``Should render mixed content (text and child elements)`` () =
+    let doc = _div [] [ _text "Hello "; _span [] [ _text "world" ]; _text "!" ]
+    renderNode doc |> should equal """<div>Hello <span>world</span>!</div>"""
+
+[<Fact>]
+let ``Should render unicode characters in text and attributes`` () =
+    let doc = _div [ _title_ "Привет мир" ] [ _text "こんにちは世界" ]
+    renderNode doc |> should equal """<div title="Привет мир">こんにちは世界</div>"""
 
 [<Fact>]
 let ``Should produce valid html doc`` () =
@@ -47,7 +59,41 @@ let ``Should produce valid html doc`` () =
             _body [] [
                 _div [ _class_ "my-class" ] [
                     _h1 [] [ _text "hello" ] ] ] ]
-    renderHtml doc |> should equal "<!DOCTYPE html><html><body><div class=\"my-class\"><h1>hello</h1></div></body></html>"
+    renderHtml doc |> should equal """<!DOCTYPE html><html><body><div class="my-class"><h1>hello</h1></div></body></html>"""
+
+[<Fact>]
+let ``Should produce valid template fragment from XmlNode and id``()
+    =
+    let doc =
+        _div [ _id_ "my-div"; _class_ "my-class" ] [
+            _h1 [ _id_ "my-heading" ] [ _text "hello" ] ]
+
+    renderFragment doc "my-heading" |> should equal """<h1 id="my-heading">hello</h1>"""
+
+[<Fact>]
+let ``Should produce empty string template fragment from XmlNode and invalid/missing id``()
+    =
+    let doc =
+        _div [ _id_ "my-div"; _class_ "my-class" ] [
+            _h1 [ _id_ "my-heading" ] [ _text "hello" ] ]
+
+    renderFragment doc "not-found" |> should equal """"""
+
+[<Fact>]
+let ``Should produce self-closing tag fragment from XmlNode and id`` () =
+    let doc =
+        _div [] [
+            _img [ _id_ "img-1"; _src_ "foo.png" ]
+        ]
+    renderFragment doc "img-1" |> should equal """<img id="img-1" src="foo.png" />"""
+
+[<Fact>]
+let ``Should produce fragment when id is on root node`` () =
+    let doc =
+        _div [ _id_ "root" ] [
+            _span [] [ _text "child" ]
+        ]
+    renderFragment doc "root" |> should equal """<div id="root"><span>child</span></div>"""
 
 [<Fact>]
 let ``_control should render label with nested input`` () =
@@ -63,8 +109,8 @@ let ``_control should render label with nested input`` () =
 
 [<Fact>]
 let ``Should create valid html button`` () =
-    let doc = _button [ _onclick_ "console.log(\"test\")"] [ _text "click me" ]
-    renderNode doc |> should equal "<button onclick=\"console.log(\"test\")\">click me</button>";
+    let doc = _button [ _onclick_ """console.log("test")""" ] [ _text "click me" ]
+    renderNode doc |> should equal """<button onclick="console.log("test")">click me</button>""";
 
 [<Fact>]
 let ``Should produce valid xml doc`` () =
@@ -75,7 +121,7 @@ let ``Should produce valid xml doc`` () =
             ]
         ]
 
-    renderXml doc |> should equal "<?xml version=\"1.0\" encoding=\"UTF-8\"?><books><book><name>To Kill A Mockingbird</name></book></books>"
+    renderXml doc |> should equal """<?xml version="1.0" encoding="UTF-8"?><books><book><name>To Kill A Mockingbird</name></book></books>"""
 
 type Product =
     { Name : string
diff --git a/test/Falco.Markup.Tests/TestHelperTests.fs b/test/Falco.Markup.Tests/TestHelperTests.fs
diff --git a/test/Falco.Markup.Tests/TextTests.fs b/test/Falco.Markup.Tests/TextTests.fs
