⚡ Spark Standard Library

Standard library utilities for web development. Zero dependencies, tree-shakeable packages.

📖 What is Spark?

Spark is a modern, lightweight standard library designed to revolutionize how you build web applications. Built on native Web Components APIs, it provides powerful declarative utilities for creating reactive, maintainable applications without framework overhead.

🎯 Why Choose Spark?

• Zero Dependencies - No runtime dependencies, just pure Web Platform APIs
• Declarative API - Describe what your components do, not how they do it
• Framework Agnostic - Works with any framework or vanilla JavaScript
• Performance First - Optimized for speed with minimal bundle size (~2KB)
• Developer Experience - Clean, intuitive decorator-based API
• Production Ready - Battle-tested in real-world applications

🚀 Perfect For

• Web Components Projects - Enhance native Web Components with powerful decorators
• Progressive Enhancement - Build on web standards, not frameworks
• Performance-Critical Apps - Minimal overhead, maximum speed
• Learning Modern APIs - Learn Web Components with a friendly API
• Micro-Frontends - Isolated components with clean interfaces

✨ Key Features

🎯 Declarative First

Describe your components' behavior declaratively, not imperatively:

// Imperative (traditional)
class MyComponent extends HTMLElement {
  constructor() {
    super();
    this.attachShadow({ mode: "open" });
    this.shadowRoot.addEventListener("click", this.handleClick.bind(this));
    this.render();
  }

  handleClick() { /* ... */ }
  render() { /* ... */ }
}

// Declarative (Spark)
@paint(template, styles)
class MyComponent extends HTMLElement {
  @event.click("button")
  handleClick() { /* ... */ }
}

📦 Tree-Shakeable

Only import what you need:

// Only imports what you use (~2KB)
import { define, attributeChanged } from "@adalink/spark-std/directive";
import { paint, html } from "@adalink/spark-std/dom";

⚡ High Performance

• Adopted stylesheets (parse once, reuse everywhere)
• Event delegation (single listener per component)
• Lazy rendering (only when needed)
• No virtual DOM overhead

🔗 Integração com Spark Ecosystem

O Spark Std é a fundação do Spark Ecosystem, trabalhando em harmonia com outras bibliotecas Spark para criar aplicações web reativas completas.

📦 Pacotes Relacionados

@adalink/spark-echo - Sistema de comunicação reativa entre componentes

Use Spark Echo para adicionar comunicação reativa aos seus componentes criados com Spark Std:

import { define, paint, html, css } from "@adalink/spark-std/directive";
import { paint as paintDom, html as htmlDom, css as cssDom } from "@adalink/spark-std/dom";
import { event } from "@adalink/spark-std/event";
import Echo from "@adalink/spark-echo";

@define("spark-message-box")
@paintDom(template, styles)
class MessageBox extends Echo(HTMLElement) {
  #message = "";

  get message() {
    return this.#message;
  }

  set message(value) {
    this.#message = value;
    this.dispatchEvent(new CustomEvent("message-changed", {
      detail: this.#message,
      bubbles: true,
      composed: true
    }));
  }

  @event.click("button.send")
  sendMessage() {
    this.message = this.shadowRoot.querySelector("input").value;
  }
}

// Outro componente que ouve as mudanças
@define("spark-display")
@paintDom(displayTemplate, displayStyles)
class Display extends Echo(HTMLElement) {
  #displayValue = "";

  // Declarative event arc via HTML
  // <spark-display on="*message-changed:method/update"></spark-display>

  update({ detail }) {
    this.#displayValue = detail;
    this.render();
  }

  render() {
    this.shadowRoot.innerHTML = `<div>${this.#displayValue}</div>`;
  }
}

function template(component) {
  return htmlDom`
    <div class="message-box">
      <input type="text" placeholder="Digite uma mensagem">
      <button class="send">Enviar</button>
    </div>
  `;
}

function styles(component) {
  return cssDom`
    .message-box {
      display: flex;
      gap: 0.5rem;
    }
    input {
      flex: 1;
      padding: 0.5rem;
    }
    button {
      padding: 0.5rem 1rem;
      background: #667eea;
      color: white;
      border: none;
      border-radius: 4px;
    }
  `;
}

Funcionalidades Combinadas:

• ✅ Spark Std fornece decorators (@define, @paint, @event)
• ✅ Spark Echo fornece comunicação reativa via event arcs
• ✅ Use decorators para definir comportamento do componente
• ✅ Use event arcs para comunicação entre componentes
• ✅ Ambos funcionam com Web Components nativos

Ecosystem Diagram:

┌─────────────────────────────────────────────────────┐
│                  Application Layer                 │
└───────────────────┬─────────────────────────────────┘
                    │
┌───────────────────▼─────────────────────────────────┐
│              Spark Framework Layer                 │
│  ┌──────────────────────────────────────────────┐  │
│  │          @adalink/spark-std                  │  │
│  │  ┌──────────┐  ┌─────┐  ┌────────┐         │  │
│  │  │Directive │  │ DOM │  │ Event  │         │  │
│  │  └──────────┘  └─────┘  └────────┘         │  │
│  │  ┌──────────┐                               │  │
│  │  │Polyfill  │                               │  │
│  │  └──────────┘                               │  │
│  └──────────────────────────────────────────────┘  │
│  ┌──────────────────────────────────────────────┐  │
│  │          @adalink/spark-echo                 │  │
│  │  ┌──────────┐  ┌─────┐  ┌────────┐         │  │
│  │  │   Echo   │  │Filter│  │ Target │         │  │
│  │  └──────────┘  └─────┘  └────────┘         │  │
│  └──────────────────────────────────────────────┘  │
└───────────────────┬─────────────────────────────────┘
                    │
┌───────────────────▼─────────────────────────────────┐
│              Web Platform APIs                     │
│  Custom Elements, Shadow DOM, EventTarget          │
└─────────────────────────────────────────────────────┘

Quando usar Spark Std vs Spark Echo:

• Spark Std: Para construir componentes individuais com decorators reativos
• Spark Echo: Para comunicação reativa entre componentes
• Juntos: Para aplicações web reativas completas

🚀 Quick Start

Installation

Option 1: Install from npm (Recommended)

# Using npm
npm install @adalink/spark-std

# Using yarn
yarn add @adalink/spark-std

# Using pnpm
pnpm add @adalink/spark-std

# Using bun
bun add @adalink/spark-std

Option 2: Install from GitHub (Alternative)

# Install directly from GitHub repository
npm install github:Adalink-ai/spark_std#v1.3.0

Option 3: Use as Development Dependency

{
  "dependencies": {
    "@adalink/spark-std": "^1.3.0"
  }
}

Option 4: Import from CDN (Browser Only)

// Import modules from unpkg or jsDelivr (ESM)
import { define, attributeChanged } from "https://unpkg.com/@adalink/[email protected]/dist/directive.js";
import { paint, html, css } from "https://unpkg.com/@adalink/[email protected]/dist/dom.js";
import { event } from "https://unpkg.com/@adalink/[email protected]/dist/event.js";

⚠️ Important Notice: This package is private and published to npm. To install it:

1. Have an npm account
2. Request access to the @adalink scope from the maintainers
3. Configure npm authentication in your environment

Installation Options:

• npm registry (recommended) - Requires npm authentication and scope access
• GitHub (alternative) - Works without npm authentication, installs directly from repository
• CDN (browser only) - Import modules directly from unpkg or jsDelivr, no build step required

Available Modules:

• @adalink/spark-std/directive - Lifecycle decorators
• @adalink/spark-std/dom - Rendering utilities
• @adalink/spark-std/event - Event decorators

💡 Dica: Combine com @adalink/spark-echo para adicionar comunicação reativa entre seus componentes. Veja a seção Integração com Spark Ecosystem para exemplos.

Your First Component

Create a reactive counter in seconds:

import { define, attributeChanged } from "@adalink/spark-std/directive";
import { paint, repaint, html, css } from "@adalink/spark-std/dom";
import { event } from "@adalink/spark-std/event";

@define("spark-counter")
@paint(template, styles)
class Counter extends HTMLElement {
  #count = 0;

  get count() {
    return this.#count;
  }

  @attributeChanged("count", Number)
  @repaint
  set count(value) {
    this.#count = value;
  }

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

  @event.click("button")
  increment() {
    this.count += 1;
  }

  @event.click("button.reset")
  reset() {
    this.count = 0;
  }
}

function template(counter) {
  return html`
    <div class="counter">
      <h2>Count: ${counter.count}</h2>
      <button class="increment">+1</button>
      <button class="reset">Reset</button>
    </div>
  `;
}

function styles(counter) {
  return css`
    .counter {
      font-family: system-ui, sans-serif;
      text-align: center;
      padding: 2rem;
    }
    button {
      margin: 0.5rem;
      padding: 0.5rem 1rem;
      font-size: 16px;
      cursor: pointer;
      background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
      color: white;
      border: none;
      border-radius: 4px;
    }
    button:hover {
      transform: translateY(-2px);
      box-shadow: 0 4px 8px rgba(102, 126, 234, 0.3);
    }
  `;
}

Use it in your HTML:

<spark-counter count="0"></spark-counter>

📦 Packages

Spark is organized into four independent, tree-shakeable packages:

🎯 Directive

Lifecycle and attribute decorators for Custom Elements.

import {
  define,           // Register custom element
  connected,        // connectedCallback
  disconnected,     // disconnectedCallback
  adopted,          // adoptedCallback
  attributeChanged  // attributeChangedCallback
} from "@adalink/spark-std/directive";

@define("my-component")
@connected
class MyComponent extends HTMLElement {
  connectedCallback() {
    // Called when element is inserted into DOM
  }
}

Features:

• ✅ Lifecycle callbacks (connected, disconnected, adopted, execute)
• ✅ Attribute change observation with type conversion
• ✅ Form-associated element support
• ✅ Clean decorator-based API

🎨 DOM

Rendering and styling utilities with reactive capabilities.

import { paint, repaint, html, css } from "@adalink/spark-std/dom";

@paint(template, styles)
class MyComponent extends HTMLElement {
  @repaint
  update() {
    // Triggers re-render
  }
}

function template(component) {
  return html`<div>Hello, ${component.name}!</div>`;
}

function styles(component) {
  return css`div { color: blue; }`;
}

Features:

• ✅ Shadow DOM integration
• ✅ Adopted stylesheets for performance
• ✅ Reactive template updates
• ✅ Lifecycle hooks (willPaint, didPaint)

⚡ Event

Dynamic event listener decorator with automatic lifecycle management.

import { event } from "@adalink/spark-std/event";

class MyComponent extends HTMLElement {
  @event.click("button.action")
  handleClick(event) {
    // Event delegation for performance
  }

  @event.input("input[type='text']")
  handleInput(event) {
    // Reactive to input changes
  }
}

Features:

• ✅ Works with any DOM event
• ✅ Event delegation for performance
• ✅ Automatic cleanup (no memory leaks)
• ✅ Support for custom events

🎯 Real-World Use Cases

Form Components

@define("spark-input")
@paint(template, styles)
class Input extends HTMLElement {
  #value = "";

  get value() {
    return this.#value;
  }

  @attributeChanged("value", String)
  @repaint
  set value(newValue) {
    this.#value = newValue;
  }

  @event.input("input")
  handleInput() {
    this.value = this.shadowRoot.querySelector("input").value;
    this.dispatchEvent(new CustomEvent("change", { detail: this.value }));
  }

  render() {
    return html`
      <div class="input-wrapper">
        <label>${this.getAttribute("label") || "Input"}</label>
        <input
          type="${this.getAttribute("type") || "text"}"
          placeholder="${this.getAttribute("placeholder") || ""}"
          value="${this.value}"
        />
      </div>
    `;
  }

  styles() {
    return css`
      .input-wrapper {
        display: flex;
        flex-direction: column;
        gap: 0.5rem;
      }
      input {
        padding: 0.5rem;
        border: 1px solid #ccc;
        border-radius: 4px;
        font-family: system-ui, sans-serif;
      }
    `;
  }
}

Data Fetching

@define("spark-data-loader")
@paint(template, styles)
class DataLoader extends HTMLElement {
  #data = null;
  #loading = false;

  get data() {
    return this.#data;
  }

  @repaint
  async loadData() {
    this.#loading = true;
    const url = this.getAttribute("url");
    const response = await fetch(url);
    this.#data = await response.json();
    this.#loading = false;
  }

  @event.click("button.load")
  load() {
    this.loadData();
  }

  connectedCallback() {
    if (this.getAttribute("autoload") === "true") {
      this.loadData();
    }
  }

  render() {
    if (this.#loading) {
      return html`<div class="loading">Loading...</div>`;
    }

    if (!this.#data) {
      return html`
        <div class="empty">
          <p>No data loaded</p>
          <button class="load">Load Data</button>
        </div>
      `;
    }

    return html`
      <div class="data">
        <pre>${JSON.stringify(this.#data, null, 2)}</pre>
      </div>
    `;
  }

  styles() {
    return css`
      .loading, .empty, .data {
        padding: 1rem;
        border: 1px solid #eee;
        border-radius: 4px;
      }
      button {
        padding: 0.5rem 1rem;
        cursor: pointer;
        background: #667eea;
        color: white;
        border: none;
        border-radius: 4px;
      }
    `;
  }
}

📊 Why Spark Over Alternatives?

| Feature | Spark | Lit | React | Vue | |---------|-------|-----|-------|-----| | Zero Dependencies | ✅ | ✅ | ❌ | ❌ | | Native Web Components | ✅ | ✅ | ⚠️ | ⚠️ | | Declarator API | ✅ | ❌ | ❌ | ⚠️ | | Event Delegation | ✅ | ❌ | ✅ | ✅ | | No Build Required | ✅ | ✅ | ❌ | ❌ | | Bundle Size | ~2KB | ~8KB | ~40KB | ~35KB | | Framework Agnostic | ✅ | ✅ | ❌ | ❌ | | Decorator Pattern | ✅ | ❌ | ❌ | ❌ |

🌐 Usage in Frameworks

With React

import { define, paint, html, css } from "@adalink/spark-std/directive";
import { event } from "@adalink/spark-std/event";

@define("react-spark-component")
class SparkComponent extends HTMLElement {
  @event.click("button")
  handleClick() {
    this.dispatchEvent(new CustomEvent("react-click"));
  }
}

// In React
function App() {
  const handleClick = () => {
    console.log("Clicked!");
  };

  return (
    <react-spark-component onReactClick={handleClick} />
  );
}

With Vue

import { define, paint, html, css } from "@adalink/spark-std/directive";

@define("vue-spark-component")
class SparkComponent extends HTMLElement {
  // Your component logic
}

// In Vue
<template>
  <vue-spark-component @vue-click="handleClick" />
</template>

🛠️ Development

Prerequisites

• Node.js 18+

Setup

# Clone repository
git clone https://github.com/Adalink-ai/spark_std.git
cd spark_std

# Install dependencies
npm install

# Build package
npm run build

# Start development server
npm run dev

# Lint and format
npx biome check .
npx biome check --write .

📚 Documentation

• Architecture: ARCHITECTURE.md - Design decisions and patterns
• Contributing: CONTRIBUTING.md - Development guidelines
• Security: SECURITY.md - Security policies
• Changelog: CHANGELOG.md - Project changes
• Authors: AUTHORS.md - Author information

🤝 Contributing

We welcome contributions! Please read our Contributing Guide before getting started.

Ways to contribute:

• 🐛 Report bugs
• 💡 Suggest features
• 📖 Improve documentation
• 🔧 Submit pull requests

👥 Author & Community

Cleber de Moraes Goncalves - Creator & Lead Maintainer

• 📧 Email: [email protected]
• 🐙 GitHub: deMGoncalves
• 💼 LinkedIn: deMGoncalves
• 📸 Instagram: deMGoncalves

🌟 Star the Project

If you find Spark useful, please ⭐ star it on GitHub!

📢 Share

Share Spark with your network:

• Twitter
• LinkedIn

🌐 Spark Ecosystem

O Spark Ecosystem é um conjunto de bibliotecas para desenvolvimento web reativo:

• @adalink/spark-std - Biblioteca padrão com decorators para Web Components
• @adalink/spark-echo - Sistema de comunicação reativa entre componentes

Mais pacotes em breve:

• @adalink/spark-form - Componentes de formulário reativos (em breve)
• @adalink/spark-router - Roteamento SPA (em breve)

📄 License

Apache-2.0 © 2026 Adalink

🔗 Links

• Repository: github.com/Adalink-ai/spark_std
• NPM Package: npmjs.com/package/@adalink/spark-std
• Organization: github.com/Adalink-ai

Built with ❤️ by Adalink

Spark Standard Library - Build better web components, faster. ⚡