phlex 0.1.0 → 0.2.1

data/docs/pages/index.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module Pages
+  class Index < ApplicationPage
+    def template
+      render Layout.new(title: "Introduction to Phlex") do
+        render Markdown.new(<<~MD)
+          # Introduction
+
+          Phlex is a framework for building fast, reusable, testable view components in pure Ruby.
+
+          Think of a component as anything on a web page that you could draw a circle around and name. Starting on the outside, you have the _“page”_ itself, inside the page is a _“header”_, in the header is a _“nav bar”_ and in the nav bar is a _“nav bar item.”_ These objects together make up an entire page and we call the objects components.
+
+          Each component object is an instance of a specific class of component. 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:
+
+          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 components are plain old Ruby objects: component 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 component templates render in an isolated execution context where only the instance variables and methods for the specific component are exposed.
+
+          ## Better performance 🚀
+
+          Phlex is ~4.35× faster than ActionView and ~2× faster than ViewComponent. Phlex components are also streamable.
+
+          Rails apps typically spend 40-80% of the response time rendering views, so this could be a significant factor in overall app performance.
+        MD
+      end
+    end
+  end
+end

data/docs/pages/templates.rb

@@ -0,0 +1,242 @@
+# frozen_string_literal: true
+
+module Pages
+  class Templates < ApplicationPage
+    def template
+      render Layout.new(title: "Templates in Phlex") do
+        render Markdown.new(<<~MD)
+          # Templates
+
+          Rather than use another langauge like ERB, HAML or Slim, Phlex provides a Ruby DSL for defining HTML templates.
+
+          You can create a component class by subclassing `Phlex::Component` 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).
+
+          The first argument to an HTML element method is the _text content_ for that element. For example, here’s a component with an `<h1>` element that says “Hello World!”
+        MD
+
+        render Example.new do |e|
+          e.tab "heading.rb", <<~RUBY
+            class Heading < Phlex::Component
+              def template
+                h1 "Hello World!"
+              end
+            end
+          RUBY
+
+          e.execute "Heading.new.call"
+        end
+
+        render Markdown.new(<<~MD)
+          The text content is always HTML-escaped, so it’s safe to use with user input.
+
+          ## 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 (`-`).
+        MD
+
+        render Example.new do |e|
+          e.tab "heading.rb", <<~RUBY
+            class Heading < Phlex::Component
+              def template
+                h1 "Hello World!",
+                  class: "text-xl font-bold",
+                  aria_details: "details"
+              end
+            end
+          RUBY
+
+          e.execute "Heading.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.
+        MD
+
+        render Example.new do |e|
+          e.tab "example.rb", <<~RUBY
+            class Example < Phlex::Component
+              def template
+                input type: "radio", name: "channel", id: "1", checked: true
+                input type: "radio", name: "channel", id: "2", checked: false
+              end
+            end
+          RUBY
+
+          e.execute "Example.new.call"
+        end
+
+        render Markdown.new(<<~MD)
+          ## Nesting
+
+          Pass a block to an element method to nest other elements inside it.
+        MD
+
+        render Example.new do |e|
+          e.tab "nav.rb", <<~RUBY
+            class Nav < Phlex::Component
+              def template
+                nav do
+                  ul do
+                    li { a "Home", href: "/" }
+                    li { a "About", href: "/about" }
+                    li { a "Contact", href: "/contact" }
+                  end
+                end
+              end
+            end
+          RUBY
+
+          e.execute "Nav.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.
+        MD
+
+        render Example.new do |e|
+          e.tab "heading.rb", <<~RUBY
+            class Heading < Phlex::Component
+              def template
+                h1 { strong "Hello "; text "World!" }
+              end
+            end
+          RUBY
+
+          e.execute "Heading.new.call"
+        end
+
+        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.
+        MD
+
+        render Example.new do |e|
+          e.tab "links.rb", <<~RUBY
+            class Links < Phlex::Component
+              def template
+                a "Home", href: "/"
+                whitespace
+                a "About", href: "/about"
+                whitespace
+                a "Contact", href: "/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` component 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::Component
+              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::Component
+              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::Component
+              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::Component
+              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 component 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::Component
+              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
+end

data/fixtures/component_helper.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module ComponentHelper
+  def self.extended(parent)
+    parent.instance_exec do
+      let(:output) { example.call }
+      let(:example) { component.new }
+    end
+  end
+
+  def component(&block)
+    let :component do
+      Class.new(Phlex::Component, &block)
+    end
+  end
+end

data/fixtures/dummy/app/controllers/articles_controller.rb

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+
+class ArticlesController < ActionController::Base
+end

data/fixtures/dummy/app/views/articles/form.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Views
+  module Articles
+    class Form < Phlex::Component
+      def template
+        form_with url: "test" do |f|
+          f.text_field :name
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,11 @@
+<p>Before</p>
+<%= render Views::Card.new do |a| %>
+  <p>Start Card A</p>
+  <%= a.title "Hello from A" %>
+  <%= render Views::Card.new do |b| %>
+    <p>Start Card B</p>
+    <%= b.title "Hello from B" %>
+    <p>End Card B</p>
+  <% end %>
+  <p>End Card A</p>
+<% end %>

data/fixtures/dummy/app/views/articles/new.html.erb

@@ -0,0 +1 @@
+<%= render Views::Articles::Form.new %>

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

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Views
+  class Card < Phlex::Component
+    def template(&block)
+      article class: "drop-shadow p-5 rounded", &block
+    end
+
+    def title(text)
+      h3 text, class: "font-bold"
+    end
+  end
+end

data/fixtures/dummy/config/database.yml

@@ -0,0 +1,3 @@
+test:
+  adapter:  sqlite3
+  database: db/combustion_test.sqlite

data/fixtures/dummy/config/routes.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+Rails.application.routes.draw do
+  # Rails routes here
+end

data/fixtures/dummy/config/storage.yml

@@ -0,0 +1,3 @@
+test:
+  service: Disk
+  root: /Users/joeldrapper/src/joeldrapper/phlex/tmp/storage

data/fixtures/dummy/db/schema.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+ActiveRecord::Schema.define do
+  # Set up any tables you need to exist for your test suite that don't belong
+  # in migrations.
+end

data/fixtures/dummy/log/.gitignore

@@ -0,0 +1 @@
+*.log

data/fixtures/layout.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Example
+  class LayoutComponent < Phlex::Component
+    def initialize(title: "Example")
+      @title = title
+    end
+
+    def template(&block)
+      html do
+        head do
+          title @title
+          meta name: "viewport", content: "width=device-width,initial-scale=1"
+          link href: "/assets/tailwind.css", rel: "stylesheet"
+        end
+
+        body class: "bg-zinc-100" do
+          nav class: "p-5", id: "main_nav" do
+            ul do
+              li(class: "p-5") { a "Home", href: "/" }
+              li(class: "p-5") { a "About", href: "/about" }
+              li(class: "p-5") { a "Contact", href: "/contact" }
+            end
+          end
+
+          div class: "container mx-auto p-5", &block
+        end
+      end
+    end
+  end
+end

data/fixtures/page.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module Example
+  class Page < Phlex::Component
+    def template
+      render LayoutComponent.new do
+        h1 "Hi"
+
+        5.times do
+          div do
+            10.times do
+              a "Test", href: "something", unique: SecureRandom.uuid, data: { value: 1 }
+            end
+          end
+        end
+
+        table do
+          thead do
+            10.times do
+              tr do
+                th "Hi"
+              end
+            end
+          end
+
+          tbody do
+            100.times do
+              tr class: "a b c d e f g", id: "something" do
+                10.times do
+                  td class: "f g h i j k l" do
+                    span "Test"
+                  end
+                end
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/fixtures/test_helper.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+require "phlex"
+require "bundler"
+
+Bundler.require :test
+
+Combustion.path = "fixtures/dummy"
+Combustion.initialize! :action_controller do
+  config.autoload_paths << "#{root}/app"
+end
+
+require "component_helper"

data/lib/generators/phlex/component/USAGE

@@ -0,0 +1,8 @@
+Description:
+  Generates a phlex component with the given name
+
+Example:
+  rails generate phlex:component Sidebar
+
+This will create:
+  app/views/components/sidebar_component.rb

data/lib/generators/phlex/component/component_generator.rb

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

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

@@ -0,0 +1,8 @@
+<% module_namespacing do -%>
+module Views
+  class <%= class_name %> < Phlex::Component
+    def template
+    end
+  end
+end
+<% end %>

data/lib/overrides/symbol/name.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Overrides::Symbol::Name
+  refine(Symbol) { alias_method :name, :to_s }
+end

data/lib/phlex/block.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module Phlex
+  class Block
+    def initialize(context, &block)
+      @context = context
+      @block = block
+    end
+
+    def to_proc
+      method(:call).to_proc
+    end
+
+    def call(*args, **kwargs)
+      @context.instance_exec(*args, **kwargs, &@block)
+    end
+  end
+end

data/lib/phlex/buffered.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Phlex
+  class Buffered
+    def initialize(object, buffer:)
+      @object, @buffer = object, buffer
+    end
+
+    def method_missing(name, *args, **kwargs, &block)
+      output = @object.public_send(name, *args, **kwargs, &block)
+      @buffer << output if output.is_a? String
+      nil
+    end
+
+    def respond_to_missing?(name)
+      @object.respond_to?(name)
+    end
+  end
+end