phlex 0.3.1 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c121a23175be64626a96f07d72e4946327bf6c152bfe4492301b26d966013969
-  data.tar.gz: 12a03aa7e70678c0663741cec8015a8aec7ed13fd0d76cda379708bb17a0662a
+  metadata.gz: 5606a60fd7cce19c44c13c26ec1abb42f52252b71208aa77f7cecf49f95910be
+  data.tar.gz: 0c55bae86c2f14514108f7d58ab9c6e7d3bc88b5a89cc8cbb7156b86e355041d
 SHA512:
-  metadata.gz: dff05a4aea349c9bfc92d6536caff37d8b903a9993ddc1b37e839e6705c7754977dc9bec2315e7b4ebb9c27b450fc93d7b73385dbc5023231117135e27dcf965
-  data.tar.gz: f3619617c75faccb730653fbdf97bec1ab830079a56c703d4089ea1571f64171cc8552e1699e1c2e1560a0a10cf6b82d13e95c0bd24db4dd658b29476d617cba
+  metadata.gz: 60e835cad9721dcf6c353d84963a93bb2518b307df493f9a4c2fcaf737a69bdb9b7c32ed5b9e8a5c0049c1fea6445e77d75988de7998d4b65ac4b9781dc038e0
+  data.tar.gz: 664c9e1fb555019b40085ad49de87bc2f99619d19157603445590a7179390a52ba66dee614896d8c5901abce5fce1f34031a3b1a6e03931bcad76ba41b48e035

data/.editorconfig

@@ -3,3 +3,11 @@ root = true
 [*]
 indent_style = tab
 indent_size = 2
+
+[*.yml]
+indent_style = space
+indent_size = 2
+
+[*.erb]
+indent_style = space
+indent_size = 2

data/.rubocop.yml

@@ -1,10 +1,6 @@
-inherit_from: "https://www.goodcop.style"
+inherit_from:
+  - "https://www.goodcop.style"
+  - "https://www.goodcop.style/tabs.yml"
 
 AllCops:
   TargetRubyVersion: 2.7
-
-Layout/IndentationStyle:
-  EnforcedStyle: tabs
-
-Layout/IndentationWidth:
-  Width: 1

data/Gemfile

@@ -10,7 +10,6 @@ gem "rake"
 gem "sus", group: [:test]
 gem "rails", group: [:test]
 gem "rouge", group: [:docs]
-gem "listen", group: [:docs]
 gem "webrick", group: [:docs]
 gem "zeitwerk", group: [:docs]
 gem "redcarpet", group: [:docs]
@@ -20,3 +19,5 @@ gem "htmlbeautifier", group: [:docs]
 gem "benchmark-memory"
 gem "rubocop", require: false, github: "joeldrapper/rubocop", branch: "rubocop-user-agent"
 gem "syntax_suggest"
+gem "foreman"
+gem "filewatcher", group: [:docs]

data/Procfile.dev

@@ -0,0 +1,3 @@
+server: ruby -run -e httpd docs/dist
+docs: bundle exec docs/build.rb --watch
+tailwind: npx tailwindcss -i ./docs/assets/application.css -o ./docs/dist/application.css --watch

data/Rakefile

@@ -2,9 +2,7 @@
 
 require "bundler/gem_tasks"
 
-begin
-	require "rspec/core/rake_task"
-	RSpec::Core::RakeTask.new(:spec)
+task :sus do
+	sh "bundle exec sus"
 end
-
-task default: :spec
+task default: :sus

data/docs/build.rb

@@ -1,22 +1,27 @@
 #!/usr/bin/env ruby
 # frozen_string_literal: true
 
+$stdout.sync = true
+
 require "phlex"
 require "bundler"
 require "fileutils"
 
 Bundler.require :docs
 
-Zeitwerk::Loader.new.tap do |loader|
-	loader.push_dir(__dir__)
-	loader.ignore(__FILE__)
-	loader.setup
-	loader.eager_load
-end
-
-FileUtils.mkdir_p("#{__dir__}/dist")
-FileUtils.cp_r("#{__dir__}/assets", "#{__dir__}/dist")
+loader = Zeitwerk::Loader.new
+loader.push_dir(__dir__)
+loader.ignore(__FILE__)
+loader.enable_reloading
+loader.setup
+loader.eager_load
 
 PageBuilder.build_all
 
-system "npx tailwindcss -i ./docs/assets/application.css -o ./docs/dist/application.css"
+if ARGV.include? "--watch"
+	Filewatcher.new("#{__dir__}/**/*rb").watch do |_changes|
+		loader.reload
+		loader.eager_load
+		PageBuilder.build_all
+	end
+end

data/docs/components/code_span.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module Components
+	class CodeSpan < Phlex::View
+		def template(&block)
+			code(class: "bg-stone-50 inline-block font-medium rounded border px-1 -mt-1", &block)
+		end
+	end
+end

data/docs/components/example.rb

@@ -24,7 +24,7 @@ module Components
 		def execute(code)
 			output = @sandbox.class_eval(code)
 
-			@t.tab("HTML Output") do
+			@t.tab("👀 Output") do
 				render CodeBlock.new(HtmlBeautifier.beautify(output), syntax: :html)
 			end
 		end

data/docs/components/heading.rb

@@ -3,7 +3,7 @@
 module Components
 	class Heading < Phlex::View
 		def template(&block)
-			h2(class: "text-xl font-bold mt-10 mb-5", &block)
+			h2(class: "text-2xl font-semibold mt-10 mb-5") { raw(&block) }
 		end
 	end
 end

data/docs/components/layout.rb

@@ -14,30 +14,52 @@ module Components
 			html do
 				head do
 					meta charset: "utf-8"
-					title @title
+					title { @title }
 					link href: "/application.css", rel: "stylesheet"
 					style { raw Rouge::Theme.find("github").render(scope: ".highlight") }
 				end
 
-				body class: "p-12" do
-					div class: "max-w-screen-lg mx-auto grid grid-cols-4 gap-10" do
-						header class: "col-span-1" do
-							a(href: "/", class: "block") { img src: "/assets/logo.png", width: "150" }
-
-							nav do
-								ul do
-									li { a "Introduction", href: "/" }
-									li { a "Templates", href: "/templates" }
-									li { a "Views", href: "/views" }
-									li { a "Rails integration", href: "/rails-integration" }
-									li { a "Source code", href: "https://github.com/joeldrapper/phlex" }
-								end
+				body class: "text-stone-700" do
+					header class: "border-b py-4 px-10 flex justify-between items-center" do
+						a(href: "/", class: "block") { img src: "/assets/logo.png", width: "100" }
+
+						nav(class: "text-stone-500 font-medium") do
+							ul(class: "flex space-x-8") do
+								li { a(href: "https://github.com/sponsors/joeldrapper") { "💖️ Sponsor" } }
+								li { a(href: "https://github.com/joeldrapper/phlex") { "GitHub" } }
 							end
 						end
+					end
+
+					div class: "grid grid-cols-4 divide-x" do
+						nav class: "col-span-1 px-10 py-5" do
+							h2(class: "text-lg font-semibold pt-5") { "Guide" }
+
+							ul do
+								render Nav::Item.new("Introduction", to: Pages::Index, active_page: @_parent)
+								render Nav::Item.new("Views", to: Pages::Views, active_page: @_parent)
+								render Nav::Item.new("Templates", to: Pages::Templates, active_page: @_parent)
+								render Nav::Item.new("Helpers", to: Pages::Helpers, active_page: @_parent)
+							end
+
+							h2(class: "text-lg font-semibold pt-5") { "Rails" }
 
-						main(class: "col-span-3", &block)
+							ul do
+								render Nav::Item.new("Getting started", to: Pages::Rails::GettingStarted, active_page: @_parent)
+								render Nav::Item.new("Rendering views", to: Pages::Rails::RenderingViews, active_page: @_parent)
+								render Nav::Item.new("Laouts", to: Pages::Rails::Layouts, active_page: @_parent)
+								render Nav::Item.new("Helpers", to: Pages::Rails::Helpers, active_page: @_parent)
+								render Nav::Item.new("Migrating to Phlex", to: Pages::Rails::Migrating, active_page: @_parent)
+							end
+						end
+
+						main class: "col-span-3 px-20 px-10 py-5" do
+							div(class: "max-w-prose prose", &block)
+						end
+					end
 
-						footer class: "text-sm text-right col-span-4 py-10"
+					footer class: "border-t p-20 flex justify-center text-stone-500 text-lg font-medium" do
+						a(href: "https://github.com/sponsors/joeldrapper") { "Sponsor this project 💖" }
 					end
 				end
 			end

data/docs/components/markdown.rb

@@ -3,17 +3,31 @@
 module Components
 	class Markdown < Phlex::View
 		class Render < Redcarpet::Render::HTML
+			include Redcarpet::Render::SmartyPants
+
 			def header(text, level)
 				case level
 				when 1
-					Title.new.call { text }
+					Title.new.call { CGI.unescapeHTML(text) }
 				else
-					Heading.new.call { text }
+					Heading.new.call { CGI.unescapeHTML(text) }
 				end
 			end
+
+			def codespan(code)
+				CodeSpan.new.call { code }
+			end
+
+			def block_code(code, language)
+				CodeBlock.new(code.gsub(/(?:^|\G) {4}/m, "	"), syntax: language).call
+			end
+
+			def html_escape(input)
+				input
+			end
 		end
 
-		MARKDOWN = Redcarpet::Markdown.new(Render.new, autolink: true, tables: true)
+		MARKDOWN = Redcarpet::Markdown.new(Render.new, filter_html: false, autolink: true, fenced_code_blocks: true, tables: true, highlight: true, escape_html: false)
 
 		def initialize(content)
 			@content = content

data/docs/components/nav/item.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Components
+	class Nav::Item < Phlex::View
+		def initialize(text, to:, active_page:)
+			@text = text
+			@to = to
+			@active_page = active_page
+		end
+
+		def template
+			li do
+				a(**link_classes, href: "/#{link}") { @text }
+			end
+		end
+
+		def link_classes
+			classes("pb-1 block font-medium text-stone-500", active?: "text-red-600 font-bold")
+		end
+
+		def link
+			path == "index" ? "" : path
+		end
+
+		def path
+			@to.name.split("::")[1..].map { _1.gsub(/(.)([A-Z])/, '\1-\2') }.map(&:downcase).join("/")
+		end
+
+		def active?
+			@active_page.instance_of?(@to)
+		end
+	end
+end

data/docs/components/nav.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+module Components
+	class Nav < Phlex::View
+	end
+end

data/docs/components/tabs/tab.rb

@@ -11,7 +11,9 @@ module Components
 			def template(&block)
 				input class: "opacity-0 fixed peer", type: "radio", name: @_parent.unique_identifier, id: unique_identifier, checked: @checked
 
-				label @name, id: "#{unique_identifier}-label", for: unique_identifier, role: "tab", aria_controls: "#{unique_identifier}-panel", class: "order-1 py-2 px-5 bg-white text-sm border border-b-0 border-l-0 font-medium first-of-type:border-l first-of-type:rounded-tl last-of-type:rounded-tr before:absolute before:pointer-events-none before:w-full before:ring before:h-full before:left-0 before:top-0 before:hidden before:rounded peer-focus:before:block cursor-pointer"
+				label id: "#{unique_identifier}-label", for: unique_identifier, role: "tab", aria_controls: "#{unique_identifier}-panel", class: "order-1 py-2 px-5 bg-white text-sm border border-b-0 border-l-0 font-medium first-of-type:border-l first-of-type:rounded-tl last-of-type:rounded-tr before:absolute before:pointer-events-none before:w-full before:ring before:h-full before:left-0 before:top-0 before:hidden before:rounded peer-focus:before:block cursor-pointer" do
+					@name
+				end
 
 				div id: "#{unique_identifier}-panel", role: "tabpanel", aria_labelledby: "#{unique_identifier}-label", class: "tab hidden order-2 w-full border rounded-b rounded-tr overflow-hidden" do
 					@_parent.instance_exec(&block)

data/docs/components/title.rb

@@ -3,7 +3,7 @@
 module Components
 	class Title < Phlex::View
 		def template(&block)
-			h1(class: "text-2xl font-bold my-5", &block)
+			h1(class: "text-3xl font-semibold my-5") { raw(&block) }
 		end
 	end
 end

data/docs/page_builder.rb

@@ -4,6 +4,8 @@ class PageBuilder
 	ROOT = Pages::ApplicationPage
 
 	def self.build_all
+		FileUtils.mkdir_p("#{__dir__}/dist")
+		FileUtils.cp_r("#{__dir__}/assets", "#{__dir__}/dist")
 		ROOT.subclasses.each { |page| new(page).call }
 	end
 
@@ -12,6 +14,7 @@ class PageBuilder
 	end
 
 	def call
+		puts "Building #{@page.name}"
 		FileUtils.mkdir_p(directory)
 		File.write(file, @page.new.call)
 	end

data/docs/pages/helpers.rb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+module Pages
+	class Helpers < ApplicationPage
+		def template
+			render Layout.new(title: "Templates in Phlex") 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::View
+							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::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(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::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
+			end
+		end
+	end
+end

data/docs/pages/index.rb

@@ -3,34 +3,23 @@
 module Pages
 	class Index < ApplicationPage
 		def template
-			render Layout.new(title: "Introduction to Phlex") do
+			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.
 
-					Each view object is an instance of a specific class of view. The nav-bar, for example, might contain three different nav-bar-items, but they’re all instances of the nav-bar-item class. This class, then, manifests everything there is to know about nav bar items in general. It models:
+					## Better developer experience 💃
 
-					1. the **data** attributes being represented — perhaps url and label;
-					2. a **template**, which dictates how the data should be represented with HTML markup and CSS classes; and
-					3. **logic**, conditions, or calculations on the data — perhaps a predicate method to determine whether the link is active or not.
-
-					# Why use Phlex?
-
-					## Better developer experience 🎉
-
-					You don’t need to introduce a new language like Slim, HAML, or ERB. 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.
+					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 🥽
-					Rails partials can implicitly depend on instance variables from a controller or view. This happens more often than you might think when copying code into a new partial extraction. If the partial is then rendered in a different context or the instance variable’s meaning changes, things can break quite severely without warning.
-
-					Conversely, Phlex view templates render in an isolated execution context where only the instance variables and methods for the specific view are exposed.
 
-					## Better performance 🚀
+					Phlex view templates render in an isolated execution context where only the instance variables and methods for the specific view are exposed.
 
-					Phlex is ~4.35× faster than ActionView and ~2× faster than ViewComponent. Phlex views are also streamable.
+					## Better performance 🔥
 
-					Rails apps typically spend 40-80% of the response time rendering views, so this could be a significant factor in overall app performance.
+					Rendering a Phlex view is ~4.35× faster than an ActionView partial and ~2× faster than ViewComponent component.
 				MD
 			end
 		end

data/docs/pages/library/collections.rb

@@ -0,0 +1,101 @@
+# 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::View`, 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
+						```
+
+						You can also access the predicates `first?` and `last?` and the instance variables `@index`, `@position` and `@collection`.
+
+						```ruby
+						def item_template
+							li **classes(first?: "border-t") do
+								"\#{@position}/\#{@collection.size} \#{@item}"
+							end
+						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::View
+								include Phlex::Collection
+
+								def collection_template(&content)
+									ul(&content)
+								end
+
+								def item_template
+									li **classes(first?: "font-bold") do
+										"(\#{@position}/\#{@collection.size}) \#{@item}"
+									end
+								end
+							end
+						RUBY
+
+						e.tab "example.rb", <<~RUBY
+							class Example < Phlex::View
+								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")
+						```
+
+						If you've used any of the iteration variables and predicates — `first?`, `last?`, `@position`, `@index`, etc. you'll need to pass these manually to simulate this item's position.
+
+						```ruby
+						render List.new(item: "A", first: true, position: 1)
+						```
+					MD
+				end
+			end
+		end
+	end
+end

data/docs/pages/rails/getting_started.rb

@@ -0,0 +1,53 @@
+# 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. The easiest way to do this is to run `bundle add phlex`.
+
+						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