phlex 0.5.3 → 1.0.0.rc2

data/docs/pages/application_page.rb

@@ -1,7 +0,0 @@
-# frozen_string_literal: true
-
-module Pages
-	class ApplicationPage < Phlex::HTML
-		include ::Components
-	end
-end

data/docs/pages/helpers.rb

@@ -1,97 +0,0 @@
-# frozen_string_literal: true
-
-module Pages
-	class Helpers < ApplicationPage
-		def template
-			render Layout.new(title: "Helpers") do
-				render Markdown.new(<<~MD)
-					# Helpers
-
-					## Conditional tokens and classes
-
-					The `tokens` method helps you define conditional HTML attribute tokens (such as CSS classes). It accepts a splat of tokens that should always be output as well as optional keyword arguments for conditional tokens.
-
-					The keyword arguments allow you to specify under which conditions certain tokens are applicable. The keys are the conditions and the values are the tokens. Conditions can be Procs which are evaluated, or Symbols that map to an instance 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`. 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::HTML
-							def initialize(text, to:, active:)
-								@text = text
-								@to = to
-								@active = active
-							end
-
-							def template
-								a(href: @to, class: tokens("nav-item",
-									active?: "nav-item-active")) { @text }
-							end
-
-							private
-
-							def active? = @active
-						end
-					RUBY
-
-					e.tab "example.rb", <<~RUBY
-						class Example < Phlex::HTML
-							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::HTML
-							def initialize(text, to:, active:)
-								@text = text
-								@to = to
-								@active = active
-							end
-
-							def template
-								a(href: @to, **classes("nav-item",
-									active?: "nav-item-active")) { @text }
-							end
-
-							private
-
-							def active? = @active
-						end
-					RUBY
-
-					e.tab "example.rb", <<~RUBY
-						class Example < Phlex::HTML
-							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
-			end
-		end
-	end
-end

data/docs/pages/index.rb

@@ -1,27 +0,0 @@
-# frozen_string_literal: true
-
-module Pages
-	class Index < ApplicationPage
-		def template
-			render Layout.new(title: "Introduction to Phlex, a fast, object-oriented view framework for Ruby") do
-				render Markdown.new(<<~MD)
-	 				# Introduction
-
-					Phlex is a framework for building fast, reusable, testable views in pure Ruby.
-
-					## Better developer experience 💃
-
-					Phlex views are plain old Ruby objects. View classes are just Ruby classes, templates are just methods, and HTML tags are just method calls. If you know how to define a method that calls another method, you pretty much already know how to use Phlex.
-
-					## Better safety 🥽
-
-					Phlex view templates render in an isolated execution context where only the instance variables and methods for the specific view are exposed.
-
-					## Better performance 🔥
-
-					Rendering a Phlex view is ~4.35× faster than an ActionView partial and ~2× faster than ViewComponent component.
-				MD
-			end
-		end
-	end
-end

data/docs/pages/library/collections.rb

@@ -1,83 +0,0 @@
-# frozen_string_literal: true
-
-module Pages
-	module Library
-		class Collections < ApplicationPage
-			def template
-				render Layout.new(title: "Getting started with Rails") do
-					render Markdown.new <<~MD
-						# Collections
-
-						Phlex comes with an abstract pattern for views that represent collections of resources — lists, grids, tables, etc. Collections have two parts: one part wraps the whole collection, the other part is repeated once for each item in that collection.
-
-						When you include `Phlex::Collection` in a `Phlex::HTML`, the `template` and `initialize` methods are defined for you. You don't need to define these. Instead, you define a `collection_template` and `item_template`.
-
-						## Collection template
-
-						The `collection_template` method should accept a content block which is used to yield the items. We can yield this block or pass it to another element, such as `<ul>`.
-
-						```ruby
-						def collection_template(&)
-							ul(&)
-						end
-						```
-
-						## Item template
-
-						From the `item_template` method, you can access a single item with the `@item` instance variable.
-
-						```ruby
-						def item_template
-							li { @item }
-						end
-						```
-
-						## Rendering a collection
-
-						Putting it all together, we can create a `List` view that renders each item in an `<li>`, all wrapped up in an outer `<ul>`.
-
-						We can render the list by passing any Enumerable as the `collection` keyword argument. Here, we pass the array `["A", "B", "C"]`.
-					MD
-
-					render Example.new do |e|
-						e.tab "list.rb", <<~RUBY
-							class List < Phlex::HTML
-								include Phlex::Collection
-
-								def collection_template(&content)
-									ul(&content)
-								end
-
-								def item_template
-									li { @item }
-								end
-							end
-						RUBY
-
-						e.tab "example.rb", <<~RUBY
-							class Example < Phlex::HTML
-								def template
-									render List.new(
-										collection: ["A", "B", "C"]
-									)
-								end
-							end
-						RUBY
-
-						e.execute "Example.new.call"
-					end
-
-					render Markdown.new <<~MD
-						## Rendering a single item
-
-						Sometimes you need to render one item of a collection on its own. This is especially handy if you're using Hotwire to append an item to the end of an existing collection. You can render an individual item without the collection wrapper by passing an `item` keyword argument to the collection view.
-
-						```ruby
-						render List.new(item: "A")
-						```
-					MD
-				end
-			end
-		end
-	end
-end

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