Documentation for stable release 1.0

.github/ISSUE_TEMPLATE.md

@@ -0,0 +1,38 @@
+<!-- Source: https://github.com/stevemao/github-issue-templates/tree/master/conversational -->
+
+**Note: for support questions, please ask questions on the gitter chat**. This repository's issues are reserved for feature requests and bug reports. Visit the gitter chat [here](https://gitter.im/omnidan/redux-undo).
+
+* **I'm submitting a ...**
+  - [ ] bug report
+  - [ ] feature request
+  - [ ] support request => Please do not submit support request here, see note at the top of this template.
+
+* **What is the current behavior?**
+
+
+
+* **What is the expected/desired behavior?**
+
+
+
+* **If this is a feature request, what is the use case for changing the behavior?**
+
+
+
+* **If the current behavior is a bug, please provide the steps to reproduce and if possible a minimal demo of the problem via a gist or similar.**
+
+
+
+* **Please tell us about your environment:**
+
+  - Library version: 1.0.0
+  - Redux version: 4.0.0
+  - Browser: [all | Chrome XX | Firefox XX | IE XX | Safari XX | Edge XX]
+  - Language: [all | TypeScript X.X | ES6/7 | ES5]
+
+
+* **Other information**
+
+(e.g. detailed explanation, stacktraces, related issues, suggestions how to fix, links for us to have context, eg. stackoverflow, gitter, etc)
+
+

.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,31 @@
+<!-- Source: https://github.com/stevemao/github-issue-templates/tree/master/conversational -->
+
+* **Please check if the PR fulfills these requirements**
+- [ ] The commit message(s) are descriptive of the changes made
+- [ ] The PR contains changes that are focused and differs from other PRs
+- For bug fixes or features:
+  - [ ] Tests for the changes have been added where needed
+  - [ ] Docs have been added / updated
+
+
+* **What kind of change does this PR introduce?** (Bug fix, feature, docs update, ...)
+
+
+<!-- If this is a simple doc change, remove the following lines -->
+
+
+* **What is the current behavior?** (You can also link to an open issue here)
+
+
+
+* **What is the new behavior (if this is a feature change)?**
+
+
+
+* **Does this PR introduce a breaking change?** (What changes might users need to make in their application due to this PR?)
+
+
+
+* **Other information**:
+
+

README.md

@@ -8,18 +8,18 @@ _simple undo/redo functionality for redux state containers_
 
 **Protip:** Check out the [todos-with-undo example](https://github.com/omnidan/redux-undo/tree/master/examples/todos-with-undo) or the [redux-undo-boilerplate](https://github.com/omnidan/redux-undo-boilerplate) to quickly get started with `redux-undo`.
 
-**Switching from 0.x to 1.0 (beta):** Make sure to update your programs to the [latest History API](#history-api).
+**Switching from 0.x to 1.0:** Make sure to update your programs to the [latest History API](#history-api).
 
 **Help wanted:** We are looking for volunteers to maintain this project, if you are interested, feel free to contact me at [[email protected]](mailto:[email protected])
 
 ---
 
-**This README is about the new 1.0-beta branch of redux-undo, if you are using
+**This README is about the new 1.0 branch of redux-undo, if you are using
 or plan on using 0.6, check out [the `0.6` branch](https://github.com/omnidan/redux-undo/tree/0.6)**
 
 ---
 
-## Note on 1.0.0-beta7
+## Note on Imports
 
 If you use Redux Undo in CommonJS environment, **don’t forget to add `.default` to your import**.
 
@@ -45,7 +45,7 @@ var ReduxUndo = window.ReduxUndo.default;
 ## Installation
 
 ```
-npm install --save redux-undo@beta
+npm install --save redux-undo
 ```
 
 
@@ -89,7 +89,7 @@ A [configuration](#configuration) can be passed like this:
 ```js
 combineReducers({
   counter: undoable(counter, {
-    limit: 10 // set a limit for the history
+    limit: 10 // set a limit for the size of the history
   })
 })
 ```
@@ -152,6 +152,8 @@ Now you can get your current state like this: `state.present`
 
 And you can access all past states (e.g. to show a history) like this: `state.past`
 
+**Note:** Your reducer still receives the current state, a.k.a. `state.present`. Therefore, you would not have to update an existing reducer to add undo functionality.
+
 
 ## Undo/Redo Actions
 
@@ -174,7 +176,7 @@ store.dispatch(ActionCreators.jump(5)) // redo 5 steps
 store.dispatch(ActionCreators.jumpToPast(index)) // jump to requested index in the past[] array
 store.dispatch(ActionCreators.jumpToFuture(index)) // jump to requested index in the future[] array
 
-store.dispatch(ActionCreators.clearHistory()) // [beta only] Remove all items from past[] and future[] arrays
+store.dispatch(ActionCreators.clearHistory()) // Remove all items from past[] and future[] arrays
 ```
 
 
@@ -198,7 +200,7 @@ undoable(reducer, {
   jumpToPastType: ActionTypes.JUMP_TO_PAST, // define custom action type for this jumpToPast action
   jumpToFutureType: ActionTypes.JUMP_TO_FUTURE, // define custom action type for this jumpToFuture action
 
-  clearHistoryType: ActionTypes.CLEAR_HISTORY, // [beta only] define custom action type for this clearHistory action
+  clearHistoryType: ActionTypes.CLEAR_HISTORY, // define custom action type for this clearHistory action
   // you can also pass an array of strings to define several action types that would clear the history
   // beware: those actions will not be passed down to the wrapped reducers
 
@@ -403,6 +405,8 @@ Have a read of the [Implementing Undo History recipe](https://redux.js.org/recip
 
 If you have a question or just want to discuss something with other redux-undo users/maintainers, [chat with the community on gitter.im/omnidan/redux-undo](https://gitter.im/omnidan/redux-undo)
 
+Also, look at the documentation over at [redux-undo.js.org](https://redux-undo.js.org/).
+
 ## License
 
 MIT, see `LICENSE.md` for more information.

docs/FAQ.md

@@ -1,3 +1,145 @@
 # FAQ
 
-Work-in-progress - check back later :)
+### Table of Contents
+
+- [Where can I get help using `redux-undo`?](#where-can-I-get-help-using-redux-undo)
+- [Where can I find examples of how to use `redux-undo`?](#where-can-i-find-examples-of-how-to-use-redux-undo)
+- [How do I prevent cluttering up history with rapidly changing state?](#how-do-I-prevent-cluttering-up-history-with-rapidly-changing-state)
+- [Can I have multiple, separate undoable functions?](#can-i-have-multiple-separate-undoable-functions)
+- [Why are my actions not being filtered?](#why-are-my-actions-not-being-filtered)
+- [What is `_latestUnfiltered`? Can I remove it?](#what-is-_latestUnfiltered-can-i-remove-it)
+- [Why am I getting `Cannot find module 'redux-undo'`?](#why-am-i-getting-cannot-find-module-redux-undo)
+- [How do I set an initial state/history?](upgrading-to-1.0.md#initialstate)
+- [How do I upgrade from 0.X to 1.0?](upgrading-to-1.0.md)
+
+## Where can I get help using `redux-undo`?
+
+To get an understanding of the basics, read through the [README](/README.md) and checkout some [examples](#where-can-i-find-examples-of-how-to-use-redux-undo).
+
+To get help with a specific use case, see if there is already an example in these docs or the examples. If not, ask for help in the [gitter chat](https://gitter.im/omnidan/redux-undo)!
+
+If it seems you have found a bug or you are itching for a new feature, go ahead and submit it as an issue following the template provided. Please reserve Github issues for bugs and features **only**. Ask any other questions on the gitter chat and someone will probably be able to help you with your problem.
+
+## Where can I find examples of how to use `redux-undo`?
+
+Look at the `examples/` directory of the project folder. The `todos-with-undo/` is a good project to start messing with.
+
+```sh
+$ git clone https://github.com/omnidan/redux-undo.git
+$ cd redux-undo/examples/todos-with-undo
+$ npm install
+$ npm start
+```
+
+Just open http://localhost:3000 and you are good to go!
+
+## How do I prevent cluttering up history with rapidly changing state?
+
+The `throttled-drag/` project found the `examples/` directory gives a good demonstration of how to debounce undos (the filter is in `util/undoFilter.js`).
+
+This general question has different solutions depending on your exact problem. Let's say you have one or more rapidly dispatched actions, for example `MOVE_CURSOR` and `UPDATE_OBJECT_POS`, that ends with a lone action `PLACE_OBJECT`, and you only want to record the end state after `PLACE_OBJECT`. Then you can simply use a filter `excludeAction(['MOVE_CURSOR', 'UPDATE_OBJECT_POS'])`
+
+For more complex requirements, consider writing your own [custom filter](https://github.com/omnidan/redux-undo#custom-filters).
+
+## Can I have multiple, separate undoable functions?
+
+Yes you can! Simply wrap each reducer with its own `undoable()`.
+
+```js
+const rootReducer = combineReducers({
+  someData: undoable(dataReducer),
+  otherData: undoable(otherDataReducer)
+});
+```
+
+Do not forget to setup different undo/redo types to undo/redo each slice separately.
+
+```js
+someData: undoable(dataReducer, {
+  undoType: "DATA_UNDO",
+  redoType: "DATA_REDO"
+  // There is also jumpType, jumpToPastType, jumpToFutureType, clearHistoryType, and initTypes (which is an array of action types)
+});
+```
+
+If you wish to have a single conglomerate history that a user can undo one action at a time, you can wrap the root reducer with `undoable()`.
+
+```js
+const rootReducer = undoable(
+  combineReducers({
+    someData: dataReducer,
+    otherData: otherDataReducer
+  }),
+  {...options...}
+);
+```
+
+You probably need to use [custom filters](https://github.com/omnidan/redux-undo#custom-filters) and/or [`groupBy`](https://github.com/omnidan/redux-undo#grouping-actions) to undo/redo in reasonable chunks.
+
+## Why are my actions not being filtered?
+
+If you are trying to prevent actions from changing state, **that is not what `filter` is for**. The `filter` option only prevents state changes from becoming part of the history, i.e. the new state being pushed into `state.past`. If you need this functionality, check out [redux-ignore](https://github.com/omnidan/redux-ignore).
+
+On the other hand, here is how to use the helper functions:
+
+```js
+undoable(myReducer, {
+  filter: combineFilters(
+    // includeAction/excludeAction helpers take an array of action type strings
+    includeAction(["MY_ACTION", "ANOTHER_ACTION"]),
+    costumeFilter
+  )
+});
+```
+
+When writing a custom filter, return `true` for actions that you want to keep in history.
+
+```js
+function onlyEveryThird(action, newState, history) {
+  // Access the whole history object
+  let { past, present, future, limit } = history;
+
+  return newState.count % 3 === 0; // Only update history every third count
+}
+```
+
+## What is `_latestUnfiltered`? Can I remove it?
+
+### What is it?
+
+State wrapped by `undoable()` contains the field `_latestUnfiltered` alongside `past`, `present`, etc. This field is used to keep track of state that should be put in the history but cannot yet because the previous action(s) were filtered. It is basically a temporary variable between filtered actions.
+
+```js
+// This action is filtered, so present cannot be pushed into past right away
+_latestUnfiltered = present;
+present = newState;
+
+// With the next unfiltered action...
+past = [...past, _latestUnfiltered]; // Now we can add it
+```
+
+### Can I remove it?
+
+Short answer, no. It is an integral part of filtering actions from history and cannot be removed from the library. You can ignore it completely, but overriding/removing it may have unwanted consequences.
+
+While there is a tad more overhead handling actions in the reducer, it is necessary with the current setup. In the future, there might be optimization that makes this field less burdensome for users that do not use the filtering functionality.
+
+## Why am I getting `Cannot find module 'redux-undo'`?
+
+If you are using redux-undo in a CommonJS or UMD environment, you need to add `.default` to your imports.
+
+```js
+// CJS
+var undoable = require("redux-undo").default;
+
+// UMD
+var undoable = window.ReduxUndo.default;
+```
+
+ES6 imports should work without a hitch.
+
+```js
+import undoable from "redux-undo";
+```
+
+If this fixed your issue, you might also want to checkout how to [upgrade from 0.6 to 1.0](upgrading-to-1.0.md).

docs/README.md

@@ -1,4 +1,5 @@
 # Table of Contents
 
- * [Read Me](/README.md)
- * [FAQ](/docs/FAQ.md)
+- [Read Me](/README.md)
+- [FAQ](/docs/FAQ.md)
+- [Upgrading from 0.x to 1.0](/docs/upgrading-to-1.0.md)

docs/upgrading-to-1.0.md

@@ -0,0 +1,94 @@
+# Upgrading redux-undo from 0.x to 1.0
+
+## Imports
+
+CommonJS and UMD bundles now need a `.default` added to your imports.
+
+```js
+// CJS
+var undoable = require("redux-undo").default;
+
+// UMD
+var undoable = window.ReduxUndo.default;
+```
+
+ES6 imports should work as expected.
+
+```js
+import undoable from "redux-undo";
+```
+
+## `distinctState()` filter applied by default
+
+In 1.0 and greater, state is only added to history if it is different than the previous state (checked by object reference equality `===`). The `distinctState()` filter is now deprecated and removed as there is no need for it.
+
+## History API change in versions `< 0.4`
+
+In versions 0.3 and earlier, the history state was stored in the form.
+
+```js
+{
+  currentState: {...currentStateHere...},
+  history: {
+    past: [...pastStatesHere...],
+    present: {...currentStateHere...},
+    future: [...futureStatesHere...]
+  }
+}
+```
+
+In versions `0.4` and greater, the full history is exposed directly.
+
+```js
+{
+  past: [...pastStatesHere...],
+  present: {...currentStateHere...},
+  future: [...futureStatesHere...]
+}
+```
+
+## InitialState
+
+Before `1.0`, you would pass an `initialState` or `initialHistory` as a config option.
+
+```js
+undoable(myReducer, {
+  initialState: {
+    myState: "initial",
+    otherField: true
+  }
+  // or initialHistory with past, present, and future
+});
+```
+
+Now, these options are removed in favor of Redux's `preloadedState` parameter.
+
+```js
+const rootReducer = combineReducers({
+  myReducer: undoable(myReducer)
+});
+
+const store = createStore(rootReducer, {
+  myReducer: {
+    myState: "initial",
+    otherField: true
+  }
+});
+```
+
+When providing initial state, redux-undo will automatically detect whether or not it is a complete history (with `past`, `present`, `future`) or not. If it is not, it will automatically convert it to one.
+
+If you wish to provide an initial history, e.g. you want to prefill `past` to recover a previous session, you **must** provide the three fields for redux-undo to recognize it as a history object.
+
+```js
+const store = createStore(rootReducer, {
+  myReducer: {
+    past: ["from", "previous", "session"],
+    present: "now"
+    // `future` not provided!! Redux-undo will not recognize this as a history
+    // and will instead set present = {past: [...], present: 'now'}
+
+    // To fix, pass `future: []`
+  }
+});
+```