@twick/video-editor 0.15.15 → 0.15.16

package/dist/helpers/constants.d.ts

@@ -4,17 +4,6 @@ import { TimelineTickConfig } from '../components/video-editor';
 /**
  * Initial timeline data structure for new video editor projects.
  * Provides a default timeline with a sample text element to get started.
- *
- * @example
- * ```js
- * import { INITIAL_TIMELINE_DATA } from '@twick/video-editor';
- *
- * // Use as starting point for new projects
- * const newProject = {
- *   ...INITIAL_TIMELINE_DATA,
- *   tracks: [...INITIAL_TIMELINE_DATA.tracks, newTrack]
- * };
- * ```
  */
 export declare const INITIAL_TIMELINE_DATA: {
     tracks: {
@@ -39,43 +28,8 @@ export declare const INITIAL_TIMELINE_DATA: {
 /**
  * Minimum duration for timeline elements in seconds.
  * Used to prevent elements from having zero or negative duration.
- *
- * @example
- * ```js
- * import { MIN_DURATION } from '@twick/video-editor';
- *
- * const elementDuration = Math.max(duration, MIN_DURATION);
- * // Ensures element has at least 0.1 seconds duration
- * ```
  */
 export declare const MIN_DURATION = 0.1;
-/**
- * Drag operation types for timeline interactions.
- * Defines the different phases of drag operations on timeline elements.
- *
- * @example
- * ```js
- * import { DRAG_TYPE } from '@twick/video-editor';
- *
- * function handleDrag(type) {
- *   switch (type) {
- *     case DRAG_TYPE.START:
- *       // Handle drag start
- *       break;
- *     case DRAG_TYPE.MOVE:
- *       // Handle drag move
- *       break;
- *     case DRAG_TYPE.END:
- *       // Handle drag end
- *       break;
- *   }
- * }
- * ```
- */
-/**
- * MIME type for media items dragged from the studio's media panels (video, audio, image)
- * to the timeline. The data format is JSON: { type: "video"|"audio"|"image", url: string }.
- */
 export declare const TIMELINE_DROP_MEDIA_TYPE = "application/x-twick-media";
 export declare const DRAG_TYPE: {
     /** Drag operation is starting */
@@ -85,35 +39,10 @@ export declare const DRAG_TYPE: {
     /** Drag operation has ended */
     readonly END: "end";
 };
-/**
- * Default zoom level for timeline view.
- * Controls the initial magnification of the timeline interface.
- *
- * @example
- * ```js
- * import { DEFAULT_TIMELINE_ZOOM } from '@twick/video-editor';
- *
- * const [zoom, setZoom] = useState(DEFAULT_TIMELINE_ZOOM);
- * // Timeline starts with 1.5x zoom
- * ```
- */
 export declare const DEFAULT_TIMELINE_ZOOM = 1.5;
 /**
  * Default timeline zoom configuration including min, max, step, and default values.
  * Controls the zoom behavior and constraints for the timeline view.
- *
- * @example
- * ```js
- * import { DEFAULT_TIMELINE_ZOOM_CONFIG } from '@twick/video-editor';
- *
- * // Use default zoom configuration
- * <VideoEditor
- *   editorConfig={{
- *     videoProps: { width: 1920, height: 1080 },
- *     timelineZoomConfig: DEFAULT_TIMELINE_ZOOM_CONFIG
- *   }}
- * />
- * ```
  */
 /**
  * Default frames per second for timeline time display.
@@ -139,54 +68,16 @@ export declare const DEFAULT_TIMELINE_ZOOM_CONFIG: {
  *
  * Each configuration applies when the duration is less than the specified threshold.
  * Configurations are ordered by duration threshold ascending.
- *
- * @example
- * ```js
- * import { DEFAULT_TIMELINE_TICK_CONFIGS } from '@twick/video-editor';
- *
- * // Use default configurations
- * <VideoEditor
- *   editorConfig={{
- *     videoProps: { width: 1920, height: 1080 },
- *     timelineTickConfigs: DEFAULT_TIMELINE_TICK_CONFIGS
- *   }}
- * />
- * ```
  */
 export declare const DEFAULT_TIMELINE_TICK_CONFIGS: TimelineTickConfig[];
 /**
  * Default color scheme for different element types in the timeline.
  * Provides consistent visual distinction between various timeline elements.
- *
- * @example
- * ```js
- * import { DEFAULT_ELEMENT_COLORS } from '@twick/video-editor';
- *
- * const videoColor = DEFAULT_ELEMENT_COLORS.video; // "#4B2E83"
- * const textColor = DEFAULT_ELEMENT_COLORS.text;   // "#375A7F"
- *
- * // Apply colors to timeline elements
- * element.style.backgroundColor = DEFAULT_ELEMENT_COLORS[element.type];
- * ```
  */
 export declare const DEFAULT_ELEMENT_COLORS: ElementColors;
 /**
  * Available text fonts for video editor text elements.
  * Includes Google Fonts, display fonts, and custom CDN fonts.
- *
- * @example
- * ```js
- * import { AVAILABLE_TEXT_FONTS } from '@twick/video-editor';
- *
- * // Use Google Fonts
- * const googleFont = AVAILABLE_TEXT_FONTS.ROBOTO; // "Roboto"
- *
- * // Use decorative fonts
- * const decorativeFont = AVAILABLE_TEXT_FONTS.BANGERS; // "Bangers"
- *
- * // Apply font to text element
- * textElement.style.fontFamily = AVAILABLE_TEXT_FONTS.POPPINS;
- * ```
  */
 export declare const AVAILABLE_TEXT_FONTS: {
     /** Modern sans-serif font */

package/dist/helpers/function.utils.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Creates a debounced version of a function.
+ * The function will only be called after it has not been invoked
+ * for the specified delay.
+ *
+ * Useful for expensive operations that should not run on every
+ * keystroke / mouse move (e.g. resize handlers, search, etc.).
+ */
+export declare function debounce<T extends (...args: any[]) => any>(fn: T, delay: number): (...args: Parameters<T>) => void;
+/**
+ * Creates a throttled version of a function.
+ * The function will be called at most once in every `interval`
+ * milliseconds, ignoring additional calls in between.
+ *
+ * Useful for high–frequency events like scroll / mousemove where
+ * you still want regular updates but not on every event.
+ */
+export declare function throttle<T extends (...args: any[]) => any>(fn: T, interval: number): (...args: Parameters<T>) => void;

package/dist/hooks/use-player-manager.d.ts

@@ -27,8 +27,9 @@ export declare const usePlayerManager: ({ videoProps, canvasConfig, }: {
 }) => {
     twickCanvas: any;
     projectData: any;
-    updateCanvas: (seekTime: number) => void;
+    updateCanvas: (seekTime: number, forceRefresh?: boolean) => void;
     buildCanvas: any;
+    resizeCanvas: any;
     onPlayerUpdate: (event: CustomEvent) => void;
     playerUpdating: boolean;
     handleDropOnCanvas: (payload: CanvasDropPayload) => Promise<void>;

package/dist/index.d.ts

@@ -15,6 +15,7 @@ import { setElementColors } from './helpers/editor.utils';
 export { setElementColors };
 export type { MediaItem, PaginationOptions, SearchOptions, Animation, TextEffect, ElementColors };
 export type { PlayerControlsProps, VideoEditorProps, VideoEditorConfig, TimelineTickConfig, TimelineZoomConfig, CanvasConfig };
+export { throttle, debounce } from './helpers/function.utils';
 export { ANIMATIONS, TEXT_EFFECTS };
 export { usePlayerControl, useEditorManager, BrowserMediaManager, BaseMediaManager, animationGifs, getAnimationGif, PlayerControls, TimelineManager, useTimelineControl };
 export * from './helpers/constants';

package/dist/index.js

@@ -6885,9 +6885,9 @@ const CANVAS_OPERATIONS = {
   CAPTION_PROPS_UPDATED: "CAPTION_PROPS_UPDATED",
   /** Watermark has been updated */
   WATERMARK_UPDATED: "WATERMARK_UPDATED",
-  /** A new element was added via drop on canvas; payload is { element } */
+  /** A new element was added via drop on canvas; payload is { element } */
   ADDED_NEW_ELEMENT: "ADDED_NEW_ELEMENT",
-  /** Z-order changed (bring to front / send to back). Payload is { elementId, direction }. Timeline should reorder tracks. */
+  /** Z-order changed (bring to front / send to back). Payload is { elementId, direction }. Timeline should reorder tracks. */
   Z_ORDER_CHANGED: "Z_ORDER_CHANGED"
 };
 const ELEMENT_TYPES = {
@@ -8443,6 +8443,30 @@ const useTwickCanvas = ({
     scaleX: 1,
     scaleY: 1
   });
+  const resizeCanvas = ({
+    canvasSize,
+    videoSize = videoSizeRef.current
+  }) => {
+    const canvas = twickCanvasRef.current;
+    if (!canvas || !getCanvasContext(canvas)) return;
+    if (!(videoSize == null ? void 0 : videoSize.width) || !(videoSize == null ? void 0 : videoSize.height)) return;
+    if (canvasResolutionRef.current.width === canvasSize.width && canvasResolutionRef.current.height === canvasSize.height) {
+      return;
+    }
+    canvasMetadataRef.current = {
+      width: canvasSize.width,
+      height: canvasSize.height,
+      aspectRatio: canvasSize.width / canvasSize.height,
+      scaleX: Number((canvasSize.width / videoSize.width).toFixed(2)),
+      scaleY: Number((canvasSize.height / videoSize.height).toFixed(2))
+    };
+    canvas.setDimensions({
+      width: canvasSize.width,
+      height: canvasSize.height
+    });
+    canvasResolutionRef.current = canvasSize;
+    canvas.requestRenderAll();
+  };
   const onVideoSizeChange = (videoSize) => {
     if (videoSize) {
       videoSizeRef.current = videoSize;
@@ -8716,9 +8740,7 @@ const useTwickCanvas = ({
       reorderElementsByZIndex(twickCanvas);
     }
   };
-  const addWatermarkToCanvas = ({
-    element
-  }) => {
+  const addWatermarkToCanvas = ({ element }) => {
     if (!twickCanvas) return;
     const handler = elementController.get("watermark");
     if (handler) {
@@ -8748,6 +8770,7 @@ const useTwickCanvas = ({
   return {
     twickCanvas,
     buildCanvas,
+    resizeCanvas,
     onVideoSizeChange,
     addWatermarkToCanvas,
     addElementToCanvas,
@@ -9261,6 +9284,7 @@ const usePlayerManager = ({
   const {
     twickCanvas,
     buildCanvas,
+    resizeCanvas,
     setCanvasElements,
     bringToFront,
     sendToBack,
@@ -9271,9 +9295,9 @@ const usePlayerManager = ({
     onCanvasOperation: handleCanvasOperation,
     enableShiftAxisLock: (canvasConfig == null ? void 0 : canvasConfig.enableShiftAxisLock) ?? false
   });
-  const updateCanvas = (seekTime) => {
+  const updateCanvas = (seekTime, forceRefresh = false) => {
     var _a;
-    if (changeLog === currentChangeLog.current && seekTime === prevSeekTime.current) {
+    if (!forceRefresh && changeLog === currentChangeLog.current && seekTime === prevSeekTime.current) {
       return;
     }
     prevSeekTime.current = seekTime;
@@ -9367,6 +9391,7 @@ const usePlayerManager = ({
     projectData,
     updateCanvas,
     buildCanvas,
+    resizeCanvas,
     onPlayerUpdate,
     playerUpdating,
     handleDropOnCanvas,
@@ -9460,6 +9485,47 @@ function getCanvasY(e3, container, videoSize) {
   const relY = (e3.clientY - rect.top) / rect.height;
   return Math.max(0, Math.min(videoSize.height, relY * videoSize.height));
 }
+function debounce(fn2, delay2) {
+  let timeoutId = null;
+  return (...args) => {
+    if (timeoutId !== null) {
+      clearTimeout(timeoutId);
+    }
+    timeoutId = setTimeout(() => {
+      timeoutId = null;
+      fn2(...args);
+    }, delay2);
+  };
+}
+function throttle(fn2, interval) {
+  let lastCallTime = 0;
+  let trailingTimeoutId = null;
+  let lastArgs = null;
+  return (...args) => {
+    const now2 = Date.now();
+    const remaining = interval - (now2 - lastCallTime);
+    if (remaining <= 0) {
+      if (trailingTimeoutId !== null) {
+        clearTimeout(trailingTimeoutId);
+        trailingTimeoutId = null;
+      }
+      lastCallTime = now2;
+      fn2(...args);
+    } else {
+      lastArgs = args;
+      if (trailingTimeoutId === null) {
+        trailingTimeoutId = setTimeout(() => {
+          trailingTimeoutId = null;
+          lastCallTime = Date.now();
+          if (lastArgs) {
+            fn2(...lastArgs);
+            lastArgs = null;
+          }
+        }, remaining);
+      }
+    }
+  };
+}
 const CanvasContextMenu = ({
   x: x2,
   y: y2,
@@ -9555,6 +9621,7 @@ const CanvasContextMenu = ({
     }
   );
 };
+const RESIZE_THROTTLE_MS = 200;
 const PlayerManager = ({
   videoProps,
   playerProps,
@@ -9564,6 +9631,7 @@ const PlayerManager = ({
   const containerRef = React.useRef(null);
   const canvasRef = React.useRef(null);
   const durationRef = React.useRef(0);
+  const seekTimeRef = React.useRef(0);
   const { changeLog } = timeline.useTimelineContext();
   const {
     playerState,
@@ -9576,6 +9644,7 @@ const PlayerManager = ({
     twickCanvas,
     projectData,
     updateCanvas,
+    resizeCanvas,
     playerUpdating,
     onPlayerUpdate,
     buildCanvas,
@@ -9597,19 +9666,44 @@ const PlayerManager = ({
   React.useEffect(() => {
     const container = containerRef.current;
     const canvasSize = {
-      width: container == null ? void 0 : container.clientWidth,
-      height: container == null ? void 0 : container.clientHeight
+      width: (container == null ? void 0 : container.clientWidth) ?? 0,
+      height: (container == null ? void 0 : container.clientHeight) ?? 0
     };
-    buildCanvas({
-      backgroundColor: videoProps.backgroundColor,
-      videoSize: {
-        width: videoProps.width,
-        height: videoProps.height
-      },
-      canvasSize,
-      canvasRef: canvasRef.current
-    });
+    if (canvasSize.width > 0 && canvasSize.height > 0) {
+      buildCanvas({
+        backgroundColor: videoProps.backgroundColor,
+        videoSize: {
+          width: videoProps.width,
+          height: videoProps.height
+        },
+        canvasSize,
+        canvasRef: canvasRef.current
+      });
+    }
   }, [videoProps]);
+  const handleResize = React.useMemo(
+    () => throttle(() => {
+      const container = containerRef.current;
+      if (!container || !canvasMode || !twickCanvas) return;
+      const width = container.clientWidth;
+      const height = container.clientHeight;
+      if (width <= 0 || height <= 0) return;
+      resizeCanvas({
+        canvasSize: { width, height },
+        videoSize: { width: videoProps.width, height: videoProps.height }
+      });
+      updateCanvas(seekTimeRef.current, true);
+    }, RESIZE_THROTTLE_MS),
+    [canvasMode, twickCanvas, resizeCanvas, updateCanvas, videoProps.width, videoProps.height]
+  );
+  React.useEffect(() => {
+    const container = containerRef.current;
+    if (!container || !canvasMode) return;
+    const resizeObserver = new ResizeObserver(handleResize);
+    resizeObserver.observe(container);
+    return () => resizeObserver.disconnect();
+  }, [canvasMode, handleResize]);
+  seekTimeRef.current = seekTime;
   React.useEffect(() => {
     if (twickCanvas && playerState === livePlayer.PLAYER_STATE.PAUSED) {
       updateCanvas(seekTime);
@@ -11119,13 +11213,23 @@ function SeekTrack({
       minorIntervalSec: minors > 0 ? major / (minors + 1) : major
     };
   }, [duration, timelineTickConfigs]);
-  const handleSeek = (clientX) => {
-    if (!containerRef.current) return;
-    const rect = containerRef.current.getBoundingClientRect();
-    const x2 = clientX - rect.left + (containerRef.current.scrollLeft || 0);
-    const newTime = Math.max(0, Math.min(duration, x2 / pixelsPerSecond));
-    onSeek(newTime);
-  };
+  const seekToTime = React.useCallback(
+    (time2) => {
+      const clamped = Math.max(0, Math.min(duration, time2));
+      onSeek(clamped);
+    },
+    [duration, onSeek]
+  );
+  const seekFromClientX = React.useCallback(
+    (clientX) => {
+      if (!containerRef.current) return;
+      const rect = containerRef.current.getBoundingClientRect();
+      const x2 = clientX - rect.left + (containerRef.current.scrollLeft || 0);
+      const newTime = Math.max(0, Math.min(duration, x2 / pixelsPerSecond));
+      seekToTime(newTime);
+    },
+    [duration, pixelsPerSecond, seekToTime]
+  );
   const bind = useDrag(({ event, xy: [x2], active }) => {
     if (event) {
       event.stopPropagation();
@@ -11135,10 +11239,11 @@ function SeekTrack({
     const rect = containerRef.current.getBoundingClientRect();
     const xPos = x2 - rect.left + (containerRef.current.scrollLeft || 0);
     const newTime = Math.max(0, Math.min(duration, xPos / pixelsPerSecond));
-    setDragPosition(xPos);
-    onSeek(newTime);
-    if (!active) {
+    if (active) {
+      setDragPosition(xPos);
+    } else {
       setDragPosition(null);
+      seekToTime(newTime);
     }
   });
   return /* @__PURE__ */ jsxRuntime.jsx("div", { className: "twick-seek-track", children: /* @__PURE__ */ jsxRuntime.jsxs(
@@ -11146,7 +11251,7 @@ function SeekTrack({
     {
       ref: containerRef,
       className: "twick-seek-track-container-no-scrollbar",
-      onClick: (e3) => handleSeek(e3.clientX),
+      onClick: (e3) => seekFromClientX(e3.clientX),
       style: {
         overflowX: "auto",
         overflowY: "hidden",
@@ -18960,16 +19065,20 @@ function usePlayheadScroll(scrollContainerRef, playheadPositionPx, isActive, con
     const container = scrollContainerRef.current;
     const contentX = labelWidth + playheadPositionPx;
     const scrollToKeepPlayheadVisible = () => {
-      const { scrollLeft, clientWidth } = container;
+      const { scrollLeft, clientWidth, scrollWidth } = container;
+      const maxScrollLeft = Math.max(0, scrollWidth - clientWidth);
       const minVisible = scrollLeft + margin;
       const maxVisible = scrollLeft + clientWidth - margin;
       let newScrollLeft = null;
       if (contentX < minVisible) {
-        newScrollLeft = Math.max(0, contentX - margin);
+        newScrollLeft = Math.max(0, Math.min(maxScrollLeft, contentX - margin));
       } else if (contentX > maxVisible) {
-        newScrollLeft = contentX - clientWidth + margin;
+        newScrollLeft = Math.max(
+          0,
+          Math.min(maxScrollLeft, contentX - clientWidth + margin)
+        );
       }
-      if (newScrollLeft !== null) {
+      if (newScrollLeft !== null && Math.abs(newScrollLeft - scrollLeft) > 0.5) {
         container.scrollLeft = newScrollLeft;
       }
     };
@@ -20381,9 +20490,11 @@ exports.TEXT_EFFECTS = TEXT_EFFECTS;
 exports.TIMELINE_DROP_MEDIA_TYPE = TIMELINE_DROP_MEDIA_TYPE;
 exports.TimelineManager = TimelineManager;
 exports.animationGifs = animationGifs;
+exports.debounce = debounce;
 exports.default = VideoEditor;
 exports.getAnimationGif = getAnimationGif;
 exports.setElementColors = setElementColors;
+exports.throttle = throttle;
 exports.useEditorManager = useEditorManager;
 exports.usePlayerControl = usePlayerControl;
 exports.useTimelineControl = useTimelineControl;