@twick/visualizer 0.14.0 → 0.14.3

package/src/animations/fade.tsx

@@ -1,60 +1,173 @@
-import { waitFor } from "@twick/core";
-import { AnimationParams } from "../helpers/types";
-
-/**
- * FadeAnimation applies a simple fade-in and fade-out effect
- * by adjusting opacity.
- *
- * Available animation modes:
- * - "enter": Starts transparent and fades in to fully opaque.
- * - "exit": Waits, then fades out to transparent.
- * - "both": Fades in, waits, then fades out.
- *
- * @param elementRef - Reference to the main element to animate.
- * @param containerRef - Optional reference to a container element.
- * @param interval - Duration of the fade transition (in frames or ms).
- * @param duration - Total duration of the animation.
- * @param animate - Animation phase ("enter" | "exit" | "both").
- */
-export const FadeAnimation = {
-  name: "fade",
-
-  /**
-   * Generator function controlling the fade animation.
-   */
-  *run({
-    elementRef,
-    containerRef,
-    interval,
-    duration,
-    animate,
-  }: AnimationParams) {
-    // Use containerRef if provided, otherwise fallback to elementRef
-    const ref = containerRef ?? elementRef;
-
-    let animationInterval = Math.min(interval, duration);
-    if (animate === "enter") {
-      // Start fully transparent
-      ref().opacity(0);
-      // Fade in to full opacity over 'interval'
-      yield* ref().opacity(1, animationInterval);
-
-    } else if (animate === "exit") {
-      // Wait until it's time to start fading out
-      yield* waitFor(duration - animationInterval);
-      // Fade out to transparent over 'interval'
-      yield* ref().opacity(0, animationInterval);
-
-    } else if (animate === "both") {
-      animationInterval = Math.min(interval, duration/2);
-      // Start fully transparent
-      ref().opacity(0);
-      // Fade in to full opacity
-      yield* ref().opacity(1, animationInterval);
-      // Wait for the remaining duration before fade-out
-      yield* waitFor(duration - animationInterval);
-      // Fade out to transparent
-      yield* ref().opacity(0, animationInterval);
-    }
-  },
-};
+import { waitFor } from "@twick/core";
+import { AnimationParams } from "../helpers/types";
+
+/**
+ * @group FadeAnimation
+ * @description Simple fade-in and fade-out effects for smooth element transitions
+ * 
+ * FadeAnimation applies a simple fade-in and fade-out effect by adjusting opacity.
+ * Creates smooth opacity transitions for elements entering or exiting the scene.
+ * Perfect for subtle, professional animations that don't distract from content.
+ * 
+ * ## Animation Modes
+ * 
+ * - **"enter"**: Starts transparent and fades in to fully opaque
+ * - **"exit"**: Waits, then fades out to transparent  
+ * - **"both"**: Fades in, waits, then fades out
+ * 
+ * ## Use Cases
+ * 
+ * - **Text overlays**: Smooth introduction of captions and titles
+ * - **Background elements**: Subtle scene transitions
+ * - **UI components**: Professional interface animations
+ * - **Content reveals**: Gentle disclosure of information
+ * 
+ * ## Best Practices
+ * 
+ * - **Duration**: 1-3 seconds for most use cases
+ * - **Timing**: Use "enter" for introductions, "exit" for conclusions
+ * - **Combination**: Pair with other animations for complex effects
+ * - **Performance**: Lightweight and efficient for multiple elements
+ * 
+ * ## Integration Examples
+ * 
+ * ### Basic Text Fade
+ * ```js
+ * {
+ *   id: "welcome-text",
+ *   type: "text",
+ *   s: 0, e: 5,
+ *   t: "Welcome!",
+ *   animation: {
+ *     name: "fade",
+ *     animate: "enter",
+ *     duration: 2
+ *   }
+ * }
+ * ```
+ * 
+ * ### Video with Fade Transition
+ * ```js
+ * {
+ *   id: "intro-video",
+ *   type: "video",
+ *   s: 0, e: 10,
+ *   props: { src: "intro.mp4" },
+ *   animation: {
+ *     name: "fade",
+ *     animate: "both",
+ *     duration: 3,
+ *     interval: 1
+ *   }
+ * }
+ * ```
+ * 
+ * ### Multi-Element Fade Sequence
+ * ```js
+ * // Fade in multiple elements with staggered timing
+ * const elements = [
+ *   {
+ *     id: "title",
+ *     type: "text",
+ *     s: 0, e: 8,
+ *     t: "Main Title",
+ *     animation: { name: "fade", animate: "enter", duration: 2 }
+ *   },
+ *   {
+ *     id: "subtitle", 
+ *     type: "text",
+ *     s: 1, e: 8,
+ *     t: "Subtitle",
+ *     animation: { name: "fade", animate: "enter", duration: 2 }
+ *   },
+ *   {
+ *     id: "background",
+ *     type: "rect",
+ *     s: 0, e: 10,
+ *     props: { fill: "#000000", opacity: 0.5 },
+ *     animation: { name: "fade", animate: "enter", duration: 1.5 }
+ *   }
+ * ];
+ * ```
+ * 
+ * @param elementRef - Reference to the main element to animate
+ * @param containerRef - Optional reference to a container element
+ * @param duration - Duration of the fade transition in seconds
+ * @param totalDuration - Total duration of the animation in seconds
+ * @param animate - Animation phase ("enter" | "exit" | "both")
+ * 
+ * @example
+ * ```js
+ * // Basic fade-in animation
+ * animation: {
+ *   name: "fade",
+ *   animate: "enter",
+ *   duration: 2,
+ *   direction: "center"
+ * }
+ * 
+ * // Fade in and out
+ * animation: {
+ *   name: "fade",
+ *   animate: "both",
+ *   duration: 3,
+ *   interval: 1
+ * }
+ * ```
+ */
+export const FadeAnimation = {
+  name: "fade",
+
+  /**
+   * Generator function controlling the fade animation.
+   * Handles opacity transitions based on the specified animation mode.
+   *
+   * @param params - Animation parameters including element references and timing
+   * @returns Generator that controls the fade animation timeline
+   * 
+   * @example
+   * ```js
+   * yield* FadeAnimation.run({
+   *   elementRef: myElement,
+   *   interval: 1,
+   *   duration: 3,
+   *   animate: "enter"
+   * });
+   * ```
+   */
+  *run({
+    elementRef,
+    containerRef,
+    interval,
+    duration,
+    animate,
+  }: AnimationParams) {
+    // Use containerRef if provided, otherwise fallback to elementRef
+    const ref = containerRef ?? elementRef;
+
+    let animationInterval = Math.min(interval, duration);
+    if (animate === "enter") {
+      // Start fully transparent
+      ref().opacity(0);
+      // Fade in to full opacity over 'interval'
+      yield* ref().opacity(1, animationInterval);
+
+    } else if (animate === "exit") {
+      // Wait until it's time to start fading out
+      yield* waitFor(duration - animationInterval);
+      // Fade out to transparent over 'interval'
+      yield* ref().opacity(0, animationInterval);
+
+    } else if (animate === "both") {
+      animationInterval = Math.min(interval, duration/2);
+      // Start fully transparent
+      ref().opacity(0);
+      // Fade in to full opacity
+      yield* ref().opacity(1, animationInterval);
+      // Wait for the remaining duration before fade-out
+      yield* waitFor(duration - animationInterval);
+      // Fade out to transparent
+      yield* ref().opacity(0, animationInterval);
+    }
+  },
+};

package/src/animations/index.ts

@@ -0,0 +1,12 @@
+/**
+ * @group Animations
+ * @description Motion effects and transitions for elements
+ */
+
+export { FadeAnimation } from './fade';
+export { RiseAnimation } from './rise';
+export { BlurAnimation } from './blur';
+export { BreatheAnimation } from './breathe';
+export { SuccessionAnimation } from './succession';
+export { PhotoRiseAnimation } from './photo-rise';
+export { PhotoZoomAnimation } from './photo-zoom';

package/src/animations/photo-rise.tsx

@@ -1,66 +1,103 @@
-import { AnimationParams } from "../helpers/types";
-
-/**
- * PhotoRiseAnimation applies a smooth directional movement to a photo element.
- *
- * Behavior:
- * - Starts offset in a given direction (up, down, left, or right).
- * - Animates back to the original position over the specified duration.
- *
- * Available directions:
- * - "up": Starts below and moves upward.
- * - "down": Starts above and moves downward.
- * - "left": Starts to the right and moves leftward.
- * - "right": Starts to the left and moves rightward.
- *
- * @param elementRef - Reference to the photo element to animate.
- * @param containerRef - Optional reference to a container element (required for this animation).
- * @param direction - Direction of the movement ("up" | "down" | "left" | "right").
- * @param duration - Duration of the movement animation.
- * @param intensity - Offset distance in pixels (default: 200).
- */
-export const PhotoRiseAnimation = {
-  name: "photo-rise",
-
-  /**
-   * Generator function controlling the photo rise animation.
-   */
-  *run({
-    elementRef,
-    containerRef,
-    direction,
-    duration,
-    intensity = 200,
-  }: AnimationParams) {
-    // Only run if a containerRef is provided
-    if (containerRef) {
-      // Get the element's current position
-      const pos = elementRef().position();
-
-      if (direction === "up") {
-        // Start offset below
-        elementRef().y(pos.y + intensity);
-        // Animate moving upward to the original position
-        yield* elementRef().y(pos.y, duration);
-
-      } else if (direction === "down") {
-        // Start offset above
-        elementRef().y(pos.y - intensity);
-        // Animate moving downward to the original position
-        yield* elementRef().y(pos.y, duration);
-
-      } else if (direction === "left") {
-        // Start offset to the right
-        elementRef().x(pos.x + intensity);
-        // Animate moving left to the original position
-        yield* elementRef().x(pos.x, duration);
-
-      } else if (direction === "right") {
-        // Start offset to the left
-        elementRef().x(pos.x - intensity);
-        // Animate moving right to the original position
-        yield* elementRef().x(pos.x, duration);
-      }
-    }
-  },
-};
+import { AnimationParams } from "../helpers/types";
+
+/**
+ * @group PhotoRiseAnimation
+ * PhotoRiseAnimation applies a smooth directional movement to a photo element.
+ * Creates elegant slide-in animations that bring photos into view from any direction.
+ * Perfect for photo galleries, presentations, and content reveals.
+ *
+ * Behavior:
+ * - Starts offset in a given direction (up, down, left, or right)
+ * - Animates back to the original position over the specified duration
+ *
+ * Available directions:
+ * - "up": Starts below and moves upward
+ * - "down": Starts above and moves downward
+ * - "left": Starts to the right and moves leftward
+ * - "right": Starts to the left and moves rightward
+ *
+ * @param elementRef - Reference to the photo element to animate
+ * @param containerRef - Optional reference to a container element (required for this animation)
+ * @param direction - Direction of the movement ("up" | "down" | "left" | "right")
+ * @param duration - Duration of the movement animation in seconds
+ * @param intensity - Offset distance in pixels (default: 200)
+ * 
+ * @example
+ * ```js
+ * // Slide in from bottom
+ * animation: {
+ *   name: "photo-rise",
+ *   direction: "up",
+ *   duration: 1.5,
+ *   intensity: 300
+ * }
+ * 
+ * // Slide in from left
+ * animation: {
+ *   name: "photo-rise",
+ *   direction: "left",
+ *   duration: 2,
+ *   intensity: 400
+ * }
+ * ```
+ */
+export const PhotoRiseAnimation = {
+  name: "photo-rise",
+
+  /**
+   * Generator function controlling the photo rise animation.
+   * Handles directional movement animations for photo elements.
+   *
+   * @param params - Animation parameters including element references and direction
+   * @returns Generator that controls the photo rise animation timeline
+   * 
+   * @example
+   * ```js
+   * yield* PhotoRiseAnimation.run({
+   *   elementRef: photoElement,
+   *   containerRef: container,
+   *   direction: "up",
+   *   duration: 1.5,
+   *   intensity: 200
+   * });
+   * ```
+   */
+  *run({
+    elementRef,
+    containerRef,
+    direction,
+    duration,
+    intensity = 200,
+  }: AnimationParams) {
+    // Only run if a containerRef is provided
+    if (containerRef) {
+      // Get the element's current position
+      const pos = elementRef().position();
+
+      if (direction === "up") {
+        // Start offset below
+        elementRef().y(pos.y + intensity);
+        // Animate moving upward to the original position
+        yield* elementRef().y(pos.y, duration);
+
+      } else if (direction === "down") {
+        // Start offset above
+        elementRef().y(pos.y - intensity);
+        // Animate moving downward to the original position
+        yield* elementRef().y(pos.y, duration);
+
+      } else if (direction === "left") {
+        // Start offset to the right
+        elementRef().x(pos.x + intensity);
+        // Animate moving left to the original position
+        yield* elementRef().x(pos.x, duration);
+
+      } else if (direction === "right") {
+        // Start offset to the left
+        elementRef().x(pos.x - intensity);
+        // Animate moving right to the original position
+        yield* elementRef().x(pos.x, duration);
+      }
+    }
+  },
+};

package/src/animations/photo-zoom.tsx

@@ -1,73 +1,109 @@
-import { Vector2 } from "@twick/core";
-import { AnimationParams } from "../helpers/types";
-
-/**
- * PhotoZoomAnimation applies a smooth zoom-in or zoom-out effect
- * on a photo element.
- *
- * Available animation modes:
- * - "in": Starts zoomed in and smoothly scales back to the original size.
- * - "out": Starts at normal size and smoothly scales up to the target zoom level.
- *
- * @param elementRef - Reference to the photo element to animate.
- * @param containerRef - Optional reference to a container element (required for this animation).
- * @param mode - Animation phase ("in" | "out").
- * @param duration - Duration of the zoom animation.
- * @param intensity - Zoom scale multiplier (default: 1.5).
- */
-export const PhotoZoomAnimation = {
-  name: "photo-zoom",
-
-  /**
-   * Generator function controlling the photo zoom animation.
-   */
-  *run({
-    elementRef,
-    containerRef,
-    mode,
-    duration,
-    intensity = 1.5,
-  }: AnimationParams) {
-    // Only run if a containerRef is provided
-    if (containerRef) {
-      // Get the element's current scale
-      const elementScale = elementRef().scale();
-
-      if (mode === "in") {
-        // Instantly set to zoomed-in scale
-        yield elementRef().scale(
-          new Vector2(
-            elementScale.x * intensity,
-            elementScale.y * intensity
-          )
-        );
-        // Smoothly scale back to original size over 'duration'
-        yield* elementRef().scale(
-          new Vector2(
-            elementScale.x,
-            elementScale.y
-          ),
-          duration
-        );
-      }
-
-      if (mode === "out") {
-        // Start at original scale
-        elementRef().scale(
-          new Vector2(
-            elementScale.x,
-            elementScale.y
-          )
-        );
-        // Smoothly scale up to zoomed-in scale over 'duration'
-        yield* elementRef().scale(
-          new Vector2(
-            elementScale.x * intensity,
-            elementScale.y * intensity
-          ),
-          duration
-        );
-      }
-    }
-  },
-};
+import { Vector2 } from "@twick/core";
+import { AnimationParams } from "../helpers/types";
+
+/**
+ * @group PhotoZoomAnimation
+ * PhotoZoomAnimation applies a smooth zoom-in or zoom-out effect on a photo element.
+ * Creates dynamic zoom effects that add depth and focus to photo content.
+ * Perfect for highlighting details or creating cinematic photo presentations.
+ *
+ * Available animation modes:
+ * - "in": Starts zoomed in and smoothly scales back to the original size
+ * - "out": Starts at normal size and smoothly scales up to the target zoom level
+ *
+ * @param elementRef - Reference to the photo element to animate
+ * @param containerRef - Optional reference to a container element (required for this animation)
+ * @param mode - Animation phase ("in" | "out")
+ * @param duration - Duration of the zoom animation in seconds
+ * @param intensity - Zoom scale multiplier (default: 1.5)
+ * 
+ * @example
+ * ```js
+ * // Zoom in effect
+ * animation: {
+ *   name: "photo-zoom",
+ *   mode: "in",
+ *   duration: 2,
+ *   intensity: 1.8
+ * }
+ * 
+ * // Zoom out effect
+ * animation: {
+ *   name: "photo-zoom",
+ *   mode: "out",
+ *   duration: 1.5,
+ *   intensity: 2.0
+ * }
+ * ```
+ */
+export const PhotoZoomAnimation = {
+  name: "photo-zoom",
+
+  /**
+   * Generator function controlling the photo zoom animation.
+   * Handles smooth scaling transitions for zoom effects on photo elements.
+   *
+   * @param params - Animation parameters including element references and zoom settings
+   * @returns Generator that controls the photo zoom animation timeline
+   * 
+   * @example
+   * ```js
+   * yield* PhotoZoomAnimation.run({
+   *   elementRef: photoElement,
+   *   containerRef: container,
+   *   mode: "in",
+   *   duration: 2,
+   *   intensity: 1.5
+   * });
+   * ```
+   */
+  *run({
+    elementRef,
+    containerRef,
+    mode,
+    duration,
+    intensity = 1.5,
+  }: AnimationParams) {
+    // Only run if a containerRef is provided
+    if (containerRef) {
+      // Get the element's current scale
+      const elementScale = elementRef().scale();
+
+      if (mode === "in") {
+        // Instantly set to zoomed-in scale
+        yield elementRef().scale(
+          new Vector2(
+            elementScale.x * intensity,
+            elementScale.y * intensity
+          )
+        );
+        // Smoothly scale back to original size over 'duration'
+        yield* elementRef().scale(
+          new Vector2(
+            elementScale.x,
+            elementScale.y
+          ),
+          duration
+        );
+      }
+
+      if (mode === "out") {
+        // Start at original scale
+        elementRef().scale(
+          new Vector2(
+            elementScale.x,
+            elementScale.y
+          )
+        );
+        // Smoothly scale up to zoomed-in scale over 'duration'
+        yield* elementRef().scale(
+          new Vector2(
+            elementScale.x * intensity,
+            elementScale.y * intensity
+          ),
+          duration
+        );
+      }
+    }
+  },
+};