phlex 2.0.0.rc2 → 2.0.1

data/lib/phlex/html/void_elements.rb

@@ -5,95 +5,62 @@ module Phlex::HTML::VoidElements
 	extend Phlex::SGML::Elements
 
 	# Outputs an `<area>` tag.
-	# See https://developer.mozilla.org/docs/Web/HTML/Element/area
-	__register_void_element__ def area(
-		class: nil,
-		id: nil,
-		**attributes
-	) = nil
+	# [MDN Docs](https://developer.mozilla.org/docs/Web/HTML/Element/area)
+	# [Spec](https://html.spec.whatwg.org/#the-area-element)
+	__register_void_element__ def area(**attributes) = nil
+
 	# Outputs a `<base>` tag.
-	# See https://developer.mozilla.org/en-US/docs/Web/HTML/Element/base
-	__register_void_element__ def base(
-		class: nil,
-		href: nil,
-		id: nil,
-		target: nil,
-		**attributes
-	) = nil
+	# [MDN Docs](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/base)
+	# [Spec](https://html.spec.whatwg.org/#the-base-element)
+	__register_void_element__ def base(**attributes) = nil
+
 	# Outputs a `<br>` tag.
-	# See https://developer.mozilla.org/docs/Web/HTML/Element/br
-	__register_void_element__ def br(
-		class: nil,
-		id: nil,
-		**attributes
-	) = nil
+	# [MDN Docs](https://developer.mozilla.org/docs/Web/HTML/Element/br)
+	# [Spec](https://html.spec.whatwg.org/#the-br-element)
+	__register_void_element__ def br(**attributes) = nil
+
 	# Outputs a `<col>` tag.
-	# See https://developer.mozilla.org/docs/Web/HTML/Element/col
-	__register_void_element__ def col(
-		class: nil,
-		id: nil,
-		**attributes
-	) = nil
+	# [MDN Docs](https://developer.mozilla.org/docs/Web/HTML/Element/col)
+	# [Spec](https://html.spec.whatwg.org/#the-col-element)
+	__register_void_element__ def col(**attributes) = nil
+
 	# Outputs an `<embed>` tag.
-	# See https://developer.mozilla.org/docs/Web/HTML/Element/embed
-	__register_void_element__ def embed(
-		class: nil,
-		id: nil,
-		**attributes
-	) = nil
+	# [MDN Docs](https://developer.mozilla.org/docs/Web/HTML/Element/embed)
+	# [Spec](https://html.spec.whatwg.org/#the-embed-element)
+	__register_void_element__ def embed(**attributes) = nil
+
 	# Outputs an `<hr>` tag.
-	# See https://developer.mozilla.org/docs/Web/HTML/Element/hr
-	__register_void_element__ def hr(
-		class: nil,
-		id: nil,
-		**attributes
-	) = nil
+	# [MDN Docs](https://developer.mozilla.org/docs/Web/HTML/Element/hr)
+	# [Spec](https://html.spec.whatwg.org/#the-hr-element)
+	__register_void_element__ def hr(**attributes) = nil
+
 	# Outputs an `<img>` tag.
-	# See https://developer.mozilla.org/docs/Web/HTML/Element/img
-	__register_void_element__ def img(
-		alt: nil,
-		class: nil,
-		id: nil,
-		src: nil,
-		**attributes
-	) = nil
+	# [MDN Docs](https://developer.mozilla.org/docs/Web/HTML/Element/img)
+	# [Spec](https://html.spec.whatwg.org/#the-img-element)
+	__register_void_element__ def img(**attributes) = nil
+
 	# Outputs an `<input>` tag.
-	# See https://developer.mozilla.org/docs/Web/HTML/Element/input
-	__register_void_element__ def input(
-		class: nil,
-		id: nil,
-		name: nil,
-		type: nil,
-		**attributes
-	) = nil
+	# [MDN Docs](https://developer.mozilla.org/docs/Web/HTML/Element/input)
+	# [Spec](https://html.spec.whatwg.org/#the-input-element)
+	__register_void_element__ def input(**attributes) = nil
+
 	# Outputs a `<link>` tag.
-	# See https://developer.mozilla.org/docs/Web/HTML/Element/link
-	__register_void_element__ def link(
-		class: nil,
-		id: nil,
-		**attributes
-	) = nil
+	# [MDN Docs](https://developer.mozilla.org/docs/Web/HTML/Element/link)
+	# [Spec](https://html.spec.whatwg.org/#the-link-element)
+	__register_void_element__ def link(**attributes) = nil
+
 	# Outputs a `<meta>` tag.
-	# See https://developer.mozilla.org/docs/Web/HTML/Element/meta
-	__register_void_element__ def meta(
-		charset: nil,
-		class: nil,
-		id: nil,
-		name: nil,
-		**attributes
-	) = nil
+	# [MDN Docs](https://developer.mozilla.org/docs/Web/HTML/Element/meta)
+	# [Spec](https://html.spec.whatwg.org/#the-meta-element)
+	__register_void_element__ def meta(**attributes) = nil
+
 	# Outputs a `<source>` tag.
-	# See https://developer.mozilla.org/docs/Web/HTML/Element/source
-	__register_void_element__ def source(
-		class: nil,
-		id: nil,
-		**attributes
-	) = nil
+	# [MDN Docs](https://developer.mozilla.org/docs/Web/HTML/Element/source)
+	# [Spec](https://html.spec.whatwg.org/#the-source-element)
+	__register_void_element__ def source(**attributes) = nil
+
 	# Outputs a `<track>` tag.
-	# See https://developer.mozilla.org/docs/Web/HTML/Element/track
-	__register_void_element__ def track(
-		class: nil,
-		id: nil,
-		**attributes
-	) = nil
+	# [MDN Docs](https://developer.mozilla.org/docs/Web/HTML/Element/track)
+	# [Spec](https://html.spec.whatwg.org/#the-track-element)
+	__register_void_element__ def track(**attributes) = nil
 end

data/lib/phlex/html.rb

@@ -16,26 +16,88 @@ class Phlex::HTML < Phlex::SGML
 		nil
 	end
 
-	# Outputs an `<svg>` tag
-	# @return [nil]
-	# @see https://developer.mozilla.org/docs/Web/SVG/Element/svg
-	def svg(...)
+	# Outputs an `<svg>` tag.
+	#
+	# [MDN Docs](https://developer.mozilla.org/docs/Web/SVG/Element/svg)
+	# [Spec](https://html.spec.whatwg.org/#the-svg-element)
+	def svg(*, **, &)
 		if block_given?
-			super do
-				render Phlex::SVG.new do |svg|
-					yield(svg)
-				end
-			end
+			super { render Phlex::SVG.new(&) }
 		else
 			super
 		end
 	end
 
+	# Override to provide a filename for the HTML file
 	def filename
 		nil
 	end
 
+	# Returns the string "text/html"
 	def content_type
 		"text/html"
 	end
+
+	# Output an HTML tag dynamically, e.g:
+	#
+	# ```ruby
+	# @tag_name = :h1
+	# tag(@tag_name, class: "title")
+	# ```
+	def tag(name, **attributes, &)
+		state = @_state
+		block_given = block_given?
+		buffer = state.buffer
+
+		unless state.should_render?
+			yield(self) if block_given
+			return nil
+		end
+
+		unless Symbol === name
+			raise Phlex::ArgumentError.new("Expected the tag name to be a Symbol.")
+		end
+
+		if (tag = StandardElements.__registered_elements__[name]) || (tag = name.name.tr("_", "-")).include?("-")
+			if attributes.length > 0 # with attributes
+				if block_given # with content block
+					buffer << "<#{tag}" << (Phlex::ATTRIBUTE_CACHE[attributes] ||= __attributes__(attributes)) << ">"
+					if tag == "svg"
+						render Phlex::SVG.new(&)
+					else
+						__yield_content__(&)
+					end
+					buffer << "</#{tag}>"
+				else # without content
+					buffer << "<#{tag}" << (::Phlex::ATTRIBUTE_CACHE[attributes] ||= __attributes__(attributes)) << "></#{tag}>"
+				end
+			else # without attributes
+				if block_given # with content block
+					buffer << ("<#{tag}>")
+					if tag == "svg"
+						render Phlex::SVG.new(&)
+					else
+						__yield_content__(&)
+					end
+					buffer << "</#{tag}>"
+				else # without content
+					buffer << "<#{tag}></#{tag}>"
+				end
+			end
+		elsif (tag = VoidElements.__registered_elements__[name])
+			if block_given
+				raise Phlex::ArgumentError.new("Void elements cannot have content blocks.")
+			end
+
+			if attributes.length > 0 # with attributes
+				buffer << "<#{tag}" << (::Phlex::ATTRIBUTE_CACHE[attributes] ||= __attributes__(attributes)) << ">"
+			else # without attributes
+				buffer << "<#{tag}>"
+			end
+
+			nil
+		else
+			raise Phlex::ArgumentError.new("Invalid HTML tag: #{name}")
+		end
+	end
 end

data/lib/phlex/kit.rb

@@ -24,7 +24,16 @@ module Phlex::Kit
 	end
 
 	def self.extended(mod)
-		mod.include(LazyLoader)
+		case mod
+		when Class
+			raise Phlex::ArgumentError.new(<<~MESSAGE)
+				`Phlex::Kit` was extended into #{mod.name}.
+
+				You should only extend modules with `Phlex::Kit` as it is not compatible with classes.
+			MESSAGE
+		else
+			mod.include(LazyLoader)
+		end
 	end
 
 	def method_missing(name, ...)
@@ -52,7 +61,7 @@ module Phlex::Kit
 		case constant
 		when Class
 			if constant < Phlex::SGML
-				constant.include(self)
+				constant.include(me)
 
 				constant = nil
 

data/lib/phlex/sgml/elements.rb

@@ -27,14 +27,14 @@ module Phlex::SGML::Elements
 						content = yield(self)
 						if original_length == buffer.bytesize
 							case content
-							when nil
-								nil
+							when ::Phlex::SGML::SafeObject
+								buffer << content.to_s
 							when String
 								buffer << ::Phlex::Escape.html_escape(content)
 							when Symbol
 								buffer << ::Phlex::Escape.html_escape(content.name)
-							when ::Phlex::SGML::SafeObject
-								buffer << content.to_s
+							when nil
+								nil
 							else
 								if (formatted_object = format_object(content))
 									buffer << ::Phlex::Escape.html_escape(formatted_object)
@@ -54,14 +54,14 @@ module Phlex::SGML::Elements
 						content = yield(self)
 						if original_length == buffer.bytesize
 							case content
-							when nil
-								nil
+							when ::Phlex::SGML::SafeObject
+								buffer << content.to_s
 							when String
 								buffer << ::Phlex::Escape.html_escape(content)
 							when Symbol
 								buffer << ::Phlex::Escape.html_escape(content.name)
-							when ::Phlex::SGML::SafeObject
-								buffer << content.to_s
+							when nil
+								nil
 							else
 								if (formatted_object = format_object(content))
 									buffer << ::Phlex::Escape.html_escape(formatted_object)

data/lib/phlex/sgml/state.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 class Phlex::SGML::State
-	def initialize(user_context: {}, view_context: nil, output_buffer:, fragments:)
+	def initialize(user_context: {}, output_buffer:, fragments:)
 		@buffer = +""
 		@capturing = false
 		@user_context = user_context
@@ -9,13 +9,12 @@ class Phlex::SGML::State
 		@fragment_depth = 0
 		@cache_stack = []
 		@halt_signal = nil
-		@view_context = view_context
 		@output_buffer = output_buffer
 	end
 
 	attr_accessor :buffer, :capturing, :user_context
 
-	attr_reader :fragments, :fragment_depth, :view_context, :output_buffer
+	attr_reader :fragments, :fragment_depth, :output_buffer
 
 	def around_render(component)
 		stack = @stack

data/lib/phlex/sgml.rb

@@ -43,10 +43,9 @@ class Phlex::SGML
 		proc { |c| c.render(self) }
 	end
 
-	def call(buffer = +"", context: {}, view_context: nil, fragments: nil, &)
+	def call(buffer = +"", context: {}, fragments: nil, &)
 		state = Phlex::SGML::State.new(
 			user_context: context,
-			view_context:,
 			output_buffer: buffer,
 			fragments: fragments&.to_set,
 		)
@@ -57,8 +56,6 @@ class Phlex::SGML
 	end
 
 	def internal_call(parent: nil, state: nil, &block)
-		return "" unless render?
-
 		if @_state
 			raise Phlex::DoubleRenderError.new(
 				"You can't render a #{self.class.name} more than once."
@@ -67,6 +64,8 @@ class Phlex::SGML
 
 		@_state = state
 
+		return "" unless render?
+
 		block ||= @_content_block
 
 		Thread.current[:__phlex_component__] = [self, Fiber.current.object_id].freeze
@@ -188,6 +187,7 @@ class Phlex::SGML
 
 	alias_method :🦺, :safe
 
+	# Flush the current state to the output buffer.
 	def flush
 		@_state.flush
 	end
@@ -195,9 +195,7 @@ class Phlex::SGML
 	def render(renderable = nil, &)
 		case renderable
 		when Phlex::SGML
-			Thread.current[:__phlex_component__] = [renderable, Fiber.current.object_id].freeze
 			renderable.internal_call(state: @_state, parent: self, &)
-			Thread.current[:__phlex_component__] = [self, Fiber.current.object_id].freeze
 		when Class
 			if renderable < Phlex::SGML
 				render(renderable.new, &)
@@ -206,7 +204,7 @@ class Phlex::SGML
 			renderable.each { |r| render(r, &) }
 		when Proc, Method
 			if renderable.arity == 0
-				__yield_content_with_no_args__(&renderable)
+				__yield_content_with_no_yield_args__(&renderable)
 			else
 				__yield_content__(&renderable)
 			end
@@ -234,11 +232,12 @@ class Phlex::SGML
 		location = caller_locations(1, 1)[0]
 
 		full_key = [
-			Phlex::DEPLOY_KEY,   # invalidates the key when deploying new code in case of changes
-			self.class.name,     # prevents collisions between classes
-			location.base_label, # prevents collisions between different methods
-			location.lineno,     # prevents collisions between different lines
-			cache_key,           # allows for custom cache keys
+			app_version_key,                                    # invalidates the key when deploying new code in case of changes
+			self.class.name,                                   # prevents collisions between classes
+			(self.class.object_id if enable_cache_reloading?), # enables reloading
+			location.base_label,                               # prevents collisions between different methods
+			location.lineno,                                   # prevents collisions between different lines
+			cache_key,                                        # allows for custom cache keys
 		].freeze
 
 		low_level_cache(full_key, **, &content)
@@ -277,14 +276,21 @@ class Phlex::SGML
 		end
 	end
 
-	# Points to the cache store used by this component.
-	# By default, it points to `Phlex::NullCacheStore`, which does no caching.
+	private
+
+	# Override this method to use a different deployment key.
+	def app_version_key
+		Phlex::DEPLOYED_AT
+	end
+
 	# Override this method to use a different cache store.
 	def cache_store
-		Phlex::NullCacheStore
+		raise "Cache store not implemented."
 	end
 
-	private
+	def enable_cache_reloading?
+		false
+	end
 
 	def vanish(*args)
 		return unless block_given?
@@ -334,13 +340,13 @@ class Phlex::SGML
 		nil
 	end
 
-	def __yield_content_with_no_args__
+	def __yield_content_with_no_yield_args__
 		return unless block_given?
 
 		buffer = @_state.buffer
 
 		original_length = buffer.bytesize
-		content = yield
+		content = yield # <-- doesn’t yield self 😉
 		__implicit_output__(content) if original_length == buffer.bytesize
 
 		nil

data/lib/phlex/svg.rb

@@ -5,11 +5,50 @@ class Phlex::SVG < Phlex::SGML
 
 	include StandardElements
 
+	# Returns the string "image/svg+xml"
 	def content_type
 		"image/svg+xml"
 	end
 
+	# Override to provide a filename for the SVG file
 	def filename
 		nil
 	end
+
+	def tag(name, **attributes, &)
+		state = @_state
+		block_given = block_given?
+		buffer = state.buffer
+
+		unless state.should_render?
+			yield(self) if block_given
+			return nil
+		end
+
+		unless Symbol === name
+			raise Phlex::ArgumentError.new("Expected the tag name to be a Symbol.")
+		end
+
+		if (tag = StandardElements.__registered_elements__[name]) || (tag = name.name.tr("_", "-")).include?("-")
+			if attributes.length > 0 # with attributes
+				if block_given # with content block
+					buffer << "<#{tag}" << (Phlex::ATTRIBUTE_CACHE[attributes] ||= __attributes__(attributes)) << ">"
+					__yield_content__(&)
+					buffer << "</#{tag}>"
+				else # without content
+					buffer << "<#{tag}" << (::Phlex::ATTRIBUTE_CACHE[attributes] ||= __attributes__(attributes)) << "></#{tag}>"
+				end
+			else # without attributes
+				if block_given # with content block
+					buffer << ("<#{tag}>")
+					__yield_content__(&)
+					buffer << "</#{tag}>"
+				else # without content
+					buffer << "<#{tag}></#{tag}>"
+				end
+			end
+		else
+			raise Phlex::ArgumentError.new("Invalid SVG tag: #{name}")
+		end
+	end
 end

data/lib/phlex/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Phlex
-	VERSION = "2.0.0.rc2"
+	VERSION = "2.0.1"
 end

data/lib/phlex.rb

@@ -4,25 +4,26 @@ require "erb"
 require "set"
 
 module Phlex
-	autoload :ArgumentError, "phlex/errors/argument_error"
-	autoload :CSV, "phlex/csv"
-	autoload :DoubleRenderError, "phlex/errors/double_render_error"
-	autoload :Error, "phlex/error"
+	autoload :Kit, "phlex/kit"
 	autoload :FIFO, "phlex/fifo"
+	autoload :Vanish, "phlex/vanish"
+	autoload :Helpers, "phlex/helpers"
 	autoload :FIFOCacheStore, "phlex/fifo_cache_store"
+
+	autoload :CSV, "phlex/csv"
+	autoload :SVG, "phlex/svg"
 	autoload :HTML, "phlex/html"
-	autoload :Helpers, "phlex/helpers"
-	autoload :Kit, "phlex/kit"
-	autoload :NameError, "phlex/errors/name_error"
-	autoload :NullCacheStore, "phlex/null_cache_store"
 	autoload :SGML, "phlex/sgml"
-	autoload :SVG, "phlex/svg"
-	autoload :Vanish, "phlex/vanish"
+
+	autoload :Error, "phlex/error"
+	autoload :NameError, "phlex/errors/name_error"
+	autoload :RuntimeError, "phlex/errors/runtime_error"
+	autoload :ArgumentError, "phlex/errors/argument_error"
+	autoload :DoubleRenderError, "phlex/errors/double_render_error"
 
 	Escape = ERB::Escape
-	Null = Object.new.freeze
 
-	DEPLOY_KEY = Process.clock_gettime(Process::CLOCK_MONOTONIC, :millisecond)
+	DEPLOYED_AT = Process.clock_gettime(Process::CLOCK_MONOTONIC, :millisecond)
 	CACHED_FILES = Set.new
 	ATTRIBUTE_CACHE = FIFO.new
 
@@ -43,6 +44,38 @@ module Phlex
 			end
 		end
 	end
+
+	# Generate an HTML string using Phlex’ HTML DSL
+	def self.html(&block)
+		HTML.call do |component|
+			receiver = block.binding.receiver
+
+			receiver.instance_variables.each do |ivar|
+				next if component.instance_variable_defined?(ivar)
+
+				value = receiver.instance_variable_get(ivar)
+				component.instance_variable_set(ivar, value)
+			end
+
+			component.instance_exec(receiver, &block)
+		end
+	end
+
+	# Generate an SVG string using Phlex’ SVG DSL
+	def self.svg(&block)
+		SVG.call do |component|
+			receiver = block.binding.receiver
+
+			receiver.instance_variables.each do |ivar|
+				next if component.instance_variable_defined?(ivar)
+
+				value = receiver.instance_variable_get(ivar)
+				component.instance_variable_set(ivar, value)
+			end
+
+			component.instance_exec(receiver, &block)
+		end
+	end
 end
 
 def 💪

metadata

@@ -1,15 +1,16 @@
 --- !ruby/object:Gem::Specification
 name: phlex
 version: !ruby/object:Gem::Version
-  version: 2.0.0.rc2
+  version: 2.0.1
 platform: ruby
 authors:
 - Joel Drapper
+- Will Cosgrove
 bindir: bin
 cert_chain: []
-date: 2025-02-10 00:00:00.000000000 Z
+date: 2025-02-15 00:00:00.000000000 Z
 dependencies: []
-description: A high-performance view framework optimised for fun.
+description: Build HTML & SVG view components with Ruby classes.
 email:
 - joel@drapper.me
 executables: []
@@ -24,6 +25,7 @@ files:
 - lib/phlex/errors/argument_error.rb
 - lib/phlex/errors/double_render_error.rb
 - lib/phlex/errors/name_error.rb
+- lib/phlex/errors/runtime_error.rb
 - lib/phlex/fifo.rb
 - lib/phlex/fifo_cache_store.rb
 - lib/phlex/helpers.rb
@@ -31,7 +33,6 @@ files:
 - lib/phlex/html/standard_elements.rb
 - lib/phlex/html/void_elements.rb
 - lib/phlex/kit.rb
-- lib/phlex/null_cache_store.rb
 - lib/phlex/sgml.rb
 - lib/phlex/sgml/elements.rb
 - lib/phlex/sgml/safe_object.rb
@@ -39,11 +40,6 @@ files:
 - lib/phlex/sgml/state.rb
 - lib/phlex/svg.rb
 - lib/phlex/svg/standard_elements.rb
-- lib/phlex/testing.rb
-- lib/phlex/testing/capybara.rb
-- lib/phlex/testing/nokogiri.rb
-- lib/phlex/testing/nokolexbor.rb
-- lib/phlex/testing/sgml.rb
 - lib/phlex/vanish.rb
 - lib/phlex/version.rb
 homepage: https://www.phlex.fun
@@ -52,7 +48,7 @@ licenses:
 metadata:
   homepage_uri: https://www.phlex.fun
   source_code_uri: https://github.com/phlex-ruby/phlex
-  changelog_uri: https://github.com/phlex-ruby/phlex/blob/main/CHANGELOG.md
+  changelog_uri: https://github.com/phlex-ruby/phlex/releases
   funding_uri: https://github.com/sponsors/joeldrapper
   rubygems_mfa_required: 'true'
 rdoc_options: []
@@ -71,5 +67,5 @@ required_rubygems_version: !ruby/object:Gem::Requirement
 requirements: []
 rubygems_version: 3.6.2
 specification_version: 4
-summary: A fun framework for building views in Ruby.
+summary: Object-oriented views in Ruby.
 test_files: []

data/lib/phlex/null_cache_store.rb

@@ -1,9 +0,0 @@
-# frozen_string_literal: true
-
-module Phlex::NullCacheStore
-	extend self
-
-	def fetch(key)
-		yield
-	end
-end

data/lib/phlex/testing/capybara.rb

@@ -1,28 +0,0 @@
-# frozen_string_literal: true
-
-require "capybara"
-
-module Phlex::Testing::Capybara
-	include Phlex::Testing::SGML
-
-	def self.included(mod)
-		if defined?(Minitest::Test) && Minitest::Test > mod
-			require "capybara/minitest"
-			mod.include Capybara::Minitest::Assertions
-		end
-
-		if defined?(RSpec::Core::ExampleGroup) && RSpec::Core::ExampleGroup > mod
-			require "capybara/rspec"
-			mod.include Capybara::RSpecMatchers
-		end
-	end
-
-	attr_reader :page
-	alias_method :component, :page
-
-	def render(...)
-		@page = ::Capybara::Node::Simple.new(
-			render_to_string(...),
-		)
-	end
-end