phlex 0.3.1 → 0.4.0

data/docs/pages/views.rb

@@ -3,107 +3,69 @@
 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::View` 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::View
+							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.
 
-					Alternatively, you can pass the content down as an argument to another view or tag.
-				MD
+					## Accepting arguments
 
-				render Example.new do |e|
-					e.tab "card.rb", <<~RUBY
-						class Card < Phlex::View
-							def template(&)
-								article(class: "drop-shadow rounded p-5", &)
-							end
-						end
-					RUBY
+					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.
 
-					e.execute "Card.new.call { 'Your content here.' }"
-				end
-
-				render Markdown.new(<<~MD)
-					## Nested views
-
-					Components can render other views and optionally pass them content as a block.
+					We'll render this view with the arguments `name: "Joel"` and see what it produces.
 				MD
 
 				render Example.new do |e|
-					e.tab "example.rb", <<~RUBY
-						class Example < Phlex::View
-							def template
-								render Card.new do
-									h1 "Hello"
-								end
+					e.tab "hello.rb", <<~RUBY
+						class Hello < Phlex::View
+							def initialize(name:)
+								@name = name
 							end
-						end
-					RUBY
 
-					e.tab "card.rb", <<~RUBY
-						class Card < Phlex::View
-							def template(&)
-								article(class: "drop-shadow rounded p-5", &)
+							def template
+								h1 { "👋 Hello \#{@name}!" }
 							end
 						end
 					RUBY
 
-					e.execute "Example.new.call"
+					e.execute "Hello.new(name: 'Joel').call"
 				end
 
 				render Markdown.new(<<~MD)
-					If the block just wraps a string, the string is treated as _text content_.
+					## Rendering views
+
+					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
 							def template
-								render(Card.new) { "Hi" }
-							end
-						end
-					RUBY
-
-					e.tab "card.rb", <<~RUBY
-						class Card < Phlex::View
-							def template(&)
-								article(class: "drop-shadow rounded p-5", &)
+								render Hello.new(name: "Joel")
+								render Hello.new(name: "Alexandre")
 							end
 						end
 					RUBY
 
-					e.execute "Example.new.call"
-				end
-
-				render Markdown.new(<<~MD)
-					## Component attributes
-
-					Besides content, views can define attributes in an initializer, which can then be rendered in the template.
-				MD
-
-				render Example.new do |e|
 					e.tab "hello.rb", <<~RUBY
 						class Hello < Phlex::View
 							def initialize(name:)
@@ -111,15 +73,7 @@ module Pages
 							end
 
 							def template
-								h1 "Hello \#{@name}!"
-							end
-						end
-					RUBY
-
-					e.tab "example.rb", <<~RUBY
-						class Example < Phlex::View
-							def template
-								render Hello.new(name: "Joel")
+								h1 { "👋 Hello \#{@name}!" }
 							end
 						end
 					RUBY
@@ -128,32 +82,17 @@ 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.
+					## Passing content blocks
 
-					## Calculations with methods
-
-					Views are just Ruby classes, so you can perform calculations on view attributes by defining your own methods.
+					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 "status.rb", <<~RUBY
-						class Status < Phlex::View
-							def initialize(status:)
-								@status = status
-							end
-
-							def template
-								span status_emoji
-							end
-
-							private
-
-							def status_emoji
-								case @status
-								when :success
-									"✅"
-								when :failure
-									"❌"
+					e.tab "card.rb", <<~RUBY
+						class Card < Phlex::View
+							def template(&content)
+								article(class: "drop-shadow") do
+									yield_content(&content)
 								end
 							end
 						end
@@ -162,13 +101,35 @@ module Pages
 					e.tab "example.rb", <<~RUBY
 						class Example < Phlex::View
 							def template
-								render Status.new(status: :success)
+								render Card.new do
+									h1 { "👋 Hello!" }
+								end
 							end
 						end
 					RUBY
 
 					e.execute "Example.new.call"
 				end
+
+				render Markdown.new(<<~MD)
+					The template in the `Card` view accepts a block argument `&content` and uses the `yield_content` method to yield it in an `<article>` element.
+
+					The `Example` view renders a `Card` and passes it a block with an `<h1>` element.
+
+					Looking at the output of the `Example` view, we can see the `<h1>` element was rendered inside the `<article>` element from the `Card` view.
+
+					## 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::View
+						def template(&content)
+							article(class: "drop-shadow", &content)
+						end
+					end
+					```
+				MD
 			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/articles/form.rb

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

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

@@ -7,7 +7,9 @@ module Views
 		end
 
 		def title(text)
-			h3 text, class: "font-bold"
+			h3 class: "font-bold" do
+				text
+			end
 		end
 	end
 end

data/fixtures/dummy/app/views/comments/comment.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Views
+	module Comments
+		class Comment < Phlex::View
+			def initialize(name:, body:)
+				@name = name
+				@body = body
+			end
+
+			def template(&block)
+				div {
+					span { @name }
+					span { @body }
+
+					yield_content(&block)
+
+					render(::ReactionComponent.new(emoji: "hamburger")) do
+						p { "Emoji reaction for a comment from #{@name} with body #{@body}" }
+					end
+				}
+			end
+		end
+	end
+end

data/fixtures/dummy/app/views/comments/index.html.erb

@@ -0,0 +1,3 @@
+<%= render(CommentComponent.new(name: "Matz", body: "hey, folks")) do %>
+  Hello, World from a ViewComponent!
+<% end %>

data/fixtures/dummy/app/views/comments/reaction.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module Views
+	module Comments
+		class Reaction < Phlex::View
+			def initialize(emoji:)
+				@emoji = emoji
+			end
+
+			def template(&block)
+				p { @emoji }
+
+				yield_content(&block)
+			end
+		end
+	end
+end

data/fixtures/dummy/app/views/comments/show.html.erb

@@ -0,0 +1,3 @@
+<%= render Views::Comments::Comment.new(name: "_why", body: "I'm back") do %>
+  Hello, World from a Phlex Component!
+<% end %>

data/fixtures/test_helper.rb

@@ -2,6 +2,7 @@
 
 require "phlex"
 require "bundler"
+require "view_component"
 
 Bundler.require :test
 
@@ -11,3 +12,5 @@ Combustion.initialize! :action_controller do
 end
 
 require "view_helper"
+
+Zeitwerk::Loader.eager_load_all

data/lib/generators/phlex/collection/USAGE

@@ -0,0 +1,8 @@
+Description:
+  Generates a Phlex collection view with the given name
+
+Example:
+  rails generate phlex:collection Articles::List
+
+This will create:
+  app/views/articles/list.rb

data/lib/generators/phlex/collection/collection_generator.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Phlex
+	module Generators
+		class CollectionGenerator < ::Rails::Generators::NamedBase
+			source_root File.expand_path("templates", __dir__)
+
+			def create_view
+				template "collection.rb.erb", File.join("app/views", class_path, "#{file_name}.rb")
+			end
+		end
+	end
+end

data/lib/generators/phlex/collection/templates/collection.rb.erb

@@ -0,0 +1,15 @@
+<% module_namespacing do -%>
+module Views
+  class <%= class_name %> < ApplicationView
+    include Phlex::Collection
+
+    def collection_template(&)
+      ul(&)
+    end
+
+    def item_template
+      li { @item }
+    end
+  end
+end
+<% end %>

data/lib/generators/phlex/layout/USAGE

@@ -0,0 +1,8 @@
+Description:
+  Generates a Phlex layout view with the given name
+
+Example:
+  rails generate phlex:layout Layout
+
+This will create:
+  app/views/layout.rb

data/lib/generators/phlex/layout/layout_generator.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Phlex
+	module Generators
+		class LayoutGenerator < ::Rails::Generators::NamedBase
+			source_root File.expand_path("templates", __dir__)
+
+			def create_view
+				template "layout.rb.erb", File.join("app/views", class_path, "#{file_name}.rb")
+			end
+		end
+	end
+end

data/lib/generators/phlex/layout/templates/layout.rb.erb

@@ -0,0 +1,30 @@
+<% module_namespacing do -%>
+module Views
+  class <%= class_name %> < ApplicationView
+    include Phlex::Rails::Layout
+
+    def initialize(title:)
+      @title = title
+    end
+
+    def template(&)
+      doctype
+
+      html do
+        head do
+          meta charset: "utf-8"
+          csp_meta_tag
+          csrf_meta_tags
+          meta name: "viewport", content: "width=device-width,initial-scale=1"
+          title { @title }
+          stylesheet_link_tag "application"
+        end
+
+        body do
+          main(&)
+        end
+      end
+    end
+  end
+end
+<% end %>

data/lib/generators/phlex/page/USAGE

@@ -0,0 +1,8 @@
+Description:
+  Generates a Phlex page view with the given name
+
+Example:
+  rails generate phlex:page Articles::Index
+
+This will create:
+  app/views/articles/index.rb

data/lib/generators/phlex/page/page_generator.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Phlex
+	module Generators
+		class PageGenerator < ::Rails::Generators::NamedBase
+			source_root File.expand_path("templates", __dir__)
+
+			def create_view
+				template "page.rb.erb", File.join("app/views", class_path, "#{file_name}.rb")
+			end
+		end
+	end
+end

data/lib/generators/phlex/page/templates/page.rb.erb

@@ -0,0 +1,11 @@
+<% module_namespacing do -%>
+module Views
+  class <%= class_name %> < ApplicationView
+    def template
+      render Layout.new(title: "<%= class_name.gsub("::", " ") %>") do
+        h1 { "👋 Hello World!" }
+      end
+    end
+  end
+end
+<% end %>

data/lib/generators/phlex/table/USAGE

@@ -0,0 +1,8 @@
+Description:
+	Generates a Phlex table collection view with the given name
+
+Example:
+	rails generate phlex:collection Articles::Table --properties title author created_at
+
+This will create:
+	app/views/articles/table.rb

data/lib/generators/phlex/table/table_generator.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module Phlex
+	module Generators
+		class TableGenerator < ::Rails::Generators::NamedBase
+			source_root File.expand_path("templates", __dir__)
+			class_option :properties, type: :array, default: []
+
+			def create_view
+				template "table.rb.erb", File.join("app/views", class_path, "#{file_name}.rb")
+			end
+		end
+	end
+end

data/lib/generators/phlex/table/templates/table.rb.erb

@@ -0,0 +1,9 @@
+<% module_namespacing do -%>
+module Views
+  class <%= class_name %> < ApplicationView
+    include Phlex::Table
+    <% options["properties"].each do |property| %>
+    property "<%= property.humanize %>", &:<%= property.underscore %><% end %>
+  end
+end
+<% end %>

data/lib/phlex/collection.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module Phlex
+	module Collection
+		def initialize(collection: nil, item: nil)
+			unless collection || item
+				raise ArgumentError, "You must pass a collection or an item as a keyword argument."
+			end
+
+			@collection = collection
+			@item = item
+		end
+
+		def template
+			if @item
+				item_template
+			else
+				collection_template { yield_items }
+			end
+		end
+
+		private
+
+		def yield_items
+			if @item
+				raise ArgumentError, "You can only yield_items when rendering a collection. You are currently rendering an item."
+			end
+
+			@collection.each_with_index do |item, index|
+				@item = item
+				@index = index
+				@position = (index + 1)
+				@first = (index == 0)
+				@last = (@position == @collection.size)
+
+				item_template
+			end
+
+			@item = nil
+			@index = nil
+			@first = nil
+			@last = nil
+			@position = nil
+		end
+
+		def first?
+			raise ArgumentError unless @item
+
+			@first
+		end
+
+		def last?
+			raise ArgumentError unless @item
+
+			@last
+		end
+	end
+end

data/lib/phlex/engine.rb

@@ -4,8 +4,5 @@ require "rails/engine"
 
 module Phlex
 	class Engine < ::Rails::Engine
-		initializer "phlex.tag_helpers" do
-			Phlex::View.include(Phlex::Rails::TagHelpers)
-		end
 	end
 end

data/lib/phlex/html.rb

@@ -113,6 +113,7 @@ module Phlex
 			area: "area",
 			br: "br",
 			embed: "embed",
+			hr: "hr",
 			img: "img",
 			input: "input",
 			link: "link",
@@ -130,10 +131,12 @@ module Phlex
         # frozen_string_literal: true
 
         def #{element}(content = nil, **attributes, &block)
+					if content
+						raise ArgumentError, %(👋 You can no longer pass content to #{element} as a positional argument.\n Instead, you can pass it as a block, e.g. #{element} { "Hello" })
+					end
+
           if attributes.length > 0
-            if content
-              @_target << "<#{tag}" << (Phlex::ATTRIBUTE_CACHE[attributes.hash] || _attributes(attributes)) << ">" << CGI.escape_html(content) << "</#{tag}>"
-            elsif block_given?
+            if block_given?
               @_target << "<#{tag}" << (Phlex::ATTRIBUTE_CACHE[attributes.hash] || _attributes(attributes)) << ">"
               yield_content(&block)
               @_target << "</#{tag}>"
@@ -141,16 +144,7 @@ module Phlex
               @_target << "<#{tag}" << (Phlex::ATTRIBUTE_CACHE[attributes.hash] || _attributes(attributes)) << "></#{tag}>"
             end
           else
-            if content
-              case content
-              when String
-                @_target << "<#{tag}>" << CGI.escape_html(content) << "</#{tag}>"
-              when Symbol
-                @_target << "<#{tag}>" << CGI.escape_html(content.name) << "</#{tag}>"
-              else
-                @_target << "<#{tag}>" << CGI.escape_html(content.to_s) << "</#{tag}>"
-              end
-            elsif block_given?
+            if block_given?
               @_target << "<#{tag}>"
               yield_content(&block)
               @_target << "</#{tag}>"