stimulus-use-actions 0.2.0 → 0.3.0

package/README.md

@@ -1,98 +1,110 @@
 # stimulus-use-actions
 
-Small helper for Stimulus controllers to declare `data-action` bindings in JavaScript, instead of markup.
+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 Example
+## Quick Start
+
+Import `Controller` from this package instead of `@hotwired/stimulus`. Declare
+`static actions` alongside your `static targets` -- that's it.
+
 ```js
-// controllers/demo_controller.js
-import { Controller } from "@hotwired/stimulus";
-import useActions from "stimulus-use-actions";
+import { Controller } from "stimulus-use-actions"
 
 export default class extends Controller {
-  static targets = ["button"];
+  static targets = ["field", "checkbox"]
 
-  connect() {
-    useActions(this, {
-      // plural targets: bind multiple events to each element
-      buttonTargets: ["click->submit", "keyup->preview"],
-      // window-scoped actions
-      window: ["resize->reflow"],
-    });
+  static actions = {
+    field: "input->update",
+    checkbox: "change->rerender",
+    window: "resize->layout",
   }
 
-  submit() { /* ... */ }
-  preview() { /* ... */ }
-  reflow() { /* ... */ }
+  update(event) { /* ... */ }
+  rerender(event) { /* ... */ }
+  layout(event) { /* ... */ }
 }
 ```
 
-### Using the built-in Controller
-Import the base `Controller` from this package to auto-bind `static actions` without calling anything in `connect()`.
+Actions are bound via **event delegation** on the controller element. This
+means:
 
-```js
-import { Controller } from "stimulus-use-actions";
+- 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
 
-export default class extends Controller {
-  static targets = ["button"];
+### Keys
 
-  static actions = {
-    buttonTarget: ["click->submit", "keyup->preview"],
-    window: "resize->reflow",
-  };
+Each key in `static actions` is a **target name** matching an entry in
+`static targets`, or the special key `window`.
 
-  submit() {}
-  preview() {}
-  reflow() {}
-}
-```
+| 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**:
 
-### Using `static actions = {}`
-Define actions on the class and either:
-- Call `useActions(this)` without the second argument; or
-- Wrap your controller with `withActions()` to auto-bind in `connect()`.
+| 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 useActions, { withActions } from "stimulus-use-actions";
+import { Controller } from "@hotwired/stimulus"
+import useActions from "stimulus-use-actions"
 
-class Base extends Controller {
-  static targets = ["button"];
-  static actions = {
-    buttonTarget: ["click->submit", "keyup->preview"],
-    window: "resize->reflow",
-  };
-  submit() {}
-  preview() {}
-  reflow() {}
-  connect() { useActions(this); }
-}
+export default class extends Controller {
+  static targets = ["button"]
+
+  connect() {
+    useActions(this, {
+      buttonTargets: ["click->submit", "keyup->preview"],
+      window: "resize->reflow",
+    })
+  }
 
-// Or auto-bind without calling in connect:
-export default withActions(Base);
+  submit() { /* ... */ }
+  preview() { /* ... */ }
+  reflow() { /* ... */ }
+}
 ```
 
-## API
-`useActions(controller, actions)`
+`useActions` binds directly to target elements (no delegation). It does **not**
+clean up on disconnect -- Stimulus handles this through its own binding
+observer.
 
-- `controller`: your Stimulus controller instance (`this`).
-- `actions`: map of target keys to action descriptors.
-  - Target keys: `<name>Target`, `<name>Targets`, or the special key `window`.
-  - Values: a string (e.g., `"click->save"`, `"save"`) or an array of such strings.
-  - If omitted, actions are read from `controller.constructor.actions`.
+### `useActions(controller, actions?)`
 
-## Action Descriptors
-- `"event->method"`: binds a specific DOM event to `controller.method`.
-- `"method"` (no event): Stimulus infers the element’s default event (e.g., `click` for buttons, `input` for text inputs).
-- Works with Stimulus modifiers, e.g. `"keyup.enter->submit"`.
+- **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`
 
-## Target Resolution
-- For `<name>Targets`, each element in that target list receives each action.
-- For `<name>Target`, the single element receives each action.
-- `window` binds to the `@window` target (e.g., `"resize->reflow"`).
+A `withActions(BaseController)` wrapper is also available -- it returns a
+subclass that auto-calls `useActions(this)` in `connect()`.
 
 ## Notes
-- Call once per controller instance (typically in `connect()`). Calling repeatedly will add duplicate bindings.
-- Keep action names in sync with your controller methods; mismatches throw at runtime via Stimulus.
+
+- `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,5 +1,8 @@
+import { Controller as StimulusController } from "@hotwired/stimulus"
+
+// --- Direct binding via Stimulus internals (useActions, withActions) ---
+
 function useActionsImpl(controller, actions) {
-  // Allow calling without explicit map: read from static/class property
   if (!actions) actions = controller?.constructor?.actions || controller?.actions;
   if (!actions || typeof actions !== "object") return;
   const bindingObserver = controller.context.bindingObserver
@@ -33,23 +36,112 @@ function useActionsImpl(controller, actions) {
 
 export default useActionsImpl
 
-// Helper to wrap a Stimulus Controller class so actions bind automatically
 export function withActions(BaseController) {
   return class WithActions extends BaseController {
     connect() {
-      if (super.connect) super.connect()
-      // Bind actions declared on the class via `static actions = {}`
-      // Call with only controller; it will resolve static actions
+      super.connect()
       useActionsImpl(this)
     }
   }
 }
-import { Controller as StimulusController } from "@hotwired/stimulus"
 
-// Base Controller that auto-binds actions declared via `static actions = {}`
+// --- 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() {
-    if (super.connect) super.connect()
-    useActionsImpl(this)
+    super.connect()
+    this._useActionListeners = bindDelegatedActions(this)
+  }
+  disconnect() {
+    super.disconnect()
+    unbindDelegatedActions(this._useActionListeners)
+    this._useActionListeners = []
   }
 }

package/package.json

@@ -1,8 +1,9 @@
 {
   "name": "stimulus-use-actions",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Stimulus mixin for declaring actions in the controller",
   "main": "index.js",
+  "files": ["index.js"],
   "scripts": {
     "test": "vitest run",
     "test:watch": "vitest",

package/.github/workflows/ci.yml

@@ -1,17 +0,0 @@
-name: CI
-on: [ push, pull_request ]
-jobs:
-  test:
-    runs-on: ubuntu-latest
-    steps:
-      - name: Checkout
-        uses: actions/checkout@v4
-      - name: Setup Node
-        uses: actions/setup-node@v4
-        with:
-          node-version: 20
-          cache: npm
-      - name: Install dependencies
-        run: npm ci
-      - name: Run tests with coverage
-        run: npm run ci

package/AGENTS.md

@@ -1,39 +0,0 @@
-# Repository Guidelines
-
-## Project Structure & Module Organization
-- Root files: `index.js` (library entry), `package.json` (metadata/scripts).
-- No build step; the module exports an ES module function for Stimulus controllers.
-- Suggested growth: place future sources in `src/` and re-export from `index.js`; put tests in `tests/`.
-
-## Build, Test, and Development Commands
-- `npm install`: installs dev tools if added later. Currently no runtime deps.
-- `npm test`: placeholder that exits with error. If you add tests, replace with a real runner (e.g., `vitest` or `jest`).
-- Local check: import `index.js` in a small sandbox app to validate Stimulus behavior.
-
-## Coding Style & Naming Conventions
-- Indentation: 2 spaces; avoid semicolons; prefer double quotes for strings; use template literals where helpful.
-- Exports: default export is the library entry. Keep API surface small and documented in JSDoc.
-- Naming: reflect Stimulus conventions. Keys in the `actions` map should match controller properties (e.g., `buttonTarget`, `buttonTargets`, or `window`). Action strings may be "click->method" or "method".
-
-## Testing Guidelines
-- Framework: Vitest with `happy-dom`. Name files `*.test.js`.
-- Location: co-locate tests next to files or under `tests/`.
-- Coverage: enforced at 100% (lines, functions, branches, statements). Use `npm run coverage`.
-- Scope: cover multiple targets, `window` target, and event prefixes like `click->`.
-- Run: `npm test` for a single run; `npm run test:watch` in dev.
-
-## Commit & Pull Request Guidelines
-- Commits: use Conventional Commits when possible (e.g., `feat: add window target support`, `fix: handle single target elements`). Keep commits focused.
-- PRs: include a concise description, rationale, example usage, and any behavioral changes. Link issues. Add before/after snippets when touching the API.
-
-## Example Usage (for sanity checks)
-```js
-import useActions from "./index.js";
-// Inside a Stimulus controller
-connect() {
-  useActions(this, {
-    buttonTargets: ["click->submit", "keyup->preview"],
-    window: "resize->reflow",
-  });
-}
-```

package/tests/controller-export.test.js

@@ -1,37 +0,0 @@
-import { describe, it, expect, beforeEach } from "vitest";
-import { Application } from "@hotwired/stimulus";
-import { Controller } from "../index.js";
-
-function nextTick() { return new Promise((r) => setTimeout(r, 0)); }
-
-describe("exported Controller base", () => {
-  let app, root;
-
-  beforeEach(async () => {
-    document.body.innerHTML = "";
-    root = document.createElement("div");
-    document.body.appendChild(root);
-    app = Application.start(root);
-    await nextTick();
-  });
-
-  it("auto-binds static actions without calling useActions manually", async () => {
-    root.innerHTML = `
-      <div data-controller="demo">
-        <button id="btn" data-demo-target="button"></button>
-      </div>
-    `;
-
-    const calls = { submit: 0 };
-    class DemoController extends Controller {
-      static targets = ["button"];
-      static actions = { buttonTarget: "click->submit" };
-      submit() { calls.submit++; }
-    }
-    app.register("demo", DemoController);
-    await nextTick();
-    document.getElementById("btn").dispatchEvent(new Event("click", { bubbles: true }));
-    expect(calls.submit).toBe(1);
-  });
-});
-

package/tests/integration.test.js

@@ -1,102 +0,0 @@
-import { describe, it, expect, beforeEach } from "vitest";
-import { Application, Controller } from "@hotwired/stimulus";
-import useActions from "../index.js";
-
-function nextTick() {
-  return new Promise((r) => setTimeout(r, 0));
-}
-
-describe("Stimulus integration", () => {
-  let app, root;
-
-  beforeEach(async () => {
-    document.body.innerHTML = "";
-    root = document.createElement("div");
-    document.body.appendChild(root);
-    app = Application.start(root);
-    await nextTick();
-  });
-
-  it("handles plural targets with prefixed events", async () => {
-    // Build DOM with controller and two target elements
-    root.innerHTML = `
-      <div data-controller="demo">
-        <button id="a" data-demo-target="button"></button>
-        <button id="b" data-demo-target="button"></button>
-      </div>
-    `;
-
-    const calls = { submit: 0, preview: 0, reflow: 0 };
-
-    class DemoController extends Controller {
-      static targets = ["button"];
-      connect() {
-        useActions(this, {
-          buttonTargets: ["click->submit", "keyup->preview"],
-          window: "resize->reflow",
-        });
-      }
-      submit() { calls.submit++; }
-      preview() { calls.preview++; }
-      reflow() { calls.reflow++; }
-    }
-
-    app.register("demo", DemoController);
-    await nextTick();
-
-    const btnA = document.getElementById("a");
-    const btnB = document.getElementById("b");
-
-    // Fire events on buttons
-    btnA.dispatchEvent(new Event("click", { bubbles: true }));
-    btnB.dispatchEvent(new KeyboardEvent("keyup", { bubbles: true }));
-    // Fire resize on window
-    window.dispatchEvent(new Event("resize"));
-
-    expect(calls.submit).toBe(1);
-    expect(calls.preview).toBe(1);
-    expect(calls.reflow).toBe(1);
-  });
-
-  it("handles single target without event prefix (defaults to click)", async () => {
-    root.innerHTML = `
-      <div data-controller="demo">
-        <button id="only" data-demo-target="button"></button>
-      </div>
-    `;
-
-    let called = 0;
-    class DemoController extends Controller {
-      static targets = ["button"];
-      connect() { useActions(this, { buttonTarget: "submit" }); }
-      submit() { called++; }
-    }
-
-    app.register("demo", DemoController);
-    await nextTick();
-    const btn = document.getElementById("only");
-    btn.dispatchEvent(new Event("click", { bubbles: true }));
-    expect(called).toBe(1);
-  });
-
-  it("supports multiple actions array on a single target", async () => {
-    root.innerHTML = `
-      <div data-controller="demo">
-        <button id="only" data-demo-target="button"></button>
-      </div>
-    `;
-    const called = { a: 0, b: 0 };
-    class DemoController extends Controller {
-      static targets = ["button"];
-      connect() { useActions(this, { buttonTarget: ["click->a", "click->b"] }); }
-      a() { called.a++; }
-      b() { called.b++; }
-    }
-    app.register("demo", DemoController);
-    await nextTick();
-    const btn = document.getElementById("only");
-    btn.dispatchEvent(new Event("click", { bubbles: true }));
-    expect(called.a).toBe(1);
-    expect(called.b).toBe(1);
-  });
-});

package/tests/static-actions.test.js

@@ -1,60 +0,0 @@
-import { describe, it, expect, beforeEach } from "vitest";
-import { Application, Controller } from "@hotwired/stimulus";
-import useActions, { withActions } from "../index.js";
-
-function nextTick() { return new Promise((r) => setTimeout(r, 0)); }
-
-describe("static actions support", () => {
-  let app, root;
-
-  beforeEach(async () => {
-    document.body.innerHTML = "";
-    root = document.createElement("div");
-    document.body.appendChild(root);
-    app = Application.start(root);
-    await nextTick();
-  });
-
-  it("binds from static actions when calling useActions(this)", async () => {
-    root.innerHTML = `
-      <div data-controller="demo">
-        <button id="one" data-demo-target="button"></button>
-      </div>
-    `;
-
-    const calls = { submit: 0 };
-    class DemoController extends Controller {
-      static targets = ["button"];
-      static actions = { buttonTarget: "click->submit" };
-      connect() { useActions(this); }
-      submit() { calls.submit++; }
-    }
-
-    app.register("demo", DemoController);
-    await nextTick();
-    document.getElementById("one").dispatchEvent(new Event("click", { bubbles: true }));
-    expect(calls.submit).toBe(1);
-  });
-
-  it("auto-binds via withActions() without calling connect helper", async () => {
-    root.innerHTML = `
-      <div data-controller="demo">
-        <button id="two" data-demo-target="button"></button>
-      </div>
-    `;
-
-    const calls = { submit: 0 };
-    class Base extends Controller {
-      static targets = ["button"];
-      static actions = { buttonTarget: "click->submit" };
-      submit() { calls.submit++; }
-    }
-    const DemoController = withActions(Base);
-
-    app.register("demo", DemoController);
-    await nextTick();
-    document.getElementById("two").dispatchEvent(new Event("click", { bubbles: true }));
-    expect(calls.submit).toBe(1);
-  });
-});
-

package/tests/window.test.js

@@ -1,40 +0,0 @@
-import { describe, it, expect, beforeEach } from "vitest";
-import { Application, Controller } from "@hotwired/stimulus";
-import useActions from "../index.js";
-
-function nextTick() { return new Promise((r) => setTimeout(r, 0)); }
-
-describe("Window actions", () => {
-  let app, root;
-
-  beforeEach(async () => {
-    document.body.innerHTML = "";
-    root = document.createElement("div");
-    document.body.appendChild(root);
-    app = Application.start(root);
-    await nextTick();
-  });
-
-  it("handles multiple window events via array", async () => {
-    root.innerHTML = `<div data-controller="demo"></div>`;
-    const hits = { resize: 0, scroll: 0 };
-
-    class DemoController extends Controller {
-      connect() {
-        useActions(this, { window: ["resize->onResize", "scroll->onScroll"] });
-      }
-      onResize() { hits.resize++; }
-      onScroll() { hits.scroll++; }
-    }
-
-    app.register("demo", DemoController);
-    await nextTick();
-
-    window.dispatchEvent(new Event("resize"));
-    window.dispatchEvent(new Event("scroll"));
-
-    expect(hits.resize).toBe(1);
-    expect(hits.scroll).toBe(1);
-  });
-});
-

package/vitest.config.mjs

@@ -1,18 +0,0 @@
-import { defineConfig } from "vitest/config";
-
-export default defineConfig({
-  test: {
-    environment: "happy-dom",
-    coverage: {
-      provider: "v8",
-      reportsDirectory: "./coverage",
-      reporter: ["text", "lcov", "json-summary", "html"],
-      thresholds: {
-        lines: 100,
-        functions: 100,
-        branches: 100,
-        statements: 100,
-      },
-    },
-  },
-});