**WIP** (the experimentation phase)
| [source code on GitHub](https://github.com/jaandrle/deka-dom-el)
| [*mirrored* on Gitea](https://gitea.jaandrle.cz/jaandrle/deka-dom-el)

<p align="center">
	<img src="docs/assets/logo.svg" alt="Deka DOM Elements Logo" width="180" height="180">
</p>

# Deka DOM Elements (dd\<el\> or DDE)

***Vanilla for flavouring — a full-fledged feast for large projects***

*…use simple DOM API by default and library tools and logic when you need them*

```javascript
// 🌟 Reactive component with clear separation of concerns
document.body.append(
	el(EmojiCounter, { initial: "🚀" })
);

function EmojiCounter({ initial }) {
	// ✨ State - Define reactive data
	const count = S(0);
	const emoji = S(initial);

	/** @param {HTMLOptionElement} el */
	const isSelected= el=> (el.selected= el.value===initial);

	// 🔄 View - UI updates automatically when signals change
	return el().append(
		el("p", {
			className: "output",
			textContent: S(() =>
				`Hello World ${emoji.get().repeat(clicks.get())}`),
		}),

		// 🎮 Controls - Update state on events
		el("button", { textContent: "Add Emoji" },
			on("click", () => count.set(count.get() + 1))
		),

		el("select", null,
			on("change", e => emoji.set(e.target.value))
		).append(
			el(Option, "🎉", isSelected),
			el(Option, "🚀", isSelected),
			el(Option, "💖", isSelected),
		)
	);
}
function Option({ textContent }){
	return el("option", { value: textContent, textContent });
}
```

Creating reactive elements, components, and Web Components using the native
[IDL](https://developer.mozilla.org/en-US/docs/Glossary/IDL)/JavaScript DOM API enhanced with
[**signals/observables**](#understanding-signals).

## Features at a Glance

- ✅ **No build step required** — use directly in browsers or Node.js
- ☑️ **Lightweight** — ~10-15kB minified (original goal 10kB) with zero/minimal dependencies
- ✅ **Declarative & functional approach** for clean, maintainable code
- ✅ **Signals and events** for reactive UI
- ✅ **Optional build-in signals** with support for custom reactive implementations
- ✅ **Server-side rendering** support via [jsdom](https://github.com/jsdom/jsdom)
- ✅ **TypeScript support** (work in progress)
- ☑️ **Support for debugging with browser DevTools** without extensions
- ☑️ **Enhanced Web Components** support (work in progress)

## Why Another Library?

This library bridges the gap between minimal solutions like van/hyperscript and more comprehensive frameworks like
[solid-js](https://github.com/solidjs/solid), offering a balanced trade-off between size, complexity, and usability.

Following functional programming principles, dd\<el\> starts with pure JavaScript (DOM API) and gradually adds
auxiliary functions. These range from minor improvements to advanced features for building complete declarative
reactive UI templates.

A key advantage: any internal function (`assign`, `classListDeclarative`, `on`, `dispatchEvent`, `S`, etc.) can be used
independently while also working seamlessly together. This modular approach makes it easier to integrate the library
into existing projects.

## Getting Started

### Installation

#### npm
```bash
# TBD
# npm install deka-dom-el
```

#### Direct Script
```html
<script src="https://cdn.jsdelivr.net/gh/jaandrle/deka-dom-el/dist/iife-with-signals.min.js"></script>
<script type="module">
	const { el, S } = DDE;
</script>
```

### Documentation

- [**Interactive Guide**](https://jaandrle.github.io/deka-dom-el): WIP
- [Examples](./examples/): TBD/WIP

## Understanding Signals

Signals are the reactive backbone of Deka DOM Elements:

- [Signals — what's going on behind the scenes](https://itnext.io/signals-whats-going-on-behind-the-scenes-ec858589ea63)
- [The Evolution of Signals in JavaScript](https://dev.to/this-is-learning/the-evolution-of-signals-in-javascript-8ob)
- [TC39 Signals Proposal](https://github.com/tc39/proposal-signals) (future standard)
- [Observer pattern](https://en.wikipedia.org/wiki/Observer_pattern) (underlying concept)

## Inspiration and Alternatives

- [vanjs-org/van](https://github.com/vanjs-org/van) - World's smallest reactive UI framework
- [adamhaile/S](https://github.com/adamhaile/S) - Simple, clean, fast reactive programming
- [hyperhype/hyperscript](https://github.com/hyperhype/hyperscript) - Create HyperText with JavaScript
- [potch/signals](https://github.com/potch/signals) - A small reactive signals library
- [jaandrle/dollar_dom_component](https://github.com/jaandrle/dollar_dom_component) -
	Functional DOM components without JSX/virtual DOM