experimental: Stagger Animation

packages/sdk-components-animation/src/animate-text.tsx

@@ -21,9 +21,24 @@ const split = {
 };
 
 type AnimateChildrenProps = {
+  /**
+   * Size of the sliding window for the animation:
+   * - 0: Typewriter effect (no animation).
+   * - (0..1]: Animates one part of the text at a time.
+   * - (1..n]: Animates multiple parts of the text within the sliding window.
+   */
   slidingWindow?: number;
+  /**
+   * Easing function applied within the sliding window.
+   */
   easing?: keyof typeof easings;
+  /**
+   * Text content to animate.
+   */
   children: React.ReactNode;
+  /**
+   * Defines how the text is split for animation (e.g., by character, space, or symbol).
+   */
   splitBy?: keyof typeof split;
 };
 

packages/sdk-components-animation/src/components.ts

@@ -1,2 +1,3 @@
 export { AnimateChildren } from "./animate-children";
 export { AnimateText } from "./animate-text";
+export { StaggerAnimation } from "./stagger-animation";

packages/sdk-components-animation/src/metas.ts

@@ -1,2 +1,3 @@
 export { meta as AnimateChildren } from "./animate-children.ws";
 export { meta as AnimateText } from "./animate-text.ws";
+export { meta as StaggerAnimation } from "./stagger-animation.ws";

packages/sdk-components-animation/src/props.ts

@@ -1,2 +1,3 @@
 export { propsMeta as AnimateChildren } from "./animate-children.ws";
 export { propsMeta as AnimateText } from "./animate-text.ws";
+export { propsMeta as StaggerAnimation } from "./stagger-animation.ws";

packages/sdk-components-animation/src/stagger-animation.tsx

@@ -0,0 +1,43 @@
+import { forwardRef, type ElementRef } from "react";
+
+const easings = {
+  linear: true,
+  easeIn: true,
+  easeInCubic: true,
+  easeInQuart: true,
+  easeOut: true,
+  easeOutCubic: true,
+  easeOutQuart: true,
+  ease: true,
+  easeInOutCubic: true,
+  easeInOutQuart: true,
+};
+
+type StaggerAnimationProps = {
+  /**
+   * Size of the sliding window for the animation:
+   * - 0: Typewriter effect (no animation).
+   * - (0..1]: Animates one child at a time.
+   * - (1..n]: Animates multiple children within the sliding window.
+   */
+  slidingWindow?: number;
+  /**
+   * Easing function applied within the sliding window.
+   */
+  easing?: keyof typeof easings;
+  /**
+   * Text content to animate.
+   */
+  children: React.ReactNode;
+};
+
+export const StaggerAnimation = forwardRef<
+  ElementRef<"div">,
+  StaggerAnimationProps
+>(({ slidingWindow = 1, easing = "linear", ...props }, ref) => {
+  // Implementation is located in private-src
+  return <div ref={ref} {...props} />;
+});
+
+const displayName = "StaggerAnimation";
+StaggerAnimation.displayName = displayName;

packages/sdk-components-animation/src/stagger-animation.ws.ts

@@ -0,0 +1,25 @@
+import { StaggerAnimationIcon } from "@webstudio-is/icons/svg";
+import type { WsComponentMeta, WsComponentPropsMeta } from "@webstudio-is/sdk";
+import { props } from "./__generated__/stagger-animation.props";
+
+export const meta: WsComponentMeta = {
+  category: "animations",
+  type: "container",
+  description:
+    "Stagger animation allows you to animate children elements with a sliding window.",
+  icon: StaggerAnimationIcon,
+  order: 6,
+  label: "Stagger Animation",
+  constraints: [
+    { relation: "parent", component: { $eq: "AnimateChildren" } },
+    {
+      relation: "child",
+      text: false,
+    },
+  ],
+};
+
+export const propsMeta: WsComponentPropsMeta = {
+  props,
+  initialProps: ["slidingWindow", "easing"],
+};