5 changed files with 147 additions and 267 deletions
--- a/doc/dom-proxy.md
+++ b/doc/dom-proxy.md
--- a/doc/observable.md
+++ b/doc/observable.md
--- a/doc/readme.md
+++ b/doc/readme.md
@ -1,93 +0,0 @@
 ## Skooma.js
 ### HTML Proxy
 The proxy object that does the actual HTML generation.
 ```js
 document.body.append(html.div(
   html.span("Hello, World!")
 ))
 ```
 ### Handle helper
 Wraps a funcion of the signature `event, ... -> value` so that
 `event.preventDefault` gets called before running the function.
 ```js
 button.addEventListener("click",
   handle(() => console.log("click"))
 )
 ```
 ### Fragment helper
 Wraps a list of elements in a new document fragment.
 ```js
 const spans = fragment(
   html.span("First span"),
   html.span("Second span")
 )
 document.body.append(spans.cloneNode())
 ```
 ### Text helper
 When called as a normal function, returns a new text node with the given
 content. Unlike `document.createTextNode`, it does not fail for non-string
 values.
 ```js
 const node = text("Hello, World!")
 ```
 When used as a tagged template, returns a document fragment containing text
 nodes and interpolated values. DOM nodes can be interpolated into the document
 fragment.
 ```js
 const description = text`Interpolate ${html.b("bold")} text`
 ```
 For consistency, even tagged templates with no interpolated variables will
 always return a document fragment.
 ## State.js
 ### AbortRegistry
 `FinalizationRegistry` that takes an `AbortController` and aborts it whenever
 the registered value gets collected.
 ### ChangeEvent
 The event class emitted when a change is detected on a skooma state.
 Provides the `final` getter.
 ### MapStorage
 A utility class that simulates the `Storage` API but is backed by a map. Can be
 used as fallback in environments where persistent storages aren't available.
 ### SimpleState
 Base state class that all other states inherit from, used primarily for class
 checking, as the `State` class introduces behaviours that may be undesireable
 when inheriting.
 ### State
 The main state class that does all the magic.
 ### ForwardState
 Proxy to a named property on another State to be used with APIs that only accept
 single-value states.
 ### StoredState
 State class that is backed by a Storage instead of an internal proxy.
 ## domLense.js
--- a/doc/render.md
+++ b/doc/render.md
@ -1,174 +0,0 @@
 # Rendering DOM nodes using `render.js`
 ```js
 import {html} from "skooma/render.js"
 ```
 A functional-friendly helper library for procedural DOM generation and templating, with support for reactive state objects.
 ## Summary
 ```js
 html.button(
 	"Clicki Me!",
 	{
 		class: "primary",
 		click({target}) {
 			console.log("User clicked", target)
 		}
 	},
 	button => { console.log("Created", button) }
 )
 ```
 * elements as functions `content -> element`
 * content as arguments or in arrays
 * attributes in object arguments
 * style, dataset, shadow root, etc. as magic attributes
 * events as function attributes
 * initialisers as `void -> void` functions
 ## Interface / Examples
 ### Basic DOM generation
 Accessing the `html` proxy with any string key returns a new node generator function.
 When called this function will generate a DOM node (HTML Tag).
 The name of the function becomes the tag name of the node.
 ```js
 html.div()
 ```
 Content and attributes can be set via the function arguments:
 Strings and DOM nodes are inserted as children, while other objects (except for some special cases) have their key-value pairs turned into attribute-value pairs on the 
 ```js
 html.div("Big Text", {style: "font-size: 1.4em"})
 ```
 Arrays are iterated and their values treated as arguments.
 This works both for inserting children and setting attributes.
 ```js
 const content = [" ps: hi", {class: "title"}]
 html.h1({id: "main-heading"}, "Heading", content)
 ```
 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(
    html.p(
        html.b("Bold Text")
    )
 )
 ```
 ### Attribute Processing
 For convenience, arrays assigned as attributes will be joined with spaces:
 ```js
 html.a({class: ["button", "important"]})
 ```
 Assigning a function as an attribute will instead attach it as an event listener:
 ```js
 html.button("Click me!", {click: event => {
    alert("You clicked the button.")
 }})
 ```
 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.
 ```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 supports reactivity through a simple protocol:
 Observable objects identify themselves with the `observable` attribute,
 which must return a truthy value.
 Observables are expected to expose a `value` attribute that is both readable and writeable,
 and to emit a "change" event whenever its vale has changed.
 Observables can be passed to skooma's node functions as both
 attribute values (values in an object) or
 child elements (direct arguments or in an array).
 #### Reactive Children
 Passing an observable as a child element will attempt to insert its current
 value into the new node as if it was passed in directly, but will also hook into
 the observable to replace the value when the state changes.
 ```js
 const state = new Observable.value(0)
 const button = html.button(state, {
 	click(event) { state.value++ }
 })
 ```
 Note that to keep the replacement logic simple, it is not currently possible to
 insert use document fragments, as these could insert several top-level children
 into a component that would then all have to be replaced. When an observable
 contains or changes to a document fragment, skooma will raise an error.
 Before replacing an element, a `"replace"` event is emitted from the old
 element. This event bubbles and is cancelable, and can thus be used both to
 completely prevent the replacement according to custom logic, to alter or
 initialise the new element before it is inserted, or even to modify the old
 object instead of replacing it.
 #### Reactive Attributes
 Passing an observable as an object value will, likewise, treat its value as the
 attribute value, and update it whenever the state's value changes.
 ```js
 const state = new Observable.value(0)
 const input_1 = html.input({ type: "number", value: state })
 const input_2 = html.input({ type: "number", value: state })
 ```
 TODO: events as for reactive children
--- a/readme.md
+++ b/readme.md
@ -1 +1,148 @@
 # Skooma
 A functional-friendly helper library for procedural DOM generation and
 templating.
 ```js
 import {html} from "skooma.js"
 ```
 ## Overview
 ```js
 const text = new State({value: "Skooma is cool"})
 setTimeout(() => {text.value = "Skooma is awesome!"}, 1e5)
 document.body.append(html.div(
    html.h1("Hello, World!"),
    html.p(text, {class: "amazing"}),
    html.button("Show Proof", {click: event => { alert("It's true!") }})
 ))
 ```
 ## Interface / Examples
 ### Basic DOM generation
 Accessing the `html` proxy with any string key returns a new node generator
 function:
 ```js
 html.div("Hello, World!")
 ```
 Attributes can be set by passing objects to the generator:
 ```js
 html.div("Big Text", {style: "font-size: 1.4em"})
 ```
 Complex structures can easily achieved by nesting generator functions:
 ```js
 html.div(
    html.p(
        html.b("Bold Text")
    )
 )
 ```
 For convenience, arrays assigned as attributes will be joined with spaces:
 ```js
 html.a({class: ["button", "important"]})
 ```
 Assigning a function as an attribute will instead attach it as an event
 listener:
 ```js
 html.button("Click me!", {click: event => {
    alert("You clicked the button.")
 }})
 ```
 <!-- TODO: Document special keys -->
 Generators can be called with many arguments. Arrays get iterated recursively as
 if they were part of a flat argument list.
 ### Generating Text Nodes
 ```js
 text("Hello, World")
 // Wraps document.createTextNode
 text()
 // Defaults to empty string instead of erroring
 text(null)
 // Non-string arguments still error
 text`Hello, World!`
 // returns a new document fragment containing the text node "Hello, World!"
 text`Hello, ${user}!`
 // returns a document fragment containing 3 nodes:
 // "Hello, ", the interpolated value of `user` and "!"
 text`Hello, ${html.b(user)}!`
 // Text node for Hello, the <b> tag with the user's name, and a text node for !
 ```
 ## handle
 ```js
 import {handle} from 'skooma.js'
 ```
 Since it is common for event handlers to call `preventDefault()`, skooma
 provides a helper function called `handle` with the following definition:
 ```js
 fn => event => { event.preventDefault(); return fn(event) }
 ```
 ## A few more examples:
 Create a Button that deletes itself:
 ```js
 document.body.append(
 	html.button("Delete Me", {click: event => event.target.remove()})
 )
 ```
 Turn a two-dimensional array into an HTML table:
 ```js
 const table = rows =>
 	html.table(html.tbody(rows.map(
 		row => html.tr(row.map(
 			cell => html.rd(cell, {dataset: {
 				content: cell.toLowerCase(),
 			}})
 		))
 	)))
 ```
 A list that you can add items to
 ```js
 let list, input = ""
 document.body.append(html.div([
 	list=html.ul(),
 	html.input({type: 'text', input: e => input = e.target.value}),
 	html.button({click: event => list.append(html.li(input))}, "Add"),
 ]))
 ```
 A list that you can also delete items from
 ```js
 const listItem = content => html.li(
 	html.span(content), " ", html.a("[remove]", {
 		click: event => event.target.closest("li").remove(),
 		style: { cursor: 'pointer', color: 'red' },
 	})
 )
 let list, input = ""
 document.body.append(html.div([
 	list=html.ul(),
 	html.input({type: 'text', input: e => input = e.target.value}),
 	html.button({click: event => list.append(listItem(input))}, "Add"),
 ]))
 ```