opal_stimulus 0.1.8 → 0.1.9

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2e85c862c3473c9962b0e1e9be1887e208648a8cd67301f6ac03bf7da0bf4257
-  data.tar.gz: 60f54f0a320aa035c476462dae509e9c3758e506392dc9a78e873f4641f18573
+  metadata.gz: ed5dba8c0e0b7d1f75d37a60d417f2e2af188a9adf0b249b9a55af55d67e0933
+  data.tar.gz: '0970f685ca56fb9d945615e53f0986bc1688c933c099aa550072fd11c1d15a9f'
 SHA512:
-  metadata.gz: 10a698fdc0764eebb12942136946e074feca1f4d1fa1afd2ed8722ed84d80451b6bde4f84a853a77d3edbbb2436b68fcb9a56e2e3d767dffd5fb2eace477bb86
-  data.tar.gz: 4b618ed01261320c78212f3a8f625aa92f4ee781cc343c19fb35510879e797423727588a3c4bf4981bf906d1dc2310df4a86b78f53ffd05b82e4ad7006d90a38
+  metadata.gz: 30354047b38f078cd5d809b608011c6e26a17d7f3953d6ba20824f33cf5f5cca2673b2d9a1eed1bb6fce9a9c2a4d9783537bc52695c156b1cef7ad982ed570bb
+  data.tar.gz: 715f6366c20a94eb653fa66ba322baced833f604cb49ae1b2202f0f32563cfddbfeb1e0787e0f511dde49659939d1e876eb884777d166a28658063eb9d7fece6

data/CHANGELOG.md

@@ -47,3 +47,8 @@
 ## [0.1.8] - 2025-08-27
 
 - Improve installation on Rails tests
+
+## [0.1.9] - 2025-11-14
+
+- Revise README for Opal Stimulus by @elia
+- Change README

data/README.md

@@ -1,45 +1,46 @@
 # Opal Stimulus for Rails
 
-**Opal Stimulus** is a Stimulus wrapper made with Opal (a source-to-source Ruby to JavaScript compiler) that allows you to write Stimulus controllers in Ruby instead of JavaScript (It works only with Rails >= 7.2 and < 8.0.3).
+Write your [Stimulus](https://stimulus.hotwired.dev/) controllers in Ruby instead of JavaScript! 🎉
+
+**Opal Stimulus** uses the [Opal Ruby-to-JavaScript compiler](https://opalrb.com/) to bring the elegance of Ruby to your frontend controllers. If you love Ruby and prefer its syntax over JavaScript, this gem is for you.
+
+**Compatibility:** Rails >= 7.2
 
 [![Ruby](https://github.com/josephschito/opal_stimulus/actions/workflows/main.yml/badge.svg)](https://github.com/josephschito/opal_stimulus/actions/workflows/main.yml)
 
-## Installation
+## Click here to watch the walkthrough! 👇
 
-Add this line to your Gemfile:
+[<img width="640" height="360" alt="opal stimulus" src="https://github.com/user-attachments/assets/3eba6d3f-c62a-4faa-b918-5181ec9e2efc" />](https://www.youtube.com/watch?v=YyaVUUMq7po)
 
-```ruby
-gem 'opal_stimulus'
-```
+## Quick Start
 
-Execute:
+Add to your Rails app and get started in seconds:
 
 ```bash
-bundle install
+bundle add opal_stimulus
 rails opal_stimulus:install
+bin/dev
 ```
 
-Start application:
+Generate your first Ruby controller:
 
 ```bash
-bin/dev
+bin/rails generate opal_stimulus hello
 ```
 
-Create a new controller:
+This creates `app/opal/controllers/hello_controller.rb`. If you have an existing JavaScript controller, you can remove it:
 
 ```bash
-bin/rails generate opal_stimulus hello
+bin/rails destroy stimulus hello  # removes app/javascript/controllers/hello_controller.js
 ```
-This command will create `app/opal/controllers/hello_controller.rb`
 
-## Basic Example
+## Example: Hello World
 
-Here's a Hello World example with OpalStimulus. Compare with the [original JavaScript example](https://stimulus.hotwired.dev/#:~:text=%2F%2F%20hello_controller.js%0Aimport%20%7B%20Controller%20%7D%20from%20%22stimulus%22%0A%0Aexport%20default%20class%20extends%20Controller%20%7B%0A%20%20static%20targets%20%3D%20%5B%20%22name%22%2C%20%22output%22%20%5D%0A%0A%20%20greet()%20%7B%0A%20%20%20%20this.outputTarget.textContent%20%3D%0A%20%20%20%20%20%20%60Hello%2C%20%24%7Bthis.nameTarget.value%7D!%60%0A%20%20%7D%0A%7D):
+Here's the classic Stimulus example, but in Ruby! Compare with the [JavaScript version](https://stimulus.hotwired.dev/#:~:text=%2F%2F%20hello_controller.js%0Aimport%20%7B%20Controller%20%7D%20from%20%22stimulus%22%0A%0Aexport%20default%20class%20extends%20Controller%20%7B%0A%20%20static%20targets%20%3D%20%5B%20%22name%22%2C%20%22output%22%20%5D%0A%0A%20%20greet()%20%7B%0A%20%20%20%20this.outputTarget.textContent%20%3D%0A%20%20%20%20%20%20%60Hello%2C%20%24%7Bthis.nameTarget.value%7D!%60%0A%20%20%7D%0A%7D).
 
-**Ruby Controller:**
+**Ruby Controller (`app/opal/controllers/hello_controller.rb`):**
 
 ```ruby
-# app/opal/controllers/hello_controller.rb
 class HelloController < StimulusController
   self.targets = ["name", "output"]
 
@@ -49,31 +50,30 @@ class HelloController < StimulusController
 end
 ```
 
-**HTML:**
+**HTML (unchanged from regular Stimulus):**
 
 ```html
 <div data-controller="hello">
   <input data-hello-target="name" type="text">
-
-  <button data-action="click->hello#greet">
-    Greet
-  </button>
-
-  <span data-hello-target="output">
-  </span>
+  <button data-action="click->hello#greet">Greet</button>
+  <span data-hello-target="output"></span>
 </div>
 ```
 
-**Notes:**
+### Key Differences from JavaScript Stimulus
 
-- In general any reference method is snake cased, so `container` target will produce `container_target` and not ~`containerTarget`~
-- Any `target`, `element`, `document`, `window` and `event` is a `JS::Proxy` instance, that provides a dynamic interface to JavaScript objects in Opal
-- The frontend definition part will remain the same
+- **Snake case**: JavaScript's `containerTarget` becomes `container_target` in Ruby
+- **DOM objects**: All `target`, `element`, `document`, `window`, and `event` objects are `JS::Proxy` instances that provide Ruby-friendly access to JavaScript APIs
+- **HTML stays the same**: Your templates and data attributes work exactly like regular Stimulus
 
+## Reference Examples
 
-## Some examples based on [Stimulus Reference](https://stimulus.hotwired.dev/reference/controllers)
+Based on the [Stimulus Reference](https://stimulus.hotwired.dev/reference/controllers), here's how common patterns work in Ruby:
 
 ### Lifecycle Callbacks
+
+> 📚 [Stimulus Lifecycle Callbacks Reference](https://stimulus.hotwired.dev/reference/lifecycle-callbacks)
+
 ```ruby
 class AlertController < StimulusController
   def initialize; end
@@ -82,12 +82,15 @@ class AlertController < StimulusController
 end
 ```
 
-### Actions
+### Actions & Events
+
+> 📚 [Stimulus Actions Reference](https://stimulus.hotwired.dev/reference/actions)
+
 ```ruby
 class WindowResizeController < StimulusController
   def resized(event)
     if !@resized && event.target.inner_width >= 1080
-      puts "Full HD? Nice!"
+      puts "Full HD detected!"
       @resized = true
     end
   end
@@ -95,6 +98,9 @@ end
 ```
 
 ### Targets
+
+> 📚 [Stimulus Targets Reference](https://stimulus.hotwired.dev/reference/targets)
+
 ```ruby
 class ContainerController < StimulusController
   self.targets = ["container"]
@@ -112,6 +118,9 @@ end
 ```
 
 ### Outlets
+
+> 📚 [Stimulus Outlets Reference](https://stimulus.hotwired.dev/reference/outlets)
+
 ```ruby
 class ChatController < StimulusController
   self.outlets = [ "user-status" ]
@@ -125,6 +134,9 @@ end
 ```
 
 ### Values
+
+> 📚 [Stimulus Values Reference](https://stimulus.hotwired.dev/reference/values)
+
 ```ruby
 class LoaderController < StimulusController
   self.values = { url: :string }
@@ -146,18 +158,24 @@ end
 ```
 
 ### CSS Classes
+
+> 📚 [Stimulus CSS Classes Reference](https://stimulus.hotwired.dev/reference/css-classes)
+
 ```ruby
 class SearchController < StimulusController
-  self.classes = [ "loading" ]
+  self.classes = ["loading"]
 
-  def loadResults
-    element.class_list.add loading_class
+  def load_results
+    element.class_list.add(loading_class)
   end
 end
 ```
 
-## Extra tools
-### Window
+## Working with the DOM
+
+Opal Stimulus gives you Ruby-friendly access to all the browser APIs you know and love:
+
+### `window`
 ```ruby
 class WindowController < StimulusController
   def connect
@@ -169,20 +187,25 @@ class WindowController < StimulusController
 end
 ```
 
-### Document
+### `document`
 ```ruby
 class DocumentController < StimulusController
   def connect
-    headers = document.querySelectorAll("h1")
-    headers.each do |h1|
+    document.querySelectorAll("h1").each do |h1|
       h1.text_content = "Opal is great!"
     end
   end
 end
 ```
 
-## Run tests
-`bundle exec rake`
+
+## Development
+
+Run the test suite:
+
+```bash
+bundle exec rake
+```
 
 ## Contributing
 

data/lib/opal_stimulus/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module OpalStimulus
-  VERSION = "0.1.8"
+  VERSION = "0.1.9"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: opal_stimulus
 version: !ruby/object:Gem::Version
-  version: 0.1.8
+  version: 0.1.9
 platform: ruby
 authors:
 - Joseph Schito
@@ -137,7 +137,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.9
+rubygems_version: 3.7.2
 specification_version: 4
 summary: 'Opal Stimulus: Write Stimulus controllers in Ruby'
 test_files: []