Merge branch 'feature/timeline-target-refs'

Author: Jan Fischer

packages/docz/src/components/Timeline.mdx

@@ -6,7 +6,7 @@ menu: Components
 import { Fragment } from 'react';
 import { Playground, Props } from 'docz'
 import { Controls, PlayState } from './../../../react-gsap/src/'
-import { Timeline, TimelinePropsDummy } from './Timeline'
+import { Timeline, TimelinePropsDummy, TargetWithNames } from './Timeline'
 import { Tween } from './Tween'
 
 # Timeline
@@ -78,6 +78,39 @@ If you don't add a target you transform all target components.
   </Controls>
 </Playground>
 
+## Advanced multiple targets
+
+If you need to target individual elements you can use a special forwardRef function.
+The `targets` parameter provide the `set` function, which you can use to set a ref to a certain key.
+
+If you use an array as value, as seen in the example, you can save multiple elements as array under one key and use e.g. the `stagger` prop.
+
+```javascript
+const TargetWithNames = forwardRef((props, targets) => (
+  <div style={{ textAlign: 'center' }}>
+    <h3 ref={div => targets.set('div1', div)}>THIS</h3>
+    <SplitChars
+      ref={(div: ReactElement) => targets.set('div2', [div])}
+      wrapper={<h3 style={{ display: 'inline-block' }} />}
+    >
+      TEST
+    </SplitChars>
+    <h3 ref={div => targets.set('div3', div)}>IS A</h3>
+  </div>
+));
+
+```
+
+<Playground>
+  <Controls playState={PlayState.stop}>
+    <Timeline target={<TargetWithNames />}>
+      <Tween from={{ x: '-100vw' }} target="div1" position="0" />
+      <Tween from={{ x: '-100vw' }} target="div2" position="2" stagger={0.1} />
+      <Tween from={{ x: '-100vw' }} target="div3" position="1" />
+    </Timeline>
+  </Controls>
+</Playground>
+
 ## Nested Timelines
 
 You can nest other Timelines or HTML structures.

packages/docz/src/components/Timeline.tsx

@@ -1,7 +1,22 @@
-import React from 'react';
+import React, { forwardRef, ReactElement } from 'react';
 import Timeline, { TimelineProps } from './../../../react-gsap/src/Timeline';
+import { SplitChars } from './../../../react-gsap/src';
 
 export const TimelinePropsDummy: React.FunctionComponent<TimelineProps> = props => (
   <div {...props} />
 );
-export { Timeline };
+
+const TargetWithNames = forwardRef((props, targets: any) => (
+  <div style={{ textAlign: 'center' }}>
+    <h3 ref={div => targets.set('div1', div)}>THIS</h3>
+    <SplitChars
+      ref={(div: ReactElement) => targets.set('div2', [div])}
+      wrapper={<h3 style={{ display: 'inline-block' }} />}
+    >
+      TEST
+    </SplitChars>
+    <h3 ref={div => targets.set('div3', div)}>IS A</h3>
+  </div>
+));
+
+export { Timeline, TargetWithNames };

packages/playground/package.json

@@ -17,7 +17,7 @@
     "gsap": "^3.2.6",
     "react": "^16.13.1",
     "react-dom": "^16.13.1",
-    "react-gsap": "2.0.6",
+    "react-gsap": "2.2.0",
     "react-router-dom": "^5.1.2",
     "react-scripts": "3.4.1",
     "react-transition-group": "^4.3.0",

packages/playground/src/examples/Animation.tsx

@@ -34,7 +34,7 @@ export const RubberBand = ({
   children,
   ...rest
 }: {
-  children: React.ReactNode;
+  children: React.ReactElement;
   [key: string]: any;
 }) => (
   <Timeline target={children} {...rest}>

packages/playground/src/examples/Timeline.tsx

@@ -1,6 +1,13 @@
-import React, { Fragment } from 'react';
+import React, {
+  forwardRef,
+  Fragment,
+  useRef,
+  useImperativeHandle,
+  ReactElement,
+  ReactHTMLElement,
+} from 'react';
 import styled from 'styled-components';
-import { Tween, Timeline, SplitWords, SplitLetters, Controls, PlayState } from 'react-gsap';
+import { Tween, Timeline, SplitWords, SplitChars, Controls, PlayState } from 'react-gsap';
 
 const TimelineStyled = styled.div``;
 
@@ -87,9 +94,9 @@ const TimelineComponent = () => (
           wrapper={<div style={{ position: 'relative', left: '90px' }} />}
           target={
             <Fragment>
-              <SplitLetters wrapper={<div style={{ fontSize: '80px', display: 'inline-block' }} />}>
+              <SplitChars wrapper={<div style={{ fontSize: '80px', display: 'inline-block' }} />}>
                 AIIIIGHHT
-              </SplitLetters>
+              </SplitChars>
             </Fragment>
           }
           labels={[
@@ -114,4 +121,27 @@ const TimelineComponent = () => (
   </TimelineStyled>
 );
 
-export default TimelineComponent;
+const TargetWithNames = forwardRef((props, targets: any) => (
+  <div>
+    <div ref={div => targets.set('div1', div)}>first</div>
+    <SplitChars
+      ref={(div: ReactElement) => targets.set('div2', [div])}
+      wrapper={<span style={{ display: 'inline-block' }} />}
+    >
+      second
+    </SplitChars>
+    <div ref={div => targets.set('div3', div)}>third</div>
+  </div>
+));
+
+const TimelineTargets = () => {
+  return (
+    <Timeline target={<TargetWithNames />}>
+      <Tween to={{ x: '200px' }} target="div3" position="0" />
+      <Tween to={{ x: '200px' }} target="div1" position="0.5" />
+      <Tween to={{ x: '200px' }} target="div2" position="1" stagger={0.1} />
+    </Timeline>
+  );
+};
+
+export default TimelineTargets;

packages/react-gsap/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-gsap",
-  "version": "2.1.0",
+  "version": "2.2.0",
   "description": "React components for GSAP",
   "author": "bitworking",
   "license": "MIT",
@@ -25,8 +25,8 @@
   },
   "peerDependencies": {
     "gsap": ">=3",
-    "react": ">=16",
-    "react-dom": ">=16"
+    "react": ">=16.6",
+    "react-dom": ">=16.6"
   },
   "husky": {
     "hooks": {
@@ -44,12 +44,16 @@
   "devDependencies": {
     "@types/react": "^16.9.34",
     "@types/react-dom": "^16.9.7",
+    "@types/react-is": "^16.7.1",
     "gsap": "^3.2.6",
     "husky": "^4.2.5",
     "react": "^16.13.1",
     "react-dom": "^16.13.1",
     "tsdx": "^0.13.2",
     "tslib": "^1.11.1",
     "typescript": "^3.8.3"
+  },
+  "dependencies": {
+    "react-is": "^16.13.1"
   }
 }

packages/react-gsap/src/Timeline.tsx

@@ -1,18 +1,27 @@
-import React, { Fragment } from 'react';
+import React, { Fragment, ReactNode, ReactElement, forwardRef } from 'react';
 import { gsap } from 'gsap';
+import { isForwardRef, isFragment } from 'react-is';
 import { PlayState } from './types';
 import { getTweenFunction, setPlayState, refOrInnerRef, nullishCoalescing } from './helper';
 import Provider, { Context } from './Provider';
+import { TweenProps } from './Tween';
 
 type Label = {
   label: string;
   position: string | number;
 };
 
+export type Targets = Map<string | number, ReactElement | ReactElement[]>;
+export type TargetsRef = {
+  set: (key: string, target: any) => void;
+};
+
+export type Target = ReactElement | null;
+
 export type TimelineProps = {
-  children: React.ReactNode;
-  wrapper?: React.ReactElement;
-  target?: any;
+  children: ReactNode;
+  wrapper?: ReactElement;
+  target?: Target;
   position?: string | number;
   labels?: Label[];
 
@@ -29,7 +38,13 @@ class Timeline extends Provider<TimelineProps> {
   static contextType = Context;
 
   timeline: any;
-  targets: any[] = [];
+  targets: Targets = new Map();
+
+  constructor(props: TimelineProps) {
+    super(props);
+
+    this.setTarget = this.setTarget.bind(this);
+  }
 
   setPlayState(playState: PlayState) {
     const { playState: previousPlayState } = this.props;
@@ -45,7 +60,7 @@ class Timeline extends Provider<TimelineProps> {
   }
 
   getSnapshotBeforeUpdate() {
-    this.targets = [];
+    this.targets = new Map();
     return null;
   }
 
@@ -105,12 +120,24 @@ class Timeline extends Provider<TimelineProps> {
     // add tweens or nested timelines to timeline
     this.consumers.forEach(consumer => {
       if (consumer.tween && !consumer.props.children) {
-        const { position, target, stagger, ...vars } = consumer.props;
-        const tween = getTweenFunction(nullishCoalescing(this.targets[target], this.targets), {
-          stagger,
-          ...vars,
-        });
+        const { position, target, stagger, ...vars } = consumer.props as TweenProps;
+
+        // get target if not nullish
+        let targets = null;
+        if (target !== null && typeof target !== 'undefined') {
+          targets = this.targets.get(target);
+        }
+
+        const tween = getTweenFunction(
+          // @ts-ignore
+          nullishCoalescing(targets, Array.from(this.targets.values())),
+          {
+            stagger,
+            ...vars,
+          }
+        );
         this.timeline.add(tween, nullishCoalescing(position, '+=0'));
+        consumer.setGSAP(tween);
       } else {
         const { position } = consumer.props;
         this.timeline.add(consumer.getGSAP(), nullishCoalescing(position, '+=0'));
@@ -139,12 +166,28 @@ class Timeline extends Provider<TimelineProps> {
   }
 
   addTarget(target: any) {
-    // target is null at unmount
     if (target !== null) {
-      this.targets.push(target);
+      this.targets.set(this.targets.size, target);
     }
   }
 
+  setTarget(key: string, target: any) {
+    if (target !== null) {
+      if (this.targets.has(key)) {
+        const targets = this.targets.get(key);
+        if (Array.isArray(targets)) {
+          this.targets.set(key, [...targets, ...target]);
+          return;
+        }
+      }
+      this.targets.set(key, target);
+    }
+  }
+
+  setTargets(targets: Targets) {
+    this.targets = targets;
+  }
+
   getTargets() {
     return this.targets;
   }
@@ -156,20 +199,40 @@ class Timeline extends Provider<TimelineProps> {
     });
   }
 
-  render() {
-    let { target, children, wrapper } = this.props;
+  renderTarget(target?: Target): ReactNode {
+    if (!target) {
+      return null;
+    }
 
-    let output = (
+    // if is forwardRef clone and pass targets as ref
+    if (isForwardRef(target)) {
+      return <target.type ref={{ set: this.setTarget }} />;
+    }
+
+    // else iterate the first level of children and set targets
+    return (
       <Fragment>
         {/* First render the target */}
-        {React.Children.map(target, child => {
-          if (child.type.toString() === 'Symbol(react.fragment)') {
+        {React.Children.map<ReactElement, ReactElement>(target, child => {
+          if (isFragment(child)) {
             return React.Children.map(child.props.children, fragmentChild => {
               return this.cloneElement(fragmentChild);
             });
           }
           return this.cloneElement(child);
         })}
+      </Fragment>
+    );
+  }
+
+  render() {
+    let { target, children, wrapper } = this.props;
+
+    const renderedTarget = this.renderTarget(target);
+
+    let output = (
+      <Fragment>
+        {renderedTarget}
         {children}
       </Fragment>
     );