@nodusjs/std

@nodusjs/std é a biblioteca de utilitários padrão do ecossistema Nodus. Ela fornece diretivas, helpers DOM e um pilar de dataflow declarativo que simplificam a construção de Web Components modernos, reativos e fáceis de manter.

Com uma abordagem baseada em decorators, @nodusjs/std permite que você se conecte ao ciclo de vida dos componentes e responda a eventos de forma limpa e intuitiva.

⚠️ Este projeto está em desenvolvimento ativo. As APIs e os pacotes podem mudar entre as versões menores.

Princípios

• Declarativo: Escreva o que seu componente faz, não como ele o faz. Decorators como @paint, @repaint e @event abstraem a manipulação manual do DOM.
• Reativo: Crie componentes que reagem a mudanças de estado automaticamente. O dataflow integrado facilita a comunicação entre componentes.
• Moderno: Construído sobre as APIs nativas da plataforma web, como Custom Elements, Shadow DOM e adoptedStyleSheets, garantindo performance e interoperabilidade.
• Modular: Importe apenas o que você precisa, mantendo seus componentes leves e eficientes.

Instalação

Você pode adicionar o @nodusjs/std ao seu projeto usando seu gerenciador de pacotes preferido ou diretamente no navegador através de uma CDN.

1. Usando um Gerenciador de Pacotes

# npm
npm install @nodusjs/std

# yarn
yarn add @nodusjs/std

# bun
bun add @nodusjs/std

Importação:

import { define, attributeChanged } from "@nodusjs/std/directive";
import { paint, repaint, html, css } from "@nodusjs/std/dom";
import on from "@nodusjs/std/event";

2. Usando via CDN

Para prototipagem rápida ou uso em plataformas como CodePen e JSFiddle, você pode importar os módulos diretamente da CDN esm.sh.

import { define } from "https://esm.sh/@nodusjs/std/directive";
import { paint, html, css } from "https://esm.sh/@nodusjs/std/dom";
import on from "https://esm.sh/@nodusjs/std/event";

Exemplo Rápido: Um Contador Reativo

O exemplo abaixo demonstra como os diferentes módulos do @nodusjs/std trabalham em harmonia para criar um componente de contador interativo e reativo com poucas linhas de código.

<x-counter value="1"></x-counter>

import {
  attributeChanged,
  define
} from "https://esm.sh/@nodusjs/std/directive";
import { html, paint, repaint, css } from "https://esm.sh/@nodusjs/std/dom";
import on from "https://esm.sh/@nodusjs/std/event";

// 1. Defina o componente e seu nome de tag
@define("x-counter")
// 2. Pinte o componente com seu HTML e CSS iniciais
@paint(component, style)
class Counter extends HTMLElement {
  #value;

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

  // 3. Conecte o atributo 'value' à propriedade da classe.
  //    O @repaint garante que o componente será re-renderizado
  //    sempre que a propriedade 'value' for alterada.
  @attributeChanged("value", Number)
  @repaint
  set value(value) {
    this.#value = value;
  }

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

  // 4. Ouça o evento de 'click' no botão e execute a lógica.
  @on.click("button")
  click() {
    this.value += 1;
    return this;
  }
}

// 5. Função que descreve a estrutura HTML
function component(counter) {
  return html`
    <button>Count ${counter.value}</button>
  `;
}

// 6. Função que descreve os estilos, que também podem ser reativos!
function style(counter) {
  return css`
    button {
      background-color: hsl(calc(${counter.value} * 3.6), 80%, 60%);
      border: none;
      border-radius: 8px;
      color: #ffffff;
      font-size: 18px;
      font-weight: bold;
      padding: 12px 24px;
      cursor: pointer;
    }
  `;
}

Scripts Úteis

• bun dev — Inicia o servidor de desenvolvimento.
• bun run build — Gera os pacotes para distribuição.
• bun run test — Executa a suíte de testes com Vitest.

Contribuindo

Contribuições são muito bem-vindas! Siga nosso Guia de Contribuição para reportar bugs, sugerir melhorias e submeter pull requests.

Licença

Distribuído sob a licença MIT. Veja o arquivo LICENSE para detalhes.