@twick/visualizer 0.14.2 → 0.14.3

package/src/animations/rise.tsx

@@ -1,28 +1,67 @@
-import { all, waitFor, delay } from "@twick/core";
+import { all, delay, waitFor } from "@twick/core";
 import { AnimationParams } from "../helpers/types";
 
 /**
- * RiseAnimation combines vertical motion and opacity transitions
- * to create a "rising" (or "falling") appearance/disappearance effect.
+ * @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.
+ * - "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).
+ * @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,

package/src/animations/succession.tsx

@@ -2,25 +2,60 @@ 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.
+ * @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.
+ * - "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").
+ * @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,

package/src/elements/audio.element.tsx

@@ -1,9 +1,71 @@
 import { ElementParams } from "../helpers/types";
-import { createRef, waitFor } from "@twick/core";
+import { all, createRef, waitFor } from "@twick/core";
 import { Audio } from "@twick/2d";
+import { addAnimation } from "../helpers/element.utils";
+import { logger } from "../helpers/log.utils";
 
+/**
+ * @group AudioElement
+ * AudioElement creates and manages audio content in the visualizer scene.
+ * Handles audio playback, timing, and synchronization for background music,
+ * sound effects, and audio narration in video presentations.
+ *
+ * Features:
+ * - Audio playback with start/end timing control
+ * - Automatic play/pause management
+ * - Resource cleanup and memory management
+ * - Synchronization with visual elements
+ *
+ * @param containerRef - Reference to the container element
+ * @param element - Audio element configuration and properties
+ * @param view - The main scene view for rendering
+ * 
+ * @example
+ * ```js
+ * // Basic audio element
+ * {
+ *   id: "background-music",
+ *   type: "audio",
+ *   s: 0,
+ *   e: 30,
+ *   props: {
+ *     src: "music.mp3",
+ *     volume: 0.7
+ *   }
+ * }
+ * 
+ * // Sound effect with timing
+ * {
+ *   id: "sound-effect",
+ *   type: "audio",
+ *   s: 5,
+ *   e: 8,
+ *   props: {
+ *     src: "effect.wav",
+ *     volume: 1.0
+ *   }
+ * }
+ * ```
+ */
 export const AudioElement = {
   name: "audio",
+
+  /**
+   * Generator function that creates and manages audio elements in the scene.
+   * Handles audio creation, playback control, and cleanup.
+   *
+   * @param params - Element parameters including container reference, element config, and view
+   * @returns Generator that controls the audio element lifecycle
+   * 
+   * @example
+   * ```js
+   * yield* AudioElement.create({
+   *   containerRef: mainContainer,
+   *   element: audioConfig,
+   *   view: sceneView
+   * });
+   * ```
+   */
   *create({ containerRef, element, view }: ElementParams) {
     const elementRef = createRef<any>();
     yield* waitFor(element?.s);

package/src/elements/caption.element.tsx

@@ -5,8 +5,90 @@ import { splitPhraseTiming } from "../helpers/caption.utils";
 import { TRANSPARENT_COLOR } from "../helpers/constants";
 import { hexToRGB } from "../helpers/utils";
 
+/**
+ * @group CaptionElement
+ * CaptionElement creates and manages styled text overlays in the visualizer scene.
+ * Handles caption rendering, text effects, background styling, and timing
+ * for professional video presentations and content creation.
+ *
+ * Features:
+ * - Styled text with custom fonts, colors, and backgrounds
+ * - Word-by-word timing and animation
+ * - Background highlighting and styling options
+ * - Text effects and animations
+ * - Automatic timing and synchronization
+ *
+ * @param containerRef - Reference to the container element
+ * @param caption - Caption configuration including text, styling, and timing
+ * 
+ * @example
+ * ```js
+ * // Basic caption
+ * {
+ *   id: "welcome-caption",
+ *   type: "caption",
+ *   s: 2,
+ *   e: 8,
+ *   t: "Welcome to our presentation!",
+ *   props: {
+ *     colors: {
+ *       text: "#ffffff",
+ *       background: "rgba(0,0,0,0.7)"
+ *     },
+ *     font: {
+ *       family: "Arial",
+ *       size: 48,
+ *       weight: 600
+ *     }
+ *   }
+ * }
+ * 
+ * // Caption with background highlighting
+ * {
+ *   id: "highlighted-caption",
+ *   type: "caption",
+ *   s: 3,
+ *   e: 10,
+ *   t: "Important information",
+ *   capStyle: "highlight_bg",
+ *   props: {
+ *     colors: {
+ *       text: "#ffffff",
+ *       background: "rgba(255,0,0,0.8)"
+ *     },
+ *     font: {
+ *       family: "Helvetica",
+ *       size: 36,
+ *       weight: 700
+ *     },
+ *     bgOpacity: 0.9,
+ *     bgOffsetWidth: 20,
+ *     bgOffsetHeight: 10,
+ *     bgMargin: [10, 5],
+ *     bgRadius: 15,
+ *     bgPadding: [20, 15]
+ *   }
+ * }
+ * ```
+ */
 export const CaptionElement = {
   name: "caption",
+  
+  /**
+   * Generator function that creates and manages caption elements in the scene.
+   * Handles caption creation, word timing, styling, and text effects.
+   *
+   * @param params - Element parameters including container reference and caption config
+   * @returns Generator that controls the caption element lifecycle
+   * 
+   * @example
+   * ```js
+   * yield* CaptionElement.create({
+   *   containerRef: mainContainer,
+   *   caption: captionConfig
+   * });
+   * ```
+   */
   *create({ containerRef, caption }: ElementParams) {
     const words = splitPhraseTiming(caption);
     let phraseStart = 0;

package/src/elements/circle.element.tsx

@@ -3,9 +3,77 @@ import { all, createRef, waitFor } from "@twick/core";
 import { Circle } from "@twick/2d";
 import { addAnimation } from "../helpers/element.utils";
 
+/**
+ * @group CircleElement
+ * CircleElement creates and manages circular shape elements in the visualizer scene.
+ * Handles circle rendering, styling, and animations for UI elements and
+ * visual design components.
+ *
+ * Features:
+ * - Circle rendering with custom styling
+ * - Radius and position control
+ * - Color and border customization
+ * - Animation support
+ *
+ * @param containerRef - Reference to the container element
+ * @param element - Circle element configuration and properties
+ * @param view - The main scene view for rendering
+ * 
+ * @example
+ * ```js
+ * // Basic circle element
+ * {
+ *   id: "background-circle",
+ *   type: "circle",
+ *   s: 0,
+ *   e: 20,
+ *   props: {
+ *     radius: 100,
+ *     fill: "#000000",
+ *     opacity: 0.5
+ *   }
+ * }
+ * 
+ * // Circle with animation
+ * {
+ *   id: "animated-circle",
+ *   type: "circle",
+ *   s: 2,
+ *   e: 15,
+ *   props: {
+ *     radius: 50,
+ *     fill: "#ff0000",
+ *     stroke: "#ffffff",
+ *     strokeWidth: 2
+ *   },
+ *   animation: {
+ *     name: "fade",
+ *     animate: "enter",
+ *     duration: 2
+ *   }
+ * }
+ * ```
+ */
 export const CircleElement = {
-  name: "circle",
-  *create({ containerRef, element, view }: ElementParams) {
+    name: "circle",
+
+    /**
+     * Generator function that creates and manages circle elements in the scene.
+     * Handles circle creation, styling, and cleanup.
+     *
+     * @param params - Element parameters including container reference, element config, and view
+     * @returns Generator that controls the circle element lifecycle
+     * 
+     * @example
+     * ```js
+     * yield* CircleElement.create({
+     *   containerRef: mainContainer,
+     *   element: circleConfig,
+     *   view: sceneView
+     * });
+     * ```
+     */
+    *create({ containerRef, element, view }: ElementParams) {
     const elementRef = createRef<any>();
     yield* waitFor(element?.s);
     yield containerRef().add(

package/src/elements/icon.element.tsx

@@ -3,9 +3,77 @@ import { all, createRef, waitFor } from "@twick/core";
 import { Icon } from "@twick/2d";
 import { addAnimation } from "../helpers/element.utils";
 
+/**
+ * @group IconElement
+ * IconElement creates and manages icon elements in the visualizer scene.
+ * Handles icon rendering, styling, and animations for UI elements and
+ * visual design components.
+ *
+ * Features:
+ * - Icon rendering with custom styling
+ * - Size and position control
+ * - Color and opacity customization
+ * - Animation support
+ *
+ * @param containerRef - Reference to the container element
+ * @param element - Icon element configuration and properties
+ * @param view - The main scene view for rendering
+ * 
+ * @example
+ * ```js
+ * // Basic icon element
+ * {
+ *   id: "play-icon",
+ *   type: "icon",
+ *   s: 0,
+ *   e: 20,
+ *   props: {
+ *     icon: "play",
+ *     size: 64,
+ *     fill: "#ffffff"
+ *   }
+ * }
+ * 
+ * // Icon with animation
+ * {
+ *   id: "animated-icon",
+ *   type: "icon",
+ *   s: 2,
+ *   e: 15,
+ *   props: {
+ *     icon: "pause",
+ *     size: 48,
+ *     fill: "#ff0000",
+ *     opacity: 0.8
+ *   },
+ *   animation: {
+ *     name: "fade",
+ *     animate: "enter",
+ *     duration: 2
+ *   }
+ * }
+ * ```
+ */
 export const IconElement = {
-  name: "icon",
-  *create({ containerRef, element, view }: ElementParams) {
+    name: "icon",
+
+    /**
+     * Generator function that creates and manages icon elements in the scene.
+     * Handles icon creation, styling, and cleanup.
+     *
+     * @param params - Element parameters including container reference, element config, and view
+     * @returns Generator that controls the icon element lifecycle
+     * 
+     * @example
+     * ```js
+     * yield* IconElement.create({
+     *   containerRef: mainContainer,
+     *   element: iconConfig,
+     *   view: sceneView
+     * });
+     * ```
+     */
+    *create({ containerRef, element, view }: ElementParams) {
     const elementRef = createRef<any>();
     yield* waitFor(element?.s);
     yield containerRef().add(

package/src/elements/image.element.tsx

@@ -3,9 +3,90 @@ import { all, createRef, waitFor } from "@twick/core";
 import { Img, Rect } from "@twick/2d";
 import { addAnimation, addFrameEffect, fitElement } from "../helpers/element.utils";
 import { applyColorFilter } from "../helpers/filters";
+import { logger } from "../helpers/log.utils";
 
+/**
+ * @group ImageElement
+ * ImageElement creates and manages image content in the visualizer scene.
+ * Handles image rendering, frame effects, animations, and content fitting
+ * for professional image presentations and content creation.
+ *
+ * Features:
+ * - Image rendering with start/end timing control
+ * - Frame effects and animations
+ * - Object fit options for content scaling
+ * - Color filters and media effects
+ * - Automatic cleanup and resource management
+ *
+ * @param containerRef - Reference to the container element
+ * @param element - Image element configuration and properties
+ * @param view - The main scene view for rendering
+ * 
+ * @example
+ * ```js
+ * // Basic image element
+ * {
+ *   id: "main-image",
+ *   type: "image",
+ *   s: 0,
+ *   e: 15,
+ *   props: {
+ *     src: "image.jpg",
+ *     width: 1920,
+ *     height: 1080
+ *   },
+ *   objectFit: "cover"
+ * }
+ * 
+ * // Image with frame effect and animation
+ * {
+ *   id: "framed-image",
+ *   type: "image",
+ *   s: 2,
+ *   e: 20,
+ *   props: { 
+ *     src: "content.jpg",
+ *     mediaFilter: "sepia"
+ *   },
+ *   animation: {
+ *     name: "fade",
+ *     animate: "enter",
+ *     duration: 2
+ *   },
+ *   frameEffects: [{
+ *     name: "circle",
+ *     s: 2,
+ *     e: 20,
+ *     props: {
+ *       frameSize: [500, 500],
+ *       frameShape: "circle",
+ *       framePosition: { x: 960, y: 540 },
+ *       radius: 250,
+ *       objectFit: "cover"
+ *     }
+ *   }]
+ * }
+ * ```
+ */
 export const ImageElement = {
   name: "image",
+
+  /**
+   * Generator function that creates and manages image elements in the scene.
+   * Handles image creation, frame setup, animations, effects, and cleanup.
+   *
+   * @param params - Element parameters including container reference, element config, and view
+   * @returns Generator that controls the image element lifecycle
+   * 
+   * @example
+   * ```js
+   * yield* ImageElement.create({
+   *   containerRef: mainContainer,
+   *   element: imageConfig,
+   *   view: sceneView
+   * });
+   * ```
+   */
   *create({ containerRef, element, view }: ElementParams) {
     yield* waitFor(element?.s);
     const frameContainerRef = createRef<any>();

package/src/elements/index.ts

@@ -0,0 +1,14 @@
+/**
+ * @group Elements
+ * @description Visual components for creating scenes and content
+ */
+
+export { VideoElement } from './video.element';
+export { ImageElement } from './image.element';
+export { AudioElement } from './audio.element';
+export { TextElement } from './text.element';
+export { CaptionElement } from './caption.element';
+export { RectElement } from './rect.element';
+export { CircleElement } from './circle.element';
+export { IconElement } from './icon.element';
+export { SceneElement } from './scene.element';

package/src/elements/rect.element.tsx

@@ -4,9 +4,79 @@ import { Rect } from "@twick/2d";
 import { addAnimation } from "../helpers/element.utils";
 import { logger } from "../helpers/log.utils";
 
+/**
+ * @group RectElement
+ * RectElement creates and manages rectangular shape elements in the visualizer scene.
+ * Handles rectangle rendering, styling, and animations for UI elements and
+ * visual design components.
+ *
+ * Features:
+ * - Rectangle rendering with custom styling
+ * - Size and position control
+ * - Color and border customization
+ * - Animation support
+ *
+ * @param containerRef - Reference to the container element
+ * @param element - Rectangle element configuration and properties
+ * @param view - The main scene view for rendering
+ * 
+ * @example
+ * ```js
+ * // Basic rectangle element
+ * {
+ *   id: "background-rect",
+ *   type: "rect",
+ *   s: 0,
+ *   e: 20,
+ *   props: {
+ *     width: 800,
+ *     height: 600,
+ *     fill: "#000000",
+ *     opacity: 0.5
+ *   }
+ * }
+ * 
+ * // Rectangle with animation
+ * {
+ *   id: "animated-rect",
+ *   type: "rect",
+ *   s: 2,
+ *   e: 15,
+ *   props: {
+ *     width: 400,
+ *     height: 300,
+ *     fill: "#ff0000",
+ *     stroke: "#ffffff",
+ *     strokeWidth: 2
+ *   },
+ *   animation: {
+ *     name: "fade",
+ *     animate: "enter",
+ *     duration: 2
+ *   }
+ * }
+ * ```
+ */
 export const RectElement = {
-  name: "rect",
-  *create({ containerRef, element, view }: ElementParams) {
+    name: "rect",
+
+    /**
+     * Generator function that creates and manages rectangle elements in the scene.
+     * Handles rectangle creation, styling, and cleanup.
+     *
+     * @param params - Element parameters including container reference, element config, and view
+     * @returns Generator that controls the rectangle element lifecycle
+     * 
+     * @example
+     * ```js
+     * yield* RectElement.create({
+     *   containerRef: mainContainer,
+     *   element: rectConfig,
+     *   view: sceneView
+     * });
+     * ```
+     */
+    *create({ containerRef, element, view }: ElementParams) {
     const elementRef = createRef<any>();
     yield* waitFor(element?.s);
     logger(`RectElement: ${JSON.stringify(element)}`);