@fnando/pulse

Pulse

Pulse is a lightweight JavaScript framework that enhances your HTML rather than replacing it.

.

Installation

This package is available as a NPM package. To install it, use the following command:

npm install @fnando/pulse --save

If you're using Yarn (and you should):

yarn add @fnando/pulse

Usage

Creating a controller

A controller encapsulates the logic for a piece of UI. That can be orchestrating multiple components, or a smaller component unit. All controllers must inherit from Controller.

import { Controller } from "@fnando/pulse";

export class Counter extends Controller {
  connect() {
    this.count = 0;
    this.on("increment->click", this.increment);
    this.on("decrement->click", this.decrement);
  }

  increment() {
    this.count += 1;
    this.update();
  }

  decrement() {
    this.count -= 1;
    this.update();
  }

  update() {
    this.target("output").textContent = this.count.toString();
  }
}

A few things about this controller:

• connect() is a method you can define that will always be called once a new element is connected (added to DOM).
• Similarly, there's a disconnect() method that's called when the controller's root element is removed. If you're overriding the original method, make sure you call super(), so event handlers are properly cleared up.
• this.on(expression, callback) will register an event handler on the target. The expression is a shortcut for a target and the event. The above example is defining a click event on [data-counter-target="increment"] and [data-counter-target="decrement"].
• the update() method is reflecting the new count on the ui. It uses target(name) to retrieve the element. The full selector would be [data-counter-target="output"].

Defining keyboard events

Just like Stimulus, you can define keyboard events mapping specific key combos. The syntax looks like this:

this.on("@window->keydown.ctrl+w", this.close);

Registering controllers

To register a controller, you'll need an application instance.

import { Application } from "@fnando/pulse";
import { Counter } from "./controllers/Counter";

const app = new Application();
app.register("counter", Counter);
app.start();

The Application#start() method will watch for DOM modifications and ensure all controllers are connected to their own elements.

FAQ

This looks like Stimulus... a lot!

Yes, it does! And that's the purpose. It doesn't implement everything, but it implements the things I like about it, so it's lot smaller (2kb min+gzip).

What's not supported?

• There's no notifications if targets are added/removed (in Stimulus, you can use ${name}TargetConnected and ${name}TargetDisconnected).
• There's no outlet support to communicate between different controllers.
• Event's are set using controller.on(expression, callback), not [data-action].
• No CSS classes or values.

Maintainer

• Nando Vieira

Contributors

• https://github.com/fnando/pulse/contributors

Contributing

For more details about how to contribute, please read https://github.com/fnando/pulse/blob/main/CONTRIBUTING.md.

License

The gem is available as open source under the terms of the MIT License. A copy of the license can be found at https://github.com/fnando/pulse/blob/main/LICENSE.md.

Code of Conduct

Everyone interacting in the pulse project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the code of conduct.