phlex 1.6.1 → 1.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ada5b83ea9c2fbd305a249ffa81a43c9e9da26a7c87860dac62e594a43341001
-  data.tar.gz: e728f6c83cae97671bf4092f7bd384c93611d51158f613a75518d1109a669942
+  metadata.gz: 463bbaade702e9495ee8965c20ca4c5aeb926b10a2e190584a0a0dfcc4f43709
+  data.tar.gz: f57de49b85bfc10920f890581656a7aa1c86d6d120ce45017c9fc0c355587514
 SHA512:
-  metadata.gz: 6f8b512d89247318f657482d3eeb1ba9fd0c1de73edcf4f3c5d0b6ff843bbd0bbca6d47d9a957780a1831e70b67ec8c2d1d1beba10a00bc9546a8966f67d545d
-  data.tar.gz: a5a780a277bc36e8fa028af0ccdd3b985189ae6c49241d737b9d86e4f37fa43bbbfc8e4cb1736914735a35821a741c8fcc964f45c8b82b96c5389053c72b2684
+  metadata.gz: cf30a011b71eb056c093b0e0691e635b7fc60f3b2ed533fec63d65bd8c29ca5ddea794ac054a33c27cb2b79e8caab587299522707646c34c12a822a819aeba05
+  data.tar.gz: c8dc0e52c90c686e0824ee611afb303c8cdb8c9d9ebbb0293e1f0a0905e83a302499cabca54e44f2bddbe859ac43dd71d004f4f05b1feaf3dbd8d7f9696f24b8

data/.ruby-version

@@ -1 +1 @@
-3.2.1
+3.2.2

data/.yardopts

@@ -0,0 +1 @@
+--private --hide-api private --markup markdown

data/CHANGELOG.md

@@ -0,0 +1,32 @@
+# Changelog
+
+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.8.0] 2024-04-19
+
+### Changed
+
+- Support `Integer` and `Float` attribute values, and fall back to calling `to_str` on other objects.
+
+## [1.7.0] 2024-04-18
+
+### Added
+
+- Experimental Smart chunking.
+
+### Changed
+
+- Improved YARD documentation, which is now available here https://rubydoc.info/gems/phlex
+- `SGML#render` can now render lambdas with zero or one arguments. Previously, it could only render lambdas with exactly one argument, although it could always render Procs with any number of arguments. When an argument is accepted, the `self` of the component rendering it is yielded to the Proc.
+- Raise an error when outputting an unknown object using `SGML#plain`.
+- Raise an error when using attribute keys that aren't Strings or Symbols.
+- Support Array and Set values for HTML/SVG attributes.
+
+### Removed
+
+- 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

@@ -8,6 +8,7 @@ gemspec
 gem "rubocop"
 gem "sus"
 gem "benchmark-ips"
+gem "yard"
 
 group :test do
 	gem "i18n"

data/README.md

@@ -1,47 +1,6 @@
-<a href="https://www.phlex.fun"><img alt="Phlex logo" src="phlex_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. It’s super-fast, thread-safe and supports TruffleRuby v22.2+, JRuby v9.2+ and MRI v2.7+.
-
-### Documentation 📗
-
-Documentation can be found at [www.phlex.fun](https://www.phlex.fun).
-
-### Support ✋
-
-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).
-
-### Who uses Phlex?
-
-- [Clearscope](https://www.clearscope.io)
-
-*If you’re using Phlex in production, please open a PR to list it here.*
-
-### Sponsorship 💖
-
-Maintaining a library is a lot of work. If your company benefits from this work or is likely to benefit from it in the future, please consider [sponsorship](https://github.com/sponsors/joeldrapper). Phlex is actively developed and maintained by **[Joel Drapper](https://github.com/sponsors/joeldrapper)**.
-
-### Security 🚨
-
-If you’ve found a potential security issue, please email [security@phlex.fun](mailto:security@phlex.fun).
-
-### Thanks 🙏
-
-Thanks [Logology](https://www.logology.co) for sponsoring our logo.
+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.
 
 ### Prior Art 🎨
 
@@ -55,3 +14,4 @@ Thanks [Logology](https://www.logology.co) for sponsoring our logo.
 - [hyperstack](https://github.com/hyperstack-org/hyperstack)
 - [clearwater](https://github.com/clearwater-rb/clearwater)
 - [paggio](https://github.com/opal/paggio)
+- [Inesita](https://github.com/inesita-rb/inesita)

data/lib/phlex/black_hole.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+# @api private
 module Phlex::BlackHole
 	extend self
 

data/lib/phlex/callable.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+# @api private
 module Phlex::Callable
 	def to_proc
 		method(:call).to_proc

data/lib/phlex/context.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+# @api private
 class Phlex::Context
 	def initialize
 		@target = +""

data/lib/phlex/deferred_render.rb

@@ -1,5 +1,29 @@
 # frozen_string_literal: true
 
+# Include this module into an {HTML} or {SVG} component to make it yield the content block before calling {#template}.
+# @example
+# 	class Tabs < Phlex::HTML
+# 		include DeferredRender
+#
+# 		Tab = Data.define(:name, :content)
+#
+# 		def initialize
+# 			@tabs = []
+# 		end
+#
+# 		def template
+# 			@tabs.each { |t| a { t.name } }
+# 			@tabs.each { |t| article(&t.content) }
+# 		end
+#
+# 		def tab(name, &content)
+# 			@tabs << Tab.new(name, content)
+# 		end
+# 	end
 module Phlex::DeferredRender
 	# This module doesn't do anything. Phlex::HTML#call checks for its inclusion in the ancestry instead.
+
+	# @!method template
+	# @abstract Override to define your own template.
+	# @note {DeferredRender} templates do not receive the content block. Instead, it is yielded in advance.
 end

data/lib/phlex/element_clobbering_guard.rb

@@ -1,13 +1,12 @@
 # frozen_string_literal: true
 
-module Phlex
-	module ElementClobberingGuard
-		def method_added(method_name)
-			if method_name[0] == "_" && element_method?(method_name[1..].to_sym)
-				raise NameError, "👋 Redefining the method `#{name}##{method_name}` is not a good idea."
-			else
-				super
-			end
+# @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."
+		else
+			super
 		end
 	end
 end

data/lib/phlex/elements.rb

@@ -4,17 +4,41 @@ 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
+# 		extend Phlex::Elements
+#
+# 		register_element :trix_editor
+# 	end
+#
+# 	class MyComponent < Phlex::HTML
+# 		include MyCustomElements
+#
+# 		def template
+# 			trix_editor
+# 		end
+# 	end
 module Phlex::Elements
+	# @api private
 	def registered_elements
 		@registered_elements ||= Concurrent::Map.new
 	end
 
-	def register_element(element, tag: element.name.tr("_", "-"))
+	# Register a custom element. This macro defines an element method for the current class and descendents only. There is no global element registry.
+	# @param method_name [Symbol]
+	# @param tag [String] the name of the tag, otherwise this will be the method name with underscores replaced with dashes.
+	# @return [Symbol] the name of the method created
+	# @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("_", "-")
+
 		class_eval(<<-RUBY, __FILE__, __LINE__ + 1)
 			# frozen_string_literal: true
 
-
-			def #{element}(**attributes, &block)
+			def #{method_name}(**attributes, &block)
 				target = @_context.target
 
 				if attributes.length > 0 # with attributes
@@ -35,22 +59,25 @@ module Phlex::Elements
 					end
 				end
 
+				#{'flush' if tag == 'head'}
+
 				nil
 			end
 
-			alias_method :_#{element}, :#{element}
+			alias_method :_#{method_name}, :#{method_name}
 		RUBY
 
-		registered_elements[element] = tag
+		registered_elements[method_name] = tag
 
-		element
+		method_name
 	end
 
-	def register_void_element(element, tag: element.name.tr("_", "-"))
+	# @api private
+	def register_void_element(method_name, tag: method_name.name.tr("_", "-"))
 		class_eval(<<-RUBY, __FILE__, __LINE__ + 1)
 			# frozen_string_literal: true
 
-			def #{element}(**attributes)
+			def #{method_name}(**attributes)
 				target = @_context.target
 
 				if attributes.length > 0 # with attributes
@@ -62,11 +89,11 @@ module Phlex::Elements
 				nil
 			end
 
-			alias_method :_#{element}, :#{element}
+			alias_method :_#{method_name}, :#{method_name}
 		RUBY
 
-		registered_elements[element] = tag
+		registered_elements[method_name] = tag
 
-		element
+		method_name
 	end
 end

data/lib/phlex/helpers.rb

@@ -5,8 +5,24 @@ if Gem::Version.new(RUBY_VERSION) < Gem::Version.new("3.0")
 end
 
 module Phlex::Helpers
+	private
+
+	# Tokens
 	# @return [String]
-	private def tokens(*tokens, **conditional_tokens)
+	# @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)
@@ -33,7 +49,7 @@ module Phlex::Helpers
 	end
 
 	# @api private
-	private def __append_token__(tokens, token)
+	def __append_token__(tokens, token)
 		case token
 			when nil then nil
 			when String then tokens << token
@@ -44,8 +60,9 @@ module Phlex::Helpers
 		end
 	end
 
+	# Like {#tokens} but returns a {Hash} where the tokens are the value for `:class`.
 	# @return [Hash]
-	private def classes(*tokens, **conditional_tokens)
+	def classes(*tokens, **conditional_tokens)
 		tokens = self.tokens(*tokens, **conditional_tokens)
 
 		if tokens.empty?
@@ -56,7 +73,7 @@ module Phlex::Helpers
 	end
 
 	# @return [Hash]
-	private def mix(*args)
+	def mix(*args)
 		args.each_with_object({}) do |object, result|
 			result.merge!(object) do |_key, old, new|
 				case new