⚡ 🔤

docs/components/code.html.js

@@ -189,6 +189,7 @@ import { el } from "deka-dom-el";
  * */
 export function code({ id, src, content, language= "js", className= host.slice(1), page_id }){
 	if(src) content= s.cat(src);
+	content= normalizeIndentation(content);
 	let dataJS;
 	if(page_id){
 		registerClientPart(page_id);
@@ -198,6 +199,10 @@ export function code({ id, src, content, language= "js", className= host.slice(1
 		el("code", { className: "language-"+language, textContent: content.trim() })
 	);
 }
+export function pre({ content }){
+	content= normalizeIndentation(content);
+	return el("pre").append(el("code", content.trim()));
+}
 let is_registered= {};
 /** @param {string} page_id */
 function registerClientPart(page_id){
@@ -218,3 +223,9 @@ function registerClientPart(page_id){
 
 	is_registered[page_id]= true;
 }
+/** @param {string} src */
+function normalizeIndentation(src){
+	const lines= src.split("\n");
+	const min_indent= Math.min(...lines.map(line=> line.search(/\S/)).filter(i=> i >= 0));
+	return lines.map(line=> line.slice(min_indent)).join("\n");
+}

docs/components/examples/customElement/dde.js

@@ -8,7 +8,8 @@ export class HTMLCustomElement extends HTMLElement{
 	connectedCallback(){
 		customElementRender(
 			this.attachShadow({ mode: "open" }),
-			ddeComponent
+			ddeComponent,
+			this
 		);
 	}
 	set attr(value){ this.setAttribute("attr", value); }

docs/components/examples/customElement/native-basic.js

@@ -9,7 +9,7 @@ export class HTMLCustomElement extends HTMLElement{
 		// nice place to render custom element
 	}
 	attributeChangedCallback(name, oldValue, newValue){
-		// listen to attribute changes (see `observedAttributes`)
+		// listen to attribute changes (see `S.observedAttributes`)
 	}
 	disconnectedCallback(){
 		// nice place to clean up

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

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

docs/components/examples/events/dispatch.js

@@ -0,0 +1,19 @@
+import { el, on, dispatchEvent, scope } from "deka-dom-el";
+document.body.append(
+	el(component),
+);
+
+function component(){
+	const { host }= scope;
+	const dispatchExample= dispatchEvent(
+		"example",
+		{ bubbles: true },
+		host
+	);
+
+	return el("div").append(
+		el("p", "Dispatch events from outside of the component."),
+		el("button", { textContent: "Dispatch", type: "button" },
+			on("click", dispatchExample))
+	);
+}

docs/components/examples/events/live-cycle.js

@@ -1,5 +1,5 @@
 import { el, on } from "deka-dom-el";
-const paragraph= el("p", "See live-cycle events in console.",
+const paragraph= el("p", "See lifecycle events in console.",
 	el=> log({ type: "dde:created", detail: el }),
 	on.connected(log),
 	on.disconnected(log),

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

@@ -8,7 +8,6 @@ button.addEventListener('click', () => {
 	document.querySelector('p').textContent =
 		'Clicked ' + count + ' times';
 
-	if (count > 10) {
+	if (count > 10)
 		button.disabled = true;
-	}
 });

docs/components/examples/introducing/helloWorld.js

@@ -1,4 +1,4 @@
-import { el, on } from "deka-dom-el";
+import { el } from "deka-dom-el";
 import { S } from "deka-dom-el/signals";
 
 // A HelloWorld component using the 3PS pattern

docs/components/examples/scopes/mixed.js

@@ -16,7 +16,9 @@ function Counter() {
 		// THE HOST IS PROBABLY DIFFERENT THAN
 		// YOU EXPECT AND SIGNAL MAY BE
 		// UNEXPECTEDLY REMOVED!!!
-		host().querySelector("button").disabled = count.get() >= 10;
+		S.on(count, (count)=>
+			host().querySelector("button").disabled = count >= 10
+		);
 	};
 	setTimeout(()=> {
 		// ok, BUT consider extract to separate function

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

@@ -1,6 +1,5 @@
 // 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() {
@@ -8,6 +7,27 @@ async function renderWithAsyncData() {
 	const { el } = await register(dom);
 
 	// Create a component that fetches data
+	const { AsyncComponent } = await import("./components/AsyncComponent.js");
+
+	// 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();
+
+// file: components/AsyncComponent.js
+import { el } from "deka-dom-el";
+import { S } from "deka-dom-el/signals";
 function AsyncComponent() {
 		const title= S("-");
 		const description= S("-");
@@ -25,19 +45,3 @@ async function renderWithAsyncData() {
 			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

@@ -11,6 +11,7 @@ async function renderPage() {
 	const { el } = await register(dom);
 
 	// Create a simple header component
+	// can be separated into a separate file and use `import { el } from "deka-dom-el"`
 	function Header({ title }) {
 		return el("header").append(
 			el("h1", title),

docs/components/examples/ssr/pages.js

@@ -17,6 +17,7 @@ async function renderPage() {
 	const { el } = await register(dom);
 
 	// 4. Dynamically import page components
+	// use `import { el } from "deka-dom-el"`
 	const { Header } = await import("./components/Header.js");
 	const { Content } = await import("./components/Content.js");
 

docs/components/examples/ssr/start.js

@@ -1,6 +1,6 @@
 // Basic jsdom integration example
 import { JSDOM } from "jsdom";
-import { register, unregister, queue } from "deka-dom-el/jsdom.js";
+import { register, unregister, queue } from "deka-dom-el/jsdom";
 
 // Create a jsdom instance
 const dom = new JSDOM("<!DOCTYPE html><html><body></body></html>");

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

@@ -12,7 +12,7 @@ async function buildSite() {
 	];
 
 	// Create output directory
-	mkdirSync("./dist", { recursive: true });
+	mkdirSync("./dist/docs", { recursive: true });
 
 	// Build each page
 	for (const page of pages) {
@@ -23,6 +23,7 @@ async function buildSite() {
 		const { el } = await register(dom);
 
 		// Import the page component
+		// use `import { el } from "deka-dom-el"`
 		const { default: PageComponent } = await import(page.component);
 
 		// Render the page with its metadata
@@ -35,7 +36,7 @@ async function buildSite() {
 
 		// Write the HTML to a file
 		const html = dom.serialize();
-		writeFileSync(`./dist/${page.id}.html`, html);
+		writeFileSync(`./dist/docs/${page.id}.html`, html);
 
 		console.log(`Built page: ${page.id}.html`);
 	}

docs/global.css.js

@@ -73,6 +73,7 @@ styles.css`
 
 html {
 	scroll-behavior: smooth;
+	tab-size: var(--tab-size, 2rem);
 }
 
 /* Accessibility improvements */

docs/index.html.js

@@ -36,9 +36,9 @@ export function page({ pkg, info }){
 			el("h4", t`What Makes dd<el> 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`Lightweight core (~10–15kB minified) without unnecessary dependencies (0 at now 😇)`),
 				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`Built-in reactivity with simplified but powerful signals system`),
 				el("li", t`Clean code organization with the 3PS pattern`)
 			)
 		),
@@ -67,7 +67,7 @@ export function page({ pkg, info }){
 		`),
 		el("ol").append(
 			el("li").append(...T`
-				${el("strong", "Create State")}: Define your application's reactive data using signals
+				${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
@@ -87,14 +87,14 @@ export function page({ pkg, info }){
 		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
+				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 dd<el>'s features step by step:
+			This guide will take you through dd<el>’s features step by step:
 		`),
 		el("ol").append(
 			el("li").append(...T`${el("strong", "Elements")} — Creating and manipulating DOM elements`),
@@ -104,13 +104,13 @@ export function page({ pkg, info }){
 			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", "Extensions")} — Integrating third-party functionalities`),
+			el("li").append(...T`${el("strong", "SSR")} — Server-side rendering with dd<el>`),
 			el("li").append(...T`${el("strong", "Ireland Components")} —
 				Creating interactive demos with server-side pre-rendering`),
-			el("li").append(...T`${el("strong", "SSR")} — Server-side rendering with dd<el>`)
 		),
 		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!
+			Let’s get started with the basics of creating elements!
 		`),
 	);
 }

docs/layout/head.html.js

@@ -105,13 +105,8 @@ ${host_nav} a .nav-number {
 }
 @media (max-width: 767px) {
 	${host_nav} {
-		padding: 0.75rem;
 		display: flex;
-		flex-direction: row;
+		flex-flow: row wrap;
-		flex-wrap: wrap;
-		gap: 0.5rem;
-		border-bottom: 1px solid var(--border);
-		border-right: none;
 		justify-content: center;
 	}
 
@@ -121,14 +116,7 @@ ${host_nav} a .nav-number {
 		white-space: nowrap;
 	}
 
-	${host_nav} a .nav-number {
-		width: auto;
-		margin-right: 0.25rem;
-	}
-
 	${host_nav} a:first-child {
-		margin-bottom: 0;
-		margin-right: 0.5rem;
 		min-width: 100%;
 		justify-content: center;
 	}

docs/p02-elements.html.js

@@ -54,7 +54,7 @@ export function page({ pkg, info }){
 			dd<el> provides a simple yet powerful approach to element creation that is declarative, chainable,
 			and maintains a clean syntax close to HTML structure.
 		`),
-		el("div", { class: "callout" }).append(
+		el("div", { className: "callout" }).append(
 			el("h4", t`dd<el> Elements: Key Benefits`),
 			el("ul").append(
 				el("li", t`Declarative element creation with intuitive property assignment`),
@@ -71,10 +71,10 @@ export function page({ pkg, info }){
 		el("p").append(...T`
 			In standard JavaScript, you create DOM elements using the
 			${el("a", references.mdn_create).append(el("code", "document.createElement()"))} method
-			and then set properties individually or with Object.assign():
+			and then set properties individually or with ${el("code", "Object.assign()")}:
 		`),
-		el("div", { class: "illustration" }).append(
+		el("div", { className: "illustration" }).append(
-			el("div", { class: "comparison" }).append(
+			el("div", { className: "comparison" }).append(
 				el("div").append(
 					el("h5", t`Native DOM API`),
 					el(code, { src: fileURL("./components/examples/elements/native-dom-create.js"), page_id })
@@ -86,42 +86,45 @@ export function page({ pkg, info }){
 			)
 		),
 		el("p").append(...T`
-			The ${el("code", "el")} function provides a simple wrapper around ${el("code", "document.createElement")}
+			The ${el("code", "el")} function provides a simple wrapper around ${el("code", "document.createElement")}
 			with enhanced property assignment.
 		`),
 		el(example, { src: fileURL("./components/examples/elements/dekaCreateElement.js"), page_id }),
 
 		el(h3, t`Advanced Property Assignment`),
 		el("p").append(...T`
-			The ${el("code", "assign")} function is the heart of dd<el>'s element property handling. It is internally
+			The ${el("code", "assign")} function is the heart of dd<el>’s element property handling. It is internally
 			used to assign properties using the ${el("code", "el")} function. ${el("code", "assign")} provides
 			intelligent assignment of both ${el("a", { textContent: "properties (IDL)", ...references.mdn_idl })}
 			and attributes:
 		`),
-		el("div", { class: "function-table" }).append(
+		el("div", { className: "function-table" }).append(
 			el("dl").append(
 				el("dt", t`Property vs Attribute Priority`),
 				el("dd", t`Prefers IDL properties, falls back to setAttribute() when no writable property exists`),
 
 				el("dt", t`Data and ARIA Attributes`),
-				el("dd", t`Both dataset.* and data-* syntaxes supported (same for ARIA)`),
+				el("dd").append(...T`Both ${el("code", "dataset")}.* and ${el("code", "data-")}* syntaxes supported
+					(same for ${el("em", "ARIA")})`),
 
 				el("dt", t`Style Handling`),
-				el("dd", t`Accepts string or object notation for style property`),
+				el("dd").append(...T`Accepts string or object notation for ${el("code", "style")} property`),
 
 				el("dt", t`Class Management`),
-				el("dd", t`Works with className, class, or classList object for toggling classes`),
+				el("dd").append(...T`Works with ${el("code", "className")}, ${el("code", "class")}, or ${el("code",
+					"classList")} object for toggling classes`),
 
 				el("dt", t`Force Modes`),
-				el("dd", t`Use = prefix to force attribute mode, . prefix to force property mode`),
+				el("dd").append(...T`Use ${el("code", "=")} prefix to force attribute mode, ${el("code", ".")} prefix to
+					force property mode`),
 
 				el("dt", t`Attribute Removal`),
-				el("dd", t`Pass undefined to remove a property or attribute`)
+				el("dd").append(...T`Pass ${el("code", "undefined")} to remove a property or attribute`)
 			)
 		),
 		el(example, { src: fileURL("./components/examples/elements/dekaAssign.js"), page_id }),
 
-		el("div", { class: "note" }).append(
+		el("div", { className: "note" }).append(
 			el("p").append(...T`
 				You can explore standard HTML element properties in the MDN documentation for
 				${el("a", { textContent: "HTMLElement", ...references.mdn_el })} (base class)
@@ -132,16 +135,16 @@ export function page({ pkg, info }){
 		el(h3, t`Building DOM Trees with Chainable Methods`),
 		el("p").append(...T`
 			One of the most powerful features of dd<el> is its approach to building element trees.
-			Unlike the native DOM API which doesn't return the parent after append(), dd<el>'s
+			Unlike the native DOM API which doesn’t return the parent after ${el("code", "append()")}, dd<el>’s
-			append() always returns the parent element:
+			${el("code", "append()")} always returns the parent element:
 		`),
-		el("div", { class: "illustration" }).append(
+		el("div", { className: "illustration" }).append(
-			el("div", { class: "comparison" }).append(
+			el("div", { className: "comparison" }).append(
-				el("div", { class: "bad-practice" }).append(
+				el("div", { className: "bad-practice" }).append(
 					el("h5", t`❌ Native DOM API`),
 					el(code, { src: fileURL("./components/examples/elements/native-dom-tree.js"), page_id })
 				),
-				el("div", { class: "good-practice" }).append(
+				el("div", { className: "good-practice" }).append(
 					el("h5", t`✅ dd<el> Approach`),
 					el(code, { src: fileURL("./components/examples/elements/dde-dom-tree.js"), page_id })
 				)
@@ -149,7 +152,7 @@ export function page({ pkg, info }){
 		),
 		el("p").append(...T`
 			This chainable pattern is much cleaner and easier to follow, especially for deeply nested elements.
-			It also makes it simple to add multiple children to a parent element in a single fluent expression.
+			It also makes it simple to add multiple children to a parent element in a single fluent expression.
 		`),
 		el(example, { src: fileURL("./components/examples/elements/dekaAppend.js"), page_id }),
 
@@ -163,12 +166,17 @@ export function page({ pkg, info }){
 			Component functions receive the properties object as their first argument, just like regular elements.
 			This makes it easy to pass data down to components and create reusable UI fragments.
 		`),
-		el("div", { class: "tip" }).append(
+		el("div", { className: "tip" }).append(
 			el("p").append(...T`
-				It's helpful to use naming conventions similar to native DOM elements for your components.
+				It’s helpful to use naming conventions similar to native DOM elements for your components.
-				This allows you to use ${el("a", { textContent: "destructuring assignment", ...references.mdn_destruct })}
+				This allows you to keeps your code consistent with the DOM API.
-				and keeps your code consistent with the DOM API.
+			`),
-			`)
+			el("p").append(...T`
+				Use ${el("a", { textContent: "destructuring assignment", ...references.mdn_destruct })}
+				to extract the properties from the ${el("code", "props")} and pass them to the component element:
+				${el("code", "function component({ className }){ return el(\"p\", { className }); }")} for make
+				templates cleaner.
+			`),
 		),
 
 		el(h3, t`Working with SVG and Other Namespaces`),
@@ -195,7 +203,7 @@ export function page({ pkg, info }){
 				from the props object for cleaner component code.
 			`),
 			el("li").append(...T`
-				${el("strong", "Leverage chainable methods for better performance:")} Use chainable methods like
+				${el("strong", "Leverage chainable methods for better performance:")} Use chainable methods
 				${el("code", ".append()")} to build complex DOM trees for better performance and cleaner code.
 			`),
 		),

docs/p03-events.html.js

@@ -43,11 +43,11 @@ export function page({ pkg, info }){
 	return el(simplePage, { info, pkg }).append(
 		el("p").append(...T`
 			Events are at the core of interactive web applications. dd<el> provides a clean, declarative approach to
-			handling DOM events and extends this pattern with a powerful Addon system to incorporate additional
+			handling DOM events and extends this pattern with a powerful Addon system to incorporate additional
 			functionalities into your UI templates.
 		`),
 		el("div", { className: "callout" }).append(
-			el("h4", t`Why dd<el>'s Event System and Addons Matters`),
+			el("h4", t`Why dd<el>’s Event System and Addons Matters`),
 			el("ul").append(
 				el("li", t`Integrate event handling directly in element declarations`),
 				el("li", t`Leverage lifecycle events for better component design`),
@@ -63,23 +63,23 @@ export function page({ pkg, info }){
 		el("p").append(...T`
 			In JavaScript you can listen to native DOM events using
 			${el("a", references.mdn_listen).append(el("code", "element.addEventListener(type, listener, options)"))}.
-			dd<el> provides an alternative approach with arguments ordered differently to better fit its declarative
+			dd<el> provides an alternative approach with arguments ordered differently to better fit its declarative
 			style:
 		`),
 		el("div", { className: "illustration" }).append(
 			el("div", { className: "tabs" }).append(
 				el("div", { className: "tab" }).append(
 					el("h5", t`Native DOM API`),
-					el(code, { content: `element.addEventListener('click', callback, options);`, page_id })
+					el(code, { content: `element.addEventListener("click", callback, options);`, page_id })
 				),
 				el("div", { className: "tab" }).append(
 					el("h5", t`dd<el> Approach`),
-					el(code, { content: `on('click', callback, options)(element);`, page_id })
+					el(code, { content: `on("click", callback, options)(element);`, page_id })
 				)
 			)
 		),
 		el("p").append(...T`
-			The main benefit of dd<el>'s approach is that it works as an Addon, making it easy to integrate
+			The main benefit of dd<el>’s approach is that it works as an Addon (see below), making it easy to integrate
 			directly into element declarations.
 		`),
 		el(example, { src: fileURL("./components/examples/events/compare.js"), page_id }),
@@ -92,10 +92,14 @@ export function page({ pkg, info }){
 			`)
 		),
 		el(example, { src: fileURL("./components/examples/events/abortSignal.js"), page_id }),
+		el("p").append(...T`
+			This is the same for signals (see next section) and works well with scopes and library extendability (
+			see scopes and extensions section).
+		`),
 
 		el(h3, t`Three Ways to Handle Events`),
 		el("div", { className: "tabs" }).append(
-			el("div", { className: "tab", "data-tab": "html-attr" }).append(
+			el("div", { className: "tab", dataTab: "html-attr" }).append(
 				el("h4", t`HTML Attribute Style`),
 				el(code, { src: fileURL("./components/examples/events/attribute-event.js"), page_id }),
 				el("p").append(...T`
@@ -104,12 +108,12 @@ export function page({ pkg, info }){
 					useful for SSR scenarios.
 				`)
 			),
-			el("div", { className: "tab", "data-tab": "property" }).append(
+			el("div", { className: "tab", dataTab: "property" }).append(
 				el("h4", t`Property Assignment`),
 				el(code, { src: fileURL("./components/examples/events/property-event.js"), page_id }),
-				el("p", t`Assigns the event handler directly to the element's property.`)
+				el("p", t`Assigns the event handler directly to the element’s property.`)
 			),
-			el("div", { className: "tab", "data-tab": "addon" }).append(
+			el("div", { className: "tab", dataTab: "addon" }).append(
 				el("h4", t`Addon Approach`),
 				el(code, { src: fileURL("./components/examples/events/chain-event.js"), page_id }),
 				el("p", t`Uses the addon pattern (so adds the event listener to the element), see above.`)
@@ -117,12 +121,12 @@ export function page({ pkg, info }){
 		),
 		el("p").append(...T`
 			For a deeper comparison of these approaches, see
-			${el("a", { textContent: "WebReflection's detailed analysis", ...references.web_events })}.
+			${el("a", { textContent: "WebReflection’s detailed analysis", ...references.web_events })}.
 		`),
 
 		el(h3, t`Understanding Addons`),
 		el("p").append(...T`
-			Addons are a powerful pattern in dd<el> that extends beyond just event handling.
+			Addons are a powerful pattern in dd<el> that extends beyond just event handling.
 			An Addon is any function that accepts an HTML element as its first parameter.
 		`),
 		el("div", { className: "callout" }).append(
@@ -147,8 +151,8 @@ export function page({ pkg, info }){
 
 		el(h3, t`Lifecycle Events`),
 		el("p").append(...T`
-			Addons are called immediately when an element is created, even before it's connected to the live DOM.
+			Addons are called immediately when an element is created, even before it’s connected to the live DOM.
-			You can think of an Addon as an "oncreate" event handler.
+			You can think of an Addon as an "oncreate" event handler.
 		`),
 		el("p").append(...T`
 			dd<el> provides two additional lifecycle events that correspond to ${el("a", { textContent:
@@ -167,9 +171,9 @@ export function page({ pkg, info }){
 
 		el("div", { className: "note" }).append(
 			el("p").append(...T`
-				For regular elements (non-custom elements), dd<el> uses
+				For regular elements (non-custom elements), dd<el> uses ${el("a",
-				${el("a", references.mdn_mutation).append(el("code", "MutationObserver"), " | MDN")}
+					references.mdn_mutation).append(el("code", "MutationObserver"), " | MDN")} internally to track
-				internally to track lifecycle events.
+				lifecycle events.
 			`)
 		),
 
@@ -184,7 +188,7 @@ export function page({ pkg, info }){
 					Use lifecycle events sparingly, as they require internal tracking
 				`),
 				el("li").append(...T`
-					Leverage parent-child relationships: when a parent is removed, all children are also removed
+					Leverage parent-child relationships: when a parent is removed, all children are also removed
 				`),
 				el("li").append(...T`
 					…see section later in documentation regarding hosts elements
@@ -197,11 +201,11 @@ export function page({ pkg, info }){
 
 		el(h3, t`Dispatching Custom Events`),
 		el("p").append(...T`
-			This makes it easy to implement component communication through events,
+			This makes it easy to implement component communication through events, following standard web platform
-			following standard web platform patterns. The curried approach allows for easy reuse
+			patterns. The curried approach allows for easy reuse of event dispatchers throughout your application.
-			of event dispatchers throughout your application.
 		`),
 		el(example, { src: fileURL("./components/examples/events/compareDispatch.js"), page_id }),
+		el(code, { src: fileURL("./components/examples/events/dispatch.js"), page_id }),
 
 		el(h3, t`Best Practices`),
 		el("ol").append(
@@ -212,7 +216,8 @@ export function page({ pkg, info }){
 				${el("strong", "Leverage lifecycle events")}: For component setup and teardown
 			`),
 			el("li").append(...T`
-				${el("strong", "Delegate when possible")}: Add listeners to container elements when handling many similar elements
+				${el("strong", "Delegate when possible")}: Add listeners to container elements when handling many
+				similar elements
 			`),
 			el("li").append(...T`
 				${el("strong", "Maintain consistency")}: Choose one event binding approach and stick with it

docs/p04-signals.html.js

@@ -48,7 +48,7 @@ export function page({ pkg, info }){
 			Signals provide a simple yet powerful way to create reactive applications with dd<el>. They handle the
 			fundamental challenge of keeping your UI in sync with changing data in a declarative, efficient way.
 		`),
-		el("div", { class: "callout" }).append(
+		el("div", { className: "callout" }).append(
 			el("h4", t`What Makes Signals Special?`),
 			el("ul").append(
 				el("li", t`Fine-grained reactivity without complex state management`),
@@ -65,18 +65,18 @@ export function page({ pkg, info }){
 			Signals organize your code into three distinct parts, following the
 			${el("a", { textContent: t`3PS principle`, href: "./#h-3ps" })}:
 		`),
-		el("div", { class: "signal-diagram" }).append(
+		el("div", { className: "signal-diagram" }).append(
-			el("div", { class: "signal-part" }).append(
+			el("div", { className: "signal-part" }).append(
 				el("h4", t`PART 1: Create Signal`),
 				el(code, { content: "const count = S(0);", page_id }),
-				el("p", t`Define a reactive value that can be observed and changed`)
+				el("p", t`Define a reactive value that can be observed and changed`)
 			),
-			el("div", { class: "signal-part" }).append(
+			el("div", { className: "signal-part" }).append(
 				el("h4", t`PART 2: React to Changes`),
 				el(code, { content: "S.on(count, value => updateUI(value));", page_id }),
 				el("p", t`Subscribe to signal changes with callbacks or effects`)
 			),
-			el("div", { class: "signal-part" }).append(
+			el("div", { className: "signal-part" }).append(
 				el("h4", t`PART 3: Update Signal`),
 				el(code, { content: "count.set(count.get() + 1);", page_id }),
 				el("p", t`Modify the signal value, which automatically triggers updates`)
@@ -84,26 +84,26 @@ export function page({ pkg, info }){
 		),
 		el(example, { src: fileURL("./components/examples/signals/signals.js"), page_id }),
 
-		el("div", { class: "note" }).append(
+		el("div", { className: "note" }).append(
 			el("p").append(...T`
-				Signals implement the ${el("a", { textContent: t`Publish–subscribe pattern`, ...references.wiki_pubsub })},
+				Signals implement the ${el("a", { textContent: t`Publish–subscribe pattern`, ...references.wiki_pubsub
-				a form of ${el("a", { textContent: t`Event-driven programming`, ...references.wiki_event_driven })}.
+				})}, a form of ${el("a", { textContent: t`Event-driven programming`, ...references.wiki_event_driven
-				This architecture allows different parts of your application to stay synchronized through a shared signal,
+				})}.  This architecture allows different parts of your application to stay synchronized through
-				without direct dependencies on each other. Compare for example with ${el("a", { textContent:
+				a shared signal, without direct dependencies on each other. Compare for example with ${el("a", {
-				t`fpubsub library`, ...references.fpubsub })}.
+					textContent: t`fpubsub library`, ...references.fpubsub })}.
 			`)
 		),
 
 		el(h3, t`Signal Essentials: Core API`),
-		el("div", { class: "function-table" }).append(
+		el("div", { className: "function-table" }).append(
 			el("dl").append(
-				el("dt", t`Creating a Signal`),
+				el("dt", t`Creating a Signal`),
 				el("dd", t`S(initialValue) → creates a signal with the given value`),
 
-				el("dt", t`Reading a Signal`),
+				el("dt", t`Reading a Signal`),
 				el("dd", t`signal.get() → returns the current value`),
 
-				el("dt", t`Writing to a Signal`),
+				el("dt", t`Writing to a Signal`),
 				el("dd", t`signal.set(newValue) → updates the value and notifies subscribers`),
 
 				el("dt", t`Subscribing to Changes`),
@@ -115,51 +115,53 @@ export function page({ pkg, info }){
 			)
 		),
 		el("p").append(...T`
-			Signals can be created with any type of value, but they work best with
+			Signals can be created with any type of value, but they work best with ${el("a", { textContent:
-			${el("a", { textContent: t`primitive types`, ...references.mdn_primitive })} like strings, numbers, and booleans.
+				t`primitive types`, ...references.mdn_primitive })} like strings, numbers, and booleans.  For complex
-			For complex data types like objects and arrays, you'll want to use Actions (covered below).
+			data types like objects and arrays, you’ll want to use Actions (covered below).
 		`),
 
 		el(h3, t`Derived Signals: Computed Values`),
 		el("p").append(...T`
 			Computed values (also called derived signals) automatically update when their dependencies change.
-			Create them by passing a function to S():
+			Create them by passing ${el("strong", "a function")} to ${el("code", "S()")}:
 		`),
 		el(example, { src: fileURL("./components/examples/signals/derived.js"), page_id }),
 		el("p").append(...T`
-			Derived signals are read-only - you can't call .set() on them. Their value is always computed
+			Derived signals are read-only - you can’t call ${el("code", ".set()")} on them. Their value is always
-			from their dependencies. They're perfect for transforming or combining data from other signals.
+			computed from their dependencies. They’re perfect for transforming or combining data from other signals.
 		`),
 		el(example, { src: fileURL("./components/examples/signals/computations-abort.js"), page_id }),
 
 		el(h3, t`Signal Actions: For Complex State`),
 		el("p").append(...T`
-			When working with objects, arrays, or other complex data structures, Signal Actions provide
+			When working with objects, arrays, or other complex data structures. Signal Actions provide
-			a structured way to modify state while maintaining reactivity.
+			a structured way to modify state while maintaining reactivity.
 		`),
-		el("div", { class: "illustration" }).append(
+		el("div", { className: "illustration" }).append(
 			el("h4", t`Actions vs. Direct Mutation`),
-			el("div", { class: "comparison" }).append(
+			el("div", { className: "comparison" }).append(
-				el("div", { class: "good-practice" }).append(
+				el("div", { className: "good-practice" }).append(
 					el("h5", t`✅ With Actions`),
-					el(code, { content: `const todos = S([], {
+					el(code, { content: `
+						const todos = S([], {
 							add(text) {
 								this.value.push(text);
 								// Subscribers notified automatically
 							}
 						});
-
 						// Use the action
-S.action(todos, "add", "New todo");`, page_id })
+						S.action(todos, "add", "New todo");
+					`, page_id })
 				),
-				el("div", { class: "bad-practice" }).append(
+				el("div", { className: "bad-practice" }).append(
 					el("h5", t`❌ Without Actions`),
 					el(code, { content: `
 						const todos = S([]);
 						// Directly mutating the array
 						const items = todos.get();
 						items.push("New todo");
-// This WON'T trigger updates!`, page_id }))
+						// This WON’T trigger updates!
+					`, page_id }))
 				),
 		),
 		el("p").append(...T`
@@ -182,16 +184,19 @@ items.push("New todo");
 			el("li", t`Act similar to reducers in other state management libraries`)
 		),
 		el("p").append(...T`
-			Here's a more complete example of a todo list using signal actions:
+			Here’s a more complete example of a todo list using signal actions:
 		`),
 		el(example, { src: fileURL("./components/examples/signals/actions-todos.js"), page_id }),
 
-		el("div", { class: "tip" }).append(
+		el("div", { className: "tip" }).append(
 			el("p").append(...T`
 				${el("strong", "Special Action Methods")}: Signal actions can implement special lifecycle hooks:
 			`),
 			el("ul").append(
-				el("li", t`[S.symbols.onclear]() - Called when the signal is cleared. Use it to clean up resources.`),
+				el("li").append(...T`
+					${el("code", "[S.symbols.onclear]()")} - Called when the signal is cleared. Use it to clean up
+					resources.
+				`),
 			)
 		),
 
@@ -200,14 +205,15 @@ items.push("New todo");
 			Signals really shine when connected to your UI. dd<el> provides several ways to bind signals to DOM elements:
 		`),
 
-		el("div", { class: "tabs" }).append(
+		el("div", { className: "tabs" }).append(
-			el("div", { class: "tab", "data-tab": "attributes" }).append(
+			el("div", { className: "tab", dataTab: "attributes" }).append(
 				el("h4", t`Reactive Attributes`),
 				el("p", t`Bind signal values directly to element attributes, properties, or styles:`),
-				el(code, { content: `// Create a signal
+				el(code, { content: `
+					// Create a signal
 					const color = S("blue");
 
-// Bind it to an element's style
+					// Bind it to an element’s style
 					el("div", {
 						style: {
 							color, // Updates when signal changes
@@ -216,15 +222,17 @@ el("div", {
 					}, "This text changes color");
 
 					// Later:
-color.set("red"); // UI updates automatically`, page_id })
+					color.set("red"); // UI updates automatically
+				`, page_id }),
 			),
-			el("div", { class: "tab", "data-tab": "elements" }).append(
+			el("div", { className: "tab", dataTab: "elements" }).append(
 				el("h4", t`Reactive Elements`),
 				el("p", t`Dynamically create or update elements based on signal values:`),
-				el(code, { content: `// Create an array signal
+				el(code, { content: `
+					// Create an array signal
 					const items = S(["Apple", "Banana", "Cherry"]);
 
-// Create a dynamic list that updates when items change
+					// Create a dynamic list that updates when items change
 					el("ul").append(
 						S.el(items, items =>
 							items.map(item => el("li", item))
@@ -232,7 +240,8 @@ el("ul").append(
 					);
 
 					// Later:
-S.action(items, "push", "Dragonfruit"); // List updates automatically`, page_id })
+					S.action(items, "push", "Dragonfruit"); // List updates automatically
+				`, page_id }),
 			)
 		),
 
@@ -254,23 +263,24 @@ S.action(items, "push", "Dragonfruit"); // List updates automatically`, page_id
 		`),
 		el("ol").append(
 			el("li").append(...T`
-				${el("strong", "Keep signals small and focused")}: Use many small signals rather than a few large ones
+				${el("strong", "Keep signals small and focused")}: Use many small signals rather than a few large ones
 			`),
 			el("li").append(...T`
-				${el("strong", "Use derived signals for computations")}: Don't recompute values in multiple places
+				${el("strong", "Use derived signals for computations")}: Don’t recompute values in multiple places
 			`),
 			el("li").append(...T`
-				${el("strong", "Clean up signal subscriptions")}: Use AbortController or scope.host() to prevent memory leaks
+				${el("strong", "Clean up signal subscriptions")}: Use AbortController (scope.host()) to prevent memory
+				leaks
 			`),
 			el("li").append(...T`
-				${el("strong", "Use actions for complex state")}: Don't directly mutate objects or arrays in signals
+				${el("strong", "Use actions for complex state")}: Don’t directly mutate objects or arrays in signals
 			`),
 			el("li").append(...T`
-				${el("strong", "Avoid infinite loops")}: Be careful when one signal updates another in a subscription
+				${el("strong", "Avoid infinite loops")}: Be careful when one signal updates another in a subscription
 			`)
 		),
 
-		el("div", { class: "troubleshooting" }).append(
+		el("div", { className: "troubleshooting" }).append(
 			el("h4", t`Common Signal Pitfalls`),
 			el("dl").append(
 				el("dt", t`UI not updating when array/object changes`),

docs/p05-scopes.html.js

@@ -10,7 +10,7 @@ import { simplePage } from "./layout/simplePage.html.js";
 import { example } from "./components/example.html.js";
 import { h3 } from "./components/pageUtils.html.js";
 import { mnemonic } from "./components/mnemonic/scopes-init.js";
-import { code } from "./components/code.html.js";
+import { code, pre } from "./components/code.html.js";
 /** @param {string} url */
 const fileURL= url=> new URL(url, import.meta.url);
 const references= {
@@ -31,7 +31,7 @@ export function page({ pkg, info }){
 	return el(simplePage, { info, pkg }).append(
 		el("p").append(...T`
 			For state-less components we can use functions as UI components (see “Elements” page). But in real life,
-			we may need to handle the component's life-cycle and provide JavaScript the way to properly use
+			we may need to handle the component’s life-cycle and provide JavaScript the way to properly use
 			the ${el("a", { textContent: t`Garbage collection`, ...references.garbage_collection })}.
 		`),
 		el(code, { src: fileURL("./components/examples/scopes/intro.js"), page_id }),
@@ -40,56 +40,56 @@ export function page({ pkg, info }){
 		el(h3, t`Understanding Host Elements and Scopes`),
 		el("p").append(...T`
 			The ${el("strong", "host")} is the name for the element representing the component. This is typically the
-			element returned by a function. To get a reference, you can use ${el("code", "scope.host()")}. To apply addons,
+			element returned by a function. To get a reference, you can use ${el("code", "scope.host()")}. To apply addons,
 			just use ${el("code", "scope.host(...<addons>)")}.
 		`),
 		el("p").append(...T`
 			Scopes are primarily needed when signals are used in DOM templates (with ${el("code", "el")}, ${el("code",
-				"assign")}, or ${el("code", "S.el")}). They provide a way for automatically removing signal listeners
+				"assign")}, or ${el("code", "S.el")}). They provide a way for automatically removing signal listeners
 			and cleaning up unused signals when components are removed from the DOM.
 		`),
 		el("div", { className: "illustration" }).append(
 			el("h4", t`Component Anatomy`),
-			el("pre").append(el("code", `
+			el(pre, { content: `
 				// 1. Component scope created
 				el(MyComponent);
 
 				function MyComponent() {
-  // 2. access the host element
+					// 2. access the host element
-  const { host } = scope;
+					const { host } = scope;
 
-  // 3. Add behavior to host
+					// 3. Add behavior to host
-  host(
+					host(
-  on.click(handleClick)
+						on.click(handleClick)
-  );
+					);
 
-  // 4. Return the host element
+					// 4. Return the host element
-  return el("div", {
+					return el("div", {
-  className: "my-component"
+						className: "my-component"
-  }).append(
+					}).append(
-  el("h2", "Title"),
+						el("h2", "Title"),
-  el("p", "Content")
+						el("p", "Content")
-  );
+					);
 				}
-			`.trim()))
+			` })
 		),
 		el("div", { className: "function-table" }).append(
 			el("h4", t`scope.host()`),
 			el("dl").append(
 				el("dt", t`When called with no arguments`),
-				el("dd", t`Returns a reference to the host element (the root element of your component)`),
+				el("dd", t`Returns a reference to the host element (the root element of your component)`),
 
 				el("dt", t`When called with addons/callbacks`),
-				el("dd", t`Applies the addons to the host element and returns the host element`)
+				el("dd", t`Applies the addons to the host element (and returns the host element)`)
 			)
 		),
 		el(example, { src: fileURL("./components/examples/scopes/scopes-and-hosts.js"), page_id }),
 
 		el("div", { className: "tip" }).append(
 			el("p").append(...T`
-				${el("strong", "Best Practice:")} Always capture the host reference at the beginning of your component
+				${el("strong", "Best Practice:")} Always capture the host reference (or other scope related values) at
-				function using ${el("code", "const { host } = scope")} to avoid scope-related issues, especially with
+				the beginning of your component function using ${el("code", "const { host } = scope")} to avoid
-				asynchronous code.
+				scope-related issues, especially with ${el("em", "asynchronous code")}.
 			`),
 			el("p").append(...T`
 				If you are interested in the implementation details, see Class-Based Components section.
@@ -112,31 +112,32 @@ function MyComponent() {
 		`),
 		el("div", { className: "illustration" }).append(
 			el("h4", t`Lifecycle Flow`),
-			el("pre").append(el("code", `
+			el(pre, { content: `
 				1. Component created → scope established
-2. Component add<el> to DOM → connected event
+				2. Component added to DOM → connected event
 				3. Component interactions happen
 				4. Component removed from DOM → disconnected event
 				5. Automatic cleanup of:
-  - Event listeners
+					- Event listeners (browser)
-  - Signal subscriptions
+					- Signal subscriptions (dd<el> and browser)
-  - Custom cleanup code
+					- Custom cleanup code (dd<el> and user)
-			`))
+			` })
 		),
 		el(example, { src: fileURL("./components/examples/scopes/cleaning.js"), page_id }),
 
 		el("div", { className: "note" }).append(
 			el("p").append(...T`
 				In this example, when you click "Remove", the component is removed from the DOM, and all its associated
-				resources are automatically cleaned up, including the signal subscription that updates the text content.
+				resources are automatically cleaned up, including ${el("em",
-				This happens because the library internally registers a disconnected event handler on the host element.
+					"the signal subscription that updates the text content")}. This happens because the library
+				internally registers a disconnected event handler on the host element.
 			`)
 		),
 
 		el(h3, t`Declarative vs Imperative Components`),
 		el("p").append(...T`
-			The library DOM API and signals work best when used declaratively. It means you split your app's logic
+			The library DOM API and signals work best when used declaratively. It means you split your app’s logic
-			into three parts as introduced in ${el("a", { textContent: "Signals", ...references.signals })}.
+			into three parts as introduced in ${el("a", { textContent: "Signals (3PS)", ...references.signals })}.
 		`),
 		el("div", { className: "note" }).append(
 			el("p").append(...T`
@@ -145,17 +146,17 @@ function MyComponent() {
 			`)
 		),
 		el("div", { className: "tabs" }).append(
-			el("div", { className: "tab", "data-tab": "declarative" }).append(
+			el("div", { className: "tab", dataTab: "declarative" }).append(
 				el("h4", t`✅ Declarative Approach`),
 				el("p", t`Define what your UI should look like based on state:`),
 				el(code, { src: fileURL("./components/examples/scopes/declarative.js"), page_id })
 			),
-			el("div", { className: "tab", "data-tab": "imperative" }).append(
+			el("div", { className: "tab", dataTab: "imperative" }).append(
 				el("h4", t`⚠️ Imperative Approach`),
 				el("p", t`Manually update the DOM in response to events:`),
 				el(code, { src: fileURL("./components/examples/scopes/imperative.js"), page_id })
 			),
-			el("div", { className: "tab", "data-tab": "mixed" }).append(
+			el("div", { className: "tab", dataTab: "mixed" }).append(
 				el("h4", t`❌ Mixed Approach`),
 				el("p", t`This approach should be avoided:`),
 				el(code, { src: fileURL("./components/examples/scopes/mixed.js"), page_id })
@@ -171,7 +172,8 @@ function MyComponent() {
 				${el("strong", "Define signals as constants:")} ${el("code", "const counter = S(0);")}
 			`),
 			el("li").append(...T`
-				${el("strong", "Prefer declarative patterns:")} Use signals to drive UI updates rather than manual DOM manipulation
+				${el("strong", "Prefer declarative patterns:")} Use signals to drive UI updates rather than manual DOM
+				manipulation
 			`),
 			el("li").append(...T`
 				${el("strong", "Keep components focused:")} Each component should do one thing well
@@ -195,7 +197,7 @@ function MyComponent() {
 				el("dd", t`Use arrow functions or .bind() to preserve context`),
 
 				el("dt", t`Mixing declarative and imperative styles`),
-				el("dd", t`Choose one approach and be consistent throughout a component`)
+				el("dd", t`Choose one approach and be consistent throughout a component(s)`)
 			)
 		),
 

docs/p06-customElement.html.js

@@ -10,7 +10,7 @@ import { simplePage } from "./layout/simplePage.html.js";
 import { example } from "./components/example.html.js";
 import { h3 } from "./components/pageUtils.html.js";
 import { mnemonic } from "./components/mnemonic/customElement-init.js";
-import { code } from "./components/code.html.js";
+import { code, pre } from "./components/code.html.js";
 /** @param {string} url */
 const fileURL= url=> new URL(url, import.meta.url);
 const references= {
@@ -49,6 +49,11 @@ const references= {
 		title: t`Everything you need to know about Shadow DOM (github repo praveenpuglia/shadow-dom-in-depth)`,
 		href: "https://github.com/praveenpuglia/shadow-dom-in-depth",
 	},
+	/** Decorators */
+	decorators: {
+		title: t`JavaScript Decorators: An In-depth Guide`,
+		href: "https://www.sitepoint.com/javascript-decorators-what-they-are/",
+	}
 };
 /** @param {import("./types.d.ts").PageAttrs} attrs */
 export function page({ pkg, info }){
@@ -56,7 +61,7 @@ export function page({ pkg, info }){
 	return el(simplePage, { info, pkg }).append(
 		el("p").append(...T`
 			dd<el> pairs powerfully with ${el("a", references.mdn_web_components).append(el("strong", t`Web
-				Components`))} to create reusable, encapsulated custom elements with all the benefits of dd<el>'s
+				Components`))} to create reusable, encapsulated custom elements with all the benefits of dd<el>’s
 				declarative DOM construction and reactivity system.
 		`),
 		el("div", { className: "callout" }).append(
@@ -66,14 +71,13 @@ export function page({ pkg, info }){
 				el("li", t`Reactive attribute updates through signals`),
 				el("li", t`Simplified event handling with the same events API`),
 				el("li", t`Clean component lifecycle management`),
-				el("li", t`Improved code organization with scopes`)
+			),
-			)
 		),
 		el(code, { src: fileURL("./components/examples/customElement/intro.js"), page_id }),
 
 		el(h3, t`Getting Started: Web Components Basics`),
 		el("p").append(...T`
-			Web Components are a set of standard browser APIs that let you create custom HTML elements with
+			Web Components are a set of standard browser APIs that let you create custom HTML elements with
 			encapsulated functionality. They consist of three main technologies:
 		`),
 		el("ul").append(
@@ -81,14 +85,15 @@ export function page({ pkg, info }){
 				${el("strong", "Custom Elements:")} Create your own HTML tags with JS-defined behavior
 			`),
 			el("li").append(...T`
-				${el("strong", "Shadow DOM:")} Encapsulate styles and markup within a component
+				${el("strong", "Shadow DOM:")} Encapsulate styles and markup within a component
 			`),
 			el("li").append(...T`
-				${el("strong", "HTML Templates:")} Define reusable markup structures
+				${el("strong", "HTML Templates:")} Define reusable markup structures (${el("em",
+					"the dd<el> replaces this part")})
 			`)
 		),
 		el("p").append(...T`
-			Let's start with a basic Custom Element example without dd<el> to establish the foundation:
+			Let’s start with a basic Custom Element example without dd<el> to establish the foundation:
 		`),
 		el(code, { src: fileURL("./components/examples/customElement/native-basic.js"), page_id }),
 
@@ -103,15 +108,16 @@ export function page({ pkg, info }){
 
 		el(h3, t`dd<el> Integration: Step 1 - Event Handling`),
 		el("p").append(...T`
-			The first step in integrating dd<el> with Web Components is enabling dd<el>'s event system to work with your
+			The first step in integrating dd<el> with Web Components is enabling dd<el>’s event system to work with your
 			Custom Elements. This is done with ${el("code", "customElementWithDDE")}, which makes your Custom Element
-			compatible with dd<el>'s event handling.
+			compatible with dd<el>’s event handling. (${el("em").append(...T`Notice that customElementWithDDE is
+			actually`)} ${el("a", { textContent: "decorator", ...references.decorators })})
 		`),
 		el("div", { className: "function-table" }).append(
 			el("h4", t`customElementWithDDE`),
 			el("dl").append(
 				el("dt", t`Purpose`),
-				el("dd", t`Enables dd<el>'s event system to work with your Custom Element`),
+				el("dd", t`Enables dd<el>’s event system to work with your Custom Element`),
 				el("dt", t`Usage`),
 				el("dd", t`customElementWithDDE(YourElementClass)`),
 				el("dt", t`Benefits`),
@@ -123,25 +129,25 @@ export function page({ pkg, info }){
 		el("div", { className: "tip" }).append(
 			el("p").append(...T`
 				${el("strong", "Key Point:")} The ${el("code", "customElementWithDDE")} function adds event dispatching
-				to your Custom Element lifecycle methods, making them work seamlessly with dd<el>'s event system.
+				to your Custom Element lifecycle methods, making them work seamlessly with dd<el>’s event system.
 			`)
 		),
 
 		el(h3, t`dd<el> Integration: Step 2 - Rendering Components`),
 		el("p").append(...T`
-			The next step is to use dd<el>'s component rendering within your Custom Element. This is done with
+			The next step is to use dd<el>’s component rendering within your Custom Element. This is done with
 			${el("code", "customElementRender")}, which connects your dd<el> component function to the Custom Element.
 		`),
 		el("div", { className: "function-table" }).append(
 			el("h4", t`customElementRender`),
 			el("dl").append(
 				el("dt", t`Purpose`),
-				el("dd", t`Connects a dd<el> component function to a Custom Element`),
+				el("dd", t`Connects a dd<el> component function to a Custom Element`),
 				el("dt", t`Parameters`),
 				el("dd").append(
 					el("ol").append(
 						el("li", t`Target (usually this or this.shadowRoot)`),
-						el("li", t`Component function that returns a DOM tree`),
+						el("li", t`Component function that returns a DOM tree`),
 						el("li", t`Optional: Attributes transformer function (empty by default or
 							S.observedAttributes)`)
 					)
@@ -154,7 +160,7 @@ export function page({ pkg, info }){
 
 		el("div", { className: "note" }).append(
 			el("p").append(...T`
-				In this example, we're using Shadow DOM (${el("code", "this.attachShadow()")}) for encapsulation,
+				In this example, we’re using Shadow DOM (${el("code", "this.attachShadow()")}) for encapsulation,
 				but you can also render directly to the element with ${el("code", "customElementRender(this, ...)")}.
 			`)
 		),
@@ -162,7 +168,7 @@ export function page({ pkg, info }){
 		el(h3, t`Reactive Web Components with Signals`),
 		el("p").append(...T`
 			One of the most powerful features of integrating dd<el> with Web Components is connecting HTML attributes
-			to dd<el>'s reactive signals system. This creates truly reactive custom elements.
+			to dd<el>’s reactive signals system. This creates truly reactive custom elements.
 		`),
 		el("div", { className: "tip" }).append(
 			el("p").append(...T`
@@ -179,8 +185,8 @@ export function page({ pkg, info }){
 			)
 		),
 		el("p").append(...T`
-			Using the ${el("code", "S.observedAttributes")} creates a reactive connection between your element's attributes
+			Using the ${el("code", "S.observedAttributes")} creates a reactive connection between your element’s
-			and its internal rendering. When attributes change, your component automatically updates!
+			attributes and its internal rendering. When attributes change, your component automatically updates!
 		`),
 		el(example, { src: fileURL("./components/examples/customElement/observedAttributes.js"), page_id }),
 
@@ -188,31 +194,32 @@ export function page({ pkg, info }){
 			el("h4", t`How S.observedAttributes Works`),
 			el("ol").append(
 				el("li", t`Takes each attribute listed in static observedAttributes`),
-				el("li", t`Creates a dd<el> signal for each one`),
+				el("li", t`Creates a dd<el> signal for each one`),
 				el("li", t`Automatically updates these signals when attributes change`),
 				el("li", t`Passes the signals to your component function`),
+				el("li", t`In opposite, updates of signals trigger attribute changes`),
 				el("li", t`Your component reacts to changes through signal subscriptions`)
 			)
 		),
 
 		el(h3, t`Working with Shadow DOM`),
 		el("p").append(...T`
-			Shadow DOM provides encapsulation for your component's styles and markup. When using dd<el> with Shadow DOM,
+			Shadow DOM provides encapsulation for your component’s styles and markup. When using dd<el> with Shadow DOM,
 			you get the best of both worlds: encapsulation plus declarative DOM creation.
 		`),
 		el("div", { className: "illustration" }).append(
 			el("h4", t`Shadow DOM Encapsulation`),
-			el("pre").append(el("code", `
+			el(pre, { content: `
 				<my-custom-element>
-  ┌─────────────────────────┐
+					┌─────────────────────────┐
-    #shadow-root
+						#shadow-root
 
-      Created with dd<el>
+					Created with dd<el>
-    ┌──────────────────┐
+						┌──────────────────┐
-      <div>
+							<div>
-       <h2>Title</h2>
+								<h2>Title</h2>
-       <p>Content</p>
+								<p>Content</p>
-			`))
+			` })
 		),
 		el(example, { src: fileURL("./components/examples/customElement/shadowRoot.js"), page_id }),
 
@@ -234,7 +241,7 @@ export function page({ pkg, info }){
 				el("dt", t`Purpose`),
 				el("dd", t`Provides slot functionality when you cannot/do not want to use shadow DOM`),
 				el("dt", t`Parameters`),
-				el("dd", t`A mapping object of slot names to DOM elements`)
+				el("dd", t`A mapping object of slot names to DOM elements`)
 			)
 		),
 
@@ -266,7 +273,7 @@ export function page({ pkg, info }){
 				el("dt", t`Events not firing properly`),
 				el("dd", t`Make sure you called customElementWithDDE before defining the element`),
 				el("dt", t`Attributes not updating`),
-				el("dd", t`Check that you've properly listed them in static observedAttributes`),
+				el("dd", t`Check that you’ve properly listed them in static observedAttributes`),
 				el("dt", t`Component not rendering`),
 				el("dd", t`Verify customElementRender is called in connectedCallback, not constructor`)
 			)

docs/p07-debugging.html.js

@@ -19,7 +19,7 @@ export function page({ pkg, info }){
 	return el(simplePage, { info, pkg }).append(
 		el("p").append(...T`
 			Debugging is an essential part of application development. This guide provides techniques
-			and best practices for debugging applications built with dd<el>, with a focus on signals.
+			and best practices for debugging applications built with dd<el>, with a focus on signals.
 		`),
 
 		el(h3, t`Debugging signals`),
@@ -30,7 +30,7 @@ export function page({ pkg, info }){
 
 		el("h4", t`Inspecting signal values`),
 		el("p").append(...T`
-			The simplest way to debug a signal is to log its current value by calling the get method:
+			The simplest way to debug a signal is to log its current value by calling the get method:
 		`),
 		el(code, { content: `
 			const signal = S(0);
@@ -39,33 +39,31 @@ console.log('Current value:', signal.get());
 			console.log('Current value:', signal.valueOf());
 		`, page_id }),
 		el("p").append(...T`
-			You can also monitor signal changes by adding a listener:
+			You can also monitor signal changes by adding a listener:
 		`),
-		el(code, {
+		el(code, { content: `
-			content:
+			// Log every time the signal changes
-			"// Log every time the signal changes\nS.on(signal, value => console.log('Signal changed:', value));",
+			S.on(signal, value => console.log('Signal changed:', value));
-			page_id }),
+		`, page_id }),
 
 		el("h4", t`Debugging derived signals`),
 		el("p").append(...T`
-			With derived signals (created with ${el("code", "S(() => computation))")}), debugging is a bit more complex
+			With derived signals (created with ${el("code", "S(() => computation))")}), debugging is a bit more complex
-			because the value depends on other signals. To understand why a derived signal isn't updating correctly:
+			because the value depends on other signals. To understand why a derived signal isn’t updating correctly:
 		`),
 		el("ol").append(
 			el("li", t`Check that all dependency signals are updating correctly`),
-			el("li", t`Add logging inside the computation function to see when it runs`),
+			el("li", t`Add logging/debugger inside the computation function to see when it runs`),
 			el("li", t`Verify that the computation function actually accesses the signal values with .get()`)
 		),
 		el(example, { src: fileURL("./components/examples/debugging/consoleLog.js"), page_id }),
 
 		el(h3, t`Common signal debugging issues`),
 		el("h4", t`Signal updates not triggering UI changes`),
-		el("p").append(...T`
+		el("p", t`If signal updates aren’t reflected in the UI, check:`),
-			If signal updates aren't reflected in the UI, check:
-		`),
 		el("ul").append(
-			el("li", t`That you're using signal.set() to update the value, not modifying objects/arrays directly`),
+			el("li", t`That you’re using signal.set() to update the value, not modifying objects/arrays directly`),
-			el("li", t`For mutable objects, ensure you're using actions or making proper copies before updating`),
+			el("li", t`For mutable objects, ensure you’re using actions or making proper copies before updating`),
 			el("li", t`That the signal is actually connected to the DOM element (check your S.el or attribute binding code)`)
 		),
 		el(code, { src: fileURL("./components/examples/debugging/mutations.js"), page_id }),
@@ -77,12 +75,10 @@ console.log('Current value:', signal.valueOf());
 		`),
 
 		el("h4", t`Performance issues with frequently updating signals`),
-		el("p").append(...T`
+		el("p", t`If you notice performance issues with signals that update very frequently:`),
-			If you notice performance issues with signals that update very frequently:
-		`),
 		el("ul").append(
 			el("li", t`Consider debouncing or throttling signal updates`),
-			el("li", t`Make sure derived signals don't perform expensive calculations unnecessarily`),
+			el("li", t`Make sure derived signals don’t perform expensive calculations unnecessarily`),
 			el("li", t`Keep signal computations focused and minimal`)
 		),
 		el(code, { src: fileURL("./components/examples/debugging/debouncing.js"), page_id }),
@@ -96,13 +92,13 @@ console.log('Current value:', signal.valueOf());
 		el("p").append(...T`
 			dd<el> marks components in the DOM with special comment nodes to help you identify component boundaries.
 			Components created with ${el("code", "el(ComponentFunction)")} are marked with comment nodes
-			${el("code", "<!--<dde:mark type=\"component\" name=\"MyComponent\" host=\"parentElement\"/>-->")} and
+			${el("code", `<!--<dde:mark type="component" name="MyComponent" host="parentElement"/>-->`)} and
 			includes:
 		`),
 		el("ul").append(
-			el("li", "type - Identifies the type of marker (\"component\", \"reactive\", or \"later\")"),
+			el("li", t`type - Identifies the type of marker ("component", "reactive", or "later")`),
-			el("li", "name - The name of the component function"),
+			el("li", t`name - The name of the component function`),
-			el("li", "host - Indicates whether the host is \"this\" (for DocumentFragments) or \"parentElement\""),
+			el("li", t`host - Indicates whether the host is "this" (for DocumentFragments) or "parentElement"`),
 		),
 
 		el("h4", t`Finding reactive elements in the DOM`),
@@ -113,7 +109,7 @@ console.log('Current value:', signal.valueOf());
 		`),
 		el(code, { src: fileURL("./components/examples/debugging/dom-reactive-mark.html"), page_id }),
 		el("p").append(...T`
-			This is particularly useful when debugging why a reactive section isn't updating as expected.
+			This is particularly useful when debugging why a reactive section isn’t updating as expected.
 			You can inspect the elements between the comment nodes to see their current state and the
 			signal connections through \`__dde_reactive\` of the host element.
 		`),
@@ -124,48 +120,49 @@ console.log('Current value:', signal.valueOf());
 		`),
 		el("p").append(...T`
 			${el("code", "<element>.__dde_reactive")} - An array property on DOM elements that tracks signal-to-element
-			relationships.  This allows you to quickly identify which elements are reactive and what signals they're
+			relationships.  This allows you to quickly identify which elements are reactive and what signals they’re
 			bound to. Each entry in the array contains:
 		`),
 		el("ul").append(
-			el("li", "A pair of signal and listener function: [signal, listener]"),
+			el("li", t`A pair of signal and listener function: [signal, listener]`),
-			el("li", "Additional context information about the element or attribute"),
+			el("li", t`Additional context information about the element or attribute`),
-			el("li", "Automatically managed by signal.el(), signal.observedAttributes(), and processReactiveAttribute()")
+			el("li", t`Automatically managed by signal.el(), signal.observedAttributes(), and processReactiveAttribute()`)
 		),
 		el("p").append(...T`
-			These properties make it easier to understand the reactive structure of your application when inspecting elements.
+			These properties make it easier to understand the reactive structure of your application when inspecting
+			elements.
 		`),
 		el(example, { src: fileURL("./components/examples/signals/debugging-dom.js"), page_id }),
 
 		el("h4", t`Examining signal connections`),
 		el("p").append(...T`
-			${el("code", "<signal>.__dde_signal")} - A Symbol property used to identify and store the internal state of
+			${el("code", "<signal>.__dde_signal")} - A Symbol property used to identify and store the internal state of
 			signal objects. It contains the following information:
 		`),
 		el("ul").append(
-			el("li", "listeners: A Set of functions called when the signal value changes"),
+			el("li", t`listeners: A Set of functions called when the signal value changes`),
-			el("li", "actions: Custom actions that can be performed on the signal"),
+			el("li", t`actions: Custom actions that can be performed on the signal`),
-			el("li", "onclear: Functions to run when the signal is cleared"),
+			el("li", t`onclear: Functions to run when the signal is cleared`),
-			el("li", "host: Reference to the host element/scope"),
+			el("li", t`host: Reference to the host element/scope`),
-			el("li", "defined: Stack trace information for debugging"),
+			el("li", t`defined: Stack trace information for debugging`),
-			el("li", "readonly: Boolean flag indicating if the signal is read-only")
+			el("li", t`readonly: Boolean flag indicating if the signal is read-only`)
 		),
 		el("p").append(...T`
 			…to determine the current value of the signal, call ${el("code", "signal.valueOf()")}.
 		`),
 		el("p").append(...T`
 			You can inspect (host) element relationships and bindings with signals in the DevTools console using
-			${el("code", "$0.__dde_reactive")} (for currently selected element). In the console you will see a list of
+			${el("code", "$0.__dde_reactive")} (for currently selected element). In the console you will see a list of
-			${el("code", "[ [ signal, listener ], element, property ]")}, where:
+			${el("code", `[ [ signal, listener ], element, property ]`)}, where:
 		`),
 		el("ul").append(
-			el("li", "signal — the signal triggering the changes"),
+			el("li", t`signal — the signal triggering the changes`),
-			el("li", "listener — the listener function (this is an internal function for dd<el>)"),
+			el("li", t`listener — the listener function (this is an internal function for dd<el>)`),
-			el("li", "element — the DOM element that is bound to the signal"),
+			el("li", t`element — the DOM element that is bound to the signal`),
-			el("li", "property — the attribute or property name which is changing based on the signal"),
+			el("li", t`property — the attribute or property name which is changing based on the signal`),
 		),
 		el("p").append(...T`
-			…the structure of \`__dde_reactive\` utilizes the browser's behavior of packing the first field,
+			…the structure of \`__dde_reactive\` utilizes the browser’s behavior of packing the first field,
 			so you can see the element and property that changes in the console right away.
 		`),
 

docs/p08-extensions.html.js

@@ -25,8 +25,8 @@ export function page({ pkg, info }){
 		el(h3, t`DOM Element Extensions with Addons`),
 		el("p").append(...T`
 			The primary method for extending DOM elements in dd<el> is through the Addon pattern.
-			Addons are functions that take an element and applying some functionality to it. This pattern enables a
+			Addons are functions that take an element and applying some functionality to it. This pattern enables
-			clean, functional approach to element enhancement.
+			a clean, functional approach to element enhancement.
 		`),
 		el("div", { className: "callout" }).append(
 			el("h4", t`What are Addons?`),
@@ -34,12 +34,12 @@ export function page({ pkg, info }){
 				Addons are simply functions with the signature: (element) => void. They:
 			`),
 			el("ul").append(
-				el("li", t`Accept a DOM element as input`),
+				el("li", t`Accept a DOM element as input`),
 				el("li", t`Apply some behavior, property, or attribute to the element`),
 			)
 		),
 		el(code, { content: `
-// Basic structure of an addon
+			// Basic structure of an addon
 			function myAddon(config) {
 				return function(element) {
 					// Apply functionality to element
@@ -47,20 +47,20 @@ function myAddon(config) {
 				};
 			}
 
-// Using an addon
+			// Using an addon
 			el("div", { id: "example" }, myAddon({ option: "value" }));
-		`.trim(), page_id }),
+		`, page_id }),
 
 		el(h3, t`Resource Cleanup with Abort Signals`),
 		el("p").append(...T`
 			When extending elements with functionality that uses resources like event listeners, timers,
-			or external subscriptions, it's critical to clean up these resources when the element is removed
+			or external subscriptions, it’s critical to clean up these resources when the element is removed
 			from the DOM. dd<el> provides utilities for this through AbortSignal integration.
 		`),
 		el("div", { className: "tip" }).append(
 			el("p").append(...T`
-				The ${el("code", "scope.signal")} property creates an AbortSignal that automatically
+				The ${el("code", "scope.signal")} property creates an AbortSignal that automatically
-				triggers when an element is disconnected from the DOM, making cleanup much easier to manage.
+				triggers when an element is disconnected from the DOM, making cleanup much easier to manage.
 			`)
 		),
 		el(code, { content: `
@@ -83,11 +83,11 @@ function Component(){
 				const { signal }= scope;
 				return el("div", null, externalLibraryAddon({ option: "value" }, signal));
 			}
-		`.trim(), page_id }),
+		`, page_id }),
 
 		el(h3, t`Building Library-Independent Extensions`),
 		el("p").append(...T`
-			When creating extensions, it's a good practice to make them as library-independent as possible.
+			When creating extensions, it’s a good practice to make them as library-independent as possible.
 			This approach enables better interoperability and future-proofing.
 		`),
 		el("div", { className: "illustration" }).append(
@@ -105,7 +105,7 @@ function enhancementElement({ signal, ...config }) {
 								});
 							};
 						}
-`.trim(), page_id })
+					`, page_id })
 				),
 				el("div", { className: "tab" }).append(
 					el("h5", t`⚠️ Library-Dependent`),
@@ -119,14 +119,14 @@ function enhancementElement(config) {
 								})(element);
 							};
 						}
-					`.trim(), page_id })
+					`, page_id })
 				)
 			)
 		),
 
 		el(h3, t`Signal Extensions and Future Compatibility`),
 		el("p").append(...T`
-			Unlike DOM elements, signal functionality in dd<el> currently lacks a standardized
+			Unlike DOM elements, signal functionality in dd<el> currently lacks a standardized
 			way to create library-independent extensions. This is because signals are implemented
 			differently across libraries.
 		`),
@@ -152,21 +152,18 @@ function createEnhancedSignal(initialValue) {
 				const decrement = () => signal.set(signal.get() - 1);
 
 				// Return the original signal with added methods
-	return Object.assign(signal, {
+				return { signal, increment, decrement };
-		increment,
-		decrement
-	});
 			}
 
 			// Usage
 			const counter = createEnhancedSignal(0);
-el("button")({ onclick: () => counter.increment() }, "Increment");
+			el("button", { textContent: "Increment", onclick: () => counter.increment() });
 			el("div", S.text\`Count: \${counter}\`);
-		`.trim(), page_id }),
+		`, page_id }),
 
 		el(h3, t`Using Signals Independently`),
 		el("p").append(...T`
-			While signals are tightly integrated with DDE's DOM elements, you can also use them independently.
+			While signals are tightly integrated with DDE’s DOM elements, you can also use them independently.
 			This can be useful when you need reactivity in non-UI code or want to integrate with other libraries.
 		`),
 		el("p").append(...T`
@@ -174,37 +171,39 @@ el("div", S.text\`Count: \${counter}\`);
 		`),
 		el("ol").append(
 			el("li").append(...T`
-				${el("strong", "Standard import")}: ${el("code", "import { S } from \"deka-dom-el/signals\";")}
+				${el("strong", "Standard import")}: ${el("code", `import { S } from "deka-dom-el/signals";`)}
-				— This automatically registers signals with DDE's DOM reactivity system
+				— This automatically registers signals with DDE’s DOM reactivity system
 			`),
 			el("li").append(...T`
-				${el("strong", "Independent import")}: ${el("code", "import { S } from \"deka-dom-el/src/signals-lib\";")}
+				${el("strong", "Independent import")}: ${el("code", `import { S } from "deka-dom-el/src/signals-lib";`)}
 				— This gives you just the signal system without DOM integration
 			`)
 		),
-		el(code, { content: `// Independent signals without DOM integration
+		el(code, { content: `
-import { signal as S, isSignal } from "deka-dom-el/src/signals-lib";
+			// Independent signals without DOM integration
+			import { signal, isSignal } from "deka-dom-el/src/signals-lib";
 
 			// Create and use signals as usual
-const count = S(0);
+			const count = signal(0);
-const doubled = S(() => count.get() * 2);
+			const doubled = signal(() => count.get() * 2);
 
 			// Subscribe to changes
-S.on(count, value => console.log(value));
+			signal.on(count, value => console.log(value));
 
 			// Update signal value
 			count.set(5); // Logs: 5
-console.log(doubled.get()); // 10`, page_id }),
+			console.log(doubled.get()); // 10
+		`, page_id }),
 		el("p").append(...T`
 			The independent signals API includes all core functionality (${el("code", "S()")}, ${el("code", "S.on()")},
 			${el("code", "S.action()")}).
 		`),
-		el("div", { class: "callout" }).append(
+		el("div", { className: "callout" }).append(
 			el("h4", t`When to Use Independent Signals`),
 			el("ul").append(
 				el("li", t`For non-UI state management in your application`),
 				el("li", t`When integrating with other libraries or frameworks`),
-				el("li", t`To minimize bundle size when you don't need DOM integration`)
+				el("li", t`To minimize bundle size when you don’t need DOM integration`)
 			)
 		),
 
@@ -247,7 +246,7 @@ console.log(doubled.get()); // 10`, page_id }),
 				el("dd", t`Prefer compositional approaches with addons over modifying element prototypes`),
 
 				el("dt", t`Complex initialization in addons`),
-				el("dd", t`Split complex logic into a separate initialization function that the addon can call`)
+				el("dd", t`Split complex logic into a separate initialization function that the addon can call`)
 			)
 		)
 	);

docs/p09-ssr.html.js

@@ -26,10 +26,10 @@ export function page({ pkg, info }){
 			`)
 		),
 		el("p").append(...T`
-			dd<el> isn't limited to browser environments. Thanks to its flexible architecture,
+			dd<el> isn’t limited to browser environments. Thanks to its flexible architecture,
 			it can be used for server-side rendering (SSR) to generate static HTML files.
 			This is achieved through integration with for example ${el("a", { href: "https://github.com/tmpvar/jsdom",
-			textContent: "jsdom" })}, a JavaScript implementation of web standards for Node.js.
+			textContent: "jsdom" })}, a JavaScript implementation of web standards for Node.js.
 		`),
 		el("p").append(...T`
 			Additionally, you might consider using these alternative solutions:
@@ -37,7 +37,7 @@ export function page({ pkg, info }){
 		el("ul").append(
 			el("li").append(...T`
 				${el("a", { href: "https://github.com/capricorn86/happy-dom", textContent: "happy-dom" })} - A JavaScript implementation
-				of a web browser without its graphical user interface that's faster than jsdom
+				of a web browser without its graphical user interface that’s faster than jsdom
 			`),
 			el("li").append(...T`
 				${el("a", { href: "https://github.com/WebReflection/linkedom", textContent: "linkedom" })} - A lightweight DOM implementation
@@ -61,40 +61,40 @@ export function page({ pkg, info }){
 		el(h3, t`How jsdom Integration Works`),
 		el("p").append(...T`
 			The jsdom export in dd<el> provides the necessary tools to use the library in Node.js
-			by integrating with jsdom. Here's what it does:
+			by integrating with jsdom. Here’s what it does:
 		`),
 		el("ol").append(
-			el("li", t`Creates a virtual DOM environment in Node.js using jsdom`),
+			el("li", t`Creates a virtual DOM environment in Node.js using jsdom`),
 			el("li", t`Registers DOM globals like HTMLElement, document, etc. for dd<el> to use`),
-			el("li", t`Sets an SSR flag in the environment to enable SSR-specific behaviors`),
+			el("li", t`Sets an SSR flag in the environment to enable SSR-specific behaviors`),
-			el("li", t`Provides a promise queue system for managing async operations during rendering`),
+			el("li", t`Provides a promise queue system for managing async operations during rendering`),
 			el("li", t`Handles DOM property/attribute mapping differences between browsers and jsdom`)
 		),
 		el(code, { src: fileURL("./components/examples/ssr/start.js"), page_id }),
 
 		el(h3, t`Basic SSR Example`),
 		el("p").append(...T`
-			Here's a simple example of how to use dd<el> for server-side rendering in a Node.js script:
+			Here’s a simple example of how to use dd<el> for server-side rendering in a Node.js script:
 		`),
 		el(code, { src: fileURL("./components/examples/ssr/basic-example.js"), page_id }),
 
-		el(h3, t`Building a Static Site Generator`),
+		el(h3, t`Building a Static Site Generator`),
 		el("p").append(...T`
-			You can build a complete static site generator with dd<el>. In fact, this documentation site
+			You can build a complete static site generator with dd<el>. In fact, this documentation site
-			is built using dd<el> for server-side rendering! Here's how the documentation build process works:
+			is built using dd<el> for server-side rendering! Here’s how the documentation build process works:
 		`),
 		el(code, { src: fileURL("./components/examples/ssr/static-site-generator.js"), page_id }),
 
 		el(h3, t`Working with Async Content in SSR`),
 		el("p").append(...T`
-			The jsdom export includes a queue system to handle asynchronous operations during rendering.
+			The jsdom export includes a queue system to handle asynchronous operations during rendering.
 			This is crucial for components that fetch data or perform other async tasks.
 		`),
 		el(code, { src: fileURL("./components/examples/ssr/async-data.js"), page_id }),
 
 		el(h3, t`Working with Dynamic Imports for SSR`),
 		el("p").append(...T`
-			When structuring server-side rendering code, a crucial pattern to follow is using dynamic imports
+			When structuring server-side rendering code, a crucial pattern to follow is using dynamic imports
 			for both the deka-dom-el/jsdom module and your page components.
 		`),
 		el("p").append(...T`
@@ -107,7 +107,7 @@ export function page({ pkg, info }){
 			`),
 			el("li").append(...T`
 				${el("strong", "Environment registration timing:")} The jsdom module auto-registers the DOM environment
-				when imported, which must happen ${el("em", "after")} you've created your JSDOM instance and
+				when imported, which must happen ${el("em", "after")} you’ve created your JSDOM instance and
 				${el("em", "before")} you import your components using ${el("code", "import { el } from \"deka-dom-el\";")}.
 			`),
 			el("li").append(...T`
@@ -126,9 +126,9 @@ export function page({ pkg, info }){
 		`),
 		el("ul").append(
 			el("li", t`Browser-specific APIs like window.localStorage are not available in jsdom by default`),
-			el("li", t`Event listeners added during SSR won't be functional in the final HTML unless hydrated on the client`),
+			el("li", t`Event listeners added during SSR won’t be functional in the final HTML unless hydrated on the client`),
 			el("li", t`Some DOM features may behave differently in jsdom compared to real browsers`),
-			el("li", t`For large sites, you may need to optimize memory usage by creating a new jsdom instance for each page`)
+			el("li", t`For large sites, you may need to optimize memory usage by creating a new jsdom instance for each page`)
 		),
 		el("p").append(...T`
 			For advanced SSR applications, consider implementing hydration on the client-side to restore
@@ -137,7 +137,7 @@ export function page({ pkg, info }){
 
 		el(h3, t`Real Example: How This Documentation is Built`),
 		el("p").append(...T`
-			This documentation site itself is built using dd<el>'s SSR capabilities.
+			This documentation site itself is built using dd<el>’s SSR capabilities.
 			The build process collects all page components, renders them with jsdom, and outputs static HTML files.
 		`),
 		el(code, { src: fileURL("./components/examples/ssr/static-site-generator.js"), page_id }),

docs/p10-ireland.html.js

@@ -30,14 +30,11 @@ export function page({ pkg, info }){
 
 		el(h3, t`What Are Ireland Components?`),
 		el("p").append(...T`
-			Ireland components are a special type of documentation component that:
+			Ireland components are a special type of component that:
 		`),
 		el("ul").append(
-			el("li", t`Display source code with syntax highlighting`),
+			el("li", t`Pre-render components on the server during SSR build`),
-			el("li", t`Pre-render components on the server during documentation build`),
+			el("li", t`Provide client-side rehydration for the component`),
-			el("li", t`Copy component source files to the documentation output`),
-			el("li", t`Provide client-side rehydration for interactive demos`),
-			el("li", t`Allow users to run and experiment with components in real-time`)
 		),
 
 		el(h3, t`How Ireland Components Work`),
@@ -55,9 +52,6 @@ export function page({ pkg, info }){
 			el("li").append(...T`
 				${el("strong", "Client-side scripting:")} JavaScript code is generated to load and render components
 			`),
-			el("li").append(...T`
-				${el("strong", "User interaction:")} The "Run Component" button dynamically loads and renders the component
-			`)
 		),
 
 		el(h3, t`Implementation Architecture`),
@@ -68,11 +62,12 @@ export function page({ pkg, info }){
 		`),
 
 		el(code, { content: `
-// Basic usage of an ireland component
+			// Basic usage of an ireland component
 			el(ireland, {
 				src: fileURL("./components/examples/path/to/component.js"),
 				exportName: "NamedExport", // optional, defaults to "default",
-})`, page_id }),
+			})
+		`, page_id }),
 
 		el("p").append(...T`
 			During the build process (${el("code", "bs/docs.js")}), the following happens:
@@ -82,7 +77,7 @@ el(ireland, {
 			el("li", t`Component source code is loaded and displayed with syntax highlighting`),
 			el("li", t`Source files are registered to be copied to the output directory`),
 			el("li", t`Client-side scripts are generated for each page with ireland components`),
-			el("li", t`The component is wrapped in a UI container with controls`)
+			el("li", t`The component is rerendered on the page ready`),
 		),
 
 		el(h3, t`Core Implementation Details`),
@@ -99,7 +94,7 @@ import { path_target, dispatchEvent } from "../docs/ssr.js";
 
 			// For each page, render it on the server
 			for(const { id, info } of pages) {
-	// Create a virtual DOM environment for server-side rendering
+				// Create a virtual DOM environment for server-side rendering
 				const serverDOM = createHTMl("");
 				serverDOM.registerGlobally("HTMLScriptElement");
 
@@ -129,7 +124,7 @@ dispatchEvent("onssrend");
 		el(code, { content: `
 			// From docs/ssr.js - File registration system
 			export function registerClientFile(url, { head, folder = "", replacer } = {}) {
-	// Ensure folder path ends with a slash
+				// Ensure folder path ends with a slash
 				if(folder && !folder.endsWith("/")) folder += "/";
 
 				// Extract filename from URL
@@ -145,7 +140,7 @@ export function registerClientFile(url, { head, folder = "", replacer } = {}) {
 				// Write content to the output directory
 				content.to(path_target.root+folder+file_name);
 
-	// If a head element was provided, add it to the document
+				// If a head element was provided, add it to the document
 				if(!head) return;
 				head[head instanceof HTMLScriptElement ? "src" : "href"] = file_name;
 				document.head.append(head);
@@ -242,7 +237,7 @@ export function loadIrelands(store) {
 				document.body.querySelectorAll("[data-dde-mark]").forEach(ireland => {
 				const { ddeMark } = ireland.dataset;
 
-	// Skip if this component isn't in our registry
+				// Skip if this component isn’t in our registry
 				if(!store.has(ddeMark)) return;
 
 				// Get component information
@@ -259,7 +254,7 @@ export function loadIrelands(store) {
 
 		el(h3, t`Live Example`),
 			el("p").append(...T`
-				Here's a live example of an Ireland component showing a standard counter.
+				Here’s a live example of an Ireland component showing a standard counter.
 				The component is defined in ${el("code", "docs/components/examples/ireland-test/counter.js")} and
 				rendered with the Ireland component system:
 			`),
@@ -275,34 +270,11 @@ export function loadIrelands(store) {
 			}),
 
 			el("p").append(...T`
-				When the "Run Component" button is clicked, the component is loaded and rendered dynamically.
+				When the page is loaded, the component is also loaded and rendered. The counter state is maintained
-				The counter state is maintained using signals, allowing for reactive updates as you click
+				using signals, allowing for reactive updates as you click the buttons to increment and decrement the
-				the buttons to increment and decrement the value.
+				value.
 			`),
 
-		el(h3, t`Creating Your Own Components`),
-		el("p").append(...T`
-			To create components for use with the Ireland system, follow these guidelines:
-		`),
-
-		el("ol").append(
-			el("li").append(...T`
-				${el("strong", "Export a function:")} Components should be exported as named or default functions
-			`),
-			el("li").append(...T`
-
-			`),
-			el("li").append(...T`
-				${el("strong", "Accept props:")} Components should accept a props object, even if not using it
-			`),
-			el("li").append(...T`
-				${el("strong", "Manage reactivity:")} Use signals for state management where appropriate
-			`),
-			el("li").append(...T`
-				${el("strong", "Handle cleanup:")} Include any necessary cleanup for event listeners or signals
-			`)
-		),
-
 		el(h3, t`Practical Considerations and Limitations`),
 			el("p").append(...T`
 				When implementing Ireland components in real documentation, there are several important
@@ -312,9 +284,9 @@ export function loadIrelands(store) {
 			el("div", { className: "warning" }).append(
 				el("h4", t`Module Resolution and Bundling`),
 				el("p").append(...T`
-					The examples shown here use bare module specifiers like ${el("code", "import { el } from \"deka-dom-el\"")}
+					The examples shown here use bare module specifiers like ${el("code",
-					which aren't supported in all browsers without importmaps. In a production implementation, you would need to:
+						`import { el } from "deka-dom-el"`)} which aren’t supported in all browsers without importmaps.
-				`),
+					In a production implementation, you would need to: `),
 				el("ol").append(
 					el("li", t`Replace bare import paths with actual paths during the build process`),
 					el("li", t`Bundle component dependencies to avoid multiple requests`),
@@ -322,7 +294,7 @@ export function loadIrelands(store) {
 				),
 				el("p").append(...T`
 					In this documentation, we replace the paths with ${el("code", "./esm-with-signals.js")} and provide
-					a bundled version of the library, but more complex components might require a dedicated bundling step.
+					a bundled version of the library, but more complex components might require a dedicated bundling step.
 				`)
 			),
 
@@ -333,7 +305,7 @@ export function loadIrelands(store) {
 					to be extended to:
 				`),
 				el("ul").append(
-					el("li", t`Detect and analyze all dependencies of a component`),
+					el("li", t`Detect and analyze all dependencies of a component`),
 					el("li", t`Bundle these dependencies together or ensure they're properly copied to the output directory`),
 					el("li", t`Handle non-JavaScript assets like CSS, images, or data files`)
 				)
@@ -345,7 +317,7 @@ export function loadIrelands(store) {
 			`),
 
 			el("ul").append(
-				el("li", t`Integrate with a bundler like esbuild, Rollup, or Webpack`),
+				el("li", t`Integrate with a bundler like esbuild, Rollup, or Webpack`),
 				el("li", t`Add props support for configuring components at runtime`),
 				el("li", t`Implement module caching to reduce network requests`),
 				el("li", t`Add code editing capabilities for interactive experimentation`),
@@ -357,7 +329,7 @@ export function loadIrelands(store) {
 				This documentation site itself is built using the techniques described here,
 				showcasing how dd<el> can be used to create both the documentation and
 				the interactive examples within it. The implementation here is simplified for clarity,
-				while a production-ready system would need to address the considerations above.
+				while a production-ready system would need to address the considerations above.
 			`)
 	);
 }