@twick/visualizer 0.14.0 → 0.14.3

package/src/text-effects/erase.tsx

@@ -1,58 +1,91 @@
-import { waitFor } from "@twick/core";
-import { TextEffectParams } from "../helpers/types";
-
-/**
- * EraseEffect animates text disappearing letter by letter,
- * simulating an "erasing" or backspace effect.
- *
- * Behavior:
- * - Optionally waits for a delay before starting.
- * - Preserves the original element size.
- * - Animates removing one character at a time from the end.
- *
- * @param elementRef - Reference to the text element to animate.
- * @param duration - Total duration of the erasing animation.
- * @param delay - Optional delay before starting.
- * @param bufferTime - Time reserved at the end of animation (default: 0.1).
- */
-export const EraseEffect = {
-  name: "erase",
-
-  /**
-   * Generator function controlling the erase text effect.
-   */
-  *run({
-    elementRef,
-    duration,
-    delay,
-    bufferTime = 0.1,
-  }: TextEffectParams) {
-    // Get the full original text
-    const fullText = elementRef().text();
-
-    // Store the original size to avoid resizing during animation
-    const size = elementRef().size();
-
-    // Initialize element: clear text, set fixed size, align left
-    elementRef().setText("");
-    elementRef().size(size);
-    elementRef().textAlign("left");
-
-    // Wait for the optional initial delay
-    if (delay) {
-      yield* waitFor(delay);
-    }
-
-    // Compute the time interval between each character removal
-    let timeInterval = (duration - bufferTime) / fullText.length;
-
-    // Optionally wait a bit before starting erasing
-    yield* waitFor(timeInterval);
-
-    // Loop backwards through the text and erase one character at a time
-    for (let i = fullText.length; i >= 0; i--) {
-      yield* waitFor(timeInterval);
-      elementRef().setText(fullText.substring(0, i));
-    }
-  },
-};
+import { waitFor } from "@twick/core";
+import { TextEffectParams } from "../helpers/types";
+
+/**
+ * @group EraseEffect
+ * EraseEffect animates text disappearing letter by letter, simulating an "erasing"
+ * or backspace effect. Creates engaging text removal animations that mimic
+ * real-world erasing or typing corrections.
+ *
+ * Behavior:
+ * - Optionally waits for a delay before starting
+ * - Preserves the original element size
+ * - Animates removing one character at a time from the end
+ *
+ * @param elementRef - Reference to the text element to animate
+ * @param duration - Total duration of the erasing animation in seconds
+ * @param delay - Optional delay before starting in seconds
+ * @param bufferTime - Time reserved at the end of animation in seconds (default: 0.1)
+ *
+ * @example
+ * ```js
+ * // Basic erase effect
+ * textEffect: {
+ *   name: "erase",
+ *   duration: 3,
+ *   delay: 1
+ * }
+ *
+ * // Quick erase with buffer time
+ * textEffect: {
+ *   name: "erase",
+ *   duration: 2,
+ *   bufferTime: 0.5
+ * }
+ * ```
+ */
+export const EraseEffect = {
+  name: "erase",
+
+  /**
+   * Generator function controlling the erase text effect.
+   * Handles character-by-character text removal animations.
+   *
+   * @param params - Text effect parameters including element reference and timing
+   * @returns Generator that controls the erase animation timeline
+   *
+   * @example
+   * ```js
+   * yield* EraseEffect.run({
+   *   elementRef: textElement,
+   *   duration: 3,
+   *   delay: 1,
+   *   bufferTime: 0.1
+   * });
+   * ```
+   */
+  *run({
+    elementRef,
+    duration,
+    delay,
+    bufferTime = 0.1,
+  }: TextEffectParams) {
+    // Get the full original text
+    const fullText = elementRef().text();
+
+    // Store the original size to avoid resizing during animation
+    const size = elementRef().size();
+
+    // Initialize element: clear text, set fixed size, align left
+    elementRef().setText("");
+    elementRef().size(size);
+    elementRef().textAlign("left");
+
+    // Wait for the optional initial delay
+    if (delay) {
+      yield* waitFor(delay);
+    }
+
+    // Compute the time interval between each character removal
+    let timeInterval = (duration - bufferTime) / fullText.length;
+
+    // Optionally wait a bit before starting erasing
+    yield* waitFor(timeInterval);
+
+    // Loop backwards through the text and erase one character at a time
+    for (let i = fullText.length; i >= 0; i--) {
+      yield* waitFor(timeInterval);
+      elementRef().setText(fullText.substring(0, i));
+    }
+  },
+};

package/src/text-effects/index.ts

@@ -0,0 +1,9 @@
+/**
+ * @group Text Effects
+ * @description Text animation and styling effects
+ */
+
+export { TypewriterEffect } from './typewriter';
+export { StreamWordEffect } from './stream-word';
+export { ElasticEffect } from './elastic';
+export { EraseEffect } from './erase';

package/src/text-effects/stream-word.tsx

@@ -1,60 +1,94 @@
-import { waitFor } from "@twick/core";
-import { TextEffectParams } from "../helpers/types";
-
-/**
- * StreamWordEffect animates text appearing word by word,
- * creating a smooth "typing" or "streaming" effect.
- *
- * Behavior:
- * - Optionally waits for a delay before starting.
- * - Clears the text initially and preserves the original size.
- * - Reveals one word at a time with a consistent interval.
- *
- * @param elementRef - Reference to the text element to animate.
- * @param duration - Total duration of the animation.
- * @param delay - Optional delay before starting.
- * @param bufferTime - Time reserved at the end of animation (default: 0.1).
- */
-export const StreamWordEffect = {
-  name: "stream-word",
-
-  /**
-   * Generator function controlling the word streaming effect.
-   */
-  *run({
-    elementRef,
-    duration,
-    delay,
-    bufferTime = 0.1,
-  }: TextEffectParams) {
-    // Retrieve the full text content
-    const fullText = elementRef().text();
-
-    // Store the element's size to avoid resizing during animation
-    const size = elementRef().size();
-
-    // Split the text into words
-    const words = fullText.split(" ");
-
-    // Clear the text and set fixed size
-    elementRef().setText("");
-    elementRef().size(size);
-
-    // Wait for optional delay before starting
-    if (delay) {
-      yield* waitFor(delay);
-    }
-
-    // Align text to the left
-    elementRef().textAlign("left");
-
-    // Calculate the interval between words
-    let timeInterval =(duration - bufferTime) / words.length;
-
-    // Reveal each word one at a time
-    for (let i = 0; i < words.length; i++) {
-      yield* waitFor(timeInterval);
-      elementRef().setText(words.slice(0, i + 1).join(" "));
-    }
-  },
-};
+import { waitFor } from "@twick/core";
+import { TextEffectParams } from "../helpers/types";
+
+/**
+ * @group StreamWordEffect
+ * StreamWordEffect animates text appearing word by word, creating a smooth
+ * "typing" or "streaming" effect. Animates text word by word for natural
+ * reading flow and storytelling content.
+ *
+ * Behavior:
+ * - Optionally waits for a delay before starting
+ * - Clears the text initially and preserves the original size
+ * - Reveals one word at a time with a consistent interval
+ *
+ * @param elementRef - Reference to the text element to animate
+ * @param duration - Total duration of the animation in seconds
+ * @param delay - Optional delay before starting in seconds
+ * @param bufferTime - Time reserved at the end of animation in seconds
+ *
+ * @example
+ * ```js
+ * // Basic stream word effect
+ * textEffect: {
+ *   name: "stream-word",
+ *   duration: 2,
+ *   interval: 0.3
+ * }
+ *
+ * // With delay for dramatic effect
+ * textEffect: {
+ *   name: "stream-word",
+ *   duration: 4,
+ *   delay: 1,
+ *   bufferTime: 0.5
+ * }
+ * ```
+ */
+export const StreamWordEffect = {
+  name: "stream-word",
+
+  /**
+   * Generator function controlling the word streaming effect.
+   * Handles text clearing, word-by-word revelation, and timing for natural reading flow.
+   *
+   * @param params - Text effect parameters including element reference and timing
+   * @returns Generator that controls the stream word animation timeline
+   *
+   * @example
+   * ```js
+   * yield* StreamWordEffect.run({
+   *   elementRef: textElement,
+   *   duration: 2,
+   *   delay: 0.5,
+   *   bufferTime: 0.1
+   * });
+   * ```
+   */
+  *run({
+    elementRef,
+    duration,
+    delay,
+    bufferTime = 0.1,
+  }: TextEffectParams) {
+    // Retrieve the full text content
+    const fullText = elementRef().text();
+
+    // Store the element's size to avoid resizing during animation
+    const size = elementRef().size();
+
+    // Split the text into words
+    const words = fullText.split(" ");
+
+    // Clear the text and set fixed size
+    elementRef().setText("");
+    elementRef().size(size);
+
+    // Wait for optional delay before starting
+    if (delay) {
+      yield* waitFor(delay);
+    }
+
+    // Align text to the left
+    elementRef().textAlign("left");
+
+    // Calculate the interval between words
+    let timeInterval =(duration - bufferTime) / words.length;
+
+    // Reveal each word one at a time
+    for (let i = 0; i < words.length; i++) {
+      yield* waitFor(timeInterval);
+      elementRef().setText(words.slice(0, i + 1).join(" "));
+    }
+  },
+};

package/src/text-effects/typewriter.tsx

@@ -1,59 +1,93 @@
-import { waitFor } from "@twick/core";
-import { TextEffectParams } from "../helpers/types";
-
-/**
- * TypewriterEffect animates text appearing one character at a time,
- * mimicking the behavior of a classic typewriter.
- *
- * Behavior:
- * - Optionally waits for a delay before starting.
- * - Clears the text initially and preserves the element's original size.
- * - Reveals one character at a time at a consistent interval.
- *
- * @param elementRef - Reference to the text element to animate.
- * @param duration - Total duration of the animation.
- * @param delay - Optional delay before starting.
- * @param bufferTime - Time reserved at the end of animation (default: 0.1).
- */
-export const TypewriterEffect = {
-  name: "typewriter",
-
-  /**
-   * Generator function controlling the character-by-character typing animation.
-   */
-  *run({
-    elementRef,
-    duration,
-    delay,
-    bufferTime = 0.1,
-  }: TextEffectParams) {
-    // Retrieve the full text content
-    const fullText = elementRef().text();
-
-    // Store the element's size to prevent resizing during animation
-    const size = elementRef().size();
-
-    // Clear the text and set fixed size
-    elementRef().setText("");
-    elementRef().size(size);
-
-    // Align text to the left for consistent typing effect
-    elementRef().textAlign("left");
-
-    // Wait for an optional initial delay
-    if (delay) {
-      yield* waitFor(delay);
-    }
-
-    let timeInterval =(duration - bufferTime) / fullText.length;
-
-    // Wait briefly before starting typing
-    yield* waitFor(timeInterval);
-
-    // Reveal each character one by one
-    for (let i = 0; i < fullText.length; i++) {
-      yield* waitFor(timeInterval);
-      elementRef().setText(fullText.substring(0, i + 1));
-    }
-  },
-};
+import { waitFor } from "@twick/core";
+import { TextEffectParams } from "../helpers/types";
+
+/**
+ * @group TypewriterEffect
+ * TypewriterEffect animates text appearing one character at a time, mimicking the
+ * behavior of a classic typewriter. Creates a nostalgic, engaging text animation
+ * that draws attention to important content.
+ *
+ * Behavior:
+ * - Optionally waits for a delay before starting
+ * - Clears the text initially and preserves the element's original size
+ * - Reveals one character at a time at a consistent interval
+ *
+ * @param elementRef - Reference to the text element to animate
+ * @param duration - Total duration of the animation in seconds
+ * @param delay - Optional delay before starting in seconds
+ * @param bufferTime - Time reserved at the end of animation in seconds
+ * 
+ * @example
+ * ```js
+ * // Basic typewriter effect
+ * textEffect: {
+ *   name: "typewriter",
+ *   duration: 3,
+ *   interval: 0.1
+ * }
+ * 
+ * // With delay and buffer time
+ * textEffect: {
+ *   name: "typewriter",
+ *   duration: 5,
+ *   delay: 1,
+ *   bufferTime: 0.5
+ * }
+ * ```
+ */
+export const TypewriterEffect = {
+  name: "typewriter",
+
+  /**
+   * Generator function controlling the character-by-character typing animation.
+   * Handles text clearing, character revelation, and timing for the typewriter effect.
+   *
+   * @param params - Text effect parameters including element reference and timing
+   * @returns Generator that controls the typewriter animation timeline
+   * 
+   * @example
+   * ```js
+   * yield* TypewriterEffect.run({
+   *   elementRef: textElement,
+   *   duration: 3,
+   *   delay: 0.5,
+   *   bufferTime: 0.1
+   * });
+   * ```
+   */
+  *run({
+    elementRef,
+    duration,
+    delay,
+    bufferTime = 0.1,
+  }: TextEffectParams) {
+    // Retrieve the full text content
+    const fullText = elementRef().text();
+
+    // Store the element's size to prevent resizing during animation
+    const size = elementRef().size();
+
+    // Clear the text and set fixed size
+    elementRef().setText("");
+    elementRef().size(size);
+
+    // Align text to the left for consistent typing effect
+    elementRef().textAlign("left");
+
+    // Wait for an optional initial delay
+    if (delay) {
+      yield* waitFor(delay);
+    }
+
+    let timeInterval =(duration - bufferTime) / fullText.length;
+
+    // Wait briefly before starting typing
+    yield* waitFor(timeInterval);
+
+    // Reveal each character one by one
+    for (let i = 0; i < fullText.length; i++) {
+      yield* waitFor(timeInterval);
+      elementRef().setText(fullText.substring(0, i + 1));
+    }
+  },
+};

package/src/visualizer-grouped.ts

@@ -0,0 +1,83 @@
+/**
+ * @twick/visualizer - Professional Video Visualization Library
+ * 
+ * A comprehensive TypeScript library for creating dynamic video visualizations with
+ * animations, effects, and interactive elements. Built on top of @twick/2d and @twick/core
+ * for high-performance 2D graphics and animation.
+ * 
+ * @packageDocumentation
+ */
+
+// Types
+export * from './helpers/types';
+
+// Core functionality
+export * from './visualizer';
+
+/**
+ * @group Core
+ * @description Main scene generator and core functionality
+ */
+export { scene } from './visualizer';
+
+/**
+ * @group Animations
+ * @description Motion effects and transitions for elements
+ */
+
+// Basic animations
+export { FadeAnimation } from './animations/fade';
+export { RiseAnimation } from './animations/rise';
+
+// Advanced animations
+export { BlurAnimation } from './animations/blur';
+export { BreatheAnimation } from './animations/breathe';
+export { SuccessionAnimation } from './animations/succession';
+
+// Photo-specific animations
+export { PhotoRiseAnimation } from './animations/photo-rise';
+export { PhotoZoomAnimation } from './animations/photo-zoom';
+
+/**
+ * @group Elements
+ * @description Visual components for creating scenes and content
+ */
+
+// Media elements
+export { VideoElement } from './elements/video.element';
+export { ImageElement } from './elements/image.element';
+export { AudioElement } from './elements/audio.element';
+
+// Text and caption elements
+export { TextElement } from './elements/text.element';
+export { CaptionElement } from './elements/caption.element';
+
+// Shape and UI elements
+export { RectElement } from './elements/rect.element';
+export { CircleElement } from './elements/circle.element';
+export { IconElement } from './elements/icon.element';
+
+// Special elements
+export { SceneElement } from './elements/scene.element';
+
+/**
+ * @group Text Effects
+ * @description Text animation and styling effects
+ */
+
+// Basic text effects
+export { TypewriterEffect } from './text-effects/typewriter';
+export { StreamWordEffect } from './text-effects/stream-word';
+
+// Advanced text effects
+export { ElasticEffect } from './text-effects/elastic';
+export { EraseEffect } from './text-effects/erase';
+
+/**
+ * @group Frame Effects
+ * @description Visual frame and masking effects
+ */
+
+// Frame effects
+export { CircleFrameEffect } from './frame-effects/circle.frame';
+export { RectFrameEffect } from './frame-effects/rect.frame';