@twick/visualizer 0.14.0 → 0.14.3

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

@@ -1,103 +1,198 @@
-/**
- * Frame effects component that handles the application of various visual effects
- * to frames and elements in the scene.
- */
-
-import { all, waitFor } from "@twick/core";
-import { getTimingFunction } from "../helpers/timing.utils";
-import { fitElement } from "../helpers/element.utils";
-import {
-  DEFAULT_POSITION,
-  DEFAULT_TIMING_FUNCTION,
-} from "../helpers/constants";
-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.
- *
- * 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.
- */
-export const RectFrameEffect = {
-  name: "rect",
-
-  /**
-   * Generator function controlling the frame resizing and positioning animation.
-   */
-  *run({
-    containerRef,
-    elementRef,
-    initFrameState,
-    frameEffect,
-  }: FrameEffectParams) {
-    // Wait until the effect start time
-    yield* waitFor(frameEffect.s);
-
-    const props = frameEffect.props;
-    const sequence = [];
-
-    // Animate resizing the container
-    sequence.push(
-      containerRef().size(
-        props.frameSize,
-        props.transitionDuration,
-        getTimingFunction(props.transitionEasing ?? DEFAULT_TIMING_FUNCTION)
-      )
-    );
-
-    // Animate repositioning the container
-    sequence.push(
-      containerRef().position(
-        props.framePosition ?? { x: 0, y: 0 },
-        props.transitionDuration,
-        getTimingFunction(props.transitionEasing ?? DEFAULT_TIMING_FUNCTION)
-      )
-    );
-
-    // Animate repositioning the element inside the container
-    sequence.push(
-      elementRef().position(
-        props.elementPosition ?? DEFAULT_POSITION,
-        props.transitionDuration,
-        getTimingFunction(props.transitionEasing ?? DEFAULT_TIMING_FUNCTION)
-      )
-    );
-
-    // Animate corner radius if specified
-    sequence.push(
-      containerRef().radius(
-        props.radius ?? 0,
-        props.transitionDuration,
-        getTimingFunction(props.transitionEasing ?? DEFAULT_TIMING_FUNCTION)
-      )
-    );
-
-    // Optionally fit the element within the container based on object-fit
-    if (props.objectFit) {
-      sequence.push(
-        fitElement({
-          elementRef,
-          containerSize: {
-            x: props.frameSize[0],
-            y: props.frameSize[1],
-          },
-          elementSize: initFrameState.element.size,
-          objectFit: props.objectFit,
-        })
-      );
-    }
-
-    // Run all animations in parallel
-    yield* all(...sequence);
-  },
-};
+/**
+ * @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";
+import { getTimingFunction } from "../helpers/timing.utils";
+import { fitElement } from "../helpers/element.utils";
+import {
+  DEFAULT_POSITION,
+  DEFAULT_TIMING_FUNCTION,
+} from "../helpers/constants";
+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. 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
+ *   }
+ * }]
+ * ```
+ */
+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,
+    elementRef,
+    initFrameState,
+    frameEffect,
+  }: FrameEffectParams) {
+    // Wait until the effect start time
+    yield* waitFor(frameEffect.s);
+
+    const props = frameEffect.props;
+    const sequence = [];
+
+    // Animate resizing the container
+    sequence.push(
+      containerRef().size(
+        props.frameSize,
+        props.transitionDuration,
+        getTimingFunction(props.transitionEasing ?? DEFAULT_TIMING_FUNCTION)
+      )
+    );
+
+    // Animate repositioning the container
+    sequence.push(
+      containerRef().position(
+        props.framePosition ?? { x: 0, y: 0 },
+        props.transitionDuration,
+        getTimingFunction(props.transitionEasing ?? DEFAULT_TIMING_FUNCTION)
+      )
+    );
+
+    // Animate repositioning the element inside the container
+    sequence.push(
+      elementRef().position(
+        props.elementPosition ?? DEFAULT_POSITION,
+        props.transitionDuration,
+        getTimingFunction(props.transitionEasing ?? DEFAULT_TIMING_FUNCTION)
+      )
+    );
+
+    // Animate corner radius if specified
+    sequence.push(
+      containerRef().radius(
+        props.radius ?? 0,
+        props.transitionDuration,
+        getTimingFunction(props.transitionEasing ?? DEFAULT_TIMING_FUNCTION)
+      )
+    );
+
+    // Optionally fit the element within the container based on object-fit
+    if (props.objectFit) {
+      sequence.push(
+        fitElement({
+          elementRef,
+          containerSize: {
+            x: props.frameSize[0],
+            y: props.frameSize[1],
+          },
+          elementSize: initFrameState.element.size,
+          objectFit: props.objectFit,
+        })
+      );
+    }
+
+    // Run all animations in parallel
+    yield* all(...sequence);
+  },
+};

package/src/global.css

@@ -1,12 +1,12 @@
-@import url('https://fonts.googleapis.com/css2?family=Rubik:ital,wght@0,300..900;1,300..900&display=swap');
-@import url('https://fonts.googleapis.com/css2?family=Mulish:ital,wght@0,200..1000;1,200..1000&display=swap');
-@import url('https://fonts.googleapis.com/css2?family=Luckiest+Guy&family=Mulish:ital,wght@0,200..1000;1,200..1000&family=Playfair+Display:ital,wght@0,400..900;1,400..900&display=swap');
-@import url('https://fonts.googleapis.com/css2?family=Roboto:ital,wght@0,100;0,300;0,400;0,500;0,700;0,900;1,100;1,300;1,400;1,500;1,700;1,900&display=swap');
-@import url('https://fonts.googleapis.com/css2?family=Bangers&family=Birthstone&family=Corinthia:wght@400;700&family=Imperial+Script&family=Kumar+One+Outline&family=Londrina+Outline&family=Marck+Script&family=Montserrat:ital,wght@0,100..900;1,100..900&family=Pattaya&family=Playfair+Display:ital,wght@0,400..900;1,400..900&family=Poppins:ital,wght@0,100;0,200;0,300;0,400;0,500;0,600;0,700;0,800;0,900;1,100;1,200;1,300;1,400;1,500;1,600;1,700;1,800;1,900&display=swap');
-@import url('https://fonts.cdnfonts.com/css/peralta');
-@import url('https://fonts.cdnfonts.com/css/impact');
-@import url('https://fonts.cdnfonts.com/css/lumanosimo');
-@import url('https://fonts.cdnfonts.com/css/kapakana');
-@import url('https://fonts.cdnfonts.com/css/handyrush');
-@import url('https://fonts.cdnfonts.com/css/dasher');
+@import url('https://fonts.googleapis.com/css2?family=Rubik:ital,wght@0,300..900;1,300..900&display=swap');
+@import url('https://fonts.googleapis.com/css2?family=Mulish:ital,wght@0,200..1000;1,200..1000&display=swap');
+@import url('https://fonts.googleapis.com/css2?family=Luckiest+Guy&family=Mulish:ital,wght@0,200..1000;1,200..1000&family=Playfair+Display:ital,wght@0,400..900;1,400..900&display=swap');
+@import url('https://fonts.googleapis.com/css2?family=Roboto:ital,wght@0,100;0,300;0,400;0,500;0,700;0,900;1,100;1,300;1,400;1,500;1,700;1,900&display=swap');
+@import url('https://fonts.googleapis.com/css2?family=Bangers&family=Birthstone&family=Corinthia:wght@400;700&family=Imperial+Script&family=Kumar+One+Outline&family=Londrina+Outline&family=Marck+Script&family=Montserrat:ital,wght@0,100..900;1,100..900&family=Pattaya&family=Playfair+Display:ital,wght@0,400..900;1,400..900&family=Poppins:ital,wght@0,100;0,200;0,300;0,400;0,500;0,600;0,700;0,800;0,900;1,100;1,200;1,300;1,400;1,500;1,600;1,700;1,800;1,900&display=swap');
+@import url('https://fonts.cdnfonts.com/css/peralta');
+@import url('https://fonts.cdnfonts.com/css/impact');
+@import url('https://fonts.cdnfonts.com/css/lumanosimo');
+@import url('https://fonts.cdnfonts.com/css/kapakana');
+@import url('https://fonts.cdnfonts.com/css/handyrush');
+@import url('https://fonts.cdnfonts.com/css/dasher');
 @import url('https://fonts.cdnfonts.com/css/brittany-signature');

package/src/helpers/caption.utils.ts

@@ -1,30 +1,30 @@
-/**
- * Caption utilities for the visualizer package.
- * Provides functions for handling caption text formatting and timing.
- */
-
-/**
- * Splits a phrase into words with timing information
- * @param {string} t - The phrase to split
- * @param {number} s - Start time of the phrase
- * @param {number} e - End time of the phrase
- * @returns {Array} Array of words with timing information
- */
-export function splitPhraseTiming({ t, s, e }: { t: string, s: number, e: number }) {
-    const words = t.split(" ");
-    const totalDuration = e - s;
-    const totalLength = words.join("").length; // Total character length without spaces
-  
-    let currentTime = s;
-    return words.map((word) => {
-      const wordDuration = (word.length / totalLength) * totalDuration;
-      const wordStart = currentTime;
-      const wordEnd = wordStart + wordDuration;
-      currentTime = wordEnd;
-      return {
-        t: word,
-        s: parseFloat(wordStart.toFixed(2)),
-        e: parseFloat(wordEnd.toFixed(2)),
-      };
-    });
+/**
+ * Caption utilities for the visualizer package.
+ * Provides functions for handling caption text formatting and timing.
+ */
+
+/**
+ * Splits a phrase into words with timing information
+ * @param {string} t - The phrase to split
+ * @param {number} s - Start time of the phrase
+ * @param {number} e - End time of the phrase
+ * @returns {Array} Array of words with timing information
+ */
+export function splitPhraseTiming({ t, s, e }: { t: string, s: number, e: number }) {
+    const words = t.split(" ");
+    const totalDuration = e - s;
+    const totalLength = words.join("").length; // Total character length without spaces
+  
+    let currentTime = s;
+    return words.map((word) => {
+      const wordDuration = (word.length / totalLength) * totalDuration;
+      const wordStart = currentTime;
+      const wordEnd = wordStart + wordDuration;
+      currentTime = wordEnd;
+      return {
+        t: word,
+        s: parseFloat(wordStart.toFixed(2)),
+        e: parseFloat(wordEnd.toFixed(2)),
+      };
+    });
   }