UIP-2751 Transition in/out-specific config, test attributes

lib/src/component/abstract_transition.dart

@@ -19,6 +19,7 @@ import 'dart:html';
 
 import 'package:meta/meta.dart';
 import 'package:over_react/over_react.dart';
+import 'package:over_react/component_base.dart' as component_base;
 
 @AbstractProps()
 abstract class AbstractTransitionProps extends UiProps with TransitionPropsMixin {}
@@ -27,7 +28,7 @@ abstract class AbstractTransitionProps extends UiProps with TransitionPropsMixin
 abstract class AbstractTransitionState extends UiState {
   /// The current phase of transition the [AbstractTransitionComponent] is in.
   ///
-  /// Default:  [AbstractTransitionComponent.initiallyShown] ? [TransitionState.SHOWN] : [TransitionState.HIDDEN]
+  /// Default:  [AbstractTransitionComponent.initiallyShown] ? [TransitionPhase.SHOWN] : [TransitionPhase.HIDDEN]
   TransitionPhase transitionPhase;
 }
 
@@ -81,6 +82,18 @@ abstract class AbstractTransitionState extends UiState {
 abstract class AbstractTransitionComponent<T extends AbstractTransitionProps,
                                            S extends AbstractTransitionState>
   extends UiStatefulComponent<T, S> {
+  /// The DOM attribute used to indicate the current transition phase,
+  /// added in test mode in [getTransitionTestAttributes].
+  ///
+  /// Possible values:
+  ///
+  /// - `pre-showing`
+  /// - `showing`
+  /// - `shown`
+  /// - `hiding`
+  /// - `hidden`
+  static const String transitionPhaseTestAttr = 'data-transition-phase';
+
   @override
   get consumedProps => const [
     const $Props(AbstractTransitionProps),
@@ -106,9 +119,25 @@ abstract class AbstractTransitionComponent<T extends AbstractTransitionProps,
   /// Returns the DOM node that will transition.
   Element getTransitionDomNode();
 
-  /// Whether the Element returned by [getTransitionDomNode] will have a transition event.
+  /// Whether transitions are enabled for this component.
   bool get hasTransition => true;
 
+  /// Whether the Element returned by [getTransitionDomNode] will have a transition event when showing.
+  bool get hasTransitionIn => hasTransition && transitionInCount > 0;
+
+  /// Whether the Element returned by [getTransitionDomNode] will have a transition event when hiding.
+  bool get hasTransitionOut => hasTransition && transitionOutCount > 0;
+
+  /// The number of `transitionend` events that occur when the transition node is shown.
+  ///
+  /// Defaults to `1` to match previous behavior in the case where `props.transitionCount` is `null`.
+  int get transitionInCount => props.transitionInCount ?? props.transitionCount ?? 1;
+
+  /// The number of `transitionend` events that occur when the transition node is hidden.
+  ///
+  /// Defaults to `1` to match previous behavior in the case where `props.transitionCount` is `null`.
+  int get transitionOutCount => props.transitionOutCount ?? props.transitionCount ?? 1;
+
   /// The duration that can elapse before a transition timeout occurs.
   Duration get transitionTimeout => const Duration(seconds: 1);
 
@@ -135,7 +164,7 @@ abstract class AbstractTransitionComponent<T extends AbstractTransitionProps,
     prepareShow();
 
     setState(newState()
-      ..transitionPhase = hasTransition ? TransitionPhase.PRE_SHOWING : TransitionPhase.SHOWN
+      ..transitionPhase = hasTransitionIn ? TransitionPhase.PRE_SHOWING : TransitionPhase.SHOWN
     );
   }
 
@@ -155,27 +184,15 @@ abstract class AbstractTransitionComponent<T extends AbstractTransitionProps,
     prepareHide();
 
     setState(newState()
-      ..transitionPhase = hasTransition ? TransitionPhase.HIDING : TransitionPhase.HIDDEN
+      ..transitionPhase = hasTransitionOut ? TransitionPhase.HIDING : TransitionPhase.HIDDEN
     );
   }
 
   /// Listens for the next `transitionend` event and invokes a callback after
   /// the event is dispatched.
   @mustCallSuper
   void onNextTransitionEnd(complete()) {
-    var skipCount = props.transitionCount - 1;
-
-    if (props.transitionCount <= 0) {
-      var warningMessage = 'You have set `props.transitionCount` to an invalid option: ${props.transitionCount}.';
-
-      if (props.transitionCount == 0) {
-        warningMessage += ' Instead of setting this prop to 0, override the `hasTransition` getter to return false.';
-      }
-
-      assert(ValidationUtil.warn(warningMessage, this));
-
-      skipCount = 0;
-    }
+    var transitionCount = isOrWillBeHidden ? transitionOutCount : transitionInCount;
 
     _cancelTransitionEventListener();
     _cancelTransitionEndTimer();
@@ -191,7 +208,7 @@ abstract class AbstractTransitionComponent<T extends AbstractTransitionProps,
       complete();
     });
 
-    _endTransitionSubscription = getTransitionDomNode()?.onTransitionEnd?.skip(skipCount)?.take(1)?.listen((_) {
+    _endTransitionSubscription = getTransitionDomNode()?.onTransitionEnd?.skip(transitionCount - 1)?.take(1)?.listen((_) {
       _cancelTransitionEndTimer();
 
       complete();
@@ -368,6 +385,23 @@ abstract class AbstractTransitionComponent<T extends AbstractTransitionProps,
     }
   }
 
+  /// Returns attributes only available during testing that indicate the state of the transition.
+  Map<String, String> getTransitionTestAttributes() {
+    if (!component_base.UiProps.testMode) return const {};
+
+    const enumToAttrValue = const <TransitionPhase, String>{
+      TransitionPhase.SHOWN: 'shown',
+      TransitionPhase.HIDDEN: 'hidden',
+      TransitionPhase.HIDING: 'hiding',
+      TransitionPhase.PRE_SHOWING: 'pre-showing',
+      TransitionPhase.SHOWING: 'showing',
+    };
+
+    return {
+      transitionPhaseTestAttr: enumToAttrValue[state.transitionPhase],
+    };
+  }
+
   // --------------------------------------------------------------------------
   // Public API Methods
   // --------------------------------------------------------------------------

lib/src/component/abstract_transition_props.dart

@@ -27,11 +27,23 @@ abstract class TransitionPropsMixin {
 
   Map get props;
 
-  /// Number of transitions to occur within the [AbstractTransitionComponent].
+  /// The number of `transitionend` event that occur when the transition node is shown/hidden.
   ///
-  /// Default: 1
+  /// Serves as the default for [transitionInCount]/[transitionOutCount] when they are not specified.
+  ///
+  /// Default: `1`
   int transitionCount;
 
+  /// The number of `transitionend` event that occur when the transition node is shown.
+  ///
+  /// Default: [transitionCount]
+  int transitionInCount;
+
+  /// The number of `transitionend` event that occur when the transition node is hidden.
+  ///
+  /// Default: [transitionCount]
+  int transitionOutCount;
+
   /// Optional callback that fires before the [AbstractTransitionComponent] is hidden.
   ///
   /// Returning `false` will cancel default behavior, and the [AbstractTransitionComponent] will remain visible.