@twick/visualizer 0.14.2 → 0.14.4

package/src/elements/scene.element.tsx

@@ -6,24 +6,92 @@ import { ImageElement } from "./image.element";
 import { VideoElement } from "./video.element";
 import { logger } from "../helpers/log.utils";
 
+/**
+ * @group SceneElement
+ * SceneElement creates and manages scene container elements in the visualizer.
+ * Handles scene setup, background configuration, and container management
+ * for organizing visual content and elements.
+ *
+ * Features:
+ * - Scene container creation and management
+ * - Background and environment setup
+ * - Element organization and grouping
+ * - Scene-level animations and effects
+ *
+ * @param containerRef - Reference to the container element
+ * @param element - Scene element configuration and properties
+ * @param view - The main scene view for rendering
+ * 
+ * @example
+ * ```js
+ * // Basic scene element
+ * {
+ *   id: "main-scene",
+ *   type: "scene",
+ *   s: 0,
+ *   e: 30,
+ *   props: {
+ *     backgroundColor: "#000000",
+ *     width: 1920,
+ *     height: 1080
+ *   }
+ * }
+ * 
+ * // Scene with background and effects
+ * {
+ *   id: "animated-scene",
+ *   type: "scene",
+ *   s: 0,
+ *   e: 60,
+ *   props: {
+ *     backgroundColor: "linear-gradient(45deg, #ff0000, #00ff00)",
+ *     width: 1920,
+ *     height: 1080,
+ *     opacity: 0.9
+ *   },
+ *   animation: {
+ *     name: "fade",
+ *     animate: "enter",
+ *     duration: 3
+ *   }
+ * }
+ * ```
+ */
 export const SceneElement = {
-  name: "scene",
-  *create({ containerRef, element, view }: ElementParams) {
-    yield* waitFor(element?.s);
-    const mediaContainerRef = createRef<any>();
-    logger(`SceneElement: ${JSON.stringify(element)}`);
-    yield containerRef().add(
-      <Rect
-        ref={mediaContainerRef}
-        fill={element.backgroundColor ?? DEFAULT_BACKGROUND_COLOR}
-        size={"100%"}
-      />
-    );
-    if (element.type === ELEMENT_TYPES.IMAGE) {
-      yield* ImageElement.create({ containerRef, element, view });
-    } else if (element.type === ELEMENT_TYPES.VIDEO) {
-      yield* VideoElement.create({ containerRef, element, view });
-    }
-    yield mediaContainerRef().remove();
-  },
+    name: "scene",
+
+    /**
+     * Generator function that creates and manages scene elements.
+     * Handles scene creation, setup, and cleanup.
+     *
+     * @param params - Element parameters including container reference, element config, and view
+     * @returns Generator that controls the scene element lifecycle
+     * 
+     * @example
+     * ```js
+     * yield* SceneElement.create({
+     *   containerRef: mainContainer,
+     *   element: sceneConfig,
+     *   view: sceneView
+     * });
+     * ```
+     */
+    *create({ containerRef, element, view }: ElementParams) {
+        yield* waitFor(element?.s);
+        const mediaContainerRef = createRef<any>();
+        logger(`SceneElement: ${JSON.stringify(element)}`);
+        yield containerRef().add(
+            <Rect
+                ref={mediaContainerRef}
+                fill={element.backgroundColor ?? DEFAULT_BACKGROUND_COLOR}
+                size={"100%"}
+            />
+        );
+        if (element.type === ELEMENT_TYPES.IMAGE) {
+            yield* ImageElement.create({ containerRef, element, view });
+        } else if (element.type === ELEMENT_TYPES.VIDEO) {
+            yield* VideoElement.create({ containerRef, element, view });
+        }
+        yield mediaContainerRef().remove();
+    },
 };

package/src/elements/text.element.tsx

@@ -2,9 +2,83 @@ import { ElementParams } from "../helpers/types";
 import { all, createRef, waitFor } from "@twick/core";
 import { Txt } from "@twick/2d";
 import { addAnimation, addTextEffect } from "../helpers/element.utils";
+import { logger } from "../helpers/log.utils";
 
+/**
+ * @group TextElement
+ * TextElement creates and manages text content in the visualizer scene.
+ * Handles text rendering, animations, and text effects for dynamic
+ * text presentations and content creation.
+ *
+ * Features:
+ * - Text rendering with custom styling and fonts
+ * - Text animations and effects
+ * - Timing control and synchronization
+ * - Automatic cleanup and resource management
+ *
+ * @param containerRef - Reference to the container element
+ * @param element - Text element configuration and properties
+ * @param view - The main scene view for rendering
+ * 
+ * @example
+ * ```js
+ * // Basic text element
+ * {
+ *   id: "welcome-text",
+ *   type: "text",
+ *   s: 0,
+ *   e: 10,
+ *   t: "Welcome to our presentation!",
+ *   props: {
+ *     fill: "#ffffff",
+ *     fontSize: 48,
+ *     fontFamily: "Arial"
+ *   }
+ * }
+ * 
+ * // Text with animation and effects
+ * {
+ *   id: "animated-text",
+ *   type: "text",
+ *   s: 2,
+ *   e: 15,
+ *   t: "Animated text content",
+ *   props: {
+ *     fill: "#ff0000",
+ *     fontSize: 36,
+ *     fontFamily: "Helvetica"
+ *   },
+ *   animation: {
+ *     name: "fade",
+ *     animate: "enter",
+ *     duration: 2
+ *   },
+ *   textEffect: {
+ *     name: "typewriter",
+ *     duration: 3
+ *   }
+ * }
+ * ```
+ */
 export const TextElement = {
     name: "text",
+
+    /**
+     * Generator function that creates and manages text elements in the scene.
+     * Handles text creation, animations, effects, and cleanup.
+     *
+     * @param params - Element parameters including container reference, element config, and view
+     * @returns Generator that controls the text element lifecycle
+     * 
+     * @example
+     * ```js
+     * yield* TextElement.create({
+     *   containerRef: mainContainer,
+     *   element: textConfig,
+     *   view: sceneView
+     * });
+     * ```
+     */
     *create({ containerRef, element, view }: ElementParams) { 
     const elementRef = createRef<any>();
 

package/src/elements/video.element.tsx

@@ -1,11 +1,230 @@
 import { ElementParams } from "../helpers/types";
 import { all, createRef, waitFor } from "@twick/core";
-import { Rect, Video } from "@twick/2d";
+import { Video, Rect } from "@twick/2d";
 import { addAnimation, addFrameEffect, fitElement } from "../helpers/element.utils";
 import { applyColorFilter } from "../helpers/filters";
+import { logger } from "../helpers/log.utils";
 
+/**
+ * @group VideoElement
+ * @description Professional video content management with effects and animations
+ * 
+ * VideoElement creates and manages video content in the visualizer scene.
+ * Handles video playback, frame effects, animations, and content fitting
+ * for professional video presentations and content creation.
+ * 
+ * ## Key Features
+ * 
+ * - **Video playback** with start/end timing control
+ * - **Frame effects** and animations for visual enhancement
+ * - **Object fit options** for content scaling (contain, cover, fill, none)
+ * - **Color filters** and media effects for artistic styling
+ * - **Automatic cleanup** and resource management
+ * - **Synchronization** with other scene elements
+ * 
+ * ## Use Cases
+ * 
+ * - **Main content videos**: Primary video content with effects
+ * - **Background videos**: Ambient video backgrounds
+ * - **Video overlays**: Picture-in-picture style content
+ * - **Video transitions**: Smooth scene-to-scene transitions
+ * - **Video effects**: Artistic and creative video manipulation
+ * 
+ * ## Best Practices
+ * 
+ * - **Format**: Use MP4 with H.264 encoding for best compatibility
+ * - **Resolution**: Match scene dimensions or use appropriate object-fit
+ * - **Performance**: Optimize video files for web delivery
+ * - **Timing**: Set precise start/end times for synchronization
+ * - **Effects**: Combine with animations and frame effects for impact
+ * 
+ * ## Integration Examples
+ * 
+ * ### Basic Video Element
+ * ```js
+ * {
+ *   id: "main-video",
+ *   type: "video",
+ *   s: 0, e: 15,
+ *   props: {
+ *     src: "video.mp4",
+ *     width: 1920,
+ *     height: 1080
+ *   },
+ *   objectFit: "cover"
+ * }
+ * ```
+ * 
+ * ### Video with Animation
+ * ```js
+ * {
+ *   id: "intro-video",
+ *   type: "video",
+ *   s: 0, e: 10,
+ *   props: { src: "intro.mp4" },
+ *   animation: {
+ *     name: "fade",
+ *     animate: "enter",
+ *     duration: 2
+ *   },
+ *   objectFit: "contain"
+ * }
+ * ```
+ * 
+ * ### Video with Frame Effect
+ * ```js
+ * {
+ *   id: "framed-video",
+ *   type: "video",
+ *   s: 2, e: 20,
+ *   props: { src: "content.mp4" },
+ *   frameEffects: [{
+ *     name: "circle",
+ *     s: 2, e: 20,
+ *     props: {
+ *       frameSize: [500, 500],
+ *       frameShape: "circle",
+ *       framePosition: { x: 960, y: 540 },
+ *       radius: 250,
+ *       objectFit: "cover",
+ *       transitionDuration: 1.5
+ *     }
+ *   }]
+ * }
+ * ```
+ * 
+ * ### Complex Video Scene
+ * ```js
+ * // Multi-track video scene with overlays
+ * const videoScene = {
+ *   backgroundColor: "#000000",
+ *   playerId: "video-player",
+ *   properties: { width: 1920, height: 1080 },
+ *   tracks: [
+ *     {
+ *       id: "background",
+ *       type: "video",
+ *       elements: [{
+ *         id: "bg-video",
+ *         type: "video",
+ *         s: 0, e: 30,
+ *         props: { src: "background.mp4", opacity: 0.3 },
+ *         objectFit: "cover"
+ *       }]
+ *     },
+ *     {
+ *       id: "main-content",
+ *       type: "video", 
+ *       elements: [
+ *         {
+ *           id: "main-video",
+ *           type: "video",
+ *           s: 2, e: 25,
+ *           props: { src: "main-content.mp4" },
+ *           animation: {
+ *             name: "fade",
+ *             animate: "enter",
+ *             duration: 2
+ *           },
+ *           frameEffects: [{
+ *             name: "rect",
+ *             s: 2, e: 25,
+ *             props: {
+ *               frameSize: [800, 600],
+ *               frameShape: "rect",
+ *               framePosition: { x: 960, y: 540 },
+ *               radius: 20,
+ *               objectFit: "cover"
+ *             }
+ *           }]
+ *         },
+ *         {
+ *           id: "video-caption",
+ *           type: "caption",
+ *           s: 5, e: 20,
+ *           t: "Video Caption",
+ *           props: {
+ *             colors: { text: "#ffffff", background: "rgba(0,0,0,0.7)" },
+ *             font: { family: "Arial", size: 36, weight: 600 }
+ *           }
+ *         }
+ *       ]
+ *     }
+ *   ]
+ * };
+ * ```
+ * 
+ * ## 🚀 Performance Tips
+ * 
+ * - **Preload videos** for smooth playback
+ * - **Use appropriate object-fit** to avoid unnecessary scaling
+ * - **Optimize video files** for web delivery (compression, format)
+ * - **Batch frame effects** for better performance
+ * - **Monitor memory usage** with multiple video elements
+ * 
+ * @param containerRef - Reference to the container element
+ * @param element - Video element configuration and properties
+ * @param view - The main scene view for rendering
+ * 
+ * @example
+ * ```js
+ * // Basic video element
+ * {
+ *   id: "main-video",
+ *   type: "video",
+ *   s: 0, e: 15,
+ *   props: {
+ *     src: "video.mp4",
+ *     width: 1920,
+ *     height: 1080
+ *   },
+ *   objectFit: "cover"
+ * }
+ * 
+ * // Video with frame effect and animation
+ * {
+ *   id: "framed-video",
+ *   type: "video",
+ *   s: 2, e: 20,
+ *   props: { src: "content.mp4" },
+ *   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 VideoElement = {
   name: "video",
+  
+  /**
+   * Generator function that creates and manages video elements in the scene.
+   * Handles video creation, frame setup, animations, effects, and cleanup.
+   *
+   * @param params - Element parameters including container reference, element config, and view
+   * @returns Generator that controls the video element lifecycle
+   * 
+   * @example
+   * ```js
+   * yield* VideoElement.create({
+   *   containerRef: mainContainer,
+   *   element: videoConfig,
+   *   view: sceneView
+   * });
+   * ```
+   */
   *create({ containerRef, element, view }: ElementParams) {
     yield* waitFor(element?.s);
     const frameContainerRef = createRef<any>();

package/src/frame-effects/circle.frame.tsx

@@ -1,6 +1,38 @@
 /**
- * Frame effects component that handles the application of various visual effects
- * to frames and elements in the scene.
+ * @group CircleFrameEffect
+ * CircleFrameEffect animates a frame transitioning into a circular shape,
+ * resizing, repositioning, and optionally fitting its content. Creates a 
+ * circular mask around content perfect for profile pictures and artistic presentations.
+ *
+ * Behavior:
+ * - Waits for the specified start time
+ * - Resizes and repositions the frame container smoothly
+ * - Animates the corner radius to create a perfect circle
+ * - Repositions the content element if needed
+ * - Optionally fits the element inside the container based on object-fit
+ *
+ * @param containerRef - Reference to the frame container element
+ * @param elementRef - Reference to the content element inside the frame
+ * @param initFrameState - Initial size and position state of the element
+ * @param frameEffect - Frame transformation configuration and timing
+ * 
+ * @example
+ * ```js
+ * // Basic circular frame
+ * frameEffects: [{
+ *   name: "circle",
+ *   s: 0,
+ *   e: 10,
+ *   props: {
+ *     frameSize: [400, 400],
+ *     frameShape: "circle",
+ *     framePosition: { x: 960, y: 540 },
+ *     radius: 200,
+ *     objectFit: "cover",
+ *     transitionDuration: 1.5
+ *   }
+ * }]
+ * ```
  */
 
 import { all, waitFor } from "@twick/core";
@@ -14,25 +46,58 @@ import { FrameEffectParams } from "../helpers/types";
 
 /**
  * CircleFrameEffect animates a frame transitioning into a circular shape,
- * resizing, repositioning, and optionally fitting its content.
+ * resizing, repositioning, and optionally fitting its content. Creates a 
+ * circular mask around content perfect for profile pictures and artistic presentations.
  *
  * Behavior:
- * - Waits for the specified start time.
- * - Resizes and repositions the frame container smoothly.
- * - Animates the corner radius to create a perfect circle.
- * - Repositions the content element if needed.
- * - Optionally fits the element inside the container based on object-fit.
+ * - Waits for the specified start time
+ * - Resizes and repositions the frame container smoothly
+ * - Animates the corner radius to create a perfect circle
+ * - Repositions the content element if needed
+ * - Optionally fits the element inside the container based on object-fit
  *
- * @param containerRef - Reference to the frame container element.
- * @param elementRef - Reference to the content element inside the frame.
- * @param initFrameState - Initial size and position state of the element.
- * @param frameEffect - Frame transformation configuration and timing.
+ * @param containerRef - Reference to the frame container element
+ * @param elementRef - Reference to the content element inside the frame
+ * @param initFrameState - Initial size and position state of the element
+ * @param frameEffect - Frame transformation configuration and timing
+ * 
+ * @example
+ * ```js
+ * // Basic circular frame
+ * frameEffects: [{
+ *   name: "circle",
+ *   s: 0,
+ *   e: 10,
+ *   props: {
+ *     frameSize: [400, 400],
+ *     frameShape: "circle",
+ *     framePosition: { x: 960, y: 540 },
+ *     radius: 200,
+ *     objectFit: "cover",
+ *     transitionDuration: 1.5
+ *   }
+ * }]
+ * ```
  */
 export const CircleFrameEffect = {
   name: "circle",
 
   /**
    * Generator function controlling the circle frame animation.
+   * Handles frame resizing, positioning, corner radius animation, and content fitting.
+   *
+   * @param params - Frame effect parameters including element references and configuration
+   * @returns Generator that controls the circle frame animation timeline
+   * 
+   * @example
+   * ```js
+   * yield* CircleFrameEffect.run({
+   *   containerRef: frameContainer,
+   *   elementRef: contentElement,
+   *   initFrameState: initialState,
+   *   frameEffect: circleConfig
+   * });
+   * ```
    */
   *run({
     containerRef,

package/src/frame-effects/index.ts

@@ -0,0 +1,7 @@
+/**
+ * @group Frame Effects
+ * @description Visual frame and masking effects
+ */
+
+export { CircleFrameEffect } from './circle.frame';
+export { RectFrameEffect } from './rect.frame';

package/src/frame-effects/rect.frame.tsx

@@ -1,6 +1,53 @@
 /**
- * Frame effects component that handles the application of various visual effects
- * to frames and elements in the scene.
+ * @group RectFrameEffect
+ * RectFrameEffect applies frame transformations such as resizing, repositioning, 
+ * rounding corners, and optionally fitting the element within the frame according 
+ * to an object-fit mode. Creates rectangular masks and containers for content 
+ * presentation with smooth transitions.
+ *
+ * Behavior:
+ * - Waits for the specified start time
+ * - Resizes and repositions the container and element smoothly
+ * - Adjusts corner radius if provided
+ * - Optionally fits the element inside the container
+ *
+ * @param containerRef - Reference to the frame container element
+ * @param elementRef - Reference to the content element inside the frame
+ * @param initFrameState - Initial size and position state of the element
+ * @param frameEffect - Frame transformation configuration and timing
+ * 
+ * @example
+ * ```js
+ * // Basic rectangular frame
+ * frameEffects: [{
+ *   name: "rect",
+ *   s: 0,
+ *   e: 10,
+ *   props: {
+ *     frameSize: [600, 400],
+ *     frameShape: "rect",
+ *     framePosition: { x: 960, y: 540 },
+ *     radius: 20,
+ *     objectFit: "cover",
+ *     transitionDuration: 1.5
+ *   }
+ * }]
+ * 
+ * // Rounded rectangle frame
+ * frameEffects: [{
+ *   name: "rect",
+ *   s: 2,
+ *   e: 15,
+ *   props: {
+ *     frameSize: [800, 600],
+ *     frameShape: "rect",
+ *     framePosition: { x: 960, y: 540 },
+ *     radius: 50,
+ *     objectFit: "contain",
+ *     transitionDuration: 2
+ *   }
+ * }]
+ * ```
  */
 
 import { all, waitFor } from "@twick/core";
@@ -13,26 +60,74 @@ import {
 import { FrameEffectParams } from "../helpers/types";
 
 /**
- * RectFrameEffect applies frame transformations such as resizing,
- * repositioning, rounding corners, and optionally fitting the element
- * within the frame according to an object-fit mode.
+ * RectFrameEffect applies frame transformations such as resizing, repositioning, 
+ * rounding corners, and optionally fitting the element within the frame according 
+ * to an object-fit mode. Creates rectangular masks and containers for content 
+ * presentation with smooth transitions.
  *
  * Behavior:
- * - Waits for the specified start time.
- * - Resizes and repositions the container and element smoothly.
- * - Adjusts corner radius if provided.
- * - Optionally fits the element inside the container.
+ * - Waits for the specified start time
+ * - Resizes and repositions the container and element smoothly
+ * - Adjusts corner radius if provided
+ * - Optionally fits the element inside the container
  *
- * @param containerRef - Reference to the frame container element.
- * @param elementRef - Reference to the content element inside the frame.
- * @param initFrameState - Initial size and position state of the element.
- * @param frameEffect - Frame transformation configuration and timing.
+ * @param containerRef - Reference to the frame container element
+ * @param elementRef - Reference to the content element inside the frame
+ * @param initFrameState - Initial size and position state of the element
+ * @param frameEffect - Frame transformation configuration and timing
+ * 
+ * @example
+ * ```js
+ * // Basic rectangular frame
+ * frameEffects: [{
+ *   name: "rect",
+ *   s: 0,
+ *   e: 10,
+ *   props: {
+ *     frameSize: [600, 400],
+ *     frameShape: "rect",
+ *     framePosition: { x: 960, y: 540 },
+ *     radius: 20,
+ *     objectFit: "cover",
+ *     transitionDuration: 1.5
+ *   }
+ * }]
+ * 
+ * // Rounded rectangle frame
+ * frameEffects: [{
+ *   name: "rect",
+ *   s: 2,
+ *   e: 15,
+ *   props: {
+ *     frameSize: [800, 600],
+ *     frameShape: "rect",
+ *     framePosition: { x: 960, y: 540 },
+ *     radius: 50,
+ *     objectFit: "contain",
+ *     transitionDuration: 2
+ *   }
+ * }]
+ * ```
  */
 export const RectFrameEffect = {
   name: "rect",
 
   /**
    * Generator function controlling the frame resizing and positioning animation.
+   * Handles rectangular frame transformations with smooth transitions and content fitting.
+   *
+   * @param params - Frame effect parameters including element references and configuration
+   * @returns Generator that controls the rectangular frame animation timeline
+   * 
+   * @example
+   * ```js
+   * yield* RectFrameEffect.run({
+   *   containerRef: frameContainer,
+   *   elementRef: contentElement,
+   *   initFrameState: initialState,
+   *   frameEffect: rectConfig
+   * });
+   * ```
    */
   *run({
     containerRef,