@twick/visualizer 0.14.0 → 0.14.3

package/src/elements/icon.element.tsx

@@ -1,20 +1,88 @@
-import { ElementParams } from "../helpers/types";
-import { all, createRef, waitFor } from "@twick/core";
-import { Icon } from "@twick/2d";
-import { addAnimation } from "../helpers/element.utils";
-
-export const IconElement = {
-  name: "icon",
-  *create({ containerRef, element, view }: ElementParams) {
-    const elementRef = createRef<any>();
-    yield* waitFor(element?.s);
-    yield containerRef().add(
-      <Icon ref={elementRef} key={element.id} {...element.props} />
-    );
-    yield* all(
-      addAnimation({ elementRef: elementRef, element: element, view }),
-      waitFor(Math.max(0, element.e - element.s))
-    );
-    yield elementRef().remove();
-  },
-};
+import { ElementParams } from "../helpers/types";
+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",
+
+    /**
+     * 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(
+      <Icon ref={elementRef} key={element.id} {...element.props} />
+    );
+    yield* all(
+      addAnimation({ elementRef: elementRef, element: element, view }),
+      waitFor(Math.max(0, element.e - element.s))
+    );
+    yield elementRef().remove();
+  },
+};

package/src/elements/image.element.tsx

@@ -1,55 +1,134 @@
-import { ElementParams } from "../helpers/types";
-import { all, createRef, waitFor } from "@twick/core";
-import { Img, Rect } from "@twick/2d";
-import { addAnimation, addFrameEffect, fitElement } from "../helpers/element.utils";
-import { logger } from "../helpers/log.utils";
-import { applyColorFilter } from "../helpers/filters";
-
-export const ImageElement = {
-  name: "image",
-  *create({ containerRef, element, view }: ElementParams) {
-    yield* waitFor(element?.s);
-    logger(`Adding image element ${element.id}`);
-    const frameContainerRef = createRef<any>();
-    const frameElementRef = createRef<any>();
-
-    yield containerRef().add(
-      <Rect ref={frameContainerRef} key={element.id} {...element.frame}>
-        <Img
-          ref={frameElementRef}
-          key={`child-${element.id}`}
-          {...element.props}
-        />
-      </Rect>
-    );
-    if (frameContainerRef()) {
-      yield fitElement({
-        elementRef: frameElementRef,
-        containerSize: frameContainerRef().size(),
-        elementSize: frameElementRef().size(),
-        objectFit: element.objectFit,
-      });
-
-      if (element?.props?.mediaFilter) {
-        applyColorFilter(frameElementRef, element.props.mediaFilter);
-      }
-
-      yield* all(
-        addAnimation({
-          elementRef: frameElementRef,
-          containerRef: frameContainerRef,
-          element: element,
-          view,
-        }),
-        addFrameEffect({
-          containerRef: frameContainerRef,
-          elementRef: frameElementRef,
-          element,
-        }),
-        waitFor(Math.max(0, element.e - element.s))
-      );
-      yield frameElementRef().remove();
-      yield frameContainerRef().remove();
-    }
-  },
-};
+import { ElementParams } from "../helpers/types";
+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>();
+    const frameElementRef = createRef<any>();
+
+    yield containerRef().add(
+      <Rect ref={frameContainerRef} key={element.id} {...element.frame}>
+        <Img
+          ref={frameElementRef}
+          key={`child-${element.id}`}
+          {...element.props}
+        />
+      </Rect>
+    );
+    if (frameContainerRef()) {
+      yield fitElement({
+        elementRef: frameElementRef,
+        containerSize: frameContainerRef().size(),
+        elementSize: frameElementRef().size(),
+        objectFit: element.objectFit,
+      });
+
+      if (element?.props?.mediaFilter) {
+        applyColorFilter(frameElementRef, element.props.mediaFilter);
+      }
+
+      yield* all(
+        addAnimation({
+          elementRef: frameElementRef,
+          containerRef: frameContainerRef,
+          element: element,
+          view,
+        }),
+        addFrameEffect({
+          containerRef: frameContainerRef,
+          elementRef: frameElementRef,
+          element,
+        }),
+        waitFor(Math.max(0, element.e - element.s))
+      );
+      yield frameElementRef().remove();
+      yield frameContainerRef().remove();
+    }
+  },
+};

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

@@ -1,22 +1,92 @@
-import { ElementParams } from "../helpers/types";
-import { all, createRef, waitFor } from "@twick/core";
-import { Rect } from "@twick/2d";
-import { addAnimation } from "../helpers/element.utils";
-import { logger } from "../helpers/log.utils";
-
-export const RectElement = {
-  name: "rect",
-  *create({ containerRef, element, view }: ElementParams) {
-    const elementRef = createRef<any>();
-    yield* waitFor(element?.s);
-    logger(`RectElement: ${JSON.stringify(element)}`);
-    yield containerRef().add(
-      <Rect ref={elementRef} key={element.id} {...element.props}/>
-    );
-    yield* all(
-      addAnimation({ elementRef: elementRef, element: element, view }),
-      waitFor(Math.max(0, element.e - element.s))
-    );
-    yield elementRef().remove();
-  },
-};
+import { ElementParams } from "../helpers/types";
+import { all, createRef, waitFor } from "@twick/core";
+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",
+
+    /**
+     * 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)}`);
+    yield containerRef().add(
+      <Rect ref={elementRef} key={element.id} {...element.props}/>
+    );
+    yield* all(
+      addAnimation({ elementRef: elementRef, element: element, view }),
+      waitFor(Math.max(0, element.e - element.s))
+    );
+    yield elementRef().remove();
+  },
+};

package/src/elements/scene.element.tsx

@@ -1,29 +1,97 @@
-import { ElementParams } from "../helpers/types";
-import { createRef, waitFor } from "@twick/core";
-import { Rect } from "@twick/2d";
-import { DEFAULT_BACKGROUND_COLOR, ELEMENT_TYPES } from "../helpers/constants";
-import { ImageElement } from "./image.element";
-import { VideoElement } from "./video.element";
-import { logger } from "../helpers/log.utils";
-
-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();
-  },
-};
+import { ElementParams } from "../helpers/types";
+import { createRef, waitFor } from "@twick/core";
+import { Rect } from "@twick/2d";
+import { DEFAULT_BACKGROUND_COLOR, ELEMENT_TYPES } from "../helpers/constants";
+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",
+
+    /**
+     * 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

@@ -1,28 +1,102 @@
-import { ElementParams } from "../helpers/types";
-import { all, createRef, waitFor } from "@twick/core";
-import { Txt } from "@twick/2d";
-import { addAnimation, addTextEffect } from "../helpers/element.utils";
-
-export const TextElement = {
-    name: "text",
-    *create({ containerRef, element, view }: ElementParams) { 
-    const elementRef = createRef<any>();
-
-    yield* waitFor(element?.s);
-    yield containerRef().add(
-      <Txt
-        ref={elementRef}
-        key={element.id}
-        text={element.t}
-        {...element.props}
-      />
-    );
-    yield* all(
-      addAnimation({ elementRef: elementRef, element: element, view }),
-      addTextEffect({ elementRef: elementRef, element: element }),
-      waitFor(Math.max(0, element.e - element.s))
-    );
-    yield elementRef().remove();
-}
-  }
+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>();
+
+    yield* waitFor(element?.s);
+    yield containerRef().add(
+      <Txt
+        ref={elementRef}
+        key={element.id}
+        text={element.t}
+        {...element.props}
+      />
+    );
+    yield* all(
+      addAnimation({ elementRef: elementRef, element: element, view }),
+      addTextEffect({ elementRef: elementRef, element: element }),
+      waitFor(Math.max(0, element.e - element.s))
+    );
+    yield elementRef().remove();
+}
+  }