@twick/timeline 0.14.2 → 0.14.3

package/dist/index.mjs

@@ -4,13 +4,19 @@ var __publicField = (obj, key, value) => __defNormalProp(obj, typeof key !== "sy
 import { jsx } from "react/jsx-runtime";
 import React, { useState, createContext, useContext, useRef, useMemo, useEffect } from "react";
 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 = {
@@ -28,34 +34,54 @@ const CAPTION_STYLE_OPTIONS = {
   }
 };
 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 = {};
@@ -1682,6 +1708,18 @@ class TrackFriend {
   }
 }
 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");
@@ -1695,66 +1733,210 @@ class Track {
     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);
@@ -1776,6 +1958,22 @@ class Track {
     }
     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 index = this.elements.findIndex((e2) => e2.getId() === element.getId());
     if (index !== -1) {
@@ -1783,9 +1981,22 @@ class Track {
     }
   }
   /**
-   * 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 {
@@ -1807,14 +2018,55 @@ class Track {
     }
     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;
@@ -1844,6 +2096,30 @@ class Track {
     });
     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 {
@@ -1855,6 +2131,35 @@ class Track {
       )
     };
   }
+  /**
+   * 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;
@@ -1934,12 +2239,37 @@ __publicField(_TimelineContextStore, "instance");
 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();
@@ -1952,6 +2282,20 @@ class ElementAdder {
     }
     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();
@@ -1964,6 +2308,20 @@ class ElementAdder {
     }
     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();
@@ -1976,6 +2334,19 @@ class ElementAdder {
     }
     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;
@@ -1987,6 +2358,19 @@ class ElementAdder {
     }
     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;
@@ -1998,6 +2382,19 @@ class ElementAdder {
     }
     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;
@@ -2009,6 +2406,19 @@ class ElementAdder {
     }
     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;
@@ -2020,6 +2430,19 @@ class ElementAdder {
     }
     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;