rbexy 2.0.0.beta8 → 2.0.0.rc2

data/README.md

@@ -2,6 +2,19 @@
 
 [![Build Status](https://travis-ci.org/patbenatar/rbexy.svg?branch=master)](https://travis-ci.org/patbenatar/rbexy)
 
+* [Getting Started](#getting-started-with-rails)
+* [Template Syntax](#template-syntax)
+* [Components](#components)
+  * [`Rbexy::Component`](#rbexycomponent)
+  * [Usage with any component library](#usage-with-any-component-library)
+* [Fragment caching in Rails](#fragment-caching-in-rails)
+* [Advanced](#advanced)
+  * [Component resolution](#component-resolution)
+  * [AST Transforms](#ast-transforms)
+  * [Usage outside of Rails](#usage-outside-of-rails)
+
+## Manifesto
+
 Love JSX and component-based frontends, but sick of paying the costs of SPA development? Rbexy brings the elegance of JSX—operating on HTML elements and custom components with an interchangeable syntax—to the world of Rails server-rendered apps.
 
 Combine this with CSS Modules in your Webpacker PostCSS pipeline and you'll have a first-class frontend development experience while maintaining the development efficiency of Rails.
@@ -85,78 +98,25 @@ Add a controller, action, route, and `rbx` view like `app/views/hello_worlds/ind
 </HelloWorld>
 ```
 
-_Or you can render Rbexy components from ERB with `<%= HelloWorldComponent.new(self, name: "Nick").render %>`_
-
 Fire up `rails s`, navigate to your route, and you should see Rbexy in action!
 
 ## Template Syntax
 
-### Text
-
-You can put arbitrary strings anywhere.
-
-At the root:
+You can use Ruby code within brackets:
 
 ```jsx
-Hello world
+<p class={@dynamic_class}>
+  Hello {"world".upcase}
+</p>
 ```
 
-Inside tags:
-
-```jsx
-<p>Hello world</p>
-```
-
-As attributes:
-
-```jsx
-<div class="myClass"></div>
-```
-
-### Comments
-
-Start a line with `#` to leave a comment:
-
-```jsx
-# Comments can be at the root
-<div>
-  # Or within tags
-  # spanning multiple lines
-  <h1>Hello world</h1>
-</div>
-```
-
-### Expressions
-
-You can put ruby code anywhere that you would put text, just wrap it in `{ ... }`
-
-At the root:
-
-```jsx
-{"hello world".upcase}
-```
-
-Inside a sentence:
-
-```jsx
-Hello {"world".upcase}
-```
-
-Inside tags:
-
-```jsx
-<p>{"hello world".upcase}</p>
-```
-
-As attributes:
+You can splat a hash into attributes:
 
 ```jsx
-<p class={@dynamic_class}>Hello world</p>
+<div {**{class: "myClass"}} {**@more_attrs}></div>
 ```
 
-#### Tags within expressions
-
-To conditionalize your template:
+You can use HTML or component tags within expressions. e.g. to conditionalize a template:
 
 ```jsx
 <div>
@@ -165,7 +125,7 @@ To conditionalize your template:
 </div>
 ```
 
-Loops:
+Or in loops:
 
 ```jsx
 <ul>
@@ -181,7 +141,7 @@ Blocks:
 end}
 ```
 
-As an attribute:
+Pass a tag to a component as an attribute:
 
 ```jsx
 <Hero title={<h1>Hello World</h1>}>
@@ -189,7 +149,7 @@ As an attribute:
 </Hero>
 ```
 
-Pass a lambda to a prop, that when called returns a tag:
+Or pass a lambda as an attribute, that when called returns a tag:
 
 ```jsx
 <Hero title={-> { <h1>Hello World</h1> }}>
@@ -207,70 +167,15 @@ _Note that when using tags inside blocks, the block must evaluate to a single ro
 -> { <i>Hello</i> World }
 ```
 
-### Tags
-
-You can put standard HTML tags anywhere.
-
-At the root:
-
-```jsx
-<h1>Hello world</h1>
-```
-
-As children:
-
-```jsx
-<div>
-  <h1>Hello world</h1>
-</div>
-```
-
-As siblings with other tags:
-
-```jsx
-<div>
-  <h1>Hello world</h1>
-  <p>Welcome to rbexy</p>
-</div>
-```
-
-As siblings with text and expressions:
-
-```jsx
-<h1>Hello world</h1>
-{an_expression}
-Some arbitrary text
-```
-
-Self-closing tags:
-
-```jsx
-<input type="text" />
-```
-
-#### Attributes
-
-Text and expressions can be provided as attributes:
-
-```jsx
-<div class="myClass" id={dynamic_id}></div>
-```
-
-Value-less attributes are allowed:
-
-```jsx
-<input type="submit" disabled>
-```
-
-You can splat a hash into attributes:
+Start a line with `#` to leave a comment:
 
 ```jsx
-<div {**{ class: "myClass" }} {**@more_attrs}></div>
+# Private note to self that won't be rendered in the final HTML
 ```
 
-## Custom components
+## Components
 
-You can use custom components alongside standard HTML tags:
+You can use Ruby classes as components alongside standard HTML tags:
 
 ```jsx
 <div>
@@ -281,6 +186,8 @@ You can use custom components alongside standard HTML tags:
 </div>
 ```
 
+By default, Rbexy will resolve `PageHeader` to a Ruby class called `PageHeaderComponent` and render it with the view context, attributes, and its children: `PageHeaderComponent.new(self, title: "Welcome").render_in(self, &block)`. This behavior is customizable, see "Component resolution" below.
+
 ### `Rbexy::Component`
 
 We ship with a component superclass that integrates nicely with Rails' ActionView and the controller rendering context. You can use it to easily implement custom components in your Rails app:
@@ -301,13 +208,11 @@ By default, we'll look for a template file in the same directory as the class an
 <h1>{@title}</h1>
 ```
 
-You can call this component from another `.rbx` template file (`<PageHeader title="Hello" />`)—either one rendered by another component class or a Rails view file like `app/views/products/index.rbx`. Or you can call it from ERB (or any other template language) like `PageHeaderComponent.new(self, title: "Hello").render_in`.
-
-Your components and their templates run in the same context as traditional Rails views, so you have access to all of the view helpers you're used to as well as any custom helpers you've defined in `app/helpers/`.
+Your components and their templates run in the same context as traditional Rails views, so you have access to all of the view helpers you're used to as well as any custom helpers you've defined in `app/helpers/` or via `helper_method` in your controller.
 
 #### Template-less components
 
-If you'd prefer to render your components entirely from Ruby, e.g. using Rails `tag` helpers, you can do so with `#call`:
+If you'd prefer to render your components entirely from Ruby, you can do so by implementing `#call`:
 
 ```ruby
 class PageHeaderComponent < Rbexy::Component
@@ -361,57 +266,115 @@ class TextFieldComponent < Rbexy::Component
 end
 ```
 
-### `ViewComponent`
+#### Usage with ERB
 
-Using Github's view_component library? Rbexy ships with a provider that'll resolve your RBX tags like `<Button />` to their corresponding `ButtonComponent < ViewComponent::Base` components.
+We recommend using `Rbexy::Component` with the rbx template language, but if you prefer ERB... a component's template can be `.html.erb` and you  can render a component from ERB like so:
 
-```ruby
-require "rbexy/component_providers/view_component_provider"
+Rails 6.1:
+
+```erb
+<%= render PageHeaderComponent.new(self, title: "Welcome") do %>
+  <p>Children...</p>
+<% end >
+```
+
+Rails 6.0 or earlier:
+
+```erb
+<%= PageHeaderComponent.new(self, title: "Welcome").render_in(self) %>
+```
+
+### Usage with any component library
 
+You can use the rbx template language with other component libraries like Github's view_component. You just need to tell Rbexy how to render the component:
+
+```ruby
+# config/initializers/rbexy.rb
 Rbexy.configure do |config|
-  config.component_provider = Rbexy::ComponentProviders::ViewComponentProvider.new
+  config.component_rendering_templates = {
+    children: "{capture{%{children}}}",
+    component: "::%{component_class}.new(%{view_context},%{kwargs}).render_in%{children_block}"
+  }
 end
 ```
 
-### Other types of components
+## Fragment caching in Rails
 
-You just need to tell rbexy how to resolve your custom component classes as it encounters them while evaluating your template by implementing a ComponentProvider:
+`.rbx` templates integrate with Rails fragment caching, automatically cachebusting when the template or its render dependencies change.
 
-```ruby
-class MyComponentProvider
-  def match?(name)
-    # Return true if the given tag name matches one of your custom components
-  end
+If you're using `Rbexy::Component`, you can further benefit from component cachebusting where the fragment cache will be busted if any dependent component's template _or_ class definition changes.
 
-  def render(context, name, **attrs, &block)
-    # Instantiate and render your custom component for the given name, using
-    # the render context as needed (e.g. ActionView in Rails)
-  end
-end
+And you can use `<Rbexy.Cache>`, a convenient wrapper for the Rails fragment cache:
+
+```rbx
+<Rbexy.Cache key={...}>
+  <p>Fragment here...</p>
+  <MyButton />
+</Rbexy.Cache>
+```
 
-# Register your component provider with Rbexy
+## Advanced
+
+### Component resolution
+
+By default, Rbexy resolves component tags to Ruby classes named `#{tag}Component`, e.g.:
+
+* `<PageHeader />` => `PageHeaderComponent`
+* `<Admin.Button />` => `Admin::ButtonComponent`
+
+You can customize this behavior by providing a custom resolver:
+
+```ruby
+# config/initializers/rbexy.rb
 Rbexy.configure do |config|
-  config.component_provider = MyComponentProvider.new
+  config.element_resolver = MyResolver.new
 end
 ```
 
-Or in Rails you can customize the component provider just for a controller:
+Where `MyResolver` implements the following API:
+
+* `component?(name: string, template: Rbexy::Template) => Boolean`
+* `component_class(name: string, template: Rbexy::Template) => T`
+
+See `lib/rbexy/component_resolver.rb` for an example.
+
+#### Auto-namespacing
+
+Want to namespace your components but sick of typing `Admin.` in front of every component call? Rbexy's default `ComponentResolver` implementation has an option for that:
 
 ```ruby
-class ThingsController < ApplicationController
-  def rbexy_component_provider
-    MyComponentProvider.new
-  end
+# config/initializers/rbexy.rb
+Rbexy.configure do |config|
+  config.element_resolver.component_namespaces = {
+    Rails.root.join("app", "views", "admin") => %w[Admin],
+    Rails.root.join("app", "components", "admin") => %w[Admin]
+  }
 end
 ```
 
-See `lib/rbexy/component_providers/` for example implementations.
+Now any calls to `<Button>` made from `.rbx` views within `app/views/admin/` or from component templates within `app/components/admin/` will first check for `Admin::ButtonComponent` before `ButtonComponent`.
 
-## Usage outside of Rails
+### AST Transforms
+
+You can hook into Rbexy's compilation process to mutate the abstract syntax tree. This is both useful and dangerous, so use with caution.
+
+An example use case is automatically scoping CSS class names if you're using something like CSS Modules. Here's an oversimplified example of this:
+
+```ruby
+# config/initializers/rbexy.rb
+Rbexy.configure do |config|
+  config.transforms.register(Rbexy::Nodes::HTMLAttr) do |node, context|
+    if node.name == "class"
+      class_list = node.value.split(" ")
+      node.value.content = scope_names(class_list, scope: context.template.identifier)
+    end
+  end
+end
+```
 
-Rbexy compiles your template into ruby code, which you can then execute in any context you like, so long as a tag builder is available at `#rbexy_tag`. We provide a built-in runtime leveraging ActionView's `tag` helper that you can extend from or build your own:
+### Usage outside of Rails
 
-Subclass to add methods and instance variables that you'd like to make available to your template.
+Rbexy compiles your template into ruby code, which you can then execute in any context you like. Subclass `Rbexy::Runtime` to add methods and instance variables that you'd like to make available to your template.
 
 ```ruby
 class MyRuntime < Rbexy::Runtime
@@ -428,50 +391,42 @@ end
 Rbexy.evaluate("<p class={a_method}>{@an_ivar}</p>", MyRuntime.new)
 ```
 
-If you're using custom components, inject a ComponentProvider (see "Custom components" for an example implementation):
-
-```ruby
-class MyRuntime < Rbexy::Runtime
-  def initialize(component_provider)
-    super(component_provider)
-    @ivar_val = "ivar value"
-  end
-
-  def splat_attrs
-    {
-      key1: "val1",
-      key2: "val2"
-    }
-  end
-end
+## Development
 
-Rbexy.evaluate(
-  "<Forms.TextField /><Button prop1=\"val1\" prop2={true && \"val2\">Submit</Button>",
-  MyRuntime.new(MyComponentProvider.new)
-)
+```
+docker-compose build
+docker-compose run rbexy bin/test
 ```
 
-Or implement your own runtime, so long as it conforms to the API:
+Or auto-run tests with guard if you prefer:
 
-* `#rbexy_tag` that returns a tag builder conforming to the API of `ActionView::Helpers::TagHelpers::TagBuilder`
-* `#evaluate(code)` that evals the given string of ruby code
+```
+docker-compose run rbexy guard
+```
 
-## Development
+If you want to run against the supported versions of Rails, use
+Appraisal:
 
 ```
-docker-compose build
-docker-compose run rbexy rspec
+docker-compose run rbexy appraisal bin/test
 ```
 
-Or auto-run tests with guard if you prefer:
+## Debugging TemplatePath methods being called
+When a new version of Rails is released, we need to check what methods are being
+called on `Rbexy::Component::TemplatePath` to make sure we always return
+a TemplatePath, not a string due to how we handle `TemplatePath`s
+internally.
+
+To list all methods being called, enable `RBEXY_TEMPLATE_PATH_DEBUG` and
+run tests:
 
 ```
-docker-compose run rbexy guard
+docker-compose run -e RBEXY_TEMPLATE_PATH_DEBUG=1 rbexy appraisal bin/test
 ```
 
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/rbexy. 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]/rbexy/blob/master/CODE_OF_CONDUCT.md).
+Bug reports and pull requests are welcome on GitHub at https://github.com/patbenatar/rbexy. 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/patbenatar/rbexy/blob/master/CODE_OF_CONDUCT.md).
 
 ## License
 
@@ -479,4 +434,4 @@ The gem is available as open source under the terms of the [MIT License](https:/
 
 ## Code of Conduct
 
-Everyone interacting in the Rbexy project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/[USERNAME]/rbexy/blob/master/CODE_OF_CONDUCT.md).
+Everyone interacting in the Rbexy project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/patbenatar/rbexy/blob/master/CODE_OF_CONDUCT.md).

data/bin/test

@@ -0,0 +1,43 @@
+#!/usr/bin/env bash
+
+declare -i RESULT=0
+
+echo "Running main suite..."
+
+bundle exec rspec
+RESULT+=$?
+
+echo "Running initial caching specs to test cold cache behavior..."
+
+bundle exec rspec spec/integration/caching/before_changes_spec.rb
+RESULT+=$?
+
+echo "Making template source changes to allow testing of cache-busting..."
+
+templates=(
+  "spec/dummy/app/views/caching/inline.rbx"
+  "spec/dummy/app/components/cached_thing_component.rbx"
+  "spec/dummy/app/components/cached_class_thing_component.rb"
+  "spec/dummy/app/components/cached_thing_call_component.rb"
+  "spec/dummy/app/views/caching/_partial_render_partial.rbx"
+)
+for i in "${templates[@]}"
+do
+  mv $i $i.original
+  mv $i.changed $i
+done
+
+echo "Running subsequent caching specs to test cache-busting of warm cache..."
+
+bundle exec rspec spec/integration/caching/after_changes_spec.rb
+RESULT+=$?
+
+echo "Cleaning up..."
+
+for i in "${templates[@]}"
+do
+  mv $i $i.changed
+  mv $i.original $i
+done
+
+exit $RESULT

data/gemfiles/.bundle/config

@@ -0,0 +1,2 @@
+---
+BUNDLE_RETRY: "1"

data/gemfiles/rails_6_1.gemfile

@@ -0,0 +1,8 @@
+# This file was generated by Appraisal
+
+source "https://rubygems.org"
+
+gem "rails", "~> 6.1.4"
+gem "net-smtp", require: false
+
+gemspec path: "../"