From b21f4f0aecaffb8b0afb4e28038a3afb0b5e1450 Mon Sep 17 00:00:00 2001
From: DarkWiiPlayer <darkwiiplayer@hotmail.com>
Date: Mon, 22 Jan 2024 11:21:44 +0100
Subject: [PATCH] [WIP] finish documenting HTML proxy

---
 doc/html-proxy.md | 48 ++++++++++++++++++++++++++++++++++++++++++++---
 1 file changed, 45 insertions(+), 3 deletions(-)

diff --git a/doc/html-proxy.md b/doc/html-proxy.md
index 16cbd8c..4a17ef4 100644
--- a/doc/html-proxy.md
+++ b/doc/html-proxy.md
@@ -42,7 +42,17 @@ const content = [" ps: hi", {class: "title"}]
 html.h1({id: "main-heading"}, "Heading", content)
 ```
 
-Nested tags can be generated with nested function calls:
+Function arguments are treated differently depending on their length: Functions with **no** named parameters are called, and their return value is then evaluated just like an argument to the generator.
+
+All other functions are (immediately) called with the newly created node as their first and only argument. These can be used to initialise the new node in a point-free style.
+
+```js
+const hello = () => html.bold("Hello, World!")
+const init = node => console.log("Initialising", node)
+html.div(hello, init)
+```
+
+Nested tags can be generated with nested function calls. When properly formatted, this means simpler templates will have the same structure as if written in HTML (sans those pesky closing tags).
 
 ```js
 html.div(
@@ -52,6 +62,8 @@ html.div(
 )
 ```
 
+### Attribute Processing
+
 For convenience, arrays assigned as attributes will be joined with spaces:
 
 ```js
@@ -66,7 +78,37 @@ html.button("Click me!", {click: event => {
 }})
 ```
 
-<!-- TODO: Document special keys -->
+The special `style` property can be set to an object and its key/value pairs will be inserted as CSS properties on the element's `style` object.
 
-Generators can be called with many arguments. Arrays get iterated recursively as if they were part of a flat argument list.
+```js
+const style = { color: "salmon" }
+html.span("Salmon", { style })
+```
+
+The special property `shadowRoot` will attach a shadow-DOM to the element if none is present and append its content to the shadow root. Arrays are iterated over and their elements appended individually.
+
+```js
+html.div({
+   shadowRoot = ["Hello, ", html.b("World"), "!"]
+})
+```
+
+The `dataset` property will add its key/value pairs to the new node's `dataset`, as a more convenient alternative to setting individual `data-` attributes.
+
+```js
+const dataset = { foo: "bar" }
+const div = html.div({dataset})
+console.log(dataset.foo === div.dataset.foo)
+console.log(div.getAttribute("data-foo") === "bar")
+```
+
+### Reactivity
+
+Skooma generator functions have a simple concept of reactive state: Any value that
+
+1. Is not an `HTMLElement`
+2. Is an `EventTarget`
+3. Has a `value` attribute
+
+When such a value is found where an attribute value or a child element would be expected, then its `value` is used instead, and a "change" event listener is added to the reactive state that either updates the property or replaces the child element respectively.