@studiometa/js-toolkit

A JavaScript data-attributes driven micro-framework shipped with plenty of useful utility functions to boost your project.

Installation

Install the latest version via NPM:

npm install @studiometa/js-toolkit

What is it?

This project is a JavaScript micro-framework (along with its utility functions) whose main objectives are:

• Enforcing best-practice and consistency between projects
• Using elements from the DOM easily
• Enabling custom behaviours on component initialization or other user events
• Disabling custom behaviours on component destruction or other user events
• Initializing components in the right place at the right time
• Defining dependencies between components

Visit js-toolkit.studiometa.dev to learn more, jump directly to ui.studiometa.dev to discover existing components, or open the playground to test it live.

Quick overview

This framework lets you define components as classes, and bind them to the DOM with data-… attributes. For example, here is how a Counter component would be defined in JavaScript:

import { Base } from '@studiometa/js-toolkit';

export default class Counter extends Base {
  static config = {
    name: 'Counter',
    refs: ['add', 'remove', 'count'],
  };

  get counter() {
    return this.$refs.count.valueAsNumber;
  }

  set counter(value) {
    this.$refs.count.value = value;
  }

  onAddClick() {
    this.counter += 1;
  }

  onRemoveClick() {
    this.counter -= 1;
  }
}

And its accompanying HTML would be sprinkled with data-… attributes to bind elements from the DOM to the JavaScript class.

<div data-component="Counter">
  <button data-ref="add">Add</button>
  <button data-ref="remove">Remove</button>
  <input data-ref="count" type="number" value="0" />
</div>

You can define options that can be specified with data-option-... attributes as well. First in JavaScript:

  class Counter extends Base {
    static config = {
      name: 'Counter',
      refs: ['add', 'remove', 'count'],
+     options: {
+       step: {
+         type: Number,
+         default: 1,
+       },
+     },
    };

    onAddClick() {
-     this.counter += 1;
+     this.counter += this.$options.step;
    }

    onRemoveClick() {
-     this.counter -= 1;
+     this.counter -= this.$options.step;
    }
  }

And then adjust it as you wish in your HTML:

- <div data-component="Counter">
+ <div data-component="Counter" data-option-step="2">
    <button data-ref="add">Add</button>
    <button data-ref="remove">Remove</button>
    <input data-ref="count" type="number" value="0">
  </div>

Like Web Components, components based on the Base class can be registered. Any matching component found in the DOM from the moment it is registered to any future change will be mounted.

import { registerComponent } from '@studiometa/js-toolkit';
import Counter from './components/Counter.js';

registerComponent(Counter);

Visit our "Getting Started" guide to learn more and try the above component by visiting the playground. Discover our existing library of components by checking out the @studiometa/ui package.

Contributing

This projects follows the Git Flow methodology to manage its branches and features. The packages and their dependencies are managed with NPM workspaces. The files are linted with ESLint, type checked with TypeScript and formatted with Prettier.

License

See LICENSE.