phlex 0.5.2 → 1.0.0.rc1

data/docs/pages/rails/getting_started.rb

@@ -1,57 +0,0 @@
-# frozen_string_literal: true
-
-module Pages
-	module Rails
-		class GettingStarted < ApplicationPage
-			def template
-				render Layout.new(title: "Getting started with Rails") do
-					render Markdown.new <<~MD
-						# Getting started with Phlex on Rails
-
-						While Phlex can be used in any Ruby project, it's especially great with [Rails](https://rubyonrails.org). But before we get into the details, it's important to understand that Phlex is very different from [ActionView](https://guides.rubyonrails.org/action_view_overview.html) and [ViewComponent](https://viewcomponent.org).
-
-						In Phlex, _layouts_, _pages_ and _components_ (or "partials") are the same thing. Phlex Views are Ruby objects that represent every piece of your app's user interface, from pages and layouts and nav-bars, to headings and buttons and links. They're not templates like ERB files in ActionView / ViewComponent; they are just Ruby objects.
-
-						It might feel a bit weird at first, but you'll soon realise how weird it was writing procedural templates in ERB while every other part of your app was object-oriented Ruby.
-
-						## Setup
-
-						If you haven't installed Phlex already, you'll need to add it to your Gemfile. This is a good place to require `phlex/rails`.
-
-						```ruby
-						gem "phlex", require: "phlex/rails"
-						```
-
-						Now run `bundle install`. Once that's finished, you'll want to run the setup script: `bin/rails phlex:install`.
-
-						This script will:
-
-						1. update `config/application.rb` to include `/app` in your auto-load paths;
-						2. generate `views/application_view.rb`.
-
-						Like `ApplicationRecord`, `ApplicationView` is your base view which all your other views should inherit from.
-
-						## Naming conventions
-
-						We recommend using the Zeitwerk conventions for naming. For example, your Articles index page, would be called `Views::Articles::Index` and live in `app/views/articles/index.rb`.
-
-						## View generator
-
-						You can generate new views with the `rails g phlex:view` command.
-
-						For example, running `rails g phlex:view Articles::Index` will create `app/views/articles/index.rb` with the following:
-
-						```ruby
-						module Views
-							class Articles::Index < ApplicationView
-								def template
-								end
-							end
-						end
-						```
-					MD
-				end
-			end
-		end
-	end
-end

data/docs/pages/rails/helpers.rb

@@ -1,55 +0,0 @@
-# frozen_string_literal: true
-
-require "phlex/rails"
-
-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
-						unsafe_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

@@ -1,61 +0,0 @@
-# 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::HTML
-									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::HTML
-									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

@@ -1,37 +0,0 @@
-# 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

@@ -1,35 +0,0 @@
-# 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::HTML` 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/rails_integration.rb

@@ -1,58 +0,0 @@
-# frozen_string_literal: true
-
-module Pages
-	class RailsIntegration < ApplicationPage
-		def template
-			render Layout.new(title: "Ruby on Rails integration") do
-				render Markdown.new(<<~MD)
-					# Ruby on Rails integration
-
-					## Installation
-
-					To install Phlex into your Rails application, you can run the `bin/rails phlex:install` command.
-
-					## View generator
-
-					You can generate new views with the `rails g phlex:view` command.
-
-					For example, running `rails g phlex:view Card` will create the following file:
-				MD
-
-				render CodeBlock.new(<<~RUBY, syntax: :ruby)
-					# app/views/card.rb
-
-					module Views
-						class Card < ApplicationView
-							def template
-							end
-						end
-					end
-				RUBY
-
-				render Markdown.new(<<~MD)
-					## Helpers
-
-					You can use the `helpers` proxy to access helpers within your views.
-
-					For example, you can use the `#t` helper for translations:
-				MD
-
-				render CodeBlock.new(<<~RUBY, syntax: :ruby)
-					# app/views/hello.rb
-
-					module Views
-						class Hello < ApplicationView
-						  delegate :t, to: :helpers
-
-							def template
-							  h1 do
-								  t "hello"
-								end
-							end
-						end
-					end
-				RUBY
-			end
-		end
-	end
-end

data/docs/pages/templates.rb

@@ -1,144 +0,0 @@
-# frozen_string_literal: true
-
-module Pages
-	class Templates < ApplicationPage
-		def template
-			render Layout.new(title: "Templates in Phlex") do
-				render Markdown.new(<<~MD)
-					# Working with 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.
-
-					## Tag attributes
-
-					You can add attributes to HTML tags by passing keyword arguments to the tag methods.
-				MD
-
-				render Example.new do |e|
-					e.tab "hello.rb", <<~RUBY
-						class Hello < Phlex::HTML
-							def template
-								h1(class: "text-xl font-bold") { "👋 Hello World!" }
-							end
-						end
-					RUBY
-
-					e.execute "Hello.new.call"
-				end
-
-				render Markdown.new(<<~MD)
-					## Hash attributes
-
-					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 "hello.rb", <<~RUBY
-						class Hello < Phlex::HTML
-							def template
-								div(data: { controller: "hello" }) do
-									# ...
-								end
-							end
-						end
-					RUBY
-
-					e.execute "Hello.new.call"
-				end
-
-				render Markdown.new(<<~MD)
-					## 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 "channel_controls.rb", <<~RUBY
-						class ChannelControls < Phlex::HTML
-							def template
-								input(
-									value: "1",
-									name: "channel",
-									type: "radio",
-									checked: true
-								)
-
-								input(
-									value: "2",
-									name: "channel",
-									type: "radio",
-									checked: false
-								)
-							end
-						end
-					RUBY
-
-					e.execute "ChannelControls.new.call"
-				end
-
-				render Markdown.new(<<~MD)
-					## The template tag
-
-					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 "example.rb", <<~RUBY
-						class Example < Phlex::HTML
-							def template
-								template_tag do
-									img src: "hidden.jpg", alt: "A hidden image."
-								end
-							end
-						end
-					RUBY
-
-					e.execute "Example.new.call"
-				end
-
-				render Markdown.new(<<~MD)
-					## Stand-alone text
-
-					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::HTML
-							def template
-								h1 do
-									strong { "Hello " }
-									text "World!"
-								end
-							end
-						end
-					RUBY
-
-					e.execute "Heading.new.call"
-				end
-
-				render Markdown.new(<<~MD)
-					## Whitespace
-
-					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::HTML
-							def template
-								a(href: "/") { "Home" }
-								whitespace
-								a(href: "/about") { "About" }
-								whitespace
-								a(href: "/contact") { "Contact" }
-							end
-						end
-					RUBY
-
-					e.execute "Links.new.call"
-				end
-			end
-		end
-	end
-end

data/docs/pages/testing/capybara.rb

@@ -1,48 +0,0 @@
-# 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

@@ -1,44 +0,0 @@
-# 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

@@ -1,83 +0,0 @@
-# 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

@@ -1,17 +0,0 @@
-# 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