Added enableDebug FX

README.md

@@ -66,6 +66,34 @@ In your HTML:
 - whenOutside
 
 
+## Enhanced Stimulus debugging
+
+Stimulus FX offers an experimental enhanced debugging feature that goes beyond Stimulus' standard `debug = true` option. Not only does it show the same details as the default debug option, but it also displays your controller's targets and values.
+
+![Preview of enhanced debugging with Stimulus](https://raw.githubusercontent.com/Rails-Designer/stimulus-fix/main/.github/enhanced-debugging.jpg)
+
+Here's how to set it up:
+
+```diff
+// app/javascript/controllers/application.js
++import { enableDebug } from "stimulus-fx"
+
+-const application = Application.start()
++const application = enableDebug(Application.start())
+```
+
+You can enable debugging for specific controllers:
+
+```diff
+ export default class extends Controller {
++  static debug = true
++
+}
+```
+
+For the best experience, it's recommended to turn off Stimulus' default debug feature when using this enhanced version.
+
+
 ## License
 
 stimulus-fx is released under the [MIT License](https://opensource.org/licenses/MIT).

src/debuggable.js

@@ -0,0 +1,44 @@
+export function debuggable(application, { with: features }) {
+  const register = application.register;
+
+  application.register = function(identifier, controller) {
+    if (!controller.debug) return register.call(application, identifier, controller);
+
+    const callbacks = {
+      initialize: [],
+      connect: [],
+      disconnect: []
+    };
+
+    features.forEach(feature => feature(identifier, callbacks));
+
+    const { initialize, connect, disconnect } = controller.prototype;
+    const methods = { initialize, connect, disconnect };
+
+    controller.prototype.initialize = function() {
+      console.group(`${identifier} controller`);
+
+      callbacks.initialize.forEach(hook => hook.call(this));
+
+      if (methods.initialize) methods.initialize.call(this);
+    };
+
+    controller.prototype.connect = function() {
+      callbacks.connect.forEach(hook => hook.call(this));
+
+      if (methods.connect) methods.connect.call(this);
+
+      console.groupEnd();
+    };
+
+    controller.prototype.disconnect = function() {
+      callbacks.disconnect.forEach(hook => hook.call(this));
+
+      if (methods.disconnect) methods.disconnect.call(this);
+    };
+
+    return register.call(application, identifier, controller);
+  };
+
+  return application;
+}

src/enableDebug.js

@@ -0,0 +1,14 @@
+import { debuggable } from "./debuggable";
+import { initialize } from "./enableDebug/initialize";
+import { values } from "./enableDebug/values";
+import { targets } from "./enableDebug/targets";
+
+export function enableDebug(application) {
+  const debugFeatures = [
+    initialize,
+    targets,
+    values
+  ];
+
+  return debuggable(application, { with: debugFeatures });
+}

src/enableDebug/initialize.js

@@ -0,0 +1,22 @@
+export function initialize(identifier, callbacks) {
+  const debugCallback = ({ for: lifecycle }) => ({
+    log(context) {
+      console.group(`#${lifecycle}`);
+
+      console.log("details:", {
+        application: context.application,
+        identifier,
+        controller: context,
+        element: context.element
+      });
+
+      console.groupEnd();
+    }
+  });
+
+  ["initialize", "connect", "disconnect"].forEach(lifecycle => {
+    callbacks[lifecycle].push(function() {
+      debugCallback({ for: lifecycle }).log(this);
+    });
+  });
+}

src/enableDebug/targets.js

@@ -0,0 +1,41 @@
+export function targets(identifier, callbacks) {
+  callbacks.connect.push(function() {
+    logTargets({ on: this.element, for: identifier });
+  });
+}
+
+function logTargets({ on: element, for: identifier }) {
+  const targets = allTargets(element, identifier);
+
+  if (Object.keys(targets).length === 0) return;
+
+  console.group("Targets");
+  console.table(formatted(targets))
+  console.groupEnd();
+}
+
+function allTargets(element, identifier) {
+  const targets = {};
+  const targetElements = element.querySelectorAll(`[data-${identifier}-target]`);
+
+  targetElements.forEach(targetElement => {
+    const targetNames = targetElement.getAttribute(`data-${identifier}-target`).split(" ");
+
+    targetNames.forEach(targetName => {
+      if (!targets[targetName]) targets[targetName] = [];
+
+      targets[targetName].push(targetElement);
+    });
+  });
+
+  return targets;
+}
+
+function formatted(targets) {
+  return Object.fromEntries(
+    Object.entries(targets).map(([name, elements]) => [
+      name,
+      { count: elements.length, elements }
+    ])
+  );
+}

src/enableDebug/values.js

@@ -0,0 +1,36 @@
+export function values(identifier, callbacks) {
+  callbacks.connect.push(function() {
+    logValues({ on: this.element, for: identifier });
+  });
+}
+
+function logValues({ on: element, for: identifier }) {
+  const values = allValues(element, identifier);
+
+  if (Object.keys(values).length === 0) return;
+
+  console.group("Values");
+  console.table(values);
+  console.groupEnd();
+}
+
+function allValues(element, identifier) {
+  const prefix = `${identifier}-`;
+  const dataPrefix = "data-";
+  const valueSuffix = "-value";
+
+  return Object.fromEntries(
+    Array.from(element.attributes)
+      .filter(attribute =>
+        attribute.name.startsWith(dataPrefix) &&
+        attribute.name.startsWith(prefix, dataPrefix.length) &&
+        attribute.name.endsWith(valueSuffix)
+      )
+      .map(attribute => {
+        const attributeName = attribute.name.slice(dataPrefix.length);
+        const valueName = attributeName.slice(prefix.length, attributeName.length - valueSuffix.length);
+
+        return [valueName, attribute.value];
+      })
+  );
+}

src/index.js

@@ -7,3 +7,5 @@ export function registerActionOptions(application) {
     application.registerActionOption(name, method);
   });
 }
+
+export { enableDebug } from "./enableDebug";