stimulus-use-actions 0.1.0 → 0.3.0

package/README.md

@@ -0,0 +1,110 @@
+# stimulus-use-actions
+
+Declare Stimulus `data-action` bindings in JavaScript instead of HTML markup.
+
+[![CI](https://github.com/botandrose/stimulus-use-actions/actions/workflows/ci.yml/badge.svg)](https://github.com/botandrose/stimulus-use-actions/actions/workflows/ci.yml)
+
+Requires Stimulus v3+ and ES modules.
+
+## Quick Start
+
+Import `Controller` from this package instead of `@hotwired/stimulus`. Declare
+`static actions` alongside your `static targets` -- that's it.
+
+```js
+import { Controller } from "stimulus-use-actions"
+
+export default class extends Controller {
+  static targets = ["field", "checkbox"]
+
+  static actions = {
+    field: "input->update",
+    checkbox: "change->rerender",
+    window: "resize->layout",
+  }
+
+  update(event) { /* ... */ }
+  rerender(event) { /* ... */ }
+  layout(event) { /* ... */ }
+}
+```
+
+Actions are bound via **event delegation** on the controller element. This
+means:
+
+- Listeners are added on `connect()` and removed on `disconnect()`
+- Target elements can appear and disappear in the DOM at any time -- events are
+  still captured
+- No need to call anything in `connect()` yourself
+
+### Keys
+
+Each key in `static actions` is a **target name** matching an entry in
+`static targets`, or the special key `window`.
+
+| Key       | Listens on          | Matches events from                          |
+| --------- | ------------------- | -------------------------------------------- |
+| `field`   | controller element  | descendants with `data-<id>-target="field"`  |
+| `window`  | `window`            | the window itself                            |
+
+### Values
+
+Values use Stimulus action descriptor syntax with an **explicit event**:
+
+| Value                          | Meaning                                    |
+| ------------------------------ | ------------------------------------------ |
+| `"input->update"`              | listen for `input`, call `this.update()`   |
+| `"click->save"`                | listen for `click`, call `this.save()`     |
+| `["click->a", "keyup->b"]`     | multiple actions on one target             |
+
+Stimulus modifiers work as usual, e.g. `"keyup.enter->submit"`.
+
+## Lower-Level API: `useActions`
+
+For cases where you need manual control (conditional bindings, dynamic action
+maps, etc.), import `useActions` directly:
+
+```js
+import { Controller } from "@hotwired/stimulus"
+import useActions from "stimulus-use-actions"
+
+export default class extends Controller {
+  static targets = ["button"]
+
+  connect() {
+    useActions(this, {
+      buttonTargets: ["click->submit", "keyup->preview"],
+      window: "resize->reflow",
+    })
+  }
+
+  submit() { /* ... */ }
+  preview() { /* ... */ }
+  reflow() { /* ... */ }
+}
+```
+
+`useActions` binds directly to target elements (no delegation). It does **not**
+clean up on disconnect -- Stimulus handles this through its own binding
+observer.
+
+### `useActions(controller, actions?)`
+
+- **controller** -- your Stimulus controller instance (`this`)
+- **actions** -- map of target keys to action descriptors
+  - Keys: `<name>Target`, `<name>Targets`, or `window`
+  - Values: a string or array of `"event->method"` strings
+  - Event inference (e.g. `"submit"` without `click->`) is supported here --
+    Stimulus infers the default event for the element
+  - If omitted, reads from `controller.constructor.actions`
+
+A `withActions(BaseController)` wrapper is also available -- it returns a
+subclass that auto-calls `useActions(this)` in `connect()`.
+
+## Notes
+
+- `useActions` binds once per call -- calling repeatedly adds duplicate
+  bindings.
+- The `Controller` base class uses delegation -- no duplicates, automatic
+  cleanup.
+- Keep method names in sync with your controller; mismatches throw at runtime.

package/index.js

@@ -1,4 +1,10 @@
-export default function(controller, actions) {
+import { Controller as StimulusController } from "@hotwired/stimulus"
+
+// --- Direct binding via Stimulus internals (useActions, withActions) ---
+
+function useActionsImpl(controller, actions) {
+  if (!actions) actions = controller?.constructor?.actions || controller?.actions;
+  if (!actions || typeof actions !== "object") return;
   const bindingObserver = controller.context.bindingObserver
 
   Object.entries(actions).forEach(([targetName, actionName]) => {
@@ -28,3 +34,114 @@ export default function(controller, actions) {
   }
 }
 
+export default useActionsImpl
+
+export function withActions(BaseController) {
+  return class WithActions extends BaseController {
+    connect() {
+      super.connect()
+      useActionsImpl(this)
+    }
+  }
+}
+
+// --- Delegated binding (Controller) ---
+
+const KEY_MAP = {
+  enter: "Enter",
+  tab: "Tab",
+  esc: "Escape",
+  space: " ",
+  up: "ArrowUp",
+  down: "ArrowDown",
+  left: "ArrowLeft",
+  right: "ArrowRight",
+}
+
+function parseDescriptor(descriptor) {
+  const arrowIndex = descriptor.indexOf("->")
+  if (arrowIndex === -1) return null
+  const eventPart = descriptor.substring(0, arrowIndex)
+  const methodPart = descriptor.substring(arrowIndex + 2)
+  const dotIndex = eventPart.indexOf(".")
+  let eventName, filter
+  if (dotIndex === -1) {
+    eventName = eventPart
+    filter = null
+  } else {
+    eventName = eventPart.substring(0, dotIndex)
+    filter = eventPart.substring(dotIndex + 1)
+  }
+  const parts = methodPart.split(":")
+  const methodName = parts[0]
+  const options = parts.slice(1)
+  return { eventName, filter, methodName, options }
+}
+
+function bindDelegatedActions(controller) {
+  const actions = controller.constructor.actions
+  if (!actions || typeof actions !== "object") return []
+  const identifier = controller.identifier
+  const listeners = []
+
+  Object.entries(actions).forEach(([key, descriptors]) => {
+    const descriptorList = Array.isArray(descriptors) ? descriptors : [descriptors]
+    const isWindow = key === "window"
+    let targetName
+    if (!isWindow) {
+      if (key.endsWith("Targets")) targetName = key.slice(0, -7)
+      else if (key.endsWith("Target")) targetName = key.slice(0, -6)
+      else targetName = key
+    }
+
+    descriptorList.forEach(descriptor => {
+      const parsed = parseDescriptor(descriptor)
+      if (!parsed) return
+      const { eventName, filter, methodName, options } = parsed
+
+      if (isWindow) {
+        const handler = (event) => {
+          if (filter && event.key !== (KEY_MAP[filter] || filter)) return
+          if (options.includes("stop")) event.stopPropagation()
+          if (options.includes("prevent")) event.preventDefault()
+          controller[methodName](event)
+        }
+        window.addEventListener(eventName, handler)
+        listeners.push({ target: window, eventName, handler })
+      } else {
+        const selector = `[data-${identifier}-target~="${targetName}"]`
+        const handler = (event) => {
+          const matched = event.target.closest(selector)
+          if (!matched || !controller.element.contains(matched)) return
+          if (filter && event.key !== (KEY_MAP[filter] || filter)) return
+          if (options.includes("self") && event.target !== matched) return
+          if (options.includes("stop")) event.stopPropagation()
+          if (options.includes("prevent")) event.preventDefault()
+          controller[methodName](event)
+        }
+        controller.element.addEventListener(eventName, handler)
+        listeners.push({ target: controller.element, eventName, handler })
+      }
+    })
+  })
+
+  return listeners
+}
+
+function unbindDelegatedActions(listeners) {
+  listeners.forEach(({ target, eventName, handler }) => {
+    target.removeEventListener(eventName, handler)
+  })
+}
+
+export class Controller extends StimulusController {
+  connect() {
+    super.connect()
+    this._useActionListeners = bindDelegatedActions(this)
+  }
+  disconnect() {
+    super.disconnect()
+    unbindDelegatedActions(this._useActionListeners)
+    this._useActionListeners = []
+  }
+}

package/package.json

@@ -1,11 +1,23 @@
 {
   "name": "stimulus-use-actions",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "Stimulus mixin for declaring actions in the controller",
   "main": "index.js",
+  "files": ["index.js"],
   "scripts": {
-    "test": "echo \"Error: no test specified\" && exit 1"
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "coverage": "vitest run --coverage",
+    "coverage:badge": "node scripts/generate-coverage-badge.js",
+    "ci": "vitest run --coverage && node scripts/generate-coverage-badge.js"
   },
   "author": "",
-  "license": "ISC"
+  "license": "ISC",
+  "devDependencies": {
+    "@hotwired/stimulus": "^3.2.2",
+    "@vitest/coverage-v8": "^4.0.4",
+    "happy-dom": "^20.0.8",
+    "jsdom": "^27.0.1",
+    "vitest": "^4.0.4"
+  }
 }