From 6bd6ef208b302879eb38018d4192a054f40c1c8b Mon Sep 17 00:00:00 2001 From: Daniel Rodgers-Pryor Date: Wed, 5 Aug 2015 13:04:25 +1000 Subject: [PATCH] ReactCSSTransitionGroup timeouts As discussed in issue 1326 (https://github.com/facebook/react/issues/1326) transitionend events are unreliable; they may not fire because the element is no longer painted, the browser tab is no longer focused or for a range of other reasons. This is particularly harmful during leave transitions since the leaving element will be permanently stuck in the DOM (and possibly visible). The ReactCSSTransitionGroup now requires timeouts to be passed in explicitly for each type of animation. Omitting the timeout duration for a transition now triggers a PropTypes warning with a link to the updated documentation. --- docs/docs/10.1-animation.md | 16 +++-- .../transitions/ReactCSSTransitionGroup.js | 32 ++++++++++ .../ReactCSSTransitionGroupChild.js | 59 +++++++++---------- .../__tests__/ReactCSSTransitionGroup-test.js | 41 ++++++++++--- 4 files changed, 101 insertions(+), 47 deletions(-) diff --git a/docs/docs/10.1-animation.md b/docs/docs/10.1-animation.md index 0cb11b3a9a..9fba2d3592 100644 --- a/docs/docs/10.1-animation.md +++ b/docs/docs/10.1-animation.md @@ -44,7 +44,7 @@ var TodoList = React.createClass({ return (
- + {items}
@@ -67,23 +67,21 @@ You can use these classes to trigger a CSS animation or transition. For example, .example-enter.example-enter-active { opacity: 1; - transition: opacity .5s ease-in; + transition: opacity 500ms ease-in; } -``` -You'll notice that when you try to remove an item `ReactCSSTransitionGroup` keeps it in the DOM. If you're using an unminified build of React with add-ons you'll see a warning that React was expecting an animation or transition to occur. That's because `ReactCSSTransitionGroup` keeps your DOM elements on the page until the animation completes. Try adding this CSS: - -```css .example-leave { opacity: 1; } .example-leave.example-leave-active { opacity: 0.01; - transition: opacity .5s ease-in; + transition: opacity 300ms ease-in; } ``` +You'll notice that animation durations need to be specified in both the CSS and the render method; this tells React when to remove the animation classes from the element and -- if it's leaving -- when to remove the element from the DOM. + ### Animate Initial Mounting `ReactCSSTransitionGroup` provides the optional prop `transitionAppear`, to add an extra transition phase at the initial mount of the component. There is generally no transition phase at the initial mount as the default value of `transitionAppear` is `false`. The following is an example which passes the prop `transitionAppear` with the value `true`. @@ -91,7 +89,7 @@ You'll notice that when you try to remove an item `ReactCSSTransitionGroup` keep ```javascript{3-5} render: function() { return ( - +

Fading at Initial Mount

); @@ -184,7 +182,7 @@ var ImageCarousel = React.createClass({ render: function() { return (
- +
diff --git a/src/addons/transitions/ReactCSSTransitionGroup.js b/src/addons/transitions/ReactCSSTransitionGroup.js index 7c478e8acd..0e012383e3 100644 --- a/src/addons/transitions/ReactCSSTransitionGroup.js +++ b/src/addons/transitions/ReactCSSTransitionGroup.js @@ -23,6 +23,31 @@ var ReactCSSTransitionGroupChild = React.createFactory( require('ReactCSSTransitionGroupChild') ); +function createTransitionTimeoutPropValidator(transitionType) { + var timeoutPropName = 'transition' + transitionType + 'Timeout'; + var enabledPropName = 'transition' + transitionType; + + return function(props) { + // If the transition is enabled + if (props[enabledPropName]) { + // If no timeout duration is provided + if (!props[timeoutPropName]) { + return new Error( + timeoutPropName + ' wasn\'t supplied to ReactCSSTransitionGroup: ' + + 'this can cause unreliable animations and won\'t be supported in ' + + 'a future version of React. See ' + + 'https://fb.me/react-animation-transition-group-timeout for more ' + + 'information.' + ); + + // If the duration isn't a number + } else if (typeof props[timeoutPropName] !== 'number') { + return new Error(timeoutPropName + ' must be a number (in milliseconds)'); + } + } + }; +} + var ReactCSSTransitionGroup = React.createClass({ displayName: 'ReactCSSTransitionGroup', @@ -43,9 +68,13 @@ var ReactCSSTransitionGroup = React.createClass({ appearActive: React.PropTypes.string, }), ]).isRequired, + transitionAppear: React.PropTypes.bool, transitionEnter: React.PropTypes.bool, transitionLeave: React.PropTypes.bool, + transitionAppearTimeout: createTransitionTimeoutPropValidator('Appear'), + transitionEnterTimeout: createTransitionTimeoutPropValidator('Enter'), + transitionLeaveTimeout: createTransitionTimeoutPropValidator('Leave'), }, getDefaultProps: function() { @@ -66,6 +95,9 @@ var ReactCSSTransitionGroup = React.createClass({ appear: this.props.transitionAppear, enter: this.props.transitionEnter, leave: this.props.transitionLeave, + appearTimeout: this.props.transitionAppearTimeout, + enterTimeout: this.props.transitionEnterTimeout, + leaveTimeout: this.props.transitionLeaveTimeout, }, child ); diff --git a/src/addons/transitions/ReactCSSTransitionGroupChild.js b/src/addons/transitions/ReactCSSTransitionGroupChild.js index 286a979b0e..4bbf83fa5e 100644 --- a/src/addons/transitions/ReactCSSTransitionGroupChild.js +++ b/src/addons/transitions/ReactCSSTransitionGroupChild.js @@ -19,35 +19,31 @@ var CSSCore = require('CSSCore'); var ReactTransitionEvents = require('ReactTransitionEvents'); var onlyChild = require('onlyChild'); -var warning = require('warning'); // We don't remove the element from the DOM until we receive an animationend or // transitionend event. If the user screws up and forgets to add an animation // their node will be stuck in the DOM forever, so we detect if an animation // does not start and if it doesn't, we just call the end listener immediately. var TICK = 17; -var NO_EVENT_TIMEOUT = 5000; - -var noEventListener = null; - - -if (__DEV__) { - noEventListener = function() { - warning( - false, - 'transition(): tried to perform an animation without ' + - 'an animationend or transitionend event after timeout (' + - '%sms). You should either disable this ' + - 'transition in JS or add a CSS animation/transition.', - NO_EVENT_TIMEOUT - ); - }; -} var ReactCSSTransitionGroupChild = React.createClass({ displayName: 'ReactCSSTransitionGroupChild', - transition: function(animationType, finishCallback) { + propTypes: { + name: React.PropTypes.string.isRequired, + + // Once we require timeouts to be specified, we can remove the + // boolean flags (appear etc.) and just accept a number + // or a bool for the timeout flags (appearTimeout etc.) + appear: React.PropTypes.bool, + enter: React.PropTypes.bool, + leave: React.PropTypes.bool, + appearTimeout: React.PropTypes.number, + enterTimeout: React.PropTypes.number, + leaveTimeout: React.PropTypes.number, + }, + + transition: function(animationType, finishCallback, userSpecifiedDelay) { var node = ReactDOM.findDOMNode(this); if (!node) { @@ -59,16 +55,14 @@ var ReactCSSTransitionGroupChild = React.createClass({ var className = this.props.name[animationType] || this.props.name + '-' + animationType; var activeClassName = this.props.name[animationType + 'Active'] || className + '-active'; - - var noEventTimeout = null; + var timeout = null; var endListener = function(e) { if (e && e.target !== node) { return; } - if (__DEV__) { - clearTimeout(noEventTimeout); - } + + clearTimeout(timeout); CSSCore.removeClass(node, className); CSSCore.removeClass(node, activeClassName); @@ -82,15 +76,18 @@ var ReactCSSTransitionGroupChild = React.createClass({ } }; - ReactTransitionEvents.addEndEventListener(node, endListener); - CSSCore.addClass(node, className); // Need to do this to actually trigger a transition. this.queueClass(activeClassName); - if (__DEV__) { - noEventTimeout = setTimeout(noEventListener, NO_EVENT_TIMEOUT); + // If the user specified a timeout delay. + if (userSpecifiedDelay) { + // Clean-up the animation after the specified delay + timeout = setTimeout(endListener, userSpecifiedDelay); + } else { + // DEPRECATED: this listener will be removed in a future version of react + ReactTransitionEvents.addEndEventListener(node, endListener); } }, @@ -124,7 +121,7 @@ var ReactCSSTransitionGroupChild = React.createClass({ componentWillAppear: function(done) { if (this.props.appear) { - this.transition('appear', done); + this.transition('appear', done, this.props.appearTimeout); } else { done(); } @@ -132,7 +129,7 @@ var ReactCSSTransitionGroupChild = React.createClass({ componentWillEnter: function(done) { if (this.props.enter) { - this.transition('enter', done); + this.transition('enter', done, this.props.enterTimeout); } else { done(); } @@ -140,7 +137,7 @@ var ReactCSSTransitionGroupChild = React.createClass({ componentWillLeave: function(done) { if (this.props.leave) { - this.transition('leave', done); + this.transition('leave', done, this.props.leaveTimeout); } else { done(); } diff --git a/src/addons/transitions/__tests__/ReactCSSTransitionGroup-test.js b/src/addons/transitions/__tests__/ReactCSSTransitionGroup-test.js index a6b11d67af..f2898e2fe4 100644 --- a/src/addons/transitions/__tests__/ReactCSSTransitionGroup-test.js +++ b/src/addons/transitions/__tests__/ReactCSSTransitionGroup-test.js @@ -29,9 +29,29 @@ describe('ReactCSSTransitionGroup', function() { spyOn(console, 'error'); }); - it('should warn after time with no transitionend', function() { + it('should warn if timeouts aren\'t specified', function() { + ReactDOM.render( + + + , + container + ); + + // Warning about the missing transitionLeaveTimeout prop + expect(console.error.argsForCall.length).toBe(1); + }); + + it('should clean-up silently after the timeout elapses', function() { var a = ReactDOM.render( - + , container @@ -41,7 +61,11 @@ describe('ReactCSSTransitionGroup', function() { setTimeout.mock.calls.length = 0; ReactDOM.render( - + , container @@ -53,14 +77,18 @@ describe('ReactCSSTransitionGroup', function() { // For some reason jst is adding extra setTimeout()s and grunt test isn't, // so we need to do this disgusting hack. for (var i = 0; i < setTimeout.mock.calls.length; i++) { - if (setTimeout.mock.calls[i][1] === 5000) { + if (setTimeout.mock.calls[i][1] === 200) { setTimeout.mock.calls[i][0](); break; } } - expect(ReactDOM.findDOMNode(a).childNodes.length).toBe(2); - expect(console.error.argsForCall.length).toBe(1); + // No warnings + expect(console.error.argsForCall.length).toBe(0); + + // The leaving child has been removed + expect(ReactDOM.findDOMNode(a).childNodes.length).toBe(1); + expect(ReactDOM.findDOMNode(a).childNodes[0].id).toBe('two'); }); it('should keep both sets of DOM nodes around', function() { @@ -170,5 +198,4 @@ describe('ReactCSSTransitionGroup', function() { expect(ReactDOM.findDOMNode(a).childNodes.length).toBe(1); expect(ReactDOM.findDOMNode(a).childNodes[0].id).toBe('one'); }); - });