Add further documentation for skooma.js

page/codeblock.js

@@ -13,7 +13,7 @@ class CodeBlock extends HTMLElement {
 		let content = this.innerHTML.replace(/^\s*\n/, "").replace(/\n\s*$/, "")
 		let prefix = new RegExp(`${content.match(/^\t*/)}`, "g")
 		content = content.replace(prefix, "").replace(/&.*;/g, str => escapes[str] ?? str)
-		this.replaceChildren(html.pre(html.code(template(hljs.highlightAuto(content).value))))
+		this.replaceChildren(html.pre(html.code(template(hljs.highlight(content, {language: 'javascript'}).value))))
 	}
 }
 

page/skooma.html

@@ -94,7 +94,7 @@
 			return button
 		</code-block>
 
-		<p>Adding a <strong>shadow-root</strong> to the new element can be done witht he <code>shadowRoot</code> property.</p>
+		<p>Adding a <strong>shadow-root</strong> to the new element can be done with the magic <code>shadowRoot</code> property.</p>
 		<p></p>
 		<code-block>
 			return html.div({
@@ -109,5 +109,144 @@
 			div.innerText = "Light-DOM text content"
 			return div
 		</code-block>
+
+		<p>Object can be <strong>styled</strong> inline via the magic <code>style</code> property.</p>
+		<p>Meanwhile in Vanilla JS styling properties have to be added one by one</p>
+		<code-block>
+			return html.div("Hello, World!" {
+				class: 'button', style: {
+					color, // some constant
+					border: '1px solid currentcolor
+				}
+			})
+		</code-block>
+		<code-block>
+			let div = document.createElement("div")
+			div.innerHTML = "Hello, World!"
+			div.style.color: color // some constant
+			div.style.border: '1px solid currentcolor'
+			return div
+		</code-block>
+
+		<p>Custom elements with hyphenated names can be created easily</p>
+		<p></p>
+		<code-block>
+			return html.myComponent()
+		</code-block>
+		<code-block>
+			return document.createElement("my-component")
+		</code-block>
 	</div>
 </section>
+
+<section>
+	<h2>The <code>text</code> helper</h2>
+	<div class="columns">
+		<p>The <code>text</code> helper provides a convenient wrapper around the
+		<code>document.createTextNode</code> function</p>
+		<p>In its simplest form, it's only a shorthand for its vanilla counterpart</p>
+		<code-block>
+			return text("Hello, World!")
+		</code-block>
+		<code-block>
+			return document.createTextNode("Hello, World!")
+		</code-block>
+
+		<p>However, you don't need to pass an argument to it.</p>
+		<p></p>
+		<code-block>
+			return text()
+		</code-block>
+		<code-block>
+			return document.createTextNode("")
+		</code-block>
+
+		<p>It also acts as a tag function for template literals, returning a
+		document fragment containing a list of text nodes.</p>
+		<p></p>
+		<code-block>
+			return text`Hello, ${name}!`
+		</code-block>
+		<code-block>
+			let fragment = new DocumentFragment()
+			fragment.append("Hello, ")
+			fragment.append(name)
+			fragment.append("!")
+			return fragment
+		</code-block>
+
+		<p>You can even interpolate actual DOM nodes in the string</p>
+		<p></p>
+		<code-block>
+			return text`Hello, ${html.b(name)}!`
+		</code-block>
+		<code-block>
+			let fragment = new DocumentFragment()
+			fragment.append("Hello, ")
+			let bold = document.createElement("b")
+			bold.innerHTML = name
+			fragment.append(bold)
+			fragment.append("!")
+			return fragment
+		</code-block>
+	</div>
+</section>
+
+<section>
+	<h2>The <code>bind</code> helper</h2>
+
+	<p>
+		<dl>
+			<dt>Callback registration function</dt>
+			<dd>
+				A function that takes a callback as its single argument and returns
+				an initial state as an array of elements. The inital state will be
+				used to generate the bound element for the first time. The callback
+				function should be called whenever an update in the UI is desired
+				and the new state should be passed as its argument.
+			</dd>
+			<dt>Transform function</dt>
+			<dd>
+				A function that takes the initial or updated state and returns a new
+				HTML element.
+				<details><summary>Planned feature</summary>
+					When no HTML element is returned, nothing happens. This can be
+					used to update the existing element instead; however, the
+					function currently provides no means to access the old element in
+					the transform function.
+				</details>
+			</dd>
+		</dl>
+	</p>
+
+	<p>
+		Imagine <code>counter</code> to be an object with a <code>count</code>
+		attribute representing the current count and <code>onIncrement</code> to
+		be a function to register a callback to be called whenever the counter
+		gets updated.
+	</p>
+	<div class="columns">
+		<h3>Creating a new Element</h3>
+		<h3>Updating the old Element</h3>
+		<code-block>
+			let counterMessage = count =&gt;
+				text`Current count: ${html.b(count)}`
+			// onIncrement doesn't return an initial
+			// state, so we have to wrap it:
+			let onIncrement = bind(callback =&gt;
+				counter.onIncrement(callback) || counter.count)
+
+			return boundElement = onIncrement(counterMessage)
+		</code-block>
+		<code-block>
+			// Not yet implemented
+		</code-block>
+	</div>
+
+	<p>
+		When an element gets replaced with a newer version of itself, any variable
+		containing the old element will become "stale". For this reason, the
+		function injects a <code>current</code> property into every element it
+		creates that will always point to the newest version of the element.
+	</p>
+</section>