feat(motion): adds dev logging to improve dx

Author: Michael Dougall

packages/docs/src/5-troubleshooting/docs.mdx

@@ -31,3 +31,26 @@ Double check your [Motion](/motion) elements.
 ```
 
 > ** Tip -** Can't find what you're looking for? [Raise an issue on Github](https://github.com/madou/element-motion/issues/new).
+
+## Styled Components
+
+Using v3? Make sure to use `innerRef`,
+like so:
+
+```js
+import styled from 'styled-components';
+
+const StyledDiv = styled.div``;
+
+<Motion>{({ ref, ...motion }) => <StyledDiv innerRef={ref} {...motion} />}</Motion>;
+```
+
+Using v4? Just use `ref` thanks to `forwardRef()`!
+
+```js
+import styled from 'styled-components';
+
+const StyledDiv = styled.div``;
+
+<Motion>{motion => <StyledDiv {...motion} />}</Motion>;
+```

packages/utils/.size-limit.js

@@ -1,10 +1,10 @@
 module.exports = [
   {
-    limit: '3.84 KB',
+    limit: '3.86 KB',
     path: 'dist/esm/index.js',
   },
   {
-    limit: '2.72 KB',
+    limit: '2.73 KB',
     path: 'dist/esm/Motion/index.js',
   },
   {

packages/utils/src/Motion/__snapshots__/test.tsx.snap

@@ -185,6 +185,56 @@ exports[`<Motion /> should render markup in a portal created in a motion 1`] = `
 </Portal>
 `;
 
+exports[`<Motion /> should throw destination ref is not found 1`] = `
+"@element-motion
+
+The destination ref was not set when trying to store data, check that a child element has a ref passed.
+This needs to be set so we can take a snapshot of the origin DOM element!
+Try setting \\"innerRef\\" or \\"ref\\" depending if the component is using React.forwardRef().
+
+<Motion name=\\"throw-no-ref-dest\\">
+  {props => <div ref={props.ref} />}
+</Motion>
+"
+`;
+
+exports[`<Motion /> should throw if destination ref is not a DOM element 1`] = `
+"@element-motion
+
+The destination ref was not a DOM element - double check your ref to make sure it's being passed to a real DOM element!
+You might need to use \\"innerRef\\" if the component isn't using React.forwardRef().
+
+<Motion name=\\"throw-non-ref-dest\\">
+  {props => <div ref={props.ref} />}
+</Motion>
+"
+`;
+
+exports[`<Motion /> should throw if origin ref is not a DOM element 1`] = `
+"@element-motion
+
+The origin ref was not a DOM element - double check your ref to make sure it's being passed to a real DOM element!
+You might need to use \\"innerRef\\" if the component isn't using React.forwardRef().
+
+<Motion name=\\"throw-non-ref-origin\\">
+  {props => <div ref={props.ref} />}
+</Motion>
+"
+`;
+
+exports[`<Motion /> should throw origin ref is not found 1`] = `
+"@element-motion
+
+The origin ref was not set when trying to store data, check that a child element has a ref passed.
+This needs to be set so we can take a snapshot of the origin DOM element!
+Try setting \\"innerRef\\" or \\"ref\\" depending if the component is using React.forwardRef().
+
+<Motion name=\\"throw-no-ref-origin\\">
+  {props => <div ref={props.ref} />}
+</Motion>
+"
+`;
+
 exports[`<Motion /> should update markup created in a motion in after animate phase 1`] = `
 <Portal
   containerInfo={

packages/utils/src/Motion/index.tsx

@@ -57,9 +57,17 @@ export default class Motion extends React.PureComponent<MotionProps, MotionState
       );
     }
 
-    if (this.element && componentIn === undefined && store.has(name)) {
+    if (store.has(name) && componentIn === undefined) {
+      if (process.env.NODE_ENV === 'development') {
+        this.throwIfElementUndefinedOrNotDOMElement(this.element, 'destination');
+      }
+
       // A child has already been stored, so this is probably the matching pair.
-      if (this.element.tagName === 'IMG' && !(this.element as HTMLImageElement).complete) {
+      if (
+        this.element &&
+        this.element.tagName === 'IMG' &&
+        !(this.element as HTMLImageElement).complete
+      ) {
         const remove = eventListener(this.element, 'load', () => {
           remove();
           this.execute();
@@ -169,6 +177,34 @@ export default class Motion extends React.PureComponent<MotionProps, MotionState
     setTimeout(() => store.remove(name), timeToWaitForNext);
   }
 
+  throwIfElementUndefinedOrNotDOMElement(element: HTMLElement | null, location: string) {
+    if (process.env.NODE_ENV === 'development') {
+      const buildMessage = (msg: string) => `${msg}
+
+<${Motion.displayName} name="${this.props.name}">
+  {props => <div ref={props.ref} />}
+</${Motion.displayName}>
+`;
+
+      throwIf(
+        !element,
+        buildMessage(
+          `The ${location} ref was not set when trying to store data, check that a child element has a ref passed.
+This needs to be set so we can take a snapshot of the origin DOM element!
+Try setting "innerRef" or "ref" depending if the component is using React.forwardRef().`
+        )
+      );
+
+      throwIf(
+        !(element instanceof HTMLElement),
+        buildMessage(
+          `The ${location} ref was not a DOM element - double check your ref to make sure it's being passed to a real DOM element!
+You might need to use "innerRef" if the component isn't using React.forwardRef().`
+        )
+      );
+    }
+  }
+
   snapshotDOMData(action: 'store' | 'return' = 'store'): store.MotionData | null {
     // If there is only a Motion target and no child motions
     // data will be undefined, which means there are no motions to store.
@@ -177,15 +213,7 @@ export default class Motion extends React.PureComponent<MotionProps, MotionState
     }
 
     if (process.env.NODE_ENV === 'development') {
-      throwIf(
-        !this.element,
-        `The ref was not set when trying to store data, check that a child element has a ref passed. This needs to be set so we can take a snapshot of the origin DOM element.
-
-<${Motion.displayName} name="${this.props.name}">
-  {props => <div ref={props.ref} />}
-</${Motion.displayName}>
-`
-      );
+      this.throwIfElementUndefinedOrNotDOMElement(this.element, 'origin');
     }
 
     const elementBoundingBox = getElementBoundingBox(this.element as HTMLElement);
@@ -230,6 +258,10 @@ If it's an image, try and have the image loaded before mounting or set a static
     const container = typeof getContainer === 'function' ? getContainer() : getContainer;
     let aborted = false;
 
+    if (process.env.NODE_ENV === 'development') {
+      this.throwIfElementUndefinedOrNotDOMElement(this.element, 'destination');
+    }
+
     if (DOMSnapshot) {
       const { collectorData, elementData } = DOMSnapshot;
       this.executing = true;

packages/utils/src/Motion/test.tsx

@@ -1,3 +1,4 @@
+/* eslint-disable react/no-multi-comp */
 import * as React from 'react';
 import { mount, ReactWrapper, shallow } from 'enzyme'; // eslint-disable-line import/no-extraneous-dependencies
 import { MemoryRouter, Link } from 'react-router-dom';
@@ -486,4 +487,90 @@ describe('<Motion />', () => {
       });
     });
   });
+
+  it('should throw if origin ref is not a DOM element', () => {
+    process.env.NODE_ENV = 'development';
+    class ReactComponent extends React.Component {
+      render() {
+        return <div />;
+      }
+    }
+    const TestMotion = utils.createTestMotion();
+    const wrapper = mount(
+      <utils.MotionUnderTest
+        from={start => (
+          <Motion name="throw-non-ref-origin" in={!start}>
+            <TestMotion>{(props: {}) => <ReactComponent {...props} />}</TestMotion>
+          </Motion>
+        )}
+        to={<Motion name="throw-non-ref-origin">{(props: {}) => <div {...props} />}</Motion>}
+        start={false}
+      />
+    );
+
+    expect(() => wrapper.setProps({ start: true })).toThrowErrorMatchingSnapshot();
+  });
+
+  it('should throw if destination ref is not a DOM element', () => {
+    process.env.NODE_ENV = 'development';
+    (getElementBoundingBox as jest.Mock).mockReturnValue(utils.domData());
+    class ReactComponent extends React.Component {
+      render() {
+        return <div />;
+      }
+    }
+    const TestMotion = utils.createTestMotion();
+    const wrapper = mount(
+      <utils.MotionUnderTest
+        from={start => (
+          <Motion name="throw-non-ref-dest" in={!start}>
+            <TestMotion>{(props: {}) => <div {...props} />}</TestMotion>
+          </Motion>
+        )}
+        to={
+          <Motion name="throw-non-ref-dest">{(props: {}) => <ReactComponent {...props} />}</Motion>
+        }
+        start={false}
+      />
+    );
+
+    expect(() => wrapper.setProps({ start: true })).toThrowErrorMatchingSnapshot();
+  });
+
+  it('should throw origin ref is not found', () => {
+    process.env.NODE_ENV = 'development';
+    const TestMotion = utils.createTestMotion();
+    const wrapper = mount(
+      <utils.MotionUnderTest
+        from={start => (
+          <Motion name="throw-no-ref-origin" in={!start}>
+            <TestMotion>{() => <div />}</TestMotion>
+          </Motion>
+        )}
+        to={<Motion name="throw-no-ref-origin">{props => <div {...props} />}</Motion>}
+        start={false}
+      />
+    );
+
+    expect(() => wrapper.setProps({ start: true })).toThrowErrorMatchingSnapshot();
+  });
+
+  it('should throw destination ref is not found', () => {
+    process.env.NODE_ENV = 'development';
+    (getElementBoundingBox as jest.Mock).mockReturnValue(utils.domData());
+    const TestMotion = utils.createTestMotion();
+    const wrapper = mount(
+      <utils.MotionUnderTest
+        from={start => (
+          <Motion name="throw-no-ref-dest" in={!start}>
+            <TestMotion>{props => <div {...props} />}</TestMotion>
+          </Motion>
+        )}
+        to={<Motion name="throw-no-ref-dest">{() => <div />}</Motion>}
+        start={false}
+      />
+    );
+
+    expect(() => wrapper.setProps({ start: true })).toThrowErrorMatchingSnapshot();
+  });
 });