Merge pull request #78 from picodom/ondestroy-docs

improve and add missing docs

README.md

@@ -10,6 +10,8 @@ Picodom is a 1 KB VDOM builder and patch function.
 ```js
 import { h, patch } from "picodom"
 
+/** @jsx h */
+
 let node
 
 function render(view, state) {
@@ -79,43 +81,87 @@ function AwesomeTitle(text) {
 }
 ```
 
-### Lifecycle
+To diff two virtual nodes and update the DOM, use the `patch` function:
+
+```js
+const element = patch(
+  parent,  // HTML container, e.g., document.body
+  oldNode, // the old VNode
+  newNode  // the new VNode
+)
+```
+
+The `patch` function returns the patched child element.
+
+## Supported Attributes
+
+This section describes the particular handling of certain HTML/SVG attributes, and certain special attributes reserved by Picodom.
+
+### Standard HTML and SVG Attributes
+
+All standard HTML and SVG attributes are supported, and the following standard attributes are handled specifically:
+
+#### `class`
+
+Both the `className`-property and `class`-attribute are supported.
+
+#### `style`
+
+This attribute expects a standard `object` rather than a `string` as in HTML.
+
+Individual style properties will be diffed and mapped against [`HTMLElement.style`](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/style) property members of the DOM element - you should therefore use the [Javascript](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Properties_Reference) `style` object property names, e.g. `backgroundColor` rather than `background-color`.
 
-#### oncreate
+### Life-Cycle Attributes
+
+Picodom supports element-level life-cycle events and keyed updates via the following reserved attributes:
+
+#### `key`
+
+The `key` attribute enables Picodom to identify and preserve DOM elements, even when the order of child elements changes during an update.
+
+The value must be a string (or number) and it must be unique among all the siblings of a given child element.
+
+For example, use keys to ensure that input elements don't get replaced (and lose their focus or selection state, etc.) during updates - or for table rows (or other repeated elements) to ensure that these get reused.
+
+#### `oncreate`
 
 Fired after the element is created and attached to the DOM.
 
 <pre>
 <a id="oncreate-api"></a>oncreate(<a href="https://developer.mozilla.org/en-US/docs/Web/API/Element">Element</a>)
 </pre>
 
-#### onupdate
+#### `onupdate`
 
 Fired after the element attributes are updated. This event will fire even if the attributes have not changed.
 
 <pre>
 <a id="onupdate-api"></a>onupdate(<a href="https://developer.mozilla.org/en-US/docs/Web/API/Element">Element</a>, oldProps: <a href="#attributes">Attributes</a>)
 </pre>
 
-#### onremove
+#### `onremove`
+
+Fired before the element is removed from the DOM.
 
-Fired before the element is removed from the DOM. Return a function that takes a `remove()` function and use it to remove the element asynchronously.
+Your event handler will receive a reference to the element that is about to be removed, and a `done` callback function, which must be called to complete the removal, upon which the `ondestroy` handler will be fired.
 
 <pre>
-<a id="onremove-api"></a>onremove(<a href="https://developer.mozilla.org/en-US/docs/Web/API/Element">Element</a>)
+<a id="onremove-api"></a>onremove(<a href="https://developer.mozilla.org/en-US/docs/Web/API/Element">Element</a>, done)
 </pre>
 
-### patch
+You can use this event to defer the physical removal of an element from the DOM, for purposes such as animation during removal.
 
-Use `patch` to diff two nodes and update the DOM. `patch` returns the patched child element.
+Note that the `onremove` event is only triggered for *direct* removals, e.g. for updates where the parent of the element still exists. For *indirect* removals (where the parent element was also removed) only the `ondestroy` event will fire.
 
-```js
-const element = patch(
-  parent,  // HTML container, e.g., document.body
-  oldNode, // the old VNode
-  newNode  // the new VNode
-)
-```
+#### `ondestroy`
+
+Fired after the element is removed from the DOM.
+
+<pre>
+<a id="ondestroy-api"></a>ondestroy(<a href="https://developer.mozilla.org/en-US/docs/Web/API/Element">Element</a>)
+</pre>
+
+You can use this event to clean up after your `oncreate` handler - this enables you to integrate third-party widgets (date-pickers, content editors, etc.) and clean up after them.
 
 ## Links