docs: update with latest fixes (MithrilJS#2116)

Author: tivac

Diff for: docs/animation.md

@@ -102,4 +102,4 @@ Note that the `onbeforeremove` hook only fires on the element that loses its `pa
 
 When creating animations, it's recommended that you only use the `opacity` and `transform` CSS rules, since these can be hardware-accelerated by modern browsers and yield better performance than animating `top`, `left`, `width`, and `height`.
 
-It's also recommended that you avoid the `box-shadow` rule and selectors like `:nth-child`, since these are also resource intensive options. If you want to animate a `box-shadow`, consider [putting the `box-shadow` rule on a pseudo element, and animate that element's opacity instead](http://tobiasahlin.com/blog/how-to-animate-box-shadow/). Other things that can be expensive include large or dynamically scaled images and overlapping elements with different `position` values (e.g. an absolute postioned element over a fixed element).
+It's also recommended that you avoid the `box-shadow` rule and selectors like `:nth-child`, since these are also resource intensive options. If you want to animate a `box-shadow`, consider [putting the `box-shadow` rule on a pseudo element, and animate that element's opacity instead](http://tobiasahlin.com/blog/how-to-animate-box-shadow/). Other things that can be expensive include large or dynamically scaled images and overlapping elements with different `position` values (e.g. an absolute positioned element over a fixed element).

Diff for: docs/code-of-conduct.md

@@ -55,7 +55,7 @@ further defined and clarified by project maintainers.
 ## Enforcement
 
 Instances of abusive, harassing, or otherwise unacceptable behavior may be
-reported by contacting the project team at [[email protected]](mailto:[email protected]?subject=Mithril Code of Conduct). All
+reported by contacting the project team at [[email protected]](mailto:[email protected]?subject=Mithril%20Code%20of%20Conduct). All
 complaints will be reviewed and investigated and will result in a response that
 is deemed necessary and appropriate to the circumstances. The project team is
 obligated to maintain confidentiality with regard to the reporter of an incident.

Diff for: docs/components.md

@@ -61,6 +61,9 @@ var ComponentWithHooks = {
 	oncreate: function(vnode) {
 		console.log("DOM created")
 	},
+	onbeforeupdate: function(vnode, old) {
+		return true
+	},
 	onupdate: function(vnode) {
 		console.log("DOM updated")
 	},
@@ -74,9 +77,6 @@ var ComponentWithHooks = {
 	onremove: function(vnode) {
 		console.log("removing DOM element")
 	},
-	onbeforeupdate: function(vnode, old) {
-		return true
-	},
 	view: function(vnode) {
 		return "hello"
 	}
@@ -177,7 +177,7 @@ They can be consumed in the same way regular components can.
 m.render(document.body, m(closureComponent))
 
 // EXAMPLE: via m.mount
-m.mount(document.body, closuresComponent)
+m.mount(document.body, closureComponent)
 
 // EXAMPLE: via m.route
 m.route(document.body, "/", {

Diff for: docs/contributing.md

@@ -22,9 +22,11 @@ To send a pull request:
 
 - fork the repo (button at the top right in GitHub)
 - clone the forked repo to your computer (green button in GitHub)
+- Switch to the `next` branch (run `git checkout next`)
 - create a feature branch (run `git checkout -b the-feature-branch-name`)
 - make your changes
-- run the tests (run `npm t`)
+- run the tests (run `npm test`)
+- push your changes to your fork
 - submit a pull request (go to the pull requests tab in GitHub, click the green button and select your feature branch)
 
 

Diff for: docs/css.md

@@ -87,7 +87,7 @@ Nowadays there are [a lot of CSS-in-JS libraries with various degrees of robustn
 
 The main problem with many of these libraries is that even though they require a non-trivial amount of transpiler tooling and configuration, they also require sacrificing code readability in order to work, e.g. `<a class={classnames(styles.button, styles.danger)}></a>` vs `<a class="button danger"></a>` (or `m("a.button.danger")` if we're using hyperscript).
 
-Often sacrifices also need to be made at time of debugging, when mapping rendered CSS class names back to their source. Often all you get in browser developer tools is a class like `button_fvp6zc2gdj35evhsl73ffzq_0 danger_fgdl0s2a5fmle5g56rbuax71_0` with useless source maps (or worse, entirely criptic class names).
+Often sacrifices also need to be made at time of debugging, when mapping rendered CSS class names back to their source. Often all you get in browser developer tools is a class like `button_fvp6zc2gdj35evhsl73ffzq_0 danger_fgdl0s2a5fmle5g56rbuax71_0` with useless source maps (or worse, entirely cryptic class names).
 
 Another common issue is lack of support for less basic CSS features such as `@keyframes` and `@font-face`.
 

Diff for: docs/generate.js

@@ -12,9 +12,6 @@ try {fs.mkdirSync("./dist/archive/v" + version)} catch (e) {/* ignore */}
 var guides = fs.readFileSync("docs/nav-guides.md", "utf-8")
 var methods = fs.readFileSync("docs/nav-methods.md", "utf-8")
 
-var index = fs.readFileSync("docs/index.md", "utf-8")
-fs.writeFileSync("README.md", index.replace(/(\]\()(.+?)\.md(\))/g, "$1http://mithril.js.org/$2.html$3"), "utf-8")
-
 generate("docs")
 
 function generate(pathname) {

Diff for: docs/index.md

@@ -225,7 +225,7 @@ var Splash = {
 
 As you can see, this component simply renders a link to `#!/hello`. The `#!` part is known as a hashbang, and it's a common convention used in Single Page Applications to indicate that the stuff after it (the `/hello` part) is a route path.
 
-Now that we going to have more than one screen, we use `m.route` instead of `m.mount`.
+Now that we're going to have more than one screen, we use `m.route` instead of `m.mount`.
 
 ```javascript
 m.route(root, "/splash", {

Diff for: docs/installation.md

@@ -2,6 +2,8 @@
 
 - [CDN](#cdn)
 - [NPM](#npm)
+- [Quick start with Webpack](#quick-start-with-webpack)
+- [TypeScript](#typescript)
 
 ### CDN
 
@@ -15,30 +17,57 @@ If you're new to Javascript or just want a very simple setup to get your feet we
 
 ### NPM
 
-#### Quick start with Webpack
+```bash
+$> npm install mithril --save
+```
+
+---
 
+### Quick start with Webpack
+
+1. Initialize the directory as an npm package
 ```bash
-# 1) install
-npm install mithril --save
+$> npm init --yes
+```
 
-npm install webpack --save
+2. install required tools
+```bash
+$> npm install mithril --save
+$> npm install webpack webpack-cli --save-dev
+```
 
-# 2) add this line into the scripts section in package.json
-#	"scripts": {
-#		"start": "webpack src/index.js bin/app.js --watch"
-#	}
+3. Add a "start" entry to the scripts section in `package.json`.
+```js
+{
+  // ...
+  "scripts": {
+    "start": "webpack src/index.js --output bin/app.js -d --watch"
+  }
+}
+```
 
-# 3) create an `src/index.js` file
+3. Create `src/index.js`
+```js
+import m from "mithril";
 
-# 4) create an `index.html` file containing `<script src="bin/app.js"></script>`
+m.render(document.body, "hello world");
+```
 
-# 5) run bundler
-npm start
+4. create `index.html`
+```html
+<!DOCTYPE html>
+<body>
+    <script src="bin/app.js"></script>
+</body>
+```
 
-# 6) open `index.html` in the (default) browser
-open index.html
+5. run bundler
+```bash
+$> npm start
 ```
 
+6. open `index.html` in a browser
+
 #### Step by step
 
 For production-level projects, the recommended way of installing Mithril is to use NPM.
@@ -78,7 +107,7 @@ Most browser today do not natively support modularization systems (CommonJS or E
 A popular way for creating a bundle is to setup an NPM script for [Webpack](https://webpack.js.org/). To install Webpack, run this from the command line:
 
 ```bash
-npm install webpack --save-dev
+npm install webpack webpack-cli --save-dev
 ```
 
 Open the `package.json` that you created earlier, and add an entry to the `scripts` section:
@@ -87,7 +116,7 @@ Open the `package.json` that you created earlier, and add an entry to the `scrip
 {
 	"name": "my-project",
 	"scripts": {
-		"start": "webpack src/index.js bin/app.js -d --watch"
+		"start": "webpack src/index.js --output bin/app.js -d --watch"
 	}
 }
 ```
@@ -149,8 +178,8 @@ If you open bin/app.js, you'll notice that the Webpack bundle is not minified, s
 {
 	"name": "my-project",
 	"scripts": {
-		"start": "webpack src/index.js bin/app.js -d --watch",
-		"build": "webpack src/index.js bin/app.js -p",
+		"start": "webpack src/index.js --output bin/app.js -d --watch",
+		"build": "webpack src/index.js --output bin/app.js -p",
 	}
 }
 ```
@@ -231,3 +260,15 @@ If you don't have the ability to run a bundler script due to company security po
 // if a CommonJS environment is not detected, Mithril will be created in the global scope
 m.render(document.body, "hello world")
 ```
+
+---
+
+### TypeScript
+
+TypeScript type definitions are available from DefinitelyTyped. They can be installed with:
+
+```bash
+$> npm install @types/mithril --save-dev
+```
+
+For example usage, to file issues or to discuss TypeScript related topics visit: https://github.com/MithrilJS/mithril.d.ts

Diff for: docs/integrating-libs.md

@@ -0,0 +1,57 @@
+# Integrating with Other Libraries
+Integration with third party libraries or vanilla javascript code can be achieved via [lifecycle methods](lifecycle-methods.md).
+
+- [Usage](#usage)
+
+### Usage
+```javascript
+var FullCalendar = {
+
+	oncreate: function (vnode) {
+		console.log('FullCalendar::oncreate')
+		$(vnode.dom).fullCalendar({
+			// put your initial options and callbacks here
+		})
+
+		Object.assign(vnode.attrs.parentState, {fullCalendarEl: vnode.dom})
+	},
+
+	// Consider that the lib will modify this parent element in the DOM (e.g. add dependent class attribute and values).
+	// As long as you return the same view results here, mithril will not
+	// overwrite the actual DOM because it's always comparing old and new VDOM
+	// before applying DOM updates. 
+	view: function (vnode) {
+		return m('div')
+	},
+
+	onbeforeremove: function (vnode) {
+		// Run any destroy / cleanup methods here.
+		//E.g. $(vnode.state.fullCalendarEl).fullCalendar('destroy')
+	}
+}
+
+m.mount(document.body, {
+	view: function (vnode) {
+		return [
+			m('h1', 'Calendar'),
+			m(FullCalendar, {parentState: vnode.state}),
+			m('button', {onclick: prev}, 'Mithril Button -'),
+			m('button', {onclick: next}, 'Mithril Button +')
+
+		]
+
+		function next() {
+			$(vnode.state.fullCalendarEl).fullCalendar('next')
+		}
+
+		function prev() {
+			$(vnode.state.fullCalendarEl).fullCalendar('prev')
+		}
+
+	}
+
+})
+
+```
+
+Running example [flems: FullCalendar](https://flems.io/#0=N4IgZglgNgpgziAXAbVAOwIYFsZJAOgAsAXLKEAGhAGMB7NYmBvAHigjQGsACAJxigBeADog4xAJ6w4hGDGKjuhfmBEgSxAA5xEAel3UAJmgBWcfNSi0ArobBQM-C7Sy6MJjAA9d7AEZxdMGsoKGoMWDRDR10AZnwAdnwABkDg0PCmKN58LA4LODhRAD4QAF8KdGxcRAIzShp6RmYagDdHbgAxNIBhDMj2wW5gYTQR4WJ6an4MRkRuILRqYgh6bgAKFrRaQxgASiGxhWI6NDhaWHwrAHM1gHIukN6oft5EREnpxlvdw-GAEg2Wx2+EMLl2+CCjz6WTWw1GR3G+m4mmsxG4EhsvG4HAgy3C3FommW9Dg3AwkW4YRCvgw1E4pNk-F+xFKP1G8PGAHlfCYYEt8BgChArmhAdsYALiMReOZNI4mMQAMrEGYwChDSFQJ6ZRwAUSgc024pBLlZh3KY3hLQgMAA7nMFksVmh1kadvs4eNxvxiNZeC6sHdDBAWt9zRRLeN6L4YGBaPx+FhaC0YA7rItiS6xe6DhziEiAErpsloCTcHbiXi0Mu6SmwcnWTTcHDEQjbBkwJzM-QAt0S8SqiE9aF6qDgzXal5B+DS6th+GlEaL9lYHI2BhrUHUaw4Bj4XzbCTqz3Ea12tMZ52uoF7XNe6XyP0u5DM8aB26EACMt3Vt0nWW+CM8zfNYHi1EdeGPOV+AYZVVUNG98AHRhWSA+8QNuXxUQmNAfzvBEjkmdg6TmTR+BaV8WV-ABZXFlGgbgACFsNWABaQDKPfLCpXoPCT3QnDLAgEjuDQGBPAUYCqO4W5aNbXgGOYniXQAannZkAF1IyOR1M1E8TiDWD1KN7RDkIlCcIP1cdhwiGFbjEiT1KOZdmV0q8yJgFojPw+9TONcyhyhOzRxs4KdV4O5PNDNl71chdLVZMoKhATAcDwfIECoE4mmIPAyg0qh2C4BAUEqdKalyeToHqP1yBqDRtD0XR000TgrmcVwqvoqAAAFP3wAaAFZdG6hSoHwOoqEkTRqhAOpynKuak13PKqDqvBGp0fRWvazrRpcBVeoAJkGgBOfBjoO1bJqykAZrmhaUrSx6AEdrE7CRat4er1ClJqdrQNqOroVwTHez7eriU7P10YNxF0cGPt4CRbvqB68Cepa8E1KkIu+36tua3aQZcVIQjxl4oYSZI4YgBHcYgtHpokWbMYQUoNNKIA)

Diff for: docs/jsx.md

@@ -98,7 +98,7 @@ npm install babel-core babel-loader babel-preset-es2015 babel-plugin-transform-r
 
 Create a `.babelrc` file:
 
-```
+```json
 {
 	"presets": ["es2015"],
 	"plugins": [
@@ -121,7 +121,7 @@ module.exports = {
 		filename: 'app.js',
 	},
 	module: {
-		loaders: [{
+		rules: [{
 			test: /\.js$/,
 			exclude: /node_modules/,
 			loader: 'babel-loader'
@@ -130,6 +130,8 @@ module.exports = {
 }
 ```
 
+For those familiar with Webpack already, please note that adding the Babel options to the `babel-loader` section of your `webpack.config.js` will throw an error, so you need to include them in the separate `.babelrc` file.
+
 This configuration assumes the source code file for the application entry point is in `src/index.js`, and this will output the bundle to `bin/app.js`.
 
 To run the bundler, setup an npm script. Open `package.json` and add this entry under `"scripts"`:
@@ -189,7 +191,7 @@ JSX is useful for teams where HTML is primarily written by someone without Javas
 Hyperscript is the compiled representation of JSX. It's designed to be readable and can also be used as-is, instead of JSX (as is done in most of the documentation). Hyperscript tends to be terser than JSX for a couple of reasons:
 
 - it does not require repeating the tag name in closing tags (e.g. `m("div")` vs `<div></div>`)
-- static attributes can be written using CSS selector syntax (i.e. `m("a.button")` vs `<div class="button"></div>`
+- static attributes can be written using CSS selector syntax (i.e. `m("a.button")` vs `<a class="button"></a>`)
 
 In addition, since hyperscript is plain Javascript, it's often more natural to indent than JSX:
 

Diff for: docs/keys.md

@@ -180,7 +180,7 @@ m("div", [
 
 #### Avoid passing model data directly to components if the model uses `key` as a data property
 
-The `key` property may appear in your data model in a way that conflicts with Mithril's key logic. For example, a component may represent an entity whose `key` property is expected to change over time. This can lead to components receiving the wrong data, re-initialise, or change positions unexpectedly. If your data model uses the `key` property, make sure to wrap the data such that Mithril doesn't misinterpret it as a rendering instruction:
+The `key` property may appear in your data model in a way that conflicts with Mithril's key logic. For example, a component may represent an entity whose `key` property is expected to change over time. This can lead to components receiving the wrong data, re-initialize, or change positions unexpectedly. If your data model uses the `key` property, make sure to wrap the data such that Mithril doesn't misinterpret it as a rendering instruction:
 
 ```javascript
 // Data model

Diff for: docs/layout.html

@@ -16,7 +16,7 @@ <h1><img src="logo.svg"> Mithril <small>[version]</small></h1>
 					<a href="index.html">Guide</a>
 					<a href="api.html">API</a>
 					<a href="https://gitter.im/MithrilJS/mithril.js">Chat</a>
-					<a href="https://github.com/MithrilJS/mithril.js">Github</a>
+					<a href="https://github.com/MithrilJS/mithril.js">GitHub</a>
 				</nav>
 			</section>
 		</header>

Diff for: docs/learning-mithril.md

@@ -0,0 +1,5 @@
+# Learning Mithril
+
+Links to Mithril learning content:
+
+- [Mithril 0-60](https://scrimba.com/playlist/playlist-34)

Diff for: 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.
 

Diff for: docs/nav-guides.md

@@ -9,6 +9,8 @@
 	- [Animation](animation.md)
 	- [Testing](testing.md)
 	- [Examples](examples.md)
+	- [Integrating with Other Libraries](integrating-libs.md)
+	- [Learning Mithril](learning-mithril.md)
 - Key concepts
 	- [Vnodes](vnodes.md)
 	- [Components](components.md)

Diff for: docs/promise.md

@@ -302,7 +302,7 @@ This example also illustrates another benefit of smaller functions: we reused th
 
 ### Why not callbacks
 
-Callbacks are another mechanism for working with asynchrounous computations, and are indeed more adequate to use if an asynchronous computation may occur more than one time (for example, an `onscroll` event handler).
+Callbacks are another mechanism for working with asynchronous computations, and are indeed more adequate to use if an asynchronous computation may occur more than one time (for example, an `onscroll` event handler).
 
 However, for asynchronous computations that only occur once in response to an action, promises can be refactored more effectively, reducing code smells known as pyramids of doom (deeply nested series of callbacks with unmanaged state being used across several closure levels).
 

Diff for: docs/redraw.md

@@ -10,7 +10,7 @@
 
 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.