@twick/visualizer 0.14.0 → 0.14.3

package/src/controllers/frame-effect.controller.tsx

@@ -1,30 +1,30 @@
-
-import { CircleFrameEffect } from "../frame-effects/circle.frame";
-import { RectFrameEffect } from "../frame-effects/rect.frame";
-import {  FrameEffectPlugin } from "../helpers/types";
-
-export class FrameEffectController {
-    private frameEffects: Map<string, FrameEffectPlugin> = new Map();
-  
-    register(frameEffect: FrameEffectPlugin) {
-      this.frameEffects.set(frameEffect.name, frameEffect);
-    }
-  
-    get(name: string): FrameEffectPlugin | undefined {
-      return this.frameEffects.get(name);
-    }
-  
-    list(): string[] {
-      return Array.from(this.frameEffects.keys());
-    }
-  }
-
-  export const registerFrameEffects = () => {
-    frameEffectController.register(CircleFrameEffect);
-    frameEffectController.register(RectFrameEffect);
-  }
-
-  const frameEffectController = new FrameEffectController();  
-  registerFrameEffects();
-
+
+import { CircleFrameEffect } from "../frame-effects/circle.frame";
+import { RectFrameEffect } from "../frame-effects/rect.frame";
+import {  FrameEffectPlugin } from "../helpers/types";
+
+export class FrameEffectController {
+    private frameEffects: Map<string, FrameEffectPlugin> = new Map();
+  
+    register(frameEffect: FrameEffectPlugin) {
+      this.frameEffects.set(frameEffect.name, frameEffect);
+    }
+  
+    get(name: string): FrameEffectPlugin | undefined {
+      return this.frameEffects.get(name);
+    }
+  
+    list(): string[] {
+      return Array.from(this.frameEffects.keys());
+    }
+  }
+
+  export const registerFrameEffects = () => {
+    frameEffectController.register(CircleFrameEffect);
+    frameEffectController.register(RectFrameEffect);
+  }
+
+  const frameEffectController = new FrameEffectController();  
+  registerFrameEffects();
+
   export default frameEffectController;

package/src/controllers/text-effect.controller.ts

@@ -1,33 +1,33 @@
-import { ElasticEffect } from "../text-effects/elastic";
-import { EraseEffect } from "../text-effects/erase";  
-import { StreamWordEffect } from "../text-effects/stream-word";
-import { TypewriterEffect } from "../text-effects/typewriter";
-import { TextEffect } from "../helpers/types";
-
-export class TextEffectController {
-    private effects: Map<string, TextEffect> = new Map();
-  
-    register(effect: TextEffect) {
-      this.effects.set(effect.name, effect);
-    }
-  
-    get(name: string): TextEffect | undefined {
-      return this.effects.get(name);
-    }
-  
-    list(): string[] {
-      return Array.from(this.effects.keys());
-    }
-  }
-
-  export const registerTextEffects = () => {
-    textEffectController.register(TypewriterEffect);
-    textEffectController.register(StreamWordEffect);
-    textEffectController.register(EraseEffect);
-    textEffectController.register(ElasticEffect);
-  }
-
-  const textEffectController = new TextEffectController();  
-  registerTextEffects();
-
+import { ElasticEffect } from "../text-effects/elastic";
+import { EraseEffect } from "../text-effects/erase";  
+import { StreamWordEffect } from "../text-effects/stream-word";
+import { TypewriterEffect } from "../text-effects/typewriter";
+import { TextEffect } from "../helpers/types";
+
+export class TextEffectController {
+    private effects: Map<string, TextEffect> = new Map();
+  
+    register(effect: TextEffect) {
+      this.effects.set(effect.name, effect);
+    }
+  
+    get(name: string): TextEffect | undefined {
+      return this.effects.get(name);
+    }
+  
+    list(): string[] {
+      return Array.from(this.effects.keys());
+    }
+  }
+
+  export const registerTextEffects = () => {
+    textEffectController.register(TypewriterEffect);
+    textEffectController.register(StreamWordEffect);
+    textEffectController.register(EraseEffect);
+    textEffectController.register(ElasticEffect);
+  }
+
+  const textEffectController = new TextEffectController();  
+  registerTextEffects();
+
   export default textEffectController;

package/src/elements/audio.element.tsx

@@ -1,17 +1,79 @@
-import { ElementParams } from "../helpers/types";
-import { createRef, waitFor } from "@twick/core";
-import { Audio } from "@twick/2d";
-
-export const AudioElement = {
-  name: "audio",
-  *create({ containerRef, element, view }: ElementParams) {
-    const elementRef = createRef<any>();
-    yield* waitFor(element?.s);
-    yield containerRef().add(
-      <Audio ref={elementRef} key={element.id} {...element.props} />
-    );
-    yield* waitFor(Math.max(0, element.e - element.s));
-    yield elementRef().playing(false);
-    yield elementRef().remove();
-  },
-};
+import { ElementParams } from "../helpers/types";
+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);
+    yield containerRef().add(
+      <Audio ref={elementRef} key={element.id} play={true} {...element.props} />
+    );
+    yield* waitFor(Math.max(0, element.e - element.s));
+    yield elementRef().play(false);
+    yield elementRef().remove();
+  },
+};

package/src/elements/caption.element.tsx

@@ -1,87 +1,169 @@
-import { CaptionProps, ElementParams } from "../helpers/types";
-import { Color, createRef, Reference, waitFor } from "@twick/core";
-import { Rect, Txt } from "@twick/2d";
-import { splitPhraseTiming } from "../helpers/caption.utils";
-import { TRANSPARENT_COLOR } from "../helpers/constants";
-import { hexToRGB } from "../helpers/utils";
-
-export const CaptionElement = {
-  name: "caption",
-  *create({ containerRef, caption }: ElementParams) {
-    const words = splitPhraseTiming(caption);
-    let phraseStart = 0;
-    if (words?.length) {
-      phraseStart = words[0].s;
-    }
-    let wordsState: {
-      refs: Array<{ bgRef?: Reference<any>; textRef: Reference<any> }>;
-      props: CaptionProps[];
-      idx: number;
-      prevTime: number;
-    } = {
-      refs: [],
-      props: [],
-      idx: 0,
-      prevTime: phraseStart,
-    };
-    for (const word of words) {
-      wordsState.props.push(caption.props);
-      const textRef = createRef<Txt>();
-      const captionProps = caption.props;
-      containerRef().add(
-        <Txt ref={textRef} {...captionProps} text={word.t} opacity={0} />
-      );
-      if (caption.capStyle == "highlight_bg") {
-        const bgContainerRef = createRef();
-        const childTextRef = createRef();
-        const _color = new Color({...hexToRGB(captionProps.colors.background), a: captionProps?.bgOpacity ?? 1});
-        containerRef().add(
-          <Rect
-            ref={bgContainerRef}
-            fill={_color}
-            width={textRef().width() + (captionProps.bgOffsetWidth ?? 30)}
-            height={textRef().height() + (captionProps.bgOffsetHeight ?? 10)}
-            margin={captionProps.bgMargin ?? [0, -5]}
-            radius={captionProps.bgRadius ?? 10}
-            padding={captionProps.bgPadding ?? [0, 15]}
-            opacity={0}
-            alignItems={"center"}
-            justifyContent={"center"}
-            layout
-          >
-            <Txt ref={childTextRef} {...captionProps} text={word.t} />
-          </Rect>
-        );
-        textRef().remove();
-        wordsState.refs.push({
-          bgRef: bgContainerRef,
-          textRef: childTextRef,
-        });
-      } else {
-        wordsState.refs.push({
-          textRef: textRef,
-        });
-      }
-      wordsState.prevTime = word.e;
-      wordsState.idx = wordsState.idx + 1;
-    }
-
-    wordsState.prevTime = phraseStart;
-    wordsState.idx = 0;
-
-    for (const word of words) {
-      if (caption.capStyle == "highlight_bg") {
-        yield* wordsState.refs[wordsState.idx]?.bgRef?.().opacity(1, 0);
-        yield* waitFor(Math.max(0, word.e - word.s));
-        yield* wordsState.refs[wordsState.idx]
-          ?.bgRef?.()
-          .fill(TRANSPARENT_COLOR, 0);
-      } else {
-        yield* wordsState.refs[wordsState.idx]?.textRef?.().opacity(1, 0);
-        yield* waitFor(Math.max(0, word.e - word.s));
-      }
-      wordsState.prevTime = word.e;
-      wordsState.idx = wordsState.idx + 1;
-    }
-  },
-};
+import { CaptionProps, ElementParams } from "../helpers/types";
+import { Color, createRef, Reference, waitFor } from "@twick/core";
+import { Rect, Txt } from "@twick/2d";
+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;
+    if (words?.length) {
+      phraseStart = words[0].s;
+    }
+    let wordsState: {
+      refs: Array<{ bgRef?: Reference<any>; textRef: Reference<any> }>;
+      props: CaptionProps[];
+      idx: number;
+      prevTime: number;
+    } = {
+      refs: [],
+      props: [],
+      idx: 0,
+      prevTime: phraseStart,
+    };
+    for (const word of words) {
+      wordsState.props.push(caption.props);
+      const textRef = createRef<Txt>();
+      const captionProps = caption.props;
+      containerRef().add(
+        <Txt ref={textRef} {...captionProps} text={word.t} opacity={0} />
+      );
+      if (caption.capStyle == "highlight_bg") {
+        const bgContainerRef = createRef();
+        const childTextRef = createRef();
+        const _color = new Color({...hexToRGB(captionProps.colors.background), a: captionProps?.bgOpacity ?? 1});
+        containerRef().add(
+          <Rect
+            ref={bgContainerRef}
+            fill={_color}
+            width={textRef().width() + (captionProps.bgOffsetWidth ?? 30)}
+            height={textRef().height() + (captionProps.bgOffsetHeight ?? 10)}
+            margin={captionProps.bgMargin ?? [0, -5]}
+            radius={captionProps.bgRadius ?? 10}
+            padding={captionProps.bgPadding ?? [0, 15]}
+            opacity={0}
+            alignItems={"center"}
+            justifyContent={"center"}
+            layout
+          >
+            <Txt ref={childTextRef} {...captionProps} text={word.t} />
+          </Rect>
+        );
+        textRef().remove();
+        wordsState.refs.push({
+          bgRef: bgContainerRef,
+          textRef: childTextRef,
+        });
+      } else {
+        wordsState.refs.push({
+          textRef: textRef,
+        });
+      }
+      wordsState.prevTime = word.e;
+      wordsState.idx = wordsState.idx + 1;
+    }
+
+    wordsState.prevTime = phraseStart;
+    wordsState.idx = 0;
+
+    for (const word of words) {
+      if (caption.capStyle == "highlight_bg") {
+        yield* wordsState.refs[wordsState.idx]?.bgRef?.().opacity(1, 0);
+        yield* waitFor(Math.max(0, word.e - word.s));
+        yield* wordsState.refs[wordsState.idx]
+          ?.bgRef?.()
+          .fill(TRANSPARENT_COLOR, 0);
+      } else {
+        yield* wordsState.refs[wordsState.idx]?.textRef?.().opacity(1, 0);
+        yield* waitFor(Math.max(0, word.e - word.s));
+      }
+      wordsState.prevTime = word.e;
+      wordsState.idx = wordsState.idx + 1;
+    }
+  },
+};

package/src/elements/circle.element.tsx

@@ -1,20 +1,88 @@
-import { ElementParams } from "../helpers/types";
-import { all, createRef, waitFor } from "@twick/core";
-import { Circle } from "@twick/2d";
-import { addAnimation } from "../helpers/element.utils";
-
-export const CircleElement = {
-  name: "circle",
-  *create({ containerRef, element, view }: ElementParams) {
-    const elementRef = createRef<any>();
-    yield* waitFor(element?.s);
-    yield containerRef().add(
-      <Circle 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 { 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",
+
+    /**
+     * 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(
+      <Circle 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();
+  },
+};