turbo_live 0.1.1 → 0.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: be283fc00ae2733bc0459e7c394e48b96359614de335b4d15cefec53a2134763
-  data.tar.gz: 7cc650231d0bc1537af64d27ebd748422b722a94be71108809d18024640472a8
+  metadata.gz: b117e175ea920117e11f0cd6c3bab5cafc0ca7c1860fb6b890c632a37efe1509
+  data.tar.gz: ca56b1155834dbeb85a29112a2f85b0901dbf14d61909587f698f45cfc25bb34
 SHA512:
-  metadata.gz: de85e08541c5fb65b2ecace8785f3688fc3b121f01a4a73991e7f25a21f935f7f4584913ca5c9a54ce99700da247ec1850d5898722fb44bd926a878d4eb84e33
-  data.tar.gz: e0d1b93943354bbde2cb5e0654966bb0be5f27bcc68d54b2772440e67ff70697742554b9dd116146c4146dcb52b657f092856dd4512fd0d2bd6a1fe5f2f1e644
+  metadata.gz: fce48eb8c3ae06f14fb6bb365004cf399c4f85d4f147776a7b05d6d7ec4b2833182fe6e4fd5d99781ef555daaad2d0bcd4b7b757378c645a7486138c2d356809
+  data.tar.gz: f0b1875a9143f5ca1ca218c05b1dbd3439ff7ebb13b8aabe9d72fcd58746fe41e8cde508f3a41f138ae3acfb25c66247594c1856397eaa89d2b9f6aaf170bea4

data/README.md

@@ -1,39 +1,230 @@
 # TurboLive
 
-TODO: Delete this and the text below, and describe your gem
-
-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/turbo_live`. To experiment with that code, run `bin/console` for an interactive prompt.
+TurboLive is a Ruby gem that enables the creation of async, progressively enhanced, live components for Ruby applications. It works seamlessly over both WebSockets and HTTPS, providing real-time interactivity with graceful degradation.
+
+## Table of Contents
+
+- [Installation](#installation)
+- [Setup](#setup)
+- [Usage](#usage)
+  - [Creating a Component](#creating-a-component)
+  - [Model State](#model-state)
+  - [View](#view)
+  - [Update](#update)
+- [Events](#events)
+  - [Manual Events](#manual-events)
+  - [Timed Events](#timed-events)
+- [Examples](#examples)
+- [Performance Considerations](#performance-considerations)
+- [Testing](#testing)
+- [Troubleshooting](#troubleshooting)
+- [Contributing](#contributing)
+- [Changelog](#changelog)
+- [License](#license)
 
 ## Installation
 
-TODO: Replace `UPDATE_WITH_YOUR_GEM_NAME_IMMEDIATELY_AFTER_RELEASE_TO_RUBYGEMS_ORG` with your gem name right after releasing it to RubyGems.org. Please do not do it earlier due to security reasons. Alternatively, replace this section with instructions to install your gem from git if you don't plan to release to RubyGems.org.
+Add it to your project with:
+
+```console
+bundle add 'turbo_live'
+```
 
-Install the gem and add to the application's Gemfile by executing:
+Or install it yourself using:
 
-```bash
-bundle add UPDATE_WITH_YOUR_GEM_NAME_IMMEDIATELY_AFTER_RELEASE_TO_RUBYGEMS_ORG
+```console
+gem install turbo_live
 ```
 
-If bundler is not being used to manage dependencies, install the gem by executing:
+### JavaScript
+
+TurboLive ships a JavaScript component that comes as an npm package. You can pin it with importmaps or install it as an npm package depending on your asset pipeline:
+
+For importmaps:
 
-```bash
-gem install UPDATE_WITH_YOUR_GEM_NAME_IMMEDIATELY_AFTER_RELEASE_TO_RUBYGEMS_ORG
+```console
+bin/importmap pin @radioactive-labs/turbo-live
+```
+
+For npm:
+
+```console
+npm install @radioactive-labs/turbo-live
+```
+
+## Setup
+
+### Stimulus Controller
+
+TurboLive uses a Stimulus controller to manage interactions. In your `app/javascript/controllers/index.js`:
+
+```diff
+import { application } from "controllers/application"
+import { eagerLoadControllersFrom } from "@hotwired/stimulus-loading"
++import * as turboLive from "@radioactive-labs/turbo-live"
+
+eagerLoadControllersFrom("controllers", application)
++turboLive.registerControllers(application)
+```
+
+### ActionCable (Optional)
+
+TurboLive supports WebSockets using ActionCable with automatic failover to HTTPS. If you have ActionCable set up and would like to benefit from better performance, you can set up the integration.
+
+In `app/javascript/channels/index.js`:
+
+```diff
++import consumer from "./consumer"
++import * as turboLive from "@radioactive-labs/turbo-live"
++
++turboLive.registerChannels(consumer)
+```
+
+Then in your `app/javascript/application.js`:
+
+```diff
+import "@hotwired/turbo-rails"
+import "controllers"
++import "channels"
 ```
 
 ## Usage
 
-TODO: Write usage instructions here
+A TurboLive component is a self-contained, interactive unit of a web application that can update in real-time without full page reloads. Components follow [The Elm Architecture](https://guide.elm-lang.org/architecture/) pattern.
+
+### Creating a Component
+
+To create a TurboLive component, inherit from `TurboLive::Component`:
+
+```ruby
+class MyComponent < TurboLive::Component
+  # Component logic goes here
+end
+```
+
+### Model State
+
+Define state variables using the `state` method:
+
+```ruby
+class MyComponent < TurboLive::Component
+  state :count, Integer do |value|
+    value || 0
+  end
+end
+```
+
+> Note: State variables can only be primitive objects and basic collections.
+
+### View
+
+Define the component's HTML structure in the `view` method:
 
-## Development
+```ruby
+def view
+  div do
+    button(**on(click: :increment)) { "+" }
+    span { count }
+    button(**on(click: :decrement)) { "-" }
+  end
+end
+```
+
+Components are [phlex](https://www.phlex.fun/) views, allowing you to write HTML in Ruby.
+
+### Update
 
-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.
+Handle events in the `update` method:
+
+```ruby
+def update(input)
+  case input
+  in [:increment]
+    self.count += 1
+  in [:decrement]
+    self.count -= 1
+  end
+end
+```
 
-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).
+## Events
+
+Events are transmitted to the server using the currently active transport (HTTP or WebSockets).
+
+### Manual Events
+
+Use the `on` method to set up manually triggered events:
+
+```ruby
+button(**on(click: :decrement)) { "-" }
+```
+
+You can also emit compound events that carry extra data:
+
+```ruby
+button(**on(click: [:change_value, 1])) { "+" }
+```
+
+> Note: Currently, only `:click` and `:change` events are supported.
+
+### Timed Events
+
+Use the `every` method to set up recurring events:
+
+```ruby
+def view
+  div do
+    h1 { countdown }
+    every(1000, :tick) if countdown > 0
+  end
+end
+```
+
+## Examples
+
+See the [/examples](/examples) folder in for detailed component examples including Counter, Countdown, Showcase and Tic-Tac-Toe components.
+
+## Performance Considerations
+
+- Use fine-grained components to minimize the amount of data transferred and rendered.
+- Implement debouncing for frequently triggered events.
+- Consider using background jobs for heavy computations to keep the UI responsive.
+
+## Testing
+
+TurboLive components can be tested using standard Rails testing tools. Here's a basic example:
+
+```ruby
+require "test_helper"
+
+class CounterComponentTest < ActiveSupport::TestCase
+  test "increments count" do
+    component = CounterComponent.new
+    assert_equal 0, component.count
+    component.update([:increment])
+    assert_equal 1, component.count
+  end
+end
+```
+
+## Troubleshooting
+
+Common issues and their solutions:
+
+1. **Component not updating**: Ensure that your `update` method is correctly handling the event and modifying the state.
+2. **WebSocket connection failing**: Check your ActionCable configuration and ensure that your server supports WebSocket connections.
+3. **JavaScript errors**: Make sure you've correctly set up the TurboLive JavaScript integration in your application.
+
+For more issues, please check our [FAQ](https://github.com/radioactive-labs/turbo_live/wiki/FAQ) or open an issue on GitHub.
 
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/turbo_live.
+We welcome contributions to TurboLive! Please see our [Contributing Guidelines](CONTRIBUTING.md) for more information on how to get started.
+
+## Changelog
+
+See the [CHANGELOG.md](CHANGELOG.md) file for details on each release.
 
 ## License
 
-The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/examples/countdown_component.rb

@@ -0,0 +1,23 @@
+class CountdownComponent < TurboLive::Component
+  state :countdown, Integer
+
+  def view
+    div do
+      if countdown.nil?
+        button(**on(click: :start)) { "Start!" }
+      else
+        h1 { countdown }
+        every(1000, :countdown) if countdown >= 1
+      end
+    end
+  end
+
+  def update(input)
+    case input
+    in [:countdown]
+      self.countdown -= 1
+    in [:start]
+      self.countdown = 1000
+    end
+  end
+end

data/examples/counter_component.rb

@@ -0,0 +1,26 @@
+class CounterComponent < TurboLive::Component
+  state :count, Integer do |value|
+    value || 0
+  end
+
+  def view
+    div do
+      button(**on(click: :increment)) { "+" }
+      span { " Clicked: #{count} " }
+      button(**on(click: :decrement)) { "-" }
+      plain " "
+      button(**on(click: :reset)) { "Reset" }
+    end
+  end
+
+  def update(input)
+    case input
+    in [:decrement]
+      self.count -= 1
+    in [:increment]
+      self.count += 1
+    in [:reset]
+      self.count = 0
+    end
+  end
+end

data/examples/showcase_component.rb

@@ -0,0 +1,41 @@
+class ShowcaseComponent < TurboLive::Component
+  state :component, Symbol
+
+  def view
+    div class: "container" do
+      div class: "left-column" do
+        h2 { "Components" }
+        ul do
+          li { button(**on(click: [:change_component, :counter])) { "Counter" } }
+          li { button(**on(click: [:change_component, :countdown])) { "Countdown" } }
+          li { button(**on(click: [:change_component, :tic_tac_toe])) { "TicTacToe" } }
+        end
+      end
+      div class: "right-column" do
+        div class: "card" do
+          render selected_component.new
+        end
+      end
+    end
+  end
+
+  def update(input)
+    case input
+    in [[:change_component, component]]
+      self.component = component
+    end
+  end
+
+  private
+
+  def selected_component
+    case component
+    when :countdown
+      CountdownComponent
+    when :tic_tac_toe
+      TicTacToeComponent
+    else
+      CounterComponent
+    end
+  end
+end

data/examples/tic_tac_toe_component.rb

@@ -0,0 +1,93 @@
+class TicTacToeComponent < TurboLive::Component
+  state :board, Array do |value|
+    value || Array.new(9, nil)
+  end
+
+  state :current_player, String do |value|
+    value || "X"
+  end
+
+  state :winner, String do |value|
+    value || nil
+  end
+
+  def view
+    div(class: "tic-tac-toe-container") do
+      render_board
+      render_status
+      render_reset_button
+    end
+  end
+
+  def render_board
+    div(class: "board") do
+      board.each_with_index do |cell, index|
+        button(
+          class: "cell",
+          **on(click: [:make_move, index]),
+          disabled: cell || winner,
+          "data-value": cell
+        ) { cell || "&nbsp;".html_safe }
+      end
+    end
+  end
+
+  def render_status
+    div(class: "status") do
+      if winner
+        "Winner: #{winner}"
+      elsif board.compact.length == 9
+        "It's a draw!"
+      else
+        "Current player: #{current_player}"
+      end
+    end
+  end
+
+  def render_reset_button
+    button(**on(click: :reset_game)) { "Reset Game" }
+  end
+
+  def update(input)
+    case input
+    in [[:make_move, index]]
+      make_move(index)
+    in [:reset_game]
+      reset_game
+    end
+  end
+
+  private
+
+  def make_move(index)
+    return if board[index] || winner
+
+    new_board = board.dup
+    new_board[index] = current_player
+    self.board = new_board
+    self.winner = check_winner
+    self.current_player = (current_player == "X") ? "O" : "X" unless winner
+  end
+
+  def check_winner
+    winning_combinations = [
+      [0, 1, 2], [3, 4, 5], [6, 7, 8], # Rows
+      [0, 3, 6], [1, 4, 7], [2, 5, 8], # Columns
+      [0, 4, 8], [2, 4, 6]             # Diagonals
+    ]
+
+    winning_combinations.each do |combo|
+      if board[combo[0]] && board[combo[0]] == board[combo[1]] && board[combo[0]] == board[combo[2]]
+        return board[combo[0]]
+      end
+    end
+
+    nil
+  end
+
+  def reset_game
+    self.board = Array.new(9, nil)
+    self.current_player = "X"
+    self.winner = nil
+  end
+end

data/lib/turbo_live/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module TurboLive
-  VERSION = "0.1.1"
+  VERSION = "0.1.2"
 end

data/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "@radioactive-labs/turbo-live",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@radioactive-labs/turbo-live",
-      "version": "0.1.1",
+      "version": "0.1.2",
       "license": "MIT",
       "dependencies": {
         "@hotwired/stimulus": "^3.2.2",

data/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@radioactive-labs/turbo-live",
-  "version": "0.1.1",
-  "description": "Stateless live components for Ruby applications",
+  "version": "0.1.2",
+  "description": "Async, progressively enhanced, live components for Ruby applications that work over Websockets and HTTP.",
   "type": "module",
   "main": "src/js/core.js",
   "files": [

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: turbo_live
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.1.2
 platform: ruby
 authors:
 - TheDumbTechGuy
@@ -38,8 +38,8 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
-description: Stateless live components for Ruby applications that work over Websockets
-  and HTTP.
+description: Async, progressively enhanced, live components for Ruby applications
+  that work over Websockets and HTTP.
 email:
 - sfroelich01@gmail.com
 executables: []
@@ -55,6 +55,10 @@ files:
 - app/channels/components_channel.rb
 - app/controllers/turbo_live/components_controller.rb
 - config/routes.rb
+- examples/countdown_component.rb
+- examples/counter_component.rb
+- examples/showcase_component.rb
+- examples/tic_tac_toe_component.rb
 - lib/turbo_live.rb
 - lib/turbo_live/component.rb
 - lib/turbo_live/engine.rb
@@ -95,5 +99,5 @@ requirements: []
 rubygems_version: 3.5.16
 signing_key:
 specification_version: 4
-summary: Stateless live components for Ruby applications
+summary: Async, progressively enhanced, live components for Ruby applications
 test_files: []