docs(#45): write feature documentation

factorial-io · Sep 29, 2020 · d820681 · d820681
1 parent 8322edf
commit d820681
Show file tree

Hide file tree

Showing 3 changed files with 78 additions and 5 deletions.
diff --git a/README.md b/README.md
@@ -312,6 +312,42 @@ await this.$nextTick();
  **/
 ```
 
+### Inspecting `done` and `undone` mutations
+
+Some vuex powered applications may require knowledge of the `done` and `undone` stacks, e.g. to preserve undo/redo functionality between page loads. The following configuration exposes the stacks by scaffoling a `undoRedoConfig` object in the store or module which uses the plugin:
+
+```js
+import Vuex from "vuex";
+import undoRedo, { scaffoldStore } from "undo-redo-vuex";
+
+// state, getters, actions & mutations ...
+
+// boolean flag to expose done and undone stacks
+const exposeUndoRedoConfig = true;
+
+const storeConfig = scaffoldStore({
+  state,
+  actions,
+  mutations
+}, exposeUndoRedoConfig); // boolean flag as the second optional param
+
+const store = new Vuex.Store({
+  ...storeConfig,
+  plugins: [
+    // Pass boolean flag as an named option
+    undoRedo({ exposeUndoRedoConfig })
+  ]
+});
+```
+
+To access the exposed `done` and `undone` stacks, e.g. in a component:
+
+```js
+const { done, undone } = this.$store.state;
+```
+
+This enhancement is described further in [issue #45](https://github.com/factorial-io/undo-redo-vuex/issues/45), with accompanying [unit tests](https://github.com/factorial-io/undo-redo-vuex/tree/master/tests/unit/test.expose-undo-redo-stacks.spec.ts).
+
 ## Testing and test scenarios
 
 Development tests are run using the [Jest](https://jestjs.io/) test runner. The `./tests/store` directory contains a basic Vuex store with a namespaced `list` module.

diff --git a/docs/api/README.md b/docs/api/README.md
@@ -6,11 +6,12 @@ The Undo-Redo plugin module
 
 **Returns**: <code>function</code> - plugin - the plugin function which accepts the store parameter
 
-| Param                   | Type                              | Description                                                         |
-| ----------------------- | --------------------------------- | ------------------------------------------------------------------- |
-| options                 | <code>Object</code>               |                                                                     |
-| options.namespace       | <code>String</code>               | The named vuex store module                                         |
-| options.ignoreMutations | <code>Array.&lt;String&gt;</code> | The list of store mutations (belonging to the module) to be ignored |
+| Param                        | Type                              | Description                                                         |
+| ---------------------------- | --------------------------------- | ------------------------------------------------------------------- |
+| options                      | <code>Object</code>               |                                                                     |
+| options.namespace            | <code>String</code>               | The named vuex store module                                         |
+| options.ignoreMutations      | <code>Array.&lt;String&gt;</code> | The list of store mutations (belonging to the module) to be ignored |
+| options.exposeUndoRedoConfig | <code>Boolean</code>              | (Optional) Flag to expose the `done` and `undone` mutation stacks   |
 
 ## undoRedo:redo()
 

diff --git a/docs/guide/usage.md b/docs/guide/usage.md
@@ -291,3 +291,39 @@ await this.$nextTick();
  * state: resetState (i.e. initial state + mutationA + mutationB)
  **/
 ```
+
+## Inspecting `done` and `undone` mutations
+
+Some vuex powered applications may require knowledge of the `done` and `undone` stacks, e.g. to preserve undo/redo functionality between page loads. The following configuration exposes the stacks by scaffoling a `undoRedoConfig` object in the store or module which uses the plugin:
+
+```js
+import Vuex from "vuex";
+import undoRedo, { scaffoldStore } from "undo-redo-vuex";
+
+// state, getters, actions & mutations ...
+
+// boolean flag to expose done and undone stacks
+const exposeUndoRedoConfig = true;
+
+const storeConfig = scaffoldStore({
+  state,
+  actions,
+  mutations
+}, exposeUndoRedoConfig); // boolean flag as the second optional param
+
+const store = new Vuex.Store({
+  ...storeConfig,
+  plugins: [
+    // Pass boolean flag as an named option
+    undoRedo({ exposeUndoRedoConfig })
+  ]
+});
+```
+
+To access the exposed `done` and `undone` stacks, e.g. in a component:
+
+```js
+const { done, undone } = this.$store.state;
+```
+
+This enhancement is described further in [issue #45](https://github.com/factorial-io/undo-redo-vuex/issues/45), with accompanying [unit tests](https://github.com/factorial-io/undo-redo-vuex/tree/master/tests/unit/test.expose-undo-redo-stacks.spec.ts).