Finalize target names, Add docz example

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/src/examples/Timeline.tsx

@@ -1,6 +1,13 @@
-import React, { forwardRef, Fragment, useRef, useImperativeHandle, ReactElement } 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={[
@@ -117,9 +124,12 @@ const TimelineComponent = () => (
 const TargetWithNames = forwardRef((props, targets: any) => (
   <div>
     <div ref={div => targets.set('div1', div)}>first</div>
-    <div ref={div => targets.set('div2', div)} style={{ display: 'inline-block' }}>
+    <SplitChars
+      ref={(div: ReactElement) => targets.set('div2', [div])}
+      wrapper={<span style={{ display: 'inline-block' }} />}
+    >
       second
-    </div>
+    </SplitChars>
     <div ref={div => targets.set('div3', div)}>third</div>
   </div>
 ));
@@ -128,8 +138,8 @@ const TimelineTargets = () => {
   return (
     <Timeline target={<TargetWithNames />}>
       <Tween to={{ x: '200px' }} target="div3" position="0" />
-      <Tween to={{ x: '200px' }} target="div1" position="0" />
-      <Tween to={{ x: '200px', rotation: 0 }} from={{ rotation: 180 }} target="div2" position="0" />
+      <Tween to={{ x: '200px' }} target="div1" position="0.5" />
+      <Tween to={{ x: '200px' }} target="div2" position="1" stagger={0.1} />
     </Timeline>
   );
 };

packages/react-gsap/src/Timeline.tsx

@@ -11,7 +11,10 @@ type Label = {
   position: string | number;
 };
 
-export type Targets = Map<string | number, ReactElement>;
+export type Targets = Map<string | number, ReactElement | ReactElement[]>;
+export type TargetsRef = {
+  set: (key: string, target: any) => void;
+};
 
 export type Target = ReactElement | null;
 
@@ -37,6 +40,12 @@ class Timeline extends Provider<TimelineProps> {
   timeline: any;
   targets: Targets = new Map();
 
+  constructor(props: TimelineProps) {
+    super(props);
+
+    this.setTarget = this.setTarget.bind(this);
+  }
+
   setPlayState(playState: PlayState) {
     const { playState: previousPlayState } = this.props;
     setPlayState(playState, previousPlayState, this.timeline);
@@ -113,12 +122,15 @@ class Timeline extends Provider<TimelineProps> {
       if (consumer.tween && !consumer.props.children) {
         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(
-            target ? this.targets.get(target) : null,
-            Array.from(this.targets.values())
-          ),
+          nullishCoalescing(targets, Array.from(this.targets.values())),
           {
             stagger,
             ...vars,
@@ -161,6 +173,13 @@ class Timeline extends Provider<TimelineProps> {
 
   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);
     }
   }
@@ -187,7 +206,7 @@ class Timeline extends Provider<TimelineProps> {
 
     // if is forwardRef clone and pass targets as ref
     if (isForwardRef(target)) {
-      return <target.type ref={this.targets} />;
+      return <target.type ref={{ set: this.setTarget }} />;
     }
 
     // else iterate the first level of children and set targets

packages/react-gsap/src/helper.ts

@@ -136,7 +136,7 @@ const refOrInnerRef = (child: any) => {
   return 'ref';
 };
 
-const nullishCoalescing = (value: any, ifNullish: any) => {
+const nullishCoalescing = <T, R>(value: T, ifNullish: R): T | R => {
   if (value === null || typeof value === 'undefined') {
     return ifNullish;
   }