Quark

Welcome to the documentation of the Quark library, a powerful tool for developers looking to create custom web components quickly and efficiently. Quark simplifies the development of custom web components using JavaScript/TypeScript and HTML.

Installation

To get started with the Quark library, you need to install it in your project. You can do this via npm or yarn:

npm install @quark-js/quark
# or
yarn add @quark-js/quark

Basic Usage

Here's a simple example of how to use the Quark library to create a counter component:

import { connected, define, on, paint, repaint } from '@quark-js/quark';

@define('quark-counter')
class Counter {
  n: number = 0;

  @on.click('button')
  @repaint
  inc(e): Counter {
    this.n += 1;
    return this;
  }

  @connected
  @paint
  template(): string {
    return `
      <div>
        <strong>${this.n}</strong>
        <button>+ add</button>
      </div>
    `;
  }
}

export default Counter;

This is an example of a simple counter component. The @define decorator is used to set the component's name. The @on.click, @repaint, @connected, and @paint decorators are used to define click behavior and rendering.

API

Below are detailed descriptions of the API features available in the Quark library:

@adopted

The @adopted decorator is used to define a method that is called when the component is adopted by a new document, meaning it is moved from one DOM document to another. This allows you to handle adoption events and adjust the component's behavior if necessary.

@adopted
handleAdoption(): void {
  // Logic to be executed when the component is adopted by a new document
}

@connected

The @connected decorator is used to define a method that is called when the component is connected to the DOM. This is useful for performing initialization or configuration tasks after the component is rendered in the document.

@connected
initializeComponent(): void {
  // Initialization logic after being connected to the DOM
}

@define(name: string)

The @define decorator is used to set the component's name. The name is crucial for identifying the component in HTML and is used in the form of a custom element.

@define('quark-counter')
class Counter {
  // Component definition
}

@disconnected

The @disconnected decorator is used to define a method that is called when the component is disconnected from the DOM. This allows you to perform cleanup or manipulation before the component is removed from the document.

@disconnected
cleanupComponent(): void {
  // Cleanup logic before disconnection from the DOM
}

@on.event(selector: string)

The @on.event decorator is used to define an event handler for a specific HTML element. You can specify the event type (e.g., 'click' or 'input') and a selector for the target element.

@on.event('button')
handleClick(event: MouseEvent): void {
  // Logic to be executed when a button is clicked
}

@paint

The @paint decorator is used to define a method that returns the HTML of the component. The HTML generated by this method is inserted into the DOM as the visual representation of the component.

@paint
render(): string {
  return `
    <div>
      <!-- HTML content of the component -->
    </div>
  `;
}

@repaint

The @repaint decorator is used to signal that the component needs to be redrawn after an action. This is useful for updating the component's view when changes in state occur.

@on.click('button')
@repaint
handleClick(event: MouseEvent): void {
  // Logic to update the state and redraw the component
}

This is an overview of the Quark library's API, highlighting key features and how to use them in your components. Be sure to refer to the examples provided in the documentation for a deeper understanding of using these features in real scenarios.

Contributing

If you wish to contribute to the development of this library, please feel free to open issues or submit pull requests. We look forward to collaborating with you!

License

This library is licensed under the MIT License. Please refer to the LICENSE file for more details.