@twick/timeline 0.14.2 → 0.14.3

package/dist/utils/constants.d.ts

@@ -1,55 +1,192 @@
+/**
+ * Player state constants for timeline playback control.
+ * Defines the different states that a timeline player can be in during playback.
+ *
+ * @example
+ * ```js
+ * import { PLAYER_STATE } from '@twick/timeline';
+ *
+ * if (playerState === PLAYER_STATE.PLAYING) {
+ *   console.log('Timeline is currently playing');
+ * }
+ * ```
+ */
 export declare const PLAYER_STATE: {
-    REFRESH: string;
-    PLAYING: string;
-    PAUSED: string;
+    /** Player is refreshing/reloading content */
+    readonly REFRESH: "Refresh";
+    /** Player is actively playing content */
+    readonly PLAYING: "Playing";
+    /** Player is paused */
+    readonly PAUSED: "Paused";
 };
+/**
+ * Caption styling options for text elements.
+ * Defines different visual styles for caption text rendering.
+ *
+ * @example
+ * ```js
+ * import { CAPTION_STYLE } from '@twick/timeline';
+ *
+ * const captionElement = new CaptionElement({
+ *   style: CAPTION_STYLE.WORD_BY_WORD
+ * });
+ * ```
+ */
 export declare const CAPTION_STYLE: {
-    WORD_BG_HIGHLIGHT: string;
-    WORD_BY_WORD: string;
-    WORD_BY_WORD_WITH_BG: string;
+    /** Highlights background of each word */
+    readonly WORD_BG_HIGHLIGHT: "highlight_bg";
+    /** Animates text word by word */
+    readonly WORD_BY_WORD: "word_by_word";
+    /** Animates text word by word with background highlighting */
+    readonly WORD_BY_WORD_WITH_BG: "word_by_word_with_bg";
 };
+/**
+ * Human-readable options for caption styles.
+ * Provides user-friendly labels for caption style selection.
+ *
+ * @example
+ * ```js
+ * import { CAPTION_STYLE_OPTIONS } from '@twick/timeline';
+ *
+ * const options = Object.values(CAPTION_STYLE_OPTIONS);
+ * // Returns array of style options with labels
+ * ```
+ */
 export declare const CAPTION_STYLE_OPTIONS: {
-    [CAPTION_STYLE.WORD_BG_HIGHLIGHT]: {
-        label: string;
-        value: string;
+    readonly highlight_bg: {
+        readonly label: "Highlight Background";
+        readonly value: "highlight_bg";
     };
-    [CAPTION_STYLE.WORD_BY_WORD]: {
-        label: string;
-        value: string;
+    readonly word_by_word: {
+        readonly label: "Word by Word";
+        readonly value: "word_by_word";
     };
-    [CAPTION_STYLE.WORD_BY_WORD_WITH_BG]: {
-        label: string;
-        value: string;
+    readonly word_by_word_with_bg: {
+        readonly label: "Word with Background";
+        readonly value: "word_by_word_with_bg";
     };
 };
+/**
+ * Default font settings for caption elements.
+ * Defines the standard typography configuration for captions.
+ *
+ * @example
+ * ```js
+ * import { CAPTION_FONT } from '@twick/timeline';
+ *
+ * const fontSize = CAPTION_FONT.size; // 40
+ * ```
+ */
 export declare const CAPTION_FONT: {
-    size: number;
+    /** Font size in pixels */
+    readonly size: 40;
 };
+/**
+ * Default color scheme for caption elements.
+ * Defines the standard color palette for caption text and backgrounds.
+ *
+ * @example
+ * ```js
+ * import { CAPTION_COLOR } from '@twick/timeline';
+ *
+ * const textColor = CAPTION_COLOR.text; // "#ffffff"
+ * const highlightColor = CAPTION_COLOR.highlight; // "#ff4081"
+ * ```
+ */
 export declare const CAPTION_COLOR: {
-    text: string;
-    highlight: string;
-    bgColor: string;
+    /** Text color in hex format */
+    readonly text: "#ffffff";
+    /** Highlight color in hex format */
+    readonly highlight: "#ff4081";
+    /** Background color in hex format */
+    readonly bgColor: "#8C52FF";
 };
+/**
+ * Number of words to display per phrase in caption animations.
+ * Controls the chunking of text for word-by-word animations.
+ *
+ * @example
+ * ```js
+ * import { WORDS_PER_PHRASE } from '@twick/timeline';
+ *
+ * const phraseLength = WORDS_PER_PHRASE; // 4
+ * ```
+ */
 export declare const WORDS_PER_PHRASE = 4;
+/**
+ * Timeline action types for state management.
+ * Defines the different actions that can be performed on the timeline.
+ *
+ * @example
+ * ```js
+ * import { TIMELINE_ACTION } from '@twick/timeline';
+ *
+ * if (action.type === TIMELINE_ACTION.SET_PLAYER_STATE) {
+ *   // Handle player state change
+ * }
+ * ```
+ */
 export declare const TIMELINE_ACTION: {
-    NONE: string;
-    SET_PLAYER_STATE: string;
-    UPDATE_PLAYER_DATA: string;
-    ON_PLAYER_UPDATED: string;
+    /** No action being performed */
+    readonly NONE: "none";
+    /** Setting the player state (play/pause) */
+    readonly SET_PLAYER_STATE: "setPlayerState";
+    /** Updating player data */
+    readonly UPDATE_PLAYER_DATA: "updatePlayerData";
+    /** Player has been updated */
+    readonly ON_PLAYER_UPDATED: "onPlayerUpdated";
 };
+/**
+ * Element type constants for timeline elements.
+ * Defines the different types of elements that can be added to timeline tracks.
+ *
+ * @example
+ * ```js
+ * import { TIMELINE_ELEMENT_TYPE } from '@twick/timeline';
+ *
+ * if (element.type === TIMELINE_ELEMENT_TYPE.VIDEO) {
+ *   // Handle video element
+ * }
+ * ```
+ */
 export declare const TIMELINE_ELEMENT_TYPE: {
-    VIDEO: string;
-    CAPTION: string;
-    IMAGE: string;
-    AUDIO: string;
-    TEXT: string;
-    RECT: string;
-    CIRCLE: string;
-    ICON: string;
+    /** Video element type */
+    readonly VIDEO: "video";
+    /** Caption element type */
+    readonly CAPTION: "caption";
+    /** Image element type */
+    readonly IMAGE: "image";
+    /** Audio element type */
+    readonly AUDIO: "audio";
+    /** Text element type */
+    readonly TEXT: "text";
+    /** Rectangle element type */
+    readonly RECT: "rect";
+    /** Circle element type */
+    readonly CIRCLE: "circle";
+    /** Icon element type */
+    readonly ICON: "icon";
 };
+/**
+ * Process state constants for async operations.
+ * Defines the different states of background processing operations.
+ *
+ * @example
+ * ```js
+ * import { PROCESS_STATE } from '@twick/timeline';
+ *
+ * if (processState === PROCESS_STATE.PROCESSING) {
+ *   // Show loading indicator
+ * }
+ * ```
+ */
 export declare const PROCESS_STATE: {
-    IDLE: string;
-    PROCESSING: string;
-    COMPLETED: string;
-    FAILED: string;
+    /** Process is idle */
+    readonly IDLE: "Idle";
+    /** Process is currently running */
+    readonly PROCESSING: "Processing";
+    /** Process has completed successfully */
+    readonly COMPLETED: "Completed";
+    /** Process has failed */
+    readonly FAILED: "Failed";
 };

package/dist/utils/timeline.utils.d.ts

@@ -2,11 +2,123 @@ import { TrackElement } from '../core/elements/base.element';
 import { Track } from '../core/track/track';
 import { TrackJSON } from '../types';
 
+/**
+ * Rounds a number to a specified decimal precision.
+ * Useful for ensuring consistent decimal places in timeline calculations.
+ *
+ * @param num - The number to round
+ * @param precision - The number of decimal places to round to
+ * @returns The rounded number
+ *
+ * @example
+ * ```js
+ * const rounded = getDecimalNumber(3.14159, 2);
+ * // rounded = 3.14
+ * ```
+ */
 export declare const getDecimalNumber: (num: number, precision?: number) => number;
+/**
+ * Calculates the total duration of all tracks in a timeline.
+ * Finds the maximum end time across all elements in all tracks
+ * to determine the overall timeline duration.
+ *
+ * @param tracks - Array of track data containing elements
+ * @returns The total duration in seconds
+ *
+ * @example
+ * ```js
+ * const duration = getTotalDuration(tracks);
+ * // duration = 120.5 (2 minutes and 0.5 seconds)
+ * ```
+ */
 export declare const getTotalDuration: (tracks: TrackJSON[]) => number;
+/**
+ * Generates a short UUID for element and track identification.
+ * Creates a 12-character unique identifier using a simplified
+ * UUID generation algorithm.
+ *
+ * @returns A 12-character unique identifier string
+ *
+ * @example
+ * ```js
+ * const id = generateShortUuid();
+ * // id = "a1b2c3d4e5f6"
+ * ```
+ */
 export declare const generateShortUuid: () => string;
+/**
+ * Gets all elements that are currently active at the specified time.
+ * Searches through all tracks to find elements whose time range
+ * includes the current playback time.
+ *
+ * @param currentTime - The current playback time in seconds
+ * @param tracks - Array of track objects to search through
+ * @returns Array of elements currently active at the specified time
+ *
+ * @example
+ * ```js
+ * const activeElements = getCurrentElements(5.5, tracks);
+ * // Returns all elements active at 5.5 seconds
+ * ```
+ */
 export declare const getCurrentElements: (currentTime: number, tracks: Track[]) => Array<Readonly<TrackElement>>;
+/**
+ * Checks if an element can be split at the specified time.
+ * Determines if the current time falls within the element's
+ * start and end time range.
+ *
+ * @param element - The element to check for splitting
+ * @param currentTime - The time at which to check if splitting is possible
+ * @returns True if the element can be split at the specified time
+ *
+ * @example
+ * ```js
+ * const canSplit = canSplitElement(videoElement, 10.5);
+ * // canSplit = true if element spans across 10.5 seconds
+ * ```
+ */
 export declare const canSplitElement: (element: TrackElement, currentTime: number) => boolean;
+/**
+ * Checks if an ID represents an element.
+ * Validates if the ID follows the element naming convention.
+ *
+ * @param id - The ID to check
+ * @returns True if the ID represents an element
+ *
+ * @example
+ * ```js
+ * const isElement = isElementId("e-abc123");
+ * // isElement = true
+ * ```
+ */
 export declare const isElementId: (id: string) => boolean;
+/**
+ * Checks if an ID represents a track.
+ * Validates if the ID follows the track naming convention.
+ *
+ * @param id - The ID to check
+ * @returns True if the ID represents a track
+ *
+ * @example
+ * ```js
+ * const isTrack = isTrackId("t-xyz789");
+ * // isTrack = true
+ * ```
+ */
 export declare const isTrackId: (id: string) => boolean;
+/**
+ * Extracts and stitches audio from video elements across all tracks.
+ * Processes all video elements in the timeline, extracts their audio segments,
+ * and combines them into a single audio file with proper timing.
+ *
+ * @param tracks - Array of track objects containing video elements
+ * @param duration - The total duration of the output audio
+ * @returns Promise resolving to a Blob URL of the combined audio
+ *
+ * @example
+ * ```js
+ * const audioUrl = await extractVideoAudio(tracks, 120);
+ * // audioUrl = "blob:http://localhost:3000/abc123"
+ * ```
+ */
 export declare const extractVideoAudio: (tracks: Track[], duration: number) => Promise<any>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@twick/timeline",
-  "version": "0.14.2",
+  "version": "0.14.3",
   "type": "module",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",
@@ -8,7 +8,7 @@
   "sideEffects": [
     "**/*.css"
   ],
-  "license": "Apache-2.0",
+  "license": "SEE LICENSE IN LICENSE.md",
   "files": [
     "dist"
   ],
@@ -20,10 +20,10 @@
     "dev": "vite build --watch",
     "lint": "eslint src/",
     "clean": "rimraf .turbo node_modules dist",
-    "docs": "typedoc --plugin typedoc-plugin-markdown --out docs src/index.ts"
+    "docs": "typedoc"
   },
   "dependencies": {
-    "@twick/media-utils": "0.14.2",
+    "@twick/media-utils": "0.14.3",
     "posthog-js": "^1.258.5"
   },
   "devDependencies": {