[added] preserveScrollPosition Route/Routes props

closes #121

Author: ryanflorence

docs/api/components/Route.md

@@ -23,6 +23,12 @@ inherit the path of their parent.
 
 The component to be rendered when the route is active.
 
+### `preserveScrollPosition`
+
+If `true`, the router will not scroll the window up when the route is
+transitioned to. Defaults to `false`. Ignored if the parent `<Routes/>`
+has been set to `true`.
+
 ### `children`
 
 Routes can be nested. When a child route matches, the parent route's

docs/api/components/Routes.md

@@ -17,8 +17,15 @@ works without a server, if you use `history` your server will need to
 support it.
 
 For browsers that don't support the HTML5 history API the router will
-fall back to `window.location` if you choose `history`. This way all
-users get the same urls and can share them.
+fall back to `window.location` if you choose `history`, in other words,
+the router will simply cause a full page reload. This way all users get
+the same urls and can share them.
+
+### `preserveScrollPosition`
+
+If `true`, the router will not scroll the window up globally when any
+route is transitioned to. Defaults to `false`. When `false`, the
+`<Route/>` gets to decide whether or not to scroll on transition.
 
 Example
 -------

modules/components/Route.js

@@ -72,10 +72,17 @@ var Route = React.createClass({
 
   },
 
+  getDefaultProps: function() {
+    return {
+      preserveScrollPosition: false
+    };
+  },
+
   propTypes: {
     handler: React.PropTypes.any.isRequired,
     path: React.PropTypes.string,
-    name: React.PropTypes.string
+    name: React.PropTypes.string,
+    preserveScrollPosition: React.PropTypes.bool
   },
 
   render: function () {

modules/components/Routes.js

@@ -54,11 +54,13 @@ var Routes = React.createClass({
 
   propTypes: {
     location: React.PropTypes.oneOf([ 'hash', 'history' ]).isRequired,
+    preserveScrollPosition: React.PropTypes.bool
   },
 
   getDefaultProps: function () {
     return {
-      location: 'hash'
+      location: 'hash',
+      preserveScrollPosition: false
     };
   },
 
@@ -339,6 +341,8 @@ function syncWithTransition(routes, transition) {
         })
       };
 
+      // TODO: add functional test
+      maybeScrollWindow(routes, toMatches[toMatches.length - 1]);
       routes.setState(state);
 
       return state;
@@ -436,4 +440,14 @@ function reversedArray(array) {
   return array.slice(0).reverse();
 }
 
+function maybeScrollWindow(routes, match) {
+  if (routes.props.preserveScrollPosition)
+    return;
+
+  if (!match || match.route.props.preserveScrollPosition)
+    return;
+
+  window.scrollTo(0, 0);
+}
+
 module.exports = Routes;