@twick/visualizer 0.14.0 → 0.14.3

package/src/animations/rise.tsx

@@ -1,118 +1,157 @@
-import { all, waitFor, delay } from "@twick/core";
-import { AnimationParams } from "../helpers/types";
-
-/**
- * RiseAnimation combines vertical motion and opacity transitions
- * to create a "rising" (or "falling") appearance/disappearance effect.
- *
- * Available animation modes:
- * - "enter": Starts offset and transparent, moves into position while fading in.
- * - "exit": Waits, then moves out of position while fading out.
- * - "both": Enters, waits, and exits in a continuous sequence.
- *
- * @param elementRef - Reference to the main element to animate.
- * @param containerRef - Optional reference to a container element.
- * @param interval - Duration of movement and opacity transitions (default: 0.25).
- * @param duration - Total duration of the animation.
- * @param animate - Animation phase ("enter" | "exit" | "both").
- * @param direction - Direction to animate ("up" or "down").
- * @param intensity - Number of units to offset position vertically (default: 200).
- */
-export const RiseAnimation = {
-  name: "rise",
-
-  /**
-   * Generator function controlling the rise/fall animation.
-   */
-  *run({
-    elementRef,
-    containerRef,
-    interval = 0.25,
-    duration,
-    animate,
-    direction,
-    intensity = 200,
-  }: AnimationParams) {
-    // Use containerRef if provided, otherwise fallback to elementRef
-    const ref = containerRef ?? elementRef;
-
-    // Get the element's current position
-    const pos = ref().position();
-
-    let animationInterval = Math.min(interval, duration);
-
-    if (animate === "enter") {
-      // Start fully transparent
-      ref().opacity(0);
-
-      if (direction === "up") {
-        // Offset element below final position
-        ref().y(pos.y + intensity);
-        // Animate moving up while fading in
-        yield* all(
-          ref().opacity(1, animationInterval / 4),
-          ref().y(pos.y, animationInterval)
-        );
-      } else if (direction === "down") {
-        // Offset element above final position
-        ref().y(pos.y - intensity);
-        // Animate moving down while fading in
-        yield* all(
-          ref().opacity(1, animationInterval / 4),
-          ref().y(pos.y, animationInterval)
-        );
-      }
-    } else if (animate === "exit") {
-      // Wait until exit animation starts
-      yield* waitFor(duration - animationInterval);
-
-      if (direction === "up") {
-        // Animate moving up while fading out (opacity fades slightly after motion starts)
-        yield* all(
-          delay((3 * animationInterval) / 4, ref().opacity(0, animationInterval / 4)),
-          ref().y(pos.y - intensity, animationInterval)
-        );
-      } else if (direction === "down") {
-        // Animate moving down while fading out
-        yield* all(
-          delay((3 * animationInterval) / 4, ref().opacity(0, animationInterval / 4)),
-          ref().y(pos.y + intensity, animationInterval)
-        );
-      }
-    } else if (animate === "both") {
-      animationInterval = Math.min(interval, duration/2);
-      // Start fully transparent
-      ref().opacity(0);
-
-      if (direction === "up") {
-        // Enter animation: move up while fading in
-        ref().y(pos.y + intensity);
-        yield* all(
-          ref().opacity(1, animationInterval / 4),
-          ref().y(pos.y, animationInterval)
-        );
-        // Wait for the remaining duration
-        yield* waitFor(duration - animationInterval);
-        // Exit animation: move up further while fading out
-        yield* all(
-          delay((3 * animationInterval) / 4, ref().opacity(0, animationInterval / 4)),
-          ref().y(pos.y - intensity, animationInterval)
-        );
-      } else if (direction === "down") {
-        // Enter animation: move down while fading in
-        ref().y(pos.y - intensity);
-        yield* all(
-          ref().opacity(1, animationInterval / 4),
-          ref().y(pos.y, animationInterval)
-        );
-        // Wait for the remaining duration
-        yield* waitFor(duration - animationInterval);
-        // Exit animation: move down further while fading out
-        yield* all(
-          delay((3 * animationInterval) / 4, ref().opacity(0, animationInterval / 4)),
-          ref().y(pos.y + intensity, animationInterval)
-        );
-      }
-    }
-  },
-};
+import { all, delay, waitFor } from "@twick/core";
+import { AnimationParams } from "../helpers/types";
+
+/**
+ * @group RiseAnimation
+ * RiseAnimation combines vertical motion and opacity transitions to create a "rising"
+ * (or "falling") appearance/disappearance effect. Moves elements vertically with
+ * optional scaling effects for dynamic visual impact.
+ *
+ * Available animation modes:
+ * - "enter": Starts offset and transparent, moves into position while fading in
+ * - "exit": Waits, then moves out of position while fading out
+ * - "both": Enters, waits, and exits in a continuous sequence
+ *
+ * @param elementRef - Reference to the main element to animate
+ * @param containerRef - Optional reference to a container element
+ * @param interval - Duration of movement and opacity transitions in seconds
+ * @param duration - Total duration of the animation in seconds
+ * @param animate - Animation phase ("enter" | "exit" | "both")
+ * @param direction - Direction to animate ("up" or "down")
+ * @param intensity - Number of units to offset position vertically
+ *
+ * @example
+ * ```js
+ * // Rise up animation
+ * animation: {
+ *   name: "rise",
+ *   animate: "enter",
+ *   duration: 1.5,
+ *   direction: "up",
+ *   intensity: 0.8
+ * }
+ *
+ * // Fall down animation
+ * animation: {
+ *   name: "rise",
+ *   animate: "exit",
+ *   duration: 2,
+ *   direction: "down",
+ *   intensity: 300
+ * }
+ * ```
+ */
+export const RiseAnimation = {
+  name: "rise",
+
+  /**
+   * Generator function controlling the rise/fall animation.
+   * Handles vertical movement and opacity transitions based on direction and intensity.
+   *
+   * @param params - Animation parameters including element references, timing, and direction
+   * @returns Generator that controls the rise animation timeline
+   *
+   * @example
+   * ```js
+   * yield* RiseAnimation.run({
+   *   elementRef: myElement,
+   *   interval: 0.25,
+   *   duration: 1.5,
+   *   animate: "enter",
+   *   direction: "up",
+   *   intensity: 200
+   * });
+   * ```
+   */
+  *run({
+    elementRef,
+    containerRef,
+    interval = 0.25,
+    duration,
+    animate,
+    direction,
+    intensity = 200,
+  }: AnimationParams) {
+    // Use containerRef if provided, otherwise fallback to elementRef
+    const ref = containerRef ?? elementRef;
+
+    // Get the element's current position
+    const pos = ref().position();
+
+    let animationInterval = Math.min(interval, duration);
+
+    if (animate === "enter") {
+      // Start fully transparent
+      ref().opacity(0);
+
+      if (direction === "up") {
+        // Offset element below final position
+        ref().y(pos.y + intensity);
+        // Animate moving up while fading in
+        yield* all(
+          ref().opacity(1, animationInterval / 4),
+          ref().y(pos.y, animationInterval)
+        );
+      } else if (direction === "down") {
+        // Offset element above final position
+        ref().y(pos.y - intensity);
+        // Animate moving down while fading in
+        yield* all(
+          ref().opacity(1, animationInterval / 4),
+          ref().y(pos.y, animationInterval)
+        );
+      }
+    } else if (animate === "exit") {
+      // Wait until exit animation starts
+      yield* waitFor(duration - animationInterval);
+
+      if (direction === "up") {
+        // Animate moving up while fading out (opacity fades slightly after motion starts)
+        yield* all(
+          delay((3 * animationInterval) / 4, ref().opacity(0, animationInterval / 4)),
+          ref().y(pos.y - intensity, animationInterval)
+        );
+      } else if (direction === "down") {
+        // Animate moving down while fading out
+        yield* all(
+          delay((3 * animationInterval) / 4, ref().opacity(0, animationInterval / 4)),
+          ref().y(pos.y + intensity, animationInterval)
+        );
+      }
+    } else if (animate === "both") {
+      animationInterval = Math.min(interval, duration/2);
+      // Start fully transparent
+      ref().opacity(0);
+
+      if (direction === "up") {
+        // Enter animation: move up while fading in
+        ref().y(pos.y + intensity);
+        yield* all(
+          ref().opacity(1, animationInterval / 4),
+          ref().y(pos.y, animationInterval)
+        );
+        // Wait for the remaining duration
+        yield* waitFor(duration - animationInterval);
+        // Exit animation: move up further while fading out
+        yield* all(
+          delay((3 * animationInterval) / 4, ref().opacity(0, animationInterval / 4)),
+          ref().y(pos.y - intensity, animationInterval)
+        );
+      } else if (direction === "down") {
+        // Enter animation: move down while fading in
+        ref().y(pos.y - intensity);
+        yield* all(
+          ref().opacity(1, animationInterval / 4),
+          ref().y(pos.y, animationInterval)
+        );
+        // Wait for the remaining duration
+        yield* waitFor(duration - animationInterval);
+        // Exit animation: move down further while fading out
+        yield* all(
+          delay((3 * animationInterval) / 4, ref().opacity(0, animationInterval / 4)),
+          ref().y(pos.y + intensity, animationInterval)
+        );
+      }
+    }
+  },
+};

package/src/animations/succession.tsx

@@ -1,77 +1,112 @@
-import { all, delay, Vector2, waitFor } from "@twick/core";
-import { AnimationParams } from "../helpers/types";
-
-/**
- * SuccessionAnimation combines scaling and opacity transitions
- * to create an appearing and disappearing zoom effect.
- *
- * Available animation modes:
- * - "enter": Starts scaled down and transparent, then scales up while fading in.
- * - "exit": Waits, then scales down while fading out.
- * - "both": Scales up and fades in, waits, then scales down and fades out.
- *
- * @param elementRef - Reference to the main element to animate.
- * @param containerRef - Optional reference to a container element.
- * @param interval - Duration of scaling and opacity transitions.
- * @param duration - Total duration of the animation.
- * @param animate - Animation phase ("enter" | "exit" | "both").
- */
-export const SuccessionAnimation = {
-  name: "succession",
-
-  /**
-   * Generator function controlling the succession animation.
-   */
-  *run({
-    elementRef,
-    containerRef,
-    interval,
-    duration,
-    animate,
-  }: AnimationParams) {
-    // Use containerRef if provided, otherwise fallback to elementRef
-    const ref = containerRef ?? elementRef;
-
-    // Capture the element's original scale
-    const scale = ref().scale();
-
-    let animationInterval = Math.min(interval, duration);
-    if (animate === "enter") {
-      // Start fully transparent and scaled down to 50%
-      ref().opacity(0);
-      ref().scale(new Vector2(scale.x / 2, scale.y / 2));
-      // Animate scaling up to original size and fading in
-      yield* all(
-        ref().scale(scale, animationInterval),
-        ref().opacity(1, animationInterval / 2)
-      );
-
-    } else if (animate === "exit") {
-      // Wait until exit animation should start
-      yield* waitFor(duration - animationInterval);
-      // Animate scaling down to 50% and fading out (opacity starts after half the interval)
-      yield* all(
-        ref().scale(new Vector2(scale.x / 2, scale.y / 2), animationInterval),
-        delay(animationInterval / 2, ref().opacity(0, animationInterval / 2))
-      );
-
-    } else if (animate === "both") {
-      animationInterval = Math.min(interval, duration/2);
-      // Start fully transparent and scaled down to 50%
-      ref().opacity(0);
-      ref().scale(new Vector2(scale.x / 2, scale.y / 2));
-      // Animate scaling up and fading in
-      yield* all(
-        ref().scale(scale, animationInterval),
-        ref().opacity(1, animationInterval / 2)
-      );
-      // Wait for the remaining duration
-      yield* waitFor(duration - animationInterval);
-      // Animate scaling down and fading out
-      yield* all(
-        ref().scale(new Vector2(scale.x / 2, scale.y / 2), animationInterval),
-        delay(animationInterval / 2, ref().opacity(0, animationInterval / 2))
-      );
-    }
-  },
-};
+import { all, delay, Vector2, waitFor } from "@twick/core";
+import { AnimationParams } from "../helpers/types";
+
+/**
+ * @group SuccessionAnimation
+ * SuccessionAnimation combines scaling and opacity transitions to create an appearing
+ * and disappearing zoom effect. Creates dynamic zoom animations that draw attention
+ * to content with smooth scaling and fade transitions.
+ *
+ * Available animation modes:
+ * - "enter": Starts scaled down and transparent, then scales up while fading in
+ * - "exit": Waits, then scales down while fading out
+ * - "both": Scales up and fades in, waits, then scales down and fades out
+ *
+ * @param elementRef - Reference to the main element to animate
+ * @param containerRef - Optional reference to a container element
+ * @param interval - Duration of scaling and opacity transitions in seconds
+ * @param duration - Total duration of the animation in seconds
+ * @param animate - Animation phase ("enter" | "exit" | "both")
+ *
+ * @example
+ * ```js
+ * // Zoom in effect
+ * animation: {
+ *   name: "succession",
+ *   animate: "enter",
+ *   duration: 2,
+ *   interval: 0.5
+ * }
+ *
+ * // Zoom out effect
+ * animation: {
+ *   name: "succession",
+ *   animate: "exit",
+ *   duration: 1.5,
+ *   interval: 0.3
+ * }
+ * ```
+ */
+export const SuccessionAnimation = {
+  name: "succession",
+
+  /**
+   * Generator function controlling the succession animation.
+   * Handles scaling and opacity transitions to create zoom effects.
+   *
+   * @param params - Animation parameters including element references and timing
+   * @returns Generator that controls the succession animation timeline
+   *
+   * @example
+   * ```js
+   * yield* SuccessionAnimation.run({
+   *   elementRef: myElement,
+   *   interval: 0.5,
+   *   duration: 2,
+   *   animate: "enter"
+   * });
+   * ```
+   */
+  *run({
+    elementRef,
+    containerRef,
+    interval,
+    duration,
+    animate,
+  }: AnimationParams) {
+    // Use containerRef if provided, otherwise fallback to elementRef
+    const ref = containerRef ?? elementRef;
+
+    // Capture the element's original scale
+    const scale = ref().scale();
+
+    let animationInterval = Math.min(interval, duration);
+    if (animate === "enter") {
+      // Start fully transparent and scaled down to 50%
+      ref().opacity(0);
+      ref().scale(new Vector2(scale.x / 2, scale.y / 2));
+      // Animate scaling up to original size and fading in
+      yield* all(
+        ref().scale(scale, animationInterval),
+        ref().opacity(1, animationInterval / 2)
+      );
+
+    } else if (animate === "exit") {
+      // Wait until exit animation should start
+      yield* waitFor(duration - animationInterval);
+      // Animate scaling down to 50% and fading out (opacity starts after half the interval)
+      yield* all(
+        ref().scale(new Vector2(scale.x / 2, scale.y / 2), animationInterval),
+        delay(animationInterval / 2, ref().opacity(0, animationInterval / 2))
+      );
+
+    } else if (animate === "both") {
+      animationInterval = Math.min(interval, duration/2);
+      // Start fully transparent and scaled down to 50%
+      ref().opacity(0);
+      ref().scale(new Vector2(scale.x / 2, scale.y / 2));
+      // Animate scaling up and fading in
+      yield* all(
+        ref().scale(scale, animationInterval),
+        ref().opacity(1, animationInterval / 2)
+      );
+      // Wait for the remaining duration
+      yield* waitFor(duration - animationInterval);
+      // Animate scaling down and fading out
+      yield* all(
+        ref().scale(new Vector2(scale.x / 2, scale.y / 2), animationInterval),
+        delay(animationInterval / 2, ref().opacity(0, animationInterval / 2))
+      );
+    }
+  },
+};