phlex 2.0.0.beta2 → 2.0.0.rc1

data/lib/phlex/sgml.rb

@@ -2,6 +2,10 @@
 
 # **Standard Generalized Markup Language** for behaviour common to {HTML} and {SVG}.
 class Phlex::SGML
+	UNSAFE_ATTRIBUTES = Set.new(%w[srcdoc sandbox http-equiv]).freeze
+	REF_ATTRIBUTES = Set.new(%w[href src action formaction lowsrc dynsrc background ping]).freeze
+
+	autoload :Elements, "phlex/sgml/elements"
 	autoload :SafeObject, "phlex/sgml/safe_object"
 	autoload :SafeValue, "phlex/sgml/safe_value"
 
@@ -15,9 +19,9 @@ class Phlex::SGML
 
 		# Create a new instance of the component.
 		# @note The block will not be delegated {#initialize}. Instead, it will be sent to {#template} when rendering.
-		def new(*, **, &block)
+		def new(*a, **k, &block)
 			if block
-				object = super(*, **, &nil)
+				object = super(*a, **k, &nil)
 				object.instance_exec { @_content_block = block }
 				object
 			else
@@ -25,12 +29,11 @@ class Phlex::SGML
 			end
 		end
 
-		# @api private
 		def __element_method__?(method_name)
 			if instance_methods.include?(method_name)
 				owner = instance_method(method_name).owner
 
-				if Phlex::Elements === owner && owner.registered_elements[method_name]
+				if Phlex::SGML::Elements === owner && owner.__registered_elements__[method_name]
 					true
 				else
 					false
@@ -41,115 +44,68 @@ class Phlex::SGML
 		end
 	end
 
-	# @!method initialize
-	# @abstract Override to define an initializer for your component.
-	# @note Your initializer will not receive a block passed to {.new}. Instead, this block will be sent to {#template} when rendering.
-	# @example
-	# 	def initialize(articles:)
-	# 		@articles = articles
-	# 	end
-
-	# @abstract Override to define a template for your component.
-	# @example
-	# 	def view_template
-	# 		h1 { "👋 Hello World!" }
-	# 	end
-	# @example Your template may yield a content block.
-	# 	def view_template
-	# 		main {
-	# 			h1 { "Hello World" }
-	# 			yield
-	# 		}
-	# 	end
-	# @example Alternatively, you can delegate the content block to an element.
-	# 	def view_template(&block)
-	# 		article(class: "card", &block)
-	# 	end
 	def view_template
 		if block_given?
 			yield
 		end
 	end
 
-	def await(task)
-		case task
-		when defined?(Concurrent::IVar) && Concurrent::IVar
-			flush if task.pending?
-			task.wait.value
-		when defined?(Async::Task) && Async::Task
-			flush if task.running?
-			task.wait
-		else
-			raise Phlex::ArgumentError.new("Expected an asynchronous task / promise.")
-		end
-	end
-
 	def to_proc
 		proc { |c| c.render(self) }
 	end
 
-	# Renders the view and returns the buffer. The default buffer is a mutable String.
-	def call(buffer = +"", context: Phlex::Context.new, view_context: nil, parent: nil, fragments: nil, &block)
+	def call(buffer = +"", context: {}, view_context: nil, parent: nil, fragments: nil, &block)
 		@_buffer = buffer
-		@_context = context
-		@_view_context = view_context
+		@_context = phlex_context = parent&.__context__ || Phlex::Context.new(user_context: context, view_context:)
 		@_parent = parent
 
 		raise Phlex::DoubleRenderError.new("You can't render a #{self.class.name} more than once.") if @_rendered
 		@_rendered = true
 
 		if fragments
-			@_context.target_fragments(fragments)
+			phlex_context.target_fragments(fragments)
 		end
 
 		block ||= @_content_block
 
 		return "" unless render?
 
-		if !parent && Phlex::SUPPORTS_FIBER_STORAGE
-			original_fiber_storage = Fiber[:__phlex_component__]
-			Fiber[:__phlex_component__] = self
-		end
+		Thread.current[:__phlex_component__] = [self, Fiber.current.object_id]
+
+		phlex_context.around_render do
+			before_template(&block)
 
-		@_context.around_render do
 			around_template do
 				if block
-					if Phlex::DeferredRender === self
-						vanish(self, &block)
-						view_template
-					else
-						view_template do |*args|
-							if args.length > 0
-								yield_content_with_args(*args, &block)
-							else
-								yield_content(&block)
-							end
+					view_template do |*args|
+						if args.length > 0
+							__yield_content_with_args__(*args, &block)
+						else
+							__yield_content__(&block)
 						end
 					end
 				else
 					view_template
 				end
 			end
+
+			after_template(&block)
 		end
 
 		unless parent
-			if Phlex::SUPPORTS_FIBER_STORAGE
-				Fiber[:__phlex_component__] = original_fiber_storage
-			end
-			buffer << context.buffer
+			buffer << phlex_context.buffer
 		end
+	ensure
+		Thread.current[:__phlex_component__] = [parent, Fiber.current.object_id]
 	end
 
-	# Access the current render context data
-	# @return the supplied context object, by default a Hash
+	protected def __context__ = @_context
+
 	def context
 		@_context.user_context
 	end
 
-	# Output text content. The text will be HTML-escaped.
-	# @param content [String, Symbol, Integer, void] the content to be output on the buffer. Strings, Symbols, and Integers are handled by `plain` directly, but any object can be handled by overriding `format_object`
-	# @return [nil]
-	# @see #format_object
+	# Output plain text.
 	def plain(content)
 		unless __text__(content)
 			raise Phlex::ArgumentError.new("You've passed an object to plain that is not handled by format_object. See https://rubydoc.info/gems/phlex/Phlex/SGML#format_object-instance_method for more information")
@@ -158,9 +114,7 @@ class Phlex::SGML
 		nil
 	end
 
-	# Output a whitespace character. This is useful for getting inline elements to wrap. If you pass a block, a whitespace will be output before and after yielding the block.
-	# @return [nil]
-	# @yield If a block is given, it yields the block with no arguments.
+	# Output a single space character. If a block is given, a space will be output before and after the block.
 	def whitespace(&)
 		context = @_context
 		return if context.fragments && !context.in_target_fragment
@@ -170,15 +124,16 @@ class Phlex::SGML
 		buffer << " "
 
 		if block_given?
-			yield_content(&)
+			__yield_content__(&)
 			buffer << " "
 		end
 
 		nil
 	end
 
-	# Output an HTML comment.
-	# @return [nil]
+	# Wrap the output in an HTML comment.
+	#
+	# [MDN Docs](https://developer.mozilla.org/en-US/docs/Web/HTML/Comments)
 	def comment(&)
 		context = @_context
 		return if context.fragments && !context.in_target_fragment
@@ -186,15 +141,13 @@ class Phlex::SGML
 		buffer = context.buffer
 
 		buffer << "<!-- "
-		yield_content(&)
+		__yield_content__(&)
 		buffer << " -->"
 
 		nil
 	end
 
-	# This method is very dangerous and should usually be avoided. It will output the given String without any HTML safety. You should never use this method to output unsafe user input.
-	# @param content [String|nil]
-	# @return [nil]
+	# Output the given safe object as-is. You may need to use `safe` to mark a string as a safe object.
 	def raw(content)
 		case content
 		when Phlex::SGML::SafeObject
@@ -210,41 +163,27 @@ class Phlex::SGML
 		nil
 	end
 
-	# Capture a block of output as a String.
-	# @note This only works if the block's receiver is the current component or the block returns a String.
-	# @return [String]
+	# Capture the output of the block and returns it as a string.
 	def capture(*args, &block)
 		return "" unless block
 
 		if args.length > 0
-			@_context.capturing_into(+"") { yield_content_with_args(*args, &block) }
+			@_context.capturing_into(+"") { __yield_content_with_args__(*args, &block) }
 		else
-			@_context.capturing_into(+"") { yield_content(&block) }
+			@_context.capturing_into(+"") { __yield_content__(&block) }
 		end
 	end
 
-	def tag(name, ...)
-		normalized_name = case name
-			when Symbol then name.name.downcase
-			when String then name.downcase
-			else raise Phlex::ArgumentError.new("Expected the tag name as a Symbol or String.")
-		end
-
-		if normalized_name == "script"
-			raise Phlex::ArgumentError.new("You can’t use the `<script>` tag from the `tag` method. Use `unsafe_tag` instead, but be careful if using user input.")
-		end
-
-		if registered_elements[normalized_name]
-			public_send(normalized_name, ...)
+	# Mark the given string as safe for HTML output.
+	def safe(value)
+		case value
+		when String
+			Phlex::SGML::SafeValue.new(value)
 		else
-			raise Phlex::ArgumentError.new("Unknown tag: #{normalized_name}")
+			raise Phlex::ArgumentError.new("Expected a String.")
 		end
 	end
 
-	def safe(value)
-		Phlex::SGML::SafeValue.new(value)
-	end
-
 	alias_method :🦺, :safe
 
 	def flush
@@ -258,23 +197,23 @@ class Phlex::SGML
 	def render(renderable = nil, &)
 		case renderable
 		when Phlex::SGML
-			renderable.call(@_buffer, context: @_context, view_context: @_view_context, parent: self, &)
+			renderable.call(@_buffer, parent: self, &)
 		when Class
 			if renderable < Phlex::SGML
-				renderable.new.call(@_buffer, context: @_context, view_context: @_view_context, parent: self, &)
+				renderable.new.call(@_buffer, parent: self, &)
 			end
 		when Enumerable
 			renderable.each { |r| render(r, &) }
 		when Proc, Method
 			if renderable.arity == 0
-				yield_content_with_no_args(&renderable)
+				__yield_content_with_no_args__(&renderable)
 			else
-				yield_content(&renderable)
+				__yield_content__(&renderable)
 			end
 		when String
 			plain(renderable)
 		when nil
-			yield_content(&) if block_given?
+			__yield_content__(&) if block_given?
 		else
 			raise Phlex::ArgumentError.new("You can't render a #{renderable.inspect}.")
 		end
@@ -284,27 +223,22 @@ class Phlex::SGML
 
 	private
 
-	# Like {#capture} but the output is vanished into a BlackHole buffer.
-	# Because the BlackHole does nothing with the output, this should be faster.
-	# @return [nil]
 	def vanish(*args)
 		return unless block_given?
 
-		@_context.capturing_into(Phlex::BlackHole) { yield(*args) }
+		if args.length > 0
+			@_context.capturing_into(Phlex::Vanish) { yield(*args) }
+		else
+			@_context.capturing_into(Phlex::Vanish) { yield(self) }
+		end
 
 		nil
 	end
 
-	# Determines if the component should render. By default, it returns `true`.
-	# @abstract Override to define your own predicate to prevent rendering.
-	# @return [Boolean]
 	def render?
 		true
 	end
 
-	# Format the object for output
-	# @abstract Override to define your own format handling for different object types. Please remember to call `super` in the case that the passed object doesn't match, so that object formatting can be added at different layers of the inheritance tree.
-	# @return [String]
 	def format_object(object)
 		case object
 		when Float, Integer
@@ -312,74 +246,80 @@ class Phlex::SGML
 		end
 	end
 
-	# @abstract Override this method to hook in around a template render. You can do things before and after calling `super` to render the template. You should always call `super` so that callbacks can be added at different layers of the inheritance tree.
-	# @return [nil]
 	def around_template
-		before_template
 		yield
-		after_template
-
 		nil
 	end
 
-	# @abstract Override this method to hook in right before a template is rendered. Please remember to call `super` so that callbacks can be added at different layers of the inheritance tree.
-	# @return [nil]
 	def before_template
 		nil
 	end
 
-	# @abstract Override this method to hook in right after a template is rendered. Please remember to call `super` so that callbacks can be added at different layers of the inheritance tree.
-	# @return [nil]
 	def after_template
 		nil
 	end
 
-	# Yields the block and checks if it buffered anything. If nothing was buffered, the return value is treated as text. The text is always HTML-escaped.
-	# @yieldparam component [self]
-	# @return [nil]
-	def yield_content
+	def __yield_content__
 		return unless block_given?
 
 		buffer = @_context.buffer
 
 		original_length = buffer.bytesize
 		content = yield(self)
-		__text__(content) if original_length == buffer.bytesize
+		__implicit_output__(content) if original_length == buffer.bytesize
 
 		nil
 	end
 
-	# Same as {#yield_content} but yields no arguments.
-	# @yield Yields the block with no arguments.
-	def yield_content_with_no_args
+	def __yield_content_with_no_args__
 		return unless block_given?
 
 		buffer = @_context.buffer
 
 		original_length = buffer.bytesize
 		content = yield
-		__text__(content) if original_length == buffer.bytesize
+		__implicit_output__(content) if original_length == buffer.bytesize
 
 		nil
 	end
 
-	# Same as {#yield_content} but accepts a splat of arguments to yield. This is slightly slower than {#yield_content}.
-	# @yield [*args] Yields the given arguments.
-	# @return [nil]
-	def yield_content_with_args(*)
+	def __yield_content_with_args__(*a)
 		return unless block_given?
 
 		buffer = @_context.buffer
 
 		original_length = buffer.bytesize
-		content = yield(*)
-		__text__(content) if original_length == buffer.bytesize
+		content = yield(*a)
+		__implicit_output__(content) if original_length == buffer.bytesize
 
 		nil
 	end
 
-	# Performs the same task as the public method #plain, but does not raise an error if an unformattable object is passed
-	# @api private
+	def __implicit_output__(content)
+		context = @_context
+		return true if context.fragments && !context.in_target_fragment
+
+		case content
+		when Phlex::SGML::SafeObject
+			context.buffer << content.to_s
+		when String
+			context.buffer << Phlex::Escape.html_escape(content)
+		when Symbol
+			context.buffer << Phlex::Escape.html_escape(content.name)
+		when nil
+			nil
+		else
+			if (formatted_object = format_object(content))
+				context.buffer << Phlex::Escape.html_escape(formatted_object)
+			else
+				return false
+			end
+		end
+
+		true
+	end
+
+	# same as __implicit_output__ but escapes even `safe` objects
 	def __text__(content)
 		context = @_context
 		return true if context.fragments && !context.in_target_fragment
@@ -402,7 +342,6 @@ class Phlex::SGML
 		true
 	end
 
-	# @api private
 	def __attributes__(attributes, buffer = +"")
 		attributes.each do |k, v|
 			next unless v
@@ -413,78 +352,87 @@ class Phlex::SGML
 				else raise Phlex::ArgumentError.new("Attribute keys should be Strings or Symbols.")
 			end
 
-			lower_name = name.downcase
-
-			unless Phlex::SGML::SafeObject === v
-				if lower_name == "href" && v.to_s.downcase.delete("^a-z:").start_with?("javascript:")
-					next
-				end
-
-				# Detect unsafe attribute names. Attribute names are considered unsafe if they match an event attribute or include unsafe characters.
-				if Phlex::HTML::UNSAFE_ATTRIBUTES.include?(lower_name.delete("^a-z-"))
-					raise Phlex::ArgumentError.new("Unsafe attribute name detected: #{k}.")
-				end
-			end
-
-			if name.match?(/[<>&"']/)
-				raise Phlex::ArgumentError.new("Unsafe attribute name detected: #{k}.")
-			end
-
-			if lower_name.to_sym == :id && k != :id
-				raise Phlex::ArgumentError.new(":id attribute should only be passed as a lowercase symbol.")
-			end
-
-			case v
+			value = case v
 			when true
-				buffer << " " << name
+				true
 			when String
-				buffer << " " << name << '="' << v.gsub('"', "&quot;") << '"'
+				v.gsub('"', "&quot;")
 			when Symbol
-				buffer << " " << name << '="' << v.name.tr("_", "-").gsub('"', "&quot;") << '"'
+				v.name.tr("_", "-").gsub('"', "&quot;")
 			when Integer, Float
-				buffer << " " << name << '="' << v.to_s << '"'
+				v.to_s
 			when Hash
 				case k
-				when :class
-					buffer << " " << name << '="' << __classes__(v).gsub('"', "&quot;") << '"'
 				when :style
-					buffer << " " << name << '="' << __styles__(v).gsub('"', "&quot;") << '"'
+					__styles__(v).gsub('"', "&quot;")
 				else
 					__nested_attributes__(v, "#{name}-", buffer)
 				end
 			when Array
-				value = case k
-				when :class
-					__classes__(v)
+				case k
 				when :style
-					__styles__(v)
+					__styles__(v).gsub('"', "&quot;")
 				else
 					__nested_tokens__(v)
 				end
-
-				buffer << " " << name << '="' << value.gsub('"', "&quot;") << '"'
 			when Set
-				buffer << " " << name << '="' << __nested_tokens__(v.to_a) << '"'
+				case k
+				when :style
+					__styles__(v).gsub('"', "&quot;")
+				else
+					__nested_tokens__(v.to_a)
+				end
 			when Phlex::SGML::SafeObject
-				buffer << " " << name << '="' << v.to_s.gsub('"', "&quot;") << '"'
+				v.to_s.gsub('"', "&quot;")
 			else
-				value = if v.respond_to?(:to_phlex_attribute_value)
-					v.to_phlex_attribute_value
-				elsif v.respond_to?(:to_str)
-					v.to_str
-				else
-					v.to_s
+				raise Phlex::ArgumentError.new("Invalid attribute value for #{k}: #{v.inspect}.")
+			end
+
+			lower_name = name.downcase
+
+			unless Phlex::SGML::SafeObject === v
+				normalized_name = lower_name.delete("^a-z-")
+
+				if value != true && REF_ATTRIBUTES.include?(normalized_name)
+					case value
+					when String
+						if value.downcase.delete("^a-z:").start_with?("javascript:")
+							# We just ignore these because they were likely not specified by the developer.
+							next
+						end
+					else
+						raise Phlex::ArgumentError.new("Invalid attribute value for #{k}: #{v.inspect}.")
+					end
 				end
 
-				buffer << " " << name << '="' << value.gsub('"', "&quot;") << '"'
+				if normalized_name.bytesize > 2 && normalized_name.start_with?("on") && !normalized_name.include?("-")
+					raise Phlex::ArgumentError.new("Unsafe attribute name detected: #{k}.")
+				end
+
+				if UNSAFE_ATTRIBUTES.include?(normalized_name)
+					raise Phlex::ArgumentError.new("Unsafe attribute name detected: #{k}.")
+				end
+			end
+
+			if name.match?(/[<>&"']/)
+				raise Phlex::ArgumentError.new("Unsafe attribute name detected: #{k}.")
+			end
+
+			if lower_name.to_sym == :id && k != :id
+				raise Phlex::ArgumentError.new(":id attribute should only be passed as a lowercase symbol.")
+			end
+
+			case value
+			when true
+				buffer << " " << name
+			when String
+				buffer << " " << name << '="' << value << '"'
 			end
 		end
 
 		buffer
 	end
 
-	# @api private
-	#
 	# Provides the nested-attributes case for serializing out attributes.
 	# This allows us to skip many of the checks the `__attributes__` method must perform.
 	def __nested_attributes__(attributes, base_name, buffer = +"")
@@ -497,6 +445,10 @@ class Phlex::SGML
 				else raise Phlex::ArgumentError.new("Attribute keys should be Strings or Symbols")
 			end
 
+			if name.match?(/[<>&"']/)
+				raise Phlex::ArgumentError.new("Unsafe attribute name detected: #{k}.")
+			end
+
 			case v
 			when true
 				buffer << " " << base_name << name
@@ -512,22 +464,16 @@ class Phlex::SGML
 				buffer << " " << base_name << name << '="' << __nested_tokens__(v) << '"'
 			when Set
 				buffer << " " << base_name << name << '="' << __nested_tokens__(v.to_a) << '"'
+			when Phlex::SGML::SafeObject
+				buffer << " " << base_name << name << '="' << v.to_s.gsub('"', "&quot;") << '"'
 			else
-				value = if v.respond_to?(:to_phlex_attribute_value)
-					v.to_phlex_attribute_value
-				elsif v.respond_to?(:to_str)
-					v.to_str
-				else
-					v.to_s
-				end
-				buffer << " " << base_name << name << '="' << value.gsub('"', "&quot;") << '"'
+				raise Phlex::ArgumentError.new("Invalid attribute value #{v.inspect}.")
 			end
 
 			buffer
 		end
 	end
 
-	# @api private
 	def __nested_tokens__(tokens)
 		buffer = +""
 
@@ -549,93 +495,105 @@ class Phlex::SGML
 				else
 					buffer << token.name.tr("_", "-")
 				end
-			when nil
-				# Do nothing
-			else
+			when Integer, Float, Phlex::SGML::SafeObject
 				if i > 0
 					buffer << " " << token.to_s
 				else
 					buffer << token.to_s
 				end
+			when Array
+				if token.length > 0
+					if i > 0
+						buffer << " " << __nested_tokens__(token)
+					else
+						buffer << __nested_tokens__(token)
+					end
+				end
+			when nil
+				# Do nothing
+			else
+				raise Phlex::ArgumentError.new("Invalid token type: #{token.class}.")
 			end
 
 			i += 1
 		end
 
-		buffer.gsub!('"', "&quot;")
-		buffer
+		buffer.gsub('"', "&quot;")
 	end
 
-	# @api private
-	def __classes__(c)
-		case c
-		when String
-			c
-		when Symbol
-			c.name.tr("_", "-")
+	# Result is **unsafe**, so it should be escaped!
+	def __styles__(styles)
+		case styles
 		when Array, Set
-			c.filter_map { |c| __classes__(c) }.join(" ")
-		when Hash
-			c.filter_map { |c, add|
-				next unless add
-				case c
-					when String then c
-					when Symbol then c.name.tr("_", "-").delete_suffix("?")
-					else raise Phlex::ArgumentError.new("Class keys should be Strings or Symbols.")
+			styles.filter_map do |s|
+				case s
+				when String
+					if s == "" || s.end_with?(";")
+						s
+					else
+						"#{s};"
+					end
+				when Phlex::SGML::SafeObject
+					value = s.to_s
+					value.end_with?(";") ? value : "#{value};"
+				when Hash
+					next __styles__(s)
+				when nil
+					next nil
+				else
+					raise Phlex::ArgumentError.new("Invalid style: #{s.inspect}.")
 				end
-			}.join(" ")
-		when nil, false
-			nil
-		else
-			if c.respond_to?(:to_phlex_attribute_value)
-				c.to_phlex_attribute_value
-			elsif c.respond_to?(:to_str)
-				c.to_str
-			else
-				c.to_s
-			end
-		end
-	end
-
-	# @api private
-	def __styles__(s)
-		style = case s
-		when String
-			s
-		when Symbol
-			s.name.tr("_", "-")
-		when Integer, Float
-			s.to_s
-		when Array, Set
-			s.filter_map { |s| __styles__(s) }.join
+			end.join(" ")
 		when Hash
 			buffer = +""
-			s.each do |k, v|
+			i = 0
+			styles.each do |k, v|
 				prop = case k
-					when String then k
-					when Symbol then k.name.tr("_", "-")
-					else raise Phlex::ArgumentError.new("Style keys should be Strings or Symbols.")
+				when String
+					k
+				when Symbol
+					k.name.tr("_", "-")
+				else
+					raise Phlex::ArgumentError.new("Style keys should be Strings or Symbols.")
 				end
 
-				value = __styles__(v)
+				value = case v
+				when String
+					v
+				when Symbol
+					v.name.tr("_", "-")
+				when Integer, Float, Phlex::SGML::SafeObject
+					v.to_s
+				when nil
+					nil
+				else
+					raise Phlex::ArgumentError.new("Invalid style value: #{v.inspect}")
+				end
 
 				if value
-					buffer << prop << ":" << value
+					if i == 0
+						buffer << prop << ": " << value << ";"
+					else
+						buffer << " " << prop << ": " << value << ";"
+					end
 				end
+
+				i += 1
 			end
+
 			buffer
-		when nil, false
-			return nil
-		else
-			if s.respond_to?(:to_phlex_attribute_value)
-				s.to_phlex_attribute_value
-			elsif s.respond_to?(:to_str)
-				s.to_str
-			else
-				s.to_s
-			end
 		end
+	end
 
-		style.end_with?(";") ? style : "#{style};"
+	private_class_method def self.method_added(method_name)
+		if method_name == :view_template
+			location = instance_method(method_name).source_location[0]
+
+			if location[0] in "/" | "."
+				Phlex.__expand_attribute_cache__(location)
+			end
+		else
+			super
+		end
 	end
 end