Docs for async redraws and assorted changes (see #1592)

docs/change-log.md

@@ -10,12 +10,31 @@
 
 ---
 
+### v2.0.0 (WIP)
+
+#### Breaking changes
+
+- API: `m.redraw()` is always asynchronous ([#1592](https://github.com/MithrilJS/mithril.js/pull/1592))
+- API: `m.mount()` will only render its own root when called, it will not trigger a `redraw()` ([#1592](https://github.com/MithrilJS/mithril.js/pull/1592))
+
+#### News
+
+- API: Introduction of `m.redraw.sync()` ([#1592](https://github.com/MithrilJS/mithril.js/pull/1592))
+
+#### Bug fixes
+
+- API: `m.route.set()` causes all mount points to be redrawn ([#1592](https://github.com/MithrilJS/mithril.js/pull/1592))
+
+---
+
 ### v1.1.3
 
 #### Bug fixes:
 
 - move out npm dependencies added by mistake
 
+---
+
 ### v1.1.2
 
 #### Bug fixes:
@@ -42,6 +61,7 @@ Our thanks to [@0joshuaolson1](https://github.com/0joshuaolson1), [@ACXgit](http
 
 - Addition of a performance regression test suite ([#1789](https://github.com/MithrilJS/mithril.js/issues/1789))
 
+---
 
 ### v1.1.1
 
@@ -51,6 +71,8 @@ Our thanks to [@0joshuaolson1](https://github.com/0joshuaolson1), [@ACXgit](http
 - hyperscript: restore `attrs.class` handling to what it was in v1.0.1 - [#1764](https://github.com/MithrilJS/mithril.js/issues/1764) / [#1769](https://github.com/MithrilJS/mithril.js/pull/1769)
 - documentation improvements ([@JAForbes](https://github.com/JAForbes), [@smuemd](https://github.com/smuemd), [@hankeypancake](https://github.com/hankeypancake))
 
+---
+
 ### v1.1.0
 
 #### News

docs/mount.md

@@ -35,12 +35,12 @@ m.mount(element, {view: function () {return m(Component, attrs)}})
 
 ### Signature
 
-`m.mount(element, component)`
+`m.mount(element, Component)`
 
 Argument    | Type                 | Required | Description
 ----------- | -------------------- | -------- | ---
 `element`   | `Element`            | Yes      | A DOM element that will be the parent node to the subtree
-`component` | `Component|null`     | Yes      | The [component](components.md) to be rendered. `null` unmounts the tree and cleans up internal state.
+`Component` | `Component|null`     | Yes      | The [component](components.md) to be rendered. `null` unmounts the tree and cleans up internal state.
 **returns** |                      |          | Returns nothing
 
 [How to read signatures](signatures.md)
@@ -49,7 +49,9 @@ Argument    | Type                 | Required | Description
 
 ### How it works
 
-Similar to [`m.render()`](render.md), the `m.mount()` method takes a component and mounts a corresponding DOM tree into `element`. If `element` already has a DOM tree mounted via a previous `m.mount()` call, the component is diffed against the previous vnode tree and the existing DOM tree is modified only where needed to reflect the changes. Unchanged DOM nodes are not touched at all.
+`m.mount(element, Component)`, when called renders the component into the element and subscribe the `(element, Component)` pair to the redraw subsystem. That tree will be re-rendered when [manual](redraw.md) or [automatic](autoredraw.md) redraws are triggered.
+
+On redraw, the new vDOM tree is compared (or "diffed") with the old one, and the existing DOM tree is modified only where needed to reflect the changes. Unchanged DOM nodes are not touched at all.
 
 #### Replace a component
 
@@ -73,7 +75,7 @@ In contrast, traversing a javascript data structure has a much more predictable
 
 ### Differences from m.render
 
-A component rendered via `m.mount` automatically auto-redraws in response to view events, `m.redraw()` calls or `m.request()` calls. Vnodes rendered via `m.render()` do not.
+A component rendered via `m.mount` [automatically redraws](autoredraw.md) in response to view events, `m.redraw()` calls or `m.request()` calls. Vnodes rendered via `m.render()` do not.
 
 `m.mount()` is suitable for application developers integrating Mithril widgets into existing codebases where routing is handled by another library or framework, while still enjoying Mithril's auto-redrawing facilities.
 

docs/redraw.md

@@ -2,6 +2,8 @@
 
 - [Description](#description)
 - [Signature](#signature)
+	- [Static members](#static-members)
+		-[m.redraw.sync()](#mredrawsync)
 - [How it works](#how-it-works)
 
 ---
@@ -10,12 +12,10 @@
 
 Updates the DOM after a change in the application data layer.
 
-You DON'T need to call it if data is modified within the execution context of an event handler defined in a Mithril view, or after request completion when using `m.request`/`m.jsonp`.
+You DON'T need to call it if data is modified within the execution context of an event handler defined in a Mithril view, or after request completion when using `m.request`/`m.jsonp`. The [autoredraw](autoredraw.md) system, which is built on top of `m.redraw()` will take care of it.
 
 You DO need to call it in `setTimeout`/`setInterval`/`requestAnimationFrame` callbacks, or callbacks from 3rd party libraries.
 
-`m.redraw` always triggers an asynchronous redraws.
-
 ---
 
 ### Signature
@@ -26,6 +26,16 @@ Argument    | Type                 | Required | Description
 ----------- | -------------------- | -------- | ---
 **returns** |                      |          | Returns nothing
 
+#### Static members
+
+##### m.redraw.sync
+
+`m.redraw.sync()`
+
+Argument    | Type                 | Required | Description
+----------- | -------------------- | -------- | ---
+**returns** |                      |          | Returns nothing
+
 ---
 
 ### How it works
@@ -34,4 +44,12 @@ When callbacks outside of Mithril run, you need to notify Mithril's rendering en
 
 To trigger a redraw, call `m.redraw()`. Note that `m.redraw` only works if you used `m.mount` or `m.route`. If you rendered via `m.render`, you should use `m.render` to redraw.
 
-You should not call m.redraw from a [lifecycle method](lifecycle-methods.md). Doing so will result in undefined behavior.
+`m.redraw()` always triggers an asynchronous redraws, whereas `m.redraw.sync()` triggers a synchronous one. `m.redraw()` is tied to `window.requestAnimationFrame()` (we provide a fallback for IE9). It will thus typically fire at most 60 times per second. It may fire faster if your monitor has a higher refresh rate.
+
+`m.redraw.sync()` is mostly intended to make videos play work in iOS. That only works in response to user-triggered events. It comes with several caveat:
+
+- You should not call `m.redraw.sync()` from a [lifecycle method](lifecycle-methods.md) or the `view()` method of a component. Doing so will result in undefined behavior (it throws an error when possible).
+- `m.redraw.sync()` called from an event handler can cause the DOM to be modified while an event is bubbling. Depending on the structure of the old and new DOM trees, the event can finish the bubbling phase in the new tree and trigger unwanted handlers.
+- It is not throttled. One call to `m.redraw.sync()` causes immediately one `m.render()` call per root registered with [`m.mount()`](mount.md) or [`m.route()`](route.md).
+
+`m.redraw()` doesn't have any of those issues, you can call it from wherever you like.