stimulus_reflex 3.5.0.pre8 → 3.5.0.pre10

data/lib/generators/stimulus_reflex/templates/app/javascript/controllers/%file_name%_controller.js.tt

@@ -1,101 +1,141 @@
 import ApplicationController from './application_controller'
 
-/* This is the custom StimulusReflex controller for the <%= class_name %> Reflex.
- * Learn more at: https://docs.stimulusreflex.com
- */
-export default class extends ApplicationController {
-  /*
-   * Regular Stimulus lifecycle methods
-   * Learn more at: https://stimulusjs.org/reference/lifecycle-callbacks
-   *
-   * If you intend to use this controller as a regular stimulus controller as well,
-   * make sure any Stimulus lifecycle methods overridden in ApplicationController call super.
-   *
-   * Important:
-   * By default, StimulusReflex overrides the -connect- method so make sure you
-   * call super if you intend to do anything else when this controller connects.
-  */
+<%- if class_name == "Example" -%>
+// 
+// This is the Stimulus controller for the Example Reflex.
+//
+// It corresponds to the server-side Reflex class located at /app/reflexes/example.rb
+//
+// Learn more at: https://docs.stimulusreflex.com/guide/reflexes
+//
 
+<%- end -%>
+export default class extends ApplicationController {
   connect () {
+<%- if class_name == "Example" -%>
+    //
+    // StimulusReflex overrides the Stimulus `connect` method. Make sure to call
+    // `super.connect()` so that any code in your superclass `connect` is run.
+    //
+<%- end -%>
     super.connect()
-    // add your code here, if applicable
   }
+<%- if class_name == "Example" -%>
 
-  /* Reflex specific lifecycle methods.
-   *
-   * For every method defined in your Reflex class, a matching set of lifecycle methods become available
-   * in this javascript controller. These are optional, so feel free to delete these stubs if you don't
-   * need them.
-   *
-   * Important:
-   * Make sure to add data-controller="<%= class_name.underscore.dasherize %>" to your markup alongside
-   * data-reflex="<%= class_name %>#dance" for the lifecycle methods to fire properly.
-   *
-   * Example:
-   *
-   *   <a href="#" data-reflex="click-><%= class_name %>#dance" data-controller="<%= class_name.underscore.dasherize %>">Dance!</a>
-   *
-   * Arguments:
-   *
-   *   element - the element that triggered the reflex
-   *             may be different than the Stimulus controller's this.element
-   *
-   *   reflex - the name of the reflex e.g. "<%= class_name %>#dance"
-   *
-   *   error/noop - the error message (for reflexError), otherwise null
-   *
-   *   reflexId - a UUID4 or developer-provided unique identifier for each Reflex
-   */
-
-<% if actions.empty? -%>
-  // Assuming you create a "<%= class_name %>#dance" action in your Reflex class
-  // you'll be able to use the following lifecycle methods:
-
-  // beforeDance(element, reflex, noop, reflexId) {
-  //  element.innerText = 'Putting dance shoes on...'
+  // With StimulusReflex active in your project, it will continuously scan your DOM for
+  // `data-reflex` attributes on your elements, even if they are dynamically created.
+  //
+  //   <a href="#" data-reflex="click->Example#dance">Dance!</a>
+  //
+  // We call this a "declared" Reflex, because it doesn't require any JS to run.
+  //
+  // When your user clicks this link, a Reflex is launched and it calls the `dance` method
+  // on your Example Reflex class. You don't have to do anything else!
+  //
+  // This Stimulus controller doesn't even need to exist for StimulusReflex to work its magic.
+  // https://docs.stimulusreflex.com/guide/reflexes#declaring-a-reflex-in-html-with-data-attributes
+  //
+  // However...
+  //
+  // If we do create an `example` Stimulus controller that extends `ApplicationController`,
+  // we can unlock several additional capabilities, including creating Reflexes with code.
+  //
+  //   <a href="#" data-controller="example" data-action="example#dance">Dance!</a>
+  //
+  // StimulusReflex gives our controller a new method, `stimulate`:
+  //
+  // dance() {
+  //   this.stimulate('Example#dance')
   // }
+  //
+  // The `stimulate` method is very flexible, and it gives you the opportunity to pass
+  // parameter options that will be passed to the `dance` method on the server.
+  // https://docs.stimulusreflex.com/guide/reflexes#calling-a-reflex-in-a-stimulus-controller
+  //
+  // Reflex lifecycle methods
+  //
+  // For every method defined in your Reflex class, a matching set of optional
+  // lifecycle callback methods become available in this javascript controller.
+  // https://docs.stimulusreflex.com/guide/lifecycle#client-side-reflex-callbacks
+  //
+  //   <a href="#" data-reflex="click->Example#dance" data-controller="example">Dance!</a>
+  //
+  // StimulusReflex will check for the presence of several methods:
+  //
+  //   afterReflex(element, reflex, noop, id) {
+  //     // fires after every Example Reflex action
+  //   }
+  //
+  //   afterDance(element, reflex, noop, id) {
+  //     // fires after Example Reflexes calling the dance action
+  //   }
+  //
+  // Arguments:
+  //
+  //   element - the element that triggered the reflex
+  //             may be different than the Stimulus controller's this.element
+  //
+  //   reflex - the name of the reflex e.g. "Example#dance"
+  //
+  //   error/noop - the error message (for reflexError), otherwise null
+  //
+  //   id - a UUID4 or developer-provided unique identifier for each Reflex
+  //
+  // Access to the client-side Reflex objects created by this controller
+  //
+  // Every Reflex you create is represented by an object in the global Reflexes collection.
+  // You can access the Example Reflexes created by this controller via the `reflexes` proxy.
+  //
+  //   this.reflexes.last
+  //   this.reflexes.all
+  //   this.reflexes.all[id]
+  //   this.reflexes.error
+  //
+  // The proxy allows you to access the most recent Reflex, an array of all Reflexes, a specific
+  // Reflex specified by its `id` and an array of all Reflexes in a given lifecycle stage.
+  //
+  // If you explore the Reflex object, you'll see all relevant details,
+  // including the `data` that is being delivered to the server.
+  //
+  // Pretty cool, right?
+  //
+<%- end -%>
+<%- actions.each do |action| -%>
 
-  // danceSuccess(element, reflex, noop, reflexId) {
-  //   element.innerText = '\nDanced like no one was watching! Was someone watching?'
+  // <%= "before_#{action}".camelize(:lower) %>(element, reflex, noop, id) {
+  //  console.log("before <%= action %>", element, reflex, id)
   // }
 
-  // danceError(element, reflex, error, reflexId) {
-  //   console.error('danceError', error);
-  //   element.innerText = "\nCouldn\'t dance!"
+  // <%= "#{action}_queued".camelize(:lower) %>(element, reflex, noop, id) {
+  //   console.log("<%= action %> enqueued for delivery upon connection", element, reflex, id)
   // }
 
-  // afterDance(element, reflex, noop, reflexId) {
-  //   element.innerText = '\nWhatever that was, it\'s over now.'
+  // <%= "#{action}_delivered".camelize(:lower) %>(element, reflex, noop, id) {
+  //   console.log("<%= action %> delivered to the server", element, reflex, id)
   // }
 
-  // finalizeDance(element, reflex, noop, reflexId) {
-  //   element.innerText = '\nNow, the cleanup can begin!'
-  // }
-<% end -%>
-<% actions.each do |action| -%>
-  // <%= "before_#{action}".camelize(:lower) %>(element, reflex, noop, reflexId) {
-  //  console.log("before <%= action %>", element, reflex, reflexId)
+  // <%= "#{action}_success".camelize(:lower) %>(element, reflex, noop, id) {
+  //   console.log("<%= action %> successfully executed", element, reflex, id)
   // }
 
-  // <%= "#{action}_success".camelize(:lower) %>(element, reflex, noop, reflexId) {
-  //   console.log("<%= action %> success", element, reflex, reflexId)
+  // <%= "#{action}_error".camelize(:lower) %>(element, reflex, error, id) {
+  //   console.error("<%= action %> server-side error", element, reflex, error, id)
   // }
 
-  // <%= "#{action}_error".camelize(:lower) %>(element, reflex, error, reflexId) {
-  //   console.error("<%= action %> error", element, reflex, error, reflexId)
+  // <%= "#{action}_halted".camelize(:lower) %>(element, reflex, noop, id) {
+  //   console.warn("<%= action %> halted before execution", element, reflex, id)
   // }
 
-  // <%= "#{action}_halted".camelize(:lower) %>(element, reflex, noop, reflexId) {
-  //   console.warn("<%= action %> halted", element, reflex, reflexId)
+  // <%= "#{action}_forbidden".camelize(:lower) %>(element, reflex, noop, id) {
+  //   console.warn("<%= action %> forbidden from executing", element, reflex, id)
   // }
 
-  // <%= "after_#{action}".camelize(:lower) %>(element, reflex, noop, reflexId) {
-  //   console.log("after <%= action %>", element, reflex, reflexId)
+  // <%= "after_#{action}".camelize(:lower) %>(element, reflex, noop, id) {
+  //   console.log("<%= action %> has been executed by the server", element, reflex, id)
   // }
 
-  // <%= "finalize_#{action}".camelize(:lower) %>(element, reflex, noop, reflexId) {
-  //   console.log("finalize <%= action %>", element, reflex, reflexId)
+  // <%= "finalize_#{action}".camelize(:lower) %>(element, reflex, noop, id) {
+  //   console.log("<%= action %> changes have been applied", element, reflex, id)
   // }
-<%= "\n" unless action == actions.last -%>
-<% end -%>
+<%- end -%>
 }

data/lib/generators/stimulus_reflex/templates/app/javascript/controllers/application.js.tt

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

data/lib/generators/stimulus_reflex/templates/app/javascript/controllers/application_controller.js.tt

@@ -1,60 +1,74 @@
-import { Controller } from 'stimulus'
+import { Controller } from '@hotwired/stimulus'
 import StimulusReflex from 'stimulus_reflex'
 
-/* This is your ApplicationController.
- * All StimulusReflex controllers should inherit from this class.
- *
- * Example:
- *
- *   import ApplicationController from './application_controller'
- *
- *   export default class extends ApplicationController { ... }
- *
- * Learn more at: https://docs.stimulusreflex.com
- */
+// This is the Stimulus ApplicationController.
+// All StimulusReflex controllers should inherit from this class.
+//
+// Example:
+//
+//   import ApplicationController from './application_controller'
+//
+//   export default class extends ApplicationController { ... }
+//
+// Learn more at: https://docs.stimulusreflex.com
+//
+
 export default class extends Controller {
   connect () {
     StimulusReflex.register(this)
   }
 
-  /* Application-wide lifecycle methods
-   *
-   * Use these methods to handle lifecycle concerns for the entire application.
-   * Using the lifecycle is optional, so feel free to delete these stubs if you don't need them.
-   *
-   * Arguments:
-   *
-   *   element - the element that triggered the reflex
-   *             may be different than the Stimulus controller's this.element
-   *
-   *   reflex - the name of the reflex e.g. "Example#demo"
-   *
-   *   error/noop - the error message (for reflexError), otherwise null
-   *
-   *   reflexId - a UUID4 or developer-provided unique identifier for each Reflex
-   */
-
-  beforeReflex (element, reflex, noop, reflexId) {
+  // Application-wide lifecycle methods
+  //
+  // Use these methods to handle lifecycle callbacks for all controllers.
+  // Using lifecycle methods is optional, so feel free to delete these if you don't need them.
+  //
+  // Arguments:
+  //
+  //   element - the element that triggered the reflex
+  //             may be different than the Stimulus controller's this.element
+  //
+  //   reflex - the name of the reflex e.g. "Example#demo"
+  //
+  //   error/noop - the error message (for reflexError), otherwise null
+  //
+  //   id - a UUID4 or developer-provided unique identifier for each Reflex
+  //
+
+  beforeReflex (element, reflex, noop, id) {
     // document.body.classList.add('wait')
   }
 
-  reflexSuccess (element, reflex, noop, reflexId) {
+  reflexQueued (element, reflex, noop, id) {
+    // Reflex will be delivered to server upon reconnection
+  }
+
+  reflexDelivered (element, reflex, noop, id) {
+    // Reflex has been delivered to the server
+  }
+
+  reflexSuccess (element, reflex, noop, id) {
     // show success message
   }
 
-  reflexError (element, reflex, error, reflexId) {
+  reflexError (element, reflex, error, id) {
     // show error message
   }
 
-  reflexHalted (element, reflex, error, reflexId) {
+  reflexForbidden (element, reflex, noop, id) {
+    // Reflex action did not have permission to run
+    // window.location = '/'
+  }
+
+  reflexHalted (element, reflex, noop, id) {
     // handle aborted Reflex action
   }
 
-  afterReflex (element, reflex, noop, reflexId) {
+  afterReflex (element, reflex, noop, id) {
     // document.body.classList.remove('wait')
   }
 
-  finalizeReflex (element, reflex, noop, reflexId) {
+  finalizeReflex (element, reflex, noop, id) {
     // all operations have completed, animation etc is now safe
   }
 }

data/lib/generators/stimulus_reflex/templates/app/javascript/controllers/index.js.esbuild.tt

@@ -0,0 +1,7 @@
+import { application } from "./application"
+
+import controllers from "./**/*_controller.js"
+
+controllers.forEach((controller) => {
+  application.register(controller.name, controller.module.default)
+})

data/lib/generators/stimulus_reflex/templates/app/javascript/controllers/index.js.importmap.tt

@@ -0,0 +1,5 @@
+import { application } from "./application"
+
+// Eager load all controllers defined in the import map under controllers/**/*_controller
+import { eagerLoadControllersFrom } from "@hotwired/stimulus-loading"
+eagerLoadControllersFrom("controllers", application)

data/lib/generators/stimulus_reflex/templates/app/javascript/controllers/index.js.shakapacker.tt

@@ -0,0 +1,5 @@
+import { application } from "./application"
+import { definitionsFromContext } from "@hotwired/stimulus-webpack-helpers"
+
+const controllers = definitionsFromContext(require.context("controllers", true, /_controller\.js$/))
+application.load(controllers)

data/lib/generators/stimulus_reflex/templates/app/javascript/controllers/index.js.vite.tt

@@ -0,0 +1,5 @@
+import { application } from "./application"
+import { registerControllers } from "stimulus-vite-helpers"
+
+const controllers = import.meta.globEager("./**/*_controller.js");
+registerControllers(application, controllers)

data/lib/generators/stimulus_reflex/templates/app/javascript/controllers/index.js.webpacker.tt

@@ -0,0 +1,5 @@
+import { application } from "./application"
+import { definitionsFromContext } from "@hotwired/stimulus-webpack-helpers"
+
+const controllers = definitionsFromContext(require.context("controllers", true, /_controller\.js$/))
+application.load(controllers)

data/lib/generators/stimulus_reflex/templates/app/reflexes/%file_name%_reflex.rb.tt

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 class <%= class_name %>Reflex < ApplicationReflex
+<%- if class_name == "Example" -%>
   # Add Reflex methods in this file.
   #
   # All Reflex instances include CableReady::Broadcaster and expose the following properties:
@@ -16,26 +17,56 @@ class <%= class_name %>Reflex < ApplicationReflex
   #     - signed    - use a signed Global ID to map dataset attribute to a model eg. element.signed[:foo]
   #     - unsigned  - use an unsigned Global ID to map dataset attribute to a model  eg. element.unsigned[:foo]
   #   - cable_ready - a special cable_ready that can broadcast to the current visitor (no brackets needed)
-  #   - reflex_id   - a UUIDv4 that uniquely identies each Reflex
+  #   - id          - a UUIDv4 that uniquely identifies each Reflex
   #   - tab_id      - a UUIDv4 that uniquely identifies the browser tab
   #
   # Example:
   #
   #   before_reflex do
   #     # throw :abort # this will prevent the Reflex from continuing
-  #     # learn more about callbacks at https://docs.stimulusreflex.com/rtfm/lifecycle
+  #     # learn more about callbacks at https://docs.stimulusreflex.com/guide/lifecycle
   #   end
   #
   #   def example(argument=true)
-  #     # Your logic here...
+  #     # Your logic here! Update models, launch jobs, poll Redis...
+  #
+  #     # By default, Reflexes call the controller action for the current page and render the view.
   #     # Any declared instance variables will be made available to the Rails controller and view.
+  #
+  #     # You can also use the `morph` method to mark a Reflex as Selector or Nothing.
+  #     # https://docs.stimulusreflex.com/guide/morph-modes#introducing-morphs
   #   end
   #
-  # Learn more at: https://docs.stimulusreflex.com/rtfm/reflex-classes
+  # Learn more at: https://docs.stimulusreflex.com/guide/reflex-classes
+
+<%- end -%>
+<%- if class_name == "Example" -%>
+  def increment
+    count = session[:count] || 0
+    session[:count] = count + 1
+
+    morph "#time", Time.now
+    morph "#count", session[:count]
+
+    cable_ready.set_value(selector: "progress", value: session[:count])
 
-<% actions.each do |action| -%>
+    if session[:count] == 5
+      cable_ready.text_content(selector: "#reload", text: "Try reloading your browser window. The count is persisted in the session!")
+    end
+
+    if session[:count] >= 10
+      cable_ready.dispatch_event(name: "fireworks")
+    end
+  end
+
+  def reset
+    session[:count] = 0
+  end
+<%- else -%>
+  <%- actions.each do |action| -%>
   def <%= action %>
   end
-<%= "\n" unless action == actions.last -%>
-<% end -%>
+  <%= "\n" unless action == actions.last -%>
+  <%- end -%>
+<%- end -%>
 end

data/lib/generators/stimulus_reflex/templates/app/reflexes/application_reflex.rb.tt

@@ -3,11 +3,19 @@
 class ApplicationReflex < StimulusReflex::Reflex
   # Put application-wide Reflex behavior and callbacks in this file.
   #
-  # Learn more at: https://docs.stimulusreflex.com/rtfm/reflex-classes
+  # Learn more at: https://docs.stimulusreflex.com/guide/reflex-classes
   #
   # If your ActionCable connection is: `identified_by :current_user`
   #   delegate :current_user, to: :connection
   #
+  # current_user delegation alloqs you to use the Current pattern, too:
+  #   before_reflex do
+  #     Current.user = current_user
+  #   end
+  #
+  # To access view helpers inside Reflexes:
+  #   delegate :helpers, to: :ApplicationController
+  #
   # If you need to localize your Reflexes, you can set the I18n locale here:
   #
   #   before_reflex do
@@ -15,5 +23,5 @@ class ApplicationReflex < StimulusReflex::Reflex
   #   end
   #
   # For code examples, considerations and caveats, see:
-  # https://docs.stimulusreflex.com/rtfm/patterns#internationalization
+  # https://docs.stimulusreflex.com/guide/patterns#internationalization
 end