docs: further extensive docs changes

docs/src/.vuepress/config.js

@@ -19,52 +19,47 @@ module.exports = {
         navbar: [
             {
                 text: 'Guide',
-                link: '/guide/'
+                link: '/guide/introduction/about.html',
+                activeMatch: '^/guide/'
             },
             {
                 text: 'Extensibility',
-                link: '/extensibility/'
+                link: '/extensibility/',
+                activeMatch: '^/extensibility/'
             },
             {
                 text: 'API Reference',
-                link: '/api-reference/'
+                link: '/api-reference/global.html',
+                activeMatch: '^/api-reference/'
             }
         ],
         sidebar: {
             '/guide/': [
                 {
                     text: 'Introduction',
                     children: [
-                        '/guide/introduction/features.html',
+                        '/guide/introduction/about.html',
                         '/guide/introduction/getting-started.html',
                     ]
                 },
                 {
                     text: 'Core Concepts',
                     children: [
-                        '/guide/core-concepts/architecture.html',
+                        '/guide/core-concepts/stores.html',
                         '/guide/core-concepts/state.html',
                         '/guide/core-concepts/getters.html',
                         '/guide/core-concepts/mutations.html',
                         '/guide/core-concepts/actions.html',
                         '/guide/core-concepts/triggers.html',
                     ]
                 },
-                {
-                    text: 'Developer Experience',
-                    children: [
-                        '/guide/dx/typescript-support.html',
-                        '/guide/dx/devtools-integration.html',
-                    ]
-                },
                 {
                     text: 'Support',
                     children: [
                         '/guide/support/tips.html',
                         '/guide/support/FAQ.html'
                     ]
                 },
-                '/guide/server-side-rendering.html',
             ],
             '/extensibility/': [
                 {
@@ -92,7 +87,7 @@ module.exports = {
                 {
                     text: 'API Reference',
                     children: [
-                        '/api-reference/README.html',
+                        '/api-reference/global.html',
                         '/api-reference/store.html',
                         '/api-reference/types.html',
                     ]

docs/src/README.md

@@ -10,14 +10,14 @@ actions:
   link: https://andrewcourtice.github.io/harlem
   type: Secondary
 features:
-- title: Simple
+- title: Simple 
   details: Harlem has a simple functional API for creating, reading and mutating state. At it's heart, Harlem just uses Vue reactive objects and computeds which means if you know how to use Vue, you'll know how to use Harlem.
 - title: Unopinionated
   details: Harlem doesn't impose any standards or conventions on your codebase. Because of it's simple functional API you can structure your code anyway you want and Harlem will just work.
 - title: Immutable
   details: All state provided from a Harlem store is immutable by default. The only write access to state is through mutations. This ensures all updates to your store are tracable, thereby reducing the amount of bugs produced by code unpredictably mutating state.
 - title: Lightweight
-  details: Harlem weighs in at around 1.5KB (minified & gzipped) which makes it the perfect solution for codebases of all sizes. Harlem is also designed to be tree-shakable - unused stores, getters, or mutations will be removed from your code at build time (provided you are using a build tool that supports tree-shaking). It's also worth noting that Harlem has zero dependencies (apart from Vue obviously).
+  details: Harlem weighs in at around 1.5KB (minified) which makes it the perfect solution for codebases of all sizes. Harlem is also designed to be tree-shakable - unused stores, getters, or mutations will be removed from your code at build time (provided you are using a build tool that supports tree-shaking). It's also worth noting that Harlem has zero dependencies (apart from Vue obviously).
 - title: Extensible
   details: Harlem is architectured with extensibility in mind so you can extend it any way you want through extensions and plugins. Some of the official plugins and extensions include Vue devtools integration, local/session storage sync, snapshots, history (undo/redo) and more.
 - title: Great DX

docs/src/extensibility/extensions/action.md

@@ -29,7 +29,7 @@ yarn add @harlem/extension-action
 
 To get started simply register this extension with the store you wish to extend.
 
-```typescript
+```typescript{16-20,23}
 import actionExtension from '@harlem/extension-action';
 
 import {

docs/src/extensibility/extensions/history.md

@@ -25,7 +25,7 @@ yarn add @harlem/extension-history
 
 To get started simply register this extension with the store you wish to extend.
 
-```typescript
+```typescript{16-17,20-28}
 import historyExtension from '@harlem/extension-history';
 
 import {

docs/src/extensibility/extensions/introduction.md

@@ -4,6 +4,7 @@ Extensions are per-store additions to Harlem's core functionaility. Extensions a
 
 Feel free to choose from some of the official extensions or write your own. See the [extensions documentation](extensions) from more information on the official set of extensions or how to author your own plugin.
 
+
 ## Official Extensions
 
 Here is a list of officially supported Harlem plugins. These plugins are not designed to suit every use-case but instead add basic functionality for common use-cases.
@@ -21,4 +22,57 @@ If you require functionality to suit a specific use-case you can write your own
 
 If you feel that there is a piece of common functionality that should be included as an official Harlem extension please open an issue providing a description of the extension, the intended API and, if possible, a working example in a codesandbox.
 
-## Writing your own extension
+
+## Writing your own extension
+
+Writing an extension for Harlem is very straightforward. An extension is simply a `function` that returns an `object` to be merged with the store instance. 
+
+### Basic example
+
+Let's take a look at a simple example:
+
+```typescript
+import type {
+    InternalStore,
+    BaseState,
+} from '@harlem/core';
+
+interface Options {
+    option1: string;
+    option2: number;
+}
+
+export default function resetExtension<TState extends BaseState>(options?: Options) {
+
+    return (store: InternalStore<TState>) => {
+
+        function doSomethingWithTheStore(input: string) {
+            // do something
+        }
+
+        return {
+            doSomethingWithTheStore
+        };
+    };
+}
+```
+
+A store instance would then look like this:
+
+```typescript{10}
+const STATE = {
+    firstName: 'John',
+    lastName: 'Smith'
+};
+
+const {
+    state,
+    getter,
+    mutation,
+    doSomethingWithTheStore
+} = createStore('user', STATE);
+```
+
+
+### Publishing your extension
+To make it easy for users to find Harlem extensions it is recommended that you name your extension with a `harlem-extension-` prefix if publishing to the NPM registry.

docs/src/extensibility/extensions/lazy.md

@@ -25,7 +25,7 @@ yarn add @harlem/extension-lazy
 
 To get started simply register this extension with the store you wish to extend.
 
-```typescript
+```typescript{16,19}
 import lazyExtension from '@harlem/extension-lazy';
 
 import {

docs/src/extensibility/extensions/reset.md

@@ -25,7 +25,7 @@ yarn add @harlem/extension-reset
 
 To get started simply register this extension with the store you wish to extend.
 
-```typescript
+```typescript{16,19}
 import resetExtension from '@harlem/extension-reset';
 
 import {

docs/src/extensibility/extensions/snapshot.md

@@ -25,7 +25,7 @@ yarn add @harlem/extension-snapshot
 
 To get started simply register this extension with the store you wish to extend.
 
-```typescript
+```typescript{16,19}
 import snapshotExtension from '@harlem/extension-snapshot';
 
 import {

docs/src/extensibility/extensions/storage.md

@@ -25,7 +25,7 @@ yarn add @harlem/extension-storage
 
 To get started simply register this extension with the store you wish to extend.
 
-```typescript
+```typescript{16-18,21-28}
 import storageExtension from '@harlem/extension-storage';
 
 import {
@@ -41,7 +41,9 @@ const {
     state,
     getter,
     mutation,
-    storage
+    startStorageSync,
+    stopStorageSync,
+    clearStorage
 } = createStore('example', STATE, {
     extensions: [
         storageExtension({
@@ -56,7 +58,7 @@ const {
 });
 ```
 
-The storage extension adds 2 methods to the store instance: `startStorageSync` and `stopStorageSync`.
+The storage extension adds 3 methods to the store instance: `startStorageSync`, `stopStorageSync` and `clearStorage`.
 
 
 ## Usage
@@ -74,6 +76,10 @@ The storage extension method accepts an options object with the following proper
 The `startStorageSync` and `stopStorageSync` methods can be used to start or stop sync behaviour.
 
 
+### Clearing storage
+Use the `clearStorage` method to clear all stored data relating to this store.
+
+
 ## Considerations
 Please keep the following points in mind when using this extension:
 

docs/src/extensibility/plugins/introduction.md

@@ -35,7 +35,7 @@ export default {
 } as HarlemPlugin;
 ```
 
-**Note:** If you're using Typescript it is recommended that you add `@harlem/core` as a devDependency and export your plugin object cast as a `HarlemPlugin` (as shown in the example above). This will give you full typing support when authoring your plugin.
+**Note:** If you're using TypeScript it is recommended that you add `@harlem/core` as a devDependency and export your plugin object cast as a `HarlemPlugin` (as shown in the example above). This will give you full typing support when authoring your plugin.
 
 As you can see the plugin is similar to Vue in that it has a single `install` method. Note however that Harlem plugins require a name field to identify your plugin and the install method has `eventEmitter` and `stores` args as opposed to `options`. 
 

docs/src/guide/README.md

@@ -1 +1,23 @@
-# Harlem
+# Harlem
+
+## Foundations
+
+### Simple
+Harlem has a simple functional API for creating, reading and mutating state. At it's heart, Harlem just uses Vue reactive objects and computeds which means if you know how to use Vue, you'll know how to use Harlem.
+
+### Unopinionated
+Harlem doesn't impose any standards or conventions on your codebase. Because of it's simple functional API you can structure your code anyway you want and Harlem will just work.
+
+### Immutable
+All state provided from a Harlem store is immutable by default. The only write access to state is through mutations. This ensures all updates to your store are tracable, thereby reducing the amount of bugs produced by code unpredictably mutating state.
+
+### Lightweight
+Harlem core weighs in at around 1.5KB (minified & gzipped) which makes it the perfect solution for codebases of all sizes. It is also designed to be tree-shakable - unused stores, getters, or mutations will be removed from your code at build time (provided you are using a build tool that supports tree-shaking). 
+
+It's also worth noting that Harlem has **zero** dependencies.
+
+### Extensible
+Harlem is architectured with extensibility in mind so you can extend it any way you want through [plugins](#plugins) and [extensions](#extensions). Some of the official plugins and extensions include Vue devtools integration, local/session storage sync, snapshots, history (undo/redo) and more.
+
+### Great DX
+Harlem has a great developer experience. It's built using TypeScript so all of your state, getters, and mutations are strongly typed. Harlem also has devtools integration so you can explore your stores and see mutation events on the timeline in realtime.

docs/src/guide/core-concepts/getters.md

@@ -26,7 +26,7 @@ export const fullName = getter('fullname', state => {
 The getter function returns a Vue computed property that can now be used in your components or even other getters.
 
 
-## Usage in Components
+## Usage in components
 
 ```html
 <template>
@@ -46,6 +46,6 @@ import {
 </script>
 ```
 
-## See Also
+## See also
 
 [Getter](/api-reference/store.html#getter) API Reference

docs/src/guide/core-concepts/mutations.md

@@ -18,7 +18,7 @@ const {
 
 // This mutation takes a string payload and updates the name field
 export const setName = mutation<string>('setName', (state, payload) => {
-    state.firstName = payload;
+    state.name = payload;
 });
 
 // This mutation takes a string payload, adds a trait to the list and returns it's id
@@ -32,18 +32,15 @@ export const addTrait = mutation<string, symbol>('addTrait', (state, payload) =>
 
     return traitId;
 });
-
-/*
-Usage
-
-setName('Jane Smith');
-
-const traitId = addTrait('funny');
-*/
 ```
 
+::: warning
+It is not recommended to call other mutations within the body of a mutation. This could cause unintended side-effects. Harlem has built-in protection to prevent infinite circular mutation calls from occurring.
+:::
+
+## Usage in components
 
-## Usage in Components
+To use a mutation just import it like any other function and call it with the expected payload type (if specified).
 
 ```html
 <template>
@@ -70,6 +67,6 @@ const name = computed({
 </script>
 ```
 
-## See Also
+## See also
 
 [Mutation](/api-reference/store.html#mutation) API Reference

docs/src/guide/core-concepts/stores.md

@@ -0,0 +1,47 @@
+# Stores
+
+In a nutshell a store is just a mechanism for storing, retrieving and mutating related data. 
+
+Harlem, much like Vuex, follows a Redux-like state management pattern. Harlem's functionality can be divided into 3 main concepts:
+- **State** - The single source of truth for your data (read-only). See [State](/guide/core-concepts/state.html).
+- **Getters** - Computed side-effects of mutations to state (read-only). See [Getters](/guide/core-concepts/getters.html).
+- **Mutations** - The means by which state is changed (read/write). See [Mutations](/guide/core-concepts/mutations.html)
+
+**Actions** (available via the [Action extension](/extensibility/extensions/action.html)) are also a major part of a modern state management solution. Harlem's action implementation can be described as cancellable async methods for batching mutations, api requests etc (async read/write). Refer to the [FAQ section](/guide/support/FAQ.html#why-aren-t-actions-included-by-default) to see why actions aren't included in the core package by default.
+
+Where Harlem differs from Vuex is that as opposed to having one monolithic state tree, Harlem uses the concept of stores to create logical boundaries between disparate data.
+
+Instead of defining store functions (getters, mutations etc) on a single object Harlem uses a more functional approach which allows you to structure your codebase any way you like. The added benefit to this approach is that your stores can be tree-shaken not just at store level but right down to a getter/mutation level.
+
+
+## Defining a store
+
+To define a store all you need is a name, some initial state.
+
+```typescript
+import {
+    createStore
+} from '@harlem/core';
+
+export default createStore('user', {
+    firstName: 'John',
+    lastName: 'Smith'
+});
+```
+
+## Specifying options
+
+You can specifiy a range of options when creating a store. This is most useful for adding any extensions you wish to include with this store. For the complete set of options available refer to the [API documentation](/api-reference/global.html#createstore).
+
+```typescript
+import {
+    createStore
+} from '@harlem/core';
+
+export default createStore('user', STATE, {
+    allowOverwrite: true,
+    extensions: [
+        actionExtension()
+    ]
+});
+```