docs(website): add actions doc and improve frontpage

Author: christianalfoni

packages/overmind-website/examples/guide/creatingactions/chain.ts

@@ -0,0 +1,33 @@
+export const js = [
+  {
+    fileName: 'app/actions.js',
+    code: `
+import * as mutations from './mutations'
+import * as operations from './operations'
+
+export const initializeApp = action =>
+  action()
+    .mutation(mutations.setLoadingUser)
+    .map(operations.getUser)
+    .mutation(mutations.setUser)
+    .mutation(mutations.unsetLoadingUser)
+  `,
+  },
+]
+
+export const ts = [
+  {
+    fileName: 'app/actions.ts',
+    code: `
+import * as mutations from './mutations'
+import * as operations from './operations'
+
+export const initializeApp = action =>
+  action()
+    .mutation(mutations.setLoadingUser)
+    .map(operations.getUser)
+    .mutation(mutations.setUser)
+    .mutation(mutations.unsetLoadingUser)
+  `,
+  },
+]

packages/overmind-website/examples/guide/creatingactions/composing.ts

@@ -0,0 +1,44 @@
+export const js = [
+  {
+    fileName: 'app/actions.js',
+    code: `
+import * as operations from './operations'
+
+export const loadApplication = action =>
+    action()
+
+export const getValidToken = action =>
+    action()
+
+export const initializeApp = action =>
+  action()
+    .when(operations.hasValidToken, {
+      true: loadApplication(action),
+      false: getValidToken(action).compose(loadApplication(action))
+    })
+  `,
+  },
+]
+
+export const ts = [
+  {
+    fileName: 'app/actions.ts',
+    code: `
+import { Action } from './'
+import * as operations from './operations'
+
+export const loadApplication: Action = action =>
+    action()
+
+export const getValidToken: Action = action =>
+    action()
+
+export const initializeApp: Action = action =>
+  action()
+    .when(operations.hasValidToken, {
+      true: loadApplication(action),
+      false: getValidToken(action).compose(loadApplication(action))
+    })
+  `,
+  },
+]

packages/overmind-website/examples/guide/creatingactions/factory.ts

@@ -0,0 +1,19 @@
+export const js = [
+  {
+    fileName: 'app/actions.js',
+    code: `
+export const initializeApp = action =>
+  action()
+  `,
+  },
+]
+
+export const ts = [
+  {
+    fileName: 'app/actions.ts',
+    code: `
+export const initializeApp = action =>
+  action()
+  `,
+  },
+]

packages/overmind-website/examples/guide/creatingactions/instead.ts

@@ -0,0 +1,17 @@
+export const js = [
+  {
+    fileName: 'app/actions.js',
+    code: `
+export const initializeApp = action
+  `,
+  },
+]
+
+export const ts = [
+  {
+    fileName: 'app/actions.ts',
+    code: `
+export const initializeApp = action
+  `,
+  },
+]

packages/overmind-website/examples/guide/creatingactions/mutations.ts

@@ -0,0 +1,58 @@
+export const js = [
+  {
+    fileName: 'app/mutations.js',
+    code: `
+export const setValue = state =>
+    state.value = 'foo'
+
+export const setValueFromAction = (state, value) =>
+  state.value2 = value
+
+export const setValueFromState = state =>
+  state.value3 = state.value
+  `,
+  },
+  {
+    fileName: 'app/actions.js',
+    code: `
+import * as mutations from './mutations'
+
+export const setValues = action =>
+    action()
+      .mutation(mutations.setValue)
+      .mutation(mutations.setValueFromAction)
+      .mutation(mutations.setValueFromState)
+  `,
+  },
+]
+
+export const ts = [
+  {
+    fileName: 'app/mutations.js',
+    code: `
+import { Mutation } from './'
+
+export const setValue: Mutation = state =>
+    state.value = 'foo'
+
+export const setValueFromAction: Mutation<string> = (state, value) =>
+  state.value2 = value
+
+export const setValueFromState: Mutation = state =>
+  state.value3 = state.value
+  `,
+  },
+  {
+    fileName: 'app/actions.js',
+    code: `
+import { Action } from './'
+import * as mutations from './mutations'
+
+export const setValues: Action<string> = action =>
+    action()
+      .mutation(mutations.setValue)
+      .mutation(mutations.setValueFromAction)
+      .mutation(mutations.setValueFromState)
+  `,
+  },
+]

packages/overmind-website/examples/guide/creatingactions/trigger.ts

@@ -0,0 +1,56 @@
+export const js = [
+  {
+    fileName: 'app/actions.js',
+    code: `
+import * as operations from './operations'    
+
+export const actionA = action =>
+  action().map(operations.sayHelloWorld)
+
+export const actionB = action =>
+  action().map(operations.sayHelloWorldAsync)
+
+export const actionC = action =>
+  action().map(operations.inputToUpperCase)
+  `,
+  },
+  {
+    fileName: 'demo.js',
+    code: `
+import app from './app'
+
+app.actions.actionA() // "hello world"
+app.actions.actionB() // Promise<"Hello world">
+app.actions.actionC("hello world") // "HELLO WORLD"
+  `,
+  },
+]
+
+export const ts = [
+  {
+    fileName: 'app/actions.ts',
+    code: `
+import { Action } from './'
+import * as operations from './operations'
+
+export const actionA: Action = action =>
+  action().map(operations.sayHelloWorld)
+  
+export const actionB: Action = action =>
+  action().map(operations.sayHelloWorldAsync)
+  
+export const actionC: Action<string> = action =>
+  action().map(operations.inputToUpperCase)
+  `,
+  },
+  {
+    fileName: 'demo.js',
+    code: `
+import app from './app'
+
+app.actions.actionA() // "hello world"
+app.actions.actionB() // Promise<"Hello world">
+app.actions.actionC("hello world") // "HELLO WORLD"
+  `,
+  },
+]

packages/overmind-website/guides/beginner/03_creatingactions.md

@@ -0,0 +1,80 @@
+# Creating actions
+
+When an event triggers in your application, that being a user interaction, a websocket message etc., you want to run logic that changes the state of the application and/or runs side effects. This logic we express with a concept called **actions**. What is important to understand about actions is that they are an orchestration tool. That means you use actions to compose together different small pieces of logic into a flow of execution. This separation pushes you into a functional approach, giving you several benefits that will be highlighted in this guide.
+
+## Action factory
+
+You define your actions in files named **actions**. From this file you export functions that will receive the action factory function as its only argument.
+
+```marksy
+<Example name="guide/creatingactions/factory" />
+```
+
+When you call this action factory you create the action. Now... why do we have this factory? Why could you not just do something like this:
+
+```marksy
+<Example name="guide/creatingactions/instead" />
+```
+
+1. We want actions to be defined as a callback. This allows actions to compose actions from other files, even in circular reference. This is an important flexibility which callbacks enable
+2. Since actions can be composed into other actions we want to ensure that every composition is unique. By using an action factory we ensure this
+3. Overmind is built with Typescript and this affects the surface API to properly do typing
+
+This might not make too much sense right now, but it will become more clear as we move on in this guide.
+
+## A chaining API
+
+The action returned by the factory has a chaining API. This is the concept that forces you into a functional world. One of the big benefits of this approach is that your code becomes declarative. That means you describe **what** your application is doing in the action chain and then you have small separate functions that actually describes the **how**.
+
+```marksy
+<Example name="guide/creatingactions/chain" />
+```
+
+Each of the methods on the action we call an **operator**. So **mutation** and **map** are operators.
+
+## Calling an action
+
+When the application is initialized you can start calling the actions. You will typically **connect** your app to components before doing this, but you can also call them directly off the application instance. Let us do that now to show how actions behave.
+
+```marksy
+<Example name="guide/creatingactions/trigger" />
+```
+
+Here we have three different examples of actions.
+
+1. **actionA** is called without a value and maps to a new value
+2. **actionB** is also called without a value, but maps to a promised value
+3. **actionC** is called with a value and that value is transformed
+
+What to learn from this is that calling an action is just like calling a plain function that returns its input by default. It is the attaching of operators that gives the action behaviour.
+
+## Changing state
+
+The most common thing you will do is changing the state of the application. You perform a **mutation**. To express this in an action you will use the **mutation** operator. You will define all your mutations in their own files called **mutations**. The reason for that is to be explicit about where mutations actually happens in your application.
+
+```marksy
+<Example name="guide/creatingactions/mutations" />
+```
+
+As the example shows above there are three ways to change the state of the application:
+
+1. Using an explicit value
+2. Using a value passed to the action
+3. Using a value from the state tree
+
+Note that when you use an existing value from the state tree that value has to be a "plain value", meaning that it can not be an existing array or object. It has to be a string, number, boolean or null. The reason is that in a single state tree you should not have the same object or array in multiple parts of the tree. That would break the tracking of changes. Do not worry though, this is very uncommon to do and if you do it, an error is thrown.
+
+## Composing actions
+
+A powerful concept in Overmind is that you can compose actions together. There are several operators that supports this. We will look at one of those operators here, the **when** operator.
+
+```marksy
+<Example name="guide/creatingactions/composing" />
+```
+
+Since each action is defined with a function we call that function and pass it the action factory. This ensures that every composition is unique. Also since each function is defined as a function we can now import actions from anywhere else, even circular imports.
+
+## Summary
+
+This guide gave you some insight into what actions are about. There are still a lot of operators to look into and you can learn more about them in the [side effects]() or go to the [API](http://localhost:4000/api/action) section for actions.
+

packages/overmind-website/src/components/App/index.tsx

@@ -68,6 +68,11 @@ class App extends React.Component<{}, State> {
 
     page.redirect('/api', '/api/action')
   }
+  componentDidUpdate(_, prevState) {
+    if (prevState.currentPath !== this.state.currentPath) {
+      document.querySelector('#overmind-app').scrollTop = 0
+    }
+  }
   componentDidMount() {
     const el = document.querySelector('#overmind-app') as HTMLElement
 

packages/overmind-website/src/components/Doc/elements.tsx

@@ -11,6 +11,29 @@ export const Content = styled.div`
   font-size: 18px;
   color: ${({ theme }) => theme.color.black};
 
+  ol {
+    list-style: none;
+    counter-reset: li;
+  }
+  ol li {
+    counter-increment: li;
+  }
+  ol li::before {
+    content: counter(li);
+    color: ${({ theme }) => theme.color.primary};
+    font-weight: bold;
+    display: inline-block;
+    width: 1em;
+    margin-left: -1em;
+  }
+  ol,
+  ul {
+    margin-top: ${({ theme }) => theme.padding.large};
+    margin-bottom: ${({ theme }) => theme.padding.large};
+  }
+  li {
+    margin-bottom: 15px;
+  }
   > p {
     line-height: 26px;
   }

packages/overmind-website/src/components/FrontPage/elements.tsx

@@ -1 +1,29 @@
 import styled from '../../styled-components'
+
+export const QuickstartWrapper = styled.div`
+  height: 75px;
+  position: fixed;
+  bottom: 0;
+  left: 0;
+  width: 100vw;
+  display: flex;
+`
+
+export const Quickstart = styled.a`
+  cursor: pointer;
+  border: 2px solid ${({ theme }) => theme.color.dark};
+  background-color: ${({ theme }) =>
+    theme.color.lighten(theme.color.dark, -0.5)};
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  text-decoration: none;
+  flex: 1;
+  > *:first-child {
+    margin-right: 15px;
+  }
+  color: ${({ theme }) => theme.color.fade(theme.color.white, 0.25)};
+  :hover {
+    color: ${({ theme }) => theme.color.white};
+  }
+`