docs(website): add more information about derived

Author: christianalfoni

packages/overmind-website/api/derive.md

@@ -12,3 +12,13 @@ The function defining your derived state receives two arguments. The first argum
 ```marksy
 h(Notice, null, "Accessing **rootState** might cause unnecessary updates to the derived function as it will track more state, though typically not an issue")
 ```
+
+An other use case for derived is to return a function. This allows you to insert functions into your state tree which can execute logic, even based on existing state. Even the function itself might be changed out based on the state of the application.
+
+```marksy
+h(Example, { name: "api/derive_function" })
+```
+
+```marksy
+h(Notice, null, "Using state inside the returned function will not be tracked. You have to access the state in the scope of the derived function")
+```

packages/overmind-website/examples/api/derive_function.ts

@@ -0,0 +1,41 @@
+export default (ts) =>
+  ts
+    ? [
+        {
+          fileName: 'app/state.ts',
+          code: `
+import { Derive } from 'overmind'
+
+export type User = {
+  name: string
+}
+
+export type State = {
+  user: User
+  tellUser: Derive<State, (message: string) => {}>
+}
+
+export const state: State = {
+  user: {
+    name: 'John'
+  },
+  tellUser: (state) =>
+    (message) => console.log(message, ', ' + state.user.name)
+}
+    `,
+        },
+      ]
+    : [
+        {
+          fileName: 'app/state.js',
+          code: `
+export const state = {
+  user: {
+    name: 'John'
+  },
+  tellUser: (state) =>
+    (message) => console.log(message, ', ' + state.user.name)
+}
+    `,
+        },
+      ]

packages/overmind-website/examples/guide/definingstate/derived.ts

@@ -0,0 +1,31 @@
+export default (ts) =>
+  ts
+    ? [
+        {
+          fileName: 'app/state.ts',
+          code: `
+import { Derive } from 'overmind'
+
+export type State = {
+  title: string
+  upperTitle: Derive<State, string>
+}
+
+export const state: State = {
+  title: 'My awesome title',
+  upperTitle: state => state.title.toUpperCase()
+}
+  `,
+        },
+      ]
+    : [
+        {
+          fileName: 'app/state.js',
+          code: `
+export const state = {
+  title: 'My awesome title',
+  upperTitle: state => state.title.toUpperCase()
+}
+  `,
+        },
+      ]

packages/overmind-website/guides/beginner/02_definingstate.md

@@ -48,6 +48,25 @@ Are things loading or not, is the user logged in or not ? These are typical usag
 
 All values, with the exception of booleans, can also be **null**. Non existing. You can have a non existing object, array, string or number. That means if we have not selected a tab both the string version and number version would have the value **null**.
 
+## Deriving state
+
+Not all state should be explicitly defined. Some state are values based off of other state. This is what we call **derived state**. A simple example of this would be:
+
+```marksy
+h(Example, { name: "guide/definingstate/derived" })
+```
+
+The first argument of the function is the state the derived function is attached to. A second argument is also passed and that is the root state of the application, allowing you to access whatever you would need. Two important traits of the derived function is:
+
+1. The state accessed is tracked
+2. The value returned is cached
+
+That means the function only runs when accessed and the depending state has changed since last access.
+
+```marksy
+h(Notice, null, "Even though derived state is defined as functions you consume them as plain values. You do not have to call the derived function to get the value")
+```
+
 ## Defining state
 
 We define the state of the application in **state** files. For example, the top level state could be defined as:
@@ -56,8 +75,6 @@ We define the state of the application in **state** files. For example, the top
 h(Example, { name: "guide/definingstate/define" })
 ```
 
-Note that we are exporting variables from our state module. We use **let** for values that can be replaced and **const** for values that can not be replaced. That would typically be derived values, but you might also have arrays or objects that should not be replaced.
-
 As your application grows you will most likely move parts of the state to their own namespaces. An example of that could be:
 
 ```marksy