phlex 0.3.2 → 0.5.0

data/docs/pages/testing/capybara.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+require "minitest"
+
+module Pages
+	module Testing
+		class Capybara < ApplicationPage
+			def template
+				render Layout.new(title: "Testing with Capybara") do
+					render Markdown.new(<<~MD)
+						# Testing with Capybara
+
+						Require `phlex/testing/capybara` and include `Phlex::Testing::Capybara::ViewHelper` to use [Capybara](http://teamcapybara.github.io/capybara/) matchers.
+
+						The `render` method will return a `Capybara::Node::Simple` and set the `page` attribute to the result.
+					MD
+
+					render Example.new do |e|
+						e.tab "test.rb", <<~RUBY
+							require "phlex/testing/capybara"
+
+							class TestExample < Minitest::Test
+								include Phlex::Testing::Capybara::ViewHelper
+
+								def test_example
+									render Example.new("Joel")
+									assert_select "h1", text: "Hello Joel"
+								end
+							end
+						RUBY
+
+						e.tab "hello.rb", <<~RUBY
+							class Hello < Phlex::HTML
+								def initialize(name)
+									@name = name
+								end
+
+								def template
+									h1 { "Hello \#{@name}" }
+								end
+							end
+						RUBY
+					end
+				end
+			end
+		end
+	end
+end

data/docs/pages/testing/getting_started.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module Pages
+	module Testing
+		class GettingStarted < ApplicationPage
+			def template
+				render Layout.new(title: "Getting Started Testing Phlex Views") do
+					render Markdown.new(<<~MD)
+						# Getting Started
+
+						The `Phlex::Testing::ViewHelper` module defines `render` allowing you to render Phlex views directly in your tests and make assertions against the output.
+					MD
+
+					render Example.new do |e|
+						e.tab "test/test_hello.rb", <<~RUBY
+							require "phlex/testing/view_helper"
+
+							class TestHello < Minitest::Test
+								include Phlex::Testing::ViewHelper
+
+								def test_hello_output_includes_name
+									output = render Hello.new("Joel")
+									assert_equal "<h1>Hello Joel</h1>", output
+								end
+							end
+						RUBY
+
+						e.tab "hello.rb", <<~RUBY
+							class Hello < Phlex::HTML
+								def initialize(name)
+									@name = name
+								end
+
+								def template
+									h1 { "Hello \#{@name}" }
+								end
+							end
+						RUBY
+					end
+				end
+			end
+		end
+	end
+end

data/docs/pages/testing/nokogiri.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+module Pages
+	module Testing
+		class Nokogiri < ApplicationPage
+			def template
+				render Layout.new(title: "Testing with Nokogiri") do
+					render Markdown.new(<<~MD)
+						# Testing with Nokogiri
+
+						Phlex includes test helpers for working with rendered views as [Nokogiri](https://nokogiri.org) documents and fragments.
+
+						Nokogiri is not a dependency of Phlex, so you’ll need to install that separately to use this helper.
+
+						## Documents
+
+						If your view represents a whole HTML document, you can require `phlex/testing/nokogiri` and include the `Phlex::Testing::Nokogiri::DocumentHelper` module to render your view as `Nokogiri::Document` using the `render` method.
+					MD
+
+					render Example.new do |e|
+						e.tab "test.rb", <<~RUBY
+							require "phlex/testing/nokogiri"
+
+							class TestExample < Minitest::Test
+								include Phlex::Testing::Nokogiri::DocumentHelper
+
+								def test_example
+									output = render Example.new
+									assert_equal "Hello Joel", output.css("h1").text
+								end
+							end
+						RUBY
+
+						e.tab "hello.rb", <<~RUBY
+							class Hello < Phlex::HTML
+								def initialize(name)
+									@name = name
+								end
+
+								def template
+									h1 { "Hello \#{@name}" }
+								end
+							end
+						RUBY
+					end
+
+					render Markdown.new(<<~MD)
+						## Fragments
+
+						If your view represents a fragment (partial), you can require `phlex/testing/nokogiri` and include the `Phlex::Testing::Nokogiri::FragmentHelper` module to render your view as `Nokogiri::Fragment` with the `render` method.
+					MD
+
+					render Example.new do |e|
+						e.tab "test.rb", <<~RUBY
+							require "phlex/testing/nokogiri"
+
+							class TestExample < Minitest::Test
+								include Phlex::Testing::Nokogiri::FragmentHelper
+
+								def test_example
+									output = render Example.new("Joel")
+									assert_equal "Hello Joel", output.css("h1").text
+								end
+							end
+						RUBY
+
+						e.tab "hello.rb", <<~RUBY
+							class Hello < Phlex::HTML
+								def initialize(name)
+									@name = name
+								end
+
+								def template
+									h1 { "Hello \#{@name}" }
+								end
+							end
+						RUBY
+					end
+				end
+			end
+		end
+	end
+end

data/docs/pages/testing/rails.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module Pages
+	module Testing
+		class Rails < ApplicationPage
+			def template
+				render Layout.new(title: "Testing Phlex Views in Rails") do
+					render Markdown.new(<<~MD)
+						# Testing Phlex views in Rails
+
+						When you include `Phlex::Testing::Rails::ViewHelper`, views rendered in the test will have a view context, so they can use Rails helpers.
+					MD
+				end
+			end
+		end
+	end
+end

data/docs/pages/translations.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+module Pages
+	class Translations < ApplicationPage
+		def initialize
+			I18n.backend.store_translations(
+				"pt-BR", {
+					hello: "Olá",
+					views: { feedback: { welcome_message: { hello: "Olá" } } }
+				}
+			)
+			I18n.locale = "pt-BR"
+		end
+
+		def template
+			render Layout.new(title: "Translations") do
+				render Markdown.new(<<~MD)
+					# Translations
+
+					Phlex has built-in support for translations with the **[I18n Gem](https://github.com/ruby-i18n/i18n)**.
+
+					Just include `Phlex::Translation` in your view and use the `translate` method to access a translation.
+				MD
+
+				render Example.new do |e|
+					e.tab "welcome_message.rb", <<~RUBY
+						class WelcomeMessage < Phlex::HTML
+							include Phlex::Translation
+
+							def template
+								h1 { translate("hello") }
+							end
+						end
+					RUBY
+
+					e.tab "pt-PR.yml", <<~YAML, syntax: :yaml
+						pt-BR:
+						  hello: "Olá"
+					YAML
+
+					e.execute "WelcomeMessage.new.call"
+				end
+
+				render Markdown.new(<<~MD)
+					## Implicit scoopes
+
+					Start your translate key with a `.` to use the name of the view as an implicit scope.
+				MD
+
+				render Example.new do |e|
+					e.tab "welcome_message.rb", <<~RUBY
+						module Views
+							module Feedback
+								class WelcomeMessage < Phlex::HTML
+									include Phlex::Translation
+
+									def template
+										h1 { translate(".hello") }
+									end
+								end
+							end
+						end
+					RUBY
+
+					e.tab "pt-BR.yml", <<~YAML, syntax: :yaml
+						pt-BR:
+						  views:
+						    feedback:
+						      welcome_message:
+						        hello: Olá
+					YAML
+
+					e.execute <<~RUBY
+						Views::Feedback::WelcomeMessage.translation_path = 'views.feedback.welcome_message'
+						Views::Feedback::WelcomeMessage.new.call
+					RUBY
+				end
+			end
+		end
+	end
+end

data/docs/pages/views.rb

@@ -3,69 +3,77 @@
 module Pages
 	class Views < ApplicationPage
 		def template
-			render Layout.new(title: "Components in Phlex") do
+			render Layout.new(title: "Phlex Views") do
 				render Markdown.new(<<~MD)
 					#  Views
 
-					## Yielding content
+					Phlex Views are Ruby objects that represent your app's user interface — from pages and layouts and nav-bars, to headings and buttons and links.
 
-					Your views can accept content as a block passed to the template method. You can capture the content block and pass it to the `content` method to yield it.
+					You can create a view class by subclassing `Phlex::HTML` and defining a `template` instance method.
 				MD
 
 				render Example.new do |e|
-					e.tab "card.rb", <<~RUBY
-						class Card < Phlex::View
-							def template(&)
-								article(class: "drop-shadow rounded p-5") {
-									h1 "Amazing content!"
-									yield_content(&)
-								}
+					e.tab "hello.rb", <<~RUBY
+						class Hello < Phlex::HTML
+							def template
+								h1 { "👋 Hello World!" }
 							end
 						end
 					RUBY
 
-					e.execute "Card.new.call { 'Your content here.\n' }"
+					e.execute "Hello.new.call"
 				end
 
 				render Markdown.new(<<~MD)
-					## Delegating content
+					The `template` method determines what your view will output when its rendered. The above example will output an `<h1>` tag with the content `👋 Hello world!`. Click on the "Output" tab above to see for yourself.
+
+					## Accepting arguments
 
-					Alternatively, you can pass the content down as an argument to another view or tag.
+					You can define an initializer for your views just like any other Ruby class. Let's make our `Hello` view take a `name` as a keyword argument, save it in an instance variable and render that variable in the template.
+
+					We'll render this view with the arguments `name: "Joel"` and see what it produces.
 				MD
 
 				render Example.new do |e|
-					e.tab "card.rb", <<~RUBY
-						class Card < Phlex::View
-							def template(&)
-								article(class: "drop-shadow rounded p-5", &)
+					e.tab "hello.rb", <<~RUBY
+						class Hello < Phlex::HTML
+							def initialize(name:)
+								@name = name
+							end
+
+							def template
+								h1 { "👋 Hello \#{@name}!" }
 							end
 						end
 					RUBY
 
-					e.execute "Card.new.call { 'Your content here.' }"
+					e.execute "Hello.new(name: 'Joel').call"
 				end
 
 				render Markdown.new(<<~MD)
-					## Nested views
+					## Rendering views
 
-					Components can render other views and optionally pass them content as a block.
+					Views can render other views in their templates using the `render` method. Let's try rendering a couple of instances of this `Hello` view from a new `Example` view and look at the output of the `Example` view.
 				MD
 
 				render Example.new do |e|
 					e.tab "example.rb", <<~RUBY
-						class Example < Phlex::View
+						class Example < Phlex::HTML
 							def template
-								render Card.new do
-									h1 "Hello"
-								end
+								render Hello.new(name: "Joel")
+								render Hello.new(name: "Alexandre")
 							end
 						end
 					RUBY
 
-					e.tab "card.rb", <<~RUBY
-						class Card < Phlex::View
-							def template(&)
-								article(class: "drop-shadow rounded p-5", &)
+					e.tab "hello.rb", <<~RUBY
+						class Hello < Phlex::HTML
+							def initialize(name:)
+								@name = name
+							end
+
+							def template
+								h1 { "👋 Hello \#{@name}!" }
 							end
 						end
 					RUBY
@@ -74,22 +82,28 @@ module Pages
 				end
 
 				render Markdown.new(<<~MD)
-					If the block just wraps a string, the string is treated as _text content_.
+					## Passing content blocks
+
+					Views can also yield content blocks, which can be passed in when rendering. Let's make a `Card` component that yields content in an `<article>` element with a `drop-shadow` class on it.
 				MD
 
 				render Example.new do |e|
-					e.tab "example.rb", <<~RUBY
-						class Example < Phlex::View
-							def template
-								render(Card.new) { "Hi" }
+					e.tab "card.rb", <<~RUBY
+						class Card < Phlex::HTML
+							def template(&content)
+								article(class: "drop-shadow") do
+									yield_content(&content)
+								end
 							end
 						end
 					RUBY
 
-					e.tab "card.rb", <<~RUBY
-						class Card < Phlex::View
-							def template(&)
-								article(class: "drop-shadow rounded p-5", &)
+					e.tab "example.rb", <<~RUBY
+						class Example < Phlex::HTML
+							def template
+								render Card.new do
+									h1 { "👋 Hello!" }
+								end
 							end
 						end
 					RUBY
@@ -98,28 +112,38 @@ module Pages
 				end
 
 				render Markdown.new(<<~MD)
-					## Component attributes
+					The template in the `Card` view accepts a block argument `&content` and uses the `yield_content` method to yield it in an `<article>` element.
 
-					Besides content, views can define attributes in an initializer, which can then be rendered in the template.
-				MD
+					The `Example` view renders a `Card` and passes it a block with an `<h1>` element.
 
-				render Example.new do |e|
-					e.tab "hello.rb", <<~RUBY
-						class Hello < Phlex::View
-							def initialize(name:)
-								@name = name
-							end
+					Looking at the output of the `Example` view, we can see the `<h1>` element was rendered inside the `<article>` element from the `Card` view.
 
-							def template
-								h1 "Hello \#{@name}!"
-							end
+					## Delegating content blocks
+
+					Since the block of content was the only thing we need in the `<article>` element, we could have just passed the content block to the element instead.
+
+					```ruby
+					class Card < Phlex::HTML
+						def template(&content)
+							article(class: "drop-shadow", &content)
 						end
-					RUBY
+					end
+					```
+				MD
+
+				render Markdown.new(<<~MD)
+					## Registering custom elements
 
+					You can register custom elements with the `register_element` macro. The custom element will only be available in the view where it is registered and subclasses of that view.
+				MD
+
+				render Example.new do |e|
 					e.tab "example.rb", <<~RUBY
-						class Example < Phlex::View
+						class Example < Phlex::HTML
+							register_element :trix_editor
+
 							def template
-								render Hello.new(name: "Joel")
+								trix_editor input: "content", autofocus: true
 							end
 						end
 					RUBY
@@ -128,41 +152,26 @@ module Pages
 				end
 
 				render Markdown.new(<<~MD)
-					It’s usually a good idea to use instance variables directly rather than creating accessor methods for them. Otherwise it’s easy to run into naming conflicts. For example, your layout view might have the attribute `title`, to render into a `<title>` element in the document head. If you define `attr_accessor :title`, that would overwrite the `title` method for creating `<title>` elements.
+					## Callbacks
 
-					## Calculations with methods
-
-					Views are just Ruby classes, so you can perform calculations on view attributes by defining your own methods.
+					Prepend the `Phlex::HTML::Callbacks` module, and if you define `#before_rendering_template` and/or `#after_rendering_template` method in your view, they will be called immediately before and after your template is rendered.
 				MD
 
 				render Example.new do |e|
-					e.tab "status.rb", <<~RUBY
-						class Status < Phlex::View
-							def initialize(status:)
-								@status = status
-							end
+					e.tab "example.rb", <<~RUBY
+						class Example < Phlex::HTML
+							prepend Phlex::HTML::Callbacks
 
-							def template
-								span status_emoji
+							def before_rendering_template
+								h1 { "Hello" }
 							end
 
-							private
-
-							def status_emoji
-								case @status
-								when :success
-									"✅"
-								when :failure
-									"❌"
-								end
+							def template
+								h2 { "World" }
 							end
-						end
-					RUBY
 
-					e.tab "example.rb", <<~RUBY
-						class Example < Phlex::View
-							def template
-								render Status.new(status: :success)
+							def after_rendering_template
+								h3 { "Bye" }
 							end
 						end
 					RUBY

data/fixtures/compiler_test_helpers.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module CompilerTestHelpers
+	# @return Array
+	def compile(view)
+		@compiler = Phlex::Compiler.new(view)
+		output = []
+
+		mock(@compiler) do |m|
+			m.before(:redefine) { output << _1 }
+		end
+
+		@compiler.call
+
+		output.map! do |method|
+			Phlex::Compiler::Formatter.format("", SyntaxTree.parse(method))
+		end
+	end
+end

data/fixtures/content.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module Fixtures
+	module Content
+		class BareString < Phlex::HTML
+			def template
+				h1 { "Hello" }
+			end
+		end
+
+		class Symbol < Phlex::HTML
+			def template
+				h1 { :hello }
+			end
+		end
+
+		class Float < Phlex::HTML
+			def template
+				h1 { 1.2 }
+			end
+		end
+
+		class Integer < Phlex::HTML
+			def template
+				h1 { 1 }
+			end
+		end
+
+		class Variable < Phlex::HTML
+			def template
+				greeting = "Hello"
+				h1 { greeting }
+			end
+		end
+
+		class InstanceVariable < Phlex::HTML
+			def template
+				h1 { @hello }
+			end
+		end
+
+		class NestedTags < Phlex::HTML
+			def template
+				article {
+					h1 { "Inside" }
+				}
+			end
+		end
+
+		class NonMutatingNestedContent < Phlex::HTML
+			def template
+				div { say_hello }
+			end
+
+			def say_hello
+				"Hello"
+			end
+		end
+	end
+end

data/fixtures/dummy/app/components/comment_component.html.erb

@@ -0,0 +1,14 @@
+<div>
+  <span>
+    <%= @name %>
+  </span>
+  <span>
+    <%= @body %>
+  </span>
+
+  <%= content %>
+
+  <%= render Views::Comments::Reaction.new(emoji: 'hamburger') do |reaction| %>
+    <p>Emoji reaction for a comment from <%= @name %> with body <%= @body %></p>
+  <% end %>
+</div>

data/fixtures/dummy/app/components/comment_component.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+class CommentComponent < ViewComponent::Base
+	def initialize(name:, body:)
+		@name = name
+		@body = body
+	end
+end

data/fixtures/dummy/app/components/reaction_component.html.erb

@@ -0,0 +1,3 @@
+<p><%= @emoji %></p>
+
+<%= content %>

data/fixtures/dummy/app/components/reaction_component.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+class ReactionComponent < ViewComponent::Base
+	def initialize(emoji:)
+		@emoji = emoji
+	end
+end

data/fixtures/dummy/app/controllers/comments_controller.rb

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+
+class CommentsController < ActionController::Base
+end

data/fixtures/dummy/app/views/application_view.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module Views
+	class ApplicationView < Phlex::HTML
+		include Rails.application.routes.url_helpers
+		include Phlex::Translation
+	end
+end

data/fixtures/dummy/app/views/articles/form.rb

@@ -2,7 +2,9 @@
 
 module Views
 	module Articles
-		class Form < Phlex::View
+		class Form < ApplicationView
+			include Phlex::Rails::Helpers::FormWith
+
 			def template
 				form_with url: "test" do |f|
 					f.text_field :name