From dbfdb883d8ec9716b6d7ebec72d1c9c9d6570ea9 Mon Sep 17 00:00:00 2001 From: Jonathan Werner Date: Sun, 12 Jun 2016 13:26:10 +0200 Subject: [PATCH] start working on Design documentation --- docs/Design.md | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+) create mode 100644 docs/Design.md diff --git a/docs/Design.md b/docs/Design.md new file mode 100644 index 0000000..8844f87 --- /dev/null +++ b/docs/Design.md @@ -0,0 +1,18 @@ +# Design +This gives you a high level overview how this library interacts with [React Router](https://github.com/reactjs/react-router) (RR) and [NavigationExperimental](https://github.com/ericvicenti/navigation-rfc) (NavExp) and explains the seperation of concerns. + +### `Router` +The `Router` that is exported by this library is basically a customized variant of the [RR Router](https://github.com/reactjs/react-router/blob/master/docs/API.md#router). We customize the [`history`](https://github.com/reactjs/react-router/blob/master/docs/API.md#history) prop by supplying a `nativeHistory` and the [`render`](https://github.com/reactjs/react-router/blob/master/docs/API.md#renderprops) prop by supplying a custom `RouterContext`. Other RR Router props such as [`createElement`](https://github.com/reactjs/react-router/blob/master/docs/API.md#createelementcomponent-props) are passed through. + +[`routes`/`children`](https://github.com/reactjs/react-router/blob/master/docs/API.md#routes) can be supplied to the `Router` via JSX (RR just has ``, this library has ``, ``, ``) or plain objects. Route definitions are like the regular RR ones with some additional props: `overlayComponent`, `reducer`, `transition` and a `routeType`. This libary's `` ``, `` just encapsulate default configurations for those additional props, plus helpful usage warnings. If you want to use plain objects, refer to the `defaultProps` that these components use. + +#### `nativeHistory` +A [history](https://github.com/ReactJSTraining/history) handles and encapsulates navigation state and notifies listeners when state has changed. A `history` instance implements some methods, for example `push(location)`, `replace(location)` and `go(n)`. Read up on these methods and the concept of a "location" [here](https://github.com/ReactJSTraining/history/blob/master/docs/GettingStarted.md#navigation). + +`nativeHistory` is an [enhanced](https://github.com/ReactJSTraining/history/blob/master/docs/Glossary.md?name=232#createhistoryenhancer) version of a memory history; it uses the enhancer `useNavState`. This enhancer adds the methods `create(Push|Pop|Replace|TransitionTo)` to the history's interface; the regular methods are exported prefixed with "base". The reason is that the actual methods (`push`, `pop`, ...) need additional information about the current navigation state or the current route configuration on which the operation should be performed - thus they are "created" in `RouteContext` (around L112). + +#### `RouterContext` +The `RouterContext` ([RR docs](https://github.com/reactjs/react-router/blob/master/docs/API.md#routercontext)) renders the component tree for a given router state and supplies the `router` object on the [context](https://facebook.github.io/react/docs/context.html). Supplying a custom one via the `Router`'s [`render`](https://github.com/reactjs/react-router/blob/master/docs/API.md#renderprops) property is the crucial integration point of React Router and this library. + +Whereas RR's `RouterContext` "just" renders the component tree given the props of `location`, `routes`, `params` and `components`, this library's `RouterContext` does more: **it holds state of navigation** (`navigationState`) **and the state of the navigation tree** (`navigationTree`) **in `this.state`.** When it receives new props ( = a navigation action has been performed), the new state and tree is calculated in [`componentWillReceiveProps`](https://facebook.github.io/react/docs/component-specs.html#updating-componentwillreceiveprops) (no additional render is performed when using `this.setState` in this hook). The next `navigationState` is calculated by **using the `reducer` defined for the given route**. (TODO: Question: i don't fully understand why it's taken from `nextState.reducer` here?) +