More detail

model.md

@@ -32,8 +32,8 @@ A statum snapshot captures an aspect of the application state at a particular po
 ## Statum Action
 
 - `uri`: The URI to request.
-- `method`: the HTTP verb to use.
-- `private`: a base64 encoded string of data only readable by the application server (can be `undefined`)
+- `method`: The HTTP verb to use.
+- `private`: A base64 encoded string of data only readable by the application server (can be `undefined`)
 
 ## Statum Directive
 
@@ -89,3 +89,85 @@ There are two variations of this header:
 
 Before an HTTP request is sent, if one or more slot snapshots's `transmit_after` timestamp is in the past, and it is not equal to its `as_at` timestamp, a pre-flight request should be made to the slot post endpoint, which will in turn provide updated snapshots and a new `as_at` timestamp.
 
+# Javascript API
+
+The Javascript API provides access to the state and actions via the global `statum` object. It automatically handles pre-flight requests, headers, and executing directives from the server.
+
+## Managing State
+
+State snapshots can be cleaned up via `statum.clear("typeName")`. All snapshots can be cleared via `statum.clear()`.
+
+## Reading State
+
+State can be read via `statum.read("typeName")` which returns the snapshot object currently associated with the type "typeName".
+
+To get the current frame of a type, use `statum.getFrame("typeName")` which will return the frame object that encapsulates the snapshot.
+
+A full state object can be generated via `statum.state()` which returns a javascript object containing properties named after each type name that currently has a state, thier values being the current snapshot object, e.g. `{ "typeName":  {"as_at": "...`.
+
+## Performing an Action
+
+To perform an action, use `statum.act(action)` where `action` is a Statum action. Use `statum.act(action, data)` to send parameters along with the request. This is encoded as query params when `action.method` == `GET`, or encoded as form encoded otherwise. `statum.act` returns a promise which resolves when the request has completed and all directives have been run.
+
+The act function can also be used with a string referring to an action name
+
+## Reacting to State
+
+Callbacks can be attached to statum using `statum.addStateListener("typeName", callback)` which calls `callback` with an object containing:
+
+- `type`: the type name
+- `frame`: the frame (can be `null` if state has been cleared)
+- `snapshot`: the snapshot object (can be `null` if state has been cleared).
+
+It is fired whenever a state of the specified type is set or cleared.
+
+# HTML API
+
+The Javascript library also has some functionality inspired by HTMX using attributes prefixed with `stm-`. Ususally their values refer to something along the JSON object path of the current `statum.state()`.
+
+The following attributes are supported:
+
+## Text binding
+
+The attribute `stm-text` binds the element's `innerText` to the specified state value, e.g. `<span stm-text="typeName.label">`.
+
+## HTML binding
+
+The attribute `stm-html` binds the element's `innerHTML` to the specified state value.
+
+## Conditional display
+
+The attribute `stm-if` adds or removes the element from the DOM depending on the expression inside the statement, e.g. `<div stm-if="typeName.visable">` or `<div stm-if="typeName.level > 5">`
+
+The attribute `stm-else-if` can only exist as the next sibling of an element with either `stm-if` or `stm-else-if` and has the same type of value as `stm-if`.
+
+The attribute `stm-else` can exist only as the next sibling of an element with `stm-if` or `stm-else-if`.
+
+## Conditional classes
+
+The attribute `stm-class.x` where `x` is any class name can be used to toggle classes on or off with a predicate, e.g. `<div stm-class.alert="typeName.waterLevel > 50">`.
+
+## Actions
+
+The attribute `stm-action` binds the elements primary action (e.g. `onclick` for buttons, or `onsubmit` for forms), overriding their default behaviour to instead perform the statum action referenced (via state path). For example `<button stm-action="typeName.deleteItem">Delete</button>`.
+
+It can be used with `stm-data` to also provide additional data to the action, e.g. `<button stm-action="typeName.deleteItem" stm-data="{'confirm': true}">Delete</button>`.
+
+The attribute will also disable the element (and any children) while the action is being processed, and restore the original state once completed (or on error). In addition to this, the attribute `stm-busy-class` can be used to specify one or more css classes to apply during this time.
+
+When used on a form, any form inputs are sent in the JSON or query string of the action, bound by their `name`, as they would for a regular native form submission.
+
+## Loops
+
+the attribute `stm-for-x-in=` attribute (where `x` can be anything) repeats the *current* element multuple times for each item in the referenced array, and makes available the specified variable name in all `stm-` attributes in its children, and for all other `stm-` attributes on itself. For example:
+
+```html
+<div class="list">
+    <div class="item" stm-for-product-in="typeName.availableProducts" stm-class.featured="product.featured">
+        <h3 stm-text="product.name"></h3>
+        <p stm-text="product.description"></p>
+        <span stm-text="product.price"></span>
+        <button stm-action="product.addToCartAction">Add to cart</button>
+    </div>
+</div>
+```