@twick/timeline 0.14.2 → 0.14.3

package/README.md

@@ -1,5 +1,40 @@
 # @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.
@@ -172,4 +207,55 @@ function MyComponent() {
 }
 ```
 
+## 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/track/track.d.ts

@@ -2,66 +2,318 @@ import { TrackJSON } from '../../types';
 import { TrackElement } from '../elements/base.element';
 import { TrackFriend } from './track.friend';
 
+/**
+ * Track class represents a timeline track that contains multiple elements.
+ * A track is a container for timeline elements (video, audio, text, etc.) that
+ * can be arranged sequentially or in parallel. Tracks provide validation,
+ * serialization, and element management capabilities.
+ *
+ * @example
+ * ```js
+ * import { Track, VideoElement, TextElement } from '@twick/timeline';
+ *
+ * // Create a new track
+ * const videoTrack = new Track("Video Track");
+ *
+ * // Add elements to the track
+ * const videoElement = new VideoElement({
+ *   src: "video.mp4",
+ *   start: 0,
+ *   end: 10
+ * });
+ *
+ * videoTrack.createFriend().addElement(videoElement);
+ *
+ * // Serialize the track
+ * const trackData = videoTrack.serialize();
+ * ```
+ */
 export declare class Track {
     private id;
     private name;
     private type;
     private elements;
     private validator;
+    /**
+     * Creates a new Track instance.
+     *
+     * @param name - The display name for the track
+     * @param id - Optional unique identifier (auto-generated if not provided)
+     *
+     * @example
+     * ```js
+     * const track = new Track("My Video Track");
+     * const trackWithId = new Track("Audio Track", "audio-track-1");
+     * ```
+     */
     constructor(name: string, id?: string);
     /**
-     * Create a friend instance for explicit access to protected methods
-     * This implements the Friend Class Pattern
-     * @returns TrackFriend instance
+     * Creates a friend instance for explicit access to protected methods.
+     * This implements the Friend Class Pattern to allow controlled access
+     * to protected methods while maintaining encapsulation.
+     *
+     * @returns TrackFriend instance that can access protected methods
+     *
+     * @example
+     * ```js
+     * const track = new Track("My Track");
+     * const friend = track.createFriend();
+     *
+     * // Use friend to add elements
+     * const element = new VideoElement({ src: "video.mp4", start: 0, end: 10 });
+     * friend.addElement(element);
+     * ```
      */
     createFriend(): TrackFriend;
     /**
-     * Friend method to add element (called by TrackFriend)
-     * @param element The element to add
-     * @param skipValidation If true, skips validation
+     * Friend method to add element (called by TrackFriend).
+     * Provides controlled access to the protected addElement method.
+     *
+     * @param element - The element to add to the track
+     * @param skipValidation - If true, skips validation (use with caution)
      * @returns true if element was added successfully
+     *
+     * @example
+     * ```js
+     * const track = new Track("My Track");
+     * const friend = track.createFriend();
+     * const element = new VideoElement({ src: "video.mp4", start: 0, end: 10 });
+     *
+     * const success = track.addElementViaFriend(element);
+     * // success = true if element was added successfully
+     * ```
      */
     addElementViaFriend(element: TrackElement, skipValidation?: boolean): boolean;
     /**
-     * Friend method to remove element (called by TrackFriend)
-     * @param element The element to remove
+     * Friend method to remove element (called by TrackFriend).
+     * Provides controlled access to the protected removeElement method.
+     *
+     * @param element - The element to remove from the track
+     *
+     * @example
+     * ```js
+     * const track = new Track("My Track");
+     * const element = new VideoElement({ src: "video.mp4", start: 0, end: 10 });
+     *
+     * track.removeElementViaFriend(element);
+     * // Element is removed from the track
+     * ```
      */
     removeElementViaFriend(element: TrackElement): void;
     /**
-     * Friend method to update element (called by TrackFriend)
-     * @param element The element to update
+     * Friend method to update element (called by TrackFriend).
+     * Provides controlled access to the protected updateElement method.
+     *
+     * @param element - The updated element to replace the existing one
      * @returns true if element was updated successfully
+     *
+     * @example
+     * ```js
+     * const track = new Track("My Track");
+     * const element = new VideoElement({ src: "video.mp4", start: 0, end: 10 });
+     *
+     * // Update the element
+     * element.setEnd(15);
+     * const success = track.updateElementViaFriend(element);
+     * // success = true if element was updated successfully
+     * ```
      */
     updateElementViaFriend(element: TrackElement): boolean;
+    /**
+     * Gets the unique identifier of the track.
+     *
+     * @returns The track's unique ID string
+     *
+     * @example
+     * ```js
+     * const track = new Track("My Track", "track-123");
+     * const id = track.getId(); // "track-123"
+     * ```
+     */
     getId(): string;
+    /**
+     * Gets the display name of the track.
+     *
+     * @returns The track's display name
+     *
+     * @example
+     * ```js
+     * const track = new Track("Video Track");
+     * const name = track.getName(); // "Video Track"
+     * ```
+     */
     getName(): string;
+    /**
+     * Gets the type of the track.
+     *
+     * @returns The track's type string
+     *
+     * @example
+     * ```js
+     * const track = new Track("My Track");
+     * const type = track.getType(); // "element"
+     * ```
+     */
     getType(): string;
+    /**
+     * Gets a read-only array of all elements in the track.
+     * Returns a copy of the elements array to prevent external modification.
+     *
+     * @returns Read-only array of track elements
+     *
+     * @example
+     * ```js
+     * const track = new Track("My Track");
+     * const elements = track.getElements();
+     * // elements is a read-only array of TrackElement instances
+     *
+     * elements.forEach(element => {
+     *   console.log(`Element: ${element.getId()}, Duration: ${element.getEnd() - element.getStart()}`);
+     * });
+     * ```
+     */
     getElements(): ReadonlyArray<TrackElement>;
     /**
-     * Validates an element
-     * @param element The element to validate
+     * Validates a single element using the track's validator.
+     * Checks if the element meets all validation requirements.
+     *
+     * @param element - The element to validate
      * @returns true if valid, throws ValidationError if invalid
+     *
+     * @example
+     * ```js
+     * const track = new Track("My Track");
+     * const element = new VideoElement({ src: "video.mp4", start: 0, end: 10 });
+     *
+     * try {
+     *   const isValid = track.validateElement(element);
+     *   console.log('Element is valid:', isValid);
+     * } catch (error) {
+     *   if (error instanceof ValidationError) {
+     *     console.log('Validation failed:', error.errors);
+     *   }
+     * }
+     * ```
      */
     validateElement(element: TrackElement): boolean;
+    /**
+     * Gets the total duration of the track.
+     * Calculates the duration based on the end time of the last element.
+     *
+     * @returns The total duration of the track in seconds
+     *
+     * @example
+     * ```js
+     * const track = new Track("My Track");
+     * const duration = track.getTrackDuration(); // 0 if no elements
+     *
+     * // After adding elements
+     * const element = new VideoElement({ src: "video.mp4", start: 0, end: 30 });
+     * track.createFriend().addElement(element);
+     * const newDuration = track.getTrackDuration(); // 30
+     * ```
+     */
     getTrackDuration(): number;
     /**
-     * Adds an element to the track with validation
-     * @param element The element to add
-     * @param skipValidation If true, skips validation (use with caution)
+     * Adds an element to the track with validation.
+     * Protected method that should be accessed through TrackFriend.
+     *
+     * @param element - The element to add to the track
+     * @param skipValidation - If true, skips validation (use with caution)
      * @returns true if element was added successfully, throws ValidationError if validation fails
+     *
+     * @example
+     * ```js
+     * const track = new Track("My Track");
+     * const element = new VideoElement({ src: "video.mp4", start: 0, end: 10 });
+     *
+     * // Use friend to access this protected method
+     * const friend = track.createFriend();
+     * const success = friend.addElement(element);
+     * ```
      */
     protected addElement(element: TrackElement, skipValidation?: boolean): boolean;
+    /**
+     * Removes an element from the track.
+     * Protected method that should be accessed through TrackFriend.
+     *
+     * @param element - The element to remove from the track
+     *
+     * @example
+     * ```js
+     * const track = new Track("My Track");
+     * const element = new VideoElement({ src: "video.mp4", start: 0, end: 10 });
+     *
+     * // Use friend to access this protected method
+     * const friend = track.createFriend();
+     * friend.removeElement(element);
+     * ```
+     */
     protected removeElement(element: TrackElement): void;
     /**
-     * Updates an element in the track with validation
-     * @param element The element to update
+     * Updates an element in the track with validation.
+     * Protected method that should be accessed through TrackFriend.
+     *
+     * @param element - The updated element to replace the existing one
      * @returns true if element was updated successfully, throws ValidationError if validation fails
+     *
+     * @example
+     * ```js
+     * const track = new Track("My Track");
+     * const element = new VideoElement({ src: "video.mp4", start: 0, end: 10 });
+     *
+     * // Use friend to access this protected method
+     * const friend = track.createFriend();
+     * element.setEnd(15);
+     * const success = friend.updateElement(element);
+     * ```
      */
     protected updateElement(element: TrackElement): boolean;
+    /**
+     * Finds an element in the track by its ID.
+     *
+     * @param id - The unique identifier of the element to find
+     * @returns The found element or undefined if not found
+     *
+     * @example
+     * ```js
+     * const track = new Track("My Track");
+     * const element = new VideoElement({ src: "video.mp4", start: 0, end: 10 });
+     * track.createFriend().addElement(element);
+     *
+     * const foundElement = track.getElementById(element.getId());
+     * // foundElement is the same element instance
+     * ```
+     */
     getElementById(id: string): Readonly<TrackElement> | undefined;
     /**
-     * Validates all elements in the track and returns combined result and per-element status
+     * Validates all elements in the track and returns combined result and per-element status.
+     * Provides detailed validation information for each element including errors and warnings.
+     *
      * @returns Object with overall isValid and array of per-element validation results
+     *
+     * @example
+     * ```js
+     * const track = new Track("My Track");
+     * const element1 = new VideoElement({ src: "video.mp4", start: 0, end: 10 });
+     * const element2 = new TextElement({ text: "Hello", start: 5, end: 15 });
+     *
+     * track.createFriend().addElement(element1);
+     * track.createFriend().addElement(element2);
+     *
+     * const validation = track.validateAllElements();
+     * console.log('Overall valid:', validation.isValid);
+     *
+     * validation.results.forEach(result => {
+     *   console.log(`Element ${result.element.getId()}: ${result.isValid ? 'Valid' : 'Invalid'}`);
+     *   if (result.errors) {
+     *     console.log('Errors:', result.errors);
+     *   }
+     *   if (result.warnings) {
+     *     console.log('Warnings:', result.warnings);
+     *   }
+     * });
+     * ```
      */
     validateAllElements(): {
         isValid: boolean;
@@ -72,6 +324,59 @@ export declare class Track {
             warnings?: string[];
         }>;
     };
+    /**
+     * Serializes the track and all its elements to JSON format.
+     * Converts the track structure to a format that can be stored or transmitted.
+     *
+     * @returns TrackJSON object representing the track and its elements
+     *
+     * @example
+     * ```js
+     * const track = new Track("My Track");
+     * const element = new VideoElement({ src: "video.mp4", start: 0, end: 10 });
+     * track.createFriend().addElement(element);
+     *
+     * const trackData = track.serialize();
+     * // trackData = {
+     * //   id: "t-abc123",
+     * //   name: "My Track",
+     * //   type: "element",
+     * //   elements: [{ ... }]
+     * // }
+     *
+     * // Save to localStorage
+     * localStorage.setItem('track-data', JSON.stringify(trackData));
+     * ```
+     */
     serialize(): TrackJSON;
+    /**
+     * Creates a Track instance from JSON data.
+     * Static factory method for deserializing track data.
+     *
+     * @param json - JSON object containing track data
+     * @returns New Track instance with loaded data
+     *
+     * @example
+     * ```js
+     * const trackData = {
+     *   id: "t-abc123",
+     *   name: "My Track",
+     *   type: "element",
+     *   elements: [
+     *     {
+     *       id: "e-def456",
+     *       type: "video",
+     *       src: "video.mp4",
+     *       start: 0,
+     *       end: 10
+     *     }
+     *   ]
+     * };
+     *
+     * const track = Track.fromJSON(trackData);
+     * console.log(track.getName()); // "My Track"
+     * console.log(track.getElements().length); // 1
+     * ```
+     */
     static fromJSON(json: any): Track;
 }