stimulus-rails 0.3.11 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 64761f6c52233208ab99ba06ecc3d99a4df3ec15a43bdda8e9059714a5e1a6ee
-  data.tar.gz: 8a7416e6f82f089575a87b27fa7706cd0aa1f5ea01786aa0754cfce51e0c9d7c
+  metadata.gz: d527795451c1f97bf1bc540f6cb5ce4171a4f016df1d8f60b30da8e96f7adf27
+  data.tar.gz: 7478ece303c9b51ed819d7a04e8ff3e7f578b6debb17ebc7ea00a8afd2fbd2f3
 SHA512:
-  metadata.gz: 929c0266cf1ed01dee781af2d228481b3e4f4164bdc09c3c9e1505ced0a40c4223fa54849ace773806d2be3df300103ed8099867735fbefa35e5288110ba799f
-  data.tar.gz: 02d4931af10963beef58c26379499486326b355e325078e24649c6ab92e0351bfbabb936fc72202df31bb10de8c9a477bf698d27df10476260fd6604ae0e192d
+  metadata.gz: 8dfe74aba6df874a5f3d8f8fe701f78b79d3f31577383a673f3556c1607c9cf1d80e5df6301327aa5bfb816b7ee36c3916d9b9ea1c57bdfc4b0fedf96c0b8fa6
+  data.tar.gz: 4dec5a152ecac26df7008230f791bf4270518de1ab48379c405a30f4485d07c5443dcde5bb892baab33351949f2bd529e31df1180a4d217db7adcb902586fb88

data/README.md

@@ -11,31 +11,24 @@ Stimulus for Rails makes it easy to use this modest framework with the asset pip
 2. Run `./bin/bundle install`.
 3. Run `./bin/rails stimulus:install`
 
-If using the asset pipeline to manage JavaScript, the last command will:
-
-1. Create an example controller in `app/assets/javascripts/controllers/hello_controller.js`.
-2. Append `import "@hotwired/stimulus-autoloader"` to your `app/assets/javascripts/application.js` entrypoint.
-
-Make sure you've already installed `importmap-rails` and that it's referenced before `stimulus-rails` (or `hotwire-rails`) in your Gemfile.
-
-If using Webpacker to manage JavaScript, the last command will:
-
-1. Import the controllers directory in the application pack.
-2. Create a controllers directory at `app/javascripts/controllers`.
-3. Create an example controller in `app/javascripts/controllers/hello_controller.js`.
-4. Install the Stimulus NPM package.
+The installer will automatically detect whether you're using an import map or node to manage your application's JavaScript. If you're using an import map, the Stimulus dependencies will be pinned to the versions of the library included with this gem. If you're using node, yarn will add the dependencies to your package.json file.
 
 
 ## Usage
 
-With the installation done, you'll automatically have activated Stimulus through the controller autoloader. You can now easily add new Stimulus controllers that'll be loaded via ESM dynamic imports.
+The installer amends your JavaScript entry point at `app/javascript/application.js` to import the `app/javascript/controllers/index.js` file, which is responsible for setting up your Stimulus application and registering your controllers.
+
+With an import-mapped application, controllers are automatically pinned and registered based on the file structure. With a node application, controllers need to be imported and registered directly in the index.js file, but this is done automatically using either the Stimulus generator (`./bin/rails generate stimulus [controller]`) or the dedicated `stimulus:manifest:update` task. Either will overwrite the `controllers/index.js` file.
 
-For example, a more advanced `hello_controller` could look like this:
+You're encouraged to use the generator to add new controllers like so:
 
 ```javascript
+// Run "./bin/rails g stimulus hello" to create the file and update the index, then amend:
+
 // app/assets/javascripts/controllers/hello_controller.js
-import { Controller } from "stimulus"
+import { Controller } from "@hotwired/stimulus"
 
+// Connects with data-controller="hello"
 export default class extends Controller {
   static targets = [ "name", "output" ]
 

data/app/assets/javascripts/stimulus-importmap-autoloader.js

@@ -1,21 +1,25 @@
-import { Application } from "@hotwired/stimulus"
+// FIXME: es-module-shim won't shim the dynamic import without this explicit import
+import "@hotwired/stimulus"
 
-function registerControllersFrom(under) {
-  const paths = Object.keys(importmap).filter(path => path.match(new RegExp(`^${under}/.*_controller$`)))
-  paths.forEach(path => registerControllerFromPath(path, under))
+export function registerControllersFrom(under, application) {
+  const paths = Object.keys(parseImportmapJson())
+    .filter(path => path.match(new RegExp(`^${under}/.*_controller$`)))
+
+  paths.forEach(path => registerControllerFromPath(path, under, application))
+}
+
+export function parseImportmapJson() {
+  return JSON.parse(document.querySelector("script[type=importmap]").text).imports
 }
 
-function registerControllerFromPath(path, under) {
-  const name = path.replace(`${under}/`, "").replace("_controller", "").replace(/\//g, "--").replace(/_/g, "-")
+function registerControllerFromPath(path, under, application) {
+  const name = path
+    .replace(`${under}/`, "")
+    .replace("_controller", "")
+    .replace(/\//g, "--")
+    .replace(/_/g, "-")
 
   import(path)
     .then(module => application.register(name, module.default))
     .catch(error => console.log(`Failed to register controller: ${name} (${path})`, error))
 }
-
-const application = Application.start()
-const importmap = JSON.parse(document.querySelector("script[type=importmap]").text).imports
-
-registerControllersFrom("controllers")
-
-export { application, registerControllersFrom }

data/lib/generators/stimulus/USAGE

@@ -0,0 +1,15 @@
+Description:
+============
+    Generates a new Stimulus controller at the passed path. If running under node,
+    it'll also call the stimulus:manifest:update task to update the controllers/index.js.
+
+Examples:
+=========
+    bin/rails generate stimulus chat
+
+    creates: app/javascript/controllers/chat_controller.js
+
+
+    bin/rails generate stimulus nested/chat
+
+    creates: app/javascript/controllers/nested/chat_controller.js

data/lib/generators/stimulus/stimulus_generator.rb

@@ -0,0 +1,16 @@
+require "rails/generators/named_base"
+
+class StimulusGenerator < Rails::Generators::NamedBase # :nodoc:
+  source_root File.expand_path("templates", __dir__)
+
+  def copy_view_files
+    @attribute = stimulus_attribute_value(name)
+    template "controller.js", "app/javascript/controllers/#{name}_controller.js"
+    rails_command "stimulus:manifest:update" if Rails.root.join("package.json").exist?
+  end
+
+  private
+    def stimulus_attribute_value(name)
+      name.gsub(/\//, "--")
+    end
+end

data/lib/generators/stimulus/templates/controller.js.tt

@@ -0,0 +1,7 @@
+import { Controller } from "@hotwired/stimulus"
+
+// Connects to data-controller="<%= @attribute %>"
+export default class extends Controller {
+  connect() {
+  }
+}

data/lib/install/app/javascript/controllers/application.js

@@ -0,0 +1,10 @@
+import { Application } from "@hotwired/stimulus"
+
+const application = Application.start()
+
+// Configure Stimulus development experience
+application.warnings = true
+application.debug    = false
+window.Stimulus      = application
+
+export { application }

data/lib/install/app/javascript/controllers/index_for_importmap.js

@@ -0,0 +1,5 @@
+// Import and register all your controllers from the importmap under controllers/*
+
+import { application } from "controllers/application"
+import { registerControllersFrom } from "@hotwired/stimulus-importmap-autoloader"
+registerControllersFrom("controllers", application)

data/lib/install/app/javascript/controllers/index_for_node.js

@@ -0,0 +1,7 @@
+// This file is auto-generated by ./bin/rails stimulus:manifest:update
+// Run that command whenever you add a new controller
+
+import { application } from "./application"
+
+import HelloController from "./hello_controller"
+application.register("hello", HelloController)

data/lib/install/stimulus_with_importmap.rb

@@ -0,0 +1,19 @@
+say "Create controllers directory"
+empty_directory "app/javascript/controllers"
+copy_file "#{__dir__}/app/javascript/controllers/index_for_importmap.js",
+  "app/javascript/controllers/index.js"
+copy_file "#{__dir__}/app/javascript/controllers/application.js",
+  "app/javascript/controllers/application.js"
+copy_file "#{__dir__}/app/javascript/controllers/hello_controller.js",
+  "app/javascript/controllers/hello_controller.js"
+
+say "Import Stimulus controllers"
+append_to_file "app/javascript/application.js", %(import "controllers"\n)
+
+say "Pin Stimulus"
+append_to_file "config/importmap.rb" do <<-RUBY
+pin "@hotwired/stimulus", to: "stimulus.js"
+pin "@hotwired/stimulus-importmap-autoloader", to: "stimulus-importmap-autoloader.js"
+pin_all_from "app/javascript/controllers", under: "controllers"
+RUBY
+end

data/lib/install/stimulus_with_node.rb

@@ -0,0 +1,18 @@
+say "Create controllers directory"
+empty_directory "app/javascript/controllers"
+copy_file "#{__dir__}/app/javascript/controllers/index_for_node.js",
+  "app/javascript/controllers/index.js"
+copy_file "#{__dir__}/app/javascript/controllers/application.js",
+  "app/javascript/controllers/application.js"
+copy_file "#{__dir__}/app/javascript/controllers/hello_controller.js",
+  "app/javascript/controllers/hello_controller.js"
+
+if (Rails.root.join("app/javascript/application.js")).exist?
+  say "Import Stimulus controllers"
+  append_to_file "app/javascript/application.js", %(import "./controllers"\n)
+else
+  say %(You must import "./controllers" in your JavaScript entrypoint), :red
+end
+
+say "Install Stimulus"
+run "yarn add @hotwired/stimulus"

data/lib/stimulus/manifest.rb

@@ -0,0 +1,23 @@
+module Stimulus::Manifest
+  extend self
+
+  def generate_from(controllers_path)
+    extract_controllers_from(controllers_path).collect do |controller_path|
+      module_path = controller_path.relative_path_from(controllers_path).to_s.remove(".js")
+      controller_class_name = module_path.camelize.gsub(/::/, "__")
+      tag_name = module_path.remove("_controller").gsub(/\//, "--")
+  
+      <<-JS
+
+import #{controller_class_name} from "./#{module_path}"
+application.register("#{tag_name}", #{controller_class_name})
+      JS
+    end
+  end
+
+  def extract_controllers_from(directory)
+    (directory.children.select { |e| e.to_s =~ /_controller.js$/ } +
+      directory.children.select(&:directory?).collect { |d| extract_controllers_from(d) }
+    ).flatten
+  end
+end

data/lib/stimulus/version.rb

@@ -1,3 +1,3 @@
 module Stimulus
-  VERSION = "0.3.11"
+  VERSION = "0.5.0"
 end

data/lib/tasks/stimulus_tasks.rake

@@ -1,26 +1,47 @@
+require "stimulus/manifest"
+
 def run_stimulus_install_template(path) system "#{RbConfig.ruby} ./bin/rails app:template LOCATION=#{File.expand_path("../install/#{path}.rb",  __dir__)}" end
 
 namespace :stimulus do
   desc "Install Stimulus into the app"
   task :install do
-    if defined?(Webpacker::Engine)
-      Rake::Task["stimulus:install:webpacker"].invoke
-    elsif defined?(Importmap)
-      Rake::Task["stimulus:install:asset_pipeline"].invoke
+    if Rails.root.join("config/importmap.rb").exist?
+      Rake::Task["stimulus:install:importmap"].invoke
+    elsif Rails.root.join("package.json").exist?
+      Rake::Task["stimulus:install:node"].invoke
     else
-      puts "You must either be running Webpacker or importmap-rails to use this gem."
+      puts "You must either be running with node (package.json) or importmap-rails (config/importmap.rb) to use this gem."
     end
   end
 
   namespace :install do
-    desc "Install Stimulus on the app with the asset pipeline"
-    task :asset_pipeline do
-      run_stimulus_install_template "stimulus_with_asset_pipeline"
+    desc "Install Stimulus on an app running importmap-rails"
+    task :importmap do
+      run_stimulus_install_template "stimulus_with_importmap"
+    end
+
+    desc "Install Stimulus on an app running node"
+    task :node do
+      run_stimulus_install_template "stimulus_with_node"
     end
+  end
+
+  namespace :manifest do
+    task :display do
+      puts Stimulus::Manifest.generate_from(Rails.root.join("app/javascript/controllers"))
+    end
+
+    task :update do
+      manifest =
+        Stimulus::Manifest.generate_from(Rails.root.join("app/javascript/controllers"))
 
-    desc "Install Stimulus on the app with webpacker"
-    task :webpacker do
-      run_stimulus_install_template "stimulus_with_webpacker"
+      File.open(Rails.root.join("app/javascript/controllers/index.js"), "w+") do |index|
+        index.puts "// This file is auto-generated by ./bin/rails stimulus:manifest:update"
+        index.puts "// Run that command whenever you add a new controller"
+        index.puts
+        index.puts %(import { application } from "./application")
+        index.puts manifest
+      end
     end
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: stimulus-rails
 version: !ruby/object:Gem::Version
-  version: 0.3.11
+  version: 0.5.0
 platform: ruby
 authors:
 - Sam Stephenson
@@ -10,7 +10,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2021-08-31 00:00:00.000000000 Z
+date: 2021-09-10 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -40,12 +40,18 @@ files:
 - app/assets/javascripts/stimulus.js
 - app/assets/javascripts/stimulus@2.js
 - app/assets/javascripts/stimulus@3.0.0-beta.1.js
+- lib/generators/stimulus/USAGE
+- lib/generators/stimulus/stimulus_generator.rb
+- lib/generators/stimulus/templates/controller.js.tt
+- lib/install/app/javascript/controllers/application.js
 - lib/install/app/javascript/controllers/hello_controller.js
-- lib/install/app/javascript/controllers/index.js
-- lib/install/stimulus_with_asset_pipeline.rb
-- lib/install/stimulus_with_webpacker.rb
+- lib/install/app/javascript/controllers/index_for_importmap.js
+- lib/install/app/javascript/controllers/index_for_node.js
+- lib/install/stimulus_with_importmap.rb
+- lib/install/stimulus_with_node.rb
 - lib/stimulus-rails.rb
 - lib/stimulus/engine.rb
+- lib/stimulus/manifest.rb
 - lib/stimulus/version.rb
 - lib/tasks/stimulus_tasks.rake
 homepage: https://stimulus.hotwired.dev

data/lib/install/app/javascript/controllers/index.js

@@ -1,9 +0,0 @@
-// Load all the controllers within this directory and all subdirectories. 
-// Controller files must be named *_controller.js or *_controller.ts.
-
-import { Application } from "stimulus"
-import { definitionsFromContext } from "stimulus/webpack-helpers"
-
-window.Stimulus = Application.start()
-const context = require.context("controllers", true, /_controller\.(js|ts)$/)
-Stimulus.load(definitionsFromContext(context))

data/lib/install/stimulus_with_asset_pipeline.rb

@@ -1,26 +0,0 @@
-APP_JS_ROOT = Rails.root.join("app/javascript")
-APP_JS_PATH = APP_JS_ROOT.join("application.js")
-IMPORTMAP_PATH = Rails.root.join("config/importmap.rb")
-
-if APP_JS_PATH.exist?
-  say "Import Stimulus importmap autoloader in existing app/javascript/application.js"
-  append_to_file APP_JS_PATH, %(\nimport "@hotwired/stimulus-importmap-autoloader"\n)
-else
-  say <<~INSTRUCTIONS, :red
-    You must import @hotwired/stimulus and @hotwired/stimulus-importmap-autoloader in your application.js.
-  INSTRUCTIONS
-end
-
-say "Creating controllers directory"
-copy_file "#{__dir__}/app/javascript/controllers/hello_controller.js", APP_JS_ROOT.join("controllers/hello_controller.js")
-
-if IMPORTMAP_PATH.exist?
-  say "Pin @hotwired/stimulus and @hotwired/stimulus-importmap-autoloader in config/importmap.rb"
-  append_to_file \
-    IMPORTMAP_PATH.to_s, 
-    %(pin "@hotwired/stimulus", to: "stimulus.js"\npin "@hotwired/stimulus-importmap-autoloader", to: "stimulus-importmap-autoloader.js"\npin_all_from "app/javascript/controllers", under: "controllers"\n)
-else
-  say <<~INSTRUCTIONS, :red
-    You must add @hotwired/stimulus and @hotwired/stimulus-importmap-autoloader to your importmap to reference them via ESM.
-  INSTRUCTIONS
-end

data/lib/install/stimulus_with_webpacker.rb

@@ -1,11 +0,0 @@
-say "Appending Stimulus setup code to #{Webpacker.config.source_entry_path}/application.js"
-append_to_file "#{Webpacker.config.source_entry_path}/application.js", %(\nimport "controllers")
-
-say "Creating controllers directory"
-directory "#{__dir__}/app/javascript/controllers", "#{Webpacker.config.source_path}/controllers"
-
-say "Using Stimulus NPM package"
-gsub_file "#{Webpacker.config.source_path}/controllers/hello_controller.js", /@hotwired\//, ''
-
-say "Installing all Stimulus dependencies"
-run "yarn add stimulus"