jaandrle/deka-dom-el
1
0
Fork 0
mirror of https://github.com/jaandrle/deka-dom-el synced 2025-04-03 04:25:53 +02:00
Code Packages Releases Activity

🔤 intro

Browse Source
This commit is contained in:
Jan Andrle 2025-03-05 15:29:53 +01:00
parent 9ed6de2f8a
commit 8f0879196f
6 changed files with 247 additions and 119 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

162
README.md
View File

@ -2,94 +2,110 @@
| [source code on GitHub](https://github.com/jaandrle/deka-dom-el)
| [*mirrored* on Gitea](https://gitea.jaandrle.cz/jaandrle/deka-dom-el)
# Deka DOM Elements
***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(HelloWorldComponent, { initial: "🚀" })
el(EmojiCounter, { initial: "🚀" })
);
/** @typedef {"🎉" | "🚀"} Emoji */
/** @param {{ initial: Emoji }} attrs */
function HelloWorldComponent({ initial }){
const clicks= S(0);
const emoji= S(initial);
/** @param {HTMLOptionElement} el */
const isSelected= el=> (el.selected= el.value===initial);
// @ts-expect-error 2339: The <select> has only two options with {@link Emoji}
const onChange= on("change", event=> emoji.set(event.target.value));
return el().append(
el("p", {
textContent: S(() => `Hello World ${emoji.get().repeat(clicks.get())}`),
className: "example",
ariaLive: "polite", //OR ariaset: { live: "polite" },
dataset: { example: "Example" }, //OR dataExample: "Example",
}),
el("button",
{ textContent: "Fire", type: "button" },
on("click", ()=> clicks.set(clicks.get() + 1)),
on("keyup", ()=> clicks.set(clicks.get() - 2)),
),
el("select", null, onChange).append(
el(OptionComponent, "🎉", isSelected),//OR { textContent: "🎉" }
el(OptionComponent, "🚀", isSelected),//OR { textContent: "🚀" }
)
);
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 OptionComponent({ textContent }){
return el("option", { value: textContent, textContent })
function Option({ textContent }){
return Ol("option", { value: textContent, textContent });
}
```
# Deka DOM Elements
Creating reactive elements, components and Web components using [IDL](https://developer.mozilla.org/en-US/docs/
Glossary/IDL)/JavaScript DOM API and [**signals/observables**](#signals).
## Inspiration and suggested alternatives
- my previous library (mostly used internaly): [jaandrle/dollar_dom_component: Functional DOM components without
JSX and virtual DOM.](https://github.com/jaandrle/dollar_dom_component)
- [vanjs-org/van: 🍦 VanJS: World's smallest reactive UI framework. Incredibly Powerful, Insanely Small -
Everyone can build a useful UI app in an hour.](https://github.com/vanjs-org/van)
- [hyperhype/hyperscript: Create HyperText with JavaScript.](https://github.com/hyperhype/hyperscript)
- [adamhaile/S: S.js - Simple, Clean, Fast Reactive Programming in Javascript](https://github.com/adamhaile/S)
([adamhaile/surplus: High performance JSX web views for S.js applications](https://github.com/adamhaile/surplus))
- [potch/signals: a small reactive signals library](https://github.com/potch/signals)
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).
## Why an another one?
This library falls somewhere between van/hyperscript and [solid-js](https://github.com/solidjs/solid) in terms of size,
complexity, and usability.
## Features at a Glance
Another goal is to proceed in the best spirit of functional programming. This involves starting with
pure JavaScript (DOM API) and gradually adding auxiliary functions, ranging from “minor” improvements
to the capability of writing complete declarative reactive UI templates.
- ✅ **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
- ✅ **Optional signals** with support for custom reactive implementations
- ✅ **Server-side rendering** support via [jsdom](https://github.com/jsdom/jsdom)
- 🔄 **TypeScript support** (work in progress)
- 🔄 **Enhanced Web Components** support (work in progress)
As a result, any “internal” function (`assign`, `classListDeclarative`, `on`, `dispatchEvent`, …, `S`, …)
can be used independently, although they are primarily designed for use in combination. This can also,
hopefully, help in integrating the library into existing projects.
## Why Another Library?
To balance these requirements, numerous compromises have been made. To summarize:
- [ ] Library size: 10–15kB minified (the original goal was a maximum of 10kB)
- [x] Optional use of *signals* with the ability to register *your own signals/observables implementation*
- [x] *No build step required*
- [x] Preference for a *declarative/functional* approach
- [x] Focus on zero/minimal dependencies
- [ ] Support for/enhancement of custom elements (web components)
- [x] Support for SSR ([jsdom](https://github.com/jsdom/jsdom))
- [ ] WIP providing types
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.
## First steps
- [**Guide**](https://jaandrle.github.io/deka-dom-el)
- Documentation
- Installation
- npm
- [dist/](dist/) (`https://cdn.jsdelivr.net/gh/jaandrle/deka-dom-el/dist/`…)
Following functional programming principles, Deka DOM Elements 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.
## Signals
- [Signals — whats going on behind the scenes \| by Ryan Hoffnan \|
ITNEXT](https://itnext.io/signals-whats-going-on-behind-the-scenes-ec858589ea63)
- [The Evolution of Signals in JavaScript - DEV
Community](https://dev.to/this-is-learning/the-evolution-of-signals-in-javascript-8ob)
- there is also [tc39/proposal-signals:
A proposal to add signals to JavaScript.](https://github.com/tc39/proposal-signals)
- [Observer pattern - Wikipedia](https://en.wikipedia.org/wiki/Observer_pattern)
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/dde-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

14
docs/components/examples/introducing/3ps-before.js Normal file
View File

@ -0,0 +1,14 @@
// pseudocode
// Mixed concerns make code hard to maintain
const button = document.querySelector('button');
let count = 0;
button.addEventListener('click', () => {
count++;
document.querySelector('p').textContent =
'Clicked ' + count + ' times';
if (count > 10) {
button.disabled = true;
}
});

20
docs/components/examples/introducing/3ps.js
View File

@ -1,6 +1,14 @@
// pseudo code!
const onchage=
event=>
console.log("Reacting to the:", event); // A
input.addEventListener("change", onchange); // B
input.dispatchEvent(new Event("change")); // C
// pseudocode
// 1. Create state
const count = S(0);
// 2. React to state changes
S.on(count, value => {
updateUI(value);
if (value > 10) disableButton();
});
// 3. Update state on events
button.addEventListener('click', () => {
count.set(count.get() + 1);
});

45
docs/components/examples/introducing/helloWorld.js
View File

@ -1,19 +1,30 @@
import { el } from "deka-dom-el";
import { el, on } from "deka-dom-el";
import { S } from "deka-dom-el/signals";
const threePS= ({ emoji= "🚀" })=> {
const clicks= S(0); // A
return el().append(
el("p", S(()=>
"Hello World "+emoji.repeat(clicks.get()) // B
)),
el("button", {
type: "button",
onclick: ()=> clicks.set(clicks.get()+1), // C
textContent: "Fire",
})
);
};
document.body.append(
el(threePS, { emoji: "🎉" }),
);
// A HelloWorld component using the 3PS pattern
function HelloWorld({ emoji = "🚀" }) {
// PART 1: Create reactive state
const clicks = S(0);
return el().append(
// PART 2: Bind state to UI elements
el("p", {
className: "greeting",
// This paragraph automatically updates when clicks changes
textContent: S(() => `Hello World ${emoji.repeat(clicks.get())}`)
}),
// PART 3: Update state in response to events
el("button", {
type: "button",
textContent: "Add emoji",
// When clicked, update the state
onclick: () => clicks.set(clicks.get() + 1)
})
);
}
// Use the component in your app
document.body.append(
el(HelloWorld, { emoji: "🎉" })
);

95
docs/index.html.js
View File

@ -2,7 +2,7 @@ import { t, T } from "./utils/index.js";
export const info= {
href: "./",
title: t`Introduction`,
description: t`Introducing a library.`,
description: t`A lightweight, reactive DOM library for creating dynamic UIs with a declarative syntax`,
};
import { el } from "deka-dom-el";
@ -26,37 +26,86 @@ const references= {
export function page({ pkg, info }){
const page_id= info.id;
return el(simplePage, { info, pkg }).append(
el("p", t`The library tries to provide pure JavaScript tool(s) to create reactive interfaces using …`),
el(h3, t`Event-driven programming (3 parts separation ≡ 3PS)`),
el("p").append(t`
Let's introduce the basic principle on which the library is built. We'll use the JavaScript listener as
a starting point.
`),
el(code, { src: fileURL("./components/examples/introducing/3ps.js"), page_id }),
el("h2", t`Vanilla for flavouring — a full-fledged feast for large projects`),
el("p").append(...T`
As we can see, in the code at location “A” we define ${el("em", t`how to react`)} when the function
is called with any event as an argument. At that moment, we ${el("em", t`don’t care who/why/how`)}
the function was called. Similarly, at point “B”, we reference to a function to be called on the event
${el("em", t`without caring`)} what the function will do at that time. Finally, at point “C”, we tell
the application that a change has occurred, in the input, and we ${el("em", t`don't care if/how someone`)}
is listening for the event.
Welcome to Deka DOM Elements (DDE) — a lightweight library for building dynamic UIs with a
declarative syntax that stays close to the native DOM API. DDE gives you powerful reactive
tools without the complexity and overhead of larger frameworks.
`),
el("div", { className: "callout" }).append(
el("h4", t`What Makes DDE Special`),
el("ul").append(
el("li", t`No build step required — use directly in the browser`),
el("li", t`Lightweight core (~10-15kB minified) with zero dependencies`),
el("li", t`Natural DOM API — work with real DOM nodes, not abstractions`),
el("li", t`Built-in reactivity with powerful signals system`),
el("li", t`Clean code organization with the 3PS pattern`)
)
),
el(example, { src: fileURL("./components/examples/introducing/helloWorld.js"), page_id }),
el(h3, t`The 3PS Pattern: A Better Way to Build UIs`),
el("p").append(...T`
The library introduces a new “type” of variable/constant called ${el("em", t`signal`)} allowing us to
to use introduced 3PS pattern in our applications. As you can see it in the example above.
At the heart of DDE is the 3PS (3-Part Separation) pattern. This simple yet powerful approach helps you
organize your UI code into three distinct areas, making your applications more maintainable and easier to reason about.
`),
el("div", { className: "illustration" }).append(
el("div", { className: "tabs" }).append(
el("div", { className: "tab" }).append(
el("h5", t`Traditional DOM Manipulation`),
el(code, { src: fileURL("./components/examples/introducing/3ps-before.js"), page_id }),
),
el("div", { className: "tab" }).append(
el("h5", t`DDE's 3PS Pattern`),
el(code, { src: fileURL("./components/examples/introducing/3ps.js"), page_id }),
)
)
),
el("p").append(...T`
Also please notice that there is very similar 3PS pattern used for separate creation of UI and
business logic.
The 3PS pattern separates your code into three clear parts:
`),
el("ol").append(
el("li").append(...T`
${el("strong", "Create State")}: Define your application's reactive data using signals
`),
el("li").append(...T`
${el("strong", "Bind to Elements")}: Define how UI elements react to state changes
`),
el("li").append(...T`
${el("strong", "Update State")}: Modify state in response to user events or other triggers
`)
),
el("p").append(...T`
The 3PS is very simplified definition of the pattern. There are more deep/academic definitions more precisely
describe usage in specific situations, see for example ${el("a", { textContent: t`MVVM`, ...references.w_mvv })}
or ${el("a", { textContent: t`MVC`, ...references.w_mvc })}.
By separating these concerns, your code becomes more modular, testable, and easier to maintain. This approach
shares principles with more formal patterns like ${el("a", { textContent: "MVVM", ...references.w_mvv })} and
${el("a", { textContent: "MVC", ...references.w_mvc })}, but with less overhead and complexity.
`),
el(h3, t`Organization of the documentation`),
el("div", { className: "note" }).append(
el("p").append(...T`
The 3PS pattern becomes especially powerful when combined with components, allowing you to create
reusable pieces of UI with encapsulated state and behavior. You'll learn more about this in the
following sections.
`)
),
el(h3, t`How to Use This Documentation`),
el("p").append(...T`
This guide will take you through DDE's features step by step:
`),
el("ol").append(
el("li").append(...T`${el("strong", "Elements")} — Creating and manipulating DOM elements`),
el("li").append(...T`${el("strong", "Events")} — Handling user interactions and lifecycle events`),
el("li").append(...T`${el("strong", "Signals")} — Adding reactivity to your UI`),
el("li").append(...T`${el("strong", "Scopes")} — Managing component lifecycles`),
el("li").append(...T`${el("strong", "Custom Elements")} — Building web components`),
el("li").append(...T`${el("strong", "Debugging")} — Tools to help you build and fix your apps`),
el("li").append(...T`${el("strong", "SSR")} — Server-side rendering with DDE`)
),
el("p").append(...T`
Each section builds on the previous ones, so we recommend following them in order.
Let's get started with the basics of creating elements!
`),
);
}

30
nohup.out Normal file
View File

@ -0,0 +1,30 @@
Markserv boot: starting Markserv...
(node:130669) [DEP0128] DeprecationWarning: Invalid 'main' field in '/home/jaandrle/.npm/_npx/13a70f167aa91a98/node_modules/implant/package.json' of 'implant'. Please either fix that or report it to the module author
(Use `node --trace-deprecation ...` to show where the warning was created)
(node:130669) [DEP0128] DeprecationWarning: Invalid 'main' field in '/home/jaandrle/.npm/_npx/13a70f167aa91a98/node_modules/balanced-pairs/package.json' of 'balanced-pairs'. Please either fix that or report it to the module author
(node:130669) [DEP0128] DeprecationWarning: Invalid 'main' field in '/home/jaandrle/.npm/_npx/13a70f167aa91a98/node_modules/super-split/package.json' of 'super-split'. Please either fix that or report it to the module author
Markserv address: http://localhost:8642
Markserv path: /home/jaandrle/Vzdálené/GitHub/deka-dom-el
Markserv livereload: communicating on port: 35729
Markserv process: your pid is: 130669
Markserv stop: press [Ctrl + C] or type "sudo kill -9 130669"
GitHub Contribute on Github - github.com/markserv
Markserv upgrade: checking for upgrade...
Markserv upgrade: no upgrade available
Markserv dir: /home/jaandrle/Vzdálené/GitHub/deka-dom-el/
Markserv markdown: /home/jaandrle/Vzdálené/GitHub/deka-dom-el/README.md
Markserv markdown: /home/jaandrle/Vzdálené/GitHub/deka-dom-el/README.md
Markserv markdown: /home/jaandrle/Vzdálené/GitHub/deka-dom-el/README.md
Markserv markdown: /home/jaandrle/Vzdálené/GitHub/deka-dom-el/README.md
Markserv markdown: /home/jaandrle/Vzdálené/GitHub/deka-dom-el/README.md
Markserv markdown: /home/jaandrle/Vzdálené/GitHub/deka-dom-el/README.md
Markserv markdown: /home/jaandrle/Vzdálené/GitHub/deka-dom-el/README.md
Markserv markdown: /home/jaandrle/Vzdálené/GitHub/deka-dom-el/README.md
Markserv markdown: /home/jaandrle/Vzdálené/GitHub/deka-dom-el/README.md
Could not find the language '~', did you forget to load/include a language module?
Markserv markdown: /home/jaandrle/Vzdálené/GitHub/deka-dom-el/README.md
Markserv markdown: /home/jaandrle/Vzdálené/GitHub/deka-dom-el/README.md
Markserv markdown: /home/jaandrle/Vzdálené/GitHub/deka-dom-el/README.md
Markserv markdown: /home/jaandrle/Vzdálené/GitHub/deka-dom-el/README.md
Markserv markdown: /home/jaandrle/Vzdálené/GitHub/deka-dom-el/README.md
Markserv markdown: /home/jaandrle/Vzdálené/GitHub/deka-dom-el/README.md