phlex 1.6.1 → 1.8.0

data/lib/phlex/html/void_elements.rb

@@ -1,76 +1,77 @@
 # frozen_string_literal: true
 
+# Void HTML elements don't accept content and never have a closing tag.
 module Phlex::HTML::VoidElements
 	extend Phlex::Elements
 
 	# @!method area(**attributes, &content)
-	# 	Outputs an <code>area</code> tag
+	# 	Outputs an `<area>` tag.
 	# 	@return [nil]
 	# 	@see https://developer.mozilla.org/docs/Web/HTML/Element/area
 	register_void_element :area, tag: "area"
 
 	# @!method br(**attributes, &content)
-	# 	Outputs a <code>br</code> tag
+	# 	Outputs a `<br>` tag.
 	# 	@return [nil]
 	# 	@see https://developer.mozilla.org/docs/Web/HTML/Element/br
 	register_void_element :br, tag: "br"
 
 	# @!method embed(**attributes, &content)
-	# 	Outputs an <code>embed</code> tag
+	# 	Outputs an `<embed>` tag.
 	# 	@return [nil]
 	# 	@see https://developer.mozilla.org/docs/Web/HTML/Element/embed
 	register_void_element :embed, tag: "embed"
 
 	# @!method hr(**attributes, &content)
-	# 	Outputs a <code>hr</code> tag
+	# 	Outputs an `<hr>` tag.
 	# 	@return [nil]
 	# 	@see https://developer.mozilla.org/docs/Web/HTML/Element/hr
 	register_void_element :hr, tag: "hr"
 
 	# @!method img(**attributes, &content)
-	# 	Outputs an <code>img</code> tag
+	# 	Outputs an `<img>` tag.
 	# 	@return [nil]
 	# 	@see https://developer.mozilla.org/docs/Web/HTML/Element/img
 	register_void_element :img, tag: "img"
 
 	# @!method input(**attributes, &content)
-	# 	Outputs an <code>input</code> tag
+	# 	Outputs an `<input>` tag.
 	# 	@return [nil]
 	# 	@see https://developer.mozilla.org/docs/Web/HTML/Element/input
 	register_void_element :input, tag: "input"
 
 	# @!method link(**attributes, &content)
-	# 	Outputs a <code>link</code> tag
+	# 	Outputs a `<link>` tag.
 	# 	@return [nil]
 	# 	@see https://developer.mozilla.org/docs/Web/HTML/Element/link
 	register_void_element :link, tag: "link"
 
 	# @!method meta(**attributes, &content)
-	# 	Outputs a <code>meta</code> tag
+	# 	Outputs a `<meta>` tag.
 	# 	@return [nil]
 	# 	@see https://developer.mozilla.org/docs/Web/HTML/Element/meta
 	register_void_element :meta, tag: "meta"
 
 	# @!method param(**attributes, &content)
-	# 	Outputs a <code>param</code> tag
+	# 	Outputs a `<param>` tag.
 	# 	@return [nil]
 	# 	@see https://developer.mozilla.org/docs/Web/HTML/Element/param
 	register_void_element :param, tag: "param"
 
 	# @!method source(**attributes, &content)
-	# 	Outputs a <code>source</code> tag
+	# 	Outputs a `<source>` tag.
 	# 	@return [nil]
 	# 	@see https://developer.mozilla.org/docs/Web/HTML/Element/source
 	register_void_element :source, tag: "source"
 
 	# @!method track(**attributes, &content)
-	# 	Outputs a <code>track</code> tag
+	# 	Outputs a `<track>` tag.
 	# 	@return [nil]
 	# 	@see https://developer.mozilla.org/docs/Web/HTML/Element/track
 	register_void_element :track, tag: "track"
 
 	# @!method col(**attributes, &content)
-	# 	Outputs a <code>col</code> tag
+	# 	Outputs a `<col>` tag.
 	# 	@return [nil]
 	# 	@see https://developer.mozilla.org/docs/Web/HTML/Element/col
 	register_void_element :col, tag: "col"

data/lib/phlex/html.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 module Phlex
+	# @abstract Subclass and define {#template} to create an HTML component class.
 	class HTML < SGML
 		# A list of HTML attributes that have the potential to execute unsafe JavaScript.
 		EVENT_ATTRIBUTES = %w[onabort onafterprint onbeforeprint onbeforeunload onblur oncanplay oncanplaythrough onchange onclick oncontextmenu oncopy oncuechange oncut ondblclick ondrag ondragend ondragenter ondragleave ondragover ondragstart ondrop ondurationchange onemptied onended onerror onfocus onhashchange oninput oninvalid onkeydown onkeypress onkeyup onload onloadeddata onloadedmetadata onloadstart onmessage onmousedown onmousemove onmouseout onmouseover onmouseup onmousewheel onoffline ononline onpagehide onpageshow onpaste onpause onplay onplaying onpopstate onprogress onratechange onreset onresize onscroll onsearch onseeked onseeking onselect onstalled onstorage onsubmit onsuspend ontimeupdate ontoggle onunload onvolumechange onwaiting onwheel].to_h { [_1, true] }.freeze
@@ -29,12 +30,9 @@ module Phlex
 			nil
 		end
 
-		# @deprecated use {#plain} instead.
-		def text(...)
-			warn "DEPRECATED: The `text` method has been deprecated in favour of `plain`. Please use `plain` instead. The `text` method will be removed in a future version of Phlex. Called from: #{caller.first}"
-			plain(...)
-		end
-
+		# Outputs an `<svg>` tag
+		# @return [nil]
+		# @see https://developer.mozilla.org/docs/Web/SVG/Element/svg
 		def svg(...)
 			super do
 				render Phlex::SVG.new do |svg|

data/lib/phlex/overrides/symbol/name.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+# @api private
 module Phlex::Overrides::Symbol::Name
 	refine(Symbol) { alias_method :name, :to_s }
 end

data/lib/phlex/sgml.rb

@@ -5,15 +5,16 @@ if Gem::Version.new(RUBY_VERSION) < Gem::Version.new("3.0")
 end
 
 module Phlex
+	# **Standard Generalized Markup Language** for behaviour common to {HTML} and {SVG}.
 	class SGML
 		class << self
-			# Render the view to a String. Arguments are delegated to <code>new</code>.
+			# Render the view to a String. Arguments are delegated to {.new}.
 			def call(...)
 				new(...).call
 			end
 
 			# Create a new instance of the component.
-			# @note The block will not be delegated to the initializer. Instead, it will be provided to `template` when rendering.
+			# @note The block will not be delegated {#initialize}. Instead, it will be sent to {#template} when rendering.
 			def new(*args, **kwargs, &block)
 				if block
 					object = super(*args, **kwargs, &nil)
@@ -42,22 +43,66 @@ module Phlex
 			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 template
+		# 		h1 { "👋 Hello World!" }
+		# 	end
+		# @example Your template may yield a content block.
+		# 	def template
+		# 		main {
+		# 			h1 { "Hello World" }
+		# 			yield
+		# 		}
+		# 	end
+		# @example Alternatively, you can delegate the content block to an element.
+		# 	def template(&block)
+		# 		article(class: "card", &block)
+		# 	end
+		def template
+			yield
+		end
+
+		# @api private
+		def await(task)
+			if task.is_a?(Concurrent::IVar)
+				flush if task.pending?
+
+				task.wait.value
+			elsif defined?(Async::Task) && task.is_a?(Async::Task)
+				flush if task.running?
+
+				task.wait
+			else
+				raise ArgumentError, "Expected an asynchronous task / promise."
+			end
+		end
+
 		# Renders the view and returns the buffer. The default buffer is a mutable String.
-		def call(buffer = nil, context: Phlex::Context.new, view_context: nil, parent: nil, &block)
+		def call(buffer = +"", context: Phlex::Context.new, view_context: nil, parent: nil, &block)
 			__final_call__(buffer, context: context, view_context: view_context, parent: parent, &block).tap do
 				self.class.rendered_at_least_once!
 			end
 		end
 
 		# @api private
-		def __final_call__(buffer = nil, context: Phlex::Context.new, view_context: nil, parent: nil, &block)
+		def __final_call__(buffer = +"", context: Phlex::Context.new, view_context: nil, parent: nil, &block)
+			@_buffer = buffer
 			@_context = context
 			@_view_context = view_context
 			@_parent = parent
 
 			block ||= @_content_block
 
-			return buffer || context.target unless render?
+			return unless render?
 
 			around_template do
 				if block
@@ -78,47 +123,16 @@ module Phlex
 				end
 			end
 
-			buffer ? (buffer << context.target) : context.target
-		end
-
-		# Render another view
-		# @param renderable [Phlex::SGML]
-		# @return [nil]
-		def render(renderable, &block)
-			case renderable
-			when Phlex::SGML
-				renderable.call(context: @_context, view_context: @_view_context, parent: self, &block)
-			when Class
-				if renderable < Phlex::SGML
-					renderable.new.call(context: @_context, view_context: @_view_context, parent: self, &block)
-				end
-			when Enumerable
-				renderable.each { |r| render(r, &block) }
-			when Proc
-				yield_content(&renderable)
-			else
-				raise ArgumentError, "You can't render a #{renderable}."
-			end
-
-			nil
+			buffer << context.target unless parent
 		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
 		def plain(content)
-			case content
-			when String
-				@_context.target << ERB::Escape.html_escape(content)
-			when Symbol
-				@_context.target << ERB::Escape.html_escape(content.name)
-			when Integer
-				@_context.target << ERB::Escape.html_escape(content.to_s)
-			when nil
-				nil
-			else
-				if (formatted_object = format_object(content))
-					@_context.target << ERB::Escape.html_escape(formatted_object)
-				end
+			unless __text__(content)
+				raise ArgumentError, "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"
 			end
 
 			nil
@@ -126,6 +140,7 @@ module Phlex
 
 		# 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.
 		def whitespace
 			target = @_context.target
 
@@ -170,10 +185,59 @@ module Phlex
 			@_context.with_target(+"") { yield_content(&block) }
 		end
 
-		# Like `capture` but the output is vanished into a BlackHole buffer.
+		private
+
+		# @api private
+		def flush
+			target = @_context.target
+			@_buffer << target.dup
+			target.clear
+		end
+
+		# Render another component, block or enumerable
+		# @return [nil]
+		# @overload render(component, &block)
+		# 	Renders the component.
+		# 	@param component [Phlex::SGML]
+		# @overload render(component_class, &block)
+		# 	Renders a new instance of the component class. This is useful for component classes that take no arguments.
+		# 	@param component_class [Class<Phlex::SGML>]
+		# @overload render(proc)
+		# 	Renders the proc with {#yield_content}.
+		# 	@param proc [Proc]
+		# @overload render(enumerable)
+		# 	Renders each item of the enumerable.
+		# 	@param enumerable [Enumerable]
+		# 	@example
+		# 		render @items
+		def render(renderable, &block)
+			case renderable
+			when Phlex::SGML
+				renderable.call(@_buffer, context: @_context, view_context: @_view_context, parent: self, &block)
+			when Class
+				if renderable < Phlex::SGML
+					renderable.new.call(@_buffer, context: @_context, view_context: @_view_context, parent: self, &block)
+				end
+			when Enumerable
+				renderable.each { |r| render(r, &block) }
+			when Proc
+				if renderable.arity == 0
+					yield_content_with_no_args(&renderable)
+				else
+					yield_content(&renderable)
+				end
+			else
+				raise ArgumentError, "You can't render a #{renderable}."
+			end
+
+			nil
+		end
+
+		# 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]
-		private def __vanish__(*args)
+		# @api private
+		def __vanish__(*args)
 			return unless block_given?
 
 			@_context.with_target(BlackHole) { yield(*args) }
@@ -181,24 +245,26 @@ module Phlex
 			nil
 		end
 
-		# Default render predicate can be overridden to prevent rendering
-		# @return [bool]
-		private def render?
+		# 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]
-		private def format_object(object)
+		def format_object(object)
 			case object
 			when Float
 				object.to_s
 			end
 		end
 
-		# Override this method to hook in around a template render. You can do things before and after calling <code>super</code> to render the template. You should always call <code>super</code> so that callbacks can be added at different layers of the inheritance tree.
+		# @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]
-		private def around_template
+		def around_template
 			before_template
 			yield
 			after_template
@@ -206,55 +272,94 @@ module Phlex
 			nil
 		end
 
-		# Override this method to hook in right before a template is rendered. Please remember to call <code>super</code> so that callbacks can be added at different layers of the inheritance tree.
+		# @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]
-		private def before_template
+		def before_template
 			nil
 		end
 
-		# Override this method to hook in right after a template is rendered. Please remember to call <code>super</code> so that callbacks can be added at different layers of the inheritance tree.
+		# @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]
-		private def after_template
+		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.
+		# 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]
-		private def yield_content
+		def yield_content
 			return unless block_given?
 
 			target = @_context.target
 
 			original_length = target.length
 			content = yield(self)
-			plain(content) if original_length == target.length
+			__text__(content) if original_length == target.length
+
+			nil
+		end
+
+		# Same as {#yield_content} but yields no arguments.
+		# @yield Yields the block with no arguments.
+		def yield_content_with_no_args
+			return unless block_given?
+
+			target = @_context.target
+
+			original_length = target.length
+			content = yield
+			__text__(content) if original_length == target.length
 
 			nil
 		end
 
-		# Same as <code>yield_content</code> but accepts a splat of arguments to yield. This is slightly slower than <code>yield_content</code>, which is why it's defined as a different method because we don't always need arguments so we can usually use <code>yield_content</code> instead.
+		# 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]
-		private def yield_content_with_args(*args)
+		def yield_content_with_args(*args)
 			return unless block_given?
 
 			target = @_context.target
 
 			original_length = target.length
 			content = yield(*args)
-			plain(content) if original_length == target.length
+			__text__(content) if original_length == target.length
 
 			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 __text__(content)
+			case content
+			when String
+				@_context.target << ERB::Escape.html_escape(content)
+			when Symbol
+				@_context.target << ERB::Escape.html_escape(content.name)
+			when Integer
+				@_context.target << content.to_s
+			when nil
+				nil
+			else
+				if (formatted_object = format_object(content))
+					@_context.target << ERB::Escape.html_escape(formatted_object)
+				else
+					return false
+				end
+			end
+
+			true
+		end
+
 		# @api private
-		private def __attributes__(**attributes)
+		def __attributes__(**attributes)
 			__final_attributes__(**attributes).tap do |buffer|
 				Phlex::ATTRIBUTE_CACHE[respond_to?(:process_attributes) ? (attributes.hash + self.class.hash) : attributes.hash] = buffer.freeze
 			end
 		end
 
 		# @api private
-		private def __final_attributes__(**attributes)
+		def __final_attributes__(**attributes)
 			if respond_to?(:process_attributes)
 				attributes = process_attributes(**attributes)
 			end
@@ -274,14 +379,14 @@ module Phlex
 		end
 
 		# @api private
-		private def __build_attributes__(attributes, buffer:)
+		def __build_attributes__(attributes, buffer:)
 			attributes.each do |k, v|
 				next unless v
 
 				name = case k
 					when String then k
 					when Symbol then k.name.tr("_", "-")
-					else k.to_s
+					else raise ArgumentError, "Attribute keys should be Strings or Symbols."
 				end
 
 				# Detect unsafe attribute names. Attribute names are considered unsafe if they match an event attribute or include unsafe characters.
@@ -296,6 +401,8 @@ module Phlex
 					buffer << " " << name << '="' << ERB::Escape.html_escape(v) << '"'
 				when Symbol
 					buffer << " " << name << '="' << ERB::Escape.html_escape(v.name) << '"'
+				when Integer, Float
+					buffer << " " << name << '="' << v.to_s << '"'
 				when Hash
 					__build_attributes__(
 						v.transform_keys { |subkey|
@@ -305,8 +412,12 @@ module Phlex
 							end
 						}, buffer: buffer
 					)
+				when Array
+					buffer << " " << name << '="' << ERB::Escape.html_escape(v.compact.join(" ")) << '"'
+				when Set
+					buffer << " " << name << '="' << ERB::Escape.html_escape(v.to_a.compact.join(" ")) << '"'
 				else
-					buffer << " " << name << '="' << ERB::Escape.html_escape(v.to_s) << '"'
+					buffer << " " << name << '="' << ERB::Escape.html_escape(v.to_str) << '"'
 				end
 			end