phlex 1.9.3 → 1.10.0

data/lib/phlex/html/void_elements.rb

@@ -8,71 +8,71 @@ module Phlex::HTML::VoidElements
 	# 	Outputs an `<area>` tag.
 	# 	@return [nil]
 	# 	@see https://developer.mozilla.org/docs/Web/HTML/Element/area
-	register_void_element :area, tag: "area"
+	register_void_element :area
 
 	# @!method br(**attributes, &content)
 	# 	Outputs a `<br>` tag.
 	# 	@return [nil]
 	# 	@see https://developer.mozilla.org/docs/Web/HTML/Element/br
-	register_void_element :br, tag: "br"
+	register_void_element :br
+
+	# @!method col(**attributes, &content)
+	# 	Outputs a `<col>` tag.
+	# 	@return [nil]
+	# 	@see https://developer.mozilla.org/docs/Web/HTML/Element/col
+	register_void_element :col
 
 	# @!method embed(**attributes, &content)
 	# 	Outputs an `<embed>` tag.
 	# 	@return [nil]
 	# 	@see https://developer.mozilla.org/docs/Web/HTML/Element/embed
-	register_void_element :embed, tag: "embed"
+	register_void_element :embed
 
 	# @!method hr(**attributes, &content)
 	# 	Outputs an `<hr>` tag.
 	# 	@return [nil]
 	# 	@see https://developer.mozilla.org/docs/Web/HTML/Element/hr
-	register_void_element :hr, tag: "hr"
+	register_void_element :hr
 
 	# @!method img(**attributes, &content)
 	# 	Outputs an `<img>` tag.
 	# 	@return [nil]
 	# 	@see https://developer.mozilla.org/docs/Web/HTML/Element/img
-	register_void_element :img, tag: "img"
+	register_void_element :img
 
 	# @!method input(**attributes, &content)
 	# 	Outputs an `<input>` tag.
 	# 	@return [nil]
 	# 	@see https://developer.mozilla.org/docs/Web/HTML/Element/input
-	register_void_element :input, tag: "input"
+	register_void_element :input
 
 	# @!method link(**attributes, &content)
 	# 	Outputs a `<link>` tag.
 	# 	@return [nil]
 	# 	@see https://developer.mozilla.org/docs/Web/HTML/Element/link
-	register_void_element :link, tag: "link"
+	register_void_element :link
 
 	# @!method meta(**attributes, &content)
 	# 	Outputs a `<meta>` tag.
 	# 	@return [nil]
 	# 	@see https://developer.mozilla.org/docs/Web/HTML/Element/meta
-	register_void_element :meta, tag: "meta"
+	register_void_element :meta
 
 	# @!method param(**attributes, &content)
 	# 	Outputs a `<param>` tag.
 	# 	@return [nil]
 	# 	@see https://developer.mozilla.org/docs/Web/HTML/Element/param
-	register_void_element :param, tag: "param"
+	register_void_element :param, deprecated: "⚠️ [DEPRECATION] The <param> tag is deprecated. See https://developer.mozilla.org/en-US/docs/Web/HTML/Element/param"
 
 	# @!method source(**attributes, &content)
 	# 	Outputs a `<source>` tag.
 	# 	@return [nil]
 	# 	@see https://developer.mozilla.org/docs/Web/HTML/Element/source
-	register_void_element :source, tag: "source"
+	register_void_element :source
 
 	# @!method track(**attributes, &content)
 	# 	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 `<col>` tag.
-	# 	@return [nil]
-	# 	@see https://developer.mozilla.org/docs/Web/HTML/Element/col
-	register_void_element :col, tag: "col"
+	register_void_element :track
 end

data/lib/phlex/html.rb

@@ -3,6 +3,9 @@
 module Phlex
 	# @abstract Subclass and define {#template} to create an HTML component class.
 	class HTML < SGML
+		autoload :StandardElements, "phlex/html/standard_elements"
+		autoload :VoidElements, "phlex/html/void_elements"
+
 		# 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
 
@@ -22,11 +25,14 @@ module Phlex
 		end
 
 		extend Elements
-		include Helpers, VoidElements, StandardElements
+		include VoidElements, StandardElements
 
 		# Output an HTML doctype.
 		def doctype
-			@_context.target << "<!DOCTYPE html>"
+			context = @_context
+			return if context.fragments && !context.in_target_fragment
+
+			context.buffer << "<!DOCTYPE html>"
 			nil
 		end
 
@@ -46,6 +52,14 @@ module Phlex
 			self.class.__unbuffered_class__.new(self)
 		end
 
+		def filename
+			nil
+		end
+
+		def content_type
+			"text/html"
+		end
+
 		# This should be extended after all method definitions
 		extend ElementClobberingGuard
 	end

data/lib/phlex/kit.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module Phlex::Kit
+	def self.extended(mod)
+		warn "⚠️ [WARNING] Phlex::Kit is experimental and may be removed from future versions of Phlex."
+		super
+	end
+
+	# When a kit is included in a module, we need to load all of its components.
+	def included(mod)
+		constants.each { |c| const_get(c) if autoload?(c) }
+		super
+	end
+
+	def method_missing(name, *args, **kwargs, &block)
+		if name[0] == name[0].upcase && constants.include?(name) && const_get(name) && methods.include?(name)
+			public_send(name, *args, **kwargs, &block)
+		else
+			super
+		end
+	end
+
+	def respond_to_missing?(name, include_private = false)
+		if name[0] == name[0].upcase && constants.include?(name) && const_get(name) && methods.include?(name)
+			true
+		else
+			super
+		end
+	end
+
+	def const_added(name)
+		return if autoload?(name)
+
+		constant = const_get(name)
+
+		if Class === constant && constant < Phlex::SGML
+			if instance_methods.include?(name)
+				raise NameError, "The instance method `#{name}' is already defined on `#{inspect}`."
+			elsif methods.include?(name)
+				raise NameError, "The method `#{name}' is already defined on `#{inspect}`."
+			end
+
+			constant.include(self)
+
+			define_method(name) do |*args, **kwargs, &block|
+				render(constant.new(*args, **kwargs), &block)
+			end
+
+			define_singleton_method(name) do |*args, **kwargs, &block|
+				if (component = Fiber[:__phlex_component__])
+					component.instance_exec do
+						render(constant.new(*args, **kwargs), &block)
+					end
+				else
+					raise "You can't call `#{name}' outside of a Phlex rendering context."
+				end
+			end
+		end
+
+		super
+	end
+end

data/lib/phlex/sgml.rb

@@ -1,12 +1,10 @@
 # frozen_string_literal: true
 
-if Gem::Version.new(RUBY_VERSION) < Gem::Version.new("3.0")
-	using Phlex::Overrides::Symbol::Name
-end
-
 module Phlex
 	# **Standard Generalized Markup Language** for behaviour common to {HTML} and {SVG}.
 	class SGML
+		include Helpers
+
 		class << self
 			# Render the view to a String. Arguments are delegated to {.new}.
 			def call(...)
@@ -53,33 +51,41 @@ module Phlex
 
 		# @abstract Override to define a template for your component.
 		# @example
-		# 	def template
+		# 	def view_template
 		# 		h1 { "👋 Hello World!" }
 		# 	end
 		# @example Your template may yield a content block.
-		# 	def template
+		# 	def view_template
 		# 		main {
 		# 			h1 { "Hello World" }
 		# 			yield
 		# 		}
 		# 	end
 		# @example Alternatively, you can delegate the content block to an element.
-		# 	def template(&block)
+		# 	def view_template(&block)
 		# 		article(class: "card", &block)
 		# 	end
 		def template
 			yield
 		end
 
-		# @api private
+		def self.method_added(method_name)
+			if method_name == :template
+				Kernel.warn "⚠️ [DEPRECATION] Defining the `template` method on a Phlex component will not be supported in Phlex 2.0. Please rename the method to `view_template` instead."
+			end
+		end
+
+		def view_template(&block)
+			template(&block)
+		end
+
 		def await(task)
-			if task.is_a?(Concurrent::IVar)
+			case task
+			when defined?(Concurrent::IVar) && Concurrent::IVar
 				flush if task.pending?
-
 				task.wait.value
-			elsif defined?(Async::Task) && task.is_a?(Async::Task)
+			when defined?(Async::Task) && Async::Task
 				flush if task.running?
-
 				task.wait
 			else
 				raise ArgumentError, "Expected an asynchronous task / promise."
@@ -87,43 +93,65 @@ module Phlex
 		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, &block)
-			__final_call__(buffer, context: context, view_context: view_context, parent: parent, &block).tap do
+		def call(...)
+			__final_call__(...).tap do
 				self.class.rendered_at_least_once!
 			end
 		end
 
 		# @api private
-		def __final_call__(buffer = +"", context: Phlex::Context.new, view_context: nil, parent: nil, &block)
+		def __final_call__(buffer = +"", context: Phlex::Context.new, view_context: nil, parent: nil, fragments: nil, &block)
 			@_buffer = buffer
 			@_context = context
 			@_view_context = view_context
 			@_parent = parent
+			if fragments
+				warn "⚠️ [WARNING] Selective Rendering is experimental, incomplete, and may change in future versions."
+				@_context.target_fragments(fragments)
+			end
 
 			block ||= @_content_block
 
 			return "" unless render?
 
-			around_template do
-				if block
-					if is_a?(DeferredRender)
-						__vanish__(self, &block)
-						template
-					else
-						template do |*args|
-							if args.length > 0
-								yield_content_with_args(*args, &block)
-							else
-								yield_content(&block)
+			if !parent && Phlex::SUPPORTS_FIBER_STORAGE
+				original_fiber_storage = Fiber[:__phlex_component__]
+				Fiber[:__phlex_component__] = self
+			end
+
+			@_context.around_render do
+				around_template do
+					if block
+						if is_a?(DeferredRender)
+							__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
 							end
 						end
+					else
+						view_template
 					end
-				else
-					template
 				end
 			end
 
-			buffer << context.target unless parent
+			unless parent
+				if Phlex::SUPPORTS_FIBER_STORAGE
+					Fiber[:__phlex_component__] = original_fiber_storage
+				end
+				buffer << context.buffer
+			end
+		end
+
+		# Access the current render context data
+		# @return the supplied context object, by default a Hash
+		def context
+			@_context.user_context
 		end
 
 		# Output text content. The text will be HTML-escaped.
@@ -141,14 +169,17 @@ 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
+		def whitespace(&block)
+			context = @_context
+			return if context.fragments && !context.in_target_fragment
 
-			target << " "
+			buffer = context.buffer
+
+			buffer << " "
 
 			if block_given?
-				yield
-				target << " "
+				yield_content(&block)
+				buffer << " "
 			end
 
 			nil
@@ -157,11 +188,14 @@ module Phlex
 		# Output an HTML comment.
 		# @return [nil]
 		def comment(&block)
-			target = @_context.target
+			context = @_context
+			return if context.fragments && !context.in_target_fragment
+
+			buffer = context.buffer
 
-			target << "<!-- "
+			buffer << "<!-- "
 			yield_content(&block)
-			target << " -->"
+			buffer << " -->"
 
 			nil
 		end
@@ -172,7 +206,10 @@ module Phlex
 		def unsafe_raw(content = nil)
 			return nil unless content
 
-			@_context.target << content
+			context = @_context
+			return if context.fragments && !context.in_target_fragment
+
+			context.buffer << content
 			nil
 		end
 
@@ -191,9 +228,9 @@ module Phlex
 		def flush
 			return if @_context.capturing
 
-			target = @_context.target
-			@_buffer << target.dup
-			target.clear
+			buffer = @_context.buffer
+			@_buffer << buffer.dup
+			buffer.clear
 		end
 
 		# Render another component, block or enumerable
@@ -294,11 +331,11 @@ module Phlex
 		def yield_content
 			return unless block_given?
 
-			target = @_context.target
+			buffer = @_context.buffer
 
-			original_length = target.length
+			original_length = buffer.bytesize
 			content = yield(self)
-			__text__(content) if original_length == target.length
+			__text__(content) if original_length == buffer.bytesize
 
 			nil
 		end
@@ -308,11 +345,11 @@ module Phlex
 		def yield_content_with_no_args
 			return unless block_given?
 
-			target = @_context.target
+			buffer = @_context.buffer
 
-			original_length = target.length
+			original_length = buffer.bytesize
 			content = yield
-			__text__(content) if original_length == target.length
+			__text__(content) if original_length == buffer.bytesize
 
 			nil
 		end
@@ -323,11 +360,11 @@ module Phlex
 		def yield_content_with_args(*args)
 			return unless block_given?
 
-			target = @_context.target
+			buffer = @_context.buffer
 
-			original_length = target.length
+			original_length = buffer.bytesize
 			content = yield(*args)
-			__text__(content) if original_length == target.length
+			__text__(content) if original_length == buffer.bytesize
 
 			nil
 		end
@@ -335,16 +372,19 @@ module Phlex
 		# 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)
+			context = @_context
+			return true if context.fragments && !context.in_target_fragment
+
 			case content
 			when String
-				@_context.target << ERB::Escape.html_escape(content)
+				@_context.buffer << Phlex::Escape.html_escape(content)
 			when Symbol
-				@_context.target << ERB::Escape.html_escape(content.name)
+				@_context.buffer << Phlex::Escape.html_escape(content.name)
 			when nil
 				nil
 			else
 				if (formatted_object = format_object(content))
-					@_context.target << ERB::Escape.html_escape(formatted_object)
+					@_context.buffer << Phlex::Escape.html_escape(formatted_object)
 				else
 					return false
 				end
@@ -384,10 +424,10 @@ module Phlex
 				end
 
 				lower_name = name.downcase
-				next if lower_name == "href" && v.to_s.downcase.tr("^a-z:",	"").start_with?("javascript:")
+				next if lower_name == "href" && v.start_with?(/\s*javascript:/i)
 
 				# Detect unsafe attribute names. Attribute names are considered unsafe if they match an event attribute or include unsafe characters.
-				if HTML::EVENT_ATTRIBUTES.include?(lower_name.tr("^a-z-", "")) || name.match?(/[<>&"']/)
+				if HTML::EVENT_ATTRIBUTES[lower_name] || name.match?(/[<>&"']/)
 					raise ArgumentError, "Unsafe attribute name detected: #{k}."
 				end
 
@@ -395,26 +435,34 @@ module Phlex
 				when true
 					buffer << " " << name
 				when String
-					buffer << " " << name << '="' << ERB::Escape.html_escape(v) << '"'
+					buffer << " " << name << '="' << Phlex::Escape.html_escape(v) << '"'
 				when Symbol
-					buffer << " " << name << '="' << ERB::Escape.html_escape(v.name) << '"'
+					buffer << " " << name << '="' << Phlex::Escape.html_escape(v.name) << '"'
 				when Integer, Float
 					buffer << " " << name << '="' << v.to_s << '"'
 				when Hash
 					__build_attributes__(
 						v.transform_keys { |subkey|
 							case subkey
-								when Symbol then"#{k}-#{subkey.name.tr('_', '-')}"
-								else "#{k}-#{subkey}"
+								when Symbol then"#{name}-#{subkey.name.tr('_', '-')}"
+								else "#{name}-#{subkey}"
 							end
 						}, buffer: buffer
 					)
 				when Array
-					buffer << " " << name << '="' << ERB::Escape.html_escape(v.compact.join(" ")) << '"'
+					buffer << " " << name << '="' << Phlex::Escape.html_escape(v.compact.join(" ")) << '"'
 				when Set
-					buffer << " " << name << '="' << ERB::Escape.html_escape(v.to_a.compact.join(" ")) << '"'
+					buffer << " " << name << '="' << Phlex::Escape.html_escape(v.to_a.compact.join(" ")) << '"'
 				else
-					buffer << " " << name << '="' << ERB::Escape.html_escape(v.to_str) << '"'
+					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 << " " << name << '="' << Phlex::Escape.html_escape(value) << '"'
 				end
 			end