@twick/timeline 0.14.2 → 0.14.3

package/dist/index.js

@@ -6,13 +6,19 @@ var __defNormalProp = (obj, key, value) => key in obj ? __defProp(obj, key, { en
 var __publicField = (obj, key, value) => __defNormalProp(obj, typeof key !== "symbol" ? key + "" : key, value);
 
   const PLAYER_STATE = {
+    /** Player is refreshing/reloading content */
     REFRESH: "Refresh",
+    /** Player is actively playing content */
     PLAYING: "Playing",
+    /** Player is paused */
     PAUSED: "Paused"
   };
   const CAPTION_STYLE = {
+    /** Highlights background of each word */
     WORD_BG_HIGHLIGHT: "highlight_bg",
+    /** Animates text word by word */
     WORD_BY_WORD: "word_by_word",
+    /** Animates text word by word with background highlighting */
     WORD_BY_WORD_WITH_BG: "word_by_word_with_bg"
   };
   const CAPTION_STYLE_OPTIONS = {
@@ -30,34 +36,54 @@ var __publicField = (obj, key, value) => __defNormalProp(obj, typeof key !== "sy
     }
   };
   const CAPTION_FONT = {
+    /** Font size in pixels */
     size: 40
   };
   const CAPTION_COLOR = {
+    /** Text color in hex format */
     text: "#ffffff",
+    /** Highlight color in hex format */
     highlight: "#ff4081",
+    /** Background color in hex format */
     bgColor: "#8C52FF"
   };
   const WORDS_PER_PHRASE = 4;
   const TIMELINE_ACTION = {
+    /** No action being performed */
     NONE: "none",
+    /** Setting the player state (play/pause) */
     SET_PLAYER_STATE: "setPlayerState",
+    /** Updating player data */
     UPDATE_PLAYER_DATA: "updatePlayerData",
+    /** Player has been updated */
     ON_PLAYER_UPDATED: "onPlayerUpdated"
   };
   const TIMELINE_ELEMENT_TYPE = {
+    /** Video element type */
     VIDEO: "video",
+    /** Caption element type */
     CAPTION: "caption",
+    /** Image element type */
     IMAGE: "image",
+    /** Audio element type */
     AUDIO: "audio",
+    /** Text element type */
     TEXT: "text",
+    /** Rectangle element type */
     RECT: "rect",
+    /** Circle element type */
     CIRCLE: "circle",
+    /** Icon element type */
     ICON: "icon"
   };
   const PROCESS_STATE = {
+    /** Process is idle */
     IDLE: "Idle",
+    /** Process is currently running */
     PROCESSING: "Processing",
+    /** Process has completed successfully */
     COMPLETED: "Completed",
+    /** Process has failed */
     FAILED: "Failed"
   };
   const imageDimensionsCache = {};
@@ -1684,6 +1710,18 @@ var __publicField = (obj, key, value) => __defNormalProp(obj, typeof key !== "sy
     }
   }
   class Track {
+    /**
+     * 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, id) {
       __publicField(this, "id");
       __publicField(this, "name");
@@ -1697,66 +1735,210 @@ var __publicField = (obj, key, value) => __defNormalProp(obj, typeof key !== "sy
       this.validator = new ElementValidator();
     }
     /**
-     * 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() {
       return new TrackFriend(this);
     }
     /**
-     * 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, skipValidation = false) {
       return this.addElement(element, skipValidation);
     }
     /**
-     * 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) {
       this.removeElement(element);
     }
     /**
-     * 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) {
       return this.updateElement(element);
     }
+    /**
+     * 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() {
       return this.id;
     }
+    /**
+     * 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() {
       return this.name;
     }
+    /**
+     * 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() {
       return this.type;
     }
+    /**
+     * 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() {
       return [...this.elements];
     }
     /**
-     * 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) {
       return element.accept(this.validator);
     }
+    /**
+     * 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() {
       var _a;
       return ((_a = this.elements) == null ? void 0 : _a.length) ? this.elements[this.elements.length - 1].getEnd() : 0;
     }
     /**
-     * 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);
+     * ```
      */
     addElement(element, skipValidation = false) {
       element.setTrackId(this.id);
@@ -1778,6 +1960,22 @@ var __publicField = (obj, key, value) => __defNormalProp(obj, typeof key !== "sy
       }
       return false;
     }
+    /**
+     * 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);
+     * ```
+     */
     removeElement(element) {
       const index2 = this.elements.findIndex((e2) => e2.getId() === element.getId());
       if (index2 !== -1) {
@@ -1785,9 +1983,22 @@ var __publicField = (obj, key, value) => __defNormalProp(obj, typeof key !== "sy
       }
     }
     /**
-     * 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);
+     * ```
      */
     updateElement(element) {
       try {
@@ -1809,14 +2020,55 @@ var __publicField = (obj, key, value) => __defNormalProp(obj, typeof key !== "sy
       }
       return false;
     }
+    /**
+     * 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) {
       const element = this.elements.find((e2) => e2.getId() === id);
       if (!element) return void 0;
       return element;
     }
     /**
-     * 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() {
       let validResult = true;
@@ -1846,6 +2098,30 @@ var __publicField = (obj, key, value) => __defNormalProp(obj, typeof key !== "sy
       });
       return { isValid: validResult, results };
     }
+    /**
+     * 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() {
       const serializer = new ElementSerializer();
       return {
@@ -1857,6 +2133,35 @@ var __publicField = (obj, key, value) => __defNormalProp(obj, typeof key !== "sy
         )
       };
     }
+    /**
+     * 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) {
       const track = new Track(json.name, json.id);
       track.type = json.type;
@@ -1936,12 +2241,37 @@ var __publicField = (obj, key, value) => __defNormalProp(obj, typeof key !== "sy
   let TimelineContextStore = _TimelineContextStore;
   const timelineContextStore = TimelineContextStore.getInstance();
   class ElementAdder {
+    /**
+     * Creates a new ElementAdder instance for the specified track.
+     *
+     * @param track - The track to add elements to
+     * 
+     * @example
+     * ```js
+     * const adder = new ElementAdder(track);
+     * const success = await adder.visitVideoElement(videoElement);
+     * ```
+     */
     constructor(track) {
       __publicField(this, "track");
       __publicField(this, "trackFriend");
       this.track = track;
       this.trackFriend = track.createFriend();
     }
+    /**
+     * Adds a video element to the track.
+     * Updates video metadata and calculates appropriate start/end times
+     * based on existing track elements.
+     *
+     * @param element - The video element to add
+     * @returns Promise resolving to true if element was added successfully
+     * 
+     * @example
+     * ```js
+     * const success = await adder.visitVideoElement(videoElement);
+     * // success = true if element was added successfully
+     * ```
+     */
     async visitVideoElement(element) {
       await element.updateVideoMeta();
       const elements = this.track.getElements();
@@ -1954,6 +2284,20 @@ var __publicField = (obj, key, value) => __defNormalProp(obj, typeof key !== "sy
       }
       return this.trackFriend.addElement(element);
     }
+    /**
+     * Adds an audio element to the track.
+     * Updates audio metadata and calculates appropriate start/end times
+     * based on existing track elements.
+     *
+     * @param element - The audio element to add
+     * @returns Promise resolving to true if element was added successfully
+     * 
+     * @example
+     * ```js
+     * const success = await adder.visitAudioElement(audioElement);
+     * // success = true if element was added successfully
+     * ```
+     */
     async visitAudioElement(element) {
       await element.updateAudioMeta();
       const elements = this.track.getElements();
@@ -1966,6 +2310,20 @@ var __publicField = (obj, key, value) => __defNormalProp(obj, typeof key !== "sy
       }
       return this.trackFriend.addElement(element);
     }
+    /**
+     * Adds an image element to the track.
+     * Updates image metadata and calculates appropriate start/end times
+     * based on existing track elements.
+     *
+     * @param element - The image element to add
+     * @returns Promise resolving to true if element was added successfully
+     * 
+     * @example
+     * ```js
+     * const success = await adder.visitImageElement(imageElement);
+     * // success = true if element was added successfully
+     * ```
+     */
     async visitImageElement(element) {
       await element.updateImageMeta();
       const elements = this.track.getElements();
@@ -1978,6 +2336,19 @@ var __publicField = (obj, key, value) => __defNormalProp(obj, typeof key !== "sy
       }
       return this.trackFriend.addElement(element);
     }
+    /**
+     * Adds a text element to the track.
+     * Calculates appropriate start/end times based on existing track elements.
+     *
+     * @param element - The text element to add
+     * @returns Promise resolving to true if element was added successfully
+     * 
+     * @example
+     * ```js
+     * const success = await adder.visitTextElement(textElement);
+     * // success = true if element was added successfully
+     * ```
+     */
     async visitTextElement(element) {
       const elements = this.track.getElements();
       const lastEndtime = (elements == null ? void 0 : elements.length) ? elements[elements.length - 1].getEnd() : 0;
@@ -1989,6 +2360,19 @@ var __publicField = (obj, key, value) => __defNormalProp(obj, typeof key !== "sy
       }
       return this.trackFriend.addElement(element);
     }
+    /**
+     * Adds a caption element to the track.
+     * Calculates appropriate start/end times based on existing track elements.
+     *
+     * @param element - The caption element to add
+     * @returns Promise resolving to true if element was added successfully
+     * 
+     * @example
+     * ```js
+     * const success = await adder.visitCaptionElement(captionElement);
+     * // success = true if element was added successfully
+     * ```
+     */
     async visitCaptionElement(element) {
       const elements = this.track.getElements();
       const lastEndtime = (elements == null ? void 0 : elements.length) ? elements[elements.length - 1].getEnd() : 0;
@@ -2000,6 +2384,19 @@ var __publicField = (obj, key, value) => __defNormalProp(obj, typeof key !== "sy
       }
       return this.trackFriend.addElement(element);
     }
+    /**
+     * Adds an icon element to the track.
+     * Calculates appropriate start/end times based on existing track elements.
+     *
+     * @param element - The icon element to add
+     * @returns Promise resolving to true if element was added successfully
+     * 
+     * @example
+     * ```js
+     * const success = await adder.visitIconElement(iconElement);
+     * // success = true if element was added successfully
+     * ```
+     */
     async visitIconElement(element) {
       const elements = this.track.getElements();
       const lastEndtime = (elements == null ? void 0 : elements.length) ? elements[elements.length - 1].getEnd() : 0;
@@ -2011,6 +2408,19 @@ var __publicField = (obj, key, value) => __defNormalProp(obj, typeof key !== "sy
       }
       return this.trackFriend.addElement(element);
     }
+    /**
+     * Adds a circle element to the track.
+     * Calculates appropriate start/end times based on existing track elements.
+     *
+     * @param element - The circle element to add
+     * @returns Promise resolving to true if element was added successfully
+     * 
+     * @example
+     * ```js
+     * const success = await adder.visitCircleElement(circleElement);
+     * // success = true if element was added successfully
+     * ```
+     */
     async visitCircleElement(element) {
       const elements = this.track.getElements();
       const lastEndtime = (elements == null ? void 0 : elements.length) ? elements[elements.length - 1].getEnd() : 0;
@@ -2022,6 +2432,19 @@ var __publicField = (obj, key, value) => __defNormalProp(obj, typeof key !== "sy
       }
       return this.trackFriend.addElement(element);
     }
+    /**
+     * Adds a rectangle element to the track.
+     * Calculates appropriate start/end times based on existing track elements.
+     *
+     * @param element - The rectangle element to add
+     * @returns Promise resolving to true if element was added successfully
+     * 
+     * @example
+     * ```js
+     * const success = await adder.visitRectElement(rectElement);
+     * // success = true if element was added successfully
+     * ```
+     */
     async visitRectElement(element) {
       const elements = this.track.getElements();
       const lastEndtime = (elements == null ? void 0 : elements.length) ? elements[elements.length - 1].getEnd() : 0;