opal_stimulus 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: e2b9722851b24c4870cc76265994a889813d4d59e826e4e945c4859b9de9f873
+  data.tar.gz: 6c9df0ea9b687094f3cb266abacb8824456809dcfdcd100a744fe04c667bf8bf
+SHA512:
+  metadata.gz: 05edb688629527e884549e82cb92a375b1006735d7c082ac2a013c553b3e7214ef1ae90160b904528626d3804ac281c26987480cf1081b84331566884d413675
+  data.tar.gz: aaad0562773f879a73bf66eed31966a8048b766056e12bf401a3f4785833d19f14b6381a9d8cd2fef68e0c1cb6239443adee71ac7176c9ac7929c800800bb473

data/.rubocop.yml

@@ -0,0 +1,8 @@
+AllCops:
+  TargetRubyVersion: 3.1
+
+Style/StringLiterals:
+  EnforcedStyle: double_quotes
+
+Style/StringLiteralsInInterpolation:
+  EnforcedStyle: double_quotes

data/CHANGELOG.md

@@ -0,0 +1,5 @@
+## [Unreleased]
+
+## [0.1.0] - 2025-03-27
+
+- Initial release

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2025 Joseph Schito
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,58 @@
+# 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).
+
+## Installation
+
+Add this line to your Gemfile:
+
+```ruby
+gem 'opal_stimulus'
+```
+
+Then execute:
+
+```bash
+bundle install
+rails generate opal_stimulus:install
+```
+
+## Basic Example
+
+Here's a Hello World example with OpalStimulus. Compare with the [original JavaScript example](https://stimulus.hotwired.dev/handbook/hello-stimulus):
+
+**Ruby Controller:**
+
+```ruby
+# app/opal/controllers/hello_controller.rb
+class HelloController < StimulusController
+  self.targets = ["name", "output"]
+
+  def greet
+    output_target.JS[:textContent] = "Hello, #{name_target.JS[:value]}!"
+  end
+end
+```
+
+**HTML:**
+
+```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>
+</div>
+```
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/josephschito/opal_stimulus.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "minitest/test_task"
+
+Minitest::TestTask.create
+
+require "rubocop/rake_task"
+
+RuboCop::RakeTask.new
+
+task default: %i[test rubocop]

data/lib/install/Procfile.dev

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

data/lib/install/application.rb

@@ -0,0 +1,9 @@
+require "opal_stimulus/stimulus_controller"
+require "controllers_requires"
+
+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

data/lib/install/controllers/my_opal_controller.rb

@@ -0,0 +1,5 @@
+class MyOpalController < StimulusController
+  def connect
+    puts "'#{self.class.name}' connected!"
+  end
+end

data/lib/install/controllers_requires.rb

@@ -0,0 +1,4 @@
+# This file is automatically generated by `bin/opal`.
+# If you want to update this file, please run: `bin/opal --update-requires`.
+
+require 'controllers/my_opal_controller'

data/lib/install/dev

@@ -0,0 +1,11 @@
+#!/usr/bin/env sh
+
+if gem list --no-installed --exact --silent foreman; then
+  echo "Installing foreman..."
+  gem install foreman
+fi
+
+# Default to port 3000 if not specified
+export PORT="${PORT:-3000}"
+
+exec foreman start -f Procfile.dev --env /dev/null "$@"

data/lib/install/install_opal_stimulus.rb

@@ -0,0 +1,55 @@
+APPLICATION_LAYOUT_PATH = Rails.root.join("app/views/layouts/application.html.erb")
+APPLICATION_OPAL_STIMULUS_BIN_PATH = Rails.root.join("bin")
+APPLICATION_OPAL_STIMULUS_PATH = Rails.root.join("app/opal")
+
+if File.exist? APPLICATION_LAYOUT_PATH
+  say "Adding Opal Stimulus to the application layout", :green
+  insert_into_file APPLICATION_LAYOUT_PATH, after: "<%= javascript_importmap_tags %>\n" do
+    <<-ERB
+    <script type="module">
+      import "application"
+      import "<%= javascript_path("opal") %>"
+    </script>
+    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"
+  else
+    say "Add default Procfile.dev"
+    copy_file "#{__dir__}/Procfile.dev", "Procfile.dev"
+
+    say "Ensure foreman is installed"
+    run "gem install foreman"
+  end
+  insert_into_file Rails.root.join("app/javascript/controllers/application.js") do
+    <<-JS
+import { Controller } from "@hotwired/stimulus";
+
+window.application = application;
+window.Controller = Controller;
+    JS
+  end
+  append_to_file ".gitignore", "/.opal-cache\n"
+  append_to_file ".gitignore", "app/assets/builds/opal.js\n"
+  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 "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/install/opal

@@ -0,0 +1,63 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "bundler/setup"
+require "listen"
+require "opal"
+
+GEM_NAME = "opal_stimulus"
+
+Opal.use_gem(GEM_NAME) rescue Opal.append_path(File.expand_path("lib", Bundler.rubygems.find_name(GEM_NAME).first.full_gem_path))
+
+Opal.append_path("app/opal")
+
+build = -> {
+  puts "🔨 Compiling Opal..."
+
+  builder = Opal::Builder.build("application", requirable: false)
+  output_path = "app/assets/builds/opal.js"
+  File.write(output_path, builder.to_s)
+
+  puts "✅ Compiled to #{output_path}"
+}
+
+update_opal_controllers_requires = -> {
+  file_path = "app/opal/controllers_requires.rb"
+
+  requires = Dir["app/opal/controllers/**/*.rb"].sort.map do |file|
+    "require '#{file.sub("app/opal/", "").sub(".rb", "")}'"
+  end
+
+  File.open(file_path, "w") do |f|
+    f.puts "# This file is automatically generated by `bin/opal`."
+    f.puts "# If you want to update this file, please run: `bin/opal --update-requires`."
+    f.puts
+    f.puts requires.join("\n")
+  end
+
+  puts "✅ Updated #{file_path} 🎉"
+}
+
+if ARGV.include?("--update-requires")
+  update_opal_controllers_requires.()
+  exit
+end
+
+update_opal_controllers_requires.()
+build.call
+
+exit unless ARGV.include?("--watch")
+
+listen = Listen.to("app/opal") do |modified, added, removed|
+  if added.any? || removed.any?
+    puts "🔄 Updating opal controllers requires..."
+    update_opal_controllers_requires.()
+  end
+
+  build.call
+end
+
+puts "👀 Watching app/opal for changes..."
+listen.start
+Signal.trap("INT") { listen.stop }
+sleep

data/lib/opal_stimulus/stimulus_controller.rb

@@ -0,0 +1,236 @@
+# backtick_javascript: true
+
+require "opal"
+require "native"
+
+class StimulusController < `Controller`
+  include Native::Wrapper
+
+  DEFAULT_METHODS = %i[initialize connect disconnect dispatch]
+  DEFAULT_GETTERS = %i[element]
+
+  def self.inherited(subclass)
+    ::Opal.bridge(subclass.stimulus_controller, subclass)
+  end
+
+  def self.stimulus_controller
+    return @stimulus_controller if @stimulus_controller
+    @stimulus_controller = `class extends Controller {}`
+    @stimulus_controller
+  end
+
+  def self.stimulus_name
+    self.name.gsub(/Controller$/, "").gsub(/([a-z])([A-Z])/, '\1-\2').downcase
+  end
+
+  def self.method_added(name)
+    return if DEFAULT_GETTERS.include?(name)
+
+    self.bridge_method(name)
+  end
+
+  def self.register(controller)
+    `Stimulus.register(#{self.stimulus_name}, #{controller})`
+  end
+
+  def self.bridge_method(name)
+    %x{
+      #{self.stimulus_controller}.prototype[name] = function (...args) {
+        return #{self.stimulus_controller}.prototype['$' + name].apply(this, args);
+      }
+    }
+  end
+
+  def self.targets=(targets = [])
+    `#{self.stimulus_controller}.targets = targets`
+
+    targets.each do |target|
+      define_method(target + "_target") do
+        `return this[#{target + "Target"}]`
+      end
+
+      define_method(target + "_targets") do
+        `return this[#{target + "Targets"}]`
+      end
+
+      define_method("has_" + target + "_target") do
+        `return this[#{"has" + target.capitalize + "Target"}]`
+      end
+
+      snake_case_connected = target + "_target_connected"
+      camel_case_connected = target + "TargetConnected"
+      %x{
+        #{self.stimulus_controller}.prototype[#{camel_case_connected}] = function() {
+          if (this['$respond_to?'] && this['$respond_to?'](#{snake_case_connected})) {
+            return this['$' + #{snake_case_connected}]();
+          }
+        }
+      }
+
+      snake_case_disconnected = target + "_target_disconnected"
+      camel_case_disconnected = target + "TargetDisconnected"
+      %x{
+        #{self.stimulus_controller}.prototype[#{camel_case_disconnected}] = function() {
+          if (this['$respond_to?'] && this['$respond_to?'](#{snake_case_disconnected})) {
+            return this['$' + #{snake_case_disconnected}]();
+          }
+        }
+      }
+    end
+  end
+
+  def self.outlets=(outlets = [])
+    `#{self.stimulus_controller}.outlets = outlets`
+
+    outlets.each do |outlet|
+      define_method(outlet + "_outlet") do
+        `return this[#{outlet + "Outlet"}]`
+      end
+
+      define_method(outlet + "_outlets") do
+        `return this[#{outlet + "Outlets"}]`
+      end
+
+      define_method("has_" + outlet + "_outlet") do
+        `return this[#{"has" + outlet.capitalize + "Outlet"}]`
+      end
+
+      snake_case_connected = outlet + "_outlet_connected"
+      camel_case_connected = outlet + "OutletConnected"
+      %x{
+        #{self.stimulus_controller}.prototype[#{camel_case_connected}] = function() {
+          if (this['$respond_to?'] && this['$respond_to?'](#{snake_case_connected})) {
+            return this['$' + #{snake_case_connected}]();
+          }
+        }
+      }
+
+      snake_case_disconnected = outlet + "_outlet_disconnected"
+      camel_case_disconnected = outlet + "OutletDisconnected"
+      %x{
+        #{self.stimulus_controller}.prototype[#{camel_case_disconnected}] = function() {
+          if (this['$respond_to?'] && this['$respond_to?'](#{snake_case_disconnected})) {
+            return this['$' + #{snake_case_disconnected}]();
+          }
+        }
+      }
+    end
+  end
+
+  def self.values=(values_hash = {})
+    js_values = {}
+
+    values_hash.each do |name, type|
+      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
+      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
+      end
+
+      define_method("has_#{name}") do
+        `return this[#{"has" + name.to_s.capitalize + "Value"}]`
+      end
+
+      snake_case_changed = "#{name}_value_changed"
+      camel_case_changed = "#{name}ValueChanged"
+      %x{
+        #{self.stimulus_controller}.prototype[#{camel_case_changed}] = function(value, 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}`
+
+    class_names.each do |class_name|
+      define_method("add_#{class_name}_class") do
+        `this.#{class_name}Classes.add()`
+      end
+
+      define_method("remove_#{class_name}_class") do
+        `this.#{class_name}Classes.remove()`
+      end
+
+      define_method("has_#{class_name}_class?") do
+        `return this.#{class_name}Classes.has()`
+      end
+
+      define_method("toggle_#{class_name}_class") do
+        `this.#{class_name}Classes.toggle()`
+      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
+  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
+  end
+
+  def element
+    `this.element`
+  end
+end

data/lib/opal_stimulus/version.rb

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

data/lib/opal_stimulus.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+require 'rake'
+
+if RUBY_ENGINE == 'opal'
+  require_relative "opal_stimulus/stimulus_controller"
+else
+  require "opal"
+  require_relative "opal_stimulus/version"
+
+  Opal.append_path File.expand_path('lib', __dir__)
+end
+
+Dir.glob(File.expand_path("../tasks/**/*.rake", __FILE__)).each { |r| load r }
+
+module OpalStimulus
+end

data/lib/tasks/install.rake

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

metadata

@@ -0,0 +1,89 @@
+--- !ruby/object:Gem::Specification
+name: opal_stimulus
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Joseph Schito
+bindir: exe
+cert_chain: []
+date: 2025-06-19 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: opal
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 1.8.2
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 1.8.2
+- !ruby/object:Gem::Dependency
+  name: listen
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 3.9.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 3.9.0
+description: Opal Stimulus provides a way to write Stimulus controllers in Ruby, leveraging
+  the Opal compiler to convert Ruby code into JavaScript. This allows developers familiar
+  with Ruby to use the Stimulus framework without needing to write JavaScript directly.
+email:
+- joseph.schito@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".rubocop.yml"
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- Rakefile
+- lib/install/Procfile.dev
+- lib/install/application.rb
+- lib/install/controllers/my_opal_controller.rb
+- lib/install/controllers_requires.rb
+- lib/install/dev
+- lib/install/install_opal_stimulus.rb
+- lib/install/opal
+- lib/opal_stimulus.rb
+- lib/opal_stimulus/stimulus_controller.rb
+- lib/opal_stimulus/version.rb
+- lib/tasks/install.rake
+homepage: https://github.com/josephschito/opal_stimulus
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/josephschito/opal_stimulus
+  source_code_uri: https://github.com/josephschito/opal_stimulus
+  changelog_uri: https://github.com/josephschito/opal_stimulus/blob/main/CHANGELOG.md
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.1.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.2
+specification_version: 4
+summary: 'Opal Stimulus: Write Stimulus controllers in Ruby'
+test_files: []