@twick/timeline 0.14.0

package/README.md

@@ -0,0 +1,175 @@
+# @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>;
+}
+```
+
+

package/dist/context/timeline-context.d.ts

@@ -0,0 +1,33 @@
+import { Track } from '../core/track/track';
+import { TrackElement } from '../core/elements/base.element';
+import { ProjectJSON, TrackJSON } from '../types';
+import { TimelineEditor } from '../core/editor/timeline.editor';
+
+export type TimelineContextType = {
+    contextId: string;
+    editor: TimelineEditor;
+    selectedItem: Track | TrackElement | null;
+    changeLog: number;
+    timelineAction: {
+        type: string;
+        payload: any;
+    };
+    totalDuration: number;
+    present: ProjectJSON | null;
+    canUndo: boolean;
+    canRedo: boolean;
+    setSelectedItem: (item: Track | TrackElement | null) => void;
+    setTimelineAction: (type: string, payload: any) => void;
+};
+export interface TimelineProviderProps {
+    children: React.ReactNode;
+    contextId: string;
+    initialData?: {
+        tracks: TrackJSON[];
+        version: number;
+    };
+    undoRedoPersistenceKey?: string;
+    maxHistorySize?: number;
+}
+export declare const TimelineProvider: ({ contextId, children, initialData, undoRedoPersistenceKey, maxHistorySize, }: TimelineProviderProps) => import("react/jsx-runtime").JSX.Element;
+export declare const useTimelineContext: () => TimelineContextType;

package/dist/context/undo-redo-context.d.ts

@@ -0,0 +1,21 @@
+import { ProjectJSON } from '../types';
+
+interface UndoRedoContextType {
+    canUndo: boolean;
+    canRedo: boolean;
+    present: ProjectJSON | null;
+    setPresent: (data: ProjectJSON) => void;
+    undo: () => ProjectJSON | null;
+    redo: () => ProjectJSON | null;
+    resetHistory: () => void;
+    getLastPersistedState: () => ProjectJSON | null;
+    disablePersistence: () => void;
+}
+export interface UndoRedoProviderProps {
+    children: React.ReactNode;
+    persistenceKey?: string;
+    maxHistorySize?: number;
+}
+export declare const UndoRedoProvider: React.FC<UndoRedoProviderProps>;
+export declare const useUndoRedo: () => UndoRedoContextType;
+export {};

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

@@ -0,0 +1,24 @@
+import { Animation } from '../../types';
+
+export declare class ElementAnimation {
+    private name;
+    private interval?;
+    private intensity?;
+    private animate?;
+    private mode?;
+    private direction?;
+    constructor(name: string);
+    getName(): string;
+    getInterval(): number | undefined;
+    getIntensity(): number | undefined;
+    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;
+    toJSON(): Animation;
+    static fromJSON(json: Animation): ElementAnimation;
+}

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

@@ -0,0 +1,14 @@
+import { FrameEffect, FrameEffectProps } from '../../types';
+
+export declare class ElementFrameEffect {
+    private s;
+    private e;
+    private props;
+    constructor(start: number, end: number);
+    setProps(props: FrameEffectProps): void;
+    getProps(): FrameEffectProps;
+    getStart(): number;
+    getEnd(): number;
+    toJSON(): FrameEffect;
+    static fromJSON(json: FrameEffect): ElementFrameEffect;
+}

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

@@ -0,0 +1,19 @@
+import { TextEffect } from '../../types';
+
+export declare class ElementTextEffect {
+    private name;
+    private duration?;
+    private delay?;
+    private bufferTime?;
+    constructor(name: string);
+    getName(): string;
+    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;
+    toJSON(): TextEffect;
+    static fromJSON(json: TextEffect): ElementTextEffect;
+}

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

@@ -0,0 +1,94 @@
+import { Track } from '../track/track';
+import { TimelineTrackData } from '../../services/data.service';
+import { SplitResult } from '../visitor/element-splitter';
+import { TrackElement } from '../elements/base.element';
+import { ProjectJSON, TrackJSON } from '../../types';
+
+/**
+ * Type for timeline operation context
+ */
+export interface TimelineOperationContext {
+    contextId: string;
+    setTotalDuration: (duration: number) => void;
+    setPresent: (data: ProjectJSON) => void;
+    handleUndo: () => ProjectJSON | null;
+    handleRedo: () => ProjectJSON | null;
+    handleResetHistory: () => void;
+    updateChangeLog: () => void;
+    setTimelineAction?: (action: string, payload?: unknown) => void;
+}
+/**
+ * TimelineEditor
+ *
+ * This class provides an interface to execute all timeline operations
+ * using a direct, class-based approach with track-based management.
+ * It also handles undo/redo operations internally.
+ */
+export declare class TimelineEditor {
+    private context;
+    constructor(context: TimelineOperationContext);
+    getContext(): TimelineOperationContext;
+    pauseVideo(): void;
+    getTimelineData(): TimelineTrackData | null;
+    getLatestVersion(): number;
+    protected setTimelineData(tracks: Track[], version?: number): TimelineTrackData;
+    addTrack(name: string): Track;
+    getTrackById(id: string): Track | null;
+    getTrackByName(name: string): Track | null;
+    removeTrackById(id: string): void;
+    removeTrack(track: Track): void;
+    /**
+     * Refresh the timeline data
+     */
+    refresh(): void;
+    /**
+     * Add an element to a specific track using the visitor pattern
+     * @param track The track to add the element to
+     * @param element The element to add
+     * @returns Promise<boolean> true if element was added successfully
+     */
+    addElementToTrack(track: Track, element: TrackElement): Promise<boolean>;
+    /**
+     * Remove an element from a specific track using the visitor pattern
+     * @param element The element to remove
+     * @returns boolean true if element was removed successfully
+     */
+    removeElement(element: TrackElement): boolean;
+    /**
+     * Update an element in a specific track using the visitor pattern
+     * @param element The updated element
+     * @returns boolean true if element was updated successfully
+     */
+    updateElement(element: TrackElement): boolean;
+    /**
+     * Split an element at a specific time point using the visitor pattern
+     * @param element The element to split
+     * @param splitTime The time point to split at
+     * @returns SplitResult with first element, second element, and success status
+     */
+    splitElement(element: TrackElement, splitTime: number): Promise<SplitResult>;
+    /**
+     * Clone an element using the visitor pattern
+     * @param element The element to clone
+     * @returns TrackElement | null - the cloned element or null if cloning failed
+     */
+    cloneElement(element: TrackElement): TrackElement | null;
+    reorderTracks(tracks: Track[]): void;
+    updateHistory(timelineTrackData: TimelineTrackData): void;
+    /**
+     * Trigger undo operation and update timeline data
+     */
+    undo(): void;
+    /**
+     * Trigger redo operation and update timeline data
+     */
+    redo(): void;
+    /**
+     * Reset history and clear timeline data
+     */
+    resetHistory(): void;
+    loadProject({ tracks, version, }: {
+        tracks: TrackJSON[];
+        version: number;
+    }): void;
+}

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

@@ -0,0 +1,20 @@
+import { TrackElement } from './base.element';
+import { ElementVisitor } from '../visitor/element-visitor';
+import { AudioProps } from '../../types';
+
+export declare class AudioElement extends TrackElement {
+    protected mediaDuration: number;
+    protected props: AudioProps;
+    constructor(src: string);
+    getMediaDuration(): number;
+    getStartAt(): number;
+    updateAudioMeta(): Promise<void>;
+    setSrc(src: string): Promise<this>;
+    setMediaDuration(mediaDuration: number): this;
+    setVolume(volume: number): this;
+    setLoop(loop: boolean): this;
+    setStartAt(time: number): this;
+    setPlaybackRate(playbackRate: number): this;
+    setProps(props: Omit<any, "src">): this;
+    accept<T>(visitor: ElementVisitor<T>): T;
+}

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

@@ -0,0 +1,35 @@
+import { ElementVisitor } from '../visitor/element-visitor';
+import { ElementAnimation } from '../addOns/animation';
+import { Position } from '../../types';
+
+export declare abstract class TrackElement {
+    protected id: string;
+    protected type: string;
+    protected s: number;
+    protected e: number;
+    protected trackId: string;
+    protected name: string;
+    protected animation?: ElementAnimation;
+    protected props: Record<string, any>;
+    constructor(type: string, id?: string);
+    abstract accept<T>(visitor: ElementVisitor<T>): T;
+    getId(): string;
+    getType(): string;
+    getStart(): number;
+    getEnd(): number;
+    getDuration(): number;
+    getTrackId(): string;
+    getProps(): Record<string, any>;
+    getName(): string;
+    getAnimation(): ElementAnimation | undefined;
+    getPosition(): Position;
+    setId(id: string): this;
+    setType(type: string): this;
+    setStart(s: number): this;
+    setEnd(e: number): this;
+    setTrackId(trackId: string): this;
+    setName(name: string): this;
+    setAnimation(animation?: ElementAnimation): this;
+    setPosition(position: Position): this;
+    setProps(props: Record<string, any>): this;
+}

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

@@ -0,0 +1,10 @@
+import { TrackElement } from './base.element';
+import { ElementVisitor } from '../visitor/element-visitor';
+
+export declare class CaptionElement extends TrackElement {
+    protected t: string;
+    constructor(t: string, start: number, end: number);
+    getText(): string;
+    setText(t: string): this;
+    accept<T>(visitor: ElementVisitor<T>): T;
+}

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

@@ -0,0 +1,13 @@
+import { TrackElement } from './base.element';
+import { ElementVisitor } from '../visitor/element-visitor';
+import { CircleProps } from '../../types';
+
+export declare class CircleElement extends TrackElement {
+    protected props: CircleProps;
+    constructor(fill: string, radius: number);
+    getFill(): string;
+    getRadius(): number;
+    setFill(fill: string): this;
+    setRadius(radius: number): this;
+    accept<T>(visitor: ElementVisitor<T>): T;
+}

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

@@ -0,0 +1,9 @@
+import { TrackElement } from './base.element';
+import { ElementVisitor } from '../visitor/element-visitor';
+import { IconProps, Size } from '../../types';
+
+export declare class IconElement extends TrackElement {
+    protected props: IconProps;
+    constructor(src: string, size: Size);
+    accept<T>(visitor: ElementVisitor<T>): T;
+}

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

@@ -0,0 +1,32 @@
+import { Frame, ImageProps, ObjectFit, Position, Size } from '../../types';
+import { TrackElement } from './base.element';
+import { ElementVisitor } from '../visitor/element-visitor';
+import { ElementFrameEffect } from '../addOns/frame-effect';
+
+export declare class ImageElement extends TrackElement {
+    protected backgroundColor: string;
+    protected parentSize: Size;
+    protected objectFit: ObjectFit;
+    frameEffects?: ElementFrameEffect[];
+    frame: Frame;
+    protected props: ImageProps;
+    constructor(src: string, parentSize: Size);
+    getParentSize(): Size;
+    getFrame(): Frame;
+    getFrameEffects(): ElementFrameEffect[] | undefined;
+    getBackgroundColor(): string;
+    getObjectFit(): ObjectFit;
+    getPosition(): Position;
+    updateImageMeta(updateFrame?: boolean): Promise<void>;
+    setPosition(position: Position): this;
+    setSrc(src: string): Promise<this>;
+    setObjectFit(objectFit: ObjectFit): this;
+    setFrame(frame: Frame): this;
+    setParentSize(parentSize: Size): this;
+    setMediaFilter(mediaFilter: string): this;
+    setBackgroundColor(backgroundColor: string): this;
+    setProps(props: Omit<any, "src">): this;
+    setFrameEffects(frameEffects?: ElementFrameEffect[]): this;
+    addFrameEffect(frameEffect: ElementFrameEffect): this;
+    accept<T>(visitor: ElementVisitor<T>): T;
+}

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

@@ -0,0 +1,11 @@
+import { RectProps, Size } from '../../types';
+import { TrackElement } from './base.element';
+import { ElementVisitor } from '../visitor/element-visitor';
+
+export declare class RectElement extends TrackElement {
+    protected props: RectProps;
+    constructor(fill: string, size: Size);
+    setFill(fill: string): this;
+    setSize(size: Size): this;
+    accept<T>(visitor: ElementVisitor<T>): T;
+}

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

@@ -0,0 +1,26 @@
+import { TextAlign, TextProps } from '../../types';
+import { TrackElement } from './base.element';
+import { ElementVisitor } from '../visitor/element-visitor';
+import { ElementTextEffect } from '../addOns/text-effect';
+
+export declare class TextElement extends TrackElement {
+    protected textEffect?: ElementTextEffect;
+    protected props: TextProps;
+    constructor(text: string);
+    getTextEffect(): ElementTextEffect | undefined;
+    getText(): string;
+    getStrokeColor(): string | undefined;
+    getLineWidth(): number | undefined;
+    setText(text: string): this;
+    setFill(fill: string): this;
+    setRotation(rotation: number): this;
+    setFontSize(fontSize: number): this;
+    setFontFamily(fontFamily: string): this;
+    setFontWeight(fontWeight: number): this;
+    setFontStyle(fontStyle: "normal" | "italic"): this;
+    setTextEffect(textEffect?: ElementTextEffect): this;
+    setTextAlign(textAlign: TextAlign): this;
+    setStrokeColor(stroke: string): this;
+    setLineWidth(lineWidth: number): this;
+    accept<T>(visitor: ElementVisitor<T>): T;
+}

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

@@ -0,0 +1,41 @@
+import { Frame, ObjectFit, Position, Size, VideoProps } from '../../types';
+import { TrackElement } from './base.element';
+import { ElementVisitor } from '../visitor/element-visitor';
+import { ElementFrameEffect } from '../addOns/frame-effect';
+
+export declare class VideoElement extends TrackElement {
+    protected baseSize: Size;
+    protected mediaDuration: number;
+    protected parentSize: Size;
+    protected backgroundColor: string;
+    protected objectFit: ObjectFit;
+    protected frameEffects?: ElementFrameEffect[];
+    protected frame: Frame;
+    protected props: VideoProps;
+    constructor(src: string, parentSize: Size);
+    getParentSize(): Size;
+    getFrame(): Frame;
+    getFrameEffects(): ElementFrameEffect[] | undefined;
+    getBackgroundColor(): string;
+    getObjectFit(): ObjectFit;
+    getMediaDuration(): number;
+    getStartAt(): number;
+    getPosition(): Position;
+    updateVideoMeta(updateFrame?: boolean): Promise<void>;
+    setPosition(position: Position): this;
+    setSrc(src: string): Promise<this>;
+    setMediaDuration(mediaDuration: number): this;
+    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;
+    setVolume(volume: number): this;
+    setBackgroundColor(backgroundColor: string): this;
+    setProps(props: Omit<any, "src">): this;
+    setFrameEffects(frameEffects?: ElementFrameEffect[]): this;
+    addFrameEffect(frameEffect: ElementFrameEffect): this;
+    accept<T>(visitor: ElementVisitor<T>): T;
+}

package/dist/core/track/track.d.ts

@@ -0,0 +1,77 @@
+import { TrackJSON } from '../../types';
+import { TrackElement } from '../elements/base.element';
+import { TrackFriend } from './track.friend';
+
+export declare class Track {
+    private id;
+    private name;
+    private type;
+    private elements;
+    private validator;
+    constructor(name: string, id?: string);
+    /**
+     * Create a friend instance for explicit access to protected methods
+     * This implements the Friend Class Pattern
+     * @returns TrackFriend instance
+     */
+    createFriend(): TrackFriend;
+    /**
+     * Friend method to add element (called by TrackFriend)
+     * @param element The element to add
+     * @param skipValidation If true, skips validation
+     * @returns 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
+     */
+    removeElementViaFriend(element: TrackElement): void;
+    /**
+     * Friend method to update element (called by TrackFriend)
+     * @param element The element to update
+     * @returns true if element was updated successfully
+     */
+    updateElementViaFriend(element: TrackElement): boolean;
+    getId(): string;
+    getName(): string;
+    getType(): string;
+    getElements(): ReadonlyArray<TrackElement>;
+    /**
+     * Validates an element
+     * @param element The element to validate
+     * @returns true if valid, throws ValidationError if invalid
+     */
+    validateElement(element: TrackElement): boolean;
+    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)
+     * @returns true if element was added successfully, throws ValidationError if validation fails
+     */
+    protected addElement(element: TrackElement, skipValidation?: boolean): boolean;
+    protected removeElement(element: TrackElement): void;
+    /**
+     * Updates an element in the track with validation
+     * @param element The element to update
+     * @returns true if element was updated successfully, throws ValidationError if validation fails
+     */
+    protected updateElement(element: TrackElement): boolean;
+    getElementById(id: string): Readonly<TrackElement> | undefined;
+    /**
+     * Validates all elements in the track and returns combined result and per-element status
+     * @returns Object with overall isValid and array of per-element validation results
+     */
+    validateAllElements(): {
+        isValid: boolean;
+        results: Array<{
+            element: TrackElement;
+            isValid: boolean;
+            errors?: string[];
+            warnings?: string[];
+        }>;
+    };
+    serialize(): TrackJSON;
+    static fromJSON(json: any): Track;
+}