@twick/video-editor 0.14.6 → 0.14.8

package/README.md

@@ -55,6 +55,24 @@ function App() {
               width: 720,
               height: 1280,
             },
+            // Optional: Customize timeline tick marks
+            timelineTickConfigs: [
+              { durationThreshold: 30, majorInterval: 5, minorTicks: 5 },
+              { durationThreshold: 300, majorInterval: 30, minorTicks: 6 }
+            ],
+            // Optional: Customize zoom behavior
+            timelineZoomConfig: {
+              min: 0.5, max: 2.0, step: 0.25, default: 1.0
+            },
+            // Optional: Customize element colors
+            elementColors: {
+              video: "#8B5FBF",
+              audio: "#3D8B8B",
+              image: "#D4956C",
+              text: "#A78EC8",
+              caption: "#9B8ACE",
+              fragment: "#1A1A1A"
+            }
           }}
         />
       </TimelineProvider>
@@ -99,14 +117,140 @@ function App() {
 
 - `leftPanel`: Custom left panel component
 - `rightPanel`: Custom right panel component
+- `bottomPanel`: Custom bottom panel component
 - `editorConfig`: Editor configuration object
-- `videoProps`: Video properties configuration
+- `defaultPlayControls`: Whether to show default playback controls
+
+### Configuration Options
+
+#### `editorConfig`
+
+```typescript
+interface VideoEditorConfig {
+  videoProps: {
+    width: number;
+    height: number;
+    backgroundColor?: string;
+  };
+  playerProps?: {
+    quality?: number;
+    maxWidth?: number;
+    maxHeight?: number;
+  };
+  canvasMode?: boolean;
+  timelineTickConfigs?: TimelineTickConfig[];
+  timelineZoomConfig?: TimelineZoomConfig;
+  elementColors?: ElementColors;
+}
+```
+
+#### Timeline Tick Configuration
+
+Customize timeline tick marks for different duration ranges:
+
+```typescript
+interface TimelineTickConfig {
+  durationThreshold: number; // Applies when duration < threshold
+  majorInterval: number;      // Major tick interval in seconds
+  minorTicks: number;         // Number of minor ticks between majors
+}
+```
+
+**Example:**
+```tsx
+timelineTickConfigs: [
+  { durationThreshold: 30, majorInterval: 5, minorTicks: 5 },    // < 30s
+  { durationThreshold: 300, majorInterval: 30, minorTicks: 6 },  // < 5min
+  { durationThreshold: 3600, majorInterval: 300, minorTicks: 5 } // < 1hr
+]
+```
+
+#### Zoom Configuration
+
+Customize timeline zoom behavior:
+
+```typescript
+interface TimelineZoomConfig {
+  min: number;     // Minimum zoom level
+  max: number;     // Maximum zoom level
+  step: number;    // Zoom step increment/decrement
+  default: number; // Default zoom level
+}
+```
+
+**Example:**
+```tsx
+timelineZoomConfig: {
+  min: 0.5,     // 50% minimum zoom
+  max: 3.0,     // 300% maximum zoom
+  step: 0.25,   // 25% zoom steps
+  default: 1.5  // 150% default zoom
+}
+```
+
+#### Element Colors
+
+Customize timeline element colors:
+
+```typescript
+interface ElementColors {
+  video: string;
+  audio: string;
+  image: string;
+  text: string;
+  caption: string;
+  fragment: string;
+}
+```
+
+**Example:**
+```tsx
+elementColors: {
+  video: "#8B5FBF",
+  audio: "#3D8B8B",
+  image: "#D4956C",
+  text: "#A78EC8",
+  caption: "#9B8ACE",
+  fragment: "#1A1A1A"
+}
+```
+
+### Default Constants
+
+The package exports default configurations that can be used or customized:
+
+```tsx
+import { 
+  DEFAULT_TIMELINE_TICK_CONFIGS,
+  DEFAULT_TIMELINE_ZOOM_CONFIG,
+  DEFAULT_ELEMENT_COLORS
+} from '@twick/video-editor';
+
+// Use defaults
+<VideoEditor
+  editorConfig={{
+    videoProps: { width: 1920, height: 1080 },
+    timelineTickConfigs: DEFAULT_TIMELINE_TICK_CONFIGS,
+    timelineZoomConfig: DEFAULT_TIMELINE_ZOOM_CONFIG,
+    elementColors: DEFAULT_ELEMENT_COLORS
+  }}
+/>
+
+// Or customize based on defaults
+const customColors = {
+  ...DEFAULT_ELEMENT_COLORS,
+  video: "#FF0000",  // Custom red for video
+  audio: "#00FF00"   // Custom green for audio
+};
+```
 
 ### Types
 
 - `VideoEditorProps`: Props interface for VideoEditor
-- `EditorConfig`: Editor configuration interface
-- `VideoProps`: Video properties interface
+- `VideoEditorConfig`: Editor configuration interface
+- `TimelineTickConfig`: Timeline tick configuration interface
+- `TimelineZoomConfig`: Zoom configuration interface
+- `ElementColors`: Element colors interface
 
 For complete API documentation, refer to the generated documentation.
 

package/dist/components/controls/control-manager.d.ts

@@ -1,5 +1,8 @@
-declare const ControlManager: ({ trackZoom, setTrackZoom, }: {
+import { TimelineZoomConfig } from '../video-editor';
+
+declare const ControlManager: ({ trackZoom, setTrackZoom, zoomConfig, }: {
     trackZoom: number;
     setTrackZoom: (zoom: number) => void;
+    zoomConfig: TimelineZoomConfig;
 }) => import("react/jsx-runtime").JSX.Element;
 export default ControlManager;

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

@@ -1,6 +1,7 @@
 import { default as React } from 'react';
 import { PLAYER_STATE } from '@twick/live-player';
 import { TrackElement, Track } from '@twick/timeline';
+import { TimelineZoomConfig } from '../video-editor';
 
 /**
  * Props for the PlayerControls component.
@@ -54,6 +55,8 @@ export interface PlayerControlsProps {
     setZoomLevel?: (zoom: number) => void;
     /** Optional CSS class name for styling */
     className?: string;
+    /** Timeline zoom configuration (min, max, step, default) */
+    zoomConfig?: TimelineZoomConfig;
 }
 declare const PlayerControls: React.FC<PlayerControlsProps>;
 export default PlayerControls;

package/dist/components/controls/seek-control.d.ts

@@ -1,7 +1,10 @@
-declare const SeekControl: ({ duration, zoom, timelineCount, onSeek, }: {
+import { TimelineTickConfig } from '../video-editor';
+
+declare const SeekControl: ({ duration, zoom, timelineCount, onSeek, timelineTickConfigs, }: {
     duration: number;
     zoom: number;
     timelineCount: number;
     onSeek: (time: number) => void;
+    timelineTickConfigs?: TimelineTickConfig[];
 }) => import("react/jsx-runtime").JSX.Element;
 export default SeekControl;

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

@@ -1,4 +1,25 @@
 
+/**
+ * PlayerManager component that manages video playback and canvas rendering.
+ * Integrates the live player with canvas operations, handling both video playback
+ * and static canvas display modes. Automatically updates canvas when paused and
+ * manages player state transitions.
+ *
+ * @param props - Component configuration props
+ * @param props.videoProps - Video dimensions and background color
+ * @param props.playerProps - Optional player quality settings
+ * @param props.canvasMode - Whether to show canvas overlay when paused
+ * @returns JSX element containing player and canvas components
+ *
+ * @example
+ * ```tsx
+ * <PlayerManager
+ *   videoProps={{ width: 1920, height: 1080, backgroundColor: '#000' }}
+ *   playerProps={{ quality: 720 }}
+ *   canvasMode={true}
+ * />
+ * ```
+ */
 export declare const PlayerManager: ({ videoProps, playerProps, canvasMode, }: {
     videoProps: {
         width: number;

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

@@ -1,4 +1,9 @@
-declare const TimelineManager: ({ trackZoom, }: {
+import { TimelineTickConfig } from '../video-editor';
+import { ElementColors } from '../../helpers/types';
+
+declare const TimelineManager: ({ trackZoom, timelineTickConfigs, elementColors, }: {
     trackZoom: number;
+    timelineTickConfigs?: TimelineTickConfig[];
+    elementColors?: ElementColors;
 }) => import("react/jsx-runtime").JSX.Element;
 export default TimelineManager;

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

@@ -1,6 +1,7 @@
 import { Track, TrackElement } from '@twick/timeline';
+import { ElementColors } from '../../helpers/types';
 
-declare function TimelineView({ zoomLevel, selectedItem, duration, tracks, seekTrack, onAddTrack, onReorder, onSelectionChange, onElementDrag, }: {
+declare function TimelineView({ zoomLevel, selectedItem, duration, tracks, seekTrack, onAddTrack, onReorder, onSelectionChange, onElementDrag, elementColors, }: {
     zoomLevel: number;
     duration: number;
     tracks: Track[];
@@ -19,5 +20,6 @@ declare function TimelineView({ zoomLevel, selectedItem, duration, tracks, seekT
     onSeek: (time: number) => void;
     onSelectionChange: (element: TrackElement | Track) => void;
     onDeletion: (element: TrackElement | Track) => void;
+    elementColors?: ElementColors;
 }): import("react/jsx-runtime").JSX.Element;
 export default TimelineView;

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

@@ -1,3 +1,4 @@
+import { TimelineTickConfig } from '../video-editor';
 
 interface SeekTrackProps {
     currentTime: number;
@@ -5,6 +6,7 @@ interface SeekTrackProps {
     zoom?: number;
     onSeek: (time: number) => void;
     timelineCount?: number;
+    timelineTickConfigs?: TimelineTickConfig[];
 }
-export default function SeekTrack({ currentTime, duration, zoom, onSeek, timelineCount, }: SeekTrackProps): import("react/jsx-runtime").JSX.Element;
+export default function SeekTrack({ currentTime, duration, zoom, onSeek, timelineCount, timelineTickConfigs, }: SeekTrackProps): import("react/jsx-runtime").JSX.Element;
 export {};

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

@@ -1,4 +1,5 @@
 import { Track, TrackElement } from '@twick/timeline';
+import { ElementColors } from '../../helpers/types';
 
 interface TrackBaseProps {
     duration: number;
@@ -16,6 +17,7 @@ interface TrackBaseProps {
             end: number;
         };
     }) => void;
+    elementColors?: ElementColors;
 }
-declare const TrackBase: ({ duration, zoom, track, trackWidth, selectedItem, onItemSelection, onDrag, allowOverlap, }: TrackBaseProps) => import("react/jsx-runtime").JSX.Element;
+declare const TrackBase: ({ duration, zoom, track, trackWidth, selectedItem, onItemSelection, onDrag, allowOverlap, elementColors, }: TrackBaseProps) => import("react/jsx-runtime").JSX.Element;
 export default TrackBase;

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

@@ -1,4 +1,5 @@
 import { TrackElement } from '@twick/timeline';
+import { ElementColors } from '../../helpers/types';
 
 export declare const TrackElementView: React.FC<{
     element: TrackElement;
@@ -17,5 +18,6 @@ export declare const TrackElementView: React.FC<{
             end: number;
         };
     }) => void;
+    elementColors?: ElementColors;
 }>;
 export default TrackElementView;

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

@@ -1,5 +1,51 @@
 import { default as React } from 'react';
+import { ElementColors } from '../helpers/types';
 
+/**
+ * Configuration for timeline tick marks at specific duration ranges.
+ * Defines major tick interval and number of minor ticks between majors.
+ *
+ * @example
+ * ```js
+ * const tickConfig = {
+ *   durationThreshold: 300, // applies when video < 5 minutes
+ *   majorInterval: 30, // major tick every 30 seconds
+ *   minorTicks: 6 // 6 minor ticks between majors (every 5 seconds)
+ * };
+ * ```
+ */
+export interface TimelineTickConfig {
+    /** Duration threshold in seconds - this config applies when duration < threshold */
+    durationThreshold: number;
+    /** Major tick interval in seconds */
+    majorInterval: number;
+    /** Number of minor ticks between major ticks */
+    minorTicks: number;
+}
+/**
+ * Configuration for timeline zoom behavior.
+ * Defines the minimum, maximum, step, and default zoom levels.
+ *
+ * @example
+ * ```js
+ * const zoomConfig = {
+ *   min: 0.5,     // 50% minimum zoom
+ *   max: 2.0,     // 200% maximum zoom
+ *   step: 0.25,   // 25% zoom steps
+ *   default: 1.0  // 100% default zoom
+ * };
+ * ```
+ */
+export interface TimelineZoomConfig {
+    /** Minimum zoom level */
+    min: number;
+    /** Maximum zoom level */
+    max: number;
+    /** Zoom step increment/decrement */
+    step: number;
+    /** Default zoom level */
+    default: number;
+}
 /**
  * Configuration options for the video editor.
  * Defines the video properties and editor behavior settings.
@@ -8,7 +54,19 @@ import { default as React } from 'react';
  * ```js
  * const editorConfig = {
  *   videoProps: { width: 1920, height: 1080 },
- *   canvasMode: true
+ *   canvasMode: true,
+ *   timelineTickConfigs: [
+ *     { durationThreshold: 30, majorInterval: 5, minorTicks: 5 },
+ *     { durationThreshold: 300, majorInterval: 30, minorTicks: 6 }
+ *   ],
+ *   timelineZoomConfig: {
+ *     min: 0.5, max: 2.0, step: 0.25, default: 1.0
+ *   },
+ *   elementColors: {
+ *     video: "#8B5FBF",
+ *     audio: "#3D8B8B",
+ *     // ... other element colors
+ *   }
  * };
  * ```
  */
@@ -29,6 +87,12 @@ export interface VideoEditorConfig {
     };
     /** Whether to use canvas mode for rendering */
     canvasMode?: boolean;
+    /** Custom timeline tick configurations for different duration ranges */
+    timelineTickConfigs?: TimelineTickConfig[];
+    /** Custom timeline zoom configuration (min, max, step, default) */
+    timelineZoomConfig?: TimelineZoomConfig;
+    /** Custom element colors for timeline elements */
+    elementColors?: ElementColors;
 }
 /**
  * Props for the VideoEditor component.

package/dist/helpers/constants.d.ts

@@ -1,4 +1,5 @@
 import { ElementColors } from './types';
+import { TimelineTickConfig } from '../components/video-editor';
 
 /**
  * Initial timeline data structure for new video editor projects.
@@ -92,6 +93,55 @@ export declare const DRAG_TYPE: {
  * ```
  */
 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
+ *   }}
+ * />
+ * ```
+ */
+export declare const DEFAULT_TIMELINE_ZOOM_CONFIG: {
+    /** Minimum zoom level (10%) */
+    min: number;
+    /** Maximum zoom level (300%) */
+    max: number;
+    /** Zoom step increment/decrement (10%) */
+    step: number;
+    /** Default zoom level (150%) */
+    default: number;
+};
+/**
+ * Default timeline tick configurations for different duration ranges.
+ * Defines major tick intervals and number of minor ticks between majors
+ * to provide optimal timeline readability at various durations.
+ *
+ * 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.

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

@@ -0,0 +1,27 @@
+import { TrackElement } from '@twick/timeline';
+
+/**
+ * Custom hook for managing video editor operations.
+ * Provides functionality to add and update timeline elements with automatic
+ * collision detection and error handling. Integrates with live player context
+ * to position elements at the current playback time.
+ *
+ * @returns Object containing editor management functions
+ * @property {Function} addElement - Add a new element to the timeline
+ * @property {Function} updateElement - Update an existing timeline element
+ *
+ * @example
+ * ```tsx
+ * const { addElement, updateElement } = useEditorManager();
+ *
+ * // Add a new element at current playback time
+ * await addElement(newElement);
+ *
+ * // Update an existing element
+ * updateElement(modifiedElement);
+ * ```
+ */
+export declare const useEditorManager: () => {
+    addElement: (element: TrackElement) => Promise<void>;
+    updateElement: (element: TrackElement) => void;
+};

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

@@ -32,6 +32,6 @@ export declare const useTimelineManager: () => {
     onReorder: (reorderedItems: Track[]) => void;
     onSeek: (time: number) => void;
     onSelectionChange: (selectedItem: TrackElement | Track | null) => void;
-    selectedItem: TrackElement | Track | null;
+    selectedItem: Track | TrackElement | null;
     totalDuration: number;
 };

package/dist/index.d.ts

@@ -1,7 +1,8 @@
-import { default as VideoEditor, VideoEditorProps, VideoEditorConfig } from './components/video-editor';
+import { default as VideoEditor, VideoEditorProps, VideoEditorConfig, TimelineTickConfig, TimelineZoomConfig } from './components/video-editor';
 import { default as PlayerControls, PlayerControlsProps } from './components/controls/player-controls';
 import { default as TimelineManager } from './components/timeline/timeline-manager';
 import { usePlayerControl } from './hooks/use-player-control';
+import { useEditorManager } from './hooks/use-editor-manager';
 import { default as BrowserMediaManager } from './helpers/media-manager/browser-media-manager';
 import { MediaItem, PaginationOptions, SearchOptions, Animation, TextEffect, ElementColors } from './helpers/types';
 import { default as BaseMediaManager } from './helpers/media-manager/base-media-manager';
@@ -13,8 +14,8 @@ import { setElementColors } from './helpers/editor.utils';
 
 export { setElementColors };
 export type { MediaItem, PaginationOptions, SearchOptions, Animation, TextEffect, ElementColors };
-export type { PlayerControlsProps, VideoEditorProps, VideoEditorConfig };
+export type { PlayerControlsProps, VideoEditorProps, VideoEditorConfig, TimelineTickConfig, TimelineZoomConfig };
 export { ANIMATIONS, TEXT_EFFECTS };
-export { usePlayerControl, BrowserMediaManager, BaseMediaManager, animationGifs, getAnimationGif, PlayerControls, TimelineManager, useTimelineControl };
+export { usePlayerControl, useEditorManager, BrowserMediaManager, BaseMediaManager, animationGifs, getAnimationGif, PlayerControls, TimelineManager, useTimelineControl };
 export * from './helpers/constants';
 export default VideoEditor;