Use refs in useAnimation and write documentation

.github/workflows/update-docs.yml

@@ -31,10 +31,10 @@ jobs:
 
       - name: Build Storybook
         run: |
-          npm ci
-          npm run build
-          npm run storybook:build
-          cp -r ./packages/*/.docs/ ./.docs
+          npm ci;
+          npm run build;
+          npm run storybook:build;
+          cp -r ./packages/*/.docs/ ./.docs;
 
       - name: Create artifact
         uses: actions/upload-pages-artifact@v1

.gitignore

@@ -65,3 +65,6 @@ node_modules/
 
 dist/
 .docs/
+
+# npmrc contains auth token for private gsap npm registry
+.npmrc

README.md

@@ -33,9 +33,18 @@ getting started guides.
 ## 💪 Contributing
 
 Pull requests are welcome. For major changes, please open an issue first to discuss what you would
-like to change.
+like to change. Please make sure to update tests accordingly.
 
-Please make sure to update tests as appropriate.
+Installation requires a greensock license, create a .npmrc file in the root of the repository with
+the necessary configuration to install the business package.
+
+```
+.npmrc
+
+//npm.greensock.com/:_authToken=<your-auth-token>
+@gsap:registry=https://npm.greensock.com
+
+```
 
 ## 📝 License
 

package.json

@@ -16,8 +16,8 @@
   },
   "devDependencies": {
     "@mediamonks/prettier-config": "^1.0.1",
-    "@storybook/react-vite": "^7.0.0-beta.19",
     "@storybook/cli": "^7.0.0-beta.19",
+    "@storybook/react-vite": "^7.0.0-beta.19",
     "@storybook/types": "^7.0.0-beta.19",
     "husky": "^7.0.4",
     "lerna": "^6.1.0",

packages/react-animation/package.json

@@ -39,6 +39,7 @@
   "author": "frontend.monks",
   "license": "MIT",
   "devDependencies": {
+    "@jest/globals": "^29.3.1",
     "@mediamonks/eslint-config": "^2.0.6",
     "@mediamonks/eslint-config-react": "^2.1.11",
     "@mediamonks/eslint-config-typescript": "^1.0.8",
@@ -47,8 +48,8 @@
     "@storybook/addon-interactions": "^7.0.0-beta.19",
     "@storybook/addon-links": "^7.0.0-beta.19",
     "@storybook/blocks": "^7.0.0-beta.19",
-    "@storybook/react-vite": "^7.0.0-beta.19",
     "@storybook/cli": "^7.0.0-beta.19",
+    "@storybook/react-vite": "^7.0.0-beta.19",
     "@storybook/types": "^7.0.0-beta.19",
     "@swc/cli": "^0.1.57",
     "@swc/core": "^1.3.24",
@@ -63,7 +64,7 @@
   },
   "peerDependencies": {
     "@mediamonks/react-hooks": "^1.0.3",
-    "gsap": "^3.11.4",
+    "gsap": "npm:@gsap/business@^3.11.4",
     "react": ">=17",
     "react-dom": ">=17"
   },
@@ -76,6 +77,9 @@
     ],
     "parserOptions": {
       "project": "tsconfig.eslint.json"
+    },
+    "rules": {
+      "@typescript-eslint/no-redundant-type-constituents": "off"
     }
   }
 }

packages/react-animation/src/SplitTextWrapper/SplitTextWrapper.mdx

@@ -1,5 +1,24 @@
-import { Meta } from '@storybook/blocks';
+import { Meta, Canvas, Story, Source } from '@storybook/blocks';
+import { Example } from './SplitTextWrapper.stories';
 
 <Meta title="components/SplitTextWrapper" />
 
 # SplitTextWrapper
+
+The SplitTextWrapper creates a SplitText instance that can be retrieved using a ref. The SplitText
+is available as soon as the just before the components is finished mounting. A new SplitText
+instance is created when the children or variables change.
+
+## Example
+
+<Canvas>
+  <Story name="Example" />
+</Canvas>
+
+## Usage
+
+The SplitTextWrapper accepts 1 child, this child is rendered to HTML inside the component to make
+sure that compnents from the vDOM are not changed on render making them untargetable in the created
+SplitText instance.
+
+<Source name="Example" dark language="tsx" />

packages/react-animation/src/SplitTextWrapper/SplitTextWrapper.stories.tsx

@@ -0,0 +1,50 @@
+/* eslint-disable react/jsx-no-literals */
+import gsap from 'gsap';
+import { useCallback, useRef, type ReactElement } from 'react';
+import { useAnimation } from '../useAnimation/useAnimation.js';
+import { SplitTextWrapper } from './SplitTextWrapper.js';
+
+export default {
+  title: 'components/SplitTextWrapper',
+};
+
+export function Example(): ReactElement {
+  const splitTextRef = useRef<SplitText>(null);
+
+  const animation = useAnimation(() => {
+    if (!splitTextRef.current) {
+      return;
+    }
+
+    return gsap.from(splitTextRef.current.words, {
+      y: 20,
+      x: 4,
+      opacity: 0,
+      duration: 0.2,
+      stagger: 0.05,
+    });
+  }, []);
+
+  const onReplay = useCallback(() => {
+    animation.current?.play(0);
+  }, [animation]);
+
+  return (
+    <>
+      <h1>
+        <SplitTextWrapper ref={splitTextRef}>
+          <>
+            Lorem ipsum dolor sit <i>amet consectetur</i>
+            <br /> adipisicing elit. <b>Tenetur perspiciatis</b> eius ea, ratione,
+            <br /> illo molestias, <code>quia sapiente</code> modi quo
+            <br /> molestiae temporibus.
+          </>
+        </SplitTextWrapper>
+      </h1>
+
+      <button onClick={onReplay} type="button">
+        Replay
+      </button>
+    </>
+  );
+}

packages/react-animation/src/animations.ts

@@ -0,0 +1,38 @@
+class AnimationsMap extends Map {
+  private readonly callbacks = new Set<() => void>();
+
+  private updateQueued = false;
+
+  public set(key: unknown, value: gsap.core.Animation): this {
+    const result = super.set(key, value);
+
+    if (this.updateQueued) {
+      return result;
+    }
+
+    this.updateQueued = true;
+
+    queueMicrotask(() => {
+      for (const callback of this.callbacks) {
+        callback();
+      }
+
+      this.updateQueued = false;
+    });
+
+    return result;
+  }
+
+  public listen(callback: () => void): () => void {
+    this.callbacks.add(callback);
+
+    return () => {
+      this.callbacks.delete(callback);
+    };
+  }
+}
+
+/**
+ * Global map of animations that can be accessed by reference
+ */
+export const animations = new AnimationsMap();

packages/react-animation/src/index.ts

@@ -1,4 +1,3 @@
 export * from './SplitTextWrapper/SplitTextWrapper.js';
 export * from './useAnimation/useAnimation.js';
 export * from './useExposeAnimation/useExposeAnimation.js';
-export * from './useScrollAnimation/useScrollAnimation.js';