Merge pull request #50 from basementstudio/stagger-component

Stagger component

Author: julianbenegas

.changeset/slow-knives-hunt.md

@@ -0,0 +1,6 @@
+---
+"website": patch
+"@bsmnt/scrollytelling": patch
+---
+
+Stagger component

scrollytelling/src/components/stagger/index.tsx

@@ -0,0 +1,236 @@
+/* -------------------------------------------------------------------------------------------------
+ * Stagger
+ * -----------------------------------------------------------------------------------------------*/
+
+import * as React from "react";
+import {
+  StaggerBaseDef,
+  TweenWithChildrenDef,
+  TweenWithTargetDef,
+} from "../../types";
+import { Animation } from "../animation";
+import { isDev } from "../../util";
+
+export function Stagger(
+  props: StaggerBaseDef & {
+    tween: TweenWithTargetDef;
+  }
+): React.ReactElement;
+
+export function Stagger(
+  props: StaggerBaseDef & {
+    children?: React.ReactNode[];
+    tween: TweenWithChildrenDef;
+  }
+): React.ReactElement;
+
+export function Stagger({
+  children,
+  overlap,
+  tween,
+  disabled = false,
+}: StaggerBaseDef & {
+  children?: React.ReactNode[];
+  tween: TweenWithChildrenDef | TweenWithTargetDef;
+}) {
+  const isTweenWithTarget = "target" in tween;
+  const targetLength =
+    isTweenWithTarget && Array.isArray(tween.target)
+      ? tween.target.length
+      : children?.length;
+
+  const timeline = React.useMemo(() => {
+    if (tween?.start === undefined || tween?.end === undefined) {
+      if (isDev) {
+        throw new Error("Stagger needs a start and end value");
+      } else {
+        console.warn("Stagger needs a start and end value");
+      }
+
+      return [];
+    }
+
+    return getStaggeredTimeline({
+      start: tween?.start,
+      end: tween?.end,
+      chunks: targetLength,
+      overlap: overlap,
+    });
+  }, [targetLength, overlap, tween?.end, tween?.start]);
+
+  if (children) {
+    return children.map((child, i) => {
+      const currTween = timeline[i];
+
+      if (!currTween) {
+        return null;
+      }
+
+      return (
+        <Animation
+          key={i}
+          tween={{
+            ...tween,
+            start: currTween.start,
+            end: currTween.end,
+          }}
+          disabled={disabled}
+        >
+          {child}
+        </Animation>
+      );
+    });
+  } else if (isTweenWithTarget) {
+    const target = tween.target;
+
+    if (Array.isArray(target)) {
+      return target.map((target, i) => {
+        const currTween = timeline[i];
+
+        if (!currTween) {
+          return null;
+        }
+
+        if (tween.to) {
+          return (
+            <Animation
+              key={i}
+              tween={{
+                ...tween,
+                target: target,
+                start: currTween.start,
+                end: currTween.end,
+                to: {
+                  ...tween.to,
+                  onUpdateParams: [i],
+                },
+              }}
+              disabled={disabled}
+            />
+          );
+        } else if (tween.from) {
+          return (
+            <Animation
+              key={i}
+              tween={{
+                ...tween,
+                target: target,
+                start: currTween.start,
+                end: currTween.end,
+                from: { ...tween.from, onUpdateParams: [i] },
+              }}
+              disabled={disabled}
+            />
+          );
+        } else if (tween.fromTo) {
+          return (
+            <Animation
+              key={i}
+              tween={{
+                ...tween,
+                target: target,
+                start: currTween.start,
+                end: currTween.end,
+                fromTo: [
+                  {
+                    ...tween.fromTo[0],
+                  },
+                  {
+                    ...tween.fromTo[1],
+                    onUpdateParams: [i],
+                  },
+                ],
+              }}
+              disabled={disabled}
+            />
+          );
+        }
+      });
+    } else if (isDev) {
+      throw new Error("Stagger target must be an array");
+    }
+  }
+
+  return <></>;
+}
+
+// Overlap duration arrays by a factor mantaining the final duration between them
+const overlapDurationArrayByFactor = (
+  durations: { start: number; end: number }[],
+  factor: number
+) => {
+  const first = durations[0];
+  const last = durations[durations.length - 1];
+
+  if (first === undefined || last === undefined) {
+    throw Error("Durations array is empty");
+  }
+
+  /*
+    We need the veryStart because is our left shift in a [0% - 100%] timeline. Overlapping durations
+    affect the timeline total duration & we don't want that, so to scale it proportionally. Steps are:
+    1. We unshift it to bring the start to 0
+    2. Then we scale it proportionally to match the initial totalDuration
+    3. And then we shift it back to the veryStart
+  */
+  const veryStart = first.start;
+  const veryEnd = last.end;
+  const totalDuration = veryEnd - veryStart;
+
+  const overlapDuration = totalDuration * factor;
+  const overlapDurationPerDuration = overlapDuration / durations.length;
+
+  const afterOverlapDuration =
+    totalDuration - overlapDurationPerDuration * (durations.length - 1);
+  const afterOverlapDurationDiffFactor = totalDuration / afterOverlapDuration;
+
+  const newDurations = durations.map((duration, i) => {
+    const newStart = duration.start - overlapDurationPerDuration * i;
+    const newEnd = duration.end - overlapDurationPerDuration * i;
+
+    return {
+      start: Math.max(
+        veryStart + (newStart - veryStart) * afterOverlapDurationDiffFactor,
+        0
+      ),
+      end: Math.min(
+        veryStart + (newEnd - veryStart) * afterOverlapDurationDiffFactor,
+        100
+      ),
+    };
+  });
+
+  return newDurations;
+};
+
+export const getStaggeredTimeline = (config: {
+  start: number;
+  end: number;
+  overlap?: number;
+  chunks?: number;
+}) => {
+  const { start, end, overlap = 0, chunks = 1 } = config;
+
+  if (overlap > 1 || overlap < 0) {
+    throw new Error("Overlap must be between 0 and 1");
+  }
+
+  const duration = end - start;
+  const chunkDuration = duration / chunks;
+
+  const animationChunks = Array.from({ length: chunks }).map((_, i) => {
+    const chunkStart = start + chunkDuration * i;
+    const chunkEnd = chunkStart + chunkDuration;
+
+    return {
+      start: chunkStart,
+      end: chunkEnd,
+    };
+  });
+
+  if (overlap > 0) {
+    return overlapDurationArrayByFactor(animationChunks, overlap);
+  }
+
+  return animationChunks;
+};

scrollytelling/src/primitive.tsx

@@ -11,6 +11,7 @@ import { Parallax } from "./components/parallax";
 import { Pin } from "./components/pin";
 import { RegisterGsapPlugins } from "./components/register-plugins";
 import { Waypoint } from "./components/waypoint";
+import { Stagger } from './components/stagger'
 
 // ---- Context ----
 import {
@@ -214,6 +215,7 @@ export {
   Pin,
   RegisterGsapPlugins,
   Waypoint,
+  Stagger,
   //
   useScrollytelling,
   useScrollToLabel,

scrollytelling/src/types/index.ts

@@ -3,11 +3,13 @@ import { gsap } from "gsap";
 // ---- Utils
 export type DataOrDataArray<T> = T | Array<T>;
 export type UnitValue<Unit = string> = { value: number; unit: Unit };
-export type RequireAtLeastOne<T, Keys extends keyof T = keyof T> =
-    Pick<T, Exclude<keyof T, Keys>> 
-    & {
-        [K in Keys]-?: Required<Pick<T, K>> & Partial<Pick<T, Exclude<Keys, K>>>
-    }[Keys]
+export type RequireAtLeastOne<T, Keys extends keyof T = keyof T> = Pick<
+  T,
+  Exclude<keyof T, Keys>
+> &
+  {
+    [K in Keys]-?: Required<Pick<T, K>> & Partial<Pick<T, Exclude<Keys, K>>>;
+  }[Keys];
 
 // ---- Tween Specifics
 export type FromToOptions =
@@ -46,10 +48,18 @@ export type WaypointBaseDef = {
   disabled?: boolean;
 };
 
+export type StaggerBaseDef = {
+  overlap: number;
+  disabled?: boolean;
+};
+
 // FIXME: This name is not clear, why SimpleTween doesn't consume TweenBaseDef?
-export type SimpleTween = FromToOptions & { duration: number; forwards?: boolean };
+export type SimpleTween = FromToOptions & {
+  duration: number;
+  forwards?: boolean;
+};
 
 // ---- Aliases
-export type TweenVars = gsap.TweenVars; 
+export type TweenVars = gsap.TweenVars;
 
 export type Plugin = Parameters<typeof gsap.registerPlugin>[number];

scrollytelling/src/util/index.ts

@@ -103,3 +103,5 @@ export function getValidAt(at: number) {
   }
   return at;
 }
+
+export const isDev = process.env.NODE_ENV === "development";

turbo.json

@@ -1,5 +1,6 @@
 {
   "$schema": "https://turborepo.org/schema.json",
+  "globalEnv": ["NODE_ENV"],
   "pipeline": {
     "build": {
       "dependsOn": ["^build"],

website/src/app/sections/falling-caps/caps.tsx

@@ -93,14 +93,6 @@ export const CapsModel = () => {
   const halfViewportWidth = responsiveVPWidth / 2;
   const fadeInYoffset = 0.1;
 
-  const capsTimeline = useMemo(() => {
-    return getTimeline({
-      start: 48,
-      end: 100,
-      chunks: clonedMaterials.length,
-      overlap: 0.65,
-    });
-  }, [clonedMaterials]);
 
   const handleUpdate = React.useCallback(
     (idx: number) => {
@@ -132,29 +124,24 @@ export const CapsModel = () => {
 
   return (
     <>
-      {capProps.map((p, idx) => {
-        const currCapAnimation = capsTimeline[idx];
-
-        if (!currCapAnimation) return;
-
-        return (
-          <Scrollytelling.Animation
-            key={idx}
-            tween={{
-              start: currCapAnimation.start,
-              end: currCapAnimation.end,
-              target: [capProps[idx]],
-              to: {
-                progress: 1,
-                ease: "power2.inOut",
-                onUpdate: () => {
-                  handleUpdate(idx);
-                },
+      <Scrollytelling.Stagger
+        overlap={0.65}
+        tween={
+          {
+            start: 48,
+            end: 100,
+            target: capProps,
+            to: {
+              progress: 1,
+              ease: "power2.inOut",
+              /* We pass current target idx by params */
+              onUpdate: (idx) => {
+                handleUpdate(idx);
               },
-            }}
-          />
-        );
-      })}
+            },
+          }
+        }
+      />
 
       {/* clean this up when the scrollytelling leaves, as when scrolling really fast,
           GSAP is not being able to do so */}