Merge pull request #2647 from rackt/1.1-context.router

1.1 context.router

Author: mjackson

Diff for: .eslintrc

@@ -1,5 +1,8 @@
 {
   "extends": "rackt",
+  "globals": {
+    "__DEV__": true
+  },
   "rules": {
     "react/jsx-uses-react": 1,
     "react/jsx-no-undef": 2,

Diff for: CHANGES.md

@@ -1,5 +1,199 @@
 ## [HEAD]
 
+### Changes to context exports and Mixins
+
+Only an object named `router` is added to context. Accessing `context.history`, `context.location`, and `context.route` are all deprecated.
+
+Additionally, since `context` is now documented, all mixins are deprecated.
+
+#### Accessing location
+
+Access `location` from `this.props.location` of your route component. If
+you'd like to get it deeper in the tree, you can use whatever
+conventions your app has for getting props from high down low. One
+option is to put it context yourself:
+
+```js
+// v1.0.x
+const RouteComponent = React.createClass({
+  childContextTypes: {
+    location: React.PropTypes.object
+  },
+
+  getChildContext() {
+    return { location: this.props.location }
+  }
+})
+```
+
+Though you may want to hide that in a mixin or higher order component,
+it's up to you.
+
+#### Navigating
+
+In all cases where you once had a `history` for navigation, you now have a `router` to navigate instead.
+
+```js
+// v1.0.0
+history.pushState(state, path, query)
+history.replaceState(state, path, query)
+
+// v1.1.0
+router.push(path)
+router.push({ path, query, state }) // new "location descriptor"
+
+router.replace(path)
+router.replace({ path, query, state }) // new "location descriptor"
+```
+
+#### Navigating in route components
+
+```js
+// v1.0.0
+class RouteComponent extends React.Component {
+  someHandler() {
+    this.props.history.pushState(...)
+  }
+}
+
+// v1.1.0
+class RouteComponent extends React.Component {
+  someHandler() {
+    this.props.router.push(...)
+  }
+}
+```
+
+#### Navigating inside deeply nested components
+
+```js
+// v1.0.0
+const DeepComponent = React.createClass({
+  mixins: [ History ],
+
+  someHandler() {
+    this.history.pushState(...)
+  }
+}
+
+// v1.1.0
+// You have a couple options:
+// Use context directly (recommended)
+const DeepComponent = React.createClass({
+  contextTypes: {
+    router: object.isRequired
+  },
+
+  someHandler() {
+    this.context.router.push(...)
+  }
+}
+
+// create your own mixin:
+const RouterMixin = {
+  contextTypes: {
+    router: object.isRequired
+  },
+  componentWillMount() {
+    this.router = this.context.router
+  }
+}
+
+const DeepComponent = React.createClass({
+  mixins: [ RouterMixin ],
+  someHandler() {
+    this.history.pushState(...)
+  }
+}
+
+// use the singleton history you are using when the router was rendered,
+import { browserHistory } from 'react-router'
+
+const DeepComponent = React.createClass({
+  someHandler() {
+    browserHistory.push(...)
+  }
+}
+```
+
+#### Lifecycle Mixin with route components
+
+```js
+// v1.0.0
+const RouteComponent = React.createClass({
+  mixins: [ Lifecycle ],
+  routerWillLeave() {
+    // ...
+  }
+})
+
+// v1.1.0
+const RouteComponent = React.createClass({
+  componentDidMount() {
+    const { router, route } = this.props
+    router.addRouteLeaveHook(route, this.routerWillLeave)
+  }
+})
+
+// or make your own mixin, check it out in the next section
+```
+
+#### Lifecycle Mixin with deep, non-route components
+
+```js
+// v1.0.0
+const DeepComponent = React.createClass({
+  mixins: [ Lifecycle ],
+  routerWillLeave() {
+    // do stuff
+  }
+})
+
+// v1.1.0
+// you have a couple of options
+// first you can put the route on context in the route component
+const RouteComponent = React.createClass({
+  childContextTypes: {
+    route: object
+  },
+
+  getChildContext() {
+    return { route: this.props.route }
+  }
+})
+
+// and then access it on your deep component
+const DeepComponent = React.createClass({
+  contextTypes: {
+    route: object.isRequired,
+    router: objec.isRequired
+  },
+
+  componentDidMount() {
+    const { router, route } = this.context
+    router.addRouteLeaveHook(route, this.routerWillLeave)
+  }
+})
+
+// or make your own mixin that will work for both route components and
+// deep components alike (as long as your route component puts `route`
+// on context
+const Lifecycle = {
+  contextTypes: {
+    route: object.isRequired,
+    router: objec.isRequired
+  },
+
+  componentDidMount() {
+    const router = this.context.router
+    const route = this.props.route || this.context.route
+    router.addRouteLeaveHook(route, this.routerWillLeave)
+  }
+}
+```
+
+
+
 ## [v1.0.1]
 > Dec 5, 2015
 

Diff for: docs/API.md

@@ -17,9 +17,9 @@
   - [Named Components](#named-components)
 
 * [Mixins](#mixins)
-  - [Lifecycle](#lifecycle-mixin)
-  - [History](#history-mixin)
-  - [RouteContext](#routecontext-mixin)
+  - [Lifecycle](#lifecycle-mixin) (Deprecated)
+  - [History](#history-mixin) (Deprecated)
+  - [RouteContext](#routecontext-mixin) (Deprecated)
 
 * [Utilities](#utilities)
   * [useRoutes](#useroutescreatehistory)

Diff for: modules/History.js

@@ -1,3 +1,4 @@
+import warning from 'warning'
 import { history } from './PropTypes'
 
 /**
@@ -10,6 +11,7 @@ const History = {
   },
 
   componentWillMount() {
+    warning(false, 'the `History` mixin is deprecated, please access `context.router` with your own `contextTypes` or see https://github.com/rackt/react-router/blob/v1.1.0/CHANGES.md#v110 for more options')
     this.history = this.context.history
   }
 

Diff for: modules/Lifecycle.js

@@ -1,3 +1,4 @@
+import warning from 'warning'
 import React from 'react'
 import invariant from 'invariant'
 
@@ -34,6 +35,7 @@ const Lifecycle = {
   },
 
   componentDidMount() {
+    warning(false, 'the `Lifcycle` mixin is deprecated, please use `this.props.router.addRouteLeaveHook(this.props.route, hook)` from a route component, see https://github.com/rackt/react-router/blob/v1.1.0/CHANGES.md#v110 for more details.')
     invariant(
       this.routerWillLeave,
       'The Lifecycle mixin requires you to define a routerWillLeave method'

Diff for: modules/RouteContext.js

@@ -1,3 +1,4 @@
+import warning from 'warning'
 import React from 'react'
 
 const { object } = React.PropTypes
@@ -22,6 +23,10 @@ const RouteContext = {
     return {
       route: this.props.route
     }
+  },
+
+  componentWillMount() {
+    warning(false, 'the `RouteContext` mixin is deprecated, please export `this.props.route` from a route component yourself. See https://github.com/rackt/react-router/blob/v1.1.0/CHANGES.md#v110 for more details.')
   }
 
 }

Diff for: modules/RoutingContext.js

@@ -1,19 +1,37 @@
+import deprecateObjectProperties from './deprecateObjectProperties'
 import invariant from 'invariant'
 import React, { Component } from 'react'
 import { isReactChildren } from './RouteUtils'
 import getRouteParams from './getRouteParams'
 
 const { array, func, object } = React.PropTypes
 
-/**
- * A <RoutingContext> renders the component tree for a given router state
- * and sets the history object and the current location in context.
- */
 class RoutingContext extends Component {
 
   getChildContext() {
     const { history, location } = this.props
-    return { history, location }
+    const router = {
+      push(...args) {
+        history.push(...args)
+      },
+      replace(...args) {
+        history.replace(...args)
+      },
+      addRouteLeaveHook(...args) {
+        return history.listenBeforeLeavingRoute(...args)
+      },
+      isActive(...args) {
+        return history.isActive(...args)
+      }
+    }
+    const contextExport = { history, location, router }
+    if (__DEV__)
+      return deprecateObjectProperties(contextExport, {
+        history: '`context.history` is deprecated, please use context.router',
+        location: '`context.location` is deprecated, please use a route component\'s `props.location` instead. If this is a deeply nested component, please refer to the strategies described in https://github.com/rackt/react-router/blob/v1.1.0/CHANGES.md#v110'
+      })
+    else
+      return contextExport
   }
 
   createElement(component, props) {
@@ -94,7 +112,8 @@ RoutingContext.defaultProps = {
 
 RoutingContext.childContextTypes = {
   history: object.isRequired,
-  location: object.isRequired
+  location: object.isRequired,
+  router: object.isRequired
 }
 
 export default RoutingContext