From 40eaabc7ed7291a5d92de8492aef0c354111b03e Mon Sep 17 00:00:00 2001 From: Jan Andrle Date: Thu, 16 Nov 2023 20:48:58 +0100 Subject: [PATCH] Update README.md --- README.md | 68 ++++++++++++++++++++++++++++++++++++------------------- 1 file changed, 45 insertions(+), 23 deletions(-) diff --git a/README.md b/README.md index a43d058..e21d8b8 100644 --- a/README.md +++ b/README.md @@ -1,49 +1,71 @@ **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) ***Vanilla by default — steroids if needed*** + *…use simple DOM API by default and library tools and logic when you need them* ```js -const value= S(""); document.body.append( - el("span", { style: { fontWeight: "bold" }, textContent: value }), - el("input", { type: "text" }, - on("change", event=> value(event.target.value))) + el("h1", "Hello World 👋"), + el("p", "See some syntax examples here:"), + el("ul").append( + el("li").append( + el("a", { textContent: "Link to the library repo", title: "Deka DOM El — GitHub", href: "https://github.com/jaandrle/deka-dom-el" }) + ), + el("li").append( + "Use extended Vanilla JavaScript DOM/IDL API: ", + el("span", { textContent: "» this is a span with class=cN and data-a=A, data-b=B «", className: "cN", dataset: { a: "A", b: "B" } }) + ), + el("li").append( + el(component, { textContent: "A component", className: "example" }, on("change", console.log)) + ) + ) + ); +function component({ textContent, className }){ + const value= S("onchange"); + + return el().append( + el("p", { textContent, className }), + el("p", { className: [ className, "second-line" ] }).append( + "…with reactivity: ", el("em", { style: { fontWeight: "bold" }, ariaset: { live: "polite" }, textContent: value }), + ), + el("input", { type: "text", value: value() }, on("change", event=> value(event.target.value))) + ); +} ``` # 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 ([Signals — whats going on behind the scenes | by Ryan Hoffnan | ITNEXT](https://itnext.io/signals-whats-going-on-behind-the-scenes-ec858589ea63) or [The Evolution of Signals in JavaScript - DEV Community](https://dev.to/this-is-learning/the-evolution-of-signals-in-javascript-8ob)). ## Inspiration and suggested alternatives -- my previous (mostly internal) library: [jaandrle/dollar_dom_component: Functional DOM components without JSX and virtual DOM.](https://github.com/jaandrle/dollar_dom_component) +- 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) ## Why an another one? -This library should lies somewhere between van/hyperscript and [solid-js](https://github.com/solidjs/solid) (S). -In the meaning of size, complexity and usability. +This library falls somewhere between van/hyperscript and [solid-js](https://github.com/solidjs/solid) in terms of size, complexity, +and usability. -An another goal is making clear library logic. Starting from pure native JavaScript (DOM API), -then using small utils (`assign`, `S`, …, `el`, …) and end up with way to write complex code. -Therefore, you can use any „internal” function to make live with native JavaScript easier -(`assign`, `classListDeclarative`, `on`, `dispatchEvent`, …, `S`, …) regarding if you -need complex library/framework. +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. -As consequence of that, it shouldn’t be hard to incorporate the library into existing projects. -That can make potecial migration easier. +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. -To balance all requirements above, lots of compromises have been made. To sumarize: -- [x] library size 10–15kB minified (10kB originaly) -- [x] allow using *signals optionaly* and allow registering *own signals implementation* -- [x] *no build step required* -- [x] prefer a *declarative/functional* approach -- [x] prefer zero/minimal dependencies -- [ ] support/enhance custom elements (web components) -- [x] support SSR ([jsdom](https://github.com/jsdom/jsdom)) -- [ ] WIP provide types +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 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 ## First steps - [**Guide**](https://jaandrle.github.io/deka-dom-el)