Add 'docs/' from commit '782e99d88000922cbe5cdd55f34566404c5a1777'

git-subtree-dir: docs
git-subtree-mainline: b3d8d47
git-subtree-split: 782e99d

Author: dead-claudia

docs/16.png

@@ -0,0 +1 @@
+mithril.js.org

docs/32.png

@@ -0,0 +1,109 @@
+<!--meta-description
+Approaches you can use to animate your Mithril.js-based apps, including technology and performance suggestions
+-->
+
+# Animations
+
+- [Technology choices](#technology-choices)
+- [Animation on element creation](#animation-on-element-creation)
+- [Animation on element removal](#animation-on-element-removal)
+- [Performance](#performance)
+
+---
+
+### Technology choices
+
+Animations are often used to make applications come alive. Nowadays, browsers have good support for CSS animations, and there are [various](https://greensock.com/gsap) [libraries](https://github.com/julianshapiro/velocity) that provide fast JavaScript-based animations. There's also an upcoming [Web API](https://developer.mozilla.org/en-US/docs/Web/API/Web_Animations_API/Using_the_Web_Animations_API) and a [polyfill](https://github.com/web-animations/web-animations-js) if you like living on the bleeding edge.
+
+Mithril.js does not provide any animation APIs per se, since these other options are more than sufficient to achieve rich, complex animations. Mithril.js does, however, offer hooks to make life easier in some specific cases where it's traditionally difficult to make animations work.
+
+---
+
+### Animation on element creation
+
+Animating an element via CSS when the element is created couldn't be simpler. Just add an animation to a CSS class normally:
+
+```css
+.fancy {animation:fade-in 0.5s;}
+@keyframes fade-in {
+	from {opacity:0;}
+	to {opacity:1;}
+}
+```
+
+```javascript
+var FancyComponent = {
+	view: function() {
+		return m(".fancy", "Hello world")
+	}
+}
+
+m.mount(document.body, FancyComponent)
+```
+
+---
+
+### Animation on element removal
+
+The problem with animating before removing an element is that we must wait until the animation is complete before we can actually remove the element. Fortunately, Mithril.js offers the [`onbeforeremove`](lifecycle-methods.md#onbeforeremove) hook that allows us to defer the removal of an element.
+
+Let's create an `exit` animation that fades `opacity` from 1 to 0.
+
+```css
+.exit {animation:fade-out 0.5s;}
+@keyframes fade-out {
+	from {opacity:1;}
+	to {opacity:0;}
+}
+```
+
+Now let's create a contrived component that shows and hides the `FancyComponent` we created in the previous section:
+
+```javascript
+var on = true
+
+var Toggler = {
+	view: function() {
+		return [
+			m("button", {onclick: function() {on = !on}}, "Toggle"),
+			on ? m(FancyComponent) : null,
+		]
+	}
+}
+```
+
+Next, let's modify `FancyComponent` so that it fades out when removed:
+
+```javascript
+var FancyComponent = {
+	onbeforeremove: function(vnode) {
+		vnode.dom.classList.add("exit")
+		return new Promise(function(resolve) {
+			vnode.dom.addEventListener("animationend", resolve)
+		})
+	},
+	view: function() {
+		return m(".fancy", "Hello world")
+	}
+}
+```
+
+`vnode.dom` points to the root DOM element of the component (`<div class="fancy">`). We use the classList API here to add an `exit` class to `<div class="fancy">`.
+
+Then we return a Promise that resolves when the `animationend` event fires. When we return a promise from `onbeforeremove`, Mithril.js waits until the promise is resolved and only then it removes the element. In this case, it waits for the exit animation to finish.
+
+We can verify that both the enter and exit animations work by mounting the `Toggler` component:
+
+```javascript
+m.mount(document.body, Toggler)
+```
+
+Note that the `onbeforeremove` hook only fires on the element that loses its `parentNode` when an element gets detached from the DOM. This behavior is by design and exists to prevent a potential jarring user experience where every conceivable exit animation on the page would run on a route change. If your exit animation is not running, make sure to attach the `onbeforeremove` handler as high up the tree as it makes sense to ensure that your animation code is called.
+
+---
+
+### Performance
+
+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](https://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).

docs/48.png

@@ -0,0 +1,140 @@
+<!--meta-description
+An API cheatsheet for Mithril.js
+-->
+
+# API
+
+### Cheatsheet
+
+Here are examples for the most commonly used methods. If a method is not listed below, it's meant for advanced usage.
+
+#### m(selector, attrs, children) - [docs](hyperscript.md)
+
+```javascript
+m("div.class#id", {title: "title"}, ["children"])
+```
+
+---
+
+#### m.mount(element, component) - [docs](mount.md)
+
+```javascript
+var state = {
+	count: 0,
+	inc: function() {state.count++}
+}
+
+var Counter = {
+	view: function() {
+		return m("div", {onclick: state.inc}, state.count)
+	}
+}
+
+m.mount(document.body, Counter)
+```
+
+---
+
+#### m.route(root, defaultRoute, routes) - [docs](route.md)
+
+```javascript
+var Home = {
+	view: function() {
+		return "Welcome"
+	}
+}
+
+m.route(document.body, "/home", {
+	"/home": Home, // defines `https://example.com/#!/home`
+})
+```
+
+#### m.route.set(path) - [docs](route.md#mrouteset)
+
+```javascript
+m.route.set("/home")
+```
+
+#### m.route.get() - [docs](route.md#mrouteget)
+
+```javascript
+var currentRoute = m.route.get()
+```
+
+#### m.route.prefix = prefix - [docs](route.md#mrouteprefix)
+
+Invoke this before `m.route()` to change the routing prefix.
+
+```javascript
+m.route.prefix = "#!"
+```
+
+#### m(m.route.Link, ...) - [docs](route.md#mroutelink)
+
+```javascript
+m(m.route.Link, {href: "/Home"}, "Go to home page")
+```
+
+---
+
+#### m.request(options) - [docs](request.md)
+
+```javascript
+m.request({
+	method: "PUT",
+	url: "/api/v1/users/:id",
+	params: {id: 1, name: "test"}
+})
+.then(function(result) {
+	console.log(result)
+})
+```
+
+---
+
+#### m.parseQueryString(querystring) - [docs](parseQueryString.md)
+
+```javascript
+var object = m.parseQueryString("a=1&b=2")
+// {a: "1", b: "2"}
+```
+
+---
+
+#### m.buildQueryString(object) - [docs](buildQueryString.md)
+
+```javascript
+var querystring = m.buildQueryString({a: "1", b: "2"})
+// "a=1&b=2"
+```
+
+---
+
+#### m.trust(htmlString) - [docs](trust.md)
+
+```javascript
+m.render(document.body, m.trust("<h1>Hello</h1>"))
+```
+
+---
+
+#### m.redraw() - [docs](redraw.md)
+
+```javascript
+var count = 0
+function inc() {
+	setInterval(function() {
+		count++
+		m.redraw()
+	}, 1000)
+}
+
+var Counter = {
+	oninit: inc,
+	view: function() {
+		return m("div", count)
+	}
+}
+
+m.mount(document.body, Counter)
+```

docs/CNAME

@@ -0,0 +1,130 @@
+<!--meta-description
+The Mithril.js auto-redraw system re-renders your app after some functions complete. Here, we describe the idiomatic Mithril.js patterns that trigger those redraws.
+-->
+
+# The auto-redraw system
+
+Mithril.js implements a virtual DOM diffing system for fast rendering, and in addition, it offers various mechanisms to gain granular control over the rendering of an application.
+
+When used idiomatically, Mithril.js employs an auto-redraw system that synchronizes the DOM whenever changes are made in the data layer. The auto-redraw system becomes enabled when you call `m.mount` or `m.route` (but it stays disabled if your app is bootstrapped solely via `m.render` calls).
+
+The auto-redraw system simply consists of triggering a re-render function behind the scenes after certain functions complete.
+
+### After event handlers
+
+Mithril.js automatically redraws after DOM event handlers that are defined in a Mithril.js view:
+
+```javascript
+var MyComponent = {
+	view: function() {
+		return m("div", {onclick: doSomething})
+	}
+}
+
+function doSomething() {
+	// a redraw happens synchronously after this function runs
+}
+
+m.mount(document.body, MyComponent)
+```
+
+You can disable an auto-redraw for specific events by setting `e.redraw` to `false`.
+
+```javascript
+var MyComponent = {
+	view: function() {
+		return m("div", {onclick: doSomething})
+	}
+}
+
+function doSomething(e) {
+	e.redraw = false
+	// no longer triggers a redraw when the div is clicked
+}
+
+m.mount(document.body, MyComponent)
+```
+
+
+### After m.request
+
+Mithril.js automatically redraws after [`m.request`](request.md) completes:
+
+```javascript
+m.request("/api/v1/users").then(function() {
+	// a redraw happens after this function runs
+})
+```
+
+You can disable an auto-redraw for a specific request by setting the `background` option to true:
+
+```javascript
+m.request("/api/v1/users", {background: true}).then(function() {
+	// does not trigger a redraw
+})
+```
+
+
+### After route changes
+
+Mithril.js automatically redraws after [`m.route.set()`](route.md#mrouteset) calls and after route changes via links using [`m.route.Link`](route.md#mroutelink).
+
+```javascript
+var RoutedComponent = {
+	view: function() {
+		return [
+			// a redraw happens asynchronously after the route changes
+			m(m.route.Link, {href: "/"}),
+			m("div", {
+				onclick: function() {
+					m.route.set("/")
+				}
+			}),
+		]
+	}
+}
+
+m.route(document.body, "/", {
+	"/": RoutedComponent,
+})
+```
+
+---
+
+### When Mithril.js does not redraw
+
+Mithril.js does not redraw after `setTimeout`, `setInterval`, `requestAnimationFrame`, raw `Promise` resolutions and 3rd party library event handlers (e.g. Socket.io callbacks). In those cases, you must manually call [`m.redraw()`](redraw.md).
+
+Mithril.js also does not redraw after lifecycle methods. Parts of the UI may be redrawn after an `oninit` handler, but other parts of the UI may already have been redrawn when a given `oninit` handler fires. Handlers like `oncreate` and `onupdate` fire after the UI has been redrawn.
+
+If you need to explicitly trigger a redraw within a lifecycle method, you should call `m.redraw()`, which will trigger an asynchronous redraw.
+
+```javascript
+function StableComponent() {
+	var height = 0
+
+	return {
+		oncreate: function(vnode) {
+			height = vnode.dom.offsetHeight
+			m.redraw()
+		},
+		view: function() {
+			return m("div", "This component is " + height + "px tall")
+		}
+	}
+}
+```
+
+Mithril.js does not auto-redraw vnode trees that are rendered via `m.render`. This means redraws do not occur after event changes and `m.request` calls for templates that were rendered via `m.render`. Thus, if your architecture requires manual control over when rendering occurs (as can sometimes be the case when using libraries like Redux), you should use `m.render` instead of `m.mount`.
+
+Remember that `m.render` expects a vnode tree, and `m.mount` expects a component:
+
+```javascript
+// wrap the component in a m() call for m.render
+m.render(document.body, m(MyComponent))
+
+// don't wrap the component for m.mount
+m.mount(document.body, MyComponent)
+```
+
+Mithril.js may also avoid auto-redrawing if the frequency of requested redraws is higher than one animation frame (typically around 16ms). This means, for example, that when using fast-firing events like `onresize` or `onscroll`, Mithril.js will automatically throttle the number of redraws to avoid lag.