@twick/video-editor 0.14.2 → 0.14.4

package/README.md

@@ -1,19 +1,135 @@
 # @twick/video-editor
 
-A React component for video editing and timeline management
+A React component for video editing and timeline management with advanced features.
+
+## Overview
+
+This package provides a comprehensive video editing interface with timeline management, multi-track support, and real-time preview capabilities. It integrates seamlessly with other Twick packages to create a complete video editing solution.
 
 ## Features
 
-- 🎥 Video preview with custom controls
-- ⏱️ Timeline-based editing interface
-- 📊 Multi-track timeline support
-- 🎯 Customizable video dimensions
-- 🔄 Drag-and-drop timeline reordering
-- ⚡ High-performance video rendering
+- Video preview with custom controls
+- Timeline-based editing interface
+- Multi-track timeline support
+- Customizable video dimensions
+- Drag-and-drop timeline reordering
+- High-performance video rendering
+- Real-time project updates
+- Advanced timeline manipulation
+- Professional editing tools
 
 ## Requirements
 
 - React 18 or higher
 - Browser environment with HTML5 Video support
 
-## Installation
+## Installation
+
+```bash
+npm install @twick/video-editor
+# or
+pnpm add @twick/video-editor
+```
+
+## Quick Start
+
+```tsx
+import { VideoEditor } from '@twick/video-editor';
+import { LivePlayerProvider } from '@twick/live-player';
+import { TimelineProvider } from '@twick/timeline';
+
+function App() {
+  return (
+    <LivePlayerProvider>
+      <TimelineProvider
+        initialData={{
+          timeline: [],
+          version: 0,
+        }}
+      >
+        <VideoEditor
+          leftPanel={null}
+          rightPanel={null}
+          editorConfig={{
+            videoProps: {
+              width: 720,
+              height: 1280,
+            },
+          }}
+        />
+      </TimelineProvider>
+    </LivePlayerProvider>
+  );
+}
+```
+
+## Key Features
+
+### Video Preview
+- Real-time video playback with custom controls
+- Frame-accurate timeline scrubbing
+- Multiple preview quality options
+- Responsive video display
+
+### Timeline Management
+- Multi-track timeline interface
+- Drag-and-drop element reordering
+- Visual timeline representation
+- Time-based element positioning
+
+### Editing Tools
+- Text overlay capabilities
+- Image and video element support
+- Audio track management
+- Effect and transition tools
+
+### Performance
+- Optimized rendering pipeline
+- Efficient memory management
+- Smooth playback performance
+- Real-time updates
+
+## API Reference
+
+### Components
+
+- `VideoEditor`: Main video editor component
+
+### Props
+
+- `leftPanel`: Custom left panel component
+- `rightPanel`: Custom right panel component
+- `editorConfig`: Editor configuration object
+- `videoProps`: Video properties configuration
+
+### Types
+
+- `VideoEditorProps`: Props interface for VideoEditor
+- `EditorConfig`: Editor configuration interface
+- `VideoProps`: Video properties interface
+
+For complete API documentation, refer to the generated documentation.
+
+## Browser Support
+
+This package requires a browser environment with support for:
+- HTML5 Video and Audio
+- Canvas API
+- Drag and Drop API
+- Modern JavaScript features (ES2020+)
+
+## Documentation
+
+For complete documentation, refer to the project documentation site.
+
+## License
+
+This package is licensed under the **Sustainable Use License (SUL) Version 1.0**.
+
+- Free for use in commercial and non-commercial apps
+- Can be modified and self-hosted
+- Cannot be sold, rebranded, or distributed as a standalone SDK
+
+For commercial licensing inquiries, contact: contact@kifferai.com
+
+For full license terms, see the main LICENSE.md file in the project root.

package/dist/components/controls/player-controls.d.ts

@@ -2,18 +2,57 @@ import { default as React } from 'react';
 import { PLAYER_STATE } from '@twick/live-player';
 import { TrackElement, Track } from '@twick/timeline';
 
-interface PlayerControlsProps {
+/**
+ * Props for the PlayerControls component.
+ * Defines the configuration options and callback functions for player controls.
+ *
+ * @example
+ * ```jsx
+ * <PlayerControls
+ *   selectedItem={selectedElement}
+ *   currentTime={5.5}
+ *   duration={120}
+ *   canUndo={true}
+ *   canRedo={false}
+ *   playerState={PLAYER_STATE.PLAYING}
+ *   togglePlayback={handleTogglePlayback}
+ *   onUndo={handleUndo}
+ *   onRedo={handleRedo}
+ *   onDelete={handleDelete}
+ *   onSplit={handleSplit}
+ *   zoomLevel={1.0}
+ *   setZoomLevel={handleZoomChange}
+ * />
+ * ```
+ */
+export interface PlayerControlsProps {
+    /** Currently selected timeline element or track */
     selectedItem: TrackElement | Track | null;
+    /** Current playback time in seconds */
     currentTime: number;
+    /** Total duration of the timeline in seconds */
     duration: number;
+    /** Whether undo operation is available */
     canUndo: boolean;
+    /** Whether redo operation is available */
     canRedo: boolean;
+    /** Current player state (playing, paused, refresh) */
     playerState: keyof typeof PLAYER_STATE;
+    /** Function to toggle between play and pause */
     togglePlayback: () => void;
+    /** Optional callback for undo operation */
     onUndo?: () => void;
+    /** Optional callback for redo operation */
     onRedo?: () => void;
+    /** Optional callback for delete operation */
     onDelete?: (item: TrackElement | Track) => void;
+    /** Optional callback for split operation */
     onSplit?: (item: TrackElement, splitTime: number) => void;
+    /** Current zoom level for timeline */
+    zoomLevel?: number;
+    /** Function to set zoom level */
+    setZoomLevel?: (zoom: number) => void;
+    /** Optional CSS class name for styling */
     className?: string;
 }
 declare const PlayerControls: React.FC<PlayerControlsProps>;

package/dist/components/player/player-manager.d.ts

@@ -3,6 +3,7 @@ export declare const PlayerManager: ({ videoProps, canvasMode, }: {
     videoProps: {
         width: number;
         height: number;
+        backgroundColor?: string;
     };
     canvasMode: boolean;
 }) => import("react/jsx-runtime").JSX.Element;

package/dist/components/timeline/timeline-view.d.ts

@@ -1,12 +1,13 @@
 import { Track, TrackElement } from '@twick/timeline';
 
-declare function TimelineView({ zoomLevel, selectedItem, duration, tracks, seekTrack, onReorder, onSelectionChange, onElementDrag, }: {
+declare function TimelineView({ zoomLevel, selectedItem, duration, tracks, seekTrack, onAddTrack, onReorder, onSelectionChange, onElementDrag, }: {
     timelineControls?: React.ReactNode;
     zoomLevel: number;
     duration: number;
     tracks: Track[];
     selectedItem: Track | TrackElement | null;
     seekTrack?: React.ReactNode;
+    onAddTrack: () => void;
     onReorder: (tracks: Track[]) => void;
     onElementDrag: ({ element, dragType, updates, }: {
         element: TrackElement;

package/dist/components/track/track-element.d.ts

@@ -5,7 +5,7 @@ export declare const TrackElementView: React.FC<{
     selectedItem: TrackElement | null;
     parentWidth: number;
     duration: number;
-    nextStart: number;
+    nextStart: number | null;
     prevEnd: number;
     allowOverlap: boolean;
     onSelection: (element: TrackElement) => void;

package/dist/components/video-editor.d.ts

@@ -1,18 +1,106 @@
 import { default as React } from 'react';
 
-interface VideoEditorProps {
+/**
+ * Configuration options for the video editor.
+ * Defines the video properties and editor behavior settings.
+ *
+ * @example
+ * ```js
+ * const editorConfig = {
+ *   videoProps: { width: 1920, height: 1080 },
+ *   canvasMode: true
+ * };
+ * ```
+ */
+export interface VideoEditorConfig {
+    /** Video dimensions and properties */
+    videoProps: {
+        /** Width of the video in pixels */
+        width: number;
+        /** Height of the video in pixels */
+        height: number;
+        /** Background color of the video */
+        backgroundColor?: string;
+    };
+    /** Whether to use canvas mode for rendering */
+    canvasMode?: boolean;
+}
+/**
+ * Props for the VideoEditor component.
+ * Defines the configuration options and custom panels for the video editor.
+ *
+ * @example
+ * ```jsx
+ * <VideoEditor
+ *   leftPanel={<MediaPanel />}
+ *   rightPanel={<PropertiesPanel />}
+ *   bottomPanel={<EffectsPanel />}
+ *   editorConfig={{
+ *     videoProps: { width: 1920, height: 1080 },
+ *     canvasMode: true
+ *   }}
+ *   defaultPlayControls={true}
+ * />
+ * ```
+ */
+export interface VideoEditorProps {
+    /** Custom left panel component (e.g., media library) */
     leftPanel?: React.ReactNode;
+    /** Custom right panel component (e.g., properties inspector) */
     rightPanel?: React.ReactNode;
+    /** Custom bottom panel component (e.g., effects library) */
     bottomPanel?: React.ReactNode;
+    /** Custom play controls component */
     playControls?: React.ReactNode;
+    /** Whether to show default play controls if no custom controls provided */
     defaultPlayControls?: boolean;
-    editorConfig: {
-        videoProps: {
-            width: number;
-            height: number;
-        };
-        canvasMode?: boolean;
-    };
+    /** Editor configuration including video properties and mode settings */
+    editorConfig: VideoEditorConfig;
 }
+/**
+ * VideoEditor is the main component for the Twick video editing interface.
+ * Provides a complete video editing environment with timeline management,
+ * player controls, and customizable panels for media, properties, and effects.
+ *
+ * The editor consists of:
+ * - Left panel: Media library and assets
+ * - Center: Video player and preview
+ * - Right panel: Properties and settings
+ * - Bottom: Timeline and track management
+ * - Controls: Playback controls and timeline zoom
+ *
+ * @param props - VideoEditor configuration and custom panels
+ * @returns Complete video editing interface
+ *
+ * @example
+ * ```jsx
+ * import VideoEditor from '@twick/video-editor';
+ *
+ * function MyVideoEditor() {
+ *   return (
+ *     <VideoEditor
+ *       leftPanel={<MediaLibrary />}
+ *       rightPanel={<PropertiesPanel />}
+ *       bottomPanel={<EffectsPanel />}
+ *       editorConfig={{
+ *         videoProps: { width: 1920, height: 1080 },
+ *         canvasMode: true
+ *       }}
+ *       defaultPlayControls={true}
+ *     />
+ *   );
+ * }
+ * ```
+ *
+ * @example
+ * ```jsx
+ * // Minimal configuration
+ * <VideoEditor
+ *   editorConfig={{
+ *     videoProps: { width: 1280, height: 720 }
+ *   }}
+ * />
+ * ```
+ */
 declare const VideoEditor: React.FC<VideoEditorProps>;
 export default VideoEditor;

package/dist/helpers/animation-manager.d.ts

@@ -1,3 +1,38 @@
 import { Animation } from './types';
 
+/**
+ * Collection of available animations for video editor elements.
+ * Provides predefined animation configurations with sample previews
+ * that can be applied to timeline elements.
+ *
+ * @example
+ * ```js
+ * import { ANIMATIONS } from '@twick/video-editor';
+ *
+ * // Get all available animations
+ * const allAnimations = ANIMATIONS;
+ *
+ * // Find a specific animation
+ * const fadeAnimation = ANIMATIONS.find(anim => anim.name === 'fade');
+ *
+ * // Get animation sample
+ * const sampleGif = fadeAnimation.getSample();
+ *
+ * // Apply animation to element
+ * element.setAnimation(fadeAnimation);
+ * ```
+ *
+ * @example
+ * ```js
+ * // Use animation with custom settings
+ * const riseAnimation = ANIMATIONS.find(anim => anim.name === 'rise');
+ * const customRise = {
+ *   ...riseAnimation,
+ *   direction: 'down',
+ *   interval: 2
+ * };
+ *
+ * element.setAnimation(customRise);
+ * ```
+ */
 export declare const ANIMATIONS: Animation[];

package/dist/helpers/constants.d.ts

@@ -1,5 +1,20 @@
 import { ElementColors } from './types';
 
+/**
+ * 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: {
         type: string;
@@ -20,35 +35,140 @@ export declare const INITIAL_TIMELINE_DATA: {
     }[];
     version: number;
 };
+/**
+ * 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;
+ *   }
+ * }
+ * ```
+ */
 export declare const DRAG_TYPE: {
-    START: string;
-    MOVE: string;
-    END: string;
+    /** Drag operation is starting */
+    readonly START: "start";
+    /** Drag operation is in progress */
+    readonly MOVE: "move";
+    /** 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 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: {
-    RUBIK: string;
-    MULISH: string;
-    LUCKIEST_GUY: string;
-    PLAYFAIR_DISPLAY: string;
-    ROBOTO: string;
-    POPPINS: string;
-    BANGERS: string;
-    BIRTHSTONE: string;
-    CORINTHIA: string;
-    IMPERIAL_SCRIPT: string;
-    KUMAR_ONE_OUTLINE: string;
-    LONDRI_OUTLINE: string;
-    MARCK_SCRIPT: string;
-    MONTSERRAT: string;
-    PATTAYA: string;
-    PERALTA: string;
-    IMPACT: string;
-    LUMANOSIMO: string;
-    KAPAKANA: string;
-    HANDYRUSH: string;
-    DASHER: string;
-    BRITTANY_SIGNATURE: string;
+    /** Modern sans-serif font */
+    readonly RUBIK: "Rubik";
+    /** Clean and readable font */
+    readonly MULISH: "Mulish";
+    /** Bold display font */
+    readonly LUCKIEST_GUY: "Luckiest Guy";
+    /** Elegant serif font */
+    readonly PLAYFAIR_DISPLAY: "Playfair Display";
+    /** Classic sans-serif font */
+    readonly ROBOTO: "Roboto";
+    /** Modern geometric font */
+    readonly POPPINS: "Poppins";
+    /** Comic-style display font */
+    readonly BANGERS: "Bangers";
+    /** Handwritten-style font */
+    readonly BIRTHSTONE: "Birthstone";
+    /** Elegant script font */
+    readonly CORINTHIA: "Corinthia";
+    /** Formal script font */
+    readonly IMPERIAL_SCRIPT: "Imperial Script";
+    /** Bold outline font */
+    readonly KUMAR_ONE_OUTLINE: "Kumar One Outline";
+    /** Light outline font */
+    readonly LONDRI_OUTLINE: "Londrina Outline";
+    /** Casual script font */
+    readonly MARCK_SCRIPT: "Marck Script";
+    /** Modern sans-serif font */
+    readonly MONTSERRAT: "Montserrat";
+    /** Stylish display font */
+    readonly PATTAYA: "Pattaya";
+    /** Unique display font */
+    readonly PERALTA: "Peralta";
+    /** Bold impact font */
+    readonly IMPACT: "Impact";
+    /** Handwritten-style font */
+    readonly LUMANOSIMO: "Lumanosimo";
+    /** Custom display font */
+    readonly KAPAKANA: "Kapakana";
+    /** Handwritten font */
+    readonly HANDYRUSH: "HandyRush";
+    /** Decorative font */
+    readonly DASHER: "Dasher";
+    /** Signature-style font */
+    readonly BRITTANY_SIGNATURE: "Brittany Signature";
 };

package/dist/helpers/text-effects-manager.d.ts

@@ -1,3 +1,35 @@
 import { TextEffect } from './types';
 
+/**
+ * Collection of available text effects for video editor text elements.
+ * Provides predefined text animation configurations that can be applied
+ * to text elements in the timeline.
+ *
+ * @example
+ * ```js
+ * import { TEXT_EFFECTS } from '@twick/video-editor';
+ *
+ * // Get all available text effects
+ * const allTextEffects = TEXT_EFFECTS;
+ *
+ * // Find a specific text effect
+ * const typewriterEffect = TEXT_EFFECTS.find(effect => effect.name === 'typewriter');
+ *
+ * // Apply text effect to element
+ * textElement.setTextEffect(typewriterEffect);
+ * ```
+ *
+ * @example
+ * ```js
+ * // Use text effect with custom settings
+ * const elasticEffect = TEXT_EFFECTS.find(effect => effect.name === 'elastic');
+ * const customElastic = {
+ *   ...elasticEffect,
+ *   delay: 0.5,
+ *   bufferTime: 0.2
+ * };
+ *
+ * textElement.setTextEffect(customElastic);
+ * ```
+ */
 export declare const TEXT_EFFECTS: TextEffect[];