Merge pull request #1172 from pygy/unmount

Unmount and cleanly refresh mount points

api/mount.js

@@ -1,14 +1,26 @@
 "use strict"
 
+var Vnode = require("../render/vnode")
 var coreRenderer = require("../render/render")
 var autoredraw = require("../api/autoredraw")
+var dummy = {view: function() {}}
 
 module.exports = function(renderer, pubsub) {
 	return function(root, component) {
+		pubsub.unsubscribe(root.redraw)
+
 		var run = autoredraw(root, renderer, pubsub, function() {
-			renderer.render(root, {tag: component})
+			renderer.render(
+				root,
+				Vnode(component === null ? dummy : component, undefined, undefined, undefined, undefined, undefined)
+			)
 		})
 
 		run()
+
+		if (component === null) {
+			pubsub.unsubscribe(root.redraw)
+			delete root.redraw
+		}
 	}
 }

api/tests/test-mount.js

@@ -32,6 +32,20 @@ o.spec("mount", function() {
 		o(root.firstChild.nodeName).equals("DIV")
 	})
 
+	o("mounting null deletes `redraw` from `root`", function() {
+		mount(root, {
+			view : function() {
+				return m("div")
+			}
+		})
+
+		o(typeof root.redraw).equals('function')
+
+		mount(root, null)
+
+		o(typeof root.redraw).equals('undefined')
+	})
+
 	o("redraws on events", function(done) {
 		var onupdate = o.spy()
 		var oninit   = o.spy()

docs/mount.md

@@ -2,6 +2,7 @@
 
 - [API](#api)
 - [How it works](#how-it-works)
+- [Performance considerations](#performance-considerations)
 - [Differences from m.render](#differences-from-m-render)
 
 ---
@@ -13,7 +14,7 @@
 Argument    | Type                 | Required | Description
 ----------- | -------------------- | -------- | ---
 `element`   | `Element`            | Yes      | A DOM element that will be the parent node to the subtree
-`component` | `Component`          | Yes      | The [component](components.md) to be rendered
+`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)
@@ -24,6 +25,18 @@ Argument    | Type                 | Required | Description
 
 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.
 
+#### Replace a component
+
+Running `mount(element, OtherComponent)` where `element` is a current mount point replaces the component previously mounted with `OtherComponent`.
+
+#### Unmount
+
+Using `m.mount(element, null)` on an element with a previously mounted component unmounts it and cleans up Mithril internal state. This can be useful to prevent memory leaks when removing the `root` node manually from the DOM.
+
+---
+
+### Performance considerations
+
 It may seem wasteful to generate a vnode tree on every redraw, but as it turns out, creating and comparing Javascript data structures is surprisingly cheap compared to reading and modifying the DOM.
 
 Touching the DOM can be extremely expensive for a couple of reasons. Alternating reads and writes can adversely affect performance by causing several browser repaints to occur in quick succession, whereas comparing virtual dom trees allows writes to be batched into a single repaint. Also, the performance characteristics of various DOM operations vary between implementations and can be difficult to learn and optimize for all browsers. For example, in some implementations, reading `childNodes.length` has a complexity of O(n); in some, reading `parentNode` causes a repaint, etc.