RubyGems - phlex - Versions diffs - 0.3.1 → 0.4.0 - Mend

phlex 0.3.1 → 0.4.0

Potentially problematic release.

This version of phlex might be problematic. Click here for more details.

Files changed (62) hide show

checksums.yaml +4 -4
data/.editorconfig +8 -0
data/.rubocop.yml +3 -7
data/Gemfile +2 -1
data/Procfile.dev +3 -0
data/Rakefile +3 -5
data/docs/build.rb +15 -10
data/docs/components/code_span.rb +9 -0
data/docs/components/example.rb +1 -1
data/docs/components/heading.rb +1 -1
data/docs/components/layout.rb +38 -16
data/docs/components/markdown.rb +17 -3
data/docs/components/nav/item.rb +33 -0
data/docs/components/nav.rb +6 -0
data/docs/components/tabs/tab.rb +3 -1
data/docs/components/title.rb +1 -1
data/docs/page_builder.rb +3 -0
data/docs/pages/helpers.rb +97 -0
data/docs/pages/index.rb +6 -17
data/docs/pages/library/collections.rb +101 -0
data/docs/pages/rails/getting_started.rb +53 -0
data/docs/pages/rails/helpers.rb +53 -0
data/docs/pages/rails/layouts.rb +61 -0
data/docs/pages/rails/migrating.rb +37 -0
data/docs/pages/rails/rendering_views.rb +35 -0
data/docs/pages/templates.rb +51 -149
data/docs/pages/views.rb +55 -94
data/fixtures/dummy/app/components/comment_component.html.erb +14 -0
data/fixtures/dummy/app/components/comment_component.rb +8 -0
data/fixtures/dummy/app/components/reaction_component.html.erb +3 -0
data/fixtures/dummy/app/components/reaction_component.rb +7 -0
data/fixtures/dummy/app/controllers/comments_controller.rb +4 -0
data/fixtures/dummy/app/views/articles/form.rb +2 -0
data/fixtures/dummy/app/views/card.rb +3 -1
data/fixtures/dummy/app/views/comments/comment.rb +25 -0
data/fixtures/dummy/app/views/comments/index.html.erb +3 -0
data/fixtures/dummy/app/views/comments/reaction.rb +17 -0
data/fixtures/dummy/app/views/comments/show.html.erb +3 -0
data/fixtures/test_helper.rb +3 -0
data/lib/generators/phlex/collection/USAGE +8 -0
data/lib/generators/phlex/collection/collection_generator.rb +13 -0
data/lib/generators/phlex/collection/templates/collection.rb.erb +15 -0
data/lib/generators/phlex/layout/USAGE +8 -0
data/lib/generators/phlex/layout/layout_generator.rb +13 -0
data/lib/generators/phlex/layout/templates/layout.rb.erb +30 -0
data/lib/generators/phlex/page/USAGE +8 -0
data/lib/generators/phlex/page/page_generator.rb +13 -0
data/lib/generators/phlex/page/templates/page.rb.erb +11 -0
data/lib/generators/phlex/table/USAGE +8 -0
data/lib/generators/phlex/table/table_generator.rb +14 -0
data/lib/generators/phlex/table/templates/table.rb.erb +9 -0
data/lib/phlex/collection.rb +58 -0
data/lib/phlex/engine.rb +0 -3
data/lib/phlex/html.rb +7 -13
data/lib/phlex/rails/helpers.rb +81 -0
data/lib/phlex/rails/layout.rb +15 -0
data/lib/phlex/table.rb +104 -0
data/lib/phlex/version.rb +1 -1
data/lib/phlex/view.rb +10 -4
data/lib/phlex.rb +1 -0
metadata +52 -3
data/lib/phlex/rails/tag_helpers.rb +0 -29

data/docs/pages/rails/helpers.rb ADDED Viewed

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+module Pages
+	module Rails
+		class Helpers < ApplicationPage
+			def template
+				render Layout.new(title: "Using Rails helpers in Phlex views") do
+					render Markdown.new <<~MD
+						# Using Rails helpers in Phlex views
+						## The `helpers` proxy
+						You can use the `helpers` proxy to access any Rails helper from a Phlex view. For example, you can use the `#t` helper for translations:
+						```ruby
+						module Views
+							class Hello < ApplicationView
+								delegate :t, to: :helpers
+								def template
+									h1 do
+										t "hello"
+									end
+								end
+							end
+						end
+						```
+						## Layout helpers
+						Rails tag helpers return strings which makes them less than ideal to use from Phlex. Including `Phlex::Rails::Layout` gives you access to the following Rails helper proxies which immediately output to the buffer:
+						#{(Phlex::Rails::Layout.instance_methods - Module.methods).sort.map { "1. `#{_1}`" }.join("\n")}
+						Using these is equvalent to passing the output of the original Rails helpers to `raw`, e.g:
+						```ruby
+						raw helpers.javascript_include_tag
+						```
+						## Including proxies
+						The following modules can be included for direct access to these helpers:
+						#{Phlex::Rails::Helpers.constants.sort.map { "1. `Phlex::Rails::Helpers::#{_1}`" }.join("\n")}
+						Note, helpers that produce HTML are adapted to output to the buffer directly.
+					MD
+				end
+			end
+		end
+	end
+end

data/docs/pages/rails/layouts.rb ADDED Viewed

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+module Pages
+	module Rails
+		class Layouts < ApplicationPage
+			def template
+				render Layout.new(title: "Getting started with Rails") do
+					render Markdown.new <<~MD
+						# Layouts in Rails
+						Rails has an implicit layouts feature that automatically wraps views in a layout template, usually `views/layouts/application.html.erb`. When using Phlex, you'll probably want to by-pass this feature completely. Here's why:
+						Sometimes you need to pass some argument to the layout, such as a page title that needs to be rendered in a `<title>` tag in the HTML `<head>`. Rails lets you do this from another part of the view using the `content_for` feature, but this pattern precludes defining an explicit interface for your layout through its initializer.
+						If layouts are Phlex views, they can be rendered just like any other view and can require that `title` argument from their initializer. The trick is the page view renders its content into the layout view.
+					MD
+					render Example.new do |e|
+						e.tab "layout.rb", <<~RUBY
+							module Views
+								class Layout < Phlex::View
+									def initialize(title:)
+										@title = title
+									end
+									def template(&)
+										html do
+											head do
+												title { @title }
+											end
+											body(&)
+										end
+									end
+								end
+							end
+						RUBY
+						e.tab "index.rb", <<~RUBY
+							module Views
+								class Index < Phlex::View
+									def template
+										render Layout.new(title: "Hello") do
+											h1 { "👋" }
+										end
+									end
+								end
+							end
+						RUBY
+						e.execute "Views::Index.new.call"
+					end
+					render Markdown.new <<~MD
+						If you're using a Phlex view as a layout, you'll want to disable layouts from your Rails controller. You can do this by adding `layout false` to your controller. In a new app, you'll probably want to add this to the `ApplicationController`.
+					MD
+				end
+			end
+		end
+	end
+end

data/docs/pages/rails/migrating.rb ADDED Viewed

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+module Pages
+	class Rails::Migrating < ApplicationPage
+		def template
+			render Layout.new(title: "Migrating to Phlex in Rails") do
+				render Markdown.new <<~MD
+					# Migrating an existing Rails app to Phlex
+					Whether you currently use ActionView or ViewComponent with ERB, HAML or Slim, you can start using Phlex in your Rails app today without a big rewrite.
+					## You can render Phlex views into existing templates
+					Phlex views implement the _renderable_ interface for Rails, which means they can be rendered from a controller or another view template — even ViewComponent templates. This means you can gradually migrate specific pages and components to Phlex without having to change anything else.
+					## You can render ActionView partials and ViewComponent components in Phlex views
+					That's right, the `render` method in Phlex doesn't only work with Phlex views. You can use it to render ActionView partials and ViewComponent components too.
+					Say you have an `articles/index.html.erb` template that renders a list of articles using the `articles/_article.html.erb` partial. You can convert the index template to an `Articles::Index` Phlex view while continuing to render the same ActionView partial inside it.
+					## Use an ERB → Phlex converter
+					The ERB → Phlex converter, [Phlexing](https://www.phlexing.fun), can do the heavy-lifting but it won't help you architect your components / design system. Take your time, converting things piece-by-piece.
+					If you're using ViewComponent, you might find you can convert components to Phlex views without even changing any call-sites.
+					## Save the layout 'til last
+					After everything I said about layouts in the previous section, I'll let you in on a little secret: Phlex actually does support `content_for` in one direction. You can't yield a `content_for` block in Phlex, but you can assign one.
+					If you're working on an established Rails app, the layout is probably the last thing you should convert. Just include `Phlex::Rails::Helpers::ContentFor` in your `ApplicationView` and you'll be able to render Phlex views into existing ActionView layouts and assign `content_for` blocks too.
+				MD
+			end
+		end
+	end
+end

data/docs/pages/rails/rendering_views.rb ADDED Viewed

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+module Pages
+	class Rails::RenderingViews < ApplicationPage
+		def template
+			render Layout.new(title: "Getting started with Rails") do
+				render Markdown.new <<~MD
+					# Rendering Phlex views in Rails
+					You can render a `Phlex::View` from your Rails controller actions as well as other views, and even from ActionView / ViewComponent templates.
+					Instead of implicitly rendering an ERB template with automatic access to all your controller instance variables, you need to explicitly render Phlex views from your controller action methods.
+					Doing this allows you to design views without implicit dependencies on controller instance variables, making them much easier to test and reuse and reason about.
+					```ruby
+					class ArticlesController < ApplicationController
+						def index
+							render Views::Articles::Index.new(
+								articles: Article.all.load_async
+							)
+						end
+						def show
+							render Views::Articles::Show.new(
+								article: Article.find(params[:id])
+							)
+						end
+					end
+					```
+				MD
+			end
+		end
+	end
+end

data/docs/pages/templates.rb CHANGED Viewed

@@ -5,101 +5,111 @@ module Pages
 		def template
 			render Layout.new(title: "Templates in Phlex") do
 				render Markdown.new(<<~MD)
-					# Templates
+					# Working with templates
-					Rather than use another language like ERB, HAML or Slim, Phlex provides a Ruby DSL for defining HTML templates.
+					In Phlex, templates are just methods that call other methods that add things to the output buffer. When you call the method `h1`, an `<h1>` tag is buffered for output.
-					You can create a view class by subclassing `Phlex::View` and defining a method called `template`. Within the `template` method, you can compose HTML markup by calling the name of any [HTML element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element).
+					## Tag attributes
-					The first argument to an HTML element method is the _text content_ for that element. For example, here’s a view with an `<h1>` element that says “Hello World!”
+					You can add attributes to HTML tags by passing keyword arguments to the tag methods.
 				MD
 				render Example.new do |e|
-					e.tab "heading.rb", <<~RUBY
-						class Heading < Phlex::View
+					e.tab "hello.rb", <<~RUBY
+						class Hello < Phlex::View
 							def template
-								h1 "Hello World!"
+								h1(class: "text-xl font-bold") { "👋 Hello World!" }
 							end
 						end
 					RUBY
-					e.execute "Heading.new.call"
+					e.execute "Hello.new.call"
 				end
 				render Markdown.new(<<~MD)
-					The text content is always HTML-escaped, so it’s safe to use with user input.
+					## Hash attributes
-					## Attributes
-					You can add attributes to HTML elements by passing keyword arguments to the tag method. Underscores (`_`) in attribute names are automatically converted to dashes (`-`).
+					If you pass a `Hash` as an attribute value, the hash will be flattened with a dash between each section.
 				MD
 				render Example.new do |e|
-					e.tab "heading.rb", <<~RUBY
-						class Heading < Phlex::View
+					e.tab "hello.rb", <<~RUBY
+						class Hello < Phlex::View
 							def template
-								h1 "Hello World!",
-									class: "text-xl font-bold",
-									aria_details: "details"
+								div(data: { controller: "hello" }) do
+									# ...
+								end
 							end
 						end
 					RUBY
-					e.execute "Heading.new.call"
+					e.execute "Hello.new.call"
 				end
 				render Markdown.new(<<~MD)
-					You can also use *boolean* attributes. When set to `true`, the attribute will be rendered without a value, when _falsy_, the attribute isn’t rendered at all.
+					## Boolean attributes
+					When `true`, the attribute will be rendered without a value; when _falsy_, the attribute isn’t rendered at all. You can still use the strings `"true"` and `"false"` as values for non-boolean attributes.
 				MD
 				render Example.new do |e|
-					e.tab "example.rb", <<~RUBY
-						class Example < Phlex::View
+					e.tab "channel_controls.rb", <<~RUBY
+						class ChannelControls < Phlex::View
 							def template
-								input type: "radio", name: "channel", id: "1", checked: true
-								input type: "radio", name: "channel", id: "2", checked: false
+								input(
+									value: "1",
+									name: "channel",
+									type: "radio",
+									checked: true
+								)
+								input(
+									value: "2",
+									name: "channel",
+									type: "radio",
+									checked: false
+								)
 							end
 						end
 					RUBY
-					e.execute "Example.new.call"
+					e.execute "ChannelControls.new.call"
 				end
 				render Markdown.new(<<~MD)
-					## Nesting
+					## The template tag
-					Pass a block to an element method to nest other elements inside it.
+					Because the `template` method is used to define the view template itself, you'll need to use the method `template_tag` if you want to to render an HTML `<template>` tag.
 				MD
 				render Example.new do |e|
-					e.tab "nav.rb", <<~RUBY
-						class Nav < Phlex::View
+					e.tab "example.rb", <<~RUBY
+						class Example < Phlex::View
 							def template
-								nav do
-									ul do
-										li { a "Home", href: "/" }
-										li { a "About", href: "/about" }
-										li { a "Contact", href: "/contact" }
-									end
+								template_tag do
+									img src: "hidden.jpg", alt: "A hidden image."
 								end
 							end
 						end
 					RUBY
-					e.execute "Nav.new.call"
+					e.execute "Example.new.call"
 				end
 				render Markdown.new(<<~MD)
 					## Stand-alone text
-					You can also output text without wrapping it in an element by using the `text` method. All text content is HTML-escaped, so it’s safe to use with user input.
+					You can output text content without wrapping it in an element by using the `text` helper method.
 				MD
 				render Example.new do |e|
 					e.tab "heading.rb", <<~RUBY
 						class Heading < Phlex::View
 							def template
-								h1 { strong "Hello "; text "World!" }
+								h1 do
+									strong { "Hello " }
+									text "World!"
+								end
 							end
 						end
 					RUBY
@@ -110,132 +120,24 @@ module Pages
 				render Markdown.new(<<~MD)
 					## Whitespace
-					While the examples on this page have been formatted for readability, there is usually no whitespace between HTML tags. If you need to add some whitespace, you can use the `whitespace` method. This is useful for adding space between _inline_ elements to allow them to wrap.
+					The example output on this site is formatted for readability, but there is usually no whitespace between HTML tags in the output. If you need to add some whitespace, you can use the `whitespace` helper. This is useful for adding space between _inline_ elements to allow them to wrap.
 				MD
 				render Example.new do |e|
 					e.tab "links.rb", <<~RUBY
 						class Links < Phlex::View
 							def template
-								a "Home", href: "/"
+								a(href: "/") { "Home" }
 								whitespace
-								a "About", href: "/about"
+								a(href: "/about") { "About" }
 								whitespace
-								a "Contact", href: "/contact"
+								a(href: "/contact") { "Contact" }
 							end
 						end
 					RUBY
 					e.execute "Links.new.call"
 				end
-				render Markdown.new(<<~MD)
-					## Tokens and classes
-					The `tokens` method helps you define conditional HTML attribute tokens (such as CSS classes).
-					The `tokens` method accepts a splat of tokens that should always be output, and accepts keyword arguments for conditional tokens.
-					The keyword arguments allow you to specify under which conditions certain tokens are applicable. The keyword argument keys are the conditions and the values are the tokens. Conditions can be Procs or Symbols that map to a relevant method. The `:active?` Symbol, for example, maps to the `active?` instance method.
-					Here we have a `Link` view that produces an `<a>` tag with the CSS class `nav-item`. And if the link is _active_, we also apply the CSS class `nav-item-active`.
-				MD
-				render Example.new do |e|
-					e.tab "link.rb", <<~RUBY
-						class Link < Phlex::View
-							def initialize(text, to:, active:)
-								@text = text
-								@to = to
-								@active = active
-							end
-							def template
-								a @text, href: @to, class: tokens("nav-item",
-									active?: "nav-item-active")
-							end
-							private
-							def active? = @active
-						end
-					RUBY
-					e.tab "example.rb", <<~RUBY
-						class Example < Phlex::View
-							def template
-								nav do
-									ul do
-										li { render Link.new("Home", to: "/", active: true) }
-										li { render Link.new("About", to: "/about", active: false) }
-									end
-								end
-							end
-						end
-					RUBY
-					e.execute "Example.new.call"
-				end
-				render Markdown.new(<<~MD)
-					You can also use the `classes` helper method to create a token list of classes. Since this method returns a hash (e.g. `{ class: "your CSS classes here" }`), you can destructure it into a `class:` keyword argument using the `**` prefix operator.
-				MD
-				render Example.new do |e|
-					e.tab "link.rb", <<~RUBY
-						class Link < Phlex::View
-							def initialize(text, to:, active:)
-								@text = text
-								@to = to
-								@active = active
-							end
-							def template
-								a @text, href: @to, **classes("nav-item",
-									active?: "nav-item-active")
-							end
-							private
-							def active? = @active
-						end
-					RUBY
-					e.tab "example.rb", <<~RUBY
-						class Example < Phlex::View
-							def template
-								nav do
-									ul do
-										li { render Link.new("Home", to: "/", active: true) }
-										li { render Link.new("About", to: "/about", active: false) }
-									end
-								end
-							end
-						end
-					RUBY
-					e.execute "Example.new.call"
-				end
-				render Markdown.new(<<~MD)
-					## The template element
-					Because the `template` method is used to define the view template itself, you need to use the method `template_tag` if you want to to render an HTML `<template>` tag.
-				MD
-				render Example.new do |e|
-					e.tab "example.rb", <<~RUBY
-						class Example < Phlex::View
-							def template
-								template_tag do
-									img src: "hidden.jpg", alt: "A hidden image."
-								end
-							end
-						end
-					RUBY
-					e.execute "Example.new.call"
-				end
 			end
 		end
 	end