Refactor Document::State -> XRB::Builder.

Author: ioquatix

lib/utopia/content/builder.rb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2025, by Samuel Williams.
+
+require "xrb/builder"
+
+module Utopia
+	module Content
+		DEFERRED_TAG_NAME = "utopia:deferred".freeze
+		
+		# A builder for rendering Utopia content that extends XRB::Builder with Utopia-specific functionality.
+		class Builder < XRB::Builder
+			def initialize(parent, tag, node, attributes = tag.to_hash, **options)
+				super(**options)
+				
+				@parent = parent
+				@tag = tag
+				@node = node
+				@attributes = attributes
+				
+				@content = nil
+				@deferred = []
+				@tags = []
+			end
+			
+			attr :parent
+			attr :tag
+			attr :attributes
+			attr :content
+			attr :node
+			
+			# A list of all tags in order of rendering them, which have not been finished yet.
+			attr :tags
+			
+			attr :deferred
+			
+			def defer(value = nil, &block)
+				@deferred << block
+				
+				XRB::Tag.closed(DEFERRED_TAG_NAME, :id => @deferred.size - 1)
+			end
+			
+			def [](key)
+				@attributes[key]
+			end
+			
+			def call(document)
+				@content = @output.dup
+				@output.clear
+				
+				if node.respond_to? :call
+					node.call(document, self)
+				else
+					document.parse_markup(@content)
+				end
+				
+				return @output
+			end
+			
+			# Override write to directly append to output
+			def write(string)
+				@output << string
+			end
+			
+			# Override text to handle build_markup protocol
+			def text(content)
+				return unless content
+				
+				if content.respond_to?(:build_markup)
+					content.build_markup(self)
+				else
+					XRB::Markup.append(@output, content)
+				end
+			end
+			
+			def tag_complete(tag)
+				tag.write(@output)
+			end
+			
+			# Whether this state has any nested tags.
+			def empty?
+				@tags.empty?
+			end
+			
+			def tag_begin(tag)
+				@tags << tag
+				tag.write_opening_tag(@output)
+			end
+			
+			def tag_end(tag)
+				raise UnbalancedTagError.new(tag) unless @tags.pop.name == tag.name
+				tag.write_closing_tag(@output)
+			end
+		end
+	end
+end

lib/utopia/content/document.rb

@@ -6,11 +6,10 @@
 require_relative "links"
 require_relative "response"
 require_relative "markup"
+require_relative "builder"
 
 module Utopia
 	module Content
-		DEFERRED_TAG_NAME = "utopia:deferred".freeze
-		
 		# This error is raised if a tag doesn't match up when parsing.
 		class UnbalancedTagError < StandardError
 			def initialize(tag)
@@ -135,9 +134,9 @@ def tag_begin(tag, node = nil)
 				node ||= lookup_tag(tag)
 
 				if node
-					@current = State.new(@current, tag, node)
+					@current = Builder.new(@current, tag, node, tag.to_hash, indent: false)
 
-					node.tag_begin(self, state) if node.respond_to?(:tag_begin)
+					node.tag_begin(self, @current) if node.respond_to?(:tag_begin)
 
 					return node
 				end
@@ -184,7 +183,7 @@ def tag_end(tag = nil)
 			end
 
 			def render_node(node, attributes = {})
-				@current = State.new(@current, nil, node, attributes)
+				@current = Builder.new(@current, nil, node, attributes, indent: false)
 
 				# We keep track of the first thing rendered by this document.
 				@first ||= @current
@@ -230,84 +229,5 @@ def parent
 				@end_tags[-2]
 			end
 		end
-		
-		# The state of a single tag being rendered within a document instance.
-		class Document::State
-			def initialize(parent, tag, node, attributes = tag.to_hash)
-				@parent = parent
-				@tag = tag
-				@node = node
-				@attributes = attributes
-				
-				@buffer = XRB::MarkupString.new.force_encoding(Encoding::UTF_8)
-				@content = nil
-				
-				@deferred = []
-				
-				@tags = []
-			end
-			
-			attr :parent
-			attr :attributes
-			attr :content
-			attr :node
-			
-			# A list of all tags in order of rendering them, which have not been finished yet.
-			attr :tags
-			
-			attr :deferred
-			
-			def defer(value = nil, &block)
-				@deferred << block
-				
-				Tag.closed(DEFERRED_TAG_NAME, :id => @deferred.size - 1)
-			end
-			
-			def [](key)
-				@attributes[key]
-			end
-			
-			def call(document)
-				@content = @buffer
-				@buffer = XRB::MarkupString.new.force_encoding(Encoding::UTF_8)
-				
-				if node.respond_to? :call
-					node.call(document, self)
-				else
-					document.parse_markup(@content)
-				end
-				
-				return @buffer
-			end
-			
-			def write(string)
-				@buffer << string
-			end
-			
-			def text(string)
-				XRB::Markup.append(@buffer, string)
-			end
-			
-			def tag_complete(tag)
-				tag.write(@buffer)
-			end
-			
-			# Whether this state has any nested tags.
-			def empty?
-				@tags.empty?
-			end
-			
-			def tag_begin(tag)
-				# raise ArgumentError.new("tag_begin: #{tag} is tag.self_closed?") if tag.self_closed?
-				
-				@tags << tag
-				tag.write_opening_tag(@buffer)
-			end
-			
-			def tag_end(tag)
-				raise UnbalancedTagError.new(tag) unless @tags.pop.name == tag.name
-				tag.write_closing_tag(@buffer)
-			end
-		end
 	end
 end

test/utopia/document/builder.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2025, by Samuel Williams.
+
+require 'utopia/content/builder'
+require 'utopia/content/tags'
+require 'xrb/builder'
+
+describe Utopia::Content::Builder do
+	it "should inherit from XRB::Builder" do
+		expect(Utopia::Content::Builder.superclass).to be == XRB::Builder
+	end
+	
+	it "should accept positional arguments" do
+		builder = Utopia::Content::Builder.new(nil, nil, nil, {})
+		
+		expect(builder.parent).to be_nil
+		expect(builder.tag).to be_nil
+		expect(builder.node).to be_nil
+		expect(builder.attributes).to be == {}
+	end
+	
+	it "should default attributes to tag.to_hash" do
+		tag = XRB::Tag.new('div', false, {'id' => 'test'})
+		
+		builder = Utopia::Content::Builder.new(nil, tag, nil)
+		
+		expect(builder.attributes).to be == {'id' => 'test'}
+	end
+	
+	it "should support fragment rendering via build_markup protocol" do
+		builder = Utopia::Content::Builder.new(nil, nil, nil, {})
+		
+		fragment = XRB::Builder.fragment do |builder|
+			builder.inline('p') do
+				builder.text "Hello from fragment"
+			end
+		end
+		
+		builder.text(fragment)
+		
+		expect(builder.output).to be =~ /Hello from fragment/
+		expect(builder.output).not.to be =~ /</
+	end
+	
+	it "should track parent builders" do
+		parent = Utopia::Content::Builder.new(nil, nil, nil, {})
+		child = Utopia::Content::Builder.new(parent, nil, nil, {})
+		
+		expect(child.parent).to be == parent
+	end
+	
+	it "should track tags" do
+		builder = Utopia::Content::Builder.new(nil, nil, nil, {})
+		
+		expect(builder.tags).to be == []
+		expect(builder).to be(:empty?)
+		
+		tag = XRB::Tag.new('div', false, {})
+		builder.tag_begin(tag)
+		
+		expect(builder.tags).to be == [tag]
+		expect(builder).not.to be(:empty?)
+	end
+	
+	it "should support deferred content" do
+		builder = Utopia::Content::Builder.new(nil, nil, nil, {})
+		
+		expect(builder.deferred).to be == []
+		
+		deferred_tag = builder.defer { "deferred content" }
+		
+		expect(builder.deferred.size).to be == 1
+		expect(deferred_tag.name).to be == "utopia:deferred"
+		expect(deferred_tag.attributes[:id]).to be == 0
+	end
+	
+	it "should write text content" do
+		builder = Utopia::Content::Builder.new(nil, nil, nil, {})
+		
+		builder.write("Hello ")
+		builder.write("World")
+		
+		expect(builder.output).to be == "Hello World"
+	end
+	
+	it "should escape regular text via text method" do
+		builder = Utopia::Content::Builder.new(nil, nil, nil, {})
+		
+		builder.text("<script>alert('xss')</script>")
+		
+		expect(builder.output).to be =~ /&lt;script&gt;/
+		expect(builder.output).not.to be =~ /<script>/
+	end
+	
+	it "should not escape objects with build_markup protocol" do
+		builder = Utopia::Content::Builder.new(nil, nil, nil, {})
+		
+		# Use XRB::Builder.fragment which implements build_markup
+		fragment = XRB::Builder.fragment do |b|
+			b.inline('p') { b.text "Safe HTML" }
+		end
+		
+		builder.text(fragment)
+		
+		expect(builder.output).to be =~ /<p>Safe HTML<\/p>/
+	end
+end