Clapton

Clapton is a Ruby on Rails gem for building web apps with pure Ruby only (no JavaScript and no HTML templates).

Stack

Ruby on Rails
Action Cable (WebSocket)
Ruby2JS (for compiling Ruby to JavaScript)
Morphdom
importmap

Installation

Add this line to your application's Gemfile:

gem 'clapton'

And then execute:

$ bundle install

Usage

To use a Clapton component in your view:

# app/components/task_list_component.rb
class TaskListComponent < Clapton::Component
  def render
    div = c(:div)
    @state.tasks.each do |task|
      div.add(TaskItemComponent.new(id: task[:id], title: task[:title], due: task[:due], done: task[:done]))
    end
    btn = c(:button)
    btn.add(c(:text, "Add Task"))
    btn.add_action(:click, :TaskListState, :add_task)
    div.add(btn)
  end
end

# app/components/task_item_component.rb
class TaskItemComponent < Clapton::Component
  def render
    div = c(:div)
    btn = c(:button)
    btn.add(c(:text, @state.done ? "✅" : "🟩"))
    btn.add_action(:click, :TaskListState, :toggle_done)

    tf = c(:input, @state, :title)
    tf.add_action(:input, :TaskListState, :update_title)

    dt = c(:datetime, @state, :due)
    dt.add_action(:input, :TaskListState, :update_due)

    div.add(btn).add(tf).add(dt)
  end
end

# app/states/task_list_state.rb
class TaskListState < Clapton::State
  attribute :tasks

  def add_task(params)
    task = Task.create(title: "New Task", due: Date.today, done: false)
    self.tasks << { id: task.id, title: task.title, due: task.due, done: task.done }
  end

  def toggle_done(params)
    task = Task.find(params[:id])
    task.update(done: !params[:done])
    self.tasks.find { |t| t[:id] == params[:id] }[:done] = task.done
  end

  def update_title(params)
    task = Task.find(params[:id])
    task.update(title: params[:title])
    self.tasks.find { |t| t[:id] == params[:id] }[:title] = task.title
  end

  def update_due(params)
    task = Task.find(params[:id])
    task.update(due: params[:due])
    self.tasks.find { |t| t[:id] == params[:id] }[:due] = task.due
  end
end

# app/states/task_item_state.rb
class TaskItemState < Clapton::State
  attribute :id
  attribute :title
  attribute :due
  attribute :done
end

# app/controllers/tasks_controller.rb
class TasksController < ApplicationController
  def index
    @tasks = Task.all
    @components = [
      [:TaskListComponent, { tasks: @tasks.map { |task| { id: task.id, title: task.title, due: task.due, done: task.done } } }]
    ]
  end
end

# app/views/layouts/application.html.erb
<%= clapton_javascript_tag %>

# app/views/tasks/index.html.erb
<%= clapton_tag %>

Make sure to include the necessary route in your config/routes.rb:

mount Clapton::Engine => "/clapton"

Component rendering

<%= clapton_component_tag(
  :TaskListComponent,
  {
    tasks: @tasks.map { |task| { id: task.id, title: task.title, due: task.due, done: task.done } }
  }
) %>

Generate Component and State

rails generate clapton TaskList

After running the generator, you will see the following files:

app/components/task_list_component.rb
app/states/task_list_state.rb

Special Event

render

The render event is a special event that is triggered when the component is rendered.

# app/components/task_list_component.rb
class TaskListComponent < Clapton::Component
  def render
    # ...
    div = c(:div)
    div.add_action(:render, :TaskListState, :add_empty_task, debounce: 500)
  end
end

Effect

The effect method is a method that is triggered when the state is changed.

# app/components/task_list_component.rb
class TaskListComponent < Clapton::Component
  effect [:tasks] do |state|
    puts state[:tasks]
  end
end

If dependencies are not specified, the effect will be triggered on the first render.

# app/components/video_player_component.rb
class VideoPlayerComponent < Clapton::Component
  effect [] do
    puts "First render"
  end
end

Streaming

Clapton supports streaming.

# app/states/chat_state.rb
class ChatState < Clapton::State
  attribute :messages

  def send(params)
    self.messages << { role: "user", content: params[:content] }
    yield continue: true # Continue the streaming

    client = OpenAI::Client.new(
      access_token: ENV.fetch("OPENAI_ACCESS_TOKEN"),
      log_errors: true
    )
    self.messages << { role: "assistant", content: "" }
    client.chat(
      parameters: {
        model: "gpt-4o-mini",
        messages: messages,
        stream: proc do |chunk, _bytesize|
          if chunk.dig("choices", 0, "finish_reason") == "stop"
            yield continue: false # Stop the streaming
          end

          self.messages.last[:content] << chunk.dig("choices", 0, "delta", "content")
          yield continue: true
        end
      }
    )
  end
end

Optional

Action Cable

Clapton uses Action Cable to broadcast state changes to the client. If you want to identify the user, you can set the current_user in the connection.

# app/channels/application_cable/connection.rb
module ApplicationCable
  class Connection < ActionCable::Connection::Base
    identified_by :current_user

    def connect
      self.current_user = find_verified_user
    end

    private

    def find_verified_user
      if verified_user = User.find_by(id: cookies.signed[:user_id])
        verified_user
      else
        reject_unauthorized_connection
      end
    end
  end
end

Using with importmap-rails

Use clapton_javascript_tag instead of javascript_importmap_tags.

- <%= javascript_importmap_tags %>
+ <%= clapton_javascript_tag %>

Events

clapton:render

The clapton:render event is a custom event that is triggered when the component is rendered.

document.addEventListener("clapton:render", () => {
  console.log("clapton:render");
});

Testing

RSpec

# spec/spec_helper.rb
require "clapton/test_helper/rspec"

RSpec.configure do |config|
  config.include Clapton::TestHelper::RSpec, type: :component
end

# spec/components/task_list_component_spec.rb

describe "TaskListComponent", type: :component do
  it "renders" do
    render_component("TaskListComponent", tasks: [{ id: 1, title: "Task 1", done: false, due: Time.current }])
    # You can use Capybara matchers here
    expect(page).to have_selector("input[type='text']")
  end
end

Minitest

# test/test_helper.rb
require "clapton/test_helper/minitest"

class ActiveSupport::TestCase
  include Clapton::TestHelper::Minitest
end

# test/components/task_list_component_test.rb
class TaskListComponentTest < ActiveSupport::TestCase
  test "renders" do
    render_component("TaskListComponent", tasks: [{ id: 1, title: "Task 1", done: false, due: Time.current }])
    # You can use Capybara matchers here
    assert_select "input[type='text']"
  end
end

Deployment

Run bundle exec rake clapton:compile to compile the components.

app/components is codes that are compiled to JavaScript. So, you need to ignore the directory from autoloading.

# config/application.rb

Rails.autoloaders.main.ignore(Rails.root.join("app/components"))

Development

After checking out the repo, run bin/setup to install dependencies. Then, run bin/dev to start the development server.

Testing

Run bundle exec rake test to run the test suite.

Run cd test/dummy && bundle exec rake test to run the test suite for the dummy app.

Run cd test/dummy && bundle exec rspec to run the test suite for the dummy app with RSpec.

Run cd lib/clapton/javascripts && npm run test to run the test suite for the JavaScript part.

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/kawakamimoeki/clapton. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the code of conduct.

License

The gem is available as open source under the terms of the MIT License.

clapton

Runtime

Clapton

Stack

Installation

Usage

Component rendering

Generate Component and State

Special Event

render

Effect

Streaming

Optional

Action Cable

Using with importmap-rails

Events

clapton:render

Testing

RSpec

Minitest

Deployment

Development

Testing

Contributing

License