opal_stimulus 0.1.3 → 0.1.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 123ac1d5e6112d3896cd623518b80732351357cfa11443dd8142fd07f32bec49
-  data.tar.gz: 41bbd48c083fc12359f979f8c8c5d5de2486acd56cf969c0af417edf9576c1d0
+  metadata.gz: f328bd466f89d10419369095e006b923c4a389c58fa14abd7c57ae2c57fb804d
+  data.tar.gz: 7b6a16a7adc502cdedcdad7e0e71f152652022a42d5a674fc033f6f13e514660
 SHA512:
-  metadata.gz: fa36ee6800f4e0795640c29c061be9b5c49cdc639c9b976381af2ea41863a40a22cac80368956edb1ca569712191f016764d4c4fa16ceb9583f5fca164b391f5
-  data.tar.gz: 9cea24bad6cbf6bfba34ab79026b8589b6f25c180ee210f263568e275a91a1da16314539ecda837e222637657e4534a4d8a421ec8e38aa9c6a90b1c67cca1605
+  metadata.gz: 775c06738928c9c1584d0515064cf7e5984ff1259cb7def3c56cd9bc34942a7da50a39a761400d9f80a824a178d3333887fedfcfec4274adfa261a3819614d59
+  data.tar.gz: f3da082b6361dc0281e743a7ded76c953504c044abe2fc5b59febbd2d68e65138bb4eea4ef2acaab08f8a3a3073c655c3e325c0084f15bce58bd8d23f30d0b2e

data/.rspec-opal

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

data/CHANGELOG.md

@@ -16,3 +16,19 @@
 
 - Add missing ignore for app/assets/builds/opal.js.map
 - Replace opal-browser with opal_proxy, check it out here.
+
+## [0.1.4] - 2025-08-03
+
+- Fix Targets
+- Fix Outlets
+- Fix Values
+- Fix `element`
+- Fix Classes
+- Add `document` and `window` private methods
+
+## [0.1.5] - 2025-08-14
+
+- Add `StimulusController` unit and system tests
+- Reduce installed new lines for Rails
+- Skip importmap in production
+- Add `bin/rails generate opal_stimulus <CONTROLLER_NAME>`, usage: `bin/rails g opal_stimulus -h`

data/README.md

@@ -2,6 +2,8 @@
 
 **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).
 
+[![Ruby](https://github.com/josephschito/opal_stimulus/actions/workflows/main.yml/badge.svg)](https://github.com/josephschito/opal_stimulus/actions/workflows/main.yml)
+
 ## Installation
 
 Add this line to your Gemfile:
@@ -23,6 +25,13 @@ Start application:
 bin/dev
 ```
 
+Create a new controller:
+
+```bash
+bin/rails opal_stimulus hello
+```
+This command will create `app/opal/controllers/hello_controller.rb`
+
 ## Basic Example
 
 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):
@@ -31,8 +40,6 @@ Here's a Hello World example with OpalStimulus. Compare with the [original JavaS
 
 ```ruby
 # app/opal/controllers/hello_controller.rb
-# new controllers will be automatically added to app/opal/controllers_requires.rb
-#   (ordered files load is not supported yet)
 class HelloController < StimulusController
   self.targets = ["name", "output"]
 
@@ -61,8 +68,125 @@ end
 
 https://github.com/user-attachments/assets/c51ed28c-13d2-4e06-b882-1cc997e9627b
 
+**Notes:**
+
+- 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
+
+
+## Some examples based on [Stimulus Reference](https://stimulus.hotwired.dev/reference/controllers)
+
+### Lifecycle Callbacks
+```ruby
+class AlertController < StimulusController
+  def initialize; end
+  def connect; end
+  def disconnect; end
+end
+```
+
+### Actions
+```ruby
+class WindowResizeController < StimulusController
+  def resized(event)
+    if !@resized && event.target.inner_width >= 1080
+      puts "Full HD? Nice!"
+      @resized = true
+    end
+  end
+end
+```
+
+### Targets
+```ruby
+class ContainerController < StimulusController
+  self.targets = ["container"]
+
+  def container_target_connected
+    container_target.inner_html = <<~HTML
+      <h1>Test connected!</h1>
+    HTML
+  end
+
+  def container_target_disconnected
+    puts "Container disconnected!"
+  end
+end
+```
+
+### Outlets
+```ruby
+class ChatController < StimulusController
+  self.outlets = [ "user-status" ]
+
+  def connect
+    user_status_outlets.each do |status|
+      puts status
+    end
+  end
+end
+```
+
+### Values
+```ruby
+class LoaderController < StimulusController
+  self.values = { url: :string }
+
+  def connect
+    window.fetch(url_value).then do |response|
+      response.json().then do |data|
+        load_data(data)
+      end
+    end
+  end
+
+  private
+
+  def load_data(data)
+    # ...
+  end
+end
+```
+
+### CSS Classes
+```ruby
+class SearchController < StimulusController
+  self.classes = [ "loading" ]
 
+  def loadResults
+    element.class_list.add loading_class
+  end
+end
+```
+
+## Extra tools
+### Window
+```ruby
+class WindowController < StimulusController
+  def connect
+    window.alert "Hello world!"
+    window.set_timeout(-> {
+      puts "1. Timeout test OK (1s delay)"
+    }, 1000)
+  end
+end
+```
+
+### Document
+```ruby
+class DocumentController < StimulusController
+  def connect
+    headers = document.querySelectorAll("h1")
+    headers.each do |h1|
+      h1.text_content = "Opal is great!"
+    end
+  end
+end
+```
 
+## Run tests
+`bundle exec rake`
 
 ## Contributing
 

data/Rakefile

@@ -9,4 +9,15 @@ require "rubocop/rake_task"
 
 RuboCop::RakeTask.new
 
-task default: %i[test rubocop]
+require 'opal/rspec/rake_task'
+require "opal"
+
+Opal.use_gem("opal_proxy")
+Opal.append_path File.expand_path('../lib', __FILE__)
+Opal.append_path File.expand_path('../shared_fixtures', __FILE__)
+
+Opal::RSpec::RakeTask.new("rspec-opal") do |server, task|
+  task.runner = :chrome
+end
+
+task default: %i[test rspec-opal]

data/lib/generators/USAGE

@@ -0,0 +1,14 @@
+Description:
+============
+    Generates a new Opal Stimulus controller at the passed path.
+
+Examples:
+=========
+    bin/rails generate opal_stimulus chat
+
+    creates: app/opal/controllers/chat_controller.rb
+
+
+    bin/rails generate stimulus nested/chat
+
+    creates: app/opal/controllers/nested/chat_controller.rb

data/lib/generators/opal_stimulus_generator.rb

@@ -0,0 +1,9 @@
+require "rails/generators/named_base"
+
+class OpalStimulusGenerator < Rails::Generators::NamedBase
+  source_root File.expand_path("templates", __dir__)
+
+  def create_controller_file
+    template "controller.rb.tt", File.join("app/opal/controllers", class_path, "#{file_name}_controller.rb")
+  end
+end

data/lib/generators/templates/controller.rb.tt

@@ -0,0 +1,14 @@
+# Connects to data-controller="<%= file_name.dasherize %>"
+<% constants = class_name.split("::") -%>
+<% modules = constants[0..-2] -%>
+<% indentation = "  " * (modules.length) -%>
+<% modules.each do |constant| -%>
+module <%= constant %>
+<% end -%>
+<%= indentation %>class <%= constants.last %>Controller < StimulusController
+<%= indentation %>  def connect
+<%= indentation %>  end
+<%= indentation %>end
+<% modules.each.with_index do |constant, i| -%>
+<%= "  " * i %>end
+<% end -%>

data/lib/install/Procfile.dev

@@ -1,2 +1,2 @@
 web: bin/rails server
-opal: bin/opal --watch
+opal: bin/rails opal_stimulus:watch

data/lib/install/application.rb

@@ -1,9 +1,4 @@
 require "opal_stimulus/stimulus_controller"
-require "controllers_requires"
+require_tree "controllers"
 
-StimulusController.subclasses.each do |controller|
-  controller.define_method(:dummy) { }
-
-  return if `Stimulus.controllers`.include?(`#{controller.stimulus_name}`)
-  `Stimulus.register(#{controller.stimulus_name}, #{controller.stimulus_controller})`
-end
+StimulusController.register_all!

data/lib/install/install_opal_stimulus.rb

@@ -13,16 +13,9 @@ if File.exist? APPLICATION_LAYOUT_PATH
     ERB
   end
 
-  insert_into_file APPLICATION_LAYOUT_PATH, after: "<body>\n" do
-    say "Adding `my-opal` to the application layout", :green
-    <<-ERB
-    <span data-controller="my-opal"></span>
-    ERB
-  end
-
   say "Creating Opal Stimulus files", :green
   if Rails.root.join("Procfile.dev").exist?
-    append_to_file "Procfile.dev", "opal: bin/opal --watch\n"
+    append_to_file "Procfile.dev", "opal: bin/rails opal_stimulus:watch\n"
   else
     say "Add default Procfile.dev"
     copy_file "#{__dir__}/Procfile.dev", "Procfile.dev"
@@ -44,13 +37,9 @@ window.Controller = Controller;
   empty_directory APPLICATION_OPAL_STIMULUS_BIN_PATH
   empty_directory APPLICATION_OPAL_STIMULUS_PATH
   empty_directory "#{APPLICATION_OPAL_STIMULUS_PATH}/controllers"
-  empty_directory "#{APPLICATION_OPAL_STIMULUS_PATH}/app/assets/builds"
+  create_file "#{APPLICATION_OPAL_STIMULUS_PATH}/controllers/.keep"
   create_file "app/assets/builds/.keep"
-  copy_file "#{__dir__}/opal", "#{APPLICATION_OPAL_STIMULUS_BIN_PATH}/opal"
-  FileUtils.chmod("+x", "#{APPLICATION_OPAL_STIMULUS_BIN_PATH}/opal")
   copy_file "#{__dir__}/dev", "#{APPLICATION_OPAL_STIMULUS_BIN_PATH}/dev"
   FileUtils.chmod("+x", "#{APPLICATION_OPAL_STIMULUS_BIN_PATH}/dev")
   copy_file "#{__dir__}/application.rb", "#{APPLICATION_OPAL_STIMULUS_PATH}/application.rb"
-  copy_file "#{__dir__}/controllers_requires.rb", "#{APPLICATION_OPAL_STIMULUS_PATH}/controllers_requires.rb"
-  copy_file "#{__dir__}/controllers/my_opal_controller.rb", "#{APPLICATION_OPAL_STIMULUS_PATH}/controllers/my_opal_controller.rb"
 end

data/lib/opal_stimulus/stimulus_controller.rb

@@ -5,8 +5,6 @@ require "native"
 require "js/proxy"
 
 class StimulusController < `Controller`
-  include Native::Wrapper
-
   DEFAULT_METHODS = %i[initialize connect disconnect dispatch]
   DEFAULT_GETTERS = %i[element]
 
@@ -30,7 +28,13 @@ class StimulusController < `Controller`
     %x{
       #{self.stimulus_controller}.prototype[name] = function (...args) {
         try {
-          return this['$' + name].apply(this, args);
+          var wrappedArgs = args.map(function(arg) {
+            if (arg && typeof arg === "object" && !arg.$$class) {
+              return Opal.JS.Proxy.$new(arg);
+            }
+            return arg;
+          });
+          return this['$' + name].apply(this, wrappedArgs);
         } catch (e) {
           console.error("Uncaught", e);
         }
@@ -38,26 +42,45 @@ class StimulusController < `Controller`
     }
   end
 
+  def self.to_ruby_name(name)
+    name
+      .to_s
+      .gsub(/([A-Z]+)/) { "_#{$1.downcase}" }
+      .sub(/^_/, '')
+  end
+
+  def self.register_all!
+    subclasses.each do |controller|
+      controller.define_method(:dummy) {}
+
+      return if `application.controllers`.include?(`#{controller.stimulus_name}`)
+      `application.register(#{controller.stimulus_name}, #{controller.stimulus_controller})`
+    end
+  end
+
   def self.targets=(targets = [])
     `#{self.stimulus_controller}.targets = targets`
 
     targets.each do |target|
-      define_method(target + "_target") do
-        JS::Proxy.new(`this[#{target + "Target"}]`)
+      js_name = target.to_s
+      ruby_name = self.to_ruby_name(target)
+
+      define_method(ruby_name + "_target") do
+        JS::Proxy.new(`this[#{js_name + "Target"}]`)
       end
 
-      define_method(target + "_targets") do
-        `this[#{target + "Targets"}]`.map do |el|
+      define_method(ruby_name + "_targets") do
+        `this[#{js_name + "Targets"}]`.map do |el|
           JS::Proxy.new(el)
         end
       end
 
-      define_method("has_" + target + "_target") do
-        `return this[#{"has" + target.capitalize + "Target"}]`
+      define_method("has_" + ruby_name + "_target") do
+        `this[#{"has" + js_name.capitalize + "Target"}]`
       end
 
-      snake_case_connected = target + "_target_connected"
-      camel_case_connected = target + "TargetConnected"
+      snake_case_connected = ruby_name + "_target_connected"
+      camel_case_connected = js_name + "TargetConnected"
       %x{
         #{self.stimulus_controller}.prototype[#{camel_case_connected}] = function() {
           if (this['$respond_to?'] && this['$respond_to?'](#{snake_case_connected})) {
@@ -66,8 +89,8 @@ class StimulusController < `Controller`
         }
       }
 
-      snake_case_disconnected = target + "_target_disconnected"
-      camel_case_disconnected = target + "TargetDisconnected"
+      snake_case_disconnected = ruby_name + "_target_disconnected"
+      camel_case_disconnected = js_name + "TargetDisconnected"
       %x{
         #{self.stimulus_controller}.prototype[#{camel_case_disconnected}] = function() {
           if (this['$respond_to?'] && this['$respond_to?'](#{snake_case_disconnected})) {
@@ -82,22 +105,23 @@ class StimulusController < `Controller`
     `#{self.stimulus_controller}.outlets = outlets`
 
     outlets.each do |outlet|
-      define_method(outlet + "_outlet") do
-        JS::Proxy.new(`this[#{outlet + "Outlet"}]`)
+      js_name = outlet.to_s
+      ruby_name = self.to_ruby_name(outlet)
+
+      define_method(ruby_name + "_outlet") do
+        `return this[#{js_name + "Outlet"}]`
       end
 
-      define_method(outlet + "_outlets") do
-        `this[#{outlet + "Outlets"}]`.map do |outlet|
-          JS::Proxy.new(outlet)
-        end
+      define_method(ruby_name + "_outlets") do
+        `this[#{js_name + "Outlets"}]`
       end
 
-      define_method("has_" + outlet + "_outlet") do
-        `return this[#{"has" + outlet.capitalize + "Outlet"}]`
+      define_method("has_" + ruby_name + "_outlet") do
+        `return this[#{"has" + js_name.capitalize + "Outlet"}]`
       end
 
-      snake_case_connected = outlet + "_outlet_connected"
-      camel_case_connected = outlet + "OutletConnected"
+      snake_case_connected = ruby_name + "_outlet_connected"
+      camel_case_connected = js_name + "OutletConnected"
       %x{
         #{self.stimulus_controller}.prototype[#{camel_case_connected}] = function() {
           if (this['$respond_to?'] && this['$respond_to?'](#{snake_case_connected})) {
@@ -106,8 +130,8 @@ class StimulusController < `Controller`
         }
       }
 
-      snake_case_disconnected = outlet + "_outlet_disconnected"
-      camel_case_disconnected = outlet + "OutletDisconnected"
+      snake_case_disconnected = ruby_name + "_outlet_disconnected"
+      camel_case_disconnected = js_name + "OutletDisconnected"
       %x{
         #{self.stimulus_controller}.prototype[#{camel_case_disconnected}] = function() {
           if (this['$respond_to?'] && this['$respond_to?'](#{snake_case_disconnected})) {
@@ -122,37 +146,29 @@ class StimulusController < `Controller`
     js_values = {}
 
     values_hash.each do |name, type|
+      name = self.to_ruby_name(name)
+
       js_type = case type
-      when String  then "String"
-      when Integer, Float, Numeric then "Number"
-      when TrueClass, FalseClass, Boolean then "Boolean"
-      when Array  then "Array"
-      when Hash, Object then "Object"
-      else "String" # Default to String for unknown types
+      when :string then `String`
+      when :number then `Number`
+      when :boolean then `Boolean`
+      when :array then `Array`
+      when :object then `Object`
+      else
+        raise ArgumentError,
+          "Unsupported value type: #{type}, please use :string, :number, :boolean, :array, or :object"
       end
 
       js_values[name] = js_type
 
-      # Define value getter method (snake_case)
-      define_method(name.to_s) do
-        # Convert JavaScript value to appropriate Ruby type
-        js_value = `this[#{name + "Value"}]`
-        case type
-        when String
-          js_value.to_s
-        when Integer
-          js_value.to_i
-        when Float
-          js_value.to_f
-        when TrueClass, FalseClass, Boolean
-          !!js_value
-        when Array
-          Native::Array.new(js_value)
-        when Hash, Object
-          Native::Object.new(js_value)
-        else
-          js_value
-        end
+      `#{self.stimulus_controller}.values = #{js_values.to_n}`
+
+      define_method(name + "_value") do
+        Native(`this[#{name + "Value"}]`)
+      end
+
+      define_method(name + "_value=") do |value|
+        Native(`this[#{name + "Value"}]= #{value}`)
       end
 
       define_method("has_#{name}") do
@@ -163,75 +179,48 @@ class StimulusController < `Controller`
       camel_case_changed = "#{name}ValueChanged"
       %x{
         #{self.stimulus_controller}.prototype[#{camel_case_changed}] = function(value, previousValue) {
+          if (#{type == :object}) {
+            value = JSON.stringify(value)
+            previousValue = JSON.stringify(previousValue)
+          }
           if (this['$respond_to?'] && this['$respond_to?'](#{snake_case_changed})) {
             return this['$' + #{snake_case_changed}](value, previousValue);
           }
         }
       }
     end
-
-    `#{self.stimulus_controller}.values = #{js_values.to_n}`
   end
 
   def self.classes=(class_names = [])
-    `#{self.stimulus_controller}.classes = #{class_names.to_n}`
+    `#{self.stimulus_controller}.classes = class_names`
 
     class_names.each do |class_name|
-      define_method("add_#{class_name}_class") do
-        `this.#{class_name}Classes.add()`
-      end
+      js_name = class_name.to_s
+      ruby_name = self.to_ruby_name(class_name)
 
-      define_method("remove_#{class_name}_class") do
-        `this.#{class_name}Classes.remove()`
+      define_method("#{ruby_name}_class") do
+        `return this[#{js_name + "Class"}]`
       end
 
-      define_method("has_#{class_name}_class?") do
-        `return this.#{class_name}Classes.has()`
+      define_method("#{ruby_name}_classes") do
+        `return this[#{js_name + "Classes"}]`
       end
 
-      define_method("toggle_#{class_name}_class") do
-        `this.#{class_name}Classes.toggle()`
+      define_method("has_#{ruby_name}_class") do
+        `return this[#{"has" + js_name.capitalize + "Class"}]`
       end
     end
   end
 
-  def add_class(class_name, element = nil)
-    if element
-      `this.addClass(#{class_name}, #{element})`
-    else
-      `this.addClass(#{class_name})`
-    end
-  end
-
-  def remove_class(class_name, element = nil)
-    if element
-      `this.removeClass(#{class_name}, #{element})`
-    else
-      `this.removeClass(#{class_name})`
-    end
-  end
-
-  def has_class?(class_name, element = nil)
-    if element
-      `return this.hasClass(#{class_name}, #{element})`
-    else
-      `return this.hasClass(#{class_name})`
-    end
+  def element
+    JS::Proxy.new(`this.element`)
   end
 
-  def toggle_class(class_name, force = nil, element = nil)
-    if element && force != nil
-      `this.toggleClass(#{class_name}, #{force}, #{element})`
-    elsif element
-      `this.toggleClass(#{class_name}, #{element})`
-    elsif force != nil
-      `this.toggleClass(#{class_name}, #{force})`
-    else
-      `this.toggleClass(#{class_name})`
-    end
+  def window
+    @window ||= JS::Proxy.new($$.window)
   end
 
-  def element
-    `this.element`
+  def document
+    @document ||= JS::Proxy.new($$.document)
   end
 end

data/lib/opal_stimulus/version.rb

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

data/lib/tasks/build.rake

@@ -0,0 +1,53 @@
+require "bundler/setup"
+require "listen"
+require "opal"
+
+namespace :opal_stimulus do
+  def prepare_paths
+    [ "opal_proxy", "opal_stimulus" ].each do |gem_name|
+      Opal.use_gem(gem_name) rescue Opal.append_path(File.expand_path("lib", Bundler.rubygems.find_name(gem_name).first.full_gem_path))
+    end
+
+    Opal.append_path(Rails.root.join("app/opal"))
+  end
+
+  def compile
+    puts "🔨 Compiling Opal..."
+
+    builder = Opal::Builder.new
+    result = builder.build("application")
+    output_path = Rails.root.join("app/assets/builds/opal.js")
+    code = result.to_s
+
+    if Rails.env.development?
+      code += "//# sourceMappingURL=/assets/opal.js.map"
+      sourcemap_path = "#{output_path}.map"
+      source_map_json = result.source_map.to_json
+      File.write(sourcemap_path, source_map_json)
+    end
+
+    File.write(output_path, code)
+
+    puts "✅ Compiled to #{output_path}"
+  end
+
+  desc "Build Opal Stimulus controllers"
+  task build: [:environment] do
+    prepare_paths
+    compile
+  end
+
+  desc "Watch and build Opal Stimulus controllers"
+  task watch: [:environment] do
+    prepare_paths
+
+    compile
+
+    listen = Listen.to(Rails.root.join("app/opal")) { compile }
+
+    puts "👀 Watching app/opal for changes..."
+    listen.start
+    Signal.trap("INT") { listen.stop }
+    sleep
+  end
+end

data/lib/tasks/install.rake

@@ -1,6 +1,6 @@
 namespace :opal_stimulus do
   desc "Install Opal Stimulus into the app"
-  task :install do
+  task install: [:environment] do
     system "#{RbConfig.ruby} ./bin/rails app:template LOCATION=#{File.expand_path("../install/install_opal_stimulus.rb", __dir__)}"
   end
 end