@twick/timeline 0.14.0 → 0.14.3

package/README.md

@@ -1,175 +1,261 @@
-# @twick/timeline
-
-## Timeline Editor CRUD Operations
-
-The TimelineEditor provides a clean interface for managing tracks and elements using the visitor pattern.
-
-### Track Operations
-
-```typescript
-import { TimelineEditor, TimelineOperationContext } from '@twick/timeline';
-
-// Create editor with context
-const context: TimelineOperationContext = {
-  contextId: 'my-editor',
-  setTotalDuration: (duration) => console.log('Duration:', duration),
-  setPresent: (data) => console.log('Present:', data),
-  handleUndo: () => console.log('Undo'),
-  handleRedo: () => console.log('Redo'),
-  handleResetHistory: () => console.log('Reset History'),
-  setLatestProjectVersion: (version) => console.log('Version:', version),
-  setTimelineAction: (action, payload) => console.log('Action:', action, payload),
-};
-
-const editor = new TimelineEditor(context);
-
-// Create a new track
-const track = editor.addTrack('My Video Track');
-
-// Get track by ID
-const trackById = editor.getTrackById(track.getId());
-
-// Get track by name
-const trackByName = editor.getTrackByName('My Video Track');
-
-// Remove track
-editor.removeTrackById(track.getId());
-```
-
-### Element Operations (Using Visitor Pattern)
-
-The TimelineEditor uses the visitor pattern to handle different element types consistently:
-
-```typescript
-import { 
-  TimelineEditor, 
-  TextElement, 
-  VideoElement, 
-  ImageElement,
-  AudioElement,
-  TrackElement
-} from '@twick/timeline';
-
-// Add elements to track
-const textElement = new TextElement('Hello World')
-  .setStart(0)
-  .setEnd(5)
-  .setName('Welcome Text');
-
-const videoElement = new VideoElement('video.mp4', { width: 720, height: 480 })
-  .setStart(0)
-  .setEnd(30)
-  .setName('Main Video');
-
-// Add elements using visitor pattern
-await editor.addElementToTrack(track.getId(), textElement);
-await editor.addElementToTrack(track.getId(), videoElement);
-
-// Update elements
-const updatedTextElement = new TextElement('Updated Text')
-  .setId(textElement.getId()) // Keep same ID
-  .setStart(0)
-  .setEnd(8)
-  .setName('Updated Welcome Text');
-
-editor.updateElementInTrack(track.getId(), updatedTextElement);
-
-// Remove elements
-editor.removeElementFromTrack(track.getId(), textElement);
-```
-
-### Complete CRUD Example
-
-```typescript
-// Create editor and track
-const editor = new TimelineEditor(context);
-const track = editor.addTrack('Demo Track');
-
-// Create elements
-const textElement = new TextElement('Sample Text')
-  .setStart(0)
-  .setEnd(5)
-  .setName('Sample Text Element');
-
-const imageElement = new ImageElement('image.jpg', { width: 300, height: 200 })
-  .setStart(5)
-  .setEnd(10)
-  .setName('Sample Image');
-
-// Add elements
-await editor.addElementToTrack(track.getId(), textElement);
-await editor.addElementToTrack(track.getId(), imageElement);
-
-// Update element
-const updatedText = new TextElement('Updated Sample Text')
-  .setId(textElement.getId())
-  .setStart(0)
-  .setEnd(8)
-  .setName('Updated Text Element');
-
-editor.updateElementInTrack(track.getId(), updatedText);
-
-// Remove element
-editor.removeElementFromTrack(track.getId(), imageElement);
-
-// Get timeline data
-const timelineData = editor.getTimelineData();
-console.log('Timeline:', timelineData);
-```
-
-### Utility Functions
-
-```typescript
-import { 
-  getCurrentElements, 
-  getTotalDuration, 
-  generateShortUuid,
-  isElementId,
-  isTrackId 
-} from '@twick/timeline';
-
-// Get elements currently playing at a specific time
-const currentElements = getCurrentElements(currentTime, tracks);
-
-// Get total duration of all tracks
-const totalDuration = getTotalDuration(trackData);
-
-// Generate unique IDs
-const elementId = generateShortUuid(); // "e-xxxxxxxxxxxx"
-const trackId = generateShortUuid();   // "t-xxxxxxxxxxxx"
-
-// Check ID types
-isElementId('e-123456789abc'); // true
-isTrackId('t-123456789abc');   // true
-```
-
-### Visitor Pattern Benefits
-
-- **Type Safety**: Each element type is handled specifically
-- **Extensibility**: Easy to add new element types
-- **Consistency**: Same pattern for all CRUD operations
-- **Maintainability**: Clean separation of concerns
-
-### React Hook Usage
-
-```typescript
-import { useTimelineContext } from '@twick/timeline';
-
-function MyComponent() {
-  const { editor } = useTimelineContext();
-  
-  // Use editor methods
-  const track = editor.addTrack('My Track');
-  
-  // Add elements
-  const textElement = new TextElement('Hello World')
-    .setStart(0)
-    .setEnd(5);
-    
-  await editor.addElementToTrack(track.getId(), textElement);
-  
-  return <div>Timeline Editor Ready</div>;
-}
-```
-
-
+# @twick/timeline
+
+Timeline management and editing capabilities for video projects.
+
+## Overview
+
+This package provides a comprehensive timeline editor with CRUD operations for managing video tracks and elements. It uses the visitor pattern to handle different element types consistently and offers a fluent interface for timeline manipulation.
+
+## Installation
+
+```bash
+npm install @twick/timeline
+# or
+pnpm add @twick/timeline
+```
+
+## Quick Start
+
+```typescript
+import { TimelineEditor, TimelineOperationContext } from '@twick/timeline';
+
+// Create editor with context
+const context: TimelineOperationContext = {
+  contextId: 'my-editor',
+  setTotalDuration: (duration) => console.log('Duration:', duration),
+  setPresent: (data) => console.log('Present:', data),
+  handleUndo: () => console.log('Undo'),
+  handleRedo: () => console.log('Redo'),
+  handleResetHistory: () => console.log('Reset History'),
+  setLatestProjectVersion: (version) => console.log('Version:', version),
+  setTimelineAction: (action, payload) => console.log('Action:', action, payload),
+};
+
+const editor = new TimelineEditor(context);
+const track = editor.addTrack('My Video Track');
+```
+
+## Timeline Editor CRUD Operations
+
+The TimelineEditor provides a clean interface for managing tracks and elements using the visitor pattern.
+
+### Track Operations
+
+```typescript
+import { TimelineEditor, TimelineOperationContext } from '@twick/timeline';
+
+// Create editor with context
+const context: TimelineOperationContext = {
+  contextId: 'my-editor',
+  setTotalDuration: (duration) => console.log('Duration:', duration),
+  setPresent: (data) => console.log('Present:', data),
+  handleUndo: () => console.log('Undo'),
+  handleRedo: () => console.log('Redo'),
+  handleResetHistory: () => console.log('Reset History'),
+  setLatestProjectVersion: (version) => console.log('Version:', version),
+  setTimelineAction: (action, payload) => console.log('Action:', action, payload),
+};
+
+const editor = new TimelineEditor(context);
+
+// Create a new track
+const track = editor.addTrack('My Video Track');
+
+// Get track by ID
+const trackById = editor.getTrackById(track.getId());
+
+// Get track by name
+const trackByName = editor.getTrackByName('My Video Track');
+
+// Remove track
+editor.removeTrackById(track.getId());
+```
+
+### Element Operations (Using Visitor Pattern)
+
+The TimelineEditor uses the visitor pattern to handle different element types consistently:
+
+```typescript
+import { 
+  TimelineEditor, 
+  TextElement, 
+  VideoElement, 
+  ImageElement,
+  AudioElement,
+  TrackElement
+} from '@twick/timeline';
+
+// Add elements to track
+const textElement = new TextElement('Hello World')
+  .setStart(0)
+  .setEnd(5)
+  .setName('Welcome Text');
+
+const videoElement = new VideoElement('video.mp4', { width: 720, height: 480 })
+  .setStart(0)
+  .setEnd(30)
+  .setName('Main Video');
+
+// Add elements using visitor pattern
+await editor.addElementToTrack(track.getId(), textElement);
+await editor.addElementToTrack(track.getId(), videoElement);
+
+// Update elements
+const updatedTextElement = new TextElement('Updated Text')
+  .setId(textElement.getId()) // Keep same ID
+  .setStart(0)
+  .setEnd(8)
+  .setName('Updated Welcome Text');
+
+editor.updateElementInTrack(track.getId(), updatedTextElement);
+
+// Remove elements
+editor.removeElementFromTrack(track.getId(), textElement);
+```
+
+### Complete CRUD Example
+
+```typescript
+// Create editor and track
+const editor = new TimelineEditor(context);
+const track = editor.addTrack('Demo Track');
+
+// Create elements
+const textElement = new TextElement('Sample Text')
+  .setStart(0)
+  .setEnd(5)
+  .setName('Sample Text Element');
+
+const imageElement = new ImageElement('image.jpg', { width: 300, height: 200 })
+  .setStart(5)
+  .setEnd(10)
+  .setName('Sample Image');
+
+// Add elements
+await editor.addElementToTrack(track.getId(), textElement);
+await editor.addElementToTrack(track.getId(), imageElement);
+
+// Update element
+const updatedText = new TextElement('Updated Sample Text')
+  .setId(textElement.getId())
+  .setStart(0)
+  .setEnd(8)
+  .setName('Updated Text Element');
+
+editor.updateElementInTrack(track.getId(), updatedText);
+
+// Remove element
+editor.removeElementFromTrack(track.getId(), imageElement);
+
+// Get timeline data
+const timelineData = editor.getTimelineData();
+console.log('Timeline:', timelineData);
+```
+
+### Utility Functions
+
+```typescript
+import { 
+  getCurrentElements, 
+  getTotalDuration, 
+  generateShortUuid,
+  isElementId,
+  isTrackId 
+} from '@twick/timeline';
+
+// Get elements currently playing at a specific time
+const currentElements = getCurrentElements(currentTime, tracks);
+
+// Get total duration of all tracks
+const totalDuration = getTotalDuration(trackData);
+
+// Generate unique IDs
+const elementId = generateShortUuid(); // "e-xxxxxxxxxxxx"
+const trackId = generateShortUuid();   // "t-xxxxxxxxxxxx"
+
+// Check ID types
+isElementId('e-123456789abc'); // true
+isTrackId('t-123456789abc');   // true
+```
+
+### Visitor Pattern Benefits
+
+- **Type Safety**: Each element type is handled specifically
+- **Extensibility**: Easy to add new element types
+- **Consistency**: Same pattern for all CRUD operations
+- **Maintainability**: Clean separation of concerns
+
+### React Hook Usage
+
+```typescript
+import { useTimelineContext } from '@twick/timeline';
+
+function MyComponent() {
+  const { editor } = useTimelineContext();
+  
+  // Use editor methods
+  const track = editor.addTrack('My Track');
+  
+  // Add elements
+  const textElement = new TextElement('Hello World')
+    .setStart(0)
+    .setEnd(5);
+    
+  await editor.addElementToTrack(track.getId(), textElement);
+  
+  return <div>Timeline Editor Ready</div>;
+}
+```
+
+## API Reference
+
+### Core Classes
+
+- `TimelineEditor`: Main timeline editor class
+- `TextElement`: Text element implementation
+- `VideoElement`: Video element implementation
+- `ImageElement`: Image element implementation
+- `AudioElement`: Audio element implementation
+
+### Hooks
+
+- `useTimelineContext`: React hook for timeline context
+
+### Utility Functions
+
+- `getCurrentElements`: Get elements at specific time
+- `getTotalDuration`: Calculate total timeline duration
+- `generateShortUuid`: Generate unique IDs
+- `isElementId`: Check if ID is element type
+- `isTrackId`: Check if ID is track type
+
+### Types
+
+- `TimelineOperationContext`: Context interface for timeline operations
+- `TrackElement`: Base track element interface
+
+For complete API documentation, refer to the generated documentation.
+
+## Browser Support
+
+This package requires a browser environment with support for:
+- Modern JavaScript features (ES2020+)
+- Promise and async/await support
+
+## 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/context/timeline-context.d.ts

@@ -3,31 +3,134 @@ import { TrackElement } from '../core/elements/base.element';
 import { ProjectJSON, TrackJSON } from '../types';
 import { TimelineEditor } from '../core/editor/timeline.editor';
 
+/**
+ * Type definition for the Timeline context.
+ * Contains all the state and functions needed to manage a timeline instance.
+ * Provides access to the timeline editor, selected items, undo/redo functionality,
+ * and timeline actions.
+ *
+ * @example
+ * ```js
+ * const {
+ *   editor,
+ *   selectedItem,
+ *   totalDuration,
+ *   canUndo,
+ *   canRedo,
+ *   setSelectedItem,
+ *   setTimelineAction
+ * } = useTimelineContext();
+ * ```
+ */
 export type TimelineContextType = {
+    /** Unique identifier for this timeline context */
     contextId: string;
+    /** The timeline editor instance for this context */
     editor: TimelineEditor;
+    /** Currently selected track or element */
     selectedItem: Track | TrackElement | null;
+    /** Change counter for tracking modifications */
     changeLog: number;
+    /** Current timeline action being performed */
     timelineAction: {
         type: string;
         payload: any;
     };
+    /** Total duration of the timeline in seconds */
     totalDuration: number;
+    /** Current project state */
     present: ProjectJSON | null;
+    /** Whether undo operation is available */
     canUndo: boolean;
+    /** Whether redo operation is available */
     canRedo: boolean;
+    /** Function to set the selected item */
     setSelectedItem: (item: Track | TrackElement | null) => void;
+    /** Function to set timeline actions */
     setTimelineAction: (type: string, payload: any) => void;
 };
+/**
+ * Props for the TimelineProvider component.
+ * Defines the configuration options for timeline context initialization.
+ *
+ * @example
+ * ```jsx
+ * <TimelineProvider
+ *   contextId="my-timeline"
+ *   initialData={{ tracks: [], version: 1 }}
+ *   undoRedoPersistenceKey="timeline-state"
+ *   maxHistorySize={50}
+ * >
+ *   <YourApp />
+ * </TimelineProvider>
+ * ```
+ */
 export interface TimelineProviderProps {
+    /** React children to wrap with timeline context */
     children: React.ReactNode;
+    /** Unique identifier for this timeline context */
     contextId: string;
+    /** Initial timeline data to load */
     initialData?: {
         tracks: TrackJSON[];
         version: number;
     };
+    /** Key for persisting undo/redo state */
     undoRedoPersistenceKey?: string;
+    /** Maximum number of history states to keep */
     maxHistorySize?: number;
 }
+/**
+ * Provider component for the Timeline context.
+ * Wraps the timeline functionality with PostHog analytics and undo/redo support.
+ * Manages the global state for timeline instances including tracks, elements,
+ * playback state, and history management.
+ *
+ * @param props - Timeline provider configuration
+ * @returns Context provider with timeline state management
+ *
+ * @example
+ * ```jsx
+ * <TimelineProvider
+ *   contextId="my-timeline"
+ *   initialData={{ tracks: [], version: 1 }}
+ *   undoRedoPersistenceKey="timeline-state"
+ * >
+ *   <YourApp />
+ * </TimelineProvider>
+ * ```
+ */
 export declare const TimelineProvider: ({ contextId, children, initialData, undoRedoPersistenceKey, maxHistorySize, }: TimelineProviderProps) => import("react/jsx-runtime").JSX.Element;
+/**
+ * Hook to access the Timeline context.
+ * Provides access to timeline state, editor instance, and timeline management functions.
+ * Must be used within a TimelineProvider component.
+ *
+ * @returns TimelineContextType object with all timeline state and controls
+ * @throws Error if used outside of TimelineProvider
+ *
+ * @example
+ * ```js
+ * const {
+ *   editor,
+ *   selectedItem,
+ *   totalDuration,
+ *   canUndo,
+ *   canRedo,
+ *   setSelectedItem,
+ *   setTimelineAction
+ * } = useTimelineContext();
+ *
+ * // Access the timeline editor
+ * const tracks = editor.getTracks();
+ *
+ * // Check if undo is available
+ * if (canUndo) {
+ *   editor.undo();
+ * }
+ *
+ * // Set timeline action
+ * setTimelineAction(TIMELINE_ACTION.SET_PLAYER_STATE, { playing: true });
+ * ```
+ */
 export declare const useTimelineContext: () => TimelineContextType;

package/dist/core/addOns/animation.d.ts

@@ -14,11 +14,11 @@ export declare class ElementAnimation {
     getAnimate(): "enter" | "exit" | "both" | undefined;
     getMode(): "in" | "out" | undefined;
     getDirection(): "left" | "center" | "right" | "up" | "down" | undefined;
-    setInterval(interval?: number): void;
-    setIntensity(intensity?: number): void;
-    setAnimate(animate?: "enter" | "exit" | "both"): void;
-    setMode(mode?: "in" | "out"): void;
-    setDirection(direction?: "up" | "down" | "left" | "right" | "center"): void;
+    setInterval(interval?: number): this;
+    setIntensity(intensity?: number): this;
+    setAnimate(animate?: "enter" | "exit" | "both"): this;
+    setMode(mode?: "in" | "out"): this;
+    setDirection(direction?: "up" | "down" | "left" | "right" | "center"): this;
     toJSON(): Animation;
     static fromJSON(json: Animation): ElementAnimation;
 }

package/dist/core/addOns/frame-effect.d.ts

@@ -5,10 +5,12 @@ export declare class ElementFrameEffect {
     private e;
     private props;
     constructor(start: number, end: number);
-    setProps(props: FrameEffectProps): void;
+    setProps(props: FrameEffectProps): this;
     getProps(): FrameEffectProps;
     getStart(): number;
     getEnd(): number;
+    setStart(start: number): this;
+    setEnd(end: number): this;
     toJSON(): FrameEffect;
     static fromJSON(json: FrameEffect): ElementFrameEffect;
 }

package/dist/core/addOns/text-effect.d.ts

@@ -10,10 +10,9 @@ export declare class ElementTextEffect {
     getDuration(): number | undefined;
     getDelay(): number | undefined;
     getBufferTime(): number | undefined;
-    setName(name: string): void;
-    setDuration(duration?: number): void;
-    setDelay(delay?: number): void;
-    setBufferTime(bufferTime?: number): void;
+    setDuration(duration?: number): this;
+    setDelay(delay?: number): this;
+    setBufferTime(bufferTime?: number): this;
     toJSON(): TextEffect;
     static fromJSON(json: TextEffect): ElementTextEffect;
 }

package/dist/core/editor/timeline.editor.d.ts

@@ -26,6 +26,7 @@ export interface TimelineOperationContext {
  */
 export declare class TimelineEditor {
     private context;
+    private totalDuration;
     constructor(context: TimelineOperationContext);
     getContext(): TimelineOperationContext;
     pauseVideo(): void;
@@ -91,4 +92,5 @@ export declare class TimelineEditor {
         tracks: TrackJSON[];
         version: number;
     }): void;
+    getVideoAudio(): Promise<string>;
 }

package/dist/core/elements/audio.element.d.ts

@@ -8,6 +8,10 @@ export declare class AudioElement extends TrackElement {
     constructor(src: string);
     getMediaDuration(): number;
     getStartAt(): number;
+    getEndAt(): number;
+    getSrc(): string;
+    getPlaybackRate(): number;
+    getVolume(): number;
     updateAudioMeta(): Promise<void>;
     setSrc(src: string): Promise<this>;
     setMediaDuration(mediaDuration: number): this;

package/dist/core/elements/video.element.d.ts

@@ -20,6 +20,10 @@ export declare class VideoElement extends TrackElement {
     getObjectFit(): ObjectFit;
     getMediaDuration(): number;
     getStartAt(): number;
+    getEndAt(): number;
+    getSrc(): string;
+    getPlaybackRate(): number;
+    getVolume(): number;
     getPosition(): Position;
     updateVideoMeta(updateFrame?: boolean): Promise<void>;
     setPosition(position: Position): this;
@@ -28,7 +32,6 @@ export declare class VideoElement extends TrackElement {
     setParentSize(parentSize: Size): this;
     setObjectFit(objectFit: ObjectFit): this;
     setFrame(frame: Frame): this;
-    setPlay(play: boolean): this;
     setPlaybackRate(playbackRate: number): this;
     setStartAt(time: number): this;
     setMediaFilter(mediaFilter: string): this;