phlex 1.4.0 → 1.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a8a6c8dfab161746b6b4e04d403fead1f2477f195ff27e72365838f169ecc287
-  data.tar.gz: e9e9da3414eba5fc53d5440b16c0eecf47d4fc5d09a178fe44c9acab3f554119
+  metadata.gz: 4a1ec24fb4717ac1f83f1d43f87db1d9674cfdc7ab1ad2ca5479d1918a7da14d
+  data.tar.gz: 0e3bc60aff556fcf4e2005dc059033f9bbf45f168a0f7626aaa351cf87a75df0
 SHA512:
-  metadata.gz: 043c059dd8ce067a50df40c293d61475892acc934a4efdd18bedae7094ebaea3c9dd11a4bc5e5b7779120d38966964a2725dcd17de3dca2de48c50e837e2e8fd
-  data.tar.gz: 00edaf160d669c8f62f40c4f66faf17a6b76b2428648be0d7c7977ad629b119a146cfacffc8636312f87e46b77cdfc3074fe39ade0b4ff45ee10e874f0459a31
+  metadata.gz: 44d1682ad2d052e8394420dccfaf3ff286d293f2a86d7bc685c704e5d2f2fcbd9f50bb06a189a8e6407bc2886bdc5f9de9e62b61aa79c8c82226ff65c719c950
+  data.tar.gz: 38d9e4e9665c67479da8dd6633613807f38b69a40c24cc1e15583c6a89f34ef1f37edadee244325389d6bd7f11442b9fa977a65a783293a34e509b713ebd8819

data/Gemfile

@@ -7,10 +7,7 @@ gemspec
 
 gem "rubocop"
 gem "sus"
-gem "zeitwerk"
 gem "benchmark-ips"
-gem "erb"
-gem "ruby-lsp"
 
 group :test do
 	gem "i18n"

data/README.md

@@ -10,6 +10,17 @@ Documentation can be found at [www.phlex.fun](https://www.phlex.fun).
 
 If you run into any trouble, please [start a discussion](https://github.com/joeldrapper/phlex/discussions/new), or [open an issue](https://github.com/joeldrapper/phlex/issues/new) if you think you’ve found a bug.
 
+### Ecosystem 🌱
+- [joeldrapper/phlex-rails](https://github.com/joeldrapper/phlex-rails) — Ruby on Rails integration
+- [joeldrapper/phlex.fun](https://github.com/joeldrapper/phlex.fun) — Docs Website
+- [joeldrapper/phlex-markdown](https://github.com/joeldrapper/phlex-markdown) — Markdown to HTML using Phlex
+- [joeldrapper/phlex-compiler](https://github.com/joeldrapper/phlex-compiler) — A compiler for Phlex
+- [joeldrapper/phlex-translation](https://github.com/joeldrapper/phlex-translation) — I18n Support for Phlex 
+- [joeldrapper/phlex-testing-nokogiri](https://github.com/joeldrapper/phlex-testing-nokogiri) — Nokogiri support
+- [joeldrapper/phlex-testing-capybara](https://github.com/joeldrapper/phlex-testing-capybara) — Capybara support
+- [marcoroth/phlexing](https://github.com/marcoroth/phlexing) — ERB → Phlex converter
+- [ViewComponent/lookbook](https://github.com/ViewComponent/lookbook) — Document and preview Phlex components in Rails (v2 beta only)
+
 ### Community 🙌
 
 Everyone interacting in Phlex codebases, issue trackers or chat rooms is expected to follow the [code of conduct](https://github.com/joeldrapper/phlex/blob/main/CODE_OF_CONDUCT.md).

data/lib/phlex/element_clobbering_guard.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Phlex
+	module ElementClobberingGuard
+		def method_added(method_name)
+			if method_name[0] == "_" && private_instance_methods.include?(:"__phlex#{method_name}__")
+				raise NameError, "👋 Redefining the method `#{name}##{method_name}` is not a good idea."
+			end
+
+			super
+		end
+	end
+end

data/lib/phlex/elements.rb

@@ -5,25 +5,33 @@ if Gem::Version.new(RUBY_VERSION) < Gem::Version.new("3.0")
 end
 
 module Phlex::Elements
+	private def slow_registered_elements
+		private_instance_methods
+			.lazy
+			.map(&:to_s)
+			.select { |m| m.start_with?("__phlex_") }
+			.map { |m| m[8...-2].to_sym }
+	end
+
 	def register_element(element, tag: element.name.tr("_", "-"))
 		class_eval(<<-RUBY, __FILE__, __LINE__ + 1)
 			# frozen_string_literal: true
 
-			def #{element}(**attributes, &block)
-				if attributes.length > 0
-					if block_given?
-						@_target << "<#{tag}" << (Phlex::ATTRIBUTE_CACHE[attributes.hash] || __attributes__(**attributes)) << ">"
+			def __phlex_#{element}__(**attributes, &block)
+				if attributes.length > 0 # with attributes
+					if block_given? # with content block
+						@_target << "<#{tag}" << (Phlex::ATTRIBUTE_CACHE[respond_to?(:process_attributes) ? (attributes.hash + self.class.hash) : attributes.hash] || __attributes__(**attributes)) << ">"
 						yield_content(&block)
 						@_target << "</#{tag}>"
-					else
-						@_target << "<#{tag}" << (Phlex::ATTRIBUTE_CACHE[attributes.hash] || __attributes__(**attributes)) << "></#{tag}>"
+					else # without content block
+						@_target << "<#{tag}" << (Phlex::ATTRIBUTE_CACHE[respond_to?(:process_attributes) ? (attributes.hash + self.class.hash) : attributes.hash] || __attributes__(**attributes)) << "></#{tag}>"
 					end
-				else
-					if block_given?
+				else # without attributes
+					if block_given? # with content block
 						@_target << "<#{tag}>"
 						yield_content(&block)
 						@_target << "</#{tag}>"
-					else
+					else # without content block
 						@_target << "<#{tag}></#{tag}>"
 					end
 				end
@@ -31,11 +39,11 @@ module Phlex::Elements
 				nil
 			end
 
-			alias_method :_#{element}, :#{element}
+			alias_method :_#{element}, :__phlex_#{element}__
+			alias_method :#{element}, :__phlex_#{element}__
+			private :__phlex_#{element}__
 		RUBY
 
-		self::REGISTERED_ELEMENTS[element] = tag
-
 		element
 	end
 
@@ -43,21 +51,21 @@ module Phlex::Elements
 		class_eval(<<-RUBY, __FILE__, __LINE__ + 1)
 			# frozen_string_literal: true
 
-			def #{element}(**attributes)
-				if attributes.length > 0
-					@_target << "<#{tag}" << (Phlex::ATTRIBUTE_CACHE[attributes.hash] || __attributes__(**attributes)) << ">"
-				else
+			def __phlex_#{element}__(**attributes)
+				if attributes.length > 0 # with attributes
+					@_target << "<#{tag}" << (Phlex::ATTRIBUTE_CACHE[respond_to?(:process_attributes) ? (attributes.hash + self.class.hash) : attributes.hash] || __attributes__(**attributes)) << ">"
+				else # without attributes
 					@_target << "<#{tag}>"
 				end
 
 				nil
 			end
 
-			alias_method :_#{element}, :#{element}
+			alias_method :_#{element}, :__phlex_#{element}__
+			alias_method :#{element}, :__phlex_#{element}__
+			private :__phlex_#{element}__
 		RUBY
 
-		self::REGISTERED_ELEMENTS[element] = tag
-
 		element
 	end
 end

data/lib/phlex/helpers.rb

@@ -5,6 +5,7 @@ if Gem::Version.new(RUBY_VERSION) < Gem::Version.new("3.0")
 end
 
 module Phlex::Helpers
+	# @return [String]
 	private def tokens(*tokens, **conditional_tokens)
 		conditional_tokens.each do |condition, token|
 			truthy = case condition
@@ -31,6 +32,7 @@ module Phlex::Helpers
 		tokens
 	end
 
+	# @api private
 	private def __append_token__(tokens, token)
 		case token
 			when nil then nil
@@ -42,6 +44,7 @@ module Phlex::Helpers
 		end
 	end
 
+	# @return [Hash]
 	private def classes(*tokens, **conditional_tokens)
 		tokens = self.tokens(*tokens, **conditional_tokens)
 
@@ -52,6 +55,7 @@ module Phlex::Helpers
 		end
 	end
 
+	# @return [Hash]
 	private def mix(*args)
 		args.each_with_object({}) do |object, result|
 			result.merge!(object) do |_key, old, new|

data/lib/phlex/html/standard_elements.rb

@@ -3,8 +3,6 @@
 module Phlex::HTML::StandardElements
 	extend Phlex::Elements
 
-	REGISTERED_ELEMENTS = Concurrent::Map.new
-
 	# @!method a(**attributes, &content)
 	# 	Outputs an <code>a</code> tag
 	# 	@return [nil]

data/lib/phlex/html/void_elements.rb

@@ -3,8 +3,6 @@
 module Phlex::HTML::VoidElements
 	extend Phlex::Elements
 
-	REGISTERED_ELEMENTS = Concurrent::Map.new
-
 	# @!method area(**attributes, &content)
 	# 	Outputs an <code>area</code> tag
 	# 	@return [nil]

data/lib/phlex/html.rb

@@ -29,6 +29,12 @@ 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
+
 		def svg(...)
 			super do
 				render Phlex::SVG.new do |svg|
@@ -42,13 +48,7 @@ module Phlex
 			self.class.__unbuffered_class__.new(self)
 		end
 
-		# This should be the last method defined
-		def self.method_added(method_name)
-			if method_name[0] == "_" && Phlex::HTML.instance_methods.include?(method_name) && instance_method(method_name).owner != Phlex::HTML
-				raise NameError, "👋 Redefining the method `#{name}##{method_name}` is not a good idea."
-			end
-
-			super
-		end
+		# This should be extended after all method definitions
+		extend ElementClobberingGuard
 	end
 end

data/lib/phlex/sgml.rb

@@ -14,6 +14,8 @@ module Phlex
 
 			alias_method :render, :call
 
+			# 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.
 			def new(*args, **kwargs, &block)
 				if block
 					object = super(*args, **kwargs, &nil)
@@ -32,21 +34,21 @@ module Phlex
 		end
 
 		# Renders the view and returns the buffer. The default buffer is a mutable String.
-		def call(buffer = +"", view_context: nil, parent: nil, &block)
-			__final_call__(buffer, view_context: view_context, parent: parent, &block).tap do
+		def call(buffer = nil, target: +"", view_context: nil, parent: nil, &block)
+			__final_call__(buffer, target: target, view_context: view_context, parent: parent, &block).tap do
 				self.class.rendered_at_least_once!
 			end
 		end
 
 		# @api private
-		def __final_call__(buffer = +"", view_context: nil, parent: nil, &block)
-			@_target = buffer
+		def __final_call__(buffer = nil, target: +"", view_context: nil, parent: nil, &block)
+			@_target = target
 			@_view_context = view_context
 			@_parent = parent
 
 			block ||= @_content_block
 
-			return buffer unless render?
+			return buffer || target unless render?
 
 			around_template do
 				if block
@@ -67,19 +69,19 @@ module Phlex
 				end
 			end
 
-			buffer
+			buffer ? (buffer << target) : target
 		end
 
 		# Render another view
-		# @param renderable [Phlex::HTML] the other view to render
-		# @return [void]
+		# @param renderable [Phlex::SGML]
+		# @return [nil]
 		def render(renderable, &block)
 			case renderable
 			when Phlex::SGML
-				renderable.call(@_target, view_context: @_view_context, parent: self, &block)
+				renderable.call(target: @_target, view_context: @_view_context, parent: self, &block)
 			when Class
 				if renderable < Phlex::SGML
-					renderable.new.call(@_target, view_context: @_view_context, parent: self, &block)
+					renderable.new.call(target: @_target, view_context: @_view_context, parent: self, &block)
 				end
 			else
 				raise ArgumentError, "You can't render a #{renderable}."
@@ -89,20 +91,28 @@ module Phlex
 		end
 
 		# Output text content. The text will be HTML-escaped.
-		def text(content)
-			@_target << ERB::Util.html_escape(
-				case content
-					when String then content
-					when Symbol then content.name
-					when Integer then content.to_s
-					else format_object(content) || content.to_s
+		# @return [nil]
+		def plain(content)
+			case content
+			when String
+				@_target << ERB::Escape.html_escape(content)
+			when Symbol
+				@_target << ERB::Escape.html_escape(content.name)
+			when Integer
+				@_target << ERB::Escape.html_escape(content.to_s)
+			when nil
+				nil
+			else
+				if (formatted_object = format_object(content))
+					@_target << ERB::Escape.html_escape(formatted_object)
 				end
-			)
+			end
 
 			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]
 		def whitespace
 			@_target << " "
 
@@ -115,6 +125,7 @@ module Phlex
 		end
 
 		# Output an HTML comment.
+		# @return [nil]
 		def comment(&block)
 			@_target << "<!-- "
 			yield_content(&block)
@@ -136,23 +147,25 @@ module Phlex
 		# Capture a block of output as a String.
 		# @return [String]
 		def capture(&block)
-			return unless block_given?
+			return "" unless block_given?
 
-			original_buffer = @_target
-			new_buffer = +""
+			original_buffer_content = @_target.dup
+			@_target.clear
 
 			begin
-				@_target = new_buffer
 				yield_content(&block)
+				new_buffer_content = @_target.dup
 			ensure
-				@_target = original_buffer
+				@_target.clear
+				@_target << original_buffer_content
 			end
 
-			new_buffer
+			new_buffer_content
 		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)
 			return unless block_given?
 
@@ -169,10 +182,13 @@ module Phlex
 		end
 
 		# Default render predicate can be overridden to prevent rendering
+		# @return [bool]
 		private def render?
 			true
 		end
 
+		# Format the object for output
+		# @return [String]
 		private def format_object(object)
 			case object
 			when Float
@@ -181,70 +197,48 @@ module Phlex
 		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.
+		# @return [nil]
 		private def around_template
 			before_template
 			yield
 			after_template
+
+			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.
+		# @return [nil]
 		private 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.
+		# @return [nil]
 		private 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.
+		# @return [nil]
 		private def yield_content
 			return unless block_given?
 
 			original_length = @_target.length
 			content = yield(self)
-			unchanged = (original_length == @_target.length)
 
-			if unchanged
-				case content
-				when String
-					@_target << ERB::Util.html_escape(content)
-				when Symbol
-					@_target << ERB::Util.html_escape(content.name)
-				when Integer
-					@_target << ERB::Util.html_escape(content.to_s)
-				else
-					if (formatted_object = format_object(content))
-						@_target << ERB::Util.html_escape(formatted_object)
-					end
-				end
-			end
+			plain(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.
+		# @return [nil]
 		private def yield_content_with_args(*args)
 			return unless block_given?
 
 			original_length = @_target.length
 			content = yield(*args)
-			unchanged = (original_length == @_target.length)
-
-			if unchanged
-				case content
-				when String
-					@_target << ERB::Util.html_escape(content)
-				when Symbol
-					@_target << ERB::Util.html_escape(content.name)
-				when Integer, Float
-					@_target << ERB::Util.html_escape(content.to_s)
-				else
-					if (formatted_object = format_object(content))
-						@_target << ERB::Util.html_escape(formatted_object)
-					end
-				end
-			end
+			plain(content) if original_length == @_target.length
 
 			nil
 		end
@@ -252,12 +246,16 @@ module Phlex
 		# @api private
 		private def __attributes__(**attributes)
 			__final_attributes__(**attributes).tap do |buffer|
-				Phlex::ATTRIBUTE_CACHE[attributes.hash] = buffer.freeze
+				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)
+			if respond_to?(:process_attributes)
+				attributes = process_attributes(**attributes)
+			end
+
 			if attributes[:href]&.start_with?(/\s*javascript:/)
 				attributes.delete(:href)
 			end
@@ -292,9 +290,9 @@ module Phlex
 				when true
 					buffer << " " << name
 				when String
-					buffer << " " << name << '="' << ERB::Util.html_escape(v) << '"'
+					buffer << " " << name << '="' << ERB::Escape.html_escape(v) << '"'
 				when Symbol
-					buffer << " " << name << '="' << ERB::Util.html_escape(v.name) << '"'
+					buffer << " " << name << '="' << ERB::Escape.html_escape(v.name) << '"'
 				when Hash
 					__build_attributes__(
 						v.transform_keys { |subkey|
@@ -305,7 +303,7 @@ module Phlex
 						}, buffer: buffer
 					)
 				else
-					buffer << " " << name << '="' << ERB::Util.html_escape(v.to_s) << '"'
+					buffer << " " << name << '="' << ERB::Escape.html_escape(v.to_s) << '"'
 				end
 			end
 

data/lib/phlex/svg/standard_elements.rb

@@ -3,8 +3,6 @@
 module Phlex::SVG::StandardElements
 	extend Phlex::Elements
 
-	REGISTERED_ELEMENTS = Concurrent::Map.new
-
 	# @!method a(**attributes, &content)
 	# 	Outputs an <code>a</code> tag
 	# 	@return [nil]

data/lib/phlex/svg.rb

@@ -7,5 +7,8 @@ module Phlex
 		def template
 			yield
 		end
+
+		# This should be extended after all method definitions
+		extend ElementClobberingGuard
 	end
 end

data/lib/phlex/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Phlex
-	VERSION = "1.4.0"
+	VERSION = "1.5.0"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: phlex
 version: !ruby/object:Gem::Version
-  version: 1.4.0
+  version: 1.5.0
 platform: ruby
 authors:
 - Joel Drapper
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2023-02-17 00:00:00.000000000 Z
+date: 2023-03-06 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: concurrent-ruby
@@ -24,6 +24,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '1.2'
+- !ruby/object:Gem::Dependency
+  name: erb
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '4'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '4'
 - !ruby/object:Gem::Dependency
   name: zeitwerk
   requirement: !ruby/object:Gem::Requirement
@@ -63,6 +77,7 @@ files:
 - lib/phlex/black_hole.rb
 - lib/phlex/callable.rb
 - lib/phlex/deferred_render.rb
+- lib/phlex/element_clobbering_guard.rb
 - lib/phlex/elements.rb
 - lib/phlex/helpers.rb
 - lib/phlex/html.rb