Simplify merge heuristics

Removes the idea of a 'boundry' transform. More explicit and
documentated merging process.

Author: Brandon Dail

demo/app.jsx

@@ -36,12 +36,10 @@ let aphroditeStyle = {
   },
 }
 
-window.animations = animations
-
-
 animations.tadaFlip = merge(animations.tada, animations.flip);
 animations.jelloFadeDown = merge(animations.fadeInDown, animations.jello);
 animations.flashSwing = merge(animations.jello, animations.bounce);
+animations.zoomWobble = merge(animations.wobble, animations.zoomOut);
 
 const animationNames = [];
 

src/merge.js

@@ -1,17 +1,21 @@
 // flow
 import type { Animation, Keyframe, CSSValue } from './types';
 
-// Keyframes that bound an animation
-const boundryFrmes: { [frame: string]: boolean } = {
-  'from': true,
-  '0%': true,
-  'to': true,
-  '100%': true,
-}
+
+type FrameMap = {
+  [source: string]: string
+};
 
 // The default allowed delta for keyframe distance
 const keyframeDistance = 10;
 
+const defaultNormalizedFrames: FrameMap = {
+  'from': 'from',
+  '0%': 'from',
+  'to': 'to',
+  '100%': 'to',
+}
+
 /**
  * Merge lets you take two Animations and merge them together. It
  * iterates through each animation and merges each keyframe. It
@@ -25,101 +29,152 @@ const keyframeDistance = 10;
  * import { merge, tada, flip } from 'react-effects';
  * const tadaFlip = merge(tada, flip);
  */
-export default function merge(primary, secondary) {
+export default function merge(
+  primary: Animation,
+  secondary: Animation
+) : Animation {
   // A map used to track the normalized frame value in cases where
   // two animations contain frames that appear closely, but not exactly
   // at the same time (e.g., 50% and 52%)
-  const normalizedFrames = {
-    'from': 'from',
-    '0%': 'from',
-    'to': 'to',
-    '100%': 'to',
-  };
-
+  const normalizedFrames: FrameMap = {};
 
-  // If we are dealing with an animation that appears to be
-  // a "boundry-specific" animation, meaning it only specifies
-  // a start and end position, we want to persist the start transform
-  // throughout.
-  let boundryTransform = null;
   // We merge each frame into a new object and return it
-  const merged = {};
-  /* primary frame should control directional movement */
-  const primaryFrames = Object.keys(primary);
-  /* secondary frames should control orientation/size */
-  const secondaryFrames = Object.keys(secondary);
+  const merged: Animation = {};
 
-  const normalizedPrimary = cacheNormalizedFrames(
+  const normalizedPrimary: Animation = cacheNormalizedFrames(
     primary,
     normalizedFrames
   );
 
-  const normalizedSecondary = cacheNormalizedFrames(
+  const normalizedSecondary: Animation = cacheNormalizedFrames(
     secondary,
     normalizedFrames
   );
 
-  // We parse a boundry transform from either the primary
-  // or secondary animation, if either look to be bounded.
-  // Primary animation is given precedence.
-  if (secondaryFrames.length <= 2) {
-    boundryTransform = parseBoundryTransform(
-      normalizedSecondary
-    );
-  } else if (primaryFrames.length <= 2) {
-    boundryTransform = parseBoundryTransform(
-      primaryFrames
-    );
-  }
-
-  // Iterate through all the cached, normalized animation frames.
+  // Iterate all normalized frames
   for (let frame in normalizedFrames) {
     const primaryFrame = normalizedPrimary[frame];
     const secondaryFrame = normalizedSecondary[frame];
+    // Create a new frame object if it doesn't exist.
     const target = merged[frame] || (merged[frame] = {});
 
-    for (let propertyName in primaryFrame) {
-      if (propertyName === 'transform' && secondaryFrame) {
-        // TODO we should only apply the boundry transform when we
-        // are in between boundry frames, not in them. We need to track
-        // what the actual start and end frame are.
-        target[propertyName] = mergeTransforms([
-          primaryFrame[propertyName],
-          secondaryFrame[propertyName],
-          boundryTransform
-        ]);
-      } else {
-        target[propertyName] = primaryFrame[propertyName];
+    // If both aniatmions define this frame, merge them carefully
+    if (primaryFrame && secondaryFrame) {
+      // Walk through all properties in the primary frame
+      for (let propertyName in primaryFrame) {
+        // Transform is special cased, as we want to combine both
+        // transforms when posssible.
+        if (propertyName === 'transform') {
+          // But we dont need to do anything if theres no other
+          // transform to merge.
+          if (secondaryFrame[propertyName]) {
+            const newTransform = mergeTransforms([
+              primaryFrame[propertyName],
+              secondaryFrame[propertyName]
+            ]);
+            // We make the assumption that animations use 'transform: none'
+            // to terminate the keyframe. If we're combining two animations
+            // that may terminate at separte frames, its safest to just
+            // ignore this.
+            if (newTransform !== 'none') {
+              target[propertyName] = newTransform;
+            }
+          } else {
+            const propertyValue = getDefined(
+              primaryFrame[propertyName],
+              secondaryFrame[propertyName]
+            );
+            target[propertyName] = propertyValue;
+          }
+        }
+        // If the property is *not* 'transform' we just write it
+        else {
+          // Use a typeof check so we don't ignore falsy values like 0.
+          const propertyValue = getDefined(
+            primaryFrame[propertyName],
+            secondaryFrame[propertyName]
+          );
+          target[propertyName] = propertyValue;
+        }
+      }
+      // Walk through all properties in the secondary frame.
+      // We should be able to assume that any property that
+      // needed to be merged has already been merged when we
+      // walked the primary frame.
+      for (let propertyName in secondaryFrame) {
+        const propertyValue = secondaryFrame[propertyName];
+        // Again, ignore 'transform: none'
+        if (propertyName === 'transform' && propertyValue === 'none') {
+          continue;
+        }
+        target[propertyName] = target[propertyName] || propertyValue;
       }
     }
-
-    for (let propertyName in secondaryFrame) {
-      if (!target[propertyName]) {
-        target[propertyName] = secondaryFrame[propertyName];
+    // Otherwise just pick the frame that is defined.
+    else {
+      const definedFrame = primaryFrame || secondaryFrame;
+      const target = {};
+      for (let propertyName in definedFrame) {
+        const propertyValue = definedFrame[propertyName];
+        // Again, ignore 'transform: none'
+        if (propertyName === 'transform' && propertyValue === 'none') {
+          continue;
+        }
+        target[propertyName] = propertyValue;
+      }
+      // Only define a frame if there are actual styles to apply
+      if (Object.keys(target).length) {
+        merged[frame] = target;
       }
     }
-  }
-  return merged;
-}
+  };
 
-function mergeTransforms(transforms) {
-  transforms = transforms.filter(
-    transform => transform && transform !== 'none'
-  )
-  transforms = transforms.join(' ');
-  return transforms.trim();
+  return merged;
 }
 
 
-function parseBoundryTransform(animation) {
-  return animation.from && animation.from.transform;
+/**
+ * Takes an array of strings representing transform values and
+ * merges them. Ignores duplicates and 'none'.
+ * @private
+ * @example
+ * mergeTransforms([
+ *   'translateX(10px)',
+ *   'rotateX(120deg)',
+ *   'translateX(10px)',
+ *   'none',
+ * ])
+ * // -> 'translateX(10px) rotateX(120deg)'
+ *
+ */
+function mergeTransforms(transforms: Array<string>): string {
+  const filtered = transforms.filter((transform, i) =>
+    transform !== 'none' && transforms.indexOf(transform) == i
+  );
+  return filtered.join(' ');
 }
 
+/**
+ * Returns whichever value is actually defined
+ * @private
+ */
+function getDefined(primary: CSSValue, secondary: CSSValue): CSSValue {
+  return typeof primary !== 'undefined' ? primary : secondary
+}
 
-function cacheNormalizedFrames(source, cache) {
-  const normalized = {};
+/**
+ * Takes a source animation and the current cache, populating the
+ * cache with the normalized keyframes and returning a copy of the
+ * source animation with the normalized keyframes as well.
+ *
+ * It uses keyframeDistance to determine how much it should normalize
+ * frames.
+ * @private
+ */
+function cacheNormalizedFrames(source: Animation, cache: FrameMap): Animation {
+  const normalized: Animation = {};
   for (let frame in source) {
-    const normalizedFrame = cache[frame] || (Math.round(
+    const normalizedFrame = defaultNormalizedFrames[frame] || (Math.round(
       parseFloat(frame) / keyframeDistance
     ) * keyframeDistance) + '%';
     normalized[normalizedFrame] = source[frame];