GitBook: [master] 11 pages modified

Author: christianalfoni

README.md

@@ -1,4 +1,63 @@
-# overmind
-Repo for proxy based Cerebral implementation (working-title)
+# Overmind
+
+### Why Overmind?
+
+Instead of writing components that isolates state:
+
+{% code-tabs %}
+{% code-tabs-item title="react.js" %}
+```javascript
+import React from 'react'
+
+class InputComponent extends React.Component {
+  state = {
+    value: ''
+  }
+  changeValue = (event) => {
+    this.setState({
+      value: event.target.value
+    })
+  }
+  render () {
+    return <input value={this.state.value} onChange={this.changeValue} />
+  }
+}
+```
+{% endcode-tabs-item %}
+{% endcode-tabs %}
+
+You keep your state and logic to change that state in Overmind:
+
+{% code-tabs %}
+{% code-tabs-item title="react.js" %}
+```javascript
+import App from 'overmind/react'
+
+const app = new App({
+  state: {
+    value: ''
+  },
+  actions: action => ({
+    changeValue: action()
+      .map((event) => event.target.value)
+      .mutation((state, value) => state.value = value)
+  })
+})
+
+const InputComponent = app.connect(
+  function InputComponent ({ appState, actions }) {
+    return <input value={appState.value} onChange={actions.changeValue} />
+  }
+)
+```
+{% endcode-tabs-item %}
+{% endcode-tabs %}
+
+There are many tools, like Redux, Mobx, Vuex, Hyperapp etc., that also moves state and logic outside your components. Where Overmind differs is:
+
+* **Automatic render.** When you connect your app to a component the component will automatically and optimally rerender based on the state that is being used inside that component 
+* **Safe mutations**. There is only one place in Overmind you can change the state of your application and that is inside the mutation operator. Any outside mutations throws errors 
+* **Next level devtools.** The Overmind devtools gives you insight into everything that is happening inside your application. That being what state connected components are watching, actions being run, mutations performed and even side effects run 
+* **Functional actions.** Instead of expressing logic as functions or methods, Overmind exposes an action chaining API. This forces you into a functional approach. Functional code encourages writing many small and focused functions that does one thing. This keeps your application more testable, maintainable and composable 
+* **Typescript for the win**. You do not have to use Typescript with Overmind, but when you do you will get full type safety in action chains and components
 
-Join the implementation at: [Overmind Implementation Specification](https://cerebral.gitbook.io/overmind/)

SUMMARY.md

@@ -0,0 +1,13 @@
+# Table of contents
+
+* [Overmind](README.md)
+* [Install](install.md)
+* [Create an app](create-an-app.md)
+* [Connect to a view](connect-to-a-view/README.md)
+  * [React](connect-to-a-view/react.md)
+  * [Vue](connect-to-a-view/vue.md)
+  * [Other views](connect-to-a-view/other-views.md)
+* [Devtools](devtools.md)
+* [Providers](untitled.md)
+* [Organizing apps](organizing-apps.md)
+

connect-to-a-view/README.md

@@ -0,0 +1,2 @@
+# Connect to a view
+

connect-to-a-view/other-views.md

@@ -0,0 +1,68 @@
+# Other views
+
+The default instance of Overmind exposes tools to track access to state. This allows you to integrate Overmind with any view layer you want. Overmind has several preset view implementations like **React**, **VueJS, Preact** etc.
+
+```typescript
+import App from 'overmind'
+
+const {
+  state,
+  actions,
+  trackState,
+  clearTrackState,
+  addMutationListener
+} = new App({
+  state: {
+    title: 'Hello from Overmind'
+  },
+  actions: (action) => ({
+    changeTitle: action()
+      .map(event => event.target.value)
+      .mutate((state, value) => state.title = value)
+  })
+})
+```
+
+#### state
+
+This is the state of your application.
+
+#### actions
+
+The actions defined. These are just plain functions you call with a value:
+
+```typescript
+document.querySelector('#input').addEventListener('input', actions.changeTitle)
+```
+
+#### trackState / clearTrackState
+
+This function allows you to track when state is accessed. Typically you would use this in combination with lifecycle hooks of components to track what the component accesses on render:
+
+```typescript
+const trackId = trackState('ComponentName')
+// Logic that renders a component
+const paths = clearTrackState(trackId)
+
+paths // Set { 'path.to.some.state', 'path.to.some.other.state' }
+```
+
+This information is automatically passed to the Overmind devtools. 
+
+**addMutationListener**
+
+This function is used with the tracked paths. You typically create the listener on the first render and update it on subsequent renders:
+
+```typescript
+const listener = addMutationListener(paths, () => {
+  // This callback is called when the paths are mutated
+  // Typically here you trigger a new render of the component
+  // and update the paths of the listener with the new tracked paths
+})
+
+listener.update(newPaths) // Update the listener with new paths
+listener.dispose() // Dispose the listener, typically when component unmounts
+```
+
+Look at the Overmind implementations of the different views to see how this is used in practice.
+

connect-to-a-view/react.md

@@ -0,0 +1,2 @@
+# React
+

connect-to-a-view/vue.md

@@ -0,0 +1,2 @@
+# Vue
+

create-an-app.md

@@ -0,0 +1,2 @@
+# Create an app
+

devtools.md

@@ -0,0 +1,2 @@
+# Devtools
+

install.md

@@ -0,0 +1,2 @@
+# Install
+

organizing-apps.md

@@ -0,0 +1,161 @@
+# Organizing apps
+
+This example shows a structured application using two modules. The **compose** function allows you to namespace your modules. In this example we are not taking any shortcuts. We explicitly split up and type all functions, components etc. By default this typing would be inferred when inlining the functions and components, but we are taking full advantage of the functional approach which makes the application highly testable, predictable and composable. The usage of two modules here is artificial, but important to show you how modules has access to each other.
+
+{% code-tabs %}
+{% code-tabs-item title="index.tsx" %}
+```typescript
+import React from 'react'
+import { render } from 'react-dom'
+import App from './components/App'
+
+render(<App />, document.querySelector('#app'))
+```
+{% endcode-tabs-item %}
+
+{% code-tabs-item title="overmind.ts" %}
+```typescript
+import Overmind, { IContext, IAction, IConnect, compose } from 'overmind/react'
+import * as main from './modules/main'
+import * as items from './modules/items'
+
+export type AppState = {
+  main: main.State,
+  items: items.State
+}
+
+export type Context = IContext<AppState>
+
+export type Action = IAction<Context>
+
+const app = new Overmind(compose({
+  main,
+  items
+}))
+
+export type Connect = IConnect<typeof app.state, typeof app.actions>
+
+export const connect = app.connect
+
+```
+{% endcode-tabs-item %}
+
+{% code-tabs-item title="modules/main/index.ts" %}
+```typescript
+import { AppState, Action } from '../../overmind'
+
+/*
+  STATE
+*/
+export type State = {
+  newItemValue: string
+}
+
+export const state: State = {
+  newItemValue: ''
+}
+
+/*
+  MUTATIONS
+*/
+export const setNewItemValue = (state: AppState, value: string) => state.main.newItemValue = value
+
+/*
+  HELPERS
+*/
+export const getEventValue = (event: React.ChangeEvent) => event.target.value
+
+/*
+  ACTIONS
+*/
+export const actions = (action: Action) => ({
+  changeNewItemValue: action<React.ChangeEvent>()
+    .map(getEventValue)
+    .mutation(setNewItemValue)
+})
+```
+{% endcode-tabs-item %}
+
+{% code-tabs-item title="modules/items/index.ts" %}
+```typescript
+import { AppState, Context, Action } from '../../overmind'
+
+/*
+  STATE
+*/
+export type Item = {
+  title: string
+}
+
+export type State = {
+  items: Item[]
+}
+
+export const state: State = {
+  items: []
+}
+
+/*
+  MUTATIONS
+*/
+export const addNewItem = (state: AppState, item: Item) => state.items.list.push(item)
+
+export const resetNewItemValue = (state: AppState) => state.main.newItemValue = ''
+
+/*
+  HELPERS
+*/
+export const createItem = (_, { state }: Context) => ({
+  title: state.main.newItemValue
+})
+
+/*
+  ACTIONS
+*/
+export const actions = (action: Action) => ({
+  addNewItem: action()
+    .map(createItem)
+    .mutation(addNewItem)
+    .mutation(resetNewItemValue)
+})
+```
+{% endcode-tabs-item %}
+
+{% code-tabs-item title="components/App/index.tsx" %}
+```typescript
+import React from 'react'
+import { connect, Connect } from '../../overmind'
+
+const App: React.SFC<Connect> = ({ appState, actions }) => (
+  <div>
+    <form onSubmit={event => {
+      event.preventDefault()
+      actions.items.addNewItem()
+    }}>
+      <input
+        onChange={actions.changeNewItemValue}
+        value={appState.main.newItemValue}
+      />
+    </form>
+    <ul>
+      {appState.items.list.map(item => (
+        <li>{item.title}</li>
+      ))}
+    </ul>
+  </div>
+)
+
+export default connect(App)
+```
+{% endcode-tabs-item %}
+{% endcode-tabs %}
+
+What to take notice of:
+
+* We are not interfering in any way with the initial rendering of the app, meaning you just connect state where you need it
+* By default Overmind takes a single module with state, actions etc., but **compose** allows us to merge multiple modules together, giving them a namespace \("main" and "items" in this example\)
+* We separate mutations and other side effects. This makes it absolutely clear where mutations are performed and only the **mutation** operator is allowed to perform these mutations.
+* The actions are now just plain functions taking any payload. When the action is typed it requires a value, when it is not typed, it does not require a value \(this is actually very difficult to do in TypeScript\)
+
+
+