phlex 1.11.0 → 2.0.0.beta1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 91e06f170cfccd6ef24d00ef34643293d36c9df7540ffb3fe482577c4a115898
-  data.tar.gz: 9eb38a0b368e1543789252f6ba8cb80df204b73fc81d413fc47b758adba191bc
+  metadata.gz: fd808f50305105b7fb8cde4624804427da99fa7a3e59a20f6442e1db35e0983d
+  data.tar.gz: f3e7f7b703a27e3a00bbea42749e4682ac0255a3c3c12abca5c94f90de1be23c
 SHA512:
-  metadata.gz: 4f2587dff9519706d7ec91c2745da7570c74a097b0282c0462504a54cc296312f1aee386a6645f1df5e7f503e1398df72681d345d18e5866f13a4dfcd4c4db1c
-  data.tar.gz: 3de0960cc4510e025620308ed8ae6c0b5594d3ee8a153b11c5c3eabdc74d3aa94193717f9a6fbc47fa378e8b7bbcd171a35bcfa3f486e66800bffd8da01bc033
+  metadata.gz: d66595c47ec3704a3b06c619e2fe8697252a8e9f5566be7c0c8082c06c69a46361686135411f04268854a1a087a78b24e072e7ca4fa98fd23b64dfaa147f6f07
+  data.tar.gz: e93c80673a2ca16d9585d76b8c348ec0a7ddf04013720d083dc064b432aaf7f1642bbe5a6b8622fea6c18eb453f663de0d36929bd903f3b40a7f243987a46dee

data/README.md

@@ -1,10 +1,24 @@
 <a href="https://www.phlex.fun/"><img alt="Phlex logo" src="https://www.phlex.fun/assets/logo.png" width="180" /></a>
 
-Phlex lets you compose web views in pure Ruby — kind of like JSX, but not really anything like JSX. It’s super-fast, thread-safe and supports TruffleRuby v22.2+, JRuby v9.2+ and MRI v2.7+. Phlex currently supports [HTML](https://rubydoc.info/gems/phlex/Phlex/HTML) and [SVG](https://rubydoc.info/gems/phlex/Phlex/SVG) views, and we’re exploring JSON and XML.
+Phlex lets you compose web views in pure Ruby.
 
-Docs and more at [Phlex.fun](https://www.phlex.fun/)
+- [1.0 Stable Docs](https://www.phlex.fun)
+- [2.0 Beta Docs](https://beta.phlex.fun)
 
-### Prior Art 🎨
+## Maintenance schedule
+
+### Bug fixes
+
+- Only the latest minor version of each major version will receive bug fixes
+- We may choose to fix bugs by releasing a new minor version rather than patching the existing minor version
+- Major versions will stop receiving bug fixes one year after the next major version is released
+
+### Security patches
+
+- When a security issue is brought to our attention, we aim to release patches for any minor version that was released in the last year.
+- Additionally, the latest minor version of the latest major version will receive security patches, even if that version is over a year old.
+
+## Prior Art 🎨
 
 - [markaby](https://github.com/markaby/markaby)
 - [erector](https://github.com/erector/erector)
@@ -17,3 +31,7 @@ Docs and more at [Phlex.fun](https://www.phlex.fun/)
 - [clearwater](https://github.com/clearwater-rb/clearwater)
 - [paggio](https://github.com/opal/paggio)
 - [Inesita](https://github.com/inesita-rb/inesita)
+- [compony](https://github.com/kalsan/compony)
+- [tagz](https://github.com/ahoward/tagz)
+- [html](https://github.com/ismasan/html)
+- [fortitude](https://github.com/ageweke/fortitude)

data/lib/phlex/context.rb

@@ -15,11 +15,6 @@ class Phlex::Context
 
 	attr_reader :fragments
 
-	# Added for backwards compatibility with phlex-rails. We can remove this with 2.0
-	def target
-		@buffer
-	end
-
 	def target_fragments(fragments)
 		@fragments = fragments.to_h { |it| [it, true] }
 	end

data/lib/phlex/csv.rb

@@ -1,10 +1,8 @@
 # frozen_string_literal: true
 
 class Phlex::CSV
-	include Phlex::Callable
-
-	FORMULA_PREFIXES = ["=", "+", "-", "@", "\t", "\r"].to_h { |prefix| [prefix, true] }.freeze
-	SPACE_CHARACTERS = [" ", "\t", "\r"].to_h { |char| [char, true] }.freeze
+	FORMULA_PREFIXES = Set["=", "+", "-", "@", "\t", "\r"].freeze
+	SPACE_CHARACTERS = Set[" ", "\t", "\r"].freeze
 
 	def initialize(collection)
 		@collection = collection
@@ -84,18 +82,14 @@ class Phlex::CSV
 		@_current_column_index += 1
 	end
 
-	def each_item(&block)
-		collection.each(&block)
+	def each_item(&)
+		collection.each(&)
 	end
 
 	def yielder(record)
 		yield(record)
 	end
 
-	def template(...)
-		nil
-	end
-
 	# Override and set to `false` to disable rendering headers.
 	def render_headers?
 		true
@@ -120,11 +114,11 @@ class Phlex::CSV
 		first_char = value[0]
 		last_char = value[-1]
 
-		if escape_csv_injection? && FORMULA_PREFIXES[first_char]
+		if escape_csv_injection? && FORMULA_PREFIXES.include?(first_char)
 			# Prefix a single quote to prevent Excel, Google Docs, etc. from interpreting the value as a formula.
 			# See https://owasp.org/www-community/attacks/CSV_Injection
 			%("'#{value.gsub('"', '""')}")
-		elsif (!trim_whitespace? && (SPACE_CHARACTERS[first_char] || SPACE_CHARACTERS[last_char])) || value.include?('"') || value.include?(",") || value.include?("\n")
+		elsif (!trim_whitespace? && (SPACE_CHARACTERS.include?(first_char) || SPACE_CHARACTERS.include?(last_char))) || value.include?('"') || value.include?(",") || value.include?("\n")
 			%("#{value.gsub('"', '""')}")
 		else
 			value

data/lib/phlex/element_clobbering_guard.rb

@@ -3,8 +3,12 @@
 # @api private
 module Phlex::ElementClobberingGuard
 	def method_added(method_name)
-		if method_name[0] == "_" && element_method?(method_name[1..].to_sym)
-			raise Phlex::NameError, "👋 Redefining the method `#{name}##{method_name}` is not a good idea."
+		if method_name[0] == "_" && __element_method__?(method_name[1..].to_sym)
+			raise Phlex::NameError.new("👋 Redefining the method `#{name}##{method_name}` is not a good idea.")
+		elsif method_name == :view_template
+			Phlex.__expand_attribute_cache__(
+				instance_method(method_name).source_location[0],
+			)
 		else
 			super
 		end

data/lib/phlex/elements.rb

@@ -28,25 +28,16 @@ module Phlex::Elements
 	# @note The methods defined by this macro depend on other methods from {SGML} so they should always be mixed into an {HTML} or {SVG} component.
 	# @example Register the custom element `<trix-editor>`
 	# 	register_element :trix_editor
-	def register_element(method_name, tag: method_name.name.tr("_", "-"), deprecated: false)
-		if deprecated
-			deprecation = <<~RUBY
-				Kernel.warn "#{deprecated}"
-			RUBY
-		else
-			deprecation = ""
-		end
-
+	def register_element(method_name, tag: method_name.name.tr("_", "-"))
 		class_eval(<<-RUBY, __FILE__, __LINE__ + 1)
 			# frozen_string_literal: true
 
-			def #{method_name}(**attributes, &block)
-				#{deprecation}
-
+			def #{method_name}(**attributes)
 				context = @_context
 				buffer = context.buffer
 				fragment = context.fragments
 				target_found = false
+				block_given = block_given?
 
 				if fragment
 					return if fragment.length == 0 # we found all our fragments already
@@ -58,26 +49,64 @@ module Phlex::Elements
 							context.begin_target(id)
 							target_found = true
 						else
-							yield(self) if block
+							yield(self) if block_given
 							return nil
 						end
 					end
 				end
 
 				if attributes.length > 0 # with attributes
-					if block # with content block
-						buffer << "<#{tag}" << (Phlex::ATTRIBUTE_CACHE[respond_to?(:process_attributes) ? (attributes.hash + self.class.hash) : attributes.hash] || __attributes__(**attributes)) << ">"
-						yield_content(&block)
+					if block_given # with content block
+						buffer << "<#{tag}" << (Phlex::ATTRIBUTE_CACHE[attributes] ||= __attributes__(attributes)) << ">"
+
+						original_length = buffer.bytesize
+						content = yield(self)
+						if original_length == buffer.bytesize
+							case content
+							when String
+								buffer << Phlex::Escape.html_escape(content)
+							when Symbol
+								buffer << Phlex::Escape.html_escape(content.name)
+							when nil
+								nil
+							when Phlex::SGML::SafeObject
+								buffer << content.to_s
+							else
+								if (formatted_object = format_object(content))
+									buffer << Phlex::Escape.html_escape(formatted_object)
+								end
+							end
+						end
+
 						buffer << "</#{tag}>"
-					else # without content block
-						buffer << "<#{tag}" << (Phlex::ATTRIBUTE_CACHE[respond_to?(:process_attributes) ? (attributes.hash + self.class.hash) : attributes.hash] || __attributes__(**attributes)) << "></#{tag}>"
+					else # without content
+						buffer << "<#{tag}" << (Phlex::ATTRIBUTE_CACHE[attributes] ||= __attributes__(attributes)) << "></#{tag}>"
 					end
 				else # without attributes
-					if block # with content block
+					if block_given # with content block
 						buffer << "<#{tag}>"
-						yield_content(&block)
+
+						original_length = buffer.bytesize
+						content = yield(self)
+						if original_length == buffer.bytesize
+							case content
+							when String
+								buffer << Phlex::Escape.html_escape(content)
+							when Symbol
+								buffer << Phlex::Escape.html_escape(content.name)
+							when nil
+								nil
+							when Phlex::SGML::SafeObject
+								buffer << content.to_s
+							else
+								if (formatted_object = format_object(content))
+									buffer << Phlex::Escape.html_escape(formatted_object)
+								end
+							end
+						end
+
 						buffer << "</#{tag}>"
-					else # without content block
+					else # without content
 						buffer << "<#{tag}></#{tag}>"
 					end
 				end
@@ -98,20 +127,11 @@ module Phlex::Elements
 	end
 
 	# @api private
-	def register_void_element(method_name, tag: method_name.name.tr("_", "-"), deprecated: false)
-		if deprecated
-			deprecation = <<~RUBY
-				Kernel.warn "#{deprecated}"
-			RUBY
-		else
-			deprecation = ""
-		end
-
+	def register_void_element(method_name, tag: method_name.name.tr("_", "-"))
 		class_eval(<<-RUBY, __FILE__, __LINE__ + 1)
 			# frozen_string_literal: true
 
 			def #{method_name}(**attributes)
-				#{deprecation}
 				context = @_context
 				buffer = context.buffer
 				fragment = context.fragments
@@ -132,7 +152,7 @@ module Phlex::Elements
 				end
 
 				if attributes.length > 0 # with attributes
-					buffer << "<#{tag}" << (Phlex::ATTRIBUTE_CACHE[respond_to?(:process_attributes) ? (attributes.hash + self.class.hash) : attributes.hash] || __attributes__(**attributes)) << ">"
+					buffer << "<#{tag}" << (Phlex::ATTRIBUTE_CACHE[attributes] ||= __attributes__(attributes)) << ">"
 				else # without attributes
 					buffer << "<#{tag}>"
 				end

data/lib/phlex/error.rb

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+
+module Phlex::Error
+end

data/lib/phlex/errors/argument_error.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+class Phlex::ArgumentError < ArgumentError
+	include Phlex::Error
+end

data/lib/phlex/errors/double_render_error.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+class Phlex::DoubleRenderError < RuntimeError
+	include Phlex::Error
+end

data/lib/phlex/errors/name_error.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+class Phlex::NameError < NameError
+	include Phlex::Error
+end

data/lib/phlex/fifo.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+class Phlex::FIFO
+	def initialize(max_bytesize: 2_000, max_value_bytesize: 2_000)
+		@store = {}
+		@max_bytesize = max_bytesize
+		@max_value_bytesize = max_value_bytesize
+		@bytesize = 0
+		@mutex = Mutex.new
+	end
+
+	attr_reader :bytesize, :max_bytesize
+
+	def expand(bytes)
+		@mutex.synchronize do
+			@max_bytesize += bytes
+		end
+	end
+
+	def [](key)
+		k, v = @store[key.hash]
+		v if k == key
+	end
+
+	def []=(key, value)
+		return if value.bytesize > @max_value_bytesize
+
+		digest = key.hash
+
+		@mutex.synchronize do
+			# Check the key definitely doesn't exist now we have the lock
+			return if @store[digest]
+
+			@store[digest] = [key, value]
+			@bytesize += value.bytesize
+
+			while @bytesize > @max_bytesize
+				k, v = @store.shift
+				@bytesize -= v[1].bytesize
+			end
+		end
+	end
+
+	def size
+		@store.size
+	end
+end

data/lib/phlex/helpers.rb

@@ -1,104 +1,31 @@
 # frozen_string_literal: true
 
-require "set"
-
 module Phlex::Helpers
 	private
 
-	# Tokens
-	# @return [String]
-	# @example With Proc conditions
-	# 	tokens(
-	# 		-> { true } => "a",
-	# 		-> { false } => "b"
-	# 	)
-	# @example With method conditions
-	# 	tokens(
-	# 		active?: "active"
-	# 	)
-	# @example With else condition
-	# 	tokens(
-	# 		active?: { then: "active", else: "inactive" }
-	# 	)
-	def tokens(*tokens, **conditional_tokens)
-		conditional_tokens.each do |condition, token|
-			truthy = case condition
-				when Symbol then send(condition)
-				when Proc then condition.call
-				else raise ArgumentError, "The class condition must be a Symbol or a Proc."
-			end
-
-			if truthy
-				case token
-					when Hash then __append_token__(tokens, token[:then])
-					else __append_token__(tokens, token)
-				end
-			else
-				case token
-					when Hash then __append_token__(tokens, token[:else])
-				end
-			end
-		end
-
-		tokens = tokens.select(&:itself).join(" ")
-		tokens.strip!
-		tokens.gsub!(/\s+/, " ")
-		tokens
-	end
-
-	# @api private
-	def __append_token__(tokens, token)
-		case token
-			when nil then nil
-			when String then tokens << token
-			when Symbol then tokens << token.name
-			when Array then tokens.concat(token)
-			else raise ArgumentError,
-				"Conditional classes must be Symbols, Strings, or Arrays of Symbols or Strings."
-		end
-	end
-
-	# Like {#tokens} but returns a {Hash} where the tokens are the value for `:class`.
-	# @return [Hash]
-	def classes(*tokens, **conditional_tokens)
-		tokens = self.tokens(*tokens, **conditional_tokens)
-
-		if tokens.empty?
-			{}
-		else
-			{ class: tokens }
-		end
-	end
-
 	# @return [Hash]
 	def mix(*args)
 		args.each_with_object({}) do |object, result|
 			result.merge!(object) do |_key, old, new|
-				next new if old.nil?
-
-				case new
-				when Hash
-					old.is_a?(Hash) ? mix(old, new) : new
-				when Array
-					case old
-					when Array then old + new
-					when Set then old.to_a + new
-					when Hash then new
-					else
-						[old] + new
-					end
-				when Set
-					case old
-					when Set then old + new
-					when Array then old + new.to_a
-					when Hash then new
-					else
-						new + [old]
-					end
-				when String
-					old.is_a?(String) ? "#{old} #{new}" : old + old.class[new]
-				when nil
-					old
+				case [old, new]
+				in [Array, Array] | [Set, Set]
+					old + new
+				in [Array, Set]
+					old + new.to_a
+				in [Array, String]
+					old + [new]
+				in [Hash, Hash]
+					mix(old, new)
+				in [Set, Array]
+					old.to_a + new
+				in [Set, String]
+					old.to_a + [new]
+				in [String, Array]
+					[old] + new
+				in [String, Set]
+					[old] + new.to_a
+				in [String, String]
+					"#{old} #{new}"
 				else
 					new
 				end
@@ -109,4 +36,12 @@ module Phlex::Helpers
 			end
 		end
 	end
+
+	def grab(**bindings)
+		if bindings.size > 1
+			bindings.values
+		else
+			bindings.values.first
+		end
+	end
 end

data/lib/phlex/html/standard_elements.rb

@@ -639,7 +639,7 @@ module Phlex::HTML::StandardElements
 	# 	@return [nil]
 	# 	@yieldparam component [self]
 	# 	@see https://developer.mozilla.org/docs/Web/HTML/Element/template
-	register_element :template_tag, tag: "template"
+	register_element :template
 
 	# @!method textarea(**attributes, &content)
 	# 	Outputs a `<textarea>` tag.

data/lib/phlex/html/void_elements.rb

@@ -58,12 +58,6 @@ module Phlex::HTML::VoidElements
 	# 	@see https://developer.mozilla.org/docs/Web/HTML/Element/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, 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]

data/lib/phlex/html.rb

@@ -1,66 +1,47 @@
 # frozen_string_literal: true
 
-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"
+class Phlex::HTML < Phlex::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
+	# A list of HTML attributes that have the potential to execute unsafe JavaScript.
+	UNSAFE_ATTRIBUTES = Set.new(%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 srcdoc]).freeze
 
-		UNBUFFERED_MUTEX = Mutex.new
+	extend Phlex::Elements
+	include VoidElements, StandardElements
 
-		class << self
-			# @api private
-			def __unbuffered_class__
-				UNBUFFERED_MUTEX.synchronize do
-					if defined? @unbuffered_class
-						@unbuffered_class
-					else
-						@unbuffered_class = Class.new(Unbuffered)
-					end
-				end
-			end
-		end
-
-		extend Elements
-		include VoidElements, StandardElements
+	# Output an HTML doctype.
+	def doctype
+		context = @_context
+		return if context.fragments && !context.in_target_fragment
 
-		# Output an HTML doctype.
-		def doctype
-			context = @_context
-			return if context.fragments && !context.in_target_fragment
-
-			context.buffer << "<!DOCTYPE html>"
-			nil
-		end
+		context.buffer << "<!doctype html>"
+		nil
+	end
 
-		# Outputs an `<svg>` tag
-		# @return [nil]
-		# @see https://developer.mozilla.org/docs/Web/SVG/Element/svg
-		def svg(...)
+	# Outputs an `<svg>` tag
+	# @return [nil]
+	# @see https://developer.mozilla.org/docs/Web/SVG/Element/svg
+	def svg(...)
+		if block_given?
 			super do
 				render Phlex::SVG.new do |svg|
 					yield(svg)
 				end
 			end
+		else
+			super
 		end
+	end
 
-		# @api private
-		def unbuffered
-			self.class.__unbuffered_class__.new(self)
-		end
-
-		def filename
-			nil
-		end
-
-		def content_type
-			"text/html"
-		end
+	def filename
+		nil
+	end
 
-		# This should be extended after all method definitions
-		extend ElementClobberingGuard
+	def content_type
+		"text/html"
 	end
+
+	# This should be extended after all method definitions
+	extend Phlex::ElementClobberingGuard
 end

data/lib/phlex/kit.rb

@@ -2,9 +2,9 @@
 
 module Phlex::Kit
 	module LazyLoader
-		def method_missing(name, *args, **kwargs, &block)
+		def method_missing(name, ...)
 			if name[0] == name[0].upcase && __phlex_kit_constants__.include?(name) && __get_phlex_kit_constant__(name) && methods.include?(name)
-				public_send(name, *args, **kwargs, &block)
+				public_send(name, ...)
 			else
 				super
 			end
@@ -38,18 +38,14 @@ module Phlex::Kit
 	def const_added(name)
 		return if autoload?(name)
 
+		me = self
 		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|
+				constant = me.const_get(name)
 				render(constant.new(*args, **kwargs), &block)
 			end
 

data/lib/phlex/sgml/safe_object.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+# @api private
+module Phlex::SGML::SafeObject
+	# This is included in objects that are safe to render in an SGML context.
+	# They must implement a `to_s` method that returns a string.
+end

data/lib/phlex/sgml/safe_value.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+class Phlex::SGML::SafeValue
+	include Phlex::SGML::SafeObject
+
+	def initialize(to_s)
+		@to_s = to_s
+	end
+
+	attr_reader :to_s
+end