phlex 0.1.0 → 0.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 899a4ffd2a666431474757fa3732dd3abbd5b0bc747db29df6044ba152aa47e4
-  data.tar.gz: 9ebbc4b7409dfd827eee58ed41d1a5951c55c99e106a3ce8a5ea7156bff6ecec
+  metadata.gz: 2eefd3a74f2982d981f510fbf51664a489edc5ca40bbfddc3be564fd8150646b
+  data.tar.gz: 8c5c168a439d41ab0c9020a6ebe6b43585cfdda7fc7135782b90df45ee3a5b56
 SHA512:
-  metadata.gz: 86640f197c38cda2906b649efa40dd208215708d221ff7ce1d57f6ed565ad0971dceda4b88a975b71d4f1e60a5b38796ed86f93e1b3e54d6e58c9cb11957c77e
-  data.tar.gz: d21c4ccc138554170fb1056ada38645fcb45dd34b74864ff1cc03e473c977f299f410a740ad7776a010026ad647ea13e97f7e4d1c14b58de806872c1f1a5e123
+  metadata.gz: 3cf930ae8e3aa73ddb806de461d0bad1a80a747c38c52c1737631d78a6fe92054f2323d8d9b5f943bf5b028619096232880a3cce6c05ae3abbacfa17f9df31c7
+  data.tar.gz: 477bfe4a00d3c304671730c2fb1be83804fc7452ce5cfd10f29e1883aa1b2c91e69fe3ca96fa08a9c0c06126292dafa248c1bc655f911ec7c5d8cf17a7395d49

data/.rspec

@@ -0,0 +1 @@
+--require spec_helper

data/.rubocop.yml

@@ -0,0 +1,4 @@
+inherit_from: "https://www.goodcop.style"
+
+AllCops:
+  TargetRubyVersion: 2.7

data/Gemfile

@@ -1,10 +1,22 @@
 # frozen_string_literal: true
 
 source "https://rubygems.org"
+git_source(:github) { |repo| "https://github.com/#{repo}.git" }
 
-# Specify your gem's dependencies in phlex.gemspec
 gemspec
 
-gem "rake", "~> 13.0"
+gem "rake"
 
-gem "minitest", "~> 5.0"
+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]
+gem "combustion", group: [:test]
+gem "benchmark-ips"
+gem "htmlbeautifier", group: [:docs]
+gem "benchmark-memory"
+gem "rubocop", require: false, github: "joeldrapper/rubocop", branch: "rubocop-user-agent"
+gem "syntax_suggest"

data/README.md

@@ -1,43 +1,27 @@
-# Phlex
+<a href="https://www.phlex.fun"><img alt="Phlex logo" src="phlex_logo.png" width="180" /></a>
 
-Welcome to your new gem! In this directory, you'll find the files you need to be able to package up your Ruby library into a gem. Put your Ruby code in the file `lib/phlex`. To experiment with that code, run `bin/console` for an interactive prompt.
+Phlex is a framework that lets you compose web views in pure Ruby.
 
-TODO: Delete this and the text above, and describe your gem
+### Documentation 📗
 
-## Installation
+Documentation can be found at [www.phlex.fun](https://www.phlex.fun).
 
-Add this line to your application's Gemfile:
+### Support ✋
 
-```ruby
-gem 'phlex'
-```
+If you run into any trouble, please [start a discussion](https://github.com/joeldrapper/phlex/discussions/new), or [open an issue](https://github.com/joeldrapper/phlex/issues/new) if you think you’ve found a bug.
 
-And then execute:
+### Community 🙌
 
-    $ bundle install
+Everyone interacting in Phlex codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/joeldrapper/phlex/blob/main/CODE_OF_CONDUCT.md).
 
-Or install it yourself as:
+### Sponsorship 💖
 
-    $ gem install phlex
+Maintaining a library like this is a lot of work. Phlex is being actively developed and maintained by **[Joel Drapper](https://github.com/sponsors/joeldrapper)**. If your company benefits from this work or is likely to benefit from it in the future, please consider sponsorship.
 
-## Usage
+### Security 👮
 
-TODO: Write usage instructions here
+If you’ve found a potential security issue, please email [joel+security@drapper.me](mailto:joel+security@drapper.me).
 
-## Development
+### Thanks 🙏
 
-After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake test` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
-
-To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
-
-## Contributing
-
-Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/phlex. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/[USERNAME]/phlex/blob/master/CODE_OF_CONDUCT.md).
-
-## License
-
-The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
-
-## Code of Conduct
-
-Everyone interacting in the Phlex project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/[USERNAME]/phlex/blob/master/CODE_OF_CONDUCT.md).
+Thanks [Logology](https://www.logology.co) for sponsoring our logo.

data/Rakefile

@@ -1,12 +1,10 @@
 # frozen_string_literal: true
 
 require "bundler/gem_tasks"
-require "rake/testtask"
 
-Rake::TestTask.new(:test) do |t|
-  t.libs << "test"
-  t.libs << "lib"
-  t.test_files = FileList["test/**/test_*.rb"]
+begin
+  require "rspec/core/rake_task"
+  RSpec::Core::RakeTask.new(:spec)
 end
 
-task default: :test
+task default: :spec

data/bench.rb

@@ -0,0 +1,14 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "phlex"
+require "benchmark/ips"
+
+require_relative "fixtures/page"
+require_relative "fixtures/layout"
+
+puts RUBY_DESCRIPTION
+
+Benchmark.ips do |x|
+  x.report("Page") { Example::Page.new.call }
+end

data/config.ru

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+require "rubygems"
+require "bundler"
+
+Bundler.require :default, :development
+
+Combustion.initialize! :all
+run Combustion::Application

data/docs/assets/application.css

@@ -0,0 +1,24 @@
+@tailwind base;
+@tailwind components;
+@tailwind utilities;
+
+.tabs input[type="radio"]:checked + label {
+  background: #f8f8f8;
+  z-index: 1;
+  margin-bottom: -1px;
+  padding-bottom: 1px;
+}
+
+.tabs input[type="radio"]:focus + label {
+  --tw-ring-offset-shadow: var(--tw-ring-inset) 0 0 0 var(--tw-ring-offset-width) var(--tw-ring-offset-color);
+  --tw-ring-shadow: var(--tw-ring-inset) 0 0 0 calc(3px + var(--tw-ring-offset-width)) var(--tw-ring-color);
+  box-shadow: var(--tw-ring-offset-shadow), var(--tw-ring-shadow), var(--tw-shadow, 0 0 #0000);
+}
+
+.tabs input[type="radio"]:checked + label + .tab {
+  display: block;
+}
+
+p {
+  @apply my-5
+}

data/docs/build.rb

@@ -0,0 +1,22 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: 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")
+
+PageBuilder.build_all
+
+system "npx tailwindcss -i ./docs/assets/application.css -o ./docs/dist/application.css"

data/docs/components/callout.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module Components
+  class Callout < Phlex::Component
+    def template(&block)
+      div(class: "rounded bg-orange-50 text-sm p-5 border border-orange-100", &block)
+    end
+  end
+end

data/docs/components/code_block.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Components
+  class CodeBlock < Phlex::Component
+    FORMATTER = Rouge::Formatters::HTML.new
+
+    def initialize(code, syntax:)
+      @code = code
+      @syntax = syntax
+    end
+
+    def template
+      pre(class: "highlight p-5 whitespace-pre-wrap bg-stone-50") {
+        raw FORMATTER.format(
+          lexer.lex(@code)
+        )
+      }
+    end
+
+    private
+
+    def lexer
+      Rouge::Lexer.find(@syntax)
+    end
+  end
+end

data/docs/components/example.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module Components
+  class Example < Phlex::Component
+    def initialize
+      @sandbox = Module.new
+    end
+
+    def template(&block)
+      render Tabs.new do |t|
+        @t = t
+        yield self
+      end
+    end
+
+    def tab(name, code)
+      @t.tab(name) do
+        render CodeBlock.new(code, syntax: :ruby)
+      end
+
+      @sandbox.instance_eval(code)
+    end
+
+    def execute(code)
+      output = @sandbox.instance_eval(code)
+
+      @t.tab("HTML Output") do
+        render CodeBlock.new(HtmlBeautifier.beautify(output), syntax: :html)
+      end
+    end
+  end
+end

data/docs/components/heading.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module Components
+  class Heading < Phlex::Component
+    def template(&block)
+      h2(class: "text-xl font-bold mt-10 mb-5", &block)
+    end
+  end
+end

data/docs/components/layout.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module Components
+  class Layout < Phlex::Component
+    register_element :style
+
+    def initialize(title:)
+      @title = title
+    end
+
+    def template(&block)
+      doctype
+
+      html do
+        head do
+          meta charset: "utf-8"
+          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 "Components", href: "/components" }
+                  li { a "Source code", href: "https://github.com/joeldrapper/phlex" }
+                end
+              end
+            end
+
+            main(class: "col-span-3", &block)
+
+            footer class: "text-sm text-right col-span-4 py-10"
+          end
+        end
+      end
+    end
+  end
+end

data/docs/components/markdown.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Components
+  class Markdown < Phlex::Component
+    class Render < Redcarpet::Render::HTML
+      def header(text, level)
+        case level
+        when 1
+          Title.new.call { text }
+        else
+          Heading.new.call { text }
+        end
+      end
+    end
+
+    MARKDOWN = Redcarpet::Markdown.new(Render.new, autolink: true, tables: true)
+
+    def initialize(content)
+      @content = content
+    end
+
+    def template
+      raw MARKDOWN.render(@content)
+    end
+  end
+end

data/docs/components/tabs/tab.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Components
+  class Tabs
+    class Tab < Phlex::Component
+      def initialize(name:, checked:)
+        @name = name
+        @checked = checked
+      end
+
+      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"
+
+        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)
+        end
+      end
+
+      def unique_identifier
+        @unique_identifier ||= SecureRandom.hex
+      end
+    end
+  end
+end

data/docs/components/tabs.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Components
+  class Tabs < Phlex::Component
+    def initialize
+      @index = 1
+    end
+
+    def template(&block)
+      div class: "tabs flex flex-wrap relative my-5", role: "tablist" do
+        content(&block)
+      end
+    end
+
+    def tab(name, &block)
+      render(Tab.new(name: name, checked: first?), &block)
+      @index += 1
+    end
+
+    def unique_identifier
+      @unique_identifier ||= SecureRandom.hex
+    end
+
+    private
+
+    def first?
+      @index == 1
+    end
+  end
+end

data/docs/components/title.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module Components
+  class Title < Phlex::Component
+    def template(&block)
+      h1(class: "text-2xl font-bold my-5", &block)
+    end
+  end
+end

data/docs/page_builder.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+class PageBuilder
+  ROOT = Pages::ApplicationPage
+
+  def self.build_all
+    ROOT.subclasses.each { |page| new(page).call }
+  end
+
+  def initialize(page)
+    @page = page
+  end
+
+  def call
+    FileUtils.mkdir_p(directory)
+    File.write(file, @page.new.call)
+  end
+
+  private
+
+  def file
+    "#{directory}/index.html"
+  end
+
+  def directory
+    if path == "index"
+      "#{__dir__}/dist"
+    else
+      "#{__dir__}/dist/#{path}"
+    end
+  end
+
+  def path
+    @page.name.downcase.split("::")[1..].join("/")
+  end
+end

data/docs/pages/application_page.rb

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

data/docs/pages/components.rb

@@ -0,0 +1,175 @@
+# frozen_string_literal: true
+
+module Pages
+  class Components < ApplicationPage
+    def template
+      render Layout.new(title: "Components in Phlex") do
+        render Markdown.new(<<~MD)
+          # Components
+
+          ## Yielding content
+
+          Your components can accept content as a block passed to the template method. You can capture the content block and pass it to the `content` method to yield it.
+        MD
+
+        render Example.new do |e|
+          e.tab "card.rb", <<~RUBY
+            class Card < Phlex::Component
+              def template(&)
+                article(class: "drop-shadow rounded p-5") {
+                  h1 "Amazing content!"
+                  content(&)
+                }
+              end
+            end
+          RUBY
+
+          e.execute "Card.new.call { 'Your content here.\n' }"
+        end
+
+        render Markdown.new(<<~MD)
+          ## Delegating content
+
+          Alternatively, you can pass the content down as an argument to another component or tag.
+        MD
+
+        render Example.new do |e|
+          e.tab "card.rb", <<~RUBY
+            class Card < Phlex::Component
+              def template(&)
+                article(class: "drop-shadow rounded p-5", &)
+              end
+            end
+          RUBY
+
+          e.execute "Card.new.call { 'Your content here.' }"
+        end
+
+        render Markdown.new(<<~MD)
+          ## Nested components
+
+          Components can render other components and optionally pass them content as a block.
+        MD
+
+        render Example.new do |e|
+          e.tab "example.rb", <<~RUBY
+            class Example < Phlex::Component
+              def template
+                render Card.new do
+                  h1 "Hello"
+                end
+              end
+            end
+          RUBY
+
+          e.tab "card.rb", <<~RUBY
+            class Card < Phlex::Component
+              def template(&)
+                article(class: "drop-shadow rounded p-5", &)
+              end
+            end
+          RUBY
+
+          e.execute "Example.new.call"
+        end
+
+        render Markdown.new(<<~MD)
+          If the block just wraps a string, the string is treated as _text content_.
+        MD
+
+        render Example.new do |e|
+          e.tab "example.rb", <<~RUBY
+            class Example < Phlex::Component
+              def template
+                render(Card.new) { "Hi" }
+              end
+            end
+          RUBY
+
+          e.tab "card.rb", <<~RUBY
+            class Card < Phlex::Component
+              def template(&)
+                article(class: "drop-shadow rounded p-5", &)
+              end
+            end
+          RUBY
+
+          e.execute "Example.new.call"
+        end
+
+        render Markdown.new(<<~MD)
+          ## Component attributes
+
+          Besides content, components can define attributes in an initializer, which can then be rendered in the template.
+        MD
+
+        render Example.new do |e|
+          e.tab "hello.rb", <<~RUBY
+            class Hello < Phlex::Component
+              def initialize(name:)
+                @name = name
+              end
+
+              def template
+                h1 "Hello \#{@name}!"
+              end
+            end
+          RUBY
+
+          e.tab "example.rb", <<~RUBY
+            class Example < Phlex::Component
+              def template
+                render Hello.new(name: "Joel")
+              end
+            end
+          RUBY
+
+          e.execute "Example.new.call"
+        end
+
+        render Markdown.new(<<~MD)
+          It’s usually a good idea to use instance variables directly rather than creating accessor methods for them. Otherwise it’s easy to run into naming conflicts. For example, your layout component might have the attribute `title`, to render into a `<title>` element in the document head. If you define `attr_accessor :title`, that would overwrite the `title` method for creating `<title>` elements.
+
+          ## Calculations with methods
+
+          Components are just Ruby classes, so you can perform calculations on component attributes by defining your own methods.
+        MD
+
+        render Example.new do |e|
+          e.tab "status.rb", <<~RUBY
+            class Status < Phlex::Component
+              def initialize(status:)
+                @status = status
+              end
+
+              def template
+                span status_emoji
+              end
+
+              private
+
+              def status_emoji
+                case @status
+                when :success
+                  "✅"
+                when :failure
+                  "❌"
+                end
+              end
+            end
+          RUBY
+
+          e.tab "example.rb", <<~RUBY
+            class Example < Phlex::Component
+              def template
+                render Status.new(status: :success)
+              end
+            end
+          RUBY
+
+          e.execute "Example.new.call"
+        end
+      end
+    end
+  end
+end