@twick/visualizer 0.14.2 → 0.14.3

package/src/helpers/element.utils.ts

@@ -9,17 +9,29 @@ import { logger } from "./log.utils";
 
 /**
  * Element utilities for the visualizer package.
- * Provides functions for handling element positioning, sizing, and transformations.
+ * Provides functions for handling element positioning, sizing, and transformations
+ * to ensure proper content display and visual effects.
  */
 
 /**
- * Fits an element within specified bounds while maintaining aspect ratio
- * @param {Object} params - Parameters for fitting the element
- * @param {Object} params.containerSize - The container size
- * @param {Object} params.elementSize - The element size
- * @param {Object} params.elementRef - The element reference
- * @param {string} [params.objectFit] - The fit mode (contain, cover, fill)
- * @returns {Object} Updated element dimensions
+ * Fits an element within specified bounds while maintaining aspect ratio.
+ * Handles different object-fit modes for proper content scaling and positioning.
+ *
+ * @param containerSize - The container size dimensions
+ * @param elementSize - The element size dimensions
+ * @param elementRef - The element reference to modify
+ * @param objectFit - The fit mode (contain, cover, fill, none)
+ * @returns Generator that controls the element fitting process
+ * 
+ * @example
+ * ```js
+ * yield* fitElement({
+ *   containerSize: { x: 800, y: 600 },
+ *   elementSize: { x: 1920, y: 1080 },
+ *   elementRef: videoElement,
+ *   objectFit: "cover"
+ * });
+ * ```
  */
 export function* fitElement({
   containerSize,
@@ -89,6 +101,28 @@ export function* fitElement({
   }
 }
 
+/**
+ * Adds text effects to an element based on its configuration.
+ * Applies text animations like typewriter, stream word, or elastic effects.
+ *
+ * @param elementRef - Reference to the text element
+ * @param element - Element configuration containing text effect settings
+ * @returns Generator that controls the text effect animation
+ * 
+ * @example
+ * ```js
+ * yield* addTextEffect({
+ *   elementRef: textElement,
+ *   element: {
+ *     textEffect: {
+ *       name: "typewriter",
+ *       duration: 3,
+ *       interval: 0.1
+ *     }
+ *   }
+ * });
+ * ```
+ */
 export function* addTextEffect({
   elementRef,
   element,
@@ -109,6 +143,33 @@ export function* addTextEffect({
   }
 }
 
+/**
+ * Adds animations to an element based on its configuration.
+ * Applies entrance, exit, or transition animations to elements.
+ *
+ * @param elementRef - Reference to the element to animate
+ * @param containerRef - Optional reference to the container element
+ * @param element - Element configuration containing animation settings
+ * @param view - The main scene view for rendering
+ * @returns Generator that controls the animation timeline
+ * 
+ * @example
+ * ```js
+ * yield* addAnimation({
+ *   elementRef: videoElement,
+ *   containerRef: frameContainer,
+ *   element: {
+ *     animation: {
+ *       name: "fade",
+ *       animate: "enter",
+ *       duration: 2,
+ *       direction: "center"
+ *     }
+ *   },
+ *   view: sceneView
+ * });
+ * ```
+ */
 export function* addAnimation({
   elementRef,
   containerRef,
@@ -136,6 +197,37 @@ export function* addAnimation({
 }
 
 
+/**
+ * Adds frame effects to an element based on its configuration.
+ * Applies visual masks and containers like circular or rectangular frames.
+ *
+ * @param containerRef - Reference to the frame container element
+ * @param elementRef - Reference to the content element inside the frame
+ * @param element - Element configuration containing frame effect settings
+ * @returns Generator that controls the frame effect timeline
+ * 
+ * @example
+ * ```js
+ * yield* addFrameEffect({
+ *   containerRef: frameContainer,
+ *   elementRef: contentElement,
+ *   element: {
+ *     frameEffects: [{
+ *       name: "circle",
+ *       s: 0,
+ *       e: 10,
+ *       props: {
+ *         frameSize: [400, 400],
+ *         frameShape: "circle",
+ *         framePosition: { x: 960, y: 540 },
+ *         radius: 200,
+ *         objectFit: "cover"
+ *       }
+ *     }]
+ *   }
+ * });
+ * ```
+ */
 export function* addFrameEffect({
   containerRef,
   elementRef,

package/src/helpers/event.utils.ts

@@ -1,3 +1,18 @@
+/**
+ * Dispatches a custom event to the window object.
+ * Creates and dispatches a CustomEvent with the specified name and detail
+ * if running in a browser environment.
+ *
+ * @param eventName - The name of the custom event to dispatch
+ * @param detail - The event detail object to include with the event
+ * @returns True if the event was dispatched successfully, false otherwise
+ * 
+ * @example
+ * ```js
+ * dispatchWindowEvent("playerUpdate", { status: "ready", playerId: "123" });
+ * // Dispatches a custom event with player update information
+ * ```
+ */
 export const dispatchWindowEvent = (eventName: string, detail: any) => {
   if (typeof window !== "undefined") {
     const event = new CustomEvent(eventName, detail as any);

package/src/helpers/log.utils.ts

@@ -1,28 +1,54 @@
 import { format } from "date-fns";
 
+/**
+ * Gets the current time formatted according to the specified format.
+ * Uses date-fns to format the current timestamp.
+ *
+ * @param dateFormat - The date format string to use
+ * @returns Formatted time string
+ * 
+ * @example
+ * ```js
+ * const time = getCurrentTime("mm:ss:SSS");
+ * // time = "05:30:123"
+ * ```
+ */
 const getCurrentTime = (dateFormat = "mm:ss:SSS") => {
   const now = new Date();
   return format(now, dateFormat);
 };
 
 /**
- * Logging utilities for the visualizer package.
- * Provides consistent logging functionality across the application.
- */
-
-/**
- * Logs a message to the console with a visualizer prefix
- * @param {string} message - The message to log
- * @param {any} [data] - Optional data to log
+ * Logs a message to the console with a visualizer prefix.
+ * Provides consistent logging functionality across the application
+ * with standardized formatting and prefixing.
+ *
+ * @param message - The message to log
+ * @param data - Optional data to log
+ * 
+ * @example
+ * ```js
+ * logger("Scene loaded successfully", { sceneId: "scene1" });
+ * // Output: [Visualizer] Scene loaded successfully { sceneId: "scene1" }
+ * ```
  */
 export function logger(message: string, data?: any) {
   console.log(`[Visualizer] ${message}`, data ? data : "");
 }
 
 /**
- * Logs an error to the console with a visualizer prefix
- * @param {string} message - The error message to log
- * @param {Error} [error] - Optional error object
+ * Logs an error to the console with a visualizer prefix.
+ * Provides consistent error logging functionality across the application
+ * with standardized formatting and prefixing.
+ *
+ * @param message - The error message to log
+ * @param error - Optional error object
+ * 
+ * @example
+ * ```js
+ * errorLogger("Failed to load scene", new Error("Network error"));
+ * // Output: [Visualizer Error] Failed to load scene Error: Network error
+ * ```
  */
 export function errorLogger(message: string, error?: Error) {
   console.error(`[Visualizer Error] ${message}`, error ? error : "");

package/src/helpers/types.ts

@@ -1,6 +1,11 @@
 import { View2D } from "@twick/2d";
 import { Reference, ThreadGenerator, Vector2 } from "@twick/core";
 
+/**
+ * Main input configuration for video visualization.
+ * Contains player settings, background color, dimensions, and track definitions
+ * for creating complete video visualizations.
+ */
 export type VideoInput = {
   playerId: string,
   backgroundColor: string;
@@ -11,27 +16,55 @@ export type VideoInput = {
   tracks: VisualizerTrack[];
 };
 
+/**
+ * Supported media types for visualizer elements.
+ * Defines the types of media content that can be displayed.
+ */
 export type MediaType = "video" | "image";
 
+/**
+ * Object fit options for content scaling within containers.
+ * Controls how content is sized and positioned within its container.
+ */
 export type ObjectFit = "contain" | "cover" | "fill" | "none";
 
+/**
+ * Two-dimensional size vector with x and y coordinates.
+ * Used for representing width and height dimensions.
+ */
 export type SizeVector = {
   x: number;
   y: number;
 };
 
+/**
+ * Size object with width and height properties.
+ * Standard size representation for elements and containers.
+ */
 export type Size = {
   width: number;
   height: number;
 };
 
+/**
+ * Size array with width and height values.
+ * Alternative size representation as a tuple.
+ */
 export type SizeArray = [number, number];
 
+/**
+ * Position object with x and y coordinates.
+ * Represents 2D positioning for elements in the scene.
+ */
 export type Position = {
   x: number;
   y: number;
 };
 
+/**
+ * Frame effect configuration for visual masking.
+ * Defines timing and properties for frame effects like circles and rectangles.
+ */
 export type FrameEffect = {
   name: string;
   s: number;
@@ -39,6 +72,10 @@ export type FrameEffect = {
   props: FrameEffectProps;
 };
 
+/**
+ * Properties for frame effect transformations.
+ * Controls frame size, shape, position, and transition behavior.
+ */
 export type FrameEffectProps = {
   frameSize: SizeArray;
   frameShape: "circle" | "rect";
@@ -50,6 +87,10 @@ export type FrameEffectProps = {
   elementPosition: Position;
 };
 
+/**
+ * Styling configuration for caption elements.
+ * Defines visual appearance of captions including layout and text styling.
+ */
 export type CaptionStyle = {
   rect: {
     alignItems?: string;
@@ -75,6 +116,10 @@ export type CaptionStyle = {
   };
 };
 
+/**
+ * Caption element configuration.
+ * Defines text content, timing, styling, and display properties for captions.
+ */
 export type Caption = {
   t: string;
   s: number;
@@ -83,6 +128,10 @@ export type Caption = {
   props?: CaptionProps;
 };
 
+/**
+ * Caption styling properties.
+ * Controls colors, fonts, background, and positioning for caption text.
+ */
 export type CaptionProps = {
   colors: CaptionColors;
   font: CaptionFont;
@@ -96,12 +145,20 @@ export type CaptionProps = {
   y?: number;
 };
 
+/**
+ * Color configuration for caption text and backgrounds.
+ * Defines text color, background color, and highlight colors.
+ */
 export type CaptionColors = {
   text?: string;
   background?: string;
   highlight?: string;
 };
 
+/**
+ * Font configuration for caption text.
+ * Controls font family, size, weight, and style.
+ */
 export type CaptionFont = {
   family?: string;
   size?: number;
@@ -109,6 +166,11 @@ export type CaptionFont = {
   style?: string;
 };
 
+/**
+ * Visualizer element configuration.
+ * Defines the structure and properties for all visual elements in the scene
+ * including videos, images, text, and captions with their animations and effects.
+ */
 export type VisualizerElement = {
   id: string;
   trackId?: string;
@@ -127,6 +189,11 @@ export type VisualizerElement = {
   hWords?: any;
 };
 
+/**
+ * Visualizer track configuration.
+ * Contains a collection of elements that share common properties and timing.
+ * Tracks organize elements into logical groups for better scene management.
+ */
 export type VisualizerTrack = {
   id: string;
   type: string;
@@ -151,6 +218,10 @@ export type VisualizerTrack = {
   };
 };
 
+/**
+ * Parameters for creating elements in the visualizer scene.
+ * Contains all necessary references and configuration for element creation.
+ */
 export type ElementParams = {
   view: View2D;
   containerRef: Reference<any>;
@@ -159,11 +230,21 @@ export type ElementParams = {
   waitOnStart?: boolean;
 };
 
+/**
+ * Interface for creating visual elements in the scene.
+ * Defines the contract for all element types including video, image, text, and captions.
+ */
 export interface Element<Params = ElementParams> {
+  /** The unique name identifier for this element type */
   name: string;
+  /** Creates and manages the element in the scene */
   create(params: Params): ThreadGenerator;
 }
 
+/**
+ * Parameters for text effect animations.
+ * Controls timing and behavior of text animation effects.
+ */
 export type TextEffectParams = {
   elementRef: Reference<any>;
   interval?: number;
@@ -173,6 +254,10 @@ export type TextEffectParams = {
   direction?: "left" | "right" | "center";
 };
 
+/**
+ * Configuration properties for text effects.
+ * Defines how text effects should behave and appear.
+ */
 export type TextEffectProps = {
   name: string;
   interval?: number;
@@ -182,11 +267,21 @@ export type TextEffectProps = {
   direction?: "left" | "right" | "center";
 };
 
+/**
+ * Interface for text effect animations.
+ * Defines the contract for text animation effects like typewriter, stream word, etc.
+ */
 export interface TextEffect<Params = TextEffectParams> {
+  /** The unique name identifier for this text effect */
   name: string;
+  /** Executes the text effect animation */
   run(params: Params): Generator;
 }
 
+/**
+ * Parameters for element animations.
+ * Controls timing, direction, and behavior of element animations.
+ */
 export type AnimationParams = {
   elementRef: Reference<any>;
   containerRef?: Reference<any>;
@@ -199,6 +294,10 @@ export type AnimationParams = {
   direction?: "left" | "right" | "center" | "up" | "down";
 };
 
+/**
+ * Configuration properties for animations.
+ * Defines how animations should behave and appear.
+ */
 export type AnimationProps = {
   name: string;
   interval?: number;
@@ -209,11 +308,21 @@ export type AnimationProps = {
   direction?: "left" | "right" | "center" | "up" | "down";
 };
 
+/**
+ * Interface for element animations.
+ * Defines the contract for element animation effects like fade, rise, blur, etc.
+ */
 export interface Animation<Params = AnimationParams> {
+  /** The unique name identifier for this animation */
   name: string;
+  /** Executes the animation */
   run(params: Params): ThreadGenerator;
 }
 
+/**
+ * Parameters for frame effects.
+ * Controls frame transformations and visual masking effects.
+ */
 export type FrameEffectParams = {
   elementRef: Reference<any>;
   containerRef?: Reference<any>;
@@ -221,11 +330,21 @@ export type FrameEffectParams = {
   frameEffect: FrameEffect;
 };
 
+/**
+ * Interface for frame effect plugins.
+ * Defines the contract for frame effects like circular and rectangular masks.
+ */
 export interface FrameEffectPlugin<Params = FrameEffectParams> {
+  /** The unique name identifier for this frame effect */
   name: string;
+  /** Executes the frame effect */
   run(params: Params): ThreadGenerator;
 }
 
+/**
+ * State information for frame and element transformations.
+ * Contains size, position, and transformation data for frame effects.
+ */
 export type FrameState = {
   frame: {
     size: Vector2;

package/src/helpers/utils.ts

@@ -1,3 +1,20 @@
+/**
+ * Converts a hex color string to RGB values.
+ * Handles both 3-digit and 6-digit hex color formats
+ * and returns an object with red, green, and blue values.
+ *
+ * @param color - The hex color string to convert
+ * @returns Object containing r, g, b values
+ * 
+ * @example
+ * ```js
+ * const rgb = hexToRGB("#ff0000");
+ * // rgb = { r: 255, g: 0, b: 0 }
+ * 
+ * const rgb = hexToRGB("#f00");
+ * // rgb = { r: 255, g: 0, b: 0 }
+ * ```
+ */
 export const hexToRGB = (color: string) => {
   // Remove leading '#' if present
   let hex = color.replace(/^#/, '');