i-runner

A tiny self-destructing custom element for one-off DOM actions (focus, reset and more).

Sponsored By Rails Designer

Want to be able to understand this JavaScript code? 😊 👉 JavaScript for Rails Developers

Installation

npm install i-runner

Then in your code:

import "i-runner";

Usage

Simply drop the <i-run> tag in your HTML:

<!-- Focus an input with id="email" -->
<i-run action="focus" target="email"></i-run>

<!-- Reset all forms with class="signup" -->
<i-run action="reset" targets="signup"></i-run>

Attributes

• action (string, required). One of the below listed actions.
• target (string, optional). An element ID to select via #id.
• targets (string, optional). A class name to select via .className.

Actions

i-runner includes a few first-party actions.

• focus; set focus to an input field;
• reset; reset a form;
• addClass; add one or many CSS classes to a field;
• setAttribute; add an attribute.

Extensibility

You can register your own actions at runtime by tapping into the exported ACTION_HANDLERS map. Every action handler follows the signature:

(elements: HTMLElement[], options: { [attrName: string]: string }) ⇒ void

1. Import the registry (ESM) or access it from the global UMD object:

import { ACTION_HANDLERS } from "i-runner";

2. Define your custom fadeOut handler:

function fadeOutAction(elements, options) {
  const duration = Number(options["data-duration"] || 300);
  const easing = options["data-easing"] || "linear";

  elements.forEach((element) => {
    element.style.transition = `opacity ${duration}ms ${easing}`;
    element.style.opacity = "0";

    setTimeout(() => {
      // Remove the element after the fade completes
      element.remove();
    }, duration);
  });
}

3. Register it under a new name:

ACTION_HANDLERS.fadeOut = fadeOutAction;

4. Use it in your HTML:

<!-- fade out and remove .alert over 500ms with ease-out -->
<i-run
  action="fadeOut"
  targets="alert"
  data-duration="500"
  data-easing="ease-out">
</i-run>

Development

# Install dev dependencies
npm install

# Build bundles (ESM + UMD)
npm run build

# Preview with a local server
npm dev

# Run basic test
npm test

Release

Because I always forget how to do this and don't feel like pulling a third-party dependency for releasing.

npm version patch # or minor, or major
npm publish
git push
git push --tags