stimulus-rails 0.6.2 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: af74b14f711ea67c26426322da6d6ae36c41db6757a56ae254bad08ccfc2a6b8
-  data.tar.gz: 2bdbda7a1fd90f0cd964831f88cef4f269c92b560815012eb9875f12b0a0e406
+  metadata.gz: 664260a2f344790d144309fde0bcec8ced34dd3efd7ee4d64a1615e264bb2402
+  data.tar.gz: 02f64ba22c5783d1003d5cf47b8d307a88633544a1d90fb1ab4bf38382f58952
 SHA512:
-  metadata.gz: 56334a9ca151712aec54fb89f8459ade60ae68dee9646e9234ed6b50da3c662d11d0bb890329e27f6ded8d8e1ddc9467cae94447d3f46173a568c0f6ddb7381d
-  data.tar.gz: f3981eec7f58455483f9f0049b6e1680ff2b808d538d220e872284a2068adb5af70289c1430d89a08042577716527c1e440c20bc0a50a30d6a34b873f51d45c9
+  metadata.gz: a887a7a83ea54b73f92956ccdfa5e1d2e0410547505fd9eb70011db6989cfb82ba796e9dc44d73f764023dfab2e133a10cb8a4192126a2856a0b4e4e424c9edd
+  data.tar.gz: 3e4cdc03165d6c021deedaedbb3bbfe5205e7126a021c169bc32e9724a5ede72a8d36fc407a81585291f46110760208e244441dcca8f0c07531ab365dd889981

data/README.md

@@ -2,7 +2,7 @@
 
 [Stimulus](https://stimulus.hotwired.dev) is a JavaScript framework with modest ambitions. It doesn’t seek to take over your entire front-end in fact, it’s not concerned with rendering HTML at all. Instead, it’s designed to augment your HTML with just enough behavior to make it shine. Stimulus pairs beautifully with Turbo to provide a complete solution for fast, compelling applications with a minimal amount of effort. Together they form the core of [Hotwire](https://hotwired.dev).
 
-Stimulus for Rails makes it easy to use this modest framework with the asset pipeline and ES6/ESM in the browser. It relies on either `importmap-rails` to make Stimulus available via ESM or a node-capable Rails (like via `jsbundling-rails`) to include Stimulus in the bundle. Make sure to install one of these first!
+Stimulus for Rails makes it easy to use this modest framework with both import-mapped and JavaScript-bundled apps. It relies on either `importmap-rails` to make Stimulus available via ESM or a Node-capable Rails (like via `jsbundling-rails`) to include Stimulus in the bundle. Make sure to install one of these first!
 
 
 ## Installation
@@ -11,14 +11,25 @@ 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`
 
-The installer will automatically detect whether you're using an [import map](https://github.com/rails/importmap-rails) or [JavaScript bundler](https://github.com/rails/jsbundling-rails) 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.
+The installer will automatically detect whether you're using an [import map](https://github.com/rails/importmap-rails) or [JavaScript bundler](https://github.com/rails/jsbundling-rails) 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.
 
+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.
 
-## Usage
 
-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.
+## Usage with import map
+
+With an import-mapped application, controllers are automatically pinned and registered based on the file structure. The installer will amend your `config/importmap.rb` to configure this such that all controllers in `app/javascript/controllers` are pinned.
+
+By default, your application will be setup to eager load all the controllers mentioned in your import map under "controllers". This works well together with preloading in the import map when you have a modest number of controllers.
+
+If you have a lot of controllers, you may well want to lazy load them instead. This can be done by changing from `eagerLoadControllersFrom` to `lazyLoadControllersFrom` in your `app/javascript/controllers/index.js` file.
+
+When lazy loading, controllers are not loaded until their data-controller identifier is encountered in the DOM.
+
 
-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.
+## Usage with JavaScript bundler
+
+With an application using a JavaScript bundler, controllers need to be imported and registered directly in the index.js file. But this can be 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.
 
 You're encouraged to use the generator to add new controllers like so:
 
@@ -38,23 +49,6 @@ export default class extends Controller {
 }
 ```
 
-And it'll be activated and registered automatically when encountering the data-controller attribute in your DOM:
-
-```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>
-```
-
-That's it!
-
 
 ## License
 

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

@@ -50,3 +50,5 @@ new MutationObserver((mutationsList) => {
 }).observe(document, { attributeFilter: [controllerAttribute], subtree: true, childList: true })
 
 autoloadControllersWithin(document)
+
+console.warn("stimulus-autoload.js has been deprecated in favor of stimulus-loading.js")

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

@@ -23,3 +23,5 @@ function registerControllerFromPath(path, under, application) {
     .then(module => application.register(name, module.default))
     .catch(error => console.log(`Failed to register controller: ${name} (${path})`, error))
 }
+
+console.warn("stimulus-importmap-autoload.js has been deprecated in favor of stimulus-loading.js")

data/app/assets/javascripts/stimulus-loading.js

@@ -0,0 +1,81 @@
+// FIXME: es-module-shim won't shim the dynamic import without this explicit import
+import "@hotwired/stimulus"
+
+const controllerAttribute = "data-controller"
+const registeredControllers = {}
+
+// Eager load all controllers registered beneath the `under` path in the import map to the passed application instance.
+export function eagerLoadControllersFrom(under, application) {
+  const paths = Object.keys(parseImportmapJson()).filter(path => path.match(new RegExp(`^${under}/.*_controller$`)))
+  paths.forEach(path => registerControllerFromPath(path, under, application))
+}
+
+function parseImportmapJson() {
+  return JSON.parse(document.querySelector("script[type=importmap]").text).imports
+}
+
+function registerControllerFromPath(path, under, application) {
+  const name = path
+    .replace(new RegExp(`^${under}/`), "")
+    .replace("_controller", "")
+    .replace(/\//g, "--")
+    .replace(/_/g, "-")
+
+  import(path)
+    .then(module => registerController(name, module, application))
+    .catch(error => console.debug(`Failed to register controller: ${name} (${path})`, error))
+}
+
+
+// Lazy load controllers registered beneath the `under` path in the import map to the passed application instance.
+export function lazyLoadControllersFrom(under, application, element = document) {
+  lazyLoadExistingControllers(under, application, element)
+  lazyLoadNewControllers(under, application, element)
+}
+
+function lazyLoadExistingControllers(under, application, element) {
+  queryControllerNamesWithin(element).forEach(controllerName => loadController(controllerName, under, application))
+}
+
+function lazyLoadNewControllers(under, application, element) {
+  new MutationObserver((mutationsList) => {
+    for (const { attributeName, target, type } of mutationsList) {
+      switch (type) {
+        case "attributes": {
+          if (attributeName == controllerAttribute && target.getAttribute(controllerAttribute)) {
+            extractControllerNamesFrom(target).forEach(controllerName => loadController(controllerName, under, application))
+          }
+        }
+
+        case "childList": {
+          lazyLoadExistingControllers(under, application, target)
+        }
+      }
+    }
+  }).observe(element, { attributeFilter: [controllerAttribute], subtree: true, childList: true })
+}
+
+function queryControllerNamesWithin(element) {
+  return Array.from(element.querySelectorAll(`[${controllerAttribute}]`)).map(extractControllerNamesFrom).flat()
+}
+
+function extractControllerNamesFrom(element) {
+  return element.getAttribute(controllerAttribute).split(/\s+/).filter(content => content.length)
+}
+
+function loadController(name, under, application) {
+  import(controllerFilename(name, under))
+    .then(module => registerController(name, module, application))
+    .catch(error => console.debug(`Failed to autoload controller: ${name}`, error))
+}
+
+function controllerFilename(name, under) {
+  return `${under}/${name.replace(/--/g, "/").replace(/-/g, "_")}_controller`
+}
+
+function registerController(name, module, application) {
+  if (name in registeredControllers) return
+
+  application.register(name, module.default)
+  registeredControllers[name] = true
+}

data/app/assets/javascripts/stimulus.js

@@ -1,5 +1,6 @@
 //= link ./stimulus-autoloader.js
 //= link ./stimulus-importmap-autoloader.js
+//= link ./stimulus-loading.js
 
 /*
 Stimulus 3.0.1

data/app/assets/javascripts/stimulus.min.js

@@ -1,5 +1,6 @@
 //= link ./stimulus-autoloader.js
 //= link ./stimulus-importmap-autoloader.js
+//= link ./stimulus-loading.js
 
 /*
 Stimulus 3.0.1

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

@@ -1,5 +1,11 @@
 // 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)
+
+// Eager load all controllers defined in the import map under controllers/**/*_controller
+import { eagerLoadControllersFrom } from "@hotwired/stimulus-loading"
+eagerLoadControllersFrom("controllers", application)
+
+// Lazy load controllers as they appear in the DOM (remember not to preload controllers in import map!)
+// import { lazyLoadControllersFrom } from "@hotwired/stimulus-loading"
+// lazyLoadControllersFrom("controllers", application)

data/lib/install/stimulus_with_importmap.rb

@@ -13,7 +13,7 @@ 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 "@hotwired/stimulus-loading", to: "stimulus-loading.js"
 pin_all_from "app/javascript/controllers", under: "controllers"
 RUBY
 end

data/lib/stimulus/version.rb

@@ -1,3 +1,3 @@
 module Stimulus
-  VERSION = "0.6.2"
+  VERSION = "0.7.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: stimulus-rails
 version: !ruby/object:Gem::Version
-  version: 0.6.2
+  version: 0.7.0
 platform: ruby
 authors:
 - Sam Stephenson
@@ -37,6 +37,7 @@ files:
 - Rakefile
 - app/assets/javascripts/stimulus-autoloader.js
 - app/assets/javascripts/stimulus-importmap-autoloader.js
+- app/assets/javascripts/stimulus-loading.js
 - app/assets/javascripts/stimulus.js
 - app/assets/javascripts/stimulus.min.js
 - lib/generators/stimulus/USAGE