stimulus-rails 0.2.4 → 1.0.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d7b182fb2a48a9405b734b3d8180930f181cf115cb52b7d9061f3f92183d2f3e
-  data.tar.gz: 663e24b437761d3ff60ad7e78e8dc9ac9191ad91b83935ae95a04100dd6c66c2
+  metadata.gz: 0ffd052c8f30205c21d994289dc5f4938f7926db658ac93a9e6264f1ff63810f
+  data.tar.gz: bafd756e667681009804b4387a04674d8af0b8a868873978f17bfea2759196de
 SHA512:
-  metadata.gz: 0d84fd49c9ad55572e525b5239b289fbe9a01839f67a24453efa875357ab0a0ecb30f39bc43df447d565dd75cda282ab21c653e09ff7db36d1150136b53fcbb0
-  data.tar.gz: 9e3bfa7a5be5a8457a3612863d7b136fd3c3e514f04367ceacce7327050f2403b69f18305c598cc07311a89cb3fa55c1f4aeb667c0f73e0c76cc15bdc8e684c7
+  metadata.gz: 9fb58d85d883bd881b1ad7a9d1478a98f57d26b41f9c844d27ffebe6020f0f7d578952e401e8057ab5555b69df63def79f8900f4b54b6115c83f25afb5080fa3
+  data.tar.gz: 386899154a67d5e79c9ca964757ba40d387367ce65309cbb704d1075d898d095f748478198eb30918af3783b9a7a6938e697b75f8bcf3f20bd014146d753f7d3

data/MIT-LICENSE

@@ -1,4 +1,4 @@
-Copyright (c) 2020 Basecamp
+Copyright (c) 2021 Basecamp
 
 Permission is hereby granted, free of charge, to any person obtaining
 a copy of this software and associated documentation files (the

data/README.md

@@ -1,70 +1,140 @@
 # Stimulus for Rails
 
-[Stimulus](https://stimulus.hotwire.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.
+[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 uses the 7kb es-module-shim to provide [importmap](https://github.com/WICG/import-maps) support for all ES6-compatible browsers. This means you can develop and deploy without using any bundling or transpiling at all! Far less complexity, no waiting for compiling.
+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!
 
-If you want to use Stimulus with a bundler, you should use [Webpacker](https://github.com/rails/webpacker) instead. This gem is purely intended for those who wish to use Stimulus with the asset pipeline using ESM in the browser.
 
 ## Installation
 
+This gem is automatically configured for applications made with Rails 7+ (unless `--skip-hotwire` is passed to the generator). But if you're on Rails 6, you can install it with the installer or manually:
+
+### Installing with installer
+
 1. Add the `stimulus-rails` gem to your Gemfile: `gem 'stimulus-rails'`
 2. Run `./bin/bundle install`.
 3. Run `./bin/rails stimulus:install`
 
-If using the asset pipeline to manage JavaScript, the last command will:
+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.
 
-1. Create an example controller in `app/assets/javascripts/controllers/hello_controller.js`.
-2. Append the include tags to the `<head>` of your `app/views/layouts/application.html.erb`.
-3. Initialize your `importmap.json` in `app/assets/javascripts/importmap.json.erb`.
-4. Ensure JavaScript is included in your `app/assets/config/manifest.js` file for compilation.
+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.
 
-If using Webpacker to manage JavaScript, the last command will:
+### Installing manually
 
-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.
+Note that we recommend running the installer as described above. But the following is helpful if you encounter errors while running the installer (e.g., if there are conflicts with existing files) or if you just like doing stuff manually. Follow the instructions for import map *or* JavaScript bundler, depending on your setup.
 
-## Usage
+1. Add the `stimulus-rails` gem to your Gemfile: `gem 'stimulus-rails'`
+2. Run `./bin/bundle install`.
 
-With the Stimulus include tags added, 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.
+#### With import map
 
-For example, a more advanced `hello_controller` could look like this:
+3. Create `app/javascript/controllers/index.js` and load your controllers like this:
+```javascript
+import { application } from "controllers/application"
+
+// Eager load all controllers defined in the import map under controllers/**/*_controller
+import { eagerLoadControllersFrom } from "@hotwired/stimulus-loading"
+eagerLoadControllersFrom("controllers", application)
+```
 
+4. Create `app/javascript/controllers/application.js` with the following content:
 ```javascript
-// app/assets/javascripts/controllers/hello_controller.js
-import { Controller } from "stimulus"
+import { Application } from "@hotwired/stimulus"
 
-export default class extends Controller {
-  static targets = [ "name", "output" ]
+const application = Application.start()
 
-  greet() {
-    this.outputTarget.textContent = `Hello, ${this.nameTarget.value}!`
-  }
-}
+// Configure Stimulus development experience
+application.debug = false
+window.Stimulus   = application
+
+export { application }
+```
+
+5. Add the following line to `app/javascript/application.js` to import all your controllers:
+```javascript
+import "controllers"
+```
+
+6. Finally, Pin Stimulus and controllers in `config/importmap.rb` by adding:
+```ruby
+pin "@hotwired/stimulus", to: "stimulus.min.js", preload: true
+pin "@hotwired/stimulus-loading", to: "stimulus-loading.js", preload: true
+pin_all_from "app/javascript/controllers", under: "controllers"
+
+```
+
+#### With JavaScript bundler
+
+3. Create `app/javascript/controllers/index.js` and load your controllers.
+
+Make sure to change `HelloController` to an actual controller and repeat for every controller you have or use the command mentioned in the comments below:
+```javascript
+// This file is auto-generated by ./bin/rails stimulus:manifest:update
+// Run that command whenever you add a new controller or create them with
+// ./bin/rails generate stimulus controllerName
+
+import { application } from "./application"
+
+import HelloController from "./hello_controller"
+application.register("hello", HelloController)
 ```
 
-And it'll be activated and registered automatically when encountering the data-controller attribute in your DOM:
+4. Create `app/javascript/controllers/application.js` with the following content:
+```javascript
+import { Application } from "@hotwired/stimulus"
+
+const application = Application.start()
 
-```html
-<div data-controller="hello">
-  <input data-hello-target="name" type="text">
+// Configure Stimulus development experience
+application.debug = false
+window.Stimulus   = application
 
-  <button data-action="click->hello#greet">
-    Greet
-  </button>
+export { application }
+```
+
+5. Add the following line to `app/javascript/application.js` to import all your controllers:
+```javascript
+import "controllers"
+```
 
-  <span data-hello-target="output">
-  </span>
-</div>
+6. Finally, add the Stimulus package to yarn:
+```bash
+yarn add @hotwired/stimulus
 ```
 
-That's it!
 
-You can add additional libraries needed by your controllers in `app/assets/javascripts/libraries` using the `library@1.0.0.js` naming convention. These libraries will be added to the dynamically generated [importmap](https://github.com/WICG/import-maps) (a shim is included with the `stimulus_include_tags`), so you can reference `cookies@0.5.6.js` as `import Cookie from "cookies"`.
+## 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.
+
+
+## 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.
 
-The libraries must be made for ESM. See https://skypack.dev where you can either directly reference libraries or download them and use them with the ESM conversion.
+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 "@hotwired/stimulus"
+
+// Connects with data-controller="hello"
+export default class extends Controller {
+  static targets = [ "name", "output" ]
+
+  greet() {
+    this.outputTarget.textContent = `Hello, ${this.nameTarget.value}!`
+  }
+}
+```
 
 
 ## License

data/app/assets/javascripts/{stimulus/loaders/autoloader.js → stimulus-autoloader.js}

@@ -1,4 +1,4 @@
-import { Application } from "stimulus"
+import { Application } from "@hotwired/stimulus"
 
 const application = Application.start()
 const { controllerAttribute } = application.schema
@@ -19,11 +19,11 @@ function extractControllerNamesFrom(element) {
 function loadController(name) {
   import(controllerFilename(name))
     .then(module => registerController(name, module))
-    .catch(error => console.log(`Failed to autoload controller: ${name}`, error))
+    .catch(error => console.error(`Failed to autoload controller: ${name}`, error))
 }
 
 function controllerFilename(name) {
-  return `${name.replace(/--/g, "/").replace(/-/g, "_")}_controller`
+  return `controllers/${name.replace(/--/g, "/").replace(/-/g, "_")}_controller`
 }
 
 function registerController(name, module) {
@@ -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

@@ -0,0 +1,27 @@
+// FIXME: es-module-shim won't shim the dynamic import without this explicit import
+import "@hotwired/stimulus"
+
+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, application) {
+  const name = path
+    .replace(new RegExp(`^${under}/`), "")
+    .replace("_controller", "")
+    .replace(/\//g, "--")
+    .replace(/_/g, "-")
+
+  import(path)
+    .then(module => application.register(name, module.default))
+    .catch(error => console.error(`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,85 @@
+// 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, "-")
+
+  if (!(name in registeredControllers)) {
+    import(path)
+      .then(module => registerController(name, module, application))
+      .catch(error => console.error(`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) {
+  if (!(name in registeredControllers)) {
+    import(controllerFilename(name, under))
+      .then(module => registerController(name, module, application))
+      .catch(error => console.error(`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)) {
+    application.register(name, module.default)
+    registeredControllers[name] = true
+  }
+}