phlex 1.9.0 → 1.10.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0b68a563745c2782c8fa9f864f1d00994d6f5b3b1ffb92d651a52875386587fb
-  data.tar.gz: 4e272a581c83f91a4ba0e0a382bb2f54f3c7b3918e88b6c232d503f407046e75
+  metadata.gz: 6cb979c6d7c51d88b32f291de0ca3133594a03e70615b17c7fe7bff3b4b3e8c6
+  data.tar.gz: 4649c3a4526638bbbde4c627c70d57e969e9924cf4d2fac9706ab01d1283faa0
 SHA512:
-  metadata.gz: 4db12efca6e80561f266b3118a401bb81c2859a5b6b4f3f6db301ea711c468b1ad426a59db9dc0e9ea02056e60e7c325223051dd2e4a2309dc14d1ffc45410ac
-  data.tar.gz: 7c6fe13e7fa6e88d4c1857d4746faae3b622586823cfe6e64a71706efa9aca7ed1e82c9c13f5916f1c6780ab914d6a3576d4cd8571df0df249767bbf0c3b86de
+  metadata.gz: aaf25254c000f2bc39fb949427bfcced283df5c0dd4b44284ae30ba830d8141d6789adde5548911cb4b381ff096a7a31cc5d877d55cc7d48dfaf650670f08232
+  data.tar.gz: f8714c5084425f13c1ebcc7fcdf1e436a6a4ce501568dcf6522e7fd10279dd2902242e3b38ef4d1d1499d316237483eadf65f143718161676677d54c1c8ff65f

data/.rubocop.yml

@@ -13,3 +13,15 @@ Style/MixinUsage:
 
 Style/RedundantDoubleSplatHashBraces:
   Enabled: false
+
+Style/OptionalArguments:
+  Enabled: false
+
+Naming/AsciiIdentifiers:
+  Enabled: false
+
+Naming/MethodName:
+  Enabled: false
+
+Style/ReturnNilInPredicateMethodDefinition:
+  Enabled: false

data/.ruby-version

@@ -1 +1 @@
-3.2.2
+3.3.0

data/.solargraph.yml

@@ -0,0 +1,11 @@
+include:
+  - "**/*.rb"
+exclude:
+  - test/**/*
+require: []
+domains: []
+reporters:
+  - rubocop
+  - require_not_found
+  - typecheck
+max_files: 0

data/CHANGELOG.md

@@ -2,6 +2,21 @@
 
 All notable changes to this project will be documented in this file. The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.10.0] 2024-04-05
+
+- [Added] new `Phlex::CSV` class for streaming CSV views
+- [Added] new (experimental) `Phlex::Kit` for collections of components
+- [Added] support for selective rendering
+- [Changed] `mix` does a better job when mixing different types of attributes
+- [Changed] Phlex will now try to call `to_s` on attribute values
+- [Changed] No runtime dependencies
+- [Deprecated] `Phlex::HTML#param`, (`<param>`) tags have been deprecated
+- [Deprecated] Defining the `template` method is now deprecated. You should define `view_template` instead. In Phlex 2.0, the `template` method will render a `<template>` tag.
+
+# [1.9.1] 2024-03-11
+
+- Security update
+
 ## [1.9.0] 2024-11-24
 
 - Improved documentation
@@ -42,6 +57,6 @@ All notable changes to this project will be documented in this file. The format
 - Removed the `menuitem` element as it's a deprecated HTML element.
 - Removed the `SGML#text` method. This has been replaced with `SGML#plain`.
 
-***
+---
 
 Before this changelog was introduced, changes were logged in the [release notes](https://github.com/phlex-ruby/phlex/releases).

data/Gemfile

@@ -5,13 +5,17 @@ git_source(:github) { |repo| "https://github.com/#{repo}.git" }
 
 gemspec
 
-gem "rubocop"
-gem "sus"
-gem "benchmark-ips"
-gem "yard"
-gem "green_dots", github: "joeldrapper/green_dots"
-
 group :test do
-	gem "i18n"
-	gem "memory_profiler"
+	gem "sus"
+	if RUBY_ENGINE == "ruby" && RUBY_VERSION[0] > "3"
+		gem "async"
+	end
+	gem "concurrent-ruby"
+end
+
+group :development do
+	gem "rubocop"
+	gem "solargraph"
+	gem "yard"
+	gem "benchmark-ips"
 end

data/README.md

@@ -1,7 +1,9 @@
-<a href="https://www.phlex.fun"><img alt="Phlex logo" src="https://www.phlex.fun/assets/logo.png" width="180" /></a>
+<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.
 
+Docs and more at [Phlex.fun](https://www.phlex.fun/)
+
 ### Prior Art 🎨
 
 - [markaby](https://github.com/markaby/markaby)

data/SECURITY.md

@@ -1,13 +1,14 @@
-# Security Policy
+# Security
 
-## Reporting a vulnerability
+If you find a possible security vulnerability, please [send us a private advisory](https://github.com/phlex-ruby/phlex/security/advisories/new). 
 
-If you find a possible security vulnerability, please email security@phlex.fun. Do not create an issue or pull request either demonstrating or fixing the vulnerability.
+> [!WARNING]
+> Please do not open a public Issue or Pull Request.
 
 ## Bug bounty
 
-[The Gem Foundation](https://ryanbigg.com/2022/11/the-gem-foundation) has kindly sponsored a $1 bug bounty to discover security vulnerabilities in Phlex.
+There is currently a bounty of $100 USD, kindly sponsored by [Seth Horsley](https://twitter.com/SethHorsley), for the next serious vulnerability responsibly disclosed to us.
 
-## Sponsoring a bug bounty
+## Bug bounty pot
 
-If you wish to sponsor a bug bounty for Phlex, please get in touch with Joel at joel@drapper.me.
+If you wish to sponsor a bug bounty for Phlex, please get in touch with Joel at [joel@drapper.me](mailto:joel@drapper.me).

data/config/sus.rb

@@ -6,5 +6,3 @@ require "bundler"
 Bundler.require :test
 
 require_relative "../fixtures/view_helper"
-
-Zeitwerk::Loader.eager_load_all

data/fixtures/components/say_hi.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+class Components::SayHi < Phlex::HTML
+	def initialize(name, times: 1)
+		@name = name
+		@times = times
+	end
+
+	def template
+		article {
+			@times.times { h1 { "Hi #{@name}" } }
+			yield
+		}
+	end
+end

data/fixtures/components.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Components
+	extend Phlex::Kit
+
+	autoload :SayHi, "components/say_hi"
+end

data/fixtures/layout.rb

@@ -6,7 +6,7 @@ module Example
 			@title = title
 		end
 
-		def template(&block)
+		def view_template(&block)
 			html do
 				head do
 					title { @title }

data/fixtures/page.rb

@@ -2,30 +2,32 @@
 
 module Example
 	class Page < Phlex::HTML
-		def template
+		def view_template
 			render LayoutComponent.new do
 				h1 { "Hi" }
 
-				table id: "test", class: "a b c d e f g" do
-					tr do
-						td id: "test", class: "a b c d e f g" do
-							span { "Hi" }
-						end
+				100.times do
+					table id: "test", class: "a b c d e f g" do
+						tr do
+							td id: "test", class: "a b c d e f g" do
+								span { "Hi" }
+							end
 
-						td id: "test", class: "a b c d e f g" do
-							span { "Hi" }
-						end
+							td id: "test", class: "a b c d e f g" do
+								span { "Hi" }
+							end
 
-						td id: "test", class: "a b c d e f g" do
-							span { "Hi" }
-						end
+							td id: "test", class: "a b c d e f g" do
+								span { "Hi" }
+							end
 
-						td id: "test", class: "a b c d e f g" do
-							span { "Hi" }
-						end
+							td id: "test", class: "a b c d e f g" do
+								span { "Hi" }
+							end
 
-						td id: "test", class: "a b c d e f g" do
-							span { "Hi" }
+							td id: "test", class: "a b c d e f g" do
+								span { "Hi" }
+							end
 						end
 					end
 				end

data/gd/phlex/sgml/attributes.rb

@@ -2,9 +2,21 @@
 
 include TestHelper
 
+class ToPhlexAttributeValueable
+	def to_phlex_attribute_value
+		"to_phlex_attribute_value"
+	end
+end
+
+class ToSable
+	def to_s
+		"to_s"
+	end
+end
+
 class ToStrable
 	def to_str
-		"foo"
+		"to_str"
 	end
 end
 
@@ -40,12 +52,28 @@ test "with a set of symbols and strings" do
 	expect(component.new).to_render %(<div class="bg-red-500 rounded"></div>)
 end
 
+test "with a to_phlex_attribute_value-able object" do
+	component = build_component_with_template do
+		div class: ToPhlexAttributeValueable.new
+	end
+
+	expect(component.new).to_render %(<div class="to_phlex_attribute_value"></div>)
+end
+
+test "with a to_s-able object" do
+	component = build_component_with_template do
+		div class: ToSable.new
+	end
+
+	expect(component.new).to_render %(<div class="to_s"></div>)
+end
+
 test "with a to_str-able object" do
 	component = build_component_with_template do
 		div class: ToStrable.new
 	end
 
-	expect(component.new).to_render %(<div class="foo"></div>)
+	expect(component.new).to_render %(<div class="to_str"></div>)
 end
 
 test "with numeric integer/float" do

data/lib/phlex/black_hole.rb

@@ -8,7 +8,7 @@ module Phlex::BlackHole
 		self
 	end
 
-	def length
+	def bytesize
 		0
 	end
 

data/lib/phlex/context.rb

@@ -2,26 +2,63 @@
 
 # @api private
 class Phlex::Context
-	def initialize
-		@target = +""
+	def initialize(user_context = {})
+		@buffer = +""
 		@capturing = false
+		@user_context = user_context
+		@fragments = nil
+		@in_target_fragment = false
+		@halt_signal = nil
 	end
 
-	attr_accessor :target, :capturing
+	attr_accessor :buffer, :capturing, :user_context, :in_target_fragment
 
-	def capturing_into(new_target)
-		original_target = @target
+	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
+
+	def around_render
+		return yield if !@fragments || @halt_signal
+
+		catch do |signal|
+			@halt_signal = signal
+			yield
+		end
+	end
+
+	def begin_target(id)
+		@in_target_fragment = id
+	end
+
+	def end_target
+		@fragments.delete(@in_target_fragment)
+		@in_target_fragment = false
+		throw @halt_signal if @fragments.length == 0
+	end
+
+	def capturing_into(new_buffer)
+		original_buffer = @buffer
 		original_capturing = @capturing
+		original_fragments = @fragments
 
 		begin
-			@target = new_target
+			@buffer = new_buffer
 			@capturing = true
+			@fragments = nil
 			yield
 		ensure
-			@target = original_target
+			@buffer = original_buffer
 			@capturing = original_capturing
+			@fragments = original_fragments
 		end
 
-		new_target
+		new_buffer
 	end
 end

data/lib/phlex/csv.rb

@@ -0,0 +1,133 @@
+# 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
+
+	def initialize(collection)
+		@collection = collection
+		@_headers = []
+		@_current_row = []
+		@_current_column_index = 0
+		@_view_context = nil
+		@_first = true
+	end
+
+	attr_reader :collection
+
+	def call(buffer = +"", view_context: nil)
+		unless escape_csv_injection? == true || escape_csv_injection? == false
+			raise <<~MESSAGE
+				You need to define escape_csv_injection? in #{self.class.name}, returning either `true` or `false`.
+
+				CSV injection is a security vulnerability where malicious spreadsheet formulae are used to execute code or exfiltrate data when a CSV is opened in a spreadsheet program such as Microsoft Excel or Google Sheets.
+
+				For more information, see https://owasp.org/www-community/attacks/CSV_Injection
+
+				If you're sure this CSV will never be opened in a spreadsheet program, you can disable CSV injection escapes:
+
+				  def escape_csv_injection? = false
+
+				This is useful when using CSVs for byte-for-byte data exchange between secure systems.
+
+				Alternatively, you can enable CSV injection escapes at the cost of data integrity:
+
+				  def escape_csv_injection? = true
+
+				Note: Enabling the CSV injection escapes will prefix any values that start with `=`, `+`, `-`, `@`, `\\t`, or `\\r` with a single quote `'` to prevent them from being interpreted as formulae by spreadsheet programs.
+
+				Unfortunately, there is no one-size-fits-all solution to CSV injection. You need to decide based on your specific use case.
+			MESSAGE
+		end
+
+		@_view_context = view_context
+
+		each_item do |record|
+			yielder(record) do |*args, **kwargs|
+				view_template(*args, **kwargs)
+
+				if @_first && render_headers?
+					buffer << @_headers.join(",") << "\n"
+				end
+
+				buffer << @_current_row.join(",") << "\n"
+				@_current_column_index = 0
+				@_current_row.clear
+			end
+
+			@_first = false
+		end
+
+		buffer
+	end
+
+	def filename
+		nil
+	end
+
+	def content_type
+		"text/csv"
+	end
+
+	private
+
+	def column(header = nil, value)
+		if @_first
+			@_headers << escape(header)
+		elsif header != @_headers[@_current_column_index]
+			raise "Inconsistent header."
+		end
+
+		@_current_row << escape(value)
+		@_current_column_index += 1
+	end
+
+	def each_item(&block)
+		collection.each(&block)
+	end
+
+	def yielder(record)
+		yield(record)
+	end
+
+	def template(...)
+		nil
+	end
+
+	# Override and set to `false` to disable rendering headers.
+	def render_headers?
+		true
+	end
+
+	# Override and set to `true` to strip leading and trailing whitespace from values.
+	def trim_whitespace?
+		false
+	end
+
+	# Override and set to `false` to disable CSV injection escapes or `true` to enable.
+	def escape_csv_injection?
+		nil
+	end
+
+	def helpers
+		@_view_context
+	end
+
+	def escape(value)
+		value = trim_whitespace? ? value.to_s.strip : value.to_s
+		first_char = value[0]
+		last_char = value[-1]
+
+		if escape_csv_injection? && FORMULA_PREFIXES[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")
+			%("#{value.gsub('"', '""')}")
+		else
+			value
+		end
+	end
+end

data/lib/phlex/deferred_render.rb

@@ -11,7 +11,7 @@
 # 			@tabs = []
 # 		end
 #
-# 		def template
+# 		def view_template
 # 			@tabs.each { |t| a { t.name } }
 # 			@tabs.each { |t| article(&t.content) }
 # 		end

data/lib/phlex/elements.rb

@@ -1,9 +1,5 @@
 # frozen_string_literal: true
 
-if Gem::Version.new(RUBY_VERSION) < Gem::Version.new("3.0")
-	using Phlex::Overrides::Symbol::Name
-end
-
 # Extending this module provides the {register_element} macro for registering your own custom elements. It's already extended by {HTML} and {SVG}.
 # @example
 # 	module MyCustomElements
@@ -15,14 +11,14 @@ end
 # 	class MyComponent < Phlex::HTML
 # 		include MyCustomElements
 #
-# 		def template
+# 		def view_template
 # 			trix_editor
 # 		end
 # 	end
 module Phlex::Elements
 	# @api private
 	def registered_elements
-		@registered_elements ||= Concurrent::Map.new
+		@registered_elements ||= {}
 	end
 
 	# Register a custom element. This macro defines an element method for the current class and descendents only. There is no global element registry.
@@ -32,35 +28,64 @@ 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: nil)
-		tag ||= method_name.name.tr("_", "-")
+	def register_element(method_name, tag: method_name.name.tr("_", "-"), deprecated: false)
+		if deprecated
+			deprecation = <<~RUBY
+				Kernel.warn "#{deprecated}"
+			RUBY
+		else
+			deprecation = ""
+		end
 
 		class_eval(<<-RUBY, __FILE__, __LINE__ + 1)
 			# frozen_string_literal: true
 
 			def #{method_name}(**attributes, &block)
-				target = @_context.target
+				#{deprecation}
+
+				context = @_context
+				buffer = context.buffer
+				fragment = context.fragments
+				target_found = false
+
+				if fragment
+					return if fragment.length == 0 # we found all our fragments already
+
+					id = attributes[:id]
+
+					if !context.in_target_fragment
+					  if fragment[id]
+							context.begin_target(id)
+							target_found = true
+						else
+							yield(self) if block
+							return nil
+						end
+					end
+				end
 
 				if attributes.length > 0 # with attributes
 					if block # with content block
-						target << "<#{tag}" << (Phlex::ATTRIBUTE_CACHE[respond_to?(:process_attributes) ? (attributes.hash + self.class.hash) : attributes.hash] || __attributes__(**attributes)) << ">"
+						buffer << "<#{tag}" << (Phlex::ATTRIBUTE_CACHE[respond_to?(:process_attributes) ? (attributes.hash + self.class.hash) : attributes.hash] || __attributes__(**attributes)) << ">"
 						yield_content(&block)
-						target << "</#{tag}>"
+						buffer << "</#{tag}>"
 					else # without content block
-						target << "<#{tag}" << (Phlex::ATTRIBUTE_CACHE[respond_to?(:process_attributes) ? (attributes.hash + self.class.hash) : attributes.hash] || __attributes__(**attributes)) << "></#{tag}>"
+						buffer << "<#{tag}" << (Phlex::ATTRIBUTE_CACHE[respond_to?(:process_attributes) ? (attributes.hash + self.class.hash) : attributes.hash] || __attributes__(**attributes)) << "></#{tag}>"
 					end
 				else # without attributes
 					if block # with content block
-						target << "<#{tag}>"
+						buffer << "<#{tag}>"
 						yield_content(&block)
-						target << "</#{tag}>"
+						buffer << "</#{tag}>"
 					else # without content block
-						target << "<#{tag}></#{tag}>"
+						buffer << "<#{tag}></#{tag}>"
 					end
 				end
 
 				#{'flush' if tag == 'head'}
 
+				context.end_target if target_found
+
 				nil
 			end
 
@@ -73,19 +98,47 @@ module Phlex::Elements
 	end
 
 	# @api private
-	def register_void_element(method_name, tag: method_name.name.tr("_", "-"))
+	def register_void_element(method_name, tag: method_name.name.tr("_", "-"), deprecated: false)
+		if deprecated
+			deprecation = <<~RUBY
+				Kernel.warn "#{deprecated}"
+			RUBY
+		else
+			deprecation = ""
+		end
+
 		class_eval(<<-RUBY, __FILE__, __LINE__ + 1)
 			# frozen_string_literal: true
 
 			def #{method_name}(**attributes)
-				target = @_context.target
+				#{deprecation}
+				context = @_context
+				buffer = context.buffer
+				fragment = context.fragments
+
+				if fragment
+					return if fragment.length == 0 # we found all our fragments already
+
+					id = attributes[:id]
+
+					if !context.in_target_fragment
+					  if fragment[id]
+							context.begin_target(id)
+							target_found = true
+						else
+							return nil
+						end
+					end
+				end
 
 				if attributes.length > 0 # with attributes
-					target << "<#{tag}" << (Phlex::ATTRIBUTE_CACHE[respond_to?(:process_attributes) ? (attributes.hash + self.class.hash) : attributes.hash] || __attributes__(**attributes)) << ">"
+					buffer << "<#{tag}" << (Phlex::ATTRIBUTE_CACHE[respond_to?(:process_attributes) ? (attributes.hash + self.class.hash) : attributes.hash] || __attributes__(**attributes)) << ">"
 				else # without attributes
-					target << "<#{tag}>"
+					buffer << "<#{tag}>"
 				end
 
+				context.end_target if target_found
+
 				nil
 			end