@limbusfoundation/uibuilder

v1.8.3

Published

4 days ago

UI Builder is a library for building user interfaces using HTML elements. It provides a set of tools and components to create dynamic and interactive web applications.

0High
0Medium
0Low

limbusfoundation

uibuilder ui html-element html

UIBuilder DOC

DOM Wrapper for JavaScript / TypeScript.

UIBuilder provides a direct API for creating, manipulating and composing HTML elements without requiring a virtual DOM or a component rendering system.

UIBuilder focuses on providing low-level UI primitives that can be composed freely instead of providing a large collection of specialized pre-built components.

API

| Method | Param | ------------- | button() | anchor() | custom() | group() | icon() | image() | label() | panel() | slider() | field() | event() | component() | blend() | style() | body | head | html | router | store | watcher | Description | | ------------------------------- | ---------------------------------------------------- | | option: IUIButton | Creates and returns a UIButton. | | option: IUIAnchor | Creates and returns a UIAnchor. | | option: IUICustom | Creates and returns a UICustom. | | option: IUIGroup | Creates and returns a UIGroup. | | option: IUIcon | Creates and returns a UIIcon (<i>). | | option: IUIImage | Creates and returns a UIImage. | | option: IUILabel | Creates and returns a UILabel. | | option: IUIPanel | Creates and returns a UIPanel. | | option: IUISlider | Creates and returns a UISlider. | | option: IUIField | Creates and returns a UIField. | | element: UIElement | Creates a UIEvent manager for an element. | | build, self | Creates a reusable UI component with state support. | | ...elements: UIElement[] | Creates a UIBlend containing multiple UI elements. | | properties: UIStyleProperties | Creates a reusable UIStyle. | | — | Provides access to <body> operations. | | — | Provides access to <head> operations. | | — | Provides HTML utility methods. | | — | Provides client-side routing operations. | | — | Provides state store creation. | | — | Provides value and store observation. |

Elements

UIBuilder elements are wrapper instances around native HTML elements.

const button = UIBuilder.button({
    label: "Click Here"
});

button.label("Hello World");

button.className("primary");

button.style({
    margin: "10px"
});

Elements expose their own methods directly, while UIBuilder provides the factory methods used to create them.

Rendering

Elements can be rendered directly into the document body:

const button = UIBuilder.button({
    label: "Click Here"
});

UIBuilder.body.render(button);

Multiple elements can be grouped using UIBuilder.blend():

const label = UIBuilder.label({
    label: "Hello"
});

const button = UIBuilder.button({
    label: "Click"
});

const content = UIBuilder.blend(label, button);

UIBuilder.body.render(content);

Elements can also be organized through a UIGroup:

const group = UIBuilder.group({
    className: "my-container"
});

group.render(button);

group.render(label);

Elements can be removed from the body using unrender():

UIBuilder.body.unrender(button);

Event Management (`UIEvent`)

The UIBuilder.event() method creates an event manager bound to a specific element.

UIBuilder.event(button).add("click", () => {
    console.log("Button clicked!");
});

Multiple listeners can be registered independently:

UIBuilder.event(button).add("click", () => {
    console.log("Clicked");
});

UIBuilder.event(button).add("mouseenter", () => {
    console.log("Mouse entered");
});

Components (`UIComponent`)

UIBuilder.component() creates reusable UI components with properties and state.

const counter = UIBuilder.component(({ text }, self) => {

    const label = UIBuilder.label({
        label: text
    });

    const button = UIBuilder.button({
        label: "Adicionar"
    });

    let count = 0;

    self.stateListen(state => {
        label.label(state.text);
    });

    UIBuilder.event(button).add("click", () => {
        count++;

        label.label(String(count));
    });

    return UIBuilder.blend(label, button);
});

Component state can be updated using .state():

counter.state({
    text: "Click para adicionar ao contador"
});

The component can then be rendered like any other UI element:

UIBuilder.body.render(counter);

Component Lifecycle

UIBuilder provides listeners for when an element is rendered or unrendered.

const button = UIBuilder.button({
    label: "Click"
});

button.renderListen(() => {
    console.log("Button rendered");
});

button.unrenderListen(() => {
    console.log("Button unrendered");
});

These listeners are useful when behavior depends on whether an element is currently mounted in the DOM.

State (`UIStore`)

UIBuilder.store provides a simple state container.

const store = UIBuilder.store.set({
    count: 3,
    username: "rick"
});

The current state can be accessed through .get:

console.log(store.get.count);

console.log(store.get.username);

Watcher (`UIWatcher`)

UIBuilder.watcher can observe values and stores.

const count = UIBuilder.watcher.watch(0, value => {
    console.log(value);
});

count.value = 10;

count.value = 20;

UIBuilder.watcher.unwatch(count);

Stores can also be watched:

const store = UIBuilder.store.set({
    count: 3,
    username: "rick"
});

UIBuilder.watcher.watch(store, value => {
    console.log(value.count);
});

Router (`UIRouter`)

UIBuilder.router provides client-side routing using the browser History API.

Routes can be registered using route():

const home = UIBuilder.label({
    label: "Home"
});

const about = UIBuilder.label({
    label: "About"
});

UIBuilder.router.route("/", home);

UIBuilder.router.route("/about", about);

UIBuilder.router.init();

Navigation can be performed programmatically:

UIBuilder.router.navigate("/about");

retarget() changes the current URL without creating a new browser history entry:

UIBuilder.router.retarget("/about");

Browser history is also supported:

UIBuilder.router.back();

UIBuilder.router.forward();

Base Path

The router can operate under a base path.

UIBuilder.router.base("/example");

Routes remain relative to the configured base:

UIBuilder.router.route("/", home);

UIBuilder.router.route("/about", about);

With the base configured as /example, the routes resolve to:

/example/
/example/about

Dynamic Parameters

Routes can contain dynamic parameters using :name.

const user = UIBuilder.label({
    label: "User"
});

UIBuilder.router.route("/users/:id", user);

A URL such as:

/users/42

matches the route and provides:

{
    id: "42"
}

Parameters can be observed using listenParam():

UIBuilder.router.listenParam("/users", ({ id }) => {
    console.log(id);
});

The listener uses the route's base path rather than repeating the dynamic parameter.

For example:

UIBuilder.router.route("/image/:age", counter);

UIBuilder.router.listenRoute("/image", () => {
    console.log("Rota /image acessada");
});

UIBuilder.router.listenParam("/image", ({ age }) => {
    console.log("Parametro age:", age);
});

Navigating to:

/image/12

triggers both listeners.

Query Parameters

Query parameters are handled separately from route parameters.

A route does not need to include the query string:

UIBuilder.router.route("/users/:id", user);

A URL such as:

/users/42?tab=posts

resolves as:

Route parameter:
id = 42

Query parameter:
tab = posts

Query parameters can be observed using listenQuery():

UIBuilder.router.listenQuery("/users", queries => {
    console.log(queries.tab);
});

Route Listeners

Routes can have listeners attached to their base path.

UIBuilder.router.listenRoute("/about", () => {
    console.log("About route accessed");
});

Dynamic routes use the route's literal base:

UIBuilder.router.route("/users/:id", user);

UIBuilder.router.listenRoute("/users", () => {
    console.log("Users route accessed");
});

Navigating to /users/42 triggers the /users route listener.

Fallback Route

A fallback element can be provided for paths that do not match a registered route.

const notFound = UIBuilder.label({
    label: "Page not found"
});

UIBuilder.router.outRoute(notFound);

When no registered route matches the current path, the fallback content is rendered.

Body

UIBuilder.body provides operations specifically for the document <body>.

UIBuilder.body.render(button);

UIBuilder.body.unrender(button);

Body styles can be applied through UIStyle:

const style = UIBuilder.style({
    backgroundColor: "green"
});

UIBuilder.body.style(style);

Head

UIBuilder.head provides operations for the document <head>.

HTML Utilities

UIBuilder.html provides utilities for working with native HTML elements.

const element = UIBuilder.html.parseHTMLElement(button);

This can be useful when direct access to the underlying native HTML element is required.

Styling

Reusable styles can be created with UIBuilder.style():

const style = UIBuilder.style({
    width: "200px",
    height: "100px"
});

The style can then be applied to an element:

button.style(style);

Styles can also be provided directly:

button.style({
    width: "200px",
    height: "100px"
});

Composition

UIBuilder is designed around composing primitive elements rather than providing a specialized component for every possible combination.

For example, instead of requiring a dedicated icon button component, an icon and a button can be composed directly:

const icon = UIBuilder.icon({
    // icon options
});

const button = UIBuilder.button({
    label: "Settings"
});

button.render(icon);

This keeps the core API focused on reusable primitives while allowing applications to create their own higher-level structures.

Deprecated API

Older APIs that have been replaced are kept separately under the deprecated source directory during the compatibility period.

Examples include:

/deprecated
    /ui-route-button
    /ui-text-field
    /ui-icon-button

The current API uses:

UIBuilder.anchor(...);

UIBuilder.field(...);

instead of the deprecated:

UIBuilder.routeButton(...);

UIBuilder.textField(...);

Deprecated APIs may remain available for backwards compatibility and should be removed in a future major version.

Example

`index.html`

<!DOCTYPE html>
<html lang="en">

<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>UIBuilder Example</title>
</head>

<body>
    <script type="module" src="./index.js"></script>
</body>

</html>

`index.ts`

import { UIBuilder } from "../dist/ui-builder/ui-builder.js";

const button = UIBuilder.button({
    label: "Click Here"
});

const label = UIBuilder.label({
    label: "Value: 50"
});

const range = UIBuilder.custom({
    tag: "input",
    attribute: {
        type: "range",
        min: 0,
        max: 100,
        value: 50
    }
});

UIBuilder.event(button).add("click", () => {
    document.body.style.background = "#1a1a1a";
});

UIBuilder.event(range).add("input", () => {
    label.label(
        UIBuilder.html.parseHTMLElement(range).value
    );
});

UIBuilder.body.render(button);

UIBuilder.body.render(label);

UIBuilder.body.render(range);

License (MIT)

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE.

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme