🇧🇷 Leia em Português | 🇺🇸 Read in English

-O-id

-O-id is a lightweight and efficient library for creating custom Web Components, focusing on simplicity and performance. Built entirely in JavaScript, -O-id ensures that your components are fast, lightweight, and easy to maintain. With an intuitive architecture and decorators like @paint and @repaint, developing reactive and modular components becomes simple and straightforward.

Why -O-id?

The name -O-id is inspired by Sigmund Freud's psychoanalytic theory. The "id" represents the most primitive part of the human personality, driving our fundamental instincts. Similarly, the -O-id library serves as an essential foundation for building web interfaces. The suffix "-O" symbolizes the transformation of ideas into tangible results—functional and efficient components.

-O-id is not just a tool but a force driving interface creation, allowing developers to transform concepts into reality in an agile and intuitive way. This name highlights the importance of starting with a solid foundation, just as the "id" is the starting point in personality formation.

Installation

To install the library, use npm:

npm install @bake-js/-o-id

Note: The library is also compatible with yarn and bun.

Usage Example

Below is a simple example of how to use the library to create an interactive counter:

import { define } from '@bake-js/-o-id';
import { css, html, paint, repaint } from '@bake-js/-o-id/dom';
import on from '@bake-js/-o-id/event';

function component(self) {
  return html`
    <button>Increment ${self.number}</button>
  `;
}

function style() {
  return css`
    button {
      background: hsl(${(self.number * 30) % 360}, 100%, 50%);
      border-radius: 8px;
      color: #222222;
      cursor: pointer;
      font-size: 16px;
      font-weight: 600;
      line-height: 20px;
      padding: 10px 20px;
      border: 1px solid #222222;

      &:hover {
        background: hsl(${(self.number * 30) % 360}, 50%, 50%);
      }
    }
  `;
}

@define('o-id-counter')
@paint(component, style)
class Counter extends HTMLElement {
  #number;

  constructor() {
    super();
    this.attachShadow({ mode: 'open' });
  }

  get number() {
    return (this.#number ??= 0);
  }

  @repaint
  set number(value) {
    this.#number = value;
  }

  @on.click('button')
  increment() {
    this.number += 1;
    return this;
  }
}

You can view the interactive example on CodePen.

Component Explanation

The example illustrates the creation of a custom element component named o-id-counter, representing a counter that can be incremented via a button. Below are the key features of the component:

• Element Definition:

  • The element is defined as o-id-counter using the @define decorator, and it uses Shadow DOM to encapsulate its styles and structure.

• Internal State:

  • The counter’s state is stored in a private property #number, starting at zero. The get number() method returns the current value, while the set number(value) method allows updates.

• Component Rendering:

  • The component(self) function generates the HTML structure for the button, and the style() function defines the applied CSS styles.

• Interactivity:

  • The increment() method is decorated with @on.click('button'), allowing the counter to be incremented with each button click. This method updates the state and re-renders the component automatically.

How to Use

To use this component in your application:

1. Ensure the code is properly imported and defined.
2. Add the <o-id-counter></o-id-counter> element anywhere in your HTML.
3. The component will be ready to use, incrementing the value with each button click.

Example of usage in HTML:

<o-id-counter></o-id-counter>

This example demonstrates how -O-id simplifies the creation of interactive components with a clear and efficient syntax.

Demo

To see the -O-id library in action, check out our interactive demo.

Assistant

If you need help or guidance on how to use the -O-id library, feel free to access our online assistant, which provides additional support and interactive documentation.

Documentation

Below you will find detailed documentation for the main modules of -O-id. Each link leads to the corresponding page where you can learn more about how to use and implement the features offered.

• Lifecycle and Forms: A complete guide to understanding and applying the main modules and decorators of -O-id.
• DOM: Documentation on DOM manipulation and component rendering.
• Event: A guide for handling and responding to events within Web Components.
• Relay: Facilitates listening to events emitted by a Custom Element's parentElement.
• Echo: Documentation on the Echo event bus for communication between components. Note: This module is in beta and may be subject to changes.

Reference Index

Lifecycle

Documentation on the callbacks and methods related to the lifecycle of Custom Elements. These methods are essential for managing the state and changes of elements throughout their existence in the DOM.

• adopted - Callback invoked when a Custom Element is adopted into a new document.
• attributeChanged - Callback invoked when an attribute of a Custom Element is changed.
• connected - Callback invoked when a Custom Element is inserted into the DOM.
• disconnected - Callback invoked when a Custom Element is removed from the DOM.
• define - Function to define and register a new Custom Element.

Lifecycle Associated with Forms

Information about the specific callbacks for Custom Elements interacting with forms. These callbacks are used to manage state and actions related to forms.

• formAssociated - Callback invoked when an element is associated with a form.
• formDisabled - Callback invoked when an element is disabled within a form.
• formReset - Callback invoked when an associated form is reset.
• formStateRestore - Callback invoked to restore the form state.

DOM

Documentation on how to manipulate the DOM and create custom elements.

• css - Helper for creating custom CSS styles for Custom Elements.
• didPaint - Decorator that allows logic execution after the component's rendering.
• html - Helper for generating clean and efficient HTML from templates.
• paint - Decorator that calls the component's render function.
• repaint - Decorator that updates the component's rendering when its state changes.
• willPaint - Decorator that allows logic execution before the component's rendering.

Events

Documentation on how to manage events in Custom Elements, facilitating communication and interactivity.

• on - Decorator for adding event listeners to elements.
• stop - Filter that calls event.stopPropagation() and returns the event, preventing it from bubbling up the DOM tree.
• prevent - Filter that calls event.preventDefault() and returns the event, preventing the default action of the event.
• formData - Filter that extracts form data and returns an object containing key-value pairs.
• value - Filter that retrieves the event's value, useful for inputs and selects.

Echo

Documentation on the Echo module, an event bus that enables efficient communication between components.

• echo - Module for communication between components, allowing simplified event emission and listening.

Contributing

Contributions are always welcome! Feel free to open issues or submit pull requests. To get started, check out the contribution guidelines.

License

This project is licensed under the MIT License. See the LICENSE file for more details.