docs(website): statecharts api

Author: christianalfoni

packages/overmind-website/api/statecharts.md

@@ -2,9 +2,9 @@
 
 Statecharts is a configuration factory, just like **merge**, **namespaced** and **lazy**. It allows you to restrict what actions are to be run in certain states.
 
-## statechart
+## statecharts
 
-The factory function you use to wrap an Overmind configuration.
+The factory function you use to wrap an Overmind configuration. You add one or multiple charts to the configuration, where the key is the *id* of the chart.
 
 ```marksy
 h(Example, { name: "api/statecharts_statechart" })
@@ -47,11 +47,59 @@ h(Example, { name: "api/statecharts_on" })
 ```
 
 ## nested
-A nested statechart will operate within its parent transition state. The means when the parent transition state is entered or exited any defined **entry** and **exit** actions will be run. When the parent enters its transition state the **initial** state of the child statechart will be activated.
+A nested statechart will operate within its parent transition state. The means when the parent transition state is entered or exited any defined **entry** and **exit** actions will be run. When the parent enters its transition state the **initial** state of the child statechart(s) will be activated.
 
 ```marksy
 h(Example, { name: "api/statecharts_nested" })
 ```
 
+## parallel
+Multiple statecharts will run in parallel. Either for the factory configuration or nested charts. You can add the same chart multiple times behind different ids.
 
+```marksy
+h(Example, { name: "api/statecharts_parallel" })
+```
 
+## matches
+
+The matches API is used in your components to identify what state your charts are in. It is accessed on the **state**.
+
+```js
+// Given that you have added statecharts to the root configuration
+state.matches({
+  chartA: {
+    STATE_A: true
+  }
+})
+
+// Nested chart
+state.matches({
+  chartA: {
+    STATE_A: {
+      nestedChartA: {
+        FOO: true
+      }
+    }
+  }
+})
+
+// Parallel
+state.matches({
+  chartA: {
+    STATE_A: true
+  },
+  chartB: {
+    STATE_B: true
+  }
+})
+
+// Negative check
+state.matches({
+  chartA: {
+    STATE_A: true
+  },
+  chartB: {
+    STATE_B: false
+  }
+})
+```

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

@@ -3,7 +3,7 @@ export default (ts) =>
     ? [
         {
           code: `
-import { Statechart, statechart } from 'overmind/config'
+import { Statechart, statecharts } from 'overmind/config'
 import * as actions from './actions'
 import { state } from './state'
 
@@ -12,29 +12,29 @@ const config = {
   state
 }
 
-enum States {
-  STATE_A = 'STATE_A',
-  STATEA_B = 'STATE_B'
-}
-
-const chart: Statechart<typeof config, States> = {
-  initial: States.STATE_A,
+const chart: Statechart<typeof config, {
+  STATE_A: void
+  STATE_B: void
+}> = {
+  initial: 'STATE_A',
   states: {
-    [States.STATE_A]: {
+    STATE_A: {
       entry: 'someActionName'
     },
-    [States.STATE_B]: {}
+    STATE_B: {}
   }
 }
 
-export default statechart(config, chart)
+export default statecharts(config, {
+  chartId: chart
+})
 `,
         },
       ]
     : [
         {
           code: `
-import { statechart } from 'overmind/config'
+import { statecharts } from 'overmind/config'
 import * as actions from './actions'
 import { state } from './state'
 
@@ -53,7 +53,9 @@ const chart = {
   }
 }
 
-export default statechart(config, chart)
+export default statecharts(config, {
+  chartId: chart
+})
 `,
         },
       ]

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

@@ -3,7 +3,7 @@ export default (ts) =>
     ? [
         {
           code: `
-import { Statechart, statechart } from 'overmind/config'
+import { Statechart, statecharts } from 'overmind/config'
 import * as actions from './actions'
 import { state } from './state'
 
@@ -12,30 +12,30 @@ const config = {
   state
 }
 
-enum States {
-  STATE_A = 'STATE_A',
-  STATEA_B = 'STATE_B'
-}
-
-const chart: Statechart<typeof config, States> = {
-  initial: States.STATE_A,
+const chart: Statechart<typeof config, {
+  STATE_A: void
+  STATE_B: void
+}> = {
+  initial: 'STATE_A',
   states: {
-    [States.STATE_A]: {
+    STATE_A: {
       entry: 'someActionName',
       exit: 'someOtherActionName'
     },
-    [States.STATE_B]: {}
+    STATE_B: {}
   }
 }
 
-export default statechart(config, chart)
+export default statecharts(config, {
+  chartId: chart
+})
 `,
         },
       ]
     : [
         {
           code: `
-import { statechart } from 'overmind/config'
+import { statecharts } from 'overmind/config'
 import * as actions from './actions'
 import { state } from './state'
 
@@ -55,7 +55,9 @@ const chart = {
   }
 }
 
-export default statechart(config, chart)
+export default statecharts(config, {
+  chartId: chart
+})
 `,
         },
       ]

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

@@ -3,7 +3,7 @@ export default (ts) =>
     ? [
         {
           code: `
-import { Statechart, statechart } from 'overmind/config'
+import { Statechart, statecharts } from 'overmind/config'
 import * as actions from './actions'
 import { state } from './state'
 
@@ -12,23 +12,22 @@ const config = {
   state
 }
 
-enum States {
-  STATE_A = 'STATE_A',
-  STATEA_B = 'STATE_B'
-}
-
-const chart: Statechart<typeof config, States> = {
-  initial: States.STATE_A
+const chart: Statechart<typeof config, {
+  STATE_A: void
+}> = {
+  initial: 'STATE_A'
 }
 
-export default statechart(config, chart)
+export default statecharts(config, {
+  chartId: chart
+})
 `,
         },
       ]
     : [
         {
           code: `
-import { statechart } from 'overmind/config'
+import { statecharts } from 'overmind/config'
 import * as actions from './actions'
 import { state } from './state'
 
@@ -41,7 +40,9 @@ const chart = {
   initial: 'STATE_A'
 }
 
-export default statechart(config, chart)
+export default statecharts(config, {
+  chartId: chart
+})
 `,
         },
       ]

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

@@ -3,7 +3,7 @@ export default (ts) =>
     ? [
         {
           code: `
-import { Statechart, statechart } from 'overmind/config'
+import { Statechart, statecharts } from 'overmind/config'
 import * as actions from './actions'
 import { state } from './state'
 
@@ -12,57 +12,57 @@ const config = {
   state
 }
 
-enum NestedStates {
-  FOO = 'FOO',
-  BAR = 'BAR'
-}
-
-const nestedChart: Statechart<typeof config, NestedStates> = {
-  initial: NestedStates.FOO,
+const nestedChart: Statechart<typeof config, {
+  FOO: void
+  BAR: void
+}> = {
+  initial: 'FOO',
   states: {
-    [NestedStates.FOO]: {
+    FOO: {
       on: {
-        transitionToBar: NestedStates.BAR
+        transitionToBar: 'BAR'
       }
     },
-    [NestedStates.BAR]: {
+    BAR: {
       on: {
-        transitionToFoo: NestedStates.FOO 
+        transitionToFoo: 'FOO'
       }
     }
   }
 }
 
-enum States {
-  STATE_A = 'STATE_A',
-  STATEA_B = 'STATE_B'
-}
-
-const chart: Statechart<typeof config, States> = {
-  initial: States.STATE_A,
+const chart: Statechart<typeof config, {
+  STATE_A: {
+    nestedChartId: typeof nestedChart
+  }
+  STATE_B: void
+}> = {
+  initial: 'STATE_A',
   states: {
-    [States.STATE_A]: {
+    STATE_A: {
       on: {
-        transitionToStateB: States.STATE_B
+        transitionToStateB: 'STATE_B'
       },
-      chart: nestedChart
+      charts: { nestedChartId: nestedChart }
     },
-    [States.STATE_B]: {
+    STATE_B: {
       on: {
-        transitionToStateA: States.STATE_A
+        transitionToStateA: 'STATE_A'
       }
     }
   }
 }
 
-export default statechart(config, chart)
+export default statecharts(config, {
+  chartId: chart
+})
 `,
         },
       ]
     : [
         {
           code: `
-import { Statechart, statechart } from 'overmind/config'
+import { Statechart, statecharts } from 'overmind/config'
 import * as actions from './actions'
 import { state } from './state'
 
@@ -88,15 +88,14 @@ const nestedChart = {
   }
 }
 
-
 const chart = {
   initial: 'STATE_A',
   states: {
     STATE_A: {
       on: {
         transitionToStateB: 'STATE_B'
       },
-      chart: nestedChart
+      charts: { nestedChartId: nestedChart }
     },
     STATE_B: {
       on: {
@@ -106,7 +105,9 @@ const chart = {
   }
 }
 
-export default statechart(config, chart)
+export default statecharts(config, {
+  chartId: chart
+})
 `,
         },
       ]