⚡ dde and docs improvements (#27)

* ⚡ 🎉

* ⚡ wip

* 🔤

* ⚡ wip

* ⚡ wip

* ⚡ Refatc signals to .get/.set syntax #26

* 🐛 Better types for on*

* 🔤

* 🔤

* 🐛 coumputed signal

* 🔤 ⚡ Docs UI/UX

* ⚡ 🔤 UI enhancements

* ⚡ (bs) (un)min

* 🔤 adds debugging

* 🔤 ssr

* 🔤

* ⚡ bs/lint

* 🔤

* 🔤 UI

* 🔤 updates texts

* 🔤UI

* ⚡ dispatch

* 🔤 events

* 🔤 elements

* 🔤 intro

* 🐛 fixes completitions for el with components

* 🐛 wrong file(s) in git

* 🔤 logo

* 🐛 🔤 types 3ps

* 🔤 ui/ux

* 🔤

* 🔤

* 🔤 scopes

* 🔤

* 🔤 ui/ux

* 🔤

* ⚡ issignal

* 🔤 improvemens

* ⚡ irelands

* 🔤 UI/UX/wording

* 🐛 npx-hint

[Scrollable region must have keyboard access | Axe Rules | Deque University | Deque Systems](https://dequeuniversity.com/rules/axe/4.10/scrollable-region-focusable?application=axeAPI)

* 🔤 logos

* ⚡ better? dts builds

* Update README.md

docs/components/examples/customElement/observedAttributes.js

@@ -26,7 +26,7 @@ function ddeComponent({ attr }){
 		on.connected(e=> console.log(( /** @type {HTMLParagraphElement} */ (e.target)).outerHTML)),
 	);
 	return el().append(
-		el("p", S(()=> `Hello from Custom Element with attribute '${attr()}'`))
+		el("p", S(()=> `Hello from Custom Element with attribute '${attr.get()}'`))
 	);
 }
 customElementWithDDE(HTMLCustomElement);

docs/components/examples/debugging/consoleLog.js

@@ -0,0 +1,15 @@
+// Debugging a (derived) signal with `console.log`
+import { S } from "deka-dom-el/signals";
+const name= S("Alice");
+const greeting = S(() => {
+	// log derived signals
+	const log = "Hello, " + name.get();
+	console.log(log);
+	console.log(name.valueOf());
+	return log;
+});
+
+// log signals in general
+S.on(greeting, value => console.log("Greeting changed to:", value));
+
+name.set("Bob"); // Should trigger computation and listener`)

docs/components/examples/debugging/debouncing.js

@@ -0,0 +1,15 @@
+import { S } from "deka-dom-el/signals";
+// Debouncing signal updates
+function debounce(func, wait) {
+	let timeout;
+	return (...args)=> {
+		clearTimeout(timeout);
+		timeout= setTimeout(() => func(...args), wait);
+	};
+}
+
+const inputSignal= S("");
+const debouncedSet= debounce(value => inputSignal.set(value), 300);
+
+// In your input handler
+inputElement.addEventListener("input", e=> debouncedSet(e.target.value));

docs/components/examples/debugging/dom-reactive-mark.js

@@ -0,0 +1,4 @@
+// Example of reactive element marker
+<!--<dde:mark type=\"reactive\" source=\"...\">-->
+<!-- content that updates when signal changes -->
+<!--</dde:mark>-->

docs/components/examples/debugging/mutations.js

@@ -0,0 +1,15 @@
+import { S } from "deka-dom-el/signals";
+// Wrong - direct mutation doesn't trigger updates
+const todos1 = S([{ text: "Learn signals", completed: false }]);
+todos1.get().push({ text: "Debug signals", completed: false }); // Won't trigger updates!
+
+// Correct - using .set() with a new array
+todos1.set([...todos1.get(), { text: "Debug signals", completed: false }]);
+
+// Better - using actions
+const todos2 = S([], {
+	add(text) {
+		this.value.push({ text, completed: false });
+	}
+});
+S.action(todos2, "add", "Debug signals");

docs/components/examples/elements/dde-dom-create.js

@@ -0,0 +1,14 @@
+import { el } from "deka-dom-el";
+
+// Create element with properties
+const button = el("button", {
+	textContent: "Click me",
+	className: "primary",
+	disabled: true
+});
+
+// Shorter and more expressive
+// than the native approach
+
+// Add to DOM
+document.body.append(button);

docs/components/examples/elements/dde-dom-tree.js

@@ -0,0 +1,11 @@
+import { el } from "deka-dom-el";
+
+// Chainable, natural nesting
+// append() returns parent element
+// making chains easy and intuitive
+document.body.append(
+	el("div").append(
+		el("h1", "Title"),
+		el("p", "Paragraph")
+	)
+);

docs/components/examples/elements/native-dom-create.js

@@ -0,0 +1,19 @@
+// Create element with properties
+const button = document.createElement('button');
+button.textContent = "Click me";
+button.className = "primary";
+button.disabled = true;
+
+// Or using Object.assign()
+const button2 = Object.assign(
+	document.createElement('button'),
+	{
+	textContent: "Click me",
+	className: "primary",
+	disabled: true
+	}
+);
+
+// Add to DOM
+document.body.appendChild(button);
+document.body.appendChild(button2);

docs/components/examples/elements/native-dom-tree.js

@@ -0,0 +1,15 @@
+// Verbose, needs temp variables
+const div = document.createElement('div');
+const h1 = document.createElement('h1');
+h1.textContent = 'Title';
+div.appendChild(h1);
+
+const p = document.createElement('p');
+p.textContent = 'Paragraph';
+div.appendChild(p);
+
+// appendChild doesn't return parent
+// so chaining is not possible
+
+// Add to DOM
+document.body.appendChild(div);

docs/components/examples/events/append-event.js

@@ -0,0 +1,8 @@
+import { el, on } from "deka-dom-el";
+
+// Third approach - append with on addon
+el("button", {
+	textContent: "click me"
+}).append(
+	on("click", (e) => console.log("Clicked!", e))
+);

docs/components/examples/events/attribute-event.js

@@ -0,0 +1,7 @@
+import { el } from "deka-dom-el";
+
+// Using events with HTML attribute style
+el("button", {
+	textContent: "click me",
+	"=onclick": "console.log(event)"
+});

docs/components/examples/events/chain-event.js

@@ -0,0 +1,8 @@
+import { el, on } from "deka-dom-el";
+
+// Using events as addons - chainable approach
+el("button", {
+	textContent: "click me",
+},
+	on("click", (e) => console.log("Clicked!", e))
+);

docs/components/examples/events/native-event.js

@@ -0,0 +1,2 @@
+// Standard DOM event listener approach
+element.addEventListener('click', callback, options);

docs/components/examples/events/property-event.js

@@ -0,0 +1,7 @@
+import { el } from "deka-dom-el";
+
+// Using events with property assignment
+el("button", {
+	textContent: "click me",
+	onclick: console.log
+});

docs/components/examples/introducing/3ps-before.js

@@ -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;
+	}
+});

docs/components/examples/introducing/3ps.js

@@ -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);
+});

docs/components/examples/introducing/helloWorld.js

@@ -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()) // B
-		)),
-		el("button", {
-			type: "button",
-			onclick: ()=> clicks(clicks()+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: "🎉" })
+);

docs/components/examples/ireland-test/counter.js

@@ -0,0 +1,37 @@
+import { el } from "deka-dom-el";
+import { S } from "deka-dom-el/signals";
+
+const className = "client-side-counter";
+document.body.append(
+	el("style").append(`
+.${className} {
+	border: 1px dashed #ccc;
+	padding: 1em;
+	margin: 1em;
+}
+		`.trim())
+);
+
+export function CounterStandard() {
+	// Create reactive state with a signal
+	const count = S(0);
+
+	// Create UI components that react to state changes
+	return el("div", { className }).append(
+		el("h4", "Client-Side Counter"),
+		el("div", {
+			// The textContent updates automatically when count changes
+			textContent: S(() => `Count: ${count.get()}`),
+		}),
+		el("div", { className: "controls" }).append(
+			el("button", {
+				onclick: () => count.set(count.get() - 1),
+				textContent: "-",
+			}),
+			el("button", {
+				onclick: () => count.set(count.get() + 1),
+				textContent: "+",
+			})
+		)
+	);
+}

docs/components/examples/scopes/custom-scope.js

@@ -0,0 +1,14 @@
+import { scope } from "deka-dom-el";
+import { S } from "deka-dom-el/signals";
+
+function customSignalLogic() {
+	// Create an isolated scope for a specific operation
+	scope.push(); // Start new scope
+
+	// These signals are in the new scope
+	const isolatedCount = S(0);
+	const isolatedDerived = S(() => isolatedCount.get() * 2);
+
+	// Clean up by returning to previous scope
+	scope.pop();
+}

docs/components/examples/scopes/declarative.js

@@ -1,35 +1,26 @@
-/* PSEUDO-CODE!!! */
 import { el } from "deka-dom-el";
 import { S } from "deka-dom-el/signals";
-function component(){
-	/* prepare changeable data */
-	const dataA= S("data");
-	const dataB= S("data");
-	/* define data flow (can be asynchronous) */
-	fetchAPI().then(data_new=> dataA(data_new));
-	setTimeout(()=> dataB("DATA"));
-	/* declarative UI */
-	return el().append(
-		el("h1", {
-			textContent: "Example",
-			/* declarative attribute(s) */
-			classList: { declarative: dataB }
-		}),
-		el("ul").append(
-			/* declarative element(s) */
-			S.el(dataA, data=> data.map(d=> el("li", d)))
-		),
-		el("ul").append(
-			/* declarative component(s) */
-			S.el(dataA, data=> data.map(d=> el(subcomponent, d)))
-		)
+function Counter() {
+	// Define state
+	const count = S(0);
+
+	// Define behavior
+	const increment = () => count.set(count.get() + 1);
+
+	// Define data flow
+	setTimeout(increment, 1000);
+	// or fetchAPI().then(increment);
+
+	// Declarative UI (how to render data/`count`)
+	// …automatically updates when changes
+	return el("div").append(
+		// declarative element(s)
+		el("p", S(() => "Count: " + count.get())),
+		el("button", {
+			onclick: increment,
+			textContent: "Increment",
+			// declarative attribute(s)
+			disabled: S(() => count.get() >= 10)
+		})
 	);
 }
-function subcomponent({ id }){
-	/* prepare changeable data */
-	const textContent= S("…");
-	/* define data flow (can be asynchronous) */
-	fetchAPI(id).then(text=> textContent(text));
-	/* declarative UI */
-	return el("li", { textContent, dataId: id });
-}

docs/components/examples/scopes/imperative.js

@@ -1,31 +1,25 @@
 /* PSEUDO-CODE!!! */
-import { el, on, scope } from "deka-dom-el";
-function component(){
-	const { host }= scope;
-	const ul= el("ul");
-	const ac= new AbortController();
-	fetchAPI({ signal: ac.signal }).then(data=> {
-		data.forEach(d=> ul.append(el("li", d)));
-	});
-	host(
-		/* element was remove before data fetched */
-		on.disconnected(()=> ac.abort())
+import { el, scope } from "deka-dom-el";
+function Counter() {
+	const { host } = scope;
+
+	let count = 0;
+	const counterText = el("p", "Count: 0");
+
+	// Manually update DOM element
+	const increment = () => {
+		count++;
+		counterText.textContent = "Count: " + count;
+		host().querySelector("button").disabled = count >= 10;
+	};
+	setTimeout(increment, 1000);
+	// or fetchAPI().then(increment);
+
+	return el("div").append(
+		counterText,
+		el("button", {
+			onclick: increment,
+			textContent: "Increment"
+		})
 	);
-	return ul;
-	/**
-	 * NEVER EVER!!
-	 * let data;
-	 * fetchAPI().then(d=> data= O(d));
-	 *
-	 * OR NEVER EVER!!
-	 * const ul= el("ul");
-	 * fetchAPI().then(d=> {
-	 *	const data= O("data");
-	 *	ul.append(el("li", data));
-	 * });
-	 *
-	 * // THE HOST IS PROBABLY DIFFERENT THAN
-	 * // YOU EXPECT AND OBSERVABLES MAY BE
-	 * // UNEXPECTEDLY REMOVED!!!
-	 * */
 }

docs/components/examples/scopes/mixed.js

@@ -0,0 +1,36 @@
+/* PSEUDO-CODE!!! */
+import { el, scope } from "deka-dom-el";
+import { S } from "deka-dom-el/signals";
+function Counter() {
+	const { host } = scope;
+
+	let count = S(0);
+	const counterText = el("p", "Count: 0");
+	S.on(count, c=> counterText.textContent= "Count: " + c);
+
+	// Manually update DOM element
+	const increment = () => {
+		count.set(count.get() + 1);
+		// NEVER EVER
+		// count = S(count.get() + 1);
+		// THE HOST IS PROBABLY DIFFERENT THAN
+		// YOU EXPECT AND SIGNAL MAY BE
+		// UNEXPECTEDLY REMOVED!!!
+		host().querySelector("button").disabled = count.get() >= 10;
+	};
+	setTimeout(()=> {
+		// ok, BUT consider extract to separate function
+		// see section below for more info
+		const ok= S(0);
+		S.on(ok, console.log);
+		setInterval(()=> ok.set(ok.get() + 1), 100);
+	}, 100);
+
+	return el("div").append(
+		counterText,
+		el("button", {
+			onclick: increment,
+			textContent: "Increment"
+		})
+	);
+}

docs/components/examples/scopes/with-scope.js

@@ -0,0 +1,45 @@
+import { el, scope } from "deka-dom-el";
+import { S } from "deka-dom-el/signals";
+
+function CounterWithIsolatedTimer() {
+	const { host } = scope;
+
+	// Main component state
+	const count = S(0);
+
+	// Create a timer in an isolated scope
+	scope.isolate(() => {
+	// These subscriptions won't be tied to the component lifecycle
+	// They would continue to run even if the component was removed
+	const timer = S(0);
+
+	// Not recommended for real applications!
+	// Just demonstrating scope isolation
+	setInterval(() => {
+		timer.set(timer.get() + 1);
+		console.log(`Timer: ${timer.get()}`);
+	}, 1000);
+	});
+
+	// Normal component functionality within main scope
+	function increment() {
+	count.set(count.get() + 1);
+	}
+
+	return el("div").append(
+	el("p").append(
+		"Count: ",
+		el("#text", S(() => count.get()))
+	),
+	el("button", {
+		textContent: "Increment",
+		onclick: increment
+	}),
+	el("p", "An isolated timer runs in console")
+	);
+}
+
+// Usage
+document.body.append(
+	el(CounterWithIsolatedTimer)
+);

docs/components/examples/signals/actions-demo.js

@@ -15,4 +15,4 @@ setTimeout(
 	clearInterval,
 	10*interval,
 	setInterval(oninterval, interval)
-);
+);

docs/components/examples/signals/actions-todos.js

@@ -22,9 +22,9 @@ const onsubmit= on("submit", function(event){
 			S.action(todos, "push", data.get("todo"));
 			break;
 		case "E"/*dit*/: {
-			const last= todos().at(-1);
+			const last= todos.get().at(-1);
 			if(!last) break;
-			last(data.get("todo"));
+			last.set(data.get("todo"));
 			break;
 		}
 		case "R"/*emove*/:

docs/components/examples/signals/computations-abort.js

@@ -1,16 +1,16 @@
 import { S } from "deka-dom-el/signals";
 const signal= S(0);
 // computation pattern
-const double= S(()=> 2*signal());
+const double= S(()=> 2*signal.get());
 
 const ac= new AbortController();
 S.on(signal, v=> console.log("signal", v), { signal: ac.signal });
 S.on(double, v=> console.log("double", v), { signal: ac.signal });
 
-signal(signal()+1);
+signal.set(signal.get()+1);
 const interval= 5 * 1000;
-const id= setInterval(()=> signal(signal()+1), interval);
+const id= setInterval(()=> signal.set(signal.get()+1), interval);
 ac.signal.addEventListener("abort",
 	()=> setTimeout(()=> clearInterval(id), 2*interval));
 
-setTimeout(()=> ac.abort(), 3*interval)
+setTimeout(()=> ac.abort(), 3*interval)

docs/components/examples/signals/debugging-console.js

@@ -0,0 +1,20 @@
+import { S } from "deka-dom-el/signals";
+
+// Debugging a derived signal
+const name = S('Alice');
+const greeting = S(() => {
+	console.log('Computing greeting...');
+	return 'Hello, ' + name.get();
+});
+
+// Monitor the derived signal
+S.on(greeting, value => console.log('Greeting changed to:', value));
+
+// Later update the dependency
+name.set('Bob'); // Should trigger computation and listener
+
+// Console output:
+// Computing greeting...
+// Greeting changed to: Hello, Alice
+// Computing greeting...
+// Greeting changed to: Hello, Bob

docs/components/examples/signals/debugging-dom.js

@@ -0,0 +1,38 @@
+import { el, on, scope } from "deka-dom-el";
+import { S } from "deka-dom-el/signals";
+
+// Create a component with reactive elements
+function ReactiveCounter() {
+	const count = S(0);
+		scope.host(on.connected(ev=>
+				console.log(ev.target.__dde_reactive)
+		));
+
+	const counter = el('div', {
+		// This element will be added into the __dde_reactive property
+		textContent: count,
+	});
+
+	const incrementBtn = el('button', {
+		textContent: 'Increment',
+		onclick: () => count.set(count.get() + 1)
+	});
+
+	// Dynamic section will be added into __dde_signal property
+	const counterInfo = S.el(count, value =>
+		el('p', `Current count is ${value}`)
+	);
+
+	return el('div', { id: 'counter' }).append(
+		counter,
+		incrementBtn,
+		counterInfo
+	);
+}
+document.body.append(
+	el(ReactiveCounter),
+);
+
+// In DevTools console:
+const counter = document.querySelector('#counter');
+setTimeout(()=> console.log(counter.__dde_reactive), 1000); // See reactive bindings

docs/components/examples/signals/derived.js

@@ -0,0 +1,13 @@
+import { S } from "deka-dom-el/signals";
+
+// Create base signals
+const firstName = S("John");
+const lastName = S("Doe");
+
+// Create a derived signal
+const fullName = S(() => firstName.get() + " " + lastName.get());
+
+// The fullName signal updates automatically when either dependency changes
+S.on(fullName, name => console.log("Name changed to:", name));
+
+firstName.set("Jane"); // logs: "Name changed to: Jane Doe"

docs/components/examples/signals/dom-attrs.js

@@ -3,8 +3,8 @@ const count= S(0);
 
 import { el } from "deka-dom-el";
 document.body.append(
-	el("p", S(()=> "Currently: "+count())),
-	el("p", { classList: { red: S(()=> count()%2 === 0) }, dataset: { count }, textContent: "Attributes example" }),
+	el("p", S(()=> "Currently: "+count.get())),
+	el("p", { classList: { red: S(()=> count.get()%2 === 0) }, dataset: { count }, textContent: "Attributes example" }),
 );
 document.head.append(
 	el("style", ".red { color: red; }")
@@ -12,4 +12,4 @@ document.head.append(
 
 const interval= 5 * 1000;
 setTimeout(clearInterval, 10*interval,
-	setInterval(()=> count(count()+1), interval));
+	setInterval(()=> count.set(count.get()+1), interval));

docs/components/examples/signals/dom-el.js

@@ -2,7 +2,7 @@ import { S } from "deka-dom-el/signals";
 const count= S(0, {
 	add(){ this.value= this.value + Math.round(Math.random()*10); }
 });
-const numbers= S([ count() ], {
+const numbers= S([ count.get() ], {
 	push(next){ this.value.push(next); }
 });
 
@@ -22,5 +22,5 @@ document.body.append(
 const interval= 5*1000;
 setTimeout(clearInterval, 10*interval, setInterval(function(){
 	S.action(count, "add");
-	S.action(numbers, "push", count());
-}, interval));
+	S.action(numbers, "push", count.get());
+}, interval));

docs/components/examples/signals/signals.js

@@ -1,10 +1,10 @@
 import { S } from "deka-dom-el/signals";
-// α — `signal` represents a reactive value
+// PART 1 — `signal` represents a reactive value
 const signal= S(0);
-// β — just reacts on signal changes
+// PART 2 — just reacts on signal changes
 S.on(signal, console.log);
-// γ — just updates the value
-const update= ()=> signal(signal()+1);
+// PART 3 — just updates the value
+const update= ()=> signal.set(signal.get()+1);
 
 update();
 const interval= 5*1000;

docs/components/examples/ssr/async-data.js

@@ -0,0 +1,43 @@
+// Handling async data in SSR
+import { JSDOM } from "jsdom";
+import { S } from "deka-dom-el/signals";
+import { register, queue } from "deka-dom-el/jsdom";
+
+async function renderWithAsyncData() {
+	const dom = new JSDOM("<!DOCTYPE html><html><body></body></html>");
+	const { el } = await register(dom);
+
+	// Create a component that fetches data
+	function AsyncComponent() {
+			const title= S("-");
+			const description= S("-");
+
+		// Use the queue to track the async operation
+		queue(fetch("https://api.example.com/data")
+			.then(response => response.json())
+			.then(data => {
+				title.set(data.title);
+				description.set(data.description);
+			}));
+
+		return el("div", { className: "async-content" }).append(
+				el("h2", title),
+				el("p", description)
+		);
+	}
+
+	// Render the page
+	dom.window.document.body.append(
+		el("h1", "Page with Async Data"),
+		el(AsyncComponent)
+	);
+
+	// IMPORTANT: Wait for all queued operations to complete
+	await queue();
+
+	// Now the HTML includes all async content
+	const html = dom.serialize();
+	console.log(html);
+}
+
+renderWithAsyncData();

docs/components/examples/ssr/basic-example.js

@@ -0,0 +1,47 @@
+// Basic SSR Example
+import { JSDOM } from "jsdom";
+import { register, queue } from "deka-dom-el/jsdom";
+import { writeFileSync } from "node:fs";
+
+async function renderPage() {
+	// Create a jsdom instance
+	const dom = new JSDOM("<!DOCTYPE html><html><head><meta charset=\"utf-8\"></head><body></body></html>");
+
+	// Register with deka-dom-el and get the el function
+	const { el } = await register(dom);
+
+	// Create a simple header component
+	function Header({ title }) {
+		return el("header").append(
+			el("h1", title),
+			el("nav").append(
+				el("ul").append(
+					el("li").append(el("a", { href: "/" }, "Home")),
+					el("li").append(el("a", { href: "/about" }, "About")),
+					el("li").append(el("a", { href: "/contact" }, "Contact"))
+				)
+			)
+		);
+	}
+
+	// Create the page content
+	dom.window.document.body.append(
+		el(Header, { title: "My Static Site" }),
+		el("main").append(
+			el("h2", "Welcome!"),
+			el("p", "This page was rendered with deka-dom-el on the server.")
+		),
+		el("footer", "© 2025 My Company")
+	);
+
+	// Wait for any async operations
+	await queue();
+
+	// Get the HTML and write it to a file
+	const html = dom.serialize();
+	writeFileSync("index.html", html);
+
+	console.log("Page rendered successfully!");
+}
+
+renderPage().catch(console.error);

docs/components/examples/ssr/intro.js

@@ -0,0 +1,2 @@
+// use NPM or for example https://cdn.jsdelivr.net/gh/jaandrle/deka-dom-el/dist/esm-with-signals.js
+import { register, unregister, queue } from "deka-dom-el/jsdom";

docs/components/examples/ssr/pages.js

@@ -0,0 +1,35 @@
+// ❌ WRONG: Static imports are hoisted and will register before JSDOM is created
+import { register } from "deka-dom-el/jsdom";
+import { el } from "deka-dom-el";
+import { Header } from "./components/Header.js";
+
+// ✅ CORRECT: Use dynamic imports to ensure proper initialization order
+import { JSDOM } from "jsdom";
+
+async function renderPage() {
+	// 1. Create JSDOM instance first
+	const dom = new JSDOM(`<!DOCTYPE html><html><body></body></html>`);
+
+	// 2. Dynamically import jsdom module
+	const { register, queue } = await import("deka-dom-el/jsdom");
+
+	// 3. Register and get el function
+	const { el } = await register(dom);
+
+	// 4. Dynamically import page components
+	const { Header } = await import("./components/Header.js");
+	const { Content } = await import("./components/Content.js");
+
+	// 5. Render components
+	const body = dom.window.document.body;
+	el(body).append(
+		el(Header, { title: "My Page" }),
+		el(Content, { text: "This is server-rendered content" })
+	);
+
+	// 6. Wait for async operations
+	await queue();
+
+	// 7. Get HTML and clean up
+	return dom.serialize();
+}

docs/components/examples/ssr/start.js

@@ -0,0 +1,27 @@
+// Basic jsdom integration example
+import { JSDOM } from "jsdom";
+import { register, unregister, queue } from "deka-dom-el/jsdom.js";
+
+// Create a jsdom instance
+const dom = new JSDOM("<!DOCTYPE html><html><body></body></html>");
+
+// Register the dom with deka-dom-el
+const { el } = await register(dom);
+
+// Use deka-dom-el normally
+dom.window.document.body.append(
+	el("div", { className: "container" }).append(
+		el("h1", "Hello, SSR World!"),
+		el("p", "This content was rendered on the server.")
+	)
+);
+
+// Wait for any async operations to complete
+await queue();
+
+// Get the rendered HTML
+const html = dom.serialize();
+console.log(html);
+
+// Clean up when done
+unregister();

docs/components/examples/ssr/static-site-generator.js

@@ -0,0 +1,44 @@
+// Building a simple static site generator
+import { JSDOM } from "jsdom";
+import { register, queue } from "deka-dom-el/jsdom";
+import { writeFileSync, mkdirSync } from "node:fs";
+
+async function buildSite() {
+	// Define pages to build
+	const pages = [
+		{ id: "index", title: "Home", component: "./pages/home.js" },
+		{ id: "about", title: "About", component: "./pages/about.js" },
+		{ id: "docs", title: "Documentation", component: "./pages/docs.js" }
+	];
+
+	// Create output directory
+	mkdirSync("./dist", { recursive: true });
+
+	// Build each page
+	for (const page of pages) {
+		// Create a fresh jsdom instance for each page
+		const dom = new JSDOM("<!DOCTYPE html><html><head><meta charset=\"utf-8\"></head><body></body></html>");
+
+		// Register with deka-dom-el
+		const { el } = await register(dom);
+
+		// Import the page component
+		const { default: PageComponent } = await import(page.component);
+
+		// Render the page with its metadata
+		dom.window.document.body.append(
+			el(PageComponent, { title: page.title, pages })
+		);
+
+		// Wait for any async operations
+		await queue();
+
+		// Write the HTML to a file
+		const html = dom.serialize();
+		writeFileSync(`./dist/${page.id}.html`, html);
+
+		console.log(`Built page: ${page.id}.html`);
+	}
+}
+
+buildSite().catch(console.error);